@gjsify/node-gi 0.64.2 → 0.64.4

package/README.md

@@ -148,6 +148,15 @@ export halves, the legacy `imports.*` modules, cairo, and the measured
 divergences from GJS — is
 [docs/node-gi-gjs-surface.md](../../../docs/node-gi-gjs-surface.md).
 
+One divergence is deliberate rather than measured, and it only exists under the
+`nativescript` export condition: there `registerClass` accepts a parent class
+that is not a GObject class, so an `@nativescript/core` widget can BE a real
+GObject subclass (properties, signals, `bind_property`, `Gio.ListStore`
+identity) while staying the widget its layout demands. Every other host throws
+GJS's invalid-base-class error, unchanged — see
+[§ `registerClass` over a FOREIGN parent class](../../../docs/node-gi-gjs-surface.md)
+and [ADR 0105](../../../docs/adr/0105-real-gobject-backs-the-nativescript-subset-on-android.md).
+
 ## Runtimes (Node / Bun / Deno)
 
 The engine is a **Node-API** addon, so the same binary loads and runs on **Node,

package/gi.js

@@ -11,7 +11,14 @@ import { ensureNative, onNativeLoaded } from './index.js';
 // Timers, `process` and the windowing env record come from the host seam (host.node.js
 // explains why they are the runtime's own, not the globals; host.nativescript.js is the
 // NativeScript Android variant).
-import { setImmediate, setInterval, clearInterval, runtimeProcess, windowingEnvWrites } from '#host';
+import {
+    setImmediate,
+    setInterval,
+    clearInterval,
+    runtimeProcess,
+    windowingEnvWrites,
+    FOREIGN_PARENT_CLASSES,
+} from '#host';
 import { createGioDBus } from './overrides/gio-dbus.js';
 import { createGioSettings } from './overrides/gio-settings.js';
 
@@ -434,7 +441,7 @@ function wrapSignalCallback(cb) {
 // means `this` is the full userProto-carrying wrapper — the SAME cached proxy the user
 // constructed. Emitter at param 0, as in wrapSignalCallback.
 function resolveTemplateCallback(handle, handlerName) {
-    return (...args) => {
+    const dispatcher = (...args) => {
         const proxy = wrapInstance(handle);
         const userProto = proxy[USER_PROTO];
         const desc = userProto !== undefined ? findProtoDescriptor(userProto, handlerName) : undefined;
@@ -445,6 +452,14 @@ function resolveTemplateCallback(handle, handlerName) {
         }
         return desc.value.apply(proxy, args.map(wrapReturn));
     };
+    // The native closure holds this dispatcher WEAKLY (src/signals.cc), and the
+    // dispatcher captures `handle` — so without a handle-keyed retain it would be
+    // garbage the moment create_closure returns, and the widget would be immortal.
+    // GJS's Gtk override reaches the same lifetime with
+    // `Gi.associateClosure(lifetimeObject, _createClosure(…))`. A fresh key per
+    // closure: one handler name can back several `<signal>` elements.
+    native.retainClosure(handle, Symbol(handlerName), dispatcher);
+    return dispatcher;
 }
 onNativeLoaded(() => native.setTemplateCallbackResolver(resolveTemplateCallback));
 
@@ -464,7 +479,12 @@ function runCtorForCObject(handle, gtypeName) {
     try {
         // No props: GtkBuilder already applied the construct properties to the C object;
         // the ctor's `params` arg is conventionally optional for a template child.
-        Reflect.construct(cls, []);
+        const instance = Reflect.construct(cls, []);
+        // A FOREIGN-PARENT class has no makeClass base ctor to consume the latch, and its
+        // attach is lazy — so if the ctor body touched nothing, `adoptHandle` would still
+        // be set here and a later attach would build a SECOND GObject, orphaning the one
+        // C already created. Force the attach while the latch is still live.
+        if (adoptHandle !== undefined && isForeignInstance(instance)) foreignHandle(instance);
     } finally {
         adoptHandle = prev;
     }
@@ -1128,6 +1148,13 @@ function assignTemplateChildren(instance, handle, reg) {
 // outside what either runtime honours.
 const propertySettersByProto = new WeakMap();
 
+// The property setters THIS file generated for a foreign-parent class (route D, see the
+// FOREIGN-PARENT section). They must be invisible to resolvePropertySetter: a generated
+// setter's whole body is `native.setProperty`, and the engine answers every custom-property
+// store by calling runJsPropertySetter — which would resolve the generated setter and store
+// again, forever. Only a setter the CLASS declared is a JS setter worth replaying.
+const generatedForeignSetters = new WeakSet();
+
 function findPropertySetter(userProto, propertyName) {
     let perProto = propertySettersByProto.get(userProto);
     if (perProto === undefined) propertySettersByProto.set(userProto, (perProto = new Map()));
@@ -1144,7 +1171,9 @@ function resolvePropertySetter(userProto, propertyName) {
     const camel = propertyName.replace(/-([a-z])/g, (m) => m[1].toUpperCase());
     for (const spelling of [propertyName, underscored, camel]) {
         const desc = findProtoDescriptor(userProto, spelling);
-        if (desc !== undefined && typeof desc.set === 'function') return desc.set;
+        if (desc !== undefined && typeof desc.set === 'function' && !generatedForeignSetters.has(desc.set)) {
+            return desc.set;
+        }
     }
     return undefined;
 }
@@ -1587,7 +1616,11 @@ function wrapInstance(handle, userProto) {
         // the leaf's OWN methods resolve). Never DOWNGRADE: a more-derived cached proto is
         // kept. The userProto lives on the target (read via the proxy here), so the
         // upgrade is in place — identity (===) and any expando fields are preserved.
-        if (userProto !== undefined && userProto !== cached[USER_PROTO]) {
+        // NEVER re-link a foreign-parent instance (route D): linkInstanceProto does
+        // `Object.setPrototypeOf`, and that object's [[Prototype]] IS its NativeScript
+        // widget chain — replacing it would turn a real Label into something `_addView`
+        // rejects. Its user prototype is already the registered one, fixed at attach.
+        if (userProto !== undefined && userProto !== cached[USER_PROTO] && !isForeignInstance(cached)) {
             const current = cached[USER_PROTO];
             if (current === undefined || isProtoSameOrDescendantOf(userProto, current)) {
                 linkInstanceProto(cached, userProto);
@@ -2612,7 +2645,11 @@ function findParentGType(klass) {
     for (let c = Object.getPrototypeOf(klass); typeof c === 'function'; c = Object.getPrototypeOf(c)) {
         const reg = registeredClasses.get(c);
         if (reg !== undefined) {
-            return { parentGTypeHandle: reg.typeHandle };
+            // `parentForeign` carries the FOREIGN-PARENT marker down the chain: a subclass
+            // of `registerClass(…, class extends Label {})` has a perfectly ordinary
+            // registered parent by this test, yet ITS instances are still NativeScript
+            // objects that need the attach path rather than the wrapper Proxy.
+            return { parentGTypeHandle: reg.typeHandle, parentForeign: reg.foreign === true };
         }
         const gt = c.$gtypeName;
         if (typeof gt === 'string') {
@@ -2620,9 +2657,19 @@ function findParentGType(klass) {
             if (dot > 0) {
                 return { parentNamespace: gt.slice(0, dot), parentType: gt.slice(dot + 1) };
             }
-            // A dotless `$gtypeName` with no registeredClasses entry should never occur
-            // (only registered types are dotless, and they are in the registry); be
-            // explicit rather than mis-resolving the namespace split.
+            // A dotless `$gtypeName` and no registry entry, with the name INHERITED: `c` is
+            // an ordinary unregistered subclass of a registered ancestor further up, reading
+            // that ancestor's static through the class-side prototype chain. Keep walking —
+            // `c` contributes no GType, and the registered ancestor above it is the parent.
+            // gjs answers the same way (measured, 1.88.1): `registerClass(C extends B)` where
+            // `class B extends RegisteredA {}` gives `type_parent(C) === A`. Without this the
+            // walk threw on its own inherited value, which is every port class that puts a
+            // plain subclass between two registrations — `AdwSwitchRow` between the two
+            // route-D mixins (ADR 0105 § 2) is the case that found it.
+            if (!Object.prototype.hasOwnProperty.call(c, '$gtypeName')) continue;
+            // An OWN dotless `$gtypeName` with no registry entry should never occur (only
+            // registered types are dotless, and they are in the registry); be explicit
+            // rather than mis-resolving the namespace split.
             throw new TypeError("GObject.registerClass: parent '" + gt + "' has no resolvable GType");
         }
     }
@@ -2787,6 +2834,335 @@ function collectVfuncs(klass) {
  * @param {Function} [maybeClass]
  * @returns {Function} the same `klass` (now registered)
  */
+// ---- FOREIGN-PARENT classes: a registered GObject attached to a host widget ----
+//
+// THE ONE DELIBERATE DIVERGENCE FROM GJS, and it only exists where GJS cannot run.
+// Gated on `FOREIGN_PARENT_CLASSES` (#host): true on NativeScript, false everywhere
+// else, where registerClass keeps throwing GJS's invalid-base error verbatim. See
+// host.nativescript.js for why that gate is sound, ADR 0105 § 2 for the decision and
+// docs/node-gi-gjs-surface.md for the surface this adds.
+//
+// What it buys: `registerClass({GTypeName, Properties, Signals}, class MyLabel extends
+// Label {})` where `Label` is a `@nativescript/core` widget. The JS object stays a REAL
+// Label — its [[Prototype]] is the untouched NativeScript chain — so `stack.addChild(w)`,
+// `ContentView.content = w` and `_addChildFromBuilder` pass their hard `instanceof
+// ViewBase` gates with no `.view` unwrap anywhere in consumer code. Beside it sits a real
+// GObject of a registered GType whose GType PARENT is GObject.Object (the GType parent is
+// independent of the JS prototype chain), so the object also answers `instanceof
+// GObject.Object`, carries custom properties with `notify::`, and emits registered signals.
+//
+// ATTACH, never wrap. Everywhere else node-gi hands back a Proxy whose get/set traps
+// resolve the GObject surface dynamically; here there is no Proxy to put traps on, so:
+//   • `[HANDLE]`/`[USER_PROTO]` become non-enumerable OWN props of the widget object
+//     (`Symbol.hasInstance` resolves `instanceof` through `instance[HANDLE]`, which is
+//     what makes the widget a GObject.Object);
+//   • everything the traps would have answered — connect/emit/notify, the property
+//     accessors, the GObject.Object methods — is installed as OWN members of
+//     `klass.prototype`, once, at registerClass time;
+//   • `Object.setPrototypeOf` is never called on such an object (see linkInstanceProto).
+//
+// LAZY. The GObject is constructed on the first access that needs it (`foreignHandle`),
+// because nothing in a NativeScript widget's construction runs node-gi code: there is no
+// base ctor to route `new` through the way makeClass does. Every entry point goes through
+// `foreignHandle`, including `unwrapArg` reading `[HANDLE]` through the prototype getter,
+// so by the time anything can OBSERVE the GObject it exists — `new MyLabel() instanceof
+// GObject.Object` attaches and answers true. Construct properties are the one thing this
+// cannot carry (the widget ctor owns its own arguments); set them after construction.
+//
+// NOT supported, deliberately: `vfunc_*` overrides. collectVfuncs finds none on a widget
+// chain, and a vfunc trampoline would need to re-link the instance prototype — the one
+// thing this path must never do.
+const FOREIGN_MATERIALISED = Symbol('nodeGiForeignMaterialised');
+
+// A registered foreign-parent class's PROTOTYPE → its registration. The instance carries
+// no class pointer we can trust (its `constructor` is the widget's), so the attach walks
+// the real prototype chain and takes the nearest entry — which is the LEAF's, since a
+// subclass's own prototype comes first.
+const foreignRegByProto = new WeakMap();
+
+// Gated first, so on a host where foreign parents cannot exist this is one boolean read
+// rather than a prototype-chain walk — it sits on wrapInstance's upgrade path.
+function isForeignInstance(obj) {
+    return FOREIGN_PARENT_CLASSES && foreignRegFor(obj) !== undefined;
+}
+
+function foreignRegFor(obj) {
+    for (let p = Object.getPrototypeOf(obj); p !== null; p = Object.getPrototypeOf(p)) {
+        const reg = foreignRegByProto.get(p);
+        if (reg !== undefined) return reg;
+    }
+    return undefined;
+}
+
+// Construct this object's GObject and bind the two together. Not a wrap: the object is
+// handed back unchanged apart from three non-enumerable own symbols.
+function attachForeignGObject(obj, reg) {
+    let handle;
+    if (adoptHandle !== undefined) {
+        // A C-created instance (runCtorForCObject) — the engine already built the GObject.
+        // Consume the latch atomically, exactly as the makeClass base ctor does.
+        handle = adoptHandle;
+        adoptHandle = undefined;
+    } else {
+        handle = native.constructType(reg.typeHandle, {});
+    }
+    // HANDLE first: it shadows the prototype getter, so anything the flush below runs can
+    // re-enter `foreignHandle` without constructing a second GObject.
+    Object.defineProperty(obj, HANDLE, { value: handle, configurable: true });
+    Object.defineProperty(obj, USER_PROTO, { value: reg.foreignProto, configurable: true });
+    instanceCache.set(handle, obj);
+    flushPropertiesToJsSetters(obj, handle, reg);
+    return handle;
+}
+
+// This object's GObject handle, attaching on first demand. Every member installed below
+// goes through here, as does `unwrapArg` (via the prototype [HANDLE] getter).
+function foreignHandle(obj) {
+    if (Object.hasOwn(obj, HANDLE)) return obj[HANDLE];
+    const reg = foreignRegFor(obj);
+    if (reg === undefined) {
+        throw new TypeError('node-gi: this object is not an instance of a GObject.registerClass()-registered class');
+    }
+    return attachForeignGObject(obj, reg);
+}
+
+// Which custom properties of this instance hold a materialised value — the state GJS's
+// generated accessors keep in their private field, and what the equal-value guard
+// compares against. Same rule as the wrapper's `materialise` (see wrapInstance): seeded
+// from what the engine has stored, then extended by every read and write.
+function foreignMaterialise(obj, name) {
+    let seen = obj[FOREIGN_MATERIALISED];
+    if (seen === undefined) {
+        seen = new Set(typeof native.storedPropertyNames === 'function' ? native.storedPropertyNames(obj[HANDLE]) : []);
+        Object.defineProperty(obj, FOREIGN_MATERIALISED, { value: seen, configurable: true });
+    }
+    const had = seen.has(name);
+    seen.add(name);
+    return had;
+}
+
+// The GObject.Object instance methods installed as callMethod thunks. A MODEST list on
+// purpose — only introspectable, GJS-reachable members with no gpointer/GValue-array
+// argument (`g_object_get_data`, `getv` and friends are deliberately absent rather than
+// present and throwing). The wrapper Proxy answers these from introspection dynamically;
+// this path has to name them.
+const FOREIGN_OBJECT_METHODS = [
+    'get_property',
+    'set_property',
+    'bind_property',
+    'notify_by_pspec',
+    'freeze_notify',
+    'thaw_notify',
+    'run_dispose',
+    'ref',
+    'unref',
+    'ref_sink',
+    'force_floating',
+    'is_floating',
+];
+
+function snakeToCamel(name) {
+    return name.replace(/_([a-z])/g, (m) => m[1].toUpperCase());
+}
+
+/** The distinct spellings a member is installed under: one entry for an underscore-free name. */
+function memberSpellings(name) {
+    const camel = snakeToCamel(name);
+    return camel === name ? [name] : [name, camel];
+}
+
+// Install a member under `name` unless the host chain already answers under it — a
+// widget's own method ALWAYS wins, because consumer code and NativeScript's own
+// internals call it. Returns false (and the caller records the skip) when it loses.
+function defineForeignMember(proto, name, descriptor, skipped) {
+    if (findProtoDescriptor(proto, name) !== undefined) {
+        skipped.push(name);
+        return false;
+    }
+    Object.defineProperty(proto, name, { configurable: true, enumerable: false, ...descriptor });
+    return true;
+}
+
+// Everything the instance wrapper's traps would have resolved, as own members of a
+// foreign-parent class's prototype. Returns the names the host chain already owned, so a
+// program (and the route-D spec) can see exactly what it did NOT get.
+function installForeignGObjectSurface(proto, properties) {
+    const skipped = [];
+
+    // `[HANDLE]` as a lazily-attaching GETTER is the whole load-bearing trick: it makes
+    // `instanceof GObject.Object`, `unwrapArg` and every member below attach on demand,
+    // with no construction hook on the widget side. An attach replaces it with an own
+    // data property, so this getter runs at most once per instance.
+    Object.defineProperty(proto, HANDLE, {
+        configurable: true,
+        get() {
+            return foreignHandle(this);
+        },
+    });
+
+    defineForeignMember(
+        proto,
+        '$typeName',
+        {
+            get() {
+                return native.getTypeName(foreignHandle(this));
+            },
+        },
+        skipped,
+    );
+
+    // Signal API. The same four thunks the wrapper builds, including the (fn → ids)
+    // bookkeeping signal_handlers_*_by_func resolves through.
+    defineForeignMember(
+        proto,
+        'connect',
+        {
+            value: function connect(signal, cb) {
+                const handle = foreignHandle(this);
+                const id = native.connectSignal(handle, signal, wrapSignalCallback(cb), false);
+                recordSignalHandler(handle, cb, id);
+                return id;
+            },
+        },
+        skipped,
+    );
+    const connectAfter = function connect_after(signal, cb) {
+        const handle = foreignHandle(this);
+        const id = native.connectSignal(handle, signal, wrapSignalCallback(cb), true);
+        recordSignalHandler(handle, cb, id);
+        return id;
+    };
+    defineForeignMember(proto, 'connect_after', { value: connectAfter }, skipped);
+    defineForeignMember(proto, 'connectAfter', { value: connectAfter }, skipped);
+    defineForeignMember(
+        proto,
+        'disconnect',
+        {
+            value: function disconnect(id) {
+                const handle = foreignHandle(this);
+                forgetSignalHandlerId(handle, id);
+                return native.disconnectSignal(handle, id);
+            },
+        },
+        skipped,
+    );
+    defineForeignMember(
+        proto,
+        'emit',
+        {
+            value: function emit(signal, ...args) {
+                return wrapReturn(native.emitSignal(foreignHandle(this), signal, unwrapArgs(args)));
+            },
+        },
+        skipped,
+    );
+
+    // `notify` is the ONE name that cannot be skipped and cannot be taken: NativeScript's
+    // Observable.prototype.notify({eventName, object}) is called by the widget machinery
+    // itself (and by consumer code), while GObject's notify(propertyName) is what a
+    // custom property's setter needs. They are told apart by ARGUMENT TYPE — a string is
+    // a GObject property name, anything else is a NativeScript event payload — and the
+    // inherited implementation is captured HERE, before this definition shadows it, so
+    // both keep working on one object. This is the only collision in the
+    // @nativescript/core 9.1 Label chain (measured: Observable.prototype.notify is the
+    // sole hit for the whole installed surface).
+    const inheritedNotify = findProtoDescriptor(proto, 'notify');
+    const hostNotify = inheritedNotify !== undefined ? inheritedNotify.value : undefined;
+    Object.defineProperty(proto, 'notify', {
+        configurable: true,
+        enumerable: false,
+        value: function notify(arg, ...rest) {
+            if (typeof arg === 'string') {
+                return wrapReturn(native.callMethod(foreignHandle(this), 'notify', [arg]));
+            }
+            if (typeof hostNotify === 'function') return hostNotify.call(this, arg, ...rest);
+            throw new TypeError('notify(): expected a GObject property name');
+        },
+    });
+
+    for (const name of FOREIGN_OBJECT_METHODS) {
+        const thunk = function giMethod(...args) {
+            return wrapReturn(native.callMethod(foreignHandle(this), name, unwrapArgs(args)));
+        };
+        // `memberSpellings(name)` and not `[name, snakeToCamel(name)]`: a name with no
+        // underscore camel-cases to ITSELF (`ref`, `unref`), so the second call would
+        // find the descriptor the first one just installed and record a skip against
+        // the host for a member the host never had. `$foreignSkipped` is read as "what
+        // did the widget already own", so a self-skip there is a false statement.
+        for (const spelling of memberSpellings(name)) {
+            defineForeignMember(proto, spelling, { value: thunk }, skipped);
+        }
+    }
+
+    // gjs's GObject.Object.prototype shims over namespace-level g_signal_* /
+    // bind_property_full — not introspected instance methods, so named explicitly here
+    // just as the wrapper's get trap routes them explicitly.
+    for (const name of [
+        'block_signal_handler',
+        'unblock_signal_handler',
+        'stop_emission_by_name',
+        'bind_property_full',
+    ]) {
+        for (const spelling of memberSpellings(name)) {
+            const shim = objectPrototypeShim(spelling);
+            defineForeignMember(
+                proto,
+                spelling,
+                {
+                    value: function shimmed(...args) {
+                        return shim(foreignHandle(this), args);
+                    },
+                },
+                skipped,
+            );
+        }
+    }
+
+    installForeignPropertyAccessors(proto, properties, skipped);
+    return skipped;
+}
+
+// GJS-style generated accessors for the DECLARED custom properties, under all three
+// spellings GJS makes equivalent (dash, underscore, camel — `_checkAccessors` mirrors the
+// declared one onto the other two). Elsewhere node-gi installs none and resolves the
+// spellings at the point of use instead (findPropertySetter), because the wrapper Proxy
+// can; this path has no Proxy, so the accessors have to exist. A ROUTE-D-ONLY divergence
+// from the rest of node-gi, and the reason the equal-value guard is replicated here.
+//
+// A spelling the host chain already answers is left ALONE: NativeScript defines `text`,
+// `width`, … on its own prototypes with real setters driving the native view, and
+// shadowing one would break the widget. The engine's store still routes to it —
+// runJsPropertySetter resolves the class-or-chain setter — so declaring a GObject
+// property named after a widget property composes instead of colliding.
+function installForeignPropertyAccessors(proto, properties, skipped) {
+    for (const spec of properties) {
+        const name = spec.name;
+        if (typeof name !== 'string' || name.length === 0) continue;
+        const spellings = new Set([
+            name,
+            name.replace(/-/g, '_'),
+            name.replace(/-([a-z])/g, (m) => m[1].toUpperCase()),
+        ]);
+        const get = function () {
+            const handle = foreignHandle(this);
+            foreignMaterialise(this, name);
+            return wrapReturn(native.getProperty(handle, name));
+        };
+        const set = function (value) {
+            const handle = foreignHandle(this);
+            // Equal-value guard, GJS's _generateAccessors setter verbatim — see the same
+            // guard in wrapInstance's set trap for why it is only armed once the value
+            // has been materialised.
+            if (foreignMaterialise(this, name) && wrapReturn(native.getProperty(handle, name)) === value) return;
+            native.setProperty(handle, name, unwrapArg(value));
+        };
+        generatedForeignSetters.add(set);
+        for (const spelling of spellings) {
+            defineForeignMember(proto, spelling, { get, set }, skipped);
+        }
+    }
+}
+
 // GJS's meta FIELD form: a class may declare its meta as static symbol fields
 // (`Klass[GObject.GTypeName] = 'X'`) instead of passing a meta object, and GJS treats
 // the symbols as the real source — `registerClass(meta, klass)` only copies meta onto
@@ -2826,13 +3202,19 @@ function registerClass(metaOrClass, maybeClass) {
     meta = { ...fieldMeta, ...meta };
 
     const parent = findParentGType(klass);
-    if (parent === undefined) {
+    // A parent that is not a node-gi GObject class at all. GJS throws here
+    // ("registerClass() used with invalid base class", refs/gjs GObject.js) and so does
+    // every host but NativeScript — where the FOREIGN-PARENT path instead registers the
+    // GType under GObject.Object and ATTACHES it to the host widget object. See the
+    // FOREIGN-PARENT section above.
+    if (parent === undefined && !FOREIGN_PARENT_CLASSES) {
         throw new TypeError(
             'GObject.registerClass: ' +
                 (klass.name || 'the class') +
                 ' must extend a node-gi GObject class (e.g. GObject.Object)',
         );
     }
+    const foreign = parent === undefined || parent.parentForeign === true;
 
     const properties = [];
     if (meta.Properties !== null && typeof meta.Properties === 'object') {
@@ -2874,10 +3256,16 @@ function registerClass(metaOrClass, maybeClass) {
     // from its runtime GType handle (it has no introspection entry); an INTROSPECTED
     // parent is resolved by namespace+type. Construction (the leaf's registered GType
     // via the makeClass new.target routing) is already multi-level-correct either way.
+    // A FOREIGN parent contributes no GType at all (it is a host widget class), so the
+    // registered type is rooted at GObject.Object — the GType parent is independent of
+    // the JS prototype chain, which is exactly what makes route D possible. A foreign
+    // SUBCLASS still has a registered parent and takes the ordinary by-GType branch.
     const typeHandle =
-        parent.parentGTypeHandle !== undefined
-            ? native.registerClassFromGType(gtypeName, parent.parentGTypeHandle, options)
-            : native.registerClass(gtypeName, parent.parentNamespace, parent.parentType, options);
+        parent === undefined
+            ? native.registerClass(gtypeName, 'GObject', 'Object', options)
+            : parent.parentGTypeHandle !== undefined
+              ? native.registerClassFromGType(gtypeName, parent.parentGTypeHandle, options)
+              : native.registerClass(gtypeName, parent.parentNamespace, parent.parentType, options);
 
     // G3: register the GType for the GIVEN class IN PLACE (no throwaway Subclass) and
     // return that same class. `$gtypeName`/`$gtype` are defined as OWN properties:
@@ -2917,6 +3305,8 @@ function registerClass(metaOrClass, maybeClass) {
         children: children.length > 0 ? children : undefined,
         internalChildren: internalChildren.length > 0 ? internalChildren : undefined,
         constructPropertyNames: constructPropertyNames.length > 0 ? constructPropertyNames : undefined,
+        foreign: foreign ? true : undefined,
+        foreignProto: foreign ? klass.prototype : undefined,
     });
     // Which properties the equal-value guard owns: the ones DECLARED here, union the
     // registered parent's (a G2 subclass inherits its parent's custom properties and
@@ -2933,6 +3323,36 @@ function registerClass(metaOrClass, maybeClass) {
     // Reverse index for runCtorForCObject: the engine identifies a C-created instance
     // by its GType name (= gtypeName, what native.registerClass registered).
     classesByGType.set(gtypeName, klass);
+    // FOREIGN parent: install the GObject surface as own members of this prototype and
+    // index the prototype, so an instance can find ITS leaf registration by walking the
+    // real (host-widget) prototype chain. Both before type_class_ref, like every record
+    // above it. `foreignSkipped` names the members the host chain already owned — the
+    // honest answer to "what did this class NOT get", which the route-D spec reports.
+    if (foreign) {
+        const reg = registeredClasses.get(klass);
+        reg.foreignSkipped = installForeignGObjectSurface(klass.prototype, properties);
+        foreignRegByProto.set(klass.prototype, reg);
+    }
+    // `$foreignSkipped`, readable from outside, because "which GObject spelling did the
+    // host widget already own?" is the one question this route cannot answer in the
+    // abstract: it depends on the parent class, so it has to be reported per
+    // registration rather than documented once.
+    //
+    // On EVERY registration of this host, not only the foreign ones, and an empty array
+    // where nothing was skipped. A class's static side is a Proxy that answers any
+    // unknown name with a static-method thunk, so `X.$foreignSkipped` is already
+    // truthy — a FUNCTION — wherever the property is absent, and `if
+    // (X.$foreignSkipped.length)` would then throw rather than read "nothing". Defining
+    // it is what makes the read mean what it says. Gated on the host flag all the same,
+    // so the default host's registerClass keeps exactly GJS's static surface.
+    if (FOREIGN_PARENT_CLASSES) {
+        Object.defineProperty(klass, '$foreignSkipped', {
+            value: Object.freeze([...(registeredClasses.get(klass).foreignSkipped ?? [])]),
+            configurable: true,
+            enumerable: false,
+            writable: false,
+        });
+    }
     // GJS parity: registration must be COMPLETE when registerClass returns. The
     // engine installs the custom properties, signals and vfunc trampolines in
     // class_init (src/class.cc), which GObject runs lazily on the first
@@ -3025,6 +3445,12 @@ function signalEmitByName(object, ...nameAndArgs) {
 // makeClass). Merged enums are cached so identity is stable.
 const OVERLAY_NAMES = new Set([
     'registerClass',
+    // Whether THIS host registers a class over a non-GObject parent (the FOREIGN-PARENT
+    // section above) or throws on one. A caller that wants route D has no other way to
+    // ask: the only alternative is to register and catch, which registers a GType as a
+    // side effect of a question and turns "this host cannot" into the same outcome as
+    // "this registration was wrong". Read by @gjsify/adwaita-gobject-native's engine.
+    '$foreignParentClasses',
     'GTypeName',
     'properties',
     'signals',
@@ -3094,6 +3520,7 @@ function decorateGObjectNamespace(baseNs) {
         if (cache.has(prop)) return cache.get(prop);
         let value;
         if (prop === 'registerClass') value = registerClass;
+        else if (prop === '$foreignParentClasses') value = FOREIGN_PARENT_CLASSES;
         else if (prop === 'GTypeName') value = GTypeNameSymbol;
         else if (prop === 'properties') value = propertiesSymbol;
         else if (prop === 'signals') value = signalsSymbol;

package/host.nativescript.js

@@ -50,6 +50,19 @@ export const RUNTIME = 'nativescript';
  */
 export const LAZY_NATIVE = true;
 
+/**
+ * Whether `GObject.registerClass` may register a class whose JS parent is NOT a node-gi
+ * GObject class — `class MyLabel extends Label {}`, where `Label` is a
+ * `@nativescript/core` widget. GJS rejects that outright and so does node-gi on every
+ * other host; this is the ONE deliberate divergence, and it is deliberate because on
+ * NativeScript there is no GJS to be compatible with: node-gi is the only GI runtime that
+ * ever executes here, so a program written against this cannot be a program that behaves
+ * differently under GJS. See the FOREIGN-PARENT section in gi.js, ADR 0105 § 2 and
+ * docs/node-gi-gjs-surface.md.
+ * @type {boolean}
+ */
+export const FOREIGN_PARENT_CLASSES = true;
+
 // Timers from the global scope: NativeScript has no node:timers, and there is no
 // GLib-backed replacement to avoid here. setImmediate is not a V8 builtin.
 export const setImmediate =

package/host.node.js

@@ -61,6 +61,16 @@ export const RUNTIME =
  */
 export const LAZY_NATIVE = false;
 
+/**
+ * Whether `GObject.registerClass` may register a class whose JS parent is NOT a node-gi
+ * GObject class. FALSE here, and that is the point: on Node/Bun/Deno/GJS a program can be
+ * run under real GJS, so registerClass must keep throwing GJS's invalid-base error
+ * (refs/gjs/modules/core/overrides/GObject.js) rather than quietly accept a class GJS
+ * would reject. Only host.nativescript.js enables it — see the note there.
+ * @type {boolean}
+ */
+export const FOREIGN_PARENT_CLASSES = false;
+
 // GJS host mode: `GjsifyNapi.init()` installs the loader as
 // `globalThis.__gjsifyNapiLoadAddon` and re-installs it if another consumer (the
 // @gjsify/napi L1) already captured + deleted it. Needs the GjsifyNapi typelib

package/index.d.ts

@@ -542,6 +542,18 @@ export function emitSignal(handle: GObjectHandle, signalName: string, args?: unk
 /** Disconnect a previously connected signal handler. */
 export function disconnectSignal(handle: GObjectHandle, handlerId: number): void;
 
+/**
+ * INTERNAL. Keep a callback alive for as long as `handle` is alive. Signal and
+ * template-callback GClosures hold their JS callback through a WEAK napi_ref, so
+ * a connected handler is not a GC root (which is what makes a handler capturing
+ * its own emitter collectable, as in GJS); this handle-keyed WeakMap is the
+ * ephemeron that keeps it callable meanwhile. `connectSignal` does it for you.
+ */
+export function retainClosure(handle: GObjectHandle, key: number | symbol, fn: Function): void;
+
+/** INTERNAL. Drop a closure retained by {@link retainClosure}. */
+export function releaseClosure(handle: GObjectHandle, key: number | symbol): void;
+
 /**
  * Register the L1 resolver mapping a Gtk.Template `<signal handler="…">` handler
  * name to the instance's bound JS method (engine template-callback scope).

package/index.js

@@ -94,9 +94,16 @@ export function ensureNative() {
     makePumpPendingCount = addon.makePumpPendingCount;
     pumpKick = addon.pumpKick;
     setMicrotaskDrain = addon.setMicrotaskDrain;
-    connectSignal = addon.connectSignal;
     emitSignal = addon.emitSignal;
-    disconnectSignal = addon.disconnectSignal;
+    connectSignal = (handle, signalName, callback, after) => {
+        const id = addon.connectSignal(handle, signalName, callback, after);
+        retainClosure(handle, id, callback);
+        return id;
+    };
+    disconnectSignal = (handle, handlerId) => {
+        releaseClosure(handle, handlerId);
+        return addon.disconnectSignal(handle, handlerId);
+    };
     setTemplateCallbackResolver = addon.setTemplateCallbackResolver;
     setConstructCallback = addon.setConstructCallback;
     setPropertySetCallback = addon.setPropertySetCallback;
@@ -205,6 +212,52 @@ export let mainContextHasPending;
 export let makePumpPendingCount;
 export let pumpKick;
 export let setMicrotaskDrain;
+// ---- signal-closure keep-alive (GJS's associate_closure, built in JS) ----
+//
+// A signal / template-callback GClosure holds its JS callback through a WEAK
+// napi_ref (src/signals.cc), so a C-held closure is NOT a GC root. That is what
+// makes `obj.connect('x', () => obj.y)` collectable instead of immortal, and it
+// is GJS's design: its signal closures keep the callable unrooted and TRACE it
+// from the owning wrapper (ObjectInstance::m_closures).
+//
+// node-gi has no tracing hook into V8, so the same edge is expressed as the one
+// ephemeron a non-extensible External can take part in: a WeakMap keyed by the
+// canonical handle. Handle reachable (JS holds the wrapper, or C owns the object
+// and the toggle ref roots the handle) → callback reachable → a connected handler
+// still fires. Handle reachable ONLY through the callback it retains → key and
+// value die together, which is exactly the cycle that used to leak.
+//
+// Pruned on disconnect. A handler disconnected by a route that bypasses
+// `disconnectSignal` (the introspected GObject.signal_handler_disconnect) leaves
+// its entry behind until the handle itself goes — harmless, the closure is
+// already gone, and the same divergence the gi.js handler-id registry documents.
+const retainedClosures = new WeakMap();
+
+/**
+ * Keep `fn` alive for as long as `handle` is alive. INTERNAL — the JS half of the
+ * weak closure refs in src/signals.cc.
+ * @param {object} handle canonical GObject handle (the WeakMap key / lifetime)
+ * @param {number | symbol} key handler id, or a unique key for a non-signal closure
+ * @param {Function} fn the callback the native closure holds weakly
+ */
+export function retainClosure(handle, key, fn) {
+    let byKey = retainedClosures.get(handle);
+    if (byKey === undefined) {
+        byKey = new Map();
+        retainedClosures.set(handle, byKey);
+    }
+    byKey.set(key, fn);
+}
+
+/**
+ * Drop a retained closure (on disconnect). INTERNAL — see retainClosure.
+ * @param {object} handle canonical GObject handle
+ * @param {number | symbol} key the key it was retained under
+ */
+export function releaseClosure(handle, key) {
+    retainedClosures.get(handle)?.delete(key);
+}
+
 export let connectSignal;
 export let emitSignal;
 export let disconnectSignal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.64.2",
+  "version": "0.64.4",
   "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/signals.cc

@@ -7,22 +7,36 @@ namespace nodegi {
 
 // ---- signals (milestone 1) ----
 //
-// A GClosure that wraps a JS callback. The callback is held by a strong
-// napi_ref; the closure's finalize notifier drops it. The generic marshal
-// converts the signal's GValue params to JS — the EMITTER instance (param 0)
-// first, then the signal's own params (1..n), matching GJS — and the JS return
-// into the signal return GValue.
+// A GClosure that wraps a JS callback. The closure's finalize notifier drops the
+// napi_ref. The generic marshal converts the signal's GValue params to JS — the
+// EMITTER instance (param 0) first, then the signal's own params (1..n), matching
+// GJS — and the JS return into the signal return GValue.
 //
-// Narrowed-leak semantics (with the toggle-ref bridge): a handler that does NOT
-// close over its own object is now collectable once C is the sole owner
-// (toggle-down → weak → GC). A handler that DOES close over its object forms a
-// GObject -> GClosure -> napi_ref -> callback -> wrapper -> handle cycle the GC
-// cannot break across C, so it keeps the object alive until disconnect — which is
-// the GJS-faithful contract (a connected self-referential handler is a reason to
-// stay alive). disconnect drops the closure's napi_ref (JsClosureFinalize),
-// breaking the cycle so the next GC collects the object. The callback ref stays
-// STRONG while connected (a connected handler must fire). Verified by the
-// signal-cycle case in test/gc-identity.test.mjs.
+// REF STRENGTH IS THE WHOLE CONTRACT, and it differs per closure KIND, exactly as
+// in GJS (refs/gjs/gi/closure.h: `create_marshaled` roots, `create_for_signal`
+// does not):
+//
+//   * GENERIC closure (a JS function marshalled as a GClosure IN-arg, invoked by
+//     arbitrary C) — STRONG. Nothing on the JS side owns it; the ref IS the owner.
+//   * SIGNAL closure (`.connect()`) and TEMPLATE-CALLBACK closure — WEAK. A
+//     handler that captures its own emitter otherwise forms a
+//     GObject → GClosure → napi_ref → callback → wrapper → toggle ref → GObject
+//     cycle that spans C, and no GC can break it: `obj.connect('x', () => obj.y)`
+//     made `obj` immortal. GJS has the identical cycle on paper and collects it,
+//     because its signal closures keep the callable UNROOTED and trace it from
+//     the owning wrapper (ObjectInstance::m_closures / trace_impl), which puts
+//     the whole cycle inside one heap the GC can reason about.
+//
+// node-gi has no tracing hook, so the equivalent edge is built in JS: index.js
+// retains the callback in a WeakMap keyed by the canonical handle — the only
+// ephemeron V8 offers over a non-extensible External, and the same shape
+// `associate_closure` has. The handle is reachable exactly when GJS would trace
+// the closure (JS holds the wrapper, or C owns the object and toggle.cc roots
+// it), so a connected handler still fires for as long as anything can emit to it,
+// and the self-referential cycle collects. A collected callback leaves the weak
+// ref empty and the marshal returns early (it already tolerates a null value).
+// Measured against gjs 1.88.1 with a FinalizationRegistry witness; verified by the
+// signal-cycle cases in test/gc-identity.test.mjs.
 
 struct JsClosureData {
   napi_env env;
@@ -191,8 +205,11 @@ static void JsGenericClosureMarshal(GClosure* closure, GValue* return_value, gui
 
 // JS function → a floating marshaled GClosure (the engine's twin of GJS's
 // Gjs::Closure::create_marshaled for "boxed" closure args — refs/gjs/gi/
-// arg-cache.cpp GClosureInTransferNone::in). The closure holds a strong ref to
-// the function; JsClosureFinalize drops it when the closure is invalidated /
+// arg-cache.cpp GClosureInTransferNone::in). The closure holds a STRONG ref to
+// the function — deliberately, and unlike the signal/template closures above:
+// `create_marshaled` defaults `root = true` (refs/gjs/gi/closure.h), because no
+// JS-side owner exists for a closure handed to arbitrary C. JsClosureFinalize
+// drops it when the closure is invalidated /
 // finalized (the callee released its last ref, or the invoke-site released the
 // only ref because the callee never kept one). Ref/sink + release policy lives at
 // the marshalling site (marshal.cc / calls.cc CreatedClosures).
@@ -231,9 +248,11 @@ Napi::Value ConnectSignal(const Napi::CallbackInfo& info) {
     return env.Null();
   }
 
+  // WEAK (refcount 0) — the keep-alive is the JS-side handle→callback edge
+  // index.js installs; see the ref-strength contract at the top of this file.
   JsClosureData* jc = g_new0(JsClosureData, 1);
   jc->env = env;
-  napi_create_reference(env, info[2], 1, &jc->callback);
+  napi_create_reference(env, info[2], 0, &jc->callback);
 
   GClosure* closure = g_closure_new_simple(sizeof(GClosure), jc);
   g_closure_set_marshal(closure, JsClosureMarshal);
@@ -468,13 +487,17 @@ static GClosure* NodeGiScopeCreateClosure(void* selfScope, void* builder,
   }
 
   // Wrap the resolved (instance-bound, arg-wrapping) JS function in a JsClosure —
-  // the same closure type a `.connect()` produces. The closure owns a strong ref to
-  // the function; g_object_watch_closure ties its lifetime to the widget (the
-  // handler `this`) and invalidates it when the widget is finalized, exactly like
+  // the same closure type a `.connect()` produces, and WEAK for the same reason:
+  // the resolver's dispatcher captures the widget handle, so a strong ref made
+  // every templated widget immortal. gi.js's resolveTemplateCallback retains the
+  // dispatcher on the widget handle before returning it, which is what GJS's Gtk
+  // override does with `Gi.associateClosure(lifetimeObject, …)`
+  // (refs/gjs/modules/core/overrides/Gtk.js). g_object_watch_closure additionally
+  // ties the closure to the widget and invalidates it on finalize, exactly like
   // GtkBuilderCScope's own create_closure.
   JsClosureData* jc = g_new0(JsClosureData, 1);
   jc->env = rawEnv;
-  napi_create_reference(rawEnv, resolved, 1, &jc->callback);
+  napi_create_reference(rawEnv, resolved, 0, &jc->callback);
   GClosure* closure = g_closure_new_simple(sizeof(GClosure), jc);
   g_closure_set_marshal(closure, JsClosureMarshal);
   g_closure_add_finalize_notifier(closure, jc, JsClosureFinalize);