@gtkx/runtime 1.0.0-rc.4 → 1.0.0

package/src/lifecycle.ts

@@ -1,5 +1,5 @@
 import { keepAlive, quit as nativeQuit } from "@gtkx/native";
-import { blockMatchedSignalHandlers } from "./signal.js";
+import { isDerivedApplication, type LocalCommandLineApplication, shutDownThroughRun } from "./application-class.js";
 
 /**
  * The GIO and GTK application surface {@link runApplication} and {@link quitApplication} drive, so any
@@ -9,13 +9,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 +26,21 @@ 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;
+};
+
+/** 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 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 +75,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 +86,78 @@ 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;
 };
 
 /**
- * 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.
+ *
+ * `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.
+ *
+ * @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 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",
+        );
+    }
+
+    const exitStatus = startedApplications.has(application)
+        ? restartApplication(application)
+        : startApplication(application, argv);
+
+    const isPrimary = application.getIsRegistered() && application.getIsRemote?.() !== true;
+
+    if (isPrimary) {
+        keepAlive(true);
+    }
+
+    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 => {
-    if (!application.getIsRegistered()) {
+    if (!application.getIsRegistered() || shutDownApplications.has(application)) {
         return;
     }
 
@@ -100,12 +167,12 @@ const quitApplication = (application: ApplicationLike): void => {
         application.removeWindow?.(window);
     }
 
-    application.on("shutdown", () => {
-        application.quit();
-    });
+    shutDownThroughRun(application);
 
-    blockMatchedSignalHandlers(application, "activate");
-    application.run([]);
+    if (application.getIsRegistered()) {
+        shutDownApplications.add(application);
+        application.emit("shutdown");
+    }
 };
 
-export { onExit, quit, runApplication, quitApplication, type ApplicationLike };
+export { onExit, quit, runApplication, quitApplication, type ApplicationLike, 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}
@@ -81,6 +81,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 +108,7 @@ function offSignal(instance: SignalConnectable, signal: string, handler: SignalH
     }
 
     untrackHandlerId(instance, signal, handlerId);
+    untrackConnection(instance, handlerId);
 
     if (!isSignalHandlerConnected(instance, handlerId)) {
         return;

package/src/mixin.ts

@@ -1,4 +1,4 @@
-import type { AnyClass } from "@gtkx/utils";
+import { type AnyClass, getParentClass } from "@gtkx/utils";
 
 /**
  * The signal plumbing every base class passed to a {@link Mixin} provides, so mixed-in interface
@@ -76,4 +76,17 @@ function installMixins(target: AnyClass, mixins: Mixin[]): void {
     }
 }
 
-export { installMixins, type MixinReceiver, type Mixin };
+function dropLayerMembers(layer: AnyClass, names: Set<string>): void {
+    for (const name of names) {
+        Reflect.deleteProperty(layer.prototype, name);
+    }
+}
+
+function insertMixinLayer(target: AnyClass, mixin: Mixin, inheritedNames: Set<string>): void {
+    const layer = mixin(getParentClass(target) as AnyClass<MixinReceiver>);
+    dropLayerMembers(layer, inheritedNames);
+    Object.setPrototypeOf(target.prototype, layer.prototype);
+    Object.setPrototypeOf(target, layer);
+}
+
+export { insertMixinLayer, installMixins, type MixinReceiver, type Mixin };

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 { getWrapperClass, tryGetHandle, wrapHandle } from "./registry.js";
+import { getHandle, getWrapperClass, 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 wrapHandle(value as ExternalObject<Handle> | null);
+            return wrapObject(value);
         }
         case "struct": {
             return wrapHandle(value as ExternalObject<Handle> | null, (descriptor as StructDescriptor).wrapperClass);
@@ -129,7 +129,9 @@ function toNative(descriptor: Descriptor, value: unknown): unknown {
         case "struct":
         case "boxed":
         case "fundamental": {
-            return tryGetHandle(value as object | null | undefined) ?? null;
+            const instance = value as object | null | undefined;
+
+            return instance == null ? null : getHandle(instance);
         }
         case "array": {
             return collectionToNative(descriptor, value);

package/src/object.ts

@@ -1,21 +1,25 @@
-import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
+import { type Descriptor, type ExternalObject, type Handle, newObject } from "@gtkx/native";
+import { type AnyClass, getParentClass } from "@gtkx/utils";
 import { bind } from "./bind.js";
-import { biguint64T, objectT, sizedArrayT, stringT, uint32T, voidT } from "./descriptors.js";
-import { LIB, VALUE_SIZE, VALUE_T } from "./library.js";
-import { getHandle } from "./registry.js";
+import { objectT, stringT, voidT } from "./descriptors.js";
+import { LIB, VALUE_T } from "./library.js";
+import { type ConstructProperty, constructPropertyFor } from "./properties.js";
+import { getHandle, registerWrapper } from "./registry.js";
 import { fromValue, newValueForDescriptor, toValue } from "./value.js";
 
-const gObjectNewWithProperties = bind(
-    LIB,
-    "g_object_new_with_properties",
-    [
-        biguint64T,
-        uint32T,
-        sizedArrayT(stringT("borrowed"), 1, "borrowed"),
-        sizedArrayT(VALUE_T, 1, "borrowed", VALUE_SIZE),
-    ],
-    objectT("full"),
-);
+/**
+ * One construct property a wrapper class accepts: the canonical `GObject` name it is set under,
+ * and the descriptor its value is marshalled through.
+ */
+type ConstructBinding = [name: string, descriptor: Descriptor];
+/** The construct properties a wrapper class accepts, keyed by the camelCased name callers give them. */
+type ConstructBindings = Record<string, ConstructBinding>;
+type ResolvedBindings = { generation: number; bindings: ConstructBindings };
+
+const declaredBindings: WeakMap<AnyClass, ConstructBindings> = new WeakMap();
+const resolvedBindings: WeakMap<AnyClass, ResolvedBindings> = new WeakMap();
+const declarations = { generation: 0 };
+const NO_BINDINGS: ConstructBindings = Object.create(null) as ConstructBindings;
 
 const gObjectGetProperty = bind(
     LIB,
@@ -31,37 +35,120 @@ const gObjectSetProperty = bind(
     voidT,
 );
 
+function collectDeclaredBindings(cls: AnyClass): ConstructBindings[] {
+    const declared: ConstructBindings[] = [];
+    let current: AnyClass | null = cls;
+
+    while (current !== null) {
+        const own = declaredBindings.get(current);
+
+        if (own !== undefined) {
+            declared.push(own);
+        }
+
+        current = getParentClass(current);
+    }
+
+    return declared;
+}
+
+function mergeDeclaredBindings(cls: AnyClass): ConstructBindings {
+    const declared = collectDeclaredBindings(cls);
+    const merged: ConstructBindings = Object.create(null) as ConstructBindings;
+
+    for (let index = declared.length - 1; index >= 0; index--) {
+        Object.assign(merged, declared[index]);
+    }
+
+    return merged;
+}
+
+function constructBindingsFor(cls: AnyClass | undefined): ConstructBindings {
+    if (cls === undefined) {
+        return NO_BINDINGS;
+    }
+
+    const cached = resolvedBindings.get(cls);
+
+    if (cached?.generation === declarations.generation) {
+        return cached.bindings;
+    }
+
+    const bindings = mergeDeclaredBindings(cls);
+    resolvedBindings.set(cls, { generation: declarations.generation, bindings });
+
+    return bindings;
+}
+
+/**
+ * Declares the construct properties a wrapper class accepts, so `newObjectWithProperties`
+ * marshals each one through its descriptor rather than resolving it from the
+ * `GObject.ParamSpec` the type installs. A class inherits the declarations of its ancestors.
+ * Registering takes effect immediately, including for classes already constructed from and for
+ * subclasses that already inherited an earlier declaration.
+ *
+ * @param cls The wrapper class the properties are declared on.
+ * @param bindings CamelCased property names mapped to their canonical name and descriptor.
+ */
+function registerConstructProperties(cls: AnyClass, bindings: ConstructBindings): void {
+    declaredBindings.set(cls, bindings);
+    declarations.generation += 1;
+}
+
+function constructPropertyForEntry(
+    source: { gtype: bigint; bindings: ConstructBindings; wrapper: object },
+    name: string,
+    value: unknown,
+): ConstructProperty | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+
+    const binding = source.bindings[name];
+
+    if (binding === undefined) {
+        return constructPropertyFor(source.gtype, name, value, source.wrapper);
+    }
+
+    return { name: binding[0], value: toValue(binding[1], value) };
+}
+
 /**
  * Constructs a new GObject of the given type, setting the supplied construct
- * properties. Entries whose value is `undefined` or not a `[descriptor, value]`
- * pair are skipped.
+ * properties, and binds `wrapper` to it. A property the wrapper's class declares
+ * through `registerConstructProperties` is marshalled through its descriptor; any
+ * other one is marshalled through the `GObject.ParamSpec` the type installs under
+ * 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.
+ * 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.
  *
  * @param gtype The GType of the object to construct.
- * @param props Property names mapped to `[descriptor, value]` pairs.
+ * @param props Property names mapped to the values to set them to.
+ * @param wrapper The wrapper instance to bind to the new object.
  * @returns The handle of the newly created object.
  */
-function newObjectWithProperties(gtype: bigint, props: Record<string, unknown>): ExternalObject<Handle> {
+function newObjectWithProperties(gtype: bigint, props: object, wrapper: object): ExternalObject<Handle> {
     const names: string[] = [];
     const values: ExternalObject<Handle>[] = [];
+    const bindings = constructBindingsFor(wrapper.constructor as AnyClass | undefined);
+    const source = { gtype, bindings, wrapper };
 
-    for (const name in props) {
-        const entry: unknown = props[name];
+    for (const name of Object.keys(props)) {
+        const property = constructPropertyForEntry(source, name, Reflect.get(props, name));
 
-        if (!Array.isArray(entry)) {
-            continue;
+        if (property !== undefined) {
+            names.push(property.name);
+            values.push(property.value);
         }
-
-        const [descriptor, value] = entry as [Descriptor, unknown];
-
-        if (value === undefined) {
-            continue;
-        }
-
-        names.push(name);
-        values.push(toValue(descriptor, value));
     }
 
-    return gObjectNewWithProperties(gtype, names.length, names, values) as ExternalObject<Handle>;
+    newObject(gtype, names, values, wrapper, registerWrapper);
+
+    return getHandle(wrapper);
 }
 
 /**
@@ -92,4 +179,11 @@ function setObjectProperty(obj: object, propertyName: string, descriptor: Descri
     gObjectSetProperty(getHandle(obj), propertyName, toValue(descriptor, jsValue));
 }
 
-export { newObjectWithProperties, getObjectProperty, setObjectProperty };
+export {
+    newObjectWithProperties,
+    getObjectProperty,
+    registerConstructProperties,
+    setObjectProperty,
+    type ConstructBinding,
+    type ConstructBindings,
+};

package/src/param-spec.ts

@@ -0,0 +1,235 @@
+import { type ExternalObject, type Handle, read } from "@gtkx/native";
+import { bind } from "./bind.js";
+import { biguint64T, booleanT, stringT, uint32T, voidT } from "./descriptors.js";
+import { LIB, PARAM_T, VALUE_T } from "./library.js";
+import { getInstanceType } from "./registry.js";
+import {
+    getStrvType,
+    isTypedClass,
+    TYPE_BOOLEAN,
+    TYPE_BOXED,
+    TYPE_CHAR,
+    TYPE_DOUBLE,
+    TYPE_ENUM,
+    TYPE_FLAGS,
+    TYPE_FLOAT,
+    TYPE_INT,
+    TYPE_INT64,
+    TYPE_INTERFACE,
+    TYPE_INVALID,
+    TYPE_LONG,
+    TYPE_OBJECT,
+    TYPE_PARAM,
+    TYPE_POINTER,
+    TYPE_STRING,
+    TYPE_UCHAR,
+    TYPE_UINT,
+    TYPE_UINT64,
+    TYPE_ULONG,
+    TYPE_VARIANT,
+    typeFundamental,
+    typeIsA,
+} from "./type.js";
+
+type ValueGuard = (value: unknown) => boolean;
+type ParamLayout = { flags: number; valueType: bigint };
+
+const PARAM_READABLE = 1;
+const PARAM_WRITABLE = 2;
+const PARAM_CONSTRUCT_ONLY = 8;
+const PARAM_LAX_VALIDATION = 16;
+const READ_FLAGS = PARAM_READABLE | PARAM_WRITABLE | PARAM_CONSTRUCT_ONLY | PARAM_LAX_VALIDATION;
+const FLAGS_BYTE_OFFSET = 16;
+const VALUE_TYPE_BYTE_OFFSET = 24;
+const LAYOUT_PROBE_NAME = "gtkx-param-layout";
+const INT8_MINIMUM = -128;
+const INT8_MAXIMUM = 127;
+const UINT8_MAXIMUM = 255;
+const INT32_MINIMUM = -2_147_483_648;
+const INT32_MAXIMUM = 2_147_483_647;
+const UINT32_MAXIMUM = 4_294_967_295;
+const INT64_MINIMUM = -(2n ** 63n);
+const INT64_MAXIMUM = 2n ** 63n - 1n;
+const UINT64_MAXIMUM = 2n ** 64n - 1n;
+const FLOAT_MAXIMUM = 3.4028234663852886e38;
+
+const WRAPPED_FUNDAMENTALS: Set<bigint> = new Set([
+    TYPE_BOXED,
+    TYPE_INTERFACE,
+    TYPE_OBJECT,
+    TYPE_PARAM,
+    TYPE_VARIANT,
+]);
+
+const SCALAR_GUARDS: Map<bigint, ValueGuard> = new Map([
+    [TYPE_BOOLEAN, isBooleanValue],
+    [TYPE_STRING, isStringValue],
+    [TYPE_CHAR, integerGuardFor(INT8_MINIMUM, INT8_MAXIMUM)],
+    [TYPE_UCHAR, integerGuardFor(0, UINT8_MAXIMUM)],
+    [TYPE_INT, integerGuardFor(INT32_MINIMUM, INT32_MAXIMUM)],
+    [TYPE_UINT, integerGuardFor(0, UINT32_MAXIMUM)],
+    [TYPE_ENUM, integerGuardFor(INT32_MINIMUM, INT32_MAXIMUM)],
+    [TYPE_FLAGS, integerGuardFor(0, UINT32_MAXIMUM)],
+    [TYPE_LONG, wideIntegerGuardFor(INT64_MINIMUM, INT64_MAXIMUM)],
+    [TYPE_ULONG, wideIntegerGuardFor(0n, UINT64_MAXIMUM)],
+    [TYPE_INT64, wideIntegerGuardFor(INT64_MINIMUM, INT64_MAXIMUM)],
+    [TYPE_UINT64, wideIntegerGuardFor(0n, UINT64_MAXIMUM)],
+    [TYPE_FLOAT, isFloatValue],
+    [TYPE_DOUBLE, isDoubleValue],
+    [TYPE_POINTER, isNullValue],
+]);
+
+const layout = { wasChecked: false };
+const paramValueValidate = bind(LIB, "g_param_value_validate", [PARAM_T, VALUE_T], booleanT);
+const paramSpecUnref = bind(LIB, "g_param_spec_unref", [PARAM_T], voidT);
+const paramSpecRefSink = bind(LIB, "g_param_spec_ref_sink", [PARAM_T], PARAM_T);
+
+const newParamSpecBoolean = bind(
+    LIB,
+    "g_param_spec_boolean",
+    [stringT("borrowed"), stringT("borrowed"), stringT("borrowed"), booleanT, uint32T],
+    PARAM_T,
+);
+
+const getParamFlags = (pspec: ExternalObject<Handle>): number => read(pspec, uint32T, FLAGS_BYTE_OFFSET) as number;
+
+const getParamValueType = (pspec: ExternalObject<Handle>): bigint =>
+    read(pspec, biguint64T, VALUE_TYPE_BYTE_OFFSET) as bigint;
+
+const isParamWritable = (flags: number): boolean => (flags & PARAM_WRITABLE) !== 0;
+const isParamConstructOnly = (flags: number): boolean => (flags & PARAM_CONSTRUCT_ONLY) !== 0;
+const isParamLaxlyValidated = (flags: number): boolean => (flags & PARAM_LAX_VALIDATION) !== 0;
+
+const wasParamValueModified = (pspec: ExternalObject<Handle>, value: ExternalObject<Handle>): boolean =>
+    paramValueValidate(pspec, value) as boolean;
+
+function isBooleanValue(value: unknown): boolean {
+    return typeof value === "boolean";
+}
+
+function isStringValue(value: unknown): boolean {
+    return value == null || typeof value === "string";
+}
+
+function isStrvValue(value: unknown): boolean {
+    return value == null || (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+
+function isDoubleValue(value: unknown): boolean {
+    return value == null || (typeof value === "number" && Number.isFinite(value));
+}
+
+function isFloatValue(value: unknown): boolean {
+    return isDoubleValue(value) && (value == null || Math.abs(value as number) <= FLOAT_MAXIMUM);
+}
+
+function isAnyValue(): boolean {
+    return true;
+}
+
+function isNullValue(value: unknown): boolean {
+    return value == null;
+}
+
+function isIntegerWithin(value: unknown, minimum: number, maximum: number): boolean {
+    return Number.isSafeInteger(value) && (value as number) >= minimum && (value as number) <= maximum;
+}
+
+function integerGuardFor(minimum: number, maximum: number): ValueGuard {
+    return (value) => value == null || isIntegerWithin(value, minimum, maximum);
+}
+
+function toWideInteger(value: unknown): bigint | undefined {
+    if (typeof value === "bigint") {
+        return value;
+    }
+
+    return Number.isSafeInteger(value) ? BigInt(value as number) : undefined;
+}
+
+function wideIntegerGuardFor(minimum: bigint, maximum: bigint): ValueGuard {
+    return (value) => {
+        if (value == null) {
+            return true;
+        }
+
+        const wide = toWideInteger(value);
+
+        return wide !== undefined && wide >= minimum && wide <= maximum;
+    };
+}
+
+function resolveGtype(value: unknown): bigint {
+    const instanceType = getInstanceType(value as object);
+
+    if (instanceType !== TYPE_INVALID) {
+        return instanceType;
+    }
+
+    return isTypedClass(value) ? value.__type__ : TYPE_INVALID;
+}
+
+function wrappedGuardFor(valueType: bigint): ValueGuard {
+    return (value) => value == null || typeIsA(resolveGtype(value), valueType);
+}
+
+function valueGuardFor(valueType: bigint): ValueGuard {
+    assertParamLayout();
+
+    if (valueType === getStrvType()) {
+        return isStrvValue;
+    }
+
+    const fundamental = typeFundamental(valueType);
+
+    if (WRAPPED_FUNDAMENTALS.has(fundamental)) {
+        return wrappedGuardFor(valueType);
+    }
+
+    return SCALAR_GUARDS.get(fundamental) ?? isAnyValue;
+}
+
+function readProbeLayout(flags: number): ParamLayout {
+    const probe = newParamSpecBoolean(LAYOUT_PROBE_NAME, null, null, false, flags) as ExternalObject<Handle>;
+    paramSpecRefSink(probe);
+
+    try {
+        return { flags: getParamFlags(probe), valueType: getParamValueType(probe) };
+    } finally {
+        paramSpecUnref(probe);
+    }
+}
+
+function isLayoutIntact(flags: number): boolean {
+    const layout = readProbeLayout(flags);
+
+    return (layout.flags & READ_FLAGS) === flags && layout.valueType === TYPE_BOOLEAN;
+}
+
+function assertParamLayout(): void {
+    if (layout.wasChecked) {
+        return;
+    }
+
+    layout.wasChecked = true;
+    const readWrite = PARAM_READABLE | PARAM_WRITABLE;
+
+    if (isLayoutIntact(readWrite) && isLayoutIntact(readWrite | PARAM_CONSTRUCT_ONLY | PARAM_LAX_VALIDATION)) {
+        return;
+    }
+
+    throw new Error(
+        "GParamSpec does not match the memory layout this build reads a property's flags and value type at",
+    );
+}
+
+export {
+    getParamFlags,
+    getParamValueType,
+    isParamConstructOnly,
+    isParamLaxlyValidated,
+    isParamWritable,
+    type ValueGuard,
+    valueGuardFor,
+    wasParamValueModified,
+};