React Native 0.78 Bridgeless JSI TurboModule Zero-Copy Binary Buffer Standard

--- description: React Native 0.78 Bridgeless JSI TurboModule Zero-Copy Binary Buffer Standard - Enforces strict memory safety and zero-copy binary communication between native C++ runtimes and JavaScript/Hermes in React Native 0.78+ bridgeless architecture. Mandates the use of jsi::ArrayBuffer wrapping direct native allocations or shared memory pools, eliminating JSON/base64 serialization overhead and avoiding cross-runtime heap fragmentation during high-throughput sensor telemetry ingestion. globs: src/**/*.{ts,tsx}, cpp/**/*.{h,cpp}, ios/**/*.{h,mm}, android/src/main/jni/**/*.{h,cpp} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-bridgeless-jsi-zero-copy-buffer-standard" --- # React Native 0.78 Bridgeless JSI TurboModule Zero-Copy Binary Buffer Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Piping Sensor Telemetry Through Serialized Bridges or Managed JavaScript Heap Copies ## System Constraints You are a Principal Mobile Systems Architect enforcing the React Native 0.78 Bridgeless JSI TurboModule Zero-Copy Binary Buffer Standard. You strictly prohibit passing binary telemetry or high-frequency sensor streams as strings, base64, JSON payloads, or dynamic host objects that require marshaling. Mandate explicit memory ownership semantics, pointer validation, and deterministic buffer recycling using C++ jsi::ArrayBuffer wrappers paired with JavaScript typed array views (Float64Array, Uint8Array) to prevent GC thrashing and Hermes heap exhaustion. ## Strict Guidelines - Engineers MUST ALWAYS expose high-throughput native byte streams to JavaScript exclusively through `jsi::ArrayBuffer` instances backed by deterministic native memory or pre-allocated rings. - Engineers MUST NOT convert high-frequency binary telemetry into base64, JSON, or standard JavaScript Arrays/Objects across the TurboModule boundary. - C++ implementations MUST explicitly define buffer lifecycle ownership (e.g., using a custom `MutableBuffer` with a release deleter or static ring buffer) to prevent use-after-free and dangling pointer crashes in Hermes. - TypeScript consumers MUST mount typed views (`Float32Array`, `Float64Array`, `Uint8Array`) directly on the incoming `ArrayBuffer` without intermediate slicing or copying operations. - Native methods handling streams MUST reuse existing allocations or utilize double-buffering rings rather than allocating new heap buffers per incoming telemetry tick. - TypeScript declarations MUST strictly type return values and arguments as `ArrayBuffer` rather than generic `unknown` or `any` to enforce view validation. ## Bad vs Good Implementations ### Consuming High-Frequency Sensor Packets in TypeScript #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Parsing JSON strings or emitting dynamic JavaScript objects at 100Hz+ creates severe Hermes garbage collection pressure, causes micro-stutter on the JS thread, and incurs massive string deserialization CPU overhead. ```typescript // Anti-pattern: Incurring bridge/Hermes deserialization, GC spikes, and payload copying import { NativeModules, DeviceEventEmitter } from 'react-native'; interface SensorPayload { timestamp: number; values: number[]; // Incurs V8/Hermes object heap allocation for every sample } export function subscribeToSensorStream(callback: (data: SensorPayload) => void) { // Anti-pattern: High-frequency JSON/Base64 serialization over native bridge/TurboModule event emitter return DeviceEventEmitter.addListener('onSensorTelemetry', (serializedData: string) => { const parsed: SensorPayload = JSON.parse(serializedData); callback(parsed); }); } ``` #### Production Standard (Correct) > **Standard**: The typed array constructs a direct view over the JSI-provided `ArrayBuffer` without allocating managed heap copies or running JSON deserialization, keeping the Hermes runtime fast and deterministic. ```typescript // Production standard: Direct typed view over raw zero-copy JSI ArrayBuffer import { TurboModuleRegistry } from 'react-native'; interface Spec { getLatestTelemetryBuffer(): ArrayBuffer; subscribeSensorStream(onFrame: (buffer: ArrayBuffer) => void): () => void; } const SensorTurboModule = TurboModuleRegistry.getEnforcing<Spec>('SensorTelemetryModule'); const BYTES_PER_SAMPLE = 32; // [timestamp: float64, accX: float32, accY: float32, accZ: float32, gyroX: float32, gyroY: float32, gyroZ: float32] export function readTelemetryBatch(buffer: ArrayBuffer): { timestamp: number; accel: [number, number, number]; gyro: [number, number, number]; } { // Zero-copy view mapping over native JSI ArrayBuffer const f64View = new Float64Array(buffer, 0, 1); const f32View = new Float32Array(buffer, 8, 6); return { timestamp: f64View[0], accel: [f32View[0], f32View[1], f32View[2]], gyro: [f32View[3], f32View[4], f32View[5]], }; } ``` ### C++ JSI Zero-Copy ArrayBuffer Allocation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Constructing individual JSI values and populating a `jsi::Array` for each sensor tick forces Hermes to create managed JS objects, triggering lock contention and frequent heap fragmentation. ```cpp // Anti-pattern: Converting sensor readings into jsi::Array or jsi::Object instances facebook::jsi::Value getSensorTelemetry(facebook::jsi::Runtime& runtime) { facebook::jsi::Array result(runtime, 6); result.setValueAtIndex(runtime, 0, facebook::jsi::Value(sensorData.accelX)); result.setValueAtIndex(runtime, 1, facebook::jsi::Value(sensorData.accelY)); result.setValueAtIndex(runtime, 2, facebook::jsi::Value(sensorData.accelZ)); result.setValueAtIndex(runtime, 3, facebook::jsi::Value(sensorData.gyroX)); result.setValueAtIndex(runtime, 4, facebook::jsi::Value(sensorData.gyroY)); result.setValueAtIndex(runtime, 5, facebook::jsi::Value(sensorData.gyroZ)); return result; } ``` #### Production Standard (Correct) > **Standard**: Creates a `jsi::ArrayBuffer` backed by a shared `MutableBuffer`. Hermes manages the buffer handle while the native byte payload remains contiguous and accessible without marshalling. ```cpp // Production standard: Exposing contiguous native memory via jsi::ArrayBuffer wrapping a MutableBuffer #include <jsi/jsi.h> #include <memory> struct SensorFrame { double timestamp; float accel[3]; float gyro[3]; }; class NativeBufferWrapper : public facebook::jsi::MutableBuffer { public: explicit NativeBufferWrapper(size_t size) : size_(size), data_(new uint8_t[size]) {} ~NativeBufferWrapper() override { delete[] data_; } size_t size() const override { return size_; } uint8_t* data() override { return data_; } private: size_t size_; uint8_t* data_; }; facebook::jsi::Value getSensorTelemetry(facebook::jsi::Runtime& runtime) { auto buffer = std::make_shared<NativeBufferWrapper>(sizeof(SensorFrame)); auto* frame = reinterpret_cast<SensorFrame*>(buffer->data()); frame->timestamp = getCurrentTimestampNs(); frame->accel[0] = sensorData.accelX; frame->accel[1] = sensorData.accelY; frame->accel[2] = sensorData.accelZ; frame->gyro[0] = sensorData.gyroX; frame->gyro[1] = sensorData.gyroY; frame->gyro[2] = sensorData.gyroZ; return facebook::jsi::ArrayBuffer(runtime, buffer); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native 0.78 Bridgeless JSI TurboModule Zero-Copy Binary Buffer Standard

React Native 0.78 Bridgeless JSI TurboModule Zero-Copy Binary Buffer Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict memory safety and zero-copy binary communication between native C++ runtimes and JavaScript/Hermes in React Native 0.78+ bridgeless architecture. Mandates the use of jsi::ArrayBuffer wrapping direct native allocations or shared memory pools, eliminating JSON/base64 serialization overhead and avoiding cross-runtime heap fragmentation during high-throughput sensor telemetry ingestion. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Piping Sensor Telemetry Through Serialized Bridges or Managed JavaScript Heap Copies Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Piping Sensor Telemetry Through Serialized Bridges or Managed JavaScript Heap Copies	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS expose high-throughput native byte streams to JavaScript exclusively through `jsi

Engineers MUST ALWAYS expose high-throughput native byte streams to JavaScript exclusively through `jsi::ArrayBuffer` instances backed by deterministic native memory or pre-allocated rings.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.