@gjsify/node-gi 0.42.0 → 0.44.0

package/gi.js

@@ -1142,6 +1142,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 +1184,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 +1400,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 +1449,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 +1463,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 +1492,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 +2127,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/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.42.0",
+  "version": "0.44.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));

package/src/calls.cc

@@ -432,6 +432,70 @@ void ThrowGError(Napi::Env env, GError* error, const std::string& context) {
   Napi::Error::New(env, "Calling " + context + ": " + message).ThrowAsJavaScriptException();
 }
 
+// Which of a callable's args are NOT consumed from the JS argument list:
+//  - the user_data + destroy-notify slots associated with a callback arg
+//    (filled from the callback itself);
+//  - array-length args of an array IN/OUT arg or of the return value
+//    (autofilled from the array's JS length / wired as an OUT slot; flagged
+//    in `isLenArg` so the invoke loop can tell the two skip kinds apart).
+// SHARED between the invoke loop and JsInArgCount below so the arity a
+// function REPORTS is by construction the arity the invoke CONSUMES.
+static void ComputeSkippedArgs(GICallableInfo* callable, unsigned int n_args,
+                               std::vector<bool>* skip, std::vector<bool>* isLenArg) {
+  for (unsigned int i = 0; i < n_args; i++) {
+    GIArgInfo* ai = gi_callable_info_get_arg(callable, i);
+    GITypeInfo* ti = gi_arg_info_get_type_info(ai);
+    if (gi_type_info_get_tag(ti) == GI_TYPE_TAG_INTERFACE) {
+      GIBaseInfo* iface = gi_type_info_get_interface(ti);
+      if (iface != nullptr && GI_IS_CALLBACK_INFO(iface)) {
+        int ci = ArgClosureIndex(ai);
+        int di = ArgDestroyIndex(ai);
+        if (ci >= 0 && static_cast<unsigned int>(ci) < n_args) (*skip)[ci] = true;
+        if (di >= 0 && static_cast<unsigned int>(di) < n_args) (*skip)[di] = true;
+      }
+      if (iface != nullptr) gi_base_info_unref(iface);
+    } else if (gi_type_info_get_tag(ti) == GI_TYPE_TAG_ARRAY) {
+      unsigned int L = 0;
+      if (gi_type_info_get_array_length_index(ti, &L) && L < n_args) {
+        (*skip)[L] = true;
+        (*isLenArg)[L] = true;
+      }
+    }
+    gi_base_info_unref(ti);
+    gi_base_info_unref(ai);
+  }
+  GITypeInfo* rt = gi_callable_info_get_return_type(callable);
+  if (gi_type_info_get_tag(rt) == GI_TYPE_TAG_ARRAY) {
+    unsigned int L = 0;
+    if (gi_type_info_get_array_length_index(rt, &L) && L < n_args) {
+      (*skip)[L] = true;
+      (*isLenArg)[L] = true;
+    }
+  }
+  gi_base_info_unref(rt);
+}
+
+// The number of JS arguments a callable consumes: IN/INOUT args minus the
+// skipped ones. This is what gjs reports as `Function.length` (m_js_in_argc,
+// refs/gjs/gi/function.cpp Function::init counts exactly the same set), and it
+// is what @gjsify/gtk-host's descriptor conformance reads to hold the widget
+// table against the installed typelib.
+int JsInArgCount(GICallableInfo* callable) {
+  unsigned int n_args = gi_callable_info_get_n_args(callable);
+  std::vector<bool> skip(n_args, false);
+  std::vector<bool> isLenArg(n_args, false);
+  ComputeSkippedArgs(callable, n_args, &skip, &isLenArg);
+  int count = 0;
+  for (unsigned int i = 0; i < n_args; i++) {
+    if (skip[i]) continue;
+    GIArgInfo* ai = gi_callable_info_get_arg(callable, i);
+    GIDirection d = gi_arg_info_get_direction(ai);
+    gi_base_info_unref(ai);
+    if (d == GI_DIRECTION_IN || d == GI_DIRECTION_INOUT) count++;
+  }
+  return count;
+}
+
 static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpointer instance,
                                       Napi::Array args, const std::string& displayName) {
   GICallableInfo* callable = reinterpret_cast<GICallableInfo*>(func);
@@ -488,56 +552,10 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
     }
   }
 
-  // Pre-scan: the user_data + destroy-notify slots associated with a callback
-  // arg are filled from the callback, not consumed from the JS argument list.
+  // Pre-scan: which args are NOT JS-consumed (see ComputeSkippedArgs).
   std::vector<bool> skip(n_args, false);
-  for (unsigned int i = 0; i < n_args; i++) {
-    GIArgInfo* ai = gi_callable_info_get_arg(callable, i);
-    GITypeInfo* ti = gi_arg_info_get_type_info(ai);
-    if (gi_type_info_get_tag(ti) == GI_TYPE_TAG_INTERFACE) {
-      GIBaseInfo* iface = gi_type_info_get_interface(ti);
-      if (iface != nullptr && GI_IS_CALLBACK_INFO(iface)) {
-        int ci = ArgClosureIndex(ai);
-        int di = ArgDestroyIndex(ai);
-        if (ci >= 0 && static_cast<unsigned int>(ci) < n_args) skip[ci] = true;
-        if (di >= 0 && static_cast<unsigned int>(di) < n_args) skip[di] = true;
-      }
-      if (iface != nullptr) gi_base_info_unref(iface);
-    }
-    gi_base_info_unref(ti);
-    gi_base_info_unref(ai);
-  }
-
-  // Pre-scan: array-length args. An array IN/OUT arg — or the return value — may
-  // carry a separate introspectable length arg. Mark it skip (not JS-consumed)
-  // and flag it so its OUT slot is wired below / its IN value is autofilled from
-  // the array's JS length when the array arg is marshalled. This extends the same
-  // skip mechanism the callback closure/destroy slots already use.
   std::vector<bool> isLenArg(n_args, false);
-  for (unsigned int i = 0; i < n_args; i++) {
-    GIArgInfo* ai = gi_callable_info_get_arg(callable, i);
-    GITypeInfo* ti = gi_arg_info_get_type_info(ai);
-    if (gi_type_info_get_tag(ti) == GI_TYPE_TAG_ARRAY) {
-      unsigned int L = 0;
-      if (gi_type_info_get_array_length_index(ti, &L) && L < n_args) {
-        skip[L] = true;
-        isLenArg[L] = true;
-      }
-    }
-    gi_base_info_unref(ti);
-    gi_base_info_unref(ai);
-  }
-  {
-    GITypeInfo* rt = gi_callable_info_get_return_type(callable);
-    if (gi_type_info_get_tag(rt) == GI_TYPE_TAG_ARRAY) {
-      unsigned int L = 0;
-      if (gi_type_info_get_array_length_index(rt, &L) && L < n_args) {
-        skip[L] = true;
-        isLenArg[L] = true;
-      }
-    }
-    gi_base_info_unref(rt);
-  }
+  ComputeSkippedArgs(callable, n_args, &skip, &isLenArg);
 
   // Caller-allocates OUT storage (fixed C array or boxed struct): blob != nullptr
   // marks the arg; boxedGType != 0 selects the boxed copy/free path on read-back.
@@ -739,7 +757,8 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
           Napi::Value v = jsCursor < args.Length() ? args.Get(jsCursor) : env.Undefined();
           jsCursor++;
           GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
-          if (JsToGIArgument(env, v, ti, &slots[i], &held[i], tr, &ownedInStrings)) {
+          if (JsToGIArgument(env, v, ti, &slots[i], &held[i], tr, &ownedInStrings, nullptr,
+                             nullptr, nullptr, gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai)))) {
             in_args[inPos[i]].v_pointer = &slots[i];
             out_args[outPos[i]].v_pointer = &slots[i];
           } else {
@@ -835,7 +854,8 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
       } else {
         GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
         ok = JsToGIArgument(env, v, ti, &in_args[inPos[i]], &held[i], tr, &ownedInStrings,
-                            &createdClosures, &createdBytes, &createdValues);
+                            &createdClosures, &createdBytes, &createdValues,
+                            gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai)));
       }
     }
 
@@ -1250,19 +1270,12 @@ Napi::Value HasMethod(const Napi::CallbackInfo& info) {
 // 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();
+// The class-level resolution HasClassMethod and ClassMethodArity share: the
+// literal-then-snake_case walk over own, implemented-interface and inherited
+// methods for an object type, or the interface's own methods for an interface
+// type. Returns a new ref or nullptr.
+static GIFunctionInfo* ResolveClassLevelMethod(GIRepository* repo, const std::string& ns,
+                                               const std::string& tn, const std::string& method) {
   GIBaseInfo* base = gi_repository_find_by_name(repo, ns.c_str(), tn.c_str());
   GIFunctionInfo* func = nullptr;
   if (base != nullptr) {
@@ -1284,6 +1297,23 @@ Napi::Value HasClassMethod(const Napi::CallbackInfo& info) {
     }
     gi_base_info_unref(base);
   }
+  return func;
+}
+
+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();
+  GIFunctionInfo* func = ResolveClassLevelMethod(repo, ns, tn, method);
   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));
@@ -1291,6 +1321,89 @@ Napi::Value HasClassMethod(const Napi::CallbackInfo& info) {
   return Napi::Boolean::New(env, invocable);
 }
 
+// classMethodArity(namespace, typeName, methodName) -> number
+// The JS-visible IN-arg count of the method — what gjs reports as the
+// materialized function's `length` — or -1 when the name does not resolve to an
+// invocable instance method. Resolution is byte-identical to hasClassMethod
+// (shared ResolveClassLevelMethod), so `arity >= 0` IS the hasClassMethod
+// answer and the prototype materializer needs a single native call for both.
+// Arity 0 is a real answer (`Gtk.Widget.show()`), which is why absence is -1.
+Napi::Value ClassMethodArity(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, "classMethodArity(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();
+  GIFunctionInfo* func = ResolveClassLevelMethod(repo, ns, tn, method);
+  g_object_unref(repo);
+  if (func == nullptr) return Napi::Number::New(env, -1);
+  const bool invocable = gi_callable_info_is_method(reinterpret_cast<GICallableInfo*>(func));
+  const int arity = invocable ? JsInArgCount(reinterpret_cast<GICallableInfo*>(func)) : -1;
+  gi_base_info_unref(func);
+  return Napi::Number::New(env, arity);
+}
+
+// Resolve a CLASS-STRUCT method — one of the GObjectClass functions gjs exposes as a
+// STATIC on the constructor (`Gtk.Button.list_properties()`, `.find_property()`).
+// Absent from the object's own GIObjectInfo, which is why CallStaticMethod's three
+// find_method arms missed it and every such call threw "no static method '…' on
+// Ns.Class" — including @gjsify/gtk-host's paramSpecs(), on every element-creation
+// path. `list_properties` is declared on GObject.ObjectClass and NOWHERE else
+// (Gio.SimpleActionClass has no GIR record at all) and class structs carry no GI
+// inheritance, so the walk is over the object-info PARENT chain, each level's class
+// struct in turn — reproducing what gjs reaches through the CONSTRUCTOR PROTOTYPE
+// CHAIN, where gjs_define_static_methods put GObjectClass's methods on
+// GObject.Object's constructor and Gtk.Button inherits them. Returns a new ref or
+// nullptr; same shape as ResolveMethodByName's parent walk above.
+static GIFunctionInfo* ResolveClassStructMethod(GIObjectInfo* objInfo, const char* name) {
+  GIObjectInfo* walk =
+      reinterpret_cast<GIObjectInfo*>(gi_base_info_ref(reinterpret_cast<GIBaseInfo*>(objInfo)));
+  GIFunctionInfo* found = nullptr;
+  while (walk != nullptr) {
+    GIStructInfo* cs = gi_object_info_get_class_struct(walk);
+    if (cs != nullptr) {
+      if (gi_struct_info_is_gtype_struct(cs)) found = gi_struct_info_find_method(cs, name);
+      gi_base_info_unref(reinterpret_cast<GIBaseInfo*>(cs));
+    }
+    if (found != nullptr) break;
+    GIObjectInfo* parent = gi_object_info_get_parent(walk);
+    gi_base_info_unref(reinterpret_cast<GIBaseInfo*>(walk));
+    walk = parent;
+  }
+  if (walk != nullptr) gi_base_info_unref(reinterpret_cast<GIBaseInfo*>(walk));
+  return found;
+}
+
+// The GTypeClass a class-struct method runs ON: the LEAF type's class, never the
+// declarer's — list_properties() on GtkButton's class must return the button's 44
+// pspecs, not GObject's zero. gjs resolves the same way, reading the gtype off the
+// constructor the call went THROUGH (`this`), which is the leaf.
+//
+// gjs's GTypeStructInstanceIn uses g_type_class_peek and states its reason: "we use
+// peek here to simplify reference counting … GType classes are never really freed …
+// we know that the GType class is referenced at least once when the JS constructor
+// is initialized". node-gi's class proxy takes no such ref, so peek alone is nullptr
+// for a type nothing has instantiated yet — hence g_type_class_ref, to REALISE the
+// class (the same reason ConstructGObject refs it before reading its pspecs). That
+// ref is KEPT: it establishes gjs's invariant once per GType (bounded — every later
+// call is served by the peek), while unrefing is the one call that could invalidate
+// the GParamSpecs list_properties just handed out, which the class owns. Since GLib
+// 2.84 g_type_class_unref is a documented no-op, so pairing buys nothing anyway.
+static gpointer ClassStructInstance(GIObjectInfo* objInfo) {
+  GType gtype =
+      gi_registered_type_info_get_g_type(reinterpret_cast<GIRegisteredTypeInfo*>(objInfo));
+  if (gtype == G_TYPE_INVALID) return nullptr;
+  gpointer klass = g_type_class_peek(gtype);
+  return klass != nullptr ? klass : g_type_class_ref(gtype);
+}
+
 // 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
@@ -1317,8 +1430,27 @@ Napi::Value CallStaticMethod(const Napi::CallbackInfo& info) {
     return env.Null();
   }
   GIFunctionInfo* func = nullptr;
+  // Non-null ONLY when the class-struct fallback is what resolved `func`: the
+  // GTypeClass to invoke it on. It doubles as the flag that the "is an instance
+  // method" rejection below must not fire — a class-struct method IS is_method,
+  // its instance is the class rather than an object.
+  gpointer classInstance = nullptr;
   if (GI_IS_OBJECT_INFO(typeInfo)) {
-    func = gi_object_info_find_method(reinterpret_cast<GIObjectInfo*>(typeInfo), method.c_str());
+    GIObjectInfo* objInfo = reinterpret_cast<GIObjectInfo*>(typeInfo);
+    func = gi_object_info_find_method(objInfo, method.c_str());
+    if (func == nullptr) {
+      func = ResolveClassStructMethod(objInfo, method.c_str());
+      if (func != nullptr) {
+        classInstance = ClassStructInstance(objInfo);
+        if (classInstance == nullptr) {
+          // No GType behind the info, so there is no class to call it on. Drop back
+          // to the plain "no static method" error rather than invoking with a null
+          // instance, which would hand the C function a null GObjectClass*.
+          gi_base_info_unref(reinterpret_cast<GIBaseInfo*>(func));
+          func = nullptr;
+        }
+      }
+    }
   } else if (GI_IS_INTERFACE_INFO(typeInfo)) {
     func = gi_interface_info_find_method(reinterpret_cast<GIInterfaceInfo*>(typeInfo), method.c_str());
   } else if (GI_IS_STRUCT_INFO(typeInfo)) {
@@ -1331,7 +1463,8 @@ Napi::Value CallStaticMethod(const Napi::CallbackInfo& info) {
         .ThrowAsJavaScriptException();
     return env.Null();
   }
-  if (gi_callable_info_is_method(reinterpret_cast<GICallableInfo*>(func))) {
+  const bool isMethod = gi_callable_info_is_method(reinterpret_cast<GICallableInfo*>(func));
+  if (isMethod && classInstance == nullptr) {
     gi_base_info_unref(func);
     g_object_unref(repo);
     Napi::TypeError::New(env, ns + "." + tn + "." + method +
@@ -1339,7 +1472,10 @@ Napi::Value CallStaticMethod(const Napi::CallbackInfo& info) {
         .ThrowAsJavaScriptException();
     return env.Null();
   }
-  Napi::Value result = InvokeFunctionInfo(env, func, nullptr, args, ns + "." + tn + "." + method);
+  // A class struct may also declare plain functions (no instance); only the
+  // is_method ones take the class.
+  Napi::Value result = InvokeFunctionInfo(env, func, isMethod ? classInstance : nullptr, args,
+                                          ns + "." + tn + "." + method);
   gi_base_info_unref(func);
   g_object_unref(repo);
   return result;