@gtkx/native 1.2.2 → 1.4.0

package/README.md

@@ -5,9 +5,9 @@
 <h1 align="center">GTKX</h1>
 
 <p align="center">
-  The React framework for Linux.<br />
-  Write native Linux applications with React and TypeScript.
-  Built on the GNOME stack and standard web tooling.
+  The React framework for Linux, built on GTK.<br />
+  Write native GTK4 desktop applications with React and TypeScript.
+  Real GTK widgets, the GNOME stack, and standard web tooling.
 </p>
 
 <p align="center">
@@ -98,7 +98,7 @@ GTK4 is mature, and GtkBuilder XML can lay out a static interface, but nothing r
 - a React reconciler that exposes every GObject as a JSX element,
 - a CLI for scaffolding, development, and production builds,
 - a dev server with Fast Refresh that patches your running UI in place,
-- CSS-in-JS styling and high-level list, grid, and dialog components,
+- CSS-in-JS styling, React Spring animations, React Navigation stack, tab, drawer, and split view navigators, and high-level list, grid, and dialog components,
 - a Testing Library-style API for querying and driving your widgets in tests,
 - and a Model Context Protocol (MCP) server that exposes your live app to AI agents.
 
@@ -157,6 +157,8 @@ Explore the [example apps](https://github.com/gtkx-org/gtkx/tree/main/examples):
 - [`hello-world`](https://github.com/gtkx-org/gtkx/tree/main/examples/hello-world): the counter above.
 - [`gtk-demo`](https://github.com/gtkx-org/gtkx/tree/main/examples/gtk-demo): a React port of the official GTK4 widget showcase, covering lists, dialogs, gestures, CSS, and OpenGL.
 - [`browser`](https://github.com/gtkx-org/gtkx/tree/main/examples/browser): a WebKitWebView-based web browser.
+- [`animations`](https://github.com/gtkx-org/gtkx/tree/main/examples/animations): a tour of `@gtkx/animated`, React Spring animations driven by the GTK frame clock.
+- [`navigation`](https://github.com/gtkx-org/gtkx/tree/main/examples/navigation): a tour of `@gtkx/navigation`, React Navigation's stack, tab, and drawer navigators rendered with libadwaita.
 - [`tutorial`](https://github.com/gtkx-org/gtkx/tree/main/examples/tutorial): the Tasks app the documentation builds.
 
 ## Status

package/index.d.ts

@@ -39,6 +39,25 @@ export type ArrayKind =  'array'|
  */
 export declare function bind(sharedLibrary: string, symbolName: string, argDescriptors: Array<Descriptor>, returnDescriptor: Descriptor, fixedArgCount?: number | undefined | null): ExternalObject<CallDescriptor>
 
+/**
+ * Precompiles the marshalling `fieldDescriptor` describes into a reusable field descriptor that
+ * `readField` and `writeField` reach a field through, at whichever offset they are given. `read`
+ * and `write` compile the descriptor on every call instead.
+ *
+ * Binding costs about as much as one unbound access, so it pays off where the binding is hoisted
+ * out of the access path — held in a module-level constant an accessor reaches through — rather
+ * than made beside the access it serves.
+ */
+export declare function bindField(fieldDescriptor: Descriptor): ExternalObject<FieldDescriptor>
+
+/**
+ * Precompiles the argument and return marshalling of a call to a raw C function pointer into a
+ * reusable call descriptor that `call` can invoke. The pointer comes from a native caller that
+ * handed a callback into a JavaScript-implemented virtual function or callback, decoded as a
+ * bigint address; it must stay valid for as long as the descriptor is called through.
+ */
+export declare function bindFunctionPointer(fnPtr: bigint, argDescriptors: Array<Descriptor>, returnDescriptor: Descriptor, label: string): ExternalObject<CallDescriptor>
+
 /**
  * Precompiles a call to the virtual function slot at `byteOffset` of `instanceType`'s class
  * structure, of the `interfaceType` vtable that class carries, or of `interfaceType`'s own default
@@ -118,7 +137,7 @@ export type Descriptor =
   | { kind: 'float32' }
   | { kind: 'float64' }
   | { kind: 'enum', sharedLibrary: string, getTypeFnName: string, isSigned: boolean }
-  | { kind: 'flags', sharedLibrary: string, getTypeFnName: string, isSigned: boolean }
+  | { kind: 'flags', sharedLibrary: string, getTypeFnName: string, isSigned: boolean, mask?: number }
   | { kind: 'boolean' }
   | { kind: 'string', ownership: Ownership, length?: number }
   | { kind: 'object', ownership: Ownership, isCallScoped?: boolean }
@@ -127,10 +146,10 @@ export type Descriptor =
   | { kind: 'buffer' }
   | { kind: 'boxed', ownership: Ownership, typeName: string, sharedLibrary?: string, getTypeFnName?: string, freeFnName?: string, isCallerAllocated?: boolean, size?: number, isInline?: boolean }
   | { kind: 'struct', ownership: Ownership, size?: number, isCallerAllocated?: boolean, isInline?: boolean }
-  | { kind: 'fundamental', ownership: Ownership, sharedLibrary: string, refFnName: string, unrefFnName: string, typeName?: string, isInline?: boolean }
-  | { kind: 'array', itemDescriptor: Descriptor, arrayKind: ArrayKind, ownership: Ownership, baseParamIndex?: number, sizeParamIndex?: number, fixedSize?: number, elementSize?: number, isBytes?: boolean }
+  | { kind: 'fundamental', ownership: Ownership, sharedLibrary: string, refFnName: string, unrefFnName: string, typeName?: string, isCallerAllocated?: boolean, isInline?: boolean }
+  | { kind: 'array', itemDescriptor: Descriptor, arrayKind: ArrayKind, ownership: Ownership, baseParamIndex?: number, sizeParamIndex?: number, fixedSize?: number, elementSize?: number, isBytes?: boolean, isCallerAllocated?: boolean }
   | { kind: 'hashtable', keyDescriptor: Descriptor, valueDescriptor: Descriptor, ownership: Ownership }
-  | { kind: 'callback', argDescriptors: Array<Descriptor>, returnDescriptor: Descriptor, hasDestroy?: boolean, destroyKind?: DestroyNotifyKind, hasUserData?: boolean, userDataIndex?: number, scope?: CallbackScope }
+  | { kind: 'callback', argDescriptors: Array<Descriptor>, returnDescriptor: Descriptor, hasDestroy?: boolean, destroyKind?: DestroyNotifyKind, hasUserData?: boolean, userDataIndex?: number, canThrow?: boolean, scope?: CallbackScope }
   | { kind: 'ref', innerDescriptor: Descriptor, inout?: boolean }
 
 /**
@@ -142,10 +161,24 @@ export type DestroyNotifyKind =  'destroyNotify'|
 'closureNotify';
 
 /**
- * Returns the `GType` of the `GObject` referenced by `handle`, or 0 when the handle does not
- * reference a `GObject`.
+ * Returns the JavaScript wrapper object previously cached for the handle's fundamental
+ * instance, or null when no wrapper is cached.
  */
-export declare function getType(handle: ExternalObject<Handle>): bigint
+export declare function getFundamentalWrapper(handle: ExternalObject<Handle>): object | null
+
+/**
+ * Returns the `GType` of the instance `handle` references, or 0 when it carries no type tag.
+ * A `GObject` always carries one. A fundamental instance carries one only when the type the
+ * binding declares, passed as `declaredType`, is instantiatable.
+ */
+export declare function getType(handle: ExternalObject<Handle>, declaredType?: bigint | undefined | null): bigint
+
+/**
+ * Returns a handle over the class struct of `gtype`, taking a class reference that is
+ * deliberately never released: the class struct of a statically registered type lives for the
+ * rest of the process, so the handle borrows it without owning anything.
+ */
+export declare function getTypeClass(gtype: bigint): ExternalObject<Handle>
 
 /**
  * Returns the JavaScript wrapper object previously attached to the handle's `GObject`,
@@ -170,9 +203,13 @@ export declare function keepAlive(enable: boolean): void
  * it by calling `associate` with the instance's handle and the wrapper. A type registered through
  * `registerClass` binds them from its `instance_init`, before `constructed` runs, so a
  * `constructed` override already sees a fully usable wrapper; any other type binds them once
- * construction has returned.
+ * construction has returned. An abstract `gtype` is rejected before anything is constructed.
+ * When construction hands back an instance that already carries a
+ * wrapper — it reached JavaScript and was wrapped before `g_object_new` returned — that existing
+ * wrapper is returned instead of binding `wrapper`, so the caller can adopt it; otherwise the
+ * call returns `null`.
  */
-export declare function newObject(gtype: bigint, names: Array<string>, values: ExternalObject<Handle>[], wrapper: object, associate: (handle: ExternalObject<Handle>, wrapper: object) => void): void
+export declare function newObject(gtype: bigint, names: Array<string>, values: ExternalObject<Handle>[], wrapper: object, associate: (handle: ExternalObject<Handle>, wrapper: object) => void): object | null
 
 /**
  * Ownership transfer mode for a marshalled value: `borrowed` leaves the native side owning it,
@@ -189,9 +226,20 @@ export declare function quit(): void
  * to interpret the raw bytes, and rejects a handle that points at nothing rather than reading at
  * the bare offset. A value the descriptor marks as stored inline decodes to a handle aliasing the
  * owner's memory, so writing one of its own fields reaches the owner.
+ *
+ * The descriptor is compiled on every call. A field read repeatedly from the same descriptor and
+ * offset is cheaper through `bindField`, which compiles both once.
  */
 export declare function read(handle: ExternalObject<Handle>, fieldDescriptor: Descriptor, offset: number): unknown
 
+/**
+ * Reads and decodes the field a previously bound `descriptor` marshals, sitting `offset` bytes
+ * into the handle's memory, and rejects a handle that points at nothing rather than reading at
+ * the bare offset. A field the descriptor marks as stored inline decodes to a handle aliasing the
+ * owner's memory, so writing one of its own fields reaches the owner.
+ */
+export declare function readField(descriptor: ExternalObject<FieldDescriptor>, handle: ExternalObject<Handle>, offset: number): unknown
+
 /**
  * Registers a new `GObject` subtype named `name` deriving from `parentType`, wiring up any vfunc
  * overrides and implemented interfaces, and returns the new `GType`.
@@ -212,7 +260,10 @@ export interface RegisterClassInterface {
   vfuncs: Array<RegisterClassVfunc>
 }
 
-/** Optional configuration for `registerClass`: vfunc overrides, implemented interfaces and properties. */
+/**
+ * Optional configuration for `registerClass`: vfunc overrides, implemented interfaces, properties
+ * and signals.
+ */
 export interface RegisterClassOptions {
   /** Virtual function overrides for the class itself. */
   vfuncs?: Array<RegisterClassVfunc>
@@ -220,6 +271,15 @@ export interface RegisterClassOptions {
   interfaces?: Array<RegisterClassInterface>
   /** Properties to install on the class. */
   properties?: Array<RegisterClassProperty>
+  /** Signals to create on the class. */
+  signals?: Array<RegisterClassSignal>
+  /** Registers the type with `G_TYPE_FLAG_ABSTRACT`, so only its subtypes can be instantiated. */
+  abstract?: boolean
+  /**
+   * Name instances of the class carry in CSS, applied through `gtk_widget_class_set_css_name`
+   * from inside the type's `class_init`. Requires `parentType` to be a `GtkWidget`.
+   */
+  cssName?: string
 }
 
 /** A property the registered class installs on its class structure. */
@@ -230,6 +290,20 @@ export interface RegisterClassProperty {
   pspec: ExternalObject<Handle>
 }
 
+/** A signal the registered class creates on its type during class initialization. */
+export interface RegisterClassSignal {
+  /** Name to create the signal under. Must satisfy `g_signal_is_valid_name`. */
+  name: string
+  /** `GSignalFlags` bit mask, defaulting to `G_SIGNAL_RUN_FIRST`. */
+  flags?: number
+  /** `GType` of each argument an emission carries, defaulting to none. */
+  paramTypes?: Array<bigint>
+  /** `GType` of the value an emission returns, defaulting to `G_TYPE_NONE`. */
+  returnType?: bigint
+  /** Built-in accumulator combining handler returns: `"first-wins"` or `"true-handled"`. */
+  accumulator?: string
+}
+
 /**
  * A single virtual function override for a registered class: which slot to patch and how its
  * arguments and return value are marshalled to and from the JavaScript implementation.
@@ -241,6 +315,11 @@ export interface RegisterClassVfunc {
   argDescriptors: Array<Descriptor>
   /** Descriptor for the value the JavaScript implementation returns. */
   returnDescriptor: Descriptor
+  /**
+   * The slot's C signature ends with a `GError**`, which receives a `GError` built from
+   * whatever the JavaScript implementation throws.
+   */
+  canThrow?: boolean
   /** The JavaScript function that implements the vfunc. */
   fn: (...args: never[]) => unknown
 }
@@ -251,6 +330,14 @@ export interface RegisterClassVfunc {
  */
 export declare function resolveType(sharedLibrary: string, getTypeFnName: string): bigint
 
+/**
+ * Caches the JavaScript `wrapper` object for the handle's fundamental instance, so wrapping the
+ * same pointer again yields the same object for as long as the wrapper stays alive. A handle
+ * that owns no reference to its instance is left uncached, since its pointer can outlive the
+ * instance and later name a different one.
+ */
+export declare function setFundamentalWrapper(handle: ExternalObject<Handle>, wrapper: object): void
+
 /**
  * Attaches the JavaScript `wrapper` object to the handle's `GObject` and registers a finalizer
  * that releases it when the wrapper is garbage collected.
@@ -260,5 +347,15 @@ export declare function setWrapper(handle: ExternalObject<Handle>, wrapper: obje
 /**
  * Encodes `value` with `fieldDescriptor` and writes it into the handle's memory at `offset` bytes,
  * rejecting a handle that points at nothing rather than writing at the bare offset.
+ *
+ * The descriptor is compiled on every call. A field written repeatedly through the same descriptor
+ * and offset is cheaper through `bindField`, which compiles both once.
  */
 export declare function write(handle: ExternalObject<Handle>, fieldDescriptor: Descriptor, offset: number, value: unknown): unknown
+
+/**
+ * Encodes `value` with a previously bound `descriptor` and writes it `offset` bytes into the
+ * handle's memory, rejecting a handle that points at nothing rather than writing at the bare
+ * offset.
+ */
+export declare function writeField(descriptor: ExternalObject<FieldDescriptor>, handle: ExternalObject<Handle>, offset: number, value: unknown): unknown

package/index.js

@@ -81,8 +81,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-android-arm64')
         const bindingPackageVersion = require('@gtkx/native-android-arm64/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -97,8 +97,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-android-arm-eabi')
         const bindingPackageVersion = require('@gtkx/native-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -118,8 +118,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-win32-x64-gnu')
         const bindingPackageVersion = require('@gtkx/native-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -134,8 +134,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-win32-x64-msvc')
         const bindingPackageVersion = require('@gtkx/native-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -151,8 +151,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-win32-ia32-msvc')
         const bindingPackageVersion = require('@gtkx/native-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -167,8 +167,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-win32-arm64-msvc')
         const bindingPackageVersion = require('@gtkx/native-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -186,8 +186,8 @@ function requireNative() {
     try {
       const binding = require('@gtkx/native-darwin-universal')
       const bindingPackageVersion = require('@gtkx/native-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -202,8 +202,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-darwin-x64')
         const bindingPackageVersion = require('@gtkx/native-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -218,8 +218,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-darwin-arm64')
         const bindingPackageVersion = require('@gtkx/native-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -238,8 +238,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-freebsd-x64')
         const bindingPackageVersion = require('@gtkx/native-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -254,8 +254,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-freebsd-arm64')
         const bindingPackageVersion = require('@gtkx/native-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -275,8 +275,8 @@ function requireNative() {
         try {
           const binding = require('@gtkx/native-linux-x64-musl')
           const bindingPackageVersion = require('@gtkx/native-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -291,8 +291,8 @@ function requireNative() {
         try {
           const binding = require('@gtkx/native-linux-x64-gnu')
           const bindingPackageVersion = require('@gtkx/native-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -309,8 +309,8 @@ function requireNative() {
         try {
           const binding = require('@gtkx/native-linux-arm64-musl')
           const bindingPackageVersion = require('@gtkx/native-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -325,8 +325,8 @@ function requireNative() {
         try {
           const binding = require('@gtkx/native-linux-arm64-gnu')
           const bindingPackageVersion = require('@gtkx/native-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -343,8 +343,8 @@ function requireNative() {
         try {
           const binding = require('@gtkx/native-linux-arm-musleabihf')
           const bindingPackageVersion = require('@gtkx/native-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -359,8 +359,8 @@ function requireNative() {
         try {
           const binding = require('@gtkx/native-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@gtkx/native-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -377,8 +377,8 @@ function requireNative() {
         try {
           const binding = require('@gtkx/native-linux-loong64-musl')
           const bindingPackageVersion = require('@gtkx/native-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -393,8 +393,8 @@ function requireNative() {
         try {
           const binding = require('@gtkx/native-linux-loong64-gnu')
           const bindingPackageVersion = require('@gtkx/native-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -411,8 +411,8 @@ function requireNative() {
         try {
           const binding = require('@gtkx/native-linux-riscv64-musl')
           const bindingPackageVersion = require('@gtkx/native-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -427,8 +427,8 @@ function requireNative() {
         try {
           const binding = require('@gtkx/native-linux-riscv64-gnu')
           const bindingPackageVersion = require('@gtkx/native-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -444,8 +444,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-linux-ppc64-gnu')
         const bindingPackageVersion = require('@gtkx/native-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -460,8 +460,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-linux-s390x-gnu')
         const bindingPackageVersion = require('@gtkx/native-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -480,8 +480,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-openharmony-arm64')
         const bindingPackageVersion = require('@gtkx/native-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -496,8 +496,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-openharmony-x64')
         const bindingPackageVersion = require('@gtkx/native-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -512,8 +512,8 @@ function requireNative() {
       try {
         const binding = require('@gtkx/native-openharmony-arm')
         const bindingPackageVersion = require('@gtkx/native-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '1.2.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -652,8 +652,8 @@ if (!nativeBinding || forceWasi) {
       if (!candidateFailed) {
         if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
           const bindingPackageVersion = require('@gtkx/native-wasm32-wasi/package.json').version
-          if (bindingPackageVersion !== '1.2.2') {
-            throw new Error(`WASI binding package version mismatch, expected 1.2.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.4.0') {
+            throw new Error(`WASI binding package version mismatch, expected 1.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
         }
         wasiBinding = require('@gtkx/native-wasm32-wasi')
@@ -703,16 +703,20 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { alloc, ArrayKind, bind, bindVfunc, call, CallbackScope, copy, DestroyNotifyKind, getType, getWrapper, init, keepAlive, newObject, Ownership, quit, read, registerClass, resolveType, setWrapper, write } = nativeBinding
+const { alloc, ArrayKind, bind, bindField, bindFunctionPointer, bindVfunc, call, CallbackScope, copy, DestroyNotifyKind, getFundamentalWrapper, getType, getTypeClass, getWrapper, init, keepAlive, newObject, Ownership, quit, read, readField, registerClass, resolveType, setFundamentalWrapper, setWrapper, write, writeField } = nativeBinding
 export { alloc }
 export { ArrayKind }
 export { bind }
+export { bindField }
+export { bindFunctionPointer }
 export { bindVfunc }
 export { call }
 export { CallbackScope }
 export { copy }
 export { DestroyNotifyKind }
+export { getFundamentalWrapper }
 export { getType }
+export { getTypeClass }
 export { getWrapper }
 export { init }
 export { keepAlive }
@@ -720,7 +724,10 @@ export { newObject }
 export { Ownership }
 export { quit }
 export { read }
+export { readField }
 export { registerClass }
 export { resolveType }
+export { setFundamentalWrapper }
 export { setWrapper }
 export { write }
+export { writeField }

package/main.d.ts

@@ -12,6 +12,12 @@ declare module "./index.js" {
      * It captures the resolved symbol and the marshalling of its arguments and return value.
      */
     export type CallDescriptor = { _opaque: "CallDescriptor" };
+    /**
+     * An opaque, precompiled binding of a struct field, produced by `bindField` and passed to
+     * `readField` and `writeField`. It captures the marshalling of the field's bytes; the byte
+     * offset the field sits at within its owner's memory is given on every access.
+     */
+    export type FieldDescriptor = { _opaque: "FieldDescriptor" };
     /**
      * A mutable box for an out or inout ('ref' descriptor) parameter. Pass an object with a `value`
      * property; after `call` returns, its `value` holds the decoded native result.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gtkx/native",
-  "version": "1.2.2",
-  "description": "Rust addon under GTKX that loads shared libraries, marshals values, and tracks GObject handles",
+  "version": "1.4.0",
+  "description": "Rust addon for GTK: loads libraries, marshals values, tracks GObjects.",
   "keywords": [
     "gtkx",
     "gtk",
@@ -69,6 +69,9 @@
         "{projectRoot}/tests/**/*",
         "{projectRoot}/test-support/**/*",
         "{workspaceRoot}/scripts/run-headless.ts",
+        "{workspaceRoot}/scripts/cargo-nightly.ts",
+        "{workspaceRoot}/scripts/coverage-target.ts",
+        "{workspaceRoot}/scripts/rust-nightly.ts",
         "{workspaceRoot}/packages/utils/src/**/*"
       ]
     },
@@ -177,8 +180,8 @@
     "@napi-rs/cli": "^3.8.6"
   },
   "optionalDependencies": {
-    "@gtkx/native-linux-arm64-gnu": "1.2.2",
-    "@gtkx/native-linux-x64-gnu": "1.2.2"
+    "@gtkx/native-linux-arm64-gnu": "1.4.0",
+    "@gtkx/native-linux-x64-gnu": "1.4.0"
   },
   "scripts": {
     "artifacts": "napi artifacts",