@gjsify/node-gi 0.13.0 → 0.20.0

package/src/private.cc

@@ -0,0 +1,351 @@
+// SPDX-License-Identifier: MIT
+// GjsPrivate-mirroring helpers: the structured-log writer func + the
+// bind_property_full / BindingGroup.bind_full transform trampolines.
+//
+// Reference: refs/gjs/libgjs-private/gjs-util.c (gjs_log_set_writer_func /
+// gjs_log_writer_func_wrapper / gjs_log_set_writer_default /
+// gjs_g_object_bind_property_full / gjs_g_binding_group_bind_full). GJS routes
+// these APIs through a private C library instead of introspection because:
+//   • a GLogWriterFunc can fire on ANY thread, but JS only runs on the thread
+//     that registered the writer — off-thread logs must fall back to the default
+//     writer in C, before any JS is entered;
+//   • the GLogField array (key + length-or-NUL-terminated value) is not
+//     generically introspectable — the C wrapper converts it field-by-field;
+//   • the binding transform's `to_value` is a WRITE-BACK GValue pre-initialised
+//     to the target property's type; a marshaled GClosure (which unboxes GValue
+//     params, per gjs's own closure marshal) cannot reach it, so gjs — and we —
+//     use plain C transform callbacks with g_object_bind_property_full.
+// node-gi mirrors that architecture 1:1 so the JS-visible contract matches gjs
+// byte-for-byte (verified: scratch gold runs vs gjs 1.88 — see the test file).
+
+#include <cstring>
+
+#include "common.h"
+
+namespace nodegi {
+
+// ---- GLib.log_set_writer_func ----------------------------------------------
+//
+// Process-global writer state, mirroring gjs-util.c's statics. GLib enforces at
+// most ONE g_log_set_writer_func call per process (a second call is a fatal
+// g_error — gjs behaves identically), so a single static slot is faithful.
+static bool g_logWriterCleared = false;
+static napi_env g_logWriterEnv = nullptr;
+static napi_ref g_logWriterFn = nullptr;
+static GThread* g_logWriterThread = nullptr;
+
+// Env teardown with the writer still installed: logs after this point must go to
+// the default writer, and the napi_ref must not be touched on a dead env.
+static void LogWriterEnvCleanup(void* arg) {
+  if (g_logWriterEnv != static_cast<napi_env>(arg)) return;
+  g_logWriterCleared = true;
+  // Deleting the ref during env cleanup is safe (the env is still tearing down,
+  // not freed); afterwards the wrapper never dereferences it again.
+  if (g_logWriterFn != nullptr) {
+    napi_delete_reference(g_logWriterEnv, g_logWriterFn);
+    g_logWriterFn = nullptr;
+  }
+  g_logWriterEnv = nullptr;
+}
+
+// The C writer installed into GLib — the twin of gjs_log_writer_func_wrapper.
+// Converts the GLogField array to a plain JS object whose values match gjs's
+// `{...stringFields.recursiveUnpack()}` shape exactly (verified vs gjs 1.88):
+//   length < 0 (NUL-terminated) → Uint8Array of strlen bytes
+//   length > 0 (binary)         → Uint8Array of length bytes
+//   length == 0                 → null (gjs packs a maybe-nothing → null)
+// and calls the JS writer as (logLevel: number, fields: object) expecting a
+// GLib.LogWriterOutput number back; UNHANDLED (or a throw, or an off-thread /
+// cleared / teardown call) falls back to g_log_writer_default.
+static GLogWriterOutput NodeGiLogWriterWrapper(GLogLevelFlags log_level, const GLogField* fields,
+                                               gsize n_fields, gpointer /*user_data*/) {
+  if (g_logWriterCleared || g_thread_self() != g_logWriterThread || g_logWriterFn == nullptr ||
+      g_logWriterEnv == nullptr) {
+    return g_log_writer_default(log_level, fields, n_fields, nullptr);
+  }
+  napi_env env = g_logWriterEnv;
+  if (!NodeGiJsAvailable(env)) {
+    return g_log_writer_default(log_level, fields, n_fields, nullptr);
+  }
+  Napi::Env napiEnv(env);
+  Napi::HandleScope scope(napiEnv);
+
+  // Field values are plain Uint8Arrays (NOT Node Buffers): gjs's recursiveUnpack
+  // of the maybe-bytestring fields yields Uint8Array — and e.g. JSON.stringify of
+  // the two differs, so the distinction is observable byte-for-byte.
+  auto bytesValue = [&](const void* data, size_t len) -> Napi::Value {
+    Napi::Uint8Array arr = Napi::Uint8Array::New(env, len);
+    if (len > 0) memcpy(arr.Data(), data, len);
+    return arr;
+  };
+  Napi::Object obj = Napi::Object::New(napiEnv);
+  for (gsize i = 0; i < n_fields; i++) {
+    const GLogField* field = &fields[i];
+    if (field->key == nullptr) continue;
+    Napi::Value value;
+    if (field->length < 0) {
+      const char* s = static_cast<const char*>(field->value);
+      value = bytesValue(s, s != nullptr ? strlen(s) : 0);
+    } else if (field->length > 0) {
+      value = bytesValue(field->value, static_cast<size_t>(field->length));
+    } else {
+      value = napiEnv.Null();
+    }
+    obj.Set(field->key, value);
+  }
+
+  napi_value fn = nullptr;
+  if (napi_get_reference_value(env, g_logWriterFn, &fn) != napi_ok || fn == nullptr) {
+    return g_log_writer_default(log_level, fields, n_fields, nullptr);
+  }
+  napi_value global = nullptr;
+  napi_get_global(env, &global);
+  napi_value args[2] = {Napi::Number::New(napiEnv, static_cast<double>(log_level)), obj};
+  napi_value ret = nullptr;
+  napi_status st = napi_make_callback(env, nullptr, global, fn, 2, args, &ret);
+  if (st != napi_ok || napiEnv.IsExceptionPending()) {
+    // A throwing writer must never wedge the logging path (nor leave a pending
+    // exception across the C boundary): surface + clear, then default-write.
+    SurfacePendingException(env, "GLib log writer func");
+    return g_log_writer_default(log_level, fields, n_fields, nullptr);
+  }
+  GLogWriterOutput output =
+      static_cast<GLogWriterOutput>(NodeGiToInt32(Napi::Value(env, ret)));
+  if (output == G_LOG_WRITER_UNHANDLED) {
+    return g_log_writer_default(log_level, fields, n_fields, nullptr);
+  }
+  return output;
+}
+
+// logSetWriterFunc(fn | null) -> void. Installs the wrapper into GLib (a second
+// call aborts inside GLib itself — "g_log_set_writer_func() called multiple
+// times" — exactly as under gjs). fn == null re-arms the default fallback.
+Napi::Value LogSetWriterFunc(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  Napi::Value fn = info.Length() >= 1 ? info[0] : env.Null();
+
+  // Replace any previous JS-side state (the GLib-side wrapper can only ever be
+  // installed once; the JS fn/env slots are ours to swap).
+  if (g_logWriterFn != nullptr && g_logWriterEnv != nullptr) {
+    napi_delete_reference(g_logWriterEnv, g_logWriterFn);
+    g_logWriterFn = nullptr;
+  }
+  g_logWriterEnv = env;
+  g_logWriterThread = g_thread_self();
+  g_logWriterCleared = false;
+  if (fn.IsFunction()) {
+    napi_create_reference(env, fn, 1, &g_logWriterFn);
+  }
+  // The cleanup hook is registered once (adding an identical fn+arg pair twice is
+  // an N-API fatal). GLib itself enforces at most one g_log_set_writer_func call
+  // per process, so a single hook covers every reachable state.
+  static bool hookAdded = false;
+  if (!hookAdded) {
+    napi_add_env_cleanup_hook(env, LogWriterEnvCleanup, env);
+    hookAdded = true;
+  }
+  g_log_set_writer_func(NodeGiLogWriterWrapper, nullptr, nullptr);
+  return env.Undefined();
+}
+
+// logSetWriterDefault() -> void. The twin of gjs_log_set_writer_default: the
+// GLib-side writer stays installed (it can never be swapped back), but every
+// subsequent log is routed to g_log_writer_default by the cleared flag.
+Napi::Value LogSetWriterDefault(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (g_logWriterFn != nullptr && g_logWriterEnv != nullptr) {
+    napi_delete_reference(g_logWriterEnv, g_logWriterFn);
+    g_logWriterFn = nullptr;
+  }
+  g_logWriterEnv = nullptr;
+  g_logWriterThread = g_thread_self();
+  g_logWriterCleared = true;
+  return env.Undefined();
+}
+
+// ---- bind_property_full / BindingGroup.bind_full ---------------------------
+//
+// The twin of gjs_g_object_bind_property_full: the JS transform functions are
+// held per binding and driven by plain C GBindingTransformFunc trampolines. The
+// JS contract (gjs gold standard, verified vs gjs 1.88):
+//   (binding, sourceValue) => [ok: boolean, targetValue]
+// — sourceValue arrives UNPACKED, a truthy ok writes targetValue into the
+// pre-initialised target GValue, [false, …] leaves the target unchanged, and a
+// non-Array return is reported (gjs logs "returned unexpected value, expecting
+// an Array") and treated as no-transform.
+struct NodeGiBindingTransforms {
+  napi_env env;
+  napi_ref toFn;    // nullptr when no transform-to
+  napi_ref fromFn;  // nullptr when no transform-from
+};
+
+static gboolean NodeGiBindingTransformInvoke(GBinding* binding, const GValue* from_value,
+                                             GValue* to_value, NodeGiBindingTransforms* data,
+                                             napi_ref fnRef) {
+  if (data == nullptr || fnRef == nullptr) return FALSE;
+  napi_env env = data->env;
+  // A binding transform fired at env teardown (a dispose cascade) must not enter
+  // JS — treat as no-transform, like the signal/callback teardown gates.
+  if (!NodeGiJsAvailable(env)) return FALSE;
+  Napi::Env napiEnv(env);
+  Napi::HandleScope scope(napiEnv);
+
+  napi_value fn = nullptr;
+  if (napi_get_reference_value(env, fnRef, &fn) != napi_ok || fn == nullptr) return FALSE;
+
+  napi_value args[2] = {WrapGObject(napiEnv, G_OBJECT(binding), GI_TRANSFER_NOTHING),
+                        GValueToJs(napiEnv, from_value)};
+  if (napiEnv.IsExceptionPending()) {
+    SurfacePendingException(env, "property binding transform");
+    return FALSE;
+  }
+  napi_value global = nullptr;
+  napi_get_global(env, &global);
+  napi_value ret = nullptr;
+  napi_status st = napi_make_callback(env, nullptr, global, fn, 2, args, &ret);
+  if (st != napi_ok || napiEnv.IsExceptionPending()) {
+    SurfacePendingException(env, "property binding transform");
+    return FALSE;
+  }
+  Napi::Value retVal(env, ret);
+  if (!retVal.IsArray()) {
+    // gjs: "Call to unnamed function (GjsPrivate.BindingTransformFunc) returned
+    // unexpected value, expecting an Array" — logged, transform treated as FALSE.
+    g_printerr("\n(node-gi) property binding transform returned unexpected value, "
+               "expecting an Array [ok, value]\n");
+    return FALSE;
+  }
+  Napi::Array arr = retVal.As<Napi::Array>();
+  if (!NodeGiToBool(arr.Get(uint32_t{0}))) return FALSE;
+  if (!JsToGValue(napiEnv, arr.Get(uint32_t{1}), to_value)) {
+    SurfacePendingException(env, "property binding transform");
+    return FALSE;
+  }
+  return TRUE;
+}
+
+static gboolean NodeGiBindingTransformTo(GBinding* binding, const GValue* from_value,
+                                         GValue* to_value, gpointer user_data) {
+  NodeGiBindingTransforms* data = static_cast<NodeGiBindingTransforms*>(user_data);
+  return NodeGiBindingTransformInvoke(binding, from_value, to_value, data,
+                                      data != nullptr ? data->toFn : nullptr);
+}
+
+static gboolean NodeGiBindingTransformFrom(GBinding* binding, const GValue* from_value,
+                                           GValue* to_value, gpointer user_data) {
+  NodeGiBindingTransforms* data = static_cast<NodeGiBindingTransforms*>(user_data);
+  return NodeGiBindingTransformInvoke(binding, from_value, to_value, data,
+                                      data != nullptr ? data->fromFn : nullptr);
+}
+
+// GDestroyNotify for the transforms — runs when the binding is destroyed
+// (unbind / source finalized). Deleting a napi_ref needs a live env; at real env
+// teardown the refs are reclaimed with the env, so skipping is leak-free.
+static void NodeGiBindingTransformsFree(gpointer user_data) {
+  NodeGiBindingTransforms* data = static_cast<NodeGiBindingTransforms*>(user_data);
+  if (data == nullptr) return;
+  if (NodeGiJsAvailable(data->env)) {
+    if (data->toFn != nullptr) napi_delete_reference(data->env, data->toFn);
+    if (data->fromFn != nullptr) napi_delete_reference(data->env, data->fromFn);
+  }
+  delete data;
+}
+
+// Shared arg parsing + invocation for bindPropertyFull / bindingGroupBindFull.
+// info: (sourceHandle|groupHandle, sourceProperty, targetHandle, targetProperty,
+//        flags, toFn|null, fromFn|null)
+static bool ParseBindFullArgs(const Napi::CallbackInfo& info, GObject** instance,
+                              std::string* sourceProp, GObject** target, std::string* targetProp,
+                              GBindingFlags* flags, NodeGiBindingTransforms** outData) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 5 || !info[1].IsString() || !info[3].IsString()) {
+    Napi::TypeError::New(env,
+                         "bindPropertyFull(handle, sourceProperty: string, targetHandle, "
+                         "targetProperty: string, flags: number, transformTo?, transformFrom?)")
+        .ThrowAsJavaScriptException();
+    return false;
+  }
+  *instance = UnwrapGObject(env, info[0]);
+  if (*instance == nullptr) return false;
+  *sourceProp = info[1].As<Napi::String>().Utf8Value();
+  *target = UnwrapGObject(env, info[2]);
+  if (*target == nullptr) return false;
+  *targetProp = info[3].As<Napi::String>().Utf8Value();
+  *flags = static_cast<GBindingFlags>(NodeGiToInt32(info[4]));
+
+  Napi::Value toFn = info.Length() >= 6 ? info[5] : env.Null();
+  Napi::Value fromFn = info.Length() >= 7 ? info[6] : env.Null();
+  bool hasTo = toFn.IsFunction();
+  bool hasFrom = fromFn.IsFunction();
+  NodeGiBindingTransforms* data = nullptr;
+  if (hasTo || hasFrom) {
+    data = new NodeGiBindingTransforms();
+    data->env = env;
+    data->toFn = nullptr;
+    data->fromFn = nullptr;
+    if (hasTo) napi_create_reference(env, toFn, 1, &data->toFn);
+    if (hasFrom) napi_create_reference(env, fromFn, 1, &data->fromFn);
+  }
+  *outData = data;
+  return true;
+}
+
+// bindPropertyFull(sourceHandle, sourceProperty, targetHandle, targetProperty,
+//                  flags, transformTo|null, transformFrom|null) -> Binding handle
+Napi::Value BindPropertyFull(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  GObject* source = nullptr;
+  GObject* target = nullptr;
+  std::string sourceProp, targetProp;
+  GBindingFlags flags = G_BINDING_DEFAULT;
+  NodeGiBindingTransforms* data = nullptr;
+  if (!ParseBindFullArgs(info, &source, &sourceProp, &target, &targetProp, &flags, &data)) {
+    return env.Null();
+  }
+  GBinding* binding = g_object_bind_property_full(
+      source, sourceProp.c_str(), target, targetProp.c_str(), flags,
+      data != nullptr && data->toFn != nullptr ? NodeGiBindingTransformTo : nullptr,
+      data != nullptr && data->fromFn != nullptr ? NodeGiBindingTransformFrom : nullptr, data,
+      data != nullptr ? NodeGiBindingTransformsFree : nullptr);
+  if (binding == nullptr) {
+    // g_object_bind_property_full already freed `data` via the destroy notify on
+    // its g_return_val_if_fail paths? It does NOT (precondition failures return
+    // before adopting user_data) — free it here so a bad property name doesn't
+    // leak the refs.
+    NodeGiBindingTransformsFree(data);
+    Napi::Error::New(env, "bind_property_full failed (unknown property?)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  // The binding return is (transfer none) — WrapGObject takes its own ref.
+  return WrapGObject(env, G_OBJECT(binding), GI_TRANSFER_NOTHING);
+}
+
+// bindingGroupBindFull(groupHandle, sourceProperty, targetHandle, targetProperty,
+//                      flags, transformTo|null, transformFrom|null) -> undefined
+// The twin of gjs_g_binding_group_bind_full (GObject.BindingGroup.bind_full).
+Napi::Value BindingGroupBindFull(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  GObject* group = nullptr;
+  GObject* target = nullptr;
+  std::string sourceProp, targetProp;
+  GBindingFlags flags = G_BINDING_DEFAULT;
+  NodeGiBindingTransforms* data = nullptr;
+  if (!ParseBindFullArgs(info, &group, &sourceProp, &target, &targetProp, &flags, &data)) {
+    return env.Undefined();
+  }
+  if (!G_IS_BINDING_GROUP(group)) {
+    NodeGiBindingTransformsFree(data);
+    Napi::TypeError::New(env, "bind_full: expected a GObject.BindingGroup instance")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  g_binding_group_bind_full(
+      G_BINDING_GROUP(group), sourceProp.c_str(), target, targetProp.c_str(), flags,
+      data != nullptr && data->toFn != nullptr ? NodeGiBindingTransformTo : nullptr,
+      data != nullptr && data->fromFn != nullptr ? NodeGiBindingTransformFrom : nullptr, data,
+      data != nullptr ? NodeGiBindingTransformsFree : nullptr);
+  return env.Undefined();
+}
+
+}  // namespace nodegi

package/src/repo.cc

@@ -0,0 +1,297 @@
+// SPDX-License-Identifier: MIT
+// Repository / introspection entry points + per-env instance-data helpers.
+
+#include "common.h"
+
+namespace nodegi {
+
+// gi_repository_dup_default() returns a new owning ref to the process-default
+// GIRepository (lazily created). Callers must g_object_unref() it.
+GIRepository* DupDefaultRepository() { return gi_repository_dup_default(); }
+
+void NodeGiEnvDataFinalize(napi_env env, void* data, void* /*hint*/) {
+  NodeGiEnvData* d = static_cast<NodeGiEnvData*>(data);
+  if (d == nullptr) return;
+  if (d->errorBuilder != nullptr) napi_delete_reference(env, d->errorBuilder);
+  if (d->templateCallbackResolver != nullptr)
+    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);
+  delete d;
+}
+
+// This env's instance data (created in Init); null only if Init's set failed.
+NodeGiEnvData* EnvData(napi_env env) {
+  void* raw = nullptr;
+  return napi_get_instance_data(env, &raw) == napi_ok ? static_cast<NodeGiEnvData*>(raw) : nullptr;
+}
+
+// requireNamespace(namespace: string, version?: string)
+//   -> { namespace: string, version: string, infoCount: number }
+//
+// Mirrors the load step every GJS gi:// / imports.gi access performs:
+// gi_repository_require() with an optional pinned version (null = let
+// GIRepository resolve the system default), then read back the resolved
+// version and the top-level info count.
+Napi::Value RequireNamespace(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "requireNamespace(namespace: string, version?: string)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  std::string ns = info[0].As<Napi::String>().Utf8Value();
+  bool has_version = info.Length() >= 2 && info[1].IsString();
+  std::string version = has_version ? info[1].As<Napi::String>().Utf8Value() : std::string();
+
+  GIRepository* repo = DupDefaultRepository();
+  GError* error = nullptr;
+  GITypelib* typelib = gi_repository_require(
+      repo, ns.c_str(), has_version ? version.c_str() : nullptr,
+      GI_REPOSITORY_LOAD_FLAG_NONE, &error);
+
+  if (typelib == nullptr) {
+    std::string message = error != nullptr ? error->message : "unknown error";
+    if (error != nullptr) g_error_free(error);
+    g_object_unref(repo);
+    Napi::Error::New(env, "Failed to require " + ns +
+                              (has_version ? (" " + version) : "") + ": " + message)
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  const char* resolved = gi_repository_get_version(repo, ns.c_str());
+  unsigned int n_infos = gi_repository_get_n_infos(repo, ns.c_str());
+
+  Napi::Object result = Napi::Object::New(env);
+  result.Set("namespace", Napi::String::New(env, ns));
+  result.Set("version", Napi::String::New(env, resolved != nullptr ? resolved : ""));
+  result.Set("infoCount", Napi::Number::New(env, static_cast<double>(n_infos)));
+
+  g_object_unref(repo);
+  return result;
+}
+
+// listInfoNames(namespace: string) -> string[]
+// Enumerates the top-level introspection infos of an already-required
+// namespace. Proves gi_repository_get_info() + gi_base_info_get_name()/unref().
+Napi::Value ListInfoNames(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "listInfoNames(namespace: string)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  std::string ns = info[0].As<Napi::String>().Utf8Value();
+  GIRepository* repo = DupDefaultRepository();
+  unsigned int n_infos = gi_repository_get_n_infos(repo, ns.c_str());
+
+  Napi::Array names = Napi::Array::New(env, n_infos);
+  for (unsigned int i = 0; i < n_infos; i++) {
+    GIBaseInfo* base = gi_repository_get_info(repo, ns.c_str(), i);
+    const char* name = gi_base_info_get_name(base);
+    names.Set(i, Napi::String::New(env, name != nullptr ? name : ""));
+    gi_base_info_unref(base);
+  }
+
+  g_object_unref(repo);
+  return names;
+}
+
+// findInfo(namespace, name) -> { kind: string } | null
+// Classify a top-level namespace member so the L1 wrapper knows whether to treat
+// it as a constructible class, a callable function, an enum, a constant, etc.
+// kind ∈ function|object|interface|struct|union|enum|flags|constant|callback|other.
+Napi::Value FindInfo(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 2 || !info[0].IsString() || !info[1].IsString()) {
+    Napi::TypeError::New(env, "findInfo(namespace: string, name: string)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  std::string ns = info[0].As<Napi::String>().Utf8Value();
+  std::string name = info[1].As<Napi::String>().Utf8Value();
+  GIRepository* repo = DupDefaultRepository();
+  GIBaseInfo* base = gi_repository_find_by_name(repo, ns.c_str(), name.c_str());
+  if (base == nullptr) {
+    g_object_unref(repo);
+    return env.Null();
+  }
+  // Order matters: GIFlagsInfo derives from GIEnumInfo, so test flags first.
+  const char* kind;
+  if (GI_IS_FUNCTION_INFO(base)) {
+    kind = "function";
+  } else if (GI_IS_FLAGS_INFO(base)) {
+    kind = "flags";
+  } else if (GI_IS_ENUM_INFO(base)) {
+    kind = "enum";
+  } else if (GI_IS_OBJECT_INFO(base)) {
+    kind = "object";
+  } else if (GI_IS_INTERFACE_INFO(base)) {
+    kind = "interface";
+  } else if (GI_IS_STRUCT_INFO(base)) {
+    kind = "struct";
+  } else if (GI_IS_UNION_INFO(base)) {
+    kind = "union";
+  } else if (GI_IS_CONSTANT_INFO(base)) {
+    kind = "constant";
+  } else if (GI_IS_CALLBACK_INFO(base)) {
+    kind = "callback";
+  } else {
+    kind = "other";
+  }
+  gi_base_info_unref(base);
+  g_object_unref(repo);
+  Napi::Object result = Napi::Object::New(env);
+  result.Set("kind", Napi::String::New(env, kind));
+  return result;
+}
+
+// getConstantValue(namespace, name) -> unknown
+// Read a namespace-level GI constant (e.g. GLib.PRIORITY_DEFAULT) and marshal it
+// to JS. The constant owns its storage, so we copy out (transfer NOTHING) then
+// free it.
+Napi::Value GetConstantValue(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 2 || !info[0].IsString() || !info[1].IsString()) {
+    Napi::TypeError::New(env, "getConstantValue(namespace: string, name: string)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  std::string ns = info[0].As<Napi::String>().Utf8Value();
+  std::string name = info[1].As<Napi::String>().Utf8Value();
+  GIRepository* repo = DupDefaultRepository();
+  GIBaseInfo* base = gi_repository_find_by_name(repo, ns.c_str(), name.c_str());
+  if (base == nullptr || !GI_IS_CONSTANT_INFO(base)) {
+    if (base != nullptr) gi_base_info_unref(base);
+    g_object_unref(repo);
+    Napi::TypeError::New(env, ns + "." + name + " is not a constant")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  GIConstantInfo* ci = reinterpret_cast<GIConstantInfo*>(base);
+  GIArgument arg;
+  gi_constant_info_get_value(ci, &arg);
+  GITypeInfo* ti = gi_constant_info_get_type_info(ci);
+  // transfer NOTHING: GIArgumentToJs copies strings (Napi::String::New) rather
+  // than g_free'ing them; gi_constant_info_free_value owns the release.
+  Napi::Value result = GIArgumentToJs(env, ti, &arg, GI_TRANSFER_NOTHING);
+  gi_constant_info_free_value(ci, &arg);
+  gi_base_info_unref(ti);
+  gi_base_info_unref(base);
+  g_object_unref(repo);
+  return result;
+}
+
+// getEnumValues(namespace, name) -> Record<string, number>
+// Enumerate an enum/flags type's members as { rawGiName: int }. The L1 wrapper
+// re-keys them GJS-style (UPPER_CASE, '-' -> '_').
+Napi::Value GetEnumValues(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 2 || !info[0].IsString() || !info[1].IsString()) {
+    Napi::TypeError::New(env, "getEnumValues(namespace: string, name: string)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  std::string ns = info[0].As<Napi::String>().Utf8Value();
+  std::string name = info[1].As<Napi::String>().Utf8Value();
+  GIRepository* repo = DupDefaultRepository();
+  GIBaseInfo* base = gi_repository_find_by_name(repo, ns.c_str(), name.c_str());
+  if (base == nullptr || !GI_IS_ENUM_INFO(base)) {
+    if (base != nullptr) gi_base_info_unref(base);
+    g_object_unref(repo);
+    Napi::TypeError::New(env, ns + "." + name + " is not an enum or flags type")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  GIEnumInfo* ei = reinterpret_cast<GIEnumInfo*>(base);
+  unsigned int n = gi_enum_info_get_n_values(ei);
+  Napi::Object result = Napi::Object::New(env);
+  for (unsigned int i = 0; i < n; i++) {
+    GIValueInfo* vi = gi_enum_info_get_value(ei, i);
+    const char* vname = gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(vi));
+    int64_t val = gi_value_info_get_value(vi);
+    result.Set(vname != nullptr ? vname : "", Napi::Number::New(env, static_cast<double>(val)));
+    gi_base_info_unref(reinterpret_cast<GIBaseInfo*>(vi));
+  }
+  gi_base_info_unref(base);
+  g_object_unref(repo);
+  return result;
+}
+
+// getErrorDomain(namespace, name) -> { name: string, quark: number } | null
+// For an enum type registered as a GError domain (e.g. Gio.IOErrorEnum), report
+// its domain quark name + numeric quark. L1 attaches these to the enum object so
+// `error.matches(Gio.IOErrorEnum, code)` can resolve the enum to its domain.
+// Returns null for a plain (non-error-domain) enum or a non-enum name.
+Napi::Value GetErrorDomain(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 2 || !info[0].IsString() || !info[1].IsString()) {
+    Napi::TypeError::New(env, "getErrorDomain(namespace: string, name: string)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  std::string ns = info[0].As<Napi::String>().Utf8Value();
+  std::string name = info[1].As<Napi::String>().Utf8Value();
+  GIRepository* repo = DupDefaultRepository();
+  GIBaseInfo* base = gi_repository_find_by_name(repo, ns.c_str(), name.c_str());
+  if (base == nullptr || !GI_IS_ENUM_INFO(base)) {
+    if (base != nullptr) gi_base_info_unref(base);
+    g_object_unref(repo);
+    return env.Null();
+  }
+  const char* domain = gi_enum_info_get_error_domain(reinterpret_cast<GIEnumInfo*>(base));
+  Napi::Value result = env.Null();
+  if (domain != nullptr) {
+    Napi::Object obj = Napi::Object::New(env);
+    obj.Set("name", Napi::String::New(env, domain));
+    obj.Set("quark", Napi::Number::New(env, static_cast<double>(g_quark_from_string(domain))));
+    result = obj;
+  }
+  gi_base_info_unref(base);
+  g_object_unref(repo);
+  return result;
+}
+
+// setErrorBuilder(builder: (domainName, domainQuark, code, message) => Error) -> void
+// Register the L1 GLib.Error factory the engine calls when a GI invoke fails, so a
+// failed sync call throws a real GLib.Error. Stored per-env (a napi_ref is env-
+// specific; the throw path is gated on the same env).
+Napi::Value SetErrorBuilder(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsFunction()) {
+    Napi::TypeError::New(env, "setErrorBuilder(builder: function)").ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  NodeGiEnvData* d = EnvData(env);
+  if (d == nullptr) return env.Undefined();  // instance data unavailable (Init failed)
+  if (d->errorBuilder != nullptr) {
+    napi_delete_reference(env, d->errorBuilder);
+    d->errorBuilder = nullptr;
+  }
+  napi_create_reference(env, info[0], 1, &d->errorBuilder);
+  return env.Undefined();
+}
+
+// prependSearchPath(path: string) -> void
+// Lets a caller add a typelib search directory before requiring (the Node twin
+// of GIRepository.prepend_search_path(); needed for non-system typelibs).
+Napi::Value PrependSearchPath(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "prependSearchPath(path: string)")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  std::string path = info[0].As<Napi::String>().Utf8Value();
+  GIRepository* repo = DupDefaultRepository();
+  gi_repository_prepend_search_path(repo, path.c_str());
+  g_object_unref(repo);
+  return env.Undefined();
+}
+
+}  // namespace nodegi