@gjsify/node-gi 0.50.0 → 0.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.50.0",
+  "version": "0.51.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",
@@ -62,6 +62,7 @@
     "binding.gyp",
     "scripts/install.mjs",
     "scripts/win-gi-gyp-flags.mjs",
+    "scripts/mac-intl-gyp-flags.mjs",
     "prebuilds"
   ],
   "gjsify": {
@@ -87,23 +88,23 @@
     "build:prebuild": "node-gyp rebuild && node scripts/stage-prebuild.mjs",
     "rebuild": "node-gyp rebuild",
     "clean": "node-gyp clean",
-    "test": "NODE_GI_NATIVE=build node --test",
-    "test:node": "NODE_GI_NATIVE=build node --test",
-    "test:gc": "NODE_GI_NATIVE=build node --test --expose-gc",
-    "test:dbus": "dbus-run-session --config-file=test/session.conf -- env NODE_GI_NATIVE=build node --test --expose-gc test/dbus.test.mjs test/dbus-async.test.mjs",
+    "test": "LC_ALL=C NODE_GI_NATIVE=build node --test",
+    "test:node": "LC_ALL=C NODE_GI_NATIVE=build node --test",
+    "test:gc": "LC_ALL=C NODE_GI_NATIVE=build node --test --expose-gc",
+    "test:dbus": "dbus-run-session --config-file=test/session.conf -- env LC_ALL=C 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",
-    "test:cairo-canvas2d": "NODE_GI_NATIVE=build node --test test/cairo-canvas2d.test.mjs",
-    "test:gtk": "NODE_GI_NATIVE=build node --test test/gtk-smoke.test.mjs",
-    "test:gtk-cairo": "NODE_GI_NATIVE=build node --test test/cairo-drawfunc.test.mjs",
-    "test:adw": "NODE_GI_NATIVE=build node --test test/adw-smoke.test.mjs",
-    "test:gtk-template": "NODE_GI_NATIVE=build node --test test/gtk-template.test.mjs",
-    "test:gtk-template-callbacks": "NODE_GI_NATIVE=build node --test test/gtk-template-callbacks.test.mjs",
-    "test:gtk-template-signals": "NODE_GI_NATIVE=build node --test test/gtk-template-signals.test.mjs"
+    "test:cairo": "LC_ALL=C NODE_GI_NATIVE=build node --test test/cairo.test.mjs",
+    "test:cairo-canvas2d": "LC_ALL=C NODE_GI_NATIVE=build node --test test/cairo-canvas2d.test.mjs",
+    "test:gtk": "LC_ALL=C NODE_GI_NATIVE=build node --test test/gtk-smoke.test.mjs",
+    "test:gtk-cairo": "LC_ALL=C NODE_GI_NATIVE=build node --test test/cairo-drawfunc.test.mjs",
+    "test:adw": "LC_ALL=C NODE_GI_NATIVE=build node --test test/adw-smoke.test.mjs",
+    "test:gtk-template": "LC_ALL=C NODE_GI_NATIVE=build node --test test/gtk-template.test.mjs",
+    "test:gtk-template-callbacks": "LC_ALL=C NODE_GI_NATIVE=build node --test test/gtk-template-callbacks.test.mjs",
+    "test:gtk-template-signals": "LC_ALL=C NODE_GI_NATIVE=build node --test test/gtk-template-signals.test.mjs"
   },
   "dependencies": {
     "node-addon-api": "^8.0.0"

package/scripts/mac-intl-gyp-flags.mjs

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: MIT
+// Emit the link flags the darwin addon needs for libintl, for binding.gyp's
+// `OS=="mac"` branch.
+//
+//   node scripts/mac-intl-gyp-flags.mjs   -> "-L<dir> -lintl", or nothing
+//
+// WHY ONLY DARWIN. `bindtextdomain` / `textdomain` / `bind_textdomain_codeset` are
+// GNU gettext. glibc absorbs them into libc, so Linux needs no flag at all
+// (`nm -D libc.so.6` lists both as weak symbols); Windows resolves them out of
+// gvsbuild's `intl.dll` through the `--static` pkg-config closure the Windows
+// branch already walks. macOS's libSystem has NO gettext — Homebrew's `gettext`
+// formula supplies `libintl.dylib`, and GLib links it, which is how `g_dgettext`
+// works there. But a Mach-O is two-level-namespaced: the addon must name the
+// library it takes symbols from, so "GLib already loaded it" is not enough at LINK
+// time, only at run time.
+//
+// Emitting NOTHING when no libintl is found is deliberate: the failure then is a
+// named undefined-symbol error at link, which says more than a guessed `-L` that
+// silently points somewhere wrong.
+import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+
+if (process.platform !== 'darwin') process.exit(0);
+
+function brewPrefix() {
+    try {
+        return execFileSync('brew', ['--prefix'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    } catch {
+        // No Homebrew on this host — the fixed paths below still cover the two
+        // standard prefixes, and MacPorts users get the honest link error.
+        return '';
+    }
+}
+
+function pkgConfigLibDirs() {
+    const pkgConfig = process.env.PKG_CONFIG || 'pkg-config';
+    try {
+        const out = execFileSync(pkgConfig, ['--libs-only-L', 'glib-2.0'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return out
+            .split(/\s+/)
+            .filter((t) => t.startsWith('-L'))
+            .map((t) => t.slice(2));
+    } catch {
+        return [];
+    }
+}
+
+// Homebrew symlinks every keg's lib/ into <prefix>/lib, so the gettext keg is
+// reachable from the prefix even though glib's own .pc points at glib's cellar dir.
+const prefix = brewPrefix();
+const candidates = [
+    ...pkgConfigLibDirs(),
+    ...(prefix ? [join(prefix, 'lib')] : []),
+    '/opt/homebrew/lib',
+    '/usr/local/lib',
+];
+
+for (const dir of candidates) {
+    if (existsSync(join(dir, 'libintl.dylib')) || existsSync(join(dir, 'libintl.a'))) {
+        process.stdout.write(`-L${dir} -lintl`);
+        break;
+    }
+}

package/scripts/win-gi-gyp-flags.mjs

@@ -124,9 +124,22 @@ if (mode === '--includes') {
     //   glib/gobject/gio/gmodule-2.0  g_*/GObject/GValue/GSignal/GClosure/Gio
     //   ffi  ffi_call / ffi_closure_alloc (girffi + the vfunc/callback trampolines)
     //   cairo  the native cairo foreign-struct binding (src/cairo.cc)
+    //   intl   bindtextdomain / textdomain / bind_textdomain_codeset (src/private.cc);
+    //          glibc absorbs these into libc so Linux names nothing, but the MSVC CRT
+    //          has no gettext and gvsbuild ships GNU gettext as `intl.dll` — the same
+    //          library GLib itself links for g_dgettext
     // Pango/GdkPixbuf/Graphene are NOT linked — the conformance programs load their
     // typelibs at RUNTIME (girepository dlopens the DLL by soname), not at link time.
-    const DIRECT_LIBS = ['girepository-2.0', 'gio-2.0', 'gobject-2.0', 'gmodule-2.0', 'glib-2.0', 'ffi', 'cairo'];
+    const DIRECT_LIBS = [
+        'girepository-2.0',
+        'gio-2.0',
+        'gobject-2.0',
+        'gmodule-2.0',
+        'glib-2.0',
+        'ffi',
+        'cairo',
+        'intl',
+    ];
     // Locate the import-lib dir: GTK_PREFIX/lib, else pkg-config's -L.
     const searchDirs = [];
     if (process.env.GTK_PREFIX) searchDirs.push(join(process.env.GTK_PREFIX, 'lib'));
@@ -146,10 +159,15 @@ if (mode === '--includes') {
             }
             if (found) break;
         }
+        // gmodule is optional (girepository may pull it internally). `intl` is too,
+        // and for a sharper reason: throwing here BLANKS the whole libraries list, so
+        // a gvsbuild that spells its gettext import lib differently would turn one
+        // missing library into "nothing links at all". Skipping leaves the linker to
+        // name the three undefined gettext symbols, which says what is actually wrong.
+        const OPTIONAL = new Set(['gmodule-2.0', 'intl']);
         if (found) resolved.push(found);
-        else if (name !== 'gmodule-2.0') {
-            // gmodule is optional (girepository may pull it internally); everything
-            // else is required — surface a missing import lib loudly.
+        else if (!OPTIONAL.has(name)) {
+            // Everything else is required — surface a missing import lib loudly.
             throw new Error(`win-gi-gyp-flags: import lib for '${name}' not found under ${searchDirs.join(', ')}`);
         }
     }

package/src/addon.cc

@@ -55,6 +55,15 @@ static void OnEnvShutdown(void* arg) {
 }
 
 static Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  // FIRST, before any GLib call: adopt the locale the environment names, the way
+  // gjs's entry point does (`setlocale(LC_ALL, "")`, refs/gjs/gjs/console.cpp).
+  // This is the seam EVERY node-gi application crosses — `gi://`, `requireGi`, the
+  // globals shim and a bare `import '@gjsify/node-gi'` all load the addon — whereas
+  // the globals module is injected only when a bundle still references the GJS
+  // ambient globals, so a locale set there would miss every program that does not.
+  // Without it the process stays in the C locale, where GNU gettext refuses to
+  // translate; the block in private.cc records what that cost.
+  NodeGiInitProcessLocale();
   // The owner env + its JS/main thread are captured lazily at the first wrap
   // (EnsureDrainAsync) — NOT here, since Init runs once PER env and a per-env
   // overwrite would mis-identify the main thread under worker_threads. The cleanup
@@ -130,12 +139,20 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("setTemplateCallbackResolver",
               Napi::Function::New(env, SetTemplateCallbackResolver));
   exports.Set("setConstructCallback", Napi::Function::New(env, SetConstructCallback));
+  exports.Set("setPropertySetCallback", Napi::Function::New(env, SetPropertySetCallback));
+  exports.Set("storedPropertyNames", Napi::Function::New(env, StoredPropertyNames));
   // GjsPrivate-mirroring helpers (private.cc): the structured-log writer func +
   // the bind_property_full / BindingGroup.bind_full transform trampolines.
   exports.Set("logSetWriterFunc", Napi::Function::New(env, LogSetWriterFunc));
   exports.Set("logSetWriterDefault", Napi::Function::New(env, LogSetWriterDefault));
   exports.Set("bindPropertyFull", Napi::Function::New(env, BindPropertyFull));
   exports.Set("bindingGroupBindFull", Napi::Function::New(env, BindingGroupBindFull));
+  // The libintl half of GjsPrivate: the binders GLib's GIR does not publish, and
+  // the LC_* constants read from this platform's headers.
+  exports.Set("setThreadLocale", Napi::Function::New(env, ApplyThreadLocale));
+  exports.Set("textdomain", Napi::Function::New(env, Textdomain));
+  exports.Set("bindtextdomain", Napi::Function::New(env, Bindtextdomain));
+  exports.Set("localeCategories", Napi::Function::New(env, LocaleCategories));
   // The native cairo binding + foreign-struct registration (the `__cairo` export).
   InitCairo(env, exports);
   return exports;

package/src/calls.cc

@@ -513,6 +513,34 @@ int JsInArgCount(GICallableInfo* callable) {
   return count;
 }
 
+// gjs's Gjs::Function::format_name (refs/gjs/gi/function.cpp:801) — the spelling its
+// argument-count TypeError carries, so a refusal reads identically on both runtimes.
+// Deliberately NOT the `displayName` the other refusals here use: that one names the
+// RUNTIME type the call was made on (`GtkLabel.get_property`), which is the useful
+// thing to say about a marshalling failure but not what gjs prints for arity. gjs
+// names the DECLARING info — `method GObject.Object.get_property` — and consumers
+// byte-compare these.
+static std::string GjsCallableName(GICallableInfo* callable) {
+  GIBaseInfo* base = reinterpret_cast<GIBaseInfo*>(callable);
+  bool isMethod = gi_callable_info_is_method(callable);
+  std::string name = isMethod ? "method " : "function ";
+  const char* ns = gi_base_info_get_namespace(base);
+  if (ns != nullptr) name += ns;
+  name += '.';
+  if (isMethod) {
+    // Borrowed ref — no unref (same contract as the container read below).
+    GIBaseInfo* container = gi_base_info_get_container(base);
+    const char* containerName = container != nullptr ? gi_base_info_get_name(container) : nullptr;
+    if (containerName != nullptr) {
+      name += containerName;
+      name += '.';
+    }
+  }
+  const char* fn = gi_base_info_get_name(base);
+  if (fn != nullptr) name += fn;
+  return name;
+}
+
 static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpointer instance,
                                       Napi::Array args, const std::string& displayName) {
   GICallableInfo* callable = reinterpret_cast<GICallableInfo*>(func);
@@ -574,6 +602,35 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
   std::vector<bool> isLenArg(n_args, false);
   ComputeSkippedArgs(callable, n_args, &skip, &isLenArg);
 
+  // Too FEW arguments is a REFUSAL — gjs does the same at
+  // refs/gjs/gi/function.cpp:891 (JS::CallArgs::reportMoreArgsNeeded). node-gi used
+  // to read a missing argument as `undefined` and marshal THAT, which is not leniency
+  // but a wrong call: on a GValue parameter `undefined` becomes gjs's null guess, a
+  // G_TYPE_POINTER GValue (JsToFreshGValue), so `label.get_property('label')` — one
+  // of the two arguments gjs demands — printed "g_object_get_property: can't retrieve
+  // property 'label' of type 'gchararray' as value of type 'gpointer'" and evaluated
+  // to `undefined`, on stock and custom classes alike, with the set_property twin
+  // mirroring it. Counted off the pre-scan JUST computed rather than by calling
+  // JsInArgCount (which would redo it on every call, on the hottest path in the
+  // binding) — same walk, so what is demanded is by construction what the loop below
+  // consumes, and stays equal to the `Function.length` the method reports. Placed
+  // here, before the marshalling loop: nothing above has taken ownership of anything,
+  // so the early return needs no unwinding. Too MANY stays permitted — gjs only warns
+  // there, through a JS warning reporter node-gi has no equivalent of.
+  int required = 0;
+  for (unsigned int i = 0; i < n_args; i++) {
+    if (skip[i]) continue;
+    if (dirs[i] == GI_DIRECTION_IN || dirs[i] == GI_DIRECTION_INOUT) required++;
+  }
+  if (required > 0 && args.Length() < static_cast<uint32_t>(required)) {
+    Napi::TypeError::New(env, GjsCallableName(callable) + ": At least " +
+                                  std::to_string(required) + " argument" +
+                                  (required == 1 ? "" : "s") + " required, but only " +
+                                  std::to_string(args.Length()) + " passed")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
   // Caller-allocates OUT storage (fixed C array or boxed struct): blob != nullptr
   // marks the arg; boxedGType != 0 selects the boxed copy/free path on read-back.
   std::vector<gpointer> callerAllocBlob(n_args, nullptr);

package/src/class.cc

@@ -299,6 +299,17 @@ static GQuark NodeGiInstancePropsQuark() {
   static GQuark q = g_quark_from_static_string("node-gi-instance-props");
   return q;
 }
+// The ORDER in which this instance's custom properties were first set. A GHashTable
+// has no order, and the construct-time replay is visible output: gjs runs the JS
+// setters in the order g_object_new applied the values (CONSTRUCT properties, then
+// the rest), so replaying in hash order prints the same setters in a different
+// sequence. Recording what actually happened is cheaper than modelling GObject's
+// application order, and it stays right for paths that do not go through
+// g_object_new at all (GtkBuilder, a binding).
+static GQuark NodeGiInstancePropOrderQuark() {
+  static GQuark q = g_quark_from_static_string("node-gi-instance-prop-order");
+  return q;
+}
 
 static void FreeStoredGValue(gpointer p) {
   GValue* v = static_cast<GValue*>(p);
@@ -362,6 +373,72 @@ static void NodeGiGetProperty(GObject* obj, guint prop_id, GValue* value, GParam
   if (cd != nullptr && cd->parentGet != nullptr) cd->parentGet(obj, prop_id, value, pspec);
 }
 
+// Push a just-set custom property through the class's own JS setter, the way gjs's
+// set_property vfunc does (refs/gjs/gi/gobject.cpp gjs_object_set_gproperty →
+// jsobj_set_gproperty → JS_SetProperty on the wrapper).
+//
+// THE GATE IS THE WRAPPER, AND THAT IS THE WHOLE DESIGN — do not replace it with a
+// flag. gjs bails when `priv->wrapper()` is null and so do we, which means a set that
+// lands DURING construction (g_object_new applying construct properties, before
+// node-gi has built the wrapper) has nothing to call into and cannot run a setter
+// early. That is not an accident to tidy up: running a plain READWRITE property's
+// setter at construct time is what crashed Learn6502's SourceView (`selectable` →
+// `_signalHandlers.forEach` against state the ctor body had not created yet). The
+// construct-time values are replayed later, from the base ctor, once the wrapper
+// exists — see gi.js flushPropertiesToJsSetters. A set that lands AFTER construction
+// (GtkBuilder applying a non-construct template property via g_object_set, a
+// property binding, set_property) is the case this branch exists for, and it is the
+// one that left every Learn6502 tutorial code block empty on `--app node`.
+static void MaybeRunJsPropertySetter(NodeGiClassData* cd, GObject* obj, const char* name) {
+  if (cd == nullptr || cd->env == nullptr) return;
+  napi_env env = cd->env;
+  // Never enter JS during GC / env teardown (same gate as the vfunc trampoline and
+  // RunJsConstructorForCObject); the property is already stored either way.
+  if (!NodeGiJsAvailable(env)) return;
+  Napi::Env napiEnv(env);
+  Napi::HandleScope scope(napiEnv);
+  NodeGiPumpJsDispatchScope pumpWindow;
+
+  Napi::Value handle = PeekGObjectHandle(napiEnv, obj);
+  if (handle.IsEmpty()) return;  // construction has not reached the wrap yet
+
+  NodeGiEnvData* d = EnvData(env);
+  napi_value cb = nullptr;
+  if (d == nullptr || d->propertySetCallback == nullptr ||
+      napi_get_reference_value(env, d->propertySetCallback, &cb) != napi_ok || cb == nullptr) {
+    return;  // L1 hasn't registered the callback (nothing to run)
+  }
+  napi_value nameVal = nullptr;
+  napi_create_string_utf8(env, name, NAPI_AUTO_LENGTH, &nameVal);
+  napi_value args[2] = {handle, nameVal};
+  napi_value undef = nullptr;
+  napi_get_undefined(env, &undef);
+  napi_value ret = nullptr;
+  // A plain call, not napi_make_callback: g_object_set may be running inside GTK's
+  // own frame and must not get a microtask checkpoint in the middle of it — the same
+  // reasoning as RunJsConstructorForCObject, and gjs's JS_SetProperty takes no
+  // checkpoint either.
+  if (napi_call_function(env, undef, cb, 2, args, &ret) != napi_ok) {
+    // The setter threw. A pending JS exception must never cross back into GObject
+    // (g_object_set has no way to report one), so fold it into a g_warning — gjs logs
+    // the uncaught exception at the same point (gjs_log_exception_uncaught).
+    napi_value ex = nullptr;
+    if (napi_get_and_clear_last_exception(env, &ex) == napi_ok && ex != nullptr) {
+      napi_value msg = nullptr;
+      std::string detail;
+      if (napi_get_named_property(env, ex, "message", &msg) == napi_ok) {
+        size_t len = 0;
+        if (napi_get_value_string_utf8(env, msg, nullptr, 0, &len) == napi_ok) {
+          detail.resize(len);
+          napi_get_value_string_utf8(env, msg, detail.data(), len + 1, &len);
+        }
+      }
+      g_warning("node-gi: JS setter for %s.%s threw: %s", g_type_name(G_OBJECT_TYPE(obj)), name,
+                detail.empty() ? "(no message)" : detail.c_str());
+    }
+  }
+}
+
 static void NodeGiSetProperty(GObject* obj, guint prop_id, const GValue* value, GParamSpec* pspec) {
   NodeGiClassData* ownerCd =
       static_cast<NodeGiClassData*>(g_type_get_qdata(pspec->owner_type, NodeGiClassDataQuark()));
@@ -372,10 +449,26 @@ static void NodeGiSetProperty(GObject* obj, guint prop_id, const GValue* value,
       g_object_set_qdata_full(obj, NodeGiInstancePropsQuark(), store,
                               reinterpret_cast<GDestroyNotify>(g_hash_table_destroy));
     }
+    // Record first-set order alongside the value (see NodeGiInstancePropOrderQuark).
+    // This is the ONLY writer of either structure, so they cannot drift.
+    if (!g_hash_table_contains(store, pspec->name)) {
+      GPtrArray* order =
+          static_cast<GPtrArray*>(g_object_get_qdata(obj, NodeGiInstancePropOrderQuark()));
+      if (order == nullptr) {
+        order = g_ptr_array_new_with_free_func(g_free);
+        g_object_set_qdata_full(obj, NodeGiInstancePropOrderQuark(), order,
+                                reinterpret_cast<GDestroyNotify>(g_ptr_array_unref));
+      }
+      g_ptr_array_add(order, g_strdup(pspec->name));
+    }
     GValue* copy = g_new0(GValue, 1);
     g_value_init(copy, G_VALUE_TYPE(value));
     g_value_copy(value, copy);
     g_hash_table_replace(store, g_strdup(pspec->name), copy);
+    // Before the notify, so a ::notify handler observes the JS-side state the setter
+    // wrote — GObject emits its own notify after this vfunc returns, which is the
+    // order gjs's handlers see.
+    MaybeRunJsPropertySetter(ownerCd, obj, pspec->name);
     g_object_notify_by_pspec(obj, pspec);
     return;
   }
@@ -1502,4 +1595,46 @@ Napi::Value SetConstructCallback(const Napi::CallbackInfo& info) {
   return env.Undefined();
 }
 
+// setPropertySetCallback(cb) -> void. L1 registers the callback NodeGiSetProperty
+// invokes after storing a custom property: (instanceHandle, propertyName) → run the
+// class's own JS setter (see gi.js runJsPropertySetter). Mirrors
+// setConstructCallback.
+Napi::Value SetPropertySetCallback(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsFunction()) {
+    Napi::TypeError::New(env, "setPropertySetCallback(cb: function)").ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  NodeGiEnvData* d = EnvData(env);
+  if (d == nullptr) return env.Undefined();
+  if (d->propertySetCallback != nullptr) {
+    napi_delete_reference(env, d->propertySetCallback);
+    d->propertySetCallback = nullptr;
+  }
+  napi_create_reference(env, info[0], 1, &d->propertySetCallback);
+  return env.Undefined();
+}
+
+// storedPropertyNames(handle) -> string[]. The custom properties that have actually
+// been SET on this instance, in the order they were first set — which is the only
+// honest record of it, since a property nobody set is absent (NodeGiGetProperty
+// answers such a read from the ParamSpec default instead). The base ctor reads it to
+// replay construct-time sets through the JS setters that did not exist yet, and
+// "actually set" is exactly the discriminator that keeps a declared-but-untouched
+// property's setter from firing early (the SourceView `selectable` crash). Order is
+// part of the contract, not a detail: the replay runs those setters, and gjs runs
+// them in the order g_object_new applied the values.
+Napi::Value StoredPropertyNames(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  GObject* obj = UnwrapGObject(env, info[0]);
+  if (obj == nullptr) return Napi::Array::New(env, 0);
+  GPtrArray* order =
+      static_cast<GPtrArray*>(g_object_get_qdata(obj, NodeGiInstancePropOrderQuark()));
+  if (order == nullptr) return Napi::Array::New(env, 0);
+  Napi::Array out = Napi::Array::New(env, order->len);
+  for (guint i = 0; i < order->len; i++)
+    out.Set(i, Napi::String::New(env, static_cast<const char*>(g_ptr_array_index(order, i))));
+  return out;
+}
+
 }  // namespace nodegi

package/src/common.h

@@ -95,6 +95,12 @@ struct NodeGiEnvData {
   // Reflect.construct(class) in adopt mode (see gi.js runCtorForCObject). Per-env
   // for the same reason as errorBuilder (a napi_ref is env-specific).
   napi_ref constructCallback = nullptr;
+  // L1 callback that pushes a just-set custom GObject property through the class's
+  // own JS setter — invoked by NodeGiSetProperty once the instance HAS a wrapper
+  // (handle, propertyName) → see gi.js runJsPropertySetter. gjs reaches the same
+  // setter from its set_property vfunc (refs/gjs/gi/gobject.cpp jsobj_set_gproperty).
+  // Per-env for the same reason as errorBuilder (a napi_ref is env-specific).
+  napi_ref propertySetCallback = nullptr;
 };
 
 void NodeGiEnvDataFinalize(napi_env env, void* data, void* hint);
@@ -458,6 +464,9 @@ void NodeGiToggleDebugLog(const char* fmt, ...) G_GNUC_PRINTF(1, 2);
 
 Napi::Value MakeGObjectHandle(Napi::Env env, GObject* obj);
 Napi::Value WrapGObject(Napi::Env env, GObject* obj, GITransfer transfer);
+// The wrapper `obj` already has in `env`, or an empty value — never creates one. See
+// toggle.cc; the caller that needs it is the set_property vfunc (class.cc).
+Napi::Value PeekGObjectHandle(Napi::Env env, GObject* obj);
 
 extern int g_syncEmitDepth;
 
@@ -665,6 +674,8 @@ Napi::Value CallParentVfunc(const Napi::CallbackInfo& info);
 Napi::Value HasClassVfunc(const Napi::CallbackInfo& info);
 Napi::Value CallClassVfunc(const Napi::CallbackInfo& info);
 Napi::Value SetConstructCallback(const Napi::CallbackInfo& info);
+Napi::Value SetPropertySetCallback(const Napi::CallbackInfo& info);
+Napi::Value StoredPropertyNames(const Napi::CallbackInfo& info);
 
 // template.cc
 Napi::Value GetTemplateChild(const Napi::CallbackInfo& info);
@@ -699,6 +710,30 @@ Napi::Value LogSetWriterDefault(const Napi::CallbackInfo& info);
 Napi::Value BindPropertyFull(const Napi::CallbackInfo& info);
 Napi::Value BindingGroupBindFull(const Napi::CallbackInfo& info);
 
+// private.cc — the locale + gettext binders (gjs_set_thread_locale /
+// gjs_textdomain / gjs_bindtextdomain, and the LC_* constants GjsPrivate exports
+// as GjsLocaleCategory). These need C because libintl is not introspectable:
+// GLib publishes the LOOKUP half (g_dgettext/g_dngettext/g_dpgettext2) in its GIR
+// and nothing else, so `bindtextdomain` has no `gi://` spelling on any runtime.
+// NOT named SetThreadLocale, though that is what it mirrors: `<windows.h>` (pulled
+// in by uv.h) defines SetThreadLocale as an object-like macro for the kernel32 API,
+// which rewrote the token at the `Napi::Function::New(env, SetThreadLocale)` call
+// site and failed the MSVC build with C2665 — the same collision the `#undef
+// RegisterClass` above exists for. Renaming the C++ symbol keeps that undef list at
+// one entry; `SetThreadLocaleImpl` is a distinct token and needs nothing.
+Napi::Value ApplyThreadLocale(const Napi::CallbackInfo& info);
+Napi::Value Textdomain(const Napi::CallbackInfo& info);
+Napi::Value Bindtextdomain(const Napi::CallbackInfo& info);
+// The LC_* values THIS platform's <locale.h> defines, as a JS object. Read from
+// the headers rather than written down: the numbers differ per C library
+// (LC_MESSAGES is 5 on glibc, 6 on darwin, and gettext's own 1729 on MSVC, which
+// has no such category), so a literal table is correct on one platform and
+// silently addresses the wrong category on every other one.
+Napi::Value LocaleCategories(const Napi::CallbackInfo& info);
+// Put the process in the locale the environment names — the `setlocale(LC_ALL,
+// "")` gjs's entry point runs before anything else. Idempotent, process-wide.
+void NodeGiInitProcessLocale();
+
 // loop.cc
 Napi::Value StartMainLoop(const Napi::CallbackInfo& info);
 Napi::Value IterateMainContext(const Napi::CallbackInfo& info);