@gjsify/node-gi 0.63.0 → 0.64.0

package/gi.js

@@ -118,82 +118,265 @@ function unwrapProps(props) {
     return out;
 }
 
-// An enum object's GError-domain descriptor ({ name, quark }), so GLib.Error.matches
-// can resolve an error-enum (Gio.IOErrorEnum) to the domain it represents. Attached by
-// makeEnum when the enum is registered as a GError domain.
-// A registry symbol, so a host-side stand-in for an enum the typelib lacks (Gtk.DialogError on
-// Android) can declare itself an error domain without importing this module.
-const ERROR_DOMAIN = Symbol.for('nodeGiErrorDomain');
-
-// GLib.Error, L1: the engine throws one of these on a failed sync GI invoke (via the
-// builder registered below) and `requireGi('GLib').Error` is this constructor, so a
-// caught error is `instanceof GLib.Error` exactly as under GJS.
+// ---- GLib.Error (L1) ----
 //
-// Deliberate divergence from GJS: `.domain` is the quark NAME string (GJS's is the
-// numeric GQuark), with the numeric quark on `.domainQuark`. `matches()` accepts the
-// domain as an error-enum object, a name string or a numeric quark.
-
-// Resolve a `matches` domain argument to a { name?, quark? } descriptor.
-function errorDomainOf(domain) {
-    if (domain === null || domain === undefined) return null;
-    if (typeof domain === 'object' && domain[ERROR_DOMAIN] !== undefined) return domain[ERROR_DOMAIN];
-    if (typeof domain === 'string') return { name: domain };
-    if (typeof domain === 'number') return { quark: domain };
-    return null;
-}
-
-class GLibError extends Error {
-    // `new GLib.Error(domain, code, message)`, where `domain` may be an error-enum
-    // object, a quark name string, or a numeric quark.
-    constructor(domain, code, message) {
-        super(typeof message === 'string' ? message : '');
-        this.name = 'GLib.Error';
-        const d = errorDomainOf(domain);
-        this.domain = d !== null && d.name !== undefined ? d.name : typeof domain === 'string' ? domain : undefined;
-        this.domainQuark =
-            d !== null && d.quark !== undefined ? d.quark : typeof domain === 'number' ? domain : undefined;
-        this.code = code;
+// ONE object for every GError, as on GJS: a boxed handle over a real `GError*` whose
+// CLASS is the error DOMAIN's class (`Gio.IOErrorEnum`) when the quark names a
+// registered domain, and `GLib.Error` otherwise. There is no JS `Error` subclass
+// behind it — `Error.isError()` is true while `instanceof Error` is FALSE, a
+// combination only `Reflect.construct(Error, [], Ctor)` reaches (GJS gets it from
+// `JSCLASS_IS_DOMJSCLASS` on ErrorBase::klass).
+//
+// Reference: refs/gjs/gi/gerror.cpp (ErrorBase/ErrorInstance/ErrorPrototype) and its
+// `gjs_define_error_properties`, plus the GLib.js override's `Error.new_literal`
+// guard and `Error.prototype.matches`. The old divergence — an `Error` subclass with
+// `.domain` the quark NAME and the number on a node-gi-only `.domainQuark`, beside a
+// SECOND plain-boxed shape for a marshalled one — is gone with no compat shim;
+// test/gerror-identity.test.mjs is the contract.
+
+// quark → the class makeErrorDomainClass built for it. A cached `null` means "asked
+// the repository, this quark has no domain class".
+const errorClassByQuark = new Map();
+
+// GJS defines the error methods enumerable and non-configurable, which is observable:
+// a formatter listing a prototype's methods sees them, and nothing can redefine them.
+const errorMethod = (value) => ({ value, enumerable: true, writable: true, configurable: false });
+
+// The class for a GError's domain quark, or null when no typelib registers one (a
+// private quark from `GLib.quark_from_string`), in which case the error is a plain
+// `GLib.Error`.
+function errorClassForQuark(quark) {
+    const cached = errorClassByQuark.get(quark);
+    if (cached !== undefined) return cached;
+    // Nothing has touched the enum yet, so the map cannot know it: ask the repository
+    // which { namespace, name } registered the domain and READ that member — makeEnum
+    // registers the class it builds on the way out. Without this an error whose domain
+    // enum the application never named would fall back to the base class, which is
+    // exactly the `catch (e) { if (e instanceof Gio.IOErrorEnum) }` case.
+    // Guarded for the cross-version pairing the `native.setPropertySetCallback` guard
+    // below describes: an addon older than this JS does not export it. Degrading means
+    // falling back to what the map alone knows — a domain whose enum `makeEnum` has
+    // already realized is in it, one nothing has touched yet lands on the base class.
+    // Nothing is cached in that case, so a later `makeEnum` still registers.
+    if (typeof native.errorDomainInfo !== 'function') return null;
+    const info = native.errorDomainInfo(quark);
+    errorClassByQuark.set(quark, null); // also breaks the cycle while the namespace loads
+    if (info === null) return null;
+    // Namespace MEMBERS are lazy (createNamespace resolves on first read), so the
+    // namespace object alone builds nothing — the member read is what runs makeEnum.
+    // oxlint-disable-next-line no-unused-expressions -- the READ is the side effect: it runs makeEnum, which registers the class
+    requireGi(info.namespace)[info.name];
+    return errorClassByQuark.get(quark);
+}
+
+// The first parseable `file:line:column` in a V8 stack. The FRAMES stay V8's — only
+// their position is lifted out, and the frame it lands on is node-gi's own dispatch
+// site for a marshalled error (see docs/node-gi-gjs-surface.md).
+function topFrame(stack) {
+    for (const line of String(stack).split('\n')) {
+        const match = /\(?([^()\s]+):(\d+):(\d+)\)?$/.exec(line.trim());
+        if (match !== null) {
+            return { fileName: match[1], lineNumber: Number(match[2]), columnNumber: Number(match[3]) };
+        }
     }
-
-    // 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);
+    return { fileName: undefined, lineNumber: undefined, columnNumber: undefined };
+}
+
+// GJS's `gjs_define_error_properties`: four own ENUMERABLE value properties saying
+// where the error came from. Enumerable is the load-bearing half — V8's own `stack`
+// is not, so a `{...err}` spread or a structured log carried the frames on GJS and
+// nothing here.
+function definePositionProperties(error, hideAbove) {
+    Error.captureStackTrace(error, hideAbove);
+    const stack = error.stack;
+    const frame = topFrame(stack);
+    for (const [name, value] of [
+        ['stack', stack],
+        ['fileName', frame.fileName],
+        ['lineNumber', frame.lineNumber],
+        ['columnNumber', frame.columnNumber],
+    ]) {
+        Object.defineProperty(error, name, { value, enumerable: true, writable: true, configurable: true });
     }
+}
+
+// Wrap a `GError*` handle as the error object. `withPosition` is GJS's asymmetry: the
+// position properties are defined when the error was THROWN or CONSTRUCTED, and
+// otherwise only for an UNKNOWN domain — because GJS then has no domain metadata to
+// build a class from and reaches the GError through its generic struct wrapper, which
+// defines them (gi/struct.cpp). `hideAbove` is the frame the position should be
+// measured at, so `new GLib.Error(…)` reports the caller and not this file.
+function wrapGError(handle, withPosition = false, hideAbove = wrapGError) {
+    const cls = errorClassForQuark(native.getBoxedField(handle, 'domain'));
+    const error = Reflect.construct(Error, [], cls ?? GLibError);
+    error[HANDLE] = handle;
+    if (withPosition || cls === null) definePositionProperties(error, hideAbove);
+    // `Reflect.construct(Error, …)` always leaves V8's own `stack` behind, and GJS has
+    // none on this path at all.
+    else delete error.stack;
+    return error;
+}
 
-    // g_error_matches: true when the error's domain AND code both match.
-    matches(domain, code) {
-        const d = errorDomainOf(domain);
-        if (d === null) return false;
-        const domainMatch =
-            (d.name !== undefined && d.name === this.domain) || (d.quark !== undefined && d.quark === this.domainQuark);
-        return domainMatch && code === this.code;
+// g_error_new_literal, behind the quark guard GJS's GLib.js puts in front of it: the
+// domain must already name something, so `new GLib.Error()` is refused here rather
+// than producing a GError no `matches()` can ever hit.
+function newErrorLiteral(domain, code, message) {
+    const quark = toDomainQuark(domain);
+    if (native.callFunction('GLib', 'quark_to_string', [quark]) === null) {
+        throw new TypeError(`Error.new_literal: ${domain} is not a valid domain`);
     }
+    return native.callStaticMethod('GLib', 'Error', 'new_literal', [quark, code, message]);
+}
+
+// GJS's uint32 conversion for a `domain` argument (gi/js-value-inl.h,
+// js_value_to_c_checked): `undefined` and a non-finite NUMBER become 0 silently,
+// anything else goes through ToNumber and is REFUSED when it misses uint32 range.
+// node-gi's own NodeGiToUint32 has no range check, so the node-gi-only spelling
+// `err.matches('g-io-error-quark', code)` converted to NaN→0 and quietly matched
+// nothing; GJS cannot run that line at all, so neither can this.
+function toDomainQuark(domain) {
+    if (domain === undefined || (typeof domain === 'number' && !Number.isFinite(domain))) return 0;
+    const quark = Number(domain);
+    if (Number.isNaN(quark) || quark < 0 || quark > 0xffffffff) {
+        throw new Error('Argument domain: value is out of range for uint32');
+    }
+    return quark >>> 0;
+}
 
-    toString() {
-        return `GLib.Error ${this.domain}: ${this.message}`;
+// `GLib.Error`: a plain FUNCTION, not a `class … extends Error` — GJS's
+// GLib.Error.prototype has Object.prototype on its chain, not Error.prototype.
+function GLibError(domain, code, message) {
+    // The spelling `@girs/glib-2.0`'s `constructor(properties?)` signature invites,
+    // and which GJS runs into its generic boxed-struct constructor with: a GError
+    // field is not writable. Replicated verbatim so the failure reads the same.
+    if (arguments.length === 1 && typeof domain === 'object' && domain !== null) {
+        throw new Error('Writing field GLib.Error.message is not supported');
     }
+    return wrapGError(newErrorLiteral(domain, code, message), true, GLibError);
 }
+Object.defineProperty(GLibError, 'name', { value: 'GLib_Error', configurable: true });
+defineLazyGType(GLibError, 'GLib', 'Error');
 
-// Called by the engine on a failed GI invoke, with the GError's authoritative fields.
-function buildGError(domainName, domainQuark, code, message) {
-    const error = new GLibError(domainName, code, message);
-    error.domain = domainName;
-    error.domainQuark = domainQuark;
-    return error;
+// The static GJS exposes because `g_error_new_literal` is in GLib-2.0.gir — and the
+// only spelling `@girs/glib-2.0` TYPES, so a cross-runtime source that has to build a
+// GError type-checks against this rather than the three positional constructor args.
+GLibError.new_literal = function new_literal(domain, code, message) {
+    return wrapGError(newErrorLiteral(domain, code, message));
+};
+
+// `domain`/`code`/`message` read straight off the `GError*` through a PROTOTYPE
+// accessor, as GJS does: getter-only (a consumer "normalising" an error by assigning
+// `.domain` is a TypeError, not a silent mutation) and own to each prototype, so the
+// refusal below can name the right one.
+function defineErrorFields(proto, displayName, protoQuark) {
+    for (const field of ['domain', 'code', 'message']) {
+        Object.defineProperty(proto, field, {
+            enumerable: true,
+            configurable: false,
+            get() {
+                const handle = this[HANDLE];
+                if (handle !== undefined) return native.getBoxedField(handle, field);
+                // A PROTOTYPE has no GError* behind it, and refusing is what keeps a
+                // prototype walk (util.inspect, a formatter collecting accessors) from
+                // reading a wild pointer. GJS still answers a DOMAIN prototype's
+                // `domain` — that is where `matches(Gio.IOErrorEnum, …)` reads the
+                // quark from — and refuses the other two.
+                if (field === 'domain' && protoQuark !== undefined) return protoQuark;
+                throw new Error(`Can't get a field on ${displayName}.prototype; only on instances`);
+            },
+        });
+    }
 }
-// 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);
+
+Object.defineProperties(GLibError.prototype, {
+    copy: errorMethod(function copy() {
+        return wrapGError(native.callBoxedMethod(this[HANDLE], 'copy', []));
+    }),
+    // g_error_free, for parity. It carries the same double-free footgun as on GJS: the
+    // handle still owns the GError* and frees it again on GC.
+    free: errorMethod(function free() {
+        return native.callBoxedMethod(this[HANDLE], 'free', []);
+    }),
+    matches: errorMethod(function matches(domain, code) {
+        if (arguments.length < 2) {
+            throw new TypeError(
+                `method GLib.Error.matches: At least 2 arguments required, but only ${arguments.length} passed`,
+            );
+        }
+        return native.callBoxedMethod(this[HANDLE], 'matches', [toDomainQuark(domain), code]);
+    }),
+});
+defineErrorFields(GLibError.prototype, 'GLib.Error', undefined);
+// Defined SEPARATELY here and on each domain prototype, which is why on GJS
+// `err.toString !== GLib.Error.prototype.toString` for a known domain: there is no
+// sentinel branch, the class that knows its name owns the method.
+Object.defineProperty(
+    GLibError.prototype,
+    'toString',
+    errorMethod(function toString() {
+        return `GLib.Error ${native.callFunction('GLib', 'quark_to_string', [this.domain])}: ${this.message}`;
+    }),
+);
+
+// An error-domain enum (`Gio.IOErrorEnum`) is BOTH the enum and the CLASS of its
+// errors on GJS — `instanceof` discriminates the domain and `new Gio.IOErrorEnum({
+// message, code })` builds one — so it has to be a function with a prototype chained
+// to GLib.Error.prototype. A frozen object, which is what makeEnum hands out
+// otherwise, can be neither.
+function makeErrorDomainClass(namespace, typeName, members, quark) {
+    const displayName = `${namespace}.${typeName}`;
+    const cls = function (props) {
+        // The wording is the contract — a cross-runtime test asserting on a
+        // constructor refusal compares the string — and `message` is checked BEFORE
+        // `code`, so a call naming neither names `message`.
+        if (arguments.length !== 1 || typeof props !== 'object' || props === null) {
+            throw new Error('Invalid parameters passed to GError constructor, expected one object');
+        }
+        if (typeof props.message !== 'string') {
+            throw new Error("No property 'message' in GError constructor (or it was not a string)");
+        }
+        if (!Number.isInteger(props.code) || props.code < -0x80000000 || props.code > 0x7fffffff) {
+            throw new Error("No property 'code' in GError constructor (or it was not a 32-bit integer)");
+        }
+        return wrapGError(newErrorLiteral(quark, props.code, props.message), true, cls);
+    };
+    Object.defineProperty(cls, 'name', { value: `${namespace}_${typeName}`, configurable: true });
+    Object.assign(cls, members);
+    // G_TYPE_ERROR, NOT the enum's own GIOErrorEnum: on GJS an error domain is an
+    // Error class before it is an enum (ErrorBase::to_gtype), and the enum GType it
+    // shadows is unreachable there, so nothing written for GJS can ask for it.
+    defineLazyGType(cls, 'GLib', 'Error');
+    // A STATIC on GJS (ErrorBase::value_of reads `this.constructor.prototype`'s
+    // domain), and what makes both `Number(Gio.IOErrorEnum)` and
+    // `err.matches(Gio.IOErrorEnum, code)` answer the quark with no registry lookup.
+    cls.valueOf = () => quark;
+    Object.setPrototypeOf(cls.prototype, GLibError.prototype);
+    defineErrorFields(cls.prototype, displayName, quark);
+    Object.defineProperty(
+        cls.prototype,
+        'toString',
+        errorMethod(function toString() {
+            return `${displayName}: ${this.message}`;
+        }),
+    );
+    errorClassByQuark.set(quark, cls);
+    return cls;
+}
+
+// Called by the engine on a failed GI invoke, with ownership of the GError* already
+// transferred to the boxed handle. Named, so the position properties report the
+// application frame rather than this one.
+native.setErrorBuilder(function buildThrownGError(handle, quark, code, message) {
+    // Same cross-version pairing: an addon older than this JS calls the builder with
+    // the GError's FIELDS (domainName, quark, code, message) rather than a handle, and
+    // there is no second `errorClass` argument to give it. Rebuilding the GError from
+    // the fields keeps the ONE shape on that pairing too — it costs only the original
+    // GError's address, which nothing can read.
+    if (typeof handle === 'string') {
+        return wrapGError(newErrorLiteral(quark, code, message), true, buildThrownGError);
+    }
+    return wrapGError(handle, true, buildThrownGError);
+});
 
 // Stamps a makeClass prototype with its { namespace, typeName } so Gio._promisify can
 // record WHICH introspected class a registration belongs to — matched against the
@@ -301,6 +484,12 @@ function wrapFundamental(handle) {
 // boxedMemberKind checks methods first — 1 = method, 2 = field, 0 = neither,
 // 3 = undecidable.
 function wrapBoxed(handle) {
+    // A GError gets the full error shape — domain class, Error brand, position
+    // properties — wherever it surfaces: an OUT param, a struct field, a container
+    // element. Routing HERE rather than in the GError-typed OUT arm in C++ is what
+    // makes those three agree; the old code only special-cased the thrown path, so a
+    // GError read out of a container was a bare method-routing proxy.
+    if (native.boxedTypeName(handle) === 'GError') return wrapGError(handle);
     const target = { [HANDLE]: handle };
     const methodDispatch =
         (prop) =>
@@ -612,6 +801,13 @@ function makeLogStructured(baseNs) {
 }
 
 function decorateGLibNamespace(baseNs) {
+    // GJS's GLib override installs this on the GLOBAL Error.prototype, which is what
+    // makes `catch (e) { if (e.matches(domain, code)) … }` safe to write without a
+    // type test in front of it. Plain assignment, so the descriptor is GJS's
+    // (writable, enumerable, configurable) rather than a hardened one.
+    Error.prototype.matches = function matches() {
+        return false;
+    };
     // Per-namespace cache of the overlay functions that need the introspected baseNs
     // (log_structured → log_variant; the *_once helpers → idle_add/timeout_add).
     const cache = new Map();
@@ -658,9 +854,9 @@ function decorateGLibNamespace(baseNs) {
     return new Proxy(baseNs, {
         get(t, prop) {
             if (prop === 'Variant') return variantClass;
-            // GLib.Error is the L1 GError subclass (the engine throws instances of it,
-            // and `new GLib.Error(domain, code, message)` constructs one), shadowing the
-            // introspected boxed type so `instanceof GLib.Error` + `.matches()` work.
+            // GLib.Error is the L1 error base class — every GError reaching JS is an
+            // instance of it or of its domain's subclass — shadowing the introspected
+            // boxed type, which would hand out a bare method-routing proxy.
             if (prop === 'Error') return GLibError;
             if (typeof prop === 'string' && GLIB_OVERLAY_NAMES.has(prop)) return overlay(prop);
             return t[prop];
@@ -1954,13 +2150,11 @@ function makeEnum(namespace, typeName) {
     for (const key of Object.keys(raw)) {
         out[key.toUpperCase().replace(/-/g, '_')] = raw[key];
     }
-    // If this enum is registered as a GError domain (Gio.IOErrorEnum, …), attach
-    // its domain descriptor (non-enumerable) so GLib.Error.matches(enum, code) can
-    // resolve the enum to its domain. A plain enum gets nothing (getErrorDomain → null).
+    // An enum registered as a GError domain (Gio.IOErrorEnum, …) is the CLASS of its
+    // errors as well, which a frozen object cannot be — it keeps its members on the
+    // function form instead.
     const domain = native.getErrorDomain(namespace, typeName);
-    if (domain !== null) {
-        Object.defineProperty(out, ERROR_DOMAIN, { value: domain, enumerable: false });
-    }
+    if (domain !== null) return makeErrorDomainClass(namespace, typeName, out, domain.quark);
     // `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

package/index.d.ts

@@ -56,17 +56,18 @@ export function getEnumValues(namespace: string, name: string): Record<string, n
 export function getErrorDomain(namespace: string, name: string): { name: string; quark: number } | null;
 
 /**
- * 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()`),
- * 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;
+ * Resolve a domain quark back to the enum type registered for it — the reverse of
+ * {@link getErrorDomain}, so a thrown error reaches its domain class even when
+ * nothing has touched that enum yet. `null` for a quark no typelib claims.
+ */
+export function errorDomainInfo(quark: number): { namespace: string; name: string } | null;
+
+/**
+ * Register the L1 `GLib.Error` factory the engine calls when a GI invoke fails. It
+ * receives the failed call's `GError` as a boxed handle, having taken ownership of
+ * it, and returns the object to throw — the same shape a marshalled error gets.
+ */
+export function setErrorBuilder(builder: (handle: BoxedHandle) => unknown): void;
 
 /** Prepend a directory to the GIRepository typelib search path. */
 export function prependSearchPath(path: string): void;
@@ -599,6 +600,7 @@ declare const native: {
     getConstantValue: typeof getConstantValue;
     getEnumValues: typeof getEnumValues;
     getErrorDomain: typeof getErrorDomain;
+    errorDomainInfo: typeof errorDomainInfo;
     setErrorBuilder: typeof setErrorBuilder;
     prependSearchPath: typeof prependSearchPath;
     prependLibraryPath: typeof prependLibraryPath;

package/index.js

@@ -29,6 +29,7 @@ export const findInfo = native.findInfo;
 export const getConstantValue = native.getConstantValue;
 export const getEnumValues = native.getEnumValues;
 export const getErrorDomain = native.getErrorDomain;
+export const errorDomainInfo = native.errorDomainInfo;
 export const setErrorBuilder = native.setErrorBuilder;
 export const prependSearchPath = native.prependSearchPath;
 export const prependLibraryPath = native.prependLibraryPath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.63.0",
+  "version": "0.64.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/addon.cc

@@ -88,6 +88,7 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("getConstantValue", Napi::Function::New(env, GetConstantValue));
   exports.Set("getEnumValues", Napi::Function::New(env, GetEnumValues));
   exports.Set("getErrorDomain", Napi::Function::New(env, GetErrorDomain));
+  exports.Set("errorDomainInfo", Napi::Function::New(env, ErrorDomainInfo));
   exports.Set("setErrorBuilder", Napi::Function::New(env, SetErrorBuilder));
   exports.Set("prependSearchPath", Napi::Function::New(env, PrependSearchPath));
   exports.Set("prependLibraryPath", Napi::Function::New(env, PrependLibraryPath));

package/src/calls.cc

@@ -380,44 +380,40 @@ bool IsSupportedOutType(GITypeInfo* type, std::string* why) {
 
 // ---- GError -> GLib.Error ----
 //
-// A failed GI invoke yields a GError (domain quark + code + message). GJS surfaces
-// it as a real `GLib.Error` (an Error subclass carrying `.domain`/`.code`/
-// `.message` + a `.matches(domain, code)` method). The GLib.Error CLASS itself is
-// owned by L1 (gi.js) so its `matches()` can resolve an error-enum object to its
-// domain; the engine just reports the GError's fields to an L1-registered builder
-// function (stored in this env's instance data — see NodeGiEnvData) and throws
-// what it returns.
+// A failed GI invoke yields a GError (domain quark + code + message), which GJS
+// throws as the error object of that DOMAIN's class. That object is L1's to build
+// (gi.js wrapGError) — only JS can give it the Error brand, the domain class and
+// the position properties — so the engine hands the builder registered in this
+// env's instance data the one thing it needs: the `GError*` itself, as a boxed
+// handle.
 //
-// Read a GError's domain (quark name + numeric quark), code and message, FREE it,
-// and throw the JS error the L1 builder produces (instanceof GLib.Error). Falls
-// back to a plain JS Error when no builder is registered for this env. `context`
-// is the "Ns.method" display name, used only in the fallback message (a real
-// GLib.Error carries the bare GError message, matching GJS).
+// Passing the HANDLE and not the fields is the whole point. The fields used to be
+// read out, the GError g_error_free'd here, and a JS Error subclass built from
+// them — so a thrown error and a marshalled one were two different objects with
+// two different `.domain` types. Ownership now transfers to the handle, which
+// frees the GError when the JS error is collected, and both directions wrap the
+// same pointer the same way.
+//
+// Falls back to a plain JS Error when no builder is registered for this env;
+// `context` is the "Ns.method" display name, used only in that fallback message (a
+// real GLib.Error carries the bare GError message, matching GJS).
 void ThrowGError(Napi::Env env, GError* error, const std::string& context) {
-  // Read everything out of the GError BEFORE g_error_free.
-  GQuark domainQuark = error != nullptr ? error->domain : 0;
-  const char* domainName = domainQuark != 0 ? g_quark_to_string(domainQuark) : nullptr;
-  std::string domain = domainName != nullptr ? domainName : "";
-  int code = error != nullptr ? error->code : 0;
   std::string message =
       (error != nullptr && error->message != nullptr) ? error->message : "invocation failed";
-  if (error != nullptr) g_error_free(error);
 
-  // Prefer this env's L1 GLib.Error builder (instanceof GLib.Error + matches()).
   NodeGiEnvData* d = EnvData(env);
-  if (d != nullptr && d->errorBuilder != nullptr) {
+  if (error != nullptr && d != nullptr && d->errorBuilder != nullptr) {
     napi_value builder = nullptr;
     if (napi_get_reference_value(env, d->errorBuilder, &builder) == napi_ok &&
         builder != nullptr) {
       napi_value undef = nullptr;
       napi_get_undefined(env, &undef);
-      napi_value bargs[4] = {nullptr, nullptr, nullptr, nullptr};
-      napi_create_string_utf8(env, domain.c_str(), NAPI_AUTO_LENGTH, &bargs[0]);
-      napi_create_uint32(env, static_cast<uint32_t>(domainQuark), &bargs[1]);
-      napi_create_int32(env, code, &bargs[2]);
-      napi_create_string_utf8(env, message.c_str(), NAPI_AUTO_LENGTH, &bargs[3]);
+      // GI_TRANSFER_EVERYTHING: the invoke's out-GError is ours, and the handle
+      // adopts it rather than copying — so nothing frees it here.
+      napi_value handle = MakeGErrorHandle(env, error, GI_TRANSFER_EVERYTHING);
+      error = nullptr;  // adopted by the handle; no path below may free it again
       napi_value errObj = nullptr;
-      napi_status st = napi_call_function(env, undef, builder, 4, bargs, &errObj);
+      napi_status st = napi_call_function(env, undef, builder, 1, &handle, &errObj);
       if (st == napi_ok && errObj != nullptr) {
         napi_throw(env, errObj);
         return;
@@ -427,6 +423,7 @@ void ThrowGError(Napi::Env env, GError* error, const std::string& context) {
       if (napi_is_exception_pending(env, &pending) == napi_ok && pending) return;
     }
   }
+  if (error != nullptr) g_error_free(error);
   Napi::Error::New(env, "Calling " + context + ": " + message).ThrowAsJavaScriptException();
 }
 
@@ -636,7 +633,6 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
   // belong to the callee (dropped only when the callee never ran).
   CreatedBytes createdBytes;
   CreatedValues createdValues;
-  CreatedErrors createdErrors;
   bool ok = true;
   size_t jsCursor = 0;
   std::vector<LengthWrite> lengthWrites;
@@ -815,7 +811,7 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
           jsCursor++;
           GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
           if (JsToGIArgument(env, v, ti, &slots[i], &held[i], tr, &ownedInStrings, nullptr,
-                             nullptr, nullptr, &createdErrors,
+                             nullptr, nullptr,
                              gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai)))) {
             in_args[inPos[i]].v_pointer = &slots[i];
             out_args[outPos[i]].v_pointer = &slots[i];
@@ -922,7 +918,7 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
       } else {
         GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
         ok = JsToGIArgument(env, v, ti, &in_args[inPos[i]], &held[i], tr, &ownedInStrings,
-                            &createdClosures, &createdBytes, &createdValues, &createdErrors,
+                            &createdClosures, &createdBytes, &createdValues,
                             gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai)));
       }
     }
@@ -944,9 +940,6 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
     // Likewise every GValue boxed from a plain JS value — never adopted.
     for (GValue* gv : createdValues.transferNone) NodeGiFreeBoxedGValue(gv);
     for (GValue* gv : createdValues.transferFull) NodeGiFreeBoxedGValue(gv);
-    // Likewise every GError built from an L1 GLib.Error — never adopted.
-    for (GError* e : createdErrors.transferNone) g_error_free(e);
-    for (GError* e : createdErrors.transferFull) g_error_free(e);
     // Likewise the transfer-full-instance ref: the callee never consumed it.
     if (instanceRefTaken) g_object_unref(static_cast<GObject*>(instance));
     for (gpointer s : ownedInStrings) g_free(s);  // never reached the callee (#658)
@@ -1001,11 +994,6 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
   // box is ours to free — success AND error paths, mirroring the GBytes rule.
   // Transfer-full GValues were adopted by the callee — no release.
   for (GValue* gv : createdValues.transferNone) NodeGiFreeBoxedGValue(gv);
-  // Transfer-none GError IN-args built from an L1 GLib.Error: the callee copied
-  // what it kept (gst_message_new_error copies the GError into the message), so
-  // the build is ours to free — success AND error paths, mirroring the two rules
-  // above. Transfer-full GErrors were adopted by the callee — no release.
-  for (GError* e : createdErrors.transferNone) g_error_free(e);
   if (!success) {
     for (const InContainer& c : inContainers) FreeInContainer(c);
     // A failed invoke did not adopt the transfer-full IN/INOUT strings we g_strdup'd

package/src/class.cc

@@ -907,7 +907,7 @@ static Napi::Value InvokeVFuncPointer(Napi::Env env, GObject* obj, GICallableInf
         jsCursor++;
         GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
         if (JsToGIArgument(env, v, ti, &slots[i], &holds[i], tr, &ownedInStrings, nullptr,
-                           nullptr, nullptr, nullptr,
+                           nullptr, nullptr,
                            gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai))))
           giArgs[1 + i].v_pointer = &slots[i];
         else
@@ -963,7 +963,7 @@ static Napi::Value InvokeVFuncPointer(Napi::Env env, GObject* obj, GICallableInf
       jsCursor++;
       GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
       ok = JsToGIArgument(env, v, ti, &giArgs[1 + i], &holds[i], tr, &ownedInStrings, nullptr,
-                          nullptr, nullptr, nullptr,
+                          nullptr, nullptr,
                           gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai)));
     }
 

package/src/common.h

@@ -83,11 +83,6 @@ GIRepository* DupDefaultRepository();
 // Init, freed by the instance-data finalizer at env teardown.
 struct NodeGiEnvData {
   napi_ref errorBuilder = nullptr;
-  // The CLASS the builder above constructs — L1's `GLib.Error`. Registered with
-  // the builder (one call, so the two cannot drift apart) and read the other way
-  // round: a GError-typed IN arg uses it to recognise an L1 error and rebuild a
-  // real GError from its fields. Per-env for the same reason as errorBuilder.
-  napi_ref errorClass = nullptr;
   // L1-registered resolver for Gtk.Template `<signal handler="…">` callbacks: given
   // (instanceHandle, handlerName) it returns the instance's bound JS method (or
   // undefined). Stored per-env for the same reason as errorBuilder (a napi_ref is
@@ -160,6 +155,13 @@ extern const napi_type_tag kGObjectHandleTag;
 Napi::Value MakeBoxedHandle(Napi::Env env, gpointer ptr, GType gtype, bool owns,
                             GIBaseInfo* info = nullptr, bool rawOwned = false);
 Napi::Value WrapVariant(Napi::Env env, GVariant* var, GITransfer transfer);
+// Wrap a `GError*` as the boxed handle L1's `wrapGError` turns into the error
+// object. ONE helper for both directions a GError reaches JS by — a GError-typed
+// return/OUT and the error a failed invoke THREW — because those used to produce
+// two different JS shapes, and sharing the wrap is what keeps them from drifting
+// apart again. Transfer follows the boxed rule: transfer-everything is adopted,
+// transfer-none is copied, so the handle always owns what it frees.
+Napi::Value MakeGErrorHandle(Napi::Env env, GError* error, GITransfer transfer);
 BoxedHandle* TryGetBoxedHandle(Napi::Value v);
 bool TryGetBoxedPtr(Napi::Value v, gpointer* out);
 Napi::Value MakeGTypeHandle(Napi::Env env, GType gtype);
@@ -317,13 +319,13 @@ struct CreatedClosures {
 
 // ---- C objects this layer SYNTHESISES for one IN argument --------------------
 //
-// Three IN arms build a throw-away C object out of a plain JS value, because the
-// JS side has no handle to hand over: a Uint8Array for a `GLib.Bytes` arg, a
-// number/string for a `GObject.Value` arg, an L1 `GLib.Error` for a `GError` arg.
-// All three carry the SAME lifetime rule, which is why they share one type
-// instead of a third near-identical struct: transfer-none → the callee borrowed
-// (or copied) it, so we release it after the invoke; transfer-full → the callee
-// adopted it, so it is released only when the invoke never ran.
+// Two IN arms build a throw-away C object out of a plain JS value, because the JS
+// side has no handle to hand over: a Uint8Array for a `GLib.Bytes` arg, a
+// number/string for a `GObject.Value` arg. Both carry the SAME lifetime rule,
+// which is why they share one type instead of a second near-identical struct:
+// transfer-none → the callee borrowed (or copied) it, so we release it after the
+// invoke; transfer-full → the callee adopted it, so it is released only when the
+// invoke never ran.
 template <typename T>
 struct CreatedIn {
   std::vector<T*> transferNone;  // release after the invoke (callee borrowed/copied)
@@ -353,17 +355,6 @@ using CreatedBytes = CreatedIn<GBytes>;
 // boxed-handle path and is passed through untouched.
 using CreatedValues = CreatedIn<GValue>;
 
-// An L1 `GLib.Error` (what a `catch` hands you, and what `new GLib.Error(…)`
-// builds) has no `GError*` behind it — it is a JS class, not a boxed handle — so
-// a `GError`-typed IN arg gets a fresh `g_error_new_literal` built from its
-// domain/code/message. Without this, the hand-back direction the OUT direction
-// exists for is only open to errors that came OUT of GI in the first place:
-// `GLib.propagate_error(caught)` and `Gst.Message.new_error(src, caught, dbg)`
-// both refused where gjs accepts, which is the shape an application actually
-// writes. A marshalled GError (a boxed handle) still routes through
-// TransferBoxedIn and is not copied here.
-using CreatedErrors = CreatedIn<GError>;
-
 // Release a GValue this layer boxed: unset the held value (dropping the ref an
 // object/boxed/string GValue took) and free the struct. A plain `g_free` would
 // leak whatever the GValue owns.
@@ -390,9 +381,6 @@ GClosure* NodeGiMakeGenericJsClosure(Napi::Env env, Napi::Value fn);
 // `values` (optional): enables the JS-value→GValue IN-arg boxing above; nullptr
 // (the default) keeps the previous behaviour (plain value → TypeError) on paths
 // that cannot release a created GValue.
-// `errors` (optional): enables the L1-GLib.Error→GError IN-arg build above;
-// nullptr (the default) keeps a marshalled boxed handle working and refuses the
-// L1 class, on paths that cannot release a created GError.
 // `argName` (optional): the introspected argument name, used ONLY in error
 // messages so a refusal reads like gjs's ("Expected type string for argument
 // 'name' but got type number"); nullptr degrades to a message without the name.
@@ -403,7 +391,6 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
                     CreatedClosures* closures = nullptr,
                     CreatedBytes* bytes = nullptr,
                     CreatedValues* values = nullptr,
-                    CreatedErrors* errors = nullptr,
                     const char* argName = nullptr);
 
 // ---- IN container building -----------------------------------------
@@ -671,6 +658,7 @@ Napi::Value FindInfo(const Napi::CallbackInfo& info);
 Napi::Value GetConstantValue(const Napi::CallbackInfo& info);
 Napi::Value GetEnumValues(const Napi::CallbackInfo& info);
 Napi::Value GetErrorDomain(const Napi::CallbackInfo& info);
+Napi::Value ErrorDomainInfo(const Napi::CallbackInfo& info);
 Napi::Value SetErrorBuilder(const Napi::CallbackInfo& info);
 Napi::Value PrependSearchPath(const Napi::CallbackInfo& info);
 Napi::Value PrependLibraryPath(const Napi::CallbackInfo& info);

package/src/marshal.cc

@@ -143,6 +143,22 @@ static Napi::Value WrapBoxed(Napi::Env env, gpointer ptr, GIBaseInfo* structInfo
   return MakeBoxedHandle(env, handlePtr, handleGType, owns, info);
 }
 
+// See common.h. Wrapped through the GLib.Error STRUCT info rather than by GType
+// alone, so `domain`/`code`/`message` resolve as fields — which is how L1 reads
+// them off the GError*.
+Napi::Value MakeGErrorHandle(Napi::Env env, GError* error, GITransfer transfer) {
+  if (error == nullptr) return env.Null();
+  GIRepository* repo = DupDefaultRepository();
+  // GLib is loaded by any namespace require; require defensively anyway so a bare
+  // engine call still resolves the struct info (idempotent, cheap).
+  gi_repository_require(repo, "GLib", "2.0", static_cast<GIRepositoryLoadFlags>(0), nullptr);
+  GIBaseInfo* errInfo = gi_repository_find_by_name(repo, "GLib", "Error");
+  Napi::Value result = WrapBoxed(env, error, errInfo, transfer);
+  if (errInfo != nullptr) gi_base_info_unref(errInfo);
+  g_object_unref(repo);
+  return result;
+}
+
 // Read a boxed handle (ptr + boxed GType) if `v` is one (tag-checked; no deref of
 // ptr). Returns nullptr when `v` is not a node-gi boxed handle. The returned handle
 // is owned by the External — never free it. Callers that need the GType (boxed
@@ -472,47 +488,6 @@ static void ThrowExpectedGLibError(Napi::Env env, const char* argName, const std
       .ThrowAsJavaScriptException();
 }
 
-// Whether `v` is an instance of the L1 `GLib.Error` class — the shape a `catch`
-// around a failed GI invoke hands you, and what `new GLib.Error(domain, code,
-// message)` builds. Recognition is `instanceof` against the class L1 registered
-// alongside its error builder, never duck-typing: a plain object carrying a
-// `code` must still be refused.
-static bool IsL1GLibError(Napi::Env env, Napi::Value v) {
-  if (!v.IsObject()) return false;
-  NodeGiEnvData* d = EnvData(env);
-  if (d == nullptr || d->errorClass == nullptr) return false;
-  napi_value cls = nullptr;
-  if (napi_get_reference_value(env, d->errorClass, &cls) != napi_ok || cls == nullptr) return false;
-  Napi::Value clsValue(env, cls);
-  return clsValue.IsFunction() && v.As<Napi::Object>().InstanceOf(clsValue.As<Napi::Function>());
-}
-
-// Build a real GError out of an L1 `GLib.Error`, which carries no `GError*` of
-// its own. Throws + returns nullptr when its domain is unusable.
-//
-// `.domainQuark` is the numeric GQuark the engine read off the original GError;
-// `.domain` is its NAME (the node-gi divergence documented in
-// docs/node-gi-gjs-surface.md), which is what an error constructed in JS from a
-// quark name carries. Either resolves to the same quark; a value with neither is
-// not a usable GError — quark 0 would produce an error no `matches()` can ever
-// answer for, so it is refused rather than marshalled into a silent mismatch.
-static GError* ErrorFromL1GLibError(Napi::Env env, Napi::Value v, const char* argName) {
-  Napi::Object err = v.As<Napi::Object>();
-  Napi::Value quark = err.Get("domainQuark");
-  Napi::Value domain = err.Get("domain");
-  GQuark gq = 0;
-  if (quark.IsNumber()) gq = static_cast<GQuark>(NodeGiToUint32(quark));
-  else if (domain.IsString())
-    gq = g_quark_from_string(domain.As<Napi::String>().Utf8Value().c_str());
-  if (gq == 0) {
-    ThrowExpectedGLibError(env, argName, "a GLib.Error with no domain");
-    return nullptr;
-  }
-  Napi::Value message = err.Get("message");
-  std::string text = message.IsString() ? message.As<Napi::String>().Utf8Value() : std::string();
-  return g_error_new_literal(gq, NodeGiToInt32(err.Get("code")), text.c_str());
-}
-
 // "Gtk.Box" for an introspected GType, g_type_name() otherwise (a registerClass
 // subtype has no GI info of its own; its C name is still exact). The gjs twin is
 // GIWrapperBase::format_name() (refs/gjs/gi/wrapperutils.h).
@@ -541,7 +516,6 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
                     CreatedClosures* closures,
                     CreatedBytes* bytes,
                     CreatedValues* values,
-                    CreatedErrors* errors,
                     const char* argName) {
   if (v.IsEmpty()) {
     // Residue of a swallowed napi failure (a fallible Get()/coercion upstream
@@ -829,43 +803,35 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
         out->v_pointer = nullptr;
         return true;
       }
-      // Shape 1: the boxed handle a GError-typed return/OUT produced. Ownership is
-      // the ordinary boxed one and TransferBoxedIn supplies it: transfer-none is a
-      // borrow, transfer-full hands the callee an independent g_error_copy
-      // (g_propagate_error ADOPTS and frees its `src`) so the JS handle's finalizer
-      // cannot double-free it. Measured against gjs: after `GLib.propagate_error(e)`
-      // the original `e` is still readable there too.
+      // There is exactly ONE shape to accept: the boxed handle every GError reaching
+      // JS carries, whether it was marshalled out, copied, constructed or thrown
+      // (L1's wrapGError puts the same handle on all four). The second arm this used
+      // to need — rebuilding a GError from an L1 Error subclass's JS fields — is gone
+      // with the subclass itself.
+      //
+      // Ownership is the ordinary boxed one and TransferBoxedIn supplies it:
+      // transfer-none is a borrow, transfer-full hands the callee an independent
+      // g_error_copy (g_propagate_error ADOPTS and frees its `src`) so the JS
+      // handle's finalizer cannot double-free it. Measured against gjs: after
+      // `GLib.propagate_error(e)` the original `e` is still readable there too.
       //
       // Type-safety is UNCONDITIONAL here, unlike the struct/boxed arm's "compare
       // only when both sides carry a registered GType": the expected type is known
       // (G_TYPE_ERROR, always), so a handle without it is a wrong pointer — and a
       // wrong pointer in a GError slot is a wild dereference inside GLib.
       BoxedHandle* h = TryGetBoxedHandle(v);
-      if (h != nullptr) {
-        if (h->gtype == G_TYPE_INVALID || !g_type_is_a(h->gtype, G_TYPE_ERROR)) {
-          ThrowExpectedGLibError(env, argName,
-                                 h->gtype != G_TYPE_INVALID ? g_type_name(h->gtype)
-                                                            : InformalValueTypeName(v));
-          return false;
-        }
-        out->v_pointer = TransferBoxedIn(h, transfer);
-        return true;
+      if (h == nullptr) {
+        ThrowExpectedGLibError(env, argName, InformalValueTypeName(v));
+        return false;
       }
-      // Shape 2: the L1 `GLib.Error` JS class — a caught error, or one built with
-      // `new GLib.Error(…)`. It carries no GError*, so build one and release it per
-      // transfer (CreatedErrors, the rule GBytes and GValue already follow). gjs has
-      // ONE object for both shapes and accepts either; refusing this one left the
-      // hand-back the OUT direction exists for closed to exactly the errors an
-      // application has in hand.
-      if (errors != nullptr && IsL1GLibError(env, v)) {
-        GError* built = ErrorFromL1GLibError(env, v, argName);
-        if (built == nullptr) return false;  // ErrorFromL1GLibError already threw
-        out->v_pointer = built;
-        errors->Record(built, transfer);
-        return true;
+      if (h->gtype == G_TYPE_INVALID || !g_type_is_a(h->gtype, G_TYPE_ERROR)) {
+        ThrowExpectedGLibError(
+            env, argName,
+            h->gtype != G_TYPE_INVALID ? g_type_name(h->gtype) : InformalValueTypeName(v));
+        return false;
       }
-      ThrowExpectedGLibError(env, argName, InformalValueTypeName(v));
-      return false;
+      out->v_pointer = TransferBoxedIn(h, transfer);
+      return true;
     }
     default:
       Napi::TypeError::New(
@@ -995,23 +961,10 @@ Napi::Value GIArgumentToJs(Napi::Env env, GITypeInfo* type, GIArgument* arg,
     }
     case GI_TYPE_TAG_ERROR: {
       // A GError-typed value (a `GLib.Error` return like Gtk.GLArea.get_error(),
-      // or a GLib.Error.new_literal construct): GJS surfaces it as a GLib.Error
-      // boxed (G_TYPE_ERROR) with `.domain`/`.code`/`.message` field access +
-      // `.matches()`/`.copy()` methods. Wrap through the GLib.Error struct info
-      // so the boxed handle resolves fields and methods; a NULL GError (the
-      // no-error case) stays null. WrapBoxed handles transfer: a transfer-none
-      // borrow is g_boxed_copy'd into an owned copy, transfer-full is adopted.
-      GError* gerr = static_cast<GError*>(arg->v_pointer);
-      if (gerr == nullptr) return env.Null();
-      GIRepository* repo = DupDefaultRepository();
-      // GLib is loaded by any namespace require; require defensively anyway so a
-      // bare engine call still resolves the struct info (idempotent, cheap).
-      gi_repository_require(repo, "GLib", "2.0", static_cast<GIRepositoryLoadFlags>(0), nullptr);
-      GIBaseInfo* errInfo = gi_repository_find_by_name(repo, "GLib", "Error");
-      Napi::Value result = WrapBoxed(env, gerr, errInfo, transfer);
-      if (errInfo != nullptr) gi_base_info_unref(errInfo);
-      g_object_unref(repo);
-      return result;
+      // or a GLib.Error.new_literal construct). The same handle a THROWN error
+      // carries, so L1 builds the same object from both — a NULL GError (the
+      // no-error case) stays null.
+      return MakeGErrorHandle(env, static_cast<GError*>(arg->v_pointer), transfer);
     }
     default:
       Napi::TypeError::New(env, "Unsupported return type tag " +
@@ -1861,7 +1814,7 @@ bool JsToAnswerArgument(Napi::Env env, Napi::Value v, GITypeInfo* ti, GITransfer
   }
   std::string held;
   return JsToGIArgument(env, v, ti, out, &held, transfer, nullptr, nullptr, nullptr, nullptr,
-                        nullptr, argName);
+                        argName);
 }
 
 }  // namespace

package/src/repo.cc

@@ -13,7 +13,6 @@ void NodeGiEnvDataFinalize(napi_env env, void* data, void* /*hint*/) {
   NodeGiEnvData* d = static_cast<NodeGiEnvData*>(data);
   if (d == nullptr) return;
   if (d->errorBuilder != nullptr) napi_delete_reference(env, d->errorBuilder);
-  if (d->errorClass != nullptr) napi_delete_reference(env, d->errorClass);
   if (d->templateCallbackResolver != nullptr)
     napi_delete_reference(env, d->templateCallbackResolver);
   if (d->cairoWrappers != nullptr) napi_delete_reference(env, d->cairoWrappers);
@@ -260,17 +259,52 @@ Napi::Value GetErrorDomain(const Napi::CallbackInfo& info) {
   return result;
 }
 
-// setErrorBuilder(builder: (domainName, domainQuark, code, message) => Error,
-//                 errorClass?: typeof GLib.Error) -> void
-// Register the L1 GLib.Error factory the engine calls when a GI invoke fails, so a
-// failed sync call throws a real GLib.Error, together with the class it builds —
-// which the GError IN-arg path needs to recognise one coming back. Both stored
-// per-env (a napi_ref is env-specific; both paths are gated on the same env), in
-// ONE call so a registration cannot supply the builder and forget the class.
+// errorDomainInfo(quark: number) -> { namespace: string, name: string } | null
+// Which introspected enum registered a GError domain quark, so L1 can resolve a
+// thrown error to its DOMAIN CLASS (Gio.IOErrorEnum) by reading that member.
+// getErrorDomain below answers the same relation the other way round, and L1's
+// quark→class map is only populated by it — which is not enough on its own: an
+// application that never named `Gio.IOErrorEnum` has nothing in the map, and the
+// error it catches would land on the base class, breaking exactly the
+// `catch (e) { if (e instanceof Gio.IOErrorEnum) }` idiom. Null for a quark no
+// typelib registers (a private `GLib.quark_from_string` domain).
+Napi::Value ErrorDomainInfo(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsNumber()) {
+    Napi::TypeError::New(env, "errorDomainInfo(quark: number)").ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  GQuark quark = static_cast<GQuark>(NodeGiToUint32(info[0]));
+  if (quark == 0) return env.Null();
+  GIRepository* repo = DupDefaultRepository();
+  GIEnumInfo* enumInfo = gi_repository_find_by_error_domain(repo, quark);
+  Napi::Value result = env.Null();
+  if (enumInfo != nullptr) {
+    GIBaseInfo* base = reinterpret_cast<GIBaseInfo*>(enumInfo);
+    const char* ns = gi_base_info_get_namespace(base);
+    const char* name = gi_base_info_get_name(base);
+    if (ns != nullptr && name != nullptr) {
+      Napi::Object obj = Napi::Object::New(env);
+      obj.Set("namespace", Napi::String::New(env, ns));
+      obj.Set("name", Napi::String::New(env, name));
+      result = obj;
+    }
+    gi_base_info_unref(base);
+  }
+  g_object_unref(repo);
+  return result;
+}
+
+// setErrorBuilder(builder: (handle) => GLib.Error) -> void
+// Register the L1 error factory the engine calls when a GI invoke fails, so a
+// failed sync call throws the error object of its domain's class. Stored per-env
+// (a napi_ref is env-specific). It takes the GError's boxed HANDLE — the L1 error
+// IS that handle, which is why nothing else needs registering here: the GError
+// IN-arg direction reads the same handle back off the object.
 Napi::Value SetErrorBuilder(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   if (info.Length() < 1 || !info[0].IsFunction()) {
-    Napi::TypeError::New(env, "setErrorBuilder(builder: function, errorClass?: function)")
+    Napi::TypeError::New(env, "setErrorBuilder(builder: function)")
         .ThrowAsJavaScriptException();
     return env.Undefined();
   }
@@ -281,12 +315,6 @@ Napi::Value SetErrorBuilder(const Napi::CallbackInfo& info) {
     d->errorBuilder = nullptr;
   }
   napi_create_reference(env, info[0], 1, &d->errorBuilder);
-  if (d->errorClass != nullptr) {
-    napi_delete_reference(env, d->errorClass);
-    d->errorClass = nullptr;
-  }
-  if (info.Length() >= 2 && info[1].IsFunction())
-    napi_create_reference(env, info[1], 1, &d->errorClass);
   return env.Undefined();
 }