@gjsify/node-gi 0.64.1 → 0.64.4

package/host.nativescript.js

@@ -44,6 +44,25 @@
 /** @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;
+
+/**
+ * Whether `GObject.registerClass` may register a class whose JS parent is NOT a node-gi
+ * GObject class — `class MyLabel extends Label {}`, where `Label` is a
+ * `@nativescript/core` widget. GJS rejects that outright and so does node-gi on every
+ * other host; this is the ONE deliberate divergence, and it is deliberate because on
+ * NativeScript there is no GJS to be compatible with: node-gi is the only GI runtime that
+ * ever executes here, so a program written against this cannot be a program that behaves
+ * differently under GJS. See the FOREIGN-PARENT section in gi.js, ADR 0105 § 2 and
+ * docs/node-gi-gjs-surface.md.
+ * @type {boolean}
+ */
+export const FOREIGN_PARENT_CLASSES = 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,22 @@ 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;
+
+/**
+ * Whether `GObject.registerClass` may register a class whose JS parent is NOT a node-gi
+ * GObject class. FALSE here, and that is the point: on Node/Bun/Deno/GJS a program can be
+ * run under real GJS, so registerClass must keep throwing GJS's invalid-base error
+ * (refs/gjs/modules/core/overrides/GObject.js) rather than quietly accept a class GJS
+ * would reject. Only host.nativescript.js enables it — see the note there.
+ * @type {boolean}
+ */
+export const FOREIGN_PARENT_CLASSES = 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.d.ts

@@ -542,6 +542,18 @@ export function emitSignal(handle: GObjectHandle, signalName: string, args?: unk
 /** Disconnect a previously connected signal handler. */
 export function disconnectSignal(handle: GObjectHandle, handlerId: number): void;
 
+/**
+ * INTERNAL. Keep a callback alive for as long as `handle` is alive. Signal and
+ * template-callback GClosures hold their JS callback through a WEAK napi_ref, so
+ * a connected handler is not a GC root (which is what makes a handler capturing
+ * its own emitter collectable, as in GJS); this handle-keyed WeakMap is the
+ * ephemeron that keeps it callable meanwhile. `connectSignal` does it for you.
+ */
+export function retainClosure(handle: GObjectHandle, key: number | symbol, fn: Function): void;
+
+/** INTERNAL. Drop a closure retained by {@link retainClosure}. */
+export function releaseClosure(handle: GObjectHandle, key: number | symbol): void;
+
 /**
  * Register the L1 resolver mapping a Gtk.Template `<signal handler="…">` handler
  * name to the instance's bound JS method (engine template-callback scope).

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,290 @@ 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;
+    emitSignal = addon.emitSignal;
+    connectSignal = (handle, signalName, callback, after) => {
+        const id = addon.connectSignal(handle, signalName, callback, after);
+        retainClosure(handle, id, callback);
+        return id;
+    };
+    disconnectSignal = (handle, handlerId) => {
+        releaseClosure(handle, handlerId);
+        return addon.disconnectSignal(handle, handlerId);
+    };
+    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;
+// ---- signal-closure keep-alive (GJS's associate_closure, built in JS) ----
+//
+// A signal / template-callback GClosure holds its JS callback through a WEAK
+// napi_ref (src/signals.cc), so a C-held closure is NOT a GC root. That is what
+// makes `obj.connect('x', () => obj.y)` collectable instead of immortal, and it
+// is GJS's design: its signal closures keep the callable unrooted and TRACE it
+// from the owning wrapper (ObjectInstance::m_closures).
+//
+// node-gi has no tracing hook into V8, so the same edge is expressed as the one
+// ephemeron a non-extensible External can take part in: a WeakMap keyed by the
+// canonical handle. Handle reachable (JS holds the wrapper, or C owns the object
+// and the toggle ref roots the handle) → callback reachable → a connected handler
+// still fires. Handle reachable ONLY through the callback it retains → key and
+// value die together, which is exactly the cycle that used to leak.
+//
+// Pruned on disconnect. A handler disconnected by a route that bypasses
+// `disconnectSignal` (the introspected GObject.signal_handler_disconnect) leaves
+// its entry behind until the handle itself goes — harmless, the closure is
+// already gone, and the same divergence the gi.js handler-id registry documents.
+const retainedClosures = new WeakMap();
+
+/**
+ * Keep `fn` alive for as long as `handle` is alive. INTERNAL — the JS half of the
+ * weak closure refs in src/signals.cc.
+ * @param {object} handle canonical GObject handle (the WeakMap key / lifetime)
+ * @param {number | symbol} key handler id, or a unique key for a non-signal closure
+ * @param {Function} fn the callback the native closure holds weakly
+ */
+export function retainClosure(handle, key, fn) {
+    let byKey = retainedClosures.get(handle);
+    if (byKey === undefined) {
+        byKey = new Map();
+        retainedClosures.set(handle, byKey);
+    }
+    byKey.set(key, fn);
+}
+
+/**
+ * Drop a retained closure (on disconnect). INTERNAL — see retainClosure.
+ * @param {object} handle canonical GObject handle
+ * @param {number | symbol} key the key it was retained under
+ */
+export function releaseClosure(handle, key) {
+    retainedClosures.get(handle)?.delete(key);
+}
+
+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.4",
   "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,