@gjsify/node-gi 0.13.0 → 0.20.0

package/globals.d.ts

@@ -1,6 +1,9 @@
 // SPDX-License-Identifier: MIT
 // @gjsify/node-gi/globals — types for the GJS ambient-globals shim.
 
+import type { SystemModule } from './system.js';
+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. */
@@ -8,39 +11,10 @@ export interface GjsImports {
     versions: Record<string, string | undefined>;
     [namespace: string]: unknown;
   };
-  /** `imports.system` — process identity + lifecycle (Node-backed subset). */
-  system: {
-    exit(code?: number): void;
-    gc(): void;
-    readonly programInvocationName: string;
-    readonly programPath: string | null;
-    version: number;
-    addressOf(): string;
-    refcount(): number;
-    breakpoint(): void;
-    dumpHeap(): void;
-    dumpMemoryInfo(): void;
-  };
-  /** `imports.gettext` — a no-translation passthrough. */
-  gettext: {
-    gettext(s: string): string;
-    dgettext(domain: string, s: string): string;
-    dcgettext(domain: string, s: string): string;
-    ngettext(s: string, p: string, n: number): string;
-    dngettext(domain: string, s: string, p: string, n: number): string;
-    pgettext(ctx: string, s: string): string;
-    dpgettext(domain: string, ctx: string, s: string): string;
-    domain(domain: string): {
-      gettext(s: string): string;
-      ngettext(s: string, p: string, n: number): string;
-      pgettext(ctx: string, s: string): string;
-    };
-    setlocale(): null;
-    bindtextdomain(): null;
-    textdomain(): null;
-    bindtextdomainCodeset(): null;
-    LocaleCategory: Record<string, number>;
-  };
+  /** `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;
   versions: Record<string, unknown>;
 }
 

package/globals.js

@@ -12,6 +12,17 @@
 // Reference: GJS's global definitions (gjs/modules/{print,system,gettext}). The
 // legacy `imports.*` namespace mirrors gjs/modules/esm/gi.js's require shape.
 import { requireGi } from './gi.js';
+// `imports.system` / `imports.gettext` / `imports.cairo` reuse the standalone
+// module implementations — ONE source of truth, also reachable directly as
+// `@gjsify/node-gi/{system,gettext,cairo}` (and the bare `system` / `gettext` /
+// `cairo` specifiers on the `--app node` build).
+import system from './system.js';
+import gettext from './gettext.js';
+import cairo from './cairo.js';
+// Legacy `imports.signals` (the pure-JS Signals mixin) + `imports.mainloop` (the
+// GLib.MainLoop convenience layer) — the GJS script modules many older sources use.
+import * as signalsModule from './overrides/_signals.js';
+import { createMainloop } from './overrides/mainloop.js';
 
 // GJS stringifies each argument with String() and joins with a space (no
 // util.inspect object formatting) — match that for fidelity.
@@ -80,58 +91,36 @@ function makeImports() {
     },
   );
 
-  // Minimal `imports.system` — the most-used members (exit, gc, the program
-  // identity). Backed by Node's process where there is an equivalent.
-  const system = {
-    exit(code) {
-      if (typeof process !== 'undefined') process.exit(code ?? 0);
-    },
-    gc() {
-      if (typeof globalThis.gc === 'function') globalThis.gc();
-    },
-    get programInvocationName() {
-      return (typeof process !== 'undefined' && process.argv[1]) || '';
-    },
-    get programPath() {
-      return (typeof process !== 'undefined' && process.argv[1]) || null;
-    },
-    version: 0,
-    addressOf() {
-      return '0x0';
-    },
-    refcount() {
-      return 0;
-    },
-    breakpoint() {},
-    dumpHeap() {},
-    dumpMemoryInfo() {},
-  };
-
-  // Minimal `imports.gettext` — a no-translation passthrough (the strings are
-  // returned untranslated, which is the correct fallback when no catalog is
-  // bound). Mirrors the surface GJS apps call at module load.
-  const identity = (s) => s;
-  const gettext = {
-    gettext: identity,
-    dgettext: (_domain, s) => s,
-    dcgettext: (_domain, s) => s,
-    ngettext: (s, p, n) => (n === 1 ? s : p),
-    dngettext: (_domain, s, p, n) => (n === 1 ? s : p),
-    pgettext: (_ctx, s) => s,
-    dpgettext: (_domain, _ctx, s) => s,
-    domain: (_domain) => ({
-      gettext: identity,
-      ngettext: (s, p, n) => (n === 1 ? s : p),
-      pgettext: (_ctx, s) => s,
-    }),
-    setlocale: () => null,
-    bindtextdomain: () => null,
-    textdomain: () => null,
-    bindtextdomainCodeset: () => null,
-    LocaleCategory: { ALL: 6, COLLATE: 3, CTYPE: 0, MESSAGES: 5, MONETARY: 4, NUMERIC: 1, TIME: 2 },
+  // `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,
+    signals: { addSignalMethods, _connect, _connectAfter, _disconnect, _emit, _signalHandlerIsConnected, _disconnectAll },
+    versions: Object.create(null),
   };
-
-  return { gi, system, gettext, 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,
+  });
+  return imports;
 }
 
 // Side effect on import: seed the globals.

package/gtk-runtime.d.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+/** A resolved GTK runtime bundle: native-code dir (dylibs on darwin, DLLs on win32) + typelib dir. */
+export interface GtkRuntimeBundle {
+    dir: string;
+    libDir: string;
+    typelibDir: string;
+}
+/** Resolve the GTK runtime bundle directory for this platform, or null. */
+export function resolveGtkRuntimeBundle(): GtkRuntimeBundle | null;
+/** macOS: re-exec once with DYLD_FALLBACK_LIBRARY_PATH set to the bundle (no-op off darwin). */
+export function maybeReexecForGtkRuntime(): void;
+/** Windows: prepend the bundle's gtk/bin DLL dir to process.env.PATH (no-op off win32). */
+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;

package/gtk-runtime.js

@@ -0,0 +1,245 @@
+// 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).
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+// 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
+// it eagerly put it in every runtime's module graph, and under Deno that tripped a
+// teardown regression on an unrelated conformance file (all its tests passed but the
+// process exited non-zero). This keeps non-darwin loads free of that side effect.
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url)); // package root
+
+// Sentinel: set on the re-exec so a bundle-activated child never re-execs again.
+const REEXEC_SENTINEL = 'GJSIFY_GTK_REEXEC';
+
+/**
+ * Resolve the GTK runtime bundle directory for this platform, or `null`. A valid
+ * bundle dir contains the native-code dir (`lib/` relocated dylibs on darwin,
+ * `bin/` DLLs on win32) + `girepository-1.0/` (typelibs).
+ * Search order (first hit wins):
+ *   1. GJSIFY_GTK_RUNTIME env (an explicit bundle dir),
+ *   2. node-gi's own prebuilds/<platform>-<arch>/gtk/ (CI/dev staging path),
+ *   3. the sibling monorepo dir ../gtk-runtime-<platform>-<arch>/gtk,
+ *   4. the published optional dep @gjsify/gtk-runtime-<platform>-<arch>.
+ * @returns {{ dir: string, libDir: string, typelibDir: string } | null}
+ */
+export function resolveGtkRuntimeBundle() {
+    const tag = `${process.platform}-${process.arch}`;
+    const candidates = [];
+
+    if (process.env.GJSIFY_GTK_RUNTIME) candidates.push(process.env.GJSIFY_GTK_RUNTIME);
+    candidates.push(join(here, 'prebuilds', tag, 'gtk'));
+    candidates.push(join(here, '..', `gtk-runtime-${tag}`, 'gtk'));
+    try {
+        // The package's index.js sits at its root; the bundle is ./gtk beside it.
+        const pkgIndex = require.resolve(`@gjsify/gtk-runtime-${tag}`);
+        candidates.push(join(dirname(pkgIndex), 'gtk'));
+    } catch {
+        // Not installed — fine.
+    }
+
+    // The loadable native code lives in `lib` (dylibs) on macOS and `bin` (DLLs) on
+    // Windows. `libDir` is the dir node-gi adds to the OS library search path
+    // (DYLD_FALLBACK on darwin, PATH on win32) — its NAME differs, its ROLE does not.
+    const nativeSubdir = process.platform === 'win32' ? 'bin' : 'lib';
+    for (const dir of candidates) {
+        if (!dir) continue;
+        const libDir = join(dir, nativeSubdir);
+        const typelibDir = join(dir, 'girepository-1.0');
+        if (existsSync(libDir) && existsSync(typelibDir)) return { dir, libDir, typelibDir };
+    }
+    return null;
+}
+
+/**
+ * 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.
+ *
+ * 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
+ * `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.
+ *
+ * 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.
+ * On re-exec this calls `process.exit()` and never returns to the caller.
+ * @returns {void}
+ */
+export function maybeReexecForGtkRuntime() {
+    if (process.platform !== 'darwin') return; // strict no-op on every non-darwin runtime
+    // Node only: the argv/execArgv reconstruction below is Node-shaped, and Node is
+    // the runtime the conformance proves. Bun/Deno set globals of their own — skip the
+    // re-exec there (they still get env-free TYPELIBS via activateBundledGtkRuntime;
+    // 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;
+    if (process.env[REEXEC_SENTINEL]) return; // already re-exec'd — the child path
+    const bundle = resolveGtkRuntimeBundle();
+    if (!bundle) return; // strict no-op when no bundle is present
+
+    const curDyld = process.env.DYLD_FALLBACK_LIBRARY_PATH ?? '';
+    if (curDyld.split(':').filter(Boolean).includes(bundle.libDir)) return; // already covered
+
+    // 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.
+    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,
+    };
+    // Reproduce this exact invocation (node flags + argv) with the augmented env.
+    const res = spawnSync(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {
+        stdio: 'inherit',
+        env,
+    });
+    if (res.error) throw res.error; // spawn failed outright — surface it, don't silently continue mis-linked
+    process.exit(res.status === null ? 1 : res.status);
+}
+
+/**
+ * Prepend the bundled GTK runtime's DLL dir (`gtk/bin`) to `process.env.PATH` so a
+ * later `LoadLibrary` resolves against the bundle with NO gvsbuild/system GTK — both
+ * the native addon's OWN static imports (glib/gobject/gio/girepository/cairo/ffi/…)
+ * AND every runtime `g_module_open(<soname>)` a typelib does for its backers
+ * (Pango/Gdk/Graphene). This is the Windows analog of the darwin re-exec, but
+ * SIMPLER: Windows re-reads the DLL search path at EACH `LoadLibrary` (unlike dyld,
+ * which captures `DYLD_FALLBACK_LIBRARY_PATH` only at process launch), so an
+ * in-process `process.env.PATH` mutation is sufficient — no re-exec, and no native
+ * `AddDllDirectory` (which would be chicken-and-egg: the addon must already be loaded
+ * to expose it). MUST be called at module top-level BEFORE the addon is `require()`'d
+ * (index.js does exactly that, before loadNative()). Strict no-op off win32 / without
+ * a bundle / when the dir is already on PATH. Idempotent.
+ * @returns {void}
+ */
+export function maybePrependGtkRuntimeDllPath() {
+    if (process.platform !== 'win32') return; // strict no-op on every non-win32 runtime
+    const bundle = resolveGtkRuntimeBundle();
+    if (!bundle) return; // strict no-op when no bundle is present
+    const binDir = bundle.libDir; // on win32 the native-code dir is gtk/bin (the DLLs)
+    const cur = process.env.PATH ?? '';
+    if (cur.split(';').filter(Boolean).includes(binDir)) return; // already on PATH
+    process.env.PATH = cur ? `${binDir};${cur}` : binDir;
+}
+
+/**
+ * Wire the env a bundled FULL-WINDOWING GTK runtime needs so a REAL GTK WINDOW
+ * finds its runtime DATA on Windows: compiled GSettings schemas
+ * (`GSETTINGS_SCHEMA_DIR`), the gdk-pixbuf image loaders (`GDK_PIXBUF_MODULEDIR` +
+ * `GDK_PIXBUF_MODULE_FILE`), the icon themes (`XDG_DATA_DIRS` → `<bundle>/share`),
+ * and — when bundled — Fontconfig (`FONTCONFIG_PATH`/`FONTCONFIG_FILE`). These live
+ * beside the DLLs the display-free path already wires (maybePrependGtkRuntimeDllPath).
+ *
+ * STRICT no-op off win32, without a bundle, or when the bundle carries NO windowing
+ * data — keyed on the `share/glib-2.0/schemas/gschemas.compiled` marker the
+ * --windowing build produces, so the DEFAULT display-free bundle is byte-unchanged.
+ * Windows re-reads these vars at first use (schema/loader/icon-theme init runs AFTER
+ * the addon loads), so an in-process mutation here suffices — no re-exec, the DLL-
+ * search analog. Each var is set only when currently unset (a host override wins).
+ * Idempotent; MUST run at module top-level with maybePrependGtkRuntimeDllPath, before
+ * the app initializes GTK. GLib uses `;` as the win32 search-path separator.
+ * @returns {void}
+ */
+export function maybeWireGtkWindowingEnv() {
+    if (process.platform !== 'win32') return; // strict no-op on every non-win32 runtime
+    const bundle = resolveGtkRuntimeBundle();
+    if (!bundle) return; // strict no-op when no bundle is present
+
+    const schemaDir = join(bundle.dir, 'share', 'glib-2.0', 'schemas');
+    // gschemas.compiled = the windowing-data marker; absent → display-free bundle.
+    if (!existsSync(join(schemaDir, 'gschemas.compiled'))) return;
+
+    const setIfUnset = (name, value) => {
+        if (!process.env[name]) process.env[name] = value;
+    };
+    setIfUnset('GSETTINGS_SCHEMA_DIR', schemaDir);
+
+    const loaderCache = join(bundle.dir, 'lib', 'gdk-pixbuf-2.0', '2.10.0', 'loaders.cache');
+    if (existsSync(loaderCache)) {
+        setIfUnset('GDK_PIXBUF_MODULEDIR', join(bundle.dir, 'lib', 'gdk-pixbuf-2.0', '2.10.0', 'loaders'));
+        setIfUnset('GDK_PIXBUF_MODULE_FILE', loaderCache);
+    }
+
+    const shareDir = join(bundle.dir, 'share');
+    if (existsSync(join(shareDir, 'icons'))) {
+        const cur = process.env.XDG_DATA_DIRS ?? '';
+        if (!cur.split(';').filter(Boolean).includes(shareDir)) {
+            process.env.XDG_DATA_DIRS = cur ? `${shareDir};${cur}` : shareDir;
+        }
+    }
+
+    const fontsConf = join(bundle.dir, 'etc', 'fonts', 'fonts.conf');
+    if (existsSync(fontsConf)) {
+        setIfUnset('FONTCONFIG_PATH', join(bundle.dir, 'etc', 'fonts'));
+        setIfUnset('FONTCONFIG_FILE', fontsConf);
+    }
+}
+
+let activated = null; // memoize: the activation result (idempotent)
+
+/**
+ * Activate the bundled GTK runtime for the native engine, if one is present.
+ *   • typelibs — prepend the bundle's girepository-1.0 dir to the GIRepository
+ *     search path (env-free, via the native prependSearchPath); this alone lets
+ *     node-gi FIND the bundled typelibs without GI_TYPELIB_PATH.
+ *   • native code — darwin: prepend the bundle's lib dir to
+ *     process.env.DYLD_FALLBACK_LIBRARY_PATH. NB dyld captures that variable at
+ *     LAUNCH, so setting it here only helps child processes / a re-exec; a bundle
+ *     whose dylibs a namespace loads by leaf name still needs the value present in
+ *     the launching environment (see the package README's env-free caveat).
+ *     Namespaces whose dylib is already in-process via the addon's link closure
+ *     (GLib/GObject/Gio/cairo) resolve regardless. win32: prepend the bundle's bin
+ *     dir to process.env.PATH — already done by maybePrependGtkRuntimeDllPath before
+ *     the addon loaded; re-asserted here for child processes + the runtime
+ *     g_module_open of typelib backers. Windows re-reads PATH per LoadLibrary, so no
+ *     launch-time capture applies (see the package README).
+ * Scoped to darwin + win32 (the platforms shipping a batteries-included bundle).
+ * @param {{ prependSearchPath: (p: string) => void }} native the loaded addon
+ * @returns {{ dir: string, libDir: string, typelibDir: string } | null}
+ */
+export function activateBundledGtkRuntime(native) {
+    if (activated !== null) return activated || null;
+    activated = false;
+    if (process.platform !== 'darwin' && process.platform !== 'win32') return null;
+
+    const bundle = resolveGtkRuntimeBundle();
+    if (!bundle) return null;
+
+    try {
+        native.prependSearchPath(bundle.typelibDir);
+    } catch {
+        // A stubbed/old addon without prependSearchPath — non-fatal.
+    }
+
+    if (process.platform === 'win32') {
+        const existing = process.env.PATH ?? '';
+        if (!existing.split(';').filter(Boolean).includes(bundle.libDir)) {
+            process.env.PATH = existing ? `${bundle.libDir};${existing}` : bundle.libDir;
+        }
+    } 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`;
+        }
+    }
+
+    activated = bundle;
+    return bundle;
+}