@gjsify/node-gi 0.27.0 → 0.27.1

package/README.md

@@ -166,6 +166,45 @@ conformance subset since 2.9 (the marshalling/async N-API quirks that excluded
 `arrays`/`async-error` on Deno 2.1 are fixed upstream) — the Node-only co-pump
 cases are the remaining, by-design gap. The authoritative full suite runs on Node.
 
+**Architectures.** CI runs the Bun/Deno legs on x86-64 only, so `linux-arm64` was
+measured by hand on a OnePlus 6T / postmarketOS (2026-08-03) against the PUBLISHED
+0.27.0 `prebuilds/linux-arm64/node_gi.node`: **Bun 1.3.14 → 38/38** cross-runtime
+files, **Deno 2.9.4 → 35/38 plus the three known non-gating Deno teardown exits,
+0 failed**. Two libc notes from that run:
+
+- the prebuild declares glibc, yet it **loads and runs on a pure-musl host** (Alpine
+  / postmarketOS, no glibc, no `gcompat`) under Bun's musl build: musl's dynamic
+  loader maps the `libc.so.6` / `libm.so.6` `DT_NEEDED` entries onto ITSELF via its
+  reserved-name list, and every other dependency (`libglib-2.0`,
+  `libgirepository-2.0`, `libcairo`, `libstdc++`, `libgcc_s`) exists musl-built.
+  **Do not read a successful load as "every symbol resolved".** Measured with a real
+  artifact (`@gjsify/sab-native`'s pre-#955 prebuild) on aarch64 musl and in
+  `alpine:3.24` x86-64: `dlopen` behaves oppositely by mode — `RTLD_NOW` fails at
+  load, `RTLD_LAZY` **loads** and the process dies at the first call through the
+  deferred PLT slot. GI opens typelib backers with `G_MODULE_BIND_LAZY`, so on musl a
+  glibc-only symbol really does hide from a load. Both arches behave identically.
+  A weak undefined symbol hides the same way. So this binary is clear by audit, not
+  by its load: 5 of its 579 undefined symbols are weak, and the 3 unresolvable on
+  musl (`_ITM_{,de}registerTMCloneTable`, `__gmon_start__`) are the NULL-guarded gcc
+  boilerplate every DSO carries. What defeats the hiding is `dlopen(RTLD_NOW)`, or —
+  with no musl machine at all — a glibc-floor `SHT_GNU_verneed` audit.
+- **Deno publishes no musl build** (`aarch64-unknown-linux-gnu` only), so on such a
+  host Deno needs a glibc environment (here the `org.gnome.Platform//49` flatpak
+  runtime: glibc 2.42, gjs 1.86.0). With `node_modules/` already materialised, both
+  `--node-modules-dir=manual` and Deno's default worked.
+
+On **Linux** the typelib's bare library leaf needs no help: `Gtk`/`Gdk`/`Adw`/`Pango`/
+`Graphene` all resolve and `Gtk.DrawingArea` subclasses correctly with no
+`GI_TYPELIB_PATH` and no `LD_LIBRARY_PATH`, both on the musl host and inside the
+flatpak runtime, because the system loader's default search path already covers the
+distro's own libraries. That is worth stating explicitly because the same step FAILS
+on macOS (`Failed to load shared library 'libgtk-4.1.dylib' referenced by the
+typelib` → `Gtk.DrawingArea is not a subclassable GObject type`): dyld has no
+`ld.so.conf` equivalent, and a plain `node`/`bun`/`deno` binary carries no rpath into
+Homebrew's prefix, where `gjs` itself does. A loader-path failure of that shape is
+never a node-gi or runtime defect — see `gtk-runtime.js` and the CLI's
+`detectNativePackages()` / `buildNativeEnv()` for how the env normally gets wired.
+
 Promise draining during a blocking loop is cross-runtime because the engine runs
 a **microtask checkpoint at every outermost loop-dispatched GLib→JS callback
 boundary**: Node's `napi_make_callback` performs it natively; Bun's and Deno's

package/gi.js

@@ -1956,25 +1956,74 @@ function paramSpecToNative(desc, key) {
     return spec;
 }
 
-// Normalise a signal param/return type to the native type-name vocabulary: a
-// string passes through; a ParamSpec descriptor contributes its `.type`.
+// Normalise a signal param/return type to the native type-name vocabulary the
+// engine resolves with g_type_from_name (src/class.cc TypeNameToGType). THREE
+// spellings are accepted, in the order tried:
+//   • a string — node-gi's own shorthand ('int', 'GBytes', any registered GType name)
+//   • a GObject.ParamSpec descriptor — contributes its `.type`
+//   • a GTYPE — `GObject.TYPE_INT`, `SomeClass.$gtype`. This is what GJS documents
+//     and what every ported GJS class writes, and it is an OPAQUE tagged External
+//     (marshal.cc kGTypeHandleTag): neither a string nor a carrier of `.type`, so it
+//     has to be turned back into its canonical name via the introspected
+//     `g_type_name()` — the same GType→name round-trip TypeNameToGType inverts.
+// `undefined` = "not a type at all"; the caller REJECTS it (see signalSpecToNative).
 function normalizeSignalType(t) {
     if (typeof t === 'string') return t;
-    if (t !== null && typeof t === 'object' && typeof t.type === 'string') return t.type;
-    return undefined;
+    if (t === null || typeof t !== 'object') return undefined;
+    if (typeof t.type === 'string') return t.type;
+    // Lazy + namespaceCache'd; GObject is necessarily loaded already (the caller got
+    // here through GObject.registerClass), same shape as the Symbol.hasInstance GType
+    // lookup above. `type_name` THROWS a TypeError for anything that is not a GType
+    // handle (marshal.cc UnwrapGTypeArg) — that IS the "not a type" answer, and the
+    // caller turns it into a message naming the signal, so it is caught here.
+    try {
+        const name = requireGi('GObject', '2.0').type_name(t);
+        return typeof name === 'string' && name.length > 0 ? name : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+function describeSignalType(t) {
+    return t === null ? 'null' : typeof t === 'object' ? 'an object' : typeof t === 'string' ? `'${t}'` : String(t);
 }
 
 // Map a meta.Signals entry (`{ param_types?, return_type?, flags? }`, GJS keys,
 // camelCase also accepted) to a native SignalSpec; the signal name is the key.
+//
+// An unresolvable entry THROWS, it is never dropped. Dropping is what shipped: the
+// GJS-canonical `Signals: { changed: { param_types: [GObject.TYPE_INT] } }` produced
+// a signal registered with ZERO parameters, so `emit('changed', 42)` delivered
+// nothing and the handler's payload argument was silently `undefined` — no error on
+// either side (the engine's own loop skips a G_TYPE_INVALID param too). Measured
+// against gjs 1.88 (n_params 1, payload 42) on aarch64.
 function signalSpecToNative(spec, key) {
     const s = spec !== null && typeof spec === 'object' ? spec : {};
     const out = { name: key };
     const params = s.param_types !== undefined ? s.param_types : s.paramTypes;
     if (Array.isArray(params)) {
-        out.paramTypes = params.map(normalizeSignalType).filter((t) => t !== undefined);
+        out.paramTypes = params.map((t, i) => {
+            const name = normalizeSignalType(t);
+            if (name === undefined) {
+                throw new TypeError(
+                    `GObject.registerClass: signal '${key}' param_types[${i}] is not a type — pass a GType ` +
+                        `(GObject.TYPE_INT, SomeClass.$gtype) or a type name ('int', 'GBytes'), got ${describeSignalType(t)}`,
+                );
+            }
+            return name;
+        });
+    }
+    const rawRet = s.return_type !== undefined ? s.return_type : s.returnType;
+    if (rawRet !== undefined) {
+        const ret = normalizeSignalType(rawRet);
+        if (ret === undefined) {
+            throw new TypeError(
+                `GObject.registerClass: signal '${key}' return_type is not a type — pass a GType ` +
+                    `(GObject.TYPE_INT, SomeClass.$gtype) or a type name ('int', 'GBytes'), got ${describeSignalType(rawRet)}`,
+            );
+        }
+        out.returnType = ret;
     }
-    const ret = normalizeSignalType(s.return_type !== undefined ? s.return_type : s.returnType);
-    if (ret !== undefined) out.returnType = ret;
     if (typeof s.flags === 'number') out.flags = s.flags;
     return out;
 }
@@ -2144,6 +2193,18 @@ function registerClass(metaOrClass, maybeClass) {
     // Reverse index for runCtorForCObject: the engine identifies a C-created instance
     // by its GType name (= gtypeName, what native.registerClass registered).
     classesByGType.set(gtypeName, klass);
+    // GJS parity: registration must be COMPLETE when registerClass returns. The
+    // engine installs the custom properties, signals and vfunc trampolines in
+    // class_init (src/class.cc), which GObject runs lazily on the first
+    // g_type_class_ref — so without this the declared surface did not exist until the
+    // first instance was constructed, and `GObject.signal_lookup('changed',
+    // Klass.$gtype)` answered 0 where gjs answers the real signal id (measured: gjs
+    // 1.88.1 vs node-gi on aarch64). g_type_class_ref is what forces it, exactly as
+    // gjs's own registerClass does; the ref is deliberately never released (a class
+    // struct outlives its GType, which is permanent). Placed LAST so every L1 record
+    // above is in place before any class_init side effect (a Gtk template install)
+    // runs. Idempotent — GObject initialises a class exactly once.
+    requireGi('GObject', '2.0').type_class_ref(typeHandle);
     return klass;
 }
 

package/gtk-runtime.js

@@ -11,6 +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';
 
 // 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
@@ -63,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.
@@ -90,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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.27.0",
+  "version": "0.27.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",
@@ -44,6 +44,8 @@
     "gi.d.ts",
     "gtk-runtime.js",
     "gtk-runtime.d.ts",
+    "system-gi.js",
+    "system-gi.d.ts",
     "globals.js",
     "globals.d.ts",
     "system.js",

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));
+}