@gtkx/native 1.0.0-rc.1 → 1.0.0-rc.3

package/index.d.ts

@@ -9,9 +9,10 @@ export declare class ExternalObject<T> {
 }
 /**
  * Allocates a zero-filled native memory block of `size` bytes and returns an opaque handle to it.
- * The optional `typeName` tags the boxed allocation with a GType name.
+ * The optional `gtype` must be a registered boxed `GType` and selects `g_boxed_free` as the
+ * handle's destructor instead of `g_free`.
  */
-export declare function alloc(size: number, typeName?: string | undefined | null): ExternalObject<Handle>
+export declare function alloc(size: number, gtype?: bigint | undefined | null): ExternalObject<Handle>
 
 /**
  * Container layout used to marshal an array: a plain C `array`, a `glist`, `gslist`, `gptrarray`,
@@ -27,8 +28,9 @@ export type ArrayKind =  'array'|
 'fixed';
 
 /**
- * Resolves `symbolName` in `sharedLibrary` and precompiles its argument and return marshalling
- * into a reusable call descriptor that `call` can invoke.
+ * Precompiles the argument and return marshalling of `symbolName` in `sharedLibrary` into a
+ * reusable call descriptor that `call` can invoke. The symbol itself is resolved on the first
+ * call, so binding a symbol the installed library does not export fails only when it is called.
  */
 export declare function bind(sharedLibrary: string, symbolName: string, argDescriptors: Array<Descriptor>, returnDescriptor: Descriptor): ExternalObject<CallDescriptor>
 
@@ -75,30 +77,36 @@ export type Descriptor =
   | { kind: 'unichar' }
   | { kind: 'void' }
   | { kind: 'buffer' }
-  | { kind: 'boxed', ownership: Ownership, typeName: string, sharedLibrary?: string, getTypeFnName?: string, freeFnName?: string, callerAllocated?: boolean, size?: number }
-  | { kind: 'struct', ownership: Ownership, size?: number, callerAllocated?: boolean }
-  | { kind: 'fundamental', ownership: Ownership, sharedLibrary: string, refFnName: string, unrefFnName: string, typeName?: string }
+  | { kind: 'boxed', ownership: Ownership, typeName: string, sharedLibrary?: string, getTypeFnName?: string, freeFnName?: string, callerAllocated?: boolean, size?: number, inline?: boolean }
+  | { kind: 'struct', ownership: Ownership, size?: number, callerAllocated?: boolean, inline?: boolean }
+  | { kind: 'fundamental', ownership: Ownership, sharedLibrary: string, refFnName: string, unrefFnName: string, typeName?: string, inline?: boolean }
   | { kind: 'array', itemDescriptor: Descriptor, arrayKind: ArrayKind, ownership: Ownership, sizeParamIndex?: number, fixedSize?: number, elementSize?: number }
   | { kind: 'hashtable', keyDescriptor: Descriptor, valueDescriptor: Descriptor, ownership: Ownership }
   | { kind: 'callback', argDescriptors: Array<Descriptor>, returnDescriptor: Descriptor, hasDestroy?: boolean, userDataIndex?: number, scope?: CallbackScope }
   | { kind: 'ref', innerDescriptor: Descriptor, inout?: boolean }
 
-/** Returns the GType of the GObject referenced by `handle`, or 0 when the pointer is null. */
+/**
+ * Returns the `GType` of the `GObject` referenced by `handle`, or 0 when the handle does not
+ * reference a `GObject`.
+ */
 export declare function getType(handle: ExternalObject<Handle>): bigint
 
 /**
- * Returns the JavaScript wrapper object previously attached to the handle's GObject,
+ * Returns the JavaScript wrapper object previously attached to the handle's `GObject`,
  * or null when no wrapper is set.
  */
 export declare function getWrapper(handle: ExternalObject<Handle>): object | null
 
 /**
- * Installs the Node environment bridge and the GLib main loop integration into the current thread.
+ * Installs the Node environment and the `GLib` main-loop integration on the current thread.
  * Call once before any other native function.
  */
 export declare function init(): void
 
-/** Enables or disables keeping the Node event loop alive while the GLib run loop is otherwise idle. */
+/**
+ * Enables or disables keeping the Node event loop alive while the `GLib` run loop is otherwise
+ * idle.
+ */
 export declare function keepAlive(enable: boolean): void
 
 /**
@@ -108,7 +116,7 @@ export declare function keepAlive(enable: boolean): void
 export type Ownership =  'borrowed'|
 'full';
 
-/** Tears down the GLib main loop integration installed by `init`. */
+/** Tears down the `GLib` main loop integration installed by `init`. */
 export declare function quit(): void
 
 /**
@@ -118,25 +126,41 @@ export declare function quit(): void
 export declare function read(handle: ExternalObject<Handle>, fieldDescriptor: Descriptor, 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.
+ * Registers a new `GObject` subtype named `name` deriving from `parentType`, wiring up any vfunc
+ * overrides and implemented interfaces, and returns the new `GType`.
  */
 export declare function registerClass(name: string, parentType: bigint, options?: RegisterClassOptions | undefined | null): bigint
 
 /** An interface a registered class implements, together with the interface vfuncs it provides. */
 export interface RegisterClassInterface {
-  /** GType of the interface to implement. */
+  /** `GType` of the interface to implement. */
   type: bigint
+  /**
+   * Byte size of the interface's vtable struct, used to bounds-check each vfunc's `byteOffset`.
+   * `g_type_query` reports nothing for an interface type, so the size has to come from the same
+   * generated metadata the offsets do; when it is omitted the offsets are only alignment-checked.
+   */
+  vtableSize?: number
   /** Interface vfunc implementations to install. */
   vfuncs: Array<RegisterClassVfunc>
 }
 
-/** Optional configuration for `registerClass`: vfunc overrides and implemented interfaces. */
+/** Optional configuration for `registerClass`: vfunc overrides, implemented interfaces and properties. */
 export interface RegisterClassOptions {
   /** Virtual function overrides for the class itself. */
   vfuncs?: Array<RegisterClassVfunc>
   /** Interfaces the class implements, each with its own vfuncs. */
   interfaces?: Array<RegisterClassInterface>
+  /** Properties to install on the class. */
+  properties?: Array<RegisterClassProperty>
+}
+
+/** A property the registered class installs on its class structure. */
+export interface RegisterClassProperty {
+  /** Property id the class's `get_property`/`set_property` vfuncs dispatch on. Must be non-zero. */
+  id: number
+  /** Handle to the `GParamSpec` describing the property. Ownership transfers to the class. */
+  pspec: ExternalObject<Handle>
 }
 
 /**
@@ -156,12 +180,12 @@ export interface RegisterClassVfunc {
 
 /**
  * Calls the `getTypeFnName` registration function in `sharedLibrary` and returns the resulting
- * GType, or 0 when the symbol is absent.
+ * `GType`, or 0 when the symbol is absent.
  */
 export declare function resolveType(sharedLibrary: string, getTypeFnName: string): bigint
 
 /**
- * Attaches the JavaScript `wrapper` object to the handle's GObject and registers a finalizer
+ * Attaches the JavaScript `wrapper` object to the handle's `GObject` and registers a finalizer
  * that releases it when the wrapper is garbage collected.
  */
 export declare function setWrapper(handle: ExternalObject<Handle>, wrapper: object): void

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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 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.0.0-rc.1' && 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.0.0-rc.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '1.0.0-rc.3' && 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.0.0-rc.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -527,47 +527,163 @@ function requireNative() {
   }
 }
 
-nativeBinding = requireNative()
+function createLoadErrorChain(errors) {
+  return errors.reduce((previous, current) => {
+    let message
+    try {
+      message =
+        current && typeof current.message === 'string'
+          ? current.message
+          : String(current)
+    } catch {
+      message = 'Unknown error'
+    }
+    const error = new Error(message)
+    error.cause = previous
+    return error
+  }, null)
+}
 
 // NAPI_RS_FORCE_WASI is a tri-state flag:
 //   unset / any other value → native binding preferred, WASI is only a fallback
-//   'true'                   → force WASI fallback even if native loaded
-//   'error'                  → force WASI and throw if no WASI binding is found
+//   'true'                   → prefer WASI, but retain native as a lazy fallback
+//   'error'                  → require WASI without initializing a native fallback
 // Treating any non-empty string as truthy (the historical behavior) meant
 // NAPI_RS_FORCE_WASI=false, NAPI_RS_FORCE_WASI=0, etc. inadvertently triggered
 // the WASI path, causing ENOENT for packages shipped without a .wasi.cjs file.
+//
+// NAPI_RS_WASI_FLAVOR selects one exact generated flavor and implies strict
+// WASI loading. It never crosses into another flavor or falls back to native.
+const __napiWasiFlavors = ["wasm32-wasi"]
+const __napiWasiFlavor = process.env.NAPI_RS_WASI_FLAVOR
+const __napiWasiFlavorRequested =
+  typeof __napiWasiFlavor === 'string' && __napiWasiFlavor.length > 0
+if (
+  __napiWasiFlavorRequested &&
+  __napiWasiFlavors.indexOf(__napiWasiFlavor) === -1
+) {
+  throw new Error(
+    'Unsupported WASI flavor "' +
+      __napiWasiFlavor +
+      '". Available flavors: ' +
+      __napiWasiFlavors.join(', '),
+  )
+}
+const forceWasiError = process.env.NAPI_RS_FORCE_WASI === 'error'
 const forceWasi =
-  process.env.NAPI_RS_FORCE_WASI === 'true' || process.env.NAPI_RS_FORCE_WASI === 'error'
+  process.env.NAPI_RS_FORCE_WASI === 'true' ||
+  forceWasiError ||
+  __napiWasiFlavorRequested
+
+if (!forceWasi) {
+  nativeBinding = requireNative()
+}
 
 if (!nativeBinding || forceWasi) {
   let wasiBinding = null
-  let wasiBindingError = null
-  try {
-    wasiBinding = require('./native.wasi.cjs')
-    nativeBinding = wasiBinding
-  } catch (err) {
-    if (forceWasi) {
-      wasiBindingError = err
+  let wasiBindingLoaded = false
+  const wasiBindingErrors = []
+  const __napiWasiResolveCandidate = (specifier, isPackage, localArtifacts) => {
+    try {
+      require.resolve(specifier)
+    } catch (resolveError) {
+      if (!resolveError || resolveError.code !== 'MODULE_NOT_FOUND') {
+        throw resolveError
+      }
+      if (isPackage) {
+        try {
+          require.resolve(specifier + '/package.json')
+        } catch (packageError) {
+          if (packageError && packageError.code === 'MODULE_NOT_FOUND') {
+            return resolveError
+          }
+          // An exports restriction proves the package exists even when its
+          // package.json is not public. Preserve the root resolution failure.
+          throw resolveError
+        }
+        // The package exists but its main/export target is broken.
+        throw resolveError
+      }
+      return resolveError
+    }
+    if (localArtifacts) {
+      let artifactError = null
+      for (let i = 0; i < localArtifacts.length; i++) {
+        try {
+          require.resolve(localArtifacts[i])
+          return null
+        } catch (resolveError) {
+          if (!resolveError || resolveError.code !== 'MODULE_NOT_FOUND') {
+            throw resolveError
+          }
+          artifactError = resolveError
+        }
+      }
+      return artifactError
     }
+    return null
   }
-  if (!nativeBinding || forceWasi) {
+  if (!wasiBindingLoaded && (!__napiWasiFlavorRequested || __napiWasiFlavor === "wasm32-wasi")) {
+    let candidateError = null
+    let candidateFailed = false
     try {
-      wasiBinding = require('@gtkx/native-wasm32-wasi')
-      nativeBinding = wasiBinding
+      candidateError = __napiWasiResolveCandidate('./native.wasi.cjs', false, ["./native.wasm32-wasi.debug.wasm","./native.wasm32-wasi.wasm"])
+      candidateFailed = candidateError !== null
+      if (!candidateFailed) {
+        wasiBinding = require('./native.wasi.cjs')
+        nativeBinding = wasiBinding
+        wasiBindingLoaded = true
+      }
     } catch (err) {
-      if (forceWasi) {
-        if (!wasiBindingError) {
-          wasiBindingError = err
-        } else {
-          wasiBindingError.cause = err
+      candidateError = err
+      candidateFailed = true
+    }
+    if (candidateFailed) {
+      wasiBindingErrors.push(candidateError)
+      loadErrors.push(candidateError)
+    }
+  }
+  if (!wasiBindingLoaded && (!__napiWasiFlavorRequested || __napiWasiFlavor === "wasm32-wasi")) {
+    let candidateError = null
+    let candidateFailed = false
+    try {
+      candidateError = __napiWasiResolveCandidate('@gtkx/native-wasm32-wasi', true, undefined)
+      candidateFailed = candidateError !== null
+      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.0.0-rc.3') {
+            throw new Error(`WASI binding package version mismatch, expected 1.0.0-rc.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
         }
-        loadErrors.push(err)
+        wasiBinding = require('@gtkx/native-wasm32-wasi')
+        nativeBinding = wasiBinding
+        wasiBindingLoaded = true
       }
+    } catch (err) {
+      candidateError = err
+      candidateFailed = true
+    }
+    if (candidateFailed) {
+      wasiBindingErrors.push(candidateError)
+      loadErrors.push(candidateError)
     }
   }
-  if (process.env.NAPI_RS_FORCE_WASI === 'error' && !wasiBinding) {
-    const error = new Error('WASI binding not found and NAPI_RS_FORCE_WASI is set to error')
-    error.cause = wasiBindingError
+  if (
+    !wasiBindingLoaded &&
+    forceWasi &&
+    !forceWasiError &&
+    !__napiWasiFlavorRequested
+  ) {
+    nativeBinding = requireNative()
+  }
+  if ((forceWasiError || __napiWasiFlavorRequested) && !wasiBindingLoaded) {
+    const error = new Error(
+      __napiWasiFlavorRequested
+        ? 'WASI binding for flavor "' + __napiWasiFlavor + '" not found'
+        : 'WASI binding not found and NAPI_RS_FORCE_WASI is set to error',
+    )
+    error.cause = createLoadErrorChain(wasiBindingErrors)
     throw error
   }
 }
@@ -581,10 +697,7 @@ if (!nativeBinding) {
     )
     // assign instead of the `new Error(message, { cause })` options form,
     // which Node < 16.9 silently ignores
-    error.cause = loadErrors.reduce((err, cur) => {
-      cur.cause = err
-      return cur
-    })
+    error.cause = createLoadErrorChain(loadErrors)
     throw error
   }
   throw new Error(`Failed to load native binding`)

package/init.js

@@ -0,0 +1,3 @@
+import { init } from "./index.js";
+
+init();

package/main.d.ts

@@ -6,12 +6,12 @@ declare module "./index.js" {
      * Produced by `alloc` and consumed by the memory and wrapper functions (`read`, `write`,
      * `copy`, `getType`, `getWrapper`, `setWrapper`). Its bytes are not accessible from JavaScript.
      */
-    export type Handle = { __opaque: "Handle" };
+    export type Handle = { _opaque: "Handle" };
     /**
      * An opaque, precompiled binding of a native function, produced by `bind` and passed to `call`.
      * It captures the resolved symbol and the marshalling of its arguments and return value.
      */
-    export type CallDescriptor = { __opaque: "CallDescriptor" };
+    export type CallDescriptor = { _opaque: "CallDescriptor" };
     /**
      * 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/main.js

@@ -1,5 +1,3 @@
-import { init } from "./index.js";
+import "./init.js";
 
 export * from "./index.js";
-
-init();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/native",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.3",
   "description": "Rust addon under GTKX that loads shared libraries, marshals values, and tracks GObject handles",
   "keywords": [
     "gtkx",
@@ -33,11 +33,13 @@
     }
   },
   "sideEffects": [
+    "./init.js",
     "./main.js"
   ],
   "files": [
     "index.js",
     "index.d.ts",
+    "init.js",
     "main.js",
     "main.d.ts"
   ],
@@ -48,23 +50,137 @@
       "aarch64-unknown-linux-gnu"
     ]
   },
+  "nx": {
+    "namedInputs": {
+      "crate": [
+        "{projectRoot}/src/**/*",
+        "{projectRoot}/build.rs",
+        "{projectRoot}/Cargo.toml",
+        "{projectRoot}/Cargo.lock",
+        "{projectRoot}/package.json",
+        "{workspaceRoot}/rust-toolchain.toml",
+        {
+          "runtime": "uname -m"
+        }
+      ],
+      "crateTests": [
+        "crate",
+        "sharedGlobals",
+        "{projectRoot}/tests/**/*",
+        "{projectRoot}/test-support/**/*",
+        "{workspaceRoot}/scripts/run-headless.ts",
+        "{workspaceRoot}/packages/utils/src/**/*"
+      ]
+    },
+    "targets": {
+      "build": {
+        "dependsOn": [],
+        "cache": true,
+        "inputs": [
+          "crate"
+        ],
+        "outputs": [
+          "{projectRoot}/index.d.ts",
+          "{projectRoot}/index.js",
+          "{projectRoot}/native.*.node"
+        ]
+      },
+      "test": {
+        "dependsOn": [
+          "build",
+          "test:asan",
+          "test:miri"
+        ],
+        "cache": true,
+        "inputs": [
+          "crateTests"
+        ],
+        "outputs": []
+      },
+      "test:asan": {
+        "dependsOn": [
+          "build"
+        ],
+        "cache": true,
+        "inputs": [
+          "crateTests"
+        ],
+        "outputs": []
+      },
+      "test:miri": {
+        "dependsOn": [
+          "build"
+        ],
+        "cache": true,
+        "inputs": [
+          "crateTests"
+        ],
+        "outputs": []
+      },
+      "coverage": {
+        "dependsOn": [
+          "build"
+        ],
+        "cache": true,
+        "inputs": [
+          "crateTests"
+        ],
+        "outputs": [
+          "{projectRoot}/coverage/**"
+        ]
+      },
+      "lint:rust": {
+        "cache": true,
+        "inputs": [
+          "crateTests"
+        ],
+        "outputs": []
+      },
+      "create-npm-dirs": {
+        "dependsOn": [
+          "build"
+        ],
+        "cache": true,
+        "inputs": [
+          "crate"
+        ],
+        "outputs": [
+          "{projectRoot}/npm/**"
+        ]
+      },
+      "artifacts": {
+        "dependsOn": [
+          "build",
+          "create-npm-dirs"
+        ],
+        "cache": false
+      },
+      "release": {
+        "dependsOn": [
+          "artifacts",
+          "create-npm-dirs"
+        ],
+        "cache": false
+      }
+    }
+  },
   "engines": {
     "node": ">=24"
   },
   "devDependencies": {
-    "@napi-rs/cli": "^3.7.3"
+    "@napi-rs/cli": "^3.8.0"
   },
   "optionalDependencies": {
-    "@gtkx/native-linux-arm64-gnu": "1.0.0-rc.1",
-    "@gtkx/native-linux-x64-gnu": "1.0.0-rc.1"
+    "@gtkx/native-linux-arm64-gnu": "1.0.0-rc.3",
+    "@gtkx/native-linux-x64-gnu": "1.0.0-rc.3"
   },
   "scripts": {
     "artifacts": "napi artifacts",
     "build": "napi build --platform --release --esm --no-dts-cache --no-const-enum",
     "coverage": "mkdir -p coverage && tsx ../../scripts/run-headless.ts cargo +nightly llvm-cov --lcov --output-path coverage/native.lcov.info --fail-under-lines 70 -- --test-threads=1",
     "create-npm-dirs": "napi create-npm-dirs",
-    "lint": "cargo fmt --check && cargo clippy --all-targets -- -D warnings",
-    "test:asan": "RUSTFLAGS=\"-Zsanitizer=address\" ASAN_OPTIONS=\"detect_leaks=0:abort_on_error=1:detect_stack_use_after_return=1\" tsx ../../scripts/run-headless.ts cargo +nightly test --target x86_64-unknown-linux-gnu -- --test-threads=1",
+    "lint:rust": "tsx ../../scripts/cargo-nightly.ts fmt --check && cargo clippy --all-targets -- -D warnings",
+    "test:asan": "RUSTFLAGS=\"-Zsanitizer=address\" ASAN_OPTIONS=\"detect_leaks=1:abort_on_error=1:detect_stack_use_after_return=1\" tsx ../../scripts/run-headless.ts cargo +nightly test --target x86_64-unknown-linux-gnu -- --test-threads=1",
     "test:miri": "tsx ../../scripts/run-headless.ts cargo +nightly miri test --test integer_codec --test descriptor_into_codec",
     "test": "tsx ../../scripts/run-headless.ts cargo test -- --test-threads=1",
     "release": "tsx ../../scripts/prepublish-native.ts && tsx ../../scripts/release-package.ts"