@gjsify/node-gi 0.20.0 → 0.22.0

package/gi.js

@@ -255,6 +255,31 @@ function resolveTemplateCallback(handle, handlerName) {
 }
 native.setTemplateCallbackResolver(resolveTemplateCallback);
 
+// Run a registered class's JS constructor for a GObject the ENGINE instantiated
+// from C — a GtkBuilder composite-template InternalChild is the common case. node-gi's
+// JS-`new` path runs the ctor via the makeClass super-substitution; a C-created
+// instance has no such driver, so NodeGiConstructor (the overridden `constructor`
+// vfunc) calls this with the instance's canonical handle + its GType name. We set
+// `adoptHandle` and Reflect.construct the class: its `super()` reaches the makeClass
+// base ctor, which adopts the handle (no second GObject) and returns the canonical
+// wrapper, so the ctor body runs against it (`this._x = …` become expandos on the
+// one wrapper GtkBuilder-fetched children later resolve to). GJS-faithful
+// (gjs_object_constructor's native-construction branch runs the JS constructor).
+function runCtorForCObject(handle, gtypeName) {
+  const cls = classesByGType.get(gtypeName);
+  if (cls === undefined) return; // not a node-gi-registered class (shouldn't happen)
+  const prev = adoptHandle;
+  adoptHandle = handle;
+  try {
+    // No props: GtkBuilder already applied the construct properties to the C object;
+    // the ctor's `params` arg is conventionally optional for a template child.
+    Reflect.construct(cls, []);
+  } finally {
+    adoptHandle = prev;
+  }
+}
+native.setConstructCallback(runCtorForCObject);
+
 // Wrap a non-GObject GObject-fundamental (e.g. a GskRenderNode from
 // Gtk.Snapshot.to_node, a GdkEvent) as an OPAQUE, round-trippable handle. The
 // native tagged External already carries the raw pointer (its Data) + drops the
@@ -835,6 +860,18 @@ function handlerIdsForFunc(handle, fn) {
 // routing keys on the leaf so construction is correct at any depth.
 const registeredClasses = new Map();
 
+// 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.
+const classesByGType = new Map();
+
+// When set (by runCtorForCObject), the makeClass base ctor ADOPTS this pre-existing
+// canonical handle instead of constructing a second GObject — so a C/GtkBuilder-
+// created instance's user ctor body runs on the wrapper the engine already built.
+// A module-scoped latch is safe: it is set immediately before a synchronous
+// Reflect.construct and consumed by the base ctor before any nested construction.
+let adoptHandle;
+
 // Surface a templated type's bound children on a freshly-constructed instance
 // (GJS convention: public `this.<name>`, internal `this._<name>`, '-' → '_'). The
 // engine already ran init_template during constructType, so getTemplateChild
@@ -853,6 +890,34 @@ function assignTemplateChildren(instance, handle, reg) {
   }
 }
 
+// Push construct-time GObject-property values through the class's own JS SETTERS.
+//
+// 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
+// (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;
+  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)));
+  }
+}
+
 // ---- Gio.Application.runAsync (L1, GJS-shaped) ----
 //
 // The Node twin of GJS's `Gio.Application.prototype.runAsync`
@@ -1295,9 +1360,22 @@ function makeClass(namespace, typeName) {
     if (nt !== undefined && nt !== proxy) {
       const reg = registeredClasses.get(nt);
       if (reg !== undefined) {
-        const handle = native.constructType(reg.typeHandle, props ? unwrapProps(props) : {});
+        let handle;
+        if (adoptHandle !== undefined) {
+          // C-created adoption (runCtorForCObject): the engine already built the
+          // GObject; use its canonical handle instead of constructing another.
+          // Consume the latch atomically so a nested `new` in the ctor body takes
+          // the normal constructType path.
+          handle = adoptHandle;
+          adoptHandle = undefined;
+        } else {
+          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).
+        flushConstructProperties(instance, handle, reg);
         return instance;
       }
       // `nt` is a subclass of this introspected GObject class but was NEVER passed to
@@ -1958,11 +2036,28 @@ 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).
+  const PARAM_CONSTRUCT_MASK = 0x4 | 0x8;
+  const constructPropertyNames = properties
+    .filter((p) => typeof p.flags === 'number' && (p.flags & PARAM_CONSTRUCT_MASK) !== 0)
+    .map((p) => p.name)
+    .filter((n) => typeof n === 'string');
   registeredClasses.set(klass, {
     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
+  // by its GType name (= gtypeName, what native.registerClass registered).
+  classesByGType.set(gtypeName, klass);
   return klass;
 }
 

package/globals.js

@@ -23,6 +23,7 @@ import cairo from './cairo.js';
 // GLib.MainLoop convenience layer) — the GJS script modules many older sources use.
 import * as signalsModule from './overrides/_signals.js';
 import { createMainloop } from './overrides/mainloop.js';
+import { createPackage } from './overrides/package.js';
 
 // GJS stringifies each argument with String() and joins with a space (no
 // util.inspect object formatting) — match that for fidelity.
@@ -109,6 +110,10 @@ function makeImports() {
     gettext,
     cairo,
     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
+    // source that reads/mutates it doesn't throw.
+    searchPath: [],
     versions: Object.create(null),
   };
   let mainloop;
@@ -120,6 +125,17 @@ function makeImports() {
     enumerable: true,
     configurable: true,
   });
+  // `imports.package` — the GJS application bootstrap (pkg.init/initGettext/
+  // initFormat). Lazy like `mainloop`: a bundle that never calls it pulls no GLib.
+  let pkg;
+  Object.defineProperty(imports, 'package', {
+    get() {
+      if (pkg === undefined) pkg = createPackage({ requireGi, gettext, imports });
+      return pkg;
+    },
+    enumerable: true,
+    configurable: true,
+  });
   return imports;
 }
 

package/gtk-runtime.js

@@ -158,7 +158,12 @@ export function maybePrependGtkRuntimeDllPath() {
  * @returns {void}
  */
 export function maybeWireGtkWindowingEnv() {
-    if (process.platform !== 'win32') return; // strict no-op on every non-win32 runtime
+    // win32 AND darwin ship a batteries-included --windowing bundle whose runtime
+    // DATA (gschemas / icons / loaders / gtksource / fonts) is located by these env
+    // vars — GLib/GTK read them at init, not at launch (unlike dyld's DYLD_FALLBACK),
+    // so setting them in-process works on both. The only platform difference is the
+    // XDG_DATA_DIRS separator (';' on win32, ':' on unix/darwin).
+    if (process.platform !== 'win32' && process.platform !== 'darwin') return;
     const bundle = resolveGtkRuntimeBundle();
     if (!bundle) return; // strict no-op when no bundle is present
 
@@ -166,6 +171,7 @@ export function maybeWireGtkWindowingEnv() {
     // gschemas.compiled = the windowing-data marker; absent → display-free bundle.
     if (!existsSync(join(schemaDir, 'gschemas.compiled'))) return;
 
+    const pathSep = process.platform === 'win32' ? ';' : ':';
     const setIfUnset = (name, value) => {
         if (!process.env[name]) process.env[name] = value;
     };
@@ -177,11 +183,13 @@ export function maybeWireGtkWindowingEnv() {
         setIfUnset('GDK_PIXBUF_MODULE_FILE', loaderCache);
     }
 
+    // XDG_DATA_DIRS → <bundle>/share so the icon themes (share/icons) AND GtkSource's
+    // language-specs/styles (share/gtksourceview-5) resolve.
     const shareDir = join(bundle.dir, 'share');
-    if (existsSync(join(shareDir, 'icons'))) {
+    if (existsSync(shareDir)) {
         const cur = process.env.XDG_DATA_DIRS ?? '';
-        if (!cur.split(';').filter(Boolean).includes(shareDir)) {
-            process.env.XDG_DATA_DIRS = cur ? `${shareDir};${cur}` : shareDir;
+        if (!cur.split(pathSep).filter(Boolean).includes(shareDir)) {
+            process.env.XDG_DATA_DIRS = cur ? `${shareDir}${pathSep}${cur}` : shareDir;
         }
     }
 

package/index.js

@@ -663,6 +663,16 @@ export const disconnectSignal = native.disconnectSignal;
  */
 export const setTemplateCallbackResolver = native.setTemplateCallbackResolver;
 
+/**
+ * Register the L1 callback the engine's overridden `constructor` vfunc invokes to
+ * run a registered class's JS constructor for a GObject it instantiated from C (a
+ * GtkBuilder composite-template InternalChild). Given (instanceHandle, gtypeName)
+ * it Reflect.constructs the class in adopt mode (see gi.js runCtorForCObject).
+ * @param {(handle: unknown, gtypeName: string) => void} cb
+ * @returns {void}
+ */
+export const setConstructCallback = native.setConstructCallback;
+
 /**
  * Install (or clear, with `null`) the structured-log writer function — the
  * engine's twin of GjsPrivate.log_set_writer_func backing GLib.log_set_writer_func.

package/overrides/package.js

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: MIT OR LGPL-2.0-or-later
+// SPDX-FileCopyrightText: 2013 Giovanni Campagna <scampa.giovanni@gmail.com>
+//
+// Adapted from GJS (refs/gjs/modules/script/package.js). Copyright (c) 2013
+// Giovanni Campagna. MIT OR LGPL-2.0-or-later.
+// Modifications: the legacy `imports.package` — the GJS application bootstrap
+// (`pkg.init` / `initGettext` / `initFormat`) — ported to @gjsify/node-gi. A GNOME
+// app's entry point does `imports.package.init({ name, version, prefix, libdir })`
+// then `pkg.initGettext()` / `pkg.initFormat()`. The GJS original's heavy
+// source-tree detection + GResource registration + module-search machinery is NOT
+// load-bearing for a node-gi consumer (the app carries its own dir constants and
+// registers its own resources — see easy6502 app-gnome resources.ts), so this is
+// the minimal, honest init: set `globalThis.pkg`, wire `_`/`C_`/`N_` and
+// `String.prototype.format`, and keep `imports.searchPath` / `GLib.set_prgname`
+// calls safe. Mirrors overrides/mainloop.js's `createX(deps)` shape.
+
+/**
+ * Build the `imports.package` object bound to the L1 backend.
+ * @param {{ requireGi: Function, gettext: any, imports: Record<string, any> }} deps
+ */
+export function createPackage({ requireGi, gettext, imports }) {
+  const pkg = {
+    // Public fields GJS source may read. Populated by init().
+    name: undefined,
+    version: undefined,
+    prefix: undefined,
+    libdir: undefined,
+    datadir: undefined,
+    pkgdatadir: undefined,
+    pkglibdir: undefined,
+    moduledir: undefined,
+    localedir: undefined,
+
+    /**
+     * @param {{ name?: string, version?: string, prefix?: string, libdir?: string, datadir?: string }} params
+     */
+    init(params = {}) {
+      // The accessor GJS apps use right after: `pkg.initGettext()`.
+      globalThis.pkg = pkg;
+
+      pkg.name = params.name;
+      pkg.version = params.version;
+      pkg.prefix = params.prefix;
+      pkg.libdir = params.libdir;
+      pkg.datadir = params.datadir ?? (params.prefix ? `${params.prefix}/share` : undefined);
+
+      // Installed-layout dirs — NOT load-bearing on node-gi (apps carry their own
+      // constants + register their own resources), computed for source-compat only.
+      if (pkg.name) {
+        if (pkg.datadir) {
+          pkg.pkgdatadir = `${pkg.datadir}/${pkg.name}`;
+          pkg.moduledir = pkg.pkgdatadir;
+          pkg.localedir = `${pkg.datadir}/locale`;
+        }
+        if (pkg.libdir) pkg.pkglibdir = `${pkg.libdir}/${pkg.name}`;
+      }
+
+      // Cheap + safe: keeps ARGV[0]/app-id semantics (window-manager grouping etc.).
+      try {
+        const GLib = requireGi('GLib', '2.0');
+        if (pkg.name && typeof GLib.set_prgname === 'function') GLib.set_prgname(pkg.name);
+      } catch {
+        /* GLib not loadable in this context — skip */
+      }
+
+      // GJS unshifts moduledir onto imports.searchPath (script-import machinery).
+      // node-gi apps use ESM + gi://, so the search path is inert here — but keep
+      // the array present + the unshift safe so source that reads it doesn't throw.
+      if (!Array.isArray(imports.searchPath)) imports.searchPath = [];
+      if (pkg.moduledir) imports.searchPath.unshift(pkg.moduledir);
+    },
+
+    initGettext() {
+      if (pkg.name) {
+        try {
+          gettext.bindtextdomain?.(pkg.name, pkg.localedir ?? null);
+          gettext.textdomain?.(pkg.name);
+        } catch {
+          /* passthrough gettext — no catalog, ignore */
+        }
+      }
+      // The globals GJS apps + compiled Blueprint use pervasively.
+      globalThis._ = (msgid) => gettext.gettext(msgid);
+      globalThis.C_ = (context, msgid) => gettext.pgettext(context, msgid);
+      globalThis.N_ = (msgid) => msgid;
+    },
+
+    initFormat() {
+      // GJS sets `String.prototype.format = imports.format.format` (backed by the
+      // native `_format` vprintf). node-gi has no `imports.format`, so supply an
+      // equivalent JS vprintf here (see makeVprintf).
+      const vprintf = makeVprintf();
+      Object.defineProperty(String.prototype, 'format', {
+        configurable: true,
+        writable: true,
+        enumerable: false,
+        value: function format(...args) {
+          return vprintf(this, args);
+        },
+      });
+    },
+
+    // Script-import machinery is not ported — node-gi apps use ESM + gi://. These
+    // keep the surface present for source that references them (Learn6502 does not).
+    require() {
+      /* no-op: apps import via ESM / gi:// on node-gi */
+    },
+    requireSymbol() {
+      return true;
+    },
+    checkSymbol() {
+      return true;
+    },
+    start(params = {}) {
+      pkg.init(params);
+      if (typeof params.main === 'function') params.main(globalThis.ARGV ? ['', ...globalThis.ARGV] : []);
+    },
+    run() {
+      /* the app drives its own main() on node-gi */
+    },
+    initSubmodule() {
+      /* n/a on node-gi */
+    },
+  };
+
+  return pkg;
+}
+
+// A small vprintf covering the GJS `String.prototype.format` spec
+// (refs/gjs/modules/script/format.js): `%s %d %x %f`, `%.Nf` precision, `%Ns`/`%Nd`
+// width, `0`-padding for numerics, and `%%` → literal `%`. Positional `%N$s` is
+// supported (GJS honours it). Learn6502 only uses `%s`; the rest is fidelity.
+function makeVprintf() {
+  return function vprintf(fmt, args) {
+    let auto = 0;
+    return String(fmt).replace(
+      /%(?:(\d+)\$)?(0)?(\d+)?(?:\.(\d+))?([%sdxf])/g,
+      (match, pos, zero, width, prec, spec) => {
+        if (spec === '%') return '%';
+        const arg = pos !== undefined ? args[Number(pos) - 1] : args[auto++];
+        let str;
+        switch (spec) {
+          case 's':
+            str = String(arg);
+            break;
+          case 'd':
+            str = String(Math.trunc(Number(arg)));
+            break;
+          case 'x':
+            str = Math.trunc(Number(arg)).toString(16);
+            break;
+          case 'f':
+            str = prec !== undefined ? Number(arg).toFixed(Number(prec)) : String(Number(arg));
+            break;
+          default:
+            return match;
+        }
+        if (width !== undefined) {
+          const w = Number(width);
+          const pad = zero && spec !== 's' ? '0' : ' ';
+          while (str.length < w) str = pad + str;
+        }
+        return str;
+      },
+    );
+  };
+}

package/package.json

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

@@ -120,6 +120,7 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("disconnectSignal", Napi::Function::New(env, DisconnectSignal));
   exports.Set("setTemplateCallbackResolver",
               Napi::Function::New(env, SetTemplateCallbackResolver));
+  exports.Set("setConstructCallback", Napi::Function::New(env, SetConstructCallback));
   // 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));

package/src/class.cc

@@ -383,11 +383,121 @@ static void NodeGiSetProperty(GObject* obj, guint prop_id, const GValue* value,
   if (cd != nullptr && cd->parentSet != nullptr) cd->parentSet(obj, prop_id, value, pspec);
 }
 
+// ---- run the JS constructor for C/GtkBuilder-instantiated instances ----
+//
+// node-gi runs a registered class's JS constructor ONLY on a JS-side `new Sub()`
+// (the makeClass new.target path in gi.js routes it to constructType, and ES
+// super-substitution runs the ctor body). A GObject built from C — a GtkBuilder
+// composite-template InternalChild is the common case — never reaches that path,
+// so its ctor body (e.g. `this._x = …`) never runs. GJS solves this by overriding
+// the GObjectClass `constructor` vfunc so BOTH paths funnel through it
+// (refs/gjs/gi/gobject.cpp gjs_object_constructor). We mirror that: NodeGiConstructor
+// chains to the first non-node-gi C constructor to create the instance, then — only
+// for the C-driven path — runs the JS ctor on the canonical wrapper via the L1
+// construct callback. The JS-`new` path is unchanged (the latch NodeGiJsConstructing
+// is raised by ConstructGObject, so we return the instance and let makeClass run it).
+
+// Thread-local so a worker_threads env has its own latch (GtkBuilder construction
+// runs on the same thread as the ConstructGObject that raised it).
+static thread_local bool g_nodegiJsConstructing = false;
+bool NodeGiJsConstructing() { return g_nodegiJsConstructing; }
+void NodeGiSetJsConstructing(bool v) { g_nodegiJsConstructing = v; }
+
+static void RunJsConstructorForCObject(napi_env env, GObject* obj) {
+  // Teardown/terminate: never enter JS during GC/context teardown (GJS-faithful;
+  // same gate as the vfunc trampoline). The C object is still fully constructed.
+  if (!NodeGiJsAvailable(env)) return;
+  Napi::Env napiEnv(env);
+  Napi::HandleScope scope(napiEnv);
+  // JS dispatched from a pump-driven iteration must not inherit the in-iteration
+  // flag (mirrors the vfunc trampoline).
+  NodeGiPumpJsDispatchScope pumpWindow;
+
+  // Build this instance's OWN composite template first (a no-op unless it carries
+  // one), so the JS ctor's assignTemplateChildren sees bound children — the JS-`new`
+  // path does this in ConstructGObject before makeClass reads them.
+  MaybeInitTemplate(napiEnv, obj);
+
+  NodeGiEnvData* d = EnvData(env);
+  napi_value cb = nullptr;
+  if (d == nullptr || d->constructCallback == nullptr ||
+      napi_get_reference_value(env, d->constructCallback, &cb) != napi_ok || cb == nullptr) {
+    return;  // L1 hasn't registered the callback (nothing to run)
+  }
+  napi_value handleVal = WrapGObject(napiEnv, obj, GI_TRANSFER_NOTHING);
+  napi_value nameVal = nullptr;
+  napi_create_string_utf8(env, g_type_name(G_OBJECT_TYPE(obj)), NAPI_AUTO_LENGTH, &nameVal);
+  napi_value args[2] = {handleVal, nameVal};
+  napi_value undef = nullptr;
+  napi_get_undefined(env, &undef);
+  napi_value ret = nullptr;
+  // A plain call (not napi_make_callback): the ctor is synchronous and we must not
+  // drain the microtask queue mid-g_object_new. Matches GJS's template-callback
+  // resolver + gjs_object_constructor's JS::Construct (no checkpoint).
+  napi_status st = napi_call_function(env, undef, cb, 2, args, &ret);
+  if (st != napi_ok) {
+    // The ctor threw. Never leave a pending JS exception across the return into C
+    // (GObject/GtkBuilder can't handle it) — clear it and fold the message into a
+    // g_warning (GJS logs the uncaught exception here too).
+    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 constructor for %s threw: %s", g_type_name(G_OBJECT_TYPE(obj)),
+                detail.empty() ? "(no message)" : detail.c_str());
+    }
+  }
+}
+
+// The overridden GObjectClass `constructor` vfunc (installed on every registered
+// type in NodeGiClassInit). GJS parity: gi/gobject.cpp gjs_object_constructor.
+static GObject* NodeGiConstructor(GType type, guint n_construct_properties,
+                                  GObjectConstructParam* construct_properties) {
+  // Chain to the first non-node-gi (C) constructor UP the hierarchy, skipping our
+  // own — that actually allocates + constructs the instance (running the real C
+  // construction chain). GJS does the identical skip-walk (gobject.cpp:155).
+  GType parent = g_type_parent(type);
+  while (parent != 0) {
+    gpointer pk = g_type_class_peek(parent);
+    if (pk == nullptr || G_OBJECT_CLASS(pk)->constructor != NodeGiConstructor) break;
+    parent = g_type_parent(parent);
+  }
+  gpointer pk = parent != 0 ? g_type_class_peek(parent) : nullptr;
+  GObject* obj = (pk != nullptr && G_OBJECT_CLASS(pk)->constructor != nullptr)
+                     ? G_OBJECT_CLASS(pk)->constructor(type, n_construct_properties,
+                                                       construct_properties)
+                     : nullptr;
+  if (obj == nullptr) return nullptr;
+
+  // JS-`new` path: the makeClass super-substitution runs the user ctor after
+  // g_object_new returns — do NOT run it here (would double-run).
+  if (NodeGiJsConstructing()) return obj;
+
+  // C/GtkBuilder-driven: the user ctor has no other driver. Run it on the leaf
+  // registered class's env (correct across worker envs).
+  NodeGiClassData* cd = FindClassData(G_OBJECT_TYPE(obj));
+  if (cd != nullptr && cd->env != nullptr) RunJsConstructorForCObject(cd->env, obj);
+  return obj;
+}
+
 static void NodeGiClassInit(gpointer g_class, gpointer class_data) {
   NodeGiClassData* cd = static_cast<NodeGiClassData*>(class_data);
   GObjectClass* oc = G_OBJECT_CLASS(g_class);
   g_type_set_qdata(G_TYPE_FROM_CLASS(g_class), NodeGiClassDataQuark(), cd);
 
+  // Route construction through NodeGiConstructor so a C/GtkBuilder-instantiated
+  // instance (a composite-template InternalChild) gets its JS constructor run —
+  // GJS parity (gi/gobject.cpp). The JS-`new` path is unaffected: NodeGiConstructor
+  // returns early while the NodeGiJsConstructing() latch is raised.
+  oc->constructor = NodeGiConstructor;
+
   if (!cd->properties.empty()) {
     cd->parentGet = oc->get_property;  // capture before override (chain target)
     cd->parentSet = oc->set_property;
@@ -941,6 +1051,9 @@ static Napi::Value RegisterClassImpl(Napi::Env env, const std::string& name, GTy
 
   // Parse the optional { properties, signals } and build the class metadata.
   NodeGiClassData* cd = new NodeGiClassData();
+  // Stamp the registering env so NodeGiConstructor (no user_data slot) can call
+  // into JS from this class's cd for a C/GtkBuilder-instantiated instance.
+  cd->env = env;
   cd->parentGet = nullptr;
   cd->parentSet = nullptr;
   if (optsValue.IsObject()) {
@@ -1167,4 +1280,24 @@ Napi::Value ConstructType(const Napi::CallbackInfo& info) {
   return ConstructGObject(env, gtype, props, std::string(g_type_name(gtype)));
 }
 
+// setConstructCallback(cb) -> void. L1 registers the callback NodeGiConstructor
+// invokes to run a registered class's JS constructor for a C/GtkBuilder-created
+// instance: (instanceHandle, gtypeName) → Reflect.construct(class) in adopt mode
+// (see gi.js runCtorForCObject). Mirrors setTemplateCallbackResolver.
+Napi::Value SetConstructCallback(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsFunction()) {
+    Napi::TypeError::New(env, "setConstructCallback(cb: function)").ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  NodeGiEnvData* d = EnvData(env);
+  if (d == nullptr) return env.Undefined();
+  if (d->constructCallback != nullptr) {
+    napi_delete_reference(env, d->constructCallback);
+    d->constructCallback = nullptr;
+  }
+  napi_create_reference(env, info[0], 1, &d->constructCallback);
+  return env.Undefined();
+}
+
 }  // namespace nodegi

package/src/common.h

@@ -82,6 +82,13 @@ struct NodeGiEnvData {
   // (napi_make_callback already runs the checkpoint there). Per-env for the same
   // reason as errorBuilder (a napi_ref is env-specific).
   napi_ref microtaskDrain = nullptr;
+  // L1 callback that runs a registered class's JS constructor body on a
+  // pre-existing canonical wrapper — invoked by NodeGiConstructor for a GObject
+  // instantiated from C (a GtkBuilder composite-template InternalChild), whose JS
+  // ctor the node-gi JS-`new` path never reaches. (handle, gtypeName) →
+  // 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;
 };
 
 void NodeGiEnvDataFinalize(napi_env env, void* data, void* hint);
@@ -457,6 +464,11 @@ struct NodeGiClassData {
   // for the class lifetime (process-permanent, like cd itself); its JS env qdata is
   // refreshed per construction so create_closure resolves handlers in the live env.
   GObject* templateScope = nullptr;
+  // The napi_env this class was registered on. NodeGiConstructor (the overridden
+  // GObjectClass `constructor` vfunc) has no user_data slot, so it reads the env to
+  // call into JS from cd — correct even across worker envs (each registers its own
+  // class, so the leaf's cd carries the right env).
+  napi_env env = nullptr;
 
   // The cold `delete cd` failure paths (a bad GParamSpec, or g_type_register_static
   // returning 0) must not leak the owned inline-template GBytes. A destructor frees
@@ -488,6 +500,14 @@ void MaybeInitTemplate(Napi::Env env, GObject* obj);
 // its env, both above that point.
 void NodeGiInstallTemplateScopeOnClass(NodeGiClassData* cd, gpointer g_class);
 
+// A thread-local latch the node-gi JS-`new` path (ConstructGObject) raises around
+// g_object_new_with_properties. NodeGiConstructor (the overridden GObjectClass
+// `constructor` vfunc) reads it to tell a JS-driven construction — where the
+// makeClass super-substitution runs the user ctor — apart from a C/GtkBuilder-driven
+// one, where NodeGiConstructor must run the user ctor itself (see class.cc / gi.js).
+bool NodeGiJsConstructing();
+void NodeGiSetJsConstructing(bool v);
+
 // ---- N-API entry points (registered in addon.cc's Init) ----
 
 // repo.cc
@@ -546,6 +566,7 @@ Napi::Value RegisterClass(const Napi::CallbackInfo& info);
 Napi::Value RegisterClassFromGType(const Napi::CallbackInfo& info);
 Napi::Value ConstructType(const Napi::CallbackInfo& info);
 Napi::Value CallParentVfunc(const Napi::CallbackInfo& info);
+Napi::Value SetConstructCallback(const Napi::CallbackInfo& info);
 
 // template.cc
 Napi::Value GetTemplateChild(const Napi::CallbackInfo& info);

package/src/object.cc

@@ -595,7 +595,15 @@ Napi::Value ConstructGObject(Napi::Env env, GType gtype, Napi::Object props,
 
   GObject* obj = nullptr;
   if (ok) {
+    // Raise the JS-`new` latch across construction: this is the node-gi JS-driven
+    // path, where the makeClass super-substitution runs the user ctor AFTER this
+    // returns. NodeGiConstructor reads the latch and does NOT re-run the ctor (a
+    // C/GtkBuilder-driven g_object_new leaves it clear, so NodeGiConstructor runs
+    // the ctor there). Save/restore keeps a reentrant construct correct.
+    bool prevConstructing = NodeGiJsConstructing();
+    NodeGiSetJsConstructing(true);
     obj = g_object_new_with_properties(gtype, n, cnames.data(), values.data());
+    NodeGiSetJsConstructing(prevConstructing);
   }
   for (guint j = 0; j < initialised; j++) g_value_unset(&values[j]);
   g_type_class_unref(klass);

package/src/repo.cc

@@ -17,6 +17,7 @@ void NodeGiEnvDataFinalize(napi_env env, void* data, void* /*hint*/) {
     napi_delete_reference(env, d->templateCallbackResolver);
   if (d->cairoWrappers != nullptr) napi_delete_reference(env, d->cairoWrappers);
   if (d->microtaskDrain != nullptr) napi_delete_reference(env, d->microtaskDrain);
+  if (d->constructCallback != nullptr) napi_delete_reference(env, d->constructCallback);
   delete d;
 }