@gjsify/node-gi 0.64.1 → 0.64.4

package/gi.js

@@ -7,10 +7,18 @@
 // Reference: gjs/modules/esm/gi.js for the require shape; node-gtk (romgrk, MIT) for the
 // binding lineage. Hand-authored JS — the package ships no build step.
 import * as native from './index.js';
+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';
 
@@ -360,17 +368,19 @@ function makeErrorDomainClass(namespace, typeName, members, quark) {
 // Called by the engine on a failed GI invoke, with ownership of the GError* already
 // transferred to the boxed handle. Named, so the position properties report the
 // application frame rather than this one.
-native.setErrorBuilder(function buildThrownGError(handle, quark, code, message) {
-    // Same cross-version pairing: an addon older than this JS calls the builder with
-    // the GError's FIELDS (domainName, quark, code, message) rather than a handle, and
-    // there is no second `errorClass` argument to give it. Rebuilding the GError from
-    // the fields keeps the ONE shape on that pairing too — it costs only the original
-    // GError's address, which nothing can read.
-    if (typeof handle === 'string') {
-        return wrapGError(newErrorLiteral(quark, code, message), true, buildThrownGError);
-    }
-    return wrapGError(handle, true, buildThrownGError);
-});
+onNativeLoaded(() =>
+    native.setErrorBuilder(function buildThrownGError(handle, quark, code, message) {
+        // Same cross-version pairing: an addon older than this JS calls the builder with
+        // the GError's FIELDS (domainName, quark, code, message) rather than a handle, and
+        // there is no second `errorClass` argument to give it. Rebuilding the GError from
+        // the fields keeps the ONE shape on that pairing too — it costs only the original
+        // GError's address, which nothing can read.
+        if (typeof handle === 'string') {
+            return wrapGError(newErrorLiteral(quark, code, message), true, buildThrownGError);
+        }
+        return wrapGError(handle, true, buildThrownGError);
+    }),
+);
 
 // Stamps a makeClass prototype with its { namespace, typeName } so Gio._promisify can
 // record WHICH introspected class a registration belongs to — matched against the
@@ -431,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;
@@ -442,8 +452,16 @@ 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;
 }
-native.setTemplateCallbackResolver(resolveTemplateCallback);
+onNativeLoaded(() => native.setTemplateCallbackResolver(resolveTemplateCallback));
 
 // Run a registered class's JS constructor for a GObject the ENGINE instantiated from C
 // — typically a GtkBuilder composite-template InternalChild, which has no JS-`new` to
@@ -461,12 +479,17 @@ 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;
     }
 }
-native.setConstructCallback(runCtorForCObject);
+onNativeLoaded(() => native.setConstructCallback(runCtorForCObject));
 
 // A non-GObject GObject-fundamental (GskRenderNode, GdkEvent) as an OPAQUE,
 // round-trippable handle: the native tagged External already carries the pointer and
@@ -927,13 +950,50 @@ function decorateGioNamespace(baseNs) {
     });
 }
 
+// The internals of the PROXY links on an introspected prototype chain: the Proxy
+// itself -> its target plus the materializer its getOwnPropertyDescriptor trap runs
+// (`null` for a Proxy that traps no descriptor read). Registered by
+// makeClassPrototype and vfuncChainProto; read only by findProtoDescriptor.
+//
+// Why: a descriptor read THROUGH a Proxy costs ~110 ns of V8 invariant machinery on
+// top of the handler, and an introspected chain is mostly Proxies. Measured on the
+// bench's depth-3 subject, a full MISS walk took 328 ns — 154 ns on the
+// makeClassPrototype link, 65 ns on vfuncChainProto, 12 ns on the one plain link.
+// With the target in hand the same answer costs 27 ns, because the trap body is
+// exactly `materialize(prop); return Reflect.getOwnPropertyDescriptor(target, prop)`
+// and running it directly skips only the machinery, never a step of the computation.
+//
+// This is NOT a cache of the ANSWER: nothing is remembered between calls. The target
+// is the object every mutation of the prototype lands on — none of the handlers trap
+// `set`, `defineProperty`, `deleteProperty` or `setPrototypeOf`, so
+// `Cls.prototype.m = f`, `Object.defineProperty(…)`, `delete` and a spliced chain
+// write through to it — and the descriptor still comes from a fresh read of it. That
+// has to hold, because GJS pins nothing: on gjs 1.88.1 every one of those mutations
+// is observable on an already-wrapped instance (measured), so an answer cache would
+// need an invalidation signal JS does not offer. test/proto-descriptor-liveness.test.mjs
+// is the proof obligation.
+const protoInternals = new WeakMap();
+
 // Walk a JS prototype chain (excluding Object.prototype) for an own property
 // descriptor of `prop` — used to surface a registerClass subclass's own methods
-// /getters/setters on the GObject wrapper.
+// /getters/setters on the GObject wrapper. One full walk runs per property GET, per
+// SET and per `emit`, so the Proxy bypass above is on the hottest path there is.
 function findProtoDescriptor(proto, prop) {
-    for (let p = proto; p !== null && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
-        const d = Object.getOwnPropertyDescriptor(p, prop);
+    for (let p = proto; p !== null && p !== Object.prototype;) {
+        const internals = protoInternals.get(p);
+        if (internals === undefined) {
+            const d = Object.getOwnPropertyDescriptor(p, prop);
+            if (d !== undefined) return d;
+            p = Object.getPrototypeOf(p);
+            continue;
+        }
+        const { target, materialize } = internals;
+        if (materialize !== null) materialize(prop);
+        const d = Object.getOwnPropertyDescriptor(target, prop);
         if (d !== undefined) return d;
+        // The target's prototype, not the Proxy's: neither handler traps
+        // getPrototypeOf, so these are the same link — one fewer trap to pay.
+        p = Object.getPrototypeOf(target);
     }
     return undefined;
 }
@@ -1088,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()));
@@ -1104,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;
 }
@@ -1131,9 +1200,9 @@ function runJsPropertySetter(handle, propertyName) {
 // function` until the next release republishes the binary. Every native call added
 // here degrades instead; without the callback, a post-construction set simply does
 // not reach the JS setter, which is what 0.50.0 did.
-if (typeof native.setPropertySetCallback === 'function') {
-    native.setPropertySetCallback(runJsPropertySetter);
-}
+onNativeLoaded(() => {
+    if (typeof native.setPropertySetCallback === 'function') native.setPropertySetCallback(runJsPropertySetter);
+});
 
 // Which properties the construct-time replay must run.
 //
@@ -1342,6 +1411,7 @@ export function startMainContextPump() {
     // GLib's default main context — a JS-timer pump would only iterate the
     // context recursively from within its own dispatch.
     if (hostPumpsItself()) return () => {};
+    ensureNative();
     pumpRefCount++;
     if (pumpTimer === null) {
         if (pendingView === null) pendingView = native.makePumpPendingCount();
@@ -1546,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);
@@ -1812,7 +1886,8 @@ function wrapInstance(handle, userProto) {
 // the introspected parent's `vfunc_x` is a thunk into the actual C vtable entry.
 // Non-`vfunc_` lookups fall through to Object.prototype (so the base prototype
 // keeps its normal object behaviour).
-const vfuncChainProto = new Proxy(Object.create(Object.prototype), {
+const vfuncChainTarget = Object.create(Object.prototype);
+const vfuncChainProto = new Proxy(vfuncChainTarget, {
     get(target, prop, receiver) {
         if (typeof prop === 'string' && prop.startsWith('vfunc_')) {
             const vfuncName = prop.slice('vfunc_'.length);
@@ -1827,6 +1902,10 @@ const vfuncChainProto = new Proxy(Object.create(Object.prototype), {
         return Reflect.get(target, prop, receiver);
     },
 });
+// No descriptor trap here: a `vfunc_*` access is synthesized by `get` alone and was
+// never reported as a descriptor, so the walk's answer for this link always came from
+// the target. `null` materializer = "read the target, that is the whole trap".
+protoInternals.set(vfuncChainProto, { target: vfuncChainTarget, materialize: null });
 
 // Surface a lazy `$gtype` getter on an introspected class/struct ctor: the real
 // GObject GType (a node-gi GType handle), resolved on first read via the engine
@@ -1994,7 +2073,7 @@ function makeClassPrototype(namespace, typeName) {
         }
         return arity >= 0 && define(prop, makeGiMethod(where, prop, arity));
     };
-    return new Proxy(target, {
+    const proto = new Proxy(target, {
         get(t, prop, receiver) {
             materialize(prop);
             return Reflect.get(t, prop, receiver);
@@ -2007,6 +2086,10 @@ function makeClassPrototype(namespace, typeName) {
             return materialize(prop) || Reflect.has(t, prop);
         },
     });
+    // Let findProtoDescriptor run the descriptor trap's body directly on the target —
+    // same two steps, without V8's per-trap invariant checks (see protoInternals).
+    protoInternals.set(proto, { target, materialize });
+    return proto;
 }
 
 function makeClass(namespace, typeName) {
@@ -2526,6 +2609,8 @@ function paramSpecGTyped(type) {
 const ParamSpec = Object.freeze({
     string: paramSpecPlain('string'),
     boolean: paramSpecPlain('boolean'),
+    char: paramSpecRanged('char'),
+    uchar: paramSpecRanged('uchar'),
     int: paramSpecRanged('int'),
     uint: paramSpecRanged('uint'),
     int64: paramSpecRanged('int64'),
@@ -2560,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') {
@@ -2568,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");
         }
     }
@@ -2735,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
@@ -2774,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') {
@@ -2822,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:
@@ -2865,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
@@ -2881,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
@@ -2973,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',
@@ -3042,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;
@@ -3190,6 +3669,7 @@ function mirrorWindowingEnvIntoCrt() {
  * @returns {Record<string, unknown>}
  */
 export function requireGi(namespace, version) {
+    ensureNative();
     native.requireNamespace(namespace, version);
     // The one moment the win32 CRT-environment mirror can run: the addon is loaded, so there
     // is a GLib to call, and nothing has built a font map or loaded a fontconfig