@gtkx/ffi 0.9.4 → 0.10.0

package/dist/gl/gl.js

@@ -1,19 +1,19 @@
-/**
- * OpenGL function bindings via libGL.
- * These wrap raw OpenGL calls for use in GtkGLArea render handlers.
- */
 import { call, createRef } from "@gtkx/native";
 import { GL_INFO_LOG_LENGTH } from "./constants.js";
 const LIB = "libGL.so.1";
 /**
- * Clear buffers to preset values.
- * @param mask - Bitwise OR of masks indicating buffers to clear (GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT, etc.)
+ * Clears buffers to preset values.
+ * @param mask - Bitwise OR of masks indicating buffers to clear (GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT, GL_STENCIL_BUFFER_BIT)
  */
 export function glClear(mask) {
     call(LIB, "glClear", [{ type: { type: "int", size: 32, unsigned: true }, value: mask }], { type: "undefined" });
 }
 /**
- * Specify clear values for the color buffers.
+ * Sets the clear color for the color buffer.
+ * @param red - Red component (0.0 to 1.0)
+ * @param green - Green component (0.0 to 1.0)
+ * @param blue - Blue component (0.0 to 1.0)
+ * @param alpha - Alpha component (0.0 to 1.0)
  */
 export function glClearColor(red, green, blue, alpha) {
     call(LIB, "glClearColor", [
@@ -24,7 +24,11 @@ export function glClearColor(red, green, blue, alpha) {
     ], { type: "undefined" });
 }
 /**
- * Set the viewport.
+ * Sets the viewport transformation.
+ * @param x - X coordinate of the lower-left corner of the viewport
+ * @param y - Y coordinate of the lower-left corner of the viewport
+ * @param width - Width of the viewport
+ * @param height - Height of the viewport
  */
 export function glViewport(x, y, width, height) {
     call(LIB, "glViewport", [
@@ -35,33 +39,37 @@ export function glViewport(x, y, width, height) {
     ], { type: "undefined" });
 }
 /**
- * Enable server-side GL capabilities.
+ * Enables a GL capability.
+ * @param cap - The capability to enable (e.g., GL_DEPTH_TEST, GL_BLEND)
  */
 export function glEnable(cap) {
     call(LIB, "glEnable", [{ type: { type: "int", size: 32, unsigned: true }, value: cap }], { type: "undefined" });
 }
 /**
- * Disable server-side GL capabilities.
+ * Disables a GL capability.
+ * @param cap - The capability to disable
  */
 export function glDisable(cap) {
     call(LIB, "glDisable", [{ type: { type: "int", size: 32, unsigned: true }, value: cap }], { type: "undefined" });
 }
 /**
- * Specify the clear value for the depth buffer.
+ * Sets the clear value for the depth buffer.
+ * @param depth - Depth value used when clearing (0.0 to 1.0)
  */
 export function glClearDepth(depth) {
     call(LIB, "glClearDepth", [{ type: { type: "float", size: 64 }, value: depth }], { type: "undefined" });
 }
 /**
- * Specify the value used for depth buffer comparisons.
+ * Sets the depth comparison function.
+ * @param func - The comparison function (e.g., GL_LESS, GL_LEQUAL)
  */
 export function glDepthFunc(func) {
     call(LIB, "glDepthFunc", [{ type: { type: "int", size: 32, unsigned: true }, value: func }], { type: "undefined" });
 }
 /**
  * Creates a shader object.
- * @param type - GL_VERTEX_SHADER or GL_FRAGMENT_SHADER
- * @returns Shader object ID
+ * @param type - The type of shader (GL_VERTEX_SHADER or GL_FRAGMENT_SHADER)
+ * @returns The shader object ID
  */
 export function glCreateShader(type) {
     return call(LIB, "glCreateShader", [{ type: { type: "int", size: 32, unsigned: true }, value: type }], {
@@ -71,8 +79,9 @@ export function glCreateShader(type) {
     });
 }
 /**
- * Replaces the source code in a shader object.
- * Note: This simplified version passes a single null-terminated string.
+ * Sets the source code for a shader object.
+ * @param shader - The shader object ID
+ * @param source - The GLSL source code string
  */
 export function glShaderSource(shader, source) {
     call(LIB, "glShaderSource", [
@@ -84,6 +93,7 @@ export function glShaderSource(shader, source) {
 }
 /**
  * Compiles a shader object.
+ * @param shader - The shader object ID to compile
  */
 export function glCompileShader(shader) {
     call(LIB, "glCompileShader", [{ type: { type: "int", size: 32, unsigned: true }, value: shader }], {
@@ -91,7 +101,10 @@ export function glCompileShader(shader) {
     });
 }
 /**
- * Returns a parameter from a shader object.
+ * Gets a parameter from a shader object.
+ * @param shader - The shader object ID
+ * @param pname - The parameter to query (e.g., GL_COMPILE_STATUS, GL_INFO_LOG_LENGTH)
+ * @returns The parameter value
  */
 export function glGetShaderiv(shader, pname) {
     const params = createRef(0);
@@ -103,17 +116,28 @@ export function glGetShaderiv(shader, pname) {
     return params.value;
 }
 /**
- * Returns the information log for a shader object.
+ * Gets the information log for a shader object.
+ * @param shader - The shader object ID
+ * @returns The shader info log string
  */
-export function glGetShaderInfoLog(shader, _maxLength) {
+export function glGetShaderInfoLog(shader) {
     const logLength = glGetShaderiv(shader, GL_INFO_LOG_LENGTH);
     if (logLength <= 0) {
         return "";
     }
-    return `Shader info log length: ${logLength} (use console.error for details)`;
+    const infoLogRef = createRef("");
+    const lengthRef = createRef(0);
+    call(LIB, "glGetShaderInfoLog", [
+        { type: { type: "int", size: 32, unsigned: true }, value: shader },
+        { type: { type: "int", size: 32, unsigned: false }, value: logLength },
+        { type: { type: "ref", innerType: { type: "int", size: 32, unsigned: false } }, value: lengthRef },
+        { type: { type: "ref", innerType: { type: "string", length: logLength } }, value: infoLogRef },
+    ], { type: "undefined" });
+    return infoLogRef.value;
 }
 /**
  * Deletes a shader object.
+ * @param shader - The shader object ID to delete
  */
 export function glDeleteShader(shader) {
     call(LIB, "glDeleteShader", [{ type: { type: "int", size: 32, unsigned: true }, value: shader }], {
@@ -122,12 +146,15 @@ export function glDeleteShader(shader) {
 }
 /**
  * Creates a program object.
+ * @returns The program object ID
  */
 export function glCreateProgram() {
     return call(LIB, "glCreateProgram", [], { type: "int", size: 32, unsigned: true });
 }
 /**
  * Attaches a shader object to a program object.
+ * @param program - The program object ID
+ * @param shader - The shader object ID to attach
  */
 export function glAttachShader(program, shader) {
     call(LIB, "glAttachShader", [
@@ -137,6 +164,7 @@ export function glAttachShader(program, shader) {
 }
 /**
  * Links a program object.
+ * @param program - The program object ID to link
  */
 export function glLinkProgram(program) {
     call(LIB, "glLinkProgram", [{ type: { type: "int", size: 32, unsigned: true }, value: program }], {
@@ -144,7 +172,8 @@ export function glLinkProgram(program) {
     });
 }
 /**
- * Installs a program object as part of current rendering state.
+ * Installs a program object as part of the current rendering state.
+ * @param program - The program object ID to use (0 to uninstall)
  */
 export function glUseProgram(program) {
     call(LIB, "glUseProgram", [{ type: { type: "int", size: 32, unsigned: true }, value: program }], {
@@ -152,7 +181,10 @@ export function glUseProgram(program) {
     });
 }
 /**
- * Returns a parameter from a program object.
+ * Gets a parameter from a program object.
+ * @param program - The program object ID
+ * @param pname - The parameter to query (e.g., GL_LINK_STATUS, GL_INFO_LOG_LENGTH)
+ * @returns The parameter value
  */
 export function glGetProgramiv(program, pname) {
     const params = createRef(0);
@@ -164,17 +196,28 @@ export function glGetProgramiv(program, pname) {
     return params.value;
 }
 /**
- * Returns the information log for a program object.
+ * Gets the information log for a program object.
+ * @param program - The program object ID
+ * @returns The program info log string
  */
-export function glGetProgramInfoLog(program, _maxLength) {
+export function glGetProgramInfoLog(program) {
     const logLength = glGetProgramiv(program, GL_INFO_LOG_LENGTH);
     if (logLength <= 0) {
         return "";
     }
-    return `Program info log length: ${logLength} (use console.error for details)`;
+    const infoLogRef = createRef("");
+    const lengthRef = createRef(0);
+    call(LIB, "glGetProgramInfoLog", [
+        { type: { type: "int", size: 32, unsigned: true }, value: program },
+        { type: { type: "int", size: 32, unsigned: false }, value: logLength },
+        { type: { type: "ref", innerType: { type: "int", size: 32, unsigned: false } }, value: lengthRef },
+        { type: { type: "ref", innerType: { type: "string", length: logLength } }, value: infoLogRef },
+    ], { type: "undefined" });
+    return infoLogRef.value;
 }
 /**
  * Deletes a program object.
+ * @param program - The program object ID to delete
  */
 export function glDeleteProgram(program) {
     call(LIB, "glDeleteProgram", [{ type: { type: "int", size: 32, unsigned: true }, value: program }], {
@@ -182,7 +225,10 @@ export function glDeleteProgram(program) {
     });
 }
 /**
- * Returns the location of a uniform variable.
+ * Gets the location of a uniform variable in a program.
+ * @param program - The program object ID
+ * @param name - The name of the uniform variable
+ * @returns The location of the uniform, or -1 if not found
  */
 export function glGetUniformLocation(program, name) {
     return call(LIB, "glGetUniformLocation", [
@@ -191,7 +237,9 @@ export function glGetUniformLocation(program, name) {
     ], { type: "int", size: 32, unsigned: false });
 }
 /**
- * Specify the value of a uniform variable (1 float).
+ * Sets a float uniform variable.
+ * @param location - The uniform location
+ * @param v0 - The float value
  */
 export function glUniform1f(location, v0) {
     call(LIB, "glUniform1f", [
@@ -200,7 +248,10 @@ export function glUniform1f(location, v0) {
     ], { type: "undefined" });
 }
 /**
- * Specify the value of a uniform variable (2 floats).
+ * Sets a vec2 uniform variable.
+ * @param location - The uniform location
+ * @param v0 - The first component
+ * @param v1 - The second component
  */
 export function glUniform2f(location, v0, v1) {
     call(LIB, "glUniform2f", [
@@ -210,7 +261,11 @@ export function glUniform2f(location, v0, v1) {
     ], { type: "undefined" });
 }
 /**
- * Specify the value of a uniform variable (3 floats).
+ * Sets a vec3 uniform variable.
+ * @param location - The uniform location
+ * @param v0 - The first component
+ * @param v1 - The second component
+ * @param v2 - The third component
  */
 export function glUniform3f(location, v0, v1, v2) {
     call(LIB, "glUniform3f", [
@@ -221,7 +276,12 @@ export function glUniform3f(location, v0, v1, v2) {
     ], { type: "undefined" });
 }
 /**
- * Specify the value of a uniform variable (4 floats).
+ * Sets a vec4 uniform variable.
+ * @param location - The uniform location
+ * @param v0 - The first component
+ * @param v1 - The second component
+ * @param v2 - The third component
+ * @param v3 - The fourth component
  */
 export function glUniform4f(location, v0, v1, v2, v3) {
     call(LIB, "glUniform4f", [
@@ -233,7 +293,9 @@ export function glUniform4f(location, v0, v1, v2, v3) {
     ], { type: "undefined" });
 }
 /**
- * Specify the value of a uniform variable (1 int).
+ * Sets an integer uniform variable.
+ * @param location - The uniform location
+ * @param v0 - The integer value
  */
 export function glUniform1i(location, v0) {
     call(LIB, "glUniform1i", [
@@ -242,7 +304,11 @@ export function glUniform1i(location, v0) {
     ], { type: "undefined" });
 }
 /**
- * Specify the value of a 4x4 matrix uniform variable.
+ * Sets a 4x4 matrix uniform variable.
+ * @param location - The uniform location
+ * @param count - Number of matrices to set
+ * @param transpose - Whether to transpose the matrix
+ * @param value - Array of 16 floats representing the matrix in column-major order
  */
 export function glUniformMatrix4fv(location, count, transpose, value) {
     call(LIB, "glUniformMatrix4fv", [
@@ -253,7 +319,8 @@ export function glUniformMatrix4fv(location, count, transpose, value) {
     ], { type: "undefined" });
 }
 /**
- * Generate a single vertex array object name.
+ * Generates a vertex array object (VAO).
+ * @returns The VAO ID
  */
 export function glGenVertexArray() {
     const array = createRef(0);
@@ -264,7 +331,8 @@ export function glGenVertexArray() {
     return array.value;
 }
 /**
- * Bind a vertex array object.
+ * Binds a vertex array object.
+ * @param array - The VAO ID to bind (0 to unbind)
  */
 export function glBindVertexArray(array) {
     call(LIB, "glBindVertexArray", [{ type: { type: "int", size: 32, unsigned: true }, value: array }], {
@@ -272,7 +340,8 @@ export function glBindVertexArray(array) {
     });
 }
 /**
- * Delete a vertex array object.
+ * Deletes a vertex array object.
+ * @param array - The VAO ID to delete
  */
 export function glDeleteVertexArray(array) {
     call(LIB, "glDeleteVertexArrays", [
@@ -281,7 +350,8 @@ export function glDeleteVertexArray(array) {
     ], { type: "undefined" });
 }
 /**
- * Generate a single buffer object name.
+ * Generates a buffer object.
+ * @returns The buffer object ID
  */
 export function glGenBuffer() {
     const buffer = createRef(0);
@@ -292,7 +362,9 @@ export function glGenBuffer() {
     return buffer.value;
 }
 /**
- * Bind a named buffer object.
+ * Binds a buffer object to a target.
+ * @param target - The buffer target (e.g., GL_ARRAY_BUFFER, GL_ELEMENT_ARRAY_BUFFER)
+ * @param buffer - The buffer object ID to bind (0 to unbind)
  */
 export function glBindBuffer(target, buffer) {
     call(LIB, "glBindBuffer", [
@@ -301,7 +373,8 @@ export function glBindBuffer(target, buffer) {
     ], { type: "undefined" });
 }
 /**
- * Delete a buffer object.
+ * Deletes a buffer object.
+ * @param buffer - The buffer object ID to delete
  */
 export function glDeleteBuffer(buffer) {
     call(LIB, "glDeleteBuffers", [
@@ -310,10 +383,10 @@ export function glDeleteBuffer(buffer) {
     ], { type: "undefined" });
 }
 /**
- * Creates and initializes a buffer object's data store.
- * @param target - Buffer target (GL_ARRAY_BUFFER, GL_ELEMENT_ARRAY_BUFFER, etc.)
- * @param data - Array of float values
- * @param usage - Usage hint (GL_STATIC_DRAW, GL_DYNAMIC_DRAW, etc.)
+ * Creates and initializes a buffer object's data store with float data.
+ * @param target - The buffer target
+ * @param data - Array of float values to upload
+ * @param usage - Usage pattern hint (e.g., GL_STATIC_DRAW, GL_DYNAMIC_DRAW)
  */
 export function glBufferData(target, data, usage) {
     const size = data.length * 4;
@@ -325,7 +398,13 @@ export function glBufferData(target, data, usage) {
     ], { type: "undefined" });
 }
 /**
- * Define an array of generic vertex attribute data.
+ * Defines an array of generic vertex attribute data.
+ * @param index - The attribute index
+ * @param size - Number of components per attribute (1, 2, 3, or 4)
+ * @param type - Data type of each component (e.g., GL_FLOAT)
+ * @param normalized - Whether to normalize fixed-point data
+ * @param stride - Byte offset between consecutive attributes
+ * @param offset - Byte offset to the first attribute in the buffer
  */
 export function glVertexAttribPointer(index, size, type, normalized, stride, offset) {
     call(LIB, "glVertexAttribPointer", [
@@ -338,7 +417,8 @@ export function glVertexAttribPointer(index, size, type, normalized, stride, off
     ], { type: "undefined" });
 }
 /**
- * Enable a generic vertex attribute array.
+ * Enables a generic vertex attribute array.
+ * @param index - The attribute index to enable
  */
 export function glEnableVertexAttribArray(index) {
     call(LIB, "glEnableVertexAttribArray", [{ type: { type: "int", size: 32, unsigned: true }, value: index }], {
@@ -346,7 +426,8 @@ export function glEnableVertexAttribArray(index) {
     });
 }
 /**
- * Disable a generic vertex attribute array.
+ * Disables a generic vertex attribute array.
+ * @param index - The attribute index to disable
  */
 export function glDisableVertexAttribArray(index) {
     call(LIB, "glDisableVertexAttribArray", [{ type: { type: "int", size: 32, unsigned: true }, value: index }], {
@@ -354,7 +435,10 @@ export function glDisableVertexAttribArray(index) {
     });
 }
 /**
- * Render primitives from array data.
+ * Renders primitives from array data.
+ * @param mode - The primitive type (e.g., GL_TRIANGLES, GL_TRIANGLE_STRIP)
+ * @param first - Starting index in the enabled arrays
+ * @param count - Number of indices to render
  */
 export function glDrawArrays(mode, first, count) {
     call(LIB, "glDrawArrays", [
@@ -365,10 +449,9 @@ export function glDrawArrays(mode, first, count) {
 }
 /**
  * Creates and initializes a buffer object's data store with unsigned short data.
- * Use this for element/index buffers with GL_UNSIGNED_SHORT type.
- * @param target - Buffer target (typically GL_ELEMENT_ARRAY_BUFFER)
- * @param data - Array of unsigned short values (indices)
- * @param usage - Usage hint (GL_STATIC_DRAW, GL_DYNAMIC_DRAW, etc.)
+ * @param target - The buffer target
+ * @param data - Array of unsigned short values to upload
+ * @param usage - Usage pattern hint (e.g., GL_STATIC_DRAW, GL_DYNAMIC_DRAW)
  */
 export function glBufferDataUshort(target, data, usage) {
     const size = data.length * 2;
@@ -380,7 +463,11 @@ export function glBufferDataUshort(target, data, usage) {
     ], { type: "undefined" });
 }
 /**
- * Render primitives from array data with indices.
+ * Renders primitives from indexed array data.
+ * @param mode - The primitive type (e.g., GL_TRIANGLES)
+ * @param count - Number of elements to render
+ * @param type - Type of indices (e.g., GL_UNSIGNED_SHORT, GL_UNSIGNED_INT)
+ * @param offset - Byte offset into the element array buffer
  */
 export function glDrawElements(mode, count, type, offset) {
     call(LIB, "glDrawElements", [
@@ -391,7 +478,10 @@ export function glDrawElements(mode, count, type, offset) {
     ], { type: "undefined" });
 }
 /**
- * Returns the location of an attribute variable.
+ * Gets the location of an attribute variable in a program.
+ * @param program - The program object ID
+ * @param name - The name of the attribute variable
+ * @returns The location of the attribute, or -1 if not found
  */
 export function glGetAttribLocation(program, name) {
     return call(LIB, "glGetAttribLocation", [
@@ -400,7 +490,10 @@ export function glGetAttribLocation(program, name) {
     ], { type: "int", size: 32, unsigned: false });
 }
 /**
- * Associate a generic vertex attribute index with a named attribute variable.
+ * Associates a generic vertex attribute index with a named attribute variable.
+ * @param program - The program object ID
+ * @param index - The attribute index to bind
+ * @param name - The name of the attribute variable
  */
 export function glBindAttribLocation(program, index, name) {
     call(LIB, "glBindAttribLocation", [
@@ -410,7 +503,8 @@ export function glBindAttribLocation(program, index, name) {
     ], { type: "undefined" });
 }
 /**
- * Return error information.
+ * Gets the current GL error code.
+ * @returns The error code (GL_NO_ERROR if no error)
  */
 export function glGetError() {
     return call(LIB, "glGetError", [], { type: "int", size: 32, unsigned: true });

package/dist/gl/index.d.ts

@@ -1,14 +1,2 @@
-/**
- * OpenGL bindings via libGL for use with GtkGLArea.
- *
- * Example usage:
- * ```typescript
- * import * as GL from "@gtkx/ffi/gl";
- *
- * // In a render handler:
- * GL.glClearColor(0.5, 0.5, 0.5, 1.0);
- * GL.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT);
- * ```
- */
 export * from "./constants.js";
 export * from "./gl.js";

package/dist/gl/index.js

@@ -1,14 +1,2 @@
-/**
- * OpenGL bindings via libGL for use with GtkGLArea.
- *
- * Example usage:
- * ```typescript
- * import * as GL from "@gtkx/ffi/gl";
- *
- * // In a render handler:
- * GL.glClearColor(0.5, 0.5, 0.5, 1.0);
- * GL.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT);
- * ```
- */
 export * from "./constants.js";
 export * from "./gl.js";

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from "./native/events.js";
 export * from "./native/lifecycle.js";
 export * from "./native/object.js";
 export * from "./registry.js";
+import "./cairo/cairo.js";

package/dist/index.js

@@ -6,3 +6,4 @@ export * from "./native/events.js";
 export * from "./native/lifecycle.js";
 export * from "./native/object.js";
 export * from "./registry.js";
+import "./cairo/cairo.js";

package/dist/native/base.d.ts

@@ -1,27 +1,44 @@
 /**
- * Abstract base class for all native GLib/GTK objects.
- * All generated classes, interfaces, and boxed types extend this.
+ * Base class for all GTK/GLib object wrappers.
+ *
+ * Provides common functionality for native object representation including
+ * type metadata and equality comparison.
+ *
+ * @see {@link getNativeObject} for creating wrapper instances
  */
 export declare abstract class NativeObject {
-    /** The GLib type name (e.g., "GtkButton"). Must be overridden by subclasses. */
+    /** The GLib type name (e.g., "GtkButton", "AdwHeaderBar") */
     static readonly glibTypeName: string;
-    /** The object type category. Must be overridden by subclasses. */
-    static readonly objectType: "gobject" | "interface" | "boxed";
-    /** The native object id for the underlying GLib object */
+    /** The type category: gobject, interface, boxed, gvariant, or struct */
+    static readonly objectType: "gobject" | "interface" | "boxed" | "gvariant" | "struct";
+    /** Native object pointer/ID */
     id: unknown;
     constructor(..._args: any[]);
+    /**
+     * Compares this object to another for equality.
+     *
+     * Objects are equal if they wrap the same native pointer.
+     *
+     * @param other - Object to compare against
+     * @returns `true` if both wrap the same native object
+     */
+    equals(other: unknown): boolean;
 }
-/** Type representing a NativeObject subclass constructor */
+/**
+ * Constructor type for native object wrapper classes.
+ *
+ * @typeParam T - The wrapped object type
+ */
 export type NativeClass<T extends NativeObject = NativeObject> = typeof NativeObject & (new (...args: any[]) => T);
 /**
- * Flag to prevent intermediate base class constructors from creating objects.
- * When a subclass is being instantiated, this flag is set to true to skip
- * object creation in parent constructors. Only the outermost constructor
- * will create the actual native object.
+ * Flag indicating if a native object is currently being instantiated.
+ *
+ * @internal
  */
 export declare let isInstantiating: boolean;
 /**
  * Sets the instantiation flag.
- * @param value - The new value for the instantiation flag.
+ *
+ * @internal
  */
 export declare const setInstantiating: (value: boolean) => void;

package/dist/native/base.js

@@ -1,28 +1,46 @@
+import { getObjectId } from "@gtkx/native";
 /**
- * Abstract base class for all native GLib/GTK objects.
- * All generated classes, interfaces, and boxed types extend this.
+ * Base class for all GTK/GLib object wrappers.
+ *
+ * Provides common functionality for native object representation including
+ * type metadata and equality comparison.
+ *
+ * @see {@link getNativeObject} for creating wrapper instances
  */
 export class NativeObject {
-    /** The GLib type name (e.g., "GtkButton"). Must be overridden by subclasses. */
+    /** The GLib type name (e.g., "GtkButton", "AdwHeaderBar") */
     static glibTypeName;
-    /** The object type category. Must be overridden by subclasses. */
+    /** The type category: gobject, interface, boxed, gvariant, or struct */
     static objectType;
-    /** The native object id for the underlying GLib object */
+    /** Native object pointer/ID */
     id;
-    // biome-ignore lint/complexity/noUselessConstructor: required for subclassing
-    // biome-ignore lint/suspicious/noExplicitAny: required for constructor args
+    // biome-ignore lint/complexity/noUselessConstructor: Required for NativeClass type compatibility
+    // biome-ignore lint/suspicious/noExplicitAny: Required for NativeClass type compatibility
     constructor(..._args) { }
+    /**
+     * Compares this object to another for equality.
+     *
+     * Objects are equal if they wrap the same native pointer.
+     *
+     * @param other - Object to compare against
+     * @returns `true` if both wrap the same native object
+     */
+    equals(other) {
+        if (!(other instanceof NativeObject))
+            return false;
+        return getObjectId(this.id) === getObjectId(other.id);
+    }
 }
 /**
- * Flag to prevent intermediate base class constructors from creating objects.
- * When a subclass is being instantiated, this flag is set to true to skip
- * object creation in parent constructors. Only the outermost constructor
- * will create the actual native object.
+ * Flag indicating if a native object is currently being instantiated.
+ *
+ * @internal
  */
 export let isInstantiating = false;
 /**
  * Sets the instantiation flag.
- * @param value - The new value for the instantiation flag.
+ *
+ * @internal
  */
 export const setInstantiating = (value) => {
     isInstantiating = value;