@fireflydb/expo-driver 0.0.6

package/README.md

@@ -0,0 +1,253 @@
+# @fireflydb/expo
+
+Expo native module that bundles the Rust `libfirefly` SQLite extension and
+wires it into [expo-sqlite](https://docs.expo.dev/versions/latest/sdk/sqlite/),
+[expo-secure-store](https://docs.expo.dev/versions/latest/sdk/securestore/),
+and React Native WebSocket. Exposes a change-listener bridge so JS gets
+notified of CRDT-relevant local writes.
+
+This document focuses on **how the native core is built and shipped**. For
+SDK usage, see [`packages/core`](../core).
+
+---
+
+## Layout
+
+```
+packages/expo/
+├── cpp/                          # Cross-platform C++ shared by iOS + Android
+│   ├── firefly_abi.h             # Rust C-ABI declarations (firefly_add_change_listener, …)
+│   ├── firefly_listener.h        # Listener registry public surface
+│   └── firefly_listener.cpp      # Process-wide handle→dispatch registry
+│
+├── ios/
+│   ├── Firefly.xcframework/      # ← produced by scripts/build-libfirefly.sh
+│   ├── FireflyClient.podspec     # Vends the xcframework + symlinks ../cpp into the pod
+│   └── FireflyClientModule.swift
+│
+├── android/
+│   ├── build.gradle              # Wires jniLibs + externalNativeBuild (CMake)
+│   └── src/main/
+│       ├── cpp/CMakeLists.txt    # Imports prebuilt libfirefly.so, builds libfirefly_jni.so
+│       ├── cpp/firefly_jni.cpp   # JNI shim
+│       └── jniLibs/<abi>/libfirefly.so   # ← produced by scripts/build-libfirefly.sh
+│
+├── scripts/
+│   └── build-libfirefly.sh       # Cross-compiles core/ for iOS + Android
+│
+└── src/                          # TypeScript surface (drivers + module bindings)
+```
+
+The single source of truth for the native core is the `core/` Rust crate at
+the repo root. Everything under `ios/Firefly.xcframework/` and
+`android/src/main/jniLibs/` is **build output** (gitignored) — never hand-edit it.
+
+---
+
+## Rebuilding the core
+
+Run from this package directory:
+
+```bash
+pnpm build:libfirefly         # both platforms
+bash scripts/build-libfirefly.sh ios       # iOS only
+bash scripts/build-libfirefly.sh android   # Android only
+```
+
+The script ([scripts/build-libfirefly.sh](scripts/build-libfirefly.sh))
+cross-compiles `core/` with `--no-default-features --features
+loadable_extension` so the resulting binary is a SQLite loadable extension
+(no bundled SQLite — both Expo and Android ship their own).
+
+### Prerequisites
+
+| Tool | Used for | Auto-installed by script? |
+|------|----------|---------------------------|
+| `rustup` + Rust toolchain | All targets | No (must be on PATH) |
+| iOS rust targets (`aarch64-apple-ios`, `aarch64-apple-ios-sim`, `x86_64-apple-ios`) | iOS | Yes (`rustup target add`) |
+| Android rust targets (`aarch64-linux-android`, `armv7-linux-androideabi`, `x86_64-linux-android`, `i686-linux-android`) | Android | Yes |
+| `xcodebuild`, `lipo`, `install_name_tool` | iOS framework assembly | No (Xcode CLT) |
+| `cargo-ndk` | Android cross-compile | Yes (`cargo install`) |
+| Android NDK r24+ (`ANDROID_NDK_HOME` exported) | Android | No |
+
+### When to rebuild
+
+Rebuild after **any change under `core/`** that affects the C-ABI surface
+or runtime behavior. The `.xcframework` and `.so` files are gitignored build
+output: the `prepack` hook rebuilds them on `pnpm pack` / `pnpm publish`, so
+the published package ships binaries and consumers never need a Rust
+toolchain. In a fresh clone, run `pnpm build:libfirefly` once before building
+the example app.
+
+The shared C++ in `cpp/` (`firefly_listener.{cpp,h}`) is **not** built by
+this script — it's compiled by the platform build systems (CocoaPods on
+iOS, Gradle/CMake on Android) when the host app builds. Editing it requires
+no rebuild script run; just rebuild the host app.
+
+---
+
+## iOS pipeline
+
+```
+core/  ──cargo build──▶  target/<rust-target>/release/libfirefly.dylib
+                          │
+                          ├─ aarch64-apple-ios          ─┐
+                          ├─ aarch64-apple-ios-sim      ─┼─lipo──▶ sim-universal
+                          └─ x86_64-apple-ios           ─┘
+                                                          │
+                          device-arm64.dylib              sim-universal.dylib
+                                  │                              │
+                          ios_make_framework            ios_make_framework
+                                  ▼                              ▼
+                  Firefly.framework (device)     Firefly.framework (sim-universal)
+                                  └──── xcodebuild -create-xcframework ────┘
+                                                  ▼
+                                    ios/Firefly.xcframework/
+```
+
+What the script does, in order:
+
+1. **Per-slice `cargo build`** for each iOS target into the workspace
+   `target/` dir (the workspace lives at the repo root, not under `core/`).
+2. **`lipo`** the two simulator slices (`arm64-sim` + `x86_64`) into a
+   single fat dylib. iOS device stays as a single `arm64` slice.
+3. **`ios_make_framework`** wraps each dylib in a proper
+   `Firefly.framework` bundle: copies the dylib in as the bundle binary
+   (named `Firefly`, no extension), rewrites its `LC_ID_DYLIB` install
+   name to `@rpath/Firefly.framework/Firefly` via `install_name_tool`, and
+   writes an `Info.plist` with the right `CFBundleSupportedPlatforms` /
+   `MinimumOSVersion`.
+4. **`xcodebuild -create-xcframework`** combines the device and
+   simulator-universal frameworks into `Firefly.xcframework`. This is the
+   canonical Apple distribution shape and the only one CocoaPods accepts
+   via `s.vendored_frameworks` for **dynamic** linking.
+5. **`nm` verification** that `_sqlite3_firefly_init` is exported in both
+   slices — that's the entry point `expo-sqlite` calls via
+   `sqlite3_load_extension`.
+
+`FireflyClient.podspec` then:
+- Vendors `Firefly.xcframework` (Xcode embeds the right slice into
+  `<App>.app/Frameworks/Firefly.framework/Firefly` and re-signs at archive
+  time).
+- Pulls in the shared C++ via `ios/_shared/*.{cpp,h}` (a committed
+  directory of per-file symlinks pointing at `../cpp/*`). This avoids
+  a separate `.mm` shim — Swift binds to the C-ABI symbols via
+  `@_silgen_name`. See the long comment in
+  [`FireflyClient.podspec`](ios/FireflyClient.podspec) for why
+  `_shared/` is committed instead of generated by `prepare_command`
+  (CocoaPods skips `prepare_command` for `:path =>` pods).
+
+---
+
+## Android pipeline
+
+```
+core/  ──cargo ndk build──▶  target/<rust-target>/release/libfirefly.so
+                              │
+                              ├─ aarch64-linux-android      ─▶ jniLibs/arm64-v8a/libfirefly.so
+                              ├─ armv7-linux-androideabi    ─▶ jniLibs/armeabi-v7a/libfirefly.so
+                              ├─ x86_64-linux-android       ─▶ jniLibs/x86_64/libfirefly.so
+                              └─ i686-linux-android         ─▶ jniLibs/x86/libfirefly.so
+
+(later, at app build time:)
+
+android/src/main/cpp/firefly_jni.cpp + cpp/firefly_listener.cpp
+                              │
+                          CMake (externalNativeBuild)
+                              ▼
+                  jniLibs/<abi>/libfirefly_jni.so   (per ABI, links against libfirefly.so)
+```
+
+What the script does:
+
+1. **`cargo ndk --target <rust-target> --platform 24`** for each ABI. The
+   `--platform 24` matches `minSdkVersion 24` in `android/build.gradle`.
+   `cargo-ndk` handles wiring the NDK toolchain into Cargo so the Rust
+   compiler emits ABI-correct shared objects.
+2. **Copies** each `libfirefly.so` into
+   `android/src/main/jniLibs/<abi>/`.
+
+At app build time, Gradle (`android/build.gradle`):
+- Picks up the prebuilt `libfirefly.so` from `jniLibs/<abi>/` and packages
+  them into the APK/AAB — `applicationInfo.nativeLibraryDir` resolves them
+  at runtime.
+- Compiles `libfirefly_jni.so` per ABI via `externalNativeBuild` /
+  CMakeLists ([android/src/main/cpp/CMakeLists.txt](android/src/main/cpp/CMakeLists.txt)).
+  CMake imports `libfirefly.so` as an `IMPORTED` target and links the JNI
+  shim against it plus the shared `cpp/firefly_listener.cpp`.
+- `packagingOptions { doNotStrip "**/libfirefly.so" }` — the Rust release
+  profile already strips, and stripping again can drop the
+  `sqlite3_firefly_init` export.
+
+Kotlin loads the native library with `System.loadLibrary("firefly_jni")`,
+which transitively pulls in `libfirefly.so` because of the import
+relationship in CMake.
+
+---
+
+## Shared C++ (`cpp/`)
+
+Both platforms include `cpp/firefly_listener.cpp` directly in their build
+([`firefly_listener.cpp`](cpp/firefly_listener.cpp)). It's a single
+process-wide registry mapping a caller-supplied `int64_t handle` to a
+platform dispatcher (Swift `sendEvent` on iOS, JNI `CallStaticVoidMethod`
+on Android). Keeping this in one place means the lifetime/race semantics
+required by `firefly_add_change_listener`'s contract are implemented
+once, not twice.
+
+Linking model:
+- **iOS:** compiled into the `FireflyClient` pod alongside the Swift
+  module, with `-fvisibility=hidden`. Swift uses `@_silgen_name` to bind
+  to `firefly_listener_register` / `firefly_listener_unregister`.
+- **Android:** compiled into `libfirefly_jni.so` by CMake. JNI calls into
+  it directly.
+
+The C-ABI between this layer and Rust (`firefly_add_change_listener`,
+`firefly_remove_change_listener`) is declared in
+[`cpp/firefly_abi.h`](cpp/firefly_abi.h).
+
+---
+
+## Troubleshooting
+
+**`sqlite3_firefly_init` not exported.** The script verifies this on iOS
+and aborts the build. If it ever fires, check that `core/src/lib.rs` still
+declares the entry point with the `sqlite_extension_init` macro and that
+release-profile `strip = true` isn't dropping the symbol on a new
+toolchain.
+
+**Android NDK not found.** Export `ANDROID_NDK_HOME` (e.g.
+`export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/27.1.12297006`). `cargo-ndk`
+reads it.
+
+**`linker 'cc' not found` on Android targets.** `cargo-ndk` injects the
+right linker via env vars only inside its child `cargo` invocation. If you
+ran `cargo build --target aarch64-linux-android` directly (not via
+`cargo ndk`), you'll get this. Use the script.
+
+**Stale `target/` cache after toolchain bump.** `cargo clean` at the repo
+root, then re-run the script. The targets are cross builds so they don't
+share intermediate artifacts with desktop dev builds, but a corrupt cache
+across a Rust version bump can manifest as missing symbols.
+
+**`Undefined symbol: _firefly_listener_register` at iOS link time.** The
+shared C++ in `cpp/` is pulled into the pod via the committed
+`ios/_shared/` directory of per-file symlinks. Two CocoaPods quirks
+combined to cause earlier breakage here:
+1. CocoaPods indexes pod sources via Ruby's `Find.find`, which does NOT
+   recurse into symlinked directories — so `_shared` cannot itself be
+   a symlink. It must be a real directory containing file-level
+   symlinks (which Find DOES list).
+2. CocoaPods does NOT run `prepare_command` for development
+   (`:path =>`) pods. Anything that expects to be set up at
+   `pod install` time silently no-ops.
+
+So `_shared/` is checked into git; if you add a file under `cpp/`,
+mirror it with `ln -sfn ../../cpp/<name> ios/_shared/<name>` and commit.
+After podspec or `_shared/` changes, re-run `pod install` (or
+`npx expo prebuild --clean` for Expo apps) so the Pods xcodeproj
+regenerates with the new sources. The `cannot link directly with
+'SwiftUICore'` line that often appears in the Expo CLI output is
+unrelated noise from Xcode 26 — check
+`apps/<app>/.expo/xcodebuild.log` for the real `Undefined symbols`
+section.

package/android/build.gradle

@@ -0,0 +1,51 @@
+plugins {
+    id 'com.android.library'
+    id 'org.jetbrains.kotlin.android'
+    id 'expo-module-gradle-plugin'
+}
+
+group = 'com.fireflydb.expo'
+version = '0.0.0'
+
+android {
+    namespace "com.fireflydb.expo"
+
+    defaultConfig {
+        minSdkVersion 24
+        compileSdk 34
+        versionCode 1
+        versionName "0.0.0"
+
+        externalNativeBuild {
+            cmake {
+                cppFlags '-std=c++17', '-fvisibility=hidden'
+            }
+        }
+    }
+
+    externalNativeBuild {
+        cmake {
+            // Builds libfirefly_jni.so per ABI. CMakeLists.txt pulls in the
+            // pre-built libfirefly.so from src/main/jniLibs/${ANDROID_ABI}/.
+            path "src/main/cpp/CMakeLists.txt"
+            version "3.22.1"
+        }
+    }
+
+    sourceSets {
+        main {
+            // jniLibs/<abi>/libfirefly.so is produced by scripts/build-libfirefly.sh.
+            // Gradle picks them up here and packages them into the host APK/AAB
+            // so applicationInfo.nativeLibraryDir resolves them at runtime.
+            // libfirefly_jni.so is produced by the externalNativeBuild above
+            // and packaged automatically.
+            jniLibs.srcDirs += ['src/main/jniLibs']
+        }
+    }
+
+    packagingOptions {
+        // Don't strip libfirefly.so. The Rust release profile already strips
+        // symbols for size; we keep the SQLite extension entry point exported.
+        doNotStrip "**/libfirefly.so"
+    }
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,21 @@
+cmake_minimum_required(VERSION 3.22.1)
+project(firefly_jni)
+
+# Pre-built libfirefly.so per ABI is already in jniLibs/${ANDROID_ABI}/.
+# Import it so the JNI shim can resolve the firefly_* C-ABI symbols at
+# load time, then `System.loadLibrary("firefly_jni")` in Kotlin pulls
+# both shared objects into the process.
+add_library(firefly SHARED IMPORTED)
+set_target_properties(firefly PROPERTIES IMPORTED_LOCATION
+  ${CMAKE_CURRENT_SOURCE_DIR}/../jniLibs/${ANDROID_ABI}/libfirefly.so)
+
+# Cross-platform listener registry shared with the iOS module. Lives at
+# packages/expo/cpp/ — sibling of android/ and ios/. The path here
+# climbs out of android/src/main/cpp/ to the package root.
+set(SHARED_CPP_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../../../cpp)
+
+add_library(firefly_jni SHARED
+  firefly_jni.cpp
+  ${SHARED_CPP_DIR}/firefly_listener.cpp)
+target_include_directories(firefly_jni PRIVATE ${SHARED_CPP_DIR})
+target_link_libraries(firefly_jni firefly log)

package/android/src/main/cpp/firefly_jni.cpp

@@ -0,0 +1,110 @@
+// JNI shim that bridges the cross-platform listener registry
+// (`firefly_listener.{h,cpp}` at packages/expo/cpp/) to the JVM. The
+// shared registry owns the libfirefly C-ABI lifetime and the
+// integer-handle dispatch table; this file only marshals bytes between
+// C++ and Kotlin's `FireflyJniBridge.dispatch(handle, byte[])`.
+
+#include <jni.h>
+#include <android/log.h>
+#include <cstdint>
+
+#include "firefly_listener.h"
+
+#define LOG_TAG "FireflyJNI"
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+
+namespace {
+
+JavaVM* g_vm = nullptr;
+jclass g_bridgeClass = nullptr;        // global ref to FireflyJniBridge
+jmethodID g_dispatchMethod = nullptr;  // dispatch(long, byte[])
+
+JNIEnv* getEnvOrAttach(bool* attached) {
+  *attached = false;
+  if (g_vm == nullptr) return nullptr;
+  JNIEnv* env = nullptr;
+  jint res = g_vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6);
+  if (res == JNI_OK) return env;
+  if (res == JNI_EDETACHED) {
+    if (g_vm->AttachCurrentThread(&env, nullptr) == JNI_OK) {
+      *attached = true;
+      return env;
+    }
+  }
+  return nullptr;
+}
+
+void detachIfNeeded(bool attached) {
+  if (attached && g_vm != nullptr) {
+    g_vm->DetachCurrentThread();
+  }
+}
+
+// Called by the shared C++ thunk on the SQLite writer thread for every
+// fire that maps to a JNI-registered listener. Marshals the blob into
+// a fresh `jbyteArray` and forwards via the Kotlin static dispatcher,
+// which routes by handle and emits the Expo event.
+void jniDispatch(int64_t handle, const uint8_t* blob, size_t len) {
+  if (g_vm == nullptr || g_bridgeClass == nullptr || g_dispatchMethod == nullptr) {
+    return;
+  }
+  bool attached = false;
+  JNIEnv* env = getEnvOrAttach(&attached);
+  if (env == nullptr) return;
+
+  jbyteArray arr = env->NewByteArray(static_cast<jsize>(len));
+  if (arr != nullptr) {
+    env->SetByteArrayRegion(
+        arr, 0, static_cast<jsize>(len),
+        reinterpret_cast<const jbyte*>(blob));
+    env->CallStaticVoidMethod(
+        g_bridgeClass, g_dispatchMethod, static_cast<jlong>(handle), arr);
+    if (env->ExceptionCheck()) {
+      env->ExceptionDescribe();
+      env->ExceptionClear();
+    }
+    env->DeleteLocalRef(arr);
+  }
+  detachIfNeeded(attached);
+}
+
+}  // namespace
+
+extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* /*reserved*/) {
+  g_vm = vm;
+  JNIEnv* env = nullptr;
+  if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {
+    return JNI_ERR;
+  }
+  jclass local = env->FindClass("com/fireflydb/expo/FireflyJniBridge");
+  if (local == nullptr) {
+    LOGE("FireflyJniBridge class not found");
+    return JNI_ERR;
+  }
+  g_bridgeClass = static_cast<jclass>(env->NewGlobalRef(local));
+  env->DeleteLocalRef(local);
+  g_dispatchMethod = env->GetStaticMethodID(g_bridgeClass, "dispatch", "(J[B)V");
+  if (g_dispatchMethod == nullptr) {
+    LOGE("FireflyJniBridge.dispatch(J[B)V not found");
+    return JNI_ERR;
+  }
+  return JNI_VERSION_1_6;
+}
+
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_fireflydb_expo_FireflyJniBridge_nativeRegister(
+    JNIEnv* env, jclass /*clazz*/, jstring path, jlong handle) {
+  if (path == nullptr) return 0;
+  const char* utf = env->GetStringUTFChars(path, nullptr);
+  if (utf == nullptr) return 0;
+  uint64_t rust_id = firefly_listener_register(
+      utf, static_cast<int64_t>(handle), &jniDispatch);
+  env->ReleaseStringUTFChars(path, utf);
+  return static_cast<jlong>(rust_id);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_fireflydb_expo_FireflyJniBridge_nativeUnregister(
+    JNIEnv* /*env*/, jclass /*clazz*/, jlong handle) {
+  firefly_listener_unregister(static_cast<int64_t>(handle));
+}

package/android/src/main/kotlin/com/fireflydb/expo/FireflyClientModule.kt

@@ -0,0 +1,101 @@
+package com.fireflydb.expo
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import java.io.File
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicLong
+
+class FireflyClientModule : Module() {
+    private val nextSwiftId = AtomicLong(1)
+    // Maps the JS-visible id to the JNI dispatch handle. The shared
+    // C++ registry tracks the libfirefly rust-id internally so we no
+    // longer keep it on the Kotlin side.
+    private val listeners = ConcurrentHashMap<Long, Long>()
+
+    override fun definition() = ModuleDefinition {
+        Name("FireflyClient")
+
+        Events("FireflyChange")
+
+        Function("getLibraryPath") {
+            // Resolve libfirefly.so against the app's native library dir.
+            // Returning an absolute path (rather than the bare name "firefly")
+            // sidesteps Android linker quirks: dlopen("firefly") on bionic does
+            // not auto-prepend "lib" or scan LD_LIBRARY_PATH the way glibc does.
+            //
+            // Strip the ".so" suffix before returning. SQLite's
+            // sqlite3_load_extension auto-appends the platform extension when
+            // the path lacks one; if we returned "/.../libfirefly.so" we'd
+            // end up with "libfirefly.so.so" and dlopen would fail.
+            val nativeLibDir = appContext.reactContext?.applicationInfo?.nativeLibraryDir
+                ?: throw IllegalStateException("FireflyClient: reactContext unavailable")
+
+            val absolute = File(nativeLibDir, "libfirefly.so")
+            if (!absolute.exists()) {
+                throw IllegalStateException(
+                    "FireflyClient: libfirefly.so not found at ${absolute.absolutePath}. " +
+                    "Did the host app rebuild after the @fireflydb/expo install?"
+                )
+            }
+            absolute.absolutePath.removeSuffix(".so")
+        }
+
+        Function("getEntryPoint") {
+            "sqlite3_firefly_init"
+        }
+
+        // Register a libfirefly change listener against the SQLite database
+        // file at `path`. The native side dispatches every encoded RowState
+        // batch to JS via the "FireflyChange" event. Returns the JS-visible
+        // listener id.
+        Function("addChangeListener") { path: String ->
+            val swiftId = nextSwiftId.getAndIncrement()
+
+            // Capture the swiftId so the dispatcher knows which JS-side
+            // listener to attribute the event to.
+            val jniHandle = FireflyJniBridge.register { blob ->
+                this@FireflyClientModule.sendEvent(
+                    "FireflyChange",
+                    mapOf(
+                        "id" to swiftId.toDouble(),
+                        "blob" to blob,
+                    ),
+                )
+            }
+
+            val rustId = FireflyJniBridge.nativeRegister(path, jniHandle)
+            if (rustId == 0L) {
+                FireflyJniBridge.unregister(jniHandle)
+                throw IllegalStateException(
+                    "firefly_listener_register rejected path '$path' " +
+                    "(in-memory DB or invalid path?)"
+                )
+            }
+            listeners[swiftId] = jniHandle
+            // JS sees a Number; Long fits below 2^53 in any realistic session.
+            swiftId.toDouble()
+        }
+
+        Function("removeChangeListener") { handle: Double ->
+            val swiftId = handle.toLong()
+            val jniHandle = listeners.remove(swiftId) ?: return@Function
+            // Stop libfirefly dispatch first (via shared C++ registry),
+            // then drop the JVM-side lambda. Both lookups are tolerant
+            // of stale fires.
+            FireflyJniBridge.nativeUnregister(jniHandle)
+            FireflyJniBridge.unregister(jniHandle)
+        }
+
+        OnDestroy {
+            // Best-effort cleanup if the module is being torn down (hot
+            // reload, app shutdown). Drop every still-registered listener.
+            val pending = listeners.toMap()
+            listeners.clear()
+            for ((_, jniHandle) in pending) {
+                FireflyJniBridge.nativeUnregister(jniHandle)
+                FireflyJniBridge.unregister(jniHandle)
+            }
+        }
+    }
+}

package/android/src/main/kotlin/com/fireflydb/expo/FireflyJniBridge.kt

@@ -0,0 +1,58 @@
+package com.fireflydb.expo
+
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * JVM-side counterpart to libfirefly_jni.so. Holds a static dispatch
+ * table so the JNI thread (where the cross-platform listener registry
+ * fires its dispatcher on libfirefly's writer-thread callback) has a
+ * stable, lookup-by-handle path back into Kotlin.
+ *
+ * The shared C++ registry at `packages/expo/cpp/firefly_listener.cpp`
+ * owns the libfirefly C-ABI lifetime and the integer-handle dispatch.
+ * `nativeRegister`/`nativeUnregister` delegate to that registry; the
+ * `dispatch(handle, blob)` static is the JVM half — JNI calls it on
+ * fire, we look up the handle and invoke the registered Kotlin lambda.
+ *
+ * Stale fires after `unregister` are silent no-ops via lookup miss in
+ * BOTH this Kotlin table AND the shared C++ registry, which is how we
+ * honor the libfirefly contract that user_data outlive
+ * `firefly_remove_change_listener`.
+ */
+internal object FireflyJniBridge {
+    init {
+        // Pulls in libfirefly_jni.so AND its link-time dependency
+        // libfirefly.so. Subsequent SQLite `loadExtension` calls on the
+        // same .so are idempotent; dlopen returns the same handle.
+        System.loadLibrary("firefly_jni")
+    }
+
+    private val listeners = ConcurrentHashMap<Long, (ByteArray) -> Unit>()
+    private val nextHandle = AtomicLong(1)
+
+    /** Register a Kotlin callback against a fresh handle. */
+    fun register(callback: (ByteArray) -> Unit): Long {
+        val handle = nextHandle.getAndIncrement()
+        listeners[handle] = callback
+        return handle
+    }
+
+    /** Stop dispatching to the lambda registered under `handle`. */
+    fun unregister(handle: Long) {
+        listeners.remove(handle)
+    }
+
+    /**
+     * Called from `firefly_jni.cpp` on the SQLite writer thread.
+     * Lookup-and-fire is intentionally cheap; the lambda usually just
+     * forwards via `sendEvent` and returns.
+     */
+    @JvmStatic
+    fun dispatch(handle: Long, blob: ByteArray) {
+        listeners[handle]?.invoke(blob)
+    }
+
+    external fun nativeRegister(path: String, handle: Long): Long
+    external fun nativeUnregister(handle: Long)
+}

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["ios", "android"],
+  "ios": {
+    "modules": ["FireflyClientModule"]
+  },
+  "android": {
+    "modules": ["com.fireflydb.expo.FireflyClientModule"]
+  }
+}

package/ios/Firefly.xcframework/Info.plist

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>AvailableLibraries</key>
+	<array>
+		<dict>
+			<key>BinaryPath</key>
+			<string>Firefly.framework/Firefly</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64</string>
+			<key>LibraryPath</key>
+			<string>Firefly.framework</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+		</dict>
+		<dict>
+			<key>BinaryPath</key>
+			<string>Firefly.framework/Firefly</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64_x86_64-simulator</string>
+			<key>LibraryPath</key>
+			<string>Firefly.framework</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+				<string>x86_64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
+		</dict>
+	</array>
+	<key>CFBundlePackageType</key>
+	<string>XFWK</string>
+	<key>XCFrameworkFormatVersion</key>
+	<string>1.0</string>
+</dict>
+</plist>