@gjsify/node-gi 0.24.2 → 0.26.0

package/gi.js

@@ -19,7 +19,18 @@ import * as native from './index.js';
 // setImmediate is a Node global but NOT a Deno global (Deno requires the explicit
 // node:timers import; Bun/Node re-export it there too), so import it for the
 // macrotask-deferred runAsync to work on all three runtimes.
-import { setImmediate } from 'node:timers';
+//
+// setInterval/clearInterval come from here for a second, load-bearing reason:
+// the RUNTIME's timers, never `globalThis.setInterval`. A GJS source running
+// through the bridge routinely replaces the global timers with GLib-backed ones
+// (`@gjsify/node-globals/register` swaps them for `GLib.timeout_add` wrappers) —
+// driving the GLib pump off a GLib timeout is a deadlock: the timer that is
+// supposed to dispatch GLib sources is itself a GLib source nobody dispatches.
+import { setImmediate, setInterval, clearInterval } from 'node:timers';
+// Same reasoning for `process`: `globalThis.process` may be the `@gjsify/process`
+// polyfill, whose EventEmitter never emits the runtime's 'beforeExit'. The
+// loop-liveness hooks below must attach to the real one or they silently never fire.
+import runtimeProcess from 'node:process';
 // The GJS Gio DBus surface (Gio.DBus.session/system, own_name/watch_name,
 // Gio.DBusProxy.makeProxyWrapper, Gio.DBusExportedObject) — ported to the L1 model.
 import { createGioDBus } from './overrides/gio-dbus.js';
@@ -977,11 +988,94 @@ function applicationRunAsync(handle) {
 // concurrent runAsync calls share one timer.
 let pumpTimer = null;
 let pumpRefCount = 0;
+// How many of those refs belong to the AUTO-armed pump (requireGi's permanent
+// hold on Bun/Deno). `pumpRefCount > pumpAutoRefs` therefore means an EXPLICIT
+// `startMainContextPump()` caller currently holds the pump.
+let pumpAutoRefs = 0;
+// Whether the pump timer currently HOLDS the runtime's event loop open (ref'd).
+let pumpHoldsRuntime = false;
+
+/** Dispatch every currently-ready GLib source, then return. */
+function drainReadySources() {
+  let guard = 0;
+  while (native.iterateMainContext(false) && guard++ < 100000) {
+    /* drain ready sources */
+  }
+}
+
+// Zero-N-API view over the JS-armed-work counter — `pendingView[0] > 0` is
+// `mainContextHasPending()` as a plain V8 memory read. The IDLE beat must not
+// enter the addon at all: on Deno, a single napi call from the pump tick during
+// the between-test-files GC window reproduces the #47 boxed-handle teardown
+// SIGSEGV (measured on the gtk-smoke leg: a query-only tick crashed 3/3, a tick
+// that never touches the addon exited 0, the full dispatching tick crashed
+// 10/10). So every read on the beat's idle path goes through this view.
+// Created LAZILY on the first pump arm (Bun/Deno only): the @gjsify/napi shim
+// loud-stubs external arraybuffers, and the gjs host never arms the pump.
+let pendingView = null;
+
+/**
+ * One pump beat: dispatch if the program owns GLib work, then re-evaluate the
+ * keep-alive hold. Both the gate and the hold read the SAME counter, so the
+ * auto-armed pump dispatches exactly when it also holds the loop open.
+ *
+ * DISPATCH is gated like the hold — on the program's OWN GLib work. An EXPLICIT
+ * `startMainContextPump()` holder gets unconditional dispatch (its documented
+ * contract: co-pump the context, whatever is in it). The AUTO-armed pump
+ * dispatches only while a JS-armed GI callback is outstanding (scope=async
+ * completions + scope=notified sources), so a FINISHED program stops touching
+ * the addon entirely instead of grinding through GDK/GIO's C-armed housekeeping
+ * sources forever.
+ *
+ * That silence is load-bearing on Deno: the documented #47 N-API teardown race
+ * is armed by the pump ENTERING the addon between test files (see pendingView
+ * above), while stopping/unref'ing the pump at teardown does NOT avoid it.
+ * Nothing is lost for a RUNNING program: any JS-observable progress path is
+ * counted (a Gio completion is scope=async, a `GLib.timeout_add` is
+ * scope=notified), and while one is outstanding the beat drains ALL ready
+ * sources, C-armed ones included.
+ */
+function pumpBeat() {
+  if (pumpRefCount > pumpAutoRefs || pendingView[0] > 0) {
+    drainReadySources();
+  }
+  syncPumpKeepAlive();
+}
+
+/**
+ * Keep-alive accounting — the portable twin of the uv auto-pump's ref/unref
+ * policy (`src/loop.cc`): scheduled GLib work (an armed timeout/idle) or an
+ * in-flight scope=async GI callback holds the runtime's event loop open;
+ * anything else lets it drain.
+ *
+ * Both halves are load-bearing. Permanently UNREF'd (the pre-fix behaviour) a
+ * program whose only pending work lives in GLib dies mid-flight — a bare
+ * `await` on a GLib timeout never settles and the runtime exits 0 with the
+ * program half-run. Permanently REF'd, a sync-only program would never exit.
+ *
+ * Consequence, identical to Node's auto-pump: a REPEATING GLib timeout has
+ * `setInterval` semantics and keeps the process alive, where `gjs -m` exits once
+ * the module settles. That is the one deliberate lifetime divergence from gjs,
+ * and it is now the SAME on node, bun and deno rather than node-only.
+ */
+function syncPumpKeepAlive() {
+  if (pumpTimer === null) return;
+  const hold = pendingView[0] > 0; // zero-N-API — see pendingView above
+  if (hold === pumpHoldsRuntime) return;
+  if (hold) pumpTimer.ref?.();
+  else pumpTimer.unref?.();
+  pumpHoldsRuntime = hold;
+}
 
 /**
  * Start co-pumping the default GLib main context from a runtime timer (Bun/Deno).
  * No-op on Node, where the libuv↔GLib bridge already co-pumps. Reference-counted;
  * returns a disposer that decrements the count (clearing the timer at zero).
+ *
+ * `requireGi` arms this automatically on Bun/Deno (the Node twin of
+ * `native.startMainLoop()`), so a plain `bun bundle.mjs` / `deno run bundle.mjs`
+ * dispatches GLib sources with no explicit loop — calling it by hand is only
+ * needed to hold the pump across a scope that must not depend on that.
  * @returns {() => void}
  */
 export function startMainContextPump() {
@@ -991,18 +1085,17 @@ export function startMainContextPump() {
   if (native.isNodeRuntime || native.RUNTIME === 'gjs') return () => {};
   pumpRefCount++;
   if (pumpTimer === null) {
-    // ~4 ms cadence: low latency without busy-spinning. Each tick drains every
+    if (pendingView === null) pendingView = native.makePumpPendingCount();
+    // ~4 ms cadence: low latency without busy-spinning. Each beat drains every
     // currently-ready source (iterateMainContext(false) returns false when none
-    // remain, bounding the inner loop), then yields to the runtime loop.
-    pumpTimer = setInterval(() => {
-      let guard = 0;
-      while (native.iterateMainContext(false) && guard++ < 100000) {
-        /* drain ready sources */
-      }
-    }, 4);
-    // Don't let the pump alone keep the process alive where the runtime allows it
-    // (Node/Bun expose Timeout.unref; Deno's numeric handle has none).
-    if (typeof pumpTimer.unref === 'function') pumpTimer.unref();
+    // remain, bounding the inner loop) — gated on the program's own GLib work
+    // for the auto-armed pump, see pumpBeat — then re-evaluates the hold.
+    pumpTimer = setInterval(pumpBeat, 4);
+    // Start UNREF'd: the pump alone must never keep a finished program alive.
+    // syncPumpKeepAlive() refs it for exactly as long as GLib has work.
+    pumpTimer.unref?.();
+    pumpHoldsRuntime = false;
+    syncPumpKeepAlive();
   }
   let disposed = false;
   return () => {
@@ -1019,6 +1112,7 @@ export function stopMainContextPump() {
   if (pumpRefCount === 0 && pumpTimer !== null) {
     clearInterval(pumpTimer);
     pumpTimer = null;
+    pumpHoldsRuntime = false;
   }
 }
 
@@ -2309,7 +2403,27 @@ export function requireGi(namespace, version) {
       // 'beforeExit' fires exactly when the loop runs empty: drain what is
       // ready and re-arm — if GLib still has scheduled work, the armed (ref'd)
       // uv timer revives the loop; otherwise the process exits normally.
-      process.on('beforeExit', () => native.pumpKick());
+      runtimeProcess.on('beforeExit', () => native.pumpKick());
+    } else if (native.RUNTIME !== 'gjs') {
+      // Bun/Deno: no libuv to hook, so the portable timer pump IS the auto-pump.
+      // Armed HERE, not left to the caller, so that `bun bundle.mjs` /
+      // `deno run bundle.mjs` behaves like `node bundle.mjs` and `gjs -m`:
+      // GLib sources dispatch with no explicit loop anywhere, and the pump's
+      // keep-alive accounting decides when the process may exit. Leaving it
+      // opt-in is what made the same bundle exit 0 MID-suite on bun/deno while
+      // node ran it to completion.
+      startMainContextPump(); // permanent +1 — the auto-pump is never disposed
+      // Tag that hold as the AUTO pump's: pumpBeat dispatches for it only while
+      // a JS-armed GI callback is outstanding, so a finished program produces
+      // no teardown churn (the deno #47 window) — explicit callers keep
+      // unconditional dispatch.
+      pumpAutoRefs++;
+      // The portable analogue of the Node pump's beforeExit kick. The runtime's
+      // loop just ran empty, which is exactly the moment an unref'd pump would
+      // let the process die with GLib work still outstanding: run one beat —
+      // if the program still owns GLib work it drains + re-refs (reviving the
+      // loop); if not, the beat stays silent and the process exits.
+      runtimeProcess.on('beforeExit', pumpBeat);
     }
     loopAttached = true;
   }

package/index.d.ts

@@ -418,6 +418,27 @@ export function startMainLoop(): void;
  */
 export function iterateMainContext(mayBlock?: boolean): boolean;
 
+/**
+ * Whether the default GLib main context holds work a *pumping* runtime must stay
+ * alive for: a scheduled source (an armed timeout/idle) or an in-flight
+ * scope=async GI callback. Pure GLib — the query half of the keep-alive contract
+ * the L1 `startMainContextPump` uses on Bun/Deno to decide whether its timer
+ * holds the runtime's event loop open. Node reads the same facts inline in the
+ * uv auto-pump.
+ */
+export function mainContextHasPending(): boolean;
+
+/**
+ * Create an `Int32Array(1)` view over the same JS-armed-work counter
+ * `mainContextHasPending()` reads (`view[0] > 0` is equivalent). Reading the
+ * view is a plain memory access — no call into the addon — which the Bun/Deno
+ * pump's idle beat depends on: on Deno, entering the addon from a timer tick
+ * during the between-test-files GC window reproduces the #47 boxed-handle
+ * teardown SIGSEGV. Lazy factory: the @gjsify/napi shim loud-stubs external
+ * arraybuffers and never arms the portable pump, so it must not run at Init.
+ */
+export function makePumpPendingCount(): Int32Array;
+
 /**
  * Drain ready GLib sources + re-arm the auto-pump's libuv wake-ups now (no-op
  * unless {@link startMainLoop} armed the pump on this env). The L1 layer wires
@@ -548,6 +569,8 @@ declare const native: {
   isVariantHandle: typeof isVariantHandle;
   startMainLoop: typeof startMainLoop;
   iterateMainContext: typeof iterateMainContext;
+  mainContextHasPending: typeof mainContextHasPending;
+  makePumpPendingCount: typeof makePumpPendingCount;
   pumpKick: typeof pumpKick;
   setMicrotaskDrain: typeof setMicrotaskDrain;
   connectSignal: typeof connectSignal;

package/index.js

@@ -179,11 +179,32 @@ if (!isNodeRuntime && RUNTIME !== 'gjs') {
       // (Bun's own processTicksAndRejections calls it from JS).
       ({ drainMicrotasks: drain } = require('bun:jsc'));
     } else if (typeof globalThis.Deno?.internal === 'symbol') {
-      // V8: core.runMicrotasks → op_run_microtasks →
-      // Isolate::PerformMicrotaskCheckpoint (a reentrant op, explicitly
-      // safe with JS frames on the stack).
+      // V8: the checkpoint needs BOTH queues. core.runMicrotasks is only
+      // Isolate::PerformMicrotaskCheckpoint; Deno's node-compat
+      // process.nextTick queue is a SEPARATE deno_core queue
+      // (ext:deno_node/_next_tick.ts → core.queueNextTick) that only the
+      // runtime's own event loop drains — and that loop is paused for the
+      // whole lifetime of a blocking run(). node:stream delivers stream
+      // 'end' via process.nextTick (endReadableNT), so with a
+      // microtask-only drain any body consumption over a Readable
+      // (@gjsify/fetch consumeBody → XHR arrayBuffer/text) got its chunks
+      // (microtask-delivered) but never the end: every asset load hung at
+      // readyState 3 forever on Deno while the SAME bundle settled on Bun,
+      // whose nextTick rides JSC's microtask queue (bun:jsc
+      // drainMicrotasks covers it). core.runNextTicks mirrors node's
+      // task_queues.js runNextTicks: microtask checkpoint when no ticks
+      // are scheduled, full processTicksAndRejections (ticks + microtasks
+      // interleaved) when there are — one call, both queues. Regression:
+      // test/blocking-run-checkpoint.test.mjs.
       const core = globalThis.Deno[globalThis.Deno.internal]?.core;
-      if (typeof core?.runMicrotasks === 'function') drain = () => core.runMicrotasks();
+      if (typeof core?.runNextTicks === 'function') {
+        drain = () => core.runNextTicks();
+      } else if (typeof core?.runMicrotasks === 'function') {
+        // Older deno_core without runNextTicks: microtask-only drain
+        // (pre-fix behaviour — promise continuations settle, nextTick
+        // consumers like node:stream 'end' still starve).
+        drain = () => core.runMicrotasks();
+      }
     }
     if (typeof drain === 'function') native.setMicrotaskDrain(drain);
   } catch {
@@ -640,6 +661,35 @@ export const startMainLoop = native.startMainLoop;
  */
 export const iterateMainContext = native.iterateMainContext;
 
+/**
+ * Whether the default GLib main context holds work a *pumping* runtime must stay
+ * alive for: a scheduled source (an armed timeout/idle — the prepare/query
+ * timeout hint is >= 0) or an in-flight scope=async GI callback. Pure GLib —
+ * the companion of {@link iterateMainContext} and the query half of the
+ * keep-alive contract the L1 `startMainContextPump` applies on Bun/Deno (Node
+ * reads the same facts inline in the uv auto-pump). A `false` answer is what
+ * lets a sync-only program exit immediately.
+ * @returns {boolean}
+ */
+export const mainContextHasPending = native.mainContextHasPending;
+
+/**
+ * Create an `Int32Array(1)` view over the SAME JS-armed-work counter
+ * {@link mainContextHasPending} reads — `view[0] > 0` ⇔
+ * `mainContextHasPending()`. The zero-N-API spelling: reading the view is a
+ * plain V8 memory access, no call into the addon. Load-bearing for the Bun/Deno
+ * pump's IDLE beat — on Deno, merely ENTERING the addon from a timer tick
+ * during the between-test-files GC window reproduces the #47 boxed-handle
+ * teardown SIGSEGV (measured: a query-only tick crashed 3/3 where a tick that
+ * never touches the addon exited 0), so the beat must be able to answer "is
+ * there work?" without a single native call. A lazy FACTORY rather than an
+ * Init-time export: the @gjsify/napi shim (the gjs-napi conformance oracle)
+ * loud-stubs `napi_create_external_arraybuffer`, and the gjs host never arms
+ * the portable pump — called only on the first Bun/Deno pump arm.
+ * @returns {Int32Array}
+ */
+export const makePumpPendingCount = native.makePumpPendingCount;
+
 /**
  * Drain ready GLib sources + re-arm the auto-pump's libuv wake-ups NOW (no-op
  * unless {@link startMainLoop} armed the pump, i.e. Node's main env). The L1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.24.2",
+  "version": "0.26.0",
   "description": "GObject-Introspection runtime for Node.js — load gi:// namespaces (GLib/GObject/Gio/…) with GJS-compatible semantics. Vendored + rewritten from node-gtk under MIT.",
   "type": "module",
   "license": "MIT",

package/src/addon.cc

@@ -113,6 +113,8 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("isVariantHandle", Napi::Function::New(env, IsVariantHandle));
   exports.Set("startMainLoop", Napi::Function::New(env, StartMainLoop));
   exports.Set("iterateMainContext", Napi::Function::New(env, IterateMainContext));
+  exports.Set("mainContextHasPending", Napi::Function::New(env, MainContextHasPending));
+  exports.Set("makePumpPendingCount", Napi::Function::New(env, MakePumpPendingCount));
   exports.Set("pumpKick", Napi::Function::New(env, PumpKick));
   exports.Set("setMicrotaskDrain", Napi::Function::New(env, SetMicrotaskDrain));
   exports.Set("connectSignal", Napi::Function::New(env, ConnectSignal));

package/src/calls.cc

@@ -28,10 +28,23 @@ struct NodeGiCallback {
   ffi_closure* closure;  // from gi_callable_info_create_closure
   gpointer native;       // executable trampoline address
   GIScopeType scope;
-  // scope=async only: counted in the auto-pump's in-flight keep-alive (the
-  // pending completion keeps the Node process alive, like in-flight Node I/O).
-  // Released exactly once — at the trampoline's single invocation, or at free
-  // if the callback never fired (an error path).
+  // Counted in the auto-pump's in-flight keep-alive — the process stays alive
+  // while JS-armed GLib work is outstanding, like in-flight Node I/O.
+  //   • scope=async    — a one-shot completion (GAsyncReadyCallback), released
+  //     at the trampoline's single invocation.
+  //   • scope=notified — a callback GLib owns until its GDestroyNotify fires:
+  //     `GLib.timeout_add` / `GLib.idle_add` and friends. Released by
+  //     NodeGiCallbackFree, i.e. exactly when GLib drops the source (the
+  //     callback returned SOURCE_REMOVE, or `GLib.Source.remove` killed it).
+  // Either way released exactly once, also at free if it never fired.
+  //
+  // Counting the JS-ARMED sources is the point: a source armed from JS is
+  // program work the process must survive for, while a source armed inside C —
+  // GDK's frame clock, GIO's portal/a11y retries — is library plumbing that
+  // `gjs -m` would never stay alive for either. Keying the keep-alive on "the
+  // context has ANY scheduled source" instead made a finished GTK program
+  // immortal: GDK leaves a ~1 s repeating timeout armed, so the context reports
+  // work forever while nothing is ever ready to dispatch.
   bool pumpCounted = false;
 };
 
@@ -301,10 +314,14 @@ static NodeGiCallback* CreateCallback(Napi::Env env, Napi::Function fn, GICallab
   cb->env = env;
   cb->info = reinterpret_cast<GICallableInfo*>(gi_base_info_ref(callbackInfo));
   cb->scope = scope;
-  // An async-scope callback is a one-shot in-flight operation (GAsyncReadyCallback
-  // et al): count it in the auto-pump keep-alive so the Node process stays alive
-  // until the completion dispatches (no-op off-Node / on non-owner envs).
-  if (scope == GI_SCOPE_TYPE_ASYNC) cb->pumpCounted = NodeGiPumpAsyncBegin(env);
+  // Count the JS-armed GLib work in the auto-pump keep-alive so the process
+  // stays alive until it completes: a one-shot in-flight operation
+  // (GAsyncReadyCallback et al, scope=async) or a source GLib owns until its
+  // destroy-notify (`GLib.timeout_add`/`idle_add`, scope=notified). See the
+  // `pumpCounted` note above for why JS-armed is the right unit.
+  if (scope == GI_SCOPE_TYPE_ASYNC || scope == GI_SCOPE_TYPE_NOTIFIED) {
+    cb->pumpCounted = NodeGiPumpAsyncBegin(env);
+  }
   napi_create_reference(env, fn, 1, &cb->jsFn);
   cb->closure = gi_callable_info_create_closure(callbackInfo, &cb->cif, NodeGiCallbackTrampoline, cb);
   cb->native = gi_callable_info_get_closure_native_address(callbackInfo, cb->closure);
@@ -545,6 +562,7 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
   // the invoke (the callee ref'd the GBytes if it kept it), transfer-full refs
   // belong to the callee (dropped only when the callee never ran).
   CreatedBytes createdBytes;
+  CreatedValues createdValues;
   bool ok = true;
   size_t jsCursor = 0;
   for (unsigned int i = 0; i < n_args && ok; i++) {
@@ -800,7 +818,7 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
       } else {
         GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
         ok = JsToGIArgument(env, v, ti, &in_args[inPos[i]], &held[i], tr, &ownedInStrings,
-                            &createdClosures, &createdBytes);
+                            &createdClosures, &createdBytes, &createdValues);
       }
     }
 
@@ -818,6 +836,9 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
     // Likewise every fresh GBytes built from a JS typed array — never adopted.
     for (GBytes* b : createdBytes.transferNone) g_bytes_unref(b);
     for (GBytes* b : createdBytes.transferFull) g_bytes_unref(b);
+    // Likewise every GValue boxed from a plain JS value — never adopted.
+    for (GValue* gv : createdValues.transferNone) NodeGiFreeBoxedGValue(gv);
+    for (GValue* gv : createdValues.transferFull) NodeGiFreeBoxedGValue(gv);
     // Likewise the transfer-full-instance ref: the callee never consumed it.
     if (instanceRefTaken) g_object_unref(static_cast<GObject*>(instance));
     for (gpointer s : ownedInStrings) g_free(s);  // never reached the callee (#658)
@@ -857,6 +878,11 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
   // paths). A callee that kept the bytes (GdkPixbuf.Pixbuf.new_from_bytes) holds
   // its own ref. Transfer-full GBytes were adopted by the callee — no release.
   for (GBytes* b : createdBytes.transferNone) g_bytes_unref(b);
+  // Transfer-none GValue IN-args boxed from plain JS values: the callee copied
+  // whatever it needed (g_object_set_property copies into the property), so the
+  // box is ours to free — success AND error paths, mirroring the GBytes rule.
+  // Transfer-full GValues were adopted by the callee — no release.
+  for (GValue* gv : createdValues.transferNone) NodeGiFreeBoxedGValue(gv);
   if (!success) {
     for (const InContainer& c : inContainers) FreeInContainer(c);
     // A failed invoke did not adopt the transfer-full IN/INOUT strings we g_strdup'd

package/src/common.h

@@ -295,6 +295,33 @@ struct CreatedBytes {
   std::vector<GBytes*> transferFull;  // callee adopts; unref only when the callee never ran
 };
 
+// A plain JS value handed to a `GObject.Value` IN-arg is BOXED into a fresh
+// GValue whose GType is guessed from the JS value — exactly what GJS does
+// (refs/gjs/gi/arg-cache.cpp GValueIn::in → gjs_value_to_g_value, whose
+// gjs_value_guess_g_type supplies the type for an uninitialized GValue). Without
+// it, the single most common GObject call in existence —
+// `obj.set_property('name', 0.5)`, whose second GI argument is a GValue — fails
+// with "Unsupported interface IN argument", because a JS number is not a boxed
+// handle. An existing GObject.Value boxed handle still routes through the
+// boxed-handle path and is passed through untouched.
+//
+// Lifetime mirrors CreatedBytes: the box is freed after the invoke for
+// transfer-none (the callee copied whatever it needed — g_object_set_property
+// copies into the property), and left with the callee for transfer-full.
+struct CreatedValues {
+  std::vector<GValue*> transferNone;  // free after the invoke (callee borrowed)
+  std::vector<GValue*> transferFull;  // callee adopts; free only when it never ran
+};
+
+// Release a GValue this layer boxed: unset the held value (dropping the ref an
+// object/boxed/string GValue took) and free the struct. A plain `g_free` would
+// leak whatever the GValue owns.
+inline void NodeGiFreeBoxedGValue(GValue* gv) {
+  if (gv == nullptr) return;
+  if (G_IS_VALUE(gv)) g_value_unset(gv);
+  g_free(gv);
+}
+
 // Build the (floating) marshaled GClosure for a JS function (signals.cc — shares
 // the battle-tested JsClosure marshal/finalize machinery with `.connect()`).
 GClosure* NodeGiMakeGenericJsClosure(Napi::Env env, Napi::Value fn);
@@ -309,12 +336,16 @@ GClosure* NodeGiMakeGenericJsClosure(Napi::Env env, Napi::Value fn);
 // `bytes` (optional): enables the JS-bytes→GBytes IN-arg marshalling above;
 // nullptr (the default) keeps the previous behaviour (typed array → TypeError) on
 // paths that cannot release a created GBytes.
+// `values` (optional): enables the JS-value→GValue IN-arg boxing above; nullptr
+// (the default) keeps the previous behaviour (plain value → TypeError) on paths
+// that cannot release a created GValue.
 bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument* out,
                     std::string* heldString,
                     GITransfer transfer = GI_TRANSFER_NOTHING,
                     std::vector<gpointer>* ownedStrings = nullptr,
                     CreatedClosures* closures = nullptr,
-                    CreatedBytes* bytes = nullptr);
+                    CreatedBytes* bytes = nullptr,
+                    CreatedValues* values = nullptr);
 
 // ---- IN container building -----------------------------------------
 //
@@ -604,6 +635,12 @@ Napi::Value BindingGroupBindFull(const Napi::CallbackInfo& info);
 // loop.cc
 Napi::Value StartMainLoop(const Napi::CallbackInfo& info);
 Napi::Value IterateMainContext(const Napi::CallbackInfo& info);
+Napi::Value MainContextHasPending(const Napi::CallbackInfo& info);
+// Factory for an Int32Array(1) view over the JS-armed-work counter (see
+// loop.cc) — lets the L1 pump answer "does the program own GLib work?" WITHOUT
+// a napi call. Lazy (a factory, not an Init-time export): the @gjsify/napi shim
+// loud-stubs napi_create_external_arraybuffer and never arms the pump.
+Napi::Value MakePumpPendingCount(const Napi::CallbackInfo& info);
 Napi::Value PumpKick(const Napi::CallbackInfo& info);
 Napi::Value SetMicrotaskDrain(const Napi::CallbackInfo& info);
 
@@ -612,8 +649,10 @@ Napi::Value SetMicrotaskDrain(const Napi::CallbackInfo& info);
 // In-flight scope=async keep-alive: while a GI scope=async callback (e.g. a
 // GAsyncReadyCallback) is pending, the pump holds a libuv ref so a plain Node
 // script survives until the completion dispatches (the top-level-await case).
-// Begin returns whether the callback was counted (only on the pump-owning env,
-// i.e. Node's main env after startMainLoop); the caller must call End exactly
+// The counter itself is runtime-independent (Bun/Deno's portable pump reads it
+// via MainContextHasPending); only the libuv ref is Node-only. Begin returns
+// whether the callback was counted (false only for a foreign env, i.e. a worker
+// thread once Node's main env owns the pump); the caller must call End exactly
 // once for each counted callback. Main-thread only.
 bool NodeGiPumpAsyncBegin(napi_env env);
 void NodeGiPumpAsyncEnd();

package/src/loop.cc

@@ -108,8 +108,14 @@ static void DrainMicrotasks() {
 //
 // Portable fix: N-API exposes no engine microtask checkpoint, but both runtimes
 // expose their OWN drain primitive to JS (Bun: `bun:jsc` drainMicrotasks —
-// JSC's VM drain, callable mid-stack by design; Deno: core.runMicrotasks →
-// Isolate::PerformMicrotaskCheckpoint via a reentrant op). index.js registers
+// JSC's VM drain, callable mid-stack by design, and Bun's process.nextTick
+// rides that same queue; Deno: core.runNextTicks — node's task_queues.js
+// runNextTicks shape, draining the node-compat process.nextTick queue AND the
+// V8 microtask checkpoint. core.runMicrotasks alone is NOT enough on Deno:
+// its nextTick queue is separate from V8's microtasks, and node:stream's
+// 'end' is nextTick-delivered (endReadableNT), so a microtask-only drain hung
+// every fetch/XHR body consumption at readyState 3 during a blocking run —
+// see test/blocking-run-checkpoint.test.mjs). index.js registers
 // it here on non-Node runtimes only; the loop-dispatched trampolines
 // (signals.cc / calls.cc / class.cc) invoke NodeGiMaybeDrainMicrotasks at their
 // OUTERMOST boundary (g_loopDispatchDepth == 0). Node never registers — its
@@ -544,14 +550,31 @@ static void PumpArmWakeups() {
     if (g_pump_async_pending > 0 && (timeout < 0 || timeout > 32)) timeout = 32;
   }
 
+  // WAKE-UP and HOLD are separate decisions.
+  //
+  // Wake-up: whenever GLib has a deadline, arm the mirrored uv timer for it, so
+  // libuv's poll sleep ends exactly when GLib next has work.
+  //
+  // Hold (uv_ref): ONLY while JS-armed GLib work is outstanding — the
+  // scope=async/notified counter. Ref'ing whenever a deadline exists (what this
+  // used to do) makes any C-armed toolkit timer immortalize the process: GDK
+  // keeps a ~1 s repeating timeout armed for the process's whole life, so
+  // `node --test test/gtk-smoke.test.mjs` never exited once the GTK stack had
+  // been initialized. `gjs -m` exits when the module settles regardless of what
+  // GLib still has scheduled; keying the hold on the program's OWN outstanding
+  // GLib work is as close to that as a libuv-driven process can get, and it is
+  // what keeps a top-level `await` on a GLib timeout alive (the timeout's
+  // GSourceFunc is a scope=notified callback, counted until GLib drops it).
   if (timeout >= 0) {
     uv_timer_start(&g_pump_timer, PumpTimerCb, static_cast<uint64_t>(timeout), 0);
-    if (!g_pump_timer_reffed) {
-      uv_ref(reinterpret_cast<uv_handle_t*>(&g_pump_timer));
-      g_pump_timer_reffed = TRUE;
-    }
-  } else if (g_pump_timer_reffed) {
+  } else {
     uv_timer_stop(&g_pump_timer);
+  }
+  const gboolean hold = g_pump_async_pending > 0 && timeout >= 0;
+  if (hold && !g_pump_timer_reffed) {
+    uv_ref(reinterpret_cast<uv_handle_t*>(&g_pump_timer));
+    g_pump_timer_reffed = TRUE;
+  } else if (!hold && g_pump_timer_reffed) {
     uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_timer));
     g_pump_timer_reffed = FALSE;
   }
@@ -626,15 +649,72 @@ static void PumpInit(uv_loop_t* loop) {
   g_pump_inited = TRUE;
 }
 
+// mainContextHasPending() -> boolean
+//
+// Is there JS-armed GLib work a *pumping* runtime must stay alive for? True
+// while a GI callback the program handed to GLib is outstanding — a scope=async
+// completion (a GAsyncReadyCallback) or a scope=notified source
+// (`GLib.timeout_add`/`idle_add`), counted in calls.cc and released when GLib
+// drops it. The query half of the keep-alive contract for the Bun/Deno pump
+// (L1 `startMainContextPump`); Node reads the same counter inline in
+// PumpArmWakeups and never calls this.
+//
+// It deliberately does NOT ask whether the context has any scheduled source.
+// That probe (`g_main_context_prepare` + `_query`, timeout >= 0) reports the
+// timers a TOOLKIT arms in C as well, and GDK keeps a ~1 s repeating timeout
+// armed for the process's whole life: a finished GTK program then answers
+// "pending" forever while nothing is ever ready to dispatch, and never exits.
+// `gjs -m` would not stay alive for those either — it exits once the module
+// settles. A `false` answer is also what lets a sync-only program exit
+// immediately: the pump alone must never keep a finished program alive.
+Napi::Value MainContextHasPending(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  return Napi::Boolean::New(env, g_pump_async_pending > 0);
+}
+
+// makePumpPendingCount() -> Int32Array(1) OVER g_pump_async_pending (external,
+// zero copy). The JS pump's beat reads this view instead of calling
+// MainContextHasPending(): on Deno, merely ENTERING the addon from the pump's
+// timer tick during the between-test-files GC window reproduces the #47
+// boxed-handle teardown SIGSEGV — measured on the gtk-smoke leg, a query-only
+// tick (one napi call, no dispatch) crashed 3/3 while a tick that never touches
+// the addon exited 0. A typed-array read is a plain JS memory access, so the
+// beat's idle path stays native-silent. No atomics: the counter is written only
+// from the JS thread (Begin/End are main-thread only) and read from JS.
+//
+// A FACTORY, deliberately not created at addon Init: the @gjsify/napi shim
+// (the gjs-napi conformance oracle runs node-gi under it) loud-stubs
+// napi_create_external_arraybuffer, and the gjs host never arms the portable
+// pump — L1 calls this lazily on the first Bun/Deno pump arm, so the stub is
+// never reached where the view is never needed.
+Napi::Value MakePumpPendingCount(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  static_assert(sizeof(g_pump_async_pending) == sizeof(int32_t),
+                "the JS Int32Array view requires a 32-bit counter");
+  // External buffer over static storage — no finalizer needed, the counter
+  // outlives every env.
+  Napi::ArrayBuffer buf =
+      Napi::ArrayBuffer::New(env, &g_pump_async_pending, sizeof(g_pump_async_pending));
+  return Napi::TypedArrayOf<int32_t>::New(env, 1, buf, 0, napi_int32_array);
+}
+
 // In-flight scope=async keep-alive: while any GI scope=async callback (a
 // GAsyncReadyCallback) is pending, REF the (always-active) prepare handle so the
 // libuv loop stays alive until the completion arrives — the exact analogue of
 // Node's own in-flight I/O keeping the process alive, and the reason a plain
 // top-level `await` on a Gio async op settles instead of exiting with an
-// unsettled-TLA error. Main-thread only; counted only for the pump-owning env.
+// unsettled-TLA error.
+//
+// The COUNTER is maintained on every runtime, not just Node: it is the
+// "in-flight async work" half of the keep-alive contract, and Bun/Deno's
+// portable pump reads it through MainContextHasPending() to decide whether its
+// timer holds the runtime's event loop open. Only the uv ref/unref half is
+// Node-only (it needs the uv handles the uv pump owns). Main-thread only —
+// where a pump env is known (Node), a foreign env is not counted.
 bool NodeGiPumpAsyncBegin(napi_env env) {
-  if (!g_pump_inited || env != g_loop_env) return false;
-  if (++g_pump_async_pending == 1 && !g_pump_prepare_reffed) {
+  if (g_loop_env != nullptr && env != g_loop_env) return false;
+  ++g_pump_async_pending;
+  if (g_pump_inited && g_pump_async_pending == 1 && !g_pump_prepare_reffed) {
     uv_ref(reinterpret_cast<uv_handle_t*>(&g_pump_prepare));
     g_pump_prepare_reffed = TRUE;
   }
@@ -642,8 +722,9 @@ bool NodeGiPumpAsyncBegin(napi_env env) {
 }
 
 void NodeGiPumpAsyncEnd() {
-  if (!g_pump_inited || g_pump_async_pending == 0) return;
-  if (--g_pump_async_pending == 0 && g_pump_prepare_reffed) {
+  if (g_pump_async_pending == 0) return;
+  --g_pump_async_pending;
+  if (g_pump_inited && g_pump_async_pending == 0 && g_pump_prepare_reffed) {
     uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_prepare));
     g_pump_prepare_reffed = FALSE;
   }

package/src/marshal.cc

@@ -3,6 +3,7 @@
 
 #include "common.h"
 
+#include <cmath>
 #include <unordered_map>
 #include <utility>
 
@@ -190,6 +191,101 @@ gpointer TransferBoxedIn(BoxedHandle* h, GITransfer transfer) {
   return h->ptr;
 }
 
+// Whether `v` is a boxed handle that ALREADY holds a GValue — the one shape a
+// `GObject.Value` IN-arg takes as-is (gjs GValueIn::in passes it through when the
+// JS object's own gtype is G_TYPE_VALUE, and boxes EVERYTHING else, including
+// other boxed handles: a GVariant handed to `set_property('state', …)` becomes a
+// G_TYPE_VARIANT GValue, it does not become the GValue).
+static bool NodeGiIsGValueHandle(Napi::Value v) {
+  BoxedHandle* h = TryGetBoxedHandle(v);
+  return h != nullptr && h->gtype != G_TYPE_INVALID && g_type_is_a(h->gtype, G_TYPE_VALUE);
+}
+
+// Initialise `out` from a plain JS value, guessing the GType the way gjs does
+// for an uninitialized GValue (refs/gjs/gi/value.cpp gjs_value_guess_g_type +
+// gjs_value_to_g_value_internal). Returns false with a pending JS exception when
+// the value has no sensible GValue representation.
+//
+// The int32-vs-double split matches gjs exactly (`value.isInt32()` →
+// `G_TYPE_INT`, `value.isDouble()` → `G_TYPE_DOUBLE`); JS has no such tag at the
+// N-API boundary, so an integral number in int32 range stands in for isInt32.
+// That distinction is not load-bearing for correctness — `g_object_set_property`
+// transforms between the numeric fundamentals — but staying bit-for-bit with gjs
+// keeps a property that reads the GValue's own type behaving identically.
+static bool JsToFreshGValue(Napi::Env env, Napi::Value v, GValue* out) {
+  if (v.IsNull() || v.IsUndefined()) {
+    // gjs guesses G_TYPE_POINTER for null. A real GValue holding NULL is also
+    // the only thing a callee can safely dereference — passing a NULL GValue*
+    // (the plain boxed-null path) would crash g_object_set_property.
+    g_value_init(out, G_TYPE_POINTER);
+    g_value_set_pointer(out, nullptr);
+    return true;
+  }
+  if (v.IsBoolean()) {
+    g_value_init(out, G_TYPE_BOOLEAN);
+    g_value_set_boolean(out, v.As<Napi::Boolean>().Value() ? TRUE : FALSE);
+    return true;
+  }
+  if (v.IsString()) {
+    g_value_init(out, G_TYPE_STRING);
+    g_value_set_string(out, v.As<Napi::String>().Utf8Value().c_str());
+    return true;
+  }
+  if (v.IsBigInt()) {
+    bool lossless = false;
+    int64_t i64 = v.As<Napi::BigInt>().Int64Value(&lossless);
+    if (lossless || i64 < 0) {
+      g_value_init(out, G_TYPE_INT64);
+      g_value_set_int64(out, i64);
+    } else {
+      bool ulossless = false;
+      g_value_init(out, G_TYPE_UINT64);
+      g_value_set_uint64(out, v.As<Napi::BigInt>().Uint64Value(&ulossless));
+    }
+    return true;
+  }
+  if (v.IsNumber()) {
+    double d = v.As<Napi::Number>().DoubleValue();
+    if (d == std::trunc(d) && d >= static_cast<double>(G_MININT32) &&
+        d <= static_cast<double>(G_MAXINT32)) {
+      g_value_init(out, G_TYPE_INT);
+      g_value_set_int(out, static_cast<gint>(d));
+    } else {
+      g_value_init(out, G_TYPE_DOUBLE);
+      g_value_set_double(out, d);
+    }
+    return true;
+  }
+  if (v.IsExternal()) {
+    // A GObject handle → a G_TYPE_OBJECT GValue carrying its own GType, so a
+    // property typed against a subclass still accepts it.
+    Napi::External<GObject> objExt = v.As<Napi::External<GObject>>();
+    if (objExt.CheckTypeTag(&kGObjectHandleTag)) {
+      GObject* obj = objExt.Data();
+      GType gt = obj != nullptr ? G_OBJECT_TYPE(obj) : G_TYPE_OBJECT;
+      g_value_init(out, gt);
+      g_value_set_object(out, obj);
+      return true;
+    }
+    // A boxed handle → its own registered GType (GVariant has its own
+    // fundamental; a non-registered C struct has no GType to name and is
+    // rejected rather than guessed at).
+    BoxedHandle* h = TryGetBoxedHandle(v);
+    if (h != nullptr && h->gtype != G_TYPE_INVALID) {
+      g_value_init(out, h->gtype);
+      if (h->gtype == G_TYPE_VARIANT) g_value_set_variant(out, static_cast<GVariant*>(h->ptr));
+      else if (G_TYPE_IS_BOXED(h->gtype)) g_value_set_boxed(out, h->ptr);
+      else g_value_set_pointer(out, h->ptr);
+      return true;
+    }
+  }
+  Napi::TypeError::New(
+      env, "Cannot convert this value to a GObject.Value (expected a boolean, number, bigint, "
+           "string, null, or a GObject/boxed handle)")
+      .ThrowAsJavaScriptException();
+  return false;
+}
+
 // Read a boxed handle's pointer if `v` is one (tag-checked; no deref of ptr).
 bool TryGetBoxedPtr(Napi::Value v, gpointer* out) {
   if (!v.IsExternal()) return false;
@@ -337,7 +433,8 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
                     GITransfer transfer,
                     std::vector<gpointer>* ownedStrings,
                     CreatedClosures* closures,
-                    CreatedBytes* bytes) {
+                    CreatedBytes* bytes,
+                    CreatedValues* values) {
   if (v.IsEmpty()) {
     // Residue of a swallowed napi failure (a fallible Get()/coercion upstream
     // failed on a terminating env, or a throwing getter left the exception
@@ -399,7 +496,31 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
             out->v_pointer = nullptr;
             handled = true;
           } else if (v.IsExternal()) {
-            out->v_pointer = v.As<Napi::External<GObject>>().Data();
+            GObject* obj = v.As<Napi::External<GObject>>().Data();
+            // A (transfer full) GObject IN arg CONSUMES a reference: the callee
+            // takes over the one it is handed. Passing the handle's own ref
+            // makes the callee and the JS wrapper share a single ref that BOTH
+            // release — the wrapper's finalize then frees an object the callee
+            // still owns, and the callee is left dereferencing freed memory.
+            //
+            // `gtk_widget_add_controller()` is the canonical case and the one
+            // that surfaced it: GTK keeps the controller in the widget's list,
+            // the JS wrapper for it goes out of scope, and the next pointer
+            // motion over the widget hits
+            //
+            //   Gtk-CRITICAL **: gtk_event_controller_handle_crossing:
+            //   assertion 'GTK_IS_EVENT_CONTROLLER (controller)' failed
+            //
+            // NONDETERMINISTICALLY — it needs a GC between the add and the
+            // event, which is why it looked unrelated to anything nearby.
+            //
+            // gjs takes the ref here (wrapperutils.h
+            // `transfer_to_gi_argument`: `GI_DIRECTION_IN && transfer !=
+            // GI_TRANSFER_NOTHING` → `copy_ptr` → `g_object_ref`), and this
+            // file already does the equivalent for BOXED args via
+            // `TransferBoxedIn`. Objects were simply never given the same rule.
+            if (transfer != GI_TRANSFER_NOTHING && obj != nullptr) g_object_ref(obj);
+            out->v_pointer = obj;
             handled = true;
           }
         } else if (GI_IS_ENUM_INFO(iface) || GI_IS_FLAGS_INFO(iface)) {
@@ -454,6 +575,29 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
             if (transfer == GI_TRANSFER_NOTHING) bytes->transferNone.push_back(b);
             else bytes->transferFull.push_back(b);
             handled = true;
+          } else if (values != nullptr && !NodeGiIsGValueHandle(v) &&
+                     gi_registered_type_info_get_g_type(
+                         reinterpret_cast<GIRegisteredTypeInfo*>(iface)) == G_TYPE_VALUE) {
+            // A plain JS value for a `GObject.Value` IN-arg → a fresh GValue whose
+            // GType is guessed from the value, exactly as gjs (refs/gjs
+            // gi/arg-cache.cpp GValueIn::in → gjs_value_to_g_value). This is what
+            // makes `obj.set_property('volume', 0.5)` — whose GI signature takes a
+            // GValue — work at all; a JS number is not a boxed handle, so it used
+            // to fall through to the "Unsupported interface IN argument" throw.
+            //
+            // An EXISTING GObject.Value handle is excluded here and routes through
+            // the boxed-handle branch below untouched, matching gjs's pass-through
+            // for an already-typed GValue.
+            GValue* boxed = g_new0(GValue, 1);
+            if (!JsToFreshGValue(env, v, boxed)) {
+              g_free(boxed);
+              gi_base_info_unref(iface);
+              return false;  // JsToFreshGValue already threw
+            }
+            out->v_pointer = boxed;
+            if (transfer == GI_TRANSFER_NOTHING) values->transferNone.push_back(boxed);
+            else values->transferFull.push_back(boxed);
+            handled = true;
           } else if (v.IsNull() || v.IsUndefined()) {
             // Boxed/struct IN args arrive as boxed handles; null/undefined maps to
             // a NULL pointer (e.g. GLib.MainLoop.new(null, false)).