@gjsify/node-gi 0.64.0 → 0.64.2

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/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.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

@@ -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).
@@ -620,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)));
@@ -640,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)));
@@ -733,6 +742,109 @@ 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;
+        }));
+  // 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);
@@ -759,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)));
@@ -905,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).