@gjsify/node-gi 0.64.0 → 0.64.1

package/cairo.d.ts

@@ -17,6 +17,25 @@ export const Operator: CairoEnum;
 export const PatternType: CairoEnum;
 export const SurfaceType: CairoEnum;
 
+/** `cairo_text_extents_t`, in the shape GJS returns. */
+export interface TextExtents {
+    xBearing: number;
+    yBearing: number;
+    width: number;
+    height: number;
+    xAdvance: number;
+    yAdvance: number;
+}
+
+/** `cairo_font_extents_t`, in the shape GJS returns. */
+export interface FontExtents {
+    ascent: number;
+    descent: number;
+    height: number;
+    maxXAdvance: number;
+    maxYAdvance: number;
+}
+
 /** cairo drawing context (`cairo_t`). */
 export class Context {
     constructor(surface: Surface);
@@ -28,6 +47,12 @@ export class Context {
     lineTo(x: number, y: number): void;
     relMoveTo(dx: number, dy: number): void;
     relLineTo(dx: number, dy: number): void;
+    selectFontFace(family: string, slant: number, weight: number): void;
+    setFontSize(size: number): void;
+    showText(utf8: string): void;
+    textPath(utf8: string): void;
+    textExtents(utf8: string): TextExtents;
+    fontExtents(): FontExtents;
     rectangle(x: number, y: number, width: number, height: number): void;
     arc(xc: number, yc: number, radius: number, angle1: number, angle2: number): void;
     arcNegative(xc: number, yc: number, radius: number, angle1: number, angle2: number): void;

package/cairo.js

@@ -332,6 +332,29 @@ export class Context {
     fillExtents() {
         return c.fillExtents(this[H]);
     }
+    /** Select the toy-API font: `family` with a {@link FontSlant} and {@link FontWeight}. */
+    selectFontFace(family, slant, weight) {
+        c.selectFontFace(this[H], family, slant, weight);
+    }
+    setFontSize(size) {
+        c.setFontSize(this[H], size);
+    }
+    /** Draw `utf8` at the current point with the current source. */
+    showText(utf8) {
+        c.showText(this[H], utf8);
+    }
+    /** Append the outline of `utf8` to the current path. */
+    textPath(utf8) {
+        c.textPath(this[H], utf8);
+    }
+    /** `{ xBearing, yBearing, width, height, xAdvance, yAdvance }` of `utf8` in the current font. */
+    textExtents(utf8) {
+        return c.textExtents(this[H], utf8);
+    }
+    /** `{ ascent, descent, height, maxXAdvance, maxYAdvance }` of the current font. */
+    fontExtents() {
+        return c.fontExtents(this[H]);
+    }
     /** Stroke bounding box as `[x1, y1, x2, y2]`. */
     strokeExtents() {
         return c.strokeExtents(this[H]);

package/gi.js

@@ -48,11 +48,21 @@ function camelToSnake(name) {
     return name.replace(/([A-Z])/g, '_$1').toLowerCase();
 }
 
+// Memoized: the wrapper's get/set/has traps convert on EVERY property access, the
+// answer depends on nothing but the name, and the set of names a program uses is
+// bounded by its source text — three regex passes per access buy nothing.
+const kebabNames = new Map();
+
 function toKebab(name) {
-    return name
-        .replace(/([A-Z])/g, '-$1')
-        .replace(/_/g, '-')
-        .toLowerCase();
+    let kebab = kebabNames.get(name);
+    if (kebab === undefined) {
+        kebab = name
+            .replace(/([A-Z])/g, '-$1')
+            .replace(/_/g, '-')
+            .toLowerCase();
+        kebabNames.set(name, kebab);
+    }
+    return kebab;
 }
 
 // Repeated passes of the same callback must marshal to the SAME native-facing function:
@@ -221,26 +231,10 @@ function wrapGError(handle, withPosition = false, hideAbove = wrapGError) {
 // 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) {
+    if (native.callFunction('GLib', 'quark_to_string', [domain]) === 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;
+    return native.callStaticMethod('GLib', 'Error', 'new_literal', [domain, code, message]);
 }
 
 // `GLib.Error`: a plain FUNCTION, not a `class … extends Error` — GJS's
@@ -303,7 +297,7 @@ Object.defineProperties(GLibError.prototype, {
                 `method GLib.Error.matches: At least 2 arguments required, but only ${arguments.length} passed`,
             );
         }
-        return native.callBoxedMethod(this[HANDLE], 'matches', [toDomainQuark(domain), code]);
+        return native.callBoxedMethod(this[HANDLE], 'matches', [domain, code]);
     }),
 });
 defineErrorFields(GLibError.prototype, 'GLib.Error', undefined);
@@ -396,6 +390,13 @@ const promisifiedWrappers = new WeakSet();
 const nativeThunks = new WeakSet();
 
 function wrapReturn(value) {
+    // EVERY engine value comes through here — each return, each OUT tuple element and
+    // each signal argument (wrapSignalCallback) — and the five tag probes below are
+    // five N-API crossings. A handle is always an OBJECT (a tagged napi External), so a
+    // primitive can answer for itself: a `notify::label` handler's `(emitter, pspec)`
+    // then costs two probes for the emitter instead of ten for the pair, and the string
+    // argument of an ordinary `emit('changed', 'x')` costs none.
+    if (value === null || typeof value !== 'object') return value;
     if (native.isGObjectHandle(value)) return wrapInstance(value);
     // A GLib.Variant is ALSO a boxed handle by tag, so it must be checked first to get
     // the Variant ergonomics rather than a plain method-routing proxy.
@@ -543,36 +544,51 @@ function wrapBoxed(handle) {
 // GParamSpec-typed value surface as. Carries [HANDLE] so it round-trips back into the
 // engine and `instanceof GObject.ParamSpec` recognises it. value_type/owner_type are
 // native GType handles, like gjs's GType objects.
+// The accessors live HERE, on one shared prototype, and read the handle off `this`.
+// Built per instance they were eleven fresh closures plus a twelve-slot object on
+// EVERY notify emission — the engine hands the pspec to the handler whether or not
+// the handler looks at it, so that allocation landed on every property write of the
+// real-GObject engine. On gjs these same members live on GObject.ParamSpec.prototype,
+// so prototype-held is also the closer shape.
+const paramSpecProto = {
+    get name() {
+        return native.paramSpecProp(this[HANDLE], 'name');
+    },
+    get nick() {
+        return native.paramSpecProp(this[HANDLE], 'nick');
+    },
+    get blurb() {
+        return native.paramSpecProp(this[HANDLE], 'blurb');
+    },
+    get flags() {
+        return native.paramSpecProp(this[HANDLE], 'flags');
+    },
+    get value_type() {
+        return native.paramSpecProp(this[HANDLE], 'valueType');
+    },
+    get owner_type() {
+        return native.paramSpecProp(this[HANDLE], 'ownerType');
+    },
+    get default_value() {
+        return wrapReturn(native.paramSpecProp(this[HANDLE], 'defaultValue'));
+    },
+    get_name() {
+        return native.paramSpecProp(this[HANDLE], 'name');
+    },
+    get_nick() {
+        return native.paramSpecProp(this[HANDLE], 'nick');
+    },
+    get_blurb() {
+        return native.paramSpecProp(this[HANDLE], 'blurb');
+    },
+    get_default_value() {
+        return wrapReturn(native.paramSpecProp(this[HANDLE], 'defaultValue'));
+    },
+};
+
 function wrapParamSpec(handle) {
-    const prop = (which) => native.paramSpecProp(handle, which);
-    const pspec = {
-        [HANDLE]: handle,
-        get name() {
-            return prop('name');
-        },
-        get nick() {
-            return prop('nick');
-        },
-        get blurb() {
-            return prop('blurb');
-        },
-        get flags() {
-            return prop('flags');
-        },
-        get value_type() {
-            return prop('valueType');
-        },
-        get owner_type() {
-            return prop('ownerType');
-        },
-        get default_value() {
-            return wrapReturn(prop('defaultValue'));
-        },
-        get_name: () => prop('name'),
-        get_nick: () => prop('nick'),
-        get_blurb: () => prop('blurb'),
-        get_default_value: () => wrapReturn(prop('defaultValue')),
-    };
+    const pspec = Object.create(paramSpecProto);
+    pspec[HANDLE] = handle;
     return pspec;
 }
 
@@ -1063,7 +1079,27 @@ function assignTemplateChildren(instance, handle, reg) {
 // resolves the same three spellings at the point of use instead — same reachability,
 // no accessor synthesis. Learn6502's SourceView is exactly why this matters: its
 // property is `line-numbers` and its accessor is `lineNumbers`.
+// Resolved per prototype, INCLUDING the "this class declares none" answer (null).
+// The native store calls runJsPropertySetter on every write of a custom property, so
+// without this a class with no accessor at all — the common case — paid three
+// prototype-chain walks and two regex rewrites per assignment to learn nothing. GJS
+// settles the same question once, at registerClass time (`_checkAccessors` mirrors
+// the declared spelling onto the other two); a prototype gaining an accessor later is
+// outside what either runtime honours.
+const propertySettersByProto = new WeakMap();
+
 function findPropertySetter(userProto, propertyName) {
+    let perProto = propertySettersByProto.get(userProto);
+    if (perProto === undefined) propertySettersByProto.set(userProto, (perProto = new Map()));
+    let setter = perProto.get(propertyName);
+    if (setter === undefined) {
+        setter = resolvePropertySetter(userProto, propertyName) ?? null;
+        perProto.set(propertyName, setter);
+    }
+    return setter ?? undefined;
+}
+
+function resolvePropertySetter(userProto, propertyName) {
     const underscored = propertyName.replace(/-/g, '_');
     const camel = propertyName.replace(/-([a-z])/g, (m) => m[1].toUpperCase());
     for (const spelling of [propertyName, underscored, camel]) {
@@ -1548,6 +1584,30 @@ function wrapInstance(handle, userProto) {
         materialised.add(name);
         return had;
     };
+    // The `connect`/`connect_after`/`emit`/`disconnect` thunks of this wrapper, each
+    // built on its first use (see the `get` trap). A null prototype so an unrelated
+    // name — `constructor`, `toString` — cannot be mistaken for a built shortcut.
+    const signalShortcuts = Object.create(null);
+    // The GI-method thunks of this wrapper, built on first use, `null` for a name
+    // that resolves to no introspected method. A thunk is a pure function of
+    // (handle, name) and presence is already memoized per GType (instanceHasMethod),
+    // so the only thing that changes by keeping it is IDENTITY — and a STABLE one is
+    // the GJS shape: there the method lives on the prototype, so `obj.m === obj.m`
+    // (the reason a user prototype's own function is handed back unbound, #1175).
+    // Built fresh, every `obj.m(…)` in a loop allocated a closure and re-asked for
+    // the type name across the N-API boundary. Null prototype: `constructor` and
+    // friends must not read as a cached thunk.
+    const giMethodThunks = Object.create(null);
+    const giMethodThunk = (prop) => {
+        let thunk = giMethodThunks[prop];
+        if (thunk === undefined) {
+            thunk = instanceHasMethod(handle, prop)
+                ? (...args) => wrapReturn(native.callMethod(handle, prop, unwrapArgs(args)))
+                : null;
+            giMethodThunks[prop] = thunk;
+        }
+        return thunk ?? undefined;
+    };
     const proxy = new Proxy(target, {
         get(t, prop) {
             if (prop === HANDLE) return handle;
@@ -1561,10 +1621,16 @@ function wrapInstance(handle, userProto) {
                 // 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)));
-                }
+                const method = giMethodThunk(prop);
+                if (method !== undefined) return method;
             }
+            // The four signal shortcuts below close over nothing but `handle`, so they
+            // are per-wrapper constants — yet the switch rebuilt one on EVERY access,
+            // i.e. one throwaway closure per `obj.emit(…)` in a loop. Built once here
+            // and reused; on gjs these live on GObject.Object.prototype and have stable
+            // identity too. Lazy, because most wrappers never reach for one.
+            const shortcut = signalShortcuts[prop];
+            if (shortcut !== undefined) return shortcut;
             switch (prop) {
                 case '$typeName':
                     // The instance's concrete RUNTIME GType name —
@@ -1581,24 +1647,25 @@ function wrapInstance(handle, userProto) {
                 case 'connect':
                     // Record the (user fn → id) mapping so signal_handlers_*_by_func can
                     // resolve the private-closure handler back to its ids (see the registry).
-                    return (signal, cb) => {
+                    return (signalShortcuts.connect = (signal, cb) => {
                         const id = native.connectSignal(handle, signal, wrapSignalCallback(cb), false);
                         recordSignalHandler(handle, cb, id);
                         return id;
-                    };
+                    });
                 case 'connect_after':
-                    return (signal, cb) => {
+                    return (signalShortcuts.connect_after = (signal, cb) => {
                         const id = native.connectSignal(handle, signal, wrapSignalCallback(cb), true);
                         recordSignalHandler(handle, cb, id);
                         return id;
-                    };
+                    });
                 case 'emit':
-                    return (signal, ...args) => wrapReturn(native.emitSignal(handle, signal, unwrapArgs(args)));
+                    return (signalShortcuts.emit = (signal, ...args) =>
+                        wrapReturn(native.emitSignal(handle, signal, unwrapArgs(args))));
                 case 'disconnect':
-                    return (id) => {
+                    return (signalShortcuts.disconnect = (id) => {
                         forgetSignalHandlerId(handle, id);
                         return native.disconnectSignal(handle, id);
-                    };
+                    });
                 default:
                     break;
             }
@@ -1674,10 +1741,7 @@ function wrapInstance(handle, userProto) {
             // camelCase like Gwebgl's `getString`) and only falls back to the
             // snake_case alias. Converting here would destroy a literal camelCase
             // GI name.
-            if (instanceHasMethod(handle, prop)) {
-                return (...args) => wrapReturn(native.callMethod(handle, prop, unwrapArgs(args)));
-            }
-            return undefined;
+            return giMethodThunk(prop);
         },
         set(t, prop, value) {
             if (typeof prop === 'string') {

package/overrides/gio-settings.js

@@ -10,16 +10,8 @@
 // throws; this is the same wrapper, so `try { … } catch` means the same on either runtime
 // (ADR 0099 conformance row `errors`).
 //
-// Two deliberate differences from the GJS override:
-//   • the constructor check is a Proxy `construct` trap — a node-gi class has no `_init` to wrap;
-//   • `set_int` / `set_uint` range-check their value, which in GJS is the argument marshaller's
-//     job. node-gi's marshaller wraps modulo 2^32 (`set_uint('k', -1)` stores 4294967295), a
-//     general divergence recorded in status/open-todos/node-gi.md; this keeps the settings
-//     surface honest without touching the addon, so it also holds in an already-built payload.
-
-const INT32_MIN = -(2 ** 31);
-const INT32_MAX = 2 ** 31 - 1;
-const UINT32_MAX = 2 ** 32 - 1;
+// One deliberate difference from the GJS override: the constructor check is a Proxy `construct`
+// trap — a node-gi class has no `_init` to wrap.
 
 const CHECKED = [
     'get_boolean',
@@ -53,12 +45,6 @@ const CHECKED = [
     'reset',
 ];
 
-/** The range a setter's JS number must be in; GJS's marshaller throws this exact message. */
-const RANGES = {
-    set_int: [INT32_MIN, INT32_MAX, 'int32'],
-    set_uint: [0, UINT32_MAX, 'uint32'],
-};
-
 /**
  * Patch `Gio.Settings` / `Gio.SettingsSchema` like GJS does, once, and return the class to hand
  * out (a Proxy whose `new` refuses a schema that is not installed instead of aborting).
@@ -87,16 +73,8 @@ export function createGioSettings(Gio) {
     for (const name of CHECKED) {
         const real = proto[name];
         if (typeof real !== 'function') continue;
-        const range = RANGES[name];
         proto[name] = function (key, ...args) {
             checkKey(this, key);
-            if (range !== undefined) {
-                const [min, max, type] = range;
-                const value = args[0];
-                if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
-                    throw new Error(`Argument value: value is out of range for ${type}`);
-                }
-            }
             return real.call(this, key, ...args);
         };
     }

package/package.json

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

@@ -17,7 +17,8 @@
 // WrapBoxed; cairo_path_t is NOT ref-counted, so a borrowed path is COPIED via
 // the gjs CairoPath::copy_ptr dummy-context trick instead of ref'd). Slice:
 // Context (drawing ops, path copy/append, dash, matrix point transforms,
-// in-fill/in-stroke, getSource), Surface + ImageSurface (headless pixels),
+// in-fill/in-stroke, getSource, the toy-text API: selectFontFace/setFontSize/
+// showText/textPath/textExtents/fontExtents), Surface + ImageSurface (headless pixels),
 // SolidPattern, LinearGradient/RadialGradient (color stops), SurfacePattern
 // (extend/filter), Path handles. Deferred: region, PDF/SVG/PS surfaces,
 // text/font ops (showText/selectFontFace — canvas2d text rides PangoCairo).
@@ -733,6 +734,70 @@ void InitCairo(Napi::Env env, Napi::Object exports) {
   CTX_EXTENTS("fillExtents", cairo_fill_extents)
   CTX_EXTENTS("strokeExtents", cairo_stroke_extents)
   CTX_EXTENTS("clipExtents", cairo_clip_extents)
+  // Toy text API (cairo_select_font_face & co), the GJS-compatible Context text ops.
+  // textExtents/fontExtents return the object shape gjs's cairo-context.cpp builds.
+  c.Set("selectFontFace", Napi::Function::New(env, +[](const Napi::CallbackInfo& info) -> Napi::Value {
+          Napi::Env env = info.Env();
+          cairo_t* cr = CtxArg(env, info);
+          if (cr == nullptr) return env.Undefined();
+          std::string family = info[1].ToString().Utf8Value();
+          cairo_select_font_face(cr, family.c_str(),
+                                 static_cast<cairo_font_slant_t>(info[2].ToNumber().Int32Value()),
+                                 static_cast<cairo_font_weight_t>(info[3].ToNumber().Int32Value()));
+          CheckStatus(env, cairo_status(cr), "selectFontFace");
+          return env.Undefined();
+        }));
+  c.Set("setFontSize", Napi::Function::New(env, CTX_1D(cairo_set_font_size)));
+  c.Set("showText", Napi::Function::New(env, +[](const Napi::CallbackInfo& info) -> Napi::Value {
+          Napi::Env env = info.Env();
+          cairo_t* cr = CtxArg(env, info);
+          if (cr == nullptr) return env.Undefined();
+          std::string text = info[1].ToString().Utf8Value();
+          cairo_show_text(cr, text.c_str());
+          CheckStatus(env, cairo_status(cr), "showText");
+          return env.Undefined();
+        }));
+  c.Set("textPath", Napi::Function::New(env, +[](const Napi::CallbackInfo& info) -> Napi::Value {
+          Napi::Env env = info.Env();
+          cairo_t* cr = CtxArg(env, info);
+          if (cr == nullptr) return env.Undefined();
+          std::string text = info[1].ToString().Utf8Value();
+          cairo_text_path(cr, text.c_str());
+          CheckStatus(env, cairo_status(cr), "textPath");
+          return env.Undefined();
+        }));
+  c.Set("textExtents", Napi::Function::New(env, +[](const Napi::CallbackInfo& info) -> Napi::Value {
+          Napi::Env env = info.Env();
+          cairo_t* cr = CtxArg(env, info);
+          if (cr == nullptr) return env.Undefined();
+          std::string text = info[1].ToString().Utf8Value();
+          cairo_text_extents_t e;
+          cairo_text_extents(cr, text.c_str(), &e);
+          if (!CheckStatus(env, cairo_status(cr), "textExtents")) return env.Undefined();
+          Napi::Object o = Napi::Object::New(env);
+          o.Set("xBearing", Napi::Number::New(env, e.x_bearing));
+          o.Set("yBearing", Napi::Number::New(env, e.y_bearing));
+          o.Set("width", Napi::Number::New(env, e.width));
+          o.Set("height", Napi::Number::New(env, e.height));
+          o.Set("xAdvance", Napi::Number::New(env, e.x_advance));
+          o.Set("yAdvance", Napi::Number::New(env, e.y_advance));
+          return o;
+        }));
+  c.Set("fontExtents", Napi::Function::New(env, +[](const Napi::CallbackInfo& info) -> Napi::Value {
+          Napi::Env env = info.Env();
+          cairo_t* cr = CtxArg(env, info);
+          if (cr == nullptr) return env.Undefined();
+          cairo_font_extents_t e;
+          cairo_font_extents(cr, &e);
+          if (!CheckStatus(env, cairo_status(cr), "fontExtents")) return env.Undefined();
+          Napi::Object o = Napi::Object::New(env);
+          o.Set("ascent", Napi::Number::New(env, e.ascent));
+          o.Set("descent", Napi::Number::New(env, e.descent));
+          o.Set("height", Napi::Number::New(env, e.height));
+          o.Set("maxXAdvance", Napi::Number::New(env, e.max_x_advance));
+          o.Set("maxYAdvance", Napi::Number::New(env, e.max_y_advance));
+          return o;
+        }));
   c.Set("status", Napi::Function::New(env, +[](const Napi::CallbackInfo& info) -> Napi::Value {
           Napi::Env env = info.Env();
           cairo_t* cr = CtxArg(env, info);

package/src/calls.cc

@@ -1242,6 +1242,57 @@ static GIFunctionInfo* ResolveInstanceMethod(GIRepository* repo, GType gtype, GI
   return func;
 }
 
+// Resolved instance methods, keyed by the instance's concrete GType and the name
+// as JS spelled it. The resolution above is the expensive half of a GI call —
+// dup the default repository, walk the GType parents for the nearest
+// GIObjectInfo, then search own + interface + inherited method tables twice (the
+// literal name, then the snake_case alias) — and it repeats IDENTICALLY on every
+// call, because a typelib's method tables do not change at runtime. MEASURED on
+// this machine (gjs 1.88.1 / GLib 2.88.3): `set_property` on a registerClass
+// subclass cost 8224 ns through callMethod against 2815 ns for the same
+// g_object_set_property through setProperty — 5.4 µs of pure re-resolution per
+// call, which is most of what a property write on the real-GObject engine spends.
+//
+// Only a HIT is cached. A miss must stay uncached: namespaces load lazily, so a
+// name that resolves to nothing now can resolve after the typelib that declares
+// it is required — caching the miss would make load order change behaviour.
+//
+// The cache OWNS the ref it holds (GIFunctionInfos live as long as the process
+// anyway, and the entry count is bounded by the methods a program actually
+// calls); callers get a borrowed pointer and must not unref it. Written only
+// from the JS thread, like every other entry point here.
+static std::map<std::pair<GType, std::string>, GIFunctionInfo*> g_instanceMethodCache;
+
+// The resolution of ResolveInstanceMethod, memoized. Returns a BORROWED pointer
+// (never unref) or nullptr.
+static GIFunctionInfo* ResolveInstanceMethodCached(GType gtype, const std::string& method) {
+  const std::pair<GType, std::string> key(gtype, method);
+  auto it = g_instanceMethodCache.find(key);
+  if (it != g_instanceMethodCache.end()) return it->second;
+
+  GIRepository* repo = DupDefaultRepository();
+  GIObjectInfo* objInfo = FindNearestObjectInfo(repo, gtype);
+  GIFunctionInfo* func = nullptr;
+  if (objInfo != nullptr) {
+    func = ResolveInstanceMethod(repo, gtype, objInfo, method);
+    gi_base_info_unref(objInfo);
+  }
+  g_object_unref(repo);
+  if (func != nullptr) g_instanceMethodCache.emplace(key, func);
+  return func;
+}
+
+// Whether `gtype` has introspection info at all — the distinction callMethod
+// reports as "no introspection info for X" before it even looks for a method.
+static bool HasObjectInfo(GType gtype) {
+  GIRepository* repo = DupDefaultRepository();
+  GIObjectInfo* objInfo = FindNearestObjectInfo(repo, gtype);
+  const bool found = objInfo != nullptr;
+  if (objInfo != nullptr) gi_base_info_unref(objInfo);
+  g_object_unref(repo);
+  return found;
+}
+
 // callMethod(handle, methodName, args?: unknown[]) -> unknown
 // Resolve an instance method by walking the instance's GIObjectInfo (own +
 // implemented-interface methods at each level, then up the parent chain), then
@@ -1262,20 +1313,14 @@ Napi::Value CallMethod(const Napi::CallbackInfo& info) {
                                                               : Napi::Array::New(env, 0);
 
   GType gtype = G_OBJECT_TYPE(obj);
-  GIRepository* repo = DupDefaultRepository();
+  GIFunctionInfo* func = ResolveInstanceMethodCached(gtype, method);
 
-  GIObjectInfo* objInfo = FindNearestObjectInfo(repo, gtype);
-  if (objInfo == nullptr) {
-    g_object_unref(repo);
+  if (func == nullptr && !HasObjectInfo(gtype)) {
     Napi::Error::New(env, std::string("no introspection info for ") + G_OBJECT_TYPE_NAME(obj))
         .ThrowAsJavaScriptException();
     return env.Null();
   }
 
-  GIFunctionInfo* func = ResolveInstanceMethod(repo, gtype, objInfo, method);
-  gi_base_info_unref(objInfo);
-  g_object_unref(repo);
-
   if (func == nullptr) {
     // On a terminating env the method-name read (info[1].Utf8Value) degrades to
     // "" (a swallowed napi failure), so resolution misses and we land here — but
@@ -1290,15 +1335,13 @@ Napi::Value CallMethod(const Napi::CallbackInfo& info) {
     return env.Null();
   }
   if (!gi_callable_info_is_method(reinterpret_cast<GICallableInfo*>(func))) {
-    gi_base_info_unref(func);
     Napi::TypeError::New(env, method + " is not an instance method").ThrowAsJavaScriptException();
     return env.Null();
   }
 
-  Napi::Value result =
-      InvokeFunctionInfo(env, func, obj, args, std::string(G_OBJECT_TYPE_NAME(obj)) + "." + method);
-  gi_base_info_unref(func);
-  return result;
+  // The cache owns `func`; this is a borrowed pointer.
+  return InvokeFunctionInfo(env, func, obj, args,
+                            std::string(G_OBJECT_TYPE_NAME(obj)) + "." + method);
 }
 
 // hasMethod(handle, methodName) -> boolean
@@ -1321,20 +1364,10 @@ Napi::Value HasMethod(const Napi::CallbackInfo& info) {
   if (obj == nullptr) return env.Null();
   std::string method = info[1].As<Napi::String>().Utf8Value();
 
-  GType gtype = G_OBJECT_TYPE(obj);
-  GIRepository* repo = DupDefaultRepository();
-  GIObjectInfo* objInfo = FindNearestObjectInfo(repo, gtype);
-  if (objInfo == nullptr) {
-    g_object_unref(repo);
-    return Napi::Boolean::New(env, false);
-  }
-  GIFunctionInfo* func = ResolveInstanceMethod(repo, gtype, objInfo, method);
-  gi_base_info_unref(objInfo);
-  g_object_unref(repo);
+  GIFunctionInfo* func = ResolveInstanceMethodCached(G_OBJECT_TYPE(obj), method);
   if (func == nullptr) return Napi::Boolean::New(env, false);
-  const bool invocable = gi_callable_info_is_method(reinterpret_cast<GICallableInfo*>(func));
-  gi_base_info_unref(func);
-  return Napi::Boolean::New(env, invocable);
+  return Napi::Boolean::New(env,
+                            gi_callable_info_is_method(reinterpret_cast<GICallableInfo*>(func)));
 }
 
 // hasClassMethod(namespace, typeName, methodName) -> boolean

package/src/common.h

@@ -35,6 +35,7 @@
 #endif
 
 #ifndef _WIN32
+#include <cmath>
 #include <dlfcn.h>  // dlopen/dlsym the GtkWidgetClass template API (no GTK link)
 #endif
 #include <napi.h>
@@ -280,6 +281,162 @@ inline uint64_t JsValueToUint64(Napi::Value v) {
   return n.IsEmpty() ? 0 : static_cast<uint64_t>(n.Int64Value());
 }
 
+// IN integers, GJS-exact (refs/gjs/gi/js-value-inl.h, arg-inl.h): an integer tag
+// REFUSES an out-of-range value instead of wrapping it. The rule is not uniform and is
+// copied as is, never made stricter: 8/16-bit run ToInt32 first (so it wraps mod 2^32)
+// and then compare against the tag range; int32 is not checked at all; uint32 and the
+// 64-bit tags refuse what falls outside their range. undefined and a non-finite Number
+// become 0. `shown` receives the text GJS prints for the offending value.
+// kPending: a BigInt/Symbol hit ToNumber, the TypeError is already pending — the caller
+// must stop without throwing a second error.
+enum class NodeGiIntResult { kOk, kOutOfRange, kPending };
+inline NodeGiIntResult NodeGiJsToInteger(Napi::Value v, GITypeTag tag, GIArgument* out,
+                                         std::string* shown) {
+  const bool is64 = tag == GI_TYPE_TAG_INT64 || tag == GI_TYPE_TAG_UINT64;
+  if (is64 && v.IsBigInt()) {
+    bool lossless = false;
+    if (tag == GI_TYPE_TAG_INT64) {
+      out->v_int64 = v.As<Napi::BigInt>().Int64Value(&lossless);
+    } else {
+      out->v_uint64 = v.As<Napi::BigInt>().Uint64Value(&lossless);
+    }
+    if (!lossless && shown != nullptr) *shown = "0";
+    return lossless ? NodeGiIntResult::kOk : NodeGiIntResult::kOutOfRange;
+  }
+  Napi::Number n = v.ToNumber();
+  if (n.IsEmpty()) return NodeGiIntResult::kPending;
+  double d = n.DoubleValue();
+  switch (tag) {
+    case GI_TYPE_TAG_INT8:
+    case GI_TYPE_TAG_UINT8:
+    case GI_TYPE_TAG_INT16:
+    case GI_TYPE_TAG_UINT16: {
+      int32_t i = n.Int32Value();
+      int32_t lo = tag == GI_TYPE_TAG_INT8 ? INT8_MIN : tag == GI_TYPE_TAG_INT16 ? INT16_MIN : 0;
+      int32_t hi = tag == GI_TYPE_TAG_INT8 ? INT8_MAX : tag == GI_TYPE_TAG_UINT8 ? UINT8_MAX
+                   : tag == GI_TYPE_TAG_INT16 ? INT16_MAX : UINT16_MAX;
+      if (shown != nullptr) *shown = std::to_string(i);
+      if (i < lo || i > hi) return NodeGiIntResult::kOutOfRange;
+      if (tag == GI_TYPE_TAG_INT8) out->v_int8 = static_cast<int8_t>(i);
+      else if (tag == GI_TYPE_TAG_UINT8) out->v_uint8 = static_cast<uint8_t>(i);
+      else if (tag == GI_TYPE_TAG_INT16) out->v_int16 = static_cast<int16_t>(i);
+      else out->v_uint16 = static_cast<uint16_t>(i);
+      return NodeGiIntResult::kOk;
+    }
+    case GI_TYPE_TAG_INT32:
+      out->v_int32 = n.Int32Value();
+      return NodeGiIntResult::kOk;
+    case GI_TYPE_TAG_UINT32: {
+      bool zero = v.IsUndefined() || (v.IsNumber() && !std::isfinite(d));
+      if (zero) {
+        out->v_uint32 = 0;
+        return NodeGiIntResult::kOk;
+      }
+      if (shown != nullptr) *shown = std::to_string(d);
+      if (std::isnan(d) || d < 0 || d > static_cast<double>(UINT32_MAX))
+        return NodeGiIntResult::kOutOfRange;
+      out->v_uint32 = static_cast<uint32_t>(d);
+      return NodeGiIntResult::kOk;
+    }
+    case GI_TYPE_TAG_INT64: {
+      double t = std::isfinite(d) ? std::trunc(d) : 0;
+      if (t < -9223372036854775808.0 || t >= 9223372036854775808.0) {
+        if (shown != nullptr)
+          *shown = std::to_string(t < 0 ? INT64_MIN : INT64_MAX);
+        return NodeGiIntResult::kOutOfRange;
+      }
+      out->v_int64 = static_cast<int64_t>(t);
+      return NodeGiIntResult::kOk;
+    }
+    case GI_TYPE_TAG_UINT64: {
+      double t = std::isfinite(d) ? std::trunc(d) : 0;
+      if (t < 0 || t >= 18446744073709551616.0) {
+        if (shown != nullptr)
+          *shown = std::to_string(t < 0 ? uint64_t{0} : UINT64_MAX);
+        return NodeGiIntResult::kOutOfRange;
+      }
+      out->v_uint64 = static_cast<uint64_t>(t);
+      return NodeGiIntResult::kOk;
+    }
+    default:
+      return NodeGiIntResult::kOk;
+  }
+}
+
+enum class NodeGiIntContext { kArgument, kField, kReturnValue };
+inline const char* NodeGiIntTagName(GITypeTag tag) {
+  switch (tag) {
+    case GI_TYPE_TAG_INT8: return "int8";
+    case GI_TYPE_TAG_UINT8: return "uint8";
+    case GI_TYPE_TAG_INT16: return "int16";
+    case GI_TYPE_TAG_UINT16: return "uint16";
+    case GI_TYPE_TAG_INT32: return "int32";
+    case GI_TYPE_TAG_UINT32: return "uint32";
+    case GI_TYPE_TAG_INT64: return "int64";
+    default: return "uint64";
+  }
+}
+// GJS's three texts (arg-cache.cpp / arg.cpp), plain Error.
+inline void NodeGiThrowIntOutOfRange(Napi::Env env, GITypeTag tag, NodeGiIntContext ctx,
+                                     const char* name, const std::string& shown) {
+  std::string t = NodeGiIntTagName(tag);
+  std::string msg;
+  if (ctx == NodeGiIntContext::kArgument) {
+    msg = std::string("Argument ") + (name != nullptr ? name : "") + ": value is out of range for " + t;
+  } else {
+    msg = "value " + shown + " is out of range for " +
+          (ctx == NodeGiIntContext::kField ? std::string("Field '") + (name ? name : "") + "'"
+                                           : std::string("Return value")) +
+          " (type " + t + ")";
+  }
+  Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+}
+
+// IN array elements and GValue int/uint, GJS-exact: these WRAP instead of refusing.
+// An array element goes through js_value_to_c_strict (refs/gjs/gi/arg.cpp:543), which
+// is ToInt32/ToUint32 truncated to the tag for 8/16/32 bits and ToInt64/ToUint64 —
+// modulo 2^64 — for 64 bits; a BigInt takes ToBigInt64/ToBigUint64 (also modulo 2^64)
+// on a 64-bit tag and is a TypeError on a narrower one. kPending: that TypeError is
+// already pending, the caller must stop without throwing a second error.
+inline uint64_t NodeGiWrapToUint64(double d) {
+  if (!std::isfinite(d)) return 0;
+  double m = std::fmod(std::trunc(d), 18446744073709551616.0);
+  return m < 0 ? uint64_t{0} - static_cast<uint64_t>(-m) : static_cast<uint64_t>(m);
+}
+inline NodeGiIntResult NodeGiJsToIntegerWrap(Napi::Value v, GITypeTag tag, GIArgument* out) {
+  const bool is64 = tag == GI_TYPE_TAG_INT64 || tag == GI_TYPE_TAG_UINT64;
+  if (is64 && v.IsBigInt()) {
+    bool lossless = false;
+    out->v_uint64 = v.As<Napi::BigInt>().Uint64Value(&lossless);
+    return NodeGiIntResult::kOk;
+  }
+  Napi::Number n = v.ToNumber();
+  if (n.IsEmpty()) return NodeGiIntResult::kPending;
+  switch (tag) {
+    case GI_TYPE_TAG_INT8: out->v_int8 = static_cast<int8_t>(n.Int32Value()); break;
+    case GI_TYPE_TAG_UINT8: out->v_uint8 = static_cast<uint8_t>(n.Uint32Value()); break;
+    case GI_TYPE_TAG_INT16: out->v_int16 = static_cast<int16_t>(n.Int32Value()); break;
+    case GI_TYPE_TAG_UINT16: out->v_uint16 = static_cast<uint16_t>(n.Uint32Value()); break;
+    case GI_TYPE_TAG_INT32: out->v_int32 = n.Int32Value(); break;
+    case GI_TYPE_TAG_UINT32: out->v_uint32 = n.Uint32Value(); break;
+    case GI_TYPE_TAG_INT64:
+    case GI_TYPE_TAG_UINT64: out->v_uint64 = NodeGiWrapToUint64(n.DoubleValue()); break;
+    default: break;
+  }
+  return NodeGiIntResult::kOk;
+}
+
+// GValue char/uchar/int64/uint64: refused out of range with gjs_value_to_g_value's own
+// text (refs/gjs/gi/value.cpp:602-690, throw_expect_type), a plain Error. `what` is the
+// "expected" noun gjs prints; the offending value is its JS ToString.
+inline void NodeGiThrowGValueOutOfRange(Napi::Env env, Napi::Value v, const char* what) {
+  Napi::String s = v.ToString();
+  std::string shown = s.IsEmpty() ? std::string() : s.Utf8Value();
+  Napi::Error::New(env, std::string("Wrong type ") + (v.IsBigInt() ? "bigint" : "number") + "; " +
+                            what + " expected. But it's out of range: " + shown)
+      .ThrowAsJavaScriptException();
+}
+
 // OUT (WarnIfUnsafe{Int,Uint}64): GJS ALWAYS returns a JS Number for a 64-bit int
 // (never a BigInt) and emits this g_warning when the value falls outside the range
 // a double represents exactly (|v| > 2^53 - 1 == Number.MAX_SAFE_INTEGER), because
@@ -391,7 +548,8 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
                     CreatedClosures* closures = nullptr,
                     CreatedBytes* bytes = nullptr,
                     CreatedValues* values = nullptr,
-                    const char* argName = nullptr);
+                    const char* argName = nullptr,
+                    NodeGiIntContext intContext = NodeGiIntContext::kArgument);
 
 // ---- IN container building -----------------------------------------
 //

package/src/marshal.cc

@@ -516,7 +516,8 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
                     CreatedClosures* closures,
                     CreatedBytes* bytes,
                     CreatedValues* values,
-                    const char* argName) {
+                    const char* argName,
+                    NodeGiIntContext intContext) {
   if (v.IsEmpty()) {
     // Residue of a swallowed napi failure (a fallible Get()/coercion upstream
     // failed on a terminating env, or a throwing getter left the exception
@@ -536,16 +537,24 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
   GITypeTag tag = gi_type_info_get_tag(type);
   switch (tag) {
     case GI_TYPE_TAG_BOOLEAN: out->v_boolean = NodeGiToBool(v); return true;
-    case GI_TYPE_TAG_INT8: out->v_int8 = static_cast<int8_t>(NodeGiToInt32(v)); return true;
-    case GI_TYPE_TAG_UINT8: out->v_uint8 = static_cast<uint8_t>(NodeGiToUint32(v)); return true;
-    case GI_TYPE_TAG_INT16: out->v_int16 = static_cast<int16_t>(NodeGiToInt32(v)); return true;
-    case GI_TYPE_TAG_UINT16: out->v_uint16 = static_cast<uint16_t>(NodeGiToUint32(v)); return true;
-    case GI_TYPE_TAG_INT32: out->v_int32 = NodeGiToInt32(v); return true;
-    case GI_TYPE_TAG_UINT32: out->v_uint32 = NodeGiToUint32(v); return true;
-    // 64-bit: accept a BigInt losslessly (else a Number, truncated) — never let a
-    // BigInt reach ToNumber() (fatal abort). See JsValueTo{Int,Uint}64 in common.h.
-    case GI_TYPE_TAG_INT64: out->v_int64 = JsValueToInt64(v); return true;
-    case GI_TYPE_TAG_UINT64: out->v_uint64 = JsValueToUint64(v); return true;
+    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: {
+      std::string shown;
+      switch (NodeGiJsToInteger(v, tag, out, &shown)) {
+        case NodeGiIntResult::kOk: return true;
+        case NodeGiIntResult::kPending: return false;
+        case NodeGiIntResult::kOutOfRange:
+          NodeGiThrowIntOutOfRange(env, tag, intContext, argName, shown);
+          return false;
+      }
+      return false;
+    }
     case GI_TYPE_TAG_FLOAT: out->v_float = static_cast<float>(NodeGiToDouble(v)); return true;
     case GI_TYPE_TAG_DOUBLE: out->v_double = NodeGiToDouble(v); return true;
     case GI_TYPE_TAG_UTF8:
@@ -1592,21 +1601,36 @@ Napi::Value ReadOutOrReturn(Napi::Env env, GICallableInfo* callable, GITypeInfo*
 // the element, so it gets a ref (objects) or an independent copy (boxed) instead.
 // Throws + returns false on an unsupported element.
 static bool ElementToGIArgument(Napi::Env env, GITypeInfo* elem, Napi::Value v, GIArgument* a,
-                                GITransfer elemTransfer) {
+                                GITransfer elemTransfer, bool wrapIntegers = false) {
   memset(a, 0, sizeof(*a));
   switch (gi_type_info_get_tag(elem)) {
     // Scalar coercions via the terminate-safe helpers (common.h): a swallowed
     // napi failure mid worker.terminate() must degrade to a zero, not cascade
     // into Error::New(nullptr)'s fatal sites.
     case GI_TYPE_TAG_BOOLEAN: a->v_boolean = NodeGiToBool(v); return true;
-    case GI_TYPE_TAG_INT8: a->v_int8 = static_cast<gint8>(NodeGiToInt32(v)); return true;
-    case GI_TYPE_TAG_UINT8: a->v_uint8 = static_cast<guint8>(NodeGiToUint32(v)); return true;
-    case GI_TYPE_TAG_INT16: a->v_int16 = static_cast<gint16>(NodeGiToInt32(v)); return true;
-    case GI_TYPE_TAG_UINT16: a->v_uint16 = static_cast<guint16>(NodeGiToUint32(v)); return true;
-    case GI_TYPE_TAG_INT32: a->v_int32 = NodeGiToInt32(v); return true;
-    case GI_TYPE_TAG_UINT32: a->v_uint32 = NodeGiToUint32(v); return true;
-    case GI_TYPE_TAG_INT64: a->v_int64 = JsValueToInt64(v); return true;
-    case GI_TYPE_TAG_UINT64: a->v_uint64 = JsValueToUint64(v); return true;
+    // Integers WRAP here, in an array (arg.cpp gjs_array_to_auto_array) — see
+    // NodeGiJsToIntegerWrap (common.h). A GList/GHashTable element keeps the older
+    // coercion: gjs's rule for those is not probed yet.
+    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:
+      if (wrapIntegers)
+        return NodeGiJsToIntegerWrap(v, gi_type_info_get_tag(elem), a) == NodeGiIntResult::kOk;
+      switch (gi_type_info_get_tag(elem)) {
+        case GI_TYPE_TAG_INT8: a->v_int8 = static_cast<gint8>(NodeGiToInt32(v)); return true;
+        case GI_TYPE_TAG_UINT8: a->v_uint8 = static_cast<guint8>(NodeGiToUint32(v)); return true;
+        case GI_TYPE_TAG_INT16: a->v_int16 = static_cast<gint16>(NodeGiToInt32(v)); return true;
+        case GI_TYPE_TAG_UINT16: a->v_uint16 = static_cast<guint16>(NodeGiToUint32(v)); return true;
+        case GI_TYPE_TAG_INT32: a->v_int32 = NodeGiToInt32(v); return true;
+        case GI_TYPE_TAG_UINT32: a->v_uint32 = NodeGiToUint32(v); return true;
+        case GI_TYPE_TAG_INT64: a->v_int64 = JsValueToInt64(v); return true;
+        default: a->v_uint64 = JsValueToUint64(v); return true;
+      }
     case GI_TYPE_TAG_FLOAT: a->v_float = static_cast<gfloat>(NodeGiToDouble(v)); return true;
     case GI_TYPE_TAG_DOUBLE: a->v_double = NodeGiToDouble(v); return true;
     case GI_TYPE_TAG_GTYPE: {
@@ -1814,7 +1838,10 @@ 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,
-                        argName);
+                        argName,
+                        argName != nullptr && strcmp(argName, "return value") == 0
+                            ? NodeGiIntContext::kReturnValue
+                            : NodeGiIntContext::kArgument);
 }
 
 }  // namespace
@@ -2273,7 +2300,8 @@ static bool JsToCArray(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransfe
       continue;
     }
     GIArgument a;
-    ok = ElementToGIArgument(env, elem, arr.Get(static_cast<uint32_t>(i)), &a, elemTransfer);
+    ok = ElementToGIArgument(env, elem, arr.Get(static_cast<uint32_t>(i)), &a, elemTransfer,
+                             /*wrapIntegers=*/true);
     if (!ok) break;
     // Copy the element's storage bytes (LE: the low elemSize bytes of the union
     // alias the active field — v_string/v_pointer for pointers, the scalar
@@ -2973,7 +3001,8 @@ Napi::Value SetBoxedField(const Napi::CallbackInfo& info) {
   GIArgument arg;
   memset(&arg, 0, sizeof(arg));
   std::string heldString;
-  if (JsToGIArgument(env, value, ftype, &arg, &heldString, GI_TRANSFER_NOTHING, nullptr)) {
+  if (JsToGIArgument(env, value, ftype, &arg, &heldString, GI_TRANSFER_NOTHING, nullptr,
+                     nullptr, nullptr, nullptr, name.c_str(), NodeGiIntContext::kField)) {
     if (!gi_field_info_set_field(field, bh->ptr, &arg)) {
       Napi::Error::New(env, std::string("Writing field ") + typeName + "." + name + " is not supported")
           .ThrowAsJavaScriptException();

package/src/object.cc

@@ -444,17 +444,53 @@ bool JsToGValue(Napi::Env env, Napi::Value js, GValue* v) {
     // napi failure mid worker.terminate() must degrade to a zero, not cascade
     // into Error::New(nullptr)'s fatal sites (the terminate-mid-`newObject` path).
     case G_TYPE_BOOLEAN: g_value_set_boolean(v, NodeGiToBool(js)); return true;
-    case G_TYPE_CHAR: g_value_set_schar(v, static_cast<gint8>(NodeGiToInt32(js))); return true;
-    case G_TYPE_UCHAR: g_value_set_uchar(v, static_cast<guchar>(NodeGiToUint32(js))); return true;
-    case G_TYPE_INT: g_value_set_int(v, NodeGiToInt32(js)); return true;
-    case G_TYPE_UINT: g_value_set_uint(v, NodeGiToUint32(js)); return true;
-    // 64-bit (glong/gulong are 64-bit on LP64): accept a BigInt losslessly, else a
-    // truncated Number — never let a BigInt reach ToNumber(). Shared with the GI
-    // scalar marshaller via JsValueTo{Int,Uint}64 (common.h).
+    // char/uchar/int64/uint64 refuse an out-of-range value and int/uint wrap, as gjs's
+    // gjs_value_to_g_value does (value.cpp:602-690) — the same rule the constructor
+    // properties and signal arguments reach. A BigInt on a 32-bit tag is ToNumber's
+    // TypeError, left pending.
+    case G_TYPE_CHAR:
+    case G_TYPE_UCHAR:
+    case G_TYPE_INT64:
+    case G_TYPE_UINT64: {
+      GITypeTag tag = ft == G_TYPE_CHAR    ? GI_TYPE_TAG_INT8
+                      : ft == G_TYPE_UCHAR ? GI_TYPE_TAG_UINT8
+                      : ft == G_TYPE_INT64 ? GI_TYPE_TAG_INT64
+                                           : GI_TYPE_TAG_UINT64;
+      GIArgument a;
+      memset(&a, 0, sizeof(a));
+      switch (NodeGiJsToInteger(js, tag, &a, nullptr)) {
+        case NodeGiIntResult::kPending: return false;
+        case NodeGiIntResult::kOutOfRange:
+          NodeGiThrowGValueOutOfRange(env, js,
+                                      ft == G_TYPE_CHAR    ? "char"
+                                      : ft == G_TYPE_UCHAR ? "unsigned char"
+                                      : ft == G_TYPE_INT64 ? "64-bit integer"
+                                                           : "unsigned 64-bit integer");
+          return false;
+        case NodeGiIntResult::kOk: break;
+      }
+      if (ft == G_TYPE_CHAR) g_value_set_schar(v, a.v_int8);
+      else if (ft == G_TYPE_UCHAR) g_value_set_uchar(v, a.v_uint8);
+      else if (ft == G_TYPE_INT64) g_value_set_int64(v, a.v_int64);
+      else g_value_set_uint64(v, a.v_uint64);
+      return true;
+    }
+    case G_TYPE_INT:
+    case G_TYPE_UINT: {
+      GIArgument a;
+      memset(&a, 0, sizeof(a));
+      if (NodeGiJsToIntegerWrap(js, ft == G_TYPE_INT ? GI_TYPE_TAG_INT32 : GI_TYPE_TAG_UINT32,
+                                &a) == NodeGiIntResult::kPending)
+        return false;
+      if (ft == G_TYPE_INT) g_value_set_int(v, a.v_int32);
+      else g_value_set_uint(v, a.v_uint32);
+      return true;
+    }
+    // glong/gulong are 64-bit on LP64: accept a BigInt losslessly, else a truncated
+    // Number — never let a BigInt reach ToNumber(). Shared with the GI scalar marshaller
+    // via JsValueTo{Int,Uint}64 (common.h). gjs has no G_TYPE_LONG case here at all.
     case G_TYPE_LONG: g_value_set_long(v, static_cast<glong>(JsValueToInt64(js))); return true;
     case G_TYPE_ULONG: g_value_set_ulong(v, static_cast<gulong>(JsValueToUint64(js))); return true;
-    case G_TYPE_INT64: g_value_set_int64(v, JsValueToInt64(js)); return true;
-    case G_TYPE_UINT64: g_value_set_uint64(v, JsValueToUint64(js)); return true;
     case G_TYPE_FLOAT: g_value_set_float(v, static_cast<float>(NodeGiToDouble(js))); return true;
     case G_TYPE_DOUBLE: g_value_set_double(v, NodeGiToDouble(js)); return true;
     case G_TYPE_ENUM: g_value_set_enum(v, NodeGiToInt32(js)); return true;
@@ -611,7 +647,16 @@ Napi::Value ConstructGObject(Napi::Env env, GType gtype, Napi::Object props,
     }
     g_value_init(&values[i], pspec->value_type);
     initialised = i + 1;
-    if (!JsToGValue(env, props.Get(nameStorage[i]), &values[i])) {
+    Napi::Value propValue = props.Get(nameStorage[i]);
+    if (!propValue.IsEmpty() && propValue.IsUndefined()) {
+      // gjs refuses `undefined` for every property type (object.cpp:2090).
+      Napi::Error::New(env, "Invalid value 'undefined' for property " + std::string(pspec->name) +
+                                " in object initializer.")
+          .ThrowAsJavaScriptException();
+      ok = false;
+      break;
+    }
+    if (!JsToGValue(env, propValue, &values[i])) {
       ok = false;
       break;
     }
@@ -734,6 +779,30 @@ Napi::Value SetProperty(const Napi::CallbackInfo& info) {
     Napi::TypeError::New(env, "no such property '" + name + "'").ThrowAsJavaScriptException();
     return env.Undefined();
   }
+  // gjs refuses an out-of-range value for these property types on assignment
+  // (object.cpp, with its own text); JsToGValue below now refuses them too, with the
+  // gjs_value_to_g_value text.
+  GITypeTag intTag = GI_TYPE_TAG_VOID;
+  switch (G_TYPE_FUNDAMENTAL(pspec->value_type)) {
+    case G_TYPE_CHAR: intTag = GI_TYPE_TAG_INT8; break;
+    case G_TYPE_UCHAR: intTag = GI_TYPE_TAG_UINT8; break;
+    case G_TYPE_UINT: intTag = GI_TYPE_TAG_UINT32; break;
+    case G_TYPE_INT64: intTag = GI_TYPE_TAG_INT64; break;
+    case G_TYPE_UINT64: intTag = GI_TYPE_TAG_UINT64; break;
+    default: break;
+  }
+  if (intTag != GI_TYPE_TAG_VOID) {
+    GIArgument probe;
+    std::string shown;
+    NodeGiIntResult r = NodeGiJsToInteger(info[2], intTag, &probe, &shown);
+    if (r == NodeGiIntResult::kPending) return env.Undefined();
+    if (r == NodeGiIntResult::kOutOfRange) {
+      Napi::Error::New(env, "value " + shown + " is out of range for " + pspec->name +
+                                " (type " + NodeGiIntTagName(intTag) + ")")
+          .ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+  }
   GValue v = G_VALUE_INIT;
   g_value_init(&v, pspec->value_type);
   if (JsToGValue(env, info[2], &v)) {

package/src/private.cc

@@ -25,6 +25,10 @@
 
 #include "common.h"
 
+#ifdef _WIN32
+#include <windows.h>
+#endif
+
 namespace nodegi {
 
 // ---- GLib.log_set_writer_func ----------------------------------------------
@@ -557,10 +561,39 @@ Napi::Value Bindtextdomain(const Napi::CallbackInfo& info) {
     }
     location = info[1].As<Napi::String>().Utf8Value();
   }
+#ifdef _WIN32
+  // bindtextdomain() reads its path in the ANSI code page, so a UTF-8 JS string with
+  // a non-ASCII directory (".../Steuererklärung/share/locale") binds a path that
+  // does not exist and every lookup silently answers the msgid (measured in a Windows
+  // 11 VM: the same catalog under an ASCII path translated). GNU gettext >= 0.21
+  // ships wbindtextdomain() for exactly this; both directions go through UTF-16.
+  std::wstring wlocation;
+  if (!query) {
+    int n = MultiByteToWideChar(CP_UTF8, 0, location.c_str(), -1, nullptr, 0);
+    if (n <= 0) {
+      Napi::TypeError::New(env, "bindtextdomain: location is not valid UTF-8")
+          .ThrowAsJavaScriptException();
+      return env.Null();
+    }
+    wlocation.resize(n);
+    MultiByteToWideChar(CP_UTF8, 0, location.c_str(), -1, wlocation.data(), n);
+    wlocation.resize(n - 1);
+  }
+  const wchar_t* wresult = wbindtextdomain(domain.c_str(), query ? nullptr : wlocation.c_str());
+  if (!query) bind_textdomain_codeset(domain.c_str(), "UTF-8");
+  if (wresult == nullptr) return env.Null();
+  int len = WideCharToMultiByte(CP_UTF8, 0, wresult, -1, nullptr, 0, nullptr, nullptr);
+  if (len <= 0) return env.Null();
+  std::string utf8(len, '\0');
+  WideCharToMultiByte(CP_UTF8, 0, wresult, -1, utf8.data(), len, nullptr, nullptr);
+  utf8.resize(len - 1);
+  return Napi::String::New(env, utf8);
+#else
   const char* result = bindtextdomain(domain.c_str(), query ? nullptr : location.c_str());
   if (!query) bind_textdomain_codeset(domain.c_str(), "UTF-8");
   if (result == nullptr) return env.Null();
   return Napi::String::New(env, result);
+#endif
 }
 
 // localeCategories() -> { ALL, COLLATE, CTYPE, MESSAGES, MONETARY, NUMERIC, TIME }