feat(windows): auto-wire bundled GTK runtime + publish prebuilts

- lib/native.js: on win32, point PATH / GI_TYPELIB_PATH / XDG_DATA_DIRS /
  GSETTINGS_SCHEMA_DIR / GDK_PIXBUF_MODULE_FILE at the runtime bundled next
  to the .node, before the addon loads. Plain `npm install node-gtk` now
  works on Windows with no MSYS2/compiler and no manual env setup.
- windows-bundle-runtime.sh: rewrite gdk-pixbuf loaders.cache to portable
  (bare) names so image loaders work on the user's machine.
- main.yaml: install the GTK4 ship-stack alongside the GTK3 test deps,
  bundle the runtime, and publish the prebuilt to S3 on [publish binary].
- smoke test now sets NO env vars (relies on native.js) and runs with the
  runner's MinGW stripped from PATH; also decodes a PNG via bundled loaders.
- doc: Windows prebuilt binaries are now available.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: romgrk

.github/workflows/main.yaml

@@ -39,13 +39,19 @@ jobs:
             mingw-w64-x86_64-gcc
             mingw-w64-x86_64-pkgconf
             mingw-w64-x86_64-python
+            mingw-w64-x86_64-ntldd-git
             mingw-w64-x86_64-gobject-introspection
-            mingw-w64-x86_64-gtk3
             mingw-w64-x86_64-cairo
+            mingw-w64-x86_64-gtk3
             mingw-w64-x86_64-gstreamer
             mingw-w64-x86_64-gst-plugins-good
             mingw-w64-x86_64-gst-plugins-bad
             mingw-w64-x86_64-libsoup3
+            mingw-w64-x86_64-gtk4
+            mingw-w64-x86_64-libadwaita
+            mingw-w64-x86_64-gtksourceview5
+            mingw-w64-x86_64-graphene
+            mingw-w64-x86_64-adwaita-icon-theme
 
       - name: Install & Build
         env:
@@ -64,6 +70,27 @@ jobs:
                     --skip=callback                 \
                     tests/__run__.js
 
+      # Make the freshly-built addon a self-contained prebuilt: bundle the GTK4
+      # runtime (DLLs + GI typelibs + data) next to the .node so Windows users
+      # can `npm install node-gtk` with no MSYS2/compiler. lib/native.js wires
+      # this bundle up automatically at load time.
+      - name: Bundle GTK4 runtime
+        run: |
+          ABI=$(node -p "process.versions.modules")
+          ./scripts/windows-bundle-runtime.sh "lib/binding/node-v${ABI}-win32-x64"
+
+      # Publish the prebuilt to S3 on a `[publish binary]` commit, like the
+      # Linux/macOS jobs do via scripts/ci.sh.
+      - name: Publish prebuilt
+        if: contains(github.event.head_commit.message, '[publish binary]')
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+        run: |
+          npx node-pre-gyp package
+          npx node-pre-gyp publish
+          npx node-pre-gyp info
+
   build:
     name: ${{ matrix.os }} - nodejs ${{ matrix.node }}
     runs-on: ${{ matrix.os }}

.github/workflows/test-windows-prebuilt.yaml

@@ -128,18 +128,29 @@ jobs:
           echo "---- bundled prebuilt ----"
           ls -la lib/binding/*/ || true
 
-      # Negative control: without the bundled DLLs on PATH the addon must fail to
-      # load. Documents WHY bundling is required. Allowed to fail.
+      # Negative control: move the bundled typelibs aside so native.js cannot
+      # auto-wire; the addon must then fail to load. Proves the pass below comes
+      # from the bundle (not the runner's GTK), then restores it. Allowed to fail.
       - name: Negative control (no bundled runtime — expected to fail)
         continue-on-error: true
         shell: bash
         run: |
+          export PATH=$(echo "$PATH" | tr ':' '\n' | grep -viE 'mingw|msys|chocolatey' | paste -sd ':' -)
+          DIR=$(echo lib/binding/node-v*-win32-x64)
+          mv "$DIR/girepository-1.0" "$DIR/girepository-1.0.off"
           if node -e "require('.')"; then
             echo "UNEXPECTED - loaded without the bundled GTK runtime"
           else
             echo "expected failure - addon needs the bundled GTK runtime/typelibs"
           fi
+          mv "$DIR/girepository-1.0.off" "$DIR/girepository-1.0"
 
-      - name: Smoke test (bundled runtime — expected to pass)
+      # The real test: NO env vars set here, and the runner's own MinGW/MSYS is
+      # stripped from PATH to simulate a clean user machine. A pass proves
+      # lib/native.js auto-wires the bundled runtime by itself.
+      - name: Smoke test (auto-wired, simulated clean machine)
         shell: bash
-        run: node scripts/windows-smoke-test.js
+        run: |
+          export PATH=$(echo "$PATH" | tr ':' '\n' | grep -viE 'mingw|msys|chocolatey' | paste -sd ':' -)
+          echo "gcc on PATH? $(which gcc || echo no)"
+          node scripts/windows-smoke-test.js

doc/installation.md

@@ -19,7 +19,10 @@ Note that prebuilt binaries are available for common systems, in those cases bui
 
 - **Linux**: prebuilt binaries available
 - **macOS**: prebuilt binaries available
-- **Windows**: no prebuilt binaries
+- **Windows**: prebuilt binaries available (the GTK4/Adwaita runtime is bundled
+  with the binary, so no MSYS2/compiler is needed to *use* node-gtk; the terminal
+  widget Vte is the one exception — it has no Windows port). Building from source
+  still requires MSYS2 (see below).
 
 ### Requirements
 

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

scripts/windows-bundle-runtime.sh

@@ -133,6 +133,16 @@ 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

scripts/windows-smoke-test.js

@@ -1,13 +1,15 @@
 /*
  * windows-smoke-test.js
  *
- * Verifies that a Windows prebuilt + bundled GTK runtime (DLLs + typelibs) 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` if we ship a
- * self-contained Windows prebuilt.
+ * 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`.
  *
- * It deliberately does NOT depend on anything from MSYS2; the only GTK bits it
- * touches are the ones bundled next to the .node by windows-bundle-runtime.sh.
+ * 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')
@@ -26,39 +28,11 @@ if (fs.existsSync(bindingDir)) {
   console.log(`bundled DLLs: ${dlls.length}`)
 }
 
-// 1) Make the bundled GTK DLLs discoverable. This covers BOTH:
-//      - the addon's own static imports (resolved when node loads the .node)
-//      - GObject-Introspection's g_module_open() of each namespace's shared lib
-//    We REPLACE the PATH (rather than prepend) with the bundle dir + only the
-//    Windows system dirs. The GitHub windows-latest runner ships its own
-//    C:\mingw64; isolating the PATH proves the test uses ONLY the bundled
-//    runtime, not whatever GTK happens to be on the machine.
-const sysRoot = process.env.SystemRoot || 'C:\\Windows'
-process.env.PATH = [
-  bindingDir,
-  path.dirname(process.execPath),       // node.exe dir
-  path.join(sysRoot, 'System32'),
-  sysRoot,
-].join(path.delimiter)
-// 2) Point GI at the bundled typelibs.
-process.env.GI_TYPELIB_PATH =
-  typelibDir + (process.env.GI_TYPELIB_PATH ? path.delimiter + process.env.GI_TYPELIB_PATH : '')
-
-// Require the local package (its lib/native.js resolves the prebuilt via
-// node-pre-gyp's binary.find, i.e. the same path users hit after install).
+// 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 + bundled DLLs loaded')
-
-// Belt and suspenders: also register the typelib dir through GI's own API.
-try { gi.prependSearchPath(typelibDir) } catch (e) { /* ignore */ }
-
-// Point GTK4/Adwaita at the bundled runtime data so a real app could run.
-const bundledShare = path.join(bindingDir, 'share')
-if (fs.existsSync(bundledShare)) {
-  process.env.XDG_DATA_DIRS = bundledShare + (process.env.XDG_DATA_DIRS ? path.delimiter + process.env.XDG_DATA_DIRS : '')
-  const schemas = path.join(bundledShare, 'glib-2.0', 'schemas')
-  if (fs.existsSync(schemas)) process.env.GSETTINGS_SCHEMA_DIR = schemas
-}
+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.
@@ -111,4 +85,20 @@ try {
 }
 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(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
+  '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 ===')