@gjsify/node-gi 0.22.0 → 0.24.1

package/README.md

@@ -678,6 +678,16 @@ imports.signals.addSignalMethods(emitter);      // the pure-JS Signals mixin
 emitter.connect('ready', () => imports.mainloop.quit());
 imports.mainloop.timeout_add(50, () => { emitter.emit('ready'); return false; });
 imports.mainloop.run();                          // thin GLib.MainLoop wrapper
+
+// imports.byteArray — the legacy byte-array module, with GJS semantics
+// (fromString/toString are zero-terminated + fatal-decode; fromGBytes/toGBytes
+// round-trip GLib.Bytes; fromArray wraps in the legacy ByteArray class). This
+// is the seam @gjsify/utils' cli()/gbytesToUint8Array — and through them
+// @gjsify/os + @gjsify/child_process — read GLib subprocess output with:
+const [ok, out] = imports.gi.GLib.spawn_command_line_sync('echo hi');
+console.log(imports.byteArray.toString(out));    // 'hi\n'
+const bytes = imports.byteArray.toGBytes(Uint8Array.of(1, 2, 3));
+imports.byteArray.fromGBytes(bytes);             // Uint8Array [1, 2, 3] (a copy)
 ```
 
 A follow-up `--app node` build step will inject this automatically for any

package/gi.d.ts

@@ -93,7 +93,7 @@ export interface GObjectNamespace extends GiNamespace {
   ParamSpec: ParamSpecFactories;
   /**
    * The FULL introspected `GParamFlags` bitfield (READABLE/WRITABLE/READWRITE/
-   * CONSTRUCT/CONSTRUCT_ONLY/LAX_VALIDATION/STATIC_*/EXPLICIT_NOTIFY/DEPRECATED/
+   * CONSTRUCT/CONSTRUCT_ONLY/LAX_VALIDATION/STATIC_.../EXPLICIT_NOTIFY/DEPRECATED/
    * …) — the named members below are the common convenience bits; the index
    * signature covers the remaining introspected members.
    */

package/gi.js

@@ -985,7 +985,10 @@ let pumpRefCount = 0;
  * @returns {() => void}
  */
 export function startMainContextPump() {
-  if (native.isNodeRuntime) return () => {};
+  // Node: the libuv↔GLib bridge already co-pumps. GJS: the host loop IS
+  // GLib's default main context — a JS-timer pump would only iterate the
+  // context recursively from within its own dispatch.
+  if (native.isNodeRuntime || native.RUNTIME === 'gjs') return () => {};
   pumpRefCount++;
   if (pumpTimer === null) {
     // ~4 ms cadence: low latency without busy-spinning. Each tick drains every
@@ -1011,7 +1014,7 @@ export function startMainContextPump() {
 
 /** Decrement the main-context pump reference count; clears the timer at zero. */
 export function stopMainContextPump() {
-  if (native.isNodeRuntime || pumpRefCount === 0) return;
+  if (native.isNodeRuntime || native.RUNTIME === 'gjs' || pumpRefCount === 0) return;
   pumpRefCount--;
   if (pumpRefCount === 0 && pumpTimer !== null) {
     clearInterval(pumpTimer);

package/globals.d.ts

@@ -15,6 +15,19 @@ export interface GjsImports {
   system: SystemModule;
   /** `imports.gettext` — the `@gjsify/node-gi/gettext` module (no-translation passthrough). */
   gettext: GettextModule;
+  /** `imports.byteArray` — the legacy GJS byte-array module (GJS semantics: zero-terminated, fatal decode). */
+  byteArray: {
+    ByteArray: new (arg?: number | Uint8Array) => {
+      length: number;
+      toString(encoding?: string): string;
+      toGBytes(): unknown;
+    };
+    fromArray(array: Iterable<number>): unknown;
+    fromGBytes(bytes: unknown): Uint8Array;
+    fromString(string: string, encoding?: string): Uint8Array;
+    toGBytes(array: Uint8Array): unknown;
+    toString(byteArray: Uint8Array, encoding?: string): string;
+  };
   versions: Record<string, unknown>;
 }
 

package/globals.js

@@ -22,6 +22,7 @@ import cairo from './cairo.js';
 // Legacy `imports.signals` (the pure-JS Signals mixin) + `imports.mainloop` (the
 // GLib.MainLoop convenience layer) — the GJS script modules many older sources use.
 import * as signalsModule from './overrides/_signals.js';
+import { createByteArray } from './overrides/byte-array.js';
 import { createMainloop } from './overrides/mainloop.js';
 import { createPackage } from './overrides/package.js';
 
@@ -109,6 +110,11 @@ function makeImports() {
     system,
     gettext,
     cairo,
+    // `imports.byteArray` — the legacy GJS byte-array module
+    // (fromGBytes/toGBytes/fromString/toString/fromArray/ByteArray), the seam
+    // `@gjsify/utils`' gbytesToUint8Array/cli() read subprocess output through.
+    // GLib is only pulled in lazily (toGBytes), so seeding it here is free.
+    byteArray: createByteArray(requireGi),
     signals: { addSignalMethods, _connect, _connectAfter, _disconnect, _emit, _signalHandlerIsConnected, _disconnectAll },
     // GJS's `imports.searchPath` — `imports.package.init` unshifts the app's
     // moduledir onto it. Inert on node-gi (ESM + gi://), but present + safe so

package/index.js

@@ -49,19 +49,25 @@ const require = createRequire(import.meta.url);
 const here = dirname(fileURLToPath(import.meta.url)); // package root
 
 /**
- * Which JS runtime we are on. The Node-API addon loads on all three, but the
+ * Which JS runtime we are on. The Node-API addon loads on all four: Node, Bun
+ * and Deno implement Node-API natively; under GJS the `@gjsify/napi` shim is
+ * the N-API host and the addon is loaded through it (`loadNative` below). The
  * libuv-backed main-loop bridge (startMainLoop) is Node-only — Deno exports no
  * libuv symbols and Bun panics on uv_backend_fd — so Bun/Deno use the portable
- * GLib-iteration pump instead (see gi.js). Detection order matters: Bun and Deno
- * both expose a `process` shim, so probe their own globals first.
- * @type {'bun' | 'deno' | 'node'}
+ * GLib-iteration pump instead (see gi.js), and GJS needs NEITHER: the host
+ * loop already IS GLib's default main context. Detection order matters: GJS is
+ * probed first via its own globals (`imports` + `print` — no other runtime
+ * defines both), then Bun/Deno (both expose a `process` shim), then Node.
+ * @type {'bun' | 'deno' | 'gjs' | 'node'}
  */
 export const RUNTIME =
-  typeof globalThis.Bun !== 'undefined'
-    ? 'bun'
-    : typeof globalThis.Deno !== 'undefined'
-      ? 'deno'
-      : 'node';
+  typeof globalThis.imports !== 'undefined' && typeof globalThis.print === 'function'
+    ? 'gjs'
+    : typeof globalThis.Bun !== 'undefined'
+      ? 'bun'
+      : typeof globalThis.Deno !== 'undefined'
+        ? 'deno'
+        : 'node';
 
 /** Whether we are on Node.js (the only runtime with the libuv main-loop bridge). */
 export const isNodeRuntime = RUNTIME === 'node';
@@ -84,9 +90,37 @@ function nativeCandidates() {
   return [prebuild, release, debug];
 }
 
+// GJS host mode: the addon is loaded through the @gjsify/napi shim, not
+// `require()`. The loader native is `globalThis.__gjsifyNapiLoadAddon`,
+// installed by `GjsifyNapi.init()`; if another consumer (the @gjsify/napi L1)
+// already captured + deleted it, init() re-defines it (idempotent). The
+// GjsifyNapi typelib must be resolvable (GI_TYPELIB_PATH/LD_LIBRARY_PATH →
+// the shim prebuild).
+function gjsLoadAddon(path) {
+  let load = globalThis.__gjsifyNapiLoadAddon;
+  if (typeof load !== 'function') {
+    const GjsifyNapi = globalThis.imports?.gi?.GjsifyNapi;
+    if (!GjsifyNapi || !GjsifyNapi.init()) {
+      throw new Error(
+        '@gjsify/node-gi: GJS host mode needs the @gjsify/napi shim — the GjsifyNapi ' +
+          'typelib is not loadable (point GI_TYPELIB_PATH and LD_LIBRARY_PATH at its prebuild).',
+      );
+    }
+    load = globalThis.__gjsifyNapiLoadAddon;
+    if (typeof load !== 'function') {
+      throw new Error('@gjsify/node-gi: GjsifyNapi.init() did not install the addon loader.');
+    }
+    // Capture-then-delete, the same no-side-channel discipline as the L1.
+    delete globalThis.__gjsifyNapiLoadAddon;
+  }
+  return load(path);
+}
+
 function loadNative() {
   for (const candidate of nativeCandidates()) {
-    if (existsSync(candidate)) return require(candidate);
+    if (existsSync(candidate)) {
+      return RUNTIME === 'gjs' ? gjsLoadAddon(candidate) : require(candidate);
+    }
   }
   throw new Error(
     `@gjsify/node-gi: native addon not found for ${RUNTIME} on ${process.platform}-${process.arch}. ` +
@@ -94,7 +128,8 @@ function loadNative() {
       'Run `node-gyp rebuild` in ' +
       here +
       ' (requires a C++ toolchain and the girepository-2.0 / glib-2.0 development headers), ' +
-      'or install a package build that ships a prebuild for your platform.',
+      'or install a package build that ships a prebuild for your platform. ' +
+      'Under a bundled GJS app (import.meta anchors at the bundle), set NODE_GI_NATIVE to the addon path.',
   );
 }
 
@@ -133,7 +168,10 @@ try {
 // matching Node's checkpoint and GJS (SpiderMonkey drains the promise-job queue
 // when the last JS frame exits). Node never registers — its checkpoint already
 // runs natively, so the Node path is byte-identical to before.
-if (!isNodeRuntime) {
+// GJS never registers: SpiderMonkey/GJS drains the promise-job queue from its
+// own main-loop source whenever the last JS frame exits — the exact semantic
+// this checkpoint recreates for Bun/Deno.
+if (!isNodeRuntime && RUNTIME !== 'gjs') {
   try {
     let drain = null;
     if (RUNTIME === 'bun') {

package/overrides/byte-array.js

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: MIT OR LGPL-2.0-or-later
+// SPDX-FileCopyrightText: 2017 Philip Chimento <philip.chimento@gmail.com>
+//
+// Adapted from GJS (refs/gjs/modules/script/byteArray.js + the native
+// refs/gjs/gjs/byteArray.cpp `imports._byteArrayNative` functions). Copyright
+// (c) 2017 Philip Chimento. MIT OR LGPL-2.0-or-later.
+// Modifications: the legacy `imports.byteArray` module ported to
+// @gjsify/node-gi. The native `fromGBytes`/`fromString`/`toString` are
+// reimplemented in JS over the engine's boxed-GBytes surface and
+// TextEncoder/TextDecoder, preserving GJS semantics:
+//   - toString/fromString are ZERO-TERMINATED (data truncates at the first NUL
+//     byte — gjs/text-encoding.cpp `zero_terminated_length`), and decoding is
+//     FATAL (invalid sequences throw a TypeError, like gjs's fatal=true).
+//   - fromGBytes/fromString return a COPY as a plain Uint8Array carrying the
+//     legacy own `toString(encoding)` method gjs tacks on
+//     (`define_legacy_tostring`), minus gjs's once-per-callsite deprecation
+//     warning (stderr-only noise a byte-golden never sees).
+//   - toGBytes routes through `new GLib.Bytes(array)` exactly as the gjs
+//     script module does; GLib is loaded lazily so building `imports` never
+//     pulls the namespace in.
+
+// Truncate a byte array at the first NUL, per gjs's ZERO_TERMINATED handling
+// (gjs/text-encoding.cpp zero_terminated_length).
+function zeroTerminated(u8) {
+  const nul = u8.indexOf(0);
+  return nul === -1 ? u8 : u8.subarray(0, nul);
+}
+
+// gjs routes non-UTF-8 encodings through iconv; Node's TextDecoder (decode
+// side) accepts WHATWG labels which cover the practical iconv set, so decoding
+// just passes the label through. The ENCODE side has no general converter on
+// Node — map the labels gjs consumers actually use onto Buffer encodings and
+// throw a clear error for the rest.
+const ENCODE_LABELS = new Map([
+  ['latin1', 'latin1'],
+  ['iso-8859-1', 'latin1'],
+  ['iso8859-1', 'latin1'],
+  ['ascii', 'ascii'],
+  ['us-ascii', 'ascii'],
+  ['utf-16', 'utf16le'],
+  ['utf-16le', 'utf16le'],
+  ['utf16le', 'utf16le'],
+]);
+
+function isUtf8Label(encoding) {
+  const label = String(encoding).toLowerCase();
+  return label === 'utf-8' || label === 'utf8';
+}
+
+// The legacy own `toString(encoding)` gjs defines on arrays returned by
+// fromString/fromGBytes/fromArray (byteArray.cpp define_legacy_tostring).
+function defineLegacyToString(u8, toString) {
+  Object.defineProperty(u8, 'toString', {
+    value(encoding = 'utf-8') {
+      return toString(u8, encoding);
+    },
+    writable: true,
+    enumerable: false,
+    configurable: true,
+  });
+  return u8;
+}
+
+/**
+ * Build the legacy `imports.byteArray` module bound to the L1 backend.
+ * @param {(ns: string, version?: string) => Record<string, any>} requireGi
+ * @returns {{ ByteArray: any, fromArray: Function, fromGBytes: Function, fromString: Function, toGBytes: Function, toString: Function }}
+ */
+export function createByteArray(requireGi) {
+  /**
+   * @param {Uint8Array} byteArray bytes to decode
+   * @param {string} [encoding] a WHATWG/iconv label, default UTF-8
+   * @returns {string} the decoded string, stopping at the first NUL byte
+   */
+  function toString(byteArray, encoding = 'utf-8') {
+    // Plain Error, not TypeError — gjs raises these argument failures via
+    // gjs_throw (Error); only the GBytes typecheck below is a TypeError.
+    if (!(byteArray instanceof Uint8Array)) throw new Error('Argument to decode() must be a Uint8Array');
+    const data = zeroTerminated(byteArray);
+    if (data.length === 0) return '';
+    // fatal:true mirrors gjs's fatal decode (invalid sequences throw).
+    return new TextDecoder(encoding, { fatal: true }).decode(data);
+  }
+
+  /**
+   * @param {string} string the string to encode
+   * @param {string} [encoding] a WHATWG/iconv label, default UTF-8
+   * @returns {Uint8Array} the encoded bytes, truncated at the first NUL byte
+   */
+  function fromString(string, encoding = 'utf-8') {
+    if (typeof string !== 'string') throw new Error('Argument to fromString() must be a string');
+    let encoded;
+    if (isUtf8Label(encoding)) {
+      encoded = new TextEncoder().encode(string);
+    } else {
+      const bufferEncoding = ENCODE_LABELS.get(String(encoding).toLowerCase());
+      if (!bufferEncoding) throw new Error(`Unsupported encoding for fromString(): ${encoding}`);
+      const buf = Buffer.from(string, bufferEncoding);
+      encoded = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    }
+    const data = zeroTerminated(encoded);
+    // Copy into a fresh plain Uint8Array (gjs returns a standalone buffer, and
+    // Buffer.from may hand out a view into Node's shared slab).
+    const out = new Uint8Array(data.length);
+    out.set(data);
+    return defineLegacyToString(out, toString);
+  }
+
+  /**
+   * @param {any} bytes a GLib.Bytes boxed handle
+   * @returns {Uint8Array} a copy of the bytes as a plain Uint8Array
+   */
+  function fromGBytes(bytes) {
+    // The engine's boxed GBytes proxy carries `toArray()` (gi.js wrapBoxed) —
+    // the same convenience gjs adds to GLib.Bytes.prototype. Its absence means
+    // the value is not a GBytes, matching gjs's G_TYPE_BYTES typecheck throw.
+    if (!bytes || typeof bytes.toArray !== 'function') {
+      throw new TypeError('Argument to fromGBytes() must be a GLib.Bytes');
+    }
+    const data = bytes.toArray();
+    // toArray() already returns a copy of the GBytes data; re-view it as a
+    // PLAIN Uint8Array (gjs returns Uint8Array, not Node's Buffer subclass).
+    const out = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    return defineLegacyToString(out, toString);
+  }
+
+  /**
+   * @param {Uint8Array} array the Uint8Array to convert to GLib.Bytes
+   * @returns {any} a GLib.Bytes boxed handle
+   */
+  function toGBytes(array) {
+    if (!(array instanceof Uint8Array)) throw new Error('Argument to ByteArray.toGBytes() must be a Uint8Array');
+    const GLib = requireGi('GLib', '2.0');
+    return new GLib.Bytes(array);
+  }
+
+  // The legacy ByteArray wrapper class, ported verbatim from
+  // refs/gjs/modules/script/byteArray.js (backwards compatibility only).
+  const ByteArray = class ByteArray {
+    constructor(arg = 0) {
+      if (arg instanceof Uint8Array) this._array = arg;
+      else this._array = new Uint8Array(arg);
+      return new Proxy(this, ByteArray);
+    }
+
+    static get(target, prop, receiver) {
+      if (!Number.isNaN(Number.parseInt(prop))) return Reflect.get(target._array, prop);
+      return Reflect.get(target, prop, receiver);
+    }
+
+    static set(target, prop, val, receiver) {
+      const ix = Number.parseInt(prop);
+      if (!Number.isNaN(ix)) {
+        if (ix >= target._array.length) {
+          const newArray = new Uint8Array(ix + 1);
+          newArray.set(target._array);
+          target._array = newArray;
+        }
+        return Reflect.set(target._array, prop, val);
+      }
+      return Reflect.set(target, prop, val, receiver);
+    }
+
+    get length() {
+      return this._array.length;
+    }
+
+    set length(newLength) {
+      if (newLength === this._array.length) return;
+      if (newLength < this._array.length) {
+        this._array = new Uint8Array(this._array.buffer, 0, newLength);
+        return;
+      }
+      const newArray = new Uint8Array(newLength);
+      newArray.set(this._array);
+      this._array = newArray;
+    }
+
+    toString(encoding = 'UTF-8') {
+      return toString(this._array, encoding);
+    }
+
+    toGBytes() {
+      return toGBytes(this._array);
+    }
+  };
+
+  /**
+   * @param {Iterable<number>} array an iterable to convert into a ByteArray wrapper
+   * @returns {InstanceType<ByteArray>}
+   */
+  function fromArray(array) {
+    return new ByteArray(Uint8Array.from(array));
+  }
+
+  return { ByteArray, fromArray, fromGBytes, fromString, toGBytes, toString };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.22.0",
+  "version": "0.24.1",
   "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",
@@ -58,6 +58,12 @@
     "prebuilds"
   ],
   "gjsify": {
+    "platforms": [
+      "linux-x64",
+      "linux-arm64",
+      "darwin-arm64",
+      "win32-x64"
+    ],
     "runtimes": {
       "gjs": "none",
       "node": "polyfill",
@@ -79,6 +85,7 @@
     "test:dbus": "dbus-run-session -- env NODE_GI_NATIVE=build node --test --expose-gc test/dbus.test.mjs test/dbus-async.test.mjs",
     "test:bun": "node scripts/cross-runtime.mjs bun",
     "test:conformance": "node scripts/conformance.mjs",
+    "test:conformance:gjs-napi": "node scripts/conformance.mjs --runtimes=gjs-napi",
     "test:gimarshalling": "node scripts/gimarshalling.mjs",
     "test:deno": "node scripts/cross-runtime.mjs deno",
     "test:cairo": "NODE_GI_NATIVE=build node --test test/cairo.test.mjs",

package/src/marshal.cc

@@ -153,6 +153,43 @@ BoxedHandle* TryGetBoxedHandle(Napi::Value v) {
   return ext.Data();
 }
 
+// The pointer to hand a callee for a boxed/struct IN argument, honouring the
+// arg's TRANSFER annotation.
+//
+// A transfer-full (or -container) IN arg is ADOPTED by the callee: it will free
+// the pointer. Handing over the very block this handle still owns makes both
+// sides free it — the finalizer's g_boxed_free then hits already-released
+// memory (`free(): invalid pointer`, SIGABRT). The canonical case is
+// `GstWebRTC.WebRTCSessionDescription.new(type, sdp)`, whose `sdp` param is
+// `(transfer full)`: the fresh `GstSDPMessage` from
+// `GstSdp.SDPMessage.new_from_text()` (an OUT `(transfer full)`, so our handle
+// owns it) got freed once by `gst_webrtc_session_description_free` and again by
+// its own finalizer.
+//
+// gjs solves this by COPYING on transfer — refs/gjs/gi/wrapperutils.h
+// `GIWrapperBase::transfer_to_gi_argument` (`GI_DIRECTION_IN &&
+// transfer != GI_TRANSFER_NOTHING` → `Instance::copy_ptr`), with
+// refs/gjs/gi/struct.h `StructInstance::copy_ptr` = `g_variant_ref` for
+// GVariant else refs/gjs/gi/boxed.h `BoxedInstance::copy_ptr` = `g_boxed_copy`.
+// Mirror that: the callee owns an independent instance, the handle keeps (and
+// still owns) its own. Transfer-NOTHING is a plain borrow — unchanged.
+//
+// A handle with no copy function (a plain, non-boxed C struct — G_TYPE_INVALID,
+// or a `rawOwned` caller-allocates OUT block) cannot be duplicated. gjs throws
+// there; we instead RELINQUISH ownership so the finalizer stays out of the
+// callee's way — a leak-free hand-over is impossible either way, and not
+// double-freeing is strictly safer than the alternative.
+gpointer TransferBoxedIn(BoxedHandle* h, GITransfer transfer) {
+  if (h == nullptr) return nullptr;
+  if (transfer == GI_TRANSFER_NOTHING || h->ptr == nullptr) return h->ptr;
+  if (h->gtype == G_TYPE_VARIANT) return g_variant_ref(static_cast<GVariant*>(h->ptr));
+  if (h->gtype != G_TYPE_INVALID && G_TYPE_IS_BOXED(h->gtype))
+    return g_boxed_copy(h->gtype, h->ptr);
+  h->owns = false;
+  h->rawOwned = false;
+  return h->ptr;
+}
+
 // Read a boxed handle's pointer if `v` is one (tag-checked; no deref of ptr).
 bool TryGetBoxedPtr(Napi::Value v, gpointer* out) {
   if (!v.IsExternal()) return false;
@@ -440,7 +477,7 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
                     .ThrowAsJavaScriptException();
                 return false;
               }
-              out->v_pointer = h->ptr;
+              out->v_pointer = TransferBoxedIn(h, transfer);
               handled = true;
             }
           }

package/src/object.cc

@@ -258,7 +258,32 @@ Napi::Value GValueToJs(Napi::Env env, const GValue* v) {
       // NOT special-cased here: gjs leaves it as a GLib.Bytes boxed handle
       // (value.cpp has no GBytes case → the generic boxed branch), which is what the
       // MakeBoxedHandle below already produces (verified: a GBytes signal param →
-      // `instanceof GLib.Bytes`). A GStrv-as-array read stays a follow-up.
+      // `instanceof GLib.Bytes`).
+      //
+      // G_TYPE_STRV (a NULL-terminated gchar**, e.g. Gtk.Widget:css-classes,
+      // Gio.ThemedIcon:names, or any Vala `public string[] x { get; }` property —
+      // valac emits g_param_spec_boxed(…, G_TYPE_STRV) for those). This is the READ
+      // half of the pair JsToGValue's GStrv branch opened: without it a GStrv
+      // property fell through to MakeBoxedHandle and JS got an opaque boxed handle
+      // instead of an array — SILENTLY, because a handle is a truthy object whose
+      // `.length` is undefined, so `arr ?? []` keeps it and every index/`for` over it
+      // yields nothing (this is how @gjsify/http lost every request header on the
+      // node-gi bridge: `bridgeReq.header_pairs` became a handle and the pair loop
+      // ran zero times). Mirrors GJS gjs_value_from_g_value_internal
+      // (refs/gjs/gi/value.cpp:1082 `gtype == G_TYPE_STRV` → gjs_array_from_strv).
+      // NULL → an EMPTY ARRAY, not null: GJS explicitly excludes G_TYPE_STRV from its
+      // "pointer-valued NULL → JS null" pre-check (value.cpp:1023) and documents the
+      // choice in gjs_array_from_strv (arg.cpp:2267) — "clients would need to always
+      // check for both an empty array and null" otherwise. g_value_get_boxed BORROWS;
+      // every string is copied into JS, so nothing is owned here.
+      if (G_VALUE_HOLDS(v, G_TYPE_STRV)) {
+        const gchar* const* strv = static_cast<const gchar* const*>(g_value_get_boxed(v));
+        guint len = 0;
+        while (strv != nullptr && strv[len] != nullptr) len++;
+        Napi::Array arr = Napi::Array::New(env, len);
+        for (guint i = 0; i < len; i++) arr.Set(i, Napi::String::New(env, strv[i]));
+        return arr;
+      }
       if (G_VALUE_HOLDS(v, G_TYPE_BYTE_ARRAY)) {
         GByteArray* ba = static_cast<GByteArray*>(g_value_get_boxed(v));
         if (ba == nullptr) return env.Null();

package/system.js

@@ -20,25 +20,61 @@
 // returning the same shape GJS does — they exist so GJS source that calls them
 // keeps running unmodified, not to reproduce SpiderMonkey internals.
 
+// The RUNTIME's own `process`, bound ONCE at module evaluation.
+//
+// `globalThis.process` is NOT a safe source for this module: a GJS program run
+// through the reverse bridge routinely installs the gjsify `@gjsify/process`
+// polyfill over it (`@gjsify/node-globals/register` defines it unconditionally),
+// and that polyfill's `exit()` takes its GJS path whenever `imports.system.exit`
+// exists — i.e. it delegates back into THIS module. Reading `globalThis.process`
+// in `exit()` closes that loop into an infinite, GLib-idle-driven recursion
+// (exit → polyfill → system.exit → polyfill → …) that spins at 100 % CPU and
+// never terminates. `getBuiltinModule('node:process')` (Node ≥ 22.3 / Bun /
+// Deno 2) returns the real builtin regardless of what the global currently is;
+// the module-evaluation capture is the fallback for hosts without it — this
+// module is loaded from `@gjsify/node-gi/globals`, before any bundle body (and
+// therefore before any register side effect) runs.
+const runtimeProcess = (() => {
+  const hostProcess = typeof process !== 'undefined' ? process : undefined;
+  try {
+    const builtin = hostProcess?.getBuiltinModule?.('node:process');
+    if (builtin && typeof builtin.exit === 'function') return builtin;
+  } catch {
+    // getBuiltinModule missing or refusing the specifier — use the captured one.
+  }
+  return hostProcess;
+})();
+
+const runtimeExit = typeof runtimeProcess?.exit === 'function' ? runtimeProcess.exit.bind(runtimeProcess) : undefined;
+
 // `programArgs` mirrors GJS's ARGV: the script arguments, excluding the
 // interpreter (argv[0]) and the script path (argv[1]).
 function readProgramArgs() {
-  return typeof process !== 'undefined' && Array.isArray(process.argv) ? process.argv.slice(2) : [];
+  return Array.isArray(runtimeProcess?.argv) ? runtimeProcess.argv.slice(2) : [];
 }
 
 // `programInvocationName` / `programPath` track the running script — Node's
 // `process.argv[1]`.
 function readProgramInvocationName() {
-  return (typeof process !== 'undefined' && process.argv[1]) || '';
+  return runtimeProcess?.argv?.[1] || '';
 }
 
 function readProgramPath() {
-  return (typeof process !== 'undefined' && process.argv[1]) || null;
+  return runtimeProcess?.argv?.[1] || null;
 }
 
-/** Exit the process (GJS `System.exit`). */
+/**
+ * Exit the process (GJS `System.exit`).
+ *
+ * Terminal by contract: under gjs this is the `exit()` syscall — it never
+ * returns and nothing a program installs can intercept it. The Node/Bun/Deno
+ * equivalent is the RUNTIME's own `process.exit`, resolved above; routing
+ * through `globalThis.process` instead is what produced the never-exiting
+ * reverse-bridge process (see the `runtimeProcess` note and
+ * `conformance/programs/system-exit-lifetime.conf.mjs`).
+ */
 export function exit(code) {
-  if (typeof process !== 'undefined') process.exit(code ?? 0);
+  if (runtimeExit !== undefined) runtimeExit(code ?? 0);
 }
 
 /** Trigger a garbage collection if the host exposed `globalThis.gc` (`--expose-gc`). */