@gtkx/runtime 1.0.0 → 1.2.0

package/src/callback.ts

@@ -1,5 +1,6 @@
 import { copy, type Descriptor } from "@gtkx/native";
 import type { CallbackDescriptor, RefDescriptor } from "./descriptors.js";
+import { foldedLengthSources, type LengthSource, type LengthSources } from "./folded-lengths.js";
 import { fromNative, toNative } from "./native-value.js";
 import { getHandle } from "./registry.js";
 import { splitTupleResult } from "./tuple.js";
@@ -7,10 +8,12 @@ import { copyValue } from "./value.js";
 import { popSeedFrame, pushSeedFrame, type RefSeeds } from "./vfunc-seeds.js";
 
 type Callback = (...args: unknown[]) => unknown;
-type CallbackReceiver = "this" | "emitter" | "none";
+type CallbackKind = "vfunc" | "signal" | "callback";
+type CallbackTraits = { isInstanceBound: boolean; hasInstanceArg: boolean; hasFoldedLengths: boolean };
 type OutParam = { value: unknown; descriptor: Descriptor; argIndex: number };
-type LengthLink = { target: OutParam; sourceIndex: number };
+type LengthLink = { target: OutParam; sources: LengthSource[] };
 type OutParamGroups = { lengthLinks: LengthLink[]; valueParams: OutParam[] };
+type OutValues = Map<number, unknown>;
 
 type CallbackSpec = {
     argDescriptors: Descriptor[];
@@ -22,12 +25,20 @@ type CallbackPlan = {
     fn: Callback;
     effectiveTypes: Descriptor[];
     returnDescriptor: Descriptor;
+    hasPrimary: boolean;
     start: number;
-    receiver: CallbackReceiver;
+    isInstanceBound: boolean;
+    lengthSources: LengthSources;
     hasOutParams: boolean;
     hasRefOutParams: boolean;
 };
 
+const CALLBACK_TRAITS: Record<CallbackKind, CallbackTraits> = {
+    callback: { isInstanceBound: false, hasInstanceArg: false, hasFoldedLengths: true },
+    signal: { isInstanceBound: false, hasInstanceArg: true, hasFoldedLengths: false },
+    vfunc: { isInstanceBound: true, hasInstanceArg: true, hasFoldedLengths: true },
+};
+
 const fillCallerAllocatedBuffer = (descriptor: Descriptor, target: object, source: object): void => {
     if (descriptor.kind === "boxed" && descriptor.typeName === "GValue") {
         copyValue(getHandle(target), getHandle(source));
@@ -108,74 +119,58 @@ const haveOutParamArgs = (effectiveTypes: Descriptor[], start: number): boolean
 const haveRefOutParamArgs = (effectiveTypes: Descriptor[], start: number): boolean =>
     effectiveTypes.slice(start).some((descriptor) => hasRefOutParamArg(descriptor));
 
-const sizeParamIndexFor = (descriptor: Descriptor): number | undefined => {
-    if (descriptor.kind !== "ref") {
-        return undefined;
-    }
-
-    const { innerDescriptor } = descriptor;
-
-    return innerDescriptor.kind === "array" ? innerDescriptor.sizeParamIndex : undefined;
-};
-
-const lengthOutParamIndices = (outParams: OutParam[]): Map<number, number> => {
-    const indices: Map<number, number> = new Map();
+const groupOutParams = (outParams: OutParam[], lengthSources: LengthSources): OutParamGroups => {
+    const groups: OutParamGroups = { lengthLinks: [], valueParams: [] };
 
     for (const outParam of outParams) {
-        const sizeParamIndex = sizeParamIndexFor(outParam.descriptor);
+        const sources = lengthSources.get(outParam.argIndex);
 
-        if (sizeParamIndex !== undefined) {
-            indices.set(sizeParamIndex, outParam.argIndex);
+        if (sources === undefined) {
+            groups.valueParams.push(outParam);
+        } else {
+            groups.lengthLinks.push({ target: outParam, sources });
         }
     }
 
-    return indices;
+    return groups;
 };
 
-const writeOutParams = (outParams: OutParam[], outValues: unknown[]): Map<number, unknown> => {
-    const written: Map<number, unknown> = new Map();
+const getLength = (value: unknown): number => {
+    const length = (value as { length?: unknown } | null | undefined)?.length;
 
-    for (const [position, outParam] of outParams.entries()) {
-        const outValue = outValues[position];
-        const { descriptor } = outParam;
-        written.set(outParam.argIndex, outValue);
+    return typeof length === "number" ? length : 0;
+};
 
-        if (descriptor.kind === "ref") {
-            (outParam.value as { value: unknown }).value = toNative(descriptor.innerDescriptor, outValue);
-        } else if (outValue != null && outParam.value != null) {
-            fillCallerAllocatedBuffer(descriptor, outParam.value, outValue);
-        }
-    }
+const lengthSourceValue = (source: LengthSource, outValues: OutValues, primary: unknown): unknown =>
+    source.kind === "return" ? primary : outValues.get(source.argIndex);
 
-    return written;
-};
+const foldedLength = (sources: LengthSource[], outValues: OutValues, primary: unknown): number =>
+    Math.min(...sources.map((source) => getLength(lengthSourceValue(source, outValues, primary))));
 
-const groupOutParams = (outParams: OutParam[]): OutParamGroups => {
-    const lengths = lengthOutParamIndices(outParams);
-    const groups: OutParamGroups = { lengthLinks: [], valueParams: [] };
+const resolveOutValues = (groups: OutParamGroups, values: unknown[], primary: unknown): OutValues => {
+    const outValues: OutValues = new Map();
 
-    for (const outParam of outParams) {
-        const sourceIndex = lengths.get(outParam.argIndex);
+    for (const [position, outParam] of groups.valueParams.entries()) {
+        outValues.set(outParam.argIndex, values[position]);
+    }
 
-        if (sourceIndex === undefined) {
-            groups.valueParams.push(outParam);
-        } else {
-            groups.lengthLinks.push({ target: outParam, sourceIndex });
-        }
+    for (const link of groups.lengthLinks) {
+        outValues.set(link.target.argIndex, foldedLength(link.sources, outValues, primary));
     }
 
-    return groups;
+    return outValues;
 };
 
-const getFoldedLength = (source: unknown): number => {
-    const length = (source as { length?: unknown } | null | undefined)?.length;
-
-    return typeof length === "number" ? length : 0;
-};
+const writeOutParams = (outParams: OutParam[], outValues: OutValues): void => {
+    for (const outParam of outParams) {
+        const { descriptor } = outParam;
+        const outValue = outValues.get(outParam.argIndex);
 
-const writeFoldedLengths = (lengthLinks: LengthLink[], written: Map<number, unknown>): void => {
-    for (const link of lengthLinks) {
-        (link.target.value as { value: unknown }).value = getFoldedLength(written.get(link.sourceIndex));
+        if (descriptor.kind === "ref") {
+            (outParam.value as { value: unknown }).value = toNative(descriptor.innerDescriptor, outValue);
+        } else if (outValue != null && outParam.value != null) {
+            fillCallerAllocatedBuffer(descriptor, outParam.value, outValue);
+        }
     }
 };
 
@@ -207,8 +202,8 @@ const applyCallback = (plan: CallbackPlan, thisArg: unknown, inputs: unknown[],
     }
 };
 
-const getThisArg = (receiver: CallbackReceiver, wrapped: unknown[]): unknown =>
-    receiver === "this" ? (wrapped[0] ?? null) : null;
+const getThisArg = (isInstanceBound: boolean, wrapped: unknown[]): unknown =>
+    isInstanceBound ? (wrapped[0] ?? null) : null;
 
 const wrapCallbackArgs = (effectiveTypes: Descriptor[], rawArgs: unknown[]): void => {
     let index = 0;
@@ -233,29 +228,35 @@ const trimCallbackInputs = (plan: CallbackPlan, wrapped: unknown[]): unknown[] =
     return wrapped;
 };
 
+const nativeReturn = (plan: CallbackPlan, primary: unknown): unknown =>
+    toNative(plan.returnDescriptor, plan.hasPrimary ? primary : undefined);
+
 const runCallback = (plan: CallbackPlan, rawArgs: unknown[]): unknown => {
-    const { effectiveTypes, returnDescriptor } = plan;
+    const { effectiveTypes } = plan;
     wrapCallbackArgs(effectiveTypes, rawArgs);
-    const thisArg = getThisArg(plan.receiver, rawArgs);
+    const thisArg = getThisArg(plan.isInstanceBound, rawArgs);
 
     if (!plan.hasOutParams) {
-        return toNative(returnDescriptor, plan.fn.apply(thisArg, trimCallbackInputs(plan, rawArgs)));
+        return nativeReturn(plan, plan.fn.apply(thisArg, trimCallbackInputs(plan, rawArgs)));
     }
 
     const { inputs, outParams } = partitionCallbackArgs(effectiveTypes, rawArgs, plan.start);
     const result = applyCallback(plan, thisArg, inputs, outParams);
 
     if (outParams.length === 0) {
-        return toNative(returnDescriptor, result);
+        return nativeReturn(plan, result);
     }
 
-    const { lengthLinks, valueParams } = groupOutParams(outParams);
-    const { primary, outValues } = splitTupleResult(result, returnDescriptor.kind !== "void", valueParams.length);
-    writeFoldedLengths(lengthLinks, writeOutParams(valueParams, outValues));
+    const groups = groupOutParams(outParams, plan.lengthSources);
+    const { primary, outValues } = splitTupleResult(result, plan.hasPrimary, groups.valueParams.length);
+    writeOutParams(outParams, resolveOutValues(groups, outValues, primary));
 
-    return toNative(returnDescriptor, primary);
+    return nativeReturn(plan, primary);
 };
 
+const planLengthSources = (spec: CallbackSpec, hasFoldedLengths: boolean): LengthSources =>
+    hasFoldedLengths ? foldedLengthSources(spec) : new Map<number, LengthSource[]>();
+
 const getEffectiveTypes = (spec: CallbackSpec): Descriptor[] => {
     const { userDataIndex } = spec;
 
@@ -267,18 +268,21 @@ const getEffectiveTypes = (spec: CallbackSpec): Descriptor[] => {
 };
 
 const wrapCallbackValue = (spec: CallbackDescriptor, callback: unknown): unknown =>
-    callback == null ? callback : wrapCallback(callback as Callback, spec, "none");
+    callback == null ? callback : wrapCallback(callback as Callback, spec, "callback");
 
-function wrapCallback(fn: Callback, spec: CallbackSpec, receiver: CallbackReceiver): Callback {
+function wrapCallback(fn: Callback, spec: CallbackSpec, kind: CallbackKind): Callback {
     const effectiveTypes = getEffectiveTypes(spec);
-    const start = receiver === "none" ? 0 : 1;
+    const { isInstanceBound, hasInstanceArg, hasFoldedLengths } = CALLBACK_TRAITS[kind];
+    const start = hasInstanceArg ? 1 : 0;
 
     const plan: CallbackPlan = {
         fn,
         effectiveTypes,
         returnDescriptor: spec.returnDescriptor,
+        hasPrimary: spec.returnDescriptor.kind !== "void",
         start,
-        receiver,
+        isInstanceBound,
+        lengthSources: planLengthSources(spec, hasFoldedLengths),
         hasOutParams: haveOutParamArgs(effectiveTypes, start),
         hasRefOutParams: haveRefOutParamArgs(effectiveTypes, start),
     };

package/src/closure.ts

@@ -40,7 +40,7 @@ const MARSHAL_T = callbackT(
         CLOSURE_T,
         MARSHAL_VALUE_T,
         uint32T,
-        sizedArrayT(MARSHAL_VALUE_T, N_PARAM_VALUES_INDEX, "borrowed", VALUE_SIZE),
+        sizedArrayT(MARSHAL_VALUE_T, N_PARAM_VALUES_INDEX, "borrowed", { elementSize: VALUE_SIZE }),
         uint64T,
         uint64T,
     ],

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,10 +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;
+    /** Whether the array carries raw bytes, and so decodes to a `Uint8Array` rather than to numbers. */
+    isBytes?: boolean | 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. */
@@ -125,6 +140,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 +192,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 +302,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 +323,7 @@ const fundamentalT = (
 
     if (options.typeName !== undefined) {
         result.typeName = options.typeName;
+        recordFundamentalLifecycle(options.typeName, { sharedLibrary, refFnName, unrefFnName });
     }
 
     if (options.wrapperClass !== undefined) {
@@ -318,6 +350,10 @@ const arrayT = (
         result.elementSize = options.elementSize;
     }
 
+    if (options?.baseParamIndex !== undefined) {
+        result.baseParamIndex = options.baseParamIndex;
+    }
+
     if (options?.sizeParamIndex !== undefined) {
         result.sizeParamIndex = options.sizeParamIndex;
     }
@@ -326,76 +362,107 @@ const arrayT = (
         result.fixedSize = options.fixedSize;
     }
 
+    if (options?.isBytes === true) {
+        result.isBytes = true;
+    }
+
     return result;
 };
 
 /** Builds a descriptor for a `GList` of items. */
-const listT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
-    arrayT(itemDescriptor, "glist", ownership);
+const listT = (
+    itemDescriptor: Descriptor,
+    ownership: Ownership = "borrowed",
+    options: ArrayOptions = {},
+): ArrayDescriptor => arrayT(itemDescriptor, "glist", ownership, options);
 
 /** Builds a descriptor for a `GSList` of items. */
-const slistT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
-    arrayT(itemDescriptor, "gslist", ownership);
+const slistT = (
+    itemDescriptor: Descriptor,
+    ownership: Ownership = "borrowed",
+    options: ArrayOptions = {},
+): ArrayDescriptor => arrayT(itemDescriptor, "gslist", ownership, options);
 
 /** Builds a descriptor for a `GPtrArray` of items. */
-const ptrArrayT = (itemDescriptor: Descriptor, ownership: Ownership = "borrowed"): ArrayDescriptor =>
-    arrayT(itemDescriptor, "gptrarray", ownership);
+const ptrArrayT = (
+    itemDescriptor: Descriptor,
+    ownership: Ownership = "borrowed",
+    options: ArrayOptions = {},
+): ArrayDescriptor => arrayT(itemDescriptor, "gptrarray", ownership, options);
 
-/** Builds a descriptor for a `GArray` of items, optionally with an explicit element size. */
+/** Builds a descriptor for a `GArray` of items. */
 const gArrayT = (
     itemDescriptor: Descriptor,
     ownership: Ownership = "borrowed",
-    elementSize?: number,
-): ArrayDescriptor =>
-    arrayT(itemDescriptor, "garray", ownership, elementSize === undefined ? undefined : { elementSize });
+    options: ArrayOptions = {},
+): ArrayDescriptor => arrayT(itemDescriptor, "garray", ownership, options);
 
 /** Builds a descriptor for a `GByteArray`. */
 const byteArrayT = (ownership: Ownership = "borrowed"): ArrayDescriptor =>
-    arrayT(uint8T, "gbytearray", ownership);
+    arrayT(uint8T, "gbytearray", ownership, { isBytes: true });
 
 /** Builds a descriptor for a C array whose length is carried by another argument. */
 const sizedArrayT = (
     itemDescriptor: Descriptor,
     sizeParamIndex: number,
     ownership: Ownership = "borrowed",
-    elementSize?: number,
-): ArrayDescriptor => arrayT(itemDescriptor, "sized", ownership, { sizeParamIndex, elementSize });
+    options: ArrayOptions = {},
+): ArrayDescriptor => arrayT(itemDescriptor, "sized", ownership, { ...options, sizeParamIndex });
+
+/**
+ * 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",
+    options: ArrayOptions = {},
+): ArrayDescriptor => arrayT(itemDescriptor, "cursor", ownership, { ...options, ...bounds });
 
 /** Builds a descriptor for a C array of a fixed length. */
 const fixedArrayT = (
     itemDescriptor: Descriptor,
     fixedSize: number,
     ownership: Ownership = "borrowed",
-    elementSize?: number,
-): ArrayDescriptor => arrayT(itemDescriptor, "fixed", ownership, { fixedSize, elementSize });
+    options: ArrayOptions = {},
+): ArrayDescriptor => arrayT(itemDescriptor, "fixed", ownership, { ...options, fixedSize });
 
-/** 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 +493,7 @@ export {
     flagsT,
     boxedT,
     structT,
+    fundamentalLifecycleFor,
     fundamentalT,
     arrayT,
     listT,
@@ -435,6 +503,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 };