@gjsify/node-gi 0.38.1 → 0.40.0

package/README.md

@@ -479,6 +479,47 @@ A *passive* fd source with no pending op (e.g. only a listening
 `Gio.SocketService`) does not keep the process alive on its own, and a
 purely-sync program still exits immediately.
 
+#### Class prototypes and the lookup order
+
+`Ns.Class.prototype` is a real prototype: reading a name on it MATERIALIZES the
+introspected method behind that name (the JS twin of the `resolve` hook GJS
+installs on every GObject prototype), and every wrapper resolves its members
+through the prototype of its runtime GType — a `registerClass` subclass's own
+prototype, otherwise the introspected class's — before any native fallback. So
+instrumenting a method works the way it does on GJS:
+
+```js
+const proto = Gio.ZlibDecompressor.prototype;
+const original = proto.convert;             // the introspected method
+proto.convert = function (...args) {        // instrument it
+    calls++;
+    return original.apply(this, args);
+};
+const d = new Gio.ZlibDecompressor({ format: Gio.ZlibCompressorFormat.GZIP });
+d.convert === proto.convert;                // true — and the wrapper IS called
+proto.convert = original;                   // put it back
+```
+
+Until 0.39 an instance ignored its prototype: the assignment stuck, `d.convert`
+still reached the native method, and a spy-based test reported itself installed
+while measuring nothing. Byte-compared against GJS by the `prototype-chain`
+conformance program.
+
+Lookup order on a wrapper: own JS field → the class prototype chain →
+`runAsync` / the GObject.js shims → GObject property → inherited `Object.prototype`
+member → a `Gio._promisify` registration → introspected method → `undefined`.
+
+Deliberate divergences from GJS, all measured:
+
+- class prototypes are NOT chained to their base classes, so `instanceof` goes
+  through `g_type_is_a` (see below) and an interface method materializes once per
+  implementing class instead of being one shared function;
+- GObject **properties** are not surfaced as prototype accessors — they resolve on
+  the instance only;
+- a private concrete GType (`GLocalFile`) resolves to its nearest INTROSPECTABLE
+  ancestor rather than to the interface GJS would use, which is why
+  `Gio._promisify` also keeps a per-class registry.
+
 #### `GLib.Variant` (build + unpack, GJS semantics)
 
 `new GLib.Variant(signature, value)` recursively builds a GVariant from a type

package/gi.js

@@ -149,16 +149,16 @@ function buildGError(domainName, domainQuark, code, message) {
 native.setErrorBuilder(buildGError);
 
 // Stamps a makeClass prototype with its { namespace, typeName } so Gio._promisify can
-// record WHICH introspected class a registration belongs to — introspected instances
-// have no live prototype chain to resolve by, so it is matched against the instance's
-// GType via native.isInstanceOf.
+// record WHICH introspected class a registration belongs to — matched against the
+// instance's GType via native.isInstanceOf when the promisified prototype is not the
+// one the instance resolves through.
 const CLASS_INFO = Symbol('nodeGiClassInfo');
 
 // Promisified async methods: GI method name (snake_case) → registrations
-// `{ namespace?, typeName?, wrapper }`. Introspected-class instances resolve methods
-// dynamically (no prototype chain), so the instance proxy consults this registry;
-// when two classes promisify the SAME method name it picks the registration whose
-// class the instance is-a.
+// `{ namespace?, typeName?, wrapper }`. An instance whose concrete GType resolves to a
+// DIFFERENT prototype than the promisified one (a private GLocalFile against
+// Gio.File.prototype) reaches the wrapper only through this registry; when two classes
+// promisify the SAME method name it picks the registration whose class the instance is-a.
 const promisifiedMethods = new Map();
 
 function wrapReturn(value) {
@@ -1113,11 +1113,42 @@ function instanceHasMethod(handle, name) {
     return present;
 }
 
-// Wrap a live GObject handle as a GJS-shaped instance. When `userProto` is given
-// (a registerClass subclass's prototype) the wrapper resolves the user class's
-// own prototype members FIRST — so `inst.myMethod()` runs the JS method with the
-// wrapper as `this` — then falls back to GObject property get/set and GI method
-// routing. `.connect()/.emit()/.disconnect()` work in both modes.
+// The JS prototype a wrapper resolves its members through, by runtime GType name.
+// Stable for the process — a GType neither gains ancestors nor changes class.
+const protoByGTypeName = new Map();
+
+// EVERY wrapper gets a prototype, as in GJS where an instance's [[Prototype]] IS
+// its class's prototype: without one, a member assigned to `Ns.Class.prototype` was
+// accepted and observable there yet invisible to the instance, which kept reaching
+// the native method underneath (#1175) — a spy that reports itself installed and
+// then measures nothing. A registerClass subclass's own prototype when the GType is
+// one we registered, else the introspected class's.
+function protoForInstance(handle) {
+    const gtypeName = native.getTypeName(handle);
+    if (gtypeName === null) return undefined;
+    const cached = protoByGTypeName.get(gtypeName);
+    if (cached !== undefined) return cached === null ? undefined : cached;
+    const registered = classesByGType.get(gtypeName);
+    let proto = registered !== undefined ? registered.prototype : null;
+    if (proto === null) {
+        // Only LOADED namespaces are searched, and a namespace object is reached
+        // through the same per-namespace cache `requireGi` fills, so the prototype
+        // resolved here is the very object a program can patch.
+        const info = native.classInfoForTypeName(gtypeName);
+        const cls = info === null ? undefined : namespaceObject(info.namespace)[info.name];
+        if (cls !== undefined && cls !== null) proto = cls.prototype ?? null;
+    }
+    protoByGTypeName.set(gtypeName, proto);
+    return proto === null ? undefined : 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
+// JS method with the wrapper as `this` — then falls back to GObject property
+// get/set and GI method routing. `userProto` overrides the prototype derived from
+// the handle's GType, for the construction paths that already know the leaf class.
+// `.connect()/.emit()/.disconnect()` work in both modes.
 function wrapInstance(handle, userProto) {
     const cached = instanceCache.get(handle);
     if (cached !== undefined) {
@@ -1139,7 +1170,8 @@ function wrapInstance(handle, userProto) {
         return cached;
     }
     const target = { [HANDLE]: handle };
-    if (userProto !== undefined) target[USER_PROTO] = userProto;
+    const proto = userProto ?? protoForInstance(handle);
+    if (proto !== undefined) target[USER_PROTO] = proto;
     const proxy = new Proxy(target, {
         get(t, prop) {
             if (prop === HANDLE) return handle;
@@ -1181,12 +1213,22 @@ function wrapInstance(handle, userProto) {
                 default:
                     break;
             }
+            // A plain JS field previously written on THIS wrapper. With the toggle-ref
+            // bridge the wrapper is CANONICAL (one proxy per GObject, cached by the
+            // canonical native handle), so a plain field IS shared across the
+            // vfunc<->instance boundary and survives a round-trip + GC while C owns the
+            // object. Read FIRST, before the class prototype — ordinary JS lookup order.
+            // (GObject PROPERTIES remain the right choice for state C must also see; the
+            // `set` trap routes those to GObject, so no expando competes with one.)
+            if (Object.prototype.hasOwnProperty.call(t, prop)) return t[prop];
             const up = t[USER_PROTO];
             if (up !== undefined) {
                 const desc = findProtoDescriptor(up, prop);
                 if (desc !== undefined) {
-                    if (typeof desc.value === 'function') return (...args) => desc.value.apply(proxy, args);
                     if (typeof desc.get === 'function') return desc.get.call(proxy);
+                    // The prototype's OWN function, never a re-bound thunk: `this` comes
+                    // from the call site anyway, and re-binding breaks the identity a
+                    // spy is recognised by — `inst.m === Cls.prototype.m` (#1175).
                     return desc.value;
                 }
             }
@@ -1210,25 +1252,16 @@ function wrapInstance(handle, userProto) {
             if (native.hasProperty(handle, propName)) {
                 return wrapReturn(native.getProperty(handle, propName));
             }
-            // Surface a plain JS field previously written on THIS wrapper. With the
-            // toggle-ref bridge the wrapper is now CANONICAL (one proxy per GObject,
-            // cached by the canonical native handle), so a plain field IS shared across
-            // the vfunc<->instance boundary and survives a round-trip + GC while C owns
-            // the object — a vfunc's `this` resolves to the same cached proxy as
-            // construct, and `store.get_item(x)` returns the same proxy a setter wrote
-            // to. Own-property only (set via the `set` trap), so an introspected GI
-            // method of the same name is never shadowed unless the user explicitly
-            // assigned an expando. (GObject PROPERTIES remain the right choice for state
-            // that must also be visible to C / other language bindings.)
-            if (Object.prototype.hasOwnProperty.call(t, prop)) return t[prop];
             // LAST resort before treating an unknown name as a GI method: an INHERITED
             // member (Object.prototype.hasOwnProperty / isPrototypeOf / … — RESERVED
             // already covers toString/valueOf/etc.) must resolve to the real function,
             // not a GI callMethod thunk that would throw on `inst.hasOwnProperty('x')`.
             if (prop in t) return t[prop];
-            // A Gio._promisify'd async method (registerClass subclasses pick it up via
-            // their userProto above; introspected instances have no prototype chain, so
-            // they resolve it here from the registry, per-class). Bound to this instance.
+            // A Gio._promisify'd async method. The prototype lookup above already finds
+            // it whenever the promisified prototype is on the instance's chain; the
+            // registry covers what a chain cannot reach — a private concrete type
+            // (GLocalFile) resolves to its nearest INTROSPECTABLE ancestor, so an
+            // instance of it never sees `Gio.File.prototype`. Bound to this instance.
             const promisified = resolvePromisified(handle, camelToSnake(prop));
             if (promisified !== undefined) return (...args) => promisified.apply(proxy, args);
             // GJS parity: an UNKNOWN member is `undefined`, never a throw-on-call
@@ -1335,6 +1368,91 @@ function defineLazyGType(ctor, namespace, typeName) {
     });
 }
 
+// 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.
+function prototypeMethodHandle(self, where) {
+    const handle = self === null || self === undefined ? undefined : self[HANDLE];
+    if (handle === undefined) throw new TypeError(`${where}: \`this\` is not a node-gi instance`);
+    return handle;
+}
+
+// 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) {
+    const fn = function (...args) {
+        return wrapReturn(native.callMethod(prototypeMethodHandle(this, where), method, unwrapArgs(args)));
+    };
+    Object.defineProperty(fn, 'name', { value: method, configurable: true });
+    return fn;
+}
+
+// A class prototype that MATERIALIZES its introspected methods on first look-up —
+// the JS twin of the SpiderMonkey `resolve` hook gjs installs on every GObject
+// prototype (refs/gjs gi/object.cpp). Without it a node-gi prototype stayed
+// permanently empty, so `Cls.prototype.method` read `undefined` and wrapping a
+// method had nothing to wrap (#1175). Lazy, not eager: a class like Gtk.Widget
+// carries hundreds of inherited methods and a program touches a handful.
+function makeClassPrototype(namespace, typeName) {
+    const target = {};
+    // Put the vfunc chain-up Proxy beneath the prototype so a registerClass
+    // subclass's `super.vfunc_<name>(...)` resolves (see vfuncChainProto).
+    Object.setPrototypeOf(target, vfuncChainProto);
+    // Stamp the prototype with its class identity so Gio._promisify(Cls.prototype, …)
+    // can record which class a registration belongs to (non-enumerable).
+    Object.defineProperty(target, CLASS_INFO, {
+        value: { namespace, typeName },
+        enumerable: false,
+        configurable: true,
+    });
+    const where = `${namespace}.${typeName}.prototype`;
+    const resolved = new Map(); // accessor name -> is an introspected method of this class
+    // 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.
+    const define = (prop, value) => {
+        Object.defineProperty(target, prop, { value, writable: true, enumerable: true, configurable: true });
+        return true;
+    };
+    // Defines the member on the target and reports whether the name resolved, so the
+    // traps answer from the target itself and stay within the Proxy invariants (a
+    // reported own property must really exist on an extensible target).
+    const materialize = (prop) => {
+        if (typeof prop !== 'string' || RESERVED.has(prop)) return false;
+        if (Object.prototype.hasOwnProperty.call(target, prop)) return true;
+        // 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
+        // marshaled GClosure cannot satisfy — so the shim must win here too.
+        const shim = objectPrototypeShim(prop);
+        if (shim !== undefined) {
+            return define(prop, function (...args) {
+                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);
+        }
+        return present && define(prop, makeGiMethod(where, prop));
+    };
+    return new Proxy(target, {
+        get(t, prop, receiver) {
+            materialize(prop);
+            return Reflect.get(t, prop, receiver);
+        },
+        getOwnPropertyDescriptor(t, prop) {
+            materialize(prop);
+            return Reflect.getOwnPropertyDescriptor(t, prop);
+        },
+        has(t, prop) {
+            return materialize(prop) || Reflect.has(t, prop);
+        },
+    });
+}
+
 function makeClass(namespace, typeName) {
     const ctor = function ctor(props) {
         // G3/G2 construction routing. `new.target` is the leaf class the `new` was
@@ -1382,20 +1500,12 @@ function makeClass(namespace, typeName) {
     Object.defineProperty(ctor, 'name', { value: typeName, configurable: true });
     ctor.$gtypeName = `${namespace}.${typeName}`;
     defineLazyGType(ctor, namespace, typeName);
-    // Put the vfunc chain-up Proxy beneath this base class's prototype so a
-    // registerClass subclass's `super.vfunc_<name>(...)` resolves (see above).
-    Object.setPrototypeOf(ctor.prototype, vfuncChainProto);
-    // Stamp the prototype with its class identity so Gio._promisify(Cls.prototype, …)
-    // can record which class a registration belongs to (non-enumerable).
-    Object.defineProperty(ctor.prototype, CLASS_INFO, {
-        value: { namespace, typeName },
-        enumerable: false,
-        configurable: true,
-    });
+    ctor.prototype = makeClassPrototype(namespace, typeName);
     // `inst instanceof Ns.Class` — GJS parity for the WHOLE GObject hierarchy, not
-    // just the leaf class. An instance is a Proxy over a bare `{[HANDLE]}` (no live JS
-    // prototype chain linking Adw.ApplicationWindow → Gtk.ApplicationWindow → …), so
-    // the default instanceof (a prototype-chain walk) reported `false` for every base
+    // just the leaf class. An instance is a Proxy carrying its class prototype as a
+    // SYMBOL rather than as [[Prototype]], and class prototypes are not linked to their
+    // bases (no Adw.ApplicationWindow → Gtk.ApplicationWindow → … chain), so the
+    // default instanceof (a prototype-chain walk) reported `false` for every base
     // class. Resolve it by the GObject type system instead: `native.isInstanceOf`
     // (g_type_is_a) recognises subclasses AND implemented interfaces, exactly like GJS.
     // Guarded by `isGObjectHandle` first — a bare/boxed/variant handle (or any non-node-gi
@@ -1456,6 +1566,14 @@ function makeClass(namespace, typeName) {
             return (...args) => wrapReturn(native.callStaticMethod(namespace, typeName, giName, unwrapArgs(args)));
         },
     });
+    // Replacing ctor.prototype dropped the automatic back-link; restore it pointing at
+    // the class the user actually holds (the Proxy), not the raw ctor behind it.
+    Object.defineProperty(ctor.prototype, 'constructor', {
+        value: proxy,
+        writable: true,
+        enumerable: false,
+        configurable: true,
+    });
     return proxy;
 }
 
@@ -2316,6 +2434,30 @@ function createNamespace(namespace) {
 
 const namespaceCache = new Map();
 
+// The ONE namespace object per GI namespace, as in gjs where `imports.gi.Ns` is a
+// singleton. Keyed by NAMESPACE alone: a repository cannot hold two versions at
+// once, and keying by `Ns@version` handed `requireGi('Gio','2.0')` and
+// `requireGi('Gio')` two independent objects — `Gio.File !== Gio.File` between the
+// spellings, a prototype patched through one invisible through the other. Does NOT
+// load the typelib (requireGi does that first).
+function namespaceObject(namespace) {
+    let ns = namespaceCache.get(namespace);
+    if (ns === undefined) {
+        ns = createNamespace(namespace);
+        // The GObject namespace also carries the GJS runtime statics (registerClass +
+        // ParamSpec/ParamFlags/SignalFlags) layered over its introspected members.
+        if (namespace === 'GObject') ns = decorateGObjectNamespace(ns);
+        // The GLib namespace carries the GJS-shaped GLib.Variant ergonomics
+        // (new GLib.Variant(sig, value) + deepUnpack/unpack/recursiveUnpack) and the
+        // GLib.Error class.
+        else if (namespace === 'GLib') ns = decorateGLibNamespace(ns);
+        // The Gio namespace carries Gio._promisify (async → Promise).
+        else if (namespace === 'Gio') ns = decorateGioNamespace(ns);
+        namespaceCache.set(namespace, ns);
+    }
+    return ns;
+}
+
 // Whether the libuv↔GLib bridge has been attached this process. The native
 // startMainLoop is itself idempotent; this just avoids the extra call.
 let loopAttached = false;
@@ -2373,22 +2515,7 @@ export function requireGi(namespace, version) {
         }
         loopAttached = true;
     }
-    const key = version ? `${namespace}@${version}` : namespace;
-    let ns = namespaceCache.get(key);
-    if (ns === undefined) {
-        ns = createNamespace(namespace);
-        // The GObject namespace also carries the GJS runtime statics (registerClass +
-        // ParamSpec/ParamFlags/SignalFlags) layered over its introspected members.
-        if (namespace === 'GObject') ns = decorateGObjectNamespace(ns);
-        // The GLib namespace carries the GJS-shaped GLib.Variant ergonomics
-        // (new GLib.Variant(sig, value) + deepUnpack/unpack/recursiveUnpack) and the
-        // GLib.Error class.
-        else if (namespace === 'GLib') ns = decorateGLibNamespace(ns);
-        // The Gio namespace carries Gio._promisify (async → Promise).
-        else if (namespace === 'Gio') ns = decorateGioNamespace(ns);
-        namespaceCache.set(key, ns);
-    }
-    return ns;
+    return namespaceObject(namespace);
 }
 
 /**

package/index.d.ts

@@ -99,6 +99,15 @@ export function callMethod(handle: GObjectHandle, methodName: string, args?: unk
  */
 export function hasMethod(handle: GObjectHandle, methodName: string): boolean;
 
+/**
+ * The CLASS-level twin of {@link hasMethod}: `true` iff `Ns.Type` declares an
+ * invocable instance method by that name (literal introspected name or
+ * snake_case alias), across own, implemented-interface and inherited methods.
+ * Answers by TYPE rather than by instance handle, which is what lets a class
+ * prototype resolve its methods before any instance of it exists.
+ */
+export function hasClassMethod(namespace: string, typeName: string, methodName: string): boolean;
+
 /**
  * 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
@@ -254,6 +263,15 @@ export function hasProperty(handle: GObjectHandle, name: string): boolean;
 /** The runtime GType name of a GObject handle (e.g. "GSimpleAction"). */
 export function getTypeName(handle: GObjectHandle): string;
 
+/**
+ * The introspected type that OWNS a runtime GType name — the reverse of
+ * {@link getGType}, walking up to the nearest ancestor carrying object info (a
+ * private concrete type such as `GLocalFile` has none of its own). Searches only
+ * LOADED namespaces, so it never pulls in a typelib as a side effect. `null` when
+ * the GType is unknown or no ancestor is introspectable.
+ */
+export function classInfoForTypeName(gtypeName: string): { namespace: string; name: string } | null;
+
 /**
  * The runtime GType of an introspected registered type, as an opaque node-gi
  * GType handle ({@link TypeHandle} — a tag-distinct External carrying the GType,
@@ -525,6 +543,7 @@ declare const native: {
     callFunction: typeof callFunction;
     callMethod: typeof callMethod;
     hasMethod: typeof hasMethod;
+    hasClassMethod: typeof hasClassMethod;
     callStaticMethod: typeof callStaticMethod;
     constructStruct: typeof constructStruct;
     newObject: typeof newObject;
@@ -535,6 +554,7 @@ declare const native: {
     setProperty: typeof setProperty;
     hasProperty: typeof hasProperty;
     getTypeName: typeof getTypeName;
+    classInfoForTypeName: typeof classInfoForTypeName;
     getGType: typeof getGType;
     isInstanceOf: typeof isInstanceOf;
     isGObjectHandle: typeof isGObjectHandle;

package/index.js

@@ -197,6 +197,7 @@ export const prependLibraryPath = native.prependLibraryPath;
 export const callFunction = native.callFunction;
 export const callMethod = native.callMethod;
 export const hasMethod = native.hasMethod;
+export const hasClassMethod = native.hasClassMethod;
 export const callStaticMethod = native.callStaticMethod;
 export const constructStruct = native.constructStruct;
 export const newObject = native.newObject;
@@ -216,6 +217,7 @@ export const getProperty = native.getProperty;
 export const setProperty = native.setProperty;
 export const hasProperty = native.hasProperty;
 export const getTypeName = native.getTypeName;
+export const classInfoForTypeName = native.classInfoForTypeName;
 export const getGType = native.getGType;
 export const isInstanceOf = native.isInstanceOf;
 export const isGObjectHandle = native.isGObjectHandle;

package/package.json

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

@@ -78,6 +78,7 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("callFunction", Napi::Function::New(env, CallFunction));
   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("callStaticMethod", Napi::Function::New(env, CallStaticMethod));
   exports.Set("constructStruct", Napi::Function::New(env, ConstructStruct));
   exports.Set("newObject", Napi::Function::New(env, NewObject));
@@ -90,6 +91,7 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("setProperty", Napi::Function::New(env, SetProperty));
   exports.Set("hasProperty", Napi::Function::New(env, HasProperty));
   exports.Set("getTypeName", Napi::Function::New(env, GetTypeName));
+  exports.Set("classInfoForTypeName", Napi::Function::New(env, ClassInfoForTypeName));
   exports.Set("getGType", Napi::Function::New(env, GetGType));
   exports.Set("isInstanceOf", Napi::Function::New(env, IsInstanceOf));
   exports.Set("isGObjectHandle", Napi::Function::New(env, IsGObjectHandle));

package/src/calls.cc

@@ -673,6 +673,23 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
           // don't. The out-container is freed (or borrowed) by ReadOutOrReturn per the
           // SAME (OUT) transfer. Verified vs gjs 1.88 (GIMarshallingTests.array_inout,
           // garray/glist/gslist/gptrarray/ghashtable_utf8_none_inout, bytearray_full_inout).
+          //
+          // THAT ABI IS TAKEN FROM THE ANNOTATION AND CANNOT BE VERIFIED HERE. `c:type`
+          // — the only place `gchar*` and `gchar**` differ — lives in the GIR XML and is
+          // NOT compiled into the typelib. `GLib.base64_decode_inplace` is annotated
+          // `direction="inout"` over a `c:type="gchar*"`, one star; compared field by
+          // field against a genuine `gchar***` INOUT (`GLib.OptionContext.parse`'s
+          // `argv`) its metadata is identical — direction INOUT, transfer EVERYTHING,
+          // tag ARRAY, is_pointer true, caller-allocates false. A mis-annotated callee
+          // therefore receives `&slots[i]` and writes its output OVER the GIArgument
+          // union, and the read-back below marshals and frees a clobbered pointer.
+          // Measured: five runs of that one call, five different return values; gjs
+          // corrupts identically, so there is no oracle to compare against either.
+          //
+          // Nothing to detect on this side — the discriminator is data the runtime does
+          // not have — and a per-function denylist ossifies. Upstream annotation bug:
+          // `status/upstream-patch-candidates.md`. `test/arrays.test.mjs` records why
+          // that call was removed from the suite and must not come back.
           Napi::Value v = jsCursor < args.Length() ? args.Get(jsCursor) : env.Undefined();
           jsCursor++;
           if (!IsSupportedContainerType(ti, &why)) {
@@ -1066,9 +1083,10 @@ static std::string CamelToSnake(const std::string& name) {
 
 // The instance's concrete GType may lack introspection info (e.g. a private
 // GLocalFile); walk up to the nearest ancestor GType that has an object info.
-// Returns a new ref or nullptr. Shared by CallMethod (invoke) and HasMethod
-// (feature detection) so both resolve identically.
-static GIObjectInfo* FindNearestObjectInfo(GIRepository* repo, GType gtype) {
+// Returns a new ref or nullptr. Shared by CallMethod (invoke), HasMethod
+// (feature detection) and object.cc's ClassInfoForTypeName (the L1 prototype
+// lookup) so all three resolve the same way.
+GIObjectInfo* FindNearestObjectInfo(GIRepository* repo, GType gtype) {
   for (GType t = gtype; t != 0; t = g_type_parent(t)) {
     GIBaseInfo* bi = gi_repository_find_by_gtype(repo, t);
     if (bi != nullptr) {
@@ -1225,6 +1243,54 @@ Napi::Value HasMethod(const Napi::CallbackInfo& info) {
   return Napi::Boolean::New(env, invocable);
 }
 
+// hasClassMethod(namespace, typeName, methodName) -> boolean
+// The CLASS-level twin of hasMethod: TRUE iff `Ns.Type` declares an invocable
+// instance method by that name (literal introspected name first, snake_case
+// alias second — the resolution callMethod itself performs), across own,
+// implemented-interface and inherited methods. Keyed by TYPE rather than by an
+// instance handle because it backs the lazy method resolution on the class
+// PROTOTYPE (#1175), which must answer before any instance exists.
+Napi::Value HasClassMethod(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 3 || !info[0].IsString() || !info[1].IsString() || !info[2].IsString()) {
+    Napi::TypeError::New(env,
+                         "hasClassMethod(namespace: string, typeName: string, methodName: string)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  std::string ns = info[0].As<Napi::String>().Utf8Value();
+  std::string tn = info[1].As<Napi::String>().Utf8Value();
+  std::string method = info[2].As<Napi::String>().Utf8Value();
+
+  GIRepository* repo = DupDefaultRepository();
+  GIBaseInfo* base = gi_repository_find_by_name(repo, ns.c_str(), tn.c_str());
+  GIFunctionInfo* func = nullptr;
+  if (base != nullptr) {
+    if (GI_IS_OBJECT_INFO(base)) {
+      GType gtype =
+          gi_registered_type_info_get_g_type(reinterpret_cast<GIRegisteredTypeInfo*>(base));
+      // An object info always carries a registered GType; the guard is for the
+      // interface-list step, which would warn on G_TYPE_INVALID.
+      if (gtype != G_TYPE_INVALID) {
+        func = ResolveInstanceMethod(repo, gtype, reinterpret_cast<GIObjectInfo*>(base), method);
+      }
+    } else if (GI_IS_INTERFACE_INFO(base)) {
+      GIInterfaceInfo* iface = reinterpret_cast<GIInterfaceInfo*>(base);
+      func = gi_interface_info_find_method(iface, method.c_str());
+      if (func == nullptr) {
+        const std::string snake = CamelToSnake(method);
+        if (snake != method) func = gi_interface_info_find_method(iface, snake.c_str());
+      }
+    }
+    gi_base_info_unref(base);
+  }
+  g_object_unref(repo);
+  if (func == nullptr) return Napi::Boolean::New(env, false);
+  const bool invocable = gi_callable_info_is_method(reinterpret_cast<GICallableInfo*>(func));
+  gi_base_info_unref(func);
+  return Napi::Boolean::New(env, invocable);
+}
+
 // callStaticMethod(namespace, typeName, methodName, args?) -> unknown
 // 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

package/src/common.h

@@ -556,6 +556,11 @@ Napi::Value PrependLibraryPath(const Napi::CallbackInfo& info);
 Napi::Value CallFunction(const Napi::CallbackInfo& info);
 Napi::Value CallMethod(const Napi::CallbackInfo& info);
 Napi::Value HasMethod(const Napi::CallbackInfo& info);
+Napi::Value HasClassMethod(const Napi::CallbackInfo& info);
+// The nearest ancestor GType carrying object introspection info (a concrete type
+// may be private — GLocalFile); a new ref, or nullptr. Shared with object.cc so
+// method dispatch and prototype lookup resolve to the same class.
+GIObjectInfo* FindNearestObjectInfo(GIRepository* repo, GType gtype);
 Napi::Value CallStaticMethod(const Napi::CallbackInfo& info);
 // The `new <Struct>()` [[Construct]] path: route to the struct's 'new'
 // constructor when it has one, else zero-allocate (GJS gi/boxed.cpp parity).
@@ -588,6 +593,7 @@ Napi::Value GetProperty(const Napi::CallbackInfo& info);
 Napi::Value SetProperty(const Napi::CallbackInfo& info);
 Napi::Value HasProperty(const Napi::CallbackInfo& info);
 Napi::Value GetTypeName(const Napi::CallbackInfo& info);
+Napi::Value ClassInfoForTypeName(const Napi::CallbackInfo& info);
 Napi::Value GetGType(const Napi::CallbackInfo& info);
 Napi::Value IsInstanceOf(const Napi::CallbackInfo& info);
 Napi::Value IsGObjectHandle(const Napi::CallbackInfo& info);

package/src/loop.cc

@@ -509,14 +509,30 @@ static void PumpDrainContext() {
   if (scope != nullptr) napi_close_handle_scope(g_loop_env, scope);
 }
 
-// The prepare+query HINT pass: learn GLib's earliest-timer deadline + poll fds
-// and mirror them into the uv timer / uv_poll watchers, so libuv's poll sleep
-// ends exactly when GLib next has work. The context is left "prepared" without a
-// matching check/dispatch — safe: the next g_main_context_iteration() (ours or a
-// blocking loop's) simply re-prepares. Runs only at g_main_depth() == 0; the
+// The prepare+query+check HINT pass: learn GLib's earliest-timer deadline + poll
+// fds and mirror them into the uv timer / uv_poll watchers, so libuv's poll sleep
+// ends exactly when GLib next has work. Runs only at g_main_depth() == 0; the
 // g_in_uv_pump flag is held across it so UvLoopSource stays parked (masking uv's
 // backend fd out of the queried set — it must not be uv_poll'd, and uv's own
 // backend timeout must not feed back into the timer hint).
+//
+// The CHECK is not cosmetic and must never be dropped again: a GSource may hold a
+// LOCK between its prepare() and its check(), and leaving the context prepared
+// deadlocks the process on the next call into that library. GDK's Wayland event
+// source is exactly that shape — its prepare() takes libwayland's designated-reader
+// slot (`wl_display_prepare_read_queue`) and only its check() releases it
+// (`wl_display_read_events` / `wl_display_cancel_read`). Measured (gjsify #1145,
+// gtk 4.22 / Fedora 44 / Mesa Vulkan): with the hint pass ending at query, the very
+// next `gtk_window_present()` blocked forever inside `wl_display_roundtrip_queue`
+// under `gsk_renderer_new_for_surface_full`, so the app never finished showing its
+// window while its GDBus worker thread kept answering Peer.Ping and Introspect —
+// a live process at ~0.5 % CPU that read as "devtools hangs". Only Wayland shows
+// it (GdkX11's source holds nothing across the pair), only node (bun/deno pump
+// through complete `g_main_context_iteration`s), and only once GTK was initialised
+// at g_main_depth() == 0 — `Gio.Application.register()` before `runAsync()` does
+// exactly that, which is why an app that only ever calls `run()` never saw it.
+// Passing revents = 0 is the right reading: this pass did NOT poll, so no fd is
+// reported ready and every source that took something in prepare() gives it back.
 static void PumpArmWakeups() {
   if (!g_pump_inited || g_main_depth() > 0 || g_in_uv_pump) return;
   GMainContext* ctx = g_main_context_default();
@@ -531,6 +547,14 @@ static void PumpArmWakeups() {
     nfds = g_main_context_query(ctx, prio, &timeout, g_pump_fds->data(),
                                 static_cast<gint>(g_pump_fds->size()));
   }
+  // g_main_context_query fills fd + events and leaves revents untouched, so the
+  // previous pass's values would otherwise be replayed as fresh readiness.
+  for (int i = 0; i < nfds; i++) (*g_pump_fds)[i].revents = 0;
+  // No dispatch pairs with this check: g_main_context_prepare() clears
+  // pending_dispatches on entry (glib gmain.c), and PumpDrainContext() — a full
+  // iteration — runs on the same libuv turn, so anything this marks ready is
+  // dispatched there rather than being stranded.
+  g_main_context_check(ctx, prio, g_pump_fds->data(), nfds);
   g_in_uv_pump = FALSE;
 
   if (!SyncPumpPolls(nfds)) {

package/src/object.cc

@@ -745,6 +745,39 @@ Napi::Value GetTypeName(const Napi::CallbackInfo& info) {
   return Napi::String::New(env, G_OBJECT_TYPE_NAME(obj));
 }
 
+// classInfoForTypeName(gtypeName) -> { namespace, name } | null
+// The introspected type that OWNS a runtime GType name — the reverse of
+// getGType, over the same nearest-ancestor walk method resolution uses (a
+// private concrete type such as GLocalFile carries no info of its own). L1 needs
+// it to hand a wrapper the JS prototype of its class, so that a member the
+// program put on `Ns.Class.prototype` is what the instance resolves (#1175).
+// Searches only LOADED namespaces (gi_repository_find_by_gtype), so it never
+// pulls in a typelib as a side effect of wrapping an object.
+Napi::Value ClassInfoForTypeName(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "classInfoForTypeName(gtypeName: string)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  std::string typeName = info[0].As<Napi::String>().Utf8Value();
+  GType gtype = g_type_from_name(typeName.c_str());
+  if (gtype == G_TYPE_INVALID) return env.Null();
+  GIRepository* repo = DupDefaultRepository();
+  GIObjectInfo* objInfo = FindNearestObjectInfo(repo, gtype);
+  Napi::Value result = env.Null();
+  if (objInfo != nullptr) {
+    GIBaseInfo* base = reinterpret_cast<GIBaseInfo*>(objInfo);
+    Napi::Object out = Napi::Object::New(env);
+    out.Set("namespace", Napi::String::New(env, gi_base_info_get_namespace(base)));
+    out.Set("name", Napi::String::New(env, gi_base_info_get_name(base)));
+    gi_base_info_unref(base);
+    result = out;
+  }
+  g_object_unref(repo);
+  return result;
+}
+
 // getGType(namespace, name) -> GType handle | null
 // The runtime GType of an introspected registered type (object/interface/struct/
 // union/enum/flags), as a node-gi GType handle. The L1 layer surfaces it as a