@gjsify/node-gi 0.51.1 → 0.53.0

package/README.md

@@ -124,8 +124,9 @@ console.log(action.get_name());   // 'greet'  — introspected method
 action.enabled = false;           // property set → set_property
 
 const cancellable = new Gio.Cancellable();
-cancellable.connect('cancelled', () => console.log('cancelled'));
+cancellable.connect_after('cancelled', () => console.log('cancelled'));
 cancellable.cancel();             // fires the signal
+// (plain `connect` is Cancellable's OWN g_cancellable_connect(cb), as on gjs)
 
 console.log(Gio.BusType.SESSION); // 2 — enums, flags and constants
 const file = Gio.File.new_for_path('/usr/bin/gjs');

package/binding.gyp

@@ -10,6 +10,7 @@
         "src/loop.cc",
         "src/marshal.cc",
         "src/object.cc",
+        "src/opengl-win32.cc",
         "src/private.cc",
         "src/repo.cc",
         "src/signals.cc",

package/gi.js

@@ -18,6 +18,9 @@ import { setImmediate, setInterval, clearInterval } from 'node:timers';
 // loop-liveness hooks below would silently never fire.
 import runtimeProcess from 'node:process';
 import { createGioDBus } from './overrides/gio-dbus.js';
+// The windowing loader's record of what it wrote into process.env. Read here and not there
+// because replaying it needs a GLib (mirrorWindowingEnvIntoCrt below).
+import { windowingEnvWrites } from './gtk-runtime.js';
 
 // The raw native GObject handle on a wrapped instance, so it can be unwrapped again
 // when passed back into the engine as a GI argument.
@@ -33,6 +36,19 @@ const USER_PROTO = Symbol('nodeGiUserProto');
 // make every wrapper look thenable).
 const RESERVED = new Set(['then', 'toString', 'valueOf', 'constructor', 'inspect']);
 
+// Names the instance wrapper's `get` trap otherwise shortcuts straight to the
+// GObject signal API (see wrapInstance below). A concrete class can introspect
+// its OWN method under one of these — `Soup.Server.disconnect(): void` is
+// `soup_server_disconnect`, zero-arg, nothing to do with a signal handler id —
+// and on gjs that own prototype property already shadows the inherited
+// override through ordinary JS lookup. This Proxy has no such chain, so
+// `wrapInstance` checks for an own introspected member under the name FIRST
+// and only falls through to the shortcut when the class declares none.
+// Regression: `Http2SecureServer.close()` called `this._soupServer.disconnect()`
+// (real libsoup API, zero args) and got `disconnectSignal(handle, handlerId:
+// number)` — the shortcut's `disconnect(id)` — under node-gi on Node.
+const SIGNAL_API_SHORTCUTS = new Set(['connect', 'connect_after', 'emit', 'disconnect']);
+
 // GJS accepts both snake_case and camelCase for methods/properties: map a JS accessor
 // to the GI method name (snake_case) and to a GObject property name (kebab-case); a
 // name already in the target case passes through.
@@ -1301,6 +1317,19 @@ function wrapInstance(handle, userProto) {
         get(t, prop) {
             if (prop === HANDLE) return handle;
             if (typeof prop !== 'string' || RESERVED.has(prop)) return t[prop];
+            if (SIGNAL_API_SHORTCUTS.has(prop)) {
+                const up = t[USER_PROTO];
+                const own = up !== undefined ? findProtoDescriptor(up, prop) : undefined;
+                if (own !== undefined) return typeof own.get === 'function' ? own.get.call(proxy) : own.value;
+                // An INTERFACE method under the name never reaches a class prototype
+                // when the concrete type is private: GSocks5Proxy wraps as its nearest
+                // introspectable ancestor (GObject.Object), yet on gjs 1.88.1
+                // `socks5.connect` IS g_proxy_connect (Gio.Proxy, 3 IN args) — measured.
+                // The same native walk the GI-method fallback below uses sees it.
+                if (instanceHasMethod(handle, prop)) {
+                    return (...args) => wrapReturn(native.callMethod(handle, prop, unwrapArgs(args)));
+                }
+            }
             switch (prop) {
                 case '$typeName':
                     // The instance's concrete RUNTIME GType name —
@@ -2295,8 +2324,15 @@ function collectVfuncs(klass) {
             if (desc === undefined || typeof desc.value !== 'function') continue;
             seen.add(key);
             const userFn = desc.value;
+            // The ARGUMENTS cross the same boundary `this` does and need the same
+            // treatment: the engine hands a GObject arg over as a raw handle, so a
+            // `Gtk.LayoutManager.vfunc_measure(widget, …)` override received an object
+            // with no prototype and `widget.get_ancestor` was `undefined`. The return
+            // goes back through `unwrapArg` because the engine reads a GObject return
+            // as a handle, never as the wrapper user code naturally hands back.
+            // Same contract as `wrapCallbackFn`, which callbacks have always had.
             vfuncs[key.slice('vfunc_'.length)] = function (...args) {
-                return userFn.apply(wrapInstance(this, klass.prototype), args);
+                return unwrapArg(userFn.apply(wrapInstance(this, klass.prototype), args.map(wrapReturn)));
             };
         }
     }
@@ -2682,6 +2718,45 @@ function namespaceObject(namespace) {
 // startMainLoop is itself idempotent; this just avoids the extra call.
 let loopAttached = false;
 
+// Whether the windowing loader's win32 env writes have been copied into the C runtime's
+// environment yet. Set BEFORE the copy runs, because the copy calls requireGi() again.
+let windowingEnvMirrored = false;
+
+/**
+ * Give the bundled GTK's `getenv()` readers the variables the loader wrote, on win32.
+ *
+ * THE VARIABLE WAS SET AND UNREACHABLE, which reads in a log exactly like a platform
+ * declining a request — and was read that way once (#1668). A Windows process carries
+ * two environments: the Win32 block, which `GetEnvironmentVariableW()`, `g_getenv()`, the DLL
+ * loader and every child process read, and the C runtime's own copy, which is what `getenv()`
+ * returns. Node's `process.env` setter is `uv_os_setenv()` → `SetEnvironmentVariableW()` and
+ * nothing else, so it writes the first and not the second. `pango_cairo_font_map_new()` reads
+ * `getenv("PANGOCAIRO_BACKEND")` and fontconfig reads `getenv("FONTCONFIG_FILE")`: both saw
+ * an empty environment while `process.env` reported the values back correctly.
+ *
+ * `g_setenv()` is the repair because glib already solved this — it calls `_wputenv()` first
+ * and `SetEnvironmentVariableW()` second, and says why in its own source. Called through the
+ * bundle's OWN GLib, so the runtime copy written is the one pango and fontconfig link against.
+ * `overwrite` is true and that is not a policy decision: every value replayed came from
+ * `setIfUnset`, so a value the operator set is already the value being written back.
+ *
+ * TIMING is why this is not in the loader: both readers are lazy — pango at the first font
+ * map, fontconfig at the first config load — and neither can fire before a namespace is
+ * required, while GLib cannot be called before the addon is loaded. The first `requireGi()` is
+ * the one moment after the second and before the first.
+ *
+ * Strict no-op off win32 (POSIX `setenv()` is the only environment there, and Node uses it)
+ * and when the windowing wiring made no writes. Held by `test/font-script-coverage.test.mjs`,
+ * which measures the loader-set value against the same value put in the LAUNCH environment.
+ * @returns {void}
+ */
+function mirrorWindowingEnvIntoCrt() {
+    const writes = windowingEnvWrites();
+    if (writes.length === 0) return;
+    const GLib = requireGi('GLib', '2.0');
+    for (const [name, value] of writes) GLib.setenv(name, value, true);
+}
+
 /**
  * Require a GObject-Introspection namespace and return a GJS-shaped namespace
  * object. The Node twin of `import Ns from 'gi://Ns?version=X'` /
@@ -2692,6 +2767,13 @@ let loopAttached = false;
  */
 export function requireGi(namespace, version) {
     native.requireNamespace(namespace, version);
+    // The one moment the win32 CRT-environment mirror can run: the addon is loaded, so there
+    // is a GLib to call, and nothing has built a font map or loaded a fontconfig
+    // configuration yet. Flag first — mirrorWindowingEnvIntoCrt() re-enters here for GLib.
+    if (!windowingEnvMirrored) {
+        windowingEnvMirrored = true;
+        mirrorWindowingEnvIntoCrt();
+    }
     // Attach the libuv↔GLib integration once. On Node this arms BOTH directions:
     // the uv-in-GLib bridge (a blocking GLib.MainLoop.run / Gio.Application.run
     // keeps Node's event loop alive) AND the uv-driven auto-pump (pending GLib

package/gtk-runtime.d.ts

@@ -26,3 +26,34 @@ export function appGiLibraryDirs(opts?: { platform?: NodeJS.Platform | string; e
 export function activateGiLibraryPath(native: { prependLibraryPath?: (p: string) => void }): string[];
 /** TEST-ONLY: allow the activation to run again. */
 export function resetGiLibraryPathForTests(): void;
+
+/** What `native.probeHostOpenGL()` reports on win32 — each field "" when absent. */
+export interface HostOpenGL {
+    wddmIcd: string;
+    registryIcd: string;
+    loadedFrom: string;
+}
+/** The OpenGL a win32 process uses: the optional GL package's Mesa opengl32.dll or the host's. */
+export interface OpenGLDecision {
+    source: 'bundle' | 'system';
+    reason: string;
+    /** Set when the host has no ICD and the optional GL package is not installed. */
+    missing?: true;
+}
+/** `@gjsify/gl-runtime-<tag>` — the optional package carrying Mesa for driverless hosts. */
+export function glRuntimePackageName(tag?: string): string;
+/** The optional GL package's opengl32.dll (monorepo sibling or installed package), or null. */
+export function resolveGlRuntime(): string | null;
+/** Decide which OpenGL serves GTK on win32 (pure). `override` is `GJSIFY_OPENGL`. */
+export function decideOpenGLSource(opts: {
+    bundled: string | null;
+    host: HostOpenGL;
+    override?: string;
+}): OpenGLDecision;
+/** win32: preload the optional GL package's opengl32.dll when the host has no OpenGL ICD (no-op elsewhere). */
+export function activateBundledOpenGL(native: {
+    probeHostOpenGL?: () => HostOpenGL;
+    preloadOpenGL?: (path: string) => string;
+}): (OpenGLDecision & { loadedFrom: string | null }) | null;
+/** The decision `activateBundledOpenGL` made for this process, or null. */
+export function openGLActivation(): (OpenGLDecision & { loadedFrom: string | null }) | null;

package/gtk-runtime.js

@@ -25,6 +25,31 @@ const here = dirname(fileURLToPath(import.meta.url)); // package root
 // Sentinel: set on the re-exec so a bundle-activated child never re-execs again.
 const REEXEC_SENTINEL = 'GJSIFY_GTK_REEXEC';
 
+/** @type {Array<[string, string]>} every write maybeWireGtkWindowingEnv() made, in order. */
+let windowingEnvWritesMade = [];
+
+/**
+ * What `maybeWireGtkWindowingEnv()` wrote into `process.env`, as `[name, value]` pairs.
+ *
+ * A WINDOWS PROCESS HAS TWO ENVIRONMENTS and a JS `process.env` write reaches one of them.
+ * Node's setter is `uv_os_setenv()`, which is `SetEnvironmentVariableW()` and nothing else:
+ * that updates the Win32 environment block — what `GetEnvironmentVariableW()`, `g_getenv()`,
+ * the DLL loader and every child process read — and never the C runtime's own copy, which is
+ * what `getenv()` returns. Libraries in the bundle use BOTH: GLib, GIO, gdk-pixbuf and GTK go
+ * through `g_getenv()` and saw every variable all along, while `pango_cairo_font_map_new()`
+ * and fontconfig's config lookup call `getenv()` and saw none of them. That is measured
+ * rather than reasoned: see the PANGOCAIRO_BACKEND note in `maybeWireGtkWindowingEnv()`.
+ *
+ * The repair is `g_setenv()`, which glib implements as `_wputenv()` + `SetEnvironmentVariableW()`
+ * for exactly this reason — so it needs a loaded GLib, which does not exist when the loader
+ * runs. `mirrorWindowingEnvIntoCrt()` in `gi.js` replays this list on the first `requireGi()`.
+ * Empty off win32 (POSIX `setenv()` has one environment) and empty when the wiring no-opped.
+ * @returns {Array<[string, string]>}
+ */
+export function windowingEnvWrites() {
+    return process.platform === 'win32' ? windowingEnvWritesMade.slice() : [];
+}
+
 /**
  * Resolve the GTK runtime bundle directory for this platform, or `null`. A valid
  * bundle dir contains the native-code dir (`lib/` relocated dylibs on darwin,
@@ -64,6 +89,22 @@ export function resolveGtkRuntimeBundle() {
     return null;
 }
 
+/**
+ * The bundle the GTK-in-use is served by, but only when it can open a WINDOW — the
+ * `share/glib-2.0/schemas/gschemas.compiled` marker the --windowing build produces.
+ * Null for no bundle, a system GTK, or the DEFAULT display-free bundle.
+ *
+ * ONE definition of that marker for both callers that need it: the windowing env
+ * wiring, which is a strict no-op without the data it locates, and the OpenGL advice
+ * below, which must not tell a headless process to add a GL package. Spelled twice the
+ * question "can this process show a window?" had two answers to drift apart.
+ * @returns {{ dir: string, libDir: string, typelibDir: string } | null}
+ */
+function windowingBundle() {
+    const bundle = gtkSource() === 'bundle' ? resolveGtkRuntimeBundle() : null;
+    return bundle && existsSync(join(bundle.dir, 'share', 'glib-2.0', 'schemas', 'gschemas.compiled')) ? bundle : null;
+}
+
 // ---- WHICH GTK WINS ---------------------------------------------------------
 //
 // Two GTKs can be reachable at once: a batteries-included bundle
@@ -283,7 +324,7 @@ export function maybeReexecForGtkRuntime() {
     // gjs process, one hop earlier: `buildNativeEnv()` in `@gjsify/cli` puts
     // `systemGiLibraryDirs()` on the child's `DYLD_FALLBACK_LIBRARY_PATH` (its
     // `system-gi.ts` is the pinned mirror of this module's `system-gi.js`). A gjs
-    // launched by hand keeps the gap — tracked in `status/open-todos.md`.
+    // launched by hand keeps the gap — tracked in `status/open-todos/README.md`.
     // Same probe index.js uses for RUNTIME — as with the Bun/Deno pair above, the
     // check has to live here too because this runs before that const is defined.
     if (typeof globalThis.imports !== 'undefined' && typeof globalThis.print === 'function') return;
@@ -362,7 +403,8 @@ export function maybePrependGtkRuntimeDllPath() {
  * finds its runtime DATA on Windows: compiled GSettings schemas
  * (`GSETTINGS_SCHEMA_DIR`), the gdk-pixbuf image loaders (`GDK_PIXBUF_MODULEDIR` +
  * `GDK_PIXBUF_MODULE_FILE`), the icon themes (`XDG_DATA_DIRS` → `<bundle>/share`),
- * and — when bundled — Fontconfig (`FONTCONFIG_PATH`/`FONTCONFIG_FILE`). These live
+ * and — when bundled — Fontconfig (`FONTCONFIG_PATH`/`FONTCONFIG_FILE`) plus the Pango
+ * backend that actually READS it (`PANGOCAIRO_BACKEND`). These live
  * beside the DLLs the display-free path already wires (maybePrependGtkRuntimeDllPath).
  *
  * STRICT no-op off win32, without a bundle, or when the bundle carries NO windowing
@@ -370,7 +412,12 @@ export function maybePrependGtkRuntimeDllPath() {
  * --windowing build produces, so the DEFAULT display-free bundle is byte-unchanged.
  * Windows re-reads these vars at first use (schema/loader/icon-theme init runs AFTER
  * the addon loads), so an in-process mutation here suffices — no re-exec, the DLL-
- * search analog. Each var is set only when currently unset (a host override wins).
+ * search analog. TRUE OF EVERY `g_getenv()` READER, and only of those: on win32 an
+ * in-process write lands in the WIN32 environment block alone, which is where
+ * `g_getenv()` looks and where `getenv()` does not. What every write here is recorded
+ * in `windowingEnvWrites()` for is the repair of that second half — see the
+ * `PANGOCAIRO_BACKEND` note below and `mirrorWindowingEnvIntoCrt()` in `gi.js`.
+ * Each var is set only when currently unset (a host override wins).
  * Idempotent; MUST run at module top-level with maybePrependGtkRuntimeDllPath, before
  * the app initializes GTK. GLib uses `;` as the win32 search-path separator.
  * @returns {void}
@@ -384,17 +431,23 @@ export function maybeWireGtkWindowingEnv() {
     if (process.platform !== 'win32' && process.platform !== 'darwin') return;
     // Same gate as the DLL/dylib path: the runtime DATA belongs to the bundle, so
     // it is wired only when the bundle is the source the policy picked.
-    if (gtkSource() !== 'bundle') return;
-    const bundle = resolveGtkRuntimeBundle();
-    if (!bundle) return; // strict no-op when no bundle is present
+    const bundle = windowingBundle();
+    if (!bundle) return; // strict no-op without a windowing bundle
 
     const schemaDir = join(bundle.dir, 'share', 'glib-2.0', 'schemas');
-    // gschemas.compiled = the windowing-data marker; absent → display-free bundle.
-    if (!existsSync(join(schemaDir, 'gschemas.compiled'))) return;
 
     const pathSep = process.platform === 'win32' ? ';' : ':';
+    // Recorded, not just written. On win32 `process.env.X = v` reaches ONE of the two
+    // environments this process has (see `windowingEnvWrites` and the PANGOCAIRO_BACKEND
+    // note below), and the mirror that reaches the other one needs a GLib, which does not
+    // exist yet at module top level. Reset per call so the function stays idempotent.
+    windowingEnvWritesMade = [];
+    const write = (name, value) => {
+        process.env[name] = value;
+        windowingEnvWritesMade.push([name, value]);
+    };
     const setIfUnset = (name, value) => {
-        if (!process.env[name]) process.env[name] = value;
+        if (!process.env[name]) write(name, value);
     };
     setIfUnset('GSETTINGS_SCHEMA_DIR', schemaDir);
 
@@ -427,7 +480,7 @@ export function maybeWireGtkWindowingEnv() {
     if (existsSync(shareDir)) {
         const cur = process.env.XDG_DATA_DIRS ?? '';
         if (!cur.split(pathSep).filter(Boolean).includes(shareDir)) {
-            process.env.XDG_DATA_DIRS = cur ? `${shareDir}${pathSep}${cur}` : shareDir;
+            write('XDG_DATA_DIRS', cur ? `${shareDir}${pathSep}${cur}` : shareDir);
         }
     }
 
@@ -437,18 +490,92 @@ export function maybeWireGtkWindowingEnv() {
         setIfUnset('FONTCONFIG_FILE', fontsConf);
     }
 
-    // THE FACES, which are a different question from the two lines above and on one of the
-    // two platforms not answerable by an environment variable at all.
+    // WHICH FONT MAP PANGO BUILDS AT ALL, which is upstream of the two lines above and is the
+    // assumption neither of them stated. `pangocairo-fontmap.c` picks the FIRST backend
+    // COMPILED IN, in the order coretext → win32 → fc, and `PANGOCAIRO_BACKEND` is the only
+    // thing that overrides it. Both bundles carry every backend their platform builds, so
+    // without this line darwin gets CoreText and win32 gets pangowin32/DirectWrite — and
+    // fontconfig, which everything else here configures, drives nothing.
+    //
+    // MEASURED 2026-09-12 on real hardware — Learn6502 0.8.0 on the published windowing
+    // bundle, macOS 15.7.9 and Windows 11, with the variable exported BY HAND into the
+    // process before launch (nothing in the loader set it then — this line is what changed
+    // that, and the distinction turns out to be the whole story on win32):
+    //
+    //   Tamil    தமிழ்   default backend: TOFU     PANGOCAIRO_BACKEND=fc: renders
+    //   Japanese 日本語   default backend: renders  PANGOCAIRO_BACKEND=fc: renders
+    //
+    // JAPANESE IS NOT A TEST — it came out right in the SAME window of the SAME run in which
+    // Tamil was empty boxes, because both platform maps carry a CJK fallback. What neither
+    // reaches from a GTK process are the Indic faces the OS itself installs (`Tamil Sangam
+    // MN.ttc`, `Nirmala.ttf` — present on both machines, and found immediately by fontconfig).
+    // So anything checking this must use a script the DEFAULT backend genuinely misses; Tamil
+    // is the one that was measured, and `test/font-script-coverage.test.mjs` carries its own
+    // negative control rather than trusting that it still is.
+    //
+    // It was NOT the translation (the UI switched language, only the glyphs were missing), not
+    // a broken fallback chain, not a missing face and not missing configuration: the win32
+    // bundle already ships `etc/fonts/fonts.conf` and the two lines above already point at it.
+    // The configuration was being read by nobody.
+    //
+    // ON WIN32 THIS WRITE ALONE DOES NOT REACH PANGO, and the first reading of that is kept
+    // here because it is the kind of wrong answer that gets re-derived. CI run 34873488108
+    // measured `PANGOCAIRO_BACKEND=fc` in `process.env` and a `PangoCairoWin32FontMap` anyway,
+    // and that was written up as "gvsbuild's pango has no fontconfig backend to select". It has
+    // one. `bin/pangocairo-1.0-0.dll` out of GTK4_Gvsbuild_2026.6.0_x64.zip registers
+    // `PangoCairoFcFontMap` as well as `PangoCairoWin32FontMap`, imports `pangoft2-1.0-0.dll`
+    // and `fontconfig-1.dll`, and carries ` win32 fontconfig` — the string pango prints for an
+    // unknown value — beside the three literals it compares against: `win32`, `fc`,
+    // `fontconfig`. Two things hid that: a `PangoCairo[A-Za-z]*FontMap` regex cannot match the
+    // digits in `Win32`, and `strings` defaults to a 4-character minimum, one more than `fc`
+    // has. An invalid value is also LOUD (`Unknown $PANGOCAIRO_BACKEND value` + a NULL map),
+    // and the run printed none — which was the evidence against the first reading all along.
+    //
+    // WHAT IS ACTUALLY WRONG IS THE REACH OF THE WRITE. `pango_cairo_font_map_new()` reads
+    // plain `getenv()`, not `g_getenv()`. On win32 Node's `process.env` setter is
+    // `uv_os_setenv()`, which is `SetEnvironmentVariableW()` and nothing else — the WIN32
+    // environment block, never the C runtime's own copy, and `getenv()` returns the copy. So
+    // `process.env.PANGOCAIRO_BACKEND` reads back `fc` (Node reads it through
+    // `GetEnvironmentVariableW`), every CHILD process inherits it, every `g_getenv()` reader on
+    // this list sees it — and pango in THIS process sees nothing, takes the `!backend` branch
+    // and builds the platform map. glib documents the split in `g_setenv()` itself and repairs
+    // it by calling `_wputenv()` first and `SetEnvironmentVariableW()` second; that is the
+    // repair here too, and it needs a GLib, which does not exist at module top level. So it
+    // happens on the first `requireGi()` — `mirrorWindowingEnvIntoCrt()` in `gi.js`, over
+    // exactly the writes recorded above. This write stays: it is what the mirror copies, what a
+    // child inherits, and what every GLib reader already uses.
+    //
+    // NOTHING ABOVE CONTRADICTS THE 2026-09-12 WINDOWS MEASUREMENT — both readings are kept
+    // because together they name which half is which. There the variable was in the process at
+    // LAUNCH, so the C runtime had it before any code of ours ran, and Tamil rendered. The
+    // gvsbuild pin was already 2026.6.0 on that date, so those are the same DLLs CI builds
+    // against: same backend, same value, different reach.
     //
-    // `XDG_DATA_DIRS` already reaches `<bundle>/share/fonts` wherever fontconfig drives
-    // Pango — its stock configuration carries `<dir prefix="xdg">fonts</dir>` — so on darwin
-    // the set above is enough and this variable is a second, cheaper route to the same files.
-    // On WIN32 it is the only route there is: GTK4 uses pangowin32, whose font map is filled
-    // exclusively by `pango_font_map_dwrite_populate()` from the DirectWrite system
-    // collection, and a `FONTCONFIG_FILE` naming a directory of faces moves that map by ZERO
-    // families even when it is the only configuration present (measured on Windows 11 /
-    // GTK 4.22.4, both directions — ADR 0038 § W1-W5). The face has to be handed to the map
-    // through `add_font_file`, which is a RUNTIME call somebody has to make.
+    // `setIfUnset`, because an operator who pins `coretext`/`win32` has to win: the price of
+    // this line is a different RASTERISER (FreeType instead of ClearType/CoreText), which is a
+    // preference, while a glyph that never arrives is a defect. No platform branch is needed —
+    // the function has already returned on anything but darwin/win32 — and it is scoped to the
+    // BUNDLE deliberately: fontconfig is a safe choice only where something hands it both a
+    // configuration and faces, which is exactly what a windowing bundle does and what an
+    // arbitrary host's Pango does not owe us.
+    setIfUnset('PANGOCAIRO_BACKEND', 'fc');
+
+    // THE FACES, which are a different question from the three settings above and on the
+    // platform font maps not answerable by an environment variable at all.
+    //
+    // `XDG_DATA_DIRS` reaches `<bundle>/share/fonts` wherever fontconfig drives Pango — its
+    // stock configuration carries `<dir prefix="xdg">fonts</dir>` — which is true only BECAUSE
+    // of the backend selection above. This comment used to read "so on darwin the set above is
+    // enough", and that sentence WAS the defect: nothing made fontconfig the darwin backend, so
+    // the directory was being named to a reader nobody had asked.
+    // It stays the route for any process that ends up on a PLATFORM map — an operator pinning
+    // `win32`/`coretext`, a host GTK, a pango built without the fontconfig backend. GTK4 on
+    // pangowin32 has a font map filled exclusively by `pango_font_map_dwrite_populate()` from
+    // the DirectWrite system collection, so a `FONTCONFIG_FILE` naming a directory of faces
+    // moves THAT map by ZERO families however it is set (measured on Windows 11 / GTK 4.22.4,
+    // both directions — ADR 0038 § W1-W5). The face has to be handed to the map through
+    // `add_font_file`, which is a RUNTIME call somebody has to make — so `initFonts()` stays
+    // wired on both platforms and is not conditional on which map won.
     //
     // So the loader's job here is to name the directory, not to register anything: it runs
     // before the addon loads and has no Pango to talk to. `@gjsify/gtk-host`'s `initFonts()`
@@ -668,3 +795,143 @@ export function activateBundledGtkRuntime(native) {
     activated = bundle;
     return bundle;
 }
+
+// --- OpenGL on win32 (#1097) -------------------------------------------------
+//
+// GTK 4 needs desktop GL >= 3.2 core over WGL on win32 — the gvsbuild GTK is built without
+// EGL, so ANGLE is unreachable, and without Vulkan. A host with no OpenGL ICD (a GPU-less VM,
+// an RDP session, a CI runner) offers only Microsoft's GDI generic OpenGL 1.1, which GDK
+// rejects: every Gtk.GLArea then reads "No GL implementation is available" and GSK falls
+// back to cairo. The OPTIONAL package `@gjsify/gl-runtime-win32-x64` carries Mesa's
+// opengl32.dll for exactly those hosts; it is ~22 MB, so it is a consumer's opt-in and never
+// part of the bundle or a dependency of node-gi (ADR 0023). This decides per process whether
+// it or the host's OpenGL serves GTK. Why it has to be a native preload rather than a PATH
+// entry: src/opengl-win32.cc.
+//
+// `GJSIFY_OPENGL=bundle|system` overrides — `system` keeps a host's OpenGL even when the
+// probe finds no ICD, `bundle` takes Mesa over a vendor driver.
+
+/** The optional GL package's npm name for a platform-arch tag. */
+export function glRuntimePackageName(tag = `${process.platform}-${process.arch}`) {
+    return `@gjsify/gl-runtime-${tag}`;
+}
+
+/**
+ * Where the optional GL package's opengl32.dll is, or null. Resolved BY NAME, like the GTK
+ * bundle: the monorepo sibling first (what CI builds in place), then the installed package.
+ * @returns {string | null}
+ */
+export function resolveGlRuntime() {
+    const tag = `${process.platform}-${process.arch}`;
+    const candidates = [join(here, '..', `gl-runtime-${tag}`, 'bin')];
+    try {
+        candidates.push(join(dirname(require.resolve(glRuntimePackageName(tag))), 'bin'));
+    } catch {
+        // Not installed — the common case; decideOpenGLSource says what that costs.
+    }
+    for (const dir of candidates) {
+        const dll = join(dir, 'opengl32.dll');
+        if (existsSync(dll)) return dll;
+    }
+    return null;
+}
+
+/** @typedef {{ wddmIcd: string, registryIcd: string, loadedFrom: string }} HostOpenGL */
+
+/**
+ * Which OpenGL this process should use. PURE, so every branch runs on any host.
+ *
+ * A host ICD wins by default: Mesa over a real GPU would still work (its d3d12 driver runs on
+ * the hardware) but replaces the vendor's driver for this process, which is a regression
+ * nobody asked for. An opengl32 that is ALREADY loaded is a fact, not a preference — no
+ * override can move it, so it is reported rather than fought. `missing` marks the one case a
+ * consumer can fix: no ICD, no package.
+ *
+ * @param {object} opts
+ * @param {string | null} opts.bundled absolute path of the GL package's opengl32.dll, or null
+ * @param {HostOpenGL} opts.host `native.probeHostOpenGL()`
+ * @param {string} [opts.override] raw `GJSIFY_OPENGL`
+ * @returns {{ source: 'bundle' | 'system', reason: string, missing?: true }}
+ */
+export function decideOpenGLSource({ bundled, host, override }) {
+    if (host.loadedFrom) return { source: 'system', reason: `opengl32 was already loaded from ${host.loadedFrom}` };
+    if (override === 'system') return { source: 'system', reason: 'GJSIFY_OPENGL=system' };
+    if (bundled && override === 'bundle') return { source: 'bundle', reason: 'GJSIFY_OPENGL=bundle' };
+    if (host.wddmIcd)
+        return { source: 'system', reason: `the display driver provides an OpenGL ICD (${host.wddmIcd})` };
+    if (host.registryIcd) return { source: 'system', reason: `an OpenGL ICD is registered (${host.registryIcd})` };
+    if (!bundled) {
+        return {
+            source: 'system',
+            missing: true,
+            reason:
+                'this host has no OpenGL driver (only the GDI generic OpenGL 1.1, which GTK rejects), so ' +
+                'Gtk.GLArea fails and GSK renders with cairo. Add ' +
+                `${glRuntimePackageName('win32-x64')} as a dependency to ship Mesa for such hosts ` +
+                '(VMs, RDP sessions, CI), or set GJSIFY_OPENGL=system to accept this',
+        };
+    }
+    return { source: 'bundle', reason: 'the host has no OpenGL ICD, only the GDI generic OpenGL 1.1' };
+}
+
+let openGL = null;
+
+/**
+ * Apply `decideOpenGLSource` to this process: preload the GL package's opengl32.dll when it
+ * wins. MUST run before anything loads gtk-4-1.dll, which imports OPENGL32 statically —
+ * index.js calls it right after the addon loads. Strict no-op off win32. Idempotent.
+ * @param {{ probeHostOpenGL?: () => HostOpenGL, preloadOpenGL?: (p: string) => string }} native
+ * @param {object} [deps] the host facts this reads, so a spec can drive the win32 advice path
+ *   on a host that has neither win32 nor a bundle: `platform` (default `process.platform`),
+ *   `bundled` (the GL package's opengl32.dll, default `resolveGlRuntime()`), `windowing`
+ *   (default `hasWindowingRuntime()`). Every default is the real reading; no production caller
+ *   passes this — it exists so the warning and the preload fallback are executed by a test at all.
+ * @returns {{ source: 'bundle' | 'system', reason: string, loadedFrom: string | null } | null}
+ */
+export function activateBundledOpenGL(native, deps) {
+    if (openGL !== null) return openGL || null;
+    openGL = false;
+    const platform = deps?.platform ?? process.platform;
+    if (platform !== 'win32' || typeof native?.probeHostOpenGL !== 'function') return null;
+    const candidate = deps?.bundled !== undefined ? deps.bundled : resolveGlRuntime();
+    const host = native.probeHostOpenGL();
+    const decision = decideOpenGLSource({ bundled: candidate, host, override: process.env.GJSIFY_OPENGL });
+    if (decision.source === 'system') {
+        // Said once, at the point the process could still be told what to add — the
+        // alternative is a GLArea painting "No GL implementation is available" with nothing
+        // naming the package. Only where a WINDOWING runtime is present: a headless process
+        // never asks for GL, and this would be noise there.
+        const canOpenWindows = deps?.windowing ?? hasWindowingRuntime();
+        if (decision.missing && canOpenWindows) {
+            process.emitWarning(decision.reason, { code: 'GJSIFY_OPENGL_MISSING' });
+        }
+        openGL = { ...decision, loadedFrom: host.loadedFrom || null };
+        return openGL;
+    }
+    try {
+        openGL = { ...decision, loadedFrom: native.preloadOpenGL(candidate) };
+    } catch (error) {
+        // preloadOpenGL throws with the loader's own reason (a missing libgallium_wgl.dll, a
+        // blocked file). The process still runs — GTK falls back to cairo — so this is a
+        // warning with the cause, where silence would read as "the host has no GL".
+        const reason = `preloading the bundled OpenGL failed: ${error.message}`;
+        process.emitWarning(reason, { code: 'GJSIFY_OPENGL_PRELOAD' });
+        openGL = { source: 'system', reason, loadedFrom: null };
+    }
+    return openGL;
+}
+
+/** TEST-ONLY: drop the memoized decision so a spec can run the activation again. */
+export function resetOpenGLForTests() {
+    openGL = null;
+}
+
+/** Whether the GTK in use can open windows — the bundle's windowing marker. */
+function hasWindowingRuntime() {
+    return !!windowingBundle();
+}
+
+/** What `activateBundledOpenGL` decided for this process, or null when it did not apply. */
+export function openGLActivation() {
+    return openGL || null;
+}

package/index.d.ts

@@ -73,6 +73,17 @@ export function prependSearchPath(path: string): void;
 /** Prepend a directory GI searches for the SHARED LIBRARY a typelib names. */
 export function prependLibraryPath(path: string): void;
 
+/** win32 only: the host's OpenGL ICDs (display driver / registry) and any opengl32 already loaded; each "" when absent. */
+export const probeHostOpenGL: (() => { wddmIcd: string; registryIcd: string; loadedFrom: string }) | undefined;
+/**
+ * win32 only: load an opengl32.dll by ABSOLUTE path and return the path the loaded module
+ * reports. THROWS when the loader refuses it (a missing sibling, a blocked file) — the reason
+ * is in the message, and the caller treats it as "this host has no usable GL", not a crash.
+ */
+export const preloadOpenGL: ((path: string) => string) | undefined;
+/** win32 only: GL_VENDOR/GL_RENDERER/GL_VERSION of the context current on this thread, or null without one. */
+export const currentGLStrings: (() => { vendor: string; renderer: string; version: string } | null) | undefined;
+
 /**
  * Invoke a namespace-level GObject-Introspection function (not an instance
  * method) with primitive/string/object args. OUT and INOUT parameters are
@@ -591,6 +602,9 @@ declare const native: {
     setErrorBuilder: typeof setErrorBuilder;
     prependSearchPath: typeof prependSearchPath;
     prependLibraryPath: typeof prependLibraryPath;
+    probeHostOpenGL: typeof probeHostOpenGL;
+    preloadOpenGL: typeof preloadOpenGL;
+    currentGLStrings: typeof currentGLStrings;
     callFunction: typeof callFunction;
     callMethod: typeof callMethod;
     hasMethod: typeof hasMethod;

package/index.js

@@ -11,6 +11,7 @@ import { hostTarget, nativeCandidates, packageRoot } from './native-paths.js';
 import { describeAddonLoadFailure } from './load-diagnostics.js';
 import {
     activateBundledGtkRuntime,
+    activateBundledOpenGL,
     activateGiLibraryPath,
     maybePrependGtkRuntimeDllPath,
     maybeReexecForGtkRuntime,
@@ -30,9 +31,12 @@ maybeReexecForGtkRuntime();
 // g_module_open of typelib backers — no re-exec needed.
 maybePrependGtkRuntimeDllPath();
 
-// Windows full-windowing GTK: point GSETTINGS_SCHEMA_DIR / GDK_PIXBUF_MODULE_FILE /
-// XDG_DATA_DIRS / FONTCONFIG_* at the data a real GTK window needs. Strict no-op for
-// the display-free bundle, which therefore loads byte-unchanged.
+// Windows/macOS full-windowing GTK: point GSETTINGS_SCHEMA_DIR / GDK_PIXBUF_MODULE_FILE /
+// XDG_DATA_DIRS / FONTCONFIG_* at the data a real GTK window needs, and PANGOCAIRO_BACKEND
+// at the one backend that reads any of the font half. Strict no-op for the display-free
+// bundle, which therefore loads byte-unchanged. On win32 these writes reach the Win32
+// environment block ONLY — gi.js replays them into the C runtime's copy on the first
+// requireGi(), which is the environment pango's and fontconfig's getenv() read.
 maybeWireGtkWindowingEnv();
 
 const require = createRequire(import.meta.url);
@@ -125,6 +129,11 @@ try {
     // Never fatal: a missing/partial bundle just leaves the host GTK in charge.
 }
 
+// win32: decide whether the bundle's Mesa opengl32.dll or the host's OpenGL serves GTK, and
+// preload the bundled one when it wins. Here because gtk-4-1.dll imports OPENGL32 statically,
+// so it must happen before any namespace loads GTK. Reports rather than throws.
+activateBundledOpenGL(native);
+
 // Every OTHER staged prebuild typelib (@gjsify/webkit-native and its kin): same
 // env-free treatment, so a namespace whose typelib is installed in node_modules
 // resolves under a plain `node app.mjs` and not only under `gjsify run`. Deliberately
@@ -302,4 +311,10 @@ export const textdomain = native.textdomain;
 export const bindtextdomain = native.bindtextdomain;
 export const localeCategories = native.localeCategories;
 
+// win32 only (undefined elsewhere): which OpenGL the process got — see gtk-runtime.js
+// activateBundledOpenGL. currentGLStrings asks the implementation behind the context
+// current on this thread, so a caller can tell Mesa from a vendor driver.
+export const probeHostOpenGL = native.probeHostOpenGL;
+export const currentGLStrings = native.currentGLStrings;
+
 export default native;