@gjsify/napi 0.22.0

package/src/napi-headers/js_native_api_types.h

@@ -0,0 +1,249 @@
+// SPDX-License-Identifier: MIT
+// Vendored from refs/node/src/js_native_api_types.h (Node.js contributors, MIT).
+// Copied unmodified (apart from this attribution header) so the @gjsify/napi
+// shim compiles standalone against the exact Node-API ABI it implements.
+
+#ifndef SRC_JS_NATIVE_API_TYPES_H_
+#define SRC_JS_NATIVE_API_TYPES_H_
+
+// Use INT_MAX, this should only be consumed by the pre-processor anyway.
+#define NAPI_VERSION_EXPERIMENTAL 2147483647
+#ifndef NAPI_VERSION
+#ifdef NAPI_EXPERIMENTAL
+#define NAPI_VERSION NAPI_VERSION_EXPERIMENTAL
+#else
+// The baseline version for Node-API.
+// NAPI_VERSION controls which version is used by default when compiling
+// a native addon. If the addon developer wants to use functions from a
+// newer Node-API version not yet available in all LTS versions, they can
+// set NAPI_VERSION to explicitly depend on that version.
+#define NAPI_VERSION 8
+#endif
+#endif
+
+#if defined(NAPI_EXPERIMENTAL) &&                                              \
+    !defined(NODE_API_EXPERIMENTAL_NO_WARNING) &&                              \
+    !defined(NODE_WANT_INTERNALS)
+#ifdef _MSC_VER
+#pragma message("NAPI_EXPERIMENTAL is enabled. "                               \
+                "Experimental features may be unstable.")
+#else
+#warning "NAPI_EXPERIMENTAL is enabled. " \
+       "Experimental features may be unstable."
+#endif
+#endif
+
+// This file needs to be compatible with C compilers.
+// This is a public include file, and these includes have essentially
+// become part of its API.
+#include <stddef.h>  // NOLINT(modernize-deprecated-headers)
+#include <stdint.h>  // NOLINT(modernize-deprecated-headers)
+
+#if !defined __cplusplus || (defined(_MSC_VER) && _MSC_VER < 1900)
+typedef uint16_t char16_t;
+#endif
+
+#ifndef NAPI_CDECL
+#ifdef _WIN32
+#define NAPI_CDECL __cdecl
+#else
+#define NAPI_CDECL
+#endif
+#endif
+
+// JSVM API types are all opaque pointers for ABI stability
+// typedef undefined structs instead of void* for compile time type safety
+typedef struct napi_env__* napi_env;
+
+// We need to mark APIs which can be called during garbage collection (GC),
+// meaning that they do not affect the state of the JS engine, and can
+// therefore be called synchronously from a finalizer that itself runs
+// synchronously during GC. Such APIs can receive either a `napi_env` or a
+// `node_api_basic_env` as their first parameter, because we should be able to
+// also call them during normal, non-garbage-collecting operations, whereas
+// APIs that affect the state of the JS engine can only receive a `napi_env` as
+// their first parameter, because we must not call them during GC. In lieu of
+// inheritance, we use the properties of the const qualifier to accomplish
+// this, because both a const and a non-const value can be passed to an API
+// expecting a const value, but only a non-const value can be passed to an API
+// expecting a non-const value.
+//
+// In conjunction with appropriate CFLAGS to warn us if we're passing a const
+// (basic) environment into an API that expects a non-const environment, and
+// the definition of basic finalizer function pointer types below, which
+// receive a basic environment as their first parameter, and can thus only call
+// basic APIs (unless the user explicitly casts the environment), we achieve
+// the ability to ensure at compile time that we do not call APIs that affect
+// the state of the JS engine from a synchronous (basic) finalizer.
+#if !defined(NAPI_EXPERIMENTAL) ||                                             \
+    (defined(NAPI_EXPERIMENTAL) &&                                             \
+     (defined(NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT) ||                       \
+      defined(NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT)))
+typedef struct napi_env__* node_api_nogc_env;
+#else
+typedef const struct napi_env__* node_api_nogc_env;
+#endif
+typedef node_api_nogc_env node_api_basic_env;
+
+typedef struct napi_value__* napi_value;
+typedef struct napi_ref__* napi_ref;
+typedef struct napi_handle_scope__* napi_handle_scope;
+typedef struct napi_escapable_handle_scope__* napi_escapable_handle_scope;
+typedef struct napi_callback_info__* napi_callback_info;
+typedef struct napi_deferred__* napi_deferred;
+
+typedef enum {
+  napi_default = 0,
+  napi_writable = 1 << 0,
+  napi_enumerable = 1 << 1,
+  napi_configurable = 1 << 2,
+
+  // Used with napi_define_class to distinguish static properties
+  // from instance properties. Ignored by napi_define_properties.
+  napi_static = 1 << 10,
+
+#if NAPI_VERSION >= 8
+  // Default for class methods.
+  napi_default_method = napi_writable | napi_configurable,
+
+  // Default for object properties, like in JS obj[prop].
+  napi_default_jsproperty = napi_writable | napi_enumerable | napi_configurable,
+#endif  // NAPI_VERSION >= 8
+} napi_property_attributes;
+
+typedef enum {
+  // ES6 types (corresponds to typeof)
+  napi_undefined,
+  napi_null,
+  napi_boolean,
+  napi_number,
+  napi_string,
+  napi_symbol,
+  napi_object,
+  napi_function,
+  napi_external,
+  napi_bigint,
+} napi_valuetype;
+
+typedef enum {
+  napi_int8_array,
+  napi_uint8_array,
+  napi_uint8_clamped_array,
+  napi_int16_array,
+  napi_uint16_array,
+  napi_int32_array,
+  napi_uint32_array,
+  napi_float32_array,
+  napi_float64_array,
+  napi_bigint64_array,
+  napi_biguint64_array,
+#define NODE_API_HAS_FLOAT16_ARRAY
+  napi_float16_array,
+} napi_typedarray_type;
+
+typedef enum {
+  napi_ok,
+  napi_invalid_arg,
+  napi_object_expected,
+  napi_string_expected,
+  napi_name_expected,
+  napi_function_expected,
+  napi_number_expected,
+  napi_boolean_expected,
+  napi_array_expected,
+  napi_generic_failure,
+  napi_pending_exception,
+  napi_cancelled,
+  napi_escape_called_twice,
+  napi_handle_scope_mismatch,
+  napi_callback_scope_mismatch,
+  napi_queue_full,
+  napi_closing,
+  napi_bigint_expected,
+  napi_date_expected,
+  napi_arraybuffer_expected,
+  napi_detachable_arraybuffer_expected,
+  napi_would_deadlock,  // unused
+  napi_no_external_buffers_allowed,
+  napi_cannot_run_js,
+} napi_status;
+// Note: when adding a new enum value to `napi_status`, please also update
+//   * `const int last_status` in the definition of `napi_get_last_error_info()'
+//     in file js_native_api_v8.cc.
+//   * `const char* error_messages[]` in file js_native_api_v8.cc with a brief
+//     message explaining the error.
+//   * the definition of `napi_status` in doc/api/n-api.md to reflect the newly
+//     added value(s).
+
+typedef napi_value(NAPI_CDECL* napi_callback)(napi_env env,
+                                              napi_callback_info info);
+typedef void(NAPI_CDECL* napi_finalize)(napi_env env,
+                                        void* finalize_data,
+                                        void* finalize_hint);
+
+#if !defined(NAPI_EXPERIMENTAL) ||                                             \
+    (defined(NAPI_EXPERIMENTAL) &&                                             \
+     (defined(NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT) ||                       \
+      defined(NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT)))
+typedef napi_finalize node_api_nogc_finalize;
+#else
+typedef void(NAPI_CDECL* node_api_nogc_finalize)(node_api_nogc_env env,
+                                                 void* finalize_data,
+                                                 void* finalize_hint);
+#endif
+typedef node_api_nogc_finalize node_api_basic_finalize;
+
+// A finalizer that can be called from any thread and at any time.
+typedef void(NAPI_CDECL* node_api_noenv_finalize)(void* finalize_data,
+                                                  void* finalize_hint);
+
+typedef struct {
+  // One of utf8name or name should be NULL.
+  const char* utf8name;
+  napi_value name;
+
+  napi_callback method;
+  napi_callback getter;
+  napi_callback setter;
+  napi_value value;
+
+  napi_property_attributes attributes;
+  void* data;
+} napi_property_descriptor;
+
+typedef struct {
+  const char* error_message;
+  void* engine_reserved;
+  uint32_t engine_error_code;
+  napi_status error_code;
+} napi_extended_error_info;
+
+#if NAPI_VERSION >= 6
+typedef enum {
+  napi_key_include_prototypes,
+  napi_key_own_only
+} napi_key_collection_mode;
+
+typedef enum {
+  napi_key_all_properties = 0,
+  napi_key_writable = 1,
+  napi_key_enumerable = 1 << 1,
+  napi_key_configurable = 1 << 2,
+  napi_key_skip_strings = 1 << 3,
+  napi_key_skip_symbols = 1 << 4
+} napi_key_filter;
+
+typedef enum {
+  napi_key_keep_numbers,
+  napi_key_numbers_to_strings
+} napi_key_conversion;
+#endif  // NAPI_VERSION >= 6
+
+#if NAPI_VERSION >= 8
+typedef struct {
+  uint64_t lower;
+  uint64_t upper;
+} napi_type_tag;
+#endif  // NAPI_VERSION >= 8
+
+#endif  // SRC_JS_NATIVE_API_TYPES_H_

package/src/napi-headers/node_api.h

@@ -0,0 +1,270 @@
+// SPDX-License-Identifier: MIT
+// Vendored from refs/node/src/node_api.h (Node.js contributors, MIT).
+// Copied unmodified (apart from this attribution header) so the @gjsify/napi
+// shim compiles standalone against the exact Node-API ABI it implements.
+
+#ifndef SRC_NODE_API_H_
+#define SRC_NODE_API_H_
+
+#if defined(BUILDING_NODE_EXTENSION) && !defined(NAPI_EXTERN)
+#ifdef _WIN32
+// Building native addon against node
+#define NAPI_EXTERN __declspec(dllimport)
+#elif defined(__wasm__)
+#define NAPI_EXTERN __attribute__((__import_module__("napi")))
+#endif
+#endif
+#include "js_native_api.h"
+#include "node_api_types.h"
+
+struct uv_loop_s;  // Forward declaration.
+
+#ifdef _WIN32
+#define NAPI_MODULE_EXPORT __declspec(dllexport)
+#else
+#ifdef __EMSCRIPTEN__
+#define NAPI_MODULE_EXPORT                                                     \
+  __attribute__((visibility("default"))) __attribute__((used))
+#else
+#define NAPI_MODULE_EXPORT __attribute__((visibility("default")))
+#endif
+#endif
+
+#if defined(__GNUC__)
+#define NAPI_NO_RETURN __attribute__((noreturn))
+#elif defined(_WIN32)
+#define NAPI_NO_RETURN __declspec(noreturn)
+#else
+#define NAPI_NO_RETURN
+#endif
+
+// Used by deprecated registration method napi_module_register.
+typedef struct napi_module {
+  int nm_version;
+  unsigned int nm_flags;
+  const char* nm_filename;
+  napi_addon_register_func nm_register_func;
+  const char* nm_modname;
+  void* nm_priv;
+  void* reserved[4];
+} napi_module;
+
+#define NAPI_MODULE_VERSION 1
+
+#define NAPI_MODULE_INITIALIZER_X(base, version)                               \
+  NAPI_MODULE_INITIALIZER_X_HELPER(base, version)
+#define NAPI_MODULE_INITIALIZER_X_HELPER(base, version) base##version
+
+#ifdef __wasm__
+#define NAPI_MODULE_INITIALIZER_BASE napi_register_wasm_v
+#else
+#define NAPI_MODULE_INITIALIZER_BASE napi_register_module_v
+#endif
+
+#define NODE_API_MODULE_GET_API_VERSION_BASE node_api_module_get_api_version_v
+
+#define NAPI_MODULE_INITIALIZER                                                \
+  NAPI_MODULE_INITIALIZER_X(NAPI_MODULE_INITIALIZER_BASE, NAPI_MODULE_VERSION)
+
+#define NODE_API_MODULE_GET_API_VERSION                                        \
+  NAPI_MODULE_INITIALIZER_X(NODE_API_MODULE_GET_API_VERSION_BASE,              \
+                            NAPI_MODULE_VERSION)
+
+#define NAPI_MODULE_INIT()                                                     \
+  EXTERN_C_START                                                               \
+  NAPI_MODULE_EXPORT int32_t NODE_API_MODULE_GET_API_VERSION(void) {           \
+    return NAPI_VERSION;                                                       \
+  }                                                                            \
+  NAPI_MODULE_EXPORT napi_value NAPI_MODULE_INITIALIZER(napi_env env,          \
+                                                        napi_value exports);   \
+  EXTERN_C_END                                                                 \
+  napi_value NAPI_MODULE_INITIALIZER(napi_env env, napi_value exports)
+
+#define NAPI_MODULE(modname, regfunc)                                          \
+  NAPI_MODULE_INIT() { return regfunc(env, exports); }
+
+// Deprecated. Use NAPI_MODULE.
+#define NAPI_MODULE_X(modname, regfunc, priv, flags)                           \
+  NAPI_MODULE(modname, regfunc)
+
+EXTERN_C_START
+
+// Deprecated. Replaced by symbol-based registration defined by NAPI_MODULE
+// and NAPI_MODULE_INIT macros.
+NAPI_EXTERN void NAPI_CDECL
+napi_module_register(napi_module* mod);
+
+NAPI_EXTERN NAPI_NO_RETURN void NAPI_CDECL
+napi_fatal_error(const char* location,
+                 size_t location_len,
+                 const char* message,
+                 size_t message_len);
+
+// Methods for custom handling of async operations
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_async_init(napi_env env,
+                napi_value async_resource,
+                napi_value async_resource_name,
+                napi_async_context* result);
+
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_async_destroy(napi_env env, napi_async_context async_context);
+
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_make_callback(napi_env env,
+                   napi_async_context async_context,
+                   napi_value recv,
+                   napi_value func,
+                   size_t argc,
+                   const napi_value* argv,
+                   napi_value* result);
+
+// Methods to provide node::Buffer functionality with napi types
+NAPI_EXTERN napi_status NAPI_CDECL napi_create_buffer(napi_env env,
+                                                      size_t length,
+                                                      void** data,
+                                                      napi_value* result);
+#ifndef NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_create_external_buffer(napi_env env,
+                            size_t length,
+                            void* data,
+                            node_api_basic_finalize finalize_cb,
+                            void* finalize_hint,
+                            napi_value* result);
+#endif  // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
+
+#if NAPI_VERSION >= 10
+
+NAPI_EXTERN napi_status NAPI_CDECL
+node_api_create_buffer_from_arraybuffer(napi_env env,
+                                        napi_value arraybuffer,
+                                        size_t byte_offset,
+                                        size_t byte_length,
+                                        napi_value* result);
+#endif  // NAPI_VERSION >= 10
+
+NAPI_EXTERN napi_status NAPI_CDECL napi_create_buffer_copy(napi_env env,
+                                                           size_t length,
+                                                           const void* data,
+                                                           void** result_data,
+                                                           napi_value* result);
+NAPI_EXTERN napi_status NAPI_CDECL napi_is_buffer(napi_env env,
+                                                  napi_value value,
+                                                  bool* result);
+NAPI_EXTERN napi_status NAPI_CDECL napi_get_buffer_info(napi_env env,
+                                                        napi_value value,
+                                                        void** data,
+                                                        size_t* length);
+
+// Methods to manage simple async operations
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_create_async_work(napi_env env,
+                       napi_value async_resource,
+                       napi_value async_resource_name,
+                       napi_async_execute_callback execute,
+                       napi_async_complete_callback complete,
+                       void* data,
+                       napi_async_work* result);
+NAPI_EXTERN napi_status NAPI_CDECL napi_delete_async_work(napi_env env,
+                                                          napi_async_work work);
+NAPI_EXTERN napi_status NAPI_CDECL napi_queue_async_work(node_api_basic_env env,
+                                                         napi_async_work work);
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_cancel_async_work(node_api_basic_env env, napi_async_work work);
+
+// version management
+NAPI_EXTERN napi_status NAPI_CDECL napi_get_node_version(
+    node_api_basic_env env, const napi_node_version** version);
+
+#if NAPI_VERSION >= 2
+
+// Return the current libuv event loop for a given environment
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_get_uv_event_loop(node_api_basic_env env, struct uv_loop_s** loop);
+
+#endif  // NAPI_VERSION >= 2
+
+#if NAPI_VERSION >= 3
+
+NAPI_EXTERN napi_status NAPI_CDECL napi_fatal_exception(napi_env env,
+                                                        napi_value err);
+
+NAPI_EXTERN napi_status NAPI_CDECL napi_add_env_cleanup_hook(
+    node_api_basic_env env, napi_cleanup_hook fun, void* arg);
+
+NAPI_EXTERN napi_status NAPI_CDECL napi_remove_env_cleanup_hook(
+    node_api_basic_env env, napi_cleanup_hook fun, void* arg);
+
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_open_callback_scope(napi_env env,
+                         napi_value resource_object,
+                         napi_async_context context,
+                         napi_callback_scope* result);
+
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_close_callback_scope(napi_env env, napi_callback_scope scope);
+
+#endif  // NAPI_VERSION >= 3
+
+#if NAPI_VERSION >= 4
+
+// Calling into JS from other threads
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_create_threadsafe_function(napi_env env,
+                                napi_value func,
+                                napi_value async_resource,
+                                napi_value async_resource_name,
+                                size_t max_queue_size,
+                                size_t initial_thread_count,
+                                void* thread_finalize_data,
+                                napi_finalize thread_finalize_cb,
+                                void* context,
+                                napi_threadsafe_function_call_js call_js_cb,
+                                napi_threadsafe_function* result);
+
+NAPI_EXTERN napi_status NAPI_CDECL napi_get_threadsafe_function_context(
+    napi_threadsafe_function func, void** result);
+
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_call_threadsafe_function(napi_threadsafe_function func,
+                              void* data,
+                              napi_threadsafe_function_call_mode is_blocking);
+
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_acquire_threadsafe_function(napi_threadsafe_function func);
+
+NAPI_EXTERN napi_status NAPI_CDECL napi_release_threadsafe_function(
+    napi_threadsafe_function func, napi_threadsafe_function_release_mode mode);
+
+NAPI_EXTERN napi_status NAPI_CDECL napi_unref_threadsafe_function(
+    node_api_basic_env env, napi_threadsafe_function func);
+
+NAPI_EXTERN napi_status NAPI_CDECL napi_ref_threadsafe_function(
+    node_api_basic_env env, napi_threadsafe_function func);
+
+#endif  // NAPI_VERSION >= 4
+
+#if NAPI_VERSION >= 8
+
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_add_async_cleanup_hook(node_api_basic_env env,
+                            napi_async_cleanup_hook hook,
+                            void* arg,
+                            napi_async_cleanup_hook_handle* remove_handle);
+
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_remove_async_cleanup_hook(napi_async_cleanup_hook_handle remove_handle);
+
+#endif  // NAPI_VERSION >= 8
+
+#if NAPI_VERSION >= 9
+
+NAPI_EXTERN napi_status NAPI_CDECL
+node_api_get_module_file_name(node_api_basic_env env, const char** result);
+
+#endif  // NAPI_VERSION >= 9
+
+EXTERN_C_END
+
+#endif  // SRC_NODE_API_H_

package/src/napi-headers/node_api_types.h

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+// Vendored from refs/node/src/node_api_types.h (Node.js contributors, MIT).
+// Copied unmodified (apart from this attribution header) so the @gjsify/napi
+// shim compiles standalone against the exact Node-API ABI it implements.
+
+#ifndef SRC_NODE_API_TYPES_H_
+#define SRC_NODE_API_TYPES_H_
+
+#include "js_native_api_types.h"
+
+typedef napi_value(NAPI_CDECL* napi_addon_register_func)(napi_env env,
+                                                         napi_value exports);
+// False positive: https://github.com/cpplint/cpplint/issues/409
+// NOLINTNEXTLINE (readability/casting)
+typedef int32_t(NAPI_CDECL* node_api_addon_get_api_version_func)(void);
+
+typedef struct napi_callback_scope__* napi_callback_scope;
+typedef struct napi_async_context__* napi_async_context;
+typedef struct napi_async_work__* napi_async_work;
+
+#if NAPI_VERSION >= 3
+typedef void(NAPI_CDECL* napi_cleanup_hook)(void* arg);
+#endif  // NAPI_VERSION >= 3
+
+#if NAPI_VERSION >= 4
+typedef struct napi_threadsafe_function__* napi_threadsafe_function;
+#endif  // NAPI_VERSION >= 4
+
+#if NAPI_VERSION >= 4
+typedef enum {
+  napi_tsfn_release,
+  napi_tsfn_abort
+} napi_threadsafe_function_release_mode;
+
+typedef enum {
+  napi_tsfn_nonblocking,
+  napi_tsfn_blocking
+} napi_threadsafe_function_call_mode;
+#endif  // NAPI_VERSION >= 4
+
+typedef void(NAPI_CDECL* napi_async_execute_callback)(napi_env env, void* data);
+typedef void(NAPI_CDECL* napi_async_complete_callback)(napi_env env,
+                                                       napi_status status,
+                                                       void* data);
+#if NAPI_VERSION >= 4
+typedef void(NAPI_CDECL* napi_threadsafe_function_call_js)(
+    napi_env env, napi_value js_callback, void* context, void* data);
+#endif  // NAPI_VERSION >= 4
+
+typedef struct {
+  uint32_t major;
+  uint32_t minor;
+  uint32_t patch;
+  const char* release;
+} napi_node_version;
+
+#if NAPI_VERSION >= 8
+typedef struct napi_async_cleanup_hook_handle__* napi_async_cleanup_hook_handle;
+typedef void(NAPI_CDECL* napi_async_cleanup_hook)(
+    napi_async_cleanup_hook_handle handle, void* data);
+#endif  // NAPI_VERSION >= 8
+
+#endif  // SRC_NODE_API_TYPES_H_

package/src/vala/gjs-1.0.vapi

@@ -0,0 +1,6 @@
+/* SPDX-License-Identifier: MIT
+ *
+ * Stub vapi: gjs-1.0 (the context accessors) is a C++-only dependency of the
+ * shim's .cc TUs. Meson forwards every dependency() to valac as --pkg; this
+ * empty vapi satisfies that lookup — Vala never touches the GJS C API.
+ */

package/src/vala/mozjs-140.vapi

@@ -0,0 +1,6 @@
+/* SPDX-License-Identifier: MIT
+ *
+ * Stub vapi: mozjs-140 is a C++-only dependency of the shim's .cc TUs.
+ * Meson forwards every dependency() to valac as --pkg; this empty vapi
+ * satisfies that lookup — no JSAPI is (or must ever be) reachable from Vala.
+ */

package/src/vala/napi.vala

@@ -0,0 +1,49 @@
+/*
+ * SPDX-License-Identifier: MIT
+ *
+ * GjsifyNapi — bootstrap-only GI surface for the @gjsify/napi N-API host.
+ *
+ * The introspectable surface is deliberately ONE call: `init()` installs the
+ * `globalThis.__gjsifyNapiLoadAddon` JSNative via the C++ bridge compiled
+ * into this same shared library (src/cc/module.cc). Everything after that —
+ * loading addons, exports, errors — happens as plain JS→JSNative calls with
+ * no GI marshalling involved (ADR 0011 / plan §3a).
+ *
+ * Mirrors the `@gjsify/tls-native` packaging template: Vala class + C code in
+ * one `.so` + `.gir` + `.typelib`, loaded from GJS via `imports.gi`.
+ */
+
+using GLib;
+
+namespace GjsifyNapi {
+
+    /*
+     * The extern C++ bridge (extern "C" in src/cc/module.cc, same .so).
+     * Returns false when there is no current GjsContext/JSContext — i.e.
+     * when called outside a GJS runtime.
+     */
+    [CCode (cname = "gjsify_napi_install")]
+    private extern bool install_bridge ();
+
+    /**
+     * Install the N-API host into the running GJS context.
+     *
+     * Defines the non-enumerable `globalThis.__gjsifyNapiLoadAddon` native.
+     * Idempotent — a second call is a no-op returning true. The TS L1
+     * (`@gjsify/napi`) captures the native and deletes the global property.
+     *
+     * @return true when the loader native was (or already is) installed.
+     */
+    public bool init () {
+        return install_bridge ();
+    }
+
+    /**
+     * Whether the native shim is loaded. The interesting availability
+     * question ("did init() manage to reach a JSContext?") is answered by
+     * init()'s return value; this exists so the L1 can probe the typelib.
+     */
+    public bool is_available () {
+        return true;
+    }
+}