@gtkx/runtime 1.5.0 → 2.0.0-beta.1

package/src/native-value.ts

@@ -11,11 +11,13 @@ import {
 } from "@gtkx/native";
 import {
     type ArrayDescriptor,
+    type BoxedDescriptor,
     boxedT,
     type CallbackDescriptor,
     type FundamentalDescriptor,
     type HashTableDescriptor,
     isGtypeDescriptor,
+    type ObjectDescriptor,
     refT,
     type StructDescriptor,
 } from "./descriptors.js";
@@ -71,6 +73,17 @@ function boxedFromNative(descriptor: Descriptor, value: unknown): unknown {
 
     const handle = value as ExternalObject<Handle>;
     const type = resolveDescriptorType(descriptor);
+    const registered = resolveWrapperClass(type);
+
+    if (registered !== null) {
+        return wrapHandle(handle, registered);
+    }
+
+    const fallback = (descriptor as BoxedDescriptor).fallbackClass?.();
+
+    if (fallback !== undefined) {
+        return wrapHandle(handle, fallback);
+    }
 
     return wrapHandle(handle, getWrapperClass(type));
 }
@@ -81,8 +94,19 @@ function fundamentalWrapperClass(descriptor: FundamentalDescriptor, handle: Exte
     }
 
     const declaredType = resolveDescriptorType(descriptor);
+    const registered = resolveWrapperClass(getType(handle, declaredType));
+
+    if (registered !== null) {
+        return registered;
+    }
+
+    const fallback = descriptor.fallbackClass?.();
+
+    if (fallback !== undefined) {
+        return fallback;
+    }
 
-    return resolveWrapperClass(getType(handle, declaredType)) ?? getWrapperClass(declaredType);
+    return getWrapperClass(declaredType);
 }
 
 function fundamentalFromNative(descriptor: FundamentalDescriptor, value: unknown): unknown {
@@ -203,7 +227,11 @@ function fromNative(descriptor: Descriptor, value: unknown): unknown {
 
     switch (descriptor.kind) {
         case "object": {
-            return descriptor.isCallScoped === true ? wrapCallScopedObject(value) : wrapObject(value);
+            const fallbackClass = (descriptor as ObjectDescriptor).fallbackClass;
+
+            return descriptor.isCallScoped === true
+                ? wrapCallScopedObject(value, fallbackClass)
+                : wrapObject(value, fallbackClass);
         }
         case "struct": {
             return wrapHandle(value as ExternalObject<Handle> | null, (descriptor as StructDescriptor).wrapperClass);
@@ -227,12 +255,33 @@ function collectionToNative(descriptor: ArrayDescriptor, value: unknown): unknow
     return value == null ? null : mapCollection(descriptor, value, toNative);
 }
 
-function hashTableToNative(descriptor: HashTableDescriptor, value: unknown): unknown {
+/**
+ * Normalises the JavaScript form of a hash table argument into its entry list. A `Map` is the
+ * expected form and any other iterable of pairs is accepted; anything else is rejected, a plain
+ * object above all, which `Array.from` would quietly flatten into an empty table.
+ *
+ * @param value The JavaScript value passed for a hash table argument.
+ */
+function toHashTableEntries(value: unknown): [unknown, unknown][] | null {
     if (value == null) {
         return null;
     }
 
-    return [...(value as Map<unknown, unknown>)].map(([key, val]): [unknown, unknown] => [
+    if (typeof (value as Partial<Iterable<unknown>>)[Symbol.iterator] !== "function") {
+        throw new TypeError("A hash table argument must be a Map or an iterable of [key, value] pairs");
+    }
+
+    return [...(value as Iterable<[unknown, unknown]>)];
+}
+
+function hashTableToNative(descriptor: HashTableDescriptor, value: unknown): unknown {
+    const entries = toHashTableEntries(value);
+
+    if (entries === null) {
+        return null;
+    }
+
+    return entries.map(([key, val]): [unknown, unknown] => [
         toNative(descriptor.keyDescriptor, key),
         toNative(descriptor.valueDescriptor, val),
     ]);
@@ -274,4 +323,4 @@ function toNative(descriptor: Descriptor, value: unknown): unknown {
     }
 }
 
-export { fromNative, toNative };
+export { fromNative, toHashTableEntries, toNative };

package/src/properties.ts

@@ -1,6 +1,5 @@
 import type { ExternalObject, Handle, RegisterClassProperty } from "@gtkx/native";
-import type { AnyClass } from "@gtkx/utils";
-import { camelCase, kebabCase, toCamelIdentifier } from "@gtkx/utils";
+import { type AnyClass, camelCase, kebabCase, toCamelIdentifier } from "@gtkx/utils";
 import { bind } from "./bind.js";
 import { biguint64T, fundamentalT, refT, sizedArrayT, stringT, structT, uint32T, voidT } from "./descriptors.js";
 import { LIB, PARAM_T, VALUE_T } from "./library.js";
@@ -347,21 +346,9 @@ function lookupCoercionCheck(gtype: bigint, name: string): PropertyCheck | null
 }
 
 function coercionCheckFor(gtype: bigint, name: string): PropertyCheck | null {
-    let checks = coercionChecks.get(gtype);
+    const checks = coercionChecks.getOrInsertComputed(gtype, () => new Map<string, PropertyCheck | null>());
 
-    if (checks === undefined) {
-        checks = new Map();
-        coercionChecks.set(gtype, checks);
-    }
-
-    let check = checks.get(name);
-
-    if (check === undefined) {
-        check = lookupCoercionCheck(gtype, name);
-        checks.set(name, check);
-    }
-
-    return check;
+    return checks.getOrInsertComputed(name, () => lookupCoercionCheck(gtype, name));
 }
 
 function truncateToWhole(check: PropertyCheck, value: number): number {

package/src/register-class.ts

@@ -45,111 +45,67 @@ import {
     TYPE_NONE,
     type TypedClass,
     typeFundamental,
+    typeInterfacePrerequisites,
     typeInterfaces,
     typeIsA,
     typeName,
 } from "./type.js";
 import { findClassVfuncDescriptor, findInterfaceVfuncDescriptor } from "./vfunc.js";
 
-/**
- * A generated interface value, such as `Gio.ListModel`, in the form {@link registerClass} takes it.
- * `__impl__` exists only in the type system: it carries the interface's `Impl` type, of which a class
- * has to match every member it declares itself, which rejects a class value and a member whose
- * signature does not fit the slot it fills. Leaving a slot to the interface is not rejected,
- * because `registerClass` does not reject it either: every member of an `Impl` type is optional,
- * and the `Partial` holds that open whatever the type declares. The `object` beside it keeps
- * TypeScript from also demanding one member in common. An interface that introspection describes
- * no vtable for carries `unknown`, since it has no slot a class could fill.
- */
+/** A generated interface value, such as `Gio.ListModel`, accepted by {@link registerClass}. */
 type Interface<TImpl> = AnyClass & {
     /** Type-level slot holding the interface's `Impl` type; no value ever carries it. */
     __impl__: (impl: Partial<TImpl> & object) => void;
 };
 
-/**
- * One key of `RegisterClassOptions.properties` with every underscore turned into the dash a canonical
- * GObject property name separates its words with.
- */
+/** Converts underscores in a property name to canonical dashes. */
 type Dashed<TName extends string> = TName extends `${infer THead}_${infer TTail}`
     ? Dashed<`${THead}-${TTail}`>
     : TName;
 
-/**
- * One dashed key in the camelCase spelling the accessors {@link registerClass} installs carry, which is
- * the spelling the hooks that address a property by name take.
- */
+/** Converts a dashed property name to its JavaScript spelling. */
 type Camelized<TName extends string> = TName extends `${infer THead}-${infer TTail}`
     ? `${THead}${Capitalize<Camelized<TTail>>}`
     : TName;
 
-/**
- * The names a registered class carries in its property map: every key of
- * `RegisterClassOptions.properties` in camelCase, whichever spelling it was written in.
- * A `properties` object given a type of its own rather than left to inference has `string` for its key
- * type and names nothing, because a name only known as `string` addresses no member in particular.
- */
+/** Property-map keys in the camelCase spelling hooks use. */
 type InstalledNames<TProperties> = string extends keyof TProperties
     ? never
     : Camelized<Dashed<keyof TProperties & string>>;
 
-/**
- * The base names the signal surface takes for the signals `RegisterClassOptions.signals` declares:
- * each name as written, plus its canonical spelling with underscores turned into dashes, which
- * GObject knows the signal by too.
- */
+/** Declared signal names in their original and canonical spellings. */
 type DeclaredSignalBase<TSignals> = (keyof TSignals & string) | Dashed<keyof TSignals & string>;
-/**
- * The names `connect` and `emit` take for one of the signals `RegisterClassOptions.signals`
- * declares: each spelling of each name, plus its detailed form for a signal emitted with a
- * `::detail` suffix.
- */
+/** Declared signal names, including detailed forms. */
 type DeclaredSignalName<TSignals> = DeclaredSignalBase<TSignals> | `${DeclaredSignalBase<TSignals>}::${string}`;
 
-/**
- * The `connect` and `emit` signatures instances gain for the signals
- * `RegisterClassOptions.signals` declares, widening the inherited ones, which take only the names
- * introspection knows. A class declaring no signals gains nothing, since no name reaches the
- * added signatures.
- */
+/** Signal methods added for declared names. */
 type DeclaredSignalMethods<TSignals> = {
-    /**
-     * Type-level map from declared signal name to handler signature, feeding the hooks that
-     * address a signal by name, such as `useSignal` from `@gtkx/react`; no value ever carries it.
-     */
+    /** Type-level map used by signal hooks. */
     __signals__?: Record<DeclaredSignalBase<TSignals>, (...args: never[]) => unknown>;
-    /** Connects a handler to a signal `RegisterClassOptions.signals` declared. */
+    /** Connects a handler. */
     connect(
         signal: DeclaredSignalName<TSignals>,
         handler: (...args: never[]) => unknown,
         isAfter?: boolean,
     ): number;
-    /** Emits a signal `RegisterClassOptions.signals` declared. */
+    /** Emits a signal. */
     emit(sigName: DeclaredSignalName<TSignals>, ...args: unknown[]): unknown;
-    /** Connects a handler to a signal `RegisterClassOptions.signals` declared, for `off` to take off. */
+    /** Connects a removable handler. */
     on(sigName: DeclaredSignalName<TSignals>, callback: (...args: unknown[]) => unknown, isAfter?: boolean): unknown;
-    /** Connects a handler to a signal `RegisterClassOptions.signals` declared for one emission. */
+    /** Connects a one-shot handler. */
     once(sigName: DeclaredSignalName<TSignals>, callback: (...args: unknown[]) => unknown, isAfter?: boolean): unknown;
-    /** Disconnects a handler `on` or `once` connected to a signal `RegisterClassOptions.signals` declared. */
+    /** Disconnects a handler. */
     off(sigName: DeclaredSignalName<TSignals>, callback: (...args: unknown[]) => unknown): unknown;
 };
 
-/**
- * An instance of a registered class: everything the class itself declares, plus the property map the
- * hooks that address a property by name, such as `useProperty` from `@gtkx/react`, read the installed
- * names off. Each name is typed with the value type the class declares for the member of that name,
- * so a property the class does not `declare` contributes nothing.
- */
+/** A registered instance with declared signal methods and property metadata. */
 type RegisteredInstance<TInstance, TProperties, TSignals> = TInstance &
     DeclaredSignalMethods<TSignals> & {
         /** Type-level map from installed property name to value type; no value ever carries it. */
         __properties__: Pick<TInstance, InstalledNames<TProperties> & keyof TInstance>;
     };
 
-/**
- * The construct signature and prototype a registered class carries, both giving
- * {@link RegisteredInstance}. The signature stays abstract for as long as the class itself is, so
- * registering an abstract base leaves it as impossible to construct as it was.
- */
+/** A registered class's construct signature and prototype. */
 type RegisteredConstructor<TClass, TArgs extends unknown[], TInstance> = {
     /** Object the class's instances inherit from. */
     prototype: TInstance;
@@ -161,45 +117,24 @@ type RegisteredConstructor<TClass, TArgs extends unknown[], TInstance> = {
 type RegisteredParts<TClass, TArgs extends unknown[], TInstance> = Omit<TClass, "prototype"> &
     RegisteredConstructor<TClass, TArgs, TInstance>;
 
-/**
- * The class {@link registerClass} hands back: the same class, with the same statics, whose instances
- * carry the properties `RegisterClassOptions.properties` installed and take the signals
- * `RegisterClassOptions.signals` declares by name. Binding the call to a name, rather than
- * discarding it, is what carries those names into the type system.
- */
+/** The registered class with its declared properties and signals. */
 type RegisteredClass<TClass extends AnyClass, TProperties, TSignals> =
     TClass extends abstract new (...args: infer TArgs) => infer TInstance
         ? RegisteredParts<TClass, TArgs, RegisteredInstance<TInstance, TProperties, TSignals>>
         : never;
 
-/**
- * A GType in the form `RegisterClassOptions.signals` takes one: the numeric GType itself, such as
- * `TYPE_STRING` from `@gtkx/gi/gobject`, or a class carrying one, which is any generated wrapper
- * class and any class an earlier {@link registerClass} call registered.
- */
+/** A numeric GType or a generated or registered wrapper class. */
 type SignalGType = bigint | AnyClass<TypedClass>;
 
-/**
- * One signal `RegisterClassOptions.signals` creates on the new type, sitting under the signal's
- * name. Every part is optional: `{}` declares a signal with no arguments and no return value that
- * runs its handlers in the default `RUN_FIRST` stage.
- */
+/** A signal installed by {@link registerClass}. */
 type SignalSpec = {
-    /**
-     * `GObject.SignalFlags` bit mask for the signal, defaulting to `RUN_FIRST`. `DETAILED` lets
-     * handlers connect to and emissions name a `::detail` suffix.
-     */
+    /** `GObject.SignalFlags` bit mask, defaulting to `RUN_FIRST`. */
     flags?: number;
-    /** GType of each argument an emission carries, defaulting to none. */
+    /** Argument GTypes, defaulting to none. */
     paramTypes?: SignalGType[];
-    /** GType of the value an emission returns, defaulting to none. */
+    /** Return GType, defaulting to none. */
     returnType?: SignalGType;
-    /**
-     * How the emission combines what its handlers return, limited to the two accumulators GObject
-     * ships: `"first-wins"` stops the emission at the first handler and keeps its result, and
-     * `"true-handled"` runs handlers until one returns `true`, which requires a boolean
-     * `returnType`. Without one, every handler runs and the last result stands.
-     */
+    /** Combines handler results; omitted means the last result wins. */
     accumulator?: "first-wins" | "true-handled";
 };
 
@@ -209,129 +144,29 @@ type RegisterClassOptions<
     TProperties extends Record<string, PropertySpec>,
     TSignals extends Record<string, SignalSpec>,
 > = {
-    /**
-     * Name to register the new GType under, defaulting to the class's own name. Either way the
-     * name has to be a valid GType name: at least three characters, starting with a letter or
-     * underscore, the rest letters, digits, `-`, `_` or `+`. Any other name throws a `TypeError`.
-     */
+    /** Registered GType name, defaulting to the class name. */
     typeName?: string;
-    /**
-     * Registers the new GType abstract, the way `G_TYPE_FLAG_ABSTRACT` marks a C type: the class
-     * still serves as a parent for further registered subclasses, which instantiate as usual, but
-     * constructing it directly throws, whether from JavaScript or from a native caller.
-     */
+    /** Prevents direct construction while allowing registered subclasses. */
     abstract?: boolean;
-    /**
-     * Name instances of the new type carry in CSS, applied through `gtk_widget_class_set_css_name`
-     * from inside the type's `class_init`, so every instance is born with it, wherever it is
-     * created from. Requires the class to extend `Gtk.Widget`; registering a non-widget with a
-     * `cssName` throws.
-     */
+    /** CSS node name for a `Gtk.Widget` subclass. */
     cssName?: string;
     /**
-     * Hook run once, synchronously, while `registerClass` registers the type, after its
-     * `class_init` has installed the vfuncs, properties and signals declared here. It receives the
-     * new type's class struct wrapped in its generated GTypeStruct wrapper, so class-level setup
-     * calls such as `Gtk.WidgetClass.installAction`, `Gtk.WidgetClass.addShortcut` and
-     * `Gtk.WidgetClass.setLayoutManagerType` have somewhere to land. The wrapper serves the
-     * members of every struct in the parent chain on one object: a widget subclass sees
-     * `Gtk.WidgetClass` and `GObject.ObjectClass` members alike, so the parameter can be declared
-     * as whichever of those types the hook needs. The class struct belongs to the type system for
-     * the life of the process, so keeping the wrapper around past the hook is safe, if rarely
-     * useful. An exception the hook throws propagates out of `registerClass`, with the type
-     * already registered: GObject offers no way to unregister a static type.
+     * Runs once after registration with the wrapped class struct. An exception propagates after
+     * the static GType has already been registered and cannot be undone.
      */
     classInit?(typeStruct: object): void;
-    /**
-     * Interfaces the new type implements on top of the ones it inherits, given as the interface values
-     * themselves, such as `Gio.ListModel`. Their vtable slots are filled from the `vfunc`-prefixed methods on
-     * the class's prototype chain, each of which has to match the interface's `Impl` type, such as
-     * `Gio.ListModelImpl`.
-     */
+    /** Interfaces implemented through matching `vfunc` methods. */
     implements?: Interface<TInstance>[];
     /**
-     * Properties to install on the new type, keyed by the name JavaScript addresses each one by and
-     * valued with the `GObject.ParamSpec` describing it. A key is read in camelCase however it is
-     * written, so `dewPoint`, `dew_point` and `dew-point` all name the same member, and the ParamSpec
-     * has to carry a name that reads back as that same member, such as `dew-point`, or registration
-     * throws: the ParamSpec's name is the one GObject emits `notify` with, and a name the key does
-     * not spell reaches nothing that listens for it. A word starting with a digit is a word of its
-     * own on either side of that reading, so `level2Depth` takes a ParamSpec named `level-2-depth`
-     * as readily as one named `level2-depth`, the way `WebKit.Settings` names
-     * `enable-2d-canvas-acceleration` for its `enable2dCanvasAcceleration` member. An uppercase
-     * letter in the ParamSpec's own name is refused, since GObject notifies under that spelling
-     * and nothing else reads it back. Every property gains prototype accessors, one for the key as
-     * written, one for it with dashes turned into underscores and one for it in camelCase, each
-     * unless the class already defines that name. They serve the value from storage of their own on
-     * the instance, which is also what the type's `get_property` and `set_property` slots read and
-     * write, so a value set from JavaScript, from `g_object_set_property` and at construction all
-     * land in the same place.
-     *
-     * A write the ParamSpec would refuse throws rather than reaching GObject, which reports such a
-     * write as a GLib critical and drops it: a `TypeError` for a read-only or construct-only
-     * property and for a value of a type the property cannot hold, and a `RangeError` for a value
-     * the ParamSpec rejects. The same checks run over a value handed to the constructor, where
-     * a construct-only property is the one that is writable. An accepted write emits one `notify`,
-     * which a `freeze_notify` batch collects; a write of the value the property already holds is
-     * dropped and emits none.
-     *
-     * `null` and `undefined` both mean NULL, and mean it only where the ParamSpec's own type holds
-     * NULL, which is a string, string-array, boxed, object, interface, param, variant or pointer
-     * property. Such a property holds the `null` either spelling wrote, so the member, the type's
-     * `get_property` slot and `g_object_get_property` serve the same thing, and writing the other
-     * spelling over it emits no `notify`. Every other property, so every integer, floating-point,
-     * boolean, enum, flags and GType one, refuses both with the same `TypeError` it refuses a
-     * string with, and keeps the value it already holds. It refuses them for what it holds rather
-     * than for its range, whatever that range is: the type is checked before the range, so a
-     * `gint` whose range excludes 0 answers a nullish with that same `TypeError` and never with
-     * the `RangeError` that names the value GObject would put in its place. The one place
-     * `undefined` means something else is the constructor, which reads it as the property not
-     * being given at all and leaves it at the ParamSpec's default, so a property is never handed a
-     * value it cannot serve back.
-     *
-     * A floating-point property takes every JavaScript number, `NaN` and both infinities
-     * included, and its ParamSpec alone rules on which of them the range admits: a `gdouble`
-     * bounded by `-Infinity` and `Infinity` holds either infinity, and a magnitude a bounded
-     * one excludes, like any `NaN`, comes back as the `RangeError` that names what GObject
-     * would put in its place rather than as the `TypeError` a type the property cannot hold
-     * earns. A `gfloat` property holds what GObject narrows the double to, so it serves `0.1`
-     * back as `0.10000000149011612` and a finite magnitude no `gfloat` reaches as an infinity,
-     * which the range then rules on in turn. That narrowing belongs to the property alone: the
-     * same magnitude written to a `gfloat` through a generated binding, a signal argument or a
-     * closure return is refused outright rather than narrowed.
-     *
-     * A generated property of a wrapped type answers a nullish differently, and the two halves of
-     * the API disagree here: that property marshals what it is written through its descriptor
-     * rather than through the checks above, so `new Gtk.Label({ widthRequest: null })` and a later
-     * write of `null` to that member both land 0, where a `gint` installed here refuses both.
-     *
-     * A class that defines the camelCase member itself owns the property: its own accessor decides
-     * what a write means, the other spellings forward to it, and the type's property slots read
-     * and write it rather than the generated storage.
+     * ParamSpecs keyed by their JavaScript property names. Keys and ParamSpec names must canonicalize
+     * to the same member. Writes validate flags, types, and ranges and notify only on changes.
+     * Nullish values require a nullable GType; constructor `undefined` means omitted. An existing
+     * camelCase accessor remains authoritative.
      */
     properties?: TProperties;
     /**
-     * Signals to create on the new type, keyed by signal name and valued with the
-     * {@link SignalSpec} describing each one. A name has to start with a lowercase letter, continue
-     * in lowercase letters, digits, `-` and `_`, and be new to the type: one an ancestor type or a
-     * listed interface already carries throws, and so does one carrying an uppercase letter, which
-     * GObject would carry under that exact spelling, out of reach of both its dashed spelling and
-     * its `on<SignalName>` default handler. The two word separators spell the same signal, so a
-     * signal declared as `data_changed` is connected to and emitted as `data-changed` too.
-     *
-     * Instances connect and emit by name through the same `connect`, `on`, `once`, `off` and
-     * `emit` surface inherited signals use: `registerClass` wraps `connect` and `emit` on the
-     * class's prototype to serve the declared names, unless the class defines the member itself,
-     * and hands every other name to the inherited implementation. A handler receives the
-     * emission's arguments without the leading emitter, matching a generated signal, and what it
-     * returns becomes the emission's return value when the signal declares one.
-     *
-     * The declared parameter GTypes rule the emission: `emit` takes exactly one argument per
-     * declared parameter, throwing a `TypeError` for any other count, and converts each argument
-     * into a `GValue` of the declared type, throwing for a value that type cannot hold. The signals
-     * are created with no class closure of their own, but a method named `on<SignalName>`
-     * becomes the signal's default handler, the way every `on`-prefixed method that names a
-     * signal the type carries does; see {@link registerClass}.
+     * New canonical signal names and specs. Declared GTypes validate emissions, and a matching
+     * `on<SignalName>` method becomes the default handler.
      */
     signals?: TSignals;
 };
@@ -381,62 +216,25 @@ const PROPERTY_VFUNC_SPECS: PropertyVfuncSpec[] = [
 ];
 
 const PROPERTY_VFUNC_NAMES: Set<string> = new Set(PROPERTY_VFUNC_SPECS.map((spec) => spec.methodName));
+const VFUNC_METHOD_PATTERN = /^vfunc[A-Z0-9]/;
 const TYPE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9\-_+]{2,}$/;
 const UPPER_CASE_PATTERN = /[A-Z]/;
 const SIGNAL_OVERRIDE_PATTERN = /^on[A-Z]/;
 
 /**
- * Registers a subclass of a wrapper class as a new GType, wiring up any class and interface
- * virtual functions it overrides, both for the interfaces it inherits and for the ones
- * `RegisterClassOptions.implements` names.
- *
- * Throws when the class does not extend a registered wrapper class, when it has no derivable type
- * name or the name is not a valid GType name, when an entry in
- * `RegisterClassOptions.implements` is not a registered interface, when a
- * listed interface has a prerequisite that neither the parent type nor another listed interface meets,
- * when the list names `Gio.AsyncInitable` as an interface the parent type does not already
- * implement and no method on the chain fills `vfuncInitAsync`, since the default `init_async`
- * would run `vfuncInit` on a worker thread, when an entry in
- * `RegisterClassOptions.properties` names its `GObject.ParamSpec` something the key it sits under
- * does not spell, when an entry in `RegisterClassOptions.signals` carries an invalid name, a name
- * spelled with an uppercase letter rather than dashed, a name the type already knows, a GType
- * that cannot hold a value, or an accumulator the spec does not admit, and when
- * `RegisterClassOptions.cssName` is
- * given for a class that does not extend `Gtk.Widget`. An exception thrown by
- * `RegisterClassOptions.classInit` also propagates, after the type has already been registered.
- *
- * A slot is filled from the `vfunc`-prefixed methods on the class's prototype chain, up to but not
- * including the registered ancestor the class extends, so a method an intermediate base class
- * declares fills a slot the same way one the class itself declares does. A slot nothing on that
- * chain fills is left untouched.
- *
- * Declare every slot as a method: a class field holding a function, such as `vfuncGetNItems = () => 1`,
- * is assigned to each instance after registration and never reaches the vtable.
- *
- * A method named `on<SignalName>` — the signal's name in camelCase after the `on`, so `onClicked`
- * for `clicked` and `onItemsChanged` for `items-changed` — becomes that signal's default handler
- * when the type carries the signal, whether an ancestor type or an implemented interface brings it
- * or `RegisterClassOptions.signals` declares it. The method is installed as a class-closure
- * override, so it runs on every emission, on the instances a native caller creates included, in
- * the stage the signal's flags name rather than alongside connected handlers. It receives the
- * emission's arguments without the leading emitter, with `this` bound to the emitter, and what it
- * returns becomes the emission's result when the signal declares one. The same discovery walks the
- * prototype chain vfunc discovery walks, and a subclass registering its own `on<SignalName>`
- * replaces the handler for its instances, where `super.on<SignalName>()` reaches the replaced one.
- * An `on`-prefixed method naming no signal the type carries is left alone as the ordinary method
- * it is.
+ * Registers a wrapper subclass as a GType with discovered vfuncs, properties, signals, and interfaces.
+ * Vfuncs must be prototype methods; function-valued fields never reach the vtable. A matching
+ * `on<SignalName>` method becomes the signal's default handler.
  *
- * An override of `vfuncConstructed` runs from inside the base constructor, before JavaScript
- * installs the subclass's field initializers and runs its constructor body, so a field still
- * reads `undefined` there and reading a `#private` field throws. Declare state the override
- * touches without an initializer, and assign private state from the constructor body after
- * `super()`. An instance a native caller creates, through `GObject.newv` or `Gtk.Builder`,
- * never runs the subclass constructor at all, so its declared fields stay uninitialized for
- * the object's whole life.
+ * `vfuncConstructed` runs before field initializers and the constructor body. Native-created
+ * instances never run the JavaScript constructor, so native-required state belongs in properties
+ * or `vfuncConstructed`. A new `Gio.AsyncInitable` must implement `vfuncInitAsync`.
  *
- * @param klass The subclass to register.
- * @param options What the new GType gains beyond the vtable slots the class overrides.
- * @returns The same class, now registered, with every name in `options.properties` in its property map.
+ * @param klass The wrapper subclass to register.
+ * @param options Additional GType configuration.
+ * @returns The registered class with declared properties and signals in its type.
+ * @throws For invalid parents, names, interfaces, vfuncs, properties, signals, or widget options.
+ * A `classInit` exception propagates after the static type has been registered and cannot be undone.
  */
 function registerClass<
     T extends AnyClass,
@@ -456,6 +254,7 @@ function registerClass(klass: AnyClass, options: AnyRegisterClassOptions = {}):
 
     const name = resolveTypeName(klass, options);
     const declaredTypes = resolveInterfaceTypes(klass, options.implements ?? []);
+    assertInterfacePrerequisites(klass, parentType, declaredTypes);
     const adoptedTypes = declaredTypes.filter((gtype) => !typeIsA(parentType, gtype));
     const properties = options.properties ?? {};
     const signals = resolveDeclaredSignals(klass, options.signals ?? {});
@@ -471,6 +270,7 @@ function registerClass(klass: AnyClass, options: AnyRegisterClassOptions = {}):
 
     const claimedMethodNames = new Set(classVfuncs.map((vfunc) => vfunc.methodName));
     const interfaceBindings = discoverInterfaceBindings(methods, parentType, declaredTypes, claimedMethodNames);
+    assertClaimedVfuncs(klass, methods, claimedMethodNames, interfaceBindings);
 
     const nativeOptions = withNativeSignals(
         toNativeOptions(classVfuncs, interfaceBindings, properties, options),
@@ -677,6 +477,61 @@ function wrapVfunc(
     );
 }
 
+const claimedVfuncNames = (
+    claimedMethodNames: Set<string>,
+    interfaceBindings: InterfaceVfuncBinding[],
+): Set<string> => {
+    const claimed = new Set(claimedMethodNames);
+
+    for (const binding of interfaceBindings) {
+        for (const vfunc of binding.vfuncs) {
+            claimed.add(vfunc.methodName);
+        }
+    }
+
+    return claimed;
+};
+
+const isPrerequisiteMet = (parentType: bigint, declaredTypes: bigint[], prerequisite: bigint): boolean =>
+    typeIsA(parentType, prerequisite) || declaredTypes.includes(prerequisite);
+
+function assertPrerequisitesFor(klass: AnyClass, parentType: bigint, declaredTypes: bigint[], iface: bigint): void {
+    for (const prerequisite of typeInterfacePrerequisites(iface)) {
+        if (!isPrerequisiteMet(parentType, declaredTypes, prerequisite)) {
+            throw new TypeError(
+                `registerClass: ${klass.name} does not meet prerequisite ` +
+                `'${typeName(prerequisite) ?? String(prerequisite)}' of interface ` +
+                `'${typeName(iface) ?? String(iface)}'`,
+            );
+        }
+    }
+}
+
+function assertInterfacePrerequisites(klass: AnyClass, parentType: bigint, declaredTypes: bigint[]): void {
+    for (const iface of declaredTypes) {
+        assertPrerequisitesFor(klass, parentType, declaredTypes, iface);
+    }
+}
+
+function assertClaimedVfuncs(
+    klass: AnyClass,
+    methods: MethodTable,
+    claimedMethodNames: Set<string>,
+    interfaceBindings: InterfaceVfuncBinding[],
+): void {
+    const claimed = claimedVfuncNames(claimedMethodNames, interfaceBindings);
+
+    for (const methodName of methods.keys()) {
+        if (VFUNC_METHOD_PATTERN.test(methodName) && !claimed.has(methodName)) {
+            throw new Error(
+                `registerClass: ${klass.name}.${methodName} matches no vtable slot on any ancestor ` +
+                "or implemented interface, so the override would never be called; check the name against " +
+                "the parent class's virtual methods",
+            );
+        }
+    }
+}
+
 function discoverInterfaceBindings(
     methods: MethodTable,
     parentGtype: bigint,