react-native-buffered-blob 1.0.0

package/cpp/BufferedBlobStreamingHostObject.cpp

@@ -0,0 +1,344 @@
+#include "BufferedBlobStreamingHostObject.h"
+#include <ReactCommon/TurboModuleUtils.h>
+#include <cmath>
+#include <string>
+#include <utility>
+
+namespace bufferedblob {
+
+static int safeHandleId(const facebook::jsi::Value& val) {
+  double d = val.asNumber();
+  if (std::isnan(d) || std::isinf(d) || d < 0 || d > 2147483647.0) {
+    return -1;  // Invalid handle ID, will be not-found in registry
+  }
+  return static_cast<int>(d);
+}
+
+using namespace facebook;
+
+// --- OwnedMutableBuffer ---
+
+OwnedMutableBuffer::OwnedMutableBuffer(std::vector<uint8_t> data)
+    : data_(std::move(data)) {}
+
+size_t OwnedMutableBuffer::size() const {
+  return data_.size();
+}
+
+uint8_t* OwnedMutableBuffer::data() {
+  return data_.data();
+}
+
+// --- BufferedBlobStreamingHostObject ---
+
+BufferedBlobStreamingHostObject::BufferedBlobStreamingHostObject(
+    jsi::Runtime& runtime,
+    std::shared_ptr<react::CallInvoker> callInvoker,
+    std::shared_ptr<PlatformBridge> bridge)
+    : runtime_(runtime),
+      callInvoker_(std::move(callInvoker)),
+      bridge_(std::move(bridge)),
+      alive_(std::make_shared<std::atomic<bool>>(true)) {}
+
+BufferedBlobStreamingHostObject::~BufferedBlobStreamingHostObject() {
+  *alive_ = false;
+}
+
+std::vector<jsi::PropNameID> BufferedBlobStreamingHostObject::getPropertyNames(
+    jsi::Runtime& rt) {
+  std::vector<jsi::PropNameID> names;
+  names.push_back(jsi::PropNameID::forAscii(rt, "readNextChunk"));
+  names.push_back(jsi::PropNameID::forAscii(rt, "write"));
+  names.push_back(jsi::PropNameID::forAscii(rt, "flush"));
+  names.push_back(jsi::PropNameID::forAscii(rt, "close"));
+  names.push_back(jsi::PropNameID::forAscii(rt, "startDownload"));
+  names.push_back(jsi::PropNameID::forAscii(rt, "cancelDownload"));
+  names.push_back(jsi::PropNameID::forAscii(rt, "getReaderInfo"));
+  names.push_back(jsi::PropNameID::forAscii(rt, "getWriterInfo"));
+  return names;
+}
+
+jsi::Value BufferedBlobStreamingHostObject::get(
+    jsi::Runtime& rt,
+    const jsi::PropNameID& name) {
+  auto propName = name.utf8(rt);
+
+  // --- readNextChunk(handleId): Promise<ArrayBuffer | null> ---
+  if (propName == "readNextChunk") {
+    return jsi::Function::createFromHostFunction(
+        rt, name, 1,
+        [this](jsi::Runtime& rt, const jsi::Value&,
+               const jsi::Value* args, size_t count) -> jsi::Value {
+          if (count < 1) {
+            throw jsi::JSError(rt, "readNextChunk requires 1 argument");
+          }
+          int handleId = safeHandleId(args[0]);
+          auto callInvoker = callInvoker_;
+          auto bridge = bridge_;
+          auto alive = alive_;
+
+          return react::createPromiseAsJSIValue(
+              rt,
+              [handleId, callInvoker, bridge, alive](
+                  jsi::Runtime& rt2,
+                  std::shared_ptr<react::Promise> promise) {
+                bridge->readNextChunk(
+                    handleId,
+                    // onSuccess: data available
+                    [callInvoker, promise, rtPtr = &rt2, alive](std::vector<uint8_t> data) {
+                      callInvoker->invokeAsync(
+                          [promise, rtPtr, data = std::move(data), alive]() mutable {
+                            if (!*alive) return;
+                            auto buffer = std::make_shared<OwnedMutableBuffer>(
+                                std::move(data));
+                            auto arrayBuffer = jsi::ArrayBuffer(
+                                *rtPtr, std::move(buffer));
+                            promise->resolve(std::move(arrayBuffer));
+                          });
+                    },
+                    // onEOF: no more data
+                    [callInvoker, promise, alive]() {
+                      callInvoker->invokeAsync([promise, alive]() {
+                        if (!*alive) return;
+                        promise->resolve(jsi::Value::null());
+                      });
+                    },
+                    // onError
+                    [callInvoker, promise, alive](std::string error) {
+                      callInvoker->invokeAsync(
+                          [promise, error = std::move(error), alive]() {
+                            if (!*alive) return;
+                            promise->reject(error);
+                          });
+                    });
+              });
+        });
+  }
+
+  // --- write(handleId, data): Promise<number> ---
+  if (propName == "write") {
+    return jsi::Function::createFromHostFunction(
+        rt, name, 2,
+        [this](jsi::Runtime& rt, const jsi::Value&,
+               const jsi::Value* args, size_t count) -> jsi::Value {
+          if (count < 2) {
+            throw jsi::JSError(rt, "write requires 2 arguments");
+          }
+          int handleId = safeHandleId(args[0]);
+          auto arrayBuffer =
+              args[1].asObject(rt).getArrayBuffer(rt);
+          auto dataPtr = arrayBuffer.data(rt);
+          auto dataSize = arrayBuffer.size(rt);
+
+          // Copy data since the ArrayBuffer may be GC'd
+          std::vector<uint8_t> dataCopy(dataPtr, dataPtr + dataSize);
+
+          auto callInvoker = callInvoker_;
+          auto bridge = bridge_;
+          auto alive = alive_;
+
+          return react::createPromiseAsJSIValue(
+              rt,
+              [handleId, callInvoker, bridge, alive,
+               dataCopy = std::move(dataCopy)](
+                  jsi::Runtime& rt2,
+                  std::shared_ptr<react::Promise> promise) {
+                bridge->write(
+                    handleId, std::move(dataCopy),
+                    [callInvoker, promise, alive](int bytesWritten) {
+                      callInvoker->invokeAsync(
+                          [promise, bytesWritten, alive]() {
+                            if (!*alive) return;
+                            promise->resolve(jsi::Value(static_cast<double>(bytesWritten)));
+                          });
+                    },
+                    [callInvoker, promise, alive](std::string error) {
+                      callInvoker->invokeAsync(
+                          [promise, error = std::move(error), alive]() {
+                            if (!*alive) return;
+                            promise->reject(error);
+                          });
+                    });
+              });
+        });
+  }
+
+  // --- flush(handleId): Promise<void> ---
+  if (propName == "flush") {
+    return jsi::Function::createFromHostFunction(
+        rt, name, 1,
+        [this](jsi::Runtime& rt, const jsi::Value&,
+               const jsi::Value* args, size_t count) -> jsi::Value {
+          if (count < 1) {
+            throw jsi::JSError(rt, "flush requires 1 argument");
+          }
+          int handleId = safeHandleId(args[0]);
+          auto callInvoker = callInvoker_;
+          auto bridge = bridge_;
+          auto alive = alive_;
+
+          return react::createPromiseAsJSIValue(
+              rt,
+              [handleId, callInvoker, bridge, alive](
+                  jsi::Runtime& rt2,
+                  std::shared_ptr<react::Promise> promise) {
+                bridge->flush(
+                    handleId,
+                    [callInvoker, promise, alive]() {
+                      callInvoker->invokeAsync([promise, alive]() {
+                        if (!*alive) return;
+                        promise->resolve(jsi::Value::undefined());
+                      });
+                    },
+                    [callInvoker, promise, alive](std::string error) {
+                      callInvoker->invokeAsync(
+                          [promise, error = std::move(error), alive]() {
+                            if (!*alive) return;
+                            promise->reject(error);
+                          });
+                    });
+              });
+        });
+  }
+
+  // --- close(handleId): void (synchronous) ---
+  if (propName == "close") {
+    return jsi::Function::createFromHostFunction(
+        rt, name, 1,
+        [this](jsi::Runtime& rt, const jsi::Value&,
+               const jsi::Value* args, size_t count) -> jsi::Value {
+          if (count < 1) {
+            throw jsi::JSError(rt, "close requires 1 argument");
+          }
+          int handleId = safeHandleId(args[0]);
+          bridge_->close(handleId);
+          return jsi::Value::undefined();
+        });
+  }
+
+  // --- startDownload(handleId, onProgress): Promise<void> ---
+  if (propName == "startDownload") {
+    return jsi::Function::createFromHostFunction(
+        rt, name, 2,
+        [this](jsi::Runtime& rt, const jsi::Value&,
+               const jsi::Value* args, size_t count) -> jsi::Value {
+          if (count < 2) {
+            throw jsi::JSError(rt, "startDownload requires 2 arguments");
+          }
+          int handleId = safeHandleId(args[0]);
+          auto progressFn =
+              std::make_shared<jsi::Function>(args[1].asObject(rt).asFunction(rt));
+          auto callInvoker = callInvoker_;
+          auto bridge = bridge_;
+          auto alive = alive_;
+          // Capture runtime pointer for use in progress callback.
+          // Safe because invokeAsync runs on JS thread where runtime is valid.
+          jsi::Runtime* rtPtr = &rt;
+
+          return react::createPromiseAsJSIValue(
+              rt,
+              [handleId, callInvoker, bridge, progressFn, rtPtr, alive](
+                  jsi::Runtime& rt2,
+                  std::shared_ptr<react::Promise> promise) {
+                bridge->startDownload(
+                    handleId,
+                    // onProgress callback - invoke on JS thread
+                    [callInvoker, progressFn, rtPtr, alive](
+                        double bytesDownloaded, double totalBytes,
+                        double progress) {
+                      callInvoker->invokeAsync(
+                          [progressFn, rtPtr, bytesDownloaded, totalBytes,
+                           progress, alive]() {
+                            if (!*alive) return;
+                            progressFn->call(
+                                *rtPtr,
+                                jsi::Value(bytesDownloaded),
+                                jsi::Value(totalBytes),
+                                jsi::Value(progress));
+                          });
+                    },
+                    // onSuccess
+                    [callInvoker, promise, alive]() {
+                      callInvoker->invokeAsync([promise, alive]() {
+                        if (!*alive) return;
+                        promise->resolve(jsi::Value::undefined());
+                      });
+                    },
+                    // onError
+                    [callInvoker, promise, alive](std::string error) {
+                      callInvoker->invokeAsync(
+                          [promise, error = std::move(error), alive]() {
+                            if (!*alive) return;
+                            promise->reject(error);
+                          });
+                    });
+              });
+        });
+  }
+
+  // --- cancelDownload(handleId): void (synchronous) ---
+  if (propName == "cancelDownload") {
+    return jsi::Function::createFromHostFunction(
+        rt, name, 1,
+        [this](jsi::Runtime& rt, const jsi::Value&,
+               const jsi::Value* args, size_t count) -> jsi::Value {
+          if (count < 1) {
+            throw jsi::JSError(rt, "cancelDownload requires 1 argument");
+          }
+          int handleId = safeHandleId(args[0]);
+          bridge_->cancelDownload(handleId);
+          return jsi::Value::undefined();
+        });
+  }
+
+  // --- getReaderInfo(handleId): { fileSize, bytesRead, isEOF } (synchronous) ---
+  if (propName == "getReaderInfo") {
+    return jsi::Function::createFromHostFunction(
+        rt, name, 1,
+        [this](jsi::Runtime& rt, const jsi::Value&,
+               const jsi::Value* args, size_t count) -> jsi::Value {
+          if (count < 1) {
+            throw jsi::JSError(rt, "getReaderInfo requires 1 argument");
+          }
+          int handleId = safeHandleId(args[0]);
+          auto info = bridge_->getReaderInfo(handleId);
+          auto obj = jsi::Object(rt);
+          obj.setProperty(rt, "fileSize", info.fileSize);
+          obj.setProperty(rt, "bytesRead", info.bytesRead);
+          obj.setProperty(rt, "isEOF", info.isEOF);
+          return obj;
+        });
+  }
+
+  // --- getWriterInfo(handleId): { bytesWritten } (synchronous) ---
+  if (propName == "getWriterInfo") {
+    return jsi::Function::createFromHostFunction(
+        rt, name, 1,
+        [this](jsi::Runtime& rt, const jsi::Value&,
+               const jsi::Value* args, size_t count) -> jsi::Value {
+          if (count < 1) {
+            throw jsi::JSError(rt, "getWriterInfo requires 1 argument");
+          }
+          int handleId = safeHandleId(args[0]);
+          auto info = bridge_->getWriterInfo(handleId);
+          auto obj = jsi::Object(rt);
+          obj.setProperty(rt, "bytesWritten", info.bytesWritten);
+          return obj;
+        });
+  }
+
+  return jsi::Value::undefined();
+}
+
+void BufferedBlobStreamingHostObject::install(
+    jsi::Runtime& runtime,
+    std::shared_ptr<react::CallInvoker> callInvoker,
+    std::shared_ptr<PlatformBridge> bridge) {
+  auto hostObject = std::make_shared<BufferedBlobStreamingHostObject>(
+      runtime, std::move(callInvoker), std::move(bridge));
+  auto object = jsi::Object::createFromHostObject(runtime, hostObject);
+  runtime.global().setProperty(
+      runtime, "__BufferedBlobStreaming", std::move(object));
+}
+
+} // namespace bufferedblob

package/cpp/BufferedBlobStreamingHostObject.h

@@ -0,0 +1,118 @@
+#pragma once
+
+#include <jsi/jsi.h>
+#include <ReactCommon/CallInvoker.h>
+#include <memory>
+#include <functional>
+#include <vector>
+#include <cstdint>
+
+namespace bufferedblob {
+
+using namespace facebook;
+
+/**
+ * Platform bridge abstraction.
+ * Each platform (Android/iOS) implements this interface to provide
+ * native streaming operations that the JSI HostObject delegates to.
+ */
+struct PlatformBridge {
+  virtual ~PlatformBridge() = default;
+
+  // Reader operations
+  virtual void readNextChunk(
+    int handleId,
+    std::function<void(std::vector<uint8_t>)> onSuccess,
+    std::function<void()> onEOF,
+    std::function<void(std::string)> onError
+  ) = 0;
+
+  // Writer operations
+  virtual void write(
+    int handleId,
+    std::vector<uint8_t> data,
+    std::function<void(int)> onSuccess,
+    std::function<void(std::string)> onError
+  ) = 0;
+
+  virtual void flush(
+    int handleId,
+    std::function<void()> onSuccess,
+    std::function<void(std::string)> onError
+  ) = 0;
+
+  // Close (sync)
+  virtual void close(int handleId) = 0;
+
+  // Download operations
+  virtual void startDownload(
+    int handleId,
+    std::function<void(double, double, double)> onProgress,
+    std::function<void()> onSuccess,
+    std::function<void(std::string)> onError
+  ) = 0;
+
+  virtual void cancelDownload(int handleId) = 0;
+
+  // Reader info (sync)
+  struct ReaderInfo {
+    double fileSize;
+    double bytesRead;
+    bool isEOF;
+  };
+  virtual ReaderInfo getReaderInfo(int handleId) = 0;
+
+  // Writer info (sync)
+  struct WriterInfo {
+    double bytesWritten;
+  };
+  virtual WriterInfo getWriterInfo(int handleId) = 0;
+};
+
+/**
+ * JSI HostObject that exposes streaming operations to JavaScript.
+ * Installed on global.__BufferedBlobStreaming by the install() method.
+ */
+class BufferedBlobStreamingHostObject : public jsi::HostObject {
+public:
+  BufferedBlobStreamingHostObject(
+    jsi::Runtime& runtime,
+    std::shared_ptr<react::CallInvoker> callInvoker,
+    std::shared_ptr<PlatformBridge> bridge
+  );
+
+  ~BufferedBlobStreamingHostObject() override;
+
+  jsi::Value get(jsi::Runtime& rt, const jsi::PropNameID& name) override;
+  std::vector<jsi::PropNameID> getPropertyNames(jsi::Runtime& rt) override;
+
+  /**
+   * Install the HostObject on the given runtime as global.__BufferedBlobStreaming.
+   */
+  static void install(
+    jsi::Runtime& runtime,
+    std::shared_ptr<react::CallInvoker> callInvoker,
+    std::shared_ptr<PlatformBridge> bridge
+  );
+
+private:
+  jsi::Runtime& runtime_;
+  std::shared_ptr<react::CallInvoker> callInvoker_;
+  std::shared_ptr<PlatformBridge> bridge_;
+  std::shared_ptr<std::atomic<bool>> alive_;
+};
+
+/**
+ * MutableBuffer subclass that owns its data for zero-copy ArrayBuffer creation.
+ */
+class OwnedMutableBuffer : public jsi::MutableBuffer {
+public:
+  explicit OwnedMutableBuffer(std::vector<uint8_t> data);
+  size_t size() const override;
+  uint8_t* data() override;
+
+private:
+  std::vector<uint8_t> data_;
+};
+
+} // namespace bufferedblob

package/cpp/CMakeLists.txt

@@ -0,0 +1,49 @@
+cmake_minimum_required(VERSION 3.13)
+project(bufferedblobstreaming)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# When included via app autolinking (REACTNATIVE_MERGED_SO), include the
+# codegen-generated CMakeLists.txt so react_codegen_BufferedBlobSpec is built.
+if(REACTNATIVE_MERGED_SO)
+  set(CODEGEN_JNI_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../android/build/generated/source/codegen/jni")
+  if(EXISTS "${CODEGEN_JNI_DIR}/CMakeLists.txt")
+    add_subdirectory(${CODEGEN_JNI_DIR} codegen_build)
+  endif()
+endif()
+
+add_library(${PROJECT_NAME} SHARED
+  BufferedBlobStreamingHostObject.cpp
+  AndroidPlatformBridge.cpp
+  jni_onload.cpp
+)
+
+target_include_directories(${PROJECT_NAME} PRIVATE
+  ${CMAKE_CURRENT_SOURCE_DIR}
+)
+
+# When included via app autolinking (REACTNATIVE_MERGED_SO), use the merged
+# reactnative/jsi/fbjni aliases set up by ReactNative-application.cmake.
+# When built standalone by the library's build.gradle, use prefab targets.
+if(REACTNATIVE_MERGED_SO)
+  target_link_libraries(${PROJECT_NAME}
+    jsi
+    reactnative
+    fbjni
+    android
+    log
+  )
+else()
+  find_package(ReactAndroid REQUIRED CONFIG)
+  find_package(fbjni REQUIRED CONFIG)
+  target_link_libraries(${PROJECT_NAME}
+    ReactAndroid::jsi
+    ReactAndroid::react_nativemodule_core
+    ReactAndroid::turbomodulejsijni
+    ReactAndroid::reactnativejni
+    fbjni::fbjni
+    android
+    log
+  )
+endif()

package/cpp/jni_onload.cpp

@@ -0,0 +1,32 @@
+#include <fbjni/fbjni.h>
+#include <jsi/jsi.h>
+#include <ReactCommon/CallInvokerHolder.h>
+#include "BufferedBlobStreamingHostObject.h"
+#include "AndroidPlatformBridge.h"
+
+using namespace facebook;
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_bufferedblob_BufferedBlobModule_nativeInstall(
+    JNIEnv* env,
+    jobject thiz,
+    jlong jsiPtr,
+    jobject callInvokerHolder) {
+  auto& runtime = *reinterpret_cast<jsi::Runtime*>(jsiPtr);
+
+  auto callInvokerHolderRef =
+      jni::make_local(reinterpret_cast<react::CallInvokerHolder::javaobject>(
+          callInvokerHolder));
+  auto callInvoker = callInvokerHolderRef->cthis()->getCallInvoker();
+
+  auto bridge = std::make_shared<bufferedblob::AndroidPlatformBridge>(env);
+
+  bufferedblob::BufferedBlobStreamingHostObject::install(
+      runtime, callInvoker, bridge);
+}
+
+JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void*) {
+  return jni::initialize(vm, [] {
+    // No native methods to register via fbjni - we use raw JNI above
+  });
+}

package/ios/AGENTS.md

@@ -0,0 +1,76 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-02-15 -->
+
+# ios/
+
+iOS platform bridge: ObjC++ Turbo Module, Swift implementation, JSI wiring, and handle registry.
+
+## Purpose
+
+Implement BufferedBlob for iOS:
+- **BufferedBlobModule.mm**: ObjC++ Turbo Module bridge; wires JSI HostObject via install()
+- **BufferedBlobModule.swift**: Swift implementation of handle factories, FS operations, hashing with CommonCrypto
+- **BufferedBlobStreamingBridge.h/mm**: IOSPlatformBridge; async dispatch via dispatch_async, NSURLSession downloads
+- **HandleRegistry.swift**: Thread-safe handle storage (NSLock), maps numeric IDs to reader/writer/downloader handles
+- **HandleTypes.swift**: ReaderHandleIOS, WriterHandleIOS, DownloaderHandleIOS classes
+- **BufferedBlob-Bridging-Header.h**: Swift/ObjC++ interop
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `BufferedBlobModule.mm` | RCT_EXPORT_MODULE, RCT_EXPORT_METHOD, install() calls installBufferedBlobStreaming() |
+| `BufferedBlobModule.swift` | Handle factories (openRead, openWrite, createDownload), FS ops, hashFile with CommonCrypto |
+| `BufferedBlobStreamingBridge.h` | IOSPlatformBridge class header; inherits from C++ PlatformBridge |
+| `BufferedBlobStreamingBridge.mm` | IOSPlatformBridge implementation: dispatch_async, NSURLSession, InputStream/OutputStream |
+| `HandleRegistry.swift` | Singleton: register(handle), remove(id), get(id); thread-safe with NSLock |
+| `HandleTypes.swift` | ReaderHandleIOS (InputStream, fileSize, bytesRead), WriterHandleIOS (OutputStream, bytesWritten), DownloaderHandleIOS (URLSessionDataTask, URL) |
+| `BufferedBlob-Bridging-Header.h` | Swift bridging header for ObjC++ classes (C++ PlatformBridge, etc.) |
+
+## For AI Agents
+
+### Working In This Directory
+
+1. **ObjC++ bridge pattern**: BufferedBlobModule.mm exports methods via RCT_EXPORT_METHOD/RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD. Delegates to Swift implementation via _swiftModule.
+2. **Bridged vs. Bridgeless**: install() detects RN 0.74+ bridgeless mode; falls back to RCTBridge.runtime. Both paths supported.
+3. **Handle lifecycle**: Turbo Module returns numeric handle IDs. Platform bridge stores actual handle objects (reader/writer/downloader). Always close handles.
+4. **Async dispatch**: File ops and downloads use `DispatchQueue.global(qos: .userInitiated)` to avoid blocking main thread. Promises resolve on main thread.
+5. **CommonCrypto hashing**: Streams file in 8192-byte chunks; supports SHA256, MD5. No full file load.
+6. **NSURLSession downloads**: Async, supports progress callback, cancellation. Data task delegates to DownloaderHandleIOS.
+
+### Testing Requirements
+
+- **Module loading**: Verify install() succeeds and JSI HostObject is accessible
+- **Handle factories**: Test openRead/openWrite/createDownload with valid/invalid paths
+- **File operations**: Test exists, stat, mkdir, ls, cp, mv, unlink on temp files
+- **Hashing**: Verify SHA256/MD5 output matches known values (use openssl dgst to verify)
+- **Streaming**: Test readNextChunk, write, flush, close; verify file contents
+- **Download**: Test with HTTP server, verify progress callback, verify file written
+- **Cleanup**: Verify handles are released (NSLock does not deadlock, no dangling FileHandles)
+
+### Common Patterns
+
+1. **Create reader**: `openRead(path, bufferSize)` → ReaderHandleIOS(path, bufferSize) → register(handle) → return handleId
+2. **Stream read**: Bridge readNextChunk(handleId) → get handle → read chunk → convert to ArrayBuffer → resolve Promise
+3. **Download with progress**: `createDownload(url, destPath)` → DownloaderHandleIOS → URLSession dataTask → progress callback → finalize
+4. **Error handling**: Catch Foundation errors; wrap in [error localizedDescription]; reject Promise
+
+## Dependencies
+
+### Internal
+- C++ PlatformBridge (abstract interface from cpp/)
+- HandleRegistry, HandleTypes (shared state across ObjC++ and Swift)
+
+### External
+- **React Native** >= 0.76.0
+  - `<React/RCTBridgeModule.h>` — RCT_EXPORT_MODULE, RCT_EXPORT_METHOD
+  - `<React/RCTBridge+Private.h>` — Bridge.runtime, jsCallInvoker
+  - `<ReactCommon/RCTTurboModule.h>` — TurboModule protocol
+  - `<jsi/jsi.h>` — JSI runtime (passed to install())
+- **Apple frameworks**
+  - `Foundation/FileManager` — File operations
+  - `CommonCrypto/CommonDigest.h` — SHA256, MD5 hashing
+  - `Foundation/URLSession` — Downloads
+  - `Foundation/InputStream, OutputStream` — Streaming
+
+<!-- MANUAL: Document CommonCrypto vs. CryptoKit trade-offs, iOS version support (min 12.0+), URLSession configuration -->

package/ios/BufferedBlobModule.h

@@ -0,0 +1,44 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+@class HandleRegistry;
+
+/**
+ * Core BufferedBlob module implementation.
+ * Provides handle factories for readers/writers/downloaders and
+ * common filesystem operations (exists, stat, unlink, mkdir, ls, cp, mv, hash).
+ *
+ * All async FS operations are dispatched to global concurrent queues.
+ * FileManager.default is documented as safe for concurrent use from multiple queues
+ * for basic operations (exists, stat, unlink, mkdir, ls, cp, mv).
+ */
+@interface BufferedBlobModule : NSObject
+
++ (NSString *)moduleName;
++ (BOOL)requiresMainQueueSetup;
+
+- (NSDictionary *)constantsToExport;
+
+// Handle factories
+- (NSNumber *)openRead:(NSString *)path bufferSize:(double)bufferSize;
+- (NSNumber *)openWrite:(NSString *)path append:(BOOL)append;
+- (NSNumber *)createDownload:(NSString *)url destPath:(NSString *)destPath headers:(NSDictionary *)headers;
+- (void)closeHandle:(double)handleId;
+
+// FS operations (async with promise callbacks)
+typedef void (^RCTPromiseResolveBlock)(id _Nullable result);
+typedef void (^RCTPromiseRejectBlock)(NSString * _Nullable code,
+                                      NSString * _Nullable message,
+                                      NSError * _Nullable error);
+
+- (void)exists:(NSString *)path resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject;
+- (void)stat:(NSString *)path resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject;
+- (void)unlink:(NSString *)path resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject;
+- (void)mkdir:(NSString *)path resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject;
+- (void)ls:(NSString *)path resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject;
+- (void)cp:(NSString *)srcPath destPath:(NSString *)destPath resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject;
+- (void)mv:(NSString *)srcPath destPath:(NSString *)destPath resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject;
+- (void)hashFile:(NSString *)path algorithm:(NSString *)algorithm resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject;
+
+@end