@gtkx/runtime 1.0.0-rc.4 → 1.1.0

package/src/fn.ts

@@ -1,13 +1,14 @@
-import type { Descriptor, Ref } from "@gtkx/native";
-import { type Arg, isCallerAllocatedArg, isInoutArg, isOutputArg, isRefArg } from "./arg.js";
-import { bind } from "./bind.js";
+import type { CallDescriptor, Descriptor, ExternalObject, 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 { wrapCallbackValue } from "./callback.js";
 import { boxedT, refT } from "./descriptors.js";
 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 = {
@@ -15,12 +16,24 @@ 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;
+    /**
+     * How many of `args` precede the callee's ellipsis, marking it variadic. Omitting it binds a
+     * fixed-arity call, which passes the wrong argument classes to a variadic callee on some
+     * architectures.
+     */
+    fixedArgCount?: number;
 };
 
 type ArgSpec = {
     arg: Arg;
+    index: number;
     isRef: boolean;
     isCallerAllocated: boolean;
     requiresInput: boolean;
@@ -28,6 +41,8 @@ type ArgSpec = {
     isOutParam: boolean;
 };
 
+const NO_OUT_PARAMS: unknown[] = [];
+
 const buildNativeArgTypes = (args: Arg[], canThrow: boolean): Descriptor[] => {
     const nativeArgTypes = args.map((argSpec) =>
         argSpec.direction !== undefined && argSpec.isCallerAllocated !== true ? refT(argSpec.type) : argSpec.type,
@@ -45,13 +60,14 @@ const buildNativeArgTypes = (args: Arg[], canThrow: boolean): Descriptor[] => {
 const buildArgSpecs = (args: Arg[]): ArgSpec[] => {
     let inputCursor = 0;
 
-    return args.map((arg) => {
+    return args.map((arg, index) => {
         const isRef = isRefArg(arg);
-        const requiresInput = !isRef || isInoutArg(arg);
+        const requiresInput = requiresInputArg(arg);
         const isOutParam = isOutputArg(arg) && arg.isConsumed !== true;
 
         return {
             arg,
+            index,
             isRef,
             isCallerAllocated: isCallerAllocatedArg(arg),
             requiresInput,
@@ -67,19 +83,19 @@ const resolveCallerAllocated = (inputs: unknown[], inputIndex: number): unknown
     return wrapper == null ? wrapper : getHandle(wrapper);
 };
 
-const buildRefValue = (requiresInput: boolean, inputs: unknown[], inputIndex: number): Ref => ({
-    value: requiresInput ? inputs[inputIndex] : null,
+const buildRefValue = (spec: ArgSpec, inputs: unknown[], seeds: RefSeeds | undefined): Ref => ({
+    value: spec.requiresInput ? inputs[spec.inputIndex] : (seeds?.get(spec.index) ?? null),
 });
 
-const buildNativeValue = (spec: ArgSpec, inputs: unknown[]): unknown => {
-    const { arg, isRef, isCallerAllocated, requiresInput, inputIndex } = spec;
+const buildNativeValue = (spec: ArgSpec, inputs: unknown[], seeds: RefSeeds | undefined): unknown => {
+    const { arg, isRef, isCallerAllocated, inputIndex } = spec;
 
     if (isCallerAllocated) {
         return resolveCallerAllocated(inputs, inputIndex);
     }
 
     if (isRef) {
-        return buildRefValue(requiresInput, inputs, inputIndex);
+        return buildRefValue(spec, inputs, seeds);
     }
 
     if (arg.type.kind === "callback") {
@@ -89,44 +105,84 @@ const buildNativeValue = (spec: ArgSpec, inputs: unknown[]): unknown => {
     return inputs[inputIndex];
 };
 
-const buildNativeValues = (plans: ArgSpec[], inputs: unknown[]): unknown[] =>
-    plans.map((plan) => buildNativeValue(plan, inputs));
+const buildNativeValues = (plans: ArgSpec[], inputs: unknown[], seeds: RefSeeds | undefined): unknown[] =>
+    plans.map((plan) => buildNativeValue(plan, inputs, seeds));
+
+const readOutParams = (outPlans: ArgSpec[], inputs: unknown[], nativeValues: unknown[]): unknown[] => {
+    if (outPlans.length === 0) {
+        return NO_OUT_PARAMS;
+    }
 
-const readOutParams = (plans: ArgSpec[], inputs: unknown[], nativeValues: unknown[]): unknown[] => {
-    const outParams: unknown[] = [];
+    return Array.from(outPlans, (plan) =>
+        plan.isCallerAllocated
+            ? inputs[plan.inputIndex]
+            : fromNative(plan.arg.type, (nativeValues[plan.index] as Ref).value));
+};
 
-    for (const [index, { arg, isCallerAllocated, inputIndex, isOutParam }] of plans.entries()) {
-        if (!isOutParam) {
-            continue;
-        }
+const isPassThroughPlan = (plan: ArgSpec, index: number): boolean =>
+    plan.inputIndex === index &&
+    !plan.isRef &&
+    !plan.isCallerAllocated &&
+    plan.arg.type.kind !== "callback";
 
-        outParams.push(
-            isCallerAllocated ? inputs[inputIndex] : fromNative(arg.type, (nativeValues[index] as Ref).value),
-        );
+const resizeInputs = (inputs: unknown[], argCount: number): unknown[] => {
+    while (inputs.length < argCount) {
+        inputs.push(undefined);
     }
 
-    return outParams;
+    if (inputs.length > argCount) {
+        inputs.length = argCount;
+    }
+
+    return inputs;
 };
 
-function fn(sharedLibrary: string, symbol: string, spec: FnSpec): (...inputs: unknown[]) => unknown {
+const directCallable = (
+    descriptor: ExternalObject<CallDescriptor>,
+    returnDescriptor: Descriptor,
+    hasPrimary: boolean,
+    argCount: number,
+): ((...inputs: unknown[]) => unknown) => {
+    const marshal = (inputs: unknown[]): unknown =>
+        fromNative(returnDescriptor, call(descriptor, resizeInputs(inputs, argCount)));
+
+    if (hasPrimary) {
+        return (...inputs) => marshal(inputs);
+    }
+
+    return (...inputs) => {
+        marshal(inputs);
+    };
+};
+
+function fromNativeCallable(
+    descriptor: ExternalObject<CallDescriptor>,
+    spec: FnSpec,
+    getRefSeeds?: () => RefSeeds | undefined,
+): (...inputs: unknown[]) => unknown {
     const { args, returns: returnDescriptor, canThrow = false } = spec;
-    const nativeArgTypes = buildNativeArgTypes(args, canThrow);
-    const nativeFn = bind(sharedLibrary, symbol, nativeArgTypes, returnDescriptor);
-    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));
 
-    const shape = (inputs: unknown[], nativeValues: unknown[], nativeResult: unknown): unknown => {
-        const primary = hasPrimary ? fromNative(returnDescriptor, nativeResult) : undefined;
+    if (!canThrow && arePassThrough) {
+        return directCallable(descriptor, returnDescriptor, hasPrimary, plans.length);
+    }
 
-        return packTupleResult(readOutParams(plans, 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) => {
-            const nativeValues = buildNativeValues(plans, inputs);
+            const nativeValues = buildNativeValues(plans, inputs, getRefSeeds?.());
             const errorRef: Ref = { value: null };
             nativeValues.push(errorRef);
-            const nativeResult = nativeFn(...nativeValues);
+            const nativeResult = call(descriptor, nativeValues);
             checkError(errorRef);
 
             return shape(inputs, nativeValues, nativeResult);
@@ -134,10 +190,25 @@ function fn(sharedLibrary: string, symbol: string, spec: FnSpec): (...inputs: un
     }
 
     return (...inputs) => {
-        const nativeValues = buildNativeValues(plans, inputs);
+        const nativeValues = buildNativeValues(plans, inputs, getRefSeeds?.());
 
-        return shape(inputs, nativeValues, nativeFn(...nativeValues));
+        return shape(inputs, nativeValues, call(descriptor, nativeValues));
     };
 }
 
-export { fn };
+/**
+ * Binds a symbol in a shared library to a callable that marshals its inputs and packs output
+ * arguments into the result. When the spec sets `canThrow`, the reported `GError` is thrown.
+ *
+ * @param sharedLibrary Shared library the symbol is looked up in.
+ * @param symbol Name of the C symbol to bind.
+ * @param spec Argument and return descriptors the call is marshalled through.
+ */
+function fn(sharedLibrary: string, symbol: string, spec: FnSpec): (...inputs: unknown[]) => unknown {
+    const nativeArgTypes = buildNativeArgTypes(spec.args, spec.canThrow ?? false);
+    const descriptor = nativeBind(sharedLibrary, symbol, nativeArgTypes, spec.returns, spec.fixedArgCount);
+
+    return fromNativeCallable(descriptor, spec);
+}
+
+export { buildNativeArgTypes, fn, fromNativeCallable };

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/index.ts

@@ -1,9 +1,13 @@
 import "./exit-hook.js";
 
+/** @public */
+export { type ApplicationClass, type CommandLineApplication, createApplication } from "./application-class.js";
+/** @public */
+export { type ClosureCallback, ClosureMarshalError, toClosure, tryToClosure } from "./closure.js";
 /** @public */
 export { createErrorDomain, type ErrorDomain } from "./error.js";
 /** @public */
-export { onExit, quit, quitApplication, runApplication } from "./lifecycle.js";
+export { onExit, quit, quitApplication, runApplication, type RunApplicationResult } from "./lifecycle.js";
 /** @public */
 export { offSignal, onceSignal, onSignal } from "./listeners.js";
 /** @public */
@@ -11,13 +15,21 @@ export { installMixins, type Mixin } from "./mixin.js";
 /** @public */
 export { fromNative, toNative } from "./native-value.js";
 /** @public */
-export { getObjectProperty, newObjectWithProperties, setObjectProperty } from "./object.js";
+export {
+    type ConstructBinding,
+    type ConstructBindings,
+    getObjectProperty,
+    newObjectWithProperties,
+    registerConstructProperties,
+    setObjectProperty,
+} from "./object.js";
 /** @public */
 export { promisify } from "./promisify.js";
 /** @public */
-export { registerClass } from "./register-class.js";
+export { type Interface, registerClass } from "./register-class.js";
 /** @public */
 export {
+    getClassType,
     getHandle,
     getInstanceType,
     getWrapperClass,
@@ -25,11 +37,10 @@ export {
     registerWrapperClass,
     type StaticBase,
     setHandle,
-    tryGetHandle,
     wrapHandle,
 } from "./registry.js";
 /** @public */
-export { connectSignal, emitSignal, getSignalBaseName, type SignalHandler } from "./signal.js";
+export { connectSignal, disconnectSignal, emitSignal, getSignalBaseName, type SignalHandler } from "./signal.js";
 /** @public */
 export { t } from "./t.js";
 /** @public */
@@ -70,4 +81,8 @@ export {
 /** @public */
 export { getBoxedValue, setBoxedValue } from "./value.js";
 /** @public */
-export { alloc, type ExternalObject, type Handle, read, setWrapper, write } from "@gtkx/native";
+export { callParent, callVfunc } from "./vfunc-call.js";
+/** @public */
+export { alloc, type ExternalObject, type Handle, read, write } from "@gtkx/native";
+/** @public */
+export { type AnyClass } from "@gtkx/utils";

package/src/internal.ts

@@ -1,5 +1,7 @@
 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";
 export {
     fromValue,

package/src/library.ts

@@ -1,7 +1,9 @@
 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" });
 
 const PARAM_T: FundamentalDescriptor = fundamentalT(LIB, "g_param_spec_ref", "g_param_spec_unref", {
@@ -14,4 +16,4 @@ const VARIANT_T: FundamentalDescriptor = fundamentalT(LIB, "g_variant_ref", "g_v
     typeName: "GVariant",
 });
 
-export { 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 { blockMatchedSignalHandlers } from "./signal.js";
+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
@@ -9,13 +10,16 @@ import { blockMatchedSignalHandlers } from "./signal.js";
 type ApplicationLike = {
     /** Returns whether the application has already been registered. */
     getIsRegistered(): boolean;
+    /** Returns whether another process owns the application ID, making this one a remote instance. */
+    getIsRemote?(): boolean;
     /** Registers the application with the session, returning whether it succeeded. */
     register(cancellable: null): boolean;
     /** Emits `activate`, bringing up the application's initial user interface. */
     activate(): void;
-    /** Quits the application, so `run` returns at the next main-loop iteration after `shutdown` runs. */
-    quit(): void;
-    /** Runs the application's main loop until it shuts down and returns the exit status. */
+    /**
+     * Runs GLib's own `g_application_run`, whose tail emits `shutdown`, destroys the application
+     * implementation and clears the registration.
+     */
     run(argv: string[]): number;
     /** Returns the windows currently attached to the application. */
     getWindows?(): object[];
@@ -23,9 +27,24 @@ type ApplicationLike = {
     removeWindow?(window: object): void;
     /** Connects a handler to the application's `activate` or `shutdown` signal. */
     on(signal: "activate" | "shutdown", handler: () => void): unknown;
+    /** Emits one of the application's own signals. */
+    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. */
+    isPrimary: boolean;
+    /** The status GLib determined for the command line, which the process should exit with. */
+    exitStatus: number;
 };
 
 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
  * call more than once; only the first call takes effect.
@@ -60,13 +79,9 @@ const onExit = (callback: () => void): void => {
     shutdownCallbacks.push(callback);
 };
 
-/**
- * Registers the application if needed and activates it, keeping the runtime alive
- * while it is active and releasing it on shutdown.
- *
- * @param application The application to register and activate.
- */
-const runApplication = (application: ApplicationLike): void => {
+const startApplication = (application: ApplicationLike & LocalCommandLineApplication, argv: string[]): number => {
+    startedApplications.add(application);
+
     application.on("activate", () => {
         keepAlive(true);
     });
@@ -75,22 +90,90 @@ const runApplication = (application: ApplicationLike): void => {
         keepAlive(false);
     });
 
-    if (!application.getIsRegistered()) {
-        application.register(null);
+    return application.runLocalCommandLine(argv)[2];
+};
+
+const restartApplication = (application: ApplicationLike): number => {
+    shutDownApplications.delete(application);
+
+    if (!application.register(null)) {
+        return 1;
     }
 
     application.activate();
+
+    return 0;
+};
+
+const getApplicationInstance = (application: ApplicationLike): ApplicationInstance => {
+    if (!application.getIsRegistered()) {
+        return registeredApplications.has(application) ? "shutDown" : "unregistered";
+    }
+
+    return application.getIsRemote?.() === true ? "remote" : "primary";
 };
 
 /**
- * Detaches every window from the application and runs its main loop until it shuts
- * down, so pending shutdown work completes before the process exits. Does nothing
- * when the application was never registered.
+ * 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
+ * forwards the command line to the process that already owns the application ID. The runtime is
+ * held alive while the application is active and released on shutdown.
  *
- * @param application The application to shut down.
+ * `g_application_run()` is not what starts the application, because it would drive its own main loop
+ * and freeze Node; only the local command line handling it delegates to runs here. {@link
+ * quitApplication} calls it once no window holds the application open, to reach the teardown only it
+ * performs.
+ *
+ * GLib parses a given application's command line at most once, so starting an application that has
+ * already run registers and activates it instead of reading `argv` again.
+ *
+ * When another process already owns the application ID, this one registers as a remote instance: no
+ * 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.
  */
-const quitApplication = (application: ApplicationLike): void => {
-    if (!application.getIsRegistered()) {
+const runApplication = (application: ApplicationLike, argv: string[]): RunApplicationResult => {
+    if (!isDerivedApplication(application)) {
+        throw new Error(
+            "runApplication: this application was not built by GTKX, so its command line cannot be " +
+            "parsed and it cannot be shut down safely; render <GtkApplication> or <AdwApplication>, " +
+            "or construct it with createApplication from @gtkx/runtime",
+        );
+    }
+
+    claimDefaultApplication(application);
+
+    const exitStatus = startedApplications.has(application)
+        ? restartApplication(application)
+        : startApplication(application, argv);
+
+    const instance = getApplicationInstance(application);
+
+    if (instance !== "unregistered") {
+        registeredApplications.add(application);
+    }
+
+    const isPrimary = instance === "primary";
+
+    if (isPrimary) {
+        keepAlive(true);
+    }
+
+    return { isPrimary, exitStatus };
+};
+
+const tearDownApplication = (application: ApplicationLike): void => {
+    if (!application.getIsRegistered() || shutDownApplications.has(application)) {
         return;
     }
 
@@ -100,12 +183,42 @@ const quitApplication = (application: ApplicationLike): void => {
         application.removeWindow?.(window);
     }
 
-    application.on("shutdown", () => {
-        application.quit();
-    });
+    shutDownThroughRun(application);
+
+    if (application.getIsRegistered()) {
+        shutDownApplications.add(application);
+        application.emit("shutdown");
+    }
+};
 
-    blockMatchedSignalHandlers(application, "activate");
-    application.run([]);
+/**
+ * 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 { onExit, quit, runApplication, quitApplication, type ApplicationLike };
+export {
+    getApplicationInstance,
+    onExit,
+    quit,
+    runApplication,
+    quitApplication,
+    type ApplicationInstance,
+    type RunApplicationResult,
+};

package/src/listeners.ts

@@ -1,4 +1,4 @@
-import { isSignalHandlerConnected, type SignalHandler } from "./signal.js";
+import { isSignalHandlerConnected, type SignalHandler, untrackConnection } from "./signal.js";
 
 /**
  * The connect and disconnect surface {@link onSignal}, {@link onceSignal} and {@link offSignal}
@@ -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);
         }
     }
@@ -81,6 +98,7 @@ function onceSignal(instance: SignalConnectable, signal: string, handler: Signal
 
     const wrapped: SignalHandler = (...args) => {
         untrackHandlerId(instance, signal, handlerId);
+        untrackConnection(instance, handlerId);
         instance.disconnect(handlerId);
 
         return handler(...args);
@@ -107,6 +125,7 @@ function offSignal(instance: SignalConnectable, signal: string, handler: SignalH
     }
 
     untrackHandlerId(instance, signal, handlerId);
+    untrackConnection(instance, handlerId);
 
     if (!isSignalHandlerConnected(instance, handlerId)) {
         return;