@gjsify/node-gi 0.26.1 → 0.27.1

package/README.md

@@ -86,16 +86,44 @@ vendored as-is — gjsify ships its own dual (GJS + Node) example/test infra.
 ## Requirements
 
 - Node.js ≥ 20
-- A C++ toolchain (`g++`/`clang`, `make`), `node-gyp`
-- GLib ≥ 2.80 development headers exposing `girepository-2.0`
-  (Fedora: `glib2-devel gobject-introspection-devel gcc-c++`;
-   Debian/Ubuntu: `libglib2.0-dev libgirepository-2.0-dev g++`)
+- **No C++ toolchain on the four prebuilt targets.** The published tarball ships
+  `prebuilds/<platform>-<arch>/node_gi.node` for `linux-x64`, `linux-arm64`,
+  `darwin-arm64` and `win32-x64` (`package.json#gjsify.platforms`), and the
+  `install` script (`scripts/install.mjs`) uses it instead of building: a source
+  build is the FALLBACK for a host with no prebuild, not the default. Force it
+  with `NODE_GI_BUILD_FROM_SOURCE=1` (or npm's `--build-from-source`); skip it
+  entirely with `NODE_GI_SKIP_NATIVE_BUILD=1`.
+- For a source build only: a C++ toolchain (`g++`/`clang`, `make`), `node-gyp`,
+  and GLib ≥ 2.80 development headers exposing `girepository-2.0` + cairo
+  (Fedora: `glib2-devel gobject-introspection-devel cairo-devel gcc-c++`;
+   Debian/Ubuntu: `libglib2.0-dev libgirepository-2.0-dev libcairo2-dev g++`)
 - At runtime, the target libraries' typelibs must be installed (same as `gi://`
-  under GJS) — **except on macOS arm64**, where the optional
-  [`@gjsify/gtk-runtime-darwin-arm64`](../gtk-runtime-darwin-arm64) bundle ships a
-  relocated GTK/GI runtime so the display-free surface works with no Homebrew GTK
-  (Phase 2). node-gi auto-detects the bundle at load and prepends its typelib dir
-  to the GIRepository search path (`gtk-runtime.js`).
+  under GJS) — **except on macOS (both arm64 and Intel x64) and Windows x64**,
+  where a batteries-included, relocated GTK/GI runtime bundle ships so `gi://`
+  works with no Homebrew/gvsbuild GTK (Phase 2). node-gi auto-detects a bundle at
+  load and prepends its typelib dir to the GIRepository search path
+  (`gtk-runtime.js`) — nothing in that loader keys on a specific target, so each
+  new bundle is found by the mechanism that found the first.
+- **Those bundles are a MANUAL install today.**
+  [`@gjsify/gtk-runtime-darwin-arm64`](../gtk-runtime-darwin-arm64),
+  [`@gjsify/gtk-runtime-darwin-x64`](../gtk-runtime-darwin-x64) and
+  [`@gjsify/gtk-runtime-win32-x64`](../gtk-runtime-win32-x64) are published, and
+  node-gi finds whichever one is present in the tree — but **no
+  package declares them as a dependency**, so nothing installs them for you.
+  Install the one for your platform alongside node-gi:
+
+  ```bash
+  npm install @gjsify/gtk-runtime-win32-x64      # Windows x64
+  npm install @gjsify/gtk-runtime-darwin-arm64   # macOS Apple silicon
+  npm install @gjsify/gtk-runtime-darwin-x64     # macOS Intel
+  ```
+
+  All three declare `os`/`cpu`, so npm/yarn/pnpm skip them off-platform. Making them
+  `optionalDependencies` of this package (which would remove the manual step
+  without any consumer-side platform branching) is pending two decisions outside
+  this package — the ADR-0003 dependency-direction rule between node-gi's tier
+  and the bundles', and `os`/`cpu` filtering in `gjsify install`'s native
+  backend, which currently places foreign-platform optional deps.
 - **Node.js ≥ 20, Bun ≥ 1.3, or Deno ≥ 2** — the addon is Node-API, so one binary
   runs on all three (see [Runtimes](#runtimes-node--bun--deno)).
 
@@ -138,6 +166,45 @@ conformance subset since 2.9 (the marshalling/async N-API quirks that excluded
 `arrays`/`async-error` on Deno 2.1 are fixed upstream) — the Node-only co-pump
 cases are the remaining, by-design gap. The authoritative full suite runs on Node.
 
+**Architectures.** CI runs the Bun/Deno legs on x86-64 only, so `linux-arm64` was
+measured by hand on a OnePlus 6T / postmarketOS (2026-08-03) against the PUBLISHED
+0.27.0 `prebuilds/linux-arm64/node_gi.node`: **Bun 1.3.14 → 38/38** cross-runtime
+files, **Deno 2.9.4 → 35/38 plus the three known non-gating Deno teardown exits,
+0 failed**. Two libc notes from that run:
+
+- the prebuild declares glibc, yet it **loads and runs on a pure-musl host** (Alpine
+  / postmarketOS, no glibc, no `gcompat`) under Bun's musl build: musl's dynamic
+  loader maps the `libc.so.6` / `libm.so.6` `DT_NEEDED` entries onto ITSELF via its
+  reserved-name list, and every other dependency (`libglib-2.0`,
+  `libgirepository-2.0`, `libcairo`, `libstdc++`, `libgcc_s`) exists musl-built.
+  **Do not read a successful load as "every symbol resolved".** Measured with a real
+  artifact (`@gjsify/sab-native`'s pre-#955 prebuild) on aarch64 musl and in
+  `alpine:3.24` x86-64: `dlopen` behaves oppositely by mode — `RTLD_NOW` fails at
+  load, `RTLD_LAZY` **loads** and the process dies at the first call through the
+  deferred PLT slot. GI opens typelib backers with `G_MODULE_BIND_LAZY`, so on musl a
+  glibc-only symbol really does hide from a load. Both arches behave identically.
+  A weak undefined symbol hides the same way. So this binary is clear by audit, not
+  by its load: 5 of its 579 undefined symbols are weak, and the 3 unresolvable on
+  musl (`_ITM_{,de}registerTMCloneTable`, `__gmon_start__`) are the NULL-guarded gcc
+  boilerplate every DSO carries. What defeats the hiding is `dlopen(RTLD_NOW)`, or —
+  with no musl machine at all — a glibc-floor `SHT_GNU_verneed` audit.
+- **Deno publishes no musl build** (`aarch64-unknown-linux-gnu` only), so on such a
+  host Deno needs a glibc environment (here the `org.gnome.Platform//49` flatpak
+  runtime: glibc 2.42, gjs 1.86.0). With `node_modules/` already materialised, both
+  `--node-modules-dir=manual` and Deno's default worked.
+
+On **Linux** the typelib's bare library leaf needs no help: `Gtk`/`Gdk`/`Adw`/`Pango`/
+`Graphene` all resolve and `Gtk.DrawingArea` subclasses correctly with no
+`GI_TYPELIB_PATH` and no `LD_LIBRARY_PATH`, both on the musl host and inside the
+flatpak runtime, because the system loader's default search path already covers the
+distro's own libraries. That is worth stating explicitly because the same step FAILS
+on macOS (`Failed to load shared library 'libgtk-4.1.dylib' referenced by the
+typelib` → `Gtk.DrawingArea is not a subclassable GObject type`): dyld has no
+`ld.so.conf` equivalent, and a plain `node`/`bun`/`deno` binary carries no rpath into
+Homebrew's prefix, where `gjs` itself does. A loader-path failure of that shape is
+never a node-gi or runtime defect — see `gtk-runtime.js` and the CLI's
+`detectNativePackages()` / `buildNativeEnv()` for how the env normally gets wired.
+
 Promise draining during a blocking loop is cross-runtime because the engine runs
 a **microtask checkpoint at every outermost loop-dispatched GLib→JS callback
 boundary**: Node's `napi_make_callback` performs it natively; Bun's and Deno's
@@ -153,7 +220,7 @@ blocking loop remain Node-only (the uv co-pump).
 ## Build & test
 
 ```bash
-npm install          # builds the native addon via node-gyp (install script)
+npm install          # prebuild if one is staged, else node-gyp (scripts/install.mjs)
 npm test             # node --test (full suite, Node — authoritative)
 npm run test:gc      # node --test --expose-gc (toggle-ref GC-stress leg)
 npm run test:bun     # conformance subset on Bun   (needs `bun`)
@@ -170,7 +237,15 @@ and the bun/deno runner defaults to it — without that, a stale staged prebuild
 silently shadows your build. CI's cross-runtime job sets `NODE_GI_NATIVE=prebuild`
 to keep validating the prebuild load path with a freshly staged binary.
 `NODE_GI_NATIVE` accepts `build`, `prebuild`, or an explicit path to a
-`node_gi.node`.
+`node_gi.node`. That candidate order lives in `native-paths.js` and is shared
+with the `install` script, so the binary the guard decides not to rebuild is
+by construction the binary the loader looks for.
+
+In a checkout `prebuilds/` is gitignored, so `npm install` here always runs the
+source build — as do the `npm install --foreground-scripts` steps in
+`node-gi.yml` and the `node-gi-prebuild-*` legs in `release.yml`, which need
+`build/Release/node_gi.node` for `scripts/stage-prebuild.mjs`. Set
+`NODE_GI_BUILD_FROM_SOURCE=1` to force it regardless of a staged prebuild.
 
 Two debug-only env vars instrument the toggle-ref / teardown machinery (both
 parsed once at first use, zero cost when unset — never set them in production):
@@ -866,7 +941,7 @@ Shader/buffer/texture breadth (a three.js triangle/teapot) is the remaining
 follow-up — the seam + context stack are proven.
 
 The tests self-skip without a display, without a `gjsify` CLI, or without the
-committed `Gwebgl-0.1` prebuild (`packages/framework/webgl/prebuilds/linux-*`,
+committed `Gwebgl-0.1` prebuild (`packages/framework/webgl-linux-*/prebuilds/`,
 which the test itself puts on `GI_TYPELIB_PATH`/`LD_LIBRARY_PATH`); the bridge
 test additionally skips when `@gjsify/webgl` is not built. The fixture build
 needs a WORKSPACE-built `@gjsify/cli` (point `GJSIFY_BIN` at
@@ -1005,6 +1080,15 @@ marker and wires the env (`GSETTINGS_SCHEMA_DIR` / `GDK_PIXBUF_MODULE_FILE` /
 `XDG_DATA_DIRS` / `FONTCONFIG_*`); a display-free bundle carries no marker, so the
 wiring is a strict no-op and that load is byte-unchanged.
 
+The bundle is not pulled in automatically — `npm install
+@gjsify/gtk-runtime-win32-x64` alongside node-gi (see
+[Requirements](#requirements)). `resolveGtkRuntimeBundle()` finds it wherever the
+package manager placed it: an explicit `GJSIFY_GTK_RUNTIME` dir, a staged
+`prebuilds/<target>/gtk/`, the sibling monorepo checkout, or
+`require.resolve('@gjsify/gtk-runtime-<target>')` — the last of which covers a
+hoisted `node_modules/@gjsify/gtk-runtime-win32-x64`, so no loader change is
+needed if the dependency edge is ever declared.
+
 ### Adwaita widget breadth realizes + reacts + renders
 
 Beyond one window's chrome: a representative slice of the REAL Libadwaita widget

package/cairo.d.ts

@@ -19,136 +19,136 @@ export const SurfaceType: CairoEnum;
 
 /** cairo drawing context (`cairo_t`). */
 export class Context {
-  constructor(surface: Surface);
-  save(): void;
-  restore(): void;
-  newPath(): void;
-  closePath(): void;
-  moveTo(x: number, y: number): void;
-  lineTo(x: number, y: number): void;
-  relMoveTo(dx: number, dy: number): void;
-  relLineTo(dx: number, dy: number): 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;
-  fill(): void;
-  fillPreserve(): void;
-  stroke(): void;
-  strokePreserve(): void;
-  paint(): void;
-  paintWithAlpha(alpha: number): void;
-  clip(): void;
-  clipPreserve(): void;
-  translate(tx: number, ty: number): void;
-  scale(sx: number, sy: number): void;
-  rotate(angle: number): void;
-  setSourceRGB(red: number, green: number, blue: number): void;
-  setSourceRGBA(red: number, green: number, blue: number, alpha: number): void;
-  setSource(pattern: Pattern): void;
-  setSourceSurface(surface: Surface, x: number, y: number): void;
-  /** The context's current source pattern (own reference; concrete subclass). */
-  getSource(): Pattern;
-  identityMatrix(): void;
-  newSubPath(): void;
-  /** User → device coordinates as `[x, y]` (GJS return shape). */
-  userToDevice(x: number, y: number): [number, number];
-  /** User → device distance (ignores translation) as `[dx, dy]`. */
-  userToDeviceDistance(dx: number, dy: number): [number, number];
-  /** Device → user coordinates as `[x, y]`. */
-  deviceToUser(x: number, y: number): [number, number];
-  /** Device → user distance (ignores translation) as `[dx, dy]`. */
-  deviceToUserDistance(dx: number, dy: number): [number, number];
-  /** Copy the current path into an owned {@link Path} handle. */
-  copyPath(): Path;
-  /** Like {@link copyPath} but with curves flattened to line segments. */
-  copyPathFlat(): Path;
-  appendPath(path: Path): void;
-  /**
-   * Set the stroke dash pattern. GJS semantics: holes/undefined entries are
-   * skipped, a non-positive value throws, an empty array disables dashing.
-   */
-  setDash(dashes: number[], offset: number): void;
-  getDashCount(): number;
-  /**
-   * The current dash pattern as `[dashes, offset]`.
-   * Note: GJS ships only `getDashCount`; this is a node-gi convenience.
-   */
-  getDash(): [number[], number];
-  inFill(x: number, y: number): boolean;
-  inStroke(x: number, y: number): boolean;
-  setLineWidth(width: number): void;
-  getLineWidth(): number;
-  setLineCap(lineCap: number): void;
-  setLineJoin(lineJoin: number): void;
-  setFillRule(fillRule: number): void;
-  setAntialias(antialias: number): void;
-  setOperator(op: number): void;
-  setMiterLimit(limit: number): void;
-  setTolerance(tolerance: number): void;
-  status(): number;
-  $dispose(): void;
+    constructor(surface: Surface);
+    save(): void;
+    restore(): void;
+    newPath(): void;
+    closePath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    relMoveTo(dx: number, dy: number): void;
+    relLineTo(dx: number, dy: number): 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;
+    fill(): void;
+    fillPreserve(): void;
+    stroke(): void;
+    strokePreserve(): void;
+    paint(): void;
+    paintWithAlpha(alpha: number): void;
+    clip(): void;
+    clipPreserve(): void;
+    translate(tx: number, ty: number): void;
+    scale(sx: number, sy: number): void;
+    rotate(angle: number): void;
+    setSourceRGB(red: number, green: number, blue: number): void;
+    setSourceRGBA(red: number, green: number, blue: number, alpha: number): void;
+    setSource(pattern: Pattern): void;
+    setSourceSurface(surface: Surface, x: number, y: number): void;
+    /** The context's current source pattern (own reference; concrete subclass). */
+    getSource(): Pattern;
+    identityMatrix(): void;
+    newSubPath(): void;
+    /** User → device coordinates as `[x, y]` (GJS return shape). */
+    userToDevice(x: number, y: number): [number, number];
+    /** User → device distance (ignores translation) as `[dx, dy]`. */
+    userToDeviceDistance(dx: number, dy: number): [number, number];
+    /** Device → user coordinates as `[x, y]`. */
+    deviceToUser(x: number, y: number): [number, number];
+    /** Device → user distance (ignores translation) as `[dx, dy]`. */
+    deviceToUserDistance(dx: number, dy: number): [number, number];
+    /** Copy the current path into an owned {@link Path} handle. */
+    copyPath(): Path;
+    /** Like {@link copyPath} but with curves flattened to line segments. */
+    copyPathFlat(): Path;
+    appendPath(path: Path): void;
+    /**
+     * Set the stroke dash pattern. GJS semantics: holes/undefined entries are
+     * skipped, a non-positive value throws, an empty array disables dashing.
+     */
+    setDash(dashes: number[], offset: number): void;
+    getDashCount(): number;
+    /**
+     * The current dash pattern as `[dashes, offset]`.
+     * Note: GJS ships only `getDashCount`; this is a node-gi convenience.
+     */
+    getDash(): [number[], number];
+    inFill(x: number, y: number): boolean;
+    inStroke(x: number, y: number): boolean;
+    setLineWidth(width: number): void;
+    getLineWidth(): number;
+    setLineCap(lineCap: number): void;
+    setLineJoin(lineJoin: number): void;
+    setFillRule(fillRule: number): void;
+    setAntialias(antialias: number): void;
+    setOperator(op: number): void;
+    setMiterLimit(limit: number): void;
+    setTolerance(tolerance: number): void;
+    status(): number;
+    $dispose(): void;
 }
 
 /** cairo surface base class (`cairo_surface_t`). */
 export class Surface {
-  getType(): number;
-  status(): number;
-  flush(): void;
-  finish(): void;
-  writeToPNG(filename: string): void;
-  $dispose(): void;
+    getType(): number;
+    status(): number;
+    flush(): void;
+    finish(): void;
+    writeToPNG(filename: string): void;
+    $dispose(): void;
 }
 
 /** cairo image surface (`cairo_image_surface_*`). */
 export class ImageSurface extends Surface {
-  constructor(format: number, width: number, height: number);
-  static create(format: number, width: number, height: number): ImageSurface;
-  static createFromPNG(filename: string): ImageSurface;
-  getWidth(): number;
-  getHeight(): number;
-  getStride(): number;
-  getFormat(): number;
-  /** Raw pixel buffer as a fresh Uint8Array copy (length = stride * height). */
-  getData(): Uint8Array;
+    constructor(format: number, width: number, height: number);
+    static create(format: number, width: number, height: number): ImageSurface;
+    static createFromPNG(filename: string): ImageSurface;
+    getWidth(): number;
+    getHeight(): number;
+    getStride(): number;
+    getFormat(): number;
+    /** Raw pixel buffer as a fresh Uint8Array copy (length = stride * height). */
+    getData(): Uint8Array;
 }
 
 /** cairo pattern base class (`cairo_pattern_t`). */
 export class Pattern {
-  getType(): number;
-  status(): number;
-  $dispose(): void;
+    getType(): number;
+    status(): number;
+    $dispose(): void;
 }
 
 /** solid-color pattern. */
 export class SolidPattern extends Pattern {
-  static createRGB(red: number, green: number, blue: number): SolidPattern;
-  static createRGBA(red: number, green: number, blue: number, alpha: number): SolidPattern;
+    static createRGB(red: number, green: number, blue: number): SolidPattern;
+    static createRGBA(red: number, green: number, blue: number, alpha: number): SolidPattern;
 }
 
 /** gradient base class — shared color-stop API. */
 export class Gradient extends Pattern {
-  addColorStopRGB(offset: number, red: number, green: number, blue: number): void;
-  addColorStopRGBA(offset: number, red: number, green: number, blue: number, alpha: number): void;
+    addColorStopRGB(offset: number, red: number, green: number, blue: number): void;
+    addColorStopRGBA(offset: number, red: number, green: number, blue: number, alpha: number): void;
 }
 
 /** linear gradient (`cairo_pattern_create_linear`). */
 export class LinearGradient extends Gradient {
-  constructor(x0: number, y0: number, x1: number, y1: number);
+    constructor(x0: number, y0: number, x1: number, y1: number);
 }
 
 /** radial gradient (`cairo_pattern_create_radial`). */
 export class RadialGradient extends Gradient {
-  constructor(cx0: number, cy0: number, radius0: number, cx1: number, cy1: number, radius1: number);
+    constructor(cx0: number, cy0: number, radius0: number, cx1: number, cy1: number, radius1: number);
 }
 
 /** surface-backed pattern (`cairo_pattern_create_for_surface`). */
 export class SurfacePattern extends Pattern {
-  constructor(surface: Surface);
-  setExtend(extend: number): void;
-  getExtend(): number;
-  setFilter(filter: number): void;
-  getFilter(): number;
+    constructor(surface: Surface);
+    setExtend(extend: number): void;
+    getExtend(): number;
+    setFilter(filter: number): void;
+    getFilter(): number;
 }
 
 /**
@@ -159,29 +159,29 @@ export class Path {}
 
 /** The GJS `cairo` module object (`import cairo from 'cairo'`). */
 declare const cairo: {
-  Antialias: CairoEnum;
-  Content: CairoEnum;
-  Extend: CairoEnum;
-  FillRule: CairoEnum;
-  Filter: CairoEnum;
-  FontSlant: CairoEnum;
-  FontWeight: CairoEnum;
-  Format: CairoEnum;
-  LineCap: CairoEnum;
-  LineJoin: CairoEnum;
-  Operator: CairoEnum;
-  PatternType: CairoEnum;
-  SurfaceType: CairoEnum;
-  Context: typeof Context;
-  Surface: typeof Surface;
-  ImageSurface: typeof ImageSurface;
-  Pattern: typeof Pattern;
-  SolidPattern: typeof SolidPattern;
-  Gradient: typeof Gradient;
-  LinearGradient: typeof LinearGradient;
-  RadialGradient: typeof RadialGradient;
-  SurfacePattern: typeof SurfacePattern;
-  Path: typeof Path;
+    Antialias: CairoEnum;
+    Content: CairoEnum;
+    Extend: CairoEnum;
+    FillRule: CairoEnum;
+    Filter: CairoEnum;
+    FontSlant: CairoEnum;
+    FontWeight: CairoEnum;
+    Format: CairoEnum;
+    LineCap: CairoEnum;
+    LineJoin: CairoEnum;
+    Operator: CairoEnum;
+    PatternType: CairoEnum;
+    SurfaceType: CairoEnum;
+    Context: typeof Context;
+    Surface: typeof Surface;
+    ImageSurface: typeof ImageSurface;
+    Pattern: typeof Pattern;
+    SolidPattern: typeof SolidPattern;
+    Gradient: typeof Gradient;
+    LinearGradient: typeof LinearGradient;
+    RadialGradient: typeof RadialGradient;
+    SurfacePattern: typeof SurfacePattern;
+    Path: typeof Path;
 };
 
 export default cairo;