@gjsify/node-gi 0.40.0 → 0.42.0

package/README.md

@@ -609,8 +609,7 @@ shared per-instance JS object yet), so use GObject **properties** for any state
 that must be visible both inside a vfunc and on the instance (those live in C and
 are consistent; the unified instance identity arrives with the toggle-ref work);
 a JS↔GObject reference cycle on a custom instance leaks (the same cycle-leak
-caveat the signal/vfunc layer carries); and multi-level registered subclass
-chains (registering a subclass of a registered subclass) are not yet supported.
+caveat the signal/vfunc layer carries).
 
 #### `GObject` conveniences (signals, `GObject.Value`, `Object.new`)
 

package/gtk-runtime.js

@@ -399,14 +399,22 @@ export function maybeWireGtkWindowingEnv() {
     setIfUnset('GSETTINGS_SCHEMA_DIR', schemaDir);
 
     // MODULE_FILE is the load-bearing one on BOTH platforms — it is the cache, and the
-    // cache is what names the modules. MODULEDIR only resolves a RELATIVE module path in
-    // that cache, and only where gdk-pixbuf was built relocatable: measured on macOS with
-    // Homebrew's gdk-pixbuf 2.44.7, the string `GDK_PIXBUF_MODULEDIR` is not in the dylib
-    // at all, so the darwin bundle's cache instead names each module `@loader_path/…`
-    // (relative to the image that dlopens it, i.e. the bundle's lib/) and resolves with no
-    // env beyond this file. gvsbuild's win32 build IS relocatable, so MODULEDIR is what
-    // its bare-leaf cache needs — hence both are set, and neither platform depends on the
-    // other's mechanism.
+    // cache is what names the modules. It is also the ONLY variable gdk-pixbuf's runtime
+    // reads: `GDK_PIXBUF_MODULEDIR` is read by queryloaders.c, the GENERATOR, where it
+    // merely picks the directory to scan. This comment used to claim the opposite — that
+    // MODULEDIR is "what its bare-leaf cache needs" on win32 — and the win32 builder wrote
+    // a bare-leaf cache on the strength of it. gdk-pixbuf 2.44.6's `build_module_path()`
+    // joins a relative cache entry with the bundle TOPLEVEL instead, so every leaf resolved
+    // to `<bundle>\<leaf>` and no SVG icon has ever decoded from a win32 bundle (#996).
+    // The cache is written toplevel-relative now; see scripts/pixbuf-loader-cache.mjs.
+    //
+    // darwin needs neither: Homebrew's gdk-pixbuf 2.44.7 has no `GDK_PIXBUF_MODULEDIR`
+    // string in the dylib at all, so that cache names each module `@loader_path/…`
+    // (relative to the image that dlopens it, i.e. the bundle's lib/) and dyld resolves it
+    // with no env beyond this file.
+    //
+    // MODULEDIR is still set, and still only if unset: it costs nothing, and it is what a
+    // consumer regenerating the cache in-process would need. Nothing here depends on it.
     const loaderCache = join(bundle.dir, 'lib', 'gdk-pixbuf-2.0', '2.10.0', 'loaders.cache');
     if (existsSync(loaderCache)) {
         setIfUnset('GDK_PIXBUF_MODULEDIR', join(bundle.dir, 'lib', 'gdk-pixbuf-2.0', '2.10.0', 'loaders'));

package/load-diagnostics.js

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 // @gjsify/node-gi/load-diagnostics — what a user is told when the addon FILE is
-// present and still will not load.
+// present and still will not load. TWO causes reach the same catch and they get
+// DIFFERENT answers: the loader could not resolve the specifier, or it resolved
+// it and the OS refused the binary. Only the second is about GTK.
 //
 // A MODULE OF ITS OWN, and that is the point: `index.js` loads the native addon
 // at evaluation time, so anything living there can only be imported by a process
@@ -13,6 +15,41 @@
 import { hostTarget } from './native-paths.js';
 import { gtkSource } from './gtk-runtime.js';
 
+/**
+ * Did the loader fail to RESOLVE the specifier, rather than to load the binary?
+ *
+ * Two entirely different failures arrive at the same `catch`, and only one of
+ * them is about GTK:
+ *
+ *   • dlopen/LoadLibrary said no — the file was found, and its dependency
+ *     closure (or its ABI) is the problem. That is the case the long GTK
+ *     explanation below describes.
+ *   • `require()` never got as far as the file. The specifier was neither
+ *     absolute nor `./`-led, so it was looked up as a MODULE — against this
+ *     package's directory and node_modules, never against the process's cwd that
+ *     the `existsSync()` one line earlier had just resolved it against.
+ *
+ * THE INCIDENT (#996 / PR #1239), and why this discriminator exists at all:
+ * node-gi.yml hands the GTK bundle builder a repo-relative `--stage`, the builder
+ * passed that straight through as `NODE_GI_NATIVE`, and all four darwin bundle
+ * legs failed with `Cannot find module 'packages/node-gi/…'` underneath a
+ * confident five-line account of the Homebrew dependency closure ending in
+ * "Reinstall @gjsify/gtk-runtime-darwin-arm64". Every word of that advice was
+ * wrong for the cause, and it is the advice a stranger would have followed. The
+ * path bug itself is fixed in `native-paths.js#nativeCandidates()`; this stays
+ * because the next relative path to reach a `require()` will not come from there.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isResolutionFailure(err) {
+    if (!err || typeof err !== 'object') return false;
+    const { code, message } = /** @type {{ code?: unknown, message?: unknown }} */ (err);
+    if (code === 'MODULE_NOT_FOUND' || code === 'ERR_MODULE_NOT_FOUND') return true;
+    // Bun, Deno and the GJS napi shim raise the same condition without Node's
+    // code, so the message is a fallback rather than the primary test.
+    return typeof message === 'string' && /cannot find module|module not found/i.test(message);
+}
+
 /**
  * Turn a failed addon load into something the reader can act on.
  *
@@ -34,6 +71,27 @@ export function describeAddonLoadFailure(addonPath, err, ctx = {}) {
     const target = ctx.target ?? hostTarget();
     const reason = err instanceof Error ? err.message : String(err);
 
+    // A resolution failure gets no GTK answer. Returning early is what keeps the
+    // dependency-closure explanation for the case it actually describes — see
+    // isResolutionFailure() for what it cost when the two shared one message.
+    if (isResolutionFailure(err)) {
+        return [
+            `@gjsify/node-gi: the native addon path could not be RESOLVED.`,
+            `  addon: ${addonPath}`,
+            `  cause: ${reason}`,
+            '',
+            `This is a module-RESOLUTION failure, NOT a missing GTK dependency: the`,
+            `loader never reached the file, so nothing here is evidence about glib,`,
+            `gobject, girepository or a runtime bundle. A path that is neither absolute`,
+            `nor written with a leading ./ is resolved by require() as a MODULE`,
+            `specifier — against @gjsify/node-gi's own directory and node_modules,`,
+            `never against the working directory of the process that set it.`,
+            '',
+            `Pass an ABSOLUTE path:`,
+            `  NODE_GI_NATIVE=/absolute/path/to/node_gi.node`,
+        ].join('\n');
+    }
+
     const lines = [
         `@gjsify/node-gi: the native addon exists but could not be loaded.`,
         `  addon: ${addonPath}`,

package/native-paths.js

@@ -26,7 +26,7 @@
 // definitions; this file is the authority for node-gi's own binary, and the third
 // copy is the one that must never be written.
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 
 /**
  * The package root. This module sits beside `index.js`, so its own directory IS
@@ -89,6 +89,15 @@ export function buildAddonPath(flavor = 'Release') {
  * Default order: prefer a shipped prebuild so a consumer needs no C toolchain and
  * no node-gyp — the only install path Deno supports (it runs no postinstall build
  * script). Fall back to a locally built addon (Release, then Debug).
+ *
+ * Every candidate is ABSOLUTE, including a pinned one, and that is load-bearing
+ * rather than tidiness: `loadNative()` tests a candidate with `existsSync()` (which
+ * reads a relative path against the CWD) and hands the SAME string to `require()`
+ * (which reads a bare one as a MODULE specifier, against this package's directory).
+ * A relative pin therefore passed the check and failed the load. Resolving HERE,
+ * where the string enters the package, is what makes the two ask about one file.
+ * The incident it cost, and the misdiagnosis it wore: load-diagnostics.js
+ * `isResolutionFailure`.
  * @param {Record<string, string | undefined>} [env] defaults to `process.env`
  * @returns {string[]}
  */
@@ -99,6 +108,9 @@ export function nativeCandidates(env = process.env) {
     const prefer = env.NODE_GI_NATIVE;
     if (prefer === 'build') return [release, debug, prebuild];
     if (prefer === 'prebuild') return [prebuild];
-    if (prefer) return [prefer]; // an explicit path to a node_gi.node
+    // An explicit path to a node_gi.node. `resolve()` keeps an absolute path
+    // byte-identical and gives a relative one the cwd meaning `existsSync` would
+    // have read into it anyway — so the check and the load name the same file.
+    if (prefer) return [resolve(prefer)];
     return [prebuild, release, debug];
 }

package/package.json

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

package/src/class.cc

@@ -669,8 +669,6 @@ static void NodeGiClassInit(gpointer g_class, gpointer class_data) {
 // return-tuple convention `[returnValue?, ...outArgs]` — one value bare, several as
 // an Array, matching exactly what a JS override of that vfunc receives as its call
 // args. Read-back reuses ReadOutOrReturn (array-length slots, containers, boxed).
-// INOUT containers stay deferred (the same rare, ownership-tricky case the function
-// path defers) with a clear, catchable throw BEFORE the ffi_call.
 //
 // MULTI-LEVEL chain-up (registered chains, G2): chains to the DEEPEST registered
 // override's captured parent (the C-side default below the whole registered chain),

package/src/marshal.cc

@@ -1736,14 +1736,134 @@ static bool ReadFieldArg(GIFieldInfo* field, gpointer base, GITypeInfo* ftype,
   return false;
 }
 
-// Marshal a field GIArgument to JS. ARRAY tags dispatch to GIArrayToJs (length
-// derived from zero-terminated / fixed-size — the common GStrv field case);
-// everything else through GIArgumentToJs. TRANSFER NOTHING throughout — a field
-// read is a borrow (the container keeps ownership), so the JS value is a copy and
-// no container/element memory is freed.
-static Napi::Value FieldArgToJs(Napi::Env env, GITypeInfo* ftype, GIArgument* arg) {
+// Field #`index` of a struct/union, or nullptr. The by-NAME lookup is
+// `FindBoxedField`; this is the by-POSITION one an `array length=` annotation needs.
+static GIFieldInfo* BoxedFieldAt(GIBaseInfo* owner, unsigned index) {
+  if (GI_IS_STRUCT_INFO(owner)) {
+    GIStructInfo* s = reinterpret_cast<GIStructInfo*>(owner);
+    return index < gi_struct_info_get_n_fields(s) ? gi_struct_info_get_field(s, index) : nullptr;
+  }
+  if (GI_IS_UNION_INFO(owner)) {
+    GIUnionInfo* u = reinterpret_cast<GIUnionInfo*>(owner);
+    return index < gi_union_info_get_n_fields(u) ? gi_union_info_get_field(u, index) : nullptr;
+  }
+  return nullptr;
+}
+
+// Can `ReadCElement` actually read this array's elements?
+//
+// Resolving a length is only ever an improvement where the reader can then walk that
+// many elements. Two shapes it cannot: an element tag it answers with `Undefined()`
+// (its `default:`), and an INLINE (by-value) interface element — for those it
+// dereferences `src` as a pointer while `CElementSize` reports `sizeof(gpointer)`
+// rather than the record's real size, so a resolved length walks garbage. Measured:
+// `new Pango.GlyphString(); gs.set_size(3); gs.glyphs[0].glyph` SIGSEGVs with a
+// length and returns an empty array without one.
+//
+// `calls.cc` draws exactly this line at its own CALLER_ALLOCATES site, with the same
+// reason recorded there — a by-value element array needs `gi_struct_info_get_size`
+// per element plus a field-access read-back. That is ONE deferred piece of work, and
+// this predicate keeps the field path on the same side of it rather than opening a
+// second, crashing entrance to it.
+static bool ElementsAreReadable(GITypeInfo* type) {
+  GITypeInfo* elem = gi_type_info_get_param_type(type, 0);
+  if (elem == nullptr) return false;
+  bool readable;
+  switch (gi_type_info_get_tag(elem)) {
+    case GI_TYPE_TAG_BOOLEAN:
+    case GI_TYPE_TAG_INT8:
+    case GI_TYPE_TAG_UINT8:
+    case GI_TYPE_TAG_INT16:
+    case GI_TYPE_TAG_UINT16:
+    case GI_TYPE_TAG_INT32:
+    case GI_TYPE_TAG_UINT32:
+    case GI_TYPE_TAG_INT64:
+    case GI_TYPE_TAG_UINT64:
+    case GI_TYPE_TAG_FLOAT:
+    case GI_TYPE_TAG_DOUBLE:
+    case GI_TYPE_TAG_UTF8:
+    case GI_TYPE_TAG_FILENAME:
+      readable = true;
+      break;
+    // A pointer array of interfaces is a `gpointer` per slot, which is what
+    // `ReadCElement` reads. By value it is the record itself, which is not.
+    case GI_TYPE_TAG_INTERFACE:
+      readable = gi_type_info_is_pointer(elem);
+      break;
+    default:
+      readable = false;
+      break;
+  }
+  gi_base_info_unref(elem);
+  return readable;
+}
+
+// The element count for an array FIELD whose GIR carries `array length=<n>`,
+// meaning "sibling field <n> of this same struct holds it".
+//
+// This is the one GIArrayToJs call site that used to pass a hard `-1`, and the cost
+// was silence: `GstMapInfo.data` is `<array length="3" c:type="guint8*">` with field 3
+// being `size`, so a mapped 32-byte buffer marshalled as `size=32, data.length=0` — no
+// error, no warning, an empty array indistinguishable from a genuinely empty one. That
+// made audio inaudible on node for an entire investigation because every layer above
+// reported success. gjs reads 32 for the identical struct.
+//
+// The ledger entry that recorded this said the dependency was one "GI cannot express
+// for a struct-field READ". It can, and does: the annotation is in the GIR and survives
+// into the typelib, which is why the CALL-argument path (`calls.cc`) has resolved it for
+// as long as it has existed. Only the field reader ignored it.
+//
+// Returns false when there is no annotation, when the index is out of range, or when
+// the sibling is not integer-typed — all of which leave the caller on its previous
+// zero-terminated/fixed-size derivation rather than inventing a length.
+static bool FieldArrayLength(GITypeInfo* ftype, GIBaseInfo* owner, gpointer base, long* out) {
+  unsigned int index = 0;
+  if (!gi_type_info_get_array_length_index(ftype, &index)) return false;
+  if (!ElementsAreReadable(ftype)) return false;
+  GIFieldInfo* lengthField = BoxedFieldAt(owner, index);
+  if (lengthField == nullptr) return false;
+
+  bool resolved = false;
+  GITypeInfo* ltype = gi_field_info_get_type_info(lengthField);
+  if (ltype != nullptr) {
+    GIArgument larg;
+    if (ReadFieldArg(lengthField, base, ltype, &larg)) {
+      switch (gi_type_info_get_tag(ltype)) {
+        case GI_TYPE_TAG_INT8: *out = larg.v_int8; resolved = true; break;
+        case GI_TYPE_TAG_UINT8: *out = larg.v_uint8; resolved = true; break;
+        case GI_TYPE_TAG_INT16: *out = larg.v_int16; resolved = true; break;
+        case GI_TYPE_TAG_UINT16: *out = larg.v_uint16; resolved = true; break;
+        case GI_TYPE_TAG_INT32: *out = larg.v_int32; resolved = true; break;
+        case GI_TYPE_TAG_UINT32: *out = static_cast<long>(larg.v_uint32); resolved = true; break;
+        case GI_TYPE_TAG_INT64: *out = static_cast<long>(larg.v_int64); resolved = true; break;
+        case GI_TYPE_TAG_UINT64: *out = static_cast<long>(larg.v_uint64); resolved = true; break;
+        default: break;  // non-integer sibling: not a length, leave it alone
+      }
+    }
+    gi_base_info_unref(ltype);
+  }
+  gi_base_info_unref(lengthField);
+  // A signed length field holding a negative value is a broken typelib, not a count.
+  // Declining sends it down the zero-terminated/fixed-size derivation the caller would
+  // have used anyway — which is also what a negative reaching `GIArrayToJs` does, so this
+  // changes no observable behaviour today. It is here to keep the CONTRACT of this
+  // function honest: it returns a resolved element count or nothing.
+  if (resolved && *out < 0) resolved = false;
+  return resolved;
+}
+
+// Marshal a field GIArgument to JS. ARRAY tags dispatch to GIArrayToJs with the
+// length resolved from an `array length=` sibling field where the GIR declares one,
+// and otherwise derived from zero-terminated / fixed-size (the common GStrv field
+// case). Everything else goes through GIArgumentToJs. TRANSFER NOTHING throughout —
+// a field read is a borrow (the container keeps ownership), so the JS value is a copy
+// and no container/element memory is freed.
+static Napi::Value FieldArgToJs(Napi::Env env, GITypeInfo* ftype, GIArgument* arg,
+                                GIBaseInfo* owner, gpointer base) {
   if (gi_type_info_get_tag(ftype) == GI_TYPE_TAG_ARRAY) {
-    return GIArrayToJs(env, ftype, arg, GI_TRANSFER_NOTHING, /*length=*/-1);
+    long length = -1;
+    if (!FieldArrayLength(ftype, owner, base, &length)) length = -1;
+    return GIArrayToJs(env, ftype, arg, GI_TRANSFER_NOTHING, length);
   }
   return GIArgumentToJs(env, ftype, arg, GI_TRANSFER_NOTHING);
 }
@@ -1854,7 +1974,7 @@ Napi::Value GetBoxedField(const Napi::CallbackInfo& info) {
     }
     GIArgument arg;
     if (ReadFieldArg(field, bh->ptr, ftype, &arg)) {
-      result = FieldArgToJs(env, ftype, &arg);
+      result = FieldArgToJs(env, ftype, &arg, ti, bh->ptr);
     } else {
       Napi::Error::New(env, std::string("Reading field ") + typeName + "." + name + " is not supported")
           .ThrowAsJavaScriptException();

package/system-gi.js

@@ -84,8 +84,14 @@ const PROBED_GI_LIBDIRS = {
     darwin: ['/opt/homebrew/lib', '/usr/local/lib', '/opt/local/lib'],
 };
 
-/** The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API. */
-const TYPELIB_SUBDIR = 'girepository-1.0';
+/**
+ * The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API.
+ *
+ * Exported so `gi-typelib.ts` shares it rather than keeping a third copy of the
+ * one string this whole layout rule turns on. Both mirrors export it, so the
+ * agreement suite still compares two files that differ only in language.
+ */
+export const TYPELIB_SUBDIR = 'girepository-1.0';
 
 /** Memoized `pkg-config` answer: the spawn happens at most once per process. */
 let pkgConfigDirsCache = null;