@gjsify/node-gi 0.49.0 → 0.51.0

package/binding.gyp

@@ -35,7 +35,12 @@
             "-std=c++17"
           ],
           "libraries": [
-            "<!@(pkg-config --libs girepository-2.0 cairo)"
+            "<!@(pkg-config --libs girepository-2.0 cairo)",
+            # libintl for the gettext binders (private.cc). Empty off darwin: glibc
+            # absorbs bindtextdomain/textdomain into libc, macOS's libSystem has no
+            # gettext at all and a two-level-namespace Mach-O must name the library
+            # it takes them from. See scripts/mac-intl-gyp-flags.mjs.
+            "<!@(node scripts/mac-intl-gyp-flags.mjs)"
           ],
           "xcode_settings": {
             "OTHER_CFLAGS": [

package/gettext.d.ts

@@ -1,19 +1,19 @@
 // SPDX-License-Identifier: MIT
 // @gjsify/node-gi/gettext — types for the GJS `Gettext` module on Node.
 
-/** Look up `msgid` in the default domain (passthrough). */
+/** Look up `msgid` in the default domain. */
 export function gettext(msgid: string): string;
-/** Look up `msgid` in `domain` (passthrough). */
+/** Look up `msgid` in `domain`. */
 export function dgettext(domain: string | null, msgid: string): string;
-/** Look up `msgid` in `domain`/`category` (passthrough). */
+/** Look up `msgid` in `domain`/`category`. */
 export function dcgettext(domain: string | null, msgid: string, category: number): string;
-/** Plural lookup in the default domain (passthrough). */
+/** Plural lookup in the default domain. */
 export function ngettext(msgid1: string, msgid2: string, n: number): string;
-/** Plural lookup in `domain` (passthrough). */
+/** Plural lookup in `domain`. */
 export function dngettext(domain: string | null, msgid1: string, msgid2: string, n: number): string;
-/** Context lookup in the default domain (passthrough). */
+/** Context lookup in the default domain. */
 export function pgettext(context: string, msgid: string): string;
-/** Context lookup in `domain` (passthrough). */
+/** Context lookup in `domain`. */
 export function dpgettext(domain: string | null, context: string, msgid: string): string;
 /** Domain-bound gettext bindings. */
 export function domain(domainName: string): {
@@ -21,15 +21,15 @@ export function domain(domainName: string): {
     ngettext(msgid1: string, msgid2: string, n: number): string;
     pgettext(context: string, msgid: string): string;
 };
-/** Set the locale for `category` (no-op on Node). */
-export function setlocale(category: number, locale: string | null): null;
-/** Set the default text domain (no-op on Node). */
-export function textdomain(domainName: string | null): null;
-/** Bind a text domain to a directory (no-op on Node). */
-export function bindtextdomain(domainName: string, dirName: string | null): null;
-/** Set the output codeset for a text domain (no-op on Node). */
+/** Set the locale for `category`, or report it when `locale` is null. */
+export function setlocale(category: number, locale: string | null): string | null;
+/** Set the default text domain, or report it when `domainName` is null. */
+export function textdomain(domainName: string | null): string | null;
+/** Bind a text domain to the directory its catalogs live in; pins UTF-8. */
+export function bindtextdomain(domainName: string, dirName: string | null): string | null;
+/** Set the output codeset for a text domain. No-op — `bindtextdomain` pins UTF-8. */
 export function bindtextdomainCodeset(domainName: string, codeset: string | null): null;
-/** The standard POSIX locale category constants. */
+/** The POSIX locale categories, read from the host C library's own <locale.h>. */
 export const LocaleCategory: {
     CTYPE: number;
     NUMERIC: number;
@@ -54,9 +54,9 @@ export interface GettextModule {
         ngettext(msgid1: string, msgid2: string, n: number): string;
         pgettext(context: string, msgid: string): string;
     };
-    setlocale(category: number, locale: string | null): null;
-    textdomain(domainName: string | null): null;
-    bindtextdomain(domainName: string, dirName: string | null): null;
+    setlocale(category: number, locale: string | null): string | null;
+    textdomain(domainName: string | null): string | null;
+    bindtextdomain(domainName: string, dirName: string | null): string | null;
     bindtextdomainCodeset(domainName: string, codeset: string | null): null;
     LocaleCategory: typeof LocaleCategory;
 }

package/gettext.js

@@ -2,108 +2,195 @@
 // @gjsify/node-gi/gettext — the GJS `Gettext` module on Node.
 //
 // GJS exposes a built-in `gettext` module (`import Gettext from 'gettext'` /
-// `imports.gettext`) — a convenience layer over GLib's gettext family. On Node
-// we provide a no-translation passthrough: every lookup returns the untranslated
-// msgid, which is exactly the correct fallback when no message catalog is bound
-// (GLib's gettext degrades to the same passthrough with no catalog). This keeps
-// GJS source that calls `Gettext.gettext(...)` at module load working unchanged
-// on Node without pulling in a real gettext binding.
+// `imports.gettext`) — a convenience layer over GLib's gettext family. This is the
+// same layer with the same split of responsibilities as GJS's:
+//   • LOOKUPS go to GLib (`g_dgettext` / `g_dngettext` / `g_dpgettext2`), which is
+//     introspectable and therefore needs no native code here;
+//   • the BINDERS (`setlocale` / `textdomain` / `bindtextdomain`) are libintl, which
+//     has no GIR at all, so they come from the addon — the same reason GJS routes
+//     them through GjsPrivate instead of `imports.gi.GLib`.
+// Reference: refs/gjs/modules/core/_gettext.js, function for function.
+//
+// THIS MODULE USED TO BE A PASSTHROUGH — every lookup returned its msgid, every
+// binder a no-op returning null. That is the right fallback when no catalog can be
+// bound, and it was written when node-gi had no way to bind one; what made it a
+// defect is that it stayed after the rest of the bridge could. It was also only
+// HALF of what was wrong — the process locale (private.cc) had to be fixed too, or
+// a real `bindtextdomain` would still have translated nothing.
 //
 // This is the single source of truth for the Gettext surface: the legacy
 // `imports.gettext` exposed by `@gjsify/node-gi/globals` re-uses this module's
 // default export. The gjsify `--app node` build aliases the bare `gettext`
 // specifier to this module (kept external — `ALIASES_GJS_FOR_NODE`).
+import * as native from './index.js';
+import { requireGi } from './gi.js';
+
+// GLib is resolved on first lookup, not at import: loading a namespace walks the
+// typelib, and a module imported for its LocaleCategory alone should not pay for
+// it. The addon itself is already loaded — `./index.js` above is what puts the
+// process in the environment's locale, and that has to happen whether or not
+// anything ever looks a string up.
+let glib = null;
+function GLib() {
+    if (glib === null) glib = requireGi('GLib', '2.0');
+    return glib;
+}
+
+// THE ADDON AND THIS JS CAN BE PAIRED ACROSS VERSIONS, so the binders are probed
+// rather than assumed — the same reason `native-prebuilds.js` probes
+// `prependLibraryPath`. `gtk-os-suites.yml`'s shipped-closure legs stage the
+// PUBLISHED addon against THIS tree's JS deliberately ("the tarball a consumer
+// actually receives"), and a bare `native.localeCategories()` died there with
+// `TypeError: native.localeCategories is not a function` — taking the whole module
+// down, and `globals.js` with it, because it is evaluated at import.
 //
-// Reference: GJS's `gettext` module (refs/gjs/modules/esm/gettext.js +
-// modules/core/_gettext.js). Signatures mirror that surface.
+// Degrading means behaving exactly as an addon without the binders always did:
+// lookups still work (they go through GLib, which every addon version has), and
+// the binders are the no-ops they used to be. It is announced once, because a
+// silently untranslated UI is the defect this file exists to close.
+const haveLocaleBinders = typeof native.localeCategories === 'function';
+
+let announcedStaleAddon = false;
+function noLocaleBinders(fn) {
+    if (!announcedStaleAddon) {
+        announcedStaleAddon = true;
+        process.emitWarning(
+            `@gjsify/node-gi: the loaded native addon predates the gettext binders, so ` +
+                `${fn}() cannot take effect and messages stay untranslated. Rebuild the addon ` +
+                `(npm run rebuild) or update @gjsify/node-gi.`,
+            'NodeGiStaleAddon',
+        );
+    }
+    return null;
+}
 
-/** Look up `msgid` in the default domain. Passthrough — returns `msgid`. */
+// The POSIX categories per C library, used ONLY when the addon cannot report its
+// own. The addon is the source of truth precisely because these are C-library
+// constants rather than a standard; this table exists so a stale pairing gets the
+// right numbers for its platform instead of glibc's everywhere, which is the bug
+// the module used to ship.
+const FALLBACK_CATEGORIES = {
+    // glibc
+    linux: { CTYPE: 0, NUMERIC: 1, TIME: 2, COLLATE: 3, MONETARY: 4, MESSAGES: 5, ALL: 6 },
+    // Darwin libc
+    darwin: { ALL: 0, COLLATE: 1, CTYPE: 2, MONETARY: 3, NUMERIC: 4, TIME: 5, MESSAGES: 6 },
+    // The MSVC CRT, which has no LC_MESSAGES — GNU gettext's <libintl.h> picks 1729.
+    win32: { ALL: 0, COLLATE: 1, CTYPE: 2, MONETARY: 3, NUMERIC: 4, TIME: 5, MESSAGES: 1729 },
+};
+
+/** Look up `msgid` in the default domain (the one `textdomain()` last named). */
 export function gettext(msgid) {
-    return msgid;
+    return GLib().dgettext(null, msgid);
 }
 
-/** Look up `msgid` in `domain`. Passthrough — returns `msgid`. */
-export function dgettext(_domain, msgid) {
-    return msgid;
+/** Look up `msgid` in `domain`. */
+export function dgettext(domain, msgid) {
+    return GLib().dgettext(domain, msgid);
 }
 
-/** Look up `msgid` in `domain`/`category`. Passthrough — returns `msgid`. */
-export function dcgettext(_domain, msgid, _category) {
-    return msgid;
+/** Look up `msgid` in `domain` for `category`. */
+export function dcgettext(domain, msgid, category) {
+    return GLib().dcgettext(domain, msgid, category);
 }
 
-/** Plural lookup in the default domain. Passthrough — singular for n===1, else plural. */
+/** Plural lookup in the default domain. */
 export function ngettext(msgid1, msgid2, n) {
-    return n === 1 ? msgid1 : msgid2;
+    return GLib().dngettext(null, msgid1, msgid2, n);
 }
 
-/** Plural lookup in `domain`. Passthrough — singular for n===1, else plural. */
-export function dngettext(_domain, msgid1, msgid2, n) {
-    return n === 1 ? msgid1 : msgid2;
+/** Plural lookup in `domain`. */
+export function dngettext(domain, msgid1, msgid2, n) {
+    return GLib().dngettext(domain, msgid1, msgid2, n);
 }
 
-/** Context lookup in the default domain. Passthrough — returns `msgid`. */
-export function pgettext(_context, msgid) {
-    return msgid;
+/** Context lookup in the default domain. */
+export function pgettext(context, msgid) {
+    return GLib().dpgettext2(null, context, msgid);
 }
 
-/** Context lookup in `domain`. Passthrough — returns `msgid`. */
-export function dpgettext(_domain, _context, msgid) {
-    return msgid;
+/** Context lookup in `domain`. */
+export function dpgettext(domain, context, msgid) {
+    return GLib().dpgettext2(domain, context, msgid);
 }
 
 /**
  * Create gettext bindings bound to a particular translation domain. Mirrors
  * GJS's `Gettext.domain()` — returns an object with `gettext`/`ngettext`/
- * `pgettext` bound to `domainName` (passthrough here).
+ * `pgettext` bound to `domainName`.
  */
-export function domain(_domainName) {
+export function domain(domainName) {
     return {
         gettext(msgid) {
-            return msgid;
+            return GLib().dgettext(domainName, msgid);
         },
         ngettext(msgid1, msgid2, n) {
-            return n === 1 ? msgid1 : msgid2;
+            return GLib().dngettext(domainName, msgid1, msgid2, n);
         },
-        pgettext(_context, msgid) {
-            return msgid;
+        pgettext(context, msgid) {
+            return GLib().dpgettext2(domainName, context, msgid);
         },
     };
 }
 
-/** Set the locale for `category`. No-op on Node — returns null. */
-export function setlocale(_category, _locale) {
-    return null;
+/**
+ * Set the locale for `category`, or report it when `locale` is null.
+ *
+ * Thread-local, as GJS's is (`GjsPrivate.set_thread_locale` → `uselocale`), and it
+ * inherits GJS's reporting quirk with it: a query answers with the name that was
+ * in effect BEFORE the last successful set on this thread, because the report
+ * comes from the global locale `uselocale` does not touch. Measured against
+ * gjs 1.88 — setting LC_MESSAGES to "C" stops translation immediately while the
+ * next query still answers the old name.
+ *
+ * @returns {string|null} the prior locale name, or null if it could not be set
+ */
+export function setlocale(category, locale) {
+    if (!haveLocaleBinders) return noLocaleBinders('setlocale');
+    return native.setThreadLocale(category, locale ?? null);
 }
 
-/** Set the default text domain. No-op on Node — returns null. */
-export function textdomain(_domainName) {
-    return null;
+/** Set the default text domain, or report it when `domainName` is null. */
+export function textdomain(domainName) {
+    if (!haveLocaleBinders) return noLocaleBinders('textdomain');
+    return native.textdomain(domainName ?? null);
 }
 
-/** Bind a text domain to a directory. No-op on Node — returns null. */
-export function bindtextdomain(_domainName, _dirName) {
-    return null;
+/**
+ * Bind a text domain to the directory its catalogs live in.
+ *
+ * The codeset is pinned to UTF-8 alongside the bind, exactly as
+ * `gjs_bindtextdomain` does — see the note in private.cc.
+ */
+export function bindtextdomain(domainName, dirName) {
+    if (!haveLocaleBinders) return noLocaleBinders('bindtextdomain');
+    return native.bindtextdomain(domainName, dirName ?? null);
 }
 
-/** Set the output codeset for a text domain. No-op on Node — returns null. */
+/**
+ * Set the output codeset for a text domain.
+ *
+ * `bindtextdomain()` already pins UTF-8, which is what every string crossing this
+ * bridge must be, so this stays a no-op returning null. It is the one member of
+ * the surface GJS does not implement either — it is absent from
+ * refs/gjs/modules/core/_gettext.js — and is kept for source that calls it.
+ */
 export function bindtextdomainCodeset(_domainName, _codeset) {
     return null;
 }
 
 /**
- * The `LocaleCategory` enum — the standard POSIX locale category constants GJS
- * surfaces via `GjsPrivate.LocaleCategory`.
+ * The `LocaleCategory` enum — the POSIX locale categories GJS surfaces via
+ * `GjsPrivate.LocaleCategory`.
+ *
+ * Read from THIS platform's `<locale.h>` rather than written down: the numbers are
+ * C-library constants, not a standard (LC_MESSAGES is 5 on glibc and 6 on darwin),
+ * so the literal table this module used to carry addressed LC_TIME on macOS while
+ * claiming to address LC_MESSAGES — on two of the three platforms the translation
+ * blocker was reported from.
  */
-export const LocaleCategory = {
-    CTYPE: 0,
-    NUMERIC: 1,
-    TIME: 2,
-    COLLATE: 3,
-    MONETARY: 4,
-    MESSAGES: 5,
-    ALL: 6,
-};
+export const LocaleCategory = haveLocaleBinders
+    ? native.localeCategories()
+    : (FALLBACK_CATEGORIES[process.platform] ?? FALLBACK_CATEGORIES.linux);
 
 /**
  * The GJS `Gettext` module as a default export — the object shape

package/gi.js

@@ -832,31 +832,99 @@ function assignTemplateChildren(instance, handle, reg) {
     }
 }
 
-// Push construct-time GObject-property values through the class's own JS SETTERS.
+// The prototype SETTER a GObject property name resolves to, across the three
+// spellings GJS makes equivalent, or undefined when the class declares none.
 //
-// A class can declare a GObject property (`Properties: { displayWidth: ParamSpec }`,
-// often CONSTRUCT with a default) AND a matching JS accessor
-// (`get/set displayWidth` over a `_displayWidth` backing field). On GJS the property
-// set vfunc delegates to the JS setter (`JS_SetProperty`), so the CONSTRUCT default
-// reaches `_displayWidth` at construction. node-gi builds the wrapper AFTER
-// g_object_new, so at construct time there is no USER_PROTO to route through — the
-// value lands only in the engine's per-instance store, and the class's getter
+// GJS's set_property vfunc writes only the UNDERSCORE spelling
+// (refs/gjs/gi/gobject.cpp jsobj_set_gproperty → JS_SetProperty(underscore_name)),
+// and reaches a camelCase accessor anyway because registerClass has already mirrored
+// whichever spelling the class declared onto the dash, underscore AND camel names
+// (`_checkAccessors`, refs/gjs/modules/core/_common.js). node-gi keeps the engine
+// store as the backing store rather than installing GJS's generated accessors, so it
+// resolves the same three spellings at the point of use instead — same reachability,
+// no accessor synthesis. Learn6502's SourceView is exactly why this matters: its
+// property is `line-numbers` and its accessor is `lineNumbers`.
+function findPropertySetter(userProto, propertyName) {
+    const underscored = propertyName.replace(/-/g, '_');
+    const camel = propertyName.replace(/-([a-z])/g, (m) => m[1].toUpperCase());
+    for (const spelling of [propertyName, underscored, camel]) {
+        const desc = findProtoDescriptor(userProto, spelling);
+        if (desc !== undefined && typeof desc.set === 'function') return desc.set;
+    }
+    return undefined;
+}
+
+// Run a class's own JS setter for a custom property the ENGINE has just stored —
+// the L1 half of NodeGiSetProperty (src/class.cc), which is node-gi's
+// gjs_object_set_gproperty. The engine calls this only once the instance HAS a
+// wrapper, so a set that lands during construction never reaches here; those are
+// replayed by flushPropertiesToJsSetters below.
+function runJsPropertySetter(handle, propertyName) {
+    const instance = instanceCache.get(handle);
+    if (instance === undefined) return;
+    const up = instance[USER_PROTO];
+    if (up === undefined) return;
+    const set = findPropertySetter(up, propertyName);
+    if (set === undefined) return; // no JS accessor: the store is the single backing store
+    set.call(instance, wrapReturn(native.getProperty(handle, propertyName)));
+}
+// Guarded because the addon paired with this JS may PREDATE it, and that pairing is
+// deliberate rather than hypothetical: gtk-os-suites.yml's shipped-closure legs run
+// this checkout's JS against the PUBLISHED addon (`NODE_GI_NATIVE=prebuild`, logged
+// as "node-gi JS: (this checkout) / addon: (published)"), so a bare call to a new
+// native export takes those three legs down with `native.<new export> is not a
+// function` until the next release republishes the binary. Every native call added
+// here degrades instead; without the callback, a post-construction set simply does
+// not reach the JS setter, which is what 0.50.0 did.
+if (typeof native.setPropertySetCallback === 'function') {
+    native.setPropertySetCallback(runJsPropertySetter);
+}
+
+// Which properties the construct-time replay must run.
+//
+// `native.storedPropertyNames` is the honest answer — what was ACTUALLY set, in
+// first-set order. An addon older than this JS does not export it (same cross-version
+// pairing as the guard above), so the fallback is the CONSTRUCT-flag filter this used
+// to be: narrower, since it misses a plain property passed to `new`, but never wrong
+// — GObject does apply CONSTRUCT properties at construction. Keeping it is what makes
+// the shipped-closure legs measure the published addon rather than this gap.
+function propertiesToReplay(handle, reg) {
+    if (typeof native.storedPropertyNames === 'function') return native.storedPropertyNames(handle);
+    return reg.constructPropertyNames ?? [];
+}
+
+// Replay the properties set DURING construction through the class's own JS SETTERS.
+//
+// A class can declare a GObject property (`Properties: { displayWidth: ParamSpec }`)
+// AND a matching JS accessor (`get/set displayWidth` over a `_displayWidth` backing
+// field). On GJS the set vfunc delegates to the JS setter, so a value applied by
+// g_object_new reaches `_displayWidth` at construction. node-gi builds the wrapper
+// AFTER g_object_new, so during construction there is no USER_PROTO to route through
+// — the value lands only in the engine's per-instance store, and the class's getter
 // (reading `_displayWidth`) sees `undefined` (the Learn6502 Display "DrawingArea is
 // required" wall). Once USER_PROTO is attached (here, right after construction), read
-// each such property's construct value back out (from the store, or the ParamSpec
-// default) and run it through the JS setter — the node-gi analogue of GJS applying a
-// CONSTRUCT property via the JS setter, and BEFORE the user ctor body runs (same
-// order as GJS). Only properties whose name resolves to a prototype SETTER are
-// touched, so a plain GObject property (no JS accessor) keeps the store as its single
-// backing store — unchanged.
-function flushConstructProperties(instance, handle, reg) {
-    if (reg.constructPropertyNames === undefined) return;
+// each such value back out and run it through the JS setter, BEFORE the user ctor
+// body runs — the same order GJS produces.
+//
+// WHICH properties: the ones the engine actually STORED, i.e. that something really
+// set (`native.storedPropertyNames`). Not every declared property — flushing those
+// runs a setter for a property nobody assigned, against state the ctor body has not
+// created yet, which is the Learn6502 SourceView `selectable` → `_signalHandlers`
+// forEach crash. "Was it set?" is the honest question and the store is its honest
+// answer; the CONSTRUCT flag is only a proxy for it (GObject applies a CONSTRUCT
+// property's default at construction, so it is stored too, and a plain READWRITE
+// property passed to `new` is stored as well — which GJS also routes through the
+// setter, and the old CONSTRUCT-only filter missed).
+//
+// Only properties whose name resolves to a prototype SETTER are touched, so a plain
+// GObject property (no JS accessor) keeps the store as its single backing store.
+function flushPropertiesToJsSetters(instance, handle, reg) {
     const up = instance[USER_PROTO];
     if (up === undefined) return;
-    for (const name of reg.constructPropertyNames) {
-        const desc = findProtoDescriptor(up, name);
-        if (desc === undefined || typeof desc.set !== 'function') continue;
-        desc.set.call(instance, wrapReturn(native.getProperty(handle, name)));
+    for (const name of propertiesToReplay(handle, reg)) {
+        const set = findPropertySetter(up, name);
+        if (set === undefined) continue;
+        set.call(instance, wrapReturn(native.getProperty(handle, name)));
     }
 }
 
@@ -1605,7 +1673,7 @@ function makeClass(namespace, typeName) {
                 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).
-                flushConstructProperties(instance, handle, reg);
+                flushPropertiesToJsSetters(instance, handle, reg);
                 return instance;
             }
             // `nt` is a subclass of this introspected GObject class but was NEVER passed to
@@ -2340,13 +2408,11 @@ function registerClass(metaOrClass, maybeClass) {
     // Record the registration so the introspected base ctor (makeClass) routes
     // `new X(args)` (where new.target === klass) to constructType(typeHandle, …) +
     // the canonical wrapper. Template children move here from the old Subclass.
-    // The names of CONSTRUCT / CONSTRUCT_ONLY properties — the ONLY ones GObject
-    // applies at construction. The flush (flushConstructProperties) must be limited to
-    // these: a plain READWRITE property is NOT set during construction, so running its
-    // JS setter early (GObject never would) fires the setter's side effects against
-    // still-uninitialised instance state (the SourceView `selectable` → `_signalHandlers`
-    // forEach crash). Matches GJS, which only runs setters for props GObject applies at
-    // construct. Flags are the ABI-stable G_PARAM_CONSTRUCT (1<<2) | CONSTRUCT_ONLY (1<<3).
+    // Which properties the construct-time flush replays is a question about this
+    // INSTANCE ("what was actually set?"), and the engine's per-instance store answers
+    // it directly. These CONSTRUCT / CONSTRUCT_ONLY names are only the FALLBACK for an
+    // addon too old to answer it — see propertiesToReplay. Flags are the ABI-stable
+    // G_PARAM_CONSTRUCT (1<<2) | CONSTRUCT_ONLY (1<<3).
     const PARAM_CONSTRUCT_MASK = 0x4 | 0x8;
     const constructPropertyNames = properties
         .filter((p) => typeof p.flags === 'number' && (p.flags & PARAM_CONSTRUCT_MASK) !== 0)
@@ -2356,7 +2422,6 @@ function registerClass(metaOrClass, maybeClass) {
         typeHandle,
         children: children.length > 0 ? children : undefined,
         internalChildren: internalChildren.length > 0 ? internalChildren : undefined,
-        // CONSTRUCT-property names, for the construct-property flush (below).
         constructPropertyNames: constructPropertyNames.length > 0 ? constructPropertyNames : undefined,
     });
     // Reverse index for runCtorForCObject: the engine identifies a C-created instance

package/globals.d.ts

@@ -13,7 +13,7 @@ export interface GjsImports {
     };
     /** `imports.system` — the `@gjsify/node-gi/system` module (process identity + lifecycle). */
     system: SystemModule;
-    /** `imports.gettext` — the `@gjsify/node-gi/gettext` module (no-translation passthrough). */
+    /** `imports.gettext` — the `@gjsify/node-gi/gettext` module (real gettext via GLib + libintl). */
     gettext: GettextModule;
     /** `imports.byteArray` — the legacy GJS byte-array module (GJS semantics: zero-terminated, fatal decode). */
     byteArray: {

package/gtk-runtime.js

@@ -437,6 +437,28 @@ export function maybeWireGtkWindowingEnv() {
         setIfUnset('FONTCONFIG_FILE', fontsConf);
     }
 
+    // THE FACES, which are a different question from the two lines above and on one of the
+    // two platforms not answerable by an environment variable at all.
+    //
+    // `XDG_DATA_DIRS` already reaches `<bundle>/share/fonts` wherever fontconfig drives
+    // Pango — its stock configuration carries `<dir prefix="xdg">fonts</dir>` — so on darwin
+    // the set above is enough and this variable is a second, cheaper route to the same files.
+    // On WIN32 it is the only route there is: GTK4 uses pangowin32, whose font map is filled
+    // exclusively by `pango_font_map_dwrite_populate()` from the DirectWrite system
+    // collection, and a `FONTCONFIG_FILE` naming a directory of faces moves that map by ZERO
+    // families even when it is the only configuration present (measured on Windows 11 /
+    // GTK 4.22.4, both directions — ADR 0038 § W1-W5). The face has to be handed to the map
+    // through `add_font_file`, which is a RUNTIME call somebody has to make.
+    //
+    // So the loader's job here is to name the directory, not to register anything: it runs
+    // before the addon loads and has no Pango to talk to. `@gjsify/gtk-host`'s `initFonts()`
+    // is the reader — the same handover `gjsify ship` makes for an application's OWN faces
+    // through `GJSIFY_FONT_DIR`, one layer down, because these faces belong to the RUNTIME
+    // and every application on it needs them. Two variables and not one: an app that ships a
+    // brand face must not have to choose between its face and the platform's.
+    const runtimeFontDir = join(shareDir, 'fonts');
+    if (existsSync(runtimeFontDir)) setIfUnset('GJSIFY_GTK_RUNTIME_FONT_DIR', runtimeFontDir);
+
     // GStreamer, which finds its plugins the way GTK finds its schemas: by env,
     // read at init. Without this the bundle can ship every Gst typelib and still
     // play nothing — `Gst.init()` succeeds against an EMPTY registry, so the

package/index.js

@@ -277,9 +277,29 @@ export const setTemplateCallbackResolver = native.setTemplateCallbackResolver;
 // Reflect.constructs the class in adopt mode — see gi.js runCtorForCObject.
 export const setConstructCallback = native.setConstructCallback;
 
+// Registers the L1 callback the engine's set_property vfunc invokes after storing a
+// custom property: given (instanceHandle, propertyName) it runs the class's own JS
+// setter — see gi.js runJsPropertySetter. The engine calls it only once the instance
+// HAS a wrapper, so a construct-time set never reaches it; those are replayed from
+// the base ctor over storedPropertyNames.
+export const setPropertySetCallback = native.setPropertySetCallback;
+
+// The custom properties actually SET on an instance (the per-instance store's keys) —
+// what that construct-time replay has to push through the class's JS setters.
+export const storedPropertyNames = native.storedPropertyNames;
+
 export const logSetWriterFunc = native.logSetWriterFunc;
 export const logSetWriterDefault = native.logSetWriterDefault;
 export const bindPropertyFull = native.bindPropertyFull;
 export const bindingGroupBindFull = native.bindingGroupBindFull;
 
+// The libintl half of GjsPrivate — the binders GLib's GIR does not publish, plus
+// the LC_* constants read from the host's own <locale.h>. Consumed by
+// `./gettext.js`; loading THIS module is also what puts the process in the
+// environment's locale (the addon's Init does it, as gjs's entry point does).
+export const setThreadLocale = native.setThreadLocale;
+export const textdomain = native.textdomain;
+export const bindtextdomain = native.bindtextdomain;
+export const localeCategories = native.localeCategories;
+
 export default native;

package/overrides/package.js

@@ -71,13 +71,13 @@ export function createPackage({ requireGi, gettext, imports }) {
         },
 
         initGettext() {
+            // No try/catch: these were no-ops returning null when node-gi had no
+            // gettext binding, and the catch that tolerated that would now swallow
+            // the one failure worth seeing — a localedir that does not hold the
+            // app's catalogs, whose only other symptom is an untranslated UI.
             if (pkg.name) {
-                try {
-                    gettext.bindtextdomain?.(pkg.name, pkg.localedir ?? null);
-                    gettext.textdomain?.(pkg.name);
-                } catch {
-                    /* passthrough gettext — no catalog, ignore */
-                }
+                gettext.bindtextdomain(pkg.name, pkg.localedir ?? null);
+                gettext.textdomain(pkg.name);
             }
             // The globals GJS apps + compiled Blueprint use pervasively.
             globalThis._ = (msgid) => gettext.gettext(msgid);