@gjsify/node-gi 0.45.0 → 0.47.0

package/README.md

@@ -35,9 +35,10 @@ vendored as-is — gjsify ships its own dual (GJS + Node) example/test infra.
 
 - **Node.js ≥ 20, Bun ≥ 1.3, or Deno ≥ 2** — the engine is a Node-API addon, so
   ONE binary serves all three (see [Runtimes](#runtimes-node--bun--deno)).
-- **No C++ toolchain on the four prebuilt targets.** The published tarball ships
-  `prebuilds/<platform>-<arch>/node_gi.node` for `linux-x64`, `linux-arm64`,
-  `darwin-arm64` and `win32-x64` (`package.json#gjsify.platforms`), and the
+- **No C++ toolchain on a prebuilt target.** The published tarball ships
+  `prebuilds/<platform>-<arch>/node_gi.node` for every target
+  `package.json#gjsify.platforms` declares — `linux-x64`, `linux-arm64`,
+  `darwin-arm64`, `darwin-x64`, `win32-x64` — and the
   `install` script (`scripts/install.mjs`) uses it instead of building: a source
   build is the FALLBACK for a host with no prebuild, not the default. Force it
   with `NODE_GI_BUILD_FROM_SOURCE=1` (or npm's `--build-from-source`); skip it
@@ -84,12 +85,25 @@ npm install @gjsify/gtk-runtime-darwin-arm64   # macOS Apple silicon
 npm install @gjsify/gtk-runtime-darwin-x64     # macOS Intel
 ```
 
-All three declare `os`/`cpu`, so npm/yarn/pnpm skip them off-platform. Making them
-`optionalDependencies` of this package (which would remove the manual step
-without any consumer-side platform branching) is pending two decisions outside
-this package — the ADR-0003 dependency-direction rule between node-gi's tier
-and the bundles', and `os`/`cpu` filtering in `gjsify install`'s native
-backend, which currently places foreign-platform optional deps.
+All three declare `os`/`cpu`, so npm/yarn/pnpm skip them off-platform.
+
+**This package will not declare one, and that is a decision, not a gap** —
+[ADR 0023 § 1 + § 3](../../../docs/adr/0023-gtk-source-precedence.md). Whoever
+SHIPS an application declares the bundle (for the showcases that is the `gjsify`
+CLI, which adds `@gjsify/gtk-runtime-<target>` to the tree it assembles); node-gi
+declares it in no dependency field at all. The reason is #910: a CI job compiled
+the addon against Homebrew GTK and then ran it on a bundle it had never been
+linked against, producing wrong method entries and a 29-minute timeout. #920
+reverted the dependency and the prohibition was written down. Pairing a
+from-source addon with a bundle is not a preference that came out wrong, it is
+an ABI error, so the bundle cannot arrive by default.
+
+What that costs is worth stating rather than discovering: on a Mac or a Windows
+box with **no** system GTK and **no** bundle installed, `@gjsify/node-gi` does
+not load at all — its addon's own link closure (`libgirepository-2.0`,
+`libglib-2.0`, `libcairo`) is unresolvable, and the failure names only the
+`.node` file (#1063). The addon's rpath lists exactly the two places it accepts:
+a sibling `gtk-runtime-<target>/gtk/lib`, and the host's `/usr/local/lib`.
 
 ## Usage
 

package/gi.js

@@ -145,6 +145,18 @@ class GLibError extends Error {
         this.code = code;
     }
 
+    // g_error_new_literal, which GJS exposes as a static on GLib.Error because it is in
+    // `GLib-2.0.gir` — and which is the only spelling `@girs/glib-2.0` TYPES, its
+    // `constructor(properties?)` signature rejecting the three positional arguments the
+    // constructor above actually takes. So a cross-runtime source that has to build a GError
+    // (a test asserting on an error a host cannot produce, say a CoreText font map's
+    // G_IO_ERROR_NOT_SUPPORTED) type-checks only against this, and without it the gjs leg
+    // passes and the node leg dies with `Error.new_literal is not a function`. Same arguments,
+    // same result — the constructor is the implementation.
+    static new_literal(domain, code, message) {
+        return new GLibError(domain, code, message);
+    }
+
     // g_error_matches: true when the error's domain AND code both match.
     matches(domain, code) {
         const d = errorDomainOf(domain);
@@ -166,7 +178,12 @@ function buildGError(domainName, domainQuark, code, message) {
     error.domainQuark = domainQuark;
     return error;
 }
-native.setErrorBuilder(buildGError);
+// The CLASS is registered with the builder, because the engine needs it the other
+// way round too: a `GError`-typed IN argument recognises a caught (or `new`-ed)
+// GLib.Error by `instanceof` and rebuilds a real GError from its fields, so an
+// application can hand back the error it is holding (`GLib.propagate_error`,
+// `Gst.Message.new_error`). One call, so builder and class cannot drift apart.
+native.setErrorBuilder(buildGError, GLibError);
 
 // Stamps a makeClass prototype with its { namespace, typeName } so Gio._promisify can
 // record WHICH introspected class a registration belongs to — matched against the
@@ -1408,6 +1425,28 @@ function defineLazyGType(ctor, namespace, typeName) {
     });
 }
 
+// The GType a static call's `this` names, or `null` when the receiver names none —
+// a primitive, a plain object, a raw (unregistered) subclass. `null` means "no
+// receiver", and the engine then runs the method on the type the name was read from,
+// which is the pre-#1438 behaviour for every non-class-struct call.
+//
+// A class answers its own `$gtype`. An INSTANCE has none — `$gtype` is a
+// constructor-level member here — but gjs answers the instance's RUNTIME class for
+// it, and the difference is observable: measured, `GObject.Object.list_properties`
+// borrowed onto an instance of a registerClass'd subclass reads the SUBCLASS's 6
+// pspecs under gjs and read GObject's 0 here. So resolve it through the type system,
+// the route `Symbol.hasInstance` above already takes.
+function gtypeOf(receiver) {
+    if (receiver === null || receiver === undefined) return null;
+    if (typeof receiver !== 'function' && typeof receiver !== 'object') return null;
+    const gt = receiver.$gtype;
+    if (gt !== undefined) return gt;
+    const handle = receiver[HANDLE];
+    if (handle === undefined || !native.isGObjectHandle(handle)) return null;
+    const G = requireGi('GObject', '2.0');
+    return G.type_from_name(native.getTypeName(handle));
+}
+
 // The GObject behind a prototype method's `this`. A prototype function is
 // reachable without an instance (`Cls.prototype.m()`, a detached reference), so
 // the engine must never be handed `undefined` for the instance argument.
@@ -1646,7 +1685,20 @@ function makeClass(namespace, typeName) {
                 return objectStaticConstructor(prop);
             }
             const giName = camelToSnake(prop);
-            return (...args) => wrapReturn(native.callStaticMethod(namespace, typeName, giName, unwrapArgs(args)));
+            // NOT an arrow: a class-struct method (GObjectClass's `list_properties`,
+            // `find_property`, …) runs on the class the call went THROUGH, so `this` is
+            // load-bearing and an arrow would discard it (#1438). What the engine does
+            // with it — and why a plain static and an incompatible receiver ignore it —
+            // is `CallStaticMethod`'s header in `src/calls.cc`.
+            return function (...args) {
+                // Short-circuit the direct `Ns.Class.method()` call: the engine would
+                // compare the receiver against the same GType and ignore it anyway, and
+                // the read would arm the lazy `$gtype` getter for nothing.
+                const receiverGType = this === proxy ? null : gtypeOf(this);
+                return wrapReturn(
+                    native.callStaticMethod(namespace, typeName, giName, unwrapArgs(args), receiverGType),
+                );
+            };
         },
     });
     // Replacing ctor.prototype dropped the automatic back-link; restore it pointing at
@@ -1728,6 +1780,17 @@ function makeEnum(namespace, typeName) {
     if (domain !== null) {
         Object.defineProperty(out, ERROR_DOMAIN, { value: domain, enumerable: false });
     }
+    // `Ns.Enum.$gtype` — gjs answers a registered G_TYPE_ENUM/G_TYPE_FLAGS here, so
+    // `GObject.type_name(Gio.BusType.$gtype)` is `GBusType` there and was `null` over
+    // the bridge: an enum object carried no `$gtype` at all. EAGER rather than
+    // defineLazyGType, because the object is frozen on the way out and a
+    // self-redefining getter could never install its cache. Non-enumerable, so
+    // `Object.keys` stays the member list; omitted entirely for an UNREGISTERED enum,
+    // which has no GType and where gjs answers `undefined` too.
+    const gtype = native.getGType(namespace, typeName);
+    if (gtype !== null) {
+        Object.defineProperty(out, '$gtype', { value: gtype, enumerable: false });
+    }
     return Object.freeze(out);
 }
 

package/gtk-runtime.js

@@ -460,6 +460,20 @@ export function maybeWireGtkWindowingEnv() {
         const scanner = join(bundle.dir, 'libexec', 'gstreamer-1.0', gstScannerLeaf());
         if (existsSync(scanner)) setIfUnset('GST_PLUGIN_SCANNER', scanner);
     }
+
+    // The GIO modules, and specifically the TLS backend. `GTlsConnection` has no
+    // implementation in GIO itself — glib-networking ships one as a module GIO
+    // g_module_opens out of ONE directory, whose compiled-in default is the BUILD
+    // machine's prefix. On a user's box that path is absent (or, worse, a foreign
+    // glib-networking against a different GLib), so a bundle-activated process fell back
+    // to the dummy backend and every https request failed: `souphttpsrc` reports
+    // "Internal data stream error", @gjsify/{tls,http2,ws} fail the same way one layer up.
+    //
+    // GIO_MODULE_DIR, not GIO_EXTRA_MODULES, for GST_PLUGIN_SYSTEM_PATH's reason: it
+    // REPLACES the compiled-in default rather than adding to it, and mixing a host's
+    // modules into the bundle's own GIO is the case we are avoiding, not one to preserve.
+    const gioModules = join(bundle.dir, 'lib', 'gio', 'modules');
+    if (existsSync(gioModules)) setIfUnset('GIO_MODULE_DIR', gioModules);
 }
 
 /** The plugin scanner's leaf name — the bundles ship the same tree on both OSes. */

package/index.d.ts

@@ -57,10 +57,15 @@ export function getErrorDomain(namespace: string, name: string): { name: string;
 
 /**
  * Register the L1 GLib.Error factory the engine calls when a GI invoke fails, so
- * a failed sync call throws a real `GLib.Error` (instanceof, with `.matches()`).
+ * a failed sync call throws a real `GLib.Error` (instanceof, with `.matches()`),
+ * together with the CLASS it builds — which a `GError`-typed IN argument uses to
+ * recognise such an error coming back and rebuild a real `GError` from its
+ * fields. Without the class that direction accepts only a marshalled (boxed)
+ * error, so a caught one cannot be handed on.
  */
 export function setErrorBuilder(
     builder: (domainName: string, domainQuark: number, code: number, message: string) => Error,
+    errorClass?: new (domain: unknown, code: number, message: string) => Error,
 ): void;
 
 /** Prepend a directory to the GIRepository typelib search path. */
@@ -387,6 +392,14 @@ export function setBoxedField(handle: BoxedHandle, name: string, value: unknown)
  * registered GType. Lets L1 attach type-specific conveniences (GLib.Bytes.toArray).
  */
 export function boxedTypeName(value: unknown): string | null;
+/**
+ * TEST-ONLY: the address a boxed handle wraps, as a hex string (`null` for anything
+ * else). Lets a test assert an IN-transfer ownership rule — "a transfer-full boxed
+ * IN arg is handed a COPY" — directly, instead of running the call many times and
+ * waiting for a double free that only aborts when the allocator has not recycled
+ * the block. Nothing on the runtime path may branch on it.
+ */
+export function __boxedAddress(value: unknown): string | null;
 
 /**
  * Opaque handle to a GObject.ParamSpec (a GObject fundamental, ref-counted via
@@ -604,6 +617,7 @@ declare const native: {
     getBoxedField: typeof getBoxedField;
     setBoxedField: typeof setBoxedField;
     boxedTypeName: typeof boxedTypeName;
+    __boxedAddress: typeof __boxedAddress;
     isParamSpecHandle: typeof isParamSpecHandle;
     paramSpecProp: typeof paramSpecProp;
     variantNew: typeof variantNew;

package/index.js

@@ -16,6 +16,7 @@ import {
     maybeReexecForGtkRuntime,
     maybeWireGtkWindowingEnv,
 } from './gtk-runtime.js';
+import { activateNativePrebuilds } from './native-prebuilds.js';
 
 // macOS bundled GTK: dyld reads DYLD_FALLBACK_LIBRARY_PATH only at launch, and GI
 // needs it to g_module_open typelib backers (get_type / Pango / Gdk / Graphene) by
@@ -124,6 +125,18 @@ try {
     // Never fatal: a missing/partial bundle just leaves the host GTK in charge.
 }
 
+// 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
+// AFTER the GTK activation — that one owns the bundle-vs-host policy (ADR 0023) and
+// this one skips gtk-runtime-* for exactly that reason.
+try {
+    activateNativePrebuilds(native);
+} catch {
+    // Same contract as the calls around it: a failed discovery leaves the search
+    // path untouched, and the caller gets GI's own "typelib not found".
+}
+
 // And where the LIBRARIES those typelibs name actually live. Separate from the
 // call above because it is not about a bundle: it applies to whichever GTK the
 // policy chose, and it is the only loader repair bun and deno get on macOS —
@@ -231,6 +244,9 @@ export const boxedMemberKind = native.boxedMemberKind;
 export const getBoxedField = native.getBoxedField;
 export const setBoxedField = native.setBoxedField;
 export const boxedTypeName = native.boxedTypeName;
+/** TEST-ONLY: the address a boxed handle wraps, so an ownership rule about pointer
+ * IDENTITY can be asserted instead of waited on (see marshal.cc BoxedAddress). */
+export const __boxedAddress = native.__boxedAddress;
 export const isParamSpecHandle = native.isParamSpecHandle;
 
 // True for a non-GObject GObject-fundamental handle (a GskRenderNode from