@gtkx/runtime 1.3.0 → 1.5.0

package/dist/t.js.map

@@ -1 +1 @@
-{"version":3,"file":"t.js","sourceRoot":"","sources":["../src/t.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAwF7B;;;;GAIG;AACH,MAAM,CAAC,GAAM;IACT,IAAI;IACJ,IAAI,EAAE,OAAO,CAAC,KAAK;IACnB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,QAAQ,EAAE,OAAO,CAAC,SAAS;IAC3B,SAAS,EAAE,OAAO,CAAC,UAAU;IAC7B,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,OAAO,EAAE,OAAO,CAAC,QAAQ;IACzB,OAAO,EAAE,OAAO,CAAC,QAAQ;IACzB,OAAO,EAAE,OAAO,CAAC,QAAQ;IACzB,IAAI,EAAE,OAAO,CAAC,KAAK;IACnB,OAAO,EAAE,OAAO,CAAC,QAAQ;IACzB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,WAAW,EAAE,OAAO,CAAC,YAAY;IACjC,GAAG,EAAE,OAAO,CAAC,IAAI;IACjB,SAAS,EAAE,OAAO,CAAC,UAAU;IAC7B,IAAI,EAAE,OAAO,CAAC,KAAK;IACnB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,IAAI,EAAE,OAAO,CAAC,KAAK;IACnB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,QAAQ,EAAE,OAAO,CAAC,SAAS;IAC3B,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,SAAS,EAAE,OAAO,CAAC,UAAU;IAC7B,UAAU,EAAE,OAAO,CAAC,WAAW;IAC/B,UAAU,EAAE,OAAO,CAAC,WAAW;IAC/B,WAAW,EAAE,OAAO,CAAC,YAAY;IACjC,QAAQ,EAAE,OAAO,CAAC,SAAS;IAC3B,EAAE;CACL,CAAC;AAEF,OAAO,EAAE,CAAC,EAAE,CAAC","sourcesContent":["import { bind } from \"./bind.js\";\nimport * as helpers from \"./descriptors.js\";\nimport { fn } from \"./fn.js\";\n\n/** The descriptor factories and function binders exposed as {@link t}. */\ntype T = {\n    /** Binds a symbol in a shared library to a callable that marshals its arguments and return value. */\n    bind: typeof bind;\n    /** Descriptor for a `gint8`, marshalled as a number. */\n    int8: typeof helpers.int8T;\n    /** Descriptor for a `guint8`, marshalled as a number. */\n    uint8: typeof helpers.uint8T;\n    /** Descriptor for a `gint16`, marshalled as a number. */\n    int16: typeof helpers.int16T;\n    /** Descriptor for a `guint16`, marshalled as a number. */\n    uint16: typeof helpers.uint16T;\n    /** Descriptor for a `gint32`, marshalled as a number. */\n    int32: typeof helpers.int32T;\n    /** Descriptor for a `guint32`, marshalled as a number. */\n    uint32: typeof helpers.uint32T;\n    /** Descriptor for a `gint64`, marshalled as a number and rejected outside the 2^53 safe range. */\n    int64: typeof helpers.int64T;\n    /** Descriptor for a `guint64`, marshalled as a number and rejected outside the 2^53 safe range. */\n    uint64: typeof helpers.uint64T;\n    /** Descriptor for a `gint64`, marshalled as a bigint so the full 64-bit range survives. */\n    bigint64: typeof helpers.bigint64T;\n    /** Descriptor for a `guint64`, marshalled as a bigint so the full 64-bit range survives. */\n    biguint64: typeof helpers.biguint64T;\n    /** Descriptor for a `GType`, marshalled as a bigint and recognized as a GType by GValue conversion. */\n    gtype: typeof helpers.gtypeT;\n    /** Descriptor for a `gfloat`. */\n    float32: typeof helpers.float32T;\n    /** Descriptor for a `gdouble`. */\n    float64: typeof helpers.float64T;\n    /** Descriptor for a `gboolean`, marshalled as a JavaScript boolean. */\n    boolean: typeof helpers.booleanT;\n    /** Descriptor for the absence of a value, used as the return descriptor of a `void` function. */\n    void: typeof helpers.voidT;\n    /** Descriptor for a `gunichar`, marshalled as a single-character string or a codepoint number. */\n    unichar: typeof helpers.unicharT;\n    /** Descriptor for an opaque `gpointer` argument, taken from a typed array's memory or a numeric address. */\n    buffer: typeof helpers.bufferT;\n    /**\n     * Builds a descriptor for a C string, whose optional length sizes the caller-allocated buffer\n     * used when the string is passed by reference.\n     */\n    string: typeof helpers.stringT;\n    /** Builds a descriptor for a `GObject`, wrapped in the class registered for its runtime GType. */\n    object: typeof helpers.objectT;\n    /** Builds a descriptor for a `GBoxed` value of the named type. */\n    boxed: typeof helpers.boxedT;\n    /** Builds a descriptor for a plain C struct. */\n    struct: typeof helpers.structT;\n    /** Builds a descriptor for a fundamental type whose lifetime is managed by named ref and unref functions. */\n    fundamental: typeof helpers.fundamentalT;\n    /** Wraps a descriptor in a pointer to it, for an output or inout argument. */\n    ref: typeof helpers.refT;\n    /** Builds a descriptor for a `GHashTable`, marshalled as an array of key/value pairs. */\n    hashTable: typeof helpers.hashTableT;\n    /** Builds a descriptor for an enumeration, resolving its GType from the named `get_type` function. */\n    enum: typeof helpers.enumT;\n    /** Builds a descriptor for a flags type, resolving its GType from the named `get_type` function. */\n    flags: typeof helpers.flagsT;\n    /** Builds a descriptor for an array of items in one of the supported container layouts. */\n    array: typeof helpers.arrayT;\n    /** Builds a descriptor for a `GList` of items. */\n    list: typeof helpers.listT;\n    /** Builds a descriptor for a `GSList` of items. */\n    slist: typeof helpers.slistT;\n    /** Builds a descriptor for a `GPtrArray` of items. */\n    ptrArray: typeof helpers.ptrArrayT;\n    /** Builds a descriptor for a `GArray` of items. */\n    gArray: typeof helpers.gArrayT;\n    /** Builds a descriptor for a `GByteArray`. */\n    byteArray: typeof helpers.byteArrayT;\n    /** Builds a descriptor for a C array whose length is carried by another argument. */\n    sizedArray: typeof helpers.sizedArrayT;\n    /** Builds a descriptor for a C array of a fixed length. */\n    fixedArray: typeof helpers.fixedArrayT;\n    /** Builds a descriptor for an out pointer into the buffer another argument supplied. */\n    cursorArray: typeof helpers.cursorArrayT;\n    /** Builds a descriptor for a function pointer, marshalling a JavaScript function into a native closure. */\n    callback: typeof helpers.callbackT;\n    /**\n     * Binds a native function, wiring up argument directions, `GError` checking, and packing output\n     * arguments into the result.\n     */\n    fn: typeof fn;\n};\n\n/**\n * Type descriptor builder: a collection of factory helpers that describe C types for\n * FFI marshalling, plus `bind` to bind a native function and `fn` to describe a\n * function signature.\n */\nconst t: T = {\n    bind,\n    int8: helpers.int8T,\n    uint8: helpers.uint8T,\n    int16: helpers.int16T,\n    uint16: helpers.uint16T,\n    int32: helpers.int32T,\n    uint32: helpers.uint32T,\n    int64: helpers.int64T,\n    uint64: helpers.uint64T,\n    bigint64: helpers.bigint64T,\n    biguint64: helpers.biguint64T,\n    gtype: helpers.gtypeT,\n    float32: helpers.float32T,\n    float64: helpers.float64T,\n    boolean: helpers.booleanT,\n    void: helpers.voidT,\n    unichar: helpers.unicharT,\n    buffer: helpers.bufferT,\n    string: helpers.stringT,\n    object: helpers.objectT,\n    boxed: helpers.boxedT,\n    struct: helpers.structT,\n    fundamental: helpers.fundamentalT,\n    ref: helpers.refT,\n    hashTable: helpers.hashTableT,\n    enum: helpers.enumT,\n    flags: helpers.flagsT,\n    array: helpers.arrayT,\n    list: helpers.listT,\n    slist: helpers.slistT,\n    ptrArray: helpers.ptrArrayT,\n    gArray: helpers.gArrayT,\n    byteArray: helpers.byteArrayT,\n    sizedArray: helpers.sizedArrayT,\n    fixedArray: helpers.fixedArrayT,\n    cursorArray: helpers.cursorArrayT,\n    callback: helpers.callbackT,\n    fn,\n};\n\nexport { t };\n"]}
+{"version":3,"file":"t.js","sourceRoot":"","sources":["../src/t.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAkG7B;;;;GAIG;AACH,MAAM,CAAC,GAAM;IACT,IAAI;IACJ,IAAI,EAAE,OAAO,CAAC,KAAK;IACnB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,QAAQ,EAAE,OAAO,CAAC,SAAS;IAC3B,SAAS,EAAE,OAAO,CAAC,UAAU;IAC7B,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,OAAO,EAAE,OAAO,CAAC,QAAQ;IACzB,OAAO,EAAE,OAAO,CAAC,QAAQ;IACzB,OAAO,EAAE,OAAO,CAAC,QAAQ;IACzB,IAAI,EAAE,OAAO,CAAC,KAAK;IACnB,OAAO,EAAE,OAAO,CAAC,QAAQ;IACzB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,WAAW,EAAE,OAAO,CAAC,YAAY;IACjC,GAAG,EAAE,OAAO,CAAC,IAAI;IACjB,SAAS,EAAE,OAAO,CAAC,UAAU;IAC7B,IAAI,EAAE,OAAO,CAAC,KAAK;IACnB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,IAAI,EAAE,OAAO,CAAC,KAAK;IACnB,KAAK,EAAE,OAAO,CAAC,MAAM;IACrB,QAAQ,EAAE,OAAO,CAAC,SAAS;IAC3B,MAAM,EAAE,OAAO,CAAC,OAAO;IACvB,SAAS,EAAE,OAAO,CAAC,UAAU;IAC7B,UAAU,EAAE,OAAO,CAAC,WAAW;IAC/B,UAAU,EAAE,OAAO,CAAC,WAAW;IAC/B,WAAW,EAAE,OAAO,CAAC,YAAY;IACjC,QAAQ,EAAE,OAAO,CAAC,SAAS;IAC3B,EAAE;IACF,KAAK;IACL,OAAO;CACV,CAAC;AAEF,OAAO,EAAE,CAAC,EAAE,CAAC","sourcesContent":["import { bind } from \"./bind.js\";\nimport * as helpers from \"./descriptors.js\";\nimport { field, fieldAt } from \"./field.js\";\nimport { fn } from \"./fn.js\";\n\n/** The descriptor factories and function binders exposed as {@link t}. */\ntype T = {\n    /** Binds a symbol in a shared library to a callable that marshals its arguments and return value. */\n    bind: typeof bind;\n    /** Descriptor for a `gint8`, marshalled as a number. */\n    int8: typeof helpers.int8T;\n    /** Descriptor for a `guint8`, marshalled as a number. */\n    uint8: typeof helpers.uint8T;\n    /** Descriptor for a `gint16`, marshalled as a number. */\n    int16: typeof helpers.int16T;\n    /** Descriptor for a `guint16`, marshalled as a number. */\n    uint16: typeof helpers.uint16T;\n    /** Descriptor for a `gint32`, marshalled as a number. */\n    int32: typeof helpers.int32T;\n    /** Descriptor for a `guint32`, marshalled as a number. */\n    uint32: typeof helpers.uint32T;\n    /** Descriptor for a `gint64`, marshalled as a number and rejected outside the 2^53 safe range. */\n    int64: typeof helpers.int64T;\n    /** Descriptor for a `guint64`, marshalled as a number and rejected outside the 2^53 safe range. */\n    uint64: typeof helpers.uint64T;\n    /** Descriptor for a `gint64`, marshalled as a bigint so the full 64-bit range survives. */\n    bigint64: typeof helpers.bigint64T;\n    /** Descriptor for a `guint64`, marshalled as a bigint so the full 64-bit range survives. */\n    biguint64: typeof helpers.biguint64T;\n    /** Descriptor for a `GType`, marshalled as a bigint and recognized as a GType by GValue conversion. */\n    gtype: typeof helpers.gtypeT;\n    /** Descriptor for a `gfloat`. */\n    float32: typeof helpers.float32T;\n    /** Descriptor for a `gdouble`. */\n    float64: typeof helpers.float64T;\n    /** Descriptor for a `gboolean`, marshalled as a JavaScript boolean. */\n    boolean: typeof helpers.booleanT;\n    /** Descriptor for the absence of a value, used as the return descriptor of a `void` function. */\n    void: typeof helpers.voidT;\n    /** Descriptor for a `gunichar`, marshalled as a single-character string or a codepoint number. */\n    unichar: typeof helpers.unicharT;\n    /** Descriptor for an opaque `gpointer` argument, taken from a typed array's memory or a numeric address. */\n    buffer: typeof helpers.bufferT;\n    /**\n     * Builds a descriptor for a C string, whose optional length sizes the caller-allocated buffer\n     * used when the string is passed by reference.\n     */\n    string: typeof helpers.stringT;\n    /** Builds a descriptor for a `GObject`, wrapped in the class registered for its runtime GType. */\n    object: typeof helpers.objectT;\n    /** Builds a descriptor for a `GBoxed` value of the named type. */\n    boxed: typeof helpers.boxedT;\n    /** Builds a descriptor for a plain C struct. */\n    struct: typeof helpers.structT;\n    /** Builds a descriptor for a fundamental type whose lifetime is managed by named ref and unref functions. */\n    fundamental: typeof helpers.fundamentalT;\n    /** Wraps a descriptor in a pointer to it, for an output or inout argument. */\n    ref: typeof helpers.refT;\n    /** Builds a descriptor for a `GHashTable`, marshalled as an array of key/value pairs. */\n    hashTable: typeof helpers.hashTableT;\n    /** Builds a descriptor for an enumeration, resolving its GType from the named `get_type` function. */\n    enum: typeof helpers.enumT;\n    /** Builds a descriptor for a flags type, resolving its GType from the named `get_type` function. */\n    flags: typeof helpers.flagsT;\n    /** Builds a descriptor for an array of items in one of the supported container layouts. */\n    array: typeof helpers.arrayT;\n    /** Builds a descriptor for a `GList` of items. */\n    list: typeof helpers.listT;\n    /** Builds a descriptor for a `GSList` of items. */\n    slist: typeof helpers.slistT;\n    /** Builds a descriptor for a `GPtrArray` of items. */\n    ptrArray: typeof helpers.ptrArrayT;\n    /** Builds a descriptor for a `GArray` of items. */\n    gArray: typeof helpers.gArrayT;\n    /** Builds a descriptor for a `GByteArray`. */\n    byteArray: typeof helpers.byteArrayT;\n    /** Builds a descriptor for a C array whose length is carried by another argument. */\n    sizedArray: typeof helpers.sizedArrayT;\n    /** Builds a descriptor for a C array of a fixed length. */\n    fixedArray: typeof helpers.fixedArrayT;\n    /** Builds a descriptor for an out pointer into the buffer another argument supplied. */\n    cursorArray: typeof helpers.cursorArrayT;\n    /** Builds a descriptor for a function pointer, marshalling a JavaScript function into a native closure. */\n    callback: typeof helpers.callbackT;\n    /**\n     * Binds a native function, wiring up argument directions, `GError` checking, and packing output\n     * arguments into the result.\n     */\n    fn: typeof fn;\n    /**\n     * Binds a struct field at a fixed offset, compiling its descriptor once into an accessor that\n     * reads and writes it.\n     */\n    field: typeof field;\n    /**\n     * Binds a struct field whose offset is supplied per access, for walking records stored at a\n     * stride in a buffer.\n     */\n    fieldAt: typeof fieldAt;\n};\n\n/**\n * Type descriptor builder: a collection of factory helpers that describe C types for\n * FFI marshalling, plus `bind` to bind a native function and `fn` to describe a\n * function signature.\n */\nconst t: T = {\n    bind,\n    int8: helpers.int8T,\n    uint8: helpers.uint8T,\n    int16: helpers.int16T,\n    uint16: helpers.uint16T,\n    int32: helpers.int32T,\n    uint32: helpers.uint32T,\n    int64: helpers.int64T,\n    uint64: helpers.uint64T,\n    bigint64: helpers.bigint64T,\n    biguint64: helpers.biguint64T,\n    gtype: helpers.gtypeT,\n    float32: helpers.float32T,\n    float64: helpers.float64T,\n    boolean: helpers.booleanT,\n    void: helpers.voidT,\n    unichar: helpers.unicharT,\n    buffer: helpers.bufferT,\n    string: helpers.stringT,\n    object: helpers.objectT,\n    boxed: helpers.boxedT,\n    struct: helpers.structT,\n    fundamental: helpers.fundamentalT,\n    ref: helpers.refT,\n    hashTable: helpers.hashTableT,\n    enum: helpers.enumT,\n    flags: helpers.flagsT,\n    array: helpers.arrayT,\n    list: helpers.listT,\n    slist: helpers.slistT,\n    ptrArray: helpers.ptrArrayT,\n    gArray: helpers.gArrayT,\n    byteArray: helpers.byteArrayT,\n    sizedArray: helpers.sizedArrayT,\n    fixedArray: helpers.fixedArrayT,\n    cursorArray: helpers.cursorArrayT,\n    callback: helpers.callbackT,\n    fn,\n    field,\n    fieldAt,\n};\n\nexport { t };\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gtkx/runtime",
-  "version": "1.3.0",
-  "description": "FFI runtime the generated GTKX bindings call into: type descriptors, GValue marshalling, signals, GObject lifecycle",
+  "version": "1.5.0",
+  "description": "FFI runtime for the generated GTK bindings: types, GValues, signals.",
   "keywords": [
     "gtkx",
     "gtk",
@@ -55,11 +55,11 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@gtkx/utils": "1.3.0",
-    "@gtkx/native": "1.3.0"
+    "@gtkx/native": "1.5.0",
+    "@gtkx/utils": "1.5.0"
   },
   "devDependencies": {
-    "@gtkx/vitest": "1.3.0"
+    "@gtkx/vitest": "1.5.0"
   },
   "scripts": {
     "release": "tsx ../../scripts/release-package.ts"

package/src/field.ts

@@ -0,0 +1,76 @@
+import {
+    bindField,
+    type Descriptor,
+    type ExternalObject,
+    type FieldDescriptor,
+    type Handle,
+    readField,
+    writeField,
+} from "@gtkx/native";
+
+/**
+ * A field of a native struct at a fixed offset, bound once against the descriptor its bytes are
+ * marshalled through, so the descriptor is not parsed again on access.
+ */
+type Field = {
+    /** Reads and decodes the field out of `handle`'s memory. */
+    read: (handle: ExternalObject<Handle>) => unknown;
+    /** Encodes `value` and writes it into the field of `handle`'s memory. */
+    write: (handle: ExternalObject<Handle>, value: unknown) => void;
+};
+
+/**
+ * A field of a native struct whose offset is supplied per access, bound once against the
+ * descriptor its bytes are marshalled through, for walking records stored at a stride.
+ */
+type StridedField = {
+    /** Reads and decodes the field `offset` bytes into `handle`'s memory. */
+    read: (handle: ExternalObject<Handle>, offset: number) => unknown;
+    /** Encodes `value` and writes it `offset` bytes into `handle`'s memory. */
+    write: (handle: ExternalObject<Handle>, offset: number, value: unknown) => void;
+};
+
+/**
+ * Binds a struct field whose offset is only known per access, compiling `descriptor` once into an
+ * accessor that reads and writes it wherever it is pointed. Use it to walk records stored one
+ * after another in a buffer; {@link field} is the one to reach for when the offset is fixed.
+ *
+ * @param descriptor Describes how the field's bytes are marshalled.
+ * @returns An accessor reading and writing that field at any offset of any handle it is given.
+ */
+const fieldAt = (descriptor: Descriptor): StridedField => {
+    const bound: ExternalObject<FieldDescriptor> = bindField(descriptor);
+
+    return {
+        read: (handle, offset) => readField(bound, handle, offset),
+        write: (handle, offset, value) => {
+            writeField(bound, handle, offset, value);
+        },
+    };
+};
+
+/**
+ * Binds a struct field at a fixed offset, compiling `descriptor` once into an accessor that reads
+ * and writes it. The `read` and `write` functions compile the descriptor on every call instead, so
+ * they remain the ones to reach for when a descriptor is only known per access.
+ *
+ * @param descriptor Describes how the field's bytes are marshalled.
+ * @param offset Byte offset of the field within its owner's memory.
+ * @returns An accessor reading and writing that field of any handle it is given.
+ */
+const field = (descriptor: Descriptor, offset: number): Field => {
+    if (!Number.isSafeInteger(offset) || offset < 0) {
+        throw new RangeError(`A field offset must be a safe whole byte count, got ${String(offset)}`);
+    }
+
+    const bound = fieldAt(descriptor);
+
+    return {
+        read: (handle) => bound.read(handle, offset),
+        write: (handle, value) => {
+            bound.write(handle, offset, value);
+        },
+    };
+};
+
+export { field, type Field, fieldAt, type StridedField };

package/src/index.ts

@@ -7,6 +7,8 @@ export { type ClosureCallback, ClosureMarshalError, toClosure, tryToClosure } fr
 /** @public */
 export { createErrorDomain, type ErrorDomain } from "./error.js";
 /** @public */
+export { type Field, type StridedField } from "./field.js";
+/** @public */
 export { onExit, quit, quitApplication, runApplication, type RunApplicationResult } from "./lifecycle.js";
 /** @public */
 export { offSignal, onceSignal, onSignal } from "./listeners.js";
@@ -28,7 +30,12 @@ export { getParamSpecFlags, getParamSpecOwnerType, getParamSpecValueType } from
 /** @public */
 export { promisify, trimFinish } from "./promisify.js";
 /** @public */
-export { coerceObjectProperty, newParamSpecOverride } from "./properties.js";
+export {
+    coerceObjectProperty,
+    getDeclaredPropertyName,
+    isReadableProperty,
+    newParamSpecOverride,
+} from "./properties.js";
 /** @public */
 export { matchAllRegex, matchRegex } from "./regex.js";
 /** @public */
@@ -50,7 +57,14 @@ export {
     type WrapperClassResolver,
 } from "./registry.js";
 /** @public */
-export { connectSignal, disconnectSignal, emitSignal, getSignalBaseName, type SignalHandler } from "./signal.js";
+export {
+    connectSignal,
+    disconnectSignal,
+    emitSignal,
+    getSignalBaseName,
+    type SignalHandler,
+    signalForHandlerName,
+} from "./signal.js";
 /** @public */
 export { t } from "./t.js";
 /** @public */

package/src/param-spec.ts

@@ -154,6 +154,7 @@ const getParamSpecOwnerType = (spec: object): bigint => {
 };
 
 const isParamWritable = (flags: number): boolean => (flags & PARAM_WRITABLE) !== 0;
+const isParamReadable = (flags: number): boolean => (flags & PARAM_READABLE) !== 0;
 const isParamConstructOnly = (flags: number): boolean => (flags & PARAM_CONSTRUCT_ONLY) !== 0;
 const isParamLaxlyValidated = (flags: number): boolean => (flags & PARAM_LAX_VALIDATION) !== 0;
 const isParamExplicitlyNotified = (flags: number): boolean => (flags & PARAM_EXPLICIT_NOTIFY) !== 0;
@@ -308,6 +309,7 @@ export {
     INT64_MAXIMUM,
     INT64_MINIMUM,
     isParamConstructOnly,
+    isParamReadable,
     isStringArray,
     isParamExplicitlyNotified,
     isParamLaxlyValidated,

package/src/properties.ts

@@ -1,8 +1,8 @@
 import type { ExternalObject, Handle, RegisterClassProperty } from "@gtkx/native";
 import type { AnyClass } from "@gtkx/utils";
-import { camelCase, kebabCase } from "@gtkx/utils";
+import { camelCase, kebabCase, toCamelIdentifier } from "@gtkx/utils";
 import { bind } from "./bind.js";
-import { biguint64T, fundamentalT, stringT, structT, voidT } from "./descriptors.js";
+import { biguint64T, fundamentalT, refT, sizedArrayT, stringT, structT, uint32T, voidT } from "./descriptors.js";
 import { LIB, PARAM_T, VALUE_T } from "./library.js";
 import {
     getParamFlags,
@@ -10,6 +10,7 @@ import {
     isParamConstructOnly,
     isParamExplicitlyNotified,
     isParamLaxlyValidated,
+    isParamReadable,
     isParamWritable,
     type ValueGuard,
     valueGuardFor,
@@ -47,14 +48,19 @@ type PropertyCheck = {
     scratch?: ExternalObject<Handle>;
 };
 
-type PropertyAccessor = PropertyCheck & {
-    memberName: string;
+type AccessorBase = PropertyCheck & {
     storage: symbol;
-    hasGeneratedMember: boolean;
-    isInterfaceProperty?: boolean;
     delegate?: InterfaceProperty;
 };
 
+type DeclaredAccessor = AccessorBase & {
+    isInterfaceProperty?: false;
+    memberName: string;
+    hasGeneratedMember: boolean;
+};
+
+type InterfaceAccessor = AccessorBase & { isInterfaceProperty: true };
+type PropertyAccessor = DeclaredAccessor | InterfaceAccessor;
 /** A `GObject.ParamSpec` wrapper describing one property's name, type, flags and default. */
 type PropertySpec = object;
 
@@ -82,6 +88,8 @@ const SET_PROPERTY_VFUNC = "vfuncSetProperty";
 const READ_ONLY_REASON = "the property is read-only";
 const CONSTRUCT_ONLY_REASON = "the property can only be set when the object is constructed";
 const CLASS_T = structT("borrowed");
+const CANONICAL_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const DECLARED_NAMES = Symbol("gtkx:declaredPropertyNames");
 
 const OVERRIDE_PARAM_T = fundamentalT(LIB, "g_param_spec_ref_sink", "g_param_spec_unref", {
     ownership: "borrowed",
@@ -95,6 +103,14 @@ const typeClassRef = bind(LIB, "g_type_class_ref", [biguint64T], CLASS_T);
 const typeClassUnref = bind(LIB, "g_type_class_unref", [CLASS_T], voidT);
 const coercionChecks: Map<bigint, Map<string, PropertyCheck | null>> = new Map();
 const classFindProperty = bind(LIB, "g_object_class_find_property", [CLASS_T, stringT("borrowed")], PARAM_T);
+
+const classListProperties = bind(
+    LIB,
+    "g_object_class_list_properties",
+    [CLASS_T, refT(uint32T)],
+    sizedArrayT(PARAM_T, 1, "full"),
+);
+
 const defaultInterfaceRef = bind(LIB, "g_type_default_interface_ref", [biguint64T], CLASS_T);
 const defaultInterfaceUnref = bind(LIB, "g_type_default_interface_unref", [CLASS_T], voidT);
 const interfaceFindProperty = bind(LIB, "g_object_interface_find_property", [CLASS_T, stringT("borrowed")], PARAM_T);
@@ -128,10 +144,22 @@ function checkFor(handle: ExternalObject<Handle>, name: string): PropertyCheck {
     };
 }
 
+function accessorSpecs(klass: ExternalObject<Handle>): Map<string, ExternalObject<Handle>> {
+    const specs: Map<string, ExternalObject<Handle>> = new Map();
+    const countRef = { value: 0 };
+
+    for (const pspec of classListProperties(klass, countRef) as ExternalObject<Handle>[]) {
+        specs.set(toCamelIdentifier(paramSpecName(pspec) as string), pspec);
+    }
+
+    return specs;
+}
+
 function findPropertySpec(klass: ExternalObject<Handle>, name: string): ExternalObject<Handle> | null {
-    const found = classFindProperty(klass, name) as ExternalObject<Handle> | null;
+    const found = (classFindProperty(klass, name) ??
+        classFindProperty(klass, canonicalCase(name))) as ExternalObject<Handle> | null;
 
-    return found ?? (classFindProperty(klass, canonicalCase(name)) as ExternalObject<Handle> | null);
+    return found ?? accessorSpecs(klass).get(toCamelIdentifier(name)) ?? null;
 }
 
 const sourceLabel = (source: bigint | AnyClass, gtype: bigint): string =>
@@ -290,6 +318,22 @@ function constructValueFor(wrapper: object, check: PropertyCheck, value: unknown
     return { name: check.propertyName, value: checkedValueFor(wrapper, check, value) };
 }
 
+/**
+ * Whether the type declares a readable GObject property under `propertyName`, asking GObject itself
+ * rather than looking for a generated accessor, which codegen omits when a method shares the name.
+ */
+function isReadableProperty(gtype: bigint, propertyName: string): boolean {
+    const klass = typeClassRef(gtype) as ExternalObject<Handle>;
+
+    try {
+        const pspec = findPropertySpec(klass, propertyName);
+
+        return pspec !== null && isParamReadable(getParamFlags(pspec));
+    } finally {
+        typeClassUnref(klass);
+    }
+}
+
 function lookupCoercionCheck(gtype: bigint, name: string): PropertyCheck | null {
     const klass = typeClassRef(gtype) as ExternalObject<Handle>;
 
@@ -436,13 +480,13 @@ function storedGetter(accessor: PropertyAccessor): (this: object) => unknown {
     };
 }
 
-function memberGetter(accessor: PropertyAccessor): (this: object) => unknown {
+function memberGetter(accessor: DeclaredAccessor): (this: object) => unknown {
     return function get(this: object) {
         return (this as Record<string, unknown>)[accessor.memberName];
     };
 }
 
-function memberSetter(accessor: PropertyAccessor): (this: object, value: unknown) => void {
+function memberSetter(accessor: DeclaredAccessor): (this: object, value: unknown) => void {
     return function set(this: object, value: unknown) {
         (this as Record<string, unknown>)[accessor.memberName] = value;
     };
@@ -454,7 +498,7 @@ function refusalFor(accessor: PropertyAccessor, reason: string): (this: object,
     };
 }
 
-function checkedSetter(accessor: PropertyAccessor): (this: object, value: unknown) => void {
+function checkedSetter(accessor: DeclaredAccessor): (this: object, value: unknown) => void {
     if (!isParamWritable(accessor.flags)) {
         return refusalFor(accessor, READ_ONLY_REASON);
     }
@@ -480,7 +524,7 @@ function defineAccessor(prototype: object, descriptor: PropertyDescriptor, alias
     Object.defineProperty(prototype, alias, descriptor);
 }
 
-function installAccessors(klass: AnyClass, accessor: PropertyAccessor): void {
+function installAccessors(klass: AnyClass, accessor: DeclaredAccessor): void {
     const prototype = (klass as { prototype: object }).prototype;
     accessor.hasGeneratedMember = !hasOwnMember(prototype, accessor.memberName);
 
@@ -509,16 +553,14 @@ function storageFor(propertyName: string): symbol {
     return created;
 }
 
-function interfaceAccessorFor(dispatch: PropertyDispatch, pspec: PropertySpec): PropertyAccessor {
+function interfaceAccessorFor(dispatch: PropertyDispatch, pspec: PropertySpec): InterfaceAccessor {
     const handle = getHandle(pspec);
     const propertyName = paramSpecName(handle) as string;
     const delegate = dispatch.delegates.get(propertyName);
 
-    const accessor: PropertyAccessor = {
+    const accessor: InterfaceAccessor = {
         ...checkFor(handle, propertyName),
-        memberName: camelCase(propertyName),
         storage: storageFor(propertyName),
-        hasGeneratedMember: false,
         isInterfaceProperty: true,
     };
 
@@ -556,7 +598,7 @@ function callMember(instance: object, member: string, args: unknown[]): unknown
     return (fn as (...values: unknown[]) => unknown).apply(instance, args);
 }
 
-function backingMemberFor(instance: object, accessor: PropertyAccessor): string | undefined {
+function backingMemberFor(instance: object, accessor: DeclaredAccessor): string | undefined {
     if (accessor.hasGeneratedMember && !Object.hasOwn(instance, accessor.memberName)) {
         return undefined;
     }
@@ -632,16 +674,17 @@ function makeSetProperty(dispatch: PropertyDispatch) {
     };
 }
 
-function assertCanonicalName(klass: AnyClass, name: string, propertyName: string): void {
-    const canonical = canonicalCase(name);
+const isCanonicalName = (name: string, propertyName: string): boolean =>
+    CANONICAL_NAME_PATTERN.test(propertyName) && toCamelIdentifier(propertyName) === toCamelIdentifier(name);
 
-    if (propertyName === canonical) {
+function assertCanonicalName(klass: AnyClass, name: string, propertyName: string): void {
+    if (isCanonicalName(name, propertyName)) {
         return;
     }
 
     throw new TypeError(
         `registerClass: ${klass.name} keys the property '${name}' to a GObject.ParamSpec named ` +
-        `'${propertyName}', which is the name GObject notifies under; name the ParamSpec '${canonical}'`,
+        `'${propertyName}', which is the name GObject notifies under; name the ParamSpec '${canonicalCase(name)}'`,
     );
 }
 
@@ -651,8 +694,8 @@ function assertCanonicalNames(klass: AnyClass, properties: Record<string, Proper
     }
 }
 
-function buildAccessor(klass: AnyClass, name: string, pspec: PropertySpec): PropertyAccessor {
-    const accessor: PropertyAccessor = {
+function buildAccessor(klass: AnyClass, name: string, pspec: PropertySpec): DeclaredAccessor {
+    const accessor: DeclaredAccessor = {
         ...checkFor(getHandle(pspec), name),
         memberName: camelCase(name),
         storage: Symbol(`gtkx:property:${name}`),
@@ -664,7 +707,7 @@ function buildAccessor(klass: AnyClass, name: string, pspec: PropertySpec): Prop
     return accessor;
 }
 
-function buildAccessors(source: PropertyDispatchSource): PropertyAccessor[] {
+function buildAccessors(source: PropertyDispatchSource): DeclaredAccessor[] {
     const { klass, properties } = source;
     assertCanonicalNames(klass, properties);
 
@@ -691,11 +734,35 @@ function interfaceDelegatesFor(adoptedTypes: bigint[]): Map<string, InterfacePro
     return delegates;
 }
 
+function recordDeclaredNames(klass: AnyClass, accessors: DeclaredAccessor[]): void {
+    const proto = klass.prototype as Record<PropertyKey, unknown>;
+    const inherited = proto[DECLARED_NAMES] as Record<string, string> | undefined;
+    const own: Record<string, string> = {};
+
+    for (const accessor of accessors) {
+        own[accessor.memberName] = accessor.propertyName;
+    }
+
+    Object.defineProperty(proto, DECLARED_NAMES, { value: { ...inherited, ...own }, enumerable: false });
+}
+
 function buildPropertyDispatch(source: PropertyDispatchSource): PropertyDispatch {
-    return {
-        accessors: buildAccessors(source),
-        delegates: interfaceDelegatesFor(source.adoptedTypes),
-    };
+    const declared = buildAccessors(source);
+    recordDeclaredNames(source.klass, declared);
+
+    return { accessors: [...declared], delegates: interfaceDelegatesFor(source.adoptedTypes) };
+}
+
+/**
+ * The GObject name a class registered with `registerClass` installed an accessor under, or
+ * `undefined` when the accessor names no property the class declared itself.
+ */
+function getDeclaredPropertyName(object: object, accessor: string): string | undefined {
+    const declared = (object as Record<PropertyKey, unknown>)[DECLARED_NAMES] as
+        | Record<string, string> |
+        undefined;
+
+    return declared?.[accessor];
 }
 
 function toNativeProperties(properties: Record<string, PropertySpec>): RegisterClassProperty[] {
@@ -708,6 +775,8 @@ function toNativeProperties(properties: Record<string, PropertySpec>): RegisterC
 export {
     buildPropertyDispatch,
     coerceObjectProperty,
+    getDeclaredPropertyName,
+    isReadableProperty,
     coercePropertyValue,
     constructPropertyFor,
     GET_PROPERTY_VFUNC,

package/src/register-class.ts

@@ -35,7 +35,9 @@ import {
     emitDeclaredSignal,
     getSignalBaseName,
     overrideSignalClassClosure,
+    signalForHandlerName,
     type SignalHandler,
+    signalIdFor,
 } from "./signal.js";
 import {
     TYPE_INTERFACE,
@@ -251,10 +253,15 @@ type RegisterClassOptions<
      * 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 the canonical spelling of that name, `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. 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
+     * 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
@@ -305,9 +312,11 @@ type RegisterClassOptions<
     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 letter, continue in
-     * letters, digits, `-` and `_`, and be new to the type: one an ancestor type or a listed
-     * interface already carries throws. The two word separators spell the same signal, so a
+     * {@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
@@ -373,6 +382,7 @@ const PROPERTY_VFUNC_SPECS: PropertyVfuncSpec[] = [
 
 const PROPERTY_VFUNC_NAMES: Set<string> = new Set(PROPERTY_VFUNC_SPECS.map((spec) => spec.methodName));
 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]/;
 
 /**
@@ -387,9 +397,9 @@ const SIGNAL_OVERRIDE_PATTERN = /^on[A-Z]/;
  * 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 other than the canonical
- * spelling of the key it sits under, when an entry in
- * `RegisterClassOptions.signals` carries an invalid name, a name the type already knows, a GType
+ * `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
@@ -769,15 +779,39 @@ function buildPropertyVfunc(
 
 const canonicalSignalName = (name: string): string => name.replaceAll("_", "-");
 
+function assertLowerCaseSignalName(klass: AnyClass, name: string): void {
+    if (!UPPER_CASE_PATTERN.test(name)) {
+        return;
+    }
+
+    throw new TypeError(
+        `registerClass: ${klass.name} declares the signal '${name}'; GObject would carry it under that ` +
+        "exact spelling, out of reach of both its dashed spelling and its default handler; " +
+        `declare it as '${kebabCase(name)}'`,
+    );
+}
+
+function overriddenSignalId(type: bigint, methodName: string): number {
+    if (!SIGNAL_OVERRIDE_PATTERN.test(methodName)) {
+        return 0;
+    }
+
+    const signal = signalForHandlerName(type, methodName);
+
+    return signal === undefined ? 0 : signalIdFor(type, signal);
+}
+
 function installSignalOverrides(newType: bigint, methods: MethodTable): void {
     for (const [methodName, fn] of methods) {
-        if (!SIGNAL_OVERRIDE_PATTERN.test(methodName)) {
+        const signalId = overriddenSignalId(newType, methodName);
+
+        if (signalId === 0) {
             continue;
         }
 
         const handler = fn as (...args: unknown[]) => unknown;
 
-        overrideSignalClassClosure(newType, kebabCase(methodName.slice(2)), (...args: unknown[]) =>
+        overrideSignalClassClosure(newType, signalId, (...args: unknown[]) =>
             handler.apply(args[0], args.slice(1)),
         );
     }
@@ -844,6 +878,7 @@ function resolveDeclaredSignals(klass: AnyClass, signals: Record<string, SignalS
     const table: Map<string, DeclaredSignalTypes> = new Map();
 
     for (const [name, spec] of Object.entries(signals)) {
+        assertLowerCaseSignalName(klass, name);
         const resolved = resolveDeclaredSignal(klass, name, spec);
         native.push(resolved.native);
         table.set(canonicalSignalName(name), resolved.declared);