@gjsify/node-gi 0.45.0 → 0.46.0

package/src/object.cc

@@ -783,6 +783,31 @@ Napi::Value ClassInfoForTypeName(const Napi::CallbackInfo& info) {
 // union/enum/flags), as a node-gi GType handle. The L1 layer surfaces it as a
 // lazy `Ns.Type.$gtype` getter (so `Adw.Clamp.$gtype` / `GObject.type_ensure(...)`
 // work). Returns null for an unknown or unregistered name.
+//
+// It also REALISES a classed type, because gjs's whole type system rests on the
+// invariant its own gi/function.cpp states — "the GType class is referenced at least
+// once when the JS constructor is initialized". Signals and properties are installed
+// in `class_init`, which GLib defers until something takes a `g_type_class_ref`, so a
+// class NOTHING in the process has referenced reports none of its own: measured,
+// `GObject.signal_lookup('popped', Adw.NavigationView.$gtype)` answered 84 under gjs
+// and 0 here, and `signal_lookup('activate', Gio.Application.$gtype)` 28 against 0 —
+// a wrong answer with nothing thrown, which a caller reads as "this class has no such
+// signal" (#1438). `$gtype` is the one read every such lookup goes through and gi.js
+// memoises it, so this costs exactly one `g_type_class_ref` per GType.
+//
+// The ref is KEPT, for the reason calls.cc's ClassStructInstanceForGType keeps its
+// own: it establishes the invariant once, a static type's class is never really freed
+// (measured on glib 2.88.3 — `g_type_class_peek` still answers the same pointer after
+// an unref), and pairing could only invalidate what a caller is still holding. The
+// `g_type_class_peek` guard bounds it at ONE ref per GType for the process, whatever
+// order the two ref sites are reached in.
+//
+// Guarded on G_TYPE_IS_CLASSED because the UNCLASSED fundamentals — boxed/struct and
+// interface — have no class: `g_type_class_ref` answers nullptr there after a
+// `GLib-GObject-CRITICAL`, so without the guard every `GLib.Bytes.$gtype` read would
+// print one. ENUM and FLAGS are classed (GEnumClass/GFlagsClass) and deliberately go
+// through, as they do in gjs. Nothing THROWS on the unguarded path, so the witness is
+// `class-realization.test.mjs`'s child-process stderr case, not an in-process read.
 Napi::Value GetGType(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   if (info.Length() < 2 || !info[0].IsString() || !info[1].IsString()) {
@@ -800,6 +825,7 @@ Napi::Value GetGType(const Napi::CallbackInfo& info) {
   if (base != nullptr) gi_base_info_unref(base);
   g_object_unref(repo);
   if (gt == G_TYPE_INVALID || gt == G_TYPE_NONE) return env.Null();
+  if (G_TYPE_IS_CLASSED(gt) && g_type_class_peek(gt) == nullptr) g_type_class_ref(gt);
   return MakeGTypeHandle(env, gt);
 }
 

package/src/repo.cc

@@ -13,6 +13,7 @@ void NodeGiEnvDataFinalize(napi_env env, void* data, void* /*hint*/) {
   NodeGiEnvData* d = static_cast<NodeGiEnvData*>(data);
   if (d == nullptr) return;
   if (d->errorBuilder != nullptr) napi_delete_reference(env, d->errorBuilder);
+  if (d->errorClass != nullptr) napi_delete_reference(env, d->errorClass);
   if (d->templateCallbackResolver != nullptr)
     napi_delete_reference(env, d->templateCallbackResolver);
   if (d->cairoWrappers != nullptr) napi_delete_reference(env, d->cairoWrappers);
@@ -258,14 +259,18 @@ Napi::Value GetErrorDomain(const Napi::CallbackInfo& info) {
   return result;
 }
 
-// setErrorBuilder(builder: (domainName, domainQuark, code, message) => Error) -> void
+// setErrorBuilder(builder: (domainName, domainQuark, code, message) => Error,
+//                 errorClass?: typeof GLib.Error) -> void
 // Register the L1 GLib.Error factory the engine calls when a GI invoke fails, so a
-// failed sync call throws a real GLib.Error. Stored per-env (a napi_ref is env-
-// specific; the throw path is gated on the same env).
+// failed sync call throws a real GLib.Error, together with the class it builds —
+// which the GError IN-arg path needs to recognise one coming back. Both stored
+// per-env (a napi_ref is env-specific; both paths are gated on the same env), in
+// ONE call so a registration cannot supply the builder and forget the class.
 Napi::Value SetErrorBuilder(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   if (info.Length() < 1 || !info[0].IsFunction()) {
-    Napi::TypeError::New(env, "setErrorBuilder(builder: function)").ThrowAsJavaScriptException();
+    Napi::TypeError::New(env, "setErrorBuilder(builder: function, errorClass?: function)")
+        .ThrowAsJavaScriptException();
     return env.Undefined();
   }
   NodeGiEnvData* d = EnvData(env);
@@ -275,6 +280,12 @@ Napi::Value SetErrorBuilder(const Napi::CallbackInfo& info) {
     d->errorBuilder = nullptr;
   }
   napi_create_reference(env, info[0], 1, &d->errorBuilder);
+  if (d->errorClass != nullptr) {
+    napi_delete_reference(env, d->errorClass);
+    d->errorClass = nullptr;
+  }
+  if (info.Length() >= 2 && info[1].IsFunction())
+    napi_create_reference(env, info[1], 1, &d->errorClass);
   return env.Undefined();
 }
 

package/src/toggle.cc

@@ -32,22 +32,35 @@ namespace nodegi {
 //      needed — N-API finalizers are post-GC.
 //   3. Cross-thread toggles + double-free: off-thread toggles are marshalled to
 //      the JS thread via a mutex-guarded queue drained on the GLib main context;
-//      a g_object_weak_ref safety net nulls the cached pointer if C finalizes the
-//      object under us; the idle clears qdata only if it still points at THIS
-//      wrapper (resurrection-safe); a shutdown flag disables toggles at teardown.
+//      a g_object_weak_ref net DETACHES the record from the object the moment glib
+//      says we may not touch it again (clearing qdata only if it still points at
+//      THIS wrapper — resurrection-safe); a shutdown flag disables toggles at
+//      teardown. The detach happens IN the weak notify, not in the teardown that
+//      follows it — see OnGObjectFinalized for why, and for what it costs.
 
 static GQuark NodeGiWrapperQuark() {
   static GQuark q = g_quark_from_static_string("node-gi::wrapper");
   return q;
 }
 
+// WHICH FIELDS g_queue_mutex PROTECTS, AND WHO TOUCHES THEM.
+//   `env` is written once at construction and never again — read from any thread.
+//   `handle_ref`, `rooted` and `teardown_queued`/`settled` are JS-THREAD ONLY by
+//   construction: only ApplyToggle (always on the drain/JS thread), the External's
+//   finalizer and the resurrection path write them.
+//   `gobject` and `toggle_added` are the CROSS-THREAD pair and are guarded by
+//   g_queue_mutex: OnGObjectFinalized clears them from whatever thread drops the
+//   object's last ref (or calls g_object_run_dispose), while RunTeardown and
+//   SettleCollectedInstance read them on the JS thread. The lock does more than
+//   order those writes — see OnGObjectFinalized for why an atomic would not do.
 struct NodeGiInstance {
   napi_env env;
-  GObject* gobject;        // nulled by the weak-ref safety net if C finalizes it
+  GObject* gobject;        // g_queue_mutex; cleared by the weak-ref net (see below)
   napi_ref handle_ref;     // ref to the canonical External; strong=rooted, weak=not
   bool rooted;             // true ⇒ handle_ref currently strong (mirrors node-gtk !dying)
-  bool toggle_added;       // a toggle ref is currently installed
-  bool teardown_queued;    // a finalizer already scheduled the idle teardown (dedupe)
+  bool toggle_added;       // g_queue_mutex; a REMOVABLE toggle ref is installed
+  bool teardown_queued;    // the External's finalizer HAS RUN (and queued the teardown)
+  bool settled;            // resurrection detached this record; the pending finalizer frees it
 };
 
 // The single N-API env that OWNS the toggle machinery (qdata cache + global drain
@@ -259,6 +272,23 @@ static void ApplyToggle(NodeGiInstance* inst, bool down) {
   }
 }
 
+// Sever every link between a GObject and a wrapper record: after this, nothing can
+// reach `inst` from `obj` on any thread. Clearing qdata is what keeps a LIVE GObject
+// from outliving its record with a dangling pointer in it (see OnGObjectFinalized).
+//
+// CALLER MUST HOLD g_queue_mutex, and `obj` must be valid FOR THE DURATION OF THE
+// CALL. Each caller has its own warrant for that: the weak-ref net is handed the
+// object while it is still addressable, RunTeardown reads inst->gobject under this
+// lock, and SettleCollectedInstance is passed the caller's construction ref.
+static void DetachInstanceLocked(NodeGiInstance* inst, GObject* obj) {
+  if (obj != nullptr && g_object_get_qdata(obj, NodeGiWrapperQuark()) == inst) {
+    g_object_set_qdata(obj, NodeGiWrapperQuark(), nullptr);
+  }
+  for (auto it = g_toggle_queue.begin(); it != g_toggle_queue.end();) {
+    it = (it->inst == inst) ? g_toggle_queue.erase(it) : it + 1;
+  }
+}
+
 // Run one wrapper's teardown on the JS thread: drop the toggle ref (may dispose →
 // emit → re-enter JS — legal here, not in a finalizer/off-thread), resurrection-
 // safely, then free the wrapper.
@@ -266,30 +296,32 @@ static void ApplyToggle(NodeGiInstance* inst, bool down) {
 // ORDER MATTERS (node-gtk's GObjectTeardownIdle): remove_toggle_ref is LAST,
 // because dropping the last ref can take refcount to 0 → dispose → finalize → the
 // GObject is freed; any qdata/weak op after that would touch freed memory. So:
-//   (1) under the queue lock: detach qdata (only if it still points at US —
-//       resurrection-safe) AND cancel any queued off-thread toggles for this inst.
-//       Both under the lock — paired with the off-thread enqueue path, which
-//       re-reads qdata under the SAME lock — so a racing toggle either enqueues
-//       then gets cancelled here, or sees the cleared qdata and never enqueues;
-//       after this no NodeGiToggleNotify can find this inst.
-//   (2) g_object_weak_unref (drop the safety net before the unref below).
-//   (3) g_object_remove_toggle_ref LAST (may dispose → emit → re-enter JS, legal
-//       here on the JS thread; the object may be freed afterwards).
+//   (1) under the queue lock: READ inst->gobject, DetachInstanceLocked, drop the
+//       weak-ref net. The same lock the off-thread enqueue path and
+//       OnGObjectFinalized take, so a racing toggle either enqueues and is
+//       cancelled here, or sees the cleared qdata and never enqueues. The READ
+//       belongs inside it: it used to sit outside, paired with an unlocked write in
+//       OnGObjectFinalized, so a stale non-null pointer was reachable here BY
+//       CONSTRUCTION and `obj` could name freed memory.
+//   (2) g_object_remove_toggle_ref LAST and OUTSIDE the lock (it may dispose →
+//       emit → re-enter arbitrary JS, which must never run under this lock; legal
+//       here on the JS thread. The object may be freed afterwards). `obj` is still
+//       ours to touch there: the toggle ref we are about to remove IS a reference.
 static void RunTeardown(NodeGiInstance* inst) {
-  GObject* obj = inst->gobject;  // null if the weak-ref net already fired
+  GObject* obj = nullptr;
+  bool remove_toggle = false;
   {
     std::lock_guard<std::recursive_mutex> guard(g_queue_mutex);
-    if (obj != nullptr && g_object_get_qdata(obj, NodeGiWrapperQuark()) == inst) {
-      g_object_set_qdata(obj, NodeGiWrapperQuark(), nullptr);
-    }
-    for (auto it = g_toggle_queue.begin(); it != g_toggle_queue.end();) {
-      it = (it->inst == inst) ? g_toggle_queue.erase(it) : it + 1;
+    obj = inst->gobject;  // null once the weak-ref net has detached this record
+    DetachInstanceLocked(inst, obj);
+    if (obj != nullptr) {
+      g_object_weak_unref(obj, OnGObjectFinalized, inst);
+      remove_toggle = inst->toggle_added;
+      inst->toggle_added = false;
+      inst->gobject = nullptr;
     }
   }
-  if (obj != nullptr) {
-    g_object_weak_unref(obj, OnGObjectFinalized, inst);
-    if (inst->toggle_added) g_object_remove_toggle_ref(obj, NodeGiToggleNotify, nullptr);
-  }
+  if (remove_toggle) g_object_remove_toggle_ref(obj, NodeGiToggleNotify, nullptr);
   if (inst->handle_ref != nullptr) napi_delete_reference(inst->env, inst->handle_ref);
   delete inst;
 }
@@ -455,19 +487,93 @@ static void NodeGiToggleNotify(gpointer /*data*/, GObject* obj, gboolean is_last
   if (enqueued) WakeDrain();  // outside the lock
 }
 
-// Weak-ref safety net: if C finalizes the GObject while we still hold the toggle
-// ref (defensive — a correct toggle ref prevents this), null the cached pointer
-// so teardown never touches freed memory.
-static void OnGObjectFinalized(gpointer data, GObject* /*where_the_object_was*/) {
+// Weak-ref net: glib is telling us this record may never touch the object again.
+// It DETACHES the record here, because this callback is the LAST moment the object
+// pointer is guaranteed addressable — RunTeardown, which used to do the detaching,
+// runs later and by then has only the nulled field.
+//
+// "The object was finalized" is NOT what this callback means, and reading it that
+// way is what left a live GObject holding a freed record. `g_object_run_dispose`
+// notifies every GWeakNotify (and clears every GWeakRef) on an object that stays
+// ALIVE — measured on glib 2.88.3. Every `run_dispose()` a JS program makes lands
+// here, and so does `gtk_native_dialog_destroy()`, whose own docs promise it keeps
+// the object's references (measured, GTK 4.22.4: notify fires, dialog alive at
+// rc=1). NOT `gtk_window_destroy()`, measured on the same GTK: it unrealizes and
+// unrefs, it does not run_dispose — that was GTK3's `gtk_widget_destroy`. The old
+// callback only nulled `inst->gobject`, so the teardown then skipped its
+// `g_object_set_qdata(obj, quark, nullptr)` — and the surviving GObject kept a
+// qdata pointer to the record the teardown went on to `delete`. The next thing to
+// hand that GObject back to JS read the freed record (`napi_get_reference_value`
+// on its `handle_ref`) or fed it to the drain, where `g_object_get_qdata` on the
+// recycled record's `gobject` field is the documented SIGSEGV. Regression:
+// gc-identity "run_dispose: a surviving object keeps no freed record in its qdata".
+//
+// WHY THE LOCK AND NOT AN ATOMIC. An atomic exchange on `gobject` would remove the
+// data race and keep the bug: the reader would still be free to act on a pointer
+// that this callback is about to invalidate. g_queue_mutex gives the property that
+// is actually needed — the detach and the teardown's read-then-use of the same
+// pointer are mutually exclusive, so the two can never be interleaved. It costs no
+// deadlock risk: this callback runs with no glib lock held (a `g_object_weak_unref`
+// from inside a weak notify returns — measured), it calls no user code, and the
+// mutex is recursive, so a notify raised by a dispose already under the lock on
+// this thread re-acquires it.
+//
+// THE PRICE when the object OUTLIVES the notify: its toggle ref stays installed —
+// it cannot be removed from here (a dispose→JS re-entry inside a weak notify is
+// exactly what the teardown queue exists to avoid) and glib offers no way to learn
+// later that the object survived. Measured, glib 2.88.3: wrapper identity does not
+// survive a `run_dispose` (C hands back a NEW wrapper), that re-wrap adds a SECOND
+// toggle ref, and glib notifies only while there is exactly one — so the next 1↔2
+// crossing prints `Unexpected number of toggle-refs` instead, the new wrapper never
+// goes weak, and the GObject is immortal. The old code leaked the same toggle ref
+// and took a use-after-free with it. Pinned by gc-identity "run_dispose costs
+// wrapper identity"; the tombstone design that would retire this, and the
+// ref_count discriminator rejected for it, are in status/open-todos.md.
+static void OnGObjectFinalized(gpointer data, GObject* where_the_object_was) {
   NodeGiInstance* inst = static_cast<NodeGiInstance*>(data);
-  inst->gobject = nullptr;
+  bool enqueued = false;
+  {
+    std::lock_guard<std::recursive_mutex> guard(g_queue_mutex);
+    DetachInstanceLocked(inst, where_the_object_was);
+    inst->gobject = nullptr;
+    inst->toggle_added = false;  // no removable toggle ref left: the object is out of reach
+    // Let the husk record be COLLECTED. Detaching clears the qdata slot, so the
+    // toggle-down that `g_object_run_dispose` fires from its own closing unref no
+    // longer finds this record and can never flip it back to weak — a rooted
+    // wrapper that nothing will ever root again is a leak of the wrapper AND the
+    // object. Flip it here instead. napi_reference_unref is JS-thread-only, so an
+    // off-thread notify queues it; DetachInstanceLocked just emptied the queue of
+    // this inst, so the enqueue always lands (no opposite-direction cancel), and
+    // RunTeardown/SettleCollectedInstance cancel it again if they get there first.
+    //
+    // Gated on the shutdown flag exactly as NodeGiToggleNotify's direct apply is:
+    // glib notifies from whatever thread drops the ref, which can be long after the
+    // owner env is gone, and a napi call there is the abort that flag exists to
+    // stop. The DETACH above is pure glib and must run either way.
+    if (!g_toggle_shutdown.load()) {
+      if (OnMainThread()) ApplyToggle(inst, /*down=*/true);
+      else enqueued = EnqueueToggleLocked(inst, /*down=*/true);
+    }
+  }
+  if (enqueued) WakeDrain();  // outside the lock
 }
 
 // The canonical External's finalizer (napi_finalize, runs at a safe point post-GC
 // but where re-entering GObject teardown is still unsafe). Do the MINIMUM: queue
 // the teardown + wake the drain async (crash mode 1).
 static void NodeGiInstanceFinalize(Napi::Env /*env*/, GObject* /*data*/, NodeGiInstance* inst) {
-  if (inst == nullptr || inst->teardown_queued) return;
+  if (inst == nullptr) return;
+  if (inst->settled) {
+    // Resurrection got here first: SettleCollectedInstance already detached and
+    // disarmed this record and deliberately left it allocated for US to free
+    // (see the ownership note there). Nothing left to tear down.
+    if (NodeGiToggleDebugEnabled())
+      NodeGiToggleDebugLog("finalizer: freeing settled inst %p (resurrected earlier)",
+                           static_cast<void*>(inst));
+    delete inst;
+    return;
+  }
+  if (inst->teardown_queued) return;
   inst->teardown_queued = true;
   {
     std::lock_guard<std::recursive_mutex> guard(g_queue_mutex);
@@ -495,28 +601,64 @@ static void NodeGiInstanceFinalize(Napi::Env /*env*/, GObject* /*data*/, NodeGiI
 // toggle ref per GObject). The caller holds a construction ref on obj, so dropping
 // the old toggle ref here cannot drive refcount to 0 / dispose. Main-thread only (==
 // the drain thread), so the pending idle teardown cannot be running concurrently.
+//
+// WHO FREES `old` (#1475): an EMPTY napi_ref proves the wrapper was COLLECTED, not
+// that its finalizer has RUN. V8 resets the weak persistent inside the first-pass
+// weak callback, during GC; Node then defers NodeGiInstanceFinalize to a SetImmediate
+// (node_napi_env__::EnqueueFinalizer). Freeing `old` inside that window is a
+// use-after-free with a reliable second act: the allocator hands the very same block
+// straight back to the fresh `new NodeGiInstance()` below (measured: identical
+// address every run), so the stale finalizer then reads the LIVE wrapper's record,
+// sees teardown_queued == false, and queues a teardown that removes the LIVE toggle
+// ref — dropping the GObject's last ref while JS still holds a wrapper for it. The
+// wreckage surfaces one drain later as `g_object_weak_unref: couldn't find weak ref`
+// plus a double napi_delete_reference / double free (STATUS_HEAP_CORRUPTION on
+// Windows, SIGSEGV on Linux). So ownership of the free follows the finalizer:
+// teardown_queued == true means it already ran and nobody else will free the record;
+// otherwise it is still pending and IT frees the record, guided by `settled`.
 static void SettleCollectedInstance(GObject* obj, NodeGiInstance* old) {
+  bool finalizer_pending = false;
+  bool remove_toggle = false;
   {
     std::lock_guard<std::recursive_mutex> guard(g_queue_mutex);
-    // Cancel old's pending teardown + any queued toggles that reference it, so the
+    // Cancel old's pending teardown, then DetachInstanceLocked for the rest, so the
     // drain never touches a freed inst (paired with the off-thread enqueue, which
-    // re-reads qdata under this SAME lock — and we clear qdata below).
+    // re-reads qdata under this SAME lock).
     for (auto it = g_teardown_queue.begin(); it != g_teardown_queue.end();)
       it = (it->inst == old) ? g_teardown_queue.erase(it) : it + 1;
-    for (auto it = g_toggle_queue.begin(); it != g_toggle_queue.end();)
-      it = (it->inst == old) ? g_toggle_queue.erase(it) : it + 1;
-    // Detach qdata only if it still points at old (resurrection-safe).
-    if (g_object_get_qdata(obj, NodeGiWrapperQuark()) == old)
-      g_object_set_qdata(obj, NodeGiWrapperQuark(), nullptr);
+    DetachInstanceLocked(old, obj);
+    finalizer_pending = !old->teardown_queued;
+    old->settled = true;
+    // `old->gobject` and `old->toggle_added` are read here, under the lock the
+    // weak-ref net clears them with — a null pointer means the net already ran and
+    // the object is out of reach, exactly as in RunTeardown.
+    if (old->gobject != nullptr) {
+      g_object_weak_unref(obj, OnGObjectFinalized, old);
+      remove_toggle = old->toggle_added;
+    }
+    // Disarm every handle the record still carries, so a pending finalizer that
+    // reaches it finds nothing to act on even if `settled` were ever missed.
+    old->gobject = nullptr;
+    old->toggle_added = false;
   }
-  if (old->gobject != nullptr) {
-    g_object_weak_unref(obj, OnGObjectFinalized, old);
-    // Remove old's toggle ref BEFORE the fresh one is added below — never two at
-    // once. We hold a construction ref, so this cannot dispose obj.
-    if (old->toggle_added) g_object_remove_toggle_ref(obj, NodeGiToggleNotify, nullptr);
+  // Remove old's toggle ref BEFORE the fresh one is added by the caller — never two
+  // at once. The caller holds a construction ref, so this cannot dispose obj; it is
+  // still done outside the lock, because remove_toggle_ref is the one call in this
+  // file that may re-enter JS and the lock is never held across that.
+  if (remove_toggle) g_object_remove_toggle_ref(obj, NodeGiToggleNotify, nullptr);
+  if (old->handle_ref != nullptr) {
+    napi_delete_reference(old->env, old->handle_ref);
+    old->handle_ref = nullptr;
   }
-  if (old->handle_ref != nullptr) napi_delete_reference(old->env, old->handle_ref);
-  delete old;
+  if (NodeGiToggleDebugEnabled())
+    NodeGiToggleDebugLog("settle: detached inst %p (obj %p); %s", static_cast<void*>(old),
+                         static_cast<void*>(obj),
+                         finalizer_pending ? "finalizer pending, it frees the record"
+                                           : "finalizer already ran, freeing here");
+  // Only free when the finalizer has already run; otherwise it owns the free. If a
+  // process dies before draining its finalizer queue the record is not freed — the
+  // same bounded leak-at-exit the shutdown-dropped teardowns already accept.
+  if (!finalizer_pending) delete old;
 }
 
 // Cache-aware factory: the caller owns exactly ONE non-floating "construction"
@@ -580,6 +722,7 @@ Napi::Value MakeGObjectHandle(Napi::Env env, GObject* obj) {
   inst->rooted = true;
   inst->toggle_added = false;
   inst->teardown_queued = false;
+  inst->settled = false;
 
   Napi::External<GObject> ext =
       Napi::External<GObject>::New(env, obj, NodeGiInstanceFinalize, inst);
@@ -598,14 +741,26 @@ Napi::Value MakeGObjectHandle(Napi::Env env, GObject* obj) {
   ext.TypeTag(&kGObjectHandleTag);
   napi_create_reference(env, ext, 1, &inst->handle_ref);  // start STRONG (node-gtk invariant)
 
-  g_object_set_qdata(obj, NodeGiWrapperQuark(), inst);     // overwrite (resurrection-safe)
-  g_object_weak_ref(obj, OnGObjectFinalized, inst);        // safety net
-  g_object_add_toggle_ref(obj, NodeGiToggleNotify, nullptr);
-  inst->toggle_added = true;
-  // Drop the construction ref → only the toggle ref remains. If nothing else
-  // holds obj (refcount 2→1) this fires toggle-down synchronously, flipping the
-  // fresh wrapper to weak; if C holds another ref it stays strong (rooted).
-  g_object_unref(obj);
+  // ARMING is done under the queue lock, so the record is never half-installed as
+  // far as another thread is concerned: publishing it in qdata, arming the weak-ref
+  // net and claiming `toggle_added` become one step. A toggle-notify raised from
+  // INSIDE this block runs on this thread and re-acquires the recursive lock; the
+  // notify does napi work only, never JS, so the no-lock-across-dispose invariant
+  // still holds. Without it, a foreign-thread g_object_run_dispose landing between
+  // g_object_weak_ref and `toggle_added = true` would have its detach overwritten.
+  // The unref below cannot reach dispose either — add_toggle_ref took a ref of its
+  // own, so the count is >= 2 going in — which is what makes it safe under a lock.
+  {
+    std::lock_guard<std::recursive_mutex> guard(g_queue_mutex);
+    g_object_set_qdata(obj, NodeGiWrapperQuark(), inst);   // overwrite (resurrection-safe)
+    g_object_weak_ref(obj, OnGObjectFinalized, inst);      // safety net
+    g_object_add_toggle_ref(obj, NodeGiToggleNotify, nullptr);
+    inst->toggle_added = true;
+    // Drop the construction ref → only the toggle ref remains. If nothing else
+    // holds obj (refcount 2→1) this fires toggle-down synchronously, flipping the
+    // fresh wrapper to weak; if C holds another ref it stays strong (rooted).
+    g_object_unref(obj);
+  }
   return ext;
 }
 

package/system-gi.d.ts

@@ -10,6 +10,10 @@ export interface SystemGiOptions {
     /** `pkg-config`'s `.pc` search directories; defaults to {@link pkgConfigSearchDirs}. */
     searchDirs?: (env: NodeJS.ProcessEnv) => string[];
 }
+/** The subdir GI's own install layout puts typelibs in — the marker that names that layout. */
+export const TYPELIB_SUBDIR: string;
+/** Library dirs a typelib dir implies, most specific first — install layout and staged layout, unverified. */
+export function giLibraryDirsForTypelibDir(typelibDir: string): string[];
 /** Split an OS search-path variable, dropping empty segments. */
 export function splitSearchPath(value: string | undefined, separator?: string): string[];
 /** `$PKG_CONFIG_PATH` plus `pkg-config`'s own `pc_path`; memoized, absent pkg-config yields just the env. */

package/system-gi.js

@@ -38,6 +38,9 @@
 // `/opt/homebrew/lib` (Homebrew arm64), `/opt/local/lib` (MacPorts) or a custom
 // prefix without needing to know that any of them exist.
 //
+// THAT IS ONE LAYOUT, NOT THE LAYOUT — {@link giLibraryDirsForTypelibDir} holds the
+// second one and the measurement that found it.
+//
 // PURE FUNCTION of injected host facts (platform / env / fs / pkg-config), like
 // `hostTarget()` beside it and the CLI's `resolvePrebuildDirName()` — so the
 // darwin branch is unit-testable from a Linux host and the host values are read
@@ -50,9 +53,10 @@
 // the child. The CLI cannot IMPORT this module: ADR 0005 Decision 2 forbids a
 // Tier-1 package taking a dependency edge on `@gjsify/node-gi`. So the port is
 // pinned by an agreement test — `packages/infra/cli/src/utils/system-gi.spec.ts`
-// imports THIS file by relative path and asserts both implementations return
-// identical arrays for a table of injected inputs. Change one, change both; the
-// eventual lift to a shared package is tracked in `status/open-todos.md`.
+// imports THIS file by relative path and asserts identical arrays for a table of
+// injected inputs. It pins a THIRD copy the same way, `@gjsify/utils/core`'s
+// `system-gi-dirs.ts`. Change one, change all three; the lift that deletes two of
+// them is tracked in `status/open-todos.md`.
 import { statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 // POSIX path semantics, not the HOST's. This function answers a question about
@@ -87,12 +91,60 @@ const PROBED_GI_LIBDIRS = {
 /**
  * The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API.
  *
- * Exported so `gi-typelib.ts` shares it rather than keeping a third copy of the
- * one string this whole layout rule turns on. Both mirrors export it, so the
- * agreement suite still compares two files that differ only in language.
+ * Exported because the whole layout rule turns on this one string and all three
+ * copies of the rule must turn on the SAME one; the agreement suite compares it
+ * across them rather than trusting three literals to stay equal.
  */
 export const TYPELIB_SUBDIR = 'girepository-1.0';
 
+/**
+ * The library directories a typelib directory implies, most specific first.
+ *
+ * TWO LAYOUTS put a typelib and the library it names in different places, and a
+ * path on its own cannot always tell which one it is looking at:
+ *
+ *   * GI's INSTALL layout — `<libdir>/girepository-1.0/Gtk-4.0.typelib` beside
+ *     `<libdir>/libgtk-4.1.dylib`. The libdir is the PARENT.
+ *   * A STAGED layout — the pair sits FLAT in one directory. That is what an
+ *     ADR 0017 prebuild is (`<pkg>/prebuilds/darwin-x64/WebKit-6.0.typelib` beside
+ *     `libgjsifywebkit.dylib`) and what `gjsify.ship.bundledTypelibs` stages. The
+ *     libdir is the DIRECTORY ITSELF.
+ *
+ * {@link TYPELIB_SUBDIR} as the basename is a POSITIVE signal for the first: a
+ * directory GI itself named is GI's own layout, and its parent is the answer.
+ * Absent that name the layout is UNKNOWN — a relocated stack's typelib directory
+ * carries no required name — so both readings are offered and `existsDir` keeps
+ * whichever is real.
+ *
+ * OFFERING BOTH IS CHEAP AND ORDER IS NOT. The caller prepends the survivors to a
+ * loader search path, so a directory that names nothing costs one `stat` per miss —
+ * but whichever comes FIRST is where a bare leaf resolves from, and only the staged
+ * reading can hold a library at all. Hence staged-then-parent, and hence the marker
+ * DECIDING for the install layout rather than a probe offering both everywhere:
+ * `<libdir>/girepository-1.0/` is the one directory guaranteed to hold no library,
+ * and the canonical case must gain no noise.
+ *
+ * MEASURED, and the parent-only derivation is what it cost. macOS 15.7.9 / Node
+ * 24.18.1 / `@gjsify/webkit-native` 0.45.0, with
+ * `GI_TYPELIB_PATH=<…>/webkit-native-darwin-x64/prebuilds/darwin-x64` and nothing
+ * else: GI found the typelib and never its backer.
+ *
+ *     GLib-GIRepository-WARNING: Failed to load shared library
+ *       'libgjsifywebkit.dylib' referenced by the typelib
+ *     TypeError: WebKit.WebView is not a constructible GObject type
+ *
+ * dyld's own trace named `…/webkit-native-darwin-x64/prebuilds/libgjsifywebkit.dylib`
+ * — the PARENT of the directory the dylib is in, which is this function's previous
+ * answer written out. On darwin that is not a degraded search but a dead one:
+ * `@gjsify/webkit-native` is the only WebKit any darwin host has (ADR 0022).
+ * @param {string} typelibDir one entry of a `GI_TYPELIB_PATH`
+ * @returns {string[]} candidate library directories, unverified
+ */
+export function giLibraryDirsForTypelibDir(typelibDir) {
+    const parent = dirname(typelibDir);
+    return basename(typelibDir) === TYPELIB_SUBDIR ? [parent] : [typelibDir, parent];
+}
+
 /** Memoized `pkg-config` answer: the spawn happens at most once per process. */
 let pkgConfigDirsCache = null;
 
@@ -156,8 +208,9 @@ export function pkgConfigSearchDirs(env) {
  *
  * Three sources, in precedence order:
  *   1. `GI_TYPELIB_PATH` — the host stating outright where typelibs live; the
- *      libraries are the sibling `dirname()`. Accepted on directory existence
- *      alone: an explicit statement is not second-guessed.
+ *      libraries are wherever {@link giLibraryDirsForTypelibDir} says the layout
+ *      puts them. Accepted on directory existence alone: an explicit statement is
+ *      not second-guessed.
  *   2. `pkg-config`'s `.pc` search path → each `<dir>/pkgconfig`'s parent. The
  *      general mechanism (any prefix, including a custom one).
  *   3. {@link PROBED_GI_LIBDIRS} — the standard macOS prefixes, for the common
@@ -201,10 +254,11 @@ export function systemGiLibraryDirs({
         if (dir && dir !== '/' && !out.includes(dir)) out.push(dir);
     };
 
-    // 1. Explicit: the typelib dir's sibling libdir.
+    // 1. Explicit: the libdirs each typelib dir implies, both layouts.
     for (const typelibDir of splitSearchPath(env.GI_TYPELIB_PATH)) {
-        const libDir = dirname(typelibDir);
-        if (existsDir(libDir)) add(libDir);
+        for (const libDir of giLibraryDirsForTypelibDir(typelibDir)) {
+            if (existsDir(libDir)) add(libDir);
+        }
     }
 
     // 2 + 3. Candidate prefixes, believed only on the girepository-1.0 marker.