@fireflydb/expo-driver 0.0.6

package/ios/Firefly.xcframework/ios-arm64/Firefly.framework/Info.plist

@@ -0,0 +1,30 @@
+<?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>CFBundleDevelopmentRegion</key>
+    <string>en</string>
+    <key>CFBundleExecutable</key>
+    <string>Firefly</string>
+    <key>CFBundleIdentifier</key>
+    <string>com.fireflydb.firefly</string>
+    <key>CFBundleInfoDictionaryVersion</key>
+    <string>6.0</string>
+    <key>CFBundleName</key>
+    <string>Firefly</string>
+    <key>CFBundlePackageType</key>
+    <string>FMWK</string>
+    <key>CFBundleShortVersionString</key>
+    <string>1.0</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+    <key>CFBundleSupportedPlatforms</key>
+    <array>
+        <string>iPhoneOS</string>
+    </array>
+    <key>DTPlatformName</key>
+    <string>iphoneos</string>
+    <key>MinimumOSVersion</key>
+    <string>15.1</string>
+</dict>
+</plist>

package/ios/Firefly.xcframework/ios-arm64_x86_64-simulator/Firefly.framework/Info.plist

@@ -0,0 +1,30 @@
+<?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>CFBundleDevelopmentRegion</key>
+    <string>en</string>
+    <key>CFBundleExecutable</key>
+    <string>Firefly</string>
+    <key>CFBundleIdentifier</key>
+    <string>com.fireflydb.firefly</string>
+    <key>CFBundleInfoDictionaryVersion</key>
+    <string>6.0</string>
+    <key>CFBundleName</key>
+    <string>Firefly</string>
+    <key>CFBundlePackageType</key>
+    <string>FMWK</string>
+    <key>CFBundleShortVersionString</key>
+    <string>1.0</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+    <key>CFBundleSupportedPlatforms</key>
+    <array>
+        <string>iPhoneSimulator</string>
+    </array>
+    <key>DTPlatformName</key>
+    <string>iphonesimulator</string>
+    <key>MinimumOSVersion</key>
+    <string>15.1</string>
+</dict>
+</plist>

package/ios/FireflyClient.podspec

@@ -0,0 +1,33 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'FireflyClient'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.license        = 'MIT'
+  s.author         = { 'FireflyDB' => 'noreply@example.com' }
+  s.homepage       = 'https://github.com/fireflydb/fireflydb'
+  s.platforms      = { :ios => '15.1' }
+  s.swift_version  = '5.9'
+  s.source         = { :git => 'https://github.com/fireflydb/fireflydb.git' }
+
+  s.dependency 'ExpoModulesCore'
+  s.dependency 'ExpoSQLite'
+
+  s.source_files = ['*.swift', '_shared/*.{cpp,h}']
+
+  # Firefly.xcframework wraps a proper Firefly.framework for each iOS slice
+  # (device-arm64 and simulator-universal). CocoaPods + Xcode embed the right
+  # framework into <App>.app/Frameworks/Firefly.framework/Firefly and re-sign
+  # at archive time. See packages/expo/scripts/build-libfirefly.sh.
+  s.vendored_frameworks = 'Firefly.xcframework'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE'              => 'YES',
+    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17',
+    'CLANG_CXX_LIBRARY'           => 'libc++',
+    'OTHER_CPLUSPLUSFLAGS'        => '-fvisibility=hidden'
+  }
+end

package/ios/FireflyClientModule.swift

@@ -0,0 +1,193 @@
+import ExpoModulesCore
+import Foundation
+
+// MARK: - Shared C++ listener registry bindings
+//
+// Listener registration goes through the cross-platform registry in
+// `cpp/firefly_listener.{h,cpp}` (linked into this pod via the _shared
+// symlink configured in FireflyClient.podspec). The registry owns the
+// libfirefly C-ABI lifetime so the iOS side only has to forward blobs
+// to JS.
+//
+// We use an `Int64` handle as the stable identifier between Swift and
+// the C++ registry. The dispatcher receives that handle on every fire
+// and looks up the live module reference in `swiftRegistry` below; a
+// lookup miss after `removeChangeListener` is the documented "stale
+// fire" path and a silent no-op — this is how we honor the libfirefly
+// contract requirement that user_data outlive
+// `firefly_remove_change_listener` calls without freeing any heap
+// object the C-side might dereference.
+
+private typealias FireflyDispatchFn = @convention(c) (
+  Int64, UnsafePointer<UInt8>?, Int
+) -> Void
+
+@_silgen_name("firefly_listener_register")
+private func firefly_listener_register(
+  _ path: UnsafePointer<CChar>?,
+  _ handle: Int64,
+  _ dispatch: FireflyDispatchFn?
+) -> UInt64
+
+@_silgen_name("firefly_listener_unregister")
+private func firefly_listener_unregister(_ handle: Int64)
+
+// MARK: - Swift-side dispatch table
+//
+// The C++ thunk hands us only the integer handle. We keep a static
+// `[Int64: WeakModule]` so a callback can find the right Expo module
+// instance to fire `sendEvent` on. The map entry is just a weak ref +
+// bookkeeping — there's no heap object whose deallocation could race
+// with an in-flight fire. Hot-reload re-instantiates the module: the
+// new instance registers fresh handles and the old (gone) entries
+// drain out as the C++ registry unregisters them on `OnDestroy`.
+
+private final class WeakModule {
+  weak var module: FireflyClientModule?
+  init(_ module: FireflyClientModule) { self.module = module }
+}
+
+private let swiftRegistryLock = NSLock()
+private var swiftRegistry: [Int64: WeakModule] = [:]
+
+private let fireflyDispatch: FireflyDispatchFn = { handle, blobPtr, blobLen in
+  guard let blobPtr = blobPtr else { return }
+
+  swiftRegistryLock.lock()
+  let weakBox = swiftRegistry[handle]
+  swiftRegistryLock.unlock()
+
+  guard let module = weakBox?.module else { return }
+
+  // Copy bytes — the buffer is only valid for the duration of this call.
+  let blob = Data(bytes: blobPtr, count: blobLen)
+  // sendEvent is safe to call from any thread; ExpoModulesCore marshals
+  // onto the JS thread internally.
+  module.sendEvent("FireflyChange", [
+    "id": NSNumber(value: handle),
+    "blob": blob,
+  ])
+}
+
+private let nextHandleLock = NSLock()
+private var nextHandleCounter: Int64 = 1
+private func mintHandle() -> Int64 {
+  nextHandleLock.lock()
+  defer { nextHandleLock.unlock() }
+  let h = nextHandleCounter
+  nextHandleCounter += 1
+  return h
+}
+
+public class FireflyClientModule: Module {
+  // Set of handles registered against this module instance. Used on
+  // teardown to unregister everything still in flight.
+  private var liveHandles: Set<Int64> = []
+  private let liveHandlesLock = NSLock()
+
+  public func definition() -> ModuleDefinition {
+    Name("FireflyClient")
+
+    Events("FireflyChange")
+
+    Function("getLibraryPath") { () -> String in
+      // Firefly.framework is embedded by Xcode into <App>.app/Frameworks/
+      // Firefly.framework/Firefly (the binary has no extension since that's
+      // the standard framework layout). We return the path to that binary.
+      //
+      // SQLite's sqlite3_load_extension auto-appends ".dylib" when the file
+      // at the given path doesn't exist; since the framework binary DOES
+      // exist at this exact path, dlopen opens it directly without any
+      // suffix mangling.
+      let frameworkBinary = Bundle.main.bundleURL
+        .appendingPathComponent("Frameworks/Firefly.framework/Firefly")
+        .path
+      if FileManager.default.fileExists(atPath: frameworkBinary) {
+        return frameworkBinary
+      }
+      throw NSError(
+        domain: "FireflyClient",
+        code: 1,
+        userInfo: [NSLocalizedDescriptionKey: "Firefly.framework not found at \(frameworkBinary). Did the host app rebuild after pod install?"]
+      )
+    }
+
+    Function("getEntryPoint") { () -> String in
+      return "sqlite3_firefly_init"
+    }
+
+    Constants([
+      "entryPoint": "sqlite3_firefly_init"
+    ])
+
+    // Register a change listener against the SQLite database file at
+    // `path`. The shared C++ registry tracks the rust-side listener id;
+    // we just hand it a freshly-minted handle and a weak ref to this
+    // module. Throws if the registry rejects (in-memory DB, bad path).
+    Function("addChangeListener") { (path: String) -> Double in
+      let handle = mintHandle()
+
+      swiftRegistryLock.lock()
+      swiftRegistry[handle] = WeakModule(self)
+      swiftRegistryLock.unlock()
+
+      let rustId: UInt64 = path.withCString { cstr in
+        firefly_listener_register(cstr, handle, fireflyDispatch)
+      }
+      if rustId == 0 {
+        swiftRegistryLock.lock()
+        swiftRegistry.removeValue(forKey: handle)
+        swiftRegistryLock.unlock()
+        throw NSError(
+          domain: "FireflyClient",
+          code: 2,
+          userInfo: [NSLocalizedDescriptionKey: "firefly_listener_register rejected path '\(path)' (in-memory DB or invalid path?)"]
+        )
+      }
+
+      self.liveHandlesLock.lock()
+      self.liveHandles.insert(handle)
+      self.liveHandlesLock.unlock()
+
+      // Return as Double so JS gets a regular Number. handle stays well
+      // below 2^53 in any realistic session lifespan.
+      return Double(handle)
+    }
+
+    Function("removeChangeListener") { (handleDouble: Double) -> Void in
+      let handle = Int64(handleDouble)
+
+      self.liveHandlesLock.lock()
+      let wasLive = self.liveHandles.remove(handle) != nil
+      self.liveHandlesLock.unlock()
+      guard wasLive else { return }
+
+      // Tell the C++ registry to drop the entry first; this also calls
+      // `firefly_remove_change_listener`. Any in-flight fire that
+      // arrived before we erased will dispatch with a stale module
+      // weak-ref check; arrivals after the erase silently no-op via
+      // lookup miss in the C++ registry.
+      firefly_listener_unregister(handle)
+
+      swiftRegistryLock.lock()
+      swiftRegistry.removeValue(forKey: handle)
+      swiftRegistryLock.unlock()
+    }
+
+    OnDestroy {
+      // Best-effort cleanup if the module is being torn down (e.g. during
+      // hot reload). Removes every still-registered listener.
+      self.liveHandlesLock.lock()
+      let pending = self.liveHandles
+      self.liveHandles.removeAll()
+      self.liveHandlesLock.unlock()
+
+      for handle in pending {
+        firefly_listener_unregister(handle)
+        swiftRegistryLock.lock()
+        swiftRegistry.removeValue(forKey: handle)
+        swiftRegistryLock.unlock()
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@fireflydb/expo-driver",
+  "version": "0.0.6",
+  "description": "Expo native module + drivers for FireflyDB. Bundles libfirefly and wires it through expo-sqlite, expo-secure-store, and React Native WebSocket.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "ios",
+    "android/build.gradle",
+    "android/src",
+    "expo-module.config.json",
+    "scripts/build-libfirefly.sh"
+  ],
+  "dependencies": {
+    "@fireflydb/core": "0.0.6"
+  },
+  "peerDependencies": {
+    "expo": ">=53.0.0",
+    "expo-crypto": ">=14.0.0",
+    "expo-modules-core": ">=2.0.0",
+    "expo-secure-store": ">=14.0.0",
+    "expo-sqlite": ">=15.0.0",
+    "react-native": ">=0.76.0"
+  },
+  "devDependencies": {
+    "expo": "^55.0.0",
+    "expo-crypto": "^55.0.0",
+    "expo-modules-core": "^55.0.0",
+    "expo-secure-store": "^55.0.0",
+    "expo-sqlite": "^55.0.0",
+    "react": "^19.2.0",
+    "react-native": "^0.83.6",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "expo",
+    "expo-module",
+    "sqlite",
+    "crdt",
+    "fireflydb"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build:libfirefly": "bash scripts/build-libfirefly.sh",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/scripts/build-libfirefly.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+#
+# Cross-compile libfirefly for iOS (fat dylib) and Android (jniLibs).
+#
+# Outputs:
+#   ios/libfirefly.dylib                                   (fat: arm64 device + arm64-sim + x86_64-sim)
+#   android/src/main/jniLibs/{arm64-v8a,armeabi-v7a,x86_64,x86}/libfirefly.so
+#
+# Usage:
+#   bash scripts/build-libfirefly.sh         # both platforms
+#   bash scripts/build-libfirefly.sh ios     # iOS only
+#   bash scripts/build-libfirefly.sh android # Android only
+#
+# Requires:
+#   - rustup with iOS targets (auto-installed if missing)
+#   - Xcode + xcodebuild + lipo (for iOS)
+#   - cargo-ndk + Android NDK r27+ (for Android, auto-installed if missing)
+#
+# Source recipes ported from:
+#   /Users/maxencehenneron/Documents/Projects/Appsent/Firefly/scripts/build-ios.sh
+#   /Users/maxencehenneron/Documents/Projects/Appsent/Firefly/Makefile (ios-* / android-* targets)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PKG_DIR="$(dirname "$SCRIPT_DIR")"
+SDK_DIR="$(cd "$PKG_DIR/../.." && pwd)"
+REPO_ROOT="$(cd "$SDK_DIR/../.." && pwd)"
+# core/ is part of a Rust workspace at REPO_ROOT, so cargo emits to
+# $REPO_ROOT/target, not $REPO_ROOT/core/target.
+CORE_DIR="$REPO_ROOT/core"
+CARGO_TARGET_DIR="$REPO_ROOT/target"
+
+IOS_XCF_OUT="$PKG_DIR/ios/Firefly.xcframework"
+IOS_FRAMEWORK_NAME="Firefly"
+IOS_BUNDLE_ID="com.fireflydb.firefly"
+IOS_DEPLOYMENT_TARGET="15.1"
+ANDROID_JNI_OUT="$PKG_DIR/android/src/main/jniLibs"
+
+IOS_TARGETS=(
+  "aarch64-apple-ios"
+  "aarch64-apple-ios-sim"
+  "x86_64-apple-ios"
+)
+
+# (rust-target, android-abi)
+ANDROID_TARGETS=(
+  "aarch64-linux-android arm64-v8a"
+  "armv7-linux-androideabi armeabi-v7a"
+  "x86_64-linux-android x86_64"
+  "i686-linux-android x86"
+)
+
+CARGO_FEATURES="--no-default-features --features loadable_extension"
+
+log() { printf '\033[1;34m[build-libfirefly]\033[0m %s\n' "$*"; }
+err() { printf '\033[1;31m[build-libfirefly]\033[0m %s\n' "$*" >&2; }
+
+ensure_rustup_target() {
+  local target="$1"
+  if ! rustup target list --installed | grep -q "^${target}$"; then
+    log "installing rust target: $target"
+    rustup target add "$target"
+  fi
+}
+
+build_ios() {
+  command -v rustup >/dev/null || { err "rustup not installed"; exit 1; }
+  command -v xcodebuild >/dev/null || { err "xcodebuild not installed"; exit 1; }
+  command -v lipo >/dev/null || { err "lipo not installed"; exit 1; }
+
+  log "iOS: ensuring rust targets installed"
+  for target in "${IOS_TARGETS[@]}"; do
+    ensure_rustup_target "$target"
+  done
+
+  for target in "${IOS_TARGETS[@]}"; do
+    log "iOS: building $target"
+    (cd "$CORE_DIR" && cargo build --release -p firefly --target "$target" $CARGO_FEATURES)
+  done
+
+  # Build the cargo dylibs (already done above). We then wrap each slice's
+  # dylib in a proper Firefly.framework bundle and ship those inside an
+  # XCFramework. This is the canonical Apple distribution shape and the only
+  # one CocoaPods accepts for dynamic linking via vendored_frameworks.
+  #
+  # Resulting layout:
+  #   Firefly.xcframework/
+  #     ios-arm64/Firefly.framework/{Firefly,Info.plist}
+  #     ios-arm64_x86_64-simulator/Firefly.framework/{Firefly,Info.plist}
+  local stage device_fw sim_fw sim_universal_dylib
+  stage="$(mktemp -d)"
+  device_fw="$stage/device/${IOS_FRAMEWORK_NAME}.framework"
+  sim_fw="$stage/sim/${IOS_FRAMEWORK_NAME}.framework"
+  sim_universal_dylib="$stage/sim-universal-libfirefly.dylib"
+
+  log "iOS: lipo simulator slices (arm64-sim + x86_64)"
+  lipo -create \
+    "$CARGO_TARGET_DIR/aarch64-apple-ios-sim/release/libfirefly.dylib" \
+    "$CARGO_TARGET_DIR/x86_64-apple-ios/release/libfirefly.dylib" \
+    -output "$sim_universal_dylib"
+
+  ios_make_framework "$device_fw" \
+    "$CARGO_TARGET_DIR/aarch64-apple-ios/release/libfirefly.dylib" \
+    "iPhoneOS" "iphoneos"
+  ios_make_framework "$sim_fw" \
+    "$sim_universal_dylib" \
+    "iPhoneSimulator" "iphonesimulator"
+
+  log "iOS: assembling Firefly.xcframework"
+  rm -rf "$IOS_XCF_OUT"
+  mkdir -p "$(dirname "$IOS_XCF_OUT")"
+  xcodebuild -create-xcframework \
+    -framework "$device_fw" \
+    -framework "$sim_fw" \
+    -output "$IOS_XCF_OUT" >/dev/null
+
+  # Clean up artifacts from earlier strategies (fat dylib + two-dylib-resource).
+  rm -f "$PKG_DIR/ios/libfirefly.dylib" \
+        "$PKG_DIR/ios/libfirefly-device.dylib" \
+        "$PKG_DIR/ios/libfirefly-sim.dylib"
+
+  log "iOS: verifying sqlite3_firefly_init export in both slices"
+  for slice in "$IOS_XCF_OUT"/*/${IOS_FRAMEWORK_NAME}.framework/${IOS_FRAMEWORK_NAME}; do
+    if ! nm -gU "$slice" 2>/dev/null | grep -q "_sqlite3_firefly_init"; then
+      err "iOS: sqlite3_firefly_init not exported in $slice"
+      exit 1
+    fi
+  done
+  log "iOS: build complete -> $IOS_XCF_OUT"
+}
+
+# Build a single Firefly.framework wrapping a Mach-O dylib. Apple's framework
+# layout for iOS is flat (binary + Info.plist at the framework's root, no
+# Versions/ symlink dance like macOS frameworks).
+ios_make_framework() {
+  local fw_path="$1"
+  local source_dylib="$2"
+  local supported_platform="$3"  # iPhoneOS or iPhoneSimulator
+  local platform_name="$4"       # iphoneos or iphonesimulator
+
+  rm -rf "$fw_path"
+  mkdir -p "$fw_path"
+
+  # The binary inside a framework is named exactly like the framework, with
+  # no extension. The dylib's install_name must use @rpath so the embedded
+  # copy resolves at runtime.
+  cp "$source_dylib" "$fw_path/$IOS_FRAMEWORK_NAME"
+  install_name_tool -id "@rpath/${IOS_FRAMEWORK_NAME}.framework/${IOS_FRAMEWORK_NAME}" \
+    "$fw_path/$IOS_FRAMEWORK_NAME"
+
+  cat > "$fw_path/Info.plist" <<PLIST
+<?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>CFBundleDevelopmentRegion</key>
+    <string>en</string>
+    <key>CFBundleExecutable</key>
+    <string>${IOS_FRAMEWORK_NAME}</string>
+    <key>CFBundleIdentifier</key>
+    <string>${IOS_BUNDLE_ID}</string>
+    <key>CFBundleInfoDictionaryVersion</key>
+    <string>6.0</string>
+    <key>CFBundleName</key>
+    <string>${IOS_FRAMEWORK_NAME}</string>
+    <key>CFBundlePackageType</key>
+    <string>FMWK</string>
+    <key>CFBundleShortVersionString</key>
+    <string>1.0</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+    <key>CFBundleSupportedPlatforms</key>
+    <array>
+        <string>${supported_platform}</string>
+    </array>
+    <key>DTPlatformName</key>
+    <string>${platform_name}</string>
+    <key>MinimumOSVersion</key>
+    <string>${IOS_DEPLOYMENT_TARGET}</string>
+</dict>
+</plist>
+PLIST
+}
+
+build_android() {
+  command -v rustup >/dev/null || { err "rustup not installed"; exit 1; }
+  if ! command -v cargo-ndk >/dev/null; then
+    log "android: installing cargo-ndk"
+    cargo install cargo-ndk
+  fi
+
+  log "android: ensuring rust targets installed"
+  for entry in "${ANDROID_TARGETS[@]}"; do
+    local rust_target="${entry%% *}"
+    ensure_rustup_target "$rust_target"
+  done
+
+  for entry in "${ANDROID_TARGETS[@]}"; do
+    local rust_target="${entry%% *}"
+    local abi="${entry##* }"
+    local out_dir="$ANDROID_JNI_OUT/$abi"
+    log "android: building $rust_target -> $abi"
+    mkdir -p "$out_dir"
+    (cd "$CORE_DIR" && cargo ndk --target "$rust_target" --platform 24 -- \
+      build --release -p firefly $CARGO_FEATURES)
+    cp "$CARGO_TARGET_DIR/$rust_target/release/libfirefly.so" "$out_dir/libfirefly.so"
+  done
+
+  log "android: build complete; .so files at $ANDROID_JNI_OUT"
+}
+
+main() {
+  local mode="${1:-all}"
+  case "$mode" in
+    ios)     build_ios ;;
+    android) build_android ;;
+    all)     build_ios; build_android ;;
+    *)       err "unknown mode: $mode (use ios|android|all)"; exit 1 ;;
+  esac
+  log "done"
+}
+
+main "$@"

package/src/FireflyClientModule.ts

@@ -0,0 +1,83 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+
+/**
+ * Payload of the `FireflyChange` event emitted by the native module each
+ * time libfirefly's notify channel signals a local CRDT-relevant write
+ * for a database that has at least one registered listener.
+ *
+ * `blob` is the raw `encode_rowstates` output — the same shape
+ * `firefly_changes()` returns and `firefly_apply()` consumes — so a
+ * subscription handler can ship it upstream over a WebSocket without
+ * touching it.
+ */
+export interface FireflyChangePayload {
+  /** Listener handle — matches the value returned by `addChangeListener`. */
+  id: number;
+  /** RowState batch encoded by `crate::codec::encode_rowstates`. */
+  blob: Uint8Array;
+}
+
+type FireflyChangeListener = (payload: FireflyChangePayload) => void;
+
+// Self-contained surface for the native module — we only declare the
+// methods we actually call. Expo Modules' `NativeModule` type alias
+// resolves to a constructor type rather than an instance type, so we
+// skip the inheritance and just spell out the EventEmitter methods we
+// use (addListener / removeAllListeners).
+export type FireflyClientNativeModule = {
+  /** Entry-point symbol passed to sqlite3_load_extension. */
+  entryPoint: string;
+  /**
+   * Absolute path to the bundled libfirefly extension, with the platform
+   * suffix stripped (SQLite's sqlite3_load_extension re-appends it). Throws
+   * if the dylib/so isn't found in the host app's bundle.
+   */
+  getLibraryPath(): string;
+  getEntryPoint(): string;
+  /**
+   * Register a native change listener against the SQLite file at `path`.
+   * Every local CRDT-relevant write to that database fires the
+   * `FireflyChange` event with the encoded RowState batch. Returns the
+   * listener id; pass it to `removeChangeListener` to stop receiving
+   * events. Throws on invalid path / in-memory DB.
+   */
+  addChangeListener(path: string): number;
+  /** Unregister a listener previously returned by `addChangeListener`. */
+  removeChangeListener(id: number): void;
+  // EventEmitter surface inherited from NativeModule.
+  addListener(eventName: 'FireflyChange', listener: FireflyChangeListener): EventSubscription;
+  removeAllListeners(eventName: 'FireflyChange'): void;
+};
+
+const FireflyClientModule =
+  requireNativeModule<FireflyClientNativeModule>('FireflyClient');
+
+export default FireflyClientModule;
+
+/**
+ * Subscribe to local CRDT writes against the database file at `path`.
+ * `handler` receives the encoded RowState batch — pass it to your
+ * upstream sender (e.g. `ws.send(blob)`). Returns a subscription whose
+ * `.remove()` tears down both the JS event listener and the native
+ * libfirefly listener.
+ *
+ * Multiple subscribers per path are supported; each gets its own handle
+ * and only sees events tagged with its own id.
+ */
+export function subscribeToChanges(
+  path: string,
+  handler: (blob: Uint8Array) => void,
+): EventSubscription {
+  const id = FireflyClientModule.addChangeListener(path);
+  const sub = FireflyClientModule.addListener('FireflyChange', (event) => {
+    if (event.id === id) handler(event.blob);
+  });
+  // Wrap so callers can `.remove()` both halves with one call.
+  return {
+    remove() {
+      sub.remove();
+      FireflyClientModule.removeChangeListener(id);
+    },
+  } as EventSubscription;
+}