@gjsify/node-gi 0.64.1 → 0.64.4

package/README.md

@@ -148,6 +148,15 @@ export halves, the legacy `imports.*` modules, cairo, and the measured
 divergences from GJS — is
 [docs/node-gi-gjs-surface.md](../../../docs/node-gi-gjs-surface.md).
 
+One divergence is deliberate rather than measured, and it only exists under the
+`nativescript` export condition: there `registerClass` accepts a parent class
+that is not a GObject class, so an `@nativescript/core` widget can BE a real
+GObject subclass (properties, signals, `bind_property`, `Gio.ListStore`
+identity) while staying the widget its layout demands. Every other host throws
+GJS's invalid-base-class error, unchanged — see
+[§ `registerClass` over a FOREIGN parent class](../../../docs/node-gi-gjs-surface.md)
+and [ADR 0105](../../../docs/adr/0105-real-gobject-backs-the-nativescript-subset-on-android.md).
+
 ## Runtimes (Node / Bun / Deno)
 
 The engine is a **Node-API** addon, so the same binary loads and runs on **Node,

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