@gjsify/node-gi 0.44.0 → 0.46.0

package/src/calls.cc

@@ -331,9 +331,8 @@ static NodeGiCallback* CreateCallback(Napi::Env env, Napi::Function fn, GICallab
 
 // Whether `type` is a supported OUT/INOUT marshalling type for this milestone:
 // fundamentals (numbers/bool), strings (utf8/filename), GObject/interface +
-// enums/flags, struct/boxed/union (wrapped as boxed handles on return), and the
-// containers (arrays, GList/GSList/GHashTable). GError (its own roadmap PR) is
-// deferred: a clear error rather than silent mis-handling. *why receives a short
+// enums/flags, struct/boxed/union (wrapped as boxed handles on return), GError,
+// and the containers (arrays, GList/GSList/GHashTable). *why receives a short
 // type label on refusal. Declared in common.h — shared with the vfunc chain-up
 // path (class.cc CallParentVfunc), which routes each OUT/INOUT vfunc arg the same
 // way this function-invoke path does.
@@ -365,6 +364,24 @@ bool IsSupportedOutType(GITypeInfo* type, std::string* why) {
       if (iface != nullptr) gi_base_info_unref(iface);
       return ok;
     }
+    case GI_TYPE_TAG_ERROR:
+      // A plain `GError**` OUT slot — `Gst.Message.parse_error()` and the other bus
+      // accessors of the GStreamer message APIs, `GLib.set_error_literal`,
+      // `GLib.propagate_error`. Swept over the installed typelibs, EVERY GError
+      // OUT/INOUT parameter is caller_allocates=false + transfer=EVERYTHING, so
+      // this tag never reaches the caller-allocates branch above and the callee
+      // always writes a GError the caller then owns.
+      //
+      // Ownership needs nothing new: ReadOutOrReturn falls through to
+      // GIArgumentToJs's GI_TYPE_TAG_ERROR arm (marshal.cc), and G_TYPE_ERROR is a
+      // BOXED type — glib gobject/gboxed.c,
+      // `G_DEFINE_BOXED_TYPE(GError, g_error, g_error_copy, g_error_free)` — so the
+      // handle adopts a transfer-full pointer and its finalizer g_boxed_free's it
+      // (= g_error_free) exactly like any other EVERYTHING boxed OUT. A callee that
+      // leaves the slot untouched (`parse_info()` on an ERROR message) reads back as
+      // `null` and not an empty error, because `slots` is value-initialised and that
+      // arm null-guards the pointer — matching gjs.
+      return true;
     case GI_TYPE_TAG_ARRAY:
     case GI_TYPE_TAG_GLIST:
     case GI_TYPE_TAG_GSLIST:
@@ -372,7 +389,7 @@ bool IsSupportedOutType(GITypeInfo* type, std::string* why) {
       // Container OUT/return — arrays (incl. GStrv / byte arrays), GList/GSList,
       // and string-keyed GHashTable. Element-type support is checked here so an
       // exotic combo defers cleanly before the invoke.
-      return IsSupportedContainerType(type, why);
+      return IsSupportedContainerType(type, why, ContainerUse::kReadBack);
     default:
       if (why != nullptr)
         *why = "type tag " + std::to_string(static_cast<int>(gi_type_info_get_tag(type)));
@@ -581,8 +598,10 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
   // belong to the callee (dropped only when the callee never ran).
   CreatedBytes createdBytes;
   CreatedValues createdValues;
+  CreatedErrors createdErrors;
   bool ok = true;
   size_t jsCursor = 0;
+  std::vector<LengthWrite> lengthWrites;
   for (unsigned int i = 0; i < n_args && ok; i++) {
     if (skip[i]) {
       // A length arg that is OUT/INOUT: the callee writes the array length into
@@ -710,7 +729,7 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
           // that call was removed from the suite and must not come back.
           Napi::Value v = jsCursor < args.Length() ? args.Get(jsCursor) : env.Undefined();
           jsCursor++;
-          if (!IsSupportedContainerType(ti, &why)) {
+          if (!IsSupportedContainerType(ti, &why, ContainerUse::kReadBack)) {
             Napi::TypeError::New(env, displayName + ": INOUT " + why +
                                           " parameters are not yet supported")
                 .ThrowAsJavaScriptException();
@@ -758,7 +777,8 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
           jsCursor++;
           GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
           if (JsToGIArgument(env, v, ti, &slots[i], &held[i], tr, &ownedInStrings, nullptr,
-                             nullptr, nullptr, gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai)))) {
+                             nullptr, nullptr, &createdErrors,
+                             gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai)))) {
             in_args[inPos[i]].v_pointer = &slots[i];
             out_args[outPos[i]].v_pointer = &slots[i];
           } else {
@@ -825,7 +845,7 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
       if (tg == GI_TYPE_TAG_ARRAY || tg == GI_TYPE_TAG_GLIST || tg == GI_TYPE_TAG_GSLIST ||
           tg == GI_TYPE_TAG_GHASH) {
         std::string why;
-        if (!IsSupportedContainerType(ti, &why)) {
+        if (!IsSupportedContainerType(ti, &why, ContainerUse::kIn)) {
           Napi::TypeError::New(env, displayName + ": IN " + why +
                                         " parameters are not yet supported")
               .ThrowAsJavaScriptException();
@@ -842,11 +862,21 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
               unsigned int L = 0;
               if (gi_type_info_get_array_length_index(ti, &L) && L < n_args &&
                   dirs[L] == GI_DIRECTION_IN && inPos[L] >= 0) {
-                GIArgInfo* la = gi_callable_info_get_arg(callable, L);
-                GITypeInfo* lt = gi_arg_info_get_type_info(la);
-                WriteLengthValue(lt, &in_args[inPos[L]], ccount);
-                gi_base_info_unref(lt);
-                gi_base_info_unref(la);
+                long other = 0;
+                if (!RecordLengthWrite(&lengthWrites, L, ccount, &other)) {
+                  Napi::TypeError::New(
+                      env, displayName + ": two arrays share length argument " +
+                               std::to_string(L) + " but have different lengths (" +
+                               std::to_string(other) + " and " + std::to_string(ccount) + ")")
+                      .ThrowAsJavaScriptException();
+                  ok = false;
+                } else {
+                  GIArgInfo* la = gi_callable_info_get_arg(callable, L);
+                  GITypeInfo* lt = gi_arg_info_get_type_info(la);
+                  WriteLengthValue(lt, &in_args[inPos[L]], ccount);
+                  gi_base_info_unref(lt);
+                  gi_base_info_unref(la);
+                }
               }
             }
           }
@@ -854,7 +884,7 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
       } else {
         GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
         ok = JsToGIArgument(env, v, ti, &in_args[inPos[i]], &held[i], tr, &ownedInStrings,
-                            &createdClosures, &createdBytes, &createdValues,
+                            &createdClosures, &createdBytes, &createdValues, &createdErrors,
                             gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai)));
       }
     }
@@ -876,6 +906,9 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
     // Likewise every GValue boxed from a plain JS value — never adopted.
     for (GValue* gv : createdValues.transferNone) NodeGiFreeBoxedGValue(gv);
     for (GValue* gv : createdValues.transferFull) NodeGiFreeBoxedGValue(gv);
+    // Likewise every GError built from an L1 GLib.Error — never adopted.
+    for (GError* e : createdErrors.transferNone) g_error_free(e);
+    for (GError* e : createdErrors.transferFull) g_error_free(e);
     // Likewise the transfer-full-instance ref: the callee never consumed it.
     if (instanceRefTaken) g_object_unref(static_cast<GObject*>(instance));
     for (gpointer s : ownedInStrings) g_free(s);  // never reached the callee (#658)
@@ -920,6 +953,11 @@ static Napi::Value InvokeFunctionInfo(Napi::Env env, GIFunctionInfo* func, gpoin
   // box is ours to free — success AND error paths, mirroring the GBytes rule.
   // Transfer-full GValues were adopted by the callee — no release.
   for (GValue* gv : createdValues.transferNone) NodeGiFreeBoxedGValue(gv);
+  // Transfer-none GError IN-args built from an L1 GLib.Error: the callee copied
+  // what it kept (gst_message_new_error copies the GError into the message), so
+  // the build is ours to free — success AND error paths, mirroring the two rules
+  // above. Transfer-full GErrors were adopted by the callee — no release.
+  for (GError* e : createdErrors.transferNone) g_error_free(e);
   if (!success) {
     for (const InContainer& c : inContainers) FreeInContainer(c);
     // A failed invoke did not adopt the transfer-full IN/INOUT strings we g_strdup'd
@@ -1362,7 +1400,15 @@ Napi::Value ClassMethodArity(const Napi::CallbackInfo& info) {
 // CHAIN, where gjs_define_static_methods put GObjectClass's methods on
 // GObject.Object's constructor and Gtk.Button inherits them. Returns a new ref or
 // nullptr; same shape as ResolveMethodByName's parent walk above.
-static GIFunctionInfo* ResolveClassStructMethod(GIObjectInfo* objInfo, const char* name) {
+//
+// `declaringGType` receives the GType whose class struct DECLARED the method —
+// G_TYPE_OBJECT for `list_properties` — and is left untouched on a miss. That is the
+// type a receiver has to be compatible with, exactly as in gjs, where the method is
+// one function on GObject.Object's constructor and every class inherits the same one:
+// measured, `Gtk.ListItem.list_properties.call(Gtk.Widget)` answers GtkWidget's 36
+// there. Checking against the type the name was READ from would refuse that.
+static GIFunctionInfo* ResolveClassStructMethod(GIObjectInfo* objInfo, const char* name,
+                                                GType* declaringGType) {
   GIObjectInfo* walk =
       reinterpret_cast<GIObjectInfo*>(gi_base_info_ref(reinterpret_cast<GIBaseInfo*>(objInfo)));
   GIFunctionInfo* found = nullptr;
@@ -1372,7 +1418,11 @@ static GIFunctionInfo* ResolveClassStructMethod(GIObjectInfo* objInfo, const cha
       if (gi_struct_info_is_gtype_struct(cs)) found = gi_struct_info_find_method(cs, name);
       gi_base_info_unref(reinterpret_cast<GIBaseInfo*>(cs));
     }
-    if (found != nullptr) break;
+    if (found != nullptr) {
+      *declaringGType =
+          gi_registered_type_info_get_g_type(reinterpret_cast<GIRegisteredTypeInfo*>(walk));
+      break;
+    }
     GIObjectInfo* parent = gi_object_info_get_parent(walk);
     gi_base_info_unref(reinterpret_cast<GIBaseInfo*>(walk));
     walk = parent;
@@ -1396,23 +1446,39 @@ static GIFunctionInfo* ResolveClassStructMethod(GIObjectInfo* objInfo, const cha
 // call is served by the peek), while unrefing is the one call that could invalidate
 // the GParamSpecs list_properties just handed out, which the class owns. Since GLib
 // 2.84 g_type_class_unref is a documented no-op, so pairing buys nothing anyway.
-static gpointer ClassStructInstance(GIObjectInfo* objInfo) {
-  GType gtype =
-      gi_registered_type_info_get_g_type(reinterpret_cast<GIRegisteredTypeInfo*>(objInfo));
-  if (gtype == G_TYPE_INVALID) return nullptr;
+//
+// nullptr for an UNCLASSED GType (boxed/struct, interface) as well as for an absent
+// one — `g_type_class_ref` has no class to hand back there and answers nullptr after
+// a CRITICAL. It is what makes the receiver retarget below refuse safely.
+static gpointer ClassStructInstanceForGType(GType gtype) {
+  if (gtype == G_TYPE_INVALID || !G_TYPE_IS_CLASSED(gtype)) return nullptr;
   gpointer klass = g_type_class_peek(gtype);
   return klass != nullptr ? klass : g_type_class_ref(gtype);
 }
 
-// callStaticMethod(namespace, typeName, methodName, args?) -> unknown
+// callStaticMethod(namespace, typeName, methodName, args?, receiverGType?) -> unknown
 // Invoke a type-level constructor/static function (e.g. Gio.File.new_for_path,
 // Gtk.Label.new) — a function found ON a type but taking no instance. The Node
 // twin of `Ns.Class.method(...)`.
+//
+// `receiverGType` is the GType of the object the call went THROUGH (`this`), and it
+// is honoured for CLASS-STRUCT methods only. gjs defines those on the constructor
+// and marshals `this` as the GTypeClass, so the very same function object answers
+// for every class it is applied to: `GObject.Object.list_properties.call(Gtk.ListItem)`
+// reads GtkListItem's 9 pspecs, and an inherited `Subclass.list_properties()` reads the
+// SUBCLASS's. node-gi bound the name to the type it was READ from, so both spellings
+// answered the declarer's pspecs — GObject's zero — with nothing thrown (#1438). A
+// plain static (Gio.File.new_for_path) ignores `this` in gjs too, so it ignores this
+// argument here; and a receiver that is not `g_type_is_a` the DECLARING type (see
+// ResolveClassStructMethod) is ignored rather than trusted, so no C function can be
+// handed the class pointer of an unrelated type.
 Napi::Value CallStaticMethod(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   if (info.Length() < 3 || !info[0].IsString() || !info[1].IsString() || !info[2].IsString()) {
     Napi::TypeError::New(
-        env, "callStaticMethod(namespace: string, typeName: string, methodName: string, args?: unknown[])")
+        env,
+        "callStaticMethod(namespace: string, typeName: string, methodName: string, args?: unknown[], "
+        "receiverGType?: GType)")
         .ThrowAsJavaScriptException();
     return env.Null();
   }
@@ -1421,6 +1487,10 @@ Napi::Value CallStaticMethod(const Napi::CallbackInfo& info) {
   std::string method = info[2].As<Napi::String>().Utf8Value();
   Napi::Array args = (info.Length() >= 4 && info[3].IsArray()) ? info[3].As<Napi::Array>()
                                                               : Napi::Array::New(env, 0);
+  // 0 for every shape that is not a GType handle (absent, null, an ordinary object),
+  // which is the "no receiver given" case — never an error, since `this` is whatever
+  // the caller's call site happened to be.
+  GType receiverGType = info.Length() >= 5 ? ReadGTypeHandle(info[4]) : G_TYPE_INVALID;
 
   GIRepository* repo = DupDefaultRepository();
   GIBaseInfo* typeInfo = gi_repository_find_by_name(repo, ns.c_str(), tn.c_str());
@@ -1439,13 +1509,19 @@ Napi::Value CallStaticMethod(const Napi::CallbackInfo& info) {
     GIObjectInfo* objInfo = reinterpret_cast<GIObjectInfo*>(typeInfo);
     func = gi_object_info_find_method(objInfo, method.c_str());
     if (func == nullptr) {
-      func = ResolveClassStructMethod(objInfo, method.c_str());
+      GType declaringGType = G_TYPE_INVALID;
+      func = ResolveClassStructMethod(objInfo, method.c_str(), &declaringGType);
       if (func != nullptr) {
-        classInstance = ClassStructInstance(objInfo);
+        GType ownGType =
+            gi_registered_type_info_get_g_type(reinterpret_cast<GIRegisteredTypeInfo*>(objInfo));
+        const bool retarget = receiverGType != G_TYPE_INVALID && receiverGType != ownGType &&
+                              declaringGType != G_TYPE_INVALID &&
+                              g_type_is_a(receiverGType, declaringGType);
+        classInstance = ClassStructInstanceForGType(retarget ? receiverGType : ownGType);
         if (classInstance == nullptr) {
-          // No GType behind the info, so there is no class to call it on. Drop back
-          // to the plain "no static method" error rather than invoking with a null
-          // instance, which would hand the C function a null GObjectClass*.
+          // No class to call it on — no GType behind the info, or an unclassed one.
+          // Drop back to the plain "no static method" error rather than invoking with
+          // a null instance, which would hand the C function a null GObjectClass*.
           gi_base_info_unref(reinterpret_cast<GIBaseInfo*>(func));
           func = nullptr;
         }

package/src/class.cc

@@ -723,6 +723,7 @@ static Napi::Value InvokeVFuncPointer(Napi::Env env, GObject* obj, GICallableInf
   // an all-IN vfunc jsCursor == i, so the IN-only path is byte-identical to before.
   bool ok = true;
   size_t jsCursor = 0;
+  std::vector<LengthWrite> lengthWrites;
   for (unsigned int i = 0; i < nDeclared && ok; i++) {
     if (skip[i]) {
       // An OUT/INOUT array-length arg: wire its slot so the callee writes the count.
@@ -796,7 +797,7 @@ static Napi::Value InvokeVFuncPointer(Napi::Env env, GObject* obj, GICallableInf
         // transfer by ReadOutOrReturn below.
         Napi::Value v = jsCursor < args.Length() ? args.Get(jsCursor) : env.Undefined();
         jsCursor++;
-        if (!IsSupportedContainerType(ti, &why)) {
+        if (!IsSupportedContainerType(ti, &why, ContainerUse::kReadBack)) {
           Napi::TypeError::New(env, where + ": INOUT " + why +
                                         " parameters are not yet supported")
               .ThrowAsJavaScriptException();
@@ -836,7 +837,8 @@ static Napi::Value InvokeVFuncPointer(Napi::Env env, GObject* obj, GICallableInf
         jsCursor++;
         GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
         if (JsToGIArgument(env, v, ti, &slots[i], &holds[i], tr, &ownedInStrings, nullptr,
-                           nullptr, nullptr, gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai))))
+                           nullptr, nullptr, nullptr,
+                           gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai))))
           giArgs[1 + i].v_pointer = &slots[i];
         else
           ok = false;  // JsToGIArgument already threw
@@ -850,7 +852,7 @@ static Napi::Value InvokeVFuncPointer(Napi::Env env, GObject* obj, GICallableInf
       std::string why;
       Napi::Value v = jsCursor < args.Length() ? args.Get(jsCursor) : env.Undefined();
       jsCursor++;
-      if (!IsSupportedContainerType(ti, &why)) {
+      if (!IsSupportedContainerType(ti, &why, ContainerUse::kIn)) {
         Napi::TypeError::New(env, where + ": IN " + why +
                                       " parameters are not yet supported")
             .ThrowAsJavaScriptException();
@@ -866,11 +868,21 @@ static Napi::Value InvokeVFuncPointer(Napi::Env env, GObject* obj, GICallableInf
             unsigned int L = 0;
             if (gi_type_info_get_array_length_index(ti, &L) && L < nDeclared &&
                 dirs[L] == GI_DIRECTION_IN) {
-              GIArgInfo* la = gi_callable_info_get_arg(ci, L);
-              GITypeInfo* lt = gi_arg_info_get_type_info(la);
-              WriteLengthValue(lt, &giArgs[1 + L], ccount);
-              gi_base_info_unref(lt);
-              gi_base_info_unref(la);
+              long other = 0;
+              if (!RecordLengthWrite(&lengthWrites, L, ccount, &other)) {
+                Napi::TypeError::New(
+                    env, where + ": two arrays share length argument " + std::to_string(L) +
+                             " but have different lengths (" + std::to_string(other) + " and " +
+                             std::to_string(ccount) + ")")
+                    .ThrowAsJavaScriptException();
+                ok = false;
+              } else {
+                GIArgInfo* la = gi_callable_info_get_arg(ci, L);
+                GITypeInfo* lt = gi_arg_info_get_type_info(la);
+                WriteLengthValue(lt, &giArgs[1 + L], ccount);
+                gi_base_info_unref(lt);
+                gi_base_info_unref(la);
+              }
             }
           }
         }
@@ -881,7 +893,8 @@ static Napi::Value InvokeVFuncPointer(Napi::Env env, GObject* obj, GICallableInf
       jsCursor++;
       GITransfer tr = gi_arg_info_get_ownership_transfer(ai);
       ok = JsToGIArgument(env, v, ti, &giArgs[1 + i], &holds[i], tr, &ownedInStrings, nullptr,
-                          nullptr, nullptr, gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai)));
+                          nullptr, nullptr, nullptr,
+                          gi_base_info_get_name(reinterpret_cast<GIBaseInfo*>(ai)));
     }
 
     avalue.push_back(&giArgs[1 + i]);

package/src/common.h

@@ -66,6 +66,11 @@ GIRepository* DupDefaultRepository();
 // Init, freed by the instance-data finalizer at env teardown.
 struct NodeGiEnvData {
   napi_ref errorBuilder = nullptr;
+  // The CLASS the builder above constructs — L1's `GLib.Error`. Registered with
+  // the builder (one call, so the two cannot drift apart) and read the other way
+  // round: a GError-typed IN arg uses it to recognise an L1 error and rebuild a
+  // real GError from its fields. Per-env for the same reason as errorBuilder.
+  napi_ref errorClass = nullptr;
   // L1-registered resolver for Gtk.Template `<signal handler="…">` callbacks: given
   // (instanceHandle, handlerName) it returns the instance's bound JS method (or
   // undefined). Stored per-env for the same reason as errorBuilder (a napi_ref is
@@ -279,22 +284,32 @@ struct CreatedClosures {
   std::vector<GClosure*> transferFull;  // callee adopts; unref only when the callee never ran
 };
 
-// ---- JS bytes -> GBytes IN-args ----------------------------------------------
+// ---- C objects this layer SYNTHESISES for one IN argument --------------------
 //
+// Three IN arms build a throw-away C object out of a plain JS value, because the
+// JS side has no handle to hand over: a Uint8Array for a `GLib.Bytes` arg, a
+// number/string for a `GObject.Value` arg, an L1 `GLib.Error` for a `GError` arg.
+// All three carry the SAME lifetime rule, which is why they share one type
+// instead of a third near-identical struct: transfer-none → the callee borrowed
+// (or copied) it, so we release it after the invoke; transfer-full → the callee
+// adopted it, so it is released only when the invoke never ran.
+template <typename T>
+struct CreatedIn {
+  std::vector<T*> transferNone;  // release after the invoke (callee borrowed/copied)
+  std::vector<T*> transferFull;  // callee adopts; release only when the callee never ran
+  void Record(T* p, GITransfer transfer) {
+    (transfer == GI_TRANSFER_NOTHING ? transferNone : transferFull).push_back(p);
+  }
+};
+
 // A JS Uint8Array (or any TypedArray/DataView/ArrayBuffer) passed for a
 // `GLib.Bytes`-typed IN parameter (e.g. GdkPixbuf.Pixbuf.new_from_bytes,
 // g_compute_checksum_for_bytes) is COPIED into a fresh GBytes — exactly what GJS
 // does (refs/gjs/gi/arg-cache.cpp GBytesIn::in → gjs_byte_array_get_bytes →
-// g_bytes_new). Lifetime follows gjs: a transfer-none arg drops the fresh ref
-// after the invoke (GBytesInTransferNone::release → g_boxed_free; a callee that
-// kept the bytes holds its own ref), a transfer-full arg leaves the ref with the
-// callee (GBytesIn::release skips via the ignore_release mark). GBytes created
-// during an invoke are recorded here so calls.cc can release them on the right
-// path (mirrors CreatedClosures).
-struct CreatedBytes {
-  std::vector<GBytes*> transferNone;  // unref after the invoke (callee borrowed/ref'd)
-  std::vector<GBytes*> transferFull;  // callee adopts; unref only when the callee never ran
-};
+// g_bytes_new), and released per the rule above (gjs
+// GBytesInTransferNone::release → g_boxed_free; GBytesIn::release skips for
+// transfer-full via the ignore_release mark).
+using CreatedBytes = CreatedIn<GBytes>;
 
 // A plain JS value handed to a `GObject.Value` IN-arg is BOXED into a fresh
 // GValue whose GType is guessed from the JS value — exactly what GJS does
@@ -305,14 +320,18 @@ struct CreatedBytes {
 // with "Unsupported interface IN argument", because a JS number is not a boxed
 // handle. An existing GObject.Value boxed handle still routes through the
 // boxed-handle path and is passed through untouched.
-//
-// Lifetime mirrors CreatedBytes: the box is freed after the invoke for
-// transfer-none (the callee copied whatever it needed — g_object_set_property
-// copies into the property), and left with the callee for transfer-full.
-struct CreatedValues {
-  std::vector<GValue*> transferNone;  // free after the invoke (callee borrowed)
-  std::vector<GValue*> transferFull;  // callee adopts; free only when it never ran
-};
+using CreatedValues = CreatedIn<GValue>;
+
+// An L1 `GLib.Error` (what a `catch` hands you, and what `new GLib.Error(…)`
+// builds) has no `GError*` behind it — it is a JS class, not a boxed handle — so
+// a `GError`-typed IN arg gets a fresh `g_error_new_literal` built from its
+// domain/code/message. Without this, the hand-back direction the OUT direction
+// exists for is only open to errors that came OUT of GI in the first place:
+// `GLib.propagate_error(caught)` and `Gst.Message.new_error(src, caught, dbg)`
+// both refused where gjs accepts, which is the shape an application actually
+// writes. A marshalled GError (a boxed handle) still routes through
+// TransferBoxedIn and is not copied here.
+using CreatedErrors = CreatedIn<GError>;
 
 // Release a GValue this layer boxed: unset the held value (dropping the ref an
 // object/boxed/string GValue took) and free the struct. A plain `g_free` would
@@ -340,6 +359,9 @@ GClosure* NodeGiMakeGenericJsClosure(Napi::Env env, Napi::Value fn);
 // `values` (optional): enables the JS-value→GValue IN-arg boxing above; nullptr
 // (the default) keeps the previous behaviour (plain value → TypeError) on paths
 // that cannot release a created GValue.
+// `errors` (optional): enables the L1-GLib.Error→GError IN-arg build above;
+// nullptr (the default) keeps a marshalled boxed handle working and refuses the
+// L1 class, on paths that cannot release a created GError.
 // `argName` (optional): the introspected argument name, used ONLY in error
 // messages so a refusal reads like gjs's ("Expected type string for argument
 // 'name' but got type number"); nullptr degrades to a message without the name.
@@ -350,6 +372,7 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
                     CreatedClosures* closures = nullptr,
                     CreatedBytes* bytes = nullptr,
                     CreatedValues* values = nullptr,
+                    CreatedErrors* errors = nullptr,
                     const char* argName = nullptr);
 
 // ---- IN container building -----------------------------------------
@@ -362,15 +385,40 @@ struct InContainer {
   gpointer ptr;
   GITransfer transfer;
   long count;  // element count (to free C-array strings)
+  // For a by-value GValue array: the caller's own GValue per element, or nullptr where
+  // the element came from a plain JS value and there is nothing to write back to. See
+  // the write-back note in FreeInContainer — some callees FILL the cells, and the
+  // typelib does not say which.
+  std::vector<gpointer> writeBack;
 };
 
-bool IsSupportedContainerType(GITypeInfo* type, std::string* why);
+// How a container argument is used, which decides which ELEMENT kinds are
+// marshallable. The two directions are not symmetric: the IN path builds a C buffer
+// and can therefore lay out a BY-VALUE element (an enum's int, a record's own bytes),
+// while a read-back — an OUT/INOUT parameter or a return — hands the buffer to
+// ReadCElement, which still dereferences an interface element as a pointer. Passing
+// kIn where the value is later read would admit a shape that marshals in and misreads
+// out, so the caller states the direction rather than the predicate guessing it.
+enum class ContainerUse { kIn, kReadBack };
+
+bool IsSupportedContainerType(GITypeInfo* type, std::string* why, ContainerUse use);
 // Whether `type` is a supported OUT/INOUT marshalling type (fundamentals, strings,
 // object/interface/enum/flags, struct/boxed/union, and containers). Shared by the
 // function-invoke path (calls.cc) and the vfunc chain-up path (class.cc).
 bool IsSupportedOutType(GITypeInfo* type, std::string* why);
 size_t CElementSize(GITypeInfo* elem);
 void WriteLengthValue(GITypeInfo* lenType, GIArgument* slot, long n);
+
+// One IN length-argument autofill, remembered so a SECOND array naming the same length
+// argument can be checked against it rather than silently overwriting it.
+struct LengthWrite {
+  unsigned int index;
+  long count;
+};
+// Record `count` for length argument `index`. Returns false when that argument was
+// already filled with a DIFFERENT count, and reports the earlier one in *other.
+bool RecordLengthWrite(std::vector<LengthWrite>* seen, unsigned int index, long count,
+                       long* other);
 Napi::Value ReadOutOrReturn(Napi::Env env, GICallableInfo* callable, GITypeInfo* ti,
                             GIArgument* arg, GITransfer transfer,
                             std::vector<GIArgument>* slots);
@@ -582,6 +630,8 @@ Napi::Value BoxedMemberKind(const Napi::CallbackInfo& info);
 Napi::Value GetBoxedField(const Napi::CallbackInfo& info);
 Napi::Value SetBoxedField(const Napi::CallbackInfo& info);
 Napi::Value BoxedTypeName(const Napi::CallbackInfo& info);
+// TEST-ONLY (see marshal.cc): the address a boxed handle wraps, as hex.
+Napi::Value BoxedAddress(const Napi::CallbackInfo& info);
 // GParamSpec wrapping (object.cc): a tagged GObject-fundamental handle plus its
 // name/nick/blurb/flags/value_type/owner_type/default_value accessors.
 Napi::Value MakeParamSpecHandle(Napi::Env env, GParamSpec* pspec, GITransfer transfer);