@candypoets/nipworker 0.96.3 → 0.96.5

package/README.md

@@ -1,118 +1,251 @@
 # @candypoets/nipworker
 
-A high-performance Nostr client library that moves everything off the main thread and becomes your entire application state layer.
+NIPWorker is one Nostr SDK across platforms: web, React Native, native integrations, and relay proxy
+tooling. It gives applications the same core model for subscribing, publishing, caching, parsing,
+signing, and tracking relay state without making every app rebuild the protocol layer.
+
+It is highly optimized and opinionated, but still lightweight at the API surface. NIPWorker pushes
+relay I/O, parsing, cache work, and signing into Rust-backed workers or native engines, then exposes
+small TypeScript entry points, framework-agnostic callback helpers, generated FlatBuffers views, and
+signer integration.
+
+It is built for Nostr clients with real feeds and long-lived sessions: social apps, wallets,
+messaging clients, media browsers, dashboards, and any interface that has to keep many relay
+connections active while rendering quickly. If your app only needs to fetch a handful of events,
+`nostr-tools` may be enough. If your app needs a fast reusable Nostr runtime across platforms,
+NIPWorker is meant for that layer.
 
 [![npm version](https://badge.fury.io/js/@candypoets%2Fnipworker.svg)](https://badge.fury.io/js/@candypoets%2Fnipworker)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## What is NIPWorker?
+## Platforms
+
+| Platform | Support | Entry point |
+| --- | --- | --- |
+| Web apps | Supported with Web Workers and Rust WASM. | `@candypoets/nipworker` |
+| Vite apps | Supported; proxy helpers are available for local or server-side relay routing. | `@candypoets/nipworker`, `@candypoets/nipworker/proxy/vite` |
+| React Native | Supported through the native backend. | `@candypoets/nipworker/react-native` |
+| Node.js servers | Supported for relay proxy server utilities; the main client runtime targets app environments. | `@candypoets/nipworker/proxy/server` |
+| Swift/native integrations | Native artifacts and Swift package sources are included in this repository. | `swift/` package sources |
 
-Big, opinionated, and built for speed. FlatBuffers and Web Workers at its core, compiled from Rust to WASM.
+The browser API is framework-agnostic. It can be used from React, Svelte, Vue, Solid, vanilla
+TypeScript, or any environment that can run module workers and WASM.
 
-## Framework Agnostic
+## Install
 
-Works with any frontend. No React dependency, no Svelte stores to learn, no Vue composables. Just hook-like methods with callbacks that you wire to your framework's reactivity however you want.
+```bash
+npm install @candypoets/nipworker flatbuffers
+```
 
-## 4 Dedicated Workers
+Optional peer dependencies:
 
-• **Connections** — Relay connections, WebSocket lifecycle, reconnection backoff. Owns all network I/O.
+- `vite` for browser builds and the Vite relay proxy plugin.
+- `ws` for the relay proxy server.
+- `react-native` for the React Native native backend.
 
-• **Cache** — Stores FlatBuffers in ring buffers in real time and IndexedDB in timeout chunks. No refetching what you already have.
+## Quick Start
 
-• **Parser** — Event validation, signature verification, content parsing. Receives raw JSON from relays, outputs FlatBuffers to your frontend. No JSON.parse on the main thread. Ever.
+```ts
+import { createNostrManager, setManager } from '@candypoets/nipworker';
+import { useSubscription, usePublish, isKind1 } from '@candypoets/nipworker/hooks';
+import { fbArray } from '@candypoets/nipworker/utils';
 
-• **Crypto** — Signing, NIP:04/44 encryption, NIP:46 remote signer sessions, Cashu proof verification.
+const manager = createNostrManager({
+	defaultRelays: ['wss://relay.damus.io', 'wss://nos.lol'],
+	indexerRelays: ['wss://purplepag.es']
+});
 
-Each worker runs in its own Web Worker. The main thread just orchestrates. Heavy work happens in parallel.
+setManager(manager);
 
-## FlatBuffers Instead of JSON
+const stop = useSubscription(
+	'home-feed',
+	[{ kinds: [1], limit: 50, relays: ['wss://relay.damus.io'] }],
+	(message) => {
+		const note = isKind1(message);
+		if (!note) return;
+
+		const blocks = fbArray(note, 'contentBlocks');
+		renderNote(note, blocks);
+	},
+	{ cacheFirst: true, closeOnEose: false }
+);
 
-NIPWorker speaks FlatBuffers end to end. Raw relay messages get parsed once in Rust, then flow through the system as zero-copy binary views. No JSON.parse. No object allocation. No GC pauses on infinite scroll.
+const stopPublish = usePublish(
+	'publish-1',
+	{ kind: 1, content: 'hello nostr', tags: [] },
+	(message) => {
+		console.log(message);
+	},
+	{ defaultRelays: ['wss://relay.damus.io'] }
+);
+```
 
-Your components read directly from FlatBuffers tables. A Kind1 note's content blocks (images, videos, hashtags) arrive pre-parsed. You iterate them with `fbArray()` and render straight from the binary buffer to the DOM. The schema lives from wire to HTML.
+The `use*` functions are framework-agnostic callback helpers. They do not depend on React and can be
+adapted to React, Svelte, Vue, Solid, or plain TypeScript state.
 
-## Apollo-Inspired State Management
+## Backends
 
-Like Apollo Client, NIPWorker IS your store. You do not need Redux, Zustand, or custom state libraries.
+### Browser, Multi-Worker
 
-`useSubscribe` pulls FlatBuffers from the worker pool and feeds your UI directly. Subscriptions accept fetch policies: `cacheFirst` serves from memory immediately if available, `noCache` always bypass the cache and hits the network. You control the speed versus freshness tradeoff per query.
+`createNostrManager()` creates the default browser backend, `NostrManager`. It starts dedicated
+workers for:
 
-`usePublish` sends events and tracks relay acknowledgments. Your entire app state flows through these two hooks. Subscriptions are deduped across components automatically. The library manages the cache, merge logic, and reactive updates.
+- `connections`: WebSocket relay connections and relay lifecycle.
+- `cache`: cached event storage and cache lookups.
+- `parser`: validation, filtering, pipelines, and FlatBuffers output.
+- `crypto`: signing, NIP-04/NIP-44 operations, NIP-46, and proof verification.
 
-## Pipeline Architecture
+Workers communicate with `MessageChannel` ports and FlatBuffers messages.
 
-Events flow through a processing pipeline: verify → dedupe → filter → transform → store. Each subscription configures its own pipeline. The pipeline runs in the Parser worker before FlatBuffers reach your callback.
+### Browser, Single-Worker Engine
 
-## Opinionated by Design
+Pass `engine: true` to use `EngineManager`, which runs the newer engine inside one WASM worker:
 
-NIPWorker enforces outbox model by default. It reads every author's NIP:65 relay list to discover where they publish. The library manages relay discovery and publication strategy for you.
+```ts
+const manager = createNostrManager({ engine: true });
+setManager(manager);
+```
 
-Built for clients that need to render thousands of events without dropping frames.
+This keeps the same public manager and hook surface while reducing worker topology.
 
-## Installation
+### React Native
 
-```bash
-npm install @candypoets/nipworker
-```
+React Native must import from the native entry point. This path avoids browser WASM worker imports
+and talks to the native module instead.
 
-Install the skill for AI assistance:
+```ts
+import { createNostrManager, setManager } from '@candypoets/nipworker/react-native';
 
-```bash
-npx skills add candypoets/skills@nipworker
+setManager(
+	createNostrManager({
+		defaultRelays: ['wss://relay.damus.io'],
+		indexerRelays: ['wss://purplepag.es']
+	})
+);
 ```
 
-## Quick Start
+## Public Entry Points
+
+| Export | Purpose |
+| --- | --- |
+| `@candypoets/nipworker` | Manager factories, manager classes, types, generated FlatBuffers exports. |
+| `@candypoets/nipworker/hooks` | Callback helpers for subscriptions, publishing, signing, and relay status. |
+| `@candypoets/nipworker/utils` | FlatBuffers helpers, type guards, content parsing, NIP-46 QR helper. |
+| `@candypoets/nipworker/proxy` | Browser proxy client. |
+| `@candypoets/nipworker/proxy/server` | Node relay proxy server. |
+| `@candypoets/nipworker/proxy/vite` | Vite plugin for relay proxy integration. |
+| `@candypoets/nipworker/react-native` | React Native native backend. |
+| `@candypoets/nipworker/engine` | Engine entry point. |
+| `@candypoets/nipworker/legacy` | Legacy compatibility entry point. |
+
+## Signers
+
+The manager supports several signer modes:
+
+```ts
+manager.setSigner('privkey', '<hex-secret-key>');
+manager.setNip07();
+manager.setNip46Bunker('<bunker-url>');
+manager.setNip46QR('<nostrconnect-url>');
+manager.setPubkey('<readonly-pubkey>');
+```
 
-```typescript
-import { createNostrManager, setManager } from '@candypoets/nipworker';
-import { useSubscription, usePublish } from '@candypoets/nipworker/hooks';
-import { isKind1, asKind1, fbArray } from '@candypoets/nipworker/utils';
+`useSignEvent(template, callback)` signs through the active signer.
 
-// Create and set the global manager
-const manager = createNostrManager();
-setManager(manager);
+## Subscription Options
+
+Subscriptions accept relay requests plus options for cache behavior, lifecycle, and pipeline control:
 
-// Subscribe to events
-const unsubscribe = useSubscription(
-  'feed_home',
-  [{ kinds: [1], limit: 50, relays: ['wss://relay.example.com'] }],
-  (msg) => {
-    const kind1 = isKind1(msg);
-    if (kind1) {
-      // Access content blocks directly from FlatBuffers view
-      const blocks = fbArray(kind1, 'contentBlocks');
-      renderNote(blocks);
-    }
-  }
+```ts
+useSubscription(
+	'profile',
+	[{ kinds: [0], authors: [pubkey], relays: ['wss://purplepag.es'], limit: 1 }],
+	onMessage,
+	{
+		cacheFirst: true,
+		cacheOnly: false,
+		closeOnEose: true,
+		timeoutMs: 5000,
+		bytesPerEvent: 4096
+	}
 );
 ```
 
+Useful request flags include `cacheFirst`, `noCache`, `closeOnEOSE`, `count`, `maxRelays`, and
+`noOptimize`.
+
+## FlatBuffers and Data Movement
+
+NIPWorker uses FlatBuffers for worker messages and parsed event data. Components can read directly
+from generated FlatBuffers views and use helpers such as `fbArray()` and `fbIterable()` for vector
+fields.
+
+Within JavaScript worker-to-worker paths, buffers are transferred with `postMessage(data,
+[transferable])`. Across the JS/WASM boundary, bytes still have to be copied into or out of WASM
+linear memory. FlatBuffers parsing itself avoids object deserialization and allocation-heavy JSON
+work, but this is not strict end-to-end zero-copy across WASM.
+
+## Development
+
+Prerequisites:
+
+- Node.js 18+
+- Rust 1.70+
+- `wasm-pack`
+- `flatc` for schema generation
+
+Common commands:
+
+```bash
+npm run build          # Build WASM crates, native artifacts, and TypeScript bundle
+npm run build:crates   # Build browser WASM crates only
+npm run build:engine   # Build the single-worker engine WASM
+npm run build:native   # Build Android and iOS native artifacts
+npm run build:types    # Emit TypeScript declarations
+npm test               # Run unit tests
+npm run test:e2e       # Run Playwright tests
+```
+
+Schema generation:
+
+```bash
+npm run flatc          # Rust, TypeScript, and Java generated files
+npm run flatc:rust
+npm run flatc:ts
+npm run flatc:java
+npm run flatc:swift
+```
+
+When editing files in `schemas/`, regenerate the affected FlatBuffers outputs before committing.
+
+## Repository Layout
+
+| Path | Purpose |
+| --- | --- |
+| `src/NostrManager.ts` | Default browser multi-worker manager. |
+| `src/EngineManager.ts` | Browser single-worker engine manager. |
+| `src/react-native.ts` | React Native manager and native bridge. |
+| `src/hooks.ts` | Framework-agnostic callback helpers. |
+| `src/types/index.ts` | Public TypeScript types. |
+| `src/lib/` | Shared TypeScript helpers. |
+| `src/generated/` | Generated TypeScript FlatBuffers code. |
+| `src/engine/` | Single-worker Rust WASM engine. |
+| `crates/connections/` | Browser relay connection WASM crate. |
+| `crates/cache/` | Browser cache WASM crate. |
+| `crates/parser/` | Browser parser WASM crate. |
+| `crates/crypto/` | Browser crypto WASM crate. |
+| `crates/core/` | Shared Rust core/generated code. |
+| `crates/native-ffi/` | Native FFI and React Native platform bindings. |
+| `schemas/` | FlatBuffers schemas. |
+| `swift/` | Swift package for native integration. |
+
 ## Supported NIPs
 
-| NIP | Description | Status |
-|-----|-------------|--------|
-| NIP-01 | Basic Protocol | ✅ Full |
-| NIP-02 | Contact List | ✅ Full |
-| NIP-04 | Encrypted DMs | ✅ Full |
-| NIP-18 | Reposts | ✅ Full |
-| NIP-19 | bech32 Entities | ✅ Full |
-| NIP-25 | Reactions | ✅ Full |
-| NIP-44 | Versioned Encryption | ✅ Full |
-| NIP-46 | Nostr Connect | ✅ Full |
-| NIP-51 | Lists | ✅ Full |
-| NIP-57 | Lightning Zaps | ✅ Full |
-| NIP-60 | Cashu Wallet | ✅ Full |
-| NIP-61 | Nutzaps | ✅ Full |
-| NIP-65 | Relay Lists | ✅ Full |
-
-## Documentation
-
-See [AGENTS.md](AGENTS.md) for detailed architecture documentation.
+The generated schema and parser currently include support for common Nostr event kinds across
+NIP-01, NIP-02, NIP-04, NIP-18, NIP-19, NIP-25, NIP-44, NIP-46, NIP-51, NIP-57, NIP-60, NIP-61, and
+NIP-65, plus newer parsed kinds such as long-form articles, media, polls, live activities, and
+community/group-related events.
 
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.
-
----
-
-Made with ❤️ by [So Tachi](mailto:sotachi@proton.me)

package/crates/native-ffi/README.md

@@ -1,158 +1,21 @@
 # NIPWorker Native FFI
 
-> **Status: Android and iOS builds verified. HarmonyOS is a skeleton.**
-> The TypeScript `createNostrManager()` auto-detects LynxJS and returns `NativeBackend` automatically.
+This crate exposes the Rust `NostrEngine` through a C ABI used by the React Native
+and Swift integrations.
 
-## Overview
+## Build Artifacts
 
-`crates/native-ffi` exposes a C API over the Rust `NostrEngine` so that native mobile applications can reuse the same core logic as the WASM/TypeScript builds.
+- Android: `android/build-android-aar.sh` builds `libnipworker_native_ffi.so`
+  for supported ABIs and places them under `android/src/main/jniLibs`.
+- iOS/macOS: `ios/build-ios.sh` builds `NipworkerNativeFFI.xcframework`.
 
-```c
-void* nipworker_init(void (*callback)(void* userdata, const uint8_t* ptr, size_t len), void* userdata);
-void nipworker_handle_message(void* handle, const uint8_t* ptr, size_t len);
-void nipworker_set_private_key(void* handle, const char* ptr);
-void nipworker_deinit(void* handle);
-void nipworker_free_bytes(uint8_t* ptr, size_t len);
-```
+The React Native package consumes these artifacts from
+`crates/native-ffi/react-native`. The Swift package consumes the iOS
+XCFramework through `swift/Package.swift`.
 
-The TypeScript side provides `NativeBackend` (`src/NativeBackend.ts`) which implements the same public interface as `EngineManager` / `NostrManager` and communicates with the native code through a Lynx module named `NipworkerLynxModule`.
+## API Ownership
 
-## Quick Start for LynxJS Developers
-
-```typescript
-import { createNostrManager, setManager } from '@candypoets/nipworker';
-
-// Auto-detects Lynx native module, WASM engine, or legacy 4-worker
-const backend = createNostrManager();
-setManager(backend);
-```
-
-`createNostrManager()` detects the runtime in this order:
-1. `globalThis.lynx.getNativeModules().NipworkerLynxModule` exists → `NativeBackend`
-2. `config.engine === true` → `EngineManager` (single WASM worker)
-3. Otherwise → `NostrManager` (legacy 4-worker WASM)
-
-## Pre-built Binaries
-
-Every git tag `v*` triggers a [GitHub Actions workflow](../../.github/workflows/native-build.yml) that builds and attaches native libraries to the release:
-
-| Platform | Artifact | Download |
-|----------|----------|----------|
-| **Android** | `nipworker-native-ffi-android-release.aar` | GitHub Release attachments |
-| **iOS** | `nipworker-native-ios.zip` (XCFramework) | GitHub Release attachments |
-| **Linux** | `nipworker-native-linux.zip` | GitHub Release attachments |
-
-## Platform Integration
-
-### Android
-
-The Android artifact is a first-class AAR that contains:
-- `com.candypoets.nipworker.lynx.NipworkerLynxModule`
-- `libnipworker_native_ffi.so` for `arm64-v8a`, `armeabi-v7a`, `x86`, and `x86_64`
-- consumer ProGuard/R8 keep rules for the native module and JNI methods
-
-**Maven integration:**
-```kotlin
-implementation("com.candypoets:nipworker-native-ffi-android:0.96.0")
-```
-
-Register the module in your Sparkling/Lynx setup:
-```kotlin
-"NipworkerLynxModule" to SparklingLynxModuleWrapper(
-    NipworkerLynxModule::class.java,
-    null
-)
-```
-
-The AAR declares Lynx/Sparkling APIs as compile-only. The host app is expected to provide the real Lynx runtime.
-
-**Local monorepo / `node_modules` fallback:**
-```kotlin
-include(":nipworker-native-ffi-android")
-project(":nipworker-native-ffi-android").projectDir =
-    file("../node_modules/@candypoets/nipworker/crates/native-ffi/android")
-```
-
-Then depend on it from the app:
-```kotlin
-implementation(project(":nipworker-native-ffi-android"))
-```
-
-**Local build (requires Android NDK):**
-```bash
-cd crates/native-ffi/android
-./build-android-aar.sh
-./validate-aar.sh
-```
-
-`build-android-aar.sh` builds Rust with `cargo-ndk --release`, copies all four ABI outputs into `src/main/jniLibs`, strips release symbols when `llvm-strip` is available, and runs `assembleRelease`.
-
-### iOS
-
-**Files you need:**
-- `ios/LynxNipworkerModule.mm` — Objective-C++ Lynx module
-- `NipworkerNativeFFI.xcframework` — built from this crate
-
-**Integration steps:**
-1. Download `nipworker-native-ios.zip` from the GitHub Release (or build locally on macOS).
-2. Drag `NipworkerNativeFFI.xcframework` into your Xcode project.
-3. In **Frameworks, Libraries, and Embedded Content**, set it to **Embed & Sign**.
-4. Copy `crates/native-ffi/ios/LynxNipworkerModule.mm` into your Xcode project.
-5. Register the module:
-   ```objc
-   [globalConfig registerModule:NipworkerLynxModule.class];
-   ```
-
-**Local build (requires macOS + Xcode + Rust):**
-```bash
-cd crates/native-ffi/ios
-./build-ios.sh
-```
-
-This produces:
-- `ios/libnipworker_native_ffi.a` — universal static library for CocoaPods
-- `ios/NipworkerNativeFFI.xcframework` — modern XCFramework for manual Xcode integration
-
-### HarmonyOS
-
-* **Language:** ArkTS
-* **Registration:** `this.modules.set('NipworkerLynxModule', { moduleClass: NipworkerLynxModule })`
-* **Linking:** Not yet implemented. ArkTS cannot call C directly without a NAPI/FFI bridge.
-* **Build steps (future):**
-  1. Write a NAPI C++ addon that wraps the 5 C functions above.
-  2. Build the addon into an `.so` shipped with the HarmonyOS app.
-  3. Replace the `TODO` stubs in `LynxNipworkerModule.ets` with actual NAPI calls.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  TypeScript App (LynxJS)                                    │
-│  createNostrManager() → NativeBackend                       │
-│         │                                                   │
-│         ▼                                                   │
-│  ┌─────────────────────────────────────┐                   │
-│  │ NativeBackend.ts                    │                   │
-│  │  calls lynx.getNativeModules()...   │                   │
-│  └─────────────────────────────────────┘                   │
-│         │                                                   │
-│         ▼                                                   │
-│  ┌─────────────────────────────────────┐                   │
-│  │ Platform wrapper                    │                   │
-│  │  Android: Kotlin + JNI C bridge     │                   │
-│  │  iOS:     Objective-C++             │                   │
-│  └─────────────────────────────────────┘                   │
-│         │                                                   │
-│         ▼                                                   │
-│  ┌─────────────────────────────────────┐                   │
-│  │ Rust: libnipworker_native_ffi.so/.a │                   │
-│  │  C ABI → NostrEngine orchestrator   │                   │
-│  └─────────────────────────────────────┘                   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Known limitations
-
-* NIP-07 (browser extension) is not applicable in native mobile contexts and will warn at runtime.
-* NIP-46 (remote signer) is declared as a skeleton; full proxy-signer callbacks from the Rust engine are not yet wired through the C FFI.
-* Wake/visibility messages are not yet forwarded to the native engine.
+Subscription and publish buffers are owned by Rust. Native hosts should create
+subscriptions and publishes through `nipworker_subscribe_message` and
+`nipworker_publish_message`, then read buffer pointers with
+`nipworker_subscription_buffer_ptr` / `nipworker_subscription_buffer_len`.

package/crates/native-ffi/ios/README.md

@@ -1,56 +1,10 @@
-# Nipworker iOS Native Module
+# NIPWorker iOS Native FFI
 
-## Prerequisites
-
-- macOS with Xcode 15+
-- Rust toolchain with Apple targets:
-  ```bash
-  rustup target add aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
-  rustup target add aarch64-apple-darwin x86_64-apple-darwin
-  ```
-
-## Build
-
-From this directory, run the build script:
+Run:
 
 ```bash
 ./build-ios.sh
 ```
 
-This script:
-1. Builds `libnipworker_native_ffi.a` for iOS device, iOS simulator, and macOS
-2. Creates universal simulator and macOS binaries with `lipo`
-3. Creates `NipworkerNativeFFI.xcframework`
-
-By default, the script builds with `IPHONEOS_DEPLOYMENT_TARGET=14.0` and
-`MACOSX_DEPLOYMENT_TARGET=11.0`. Override either environment variable before
-running the script if the consuming package raises its minimum supported OS.
-
-## CocoaPods integration
-
-The `Nipworker.podspec` in this directory references `libnipworker_native_ffi.a`.
-Make sure you ran `./build-ios.sh` first so the static library exists.
-
-In your app's `Podfile`:
-```ruby
-pod 'Nipworker', :path => '../node_modules/@candypoets/nipworker/crates/native-ffi/ios'
-```
-
-Then run:
-```bash
-cd ios && pod install
-```
-
-## Manual Xcode integration (no CocoaPods)
-
-Drag `NipworkerNativeFFI.xcframework` into your Xcode project.
-In **Frameworks, Libraries, and Embedded Content**, set it to **Embed & Sign**.
-Also add `LynxNipworkerModule.h` and `LynxNipworkerModule.mm` to your build target.
-
-## Registration
-
-The module is automatically registered by CocoaPods via the `LynxModule` protocol. No manual `[LynxEnv registerModule:]` call is required unless you prefer to do it in your `AppDelegate`.
-
-```objc
-[globalConfig registerModule:NipworkerLynxModule.class];
-```
+This builds `NipworkerNativeFFI.xcframework` for iOS device, iOS simulator, and
+macOS. React Native iOS and the Swift package both link this XCFramework.

package/crates/native-ffi/react-native/README.md

@@ -14,7 +14,11 @@ setManager(manager);
 
 ## Event Transport
 
-The current legacy React Native bridge receives native events as:
+The React Native entry point installs a JSI byte runtime when possible. Rust owns
+subscription and publish buffers; JS receives a small wake event and drains
+callback packets from native memory.
+
+Fallback bridge events use:
 
 ```ts
 {
@@ -24,11 +28,7 @@ The current legacy React Native bridge receives native events as:
 }
 ```
 
-The JS entry point decodes those events and routes them through the shared
-`NativeBackend`. Outgoing `handleMessage` calls pass `number[]` payloads for the
-same reason: this legacy React Native native module does not expose a direct
-`ArrayBuffer` transport. A future JSI/TurboModule backend should replace the
-array bridge with direct `ArrayBuffer`/native-buffer access.
+The fallback path decodes those events in `ReactNativeManager`.
 
 ## TurboModule Experiment
 
@@ -42,7 +42,8 @@ JSI runtime object:
 
 ```ts
 installByteRuntime(): boolean
-globalThis.__nipworkerReactNativeByteRuntime.handleMessage(bytes: ArrayBuffer): void
+globalThis.__nipworkerReactNativeByteRuntime.subscribe(bytes: ArrayBuffer, subId: string): ArrayBuffer
+globalThis.__nipworkerReactNativeByteRuntime.publish(bytes: ArrayBuffer, publishId: string): ArrayBuffer
 ```
 
 The installer keeps the codegen surface on officially supported types while the

package/crates/native-ffi/react-native/android/build.gradle

@@ -70,4 +70,5 @@ android {
 
 dependencies {
 	implementation 'com.facebook.react:react-android'
+	api 'com.google.flatbuffers:flatbuffers-java:25.2.10'
 }