@gjsify/node-gi 0.44.0 → 0.46.0

package/README.md

@@ -35,9 +35,10 @@ vendored as-is — gjsify ships its own dual (GJS + Node) example/test infra.
 
 - **Node.js ≥ 20, Bun ≥ 1.3, or Deno ≥ 2** — the engine is a Node-API addon, so
   ONE binary serves all three (see [Runtimes](#runtimes-node--bun--deno)).
-- **No C++ toolchain on the four prebuilt targets.** The published tarball ships
-  `prebuilds/<platform>-<arch>/node_gi.node` for `linux-x64`, `linux-arm64`,
-  `darwin-arm64` and `win32-x64` (`package.json#gjsify.platforms`), and the
+- **No C++ toolchain on a prebuilt target.** The published tarball ships
+  `prebuilds/<platform>-<arch>/node_gi.node` for every target
+  `package.json#gjsify.platforms` declares — `linux-x64`, `linux-arm64`,
+  `darwin-arm64`, `darwin-x64`, `win32-x64` — and the
   `install` script (`scripts/install.mjs`) uses it instead of building: a source
   build is the FALLBACK for a host with no prebuild, not the default. Force it
   with `NODE_GI_BUILD_FROM_SOURCE=1` (or npm's `--build-from-source`); skip it
@@ -55,6 +56,14 @@ vendored as-is — gjsify ships its own dual (GJS + Node) example/test infra.
   specific target, so each new bundle is found by the mechanism that found the
   first. The loader contract and the per-platform measurements are
   [docs/node-gi-platform-notes.md](../../../docs/node-gi-platform-notes.md).
+- An application that carries **its own** GI library — a typelib plus the shared
+  library behind it, staged beside the app rather than installed — names those
+  directories in `GJSIFY_GI_LIBRARY_PATH` (`:`-separated; `;` on Windows;
+  absolute paths only). node-gi reads it in JS and hands the directories to
+  `gi_repository_prepend_library_path()`, so GI can open the bare leaf its own
+  typelib records. This is the only route that survives on macOS: dyld strips
+  every `DYLD_*` from a restricted process, so a signed `.app` cannot use one.
+  Entries take precedence over the GTK bundle / system GI libdirs.
 
 ## Install
 
@@ -76,12 +85,25 @@ npm install @gjsify/gtk-runtime-darwin-arm64   # macOS Apple silicon
 npm install @gjsify/gtk-runtime-darwin-x64     # macOS Intel
 ```
 
-All three declare `os`/`cpu`, so npm/yarn/pnpm skip them off-platform. Making them
-`optionalDependencies` of this package (which would remove the manual step
-without any consumer-side platform branching) is pending two decisions outside
-this package — the ADR-0003 dependency-direction rule between node-gi's tier
-and the bundles', and `os`/`cpu` filtering in `gjsify install`'s native
-backend, which currently places foreign-platform optional deps.
+All three declare `os`/`cpu`, so npm/yarn/pnpm skip them off-platform.
+
+**This package will not declare one, and that is a decision, not a gap** —
+[ADR 0023 § 1 + § 3](../../../docs/adr/0023-gtk-source-precedence.md). Whoever
+SHIPS an application declares the bundle (for the showcases that is the `gjsify`
+CLI, which adds `@gjsify/gtk-runtime-<target>` to the tree it assembles); node-gi
+declares it in no dependency field at all. The reason is #910: a CI job compiled
+the addon against Homebrew GTK and then ran it on a bundle it had never been
+linked against, producing wrong method entries and a 29-minute timeout. #920
+reverted the dependency and the prohibition was written down. Pairing a
+from-source addon with a bundle is not a preference that came out wrong, it is
+an ABI error, so the bundle cannot arrive by default.
+
+What that costs is worth stating rather than discovering: on a Mac or a Windows
+box with **no** system GTK and **no** bundle installed, `@gjsify/node-gi` does
+not load at all — its addon's own link closure (`libgirepository-2.0`,
+`libglib-2.0`, `libcairo`) is unresolvable, and the failure names only the
+`.node` file (#1063). The addon's rpath lists exactly the two places it accepts:
+a sibling `gtk-runtime-<target>/gtk/lib`, and the host's `/usr/local/lib`.
 
 ## Usage
 

package/gi.js

@@ -70,6 +70,26 @@ function unwrapArg(value) {
     if (value !== null && typeof value === 'object' && value[HANDLE] !== undefined) {
         return value[HANDLE];
     }
+    // An ARRAY is a container whose ELEMENTS need the same unwrapping, and until this
+    // line they did not get it: only the top-level argument was unwrapped, so an array
+    // of GObjects reached the engine as an array of JS wrappers and
+    // `NodeGiToGIArgument`'s GI_TYPE_TAG_INTERFACE branch — which accepts nothing but
+    // an External carrying the handle — threw
+    // `expected a GObject handle as a container element`. That is EVERY GI method
+    // taking an array of objects, not one method: measured on
+    // `Gio.ListStore.splice(0, n, [a, b])`, where `append(a)` on the same store
+    // succeeded because one GObject as a top-level arg was always unwrapped.
+    //
+    // `Array.isArray`, not `typeof value === 'object'`: a Uint8Array is a
+    // GByteArray/guint8[] argument the engine reads directly, and mapping over it here
+    // would turn it into a plain Array and lose that.
+    //
+    // Recursive, so a nested array and a GObject inside one are handled by the same
+    // rule rather than by a second one that drifts — and this is now the same shape
+    // `wrapReturn` has carried all along for the OTHER direction. That asymmetry is
+    // why the gap stayed invisible: a container coming BACK had its elements wrapped,
+    // a container going IN did not, and nothing read both lines at once.
+    if (Array.isArray(value)) return value.map(unwrapArg);
     if (typeof value === 'function') return wrapCallbackFn(value);
     return value;
 }
@@ -146,7 +166,12 @@ function buildGError(domainName, domainQuark, code, message) {
     error.domainQuark = domainQuark;
     return error;
 }
-native.setErrorBuilder(buildGError);
+// The CLASS is registered with the builder, because the engine needs it the other
+// way round too: a `GError`-typed IN argument recognises a caught (or `new`-ed)
+// GLib.Error by `instanceof` and rebuilds a real GError from its fields, so an
+// application can hand back the error it is holding (`GLib.propagate_error`,
+// `Gst.Message.new_error`). One call, so builder and class cannot drift apart.
+native.setErrorBuilder(buildGError, GLibError);
 
 // Stamps a makeClass prototype with its { namespace, typeName } so Gio._promisify can
 // record WHICH introspected class a registration belongs to — matched against the
@@ -1388,6 +1413,28 @@ function defineLazyGType(ctor, namespace, typeName) {
     });
 }
 
+// The GType a static call's `this` names, or `null` when the receiver names none —
+// a primitive, a plain object, a raw (unregistered) subclass. `null` means "no
+// receiver", and the engine then runs the method on the type the name was read from,
+// which is the pre-#1438 behaviour for every non-class-struct call.
+//
+// A class answers its own `$gtype`. An INSTANCE has none — `$gtype` is a
+// constructor-level member here — but gjs answers the instance's RUNTIME class for
+// it, and the difference is observable: measured, `GObject.Object.list_properties`
+// borrowed onto an instance of a registerClass'd subclass reads the SUBCLASS's 6
+// pspecs under gjs and read GObject's 0 here. So resolve it through the type system,
+// the route `Symbol.hasInstance` above already takes.
+function gtypeOf(receiver) {
+    if (receiver === null || receiver === undefined) return null;
+    if (typeof receiver !== 'function' && typeof receiver !== 'object') return null;
+    const gt = receiver.$gtype;
+    if (gt !== undefined) return gt;
+    const handle = receiver[HANDLE];
+    if (handle === undefined || !native.isGObjectHandle(handle)) return null;
+    const G = requireGi('GObject', '2.0');
+    return G.type_from_name(native.getTypeName(handle));
+}
+
 // The GObject behind a prototype method's `this`. A prototype function is
 // reachable without an instance (`Cls.prototype.m()`, a detached reference), so
 // the engine must never be handed `undefined` for the instance argument.
@@ -1626,7 +1673,20 @@ function makeClass(namespace, typeName) {
                 return objectStaticConstructor(prop);
             }
             const giName = camelToSnake(prop);
-            return (...args) => wrapReturn(native.callStaticMethod(namespace, typeName, giName, unwrapArgs(args)));
+            // NOT an arrow: a class-struct method (GObjectClass's `list_properties`,
+            // `find_property`, …) runs on the class the call went THROUGH, so `this` is
+            // load-bearing and an arrow would discard it (#1438). What the engine does
+            // with it — and why a plain static and an incompatible receiver ignore it —
+            // is `CallStaticMethod`'s header in `src/calls.cc`.
+            return function (...args) {
+                // Short-circuit the direct `Ns.Class.method()` call: the engine would
+                // compare the receiver against the same GType and ignore it anyway, and
+                // the read would arm the lazy `$gtype` getter for nothing.
+                const receiverGType = this === proxy ? null : gtypeOf(this);
+                return wrapReturn(
+                    native.callStaticMethod(namespace, typeName, giName, unwrapArgs(args), receiverGType),
+                );
+            };
         },
     });
     // Replacing ctor.prototype dropped the automatic back-link; restore it pointing at
@@ -1708,6 +1768,17 @@ function makeEnum(namespace, typeName) {
     if (domain !== null) {
         Object.defineProperty(out, ERROR_DOMAIN, { value: domain, enumerable: false });
     }
+    // `Ns.Enum.$gtype` — gjs answers a registered G_TYPE_ENUM/G_TYPE_FLAGS here, so
+    // `GObject.type_name(Gio.BusType.$gtype)` is `GBusType` there and was `null` over
+    // the bridge: an enum object carried no `$gtype` at all. EAGER rather than
+    // defineLazyGType, because the object is frozen on the way out and a
+    // self-redefining getter could never install its cache. Non-enumerable, so
+    // `Object.keys` stays the member list; omitted entirely for an UNREGISTERED enum,
+    // which has no GType and where gjs answers `undefined` too.
+    const gtype = native.getGType(namespace, typeName);
+    if (gtype !== null) {
+        Object.defineProperty(out, '$gtype', { value: gtype, enumerable: false });
+    }
     return Object.freeze(out);
 }
 

package/gtk-runtime.d.ts

@@ -19,7 +19,10 @@ export function activateBundledGtkRuntime(native: {
     prependLibraryPath?: (p: string) => void;
 }): GtkRuntimeBundle | null;
 
-/** Prepend GI's shared-library search path for the GTK the policy chose. */
+/** Absolute directories from `GJSIFY_GI_LIBRARY_PATH` — where an app carries its OWN GI libraries. */
+export function appGiLibraryDirs(opts?: { platform?: NodeJS.Platform | string; env?: NodeJS.ProcessEnv }): string[];
+
+/** Prepend GI's shared-library search path: the app's own dirs, then the GTK the policy chose. */
 export function activateGiLibraryPath(native: { prependLibraryPath?: (p: string) => void }): string[];
 /** TEST-ONLY: allow the activation to run again. */
 export function resetGiLibraryPathForTests(): void;

package/gtk-runtime.js

@@ -9,7 +9,7 @@
 // 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 { dirname, join, posix, win32 } from 'node:path';
 import { existsSync } from 'node:fs';
 import { composeDyldFallback, pathCovers, splitSearchPath, systemGiLibraryDirs } from './system-gi.js';
 import { nativeCandidates, prebuildAddonPath } from './native-paths.js';
@@ -460,6 +460,20 @@ export function maybeWireGtkWindowingEnv() {
         const scanner = join(bundle.dir, 'libexec', 'gstreamer-1.0', gstScannerLeaf());
         if (existsSync(scanner)) setIfUnset('GST_PLUGIN_SCANNER', scanner);
     }
+
+    // The GIO modules, and specifically the TLS backend. `GTlsConnection` has no
+    // implementation in GIO itself — glib-networking ships one as a module GIO
+    // g_module_opens out of ONE directory, whose compiled-in default is the BUILD
+    // machine's prefix. On a user's box that path is absent (or, worse, a foreign
+    // glib-networking against a different GLib), so a bundle-activated process fell back
+    // to the dummy backend and every https request failed: `souphttpsrc` reports
+    // "Internal data stream error", @gjsify/{tls,http2,ws} fail the same way one layer up.
+    //
+    // GIO_MODULE_DIR, not GIO_EXTRA_MODULES, for GST_PLUGIN_SYSTEM_PATH's reason: it
+    // REPLACES the compiled-in default rather than adding to it, and mixing a host's
+    // modules into the bundle's own GIO is the case we are avoiding, not one to preserve.
+    const gioModules = join(bundle.dir, 'lib', 'gio', 'modules');
+    if (existsSync(gioModules)) setIfUnset('GIO_MODULE_DIR', gioModules);
 }
 
 /** The plugin scanner's leaf name — the bundles ship the same tree on both OSes. */
@@ -469,9 +483,49 @@ function gstScannerLeaf() {
 
 let libraryPathActivated = false;
 
+/**
+ * Where an APPLICATION carries the shared libraries ITS OWN typelibs name by bare
+ * leaf — `GJSIFY_GI_LIBRARY_PATH`, `:`-separated (`;` on win32).
+ *
+ * THE GAP THIS CLOSES is a different one from the note below. An app shipping a GI
+ * library of its own (`gjsify.ship.bundledTypelibs`) stages the typelib and its
+ * backer side by side and points `GI_TYPELIB_PATH` there, so GI finds the typelib
+ * and then `g_module_open`s a bare leaf nothing has located. The launcher's
+ * `LD_LIBRARY_PATH` covers that on linux; on macOS no environment variable can,
+ * because dyld strips every `DYLD_*` from a restricted process and a signed,
+ * hardened `.app` IS restricted — so a launcher depending on one works unsigned and
+ * breaks at signing time. The dirs below do not cover it either: they answer "where
+ * is the GTK stack", never "where are this application's own libraries". Neither
+ * does `dirname(GI_TYPELIB_PATH entry)`: {@link systemGiLibraryDirs} derives a
+ * libdir that way because GI's INSTALL layout puts typelibs in
+ * `<libdir>/girepository-1.0/`, and an app stages the pair FLAT, so that derivation
+ * yields the directory's PARENT — a real path holding nothing.
+ *
+ * Only ABSOLUTE entries are kept: a relative one resolves against the working
+ * directory, which for a double-clicked `.app` is `/`. PURE in its inputs, so the
+ * win32 dialect is executable from any host.
+ * @param {object} [opts]
+ * @param {NodeJS.Platform | string} [opts.platform]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @returns {string[]} absolute directories, in the order the variable listed them
+ */
+export function appGiLibraryDirs({ platform = process.platform, env = process.env } = {}) {
+    const isAbsolute = platform === 'win32' ? win32.isAbsolute : posix.isAbsolute;
+    const out = [];
+    for (const dir of splitSearchPath(env.GJSIFY_GI_LIBRARY_PATH, platform === 'win32' ? ';' : ':')) {
+        if (isAbsolute(dir) && !out.includes(dir)) out.push(dir);
+    }
+    return out;
+}
+
 /**
  * Tell GI where the shared libraries its typelibs name by BARE LEAF actually are
- * — for whichever GTK the policy chose, and WITHOUT an environment variable.
+ * — for whichever GTK the policy chose plus whatever the app carries itself, and
+ * WITHOUT a loader environment variable.
+ *
+ * `GJSIFY_GI_LIBRARY_PATH` is not a counter-example: it is read by THIS process, in
+ * JS, and handed to GI through the binding. dyld never sees it — which is the whole
+ * point, because dyld is what refuses to see `DYLD_*` in a signed, hardened app.
  *
  * THE GAP THIS CLOSES. A typelib records its backer as `libgtk-4.1.dylib`, and on
  * macOS neither a relocated bundle's `lib` dir nor Homebrew's `/usr/local/lib` is
@@ -488,10 +542,23 @@ let libraryPathActivated = false;
  * still cover a dylib pulled in by ANOTHER dylib's link closure, which never
  * passes through GI.
  *
- * The dirs come from `gtkSource()`, not a second opinion: the bundle's `libDir`
- * for `bundle`, `systemGiLibraryDirs()` for `system` — the pair the re-exec
- * composes. Mixing them is the two-copies hazard #920 records. Idempotent, and
- * never fatal: an addon predating the binding changes nothing.
+ * The GTK dirs come from `gtkSource()`, not a second opinion: the bundle's
+ * `libDir` for `bundle`, `systemGiLibraryDirs()` for `system` — the pair the
+ * re-exec composes. Mixing them is the two-copies hazard #920 records. The
+ * application's own dirs ({@link appGiLibraryDirs}) are added on TOP of whichever
+ * of those the policy picked, and independently of it: an app carrying its own GI
+ * library needs it found whether the GTK behind it is a bundle, the host's, or —
+ * `source === 'none'` — neither.
+ *
+ * ORDER: the app's entries come FIRST. That only decides an OVERLAP — a leaf both
+ * places hold — since a name only one of them has is found either way. An
+ * explicitly-set variable is consent and outranks an inferred location (the
+ * precedence `GJSIFY_GTK_RUNTIME` already has over the probed bundle candidates),
+ * and on an overlap the app's copy is the one its OWN typelib was compiled against:
+ * the pair ships as a unit, and splitting it is not a missing library but an ABI
+ * mismatch — #910's failure shape, the expensive one.
+ *
+ * Idempotent, and never fatal: an addon predating the binding changes nothing.
  * @param {{ prependLibraryPath?: (p: string) => void }} native the loaded addon
  * @returns {string[]} the directories handed to GI (empty when there was nothing to add)
  */
@@ -501,12 +568,18 @@ export function activateGiLibraryPath(native) {
     if (typeof native?.prependLibraryPath !== 'function') return [];
 
     const source = gtkSource();
-    const dirs =
+    const gtkDirs =
         source === 'bundle' ? [resolveGtkRuntimeBundle()?.libDir] : source === 'system' ? systemGiLibraryDirs() : [];
+    const dirs = [];
+    // Deduplicated: an app that names a directory the policy already found would
+    // otherwise grow GI's search path by a second, identical entry.
+    for (const dir of [...appGiLibraryDirs(), ...gtkDirs.filter(Boolean)]) {
+        if (!dirs.includes(dir)) dirs.push(dir);
+    }
     const applied = [];
     // LAST wins with a prepend, so walking in reverse leaves the array's own
     // order intact in GI's search path.
-    for (const dir of dirs.filter(Boolean).reverse()) {
+    for (const dir of dirs.reverse()) {
         native.prependLibraryPath(dir);
         applied.unshift(dir);
     }

package/index.d.ts

@@ -57,10 +57,15 @@ export function getErrorDomain(namespace: string, name: string): { name: string;
 
 /**
  * Register the L1 GLib.Error factory the engine calls when a GI invoke fails, so
- * a failed sync call throws a real `GLib.Error` (instanceof, with `.matches()`).
+ * a failed sync call throws a real `GLib.Error` (instanceof, with `.matches()`),
+ * together with the CLASS it builds — which a `GError`-typed IN argument uses to
+ * recognise such an error coming back and rebuild a real `GError` from its
+ * fields. Without the class that direction accepts only a marshalled (boxed)
+ * error, so a caught one cannot be handed on.
  */
 export function setErrorBuilder(
     builder: (domainName: string, domainQuark: number, code: number, message: string) => Error,
+    errorClass?: new (domain: unknown, code: number, message: string) => Error,
 ): void;
 
 /** Prepend a directory to the GIRepository typelib search path. */
@@ -387,6 +392,14 @@ export function setBoxedField(handle: BoxedHandle, name: string, value: unknown)
  * registered GType. Lets L1 attach type-specific conveniences (GLib.Bytes.toArray).
  */
 export function boxedTypeName(value: unknown): string | null;
+/**
+ * TEST-ONLY: the address a boxed handle wraps, as a hex string (`null` for anything
+ * else). Lets a test assert an IN-transfer ownership rule — "a transfer-full boxed
+ * IN arg is handed a COPY" — directly, instead of running the call many times and
+ * waiting for a double free that only aborts when the allocator has not recycled
+ * the block. Nothing on the runtime path may branch on it.
+ */
+export function __boxedAddress(value: unknown): string | null;
 
 /**
  * Opaque handle to a GObject.ParamSpec (a GObject fundamental, ref-counted via
@@ -604,6 +617,7 @@ declare const native: {
     getBoxedField: typeof getBoxedField;
     setBoxedField: typeof setBoxedField;
     boxedTypeName: typeof boxedTypeName;
+    __boxedAddress: typeof __boxedAddress;
     isParamSpecHandle: typeof isParamSpecHandle;
     paramSpecProp: typeof paramSpecProp;
     variantNew: typeof variantNew;

package/index.js

@@ -16,6 +16,7 @@ import {
     maybeReexecForGtkRuntime,
     maybeWireGtkWindowingEnv,
 } from './gtk-runtime.js';
+import { activateNativePrebuilds } from './native-prebuilds.js';
 
 // macOS bundled GTK: dyld reads DYLD_FALLBACK_LIBRARY_PATH only at launch, and GI
 // needs it to g_module_open typelib backers (get_type / Pango / Gdk / Graphene) by
@@ -124,6 +125,18 @@ try {
     // Never fatal: a missing/partial bundle just leaves the host GTK in charge.
 }
 
+// Every OTHER staged prebuild typelib (@gjsify/webkit-native and its kin): same
+// env-free treatment, so a namespace whose typelib is installed in node_modules
+// resolves under a plain `node app.mjs` and not only under `gjsify run`. Deliberately
+// AFTER the GTK activation — that one owns the bundle-vs-host policy (ADR 0023) and
+// this one skips gtk-runtime-* for exactly that reason.
+try {
+    activateNativePrebuilds(native);
+} catch {
+    // Same contract as the calls around it: a failed discovery leaves the search
+    // path untouched, and the caller gets GI's own "typelib not found".
+}
+
 // And where the LIBRARIES those typelibs name actually live. Separate from the
 // call above because it is not about a bundle: it applies to whichever GTK the
 // policy chose, and it is the only loader repair bun and deno get on macOS —
@@ -231,6 +244,9 @@ export const boxedMemberKind = native.boxedMemberKind;
 export const getBoxedField = native.getBoxedField;
 export const setBoxedField = native.setBoxedField;
 export const boxedTypeName = native.boxedTypeName;
+/** TEST-ONLY: the address a boxed handle wraps, so an ownership rule about pointer
+ * IDENTITY can be asserted instead of waited on (see marshal.cc BoxedAddress). */
+export const __boxedAddress = native.__boxedAddress;
 export const isParamSpecHandle = native.isParamSpecHandle;
 
 // True for a non-GObject GObject-fundamental handle (a GskRenderNode from