@gtkx/runtime 1.2.1 → 1.3.0

package/src/descriptors.ts

@@ -102,6 +102,11 @@ type CallbackOptions = {
     hasUserData?: boolean;
     /** Position of `user_data` among the callback's own arguments, dropped before the closure is called. */
     userDataIndex?: number;
+    /**
+     * The callback's C signature ends with a `GError**`, which receives a `GError` built from
+     * whatever the JavaScript function throws while the callback returns its failure value.
+     */
+    canThrow?: boolean;
     /** Lifetime of the closure; defaults to `notified` when `hasDestroy` is set and `call` otherwise. */
     scope?: CallbackDescriptor["scope"];
 };
@@ -118,6 +123,12 @@ type ArrayOptions = {
     fixedSize?: number | undefined;
     /** Whether the array carries raw bytes, and so decodes to a `Uint8Array` rather than to numbers. */
     isBytes?: boolean | undefined;
+    /**
+     * Whether the caller supplies the storage for a fixed-length out array: the runtime allocates
+     * a buffer of the element stride times the fixed element count, passes its pointer, and
+     * decodes the elements the callee wrote into it.
+     */
+    isCallerAllocated?: boolean | undefined;
 };
 
 /** Where a cursor array's base buffer and total length come from. */
@@ -136,6 +147,8 @@ type FundamentalOptions = {
     typeName?: string;
     /** Class a decoded value is wrapped in, instead of the one registered for `typeName`. */
     wrapperClass?: AnyClass;
+    /** The caller owns the storage the callee fills, so a decoded value is borrowed instead of acquired. */
+    isCallerAllocated?: boolean;
     /** The value is embedded in the containing struct rather than reached through a pointer. */
     isInline?: boolean;
 };
@@ -194,6 +207,9 @@ const unicharT: UnicharDescriptor = { kind: "unichar" };
 const bufferT: BufferDescriptor = { kind: "buffer" };
 const fundamentalLifecycles: Map<string, FundamentalLifecycle> = new Map();
 
+const isGtypeDescriptor = (descriptor: Descriptor): descriptor is TypeDescriptor =>
+    descriptor.kind === "biguint64" && "type" in descriptor;
+
 /**
  * Builds a descriptor for a C string, whose optional length sizes the caller-allocated buffer
  * used when the string is passed by reference.
@@ -228,13 +244,25 @@ const enumT = (sharedLibrary: string, typeFnName: string, isSigned: boolean): En
     isSigned,
 });
 
-/** Builds a descriptor for a flags type, resolving its GType from the named `get_type` function. */
-const flagsT = (sharedLibrary: string, typeFnName: string, isSigned: boolean): FlagsDescriptor => ({
-    kind: "flags",
-    sharedLibrary,
-    getTypeFnName: typeFnName,
-    isSigned,
-});
+/**
+ * Builds a descriptor for a flags type, resolving its GType from the named `get_type` function.
+ * For flags without a registered GType, pass empty library and function names and supply `mask`,
+ * the union of all valid bits, which invalid combinations are rejected against.
+ */
+const flagsT = (sharedLibrary: string, typeFnName: string, isSigned: boolean, mask?: number): FlagsDescriptor => {
+    const result: FlagsDescriptor = {
+        kind: "flags",
+        sharedLibrary,
+        getTypeFnName: typeFnName,
+        isSigned,
+    };
+
+    if (mask !== undefined) {
+        result.mask = mask;
+    }
+
+    return result;
+};
 
 const applyBoxedNames = (result: BoxedDescriptor, options: BoxedOptions): void => {
     if (options.sharedLibrary !== undefined) {
@@ -330,6 +358,10 @@ const fundamentalT = (
         result.wrapperClass = options.wrapperClass;
     }
 
+    if (options.isCallerAllocated) {
+        result.isCallerAllocated = true;
+    }
+
     if (options.isInline) {
         result.isInline = true;
     }
@@ -337,6 +369,20 @@ const fundamentalT = (
     return result;
 };
 
+const applyArrayBounds = (result: ArrayDescriptor, options: ArrayOptions): void => {
+    if (options.baseParamIndex !== undefined) {
+        result.baseParamIndex = options.baseParamIndex;
+    }
+
+    if (options.sizeParamIndex !== undefined) {
+        result.sizeParamIndex = options.sizeParamIndex;
+    }
+
+    if (options.fixedSize !== undefined) {
+        result.fixedSize = options.fixedSize;
+    }
+};
+
 /** Builds a descriptor for an array of items in one of the supported container layouts. */
 const arrayT = (
     itemDescriptor: Descriptor,
@@ -346,24 +392,22 @@ const arrayT = (
 ): ArrayDescriptor => {
     const result: ArrayDescriptor = { kind: "array", itemDescriptor, arrayKind, ownership };
 
-    if (options?.elementSize !== undefined) {
-        result.elementSize = options.elementSize;
+    if (options === undefined) {
+        return result;
     }
 
-    if (options?.baseParamIndex !== undefined) {
-        result.baseParamIndex = options.baseParamIndex;
-    }
+    applyArrayBounds(result, options);
 
-    if (options?.sizeParamIndex !== undefined) {
-        result.sizeParamIndex = options.sizeParamIndex;
+    if (options.elementSize !== undefined) {
+        result.elementSize = options.elementSize;
     }
 
-    if (options?.fixedSize !== undefined) {
-        result.fixedSize = options.fixedSize;
+    if (options.isBytes === true) {
+        result.isBytes = true;
     }
 
-    if (options?.isBytes === true) {
-        result.isBytes = true;
+    if (options.isCallerAllocated === true) {
+        result.isCallerAllocated = true;
     }
 
     return result;
@@ -428,7 +472,7 @@ const fixedArrayT = (
     options: ArrayOptions = {},
 ): ArrayDescriptor => arrayT(itemDescriptor, "fixed", ownership, { ...options, fixedSize });
 
-const applyClosureOptions = (result: CallbackDescriptor, options: CallbackOptions): void => {
+const applyClosureLifetimeOptions = (result: CallbackDescriptor, options: CallbackOptions): void => {
     if (options.hasDestroy !== undefined) {
         result.hasDestroy = options.hasDestroy;
     }
@@ -437,6 +481,14 @@ const applyClosureOptions = (result: CallbackDescriptor, options: CallbackOption
         result.destroyKind = options.destroyKind;
     }
 
+    if (options.scope !== undefined) {
+        result.scope = options.scope;
+    }
+};
+
+const applyClosureOptions = (result: CallbackDescriptor, options: CallbackOptions): void => {
+    applyClosureLifetimeOptions(result, options);
+
     if (options.hasUserData !== undefined) {
         result.hasUserData = options.hasUserData;
     }
@@ -445,8 +497,8 @@ const applyClosureOptions = (result: CallbackDescriptor, options: CallbackOption
         result.userDataIndex = options.userDataIndex;
     }
 
-    if (options.scope !== undefined) {
-        result.scope = options.scope;
+    if (options.canThrow !== undefined) {
+        result.canThrow = options.canThrow;
     }
 };
 
@@ -479,6 +531,7 @@ export {
     bigint64T,
     biguint64T,
     gtypeT,
+    isGtypeDescriptor,
     float32T,
     float64T,
     booleanT,

package/src/fn.ts

@@ -1,14 +1,16 @@
-import type { CallDescriptor, Descriptor, ExternalObject, Ref } from "@gtkx/native";
+import type { CallDescriptor, Descriptor, ExternalObject, Handle, Ref } from "@gtkx/native";
 import { call, bind as nativeBind } from "@gtkx/native";
 import type { RefSeeds } from "./vfunc-seeds.js";
-import { type Arg, isCallerAllocatedArg, isOutputArg, isRefArg, requiresInputArg } from "./arg.js";
+import { type Arg, isCallerAllocatedArg, isOutputArg, isRefArg, isUnpackedArg, requiresInputArg } from "./arg.js";
 import { wrapCallbackValue } from "./callback.js";
-import { boxedT, refT } from "./descriptors.js";
+import { boxedT, isGtypeDescriptor, refT } from "./descriptors.js";
 import { checkError } from "./error.js";
 import { LIB } from "./library.js";
-import { fromNative } from "./native-value.js";
+import { fromNative, toNative } from "./native-value.js";
 import { getHandle } from "./registry.js";
 import { hasSurfacedPrimary, packTupleResult } from "./tuple.js";
+import { TYPE_INVALID } from "./type.js";
+import { fromValue, getValueType } from "./value.js";
 
 /** The signature a native function is bound against. */
 type FnSpec = {
@@ -29,6 +31,8 @@ type FnSpec = {
      * architectures.
      */
     fixedArgCount?: number;
+    /** The callee returns a `GValue`, surfaced as what it holds rather than as the value itself. */
+    isReturnUnpacked?: boolean;
 };
 
 type ArgSpec = {
@@ -36,13 +40,18 @@ type ArgSpec = {
     index: number;
     isRef: boolean;
     isCallerAllocated: boolean;
+    isUnpacked: boolean;
     requiresInput: boolean;
     inputIndex: number;
     isOutParam: boolean;
+    carriesGtype: boolean;
 };
 
 const NO_OUT_PARAMS: unknown[] = [];
 
+const hasGtypeInput = (descriptor: Descriptor): boolean =>
+    isGtypeDescriptor(descriptor) || (descriptor.kind === "array" && isGtypeDescriptor(descriptor.itemDescriptor));
+
 const buildNativeArgTypes = (args: Arg[], canThrow: boolean): Descriptor[] => {
     const nativeArgTypes = args.map((argSpec) =>
         argSpec.direction !== undefined && argSpec.isCallerAllocated !== true ? refT(argSpec.type) : argSpec.type,
@@ -70,9 +79,11 @@ const buildArgSpecs = (args: Arg[]): ArgSpec[] => {
             index,
             isRef,
             isCallerAllocated: isCallerAllocatedArg(arg),
+            isUnpacked: isUnpackedArg(arg),
             requiresInput,
             inputIndex: requiresInput ? inputCursor++ : -1,
             isOutParam,
+            carriesGtype: hasGtypeInput(arg.type),
         };
     });
 };
@@ -83,8 +94,11 @@ const resolveCallerAllocated = (inputs: unknown[], inputIndex: number): unknown
     return wrapper == null ? wrapper : getHandle(wrapper);
 };
 
+const inputValueFor = (spec: ArgSpec, inputs: unknown[]): unknown =>
+    spec.carriesGtype ? toNative(spec.arg.type, inputs[spec.inputIndex]) : inputs[spec.inputIndex];
+
 const buildRefValue = (spec: ArgSpec, inputs: unknown[], seeds: RefSeeds | undefined): Ref => ({
-    value: spec.requiresInput ? inputs[spec.inputIndex] : (seeds?.get(spec.index) ?? null),
+    value: spec.requiresInput ? inputValueFor(spec, inputs) : (seeds?.get(spec.index) ?? null),
 });
 
 const buildNativeValue = (spec: ArgSpec, inputs: unknown[], seeds: RefSeeds | undefined): unknown => {
@@ -102,12 +116,30 @@ const buildNativeValue = (spec: ArgSpec, inputs: unknown[], seeds: RefSeeds | un
         return wrapCallbackValue(arg.type, inputs[inputIndex]);
     }
 
-    return inputs[inputIndex];
+    return inputValueFor(spec, inputs);
 };
 
 const buildNativeValues = (plans: ArgSpec[], inputs: unknown[], seeds: RefSeeds | undefined): unknown[] =>
     plans.map((plan) => buildNativeValue(plan, inputs, seeds));
 
+const unpackValueHandle = (handle: ExternalObject<Handle> | null): unknown => {
+    if (handle === null || getValueType(handle) === TYPE_INVALID) {
+        return null;
+    }
+
+    return fromValue(handle);
+};
+
+const readCallerAllocated = (plan: ArgSpec, inputs: unknown[]): unknown => {
+    const wrapper = inputs[plan.inputIndex];
+
+    if (!plan.isUnpacked) {
+        return wrapper;
+    }
+
+    return unpackValueHandle(wrapper == null ? null : getHandle(wrapper));
+};
+
 const readOutParams = (outPlans: ArgSpec[], inputs: unknown[], nativeValues: unknown[]): unknown[] => {
     if (outPlans.length === 0) {
         return NO_OUT_PARAMS;
@@ -115,7 +147,7 @@ const readOutParams = (outPlans: ArgSpec[], inputs: unknown[], nativeValues: unk
 
     return Array.from(outPlans, (plan) =>
         plan.isCallerAllocated
-            ? inputs[plan.inputIndex]
+            ? readCallerAllocated(plan, inputs)
             : fromNative(plan.arg.type, (nativeValues[plan.index] as Ref).value));
 };
 
@@ -123,8 +155,20 @@ const isPassThroughPlan = (plan: ArgSpec, index: number): boolean =>
     plan.inputIndex === index &&
     !plan.isRef &&
     !plan.isCallerAllocated &&
+    !plan.carriesGtype &&
     plan.arg.type.kind !== "callback";
 
+const requiredInputIndices = (plans: ArgSpec[]): number[] =>
+    plans.filter((plan) => plan.requiresInput && plan.arg.isRequired === true).map((plan) => plan.inputIndex);
+
+const assertRequiredInputs = (requiredIndices: number[], inputs: unknown[]): void => {
+    for (const index of requiredIndices) {
+        if (inputs[index] === undefined) {
+            throw new TypeError(`Missing required argument at position ${String(index + 1)}`);
+        }
+    }
+};
+
 const resizeInputs = (inputs: unknown[], argCount: number): unknown[] => {
     while (inputs.length < argCount) {
         inputs.push(undefined);
@@ -137,14 +181,25 @@ const resizeInputs = (inputs: unknown[], argCount: number): unknown[] => {
     return inputs;
 };
 
+const returnReader = (spec: FnSpec): ((nativeResult: unknown) => unknown) =>
+    spec.isReturnUnpacked === true
+        ? (nativeResult) => unpackValueHandle((nativeResult ?? null) as ExternalObject<Handle> | null)
+        : (nativeResult) => fromNative(spec.returns, nativeResult);
+
 const directCallable = (
     descriptor: ExternalObject<CallDescriptor>,
-    returnDescriptor: Descriptor,
+    readReturn: (nativeResult: unknown) => unknown,
     hasPrimary: boolean,
-    argCount: number,
+    plans: ArgSpec[],
 ): ((...inputs: unknown[]) => unknown) => {
-    const marshal = (inputs: unknown[]): unknown =>
-        fromNative(returnDescriptor, call(descriptor, resizeInputs(inputs, argCount)));
+    const argCount = plans.length;
+    const requiredIndices = requiredInputIndices(plans);
+
+    const marshal = (inputs: unknown[]): unknown => {
+        assertRequiredInputs(requiredIndices, inputs);
+
+        return readReturn(call(descriptor, resizeInputs(inputs, argCount)));
+    };
 
     if (hasPrimary) {
         return (...inputs) => marshal(inputs);
@@ -165,20 +220,20 @@ function fromNativeCallable(
     const plans = buildArgSpecs(args);
     const outPlans = plans.filter((plan) => plan.isOutParam);
     const arePassThrough = plans.every((plan, index) => isPassThroughPlan(plan, index));
+    const readReturn = returnReader(spec);
 
     if (!canThrow && arePassThrough) {
-        return directCallable(descriptor, returnDescriptor, hasPrimary, plans.length);
+        return directCallable(descriptor, readReturn, hasPrimary, plans);
     }
 
+    const requiredIndices = requiredInputIndices(plans);
+
     const shape = (inputs: unknown[], nativeValues: unknown[], nativeResult: unknown): unknown =>
-        packTupleResult(
-            readOutParams(outPlans, inputs, nativeValues),
-            fromNative(returnDescriptor, nativeResult),
-            hasPrimary,
-        );
+        packTupleResult(readOutParams(outPlans, inputs, nativeValues), readReturn(nativeResult), hasPrimary);
 
     if (canThrow) {
         return (...inputs) => {
+            assertRequiredInputs(requiredIndices, inputs);
             const nativeValues = buildNativeValues(plans, inputs, getRefSeeds?.());
             const errorRef: Ref = { value: null };
             nativeValues.push(errorRef);
@@ -190,6 +245,7 @@ function fromNativeCallable(
     }
 
     return (...inputs) => {
+        assertRequiredInputs(requiredIndices, inputs);
         const nativeValues = buildNativeValues(plans, inputs, getRefSeeds?.());
 
         return shape(inputs, nativeValues, call(descriptor, nativeValues));

package/src/index.ts

@@ -24,20 +24,30 @@ export {
     setObjectProperty,
 } from "./object.js";
 /** @public */
-export { promisify } from "./promisify.js";
+export { getParamSpecFlags, getParamSpecOwnerType, getParamSpecValueType } from "./param-spec.js";
 /** @public */
-export { type Interface, registerClass } from "./register-class.js";
+export { promisify, trimFinish } from "./promisify.js";
+/** @public */
+export { coerceObjectProperty, newParamSpecOverride } from "./properties.js";
+/** @public */
+export { matchAllRegex, matchRegex } from "./regex.js";
+/** @public */
+export { type Interface, registerClass, type SignalGType, type SignalSpec } from "./register-class.js";
 /** @public */
 export {
     getClassType,
     getHandle,
     getInstanceType,
     getWrapperClass,
+    peekTypeClass,
+    registerClassStruct,
     registerInterface,
     registerWrapperClass,
+    registerWrapperClassResolver,
     type StaticBase,
     setHandle,
     wrapHandle,
+    type WrapperClassResolver,
 } from "./registry.js";
 /** @public */
 export { connectSignal, disconnectSignal, emitSignal, getSignalBaseName, type SignalHandler } from "./signal.js";
@@ -79,9 +89,26 @@ export {
     valueIsA,
 } from "./type.js";
 /** @public */
-export { getBoxedValue, setBoxedValue } from "./value.js";
+export {
+    fromValue,
+    getBoxedValue,
+    type JsValue,
+    setBoxedValue,
+    toValueHandle,
+    tryToValueHandle,
+    ValueMarshalError,
+} from "./value.js";
 /** @public */
-export { fromVariant, toVariant, type VariantValue } from "./variant.js";
+export {
+    type ByteArray,
+    type FromVariantOptions,
+    fromVariant,
+    type RecursiveFromVariantOptions,
+    type RecursiveVariantValue,
+    toVariant,
+    type VariantInput,
+    type VariantValue,
+} from "./variant.js";
 /** @public */
 export { callParent, callVfunc } from "./vfunc-call.js";
 /** @public */

package/src/mixin.ts

@@ -89,4 +89,4 @@ function insertMixinLayer(target: AnyClass, mixin: Mixin, inheritedNames: Set<st
     Object.setPrototypeOf(target, layer);
 }
 
-export { insertMixinLayer, installMixins, type MixinReceiver, type Mixin };
+export { copyLayerMembers, insertMixinLayer, installMixins, type MixinReceiver, type Mixin };

package/src/native-value.ts

@@ -1,10 +1,41 @@
-import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
-import type { ArrayDescriptor, FundamentalDescriptor, HashTableDescriptor, StructDescriptor } from "./descriptors.js";
-import { getHandle, getWrapperClass, wrapCallScopedObject, wrapHandle, wrapObject } from "./registry.js";
+import type { AnyClass } from "@gtkx/utils";
+import {
+    bindFunctionPointer,
+    call,
+    type CallDescriptor,
+    type Descriptor,
+    type ExternalObject,
+    getType,
+    type Handle,
+    type Ref,
+} from "@gtkx/native";
+import {
+    type ArrayDescriptor,
+    boxedT,
+    type CallbackDescriptor,
+    type FundamentalDescriptor,
+    type HashTableDescriptor,
+    isGtypeDescriptor,
+    refT,
+    type StructDescriptor,
+} from "./descriptors.js";
+import { checkError } from "./error.js";
+import { LIB } from "./library.js";
+import {
+    coerceGType,
+    getHandle,
+    getWrapperClass,
+    resolveWrapperClass,
+    wrapCallScopedObject,
+    wrapFundamentalHandle,
+    wrapHandle,
+    wrapObject,
+} from "./registry.js";
 import { resolveDescriptorType } from "./type.js";
 
 type MarshalledKind = "object" | "struct" | "boxed" | "fundamental" | "array" | "hashtable";
 type MarshalledDescriptor = Extract<Descriptor, { kind: MarshalledKind }>;
+type DecodedCallbackTarget = { fnPtr: bigint; userData?: bigint | undefined };
 
 const MARSHALLED_KINDS: Set<Descriptor["kind"]> = new Set<MarshalledKind>([
     "object",
@@ -15,6 +46,8 @@ const MARSHALLED_KINDS: Set<Descriptor["kind"]> = new Set<MarshalledKind>([
     "hashtable",
 ]);
 
+const NULL_POINTER = 0n;
+
 function isMarshalledDescriptor(descriptor: Descriptor): descriptor is MarshalledDescriptor {
     return MARSHALLED_KINDS.has(descriptor.kind);
 }
@@ -32,18 +65,103 @@ function collectionFromNative(descriptor: ArrayDescriptor, value: unknown): unkn
 }
 
 function boxedFromNative(descriptor: Descriptor, value: unknown): unknown {
-    return value == null
-        ? null
-        : wrapHandle(value as ExternalObject<Handle>, getWrapperClass(resolveDescriptorType(descriptor)));
+    if (value == null) {
+        return null;
+    }
+
+    const handle = value as ExternalObject<Handle>;
+    const type = resolveDescriptorType(descriptor);
+
+    return wrapHandle(handle, getWrapperClass(type));
+}
+
+function fundamentalWrapperClass(descriptor: FundamentalDescriptor, handle: ExternalObject<Handle>): AnyClass {
+    if (descriptor.wrapperClass !== undefined) {
+        return descriptor.wrapperClass;
+    }
+
+    const declaredType = resolveDescriptorType(descriptor);
+
+    return resolveWrapperClass(getType(handle, declaredType)) ?? getWrapperClass(declaredType);
 }
 
 function fundamentalFromNative(descriptor: FundamentalDescriptor, value: unknown): unknown {
-    return value == null
-        ? null
-        : wrapHandle(
-                value as ExternalObject<Handle>,
-                descriptor.wrapperClass ?? getWrapperClass(resolveDescriptorType(descriptor)),
-            );
+    if (value == null) {
+        return null;
+    }
+
+    const handle = value as ExternalObject<Handle>;
+
+    return wrapFundamentalHandle(handle, fundamentalWrapperClass(descriptor, handle));
+}
+
+const errorRefDescriptor = (): Descriptor =>
+    refT(boxedT("GError", { ownership: "full", sharedLibrary: LIB, getTypeFnName: "g_error_get_type" }));
+
+function decodedCallbackValues(
+    descriptor: CallbackDescriptor,
+    target: DecodedCallbackTarget,
+    inputs: unknown[],
+): unknown[] {
+    const values: unknown[] = [];
+    let cursor = 0;
+
+    for (const [index, argDescriptor] of descriptor.argDescriptors.entries()) {
+        if (index === descriptor.userDataIndex) {
+            values.push(target.userData ?? NULL_POINTER);
+        } else {
+            values.push(toNative(argDescriptor, inputs[cursor]));
+            cursor += 1;
+        }
+    }
+
+    return values;
+}
+
+function decodedCallbackCallable(
+    descriptor: CallbackDescriptor,
+    target: DecodedCallbackTarget,
+): (...inputs: unknown[]) => unknown {
+    const canThrow = descriptor.canThrow === true;
+    const isOneShot = descriptor.scope === "async";
+    const argDescriptors = canThrow ? [...descriptor.argDescriptors, errorRefDescriptor()] : descriptor.argDescriptors;
+    let bound: ExternalObject<CallDescriptor> | undefined;
+    let isSpent = false;
+
+    return (...inputs) => {
+        if (isSpent) {
+            throw new Error("An async-scoped callback was already invoked; its native caller has released it");
+        }
+
+        bound ??= bindFunctionPointer(target.fnPtr, argDescriptors, descriptor.returnDescriptor, "decoded callback");
+        const values = decodedCallbackValues(descriptor, target, inputs);
+        isSpent = isOneShot;
+
+        if (!canThrow) {
+            return fromNative(descriptor.returnDescriptor, call(bound, values));
+        }
+
+        const errorRef: Ref = { value: null };
+        values.push(errorRef);
+        const result = call(bound, values);
+        checkError(errorRef);
+
+        return fromNative(descriptor.returnDescriptor, result);
+    };
+}
+
+function callbackFromNative(descriptor: CallbackDescriptor, value: unknown): unknown {
+    if (value == null) {
+        return value;
+    }
+
+    const target = value as Partial<DecodedCallbackTarget>;
+
+    if (typeof target.fnPtr !== "bigint") {
+        return value;
+    }
+
+    return decodedCallbackCallable(descriptor, { fnPtr: target.fnPtr, userData: target.userData });
 }
 
 function hashTableFromNative(descriptor: HashTableDescriptor, value: unknown): unknown {
@@ -64,12 +182,21 @@ function hashTableFromNative(descriptor: HashTableDescriptor, value: unknown): u
 /**
  * Converts a raw value returned from native code into its JavaScript form,
  * wrapping object, struct, boxed, and fundamental handles and recursively
- * converting arrays and hash tables according to the descriptor.
+ * converting arrays and hash tables according to the descriptor. A callback
+ * decoded from a native function pointer and its bound user data becomes a
+ * callable function that invokes the native callback; it stays valid only as
+ * long as the native caller keeps the pointer pair alive, which for an
+ * async-scoped callback means until the first invocation — calling one a
+ * second time throws instead of reaching the released native closure.
  *
  * @param descriptor Describes the native type of the value.
  * @param value The raw native value to convert.
  */
 function fromNative(descriptor: Descriptor, value: unknown): unknown {
+    if (descriptor.kind === "callback") {
+        return callbackFromNative(descriptor, value);
+    }
+
     if (!isMarshalledDescriptor(descriptor)) {
         return value;
     }
@@ -113,13 +240,18 @@ function hashTableToNative(descriptor: HashTableDescriptor, value: unknown): unk
 
 /**
  * Converts a JavaScript value into the raw form native code expects, unwrapping
- * object, struct, boxed, and fundamental wrappers back to their handles and
+ * object, struct, boxed, and fundamental wrappers back to their handles,
+ * resolving a class passed for a GType to the GType it was registered under, and
  * recursively converting arrays and maps according to the descriptor.
  *
  * @param descriptor Describes the native type to convert to.
  * @param value The JavaScript value to convert.
  */
 function toNative(descriptor: Descriptor, value: unknown): unknown {
+    if (isGtypeDescriptor(descriptor)) {
+        return coerceGType(value);
+    }
+
     if (!isMarshalledDescriptor(descriptor)) {
         return value;
     }