node-gtk 2.0.0 → 2.2.0

package/README.md

@@ -10,24 +10,31 @@
 
 <h1 align="center">node-gtk</h1>
 <p align="center">
-  <b>GNOME Gtk+ bindings for NodeJS</b>
+  <b>GTK bindings for NodeJS</b>
   <br/>
   <img src="https://img.shields.io/npm/v/node-gtk" alt="Package Version" />
 </p>
 
-Node-Gtk is a [gobject-introspection](https://gi.readthedocs.io/en/latest) library for nodejs. It makes it possible to
-use any introspected library, such as Gtk+, usable. It is similar in essence to [GJS](https://wiki.gnome.org/action/show/Projects/Gjs) or [PyGObject](https://pygobject.readthedocs.io). Please note this project is currently in a _beta_ state and is being developed. Any contributors willing to help
-will be welcomed.
+`node-gtk` is a [gobject-introspection](https://gi.readthedocs.io/en/latest) library 
+for nodejs. It makes it possible to use any introspected C library, such as GTK, 
+usable. It is similar in essence to [GJS](https://wiki.gnome.org/action/show/Projects/Gjs) 
+or [PyGObject](https://pygobject.readthedocs.io). Please note this project is 
+currently in a _alpha_ state.
 
 Supported Node.js versions: **20**, **22**, **24** (other versions may work but are untested)<br>
-Pre-built binaries available for: **Linux**, **macOS**
+Supported platforms:
+- **Linux** — prebuilt binaries available
+- **macOS** — prebuilt binaries available
+- **Windows** — prebuilt binaries available (but read [Windows](#windows))
+
 
 ### Table of contents
 
 - [Usage](#usage)
+- [ES modules](#es-modules)
 - [Documentation](#documentation)
 - [TypeScript](#typescript)
-- [Installing and building](#installing-and-building)
+- [Installing](#installing)
 - [Contributing](#contributing)
 
 ## Usage
@@ -80,9 +87,28 @@ You can also easily create custom applications:
   <img src="./img/system-monitor.png" style="width: 400px; height: auto;"/>
 </p>
 
-#### Other projects
+## ES modules
+
+The Usage example above is CommonJS. node-gtk also works under ESM, but the
+blocking main-loop calls (`GLib.MainLoop.run`, `Gio`/`Gtk.Application.run`,
+`Gtk.main`) **return immediately** instead of blocking and **don't return a
+value** — so make the run call the last statement and exit from your handler:
 
-The [react-gtk](https://github.com/codejamninja/react-gtk) project may also allow you to use GTK via React (unmaintained).
+```javascript
+app.on('activate', () => {
+  // ...build the window...
+  window.on('close-request', () => (loop.quit(), app.quit(), false));
+  window.present();
+
+  gi.startLoop();
+  loop.run();      // returns immediately under ESM; do cleanup/exit in the handler
+});
+
+app.run([]);       // not `process.exit(app.run([]))` — the return value is unavailable
+```
+
+CommonJS (and signal callbacks) are unaffected. For the why and the design
+trade-off, see [#449](https://github.com/romgrk/node-gtk/issues/449).
 
 ## Documentation
 
@@ -140,9 +166,44 @@ script so it regenerates on install:
 
 Run `npx node-gtk generate-types --help` for options.
 
-## Installing and building
+## Installing
+
+1. Install `node-gtk` itself
+2. Install the native libraries you use (see examples per platform below)
+
+```sh
+npm install node-gtk
+
+# This installs a prebuilt binary when one is available for your platform and
+# Node.js version, otherwise it falls back to building from source.
+```
+
+#### Linux
+
+```sh
+# archlinux
+pacman -S gtk4
+
+# ubuntu
+apt install libgtk-4-1
+```
 
-See [Installing & building](./doc/installation.md) for prebuilt-binary notes, per-platform build instructions (Linux, macOS, Windows), and how to run the tests and examples.
+#### macOS
+
+```sh
+brew install gtk4
+```
+
+#### Windows
+
+Windows doesn't have the dependencies we need in a package manager, therefore 
+`node-gtk` ships prebuilt versions of GTK 4 / Adwaita runtime (DLLs, typelibs, 
+icons), so `npm install node-gtk` is all you need **if** your dependency is in 
+our [list of prebuilt libraries](./windows/runtime-libraries.txt).
+
+### build from source
+
+Building from source, or contributing? See [Building from source](./doc/building.md).
 
 ## Contributing
 
@@ -153,6 +214,3 @@ for LSP to work nicely, you can use [bear](https://github.com/rizsotto/Bear) as
 - https://developer.gnome.org/gi/stable/index.html
 - https://v8docs.nodesource.com/
 - https://github.com/nodejs/nan#api
-
-There is a [Discord channel](https://discord.gg/r2VqPUV) but it receives little monitoring, use github issues or
-discussions preferably.

package/lib/loop.js

@@ -6,6 +6,7 @@ const internal = require('./native.js')
 
 module.exports = {
   start,
+  runLoopEntry,
 }
 
 
@@ -32,6 +33,39 @@ function start() {
 }
 
 
+/**
+ * Runs a blocking main-loop entry point (e.g. GLib.MainLoop.run,
+ * Gio.Application.run, Gtk.main) so that Promise/async continuations keep
+ * draining while it blocks.
+ *
+ * Under ES modules the top-level body executes as a V8 microtask, so a blocking
+ * call made directly from it nests inside V8's microtask drain. V8 refuses
+ * nested microtask checkpoints, so any pending Promise/async continuation is
+ * starved for the entire lifetime of the loop. Deferring the blocking call to a
+ * macrotask lets the module's top-level microtask return first, so the queue
+ * drains and the loop integration takes over from a clean (non-nested) state.
+ *
+ * Under CommonJS (and inside signal callbacks) we are not in a microtask, so we
+ * run synchronously and preserve the original blocking semantics exactly.
+ *
+ * https://github.com/romgrk/node-gtk/issues/442
+ *
+ * Returns the native call's result when run synchronously (so e.g.
+ * `const status = app.run()` keeps working under CommonJS); returns undefined
+ * when deferred, since the result is not yet available.
+ *
+ * @param {Function} run - performs the blocking native call
+ * @returns {*} the native return value, or undefined when deferred
+ */
+function runLoopEntry(run) {
+  if (internal.IsRunningMicrotasks()) {
+    setImmediate(run)
+    return undefined
+  }
+  return run()
+}
+
+
 // Helpers
 
 function wrappedLoopFunction(fn) {

package/lib/native.js

@@ -4,10 +4,61 @@
 
 const binary = require('@mapbox/node-pre-gyp')
 const path = require('path')
+const fs = require('fs')
 
 const packagePath = path.resolve(path.join(__dirname,'../package.json'))
 const bindingPath = binary.find(packagePath)
 
+// On Windows, the prebuilt binary ships with its whole GTK runtime bundled in
+// the same directory as the .node (DLLs, GObject-Introspection typelibs, and
+// runtime data). Wire the process environment to that bundle BEFORE the addon
+// is loaded, so a plain `npm install node-gtk` works with no MSYS2, no compiler
+// and no manual PATH setup. Done in this file specifically because it must run
+// before `require(bindingPath)` (the addon's DLL imports are resolved at load
+// time) and before bootstrap.js requires the GIRepository typelib.
+if (process.platform === 'win32')
+  setupBundledRuntime(path.dirname(bindingPath))
+
+function setupBundledRuntime(bundleDir) {
+  // A self-contained prebuilt always bundles its typelibs; if that marker is
+  // absent the addon was built from source against a system GTK, so leave the
+  // environment alone.
+  const typelibDir = path.join(bundleDir, 'girepository-1.0')
+  if (!fs.existsSync(typelibDir))
+    return
+
+  const prepend = (name, value) => {
+    const cur = process.env[name]
+    process.env[name] = cur ? value + path.delimiter + cur : value
+  }
+  const exists = p => { try { return fs.existsSync(p) } catch (e) { return false } }
+
+  // 1) DLLs — both the addon's own imports and the namespace shared libraries
+  //    GObject-Introspection loads at runtime via g_module_open().
+  prepend('PATH', bundleDir)
+
+  // 2) GI typelibs.
+  prepend('GI_TYPELIB_PATH', typelibDir)
+
+  // 3) Runtime data: icon themes, GtkSourceView languages/styles, schemas.
+  const share = path.join(bundleDir, 'share')
+  if (exists(share))
+    prepend('XDG_DATA_DIRS', share)
+  const schemas = path.join(share, 'glib-2.0', 'schemas')
+  if (exists(schemas) && !process.env.GSETTINGS_SCHEMA_DIR)
+    process.env.GSETTINGS_SCHEMA_DIR = schemas
+
+  // 4) gdk-pixbuf image loaders (made path-portable at bundle time). The
+  //    loaders dir goes on PATH so g_module_open() of a bare loader name from
+  //    the cache resolves.
+  const loadersDir = path.join(bundleDir, 'lib', 'gdk-pixbuf-2.0', '2.10.0', 'loaders')
+  if (exists(loadersDir))
+    prepend('PATH', loadersDir)
+  const loaderCache = path.join(bundleDir, 'lib', 'gdk-pixbuf-2.0', '2.10.0', 'loaders.cache')
+  if (exists(loaderCache) && !process.env.GDK_PIXBUF_MODULE_FILE)
+    process.env.GDK_PIXBUF_MODULE_FILE = loaderCache
+}
+
 const binding = require(bindingPath)
 
 module.exports = binding

package/lib/overrides/GLib-2.0.js

@@ -3,6 +3,7 @@
  */
 
 const internal = require('../native.js')
+const { runLoopEntry } = require('../loop.js')
 
 exports.apply = (GLib) => {
 
@@ -10,17 +11,19 @@ exports.apply = (GLib) => {
     GLib.MainLoop.prototype._quit = GLib.MainLoop.prototype.quit
 
     GLib.MainLoop.prototype.run = function run() {
-        /* Run before we enter the loop otherwise pending microtasks
-         * are not run */
-        process._tickCallback()
-
         const loopStack = internal.GetLoopStack()
-
         loopStack.push(() => this.quit())
-        this._run()
-        if (this._userQuit)
-            loopStack.pop()
-        delete this._userQuit
+
+        return runLoopEntry(() => {
+            /* Run before we enter the loop otherwise pending microtasks
+             * are not run */
+            process._tickCallback()
+
+            this._run()
+            if (this._userQuit)
+                loopStack.pop()
+            delete this._userQuit
+        })
     }
     GLib.MainLoop.prototype.quit = function quit() {
         this._userQuit = true

package/lib/overrides/Gio-2.0.js

@@ -0,0 +1,26 @@
+/*
+ * Gio-2.0.js
+ */
+
+const { runLoopEntry } = require('../loop.js')
+
+exports.apply = (Gio) => {
+
+    Gio.Application.prototype._run = Gio.Application.prototype.run
+
+    /* g_application_run() blocks until the application quits. Under ES modules
+     * this would starve Promise/async continuations; runLoopEntry() defers the
+     * blocking call when needed so they keep draining. See loop.js / #442.
+     *
+     * Note: when deferred (ESM), the exit status is not available synchronously,
+     * so `app.run()` returns undefined instead of the status code in that case. */
+    Gio.Application.prototype.run = function run(...args) {
+        return runLoopEntry(() => {
+            /* Run before we enter the loop otherwise pending microtasks
+             * are not run */
+            process._tickCallback()
+
+            return this._run(...args)
+        })
+    }
+}

package/lib/overrides/Gtk-3.0.js

@@ -3,6 +3,7 @@
  */
 
 const internal = require('../native.js')
+const { runLoopEntry } = require('../loop.js')
 
 /**
  * @typedef {Object} Dimension
@@ -27,10 +28,6 @@ exports.apply = (Gtk) => {
     let userCallingQuit = false
 
     Gtk.main = function main() {
-        /* Run before we enter the loop otherwise pending microtasks
-         * are not run */
-        process._tickCallback()
-
         const loopStack = internal.GetLoopStack()
 
         /*
@@ -42,17 +39,25 @@ exports.apply = (Gtk) => {
 
         loopStack.push(originalQuit)
 
-        originalMain()
+        /* runLoopEntry() defers the blocking call under ES modules so pending
+         * Promise/async continuations keep draining. See loop.js / #442. */
+        return runLoopEntry(() => {
+            /* Run before we enter the loop otherwise pending microtasks
+             * are not run */
+            process._tickCallback()
 
-        if (userCallingQuit) {
-          loopStack.pop()
-        }
+            originalMain()
 
-        userCallingQuit = false
+            if (userCallingQuit) {
+              loopStack.pop()
+            }
 
-        if (Gtk.mainLevel() === 0) {
-          placeholderIntervalID = clearInterval(placeholderIntervalID)
-        }
+            userCallingQuit = false
+
+            if (Gtk.mainLevel() === 0) {
+              placeholderIntervalID = clearInterval(placeholderIntervalID)
+            }
+        })
     }
 
     Gtk.mainQuit = function mainQuit() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-gtk",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "GNOME Gtk+ bindings for NodeJS",
   "main": "lib/index.js",
   "bin": {

package/scripts/windows-bundle-runtime.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+#
+# windows-bundle-runtime.sh
+#
+# Make a freshly-built Windows prebuilt self-contained so it can be used WITHOUT
+# MSYS2/MinGW or any compiler on the target machine. We copy the addon's entire
+# transitive MinGW DLL closure next to the .node, plus the GObject-Introspection
+# typelibs and runtime data it needs at runtime.
+#
+# The set of bundled libraries is driven by the curated seed list
+# windows/runtime-libraries.txt (also a user-facing reference). The exact
+# resolved DLL set is written to <binding-dir>/bundled-dlls.txt.
+#
+# Run inside the MINGW64 shell, after building.
+#
+#   ./scripts/windows-bundle-runtime.sh lib/binding/node-v127-win32-x64
+#
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+
+BINDING_DIR="${1:?usage: windows-bundle-runtime.sh <binding-dir> [runtime-libraries.txt]}"
+# The curated seed list lives in a text file so it doubles as user-facing
+# reference (windows/runtime-libraries.txt). Override with $2 if needed.
+LIBS_FILE="${2:-$SCRIPT_DIR/../windows/runtime-libraries.txt}"
+# MinGW bin dir the seed names resolve against.
+MB="${MINGW_BIN:-/mingw64/bin}"
+
+NODE_FILE="$BINDING_DIR/node_gtk.node"
+
+if [ ! -f "$NODE_FILE" ]; then
+  echo "error: $NODE_FILE not found"
+  ls -la "$BINDING_DIR" || true
+  exit 1
+fi
+if [ ! -f "$LIBS_FILE" ]; then
+  echo "error: seed list $LIBS_FILE not found"
+  exit 1
+fi
+
+# GObject-Introspection loads each namespace's shared library at runtime via
+# g_module_open() when you call gi.require('Gtk', ...). Those libraries
+# (libgio, libgtk, libgdk, libpango, libgdk_pixbuf, ...) are NOT linked by
+# node_gtk.node, so ntldd on the addon alone misses them. We therefore seed the
+# closure from the addon AND from the GTK runtime libraries listed in LIBS_FILE.
+echo "## Seed libraries from $LIBS_FILE"
+ENTRY_LIBS=("$NODE_FILE")
+while IFS= read -r line; do
+  # strip comments and surrounding whitespace; skip blanks
+  name="${line%%#*}"
+  name="$(echo "$name" | tr -d '[:space:]')"
+  [ -z "$name" ] && continue
+  if [ -f "$MB/$name" ]; then
+    ENTRY_LIBS+=("$MB/$name")
+    echo "  - $name"
+  else
+    echo "  (skip missing seed $name)"
+  fi
+done < "$LIBS_FILE"
+
+echo "## Computing recursive DLL closure for the addon + GTK runtime"
+# ntldd -R prints every transitive dependency with its resolved Windows path:
+#   libgtk-3-0.dll => C:\msys64\mingw64\bin\libgtk-3-0.dll (0x...)
+# Collect the union of every entry's closure, keep only MinGW-provided DLLs
+# (skip C:\Windows\System32 OS DLLs), and copy them next to the .node.
+: > /tmp/dll-closure.txt
+for lib in "${ENTRY_LIBS[@]}"; do
+  [ -f "$lib" ] || { echo "  (skip missing entry $lib)"; continue; }
+  # the entry library itself (when it is one of the GTK runtime DLLs)
+  case "$lib" in *mingw64*) echo "$lib" >> /tmp/dll-closure.txt ;; esac
+  ntldd -R "$lib" \
+    | sed -n 's/.* => \(.*\) (0x.*/\1/p' \
+    | while IFS= read -r winpath; do
+        [ -z "$winpath" ] && continue
+        u=$(cygpath -u "$winpath" 2>/dev/null || echo "$winpath")
+        case "$u" in *mingw64*) echo "$u" >> /tmp/dll-closure.txt ;; esac
+      done
+done
+
+copied=0
+sort -u /tmp/dll-closure.txt | while IFS= read -r u; do
+  if [ -f "$u" ]; then
+    cp -f "$u" "$BINDING_DIR/"
+    echo "  + $(basename "$u")"
+    copied=$((copied + 1))
+  fi
+done
+DLL_COUNT=$(ls "$BINDING_DIR"/*.dll 2>/dev/null | wc -l | tr -d ' ')
+echo "## DLLs bundled into $BINDING_DIR ($DLL_COUNT total)"
+
+# Write the exact set that shipped, as a reference manifest (ships in the
+# bundle and the artifact). Generated from the curated seed list above.
+MANIFEST="$BINDING_DIR/bundled-dlls.txt"
+{
+  echo "# bundled-dlls.txt — Windows DLLs shipped with this node-gtk prebuilt."
+  echo "# GENERATED by scripts/windows-bundle-runtime.sh; do not edit by hand."
+  echo "# Edit the curated seed list windows/runtime-libraries.txt instead."
+  echo "# $DLL_COUNT DLLs, expanded from the seed list via 'ntldd -R'."
+  echo "#"
+  ( cd "$BINDING_DIR" && ls -1 *.dll 2>/dev/null | sort )
+} > "$MANIFEST"
+echo "## Wrote manifest $MANIFEST"
+
+echo "## Bundling GObject-Introspection typelibs"
+TYPELIB_SRC=$(pkg-config --variable=typelibdir gobject-introspection-1.0 2>/dev/null || true)
+if [ -z "$TYPELIB_SRC" ] || [ ! -d "$TYPELIB_SRC" ]; then
+  TYPELIB_SRC=/mingw64/lib/girepository-1.0
+fi
+TYPELIB_DST="$BINDING_DIR/girepository-1.0"
+mkdir -p "$TYPELIB_DST"
+# Copy the full typelib set; it is small and guarantees every transitive
+# namespace dependency (Gdk, Pango, cairo, GdkPixbuf, Graphene, ...) is present.
+cp -f "$TYPELIB_SRC"/*.typelib "$TYPELIB_DST/"
+echo "## Typelibs bundled from $TYPELIB_SRC -> $TYPELIB_DST"
+
+# ---------------------------------------------------------------------------
+# Runtime DATA a real GTK4/Adwaita app needs at run time (beyond DLLs/typelibs).
+# These are copied so we can MEASURE the realistic bundle size and ship a
+# self-contained app. cp is best-effort: a missing source is not fatal.
+# ---------------------------------------------------------------------------
+copy_tree() { # src dst
+  if [ -d "$1" ]; then mkdir -p "$2"; cp -rf "$1"/. "$2"/ 2>/dev/null || true; fi
+}
+
+echo "## Bundling runtime data (loaders, schemas, icons, gtksourceview)"
+# gdk-pixbuf image loaders (PNG/SVG/... — needed for icons/images)
+copy_tree /mingw64/lib/gdk-pixbuf-2.0 "$BINDING_DIR/lib/gdk-pixbuf-2.0"
+# compiled GSettings schemas (GTK4/Adw/GtkSourceView read settings)
+copy_tree /mingw64/share/glib-2.0/schemas "$BINDING_DIR/share/glib-2.0/schemas"
+# icon themes (Adwaita + hicolor fallback) — typically the biggest chunk
+copy_tree /mingw64/share/icons/Adwaita "$BINDING_DIR/share/icons/Adwaita"
+copy_tree /mingw64/share/icons/hicolor "$BINDING_DIR/share/icons/hicolor"
+# GtkSourceView language definitions + style schemes
+copy_tree /mingw64/share/gtksourceview-5 "$BINDING_DIR/share/gtksourceview-5"
+
+# Make the gdk-pixbuf loaders cache path-portable: the build machine bakes in
+# absolute paths to each loader DLL, which don't exist on the user's machine.
+# Rewrite each loader path to its bare file name; lib/native.js puts the loaders
+# dir on PATH so g_module_open() resolves the bare name at run time.
+LOADER_CACHE="$BINDING_DIR/lib/gdk-pixbuf-2.0/2.10.0/loaders.cache"
+if [ -f "$LOADER_CACHE" ]; then
+  sed -i -E 's#^"[^"]*[\\/]([^"\\/]+\.dll)"#"\1"#' "$LOADER_CACHE"
+  echo "## Rewrote $LOADER_CACHE to portable (bare) loader names"
+fi
+
+echo
+echo "## ===== SIZE BREAKDOWN ====="
+size() { # label dir-or-glob
+  local label="$1"; shift
+  local total
+  total=$(du -ch "$@" 2>/dev/null | tail -1 | cut -f1)
+  printf '  %-26s %s\n' "$label" "${total:-0}"
+}
+size "DLLs (load-critical)"        "$BINDING_DIR"/*.dll
+size "typelibs (load-critical)"    "$TYPELIB_DST"
+size "  + .node"                   "$NODE_FILE"
+size "gdk-pixbuf loaders"          "$BINDING_DIR/lib/gdk-pixbuf-2.0"
+size "glib schemas"                "$BINDING_DIR/share/glib-2.0/schemas"
+size "icons (Adwaita+hicolor)"     "$BINDING_DIR/share/icons"
+size "gtksourceview data"          "$BINDING_DIR/share/gtksourceview-5"
+echo "  --------------------------------------"
+size "TOTAL (uncompressed)"        "$BINDING_DIR"
+echo "## =========================="

package/scripts/windows-smoke-test.js

@@ -0,0 +1,104 @@
+/*
+ * windows-smoke-test.js
+ *
+ * Verifies that a Windows prebuilt + bundled GTK runtime can be loaded and used
+ * on a clean machine that has NO MSYS2/MinGW and NO compiler — i.e. exactly what
+ * a user gets from `npm install node-gtk`.
+ *
+ * CRITICAL: this test sets NO environment variables. Everything (DLL search
+ * path, GI typelib path, icon/schema/loader data) is wired up automatically by
+ * lib/native.js when it loads the bundled prebuilt. The workflow runs this with
+ * the runner's own MinGW stripped from PATH, so a pass proves the bundle is
+ * fully self-sufficient via the auto-wiring alone.
+ */
+
+const path = require('path')
+const fs = require('fs')
+
+const abi = process.versions.modules
+const bindingDir = path.join(__dirname, '..', 'lib', 'binding', `node-v${abi}-win32-x64`)
+const typelibDir = path.join(bindingDir, 'girepository-1.0')
+
+console.log('node:', process.version, '| abi:', abi)
+console.log('binding dir:', bindingDir, '| exists:', fs.existsSync(bindingDir))
+console.log('.node:', fs.existsSync(path.join(bindingDir, 'node_gtk.node')))
+console.log('typelibs:', fs.existsSync(typelibDir))
+if (fs.existsSync(bindingDir)) {
+  const dlls = fs.readdirSync(bindingDir).filter(f => f.endsWith('.dll'))
+  console.log(`bundled DLLs: ${dlls.length}`)
+}
+
+// Require the local package. lib/native.js resolves the prebuilt via
+// node-pre-gyp's binary.find and auto-wires the bundled runtime — NO manual
+// PATH / GI_TYPELIB_PATH / XDG_DATA_DIRS setup here on purpose.
+const gi = require(path.join(__dirname, '..'))
+console.log('OK: require(node-gtk) — prebuilt loaded and runtime auto-wired by native.js')
+
+// The full quilx namespace set. Vte (3.91) has no Windows port, so it is
+// expected to be unavailable; everything else must load.
+const REQUIRED = [
+  ['GLib', '2.0'], ['GObject', '2.0'], ['Gio', '2.0'],
+  ['Pango', '1.0'], ['PangoCairo', '1.0'],
+  ['Gdk', '4.0'], ['GdkPixbuf', '2.0'], ['Graphene', '1.0'],
+  ['Gtk', '4.0'], ['Adw', '1'], ['GtkSource', '5'],
+]
+const OPTIONAL = [['Vte', '3.91']]
+
+const loaded = {}
+function load(ns, version, optional) {
+  try {
+    const mod = gi.require(ns, version)
+    console.log(`OK: gi.require('${ns}', '${version}')`)
+    loaded[ns] = mod
+    return mod
+  } catch (e) {
+    console.log(`${optional ? 'note' : 'FAIL'}: gi.require('${ns}', '${version}') — ${e.message}`)
+    if (!optional) throw e
+    return null
+  }
+}
+
+for (const [ns, v] of REQUIRED) load(ns, v, false)
+for (const [ns, v] of OPTIONAL) load(ns, v, true)
+
+// Sanity: the typelibs really resolved their symbols.
+if (typeof loaded.GLib.getMonotonicTime !== 'function')
+  throw new Error('GLib.getMonotonicTime missing — typelib not really loaded')
+if (typeof loaded.Gtk.Window !== 'function')
+  throw new Error('Gtk.Window missing — Gtk4 typelib not really loaded')
+if (typeof loaded.Adw.ApplicationWindow !== 'function')
+  throw new Error('Adw.ApplicationWindow missing — libadwaita not really loaded')
+
+// Exercise a real GTK4 + Adwaita object graph (needs a display; the runner has one).
+let appOk = false
+try {
+  loaded.Gtk.init()
+  const win = new loaded.Adw.ApplicationWindow()
+  const buffer = new loaded.GtkSource.Buffer()
+  const view = new loaded.GtkSource.View()
+  view.setBuffer(buffer)
+  win.setContent(view)
+  console.log('OK: created Adw.ApplicationWindow + GtkSource.View')
+  appOk = true
+} catch (e) {
+  console.log('note: live widget creation threw (likely no display):', e.message)
+}
+console.log('live GTK4/Adwaita widgets:', appOk ? 'ok' : 'skipped (no display)')
+
+// Exercise the bundled gdk-pixbuf image loaders + (portable) loaders.cache by
+// decoding a real PNG. This proves the loader subsystem works from the bundle.
+const PNG_1x1 = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC',
+  'base64')
+const pngPath = path.join(__dirname, '..', 'smoke-test-pixel.png')
+fs.writeFileSync(pngPath, PNG_1x1)
+try {
+  const pixbuf = loaded.GdkPixbuf.Pixbuf.newFromFile(pngPath)
+  if (pixbuf.getWidth() !== 1 || pixbuf.getHeight() !== 1)
+    throw new Error(`unexpected pixbuf size ${pixbuf.getWidth()}x${pixbuf.getHeight()}`)
+  console.log('OK: GdkPixbuf decoded a PNG via the bundled loaders')
+} finally {
+  try { fs.unlinkSync(pngPath) } catch (e) { /* ignore */ }
+}
+
+console.log('\n=== SMOKE TEST PASSED: GTK4/Adwaita prebuilt usable with NO compiler/MSYS2 ===')

package/src/closure.cc

@@ -113,9 +113,19 @@ void Closure::Execute(GICallableInfo *info, guint signal_id,
                 LoadGIArgumentFromPointer(&type_info, &argument);
                 ownership = kNone;
             } else if (direction == GI_DIRECTION_OUT) {
-                // Pure out: there is no meaningful incoming value.
-                memset(&argument, 0, sizeof(argument));
-                ownership = kNone;
+                if (g_arg_info_is_caller_allocates(&arg_info)) {
+                    // Caller-allocated out (e.g. a GdkRectangle in
+                    // GtkOverlay::get-child-position): the GValue already holds a
+                    // pointer to caller (GLib/GTK) memory. Pass a live wrapper so the
+                    // handler fills it in place — it is NOT written back from the
+                    // return value (see the output loop below). #444.
+                    ownership = kNone;
+                } else {
+                    // Callee-allocated out: no meaningful incoming value; the handler
+                    // supplies it through the return value.
+                    memset(&argument, 0, sizeof(argument));
+                    ownership = kNone;
+                }
             }
 
             js_args[i - 1] = GIArgumentToV8(&type_info, &argument, -1, ownership);
@@ -156,11 +166,14 @@ void Closure::Execute(GICallableInfo *info, guint signal_id,
             GIArgInfo  out_arg_info;
             GITypeInfo out_type_info;
 
+            // Caller-allocated out structs are filled in place via the wrapper
+            // passed to the handler, so they are not part of the return value.
             int n_outputs = (g_return_value != NULL) ? 1 : 0;
             for (guint i = 1; i < n_param_values; i++) {
                 g_callable_info_load_arg(info, i - 1, &out_arg_info);
                 GIDirection d = g_arg_info_get_direction(&out_arg_info);
-                if (d == GI_DIRECTION_OUT || d == GI_DIRECTION_INOUT)
+                if (d == GI_DIRECTION_INOUT ||
+                    (d == GI_DIRECTION_OUT && !g_arg_info_is_caller_allocates(&out_arg_info)))
                     n_outputs++;
             }
 
@@ -184,6 +197,10 @@ void Closure::Execute(GICallableInfo *info, guint signal_id,
                 GIDirection d = g_arg_info_get_direction(&out_arg_info);
                 if (d != GI_DIRECTION_OUT && d != GI_DIRECTION_INOUT)
                     continue;
+                // Caller-allocated out structs were filled in place by the handler
+                // via their wrapper; nothing to write back from the return value.
+                if (d == GI_DIRECTION_OUT && g_arg_info_is_caller_allocates(&out_arg_info))
+                    continue;
 
                 g_arg_info_load_type(&out_arg_info, &out_type_info);
 

package/src/function.cc

@@ -481,12 +481,15 @@ Local<Value> FunctionCall (
                     param.data.v_pointer = CaptureTransferContainerElements(
                             &type_info, callable_arg_values[i].v_pointer);
                 }
-                // For a transfer-full IN boxed (or array of boxed) the callee
-                // frees the memory; hand it a copy so the JS wrapper's own
-                // memory isn't double-freed when it's finalized (#409).
+                // For a transfer-full IN argument the callee takes ownership.
+                // Boxed: hand it a copy so the JS wrapper's own memory isn't
+                // double-freed when finalized (#409). GObject: add the reference
+                // the callee will own, so it isn't finalized out from under the
+                // callee once the wrapper is GC'd (#439).
                 else if (direction == GI_DIRECTION_IN
                         && g_arg_info_get_ownership_transfer(&arg_info) == GI_TRANSFER_EVERYTHING) {
                     CopyBoxedForTransferFullIn(&type_info, &callable_arg_values[i], param.length);
+                    RefObjectForTransferFullIn(&type_info, &callable_arg_values[i]);
                 }
             }
 

package/src/gi.cc

@@ -380,6 +380,10 @@ NAN_METHOD(StartLoop) {
     GNodeJS::StartLoop ();
 }
 
+NAN_METHOD(IsRunningMicrotasks) {
+    info.GetReturnValue().Set(Nan::New<Boolean>(GNodeJS::IsRunningMicrotasks ()));
+}
+
 NAN_METHOD(GetBaseClass) {
     auto tpl = GNodeJS::GetBaseClassTemplate ();
     auto fn = Nan::GetFunction (tpl).ToLocalChecked();
@@ -425,6 +429,7 @@ void InitModule(Local<Object> exports, Local<Value> module, void *priv) {
     Nan::Export(exports, "ObjectPropertyGetter", ObjectPropertyGetter);
     Nan::Export(exports, "ObjectPropertySetter", ObjectPropertySetter);
     Nan::Export(exports, "StartLoop",            StartLoop);
+    Nan::Export(exports, "IsRunningMicrotasks",  IsRunningMicrotasks);
     Nan::Export(exports, "GetLoopStack",         GetLoopStack);
     Nan::Export(exports, "RegisterClass",        RegisterClass);
     Nan::Export(exports, "RegisterVFunc",        RegisterVFunc);

package/src/gobject.cc

@@ -34,7 +34,6 @@ namespace GNodeJS {
 static Nan::Persistent<FunctionTemplate> baseTemplate;
 
 
-static void GObjectDestroyed(const Nan::WeakCallbackInfo<GObject> &data);
 static MaybeLocal<FunctionTemplate> GetClassTemplate(GType gtype);
 static MaybeLocal<Function>         GetClass(GType gtype);
 static void StoreVFunc(GType gtype, Callback *callback);
@@ -100,21 +99,66 @@ out:
     return gobject;
 }
 
+struct GObjectWrapper;
+static void GObjectDestroyedFirstPass(const v8::WeakCallbackInfo<GObjectWrapper> &data);
+static void GObjectDestroyedSecondPass(const v8::WeakCallbackInfo<GObjectWrapper> &data);
+static void GObjectFinalized(gpointer data, GObject *where_the_object_was);
+
+struct GObjectWrapper {
+    Nan::Persistent<Object> persistent;
+    GObject *gobject;
+    /* Set to true the moment SetWeak is called. Between that point and the
+     * destroy callback actually running, the V8 handle is weak (and, once GC
+     * reclaims it, dead). If ToggleNotify fires in that window (because native
+     * code adjusts the refcount), touching the persistent crashes. Guard every
+     * persistent access with this flag. */
+    bool dying = false;
+    /* Set in the first-pass weak callback, i.e. the instant GC reclaims the
+     * wrapper, before any JS/GTK code resumes. While this is true the
+     * persistent is dead but the qdata still points here until the second-pass
+     * callback runs; WrapperFromGObject must build a fresh wrapper rather than
+     * resurrect this one. */
+    bool collected = false;
+};
+
 static void ToggleNotify(gpointer user_data, GObject *gobject, gboolean toggle_down) {
     void *data = g_object_get_qdata (gobject, GNodeJS::object_quark());
 
     g_assert (data != NULL);
 
-    auto *persistent = (Nan::Persistent<Object> *) data;
+    auto *wrapper = (GObjectWrapper *) data;
+
+    /* The V8 handle has already been reclaimed by GC (collected) — it is dead
+     * and can be made neither weak nor strong. If the object is marshalled
+     * again, WrapperFromGObject builds a fresh wrapper. */
+    if (wrapper->collected)
+        return;
 
     if (toggle_down) {
-        /* We're dropping from 2 refs to 1 ref. We are the last holder. Make
-         * sure that that our weak ref is installed. */
-        persistent->SetWeak (gobject, GObjectDestroyed, v8::WeakCallbackType::kParameter);
+        /* We're dropping from 2 refs to 1 ref: we are the last holder, so the
+         * wrapper may be collected. Install the weak ref (unless it already is). */
+        if (wrapper->dying)
+            return;
+        wrapper->dying = true;
+        /* Two-pass weak callback: the first pass runs *during* GC (before any
+         * JS/GTK code resumes) and only flips a flag, so WrapperFromGObject can
+         * tell a reclaimed wrapper from a live one and never marshals a dead
+         * handle to JS. All GObject teardown happens in the second pass — a
+         * first-pass callback may not call into GObject. */
+        wrapper->persistent.v8::PersistentBase<Object>::SetWeak (
+            wrapper, GObjectDestroyedFirstPass, v8::WeakCallbackType::kParameter);
     } else {
-        /* We're going from 1 ref to 2 refs. We can't let our wrapper be
-         * collected, so make sure that our reference is persistent */
-        persistent->ClearWeak ();
+        /* We're going from 1 ref to 2 refs: something other than us now holds
+         * the object, so the wrapper must stay alive (strong) until that ref is
+         * dropped again. Reviving here is essential — without it a wrapper that
+         * went weak once (e.g. a freshly constructed object at refcount 1) would
+         * never become strong again when GTK takes ownership, and GC could then
+         * collect a wrapper whose GObject is still in use (notably a subclassed
+         * widget owned by GTK, losing its overridden vfuncs and instance state). */
+        if (!wrapper->dying)
+            return;
+        wrapper->dying = false;
+        wrapper->persistent.ClearWeak ();
     }
 }
 
@@ -123,8 +167,10 @@ static void AssociateGObject(Local<Object> object, GObject *gobject, GType gtype
 
     SET_OBJECT_GTYPE(object, gtype);
 
-    auto *persistent = new Nan::Persistent<Object>(object);
-    g_object_set_qdata (gobject, GNodeJS::object_quark(), persistent);
+    auto *wrapper = new GObjectWrapper();
+    wrapper->gobject = gobject;
+    wrapper->persistent.Reset(object);
+    g_object_set_qdata (gobject, GNodeJS::object_quark(), wrapper);
 
     // Because we can't sink floating ref and add toggle ref at the same time,
     // first sink the floating ref, add the toggle ref, and then release the
@@ -132,6 +178,18 @@ static void AssociateGObject(Local<Object> object, GObject *gobject, GType gtype
     g_object_ref_sink (gobject);
     g_object_add_toggle_ref (gobject, ToggleNotify, NULL);
     g_object_unref (gobject);
+
+    // The toggle ref above is supposed to keep the GObject alive for as long as
+    // the wrapper exists. A weak ref guards against the case where it doesn't —
+    // e.g. a JS-subclassed instance whose refcount is driven to 0 from the GTK
+    // side while we still hold the toggle ref: GObjectFinalized then clears the
+    // dangling pointer so the destroy callbacks never touch freed memory.
+    g_object_weak_ref (gobject, GObjectFinalized, wrapper);
+}
+
+static void GObjectFinalized(gpointer data, GObject *where_the_object_was) {
+    auto *wrapper = (GObjectWrapper *) data;
+    wrapper->gobject = NULL;
 }
 
 static void GObjectConstructor(const FunctionCallbackInfo<Value> &info) {
@@ -183,18 +241,71 @@ static void GObjectConstructor(const FunctionCallbackInfo<Value> &info) {
     }
 }
 
-static void GObjectDestroyed(const Nan::WeakCallbackInfo<GObject> &data) {
-    GObject *gobject = data.GetParameter ();
+static void GObjectDestroyedFirstPass(const v8::WeakCallbackInfo<GObjectWrapper> &data) {
+    GObjectWrapper *wrapper = data.GetParameter ();
+
+    /* This runs *during* GC, where it is not legal to call into V8 (beyond
+     * resetting the handle, which the two-pass contract requires) or into
+     * GObject — the GObject is not safe to touch here, and doing so crashes in
+     * g_type_check_instance_is_fundamentally_a. So only flip a flag and reset
+     * the handle; the real teardown is deferred to the second pass.
+     *
+     * The flag lets WrapperFromGObject distinguish a reclaimed wrapper (whose
+     * persistent is now dead) from a live one during the window before the
+     * second pass nulls the qdata, so it builds a fresh wrapper instead of
+     * handing the dead handle to JS — which crashed on first property access. */
+    wrapper->collected = true;
+    wrapper->persistent.Reset ();
+
+    data.SetSecondPassCallback (GObjectDestroyedSecondPass);
+}
 
-    void *type_data = g_object_get_qdata (gobject, GNodeJS::object_quark());
-    auto *persistent = (Nan::Persistent<Object> *) type_data;
-    delete persistent;
+static gboolean GObjectTeardownIdle(gpointer data) {
+    GObjectWrapper *wrapper = (GObjectWrapper *) data;
+    GObject *gobject = wrapper->gobject;
+
+    /* If the GObject was already finalized out from under us, GObjectFinalized
+     * cleared the pointer; there is nothing left to detach or unref. */
+    if (gobject != NULL) {
+        /* Drop the weak ref first so removing the toggle ref (which may finalize
+         * the object) doesn't re-enter GObjectFinalized. */
+        g_object_weak_unref (gobject, GObjectFinalized, wrapper);
+
+        /* Only detach the qdata if it still points at us — WrapperFromGObject
+         * may have resurrected this GObject with a fresh wrapper while we were
+         * pending, and we must not clobber it. */
+        if (g_object_get_qdata (gobject, GNodeJS::object_quark()) == wrapper)
+            g_object_set_qdata (gobject, GNodeJS::object_quark(), NULL);
+
+        /* Dropping the last toggle ref disposes the object, and GTK's dispose
+         * synchronously emits signals (e.g. ::destroy) into still-connected
+         * node-gtk closures — i.e. it re-enters arbitrary JS. That is only legal
+         * here because we run from a GLib idle on the main loop, not from the GC
+         * second-pass callback that scheduled us (see GObjectDestroyedSecondPass). */
+        g_object_remove_toggle_ref (gobject, &ToggleNotify, NULL);
+    }
 
-    /* We're destroying the wrapper object, so make sure to clear out
-     * the qdata that points back to us. */
-    g_object_set_qdata (gobject, GNodeJS::object_quark(), NULL);
+    delete wrapper;
+    return G_SOURCE_REMOVE;
+}
 
-    g_object_remove_toggle_ref (gobject, &ToggleNotify, NULL);
+static void GObjectDestroyedSecondPass(const v8::WeakCallbackInfo<GObjectWrapper> &data) {
+    GObjectWrapper *wrapper = data.GetParameter ();
+
+    /* Defer the actual teardown to a main-loop idle instead of running it here.
+     * This callback fires from V8's InvokeSecondPassPhantomCallbacks *during* a
+     * garbage collection. Dropping the toggle ref can take the GObject's refcount
+     * to zero, and GTK's dispose then emits signals into node-gtk closures,
+     * re-entering JS (Nan::Call) — which crashes when invoked mid-GC. Running the
+     * teardown from a GLib idle moves the ref drop (and any disposal/signal
+     * emission it triggers) to a point where calling into JS is safe again.
+     *
+     * The GObject stays alive across the window because we still hold the toggle
+     * ref; the wrapper (with its now-reset persistent and collected=true) is kept
+     * until the idle deletes it. WrapperFromGObject already handles a resurrected
+     * GObject during this window by building a fresh wrapper, and the idle's
+     * qdata check above won't clobber it. */
+    g_idle_add (GObjectTeardownIdle, wrapper);
 }
 
 static void GObjectClassDestroyed(const Nan::WeakCallbackInfo<GType> &info) {
@@ -657,10 +768,15 @@ Local<Value> WrapperFromGObject(GObject *gobject) {
     void *data = g_object_get_qdata (gobject, GNodeJS::object_quark());
 
     if (data) {
-        /* Easy case: we already have an object. */
-        auto *persistent = (Nan::Persistent<Object> *) data;
-        auto obj = New<Object> (*persistent);
-        return obj;
+        auto *wrapper = (GObjectWrapper *) data;
+        /* Reuse the existing wrapper unless GC has already reclaimed it (its
+         * persistent is dead and only awaiting the second-pass teardown). In
+         * that case fall through and build a fresh wrapper; the stale one's
+         * second pass is guarded so it won't clobber the new qdata. */
+        if (!wrapper->collected) {
+            auto obj = New<Object> (wrapper->persistent);
+            return obj;
+        }
     }
 
     GType gtype = G_OBJECT_TYPE(gobject);

package/src/loop.cc

@@ -26,6 +26,8 @@ static Nan::Persistent<Array> loopStack(Nan::New<Array> ());
 struct uv_loop_source {
     GSource source;
     uv_loop_t *loop;
+    gpointer fd_tag;
+    bool fd_polled;
 };
 
 static gboolean loop_source_prepare (GSource *base, int *timeout) {
@@ -45,6 +47,24 @@ static gboolean loop_source_prepare (GSource *base, int *timeout) {
 
     bool loop_alive = uv_loop_alive (source->loop);
 
+    /* Toggle whether GLib polls uv's backend fd. When the loop is dead we must
+     * stop polling it: an *unref'd* but still-active uv handle (e.g. the async
+     * eventfd left signaling by emscripten/WASM runtimes such as web-tree-sitter,
+     * or by worker_threads) keeps the backend epoll fd perpetually readable.
+     * uv_loop_alive() reports the loop dead (unref'd handles don't count), so we
+     * intend to sleep here, but a polled-and-ready fd makes GLib's poll() return
+     * immediately every iteration -> loop_source_dispatch() busy-spins at 100%
+     * CPU, starving GTK. Masking the fd lets GLib actually block until a GTK
+     * source wakes us; we restore polling as soon as the loop is alive again. */
+#if !OS_WINDOWS
+    if (source->fd_tag != NULL && loop_alive != source->fd_polled) {
+        g_source_modify_unix_fd (&source->source, source->fd_tag,
+                                 loop_alive ? (GIOCondition) (G_IO_IN | G_IO_OUT | G_IO_ERR)
+                                            : (GIOCondition) 0);
+        source->fd_polled = loop_alive;
+    }
+#endif
+
     /* If the loop is dead, we can simply sleep forever until a GTK+ source
      * (presumably) wakes us back up again. */
     if (!loop_alive)
@@ -92,13 +112,15 @@ static GSourceFuncs uv_loop_source_funcs = {
 static GSource *loop_source_new (uv_loop_t *loop) {
     struct uv_loop_source *source = (struct uv_loop_source *) g_source_new (&uv_loop_source_funcs, sizeof (*source));
     source->loop = loop;
+    source->fd_tag = NULL;
+    source->fd_polled = true;
 #if OS_WINDOWS
     // FIXME
     // https://github.com/nodejs/node/issues/36015
 #else
-    g_source_add_unix_fd (&source->source,
-                          uv_backend_fd (loop),
-                          (GIOCondition) (G_IO_IN | G_IO_OUT | G_IO_ERR));
+    source->fd_tag = g_source_add_unix_fd (&source->source,
+                                           uv_backend_fd (loop),
+                                           (GIOCondition) (G_IO_IN | G_IO_OUT | G_IO_ERR));
 #endif
     return &source->source;
 }
@@ -145,6 +167,20 @@ void CallMicrotaskHandlers () {
 #endif
 }
 
+bool IsRunningMicrotasks() {
+    /* True while V8 is draining the microtask queue. Under ES modules the
+     * top-level body executes as a microtask, so a synchronous blocking call
+     * (e.g. g_main_loop_run) made from it nests inside this drain. V8 refuses
+     * nested microtask checkpoints, so any Promise/async continuation queued
+     * by user code is stuck until the blocking call returns. Callers use this
+     * to detect that situation and defer the blocking call to a macrotask so
+     * the module's top-level microtask can return and the queue can drain.
+     *
+     * - https://github.com/romgrk/node-gtk/issues/442
+     */
+    return MicrotasksScope::IsRunningMicrotasks(Isolate::GetCurrent());
+}
+
 void StartLoop() {
     GSource *source = loop_source_new (uv_default_loop ());
     g_source_attach (source, NULL);

package/src/loop.h

@@ -12,6 +12,8 @@ namespace GNodeJS {
 
   void StartLoop();
 
+  bool IsRunningMicrotasks();
+
   void QuitLoopStack();
 
   Local<Array> GetLoopStack();

package/src/value.cc

@@ -1650,6 +1650,30 @@ void CopyBoxedForTransferFullIn (GITypeInfo *type_info, GIArgument *arg, long le
     }
 }
 
+void RefObjectForTransferFullIn (GITypeInfo *type_info, GIArgument *arg) {
+    if (arg->v_pointer == NULL)
+        return;
+
+    if (g_type_info_get_tag(type_info) != GI_TYPE_TAG_INTERFACE)
+        return;
+
+    GIBaseInfo *iface = g_type_info_get_interface(type_info);
+    GIInfoType  itype = g_base_info_get_type(iface);
+
+    // The callee owns one reference after the call (transfer-full). node-gtk
+    // keeps only its toggle ref, so without this the callee would effectively
+    // "own" the toggle ref: the refcount never accounts for the new owner, no
+    // toggle-up fires, the wrapper stays weak, and once GC collects it the
+    // destroy callback finalizes the object while the callee still uses it
+    // (e.g. a controller passed to gtk_widget_add_controller). The G_IS_OBJECT
+    // guard skips boxed/fundamental interface types (handled elsewhere).
+    if ((itype == GI_INFO_TYPE_OBJECT || itype == GI_INFO_TYPE_INTERFACE)
+            && G_IS_OBJECT(arg->v_pointer))
+        g_object_ref(arg->v_pointer);
+
+    g_base_info_unref(iface);
+}
+
 
 /*
  * GValue conversion functions

package/src/value.h

@@ -46,6 +46,12 @@ void         FreeTransferContainerElements (GITypeInfo *type_info, gpointer capt
 // See #409.
 void         CopyBoxedForTransferFullIn (GITypeInfo *type_info, GIArgument *arg, long length);
 
+// For a transfer-full IN GObject argument the callee takes ownership of one
+// reference. node-gtk only holds a toggle ref on the wrapper, so add the
+// reference the callee expects — otherwise the object is finalized out from
+// under the callee once the wrapper is GC'd. See #439.
+void         RefObjectForTransferFullIn (GITypeInfo *type_info, GIArgument *arg);
+
 bool         CanConvertV8ToGIArgument (GITypeInfo *type_info, Local<Value> value, bool may_be_null);
 
 bool         V8ToGValue(GValue *gvalue, Local<Value> value, ResourceOwnership ownership = kNone);