@gjsify/node-gi 0.43.0 → 0.45.0

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;
 }
@@ -1142,6 +1162,26 @@ function protoForInstance(handle) {
     return proto === null ? undefined : proto;
 }
 
+// Attach a class prototype to a wrapper — as its [[Prototype]] AND as the USER_PROTO
+// symbol the traps resolve members through.
+//
+// The symbol alone is not the link. `constructor` is RESERVED, so the get trap hands
+// it straight to the bare target, whose [[Prototype]] was Object.prototype: every
+// introspected instance answered `Object` — carrying no `$gtype`, so
+// `GObject.type_name(inst.constructor.$gtype)` was `null` and @gjsify/gtk-host's
+// adopt() / nearestRegistered() / every descriptor lookup failed with
+// "No descriptor registered for null" (99 rows of its node leg). On gjs an instance's
+// [[Prototype]] IS its class's prototype and `constructor` is the class object itself
+// (measured on gjs 1.88.1), which is what the class prototype's own `constructor`
+// back-link — the makeClass Proxy, the object `requireGi` returns — now supplies.
+// It is also what puts a class prototype on the chain findProtoDescriptor walks for
+// `vfunc_*` (see makeClassPrototype). Works on the wrapper Proxy too: neither
+// setPrototypeOf nor the symbol write is trapped, so both reach the target.
+function linkInstanceProto(objOrProxy, proto) {
+    objOrProxy[USER_PROTO] = proto;
+    Object.setPrototypeOf(objOrProxy, proto);
+}
+
 // Wrap a live GObject handle as a GJS-shaped instance. The wrapper resolves its
 // class prototype chain FIRST (a registerClass subclass's own methods, anything
 // the program put on the introspected prototype) — so `inst.myMethod()` runs the
@@ -1164,14 +1204,14 @@ function wrapInstance(handle, userProto) {
         if (userProto !== undefined && userProto !== cached[USER_PROTO]) {
             const current = cached[USER_PROTO];
             if (current === undefined || isProtoSameOrDescendantOf(userProto, current)) {
-                cached[USER_PROTO] = userProto;
+                linkInstanceProto(cached, userProto);
             }
         }
         return cached;
     }
     const target = { [HANDLE]: handle };
     const proto = userProto ?? protoForInstance(handle);
-    if (proto !== undefined) target[USER_PROTO] = proto;
+    if (proto !== undefined) linkInstanceProto(target, proto);
     const proxy = new Proxy(target, {
         get(t, prop) {
             if (prop === HANDLE) return handle;
@@ -1380,11 +1420,33 @@ function prototypeMethodHandle(self, where) {
 // The invocable form of an introspected instance method, as it sits on a class
 // prototype: `this` supplies the GObject, so ONE function serves every instance of
 // the class and `inst.m === Cls.prototype.m` holds (gjs parity).
-function makeGiMethod(where, method) {
+//
+// `arity` becomes the function's `length`, as on gjs (m_js_in_argc — the
+// JS-visible IN args, not the C arg count). A rest-args thunk reports 0, and
+// @gjsify/gtk-host's descriptor conformance reads `.length` to hold the widget
+// table against the installed GTK — `add_titled() takes 3 argument(s), but
+// GtkStack's takes 0` was this thunk, not the typelib.
+function makeGiMethod(where, method, arity) {
     const fn = function (...args) {
         return wrapReturn(native.callMethod(prototypeMethodHandle(this, where), method, unwrapArgs(args)));
     };
     Object.defineProperty(fn, 'name', { value: method, configurable: true });
+    Object.defineProperty(fn, 'length', { value: arity, configurable: true });
+    return fn;
+}
+
+// The invocable form of an introspected VFUNC as it sits on a class prototype. Like
+// makeGiMethod, but the engine resolves the vtable slot of THIS class (not a captured
+// parent pointer), so it works on a plain `new Ns.Class()` — which is what gjs does
+// and what `vfunc_add_child` (a GtkBuildable slot with no introspected method form)
+// has no other route to.
+function makeGiVFunc(namespace, typeName, vfuncName, where) {
+    const fn = function (...args) {
+        return wrapReturn(
+            native.callClassVfunc(prototypeMethodHandle(this, where), namespace, typeName, vfuncName, unwrapArgs(args)),
+        );
+    };
+    Object.defineProperty(fn, 'name', { value: `vfunc_${vfuncName}`, configurable: true });
     return fn;
 }
 
@@ -1407,7 +1469,7 @@ function makeClassPrototype(namespace, typeName) {
         configurable: true,
     });
     const where = `${namespace}.${typeName}.prototype`;
-    const resolved = new Map(); // accessor name -> is an introspected method of this class
+    const resolved = new Map(); // accessor name -> method arity (-1 = absent) or vfunc addressability
     // Writable + configurable: a program REPLACES a method to instrument it and puts
     // the original back afterwards, which is the whole point of the prototype.
     // Enumerable, like the methods gjs's resolve hook defines.
@@ -1421,6 +1483,25 @@ function makeClassPrototype(namespace, typeName) {
     const materialize = (prop) => {
         if (typeof prop !== 'string' || RESERVED.has(prop)) return false;
         if (Object.prototype.hasOwnProperty.call(target, prop)) return true;
+        // A vfunc slot. Defining it HERE — rather than leaving it to the vfuncChainProto
+        // Proxy below the prototype — is what makes it reachable from an INSTANCE: the
+        // wrapper resolves members by descriptor (findProtoDescriptor), and a Proxy that
+        // traps only `get` reports no descriptor and no `in`, so `new Gtk.Box()
+        // .vfunc_add_child` was `undefined` while `Gtk.Box.prototype.vfunc_add_child` was
+        // a function. Gated on the engine being able to ADDRESS the slot, which gives gjs
+        // parity two ways: an unknown vfunc name stays `undefined` instead of becoming a
+        // throw-on-call thunk, and a name the engine cannot address (GObject's own vfuncs
+        // report GI_UNKNOWN as their struct offset) still falls through to the chain-up
+        // thunk, so `super.vfunc_dispose()` keeps working.
+        if (prop.startsWith('vfunc_')) {
+            const vfuncName = prop.slice('vfunc_'.length);
+            let addressable = resolved.get(prop);
+            if (addressable === undefined) {
+                addressable = native.hasClassVfunc(namespace, typeName, vfuncName);
+                resolved.set(prop, addressable);
+            }
+            return addressable && define(prop, makeGiVFunc(namespace, typeName, vfuncName, `${where}.${prop}`));
+        }
         // gjs's GObject.Object.prototype members are JS shims over namespace-level
         // functions (see objectPrototypeShim), and `bind_property_full` even HAS an
         // introspected GIR shadow — bind_with_closures, whose GValue write-back a
@@ -1431,12 +1512,14 @@ function makeClassPrototype(namespace, typeName) {
                 return shim(prototypeMethodHandle(this, `${where}.${prop}`), args);
             });
         }
-        let present = resolved.get(prop);
-        if (present === undefined) {
-            present = native.hasClassMethod(namespace, typeName, prop);
-            resolved.set(prop, present);
+        // ONE native call answers both presence (arity >= 0) and the function's
+        // `length` — see classMethodArity in calls.cc.
+        let arity = resolved.get(prop);
+        if (arity === undefined) {
+            arity = native.classMethodArity(namespace, typeName, prop);
+            resolved.set(prop, arity);
         }
-        return present && define(prop, makeGiMethod(where, prop));
+        return arity >= 0 && define(prop, makeGiMethod(where, prop, arity));
     };
     return new Proxy(target, {
         get(t, prop, receiver) {
@@ -2064,6 +2147,15 @@ function collectVfuncs(klass) {
     const vfuncs = {};
     const seen = new Set();
     for (let p = klass.prototype; p !== null && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
+        // The INTROSPECTED base's prototype declares no user override, and since it
+        // materializes its own `vfunc_*` members on first look-up (makeClassPrototype)
+        // it now CARRIES such names: without this boundary a program that read
+        // `base.vfunc_activate` before registering a subclass had that vfunc collected
+        // as the subclass's own override, installing a trampoline for a slot the user
+        // never wrote ("registerClass vfunc 'activate' not found on any ancestor").
+        // CLASS_INFO is stamped only by makeClassPrototype, and only OWN counts — a
+        // registered subclass's prototype inherits it from its base.
+        if (p !== klass.prototype && Object.prototype.hasOwnProperty.call(p, CLASS_INFO)) break;
         const owner = Object.getOwnPropertyDescriptor(p, 'constructor')?.value;
         if (owner !== undefined && owner !== klass && registeredClasses.has(owner)) break;
         for (const key of Object.getOwnPropertyNames(p)) {

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';
@@ -469,9 +469,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 +528,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 +554,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

@@ -108,6 +108,16 @@ export function hasMethod(handle: GObjectHandle, methodName: string): boolean;
  */
 export function hasClassMethod(namespace: string, typeName: string, methodName: string): boolean;
 
+/**
+ * The JS-visible IN-arg count of an instance method — what gjs reports as the
+ * materialized function's `length` (IN/INOUT args minus array-length and
+ * callback user_data/destroy-notify slots) — or -1 when the name does not
+ * resolve to an invocable instance method. Resolution is shared with
+ * {@link hasClassMethod}, so `classMethodArity(...) >= 0` answers both
+ * questions in one call.
+ */
+export function classMethodArity(namespace: string, typeName: string, methodName: string): number;
+
 /**
  * Invoke a type-level constructor/static function (e.g. `Gio.File.new_for_path`,
  * `Gtk.Label.new`) — a function found on a type but taking no instance. The Node
@@ -232,6 +242,34 @@ export function registerClass(
  */
 export function callParentVfunc(handle: GObjectHandle, vfuncName: string, args?: unknown[]): unknown;
 
+/**
+ * Whether `Ns.Type.prototype.vfunc_<vfuncName>` can be dispatched directly — i.e.
+ * an ancestor of `typeName` (or one of the interfaces it implements) declares that
+ * virtual function AND girepository can locate its slot in the class's vtable.
+ * The gate the L1 class prototype asks before materializing a vfunc member: `false`
+ * leaves the name `undefined` (gjs parity for an unknown vfunc) or, for a declared
+ * one whose struct offset girepository reports as unknown — GObject's own vfuncs —
+ * lets it fall through to the {@link callParentVfunc} chain-up thunk.
+ */
+export function hasClassVfunc(namespace: string, typeName: string, vfuncName: string): boolean;
+
+/**
+ * Invoke the virtual function `Ns.Type` carries in its vtable, with `handle` as the
+ * instance — what `new Gtk.Box().vfunc_add_child(builder, child, null)` does on gjs,
+ * and the ONLY route to a `Gtk.Buildable` adder (`add_child` is introspected as a
+ * vfunc, never as a method). Unlike {@link callParentVfunc} this needs no
+ * {@link registerClass} override: the slot comes from the class itself. Same
+ * marshalling and same `[returnValue?, ...outArgs]` return convention. Throws if the
+ * vfunc is not addressable on that class, or if `handle` is not an instance of it.
+ */
+export function callClassVfunc(
+    handle: GObjectHandle,
+    namespace: string,
+    typeName: string,
+    vfuncName: string,
+    args?: unknown[],
+): unknown;
+
 /**
  * Construct a GObject of a registered type handle (from {@link registerClass})
  * with optional construct/settable properties. For a templated type the engine
@@ -544,6 +582,7 @@ declare const native: {
     callMethod: typeof callMethod;
     hasMethod: typeof hasMethod;
     hasClassMethod: typeof hasClassMethod;
+    classMethodArity: typeof classMethodArity;
     callStaticMethod: typeof callStaticMethod;
     constructStruct: typeof constructStruct;
     newObject: typeof newObject;

package/index.js

@@ -198,6 +198,7 @@ export const callFunction = native.callFunction;
 export const callMethod = native.callMethod;
 export const hasMethod = native.hasMethod;
 export const hasClassMethod = native.hasClassMethod;
+export const classMethodArity = native.classMethodArity;
 export const callStaticMethod = native.callStaticMethod;
 export const constructStruct = native.constructStruct;
 export const newObject = native.newObject;
@@ -212,6 +213,8 @@ export const registerClassFromGType = native.registerClassFromGType;
 
 export const constructType = native.constructType;
 export const callParentVfunc = native.callParentVfunc;
+export const hasClassVfunc = native.hasClassVfunc;
+export const callClassVfunc = native.callClassVfunc;
 export const getTemplateChild = native.getTemplateChild;
 export const getProperty = native.getProperty;
 export const setProperty = native.setProperty;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "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",

package/src/addon.cc

@@ -79,6 +79,7 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("callMethod", Napi::Function::New(env, CallMethod));
   exports.Set("hasMethod", Napi::Function::New(env, HasMethod));
   exports.Set("hasClassMethod", Napi::Function::New(env, HasClassMethod));
+  exports.Set("classMethodArity", Napi::Function::New(env, ClassMethodArity));
   exports.Set("callStaticMethod", Napi::Function::New(env, CallStaticMethod));
   exports.Set("constructStruct", Napi::Function::New(env, ConstructStruct));
   exports.Set("newObject", Napi::Function::New(env, NewObject));
@@ -86,6 +87,8 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("registerClassFromGType", Napi::Function::New(env, RegisterClassFromGType));
   exports.Set("constructType", Napi::Function::New(env, ConstructType));
   exports.Set("callParentVfunc", Napi::Function::New(env, CallParentVfunc));
+  exports.Set("hasClassVfunc", Napi::Function::New(env, HasClassVfunc));
+  exports.Set("callClassVfunc", Napi::Function::New(env, CallClassVfunc));
   exports.Set("getTemplateChild", Napi::Function::New(env, GetTemplateChild));
   exports.Set("getProperty", Napi::Function::New(env, GetProperty));
   exports.Set("setProperty", Napi::Function::New(env, SetProperty));