@gtkx/runtime 1.0.0 → 1.1.0

package/src/default-application.ts

@@ -0,0 +1,21 @@
+import { bind } from "./bind.js";
+import { objectT, voidT } from "./descriptors.js";
+import { GIO_LIB } from "./library.js";
+import { getHandle } from "./registry.js";
+
+const readDefaultApplication = bind(GIO_LIB, "g_application_get_default", [], objectT("borrowed"));
+const writeDefaultApplication = bind(GIO_LIB, "g_application_set_default", [objectT("borrowed")], voidT);
+
+const claimDefaultApplication = (application: object): void => {
+    writeDefaultApplication(getHandle(application));
+};
+
+const releaseDefaultApplication = (application: object): void => {
+    if (readDefaultApplication() !== application) {
+        return;
+    }
+
+    writeDefaultApplication(null);
+};
+
+export { claimDefaultApplication, releaseDefaultApplication };

package/src/descriptors.ts

@@ -89,7 +89,10 @@ type BoxedOptions = {
     size?: number;
 };
 
-/** How the callee takes a callback's closure, and how long that closure has to stay alive. */
+/**
+ * What the bindings do with a callback's return value, how the callee takes its closure, and how
+ * long that closure has to stay alive.
+ */
 type CallbackOptions = {
     /** The callee also takes a destroy notify, which frees the closure once it is done with it. */
     hasDestroy?: boolean;
@@ -107,12 +110,22 @@ type CallbackOptions = {
 type ArrayOptions = {
     /** Stride in bytes between elements stored inline in the array. */
     elementSize?: number | undefined;
+    /** Position of the argument whose buffer a cursor array points into. */
+    baseParamIndex?: number | undefined;
     /** Position of the argument carrying the element count, for a length-bounded array. */
     sizeParamIndex?: number | undefined;
     /** Element count of a fixed-length array. */
     fixedSize?: number | undefined;
 };
 
+/** Where a cursor array's base buffer and total length come from. */
+type CursorBounds = {
+    /** Position of the argument holding the buffer the cursor points into. */
+    baseParamIndex: number;
+    /** Position of the argument carrying that buffer's element count. */
+    sizeParamIndex: number;
+};
+
 /** How a ref-counted fundamental value is named, wrapped and stored. */
 type FundamentalOptions = {
     /** Whether a decoded value is owned by the caller; defaults to `"borrowed"`. */
@@ -125,6 +138,12 @@ type FundamentalOptions = {
     isInline?: boolean;
 };
 
+type FundamentalLifecycle = {
+    sharedLibrary: string;
+    refFnName: string;
+    unrefFnName: string;
+};
+
 /** How a plain C struct is stored and wrapped. */
 type StructOptions = {
     /** The caller owns the storage the callee fills, so a decoded value is borrowed instead of copied. */
@@ -171,6 +190,7 @@ const voidT: VoidDescriptor = { kind: "void" };
 const unicharT: UnicharDescriptor = { kind: "unichar" };
 /** Descriptor for an opaque `gpointer`, taken from a typed array's memory or a numeric address. */
 const bufferT: BufferDescriptor = { kind: "buffer" };
+const fundamentalLifecycles: Map<string, FundamentalLifecycle> = new Map();
 
 /**
  * Builds a descriptor for a C string, whose optional length sizes the caller-allocated buffer
@@ -280,6 +300,15 @@ const structT = (ownership: Ownership = "borrowed", options: StructOptions = {})
     return result;
 };
 
+const recordFundamentalLifecycle = (typeName: string, lifecycle: FundamentalLifecycle): void => {
+    if (!fundamentalLifecycles.has(typeName)) {
+        fundamentalLifecycles.set(typeName, lifecycle);
+    }
+};
+
+const fundamentalLifecycleFor = (typeName: string): FundamentalLifecycle | undefined =>
+    fundamentalLifecycles.get(typeName);
+
 /** Builds a descriptor for a fundamental type whose lifetime is managed by named ref and unref functions. */
 const fundamentalT = (
     sharedLibrary: string,
@@ -292,6 +321,7 @@ const fundamentalT = (
 
     if (options.typeName !== undefined) {
         result.typeName = options.typeName;
+        recordFundamentalLifecycle(options.typeName, { sharedLibrary, refFnName, unrefFnName });
     }
 
     if (options.wrapperClass !== undefined) {
@@ -318,6 +348,10 @@ const arrayT = (
         result.elementSize = options.elementSize;
     }
 
+    if (options?.baseParamIndex !== undefined) {
+        result.baseParamIndex = options.baseParamIndex;
+    }
+
     if (options?.sizeParamIndex !== undefined) {
         result.sizeParamIndex = options.sizeParamIndex;
     }
@@ -361,6 +395,17 @@ const sizedArrayT = (
     elementSize?: number,
 ): ArrayDescriptor => arrayT(itemDescriptor, "sized", ownership, { sizeParamIndex, elementSize });
 
+/**
+ * Builds a descriptor for an out pointer into the buffer another argument supplied, decoded as the
+ * elements from where it points to the end of that buffer.
+ */
+const cursorArrayT = (
+    itemDescriptor: Descriptor,
+    bounds: CursorBounds,
+    ownership: Ownership = "borrowed",
+    elementSize?: number,
+): ArrayDescriptor => arrayT(itemDescriptor, "cursor", ownership, { ...bounds, elementSize });
+
 /** Builds a descriptor for a C array of a fixed length. */
 const fixedArrayT = (
     itemDescriptor: Descriptor,
@@ -369,33 +414,41 @@ const fixedArrayT = (
     elementSize?: number,
 ): ArrayDescriptor => arrayT(itemDescriptor, "fixed", ownership, { fixedSize, elementSize });
 
-/** Builds a descriptor for a function pointer, marshalling a JavaScript function into a native closure. */
-const callbackT = (
-    argDescriptors: Descriptor[],
-    returnDescriptor: Descriptor,
-    options?: CallbackOptions,
-): CallbackDescriptor => {
-    const result: CallbackDescriptor = { kind: "callback", argDescriptors, returnDescriptor };
-
-    if (options?.hasDestroy !== undefined) {
+const applyClosureOptions = (result: CallbackDescriptor, options: CallbackOptions): void => {
+    if (options.hasDestroy !== undefined) {
         result.hasDestroy = options.hasDestroy;
     }
 
-    if (options?.destroyKind !== undefined) {
+    if (options.destroyKind !== undefined) {
         result.destroyKind = options.destroyKind;
     }
 
-    if (options?.hasUserData !== undefined) {
+    if (options.hasUserData !== undefined) {
         result.hasUserData = options.hasUserData;
     }
 
-    if (options?.userDataIndex !== undefined) {
+    if (options.userDataIndex !== undefined) {
         result.userDataIndex = options.userDataIndex;
     }
 
-    if (options?.scope !== undefined) {
+    if (options.scope !== undefined) {
         result.scope = options.scope;
     }
+};
+
+/** Builds a descriptor for a function pointer, marshalling a JavaScript function into a native closure. */
+const callbackT = (
+    argDescriptors: Descriptor[],
+    returnDescriptor: Descriptor,
+    options?: CallbackOptions,
+): CallbackDescriptor => {
+    const result: CallbackDescriptor = { kind: "callback", argDescriptors, returnDescriptor };
+
+    if (options === undefined) {
+        return result;
+    }
+
+    applyClosureOptions(result, options);
 
     return result;
 };
@@ -426,6 +479,7 @@ export {
     flagsT,
     boxedT,
     structT,
+    fundamentalLifecycleFor,
     fundamentalT,
     arrayT,
     listT,
@@ -435,6 +489,7 @@ export {
     byteArrayT,
     sizedArrayT,
     fixedArrayT,
+    cursorArrayT,
     callbackT,
     type BoxedDescriptor,
     type StructDescriptor,

package/src/exit-hook.ts

@@ -1,3 +1,21 @@
 import { quit } from "./lifecycle.js";
 
+const TERMINATION_SIGNALS: NodeJS.Signals[] = ["SIGHUP", "SIGINT", "SIGTERM"];
+
+const isSoleHandler = (signal: NodeJS.Signals): boolean => process.listenerCount(signal) === 1;
+
+const quitOnSignal = (signal: NodeJS.Signals): void => {
+    if (!isSoleHandler(signal)) {
+        return;
+    }
+
+    quit();
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+};
+
 process.on("exit", quit);
+
+for (const signal of TERMINATION_SIGNALS) {
+    process.on(signal, quitOnSignal);
+}

package/src/fn.ts

@@ -8,7 +8,7 @@ import { checkError } from "./error.js";
 import { LIB } from "./library.js";
 import { fromNative } from "./native-value.js";
 import { getHandle } from "./registry.js";
-import { packTupleResult } from "./tuple.js";
+import { hasSurfacedPrimary, packTupleResult } from "./tuple.js";
 
 /** The signature a native function is bound against. */
 type FnSpec = {
@@ -16,6 +16,11 @@ type FnSpec = {
     args: Arg[];
     /** Descriptor for the C return value, packed first when output arguments are also returned. */
     returns: Descriptor;
+    /**
+     * The callee returns a value the bindings do not surface, so the call is made against the
+     * declared return type and the value is dropped instead of being packed into the result.
+     */
+    isReturnSkipped?: boolean;
     /** The function takes a trailing `GError**`, whose contents are thrown as an error on return. */
     canThrow?: boolean;
     /**
@@ -135,15 +140,19 @@ const resizeInputs = (inputs: unknown[], argCount: number): unknown[] => {
 const directCallable = (
     descriptor: ExternalObject<CallDescriptor>,
     returnDescriptor: Descriptor,
+    hasPrimary: boolean,
     argCount: number,
 ): ((...inputs: unknown[]) => unknown) => {
-    if (returnDescriptor.kind === "void") {
-        return (...inputs) => {
-            call(descriptor, resizeInputs(inputs, argCount));
-        };
+    const marshal = (inputs: unknown[]): unknown =>
+        fromNative(returnDescriptor, call(descriptor, resizeInputs(inputs, argCount)));
+
+    if (hasPrimary) {
+        return (...inputs) => marshal(inputs);
     }
 
-    return (...inputs) => fromNative(returnDescriptor, call(descriptor, resizeInputs(inputs, argCount)));
+    return (...inputs) => {
+        marshal(inputs);
+    };
 };
 
 function fromNativeCallable(
@@ -152,20 +161,21 @@ function fromNativeCallable(
     getRefSeeds?: () => RefSeeds | undefined,
 ): (...inputs: unknown[]) => unknown {
     const { args, returns: returnDescriptor, canThrow = false } = spec;
-    const hasPrimary = returnDescriptor.kind !== "void";
+    const hasPrimary = hasSurfacedPrimary(returnDescriptor, spec.isReturnSkipped);
     const plans = buildArgSpecs(args);
     const outPlans = plans.filter((plan) => plan.isOutParam);
     const arePassThrough = plans.every((plan, index) => isPassThroughPlan(plan, index));
 
     if (!canThrow && arePassThrough) {
-        return directCallable(descriptor, returnDescriptor, plans.length);
+        return directCallable(descriptor, returnDescriptor, hasPrimary, plans.length);
     }
 
-    const shape = (inputs: unknown[], nativeValues: unknown[], nativeResult: unknown): unknown => {
-        const primary = hasPrimary ? fromNative(returnDescriptor, nativeResult) : undefined;
-
-        return packTupleResult(readOutParams(outPlans, inputs, nativeValues), primary, hasPrimary);
-    };
+    const shape = (inputs: unknown[], nativeValues: unknown[], nativeResult: unknown): unknown =>
+        packTupleResult(
+            readOutParams(outPlans, inputs, nativeValues),
+            fromNative(returnDescriptor, nativeResult),
+            hasPrimary,
+        );
 
     if (canThrow) {
         return (...inputs) => {

package/src/folded-lengths.ts

@@ -0,0 +1,64 @@
+import type { Descriptor } from "@gtkx/native";
+
+type LengthSource = { kind: "return" } | { kind: "outArg"; argIndex: number };
+type LengthSources = Map<number, LengthSource[]>;
+
+type FoldedLengthSpec = {
+    argDescriptors: Descriptor[];
+    returnDescriptor: Descriptor;
+    userDataIndex?: number | undefined;
+};
+
+const sizedArrayLengthIndex = (descriptor: Descriptor): number | undefined =>
+    descriptor.kind === "array" && descriptor.arrayKind === "sized" ? descriptor.sizeParamIndex : undefined;
+
+const outArgLengthIndex = (descriptor: Descriptor | undefined): number | undefined =>
+    descriptor?.kind === "ref" ? sizedArrayLengthIndex(descriptor.innerDescriptor) : undefined;
+
+const effectiveArgIndex = (argIndex: number | undefined, userDataIndex: number | undefined): number | undefined => {
+    if (argIndex === undefined || userDataIndex === undefined || argIndex < userDataIndex) {
+        return argIndex;
+    }
+
+    return argIndex === userDataIndex ? undefined : argIndex - 1;
+};
+
+const addLengthSource = (sources: LengthSources, index: number | undefined, source: LengthSource): void => {
+    if (index === undefined) {
+        return;
+    }
+
+    const existing = sources.get(index);
+
+    if (existing === undefined) {
+        sources.set(index, [source]);
+
+        return;
+    }
+
+    existing.push(source);
+};
+
+const addOutArgLengthSources = (sources: LengthSources, spec: FoldedLengthSpec): void => {
+    const { userDataIndex } = spec;
+
+    for (const [declaredIndex, descriptor] of spec.argDescriptors.entries()) {
+        const argIndex = effectiveArgIndex(declaredIndex, userDataIndex);
+
+        if (argIndex !== undefined) {
+            const lengthIndex = effectiveArgIndex(outArgLengthIndex(descriptor), userDataIndex);
+            addLengthSource(sources, lengthIndex, { kind: "outArg", argIndex });
+        }
+    }
+};
+
+const foldedLengthSources = (spec: FoldedLengthSpec): LengthSources => {
+    const sources: LengthSources = new Map();
+    const returnLengthIndex = effectiveArgIndex(sizedArrayLengthIndex(spec.returnDescriptor), spec.userDataIndex);
+    addLengthSource(sources, returnLengthIndex, { kind: "return" });
+    addOutArgLengthSources(sources, spec);
+
+    return sources;
+};
+
+export { foldedLengthSources, type LengthSource, type LengthSources };

package/src/internal.ts

@@ -1,4 +1,5 @@
 export { checkError, createErrorDomain } from "./error.js";
+export { type ApplicationInstance, getApplicationInstance } from "./lifecycle.js";
 export { registerClassType, resolveWrapperClass, wrapHandle } from "./registry.js";
 export { hasSignalListener } from "./signal.js";
 export { resolveType } from "./type.js";

package/src/library.ts

@@ -1,6 +1,7 @@
 import { type BoxedDescriptor, boxedT, type FundamentalDescriptor, fundamentalT } from "./descriptors.js";
 
 const LIB = "libgobject-2.0.so.0,libglib-2.0.so.0";
+const GIO_LIB = "libgio-2.0.so.0";
 const VALUE_SIZE = 24;
 const CLOSURE_SIZE = 32;
 const VALUE_T: BoxedDescriptor = boxedT("GValue", { sharedLibrary: LIB, getTypeFnName: "g_value_get_type" });
@@ -15,4 +16,4 @@ const VARIANT_T: FundamentalDescriptor = fundamentalT(LIB, "g_variant_ref", "g_v
     typeName: "GVariant",
 });
 
-export { CLOSURE_SIZE, LIB, VALUE_SIZE, VALUE_T, PARAM_T, VARIANT_T };
+export { CLOSURE_SIZE, GIO_LIB, LIB, VALUE_SIZE, VALUE_T, PARAM_T, VARIANT_T };

package/src/lifecycle.ts

@@ -1,5 +1,6 @@
 import { keepAlive, quit as nativeQuit } from "@gtkx/native";
 import { isDerivedApplication, type LocalCommandLineApplication, shutDownThroughRun } from "./application-class.js";
+import { claimDefaultApplication, releaseDefaultApplication } from "./default-application.js";
 
 /**
  * The GIO and GTK application surface {@link runApplication} and {@link quitApplication} drive, so any
@@ -30,6 +31,8 @@ type ApplicationLike = {
     emit(signal: "shutdown"): unknown;
 };
 
+type ApplicationInstance = "primary" | "remote" | "shutDown" | "unregistered";
+
 /** What {@link runApplication} reports about the process it just started. */
 type RunApplicationResult = {
     /** Whether this process owns the application ID and may build a user interface. */
@@ -40,6 +43,7 @@ type RunApplicationResult = {
 
 const shutdownCallbacks: (() => void)[] = [];
 const startedApplications: WeakSet<object> = new WeakSet();
+const registeredApplications: WeakSet<object> = new WeakSet();
 const shutDownApplications: WeakSet<object> = new WeakSet();
 /**
  * Runs every registered exit callback and shuts down the native runtime. Safe to
@@ -101,6 +105,14 @@ const restartApplication = (application: ApplicationLike): number => {
     return 0;
 };
 
+const getApplicationInstance = (application: ApplicationLike): ApplicationInstance => {
+    if (!application.getIsRegistered()) {
+        return registeredApplications.has(application) ? "shutDown" : "unregistered";
+    }
+
+    return application.getIsRemote?.() === true ? "remote" : "primary";
+};
+
 /**
  * Hands `argv` to GLib's own command line handling, which parses the application's options, prints
  * `--help`, runs `handle-local-options`, registers the application, and either activates it or
@@ -119,6 +131,13 @@ const restartApplication = (application: ApplicationLike): number => {
  * user interface may be built here, because a remote application has no `GtkApplicationImpl` and
  * attaching a window to it crashes.
  *
+ * The application also claims the process-wide default `Gio.Application.getDefault()` returns, before
+ * its command line is parsed, so an `activate` handler and anything the host reads afterwards see the
+ * application being started rather than an earlier one. That holds whether the start ends registered,
+ * remote or unregistered: a refused command line still has to be reportable through the default, which
+ * is how `gtkx dev` learns which application its entry mounted. {@link quitApplication} gives the
+ * default back up, since GLib drops it only at finalize.
+ *
  * @param application The application to start.
  * @param argv The command line, whose first entry names the program as `--help` should print it.
  * @returns Whether this process may build a user interface, and the status to exit with.
@@ -132,11 +151,19 @@ const runApplication = (application: ApplicationLike, argv: string[]): RunApplic
         );
     }
 
+    claimDefaultApplication(application);
+
     const exitStatus = startedApplications.has(application)
         ? restartApplication(application)
         : startApplication(application, argv);
 
-    const isPrimary = application.getIsRegistered() && application.getIsRemote?.() !== true;
+    const instance = getApplicationInstance(application);
+
+    if (instance !== "unregistered") {
+        registeredApplications.add(application);
+    }
+
+    const isPrimary = instance === "primary";
 
     if (isPrimary) {
         keepAlive(true);
@@ -145,18 +172,7 @@ const runApplication = (application: ApplicationLike, argv: string[]): RunApplic
     return { isPrimary, exitStatus };
 };
 
-/**
- * Detaches every window from the application and runs GLib's own shutdown, which emits `shutdown`,
- * destroys the application implementation and releases the D-Bus registration. Does nothing for an
- * application that is not registered, so a repeated call is a no-op.
- *
- * GLib's own shutdown is reachable once per application: reaching it marks the application as
- * quitting, which GLib never undoes. An application that has already quit falls back to emitting
- * `shutdown`, which releases the runtime and leaves the registration for GLib to drop at finalize.
- *
- * @param application The application to shut down.
- */
-const quitApplication = (application: ApplicationLike): void => {
+const tearDownApplication = (application: ApplicationLike): void => {
     if (!application.getIsRegistered() || shutDownApplications.has(application)) {
         return;
     }
@@ -175,4 +191,34 @@ const quitApplication = (application: ApplicationLike): void => {
     }
 };
 
-export { onExit, quit, runApplication, quitApplication, type ApplicationLike, type RunApplicationResult };
+/**
+ * Detaches every window from the application and runs GLib's own shutdown, which emits `shutdown`,
+ * destroys the application implementation and releases the D-Bus registration. Does nothing for an
+ * application that is not registered, so a repeated call is a no-op.
+ *
+ * GLib's own shutdown is reachable once per application: reaching it marks the application as
+ * quitting, which GLib never undoes. An application that has already quit falls back to emitting
+ * `shutdown`, which releases the runtime and leaves the registration for GLib to drop at finalize.
+ *
+ * The process-wide default {@link runApplication} claimed is given up whichever of those paths the
+ * application took, including the ones that have no teardown left to do, so
+ * `Gio.Application.getDefault()` never hands back an application that has been torn down or that
+ * never registered in the first place. GLib clears that default only at finalize, which a
+ * garbage-collected wrapper reaches arbitrarily late or never.
+ *
+ * @param application The application to shut down.
+ */
+const quitApplication = (application: ApplicationLike): void => {
+    tearDownApplication(application);
+    releaseDefaultApplication(application);
+};
+
+export {
+    getApplicationInstance,
+    onExit,
+    quit,
+    runApplication,
+    quitApplication,
+    type ApplicationInstance,
+    type RunApplicationResult,
+};

package/src/listeners.ts

@@ -11,10 +11,10 @@ type SignalConnectable = {
     disconnect(handlerId: number): void;
 };
 
-const listenerTable: WeakMap<object, Map<string, Map<SignalHandler, number>>> = new WeakMap();
+const listenerTable: WeakMap<object, Map<string, Map<SignalHandler, number[]>>> = new WeakMap();
 
 const findListenerHandlerId = (instance: object, signal: string, handler: SignalHandler): number | undefined =>
-    listenerTable.get(instance)?.get(signal)?.get(handler);
+    listenerTable.get(instance)?.get(signal)?.get(handler)?.at(-1);
 
 const trackListener = (instance: object, signal: string, handler: SignalHandler, handlerId: number): void => {
     let bySignal = listenerTable.get(instance);
@@ -31,7 +31,24 @@ const trackListener = (instance: object, signal: string, handler: SignalHandler,
         bySignal.set(signal, byHandler);
     }
 
-    byHandler.set(handler, handlerId);
+    let handlerIds = byHandler.get(handler);
+
+    if (!handlerIds) {
+        handlerIds = [];
+        byHandler.set(handler, handlerIds);
+    }
+
+    handlerIds.push(handlerId);
+};
+
+const removeTrackedHandlerId = (handlerIds: number[], handlerId: number): number => {
+    const index = handlerIds.lastIndexOf(handlerId);
+
+    if (index !== -1) {
+        handlerIds.splice(index, 1);
+    }
+
+    return handlerIds.length;
 };
 
 const untrackHandlerId = (instance: object, signal: string, handlerId: number): void => {
@@ -42,8 +59,8 @@ const untrackHandlerId = (instance: object, signal: string, handlerId: number):
         return;
     }
 
-    for (const [handler, id] of byHandler) {
-        if (id === handlerId) {
+    for (const [handler, handlerIds] of byHandler) {
+        if (removeTrackedHandlerId(handlerIds, handlerId) === 0) {
             byHandler.delete(handler);
         }
     }

package/src/native-value.ts

@@ -1,6 +1,6 @@
 import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
 import type { ArrayDescriptor, FundamentalDescriptor, HashTableDescriptor, StructDescriptor } from "./descriptors.js";
-import { getHandle, getWrapperClass, wrapHandle, wrapObject } from "./registry.js";
+import { getHandle, getWrapperClass, wrapCallScopedObject, wrapHandle, wrapObject } from "./registry.js";
 import { resolveDescriptorType } from "./type.js";
 
 type MarshalledKind = "object" | "struct" | "boxed" | "fundamental" | "array" | "hashtable";
@@ -76,7 +76,7 @@ function fromNative(descriptor: Descriptor, value: unknown): unknown {
 
     switch (descriptor.kind) {
         case "object": {
-            return wrapObject(value);
+            return descriptor.isCallScoped === true ? wrapCallScopedObject(value) : wrapObject(value);
         }
         case "struct": {
             return wrapHandle(value as ExternalObject<Handle> | null, (descriptor as StructDescriptor).wrapperClass);

package/src/object.ts

@@ -121,7 +121,9 @@ function constructPropertyForEntry(
  * that name, dashed or camelCased, and is skipped when the type installs none.
  * A value that ParamSpec would refuse throws before GObject sees it: a `TypeError`
  * for a read-only property and for a value of a type the property cannot hold, and
- * a `RangeError` for a value the ParamSpec rejects.
+ * a `RangeError` for a value the ParamSpec rejects. A value marshalled through a
+ * declared descriptor is converted rather than checked, so a `null` handed to a
+ * numeric one of those lands 0 rather than being refused.
  * Properties whose value is `undefined` are skipped. A type registered with
  * `registerClass` binds the wrapper before its `constructed` slot runs, so an
  * override of that slot already sees a usable instance.
@@ -168,7 +170,10 @@ function getObjectProperty(obj: object, propertyName: string, descriptor: Descri
 
 /**
  * Writes a JavaScript value to a GObject property, converting it to native form
- * using the descriptor.
+ * using the descriptor. The descriptor converts what it is given rather than checking it against
+ * the property's `GObject.ParamSpec`, so `null` and `undefined` written to a numeric or enum
+ * property land 0, where the same write to a property installed through `registerClass` is
+ * refused with a `TypeError`.
  *
  * @param obj The object to write to.
  * @param propertyName The property name.