@react-native-native/nativ-fabric 0.1.0

package/ios/NativRuntime.mm

@@ -0,0 +1,549 @@
+// NativRuntime.mm — C++ function registry + JSI bridge.
+//
+// 1. Bridge files call nativ_register_sync/async at +load time.
+// 2. When the JS runtime is ready, we install global.__nativ with callSync/callAsync.
+// 3. JS shims generated by the Metro transformer call global.__nativ.callSync(...).
+
+#import <Foundation/Foundation.h>
+#include <jsi/jsi.h>
+#include <ReactCommon/CallInvoker.h>
+#if DEBUG
+#include <dlfcn.h>  // Dev only — loadDylib uses dlopen for hot-reload
+#endif
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <mutex>
+#include <vector>
+
+#import "NativRuntime.h"
+
+using namespace facebook;
+
+// ─── Registry ──────────────────────────────────────────────────────────
+
+struct FnEntry {
+  NativSyncFn syncFn = nullptr;
+  NativAsyncFn asyncFn = nullptr;
+};
+
+// key = "moduleId::fnName"
+static std::unordered_map<std::string, FnEntry>& getRegistry() {
+  static std::unordered_map<std::string, FnEntry> reg;
+  return reg;
+}
+
+static std::string makeKey(const char* moduleId, const char* fnName) {
+  return std::string(moduleId) + "::" + fnName;
+}
+
+extern "C" void nativ_register_sync(const char* moduleId, const char* fnName, NativSyncFn fn) {
+  getRegistry()[makeKey(moduleId, fnName)].syncFn = fn;
+  NSLog(@"[Nativ] registered sync: %s::%s", moduleId, fnName);
+}
+
+extern "C" void nativ_register_async(const char* moduleId, const char* fnName, NativAsyncFn fn) {
+  getRegistry()[makeKey(moduleId, fnName)].asyncFn = fn;
+  NSLog(@"[Nativ] registered async: %s::%s", moduleId, fnName);
+}
+
+// ─── Component render registry ────────────────────────────────────────
+
+static std::unordered_map<std::string, NativRenderFn>& getRenderRegistry() {
+  static std::unordered_map<std::string, NativRenderFn> reg;
+  return reg;
+}
+
+extern "C" void nativ_register_render(const char* componentId, NativRenderFn fn) {
+  getRenderRegistry()[std::string(componentId)] = fn;
+  NSLog(@"[Nativ] registered render: %s", componentId);
+}
+
+// ─── Props storage ─────────────────────────────────────────────────────
+// Props are stored as live jsi::Object references. Both setComponentProps and
+// nativ_try_render run on the JS thread, so the object is alive during render.
+// This supports ALL prop types: strings, numbers, bools, objects, arrays, null.
+
+static jsi::Runtime* g_runtime = nullptr;
+static std::shared_ptr<facebook::react::CallInvoker> g_callInvoker = nullptr;
+
+static std::unordered_map<std::string, std::shared_ptr<jsi::Object>>& getPropsStore() {
+  static std::unordered_map<std::string, std::shared_ptr<jsi::Object>> store;
+  return store;
+}
+
+extern "C" void nativ_register_view(const char*, void*) {}
+extern "C" void nativ_unregister_view(const char*) {}
+
+static std::string g_currentRenderingComponent;
+
+extern "C" const char* nativ_try_render(const char* componentId, void* view, float w, float h) {
+  auto &reg = getRenderRegistry();
+  auto it = reg.find(std::string(componentId));
+  if (it == reg.end()) return nullptr;
+
+  void* runtime_ptr = nullptr;
+  void* props_ptr = nullptr;
+  auto &store = getPropsStore();
+  auto sit = store.find(std::string(componentId));
+  if (sit != store.end() && sit->second && g_runtime) {
+    runtime_ptr = reinterpret_cast<void*>(g_runtime);
+    props_ptr = reinterpret_cast<void*>(sit->second.get());
+  }
+
+  g_currentRenderingComponent = std::string(componentId);
+  it->second(view, w, h, runtime_ptr, props_ptr);
+  g_currentRenderingComponent.clear();
+  return "ok";
+}
+
+// ─── JSI value access (C wrappers for Rust/C++/Swift) ─────────────────
+// All functions receive a live jsi::Runtime* and jsi::Object* from the
+// props store. Supports all JS types: string, number, bool, object, array, null.
+
+extern "C" const char* nativ_jsi_get_string(void* runtime, void* object, const char* prop_name) {
+  if (!runtime || !object) return "";
+  auto &rt = *reinterpret_cast<jsi::Runtime*>(runtime);
+  auto &obj = *reinterpret_cast<jsi::Object*>(object);
+  auto val = obj.getProperty(rt, prop_name);
+  if (val.isString()) {
+    static thread_local std::string buf;
+    buf = val.asString(rt).utf8(rt);
+    return buf.c_str();
+  }
+  return "";
+}
+
+extern "C" double nativ_jsi_get_number(void* runtime, void* object, const char* prop_name) {
+  if (!runtime || !object) return 0.0;
+  auto &rt = *reinterpret_cast<jsi::Runtime*>(runtime);
+  auto &obj = *reinterpret_cast<jsi::Object*>(object);
+  auto val = obj.getProperty(rt, prop_name);
+  if (val.isNumber()) return val.asNumber();
+  return 0.0;
+}
+
+extern "C" int nativ_jsi_get_bool(void* runtime, void* object, const char* prop_name) {
+  if (!runtime || !object) return 0;
+  auto &rt = *reinterpret_cast<jsi::Runtime*>(runtime);
+  auto &obj = *reinterpret_cast<jsi::Object*>(object);
+  auto val = obj.getProperty(rt, prop_name);
+  if (val.isBool()) return val.getBool() ? 1 : 0;
+  return 0;
+}
+
+extern "C" int nativ_jsi_has_prop(void* runtime, void* object, const char* prop_name) {
+  if (!runtime || !object) return 0;
+  auto &rt = *reinterpret_cast<jsi::Runtime*>(runtime);
+  auto &obj = *reinterpret_cast<jsi::Object*>(object);
+  return obj.hasProperty(rt, prop_name) ? 1 : 0;
+}
+
+extern "C" void nativ_jsi_call_function(void* runtime, void* object, const char* prop_name) {
+  if (!runtime || !object) return;
+  auto &rt = *reinterpret_cast<jsi::Runtime*>(runtime);
+  auto &obj = *reinterpret_cast<jsi::Object*>(object);
+  auto val = obj.getProperty(rt, prop_name);
+  if (val.isObject() && val.asObject(rt).isFunction(rt)) {
+    val.asObject(rt).asFunction(rt).call(rt);
+  }
+}
+
+extern "C" void nativ_jsi_call_function_with_string(void* runtime, void* object,
+                                                      const char* prop_name, const char* arg) {
+  if (!runtime || !object) return;
+  auto &rt = *reinterpret_cast<jsi::Runtime*>(runtime);
+  auto &obj = *reinterpret_cast<jsi::Object*>(object);
+  auto val = obj.getProperty(rt, prop_name);
+  if (val.isObject() && val.asObject(rt).isFunction(rt)) {
+    val.asObject(rt).asFunction(rt).call(rt, jsi::String::createFromUtf8(rt, arg));
+  }
+}
+
+// ─── New: array and object access ─────────────────────────────────────
+
+extern "C" int nativ_jsi_is_array(void* runtime, void* object, const char* prop_name) {
+  if (!runtime || !object) return 0;
+  auto &rt = *reinterpret_cast<jsi::Runtime*>(runtime);
+  auto &obj = *reinterpret_cast<jsi::Object*>(object);
+  auto val = obj.getProperty(rt, prop_name);
+  return (val.isObject() && val.asObject(rt).isArray(rt)) ? 1 : 0;
+}
+
+extern "C" int nativ_jsi_get_array_length(void* runtime, void* object, const char* prop_name) {
+  if (!runtime || !object) return 0;
+  auto &rt = *reinterpret_cast<jsi::Runtime*>(runtime);
+  auto &obj = *reinterpret_cast<jsi::Object*>(object);
+  auto val = obj.getProperty(rt, prop_name);
+  if (val.isObject() && val.asObject(rt).isArray(rt)) {
+    return (int)val.asObject(rt).asArray(rt).size(rt);
+  }
+  return 0;
+}
+
+extern "C" int nativ_jsi_is_object(void* runtime, void* object, const char* prop_name) {
+  if (!runtime || !object) return 0;
+  auto &rt = *reinterpret_cast<jsi::Runtime*>(runtime);
+  auto &obj = *reinterpret_cast<jsi::Object*>(object);
+  auto val = obj.getProperty(rt, prop_name);
+  return (val.isObject() && !val.asObject(rt).isArray(rt) && !val.asObject(rt).isFunction(rt)) ? 1 : 0;
+}
+
+extern "C" int nativ_jsi_is_null(void* runtime, void* object, const char* prop_name) {
+  if (!runtime || !object) return 1;
+  auto &rt = *reinterpret_cast<jsi::Runtime*>(runtime);
+  auto &obj = *reinterpret_cast<jsi::Object*>(object);
+  auto val = obj.getProperty(rt, prop_name);
+  return (val.isNull() || val.isUndefined()) ? 1 : 0;
+}
+
+// ─── JSI installation ──────────────────────────────────────────────────
+
+static void installNativRuntime(jsi::Runtime &rt, std::shared_ptr<facebook::react::CallInvoker> callInvoker = nullptr) {
+  g_callInvoker = callInvoker;
+  // Props from a previous runtime are now invalid — the old runtime is gone.
+  // We can't destroy jsi::Objects tied to a dead runtime (invalidate() crashes).
+  // Leak them intentionally — small, only happens on hot-reload.
+  {
+    auto &store = getPropsStore();
+    for (auto &[k, v] : store) {
+      new std::shared_ptr<jsi::Object>(std::move(v));  // leak the shared_ptr
+    }
+    store.clear();
+  }
+  g_runtime = nullptr;
+
+  auto nativObj = jsi::Object(rt);
+
+  // __nativ.callSync(moduleId, fnName, argsJson) → string
+  auto callSync = jsi::Function::createFromHostFunction(
+      rt,
+      jsi::PropNameID::forAscii(rt, "callSync"),
+      3,
+      [](jsi::Runtime &rt,
+         const jsi::Value &,
+         const jsi::Value *args,
+         size_t count) -> jsi::Value {
+
+        if (count < 3) {
+          throw jsi::JSError(rt, "__nativ.callSync requires 3 args: moduleId, fnName, argsJson");
+        }
+
+        auto moduleId = args[0].asString(rt).utf8(rt);
+        auto fnName   = args[1].asString(rt).utf8(rt);
+        auto argsJson = args[2].asString(rt).utf8(rt);
+
+        auto key = moduleId + "::" + fnName;
+        auto &reg = getRegistry();
+        auto it = reg.find(key);
+        if (it == reg.end() || !it->second.syncFn) {
+          throw jsi::JSError(rt, "Unknown Nativ function: " + key);
+        }
+
+        const char* result = it->second.syncFn(argsJson.c_str());
+        if (!result) return jsi::Value::null();
+
+        return jsi::String::createFromUtf8(rt, result);
+      });
+
+  // __nativ.callAsync(moduleId, fnName, argsJson) → Promise
+  auto callAsync = jsi::Function::createFromHostFunction(
+      rt,
+      jsi::PropNameID::forAscii(rt, "callAsync"),
+      3,
+      [](jsi::Runtime &rt,
+         const jsi::Value &,
+         const jsi::Value *args,
+         size_t count) -> jsi::Value {
+
+        if (count < 3) {
+          throw jsi::JSError(rt, "__nativ.callAsync requires 3 args: moduleId, fnName, argsJson");
+        }
+
+        auto moduleId = args[0].asString(rt).utf8(rt);
+        auto fnName   = args[1].asString(rt).utf8(rt);
+        auto argsJson = args[2].asString(rt).utf8(rt);
+
+        auto key = moduleId + "::" + fnName;
+        auto &reg = getRegistry();
+        auto it = reg.find(key);
+        if (it == reg.end() || !it->second.asyncFn) {
+          throw jsi::JSError(rt, "Unknown Nativ async function: " + key);
+        }
+
+        auto asyncFn = it->second.asyncFn;
+
+        // Create a Promise via JSI
+        auto Promise = rt.global().getPropertyAsFunction(rt, "Promise");
+        auto executor = jsi::Function::createFromHostFunction(
+            rt,
+            jsi::PropNameID::forAscii(rt, "executor"),
+            2,
+            [asyncFn, argsJson](jsi::Runtime &rt,
+                                const jsi::Value &,
+                                const jsi::Value *pargs,
+                                size_t) -> jsi::Value {
+
+              auto resolve = std::make_shared<jsi::Function>(pargs[0].asObject(rt).asFunction(rt));
+              auto reject  = std::make_shared<jsi::Function>(pargs[1].asObject(rt).asFunction(rt));
+              auto invoker = g_callInvoker;
+
+              // Context struct for C callback bridge.
+              // NativAsyncFn uses plain C function pointers — can't capture.
+              // We pass context via a thread-local pointer.
+              struct AsyncCtx {
+                std::shared_ptr<jsi::Function> resolve;
+                std::shared_ptr<jsi::Function> reject;
+                std::shared_ptr<facebook::react::CallInvoker> invoker;
+              };
+              // Stored on heap, freed after callbacks fire.
+              static thread_local AsyncCtx* _asyncCtx = nullptr;
+              auto ctx = new AsyncCtx{resolve, reject, invoker};
+
+              dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
+                auto argsCopy = argsJson;
+                _asyncCtx = ctx;
+
+                asyncFn(
+                    argsCopy.c_str(),
+                    // resolve callback (plain C function pointer)
+                    [](const char* result) {
+                      auto* c = _asyncCtx;
+                      if (!c) return;
+                      _asyncCtx = nullptr;
+                      auto resultStr = std::string(result ? result : "null");
+                      auto res = c->resolve;
+                      auto inv = c->invoker;
+                      delete c;
+                      if (inv) {
+                        inv->invokeAsync([res, resultStr]() {
+                          auto &rt = *g_runtime;
+                          auto json = rt.global().getPropertyAsObject(rt, "JSON");
+                          auto parse = json.getPropertyAsFunction(rt, "parse");
+                          auto parsed = parse.call(rt, jsi::String::createFromUtf8(rt, resultStr));
+                          res->call(rt, std::move(parsed));
+                        });
+                      }
+                    },
+                    // reject callback (plain C function pointer)
+                    [](const char* code, const char* msg) {
+                      auto* c = _asyncCtx;
+                      if (!c) return;
+                      _asyncCtx = nullptr;
+                      auto codeStr = std::string(code ? code : "ASYNC_ERROR");
+                      auto msgStr = std::string(msg ? msg : "Unknown error");
+                      auto rej = c->reject;
+                      auto inv = c->invoker;
+                      delete c;
+                      if (inv) {
+                        inv->invokeAsync([rej, msgStr]() {
+                          auto &rt = *g_runtime;
+                          rej->call(rt, jsi::String::createFromUtf8(rt, msgStr));
+                        });
+                      }
+                    });
+              });
+
+              return jsi::Value::undefined();
+            });
+
+        return Promise.callAsConstructor(rt, executor);
+      });
+
+  // __nativ.modules() → list registered module::fn keys (for debugging)
+  auto listModules = jsi::Function::createFromHostFunction(
+      rt,
+      jsi::PropNameID::forAscii(rt, "modules"),
+      0,
+      [](jsi::Runtime &rt,
+         const jsi::Value &,
+         const jsi::Value *,
+         size_t) -> jsi::Value {
+        auto &reg = getRegistry();
+        auto arr = jsi::Array(rt, reg.size());
+        size_t i = 0;
+        for (auto &[key, _] : reg) {
+          arr.setValueAtIndex(rt, i++, jsi::String::createFromUtf8(rt, key));
+        }
+        return arr;
+      });
+
+  // In release builds there are no dylibs to load — all native code is statically linked.
+#if DEBUG
+  auto loadDylib = jsi::Function::createFromHostFunction(
+      rt,
+      jsi::PropNameID::forAscii(rt, "loadDylib"),
+      1,
+      [](jsi::Runtime &rt,
+         const jsi::Value &,
+         const jsi::Value *args,
+         size_t count) -> jsi::Value {
+
+        if (count < 1 || !args[0].isString()) {
+          throw jsi::JSError(rt, "__nativ.loadDylib requires a URL string");
+        }
+
+        auto urlStr = args[0].asString(rt).utf8(rt);
+        NSURL *url = [NSURL URLWithString:[NSString stringWithUTF8String:urlStr.c_str()]];
+
+        // Synchronous download to app sandbox (PoC — production would be async)
+        NSError *err = nil;
+        NSLog(@"[Nativ] Downloading dylib from: %@", url);
+        // Use NSURLRequest with no-cache policy to bypass NSURLCache
+        NSURLRequest *request = [NSURLRequest requestWithURL:url
+                                                 cachePolicy:NSURLRequestReloadIgnoringLocalCacheData
+                                             timeoutInterval:120.0];
+        NSURLResponse *response = nil;
+        NSData *data = [NSURLConnection sendSynchronousRequest:request
+                                             returningResponse:&response
+                                                         error:&err];
+        if (!data) {
+          auto msg = std::string("Failed to download dylib: ") +
+                     (err ? err.localizedDescription.UTF8String : "unknown");
+          throw jsi::JSError(rt, msg);
+        }
+
+        // Verify we got a Mach-O file (magic: 0xFEEDFACF for 64-bit)
+        NSLog(@"[Nativ] Downloaded %lu bytes", (unsigned long)data.length);
+        if (data.length >= 4) {
+          uint32_t magic = 0;
+          [data getBytes:&magic length:4];
+          NSLog(@"[Nativ] Magic: 0x%08X (expected 0xFEEDFACF for arm64)", magic);
+          if (magic != 0xFEEDFACF && magic != 0xCFFAEDFE) {
+            // Not a Mach-O — log first bytes for debugging
+            const char *bytes = (const char *)data.bytes;
+            NSString *preview = [[NSString alloc] initWithBytes:bytes
+                                                         length:MIN(100, data.length)
+                                                       encoding:NSUTF8StringEncoding];
+            NSLog(@"[Nativ] Not Mach-O! First bytes: %@", preview ?: @"(binary)");
+            throw jsi::JSError(rt, "Downloaded data is not a valid Mach-O dylib");
+          }
+        }
+
+        // Write to sandbox with unique name (timestamp-based)
+        NSString *docsDir = NSSearchPathForDirectoriesInDomains(
+            NSDocumentDirectory, NSUserDomainMask, YES).firstObject;
+        NSString *dylibDir = [docsDir stringByAppendingPathComponent:@"nativ_dylibs"];
+        [[NSFileManager defaultManager] createDirectoryAtPath:dylibDir
+                                  withIntermediateDirectories:YES
+                                                  attributes:nil
+                                                       error:nil];
+
+        // Use a unique filename so dlopen sees it as a new library
+        NSString *filename = [NSString stringWithFormat:@"nativ_%llu.dylib",
+                              (unsigned long long)[[NSDate date] timeIntervalSince1970] * 1000];
+        NSString *localPath = [dylibDir stringByAppendingPathComponent:filename];
+        [data writeToFile:localPath atomically:YES];
+
+        // dlopen with RTLD_GLOBAL so symbols from shared dylibs (native.dylib)
+        // are available to subsequently loaded component dylibs.
+        void *handle = dlopen(localPath.UTF8String, RTLD_NOW | RTLD_GLOBAL);
+        if (!handle) {
+          auto msg = std::string("dlopen failed: ") + (dlerror() ?: "unknown");
+          NSLog(@"[Nativ] %s", msg.c_str());
+          throw jsi::JSError(rt, msg);
+        }
+
+        NSLog(@"[Nativ] Hot-reloaded dylib: %@", localPath);
+        return jsi::Value(true);
+      });
+#endif
+
+  // __nativ.setComponentProps(componentId, propsObject)
+  // Stores the live JSI object. nativ_try_render passes it directly to the
+  // render function. Supports all prop types (objects, arrays, functions, etc).
+  auto setComponentProps = jsi::Function::createFromHostFunction(
+      rt,
+      jsi::PropNameID::forAscii(rt, "setComponentProps"),
+      2,
+      [](jsi::Runtime &rt,
+         const jsi::Value &,
+         const jsi::Value *args,
+         size_t count) -> jsi::Value {
+        if (count < 2 || !args[0].isString()) return jsi::Value::undefined();
+
+        auto componentId = args[0].asString(rt).utf8(rt);
+        auto &store = getPropsStore();
+
+        if (args[1].isObject()) {
+          store[componentId] = std::make_shared<jsi::Object>(args[1].asObject(rt));
+        } else {
+          store.erase(componentId);
+        }
+
+        return jsi::Value::undefined();
+      });
+
+  nativObj.setProperty(rt, "callSync", std::move(callSync));
+  nativObj.setProperty(rt, "callAsync", std::move(callAsync));
+  nativObj.setProperty(rt, "modules", std::move(listModules));
+#if DEBUG
+  nativObj.setProperty(rt, "loadDylib", std::move(loadDylib));
+#endif
+  nativObj.setProperty(rt, "setComponentProps", std::move(setComponentProps));
+
+  // Device/simulator target — used by JS shim to request correct dylib
+#if TARGET_OS_SIMULATOR
+  nativObj.setProperty(rt, "target", jsi::String::createFromUtf8(rt, "simulator"));
+#else
+  nativObj.setProperty(rt, "target", jsi::String::createFromUtf8(rt, "device"));
+#endif
+
+  rt.global().setProperty(rt, "__nativ", std::move(nativObj));
+  g_runtime = &rt;  // Store for render function prop access
+  NSLog(@"[Nativ] __nativ installed with %lu registered functions", (unsigned long)getRegistry().size());
+}
+
+// ─── TurboModule with JSI bindings ─────────────────────────────────────
+// Codegen-backed TurboModule. RN calls installJSIBindingsWithRuntime:
+// when the module is first accessed → installs global.__nativ.
+// No dependency on the old expo-ferrum module.
+
+#import <React/RCTBridgeModule.h>
+#import <ReactCommon/RCTTurboModule.h>
+#import <ReactCommon/RCTTurboModuleWithJSIBindings.h>
+#import <ReactCommon/CallInvoker.h>
+
+#if __has_include(<NativFabricSpec/NativFabricSpec.h>)
+#import <NativFabricSpec/NativFabricSpec.h>
+#elif __has_include(<ReactCodegen/NativFabricSpec.h>)
+#import <ReactCodegen/NativFabricSpec.h>
+#elif __has_include("NativFabricSpec.h")
+#import "NativFabricSpec.h"
+#endif
+
+@interface NativRuntimeModule : NSObject <NativeNativRuntimeSpec, RCTTurboModuleWithJSIBindings>
+@end
+
+@implementation NativRuntimeModule
+
+RCT_EXPORT_MODULE(NativRuntime)
+
+- (NSDictionary *)getConstants {
+  return @{};
+}
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params {
+  return std::make_shared<facebook::react::NativeNativRuntimeSpecJSI>(params);
+}
+
+- (void)installJSIBindingsWithRuntime:(facebook::jsi::Runtime &)runtime
+                          callInvoker:(const std::shared_ptr<facebook::react::CallInvoker> &)callinvoker
+{
+  installNativRuntime(runtime, callinvoker);
+}
+
++ (BOOL)requiresMainQueueSetup {
+  return NO;
+}
+
+@end
+
+// Keep nativ_cpp_install for backward compatibility with expo-ferrum (if installed)
+extern "C" void nativ_cpp_install(void *runtimePtr) {
+  if (!runtimePtr) return;
+  auto &rt = *reinterpret_cast<jsi::Runtime *>(runtimePtr);
+  installNativRuntime(rt);
+}
+

package/metro/Nativ.h

@@ -0,0 +1,126 @@
+// Nativ.h — Runtime header for react-native-native C++/ObjC++ files.
+// Include this in any .cpp or .mm file that exports functions or components to JS.
+
+#pragma once
+
+#include <string>
+#include <vector>
+#include <cstdint>
+#include <stdexcept>
+#include <optional>
+#include <functional>
+
+// ─── Function export annotation ───────────────────────────────────────
+// NATIV_EXPORT(sync)
+// int add(int a, int b) { return a + b; }
+
+#define NATIV_EXPORT(...) __attribute__((annotate("nativ_export:" #__VA_ARGS__)))
+
+// ─── Component system ─────────────────────────────────────────────────
+// Define a props struct, then use NATIV_COMPONENT to register:
+//
+// struct MyProps {
+//   std::string title = "Hello";
+//   double opacity = 1.0;
+//   std::function<void()> onPress;
+// };
+//
+// NATIV_COMPONENT(MyComponent, MyProps)
+// void mount(void* view, float w, float h, MyProps props) {
+//   UIView* v = (__bridge UIView*)view;
+//   // ... use props.title, props.opacity, props.onPress()
+// }
+
+// JSI C API — defined in NativRuntime, resolved at dlopen
+extern "C" {
+  typedef void (*NativRenderFn)(void*, float, float, void*, void*);
+  void nativ_register_render(const char*, NativRenderFn);
+
+  // Scalar props
+  const char* nativ_jsi_get_string(void* rt, void* obj, const char* name);
+  double nativ_jsi_get_number(void* rt, void* obj, const char* name);
+  int nativ_jsi_get_bool(void* rt, void* obj, const char* name);
+  int nativ_jsi_has_prop(void* rt, void* obj, const char* name);
+
+  // Callbacks
+  void nativ_jsi_call_function(void* rt, void* obj, const char* name);
+  void nativ_jsi_call_function_with_string(void* rt, void* obj, const char* name, const char* arg);
+
+  // Type checking
+  int nativ_jsi_is_array(void* rt, void* obj, const char* name);
+  int nativ_jsi_get_array_length(void* rt, void* obj, const char* name);
+  int nativ_jsi_is_object(void* rt, void* obj, const char* name);
+  int nativ_jsi_is_null(void* rt, void* obj, const char* name);
+}
+
+// Helper: extract a std::string prop
+inline std::string _nativ_get_string(void* rt, void* obj, const char* name, const std::string& def = "") {
+  if (!rt || !obj) return def;
+  const char* s = nativ_jsi_get_string(rt, obj, name);
+  return (s && s[0]) ? std::string(s) : def;
+}
+
+// Helper: extract a double prop
+inline double _nativ_get_number(void* rt, void* obj, const char* name, double def = 0.0) {
+  if (!rt || !obj || !nativ_jsi_has_prop(rt, obj, name)) return def;
+  return nativ_jsi_get_number(rt, obj, name);
+}
+
+// Helper: extract a bool prop
+inline bool _nativ_get_bool(void* rt, void* obj, const char* name, bool def = false) {
+  if (!rt || !obj || !nativ_jsi_has_prop(rt, obj, name)) return def;
+  return nativ_jsi_get_bool(rt, obj, name) != 0;
+}
+
+// Helper: extract a callback prop
+inline std::function<void()> _nativ_get_callback(void* rt, void* obj, const char* name) {
+  if (!rt || !obj || !nativ_jsi_has_prop(rt, obj, name)) return nullptr;
+  // Capture by value — safe only during mount()
+  return [rt, obj, n = std::string(name)]() {
+    nativ_jsi_call_function(rt, obj, n.c_str());
+  };
+}
+
+// nativ::component marker (parsed by Metro transformer)
+// NATIV_COMPONENT(Name, PropsStruct) must be followed by:
+//   void mount(void* view, float w, float h, PropsStruct props) { ... }
+#define NATIV_COMPONENT(name, props_type)                                        \
+  /* Forward declare mount */                                                  \
+  static void mount(void* view, float w, float h, props_type props);           \
+                                                                               \
+  /* Render entry point — unique per component for static linking */           \
+  extern "C" void nativ_##name##_render(void* view, float w, float h,        \
+                                         void* jsi_runtime, void* jsi_props); \
+                                                                               \
+  /* Registration */                                                           \
+  __attribute__((constructor, used))                                           \
+  static void _nativ_register_##name() {                                         \
+    nativ_register_render("nativ." #name, nativ_##name##_render);            \
+  }
+
+// ─── JSON helpers (for NATIV_EXPORT functions) ──────────────────────────
+
+namespace nativ {
+
+inline std::string toJson(int v)         { return std::to_string(v); }
+inline std::string toJson(int64_t v)     { return std::to_string(v); }
+inline std::string toJson(uint32_t v)    { return std::to_string(v); }
+inline std::string toJson(float v)       { return std::to_string(v); }
+inline std::string toJson(double v)      { return std::to_string(v); }
+inline std::string toJson(bool v)        { return v ? "true" : "false"; }
+inline std::string toJson(const std::string& v) {
+  std::string out = "\"";
+  for (char c : v) {
+    switch (c) {
+      case '"':  out += "\\\""; break;
+      case '\\': out += "\\\\"; break;
+      case '\n': out += "\\n";  break;
+      default:   out += c;      break;
+    }
+  }
+  out += '"';
+  return out;
+}
+inline std::string toJson(const char* v) { return v ? toJson(std::string(v)) : "null"; }
+
+} // namespace nativ