@gjsify/node-gi 0.59.1 → 0.61.0

package/gi.d.ts

@@ -138,6 +138,16 @@ export interface GObjectNamespace extends GiNamespace {
      */
     registerClass(klass: Function): Function;
     registerClass(meta: RegisterClassMeta, klass: Function): Function;
+    /**
+     * Static-field key for {@link RegisterClassMeta.GTypeName} — gjs's meta FIELD form,
+     * `Klass[GObject.GTypeName] = 'X'` instead of a meta object. A meta object passed to
+     * `registerClass` still wins over the field.
+     */
+    GTypeName: symbol;
+    /** Static-field key for {@link RegisterClassMeta.Properties} (the field form of the meta). */
+    properties: symbol;
+    /** Static-field key for {@link RegisterClassMeta.Signals} (the field form of the meta). */
+    signals: symbol;
     ParamSpec: ParamSpecFactories;
     /**
      * The FULL introspected `GParamFlags` bitfield (READABLE/WRITABLE/READWRITE/

package/gi.js

@@ -809,6 +809,12 @@ function handlerIdsForFunc(handle, fn) {
 // routing keys on the leaf so construction is correct at any depth.
 const registeredClasses = new Map();
 
+// A registered class's prototype → the kebab names of the CUSTOM GObject properties
+// it declared, plus every registered ancestor's. Keyed by the prototype because that
+// is what an instance carries (USER_PROTO), and the set trap is the only consumer:
+// see the equal-value guard in wrapInstance.
+const customPropertiesByProto = new WeakMap();
+
 // GTypeName → registered JS class, the reverse of registeredClasses. The engine's
 // NodeGiConstructor hands runCtorForCObject (below) the C-created instance's GType
 // NAME (g_type_name), which this resolves back to the class to Reflect.construct.
@@ -1309,6 +1315,33 @@ function wrapInstance(handle, userProto) {
     const target = { [HANDLE]: handle };
     const proto = userProto ?? protoForInstance(handle);
     if (proto !== undefined) linkInstanceProto(target, proto);
+    // Which CUSTOM properties of this instance have a value yet — the thing GJS's
+    // generated accessors track with the PRESENCE of their private field, and what its
+    // setter's equal-value guard actually compares against (`value !== this[privateName]`,
+    // refs/gjs/modules/core/_common.js). Not the ParamSpec default: on gjs 1.88.1 a fresh
+    // object's `o.p = <default>` DOES notify (the field holds `undefined`), while the same
+    // assignment after a READ does not — the getter installs the default into the field
+    // first (`if (!(privateName in this)) this[privateName] = defaultValue`) — and nor
+    // does it after `new K({p: <default>})`, since the construct value went through the
+    // setter. Three behaviours, one state: has the value been materialised.
+    //
+    // Seeded lazily from what the ENGINE has stored (`storedPropertyNames` — construct
+    // values included), then extended by every read and write through this wrapper. A set
+    // from C on a property no JS code has touched is the one gap, and it falls back to
+    // notifying — what node-gi did before the guard existed. Same for an addon too old to
+    // export storedPropertyNames (the cross-version pairing of the shipped-closure legs,
+    // see runJsPropertySetter): the guard then only narrows, never widens.
+    let materialised;
+    const materialise = (name) => {
+        if (materialised === undefined) {
+            materialised = new Set(
+                typeof native.storedPropertyNames === 'function' ? native.storedPropertyNames(handle) : [],
+            );
+        }
+        const had = materialised.has(name);
+        materialised.add(name);
+        return had;
+    };
     const proxy = new Proxy(target, {
         get(t, prop) {
             if (prop === HANDLE) return handle;
@@ -1400,6 +1433,14 @@ function wrapInstance(handle, userProto) {
             if (shim !== undefined) return (...args) => shim(handle, args);
             const propName = toKebab(prop);
             if (native.hasProperty(handle, propName)) {
+                // A READ materialises a custom property's value, exactly as GJS's generated
+                // getter writes the default into its private field on first look-up — which
+                // is what makes a LATER assignment of that same default silent. See the
+                // equal-value guard in the set trap.
+                const up = t[USER_PROTO];
+                if (up !== undefined && customPropertiesByProto.get(up)?.has(propName) === true) {
+                    materialise(propName);
+                }
                 return wrapReturn(native.getProperty(handle, propName));
             }
             // LAST resort before treating an unknown name as a GI method: an INHERITED
@@ -1444,6 +1485,29 @@ function wrapInstance(handle, userProto) {
                 }
                 const propName = toKebab(prop);
                 if (native.hasProperty(handle, propName)) {
+                    // Equal-value guard, GJS's `_generateAccessors` setter verbatim:
+                    // `if (value !== this[privateName]) { …; this.notify(name) }`
+                    // (refs/gjs/modules/core/_common.js). GJS puts it in the accessor it
+                    // GENERATES for a declared property, so it covers exactly the custom
+                    // properties with no accessor of the class's own — the branch above
+                    // already took every class-declared accessor, and `set_property`
+                    // bypasses the accessor and so keeps notifying unconditionally on both
+                    // runtimes (measured on gjs 1.88.1: assignment [1,1,2], set_property
+                    // [1,2,3]). node-gi installs no generated accessors (the engine store
+                    // IS the backing store, see findPropertySetter), so without this the
+                    // store's unconditional g_object_notify_by_pspec made every assignment
+                    // notify — [1,2,3] where gjs gives [1,1,2], and the three spellings of
+                    // a dashed name notified once EACH instead of sharing one.
+                    //
+                    // Only once the value is MATERIALISED (see `materialise`): an unset
+                    // property's private field is `undefined` on gjs, never the ParamSpec
+                    // default, so the first assignment notifies even when it equals the
+                    // default. The dash spelling is the key, since toKebab canonicalises
+                    // all three spellings onto it.
+                    const custom = up !== undefined && customPropertiesByProto.get(up)?.has(propName) === true;
+                    if (custom && materialise(propName)) {
+                        if (wrapReturn(native.getProperty(handle, propName)) === value) return true;
+                    }
                     native.setProperty(handle, propName, unwrapArg(value));
                     return true;
                 }
@@ -1695,10 +1759,17 @@ function makeClass(namespace, typeName) {
                     handle = native.constructType(reg.typeHandle, props ? unwrapProps(props) : {});
                 }
                 const instance = wrapInstance(handle, nt.prototype);
-                assignTemplateChildren(instance, handle, reg);
                 // Route construct-time property values through the class's JS setters now
                 // that USER_PROTO is attached — before the user ctor body runs (GJS order).
+                //
+                // BEFORE the template children, because that is the order GJS produces: a
+                // construct property's setter runs inside g_object_new, where the template
+                // is not yet built, so it sees `this._child === undefined`; the children
+                // appear only once construction returns. Binding them first made a setter
+                // observe a child GJS cannot have handed it yet, so a class that guards on
+                // `if (this._child)` took the wrong branch on node-gi and only on node-gi.
                 flushPropertiesToJsSetters(instance, handle, reg);
+                assignTemplateChildren(instance, handle, reg);
                 return instance;
             }
             // `nt` is a subclass of this introspected GObject class but was NEVER passed to
@@ -2349,6 +2420,19 @@ function collectVfuncs(klass) {
  * @param {Function} [maybeClass]
  * @returns {Function} the same `klass` (now registered)
  */
+// GJS's meta FIELD form: a class may declare its meta as static symbol fields
+// (`Klass[GObject.GTypeName] = 'X'`) instead of passing a meta object, and GJS treats
+// the symbols as the real source — `registerClass(meta, klass)` only copies meta onto
+// them and reads them back (refs/gjs/modules/core/_common.js). The descriptions match
+// GJS's so a stringified symbol reads the same in both runtimes.
+//
+// GObject.interfaces / GObject.interface requires are deliberately absent: registerClass
+// implements no interfaces in EITHER form yet, and a symbol that is accepted and then
+// ignored promises more than the object form delivers.
+const GTypeNameSymbol = Symbol('GType name');
+const propertiesSymbol = Symbol('GObject properties');
+const signalsSymbol = Symbol('GObject signals');
+
 function registerClass(metaOrClass, maybeClass) {
     let meta;
     let klass;
@@ -2363,6 +2447,17 @@ function registerClass(metaOrClass, maybeClass) {
         throw new TypeError('GObject.registerClass: expected a class to register');
     }
 
+    // Fold in whatever the class declared as symbol fields, with the meta OBJECT winning
+    // — the same precedence GJS gets from copying meta onto the symbols before reading
+    // them. Until the symbols existed on the namespace, `{[G.GTypeName]: 'X'}` wrote a
+    // literal "undefined" key and the whole declaration vanished without a word: the
+    // GTypeName fell back to the class name and the signals were never registered.
+    const fieldMeta = {};
+    if (klass[GTypeNameSymbol] !== undefined) fieldMeta.GTypeName = klass[GTypeNameSymbol];
+    if (klass[propertiesSymbol] !== undefined) fieldMeta.Properties = klass[propertiesSymbol];
+    if (klass[signalsSymbol] !== undefined) fieldMeta.Signals = klass[signalsSymbol];
+    meta = { ...fieldMeta, ...meta };
+
     const parent = findParentGType(klass);
     if (parent === undefined) {
         throw new TypeError(
@@ -2456,6 +2551,18 @@ function registerClass(metaOrClass, maybeClass) {
         internalChildren: internalChildren.length > 0 ? internalChildren : undefined,
         constructPropertyNames: constructPropertyNames.length > 0 ? constructPropertyNames : undefined,
     });
+    // Which properties the equal-value guard owns: the ones DECLARED here, union the
+    // registered parent's (a G2 subclass inherits its parent's custom properties and
+    // the guard must follow them down). Introspected properties are deliberately
+    // absent — their C setter decides whether an equal value notifies, and guarding
+    // them here would answer for it.
+    const inheritedCustom = registeredClasses.get(Object.getPrototypeOf(klass))?.customProperties;
+    const customProperties = new Set(inheritedCustom);
+    for (const p of properties) {
+        if (typeof p.name === 'string') customProperties.add(p.name);
+    }
+    registeredClasses.get(klass).customProperties = customProperties;
+    customPropertiesByProto.set(klass.prototype, customProperties);
     // Reverse index for runCtorForCObject: the engine identifies a C-created instance
     // by its GType name (= gtypeName, what native.registerClass registered).
     classesByGType.set(gtypeName, klass);
@@ -2551,6 +2658,9 @@ function signalEmitByName(object, ...nameAndArgs) {
 // makeClass). Merged enums are cached so identity is stable.
 const OVERLAY_NAMES = new Set([
     'registerClass',
+    'GTypeName',
+    'properties',
+    'signals',
     'ParamSpec',
     'ParamFlags',
     'SignalFlags',
@@ -2617,6 +2727,9 @@ function decorateGObjectNamespace(baseNs) {
         if (cache.has(prop)) return cache.get(prop);
         let value;
         if (prop === 'registerClass') value = registerClass;
+        else if (prop === 'GTypeName') value = GTypeNameSymbol;
+        else if (prop === 'properties') value = propertiesSymbol;
+        else if (prop === 'signals') value = signalsSymbol;
         else if (prop === 'ParamSpec') value = ParamSpec;
         else if (prop === 'ParamFlags') value = mergeFlags(baseNs.ParamFlags, ParamFlags);
         else if (prop === 'SignalFlags') value = mergeFlags(baseNs.SignalFlags, SignalFlags);

package/host.nativescript.js

@@ -157,18 +157,74 @@ function configureEnvironment() {
     setNativeEnv('XDG_RUNTIME_DIR', `${appDir}/.run`);
 }
 
+/**
+ * The names under which NativeScript's own module loader can be reached from the GLOBAL scope,
+ * in the order a bundle may offer them. `system_lib://` is the runtime's scheme, so whichever
+ * of these answers, it is the same loader underneath.
+ *
+ *   * `require` — the loader the runtime installs globally. A CommonJS bundle also has a
+ *     module-scoped `require`, but that one is the BUNDLER's; reading the global by name is
+ *     what keeps the two apart, and it is why this list is read off a scope object rather
+ *     than written as bare identifiers.
+ *   * `__nativeRequire` — the same loader under the name the runtime uses internally
+ *     (measured in @nativescript/android 9.1's libNativeScript.so, beside `ns:module`'s
+ *     `createRequire`). It is the fallback for a runtime that stops exposing `require`
+ *     globally, which an ESM-only bundle would otherwise have no way to reach.
+ */
+const RUNTIME_REQUIRE_GLOBALS = ['require', '__nativeRequire'];
+
+/**
+ * Pick the function that can load `system_lib://libnode_gi.so`.
+ *
+ * WHY THIS IS A CHAIN AND NOT webpack's ONE NAME. `__non_webpack_require__` only exists
+ * because webpack REWRITES that free identifier to the runtime's require; under
+ * @nativescript/vite (Rolldown, ESM output) nothing rewrites it, so the old single check made
+ * every non-webpack NativeScript bundle fail at the first `requireGi` with a message telling
+ * the app to switch bundlers — which is not a fix available to a vite app.
+ *
+ * ORDER MATTERS. webpack's rewrite wins first: in a webpack bundle the module-scoped `require`
+ * is webpack's own and would resolve `system_lib://…` against the bundle graph instead of the
+ * runtime. Only after that do the runtime's global names get a turn.
+ *
+ * Pure on purpose — `scope` is an argument so the chain is testable without a device
+ * (`test/host-nativescript.test.mjs`).
+ *
+ * @param {Record<string, unknown>} scope the global object to read the runtime names off
+ * @param {unknown} webpackRequire webpack's rewritten `__non_webpack_require__`, if any
+ * @returns {{ load: ((id: string) => any) | null, via: string | null }}
+ */
+export function resolveNativeRequire(scope, webpackRequire) {
+    if (typeof webpackRequire === 'function') {
+        return { load: /** @type {(id: string) => any} */ (webpackRequire), via: '__non_webpack_require__' };
+    }
+    for (const name of RUNTIME_REQUIRE_GLOBALS) {
+        const candidate = scope?.[name];
+        if (typeof candidate === 'function') {
+            return { load: /** @type {(id: string) => any} */ (candidate), via: name };
+        }
+    }
+    return { load: null, via: null };
+}
+
 /**
  * Load the addon from the APK's native libs and point GI at the app's typelibs.
  * @returns {Record<string, any>} the native engine
  */
 export function loadNativeHost() {
     configureEnvironment();
-    // webpack rewrites __non_webpack_require__ to the runtime's own `require`.
-    const load = typeof __non_webpack_require__ === 'function' ? __non_webpack_require__ : null;
+    // The bare identifier is what webpack rewrites; everything else is read off the global
+    // scope inside resolveNativeRequire.
+    const { load } = resolveNativeRequire(
+        globalThis,
+        typeof __non_webpack_require__ === 'function' ? __non_webpack_require__ : undefined,
+    );
     if (load === null) {
         throw new Error(
-            '@gjsify/node-gi: the NativeScript host needs __non_webpack_require__ ' +
-                '(bundle with @nativescript/webpack, which adds the `nativescript` resolve condition).',
+            '@gjsify/node-gi: the NativeScript host found no module loader to pass ' +
+                "'system_lib://libnode_gi.so' to. It looked for __non_webpack_require__ (webpack " +
+                `rewrites it) and then for ${RUNTIME_REQUIRE_GLOBALS.map((n) => `globalThis.${n}`).join(' and ')}` +
+                " — the names NativeScript's own loader answers to. None of them is a function, which " +
+                'means this is not a NativeScript runtime, or its loader moved.',
         );
     }
     const native = load('system_lib://libnode_gi.so');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.59.1",
+  "version": "0.61.0",
   "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/marshal.cc

@@ -605,6 +605,40 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
         out->v_string = const_cast<char*>(heldString->c_str());
       }
       return true;
+    case GI_TYPE_TAG_VOID:
+      // A bare `gpointer` IN argument: the `user_data` of the log handlers
+      // (`GLib.log_default_handler(domain, level, message, null)`), of
+      // `g_log_writer_default`, and of every introspected function that takes a
+      // closure's data separately. There is nothing to marshal INTO a void* from
+      // JS, so gjs installs Arg::NullIn for this tag (refs/gjs/gi/arg-cache.cpp
+      // ArgsCache::build_normal_in_arg) — it writes NULL and ignores the value
+      // entirely. Without this arm the whole CALL failed with "Unsupported IN
+      // argument type tag 0", which is how `GLib.log_default_handler` — the only
+      // introspectable way to make GLib write to fd 1/2, and so the only way to
+      // SEE the Android stdout/stderr redirect from JS — was unreachable.
+      //
+      // Deliberate divergence: a value that is not null/undefined is REFUSED here
+      // where gjs drops it silently. node-gi cannot turn a JS value into a
+      // gpointer, and a caller that passes one meant it to arrive; swallowing it
+      // hides the mistake at the only place that can still name the argument.
+      // (The nullability of the arg is not known at this level — JsToGIArgument
+      // sees the GITypeInfo, not the GIArgInfo — so a non-nullable void* gets
+      // NULL instead of gjs's "argument may not be null". In the introspected API
+      // such an argument is `allow-none` throughout.)
+      if (!gi_type_info_is_pointer(type)) return true;  // plain `void`: no slot to fill
+      if (v.IsNull() || v.IsUndefined()) {
+        out->v_pointer = nullptr;
+        return true;
+      }
+      {
+        std::string msg = std::string("Expected null for pointer ") +
+                          (argName != nullptr ? std::string("argument '") + argName + "'"
+                                              : std::string("argument")) +
+                          " but got type " + InformalValueTypeName(v) +
+                          " (node-gi cannot marshal a JS value into a gpointer)";
+        Napi::TypeError::New(env, msg).ThrowAsJavaScriptException();
+      }
+      return false;
     case GI_TYPE_TAG_INTERFACE: {
       // Object/interface instances arrive as opaque External<GObject> handles;
       // enums/flags as plain numbers. Other interface kinds (structs/unions/

package/src/signals.cc

@@ -270,6 +270,19 @@ Napi::Value EmitSignal(const Napi::CallbackInfo& info) {
   g_signal_query(sigid, &query);
 
   guint n = query.n_params;
+  // ARITY, gjs's message verbatim ("Signal 'changed' on ArSig requires 2 args got 1",
+  // measured on gjs 1.88.1 — which rejects too MANY as well as too few). Without it a
+  // missing argument was marshalled from `undefined`: a signal declared (string, int)
+  // and emitted with one argument reached its handlers with a silent "" / 0 in the
+  // gap, so the caller's mistake surfaced as wrong data somewhere downstream instead
+  // of as a throw at the emit.
+  if (args.Length() != n) {
+    Napi::Error::New(env, std::string("Signal '") + name + "' on " + G_OBJECT_TYPE_NAME(obj) +
+                              " requires " + std::to_string(n) + " args got " +
+                              std::to_string(args.Length()))
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
   std::vector<GValue> params(n + 1);  // [0] = instance
   g_value_init(&params[0], gtype);
   g_value_set_object(&params[0], obj);
@@ -279,7 +292,7 @@ Napi::Value EmitSignal(const Napi::CallbackInfo& info) {
     GType pt = query.param_types[i] & ~G_SIGNAL_TYPE_STATIC_SCOPE;
     g_value_init(&params[i + 1], pt);
     initialised = i + 2;
-    Napi::Value v = i < args.Length() ? args.Get(i) : env.Undefined();
+    Napi::Value v = args.Get(i);
     // An EMPTY v is the residue of a swallowed args.Get() failure (terminating
     // env / throwing getter): JsToGValue's coercions on it would abort via
     // Error::New(nullptr)'s fatal sites — bail before marshalling.