@gjsify/node-gi 0.64.1 → 0.64.2

package/cairo.d.ts

@@ -36,6 +36,16 @@ export interface FontExtents {
     maxYAdvance: number;
 }
 
+/** `cairo_matrix_t` as the plain object GJS passes around (no matrix wrapper). */
+export interface Matrix {
+    xx: number;
+    yx: number;
+    xy: number;
+    yy: number;
+    x0: number;
+    y0: number;
+}
+
 /** cairo drawing context (`cairo_t`). */
 export class Context {
     constructor(surface: Surface);
@@ -53,10 +63,17 @@ export class Context {
     textPath(utf8: string): void;
     textExtents(utf8: string): TextExtents;
     fontExtents(): FontExtents;
+    /**
+     * The current font matrix. GJS has no cairo matrix wrapper
+     * (`getMatrix`/`setMatrix` stay unbound), so it travels as a plain object.
+     */
+    getFontMatrix(): Matrix;
+    setFontMatrix(matrix: Matrix): void;
     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;
     curveTo(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number): void;
+    relCurveTo(dx1: number, dy1: number, dx2: number, dy2: number, dx3: number, dy3: number): void;
     fill(): void;
     fillPreserve(): void;
     stroke(): void;
@@ -65,6 +82,19 @@ export class Context {
     paintWithAlpha(alpha: number): void;
     clip(): void;
     clipPreserve(): void;
+    resetClip(): void;
+    /** Redirect drawing to an intermediate group surface. */
+    pushGroup(): void;
+    /** Like {@link pushGroup} but with an explicit {@link Content} for the group surface. */
+    pushGroupWithContent(content: number): void;
+    /** End the current group and return it as a pattern (concrete subclass). */
+    popGroup(): Pattern;
+    /** End the current group and install it as this context's source. */
+    popGroupToSource(): void;
+    /** Paint the current source through `pattern`'s alpha. */
+    mask(pattern: Pattern): void;
+    /** Paint the current source through `surface`'s alpha, offset to `(x, y)`. */
+    maskSurface(surface: Surface, x: number, y: number): void;
     translate(tx: number, ty: number): void;
     scale(sx: number, sy: number): void;
     rotate(angle: number): void;
@@ -74,6 +104,10 @@ export class Context {
     setSourceSurface(surface: Surface, x: number, y: number): void;
     /** The context's current source pattern (own reference; concrete subclass). */
     getSource(): Pattern;
+    /** The surface this context draws to (own reference; concrete subclass). */
+    getTarget(): Surface;
+    /** The target of the current group, or {@link getTarget} outside a group. */
+    getGroupTarget(): Surface;
     identityMatrix(): void;
     newSubPath(): void;
     /** User → device coordinates as `[x, y]` (GJS return shape). */
@@ -111,6 +145,10 @@ export class Context {
     setOperator(op: number): void;
     setMiterLimit(limit: number): void;
     setTolerance(tolerance: number): void;
+    /** Emit the current page and clear it (paginated surfaces; a no-op elsewhere). */
+    copyPage(): void;
+    /** Like {@link copyPage} but also clears the current page's contents. */
+    showPage(): void;
     status(): number;
     $dispose(): void;
 }

package/cairo.js

@@ -23,16 +23,25 @@
 // (the `Object.assign({}, imports._cairo, cairoNative)` merge shape).
 // Copyright (c) 2010 litl, LLC / GJS contributors. MIT OR LGPL-2.0-or-later.
 
-import native from './index.js';
+import native, { ensureNative, onNativeLoaded } from './index.js';
 
-const c = native.__cairo;
-if (c === undefined) {
-    throw new Error(
+// Bound when the addon loads: at import on desktop, on first use on a lazy host (NativeScript).
+// Every call that can run before any cairo object exists goes through `engine()`.
+let c;
+
+function missingBinding() {
+    return new Error(
         '@gjsify/node-gi/cairo: the native cairo binding is missing from the addon. ' +
             'Rebuild @gjsify/node-gi (node-gyp rebuild) — the addon must link libcairo.',
     );
 }
 
+function engine() {
+    ensureNative();
+    if (c === undefined) throw missingBinding();
+    return c;
+}
+
 // ---- enums (ported verbatim from refs/gjs/modules/core/_cairo.js) -----------
 
 export const Antialias = { DEFAULT: 0, NONE: 1, GRAY: 2, SUBPIXEL: 3 };
@@ -141,7 +150,7 @@ function handleOf(x, what) {
 /** cairo drawing context. `new cairo.Context(surface)` wraps `cairo_create`. */
 export class Context {
     constructor(surface) {
-        setHandle(this, c.contextCreate(handleOf(surface, 'cairo.Surface')));
+        setHandle(this, engine().contextCreate(handleOf(surface, 'cairo.Surface')));
     }
 
     save() {
@@ -181,6 +190,9 @@ export class Context {
     curveTo(x1, y1, x2, y2, x3, y3) {
         c.curveTo(this[H], x1, y1, x2, y2, x3, y3);
     }
+    relCurveTo(dx1, dy1, dx2, dy2, dx3, dy3) {
+        c.relCurveTo(this[H], dx1, dy1, dx2, dy2, dx3, dy3);
+    }
 
     fill() {
         c.fill(this[H]);
@@ -206,6 +218,33 @@ export class Context {
     clipPreserve() {
         c.clipPreserve(this[H]);
     }
+    resetClip() {
+        c.resetClip(this[H]);
+    }
+    /** Redirect drawing to an intermediate group surface. */
+    pushGroup() {
+        c.pushGroup(this[H]);
+    }
+    /** Like {@link pushGroup} but with an explicit {@link Content} for the group surface. */
+    pushGroupWithContent(content) {
+        c.pushGroupWithContent(this[H], content);
+    }
+    /** End the current group and return it as a pattern (concrete subclass). */
+    popGroup() {
+        return wrapPatternHandle(c.popGroup(this[H]));
+    }
+    /** End the current group and install it as this context's source. */
+    popGroupToSource() {
+        c.popGroupToSource(this[H]);
+    }
+    /** Paint the current source through `pattern`'s alpha. */
+    mask(pattern) {
+        c.mask(this[H], handleOf(pattern, 'cairo.Pattern'));
+    }
+    /** Paint the current source through `surface`'s alpha, offset to `(x, y)`. */
+    maskSurface(surface, x, y) {
+        c.maskSurface(this[H], handleOf(surface, 'cairo.Surface'), x, y);
+    }
 
     translate(tx, ty) {
         c.translate(this[H], tx, ty);
@@ -289,6 +328,14 @@ export class Context {
     getSource() {
         return wrapPatternHandle(c.getSource(this[H]));
     }
+    /** The surface this context draws to (a ref of its own — safe to keep). */
+    getTarget() {
+        return wrapSurfaceHandle(c.getTarget(this[H]));
+    }
+    /** The target of the current group, or {@link getTarget} outside a group. */
+    getGroupTarget() {
+        return wrapSurfaceHandle(c.getGroupTarget(this[H]));
+    }
 
     setLineWidth(width) {
         c.setLineWidth(this[H], width);
@@ -355,6 +402,18 @@ export class Context {
     fontExtents() {
         return c.fontExtents(this[H]);
     }
+    /**
+     * The current font matrix as `{ xx, yx, xy, yy, x0, y0}`. GJS has no cairo
+     * matrix wrapper (`getMatrix`/`setMatrix` stay unbound), so it travels as
+     * a plain object of the six doubles.
+     */
+    getFontMatrix() {
+        return c.getFontMatrix(this[H]);
+    }
+    /** Set the font matrix from `{ xx, yx, xy, yy, x0, y0}`. */
+    setFontMatrix(matrix) {
+        c.setFontMatrix(this[H], matrix);
+    }
     /** Stroke bounding box as `[x1, y1, x2, y2]`. */
     strokeExtents() {
         return c.strokeExtents(this[H]);
@@ -385,6 +444,15 @@ export class Context {
         c.setTolerance(this[H], tolerance);
     }
 
+    /** Emit the current page and clear it (paginated surfaces; a no-op elsewhere). */
+    copyPage() {
+        c.copyPage(this[H]);
+    }
+    /** Like {@link copyPage} but also clears the current page's contents. */
+    showPage() {
+        c.showPage(this[H]);
+    }
+
     status() {
         return c.status(this[H]);
     }
@@ -422,14 +490,14 @@ export class Surface {
 export class ImageSurface extends Surface {
     constructor(format, width, height) {
         super();
-        setHandle(this, c.imageSurfaceCreate(format, width, height));
+        setHandle(this, engine().imageSurfaceCreate(format, width, height));
     }
 
     static create(format, width, height) {
         return new ImageSurface(format, width, height);
     }
     static createFromPNG(filename) {
-        return wrapRaw(ImageSurface, c.imageSurfaceCreateFromPNG(filename));
+        return wrapRaw(ImageSurface, engine().imageSurfaceCreateFromPNG(filename));
     }
 
     getWidth() {
@@ -471,10 +539,10 @@ export class Pattern {
 /** A solid-color pattern (`cairo_pattern_create_rgb[a]`). */
 export class SolidPattern extends Pattern {
     static createRGB(red, green, blue) {
-        return wrapRaw(SolidPattern, c.solidPatternCreateRGB(red, green, blue));
+        return wrapRaw(SolidPattern, engine().solidPatternCreateRGB(red, green, blue));
     }
     static createRGBA(red, green, blue, alpha) {
-        return wrapRaw(SolidPattern, c.solidPatternCreateRGBA(red, green, blue, alpha));
+        return wrapRaw(SolidPattern, engine().solidPatternCreateRGBA(red, green, blue, alpha));
     }
 }
 
@@ -492,7 +560,7 @@ export class Gradient extends Pattern {
 export class LinearGradient extends Gradient {
     constructor(x0, y0, x1, y1) {
         super();
-        setHandle(this, c.linearGradientCreate(x0, y0, x1, y1));
+        setHandle(this, engine().linearGradientCreate(x0, y0, x1, y1));
     }
 }
 
@@ -500,7 +568,7 @@ export class LinearGradient extends Gradient {
 export class RadialGradient extends Gradient {
     constructor(cx0, cy0, radius0, cx1, cy1, radius1) {
         super();
-        setHandle(this, c.radialGradientCreate(cx0, cy0, radius0, cx1, cy1, radius1));
+        setHandle(this, engine().radialGradientCreate(cx0, cy0, radius0, cx1, cy1, radius1));
     }
 }
 
@@ -508,7 +576,7 @@ export class RadialGradient extends Gradient {
 export class SurfacePattern extends Pattern {
     constructor(surface) {
         super();
-        setHandle(this, c.surfacePatternCreate(handleOf(surface, 'cairo.Surface')));
+        setHandle(this, engine().surfacePatternCreate(handleOf(surface, 'cairo.Surface')));
     }
 
     setExtend(extend) {
@@ -532,6 +600,12 @@ export class SurfacePattern extends Pattern {
  */
 export class Path {}
 
+// Fan a surface handle out to the concrete subclass by cairo runtime type —
+// mirrors CairoSurface::from_c_ptr (only the image surface has a subclass here).
+function wrapSurfaceHandle(handle) {
+    return wrapRaw(c.surfaceGetType(handle) === SurfaceType.IMAGE ? ImageSurface : Surface, handle);
+}
+
 // Fan a pattern handle out to the concrete subclass by cairo runtime type —
 // mirrors gjs_cairo_pattern_from_pattern (MESH/RASTER_SOURCE fall back to the
 // base Pattern; gjs throws for those, but they are unreachable from this module).
@@ -554,11 +628,15 @@ function wrapPatternHandle(handle) {
 // a returned/callback cairo pointer into the right JS instance. Surface + Pattern
 // fan out to the concrete subclass by cairo runtime type (mirrors
 // CairoSurface::from_c_ptr / gjs_cairo_pattern_from_pattern).
-c.setup({
-    context: (handle) => wrapRaw(Context, handle),
-    surface: (handle) => wrapRaw(c.surfaceGetType(handle) === SurfaceType.IMAGE ? ImageSurface : Surface, handle),
-    pattern: (handle) => wrapPatternHandle(handle),
-    path: (handle) => wrapRaw(Path, handle),
+onNativeLoaded(() => {
+    if (native.__cairo === undefined) throw missingBinding();
+    c = native.__cairo;
+    c.setup({
+        context: (handle) => wrapRaw(Context, handle),
+        surface: (handle) => wrapSurfaceHandle(handle),
+        pattern: (handle) => wrapPatternHandle(handle),
+        path: (handle) => wrapRaw(Path, handle),
+    });
 });
 
 // The default export mirrors GJS's ESM `cairo` object (enums + constructors), the

package/gettext.js

@@ -23,6 +23,7 @@
 // default export. The gjsify `--app node` build aliases the bare `gettext`
 // specifier to this module (kept external — `ALIASES_GJS_FOR_NODE`).
 import * as native from './index.js';
+import { ensureNative } from './index.js';
 import { requireGi } from './gi.js';
 
 // GLib is resolved on first lookup, not at import: loading a namespace walks the
@@ -48,7 +49,10 @@ function GLib() {
 // lookups still work (they go through GLib, which every addon version has), and
 // the binders are the no-ops they used to be. It is announced once, because a
 // silently untranslated UI is the defect this file exists to close.
-const haveLocaleBinders = typeof native.localeCategories === 'function';
+function haveLocaleBinders() {
+    ensureNative();
+    return typeof native.localeCategories === 'function';
+}
 
 let announcedStaleAddon = false;
 function noLocaleBinders(fn) {
@@ -78,6 +82,18 @@ const FALLBACK_CATEGORIES = {
     win32: { ALL: 0, COLLATE: 1, CTYPE: 2, MONETARY: 3, NUMERIC: 4, TIME: 5, MESSAGES: 1729 },
 };
 
+// Resolved on first read, not at import, so a lazy host (NativeScript) that only imports this
+// module has not loaded the addon yet; a failed load throws here, there is no fallback table.
+let categories = null;
+function localeCategories() {
+    if (categories === null) {
+        categories = haveLocaleBinders()
+            ? native.localeCategories()
+            : (FALLBACK_CATEGORIES[globalThis.process?.platform] ?? FALLBACK_CATEGORIES.linux);
+    }
+    return categories;
+}
+
 /** Look up `msgid` in the default domain (the one `textdomain()` last named). */
 export function gettext(msgid) {
     return GLib().dgettext(null, msgid);
@@ -145,13 +161,13 @@ export function domain(domainName) {
  * @returns {string|null} the prior locale name, or null if it could not be set
  */
 export function setlocale(category, locale) {
-    if (!haveLocaleBinders) return noLocaleBinders('setlocale');
+    if (!haveLocaleBinders()) return noLocaleBinders('setlocale');
     return native.setThreadLocale(category, locale ?? null);
 }
 
 /** Set the default text domain, or report it when `domainName` is null. */
 export function textdomain(domainName) {
-    if (!haveLocaleBinders) return noLocaleBinders('textdomain');
+    if (!haveLocaleBinders()) return noLocaleBinders('textdomain');
     return native.textdomain(domainName ?? null);
 }
 
@@ -162,7 +178,7 @@ export function textdomain(domainName) {
  * `gjs_bindtextdomain` does — see the note in private.cc.
  */
 export function bindtextdomain(domainName, dirName) {
-    if (!haveLocaleBinders) return noLocaleBinders('bindtextdomain');
+    if (!haveLocaleBinders()) return noLocaleBinders('bindtextdomain');
     return native.bindtextdomain(domainName, dirName ?? null);
 }
 
@@ -188,9 +204,15 @@ export function bindtextdomainCodeset(_domainName, _codeset) {
  * claiming to address LC_MESSAGES — on two of the three platforms the translation
  * blocker was reported from.
  */
-export const LocaleCategory = haveLocaleBinders
-    ? native.localeCategories()
-    : (FALLBACK_CATEGORIES[globalThis.process?.platform] ?? FALLBACK_CATEGORIES.linux);
+export const LocaleCategory = Object.defineProperties(
+    {},
+    Object.fromEntries(
+        Object.keys(FALLBACK_CATEGORIES.linux).map((name) => [
+            name,
+            { enumerable: true, get: () => localeCategories()[name] },
+        ]),
+    ),
+);
 
 /**
  * The GJS `Gettext` module as a default export — the object shape

package/gi.js

@@ -7,6 +7,7 @@
 // Reference: gjs/modules/esm/gi.js for the require shape; node-gtk (romgrk, MIT) for the
 // binding lineage. Hand-authored JS — the package ships no build step.
 import * as native from './index.js';
+import { ensureNative, onNativeLoaded } from './index.js';
 // Timers, `process` and the windowing env record come from the host seam (host.node.js
 // explains why they are the runtime's own, not the globals; host.nativescript.js is the
 // NativeScript Android variant).
@@ -360,17 +361,19 @@ function makeErrorDomainClass(namespace, typeName, members, quark) {
 // 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);
-});
+onNativeLoaded(() =>
+    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
@@ -443,7 +446,7 @@ function resolveTemplateCallback(handle, handlerName) {
         return desc.value.apply(proxy, args.map(wrapReturn));
     };
 }
-native.setTemplateCallbackResolver(resolveTemplateCallback);
+onNativeLoaded(() => native.setTemplateCallbackResolver(resolveTemplateCallback));
 
 // Run a registered class's JS constructor for a GObject the ENGINE instantiated from C
 // — typically a GtkBuilder composite-template InternalChild, which has no JS-`new` to
@@ -466,7 +469,7 @@ function runCtorForCObject(handle, gtypeName) {
         adoptHandle = prev;
     }
 }
-native.setConstructCallback(runCtorForCObject);
+onNativeLoaded(() => native.setConstructCallback(runCtorForCObject));
 
 // A non-GObject GObject-fundamental (GskRenderNode, GdkEvent) as an OPAQUE,
 // round-trippable handle: the native tagged External already carries the pointer and
@@ -927,13 +930,50 @@ function decorateGioNamespace(baseNs) {
     });
 }
 
+// The internals of the PROXY links on an introspected prototype chain: the Proxy
+// itself -> its target plus the materializer its getOwnPropertyDescriptor trap runs
+// (`null` for a Proxy that traps no descriptor read). Registered by
+// makeClassPrototype and vfuncChainProto; read only by findProtoDescriptor.
+//
+// Why: a descriptor read THROUGH a Proxy costs ~110 ns of V8 invariant machinery on
+// top of the handler, and an introspected chain is mostly Proxies. Measured on the
+// bench's depth-3 subject, a full MISS walk took 328 ns — 154 ns on the
+// makeClassPrototype link, 65 ns on vfuncChainProto, 12 ns on the one plain link.
+// With the target in hand the same answer costs 27 ns, because the trap body is
+// exactly `materialize(prop); return Reflect.getOwnPropertyDescriptor(target, prop)`
+// and running it directly skips only the machinery, never a step of the computation.
+//
+// This is NOT a cache of the ANSWER: nothing is remembered between calls. The target
+// is the object every mutation of the prototype lands on — none of the handlers trap
+// `set`, `defineProperty`, `deleteProperty` or `setPrototypeOf`, so
+// `Cls.prototype.m = f`, `Object.defineProperty(…)`, `delete` and a spliced chain
+// write through to it — and the descriptor still comes from a fresh read of it. That
+// has to hold, because GJS pins nothing: on gjs 1.88.1 every one of those mutations
+// is observable on an already-wrapped instance (measured), so an answer cache would
+// need an invalidation signal JS does not offer. test/proto-descriptor-liveness.test.mjs
+// is the proof obligation.
+const protoInternals = new WeakMap();
+
 // Walk a JS prototype chain (excluding Object.prototype) for an own property
 // descriptor of `prop` — used to surface a registerClass subclass's own methods
-// /getters/setters on the GObject wrapper.
+// /getters/setters on the GObject wrapper. One full walk runs per property GET, per
+// SET and per `emit`, so the Proxy bypass above is on the hottest path there is.
 function findProtoDescriptor(proto, prop) {
-    for (let p = proto; p !== null && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
-        const d = Object.getOwnPropertyDescriptor(p, prop);
+    for (let p = proto; p !== null && p !== Object.prototype;) {
+        const internals = protoInternals.get(p);
+        if (internals === undefined) {
+            const d = Object.getOwnPropertyDescriptor(p, prop);
+            if (d !== undefined) return d;
+            p = Object.getPrototypeOf(p);
+            continue;
+        }
+        const { target, materialize } = internals;
+        if (materialize !== null) materialize(prop);
+        const d = Object.getOwnPropertyDescriptor(target, prop);
         if (d !== undefined) return d;
+        // The target's prototype, not the Proxy's: neither handler traps
+        // getPrototypeOf, so these are the same link — one fewer trap to pay.
+        p = Object.getPrototypeOf(target);
     }
     return undefined;
 }
@@ -1131,9 +1171,9 @@ function runJsPropertySetter(handle, propertyName) {
 // function` until the next release republishes the binary. Every native call added
 // here degrades instead; without the callback, a post-construction set simply does
 // not reach the JS setter, which is what 0.50.0 did.
-if (typeof native.setPropertySetCallback === 'function') {
-    native.setPropertySetCallback(runJsPropertySetter);
-}
+onNativeLoaded(() => {
+    if (typeof native.setPropertySetCallback === 'function') native.setPropertySetCallback(runJsPropertySetter);
+});
 
 // Which properties the construct-time replay must run.
 //
@@ -1342,6 +1382,7 @@ export function startMainContextPump() {
     // GLib's default main context — a JS-timer pump would only iterate the
     // context recursively from within its own dispatch.
     if (hostPumpsItself()) return () => {};
+    ensureNative();
     pumpRefCount++;
     if (pumpTimer === null) {
         if (pendingView === null) pendingView = native.makePumpPendingCount();
@@ -1812,7 +1853,8 @@ function wrapInstance(handle, userProto) {
 // the introspected parent's `vfunc_x` is a thunk into the actual C vtable entry.
 // Non-`vfunc_` lookups fall through to Object.prototype (so the base prototype
 // keeps its normal object behaviour).
-const vfuncChainProto = new Proxy(Object.create(Object.prototype), {
+const vfuncChainTarget = Object.create(Object.prototype);
+const vfuncChainProto = new Proxy(vfuncChainTarget, {
     get(target, prop, receiver) {
         if (typeof prop === 'string' && prop.startsWith('vfunc_')) {
             const vfuncName = prop.slice('vfunc_'.length);
@@ -1827,6 +1869,10 @@ const vfuncChainProto = new Proxy(Object.create(Object.prototype), {
         return Reflect.get(target, prop, receiver);
     },
 });
+// No descriptor trap here: a `vfunc_*` access is synthesized by `get` alone and was
+// never reported as a descriptor, so the walk's answer for this link always came from
+// the target. `null` materializer = "read the target, that is the whole trap".
+protoInternals.set(vfuncChainProto, { target: vfuncChainTarget, materialize: null });
 
 // Surface a lazy `$gtype` getter on an introspected class/struct ctor: the real
 // GObject GType (a node-gi GType handle), resolved on first read via the engine
@@ -1994,7 +2040,7 @@ function makeClassPrototype(namespace, typeName) {
         }
         return arity >= 0 && define(prop, makeGiMethod(where, prop, arity));
     };
-    return new Proxy(target, {
+    const proto = new Proxy(target, {
         get(t, prop, receiver) {
             materialize(prop);
             return Reflect.get(t, prop, receiver);
@@ -2007,6 +2053,10 @@ function makeClassPrototype(namespace, typeName) {
             return materialize(prop) || Reflect.has(t, prop);
         },
     });
+    // Let findProtoDescriptor run the descriptor trap's body directly on the target —
+    // same two steps, without V8's per-trap invariant checks (see protoInternals).
+    protoInternals.set(proto, { target, materialize });
+    return proto;
 }
 
 function makeClass(namespace, typeName) {
@@ -2526,6 +2576,8 @@ function paramSpecGTyped(type) {
 const ParamSpec = Object.freeze({
     string: paramSpecPlain('string'),
     boolean: paramSpecPlain('boolean'),
+    char: paramSpecRanged('char'),
+    uchar: paramSpecRanged('uchar'),
     int: paramSpecRanged('int'),
     uint: paramSpecRanged('uint'),
     int64: paramSpecRanged('int64'),
@@ -3190,6 +3242,7 @@ function mirrorWindowingEnvIntoCrt() {
  * @returns {Record<string, unknown>}
  */
 export function requireGi(namespace, version) {
+    ensureNative();
     native.requireNamespace(namespace, version);
     // The one moment the win32 CRT-environment mirror can run: the addon is loaded, so there
     // is a GLib to call, and nothing has built a font map or loaded a fontconfig

package/host.nativescript.js

@@ -44,6 +44,12 @@
 /** @type {'nativescript'} */
 export const RUNTIME = 'nativescript';
 
+/**
+ * Whether the addon may be loaded on first use instead of at import — see index.js.
+ * @type {boolean}
+ */
+export const LAZY_NATIVE = true;
+
 // Timers from the global scope: NativeScript has no node:timers, and there is no
 // GLib-backed replacement to avoid here. setImmediate is not a V8 builtin.
 export const setImmediate =

package/host.node.js

@@ -55,6 +55,12 @@ export const RUNTIME =
             ? 'deno'
             : 'node';
 
+/**
+ * Whether the addon may be loaded on first use instead of at import — see index.js.
+ * @type {boolean}
+ */
+export const LAZY_NATIVE = false;
+
 // GJS host mode: `GjsifyNapi.init()` installs the loader as
 // `globalThis.__gjsifyNapiLoadAddon` and re-installs it if another consumer (the
 // @gjsify/napi L1) already captured + deleted it. Needs the GjsifyNapi typelib

package/index.js

@@ -5,7 +5,7 @@
 // a native package's JS entry is a loader, not a tsc artifact, and the repo
 // ignores `lib/`. The addon is Node-API (ABI-stable), so the same binary loads on
 // Node, Bun and Deno; runtime-specific behaviour is gated off RUNTIME below.
-import { RUNTIME, loadNativeHost } from '#host';
+import { RUNTIME, loadNativeHost, LAZY_NATIVE } from '#host';
 
 /**
  * Which JS runtime we are on. Detection — and why each runtime gets the main-loop
@@ -17,121 +17,237 @@ export { RUNTIME };
 /** Whether we are on Node.js (the only runtime with the libuv main-loop bridge). */
 export const isNodeRuntime = RUNTIME === 'node';
 
-const native = loadNativeHost();
+/**
+ * The native engine. Desktop runtimes load it HERE, while this module evaluates, exactly as
+ * before. A host that sets `LAZY_NATIVE` (NativeScript: dlopen of `libnode_gi.so` plus its
+ * closure costs real cold-start time) defers the load to the first `ensureNative()`, so an app
+ * that imports this package but never asks for GObject pays nothing. A failed load throws from
+ * `ensureNative()` every time it is asked — a selected real engine still fails loudly, there
+ * is no fallback here (ADR 0105 § 4).
+ * @type {Record<string, any>}
+ */
+let native;
+let loaded = false;
+/** @type {Array<() => void>} */
+const loadHooks = [];
+
+/**
+ * Load the addon if that has not happened yet, and return it. The L1 layers call this before
+ * they touch any binding below.
+ * @returns {Record<string, any>}
+ */
+export function ensureNative() {
+    if (loaded) return native;
+    const addon = loadNativeHost();
+    native = addon;
+    requireNamespace = addon.requireNamespace;
+    listInfoNames = addon.listInfoNames;
+    findInfo = addon.findInfo;
+    getConstantValue = addon.getConstantValue;
+    getEnumValues = addon.getEnumValues;
+    getErrorDomain = addon.getErrorDomain;
+    errorDomainInfo = addon.errorDomainInfo;
+    setErrorBuilder = addon.setErrorBuilder;
+    prependSearchPath = addon.prependSearchPath;
+    prependLibraryPath = addon.prependLibraryPath;
+    callFunction = addon.callFunction;
+    callMethod = addon.callMethod;
+    hasMethod = addon.hasMethod;
+    hasClassMethod = addon.hasClassMethod;
+    classMethodArity = addon.classMethodArity;
+    callStaticMethod = addon.callStaticMethod;
+    constructStruct = addon.constructStruct;
+    newObject = addon.newObject;
+    registerClass = addon.registerClass;
+    registerClassFromGType = addon.registerClassFromGType;
+    constructType = addon.constructType;
+    callParentVfunc = addon.callParentVfunc;
+    hasClassVfunc = addon.hasClassVfunc;
+    callClassVfunc = addon.callClassVfunc;
+    getTemplateChild = addon.getTemplateChild;
+    getProperty = addon.getProperty;
+    setProperty = addon.setProperty;
+    hasProperty = addon.hasProperty;
+    getTypeName = addon.getTypeName;
+    classInfoForTypeName = addon.classInfoForTypeName;
+    getGType = addon.getGType;
+    isInstanceOf = addon.isInstanceOf;
+    isGObjectHandle = addon.isGObjectHandle;
+    newGValue = addon.newGValue;
+    callBoxedMethod = addon.callBoxedMethod;
+    isBoxedHandle = addon.isBoxedHandle;
+    boxedMemberKind = addon.boxedMemberKind;
+    getBoxedField = addon.getBoxedField;
+    setBoxedField = addon.setBoxedField;
+    boxedTypeName = addon.boxedTypeName;
+    __boxedAddress = addon.__boxedAddress;
+    isParamSpecHandle = addon.isParamSpecHandle;
+    isFundamentalHandle = addon.isFundamentalHandle;
+    paramSpecProp = addon.paramSpecProp;
+    variantNew = addon.variantNew;
+    variantUnpack = addon.variantUnpack;
+    variantGetTypeString = addon.variantGetTypeString;
+    isVariantHandle = addon.isVariantHandle;
+    startMainLoop = addon.startMainLoop;
+    iterateMainContext = addon.iterateMainContext;
+    mainContextHasPending = addon.mainContextHasPending;
+    makePumpPendingCount = addon.makePumpPendingCount;
+    pumpKick = addon.pumpKick;
+    setMicrotaskDrain = addon.setMicrotaskDrain;
+    connectSignal = addon.connectSignal;
+    emitSignal = addon.emitSignal;
+    disconnectSignal = addon.disconnectSignal;
+    setTemplateCallbackResolver = addon.setTemplateCallbackResolver;
+    setConstructCallback = addon.setConstructCallback;
+    setPropertySetCallback = addon.setPropertySetCallback;
+    storedPropertyNames = addon.storedPropertyNames;
+    logSetWriterFunc = addon.logSetWriterFunc;
+    logSetWriterDefault = addon.logSetWriterDefault;
+    bindPropertyFull = addon.bindPropertyFull;
+    bindingGroupBindFull = addon.bindingGroupBindFull;
+    setThreadLocale = addon.setThreadLocale;
+    textdomain = addon.textdomain;
+    bindtextdomain = addon.bindtextdomain;
+    localeCategories = addon.localeCategories;
+    probeHostOpenGL = addon.probeHostOpenGL;
+    currentGLStrings = addon.currentGLStrings;
+    loaded = true;
+    for (const hook of loadHooks.splice(0)) hook();
+    return native;
+}
+
+/** Whether the addon is loaded now — what the lazy host makes observable. */
+export function isNativeLoaded() {
+    return loaded;
+}
+
+/**
+ * Run `hook` once the addon is loaded: now if it is, else straight after the first load. The
+ * L1 module-scope registrations (error builder, template resolver, …) go through this, so they
+ * run at import on desktop and at first use on a lazy host.
+ * @param {() => void} hook
+ */
+export function onNativeLoaded(hook) {
+    if (loaded) hook();
+    else loadHooks.push(hook);
+}
 
 // Straight re-exports of the native engine surface. Each contract — arguments,
 // ownership, the OUT/INOUT return-tuple convention, the keep-alive rules of the
 // main-loop group — is documented once in index.d.ts, the published type surface;
 // only what index.d.ts does not carry is noted here.
-export const requireNamespace = native.requireNamespace;
-export const listInfoNames = native.listInfoNames;
-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;
-export const callFunction = native.callFunction;
-export const callMethod = native.callMethod;
-export const hasMethod = native.hasMethod;
-export const hasClassMethod = native.hasClassMethod;
-export const classMethodArity = native.classMethodArity;
-export const callStaticMethod = native.callStaticMethod;
-export const constructStruct = native.constructStruct;
-export const newObject = native.newObject;
-export const registerClass = native.registerClass;
+export let requireNamespace;
+export let listInfoNames;
+export let findInfo;
+export let getConstantValue;
+export let getEnumValues;
+export let getErrorDomain;
+export let errorDomainInfo;
+export let setErrorBuilder;
+export let prependSearchPath;
+export let prependLibraryPath;
+export let callFunction;
+export let callMethod;
+export let hasMethod;
+export let hasClassMethod;
+export let classMethodArity;
+export let callStaticMethod;
+export let constructStruct;
+export let newObject;
+export let registerClass;
 
 // Subclass an ALREADY-REGISTERED parent by its GType handle instead of a
 // `namespace.typeName`: a registered (dynamic) parent has no introspection entry, so it
 // cannot be resolved by name. Custom properties, signals and vfunc slots of registered
 // ancestors compose through ordinary GObject inheritance. The L1 `GObject.registerClass`
 // picks this variant when the nearest base is itself a registered class.
-export const registerClassFromGType = native.registerClassFromGType;
-
-export const constructType = native.constructType;
-export const callParentVfunc = native.callParentVfunc;
-export const hasClassVfunc = native.hasClassVfunc;
-export const callClassVfunc = native.callClassVfunc;
-export const getTemplateChild = native.getTemplateChild;
-export const getProperty = native.getProperty;
-export const setProperty = native.setProperty;
-export const hasProperty = native.hasProperty;
-export const getTypeName = native.getTypeName;
-export const classInfoForTypeName = native.classInfoForTypeName;
-export const getGType = native.getGType;
-export const isInstanceOf = native.isInstanceOf;
-export const isGObjectHandle = native.isGObjectHandle;
-export const newGValue = native.newGValue;
-export const callBoxedMethod = native.callBoxedMethod;
-export const isBoxedHandle = native.isBoxedHandle;
-export const boxedMemberKind = native.boxedMemberKind;
-export const getBoxedField = native.getBoxedField;
-export const setBoxedField = native.setBoxedField;
-export const boxedTypeName = native.boxedTypeName;
+export let registerClassFromGType;
+
+export let constructType;
+export let callParentVfunc;
+export let hasClassVfunc;
+export let callClassVfunc;
+export let getTemplateChild;
+export let getProperty;
+export let setProperty;
+export let hasProperty;
+export let getTypeName;
+export let classInfoForTypeName;
+export let getGType;
+export let isInstanceOf;
+export let isGObjectHandle;
+export let newGValue;
+export let callBoxedMethod;
+export let isBoxedHandle;
+export let boxedMemberKind;
+export let getBoxedField;
+export let setBoxedField;
+export let boxedTypeName;
 /** TEST-ONLY: the address a boxed handle wraps, so an ownership rule about pointer
  * IDENTITY can be asserted instead of waited on (see marshal.cc BoxedAddress). */
-export const __boxedAddress = native.__boxedAddress;
-export const isParamSpecHandle = native.isParamSpecHandle;
+export let __boxedAddress;
+export let isParamSpecHandle;
 
 // True for a non-GObject GObject-fundamental handle (a GskRenderNode from
 // Gtk.Snapshot.to_node, a GdkEvent): introspected as object info, but ref-counted
 // through its own ref/unref funcs, NOT g_object_ref. L1 surfaces it as an opaque,
 // round-trippable pass-through handle.
-export const isFundamentalHandle = native.isFundamentalHandle;
-
-export const paramSpecProp = native.paramSpecProp;
-export const variantNew = native.variantNew;
-export const variantUnpack = native.variantUnpack;
-export const variantGetTypeString = native.variantGetTypeString;
-export const isVariantHandle = native.isVariantHandle;
-export const startMainLoop = native.startMainLoop;
-export const iterateMainContext = native.iterateMainContext;
-export const mainContextHasPending = native.mainContextHasPending;
-export const makePumpPendingCount = native.makePumpPendingCount;
-export const pumpKick = native.pumpKick;
-export const setMicrotaskDrain = native.setMicrotaskDrain;
-export const connectSignal = native.connectSignal;
-export const emitSignal = native.emitSignal;
-export const disconnectSignal = native.disconnectSignal;
-export const setTemplateCallbackResolver = native.setTemplateCallbackResolver;
+export let isFundamentalHandle;
+
+export let paramSpecProp;
+export let variantNew;
+export let variantUnpack;
+export let variantGetTypeString;
+export let isVariantHandle;
+export let startMainLoop;
+export let iterateMainContext;
+export let mainContextHasPending;
+export let makePumpPendingCount;
+export let pumpKick;
+export let setMicrotaskDrain;
+export let connectSignal;
+export let emitSignal;
+export let disconnectSignal;
+export let setTemplateCallbackResolver;
 
 // Registers the L1 callback the engine's overridden `constructor` vfunc invokes to run a
 // registered class's JS constructor for a GObject that C instantiated (a GtkBuilder
 // composite-template InternalChild): given (instanceHandle, gtypeName) it
 // Reflect.constructs the class in adopt mode — see gi.js runCtorForCObject.
-export const setConstructCallback = native.setConstructCallback;
+export let setConstructCallback;
 
 // Registers the L1 callback the engine's set_property vfunc invokes after storing a
 // custom property: given (instanceHandle, propertyName) it runs the class's own JS
 // setter — see gi.js runJsPropertySetter. The engine calls it only once the instance
 // HAS a wrapper, so a construct-time set never reaches it; those are replayed from
 // the base ctor over storedPropertyNames.
-export const setPropertySetCallback = native.setPropertySetCallback;
+export let setPropertySetCallback;
 
 // The custom properties actually SET on an instance (the per-instance store's keys) —
 // what that construct-time replay has to push through the class's JS setters.
-export const storedPropertyNames = native.storedPropertyNames;
+export let storedPropertyNames;
 
-export const logSetWriterFunc = native.logSetWriterFunc;
-export const logSetWriterDefault = native.logSetWriterDefault;
-export const bindPropertyFull = native.bindPropertyFull;
-export const bindingGroupBindFull = native.bindingGroupBindFull;
+export let logSetWriterFunc;
+export let logSetWriterDefault;
+export let bindPropertyFull;
+export let bindingGroupBindFull;
 
 // The libintl half of GjsPrivate — the binders GLib's GIR does not publish, plus
 // the LC_* constants read from the host's own <locale.h>. Consumed by
 // `./gettext.js`; loading THIS module is also what puts the process in the
 // environment's locale (the addon's Init does it, as gjs's entry point does).
-export const setThreadLocale = native.setThreadLocale;
-export const textdomain = native.textdomain;
-export const bindtextdomain = native.bindtextdomain;
-export const localeCategories = native.localeCategories;
+export let setThreadLocale;
+export let textdomain;
+export let bindtextdomain;
+export let localeCategories;
 
 // win32 only (undefined elsewhere): which OpenGL the process got — see gtk-runtime.js
 // activateBundledOpenGL. currentGLStrings asks the implementation behind the context
 // current on this thread, so a caller can tell Mesa from a vendor driver.
-export const probeHostOpenGL = native.probeHostOpenGL;
-export const currentGLStrings = native.currentGLStrings;
+export let probeHostOpenGL;
+export let currentGLStrings;
+
+export { native as default };
 
-export default native;
+// Last, so every `export let` above is initialised before the eager load assigns it.
+if (!LAZY_NATIVE) ensureNative();

package/package.json

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

@@ -621,6 +621,11 @@ void InitCairo(Napi::Env env, Napi::Object exports) {
   c.Set("paint", Napi::Function::New(env, CTX_0(cairo_paint)));
   c.Set("clip", Napi::Function::New(env, CTX_0(cairo_clip)));
   c.Set("clipPreserve", Napi::Function::New(env, CTX_0(cairo_clip_preserve)));
+  c.Set("resetClip", Napi::Function::New(env, CTX_0(cairo_reset_clip)));
+  c.Set("pushGroup", Napi::Function::New(env, CTX_0(cairo_push_group)));
+  c.Set("popGroupToSource", Napi::Function::New(env, CTX_0(cairo_pop_group_to_source)));
+  c.Set("copyPage", Napi::Function::New(env, CTX_0(cairo_copy_page)));
+  c.Set("showPage", Napi::Function::New(env, CTX_0(cairo_show_page)));
 
   c.Set("setLineWidth", Napi::Function::New(env, CTX_1D(cairo_set_line_width)));
   c.Set("paintWithAlpha", Napi::Function::New(env, CTX_1D(cairo_paint_with_alpha)));
@@ -641,7 +646,10 @@ void InitCairo(Napi::Env env, Napi::Object exports) {
   c.Set("arc", Napi::Function::New(env, CTX_5D(cairo_arc)));
   c.Set("arcNegative", Napi::Function::New(env, CTX_5D(cairo_arc_negative)));
   c.Set("curveTo", Napi::Function::New(env, CTX_6D(cairo_curve_to)));
+  c.Set("relCurveTo", Napi::Function::New(env, CTX_6D(cairo_rel_curve_to)));
 
+  c.Set("pushGroupWithContent",
+        Napi::Function::New(env, CTX_ENUM(cairo_push_group_with_content, cairo_content_t)));
   c.Set("setOperator", Napi::Function::New(env, CTX_ENUM(cairo_set_operator, cairo_operator_t)));
   c.Set("setLineCap", Napi::Function::New(env, CTX_ENUM(cairo_set_line_cap, cairo_line_cap_t)));
   c.Set("setLineJoin", Napi::Function::New(env, CTX_ENUM(cairo_set_line_join, cairo_line_join_t)));
@@ -798,6 +806,45 @@ void InitCairo(Napi::Env env, Napi::Object exports) {
           o.Set("maxYAdvance", Napi::Number::New(env, e.max_y_advance));
           return o;
         }));
+  // The font matrix is a plain `{xx, yx, xy, yy, x0, y0}` object in GJS — cairo's
+  // matrix type has no wrapper there (getMatrix/setMatrix stay unbound for that
+  // reason), so the font matrix travels as the six doubles.
+  c.Set("getFontMatrix", 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_matrix_t m;
+          cairo_get_font_matrix(cr, &m);
+          if (!CheckStatus(env, cairo_status(cr), "context")) return env.Undefined();
+          Napi::Object o = Napi::Object::New(env);
+          o.Set("xx", Napi::Number::New(env, m.xx));
+          o.Set("yx", Napi::Number::New(env, m.yx));
+          o.Set("xy", Napi::Number::New(env, m.xy));
+          o.Set("yy", Napi::Number::New(env, m.yy));
+          o.Set("x0", Napi::Number::New(env, m.x0));
+          o.Set("y0", Napi::Number::New(env, m.y0));
+          return o;
+        }));
+  c.Set("setFontMatrix", 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();
+          if (!info[1].IsObject()) {
+            Napi::TypeError::New(env, "matrix must be an object").ThrowAsJavaScriptException();
+            return env.Undefined();
+          }
+          Napi::Object o = info[1].As<Napi::Object>();
+          cairo_matrix_t m;
+          m.xx = o.Get("xx").ToNumber().DoubleValue();
+          m.yx = o.Get("yx").ToNumber().DoubleValue();
+          m.xy = o.Get("xy").ToNumber().DoubleValue();
+          m.yy = o.Get("yy").ToNumber().DoubleValue();
+          m.x0 = o.Get("x0").ToNumber().DoubleValue();
+          m.y0 = o.Get("y0").ToNumber().DoubleValue();
+          cairo_set_font_matrix(cr, &m);
+          CheckStatus(env, cairo_status(cr), "context");
+          return env.Undefined();
+        }));
   c.Set("status", Napi::Function::New(env, +[](const Napi::CallbackInfo& info) -> Napi::Value {
           Napi::Env env = info.Env();
           cairo_t* cr = CtxArg(env, info);
@@ -824,6 +871,26 @@ void InitCairo(Napi::Env env, Napi::Object exports) {
           CheckStatus(env, cairo_status(cr), "context");
           return env.Undefined();
         }));
+  c.Set("mask", 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_pattern_t* p = PatternFromExt(env, info[1]);
+          if (p == nullptr) return env.Undefined();
+          cairo_mask(cr, p);
+          CheckStatus(env, cairo_status(cr), "context");
+          return env.Undefined();
+        }));
+  c.Set("maskSurface", 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_surface_t* s = SurfaceFromExt(env, info[1]);
+          if (s == nullptr) return env.Undefined();
+          cairo_mask_surface(cr, s, Num(info, 2), Num(info, 3));
+          CheckStatus(env, cairo_status(cr), "context");
+          return env.Undefined();
+        }));
 
   c.Set("identityMatrix", Napi::Function::New(env, CTX_0(cairo_identity_matrix)));
   c.Set("newSubPath", Napi::Function::New(env, CTX_0(cairo_new_sub_path)));
@@ -970,6 +1037,35 @@ void InitCairo(Napi::Env env, Napi::Object exports) {
           return MakeCairoHandle(env, p, CairoKind::Pattern);
         }));
 
+  // popGroup: cairo_pop_group returns a NEW pattern (transfer-full) — the handle
+  // adopts that ref directly, no extra reference (gjs wraps and then drops its own).
+  c.Set("popGroup", 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_pattern_t* p = cairo_pop_group(cr);
+          if (!CheckStatus(env, cairo_status(cr), "context")) {
+            cairo_pattern_destroy(p);
+            return env.Undefined();
+          }
+          return MakeCairoHandle(env, p, CairoKind::Pattern);
+        }));
+
+  // getTarget/getGroupTarget: the surface belongs to the context — ref it so the
+  // JS wrapper owns one (mirrors CairoSurface::from_c_ptr's kept reference).
+#define CTX_SURFACE_GETTER(NAME, CFN)                                                       \
+  c.Set(NAME, 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_surface_t* s = CFN(cr);                                                     \
+          if (!CheckStatus(env, cairo_status(cr), "context")) return env.Undefined();       \
+          cairo_surface_reference(s);                                                       \
+          return MakeCairoHandle(env, s, CairoKind::Surface);                                \
+        }));
+  CTX_SURFACE_GETTER("getTarget", cairo_get_target)
+  CTX_SURFACE_GETTER("getGroupTarget", cairo_get_group_target)
+
   // ---- $dispose (Context / Surface / Pattern / Path) ----
   // Eagerly destroy the underlying cairo object + mark the handle so the finalizer
   // won't double-free and any further method call throws (a live-handle check).

package/src/class.cc

@@ -44,6 +44,8 @@ static GType UnwrapGType(Napi::Env env, Napi::Value v) {
 static GType TypeNameToGType(const std::string& t) {
   if (t == "string" || t == "utf8") return G_TYPE_STRING;
   if (t == "boolean" || t == "bool") return G_TYPE_BOOLEAN;
+  if (t == "char") return G_TYPE_CHAR;
+  if (t == "uchar") return G_TYPE_UCHAR;
   if (t == "int") return G_TYPE_INT;
   if (t == "uint") return G_TYPE_UINT;
   if (t == "int64") return G_TYPE_INT64;
@@ -95,6 +97,19 @@ static GParamSpec* BuildParamSpec(Napi::Env env, Napi::Object spec, std::string*
                                  : (def.IsNumber() ? NodeGiToBool(def) : FALSE);
     return g_param_spec_boolean(nm, nm, nm, d, flags);
   }
+  if (type == "char") {
+    return g_param_spec_char(nm, nm, nm, hasMin ? static_cast<gint8>(mn) : G_MININT8,
+                             hasMax ? static_cast<gint8>(mx) : G_MAXINT8,
+                             def.IsNumber() ? static_cast<gint8>(def.As<Napi::Number>().Int32Value()) : 0,
+                             flags);
+  }
+  if (type == "uchar") {
+    return g_param_spec_uchar(nm, nm, nm, hasMin ? static_cast<guint8>(mn) : 0,
+                              hasMax ? static_cast<guint8>(mx) : G_MAXUINT8,
+                              def.IsNumber() ? static_cast<guint8>(def.As<Napi::Number>().Uint32Value())
+                                             : 0,
+                              flags);
+  }
   if (type == "int") {
     return g_param_spec_int(nm, nm, nm, hasMin ? static_cast<gint>(mn) : G_MININT,
                             hasMax ? static_cast<gint>(mx) : G_MAXINT,

package/src/common.h

@@ -363,7 +363,7 @@ inline NodeGiIntResult NodeGiJsToInteger(Napi::Value v, GITypeTag tag, GIArgumen
   }
 }
 
-enum class NodeGiIntContext { kArgument, kField, kReturnValue };
+enum class NodeGiIntContext { kArgument, kField, kReturnValue, kListElement, kHashElement };
 inline const char* NodeGiIntTagName(GITypeTag tag) {
   switch (tag) {
     case GI_TYPE_TAG_INT8: return "int8";
@@ -385,13 +385,31 @@ inline void NodeGiThrowIntOutOfRange(Napi::Env env, GITypeTag tag, NodeGiIntCont
     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")) +
+          (ctx == NodeGiIntContext::kField
+               ? std::string("Field '") + (name ? name : "") + "'"
+               : ctx == NodeGiIntContext::kListElement   ? std::string("List element")
+               : ctx == NodeGiIntContext::kHashElement   ? std::string("Hash element")
+                                                         : std::string("Return value")) +
           " (type " + t + ")";
   }
   Napi::Error::New(env, msg).ThrowAsJavaScriptException();
 }
 
+// The text gjs_debug_value (refs/gjs/gi/../jsapi-util-string.cpp) prints for the offending
+// value in a list/hash element error: a Number goes through C++ ostream (%g, 6 digits), a
+// BigInt is shown as its signed 64-bit value with a "(modulo 2^64)" suffix.
+inline std::string NodeGiDebugValue(Napi::Value v) {
+  if (v.IsBigInt()) {
+    bool lossless = false;
+    return std::to_string(v.As<Napi::BigInt>().Int64Value(&lossless)) + "n (modulo 2^64)";
+  }
+  Napi::Number n = v.ToNumber();
+  if (n.IsEmpty()) return std::string();
+  char buf[G_ASCII_DTOSTR_BUF_SIZE];
+  g_ascii_formatd(buf, sizeof(buf), "%g", n.DoubleValue());  // locale-independent, like ostream
+  return buf;
+}
+
 // 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 —

package/src/marshal.cc

@@ -1060,6 +1060,8 @@ static bool IsSupportedElementType(GITypeInfo* elem, std::string* why, bool byVa
     case GI_TYPE_TAG_UTF8:
     case GI_TYPE_TAG_FILENAME:
       return true;
+    // A gunichar is a 4-byte cell; only a C array writes one (no list/hash node).
+    case GI_TYPE_TAG_UNICHAR: return cArrayCell;
     case GI_TYPE_TAG_INTERFACE: {
       GIBaseInfo* iface = gi_type_info_get_interface(elem);
       bool ok = iface != nullptr && (GI_IS_OBJECT_INFO(iface) || GI_IS_INTERFACE_INFO(iface));
@@ -1178,7 +1180,8 @@ size_t CElementSize(GITypeInfo* elem) {
     case GI_TYPE_TAG_INT16:
     case GI_TYPE_TAG_UINT16: return 2;
     case GI_TYPE_TAG_INT32:
-    case GI_TYPE_TAG_UINT32: return 4;
+    case GI_TYPE_TAG_UINT32:
+    case GI_TYPE_TAG_UNICHAR: return 4;
     case GI_TYPE_TAG_INT64:
     case GI_TYPE_TAG_UINT64: return 8;
     case GI_TYPE_TAG_FLOAT: return sizeof(gfloat);
@@ -1601,16 +1604,16 @@ 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, bool wrapIntegers = false) {
+                                GITransfer elemTransfer, NodeGiIntContext intContext = NodeGiIntContext::kListElement,
+                                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;
-    // 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.
+    // Integers WRAP in an array (arg.cpp gjs_array_to_auto_array, NodeGiJsToIntegerWrap in
+    // common.h) and are REFUSED out of range in a GList/GHashTable node.
     case GI_TYPE_TAG_INT8:
     case GI_TYPE_TAG_UINT8:
     case GI_TYPE_TAG_INT16:
@@ -1621,16 +1624,20 @@ static bool ElementToGIArgument(Napi::Env env, GITypeInfo* elem, Napi::Value v,
     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;
+      // A list/hash node is checked, not wrapped (arg.cpp gjs_value_to_basic_gi_argument
+      // -> gjs_arg_set_from_js_value): out of range is a plain Error.
+      switch (NodeGiJsToInteger(v, gi_type_info_get_tag(elem), a, nullptr)) {
+        case NodeGiIntResult::kPending: return false;
+        case NodeGiIntResult::kOutOfRange:
+          NodeGiThrowIntOutOfRange(env, gi_type_info_get_tag(elem), intContext, nullptr,
+                                   NodeGiDebugValue(v));
+          return false;
+        case NodeGiIntResult::kOk: return true;
       }
+      return true;
+    // gjs_array_to_auto_array<char32_t> wraps like uint32 (arg.cpp js_value_to_c_strict).
+    case GI_TYPE_TAG_UNICHAR:
+      return NodeGiJsToIntegerWrap(v, GI_TYPE_TAG_UINT32, a) == NodeGiIntResult::kOk;
     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: {
@@ -2267,6 +2274,20 @@ static bool JsToCArray(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransfe
     return true;
   }
 
+  // A JS string as a gunichar C array → its code points (arg.cpp:584, gjs_string_to_ucs4).
+  if (at == GI_ARRAY_TYPE_C && etag == GI_TYPE_TAG_UNICHAR && v.IsString()) {
+    std::string s = v.As<Napi::String>().Utf8Value();
+    glong n = 0;
+    gunichar* ucs = g_utf8_to_ucs4_fast(s.c_str(), static_cast<glong>(s.size()), &n);
+    void* buf = g_malloc0(elemSize * (n + (zt ? 1 : 0)));
+    if (n > 0) memcpy(buf, ucs, elemSize * n);
+    g_free(ucs);
+    *outPtr = buf;
+    *outCount = static_cast<long>(n);
+    gi_base_info_unref(elem);
+    return true;
+  }
+
   if (!v.IsArray()) {
     gi_base_info_unref(elem);
     Napi::TypeError::New(env, "expected an array for the array argument")
@@ -2301,7 +2322,7 @@ static bool JsToCArray(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransfe
     }
     GIArgument a;
     ok = ElementToGIArgument(env, elem, arr.Get(static_cast<uint32_t>(i)), &a, elemTransfer,
-                             /*wrapIntegers=*/true);
+                             NodeGiIntContext::kListElement, /*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
@@ -2448,7 +2469,8 @@ static bool JsToGHashIn(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransf
     } else {
       GIArgument ka;
       Napi::Value keyNum = Napi::Number::New(env, static_cast<double>(g_ascii_strtoll(ks.c_str(), nullptr, 10)));
-      ok = ElementToGIArgument(env, kt, keyNum, &ka, GI_TRANSFER_NOTHING);
+      ok = ElementToGIArgument(env, kt, keyNum, &ka, GI_TRANSFER_NOTHING,
+                               NodeGiIntContext::kHashElement, /*wrapIntegers=*/true);
       if (!ok) break;
       kp = gi_type_info_hash_pointer_from_argument(kt, &ka);
     }
@@ -2459,7 +2481,7 @@ static bool JsToGHashIn(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransf
     Napi::Value val = obj.Get(key);
     gpointer vp = nullptr;
     GIArgument va;
-    ok = ElementToGIArgument(env, vt, val, &va, elemTransfer);
+    ok = ElementToGIArgument(env, vt, val, &va, elemTransfer, NodeGiIntContext::kHashElement);
     if (!ok) {
       g_free(kp);
       break;