@gjsify/node-gi 0.52.0 → 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

@@ -36,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.
@@ -1304,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 —
@@ -2298,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)));
             };
         }
     }

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

@@ -89,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
@@ -308,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;
@@ -415,13 +431,10 @@ 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
@@ -782,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,
@@ -128,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
@@ -305,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "GObject-Introspection runtime for Node.js — load gi:// namespaces (GLib/GObject/Gio/…) with GJS-compatible semantics. Vendored + rewritten from node-gtk under MIT.",
   "type": "module",
   "license": "MIT",
@@ -88,23 +88,23 @@
     "build:prebuild": "node-gyp rebuild && node scripts/stage-prebuild.mjs",
     "rebuild": "node-gyp rebuild",
     "clean": "node-gyp clean",
-    "test": "LC_ALL=C NODE_GI_NATIVE=build node --test",
-    "test:node": "LC_ALL=C NODE_GI_NATIVE=build node --test",
-    "test:gc": "LC_ALL=C NODE_GI_NATIVE=build node --test --expose-gc",
-    "test:dbus": "dbus-run-session --config-file=test/session.conf -- env LC_ALL=C NODE_GI_NATIVE=build node --test --expose-gc test/dbus.test.mjs test/dbus-async.test.mjs",
+    "test": "node scripts/pinned-env.mjs --test",
+    "test:node": "node scripts/pinned-env.mjs --test",
+    "test:gc": "node scripts/pinned-env.mjs --test --expose-gc",
+    "test:dbus": "dbus-run-session --config-file=test/session.conf -- node scripts/pinned-env.mjs --test --expose-gc test/dbus.test.mjs test/dbus-async.test.mjs",
     "test:bun": "node scripts/cross-runtime.mjs bun",
     "test:conformance": "node scripts/conformance.mjs",
     "test:conformance:gjs-napi": "node scripts/conformance.mjs --runtimes=gjs-napi",
     "test:gimarshalling": "node scripts/gimarshalling.mjs",
     "test:deno": "node scripts/cross-runtime.mjs deno",
-    "test:cairo": "LC_ALL=C NODE_GI_NATIVE=build node --test test/cairo.test.mjs",
-    "test:cairo-canvas2d": "LC_ALL=C NODE_GI_NATIVE=build node --test test/cairo-canvas2d.test.mjs",
-    "test:gtk": "LC_ALL=C NODE_GI_NATIVE=build node --test test/gtk-smoke.test.mjs",
-    "test:gtk-cairo": "LC_ALL=C NODE_GI_NATIVE=build node --test test/cairo-drawfunc.test.mjs",
-    "test:adw": "LC_ALL=C NODE_GI_NATIVE=build node --test test/adw-smoke.test.mjs",
-    "test:gtk-template": "LC_ALL=C NODE_GI_NATIVE=build node --test test/gtk-template.test.mjs",
-    "test:gtk-template-callbacks": "LC_ALL=C NODE_GI_NATIVE=build node --test test/gtk-template-callbacks.test.mjs",
-    "test:gtk-template-signals": "LC_ALL=C NODE_GI_NATIVE=build node --test test/gtk-template-signals.test.mjs"
+    "test:cairo": "node scripts/pinned-env.mjs --test test/cairo.test.mjs",
+    "test:cairo-canvas2d": "node scripts/pinned-env.mjs --test test/cairo-canvas2d.test.mjs",
+    "test:gtk": "node scripts/pinned-env.mjs --test test/gtk-smoke.test.mjs",
+    "test:gtk-cairo": "node scripts/pinned-env.mjs --test test/cairo-drawfunc.test.mjs",
+    "test:adw": "node scripts/pinned-env.mjs --test test/adw-smoke.test.mjs",
+    "test:gtk-template": "node scripts/pinned-env.mjs --test test/gtk-template.test.mjs",
+    "test:gtk-template-callbacks": "node scripts/pinned-env.mjs --test test/gtk-template-callbacks.test.mjs",
+    "test:gtk-template-signals": "node scripts/pinned-env.mjs --test test/gtk-template-signals.test.mjs"
   },
   "dependencies": {
     "node-addon-api": "^8.0.0"

package/src/addon.cc

@@ -155,6 +155,7 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("localeCategories", Napi::Function::New(env, LocaleCategories));
   // The native cairo binding + foreign-struct registration (the `__cairo` export).
   InitCairo(env, exports);
+  InitOpenGLWin32(env, exports);
   return exports;
 }
 

package/src/calls.cc

@@ -223,58 +223,34 @@ static void NodeGiCallbackTrampoline(ffi_cif* /*cif*/, void* result, void** args
   if (cb->scope != GI_SCOPE_TYPE_CALL) depthReset = std::make_unique<SyncEmitDepthReset>();
 
   GICallableInfo* ci = cb->info;
-  unsigned int n = gi_callable_info_get_n_args(ci);
+  // Arguments and the answer in gjs's OUT/INOUT shape, shared with the vfunc
+  // trampoline (CToJsCall, marshal.cc): a pure OUT is not a JS argument and is
+  // written back from the return value. ffi hands each argument's storage as
+  // args[i] (a user_data/void IN arg marshals to undefined, which JS ignores).
+  CToJsCall call(napiEnv, ci, std::string("callback '") +
+                                  gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ci)) + "'");
   std::vector<napi_value> jsArgs;
-  jsArgs.reserve(n);
-  bool ok = true;
-  for (unsigned int i = 0; i < n; i++) {
-    GIArgInfo* ai = gi_callable_info_get_arg(ci, i);
-    GITypeInfo* ti = gi_arg_info_get_type_info(ai);
-    // ffi hands each argument's storage as args[i]; reinterpret as a GIArgument
-    // union (a user_data/void arg marshals to undefined, which JS ignores).
-    Napi::Value v = GIArgumentToJs(napiEnv, ti, static_cast<GIArgument*>(args[i]), GI_TRANSFER_NOTHING);
-    gi_base_info_unref(ti);
-    gi_base_info_unref(ai);
-    if (napiEnv.IsExceptionPending()) {
-      ok = false;
-      break;
-    }
-    jsArgs.push_back(v);
-  }
+  bool ok = call.MarshalArgs(args, 0, &jsArgs);
 
   // Zero the result slot first (it is >= ffi_arg wide; narrow returns leave the
   // upper bytes indeterminate otherwise).
   if (result != nullptr) static_cast<GIArgument*>(result)->v_uint64 = 0;
 
-  GITypeInfo* retType = gi_callable_info_get_return_type(ci);
+  napi_value ret = nullptr;
   if (ok) {
     napi_value fn = nullptr;
     if (napi_get_reference_value(env, cb->jsFn, &fn) == napi_ok && fn != nullptr) {
       napi_value global = nullptr;
       napi_get_global(env, &global);
-      napi_value ret = nullptr;
       // napi_make_callback drains nextTick/microtasks around the call (Node; on
       // Bun/Deno the checkpoint is run by NodeGiMaybeDrainMicrotasks below).
       g_loopDispatchDepth++;
       napi_status st = napi_make_callback(env, nullptr, global, fn, jsArgs.size(), jsArgs.data(), &ret);
       g_loopDispatchDepth--;
-      if (st == napi_ok && result != nullptr) {
-        GITypeTag rtag = gi_type_info_get_tag(retType);
-        if (rtag == GI_TYPE_TAG_UTF8 || rtag == GI_TYPE_TAG_FILENAME) {
-          // Hand the caller an owned copy — a JsToGIArgument string would point
-          // into a std::string that dies with this frame.
-          Napi::Value rv(env, ret);
-          static_cast<GIArgument*>(result)->v_string =
-              rv.IsString() ? g_strdup(rv.As<Napi::String>().Utf8Value().c_str()) : nullptr;
-        } else if (rtag != GI_TYPE_TAG_VOID) {
-          std::string held;
-          JsToGIArgument(napiEnv, Napi::Value(env, ret), retType, static_cast<GIArgument*>(result),
-                         &held);
-        }
-      }
+      if (st != napi_ok) ret = nullptr;
     }
   }
-  gi_base_info_unref(retType);
+  call.WriteAnswer(ret, result);
   // A CALL-scope callback (e.g. a list `foreach`) runs synchronously inside a
   // JS-initiated GI invoke, so a pending exception must propagate to that JS
   // caller — leave it to surface at the invoke's N-API boundary. A NOTIFIED/ASYNC

package/src/class.cc

@@ -223,37 +223,27 @@ static void NodeGiVFuncTrampoline(ffi_cif* /*cif*/, void* result, void** args,
 
   GICallableInfo* ci = reinterpret_cast<GICallableInfo*>(vf->info);
   // args[0] is the instance; declared args follow at args[1..].
-  Napi::Value recv = WrapGObject(
-      napiEnv, static_cast<GObject*>(static_cast<GIArgument*>(args[0])->v_pointer),
-      GI_TRANSFER_NOTHING);
-
-  unsigned int n = gi_callable_info_get_n_args(ci);
+  GObject* instance = static_cast<GObject*>(static_cast<GIArgument*>(args[0])->v_pointer);
+  Napi::Value recv = WrapGObject(napiEnv, instance, GI_TRANSFER_NOTHING);
+
+  // Arguments and the answer in gjs's OUT/INOUT shape, shared with the GI-callback
+  // trampoline (CToJsCall, marshal.cc). args[0] is the instance, so the declared
+  // arguments start at offset 1. `instance` is also the owner a transfer-none string
+  // answer ties its lifetime to (StringForC, marshal.cc) instead of interning it
+  // forever — a real vfunc can answer a fresh string every call (e.g.
+  // Gtk.Editable's vfunc_get_text on a live-updating buffer).
+  CToJsCall call(napiEnv, ci, "vfunc '" + vf->name + "'", instance);
   std::vector<napi_value> jsArgs;
-  jsArgs.reserve(n);
-  bool ok = true;
-  for (unsigned int i = 0; i < n; i++) {
-    GIArgInfo* ai = gi_callable_info_get_arg(ci, i);
-    GITypeInfo* ti = gi_arg_info_get_type_info(ai);
-    Napi::Value v =
-        GIArgumentToJs(napiEnv, ti, static_cast<GIArgument*>(args[i + 1]), GI_TRANSFER_NOTHING);
-    gi_base_info_unref(ti);
-    gi_base_info_unref(ai);
-    if (napiEnv.IsExceptionPending()) {
-      ok = false;
-      break;
-    }
-    jsArgs.push_back(v);
-  }
+  bool ok = call.MarshalArgs(args, 1, &jsArgs);
 
   // Zero the result slot first (it is >= ffi_arg wide; narrow returns leave the
   // upper bytes indeterminate otherwise).
   if (result != nullptr) static_cast<GIArgument*>(result)->v_uint64 = 0;
 
-  GITypeInfo* retType = gi_callable_info_get_return_type(ci);
+  napi_value ret = nullptr;
   if (ok) {
     napi_value fn = nullptr;
     if (napi_get_reference_value(env, vf->fn, &fn) == napi_ok && fn != nullptr) {
-      napi_value ret = nullptr;
       // napi_make_callback drains nextTick/microtasks around the call (Node; on
       // Bun/Deno the checkpoint is run by NodeGiMaybeDrainMicrotasks below); the
       // wrapped instance is the receiver (`this`).
@@ -261,23 +251,10 @@ static void NodeGiVFuncTrampoline(ffi_cif* /*cif*/, void* result, void** args,
       napi_status st =
           napi_make_callback(env, nullptr, recv, fn, jsArgs.size(), jsArgs.data(), &ret);
       g_loopDispatchDepth--;
-      if (st == napi_ok && result != nullptr) {
-        GITypeTag rtag = gi_type_info_get_tag(retType);
-        if (rtag == GI_TYPE_TAG_UTF8 || rtag == GI_TYPE_TAG_FILENAME) {
-          // Hand the caller an owned copy — a JsToGIArgument string would point
-          // into a std::string that dies with this frame.
-          Napi::Value rv(env, ret);
-          static_cast<GIArgument*>(result)->v_string =
-              rv.IsString() ? g_strdup(rv.As<Napi::String>().Utf8Value().c_str()) : nullptr;
-        } else if (rtag != GI_TYPE_TAG_VOID) {
-          std::string held;
-          JsToGIArgument(napiEnv, Napi::Value(env, ret), retType, static_cast<GIArgument*>(result),
-                         &held);
-        }
-      }
+      if (st != napi_ok) ret = nullptr;
     }
   }
-  gi_base_info_unref(retType);
+  call.WriteAnswer(ret, result);
   // A pending JS exception surfaces at the next N-API boundary (e.g. when the
   // constructType / method call that triggered this vfunc returns).
   //

package/src/common.h

@@ -176,6 +176,8 @@ const ForeignStructOps* ForeignOpsForInfo(GIBaseInfo* iface);
 // from addon.cc's Init; sets the `__cairo` export + registers Context/Surface/
 // Pattern foreign converters.
 void InitCairo(Napi::Env env, Napi::Object exports);
+// win32: probeHostOpenGL / preloadOpenGL / currentGLStrings (opengl-win32.cc); a no-op elsewhere.
+void InitOpenGLWin32(Napi::Env env, Napi::Object exports);
 
 // ---- GJS-exact 64-bit integer marshalling helpers (shared) -------------------
 //
@@ -413,6 +415,42 @@ bool IsSupportedContainerType(GITypeInfo* type, std::string* why, ContainerUse u
 // function-invoke path (calls.cc) and the vfunc chain-up path (class.cc).
 bool IsSupportedOutType(GITypeInfo* type, std::string* why);
 size_t CElementSize(GITypeInfo* elem);
+// One call C makes INTO JS — a JS vfunc override (class.cc) or a GI callback
+// (calls.cc) — marshalled in gjs's OUT/INOUT shape (see marshal.cc). Lives on the
+// trampoline's stack under its HandleScope; `ci` is borrowed.
+class CToJsCall {
+ public:
+  // `owner` is the vfunc's instance (class.cc passes args[0]'s GObject*); nullptr for a
+  // plain GI callback (calls.cc), which has no natural object. Only used to tie a
+  // transfer-none string ANSWER's lifetime to something bounded (StringForC,
+  // marshal.cc) — gjs's own fallback (g_intern_string, unbounded) when there is none.
+  CToJsCall(Napi::Env env, GICallableInfo* ci, std::string label, GObject* owner = nullptr);
+  ~CToJsCall();
+  CToJsCall(const CToJsCall&) = delete;
+  CToJsCall& operator=(const CToJsCall&) = delete;
+  // The JS arguments from the ffi args (`args[offset + i]` is declared arg i): IN as
+  // values, INOUT as their current value, pure OUT omitted. False = exception pending.
+  bool MarshalArgs(void** args, unsigned int offset, std::vector<napi_value>* jsArgs);
+  // Write JS's answer back: the return value into `result` (already zeroed by the
+  // caller), the OUT/INOUT through their pointers. A wrong shape or a failed
+  // conversion throws; every pure OUT left unanswered is zeroed, never uninitialised.
+  // `ret` is nullptr when the JS call itself failed.
+  void WriteAnswer(napi_value ret, void* result);
+
+ private:
+  struct Slot {
+    GIArgInfo* ai;   // owned
+    GITypeInfo* ti;  // owned
+    gpointer dest;   // the caller's variable (or caller-allocated record); may be NULL
+  };
+  void ThrowUnsupported(const Slot& s) const;
+  bool WriteOut(const Slot& s, Napi::Value v);
+  Napi::Env env_;
+  GICallableInfo* ci_;
+  std::string label_;
+  GObject* owner_;  // borrowed; see the constructor comment
+  std::vector<Slot> outs_;
+};
 void WriteLengthValue(GITypeInfo* lenType, GIArgument* slot, long n);
 
 // One IN length-argument autofill, remembered so a SECOND array naming the same length