React Native 0.78 Bridgeless Fabric Thread-Safe Mutation Barrier

--- description: React Native 0.78 Bridgeless Fabric Thread-Safe Mutation Barrier - Enforces deterministic, thread-safe state mutation barriers across JSI boundaries in React Native 0.78 Bridgeless Fabric architecture. Eliminates torn frames, layout desynchronization, and crashes induced by concurrent native gesture driver events mutating React Fiber trees outside the worklet-to-UI shadow tree pipeline. Mandates strict separation between synchronous UI runtime worklet mutations and asynchronous React state commits. globs: src/**/*.{ts,tsx}, packages/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rn-78-bridgeless-fabric-mutation-barrier" --- # React Native 0.78 Bridgeless Fabric Thread-Safe Mutation Barrier > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Mutating React Fiber state synchronously within concurrent native gesture JSI callbacks, triggering shadow tree race conditions and torn frames. ## System Constraints You are a Principal Mobile Architect enforcing thread-safety invariants for React Native 0.78 in Bridgeless and Fabric mode. In Bridgeless Fabric, direct concurrent JSI mutations from gesture handlers or native event streams can bypass the React shadow tree reconciler, causing torn UI renders, race conditions with C++ ShadowNodes, and SIGSEGV memory faults. You must mandate strict transactional isolation: synchronous gesture updates must be confined to the UI Runtime (Worklets/SharedValues), and transitions to React Fiber state must pass through thread-safe batch barriers (startTransition/runOnJS) decoupled from the native gesture frame loop. ## Strict Guidelines - Engineers MUST ALWAYS isolate high-frequency gesture updates to the UI runtime using Reanimated SharedValues or direct Fabric ShadowNode mutations via Worklets. - Engineers MUST NOT invoke React state setters (useState, useReducer, dispatch) synchronously inside high-frequency JSI gesture handler callbacks (e.g., onUpdate). - Engineers MUST wrap any terminal state synchronization back to the React Fiber thread in 'runOnJS' coupled with 'React.startTransition' inside an 'onEnd' or 'onFinalize' boundary. - Components NEVER bridge dynamic native layout dimensions directly to React state during active pan or pinch tracking without an intermediate UI thread value barrier. - Custom Fabric native view components MUST utilize C++ ShadowNode transactional state updates via StateTarget instead of direct asynchronous JavaScript mutations during concurrent layouts. ## Bad vs Good Implementations ### Concurrent Gesture Tracking Synchronization Barrier #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Invoking React state dispatchers synchronously inside the gesture's onUpdate handler crosses the JSI boundary per touch frame. In Bridgeless Fabric, this starves the JS event loop, triggers concurrent Fiber reconciliation alongside C++ ShadowNode layout passes, and produces torn frames or dropouts. ```typescript import React, { useState } from 'react'; import { Gesture, GestureDetector } from 'react-native-gesture-handler'; import Animated from 'react-native-reanimated'; export const TornPanComponent = () => { const [position, setPosition] = useState({ x: 0, y: 0 }); // BAD: Direct JSI bridge crossover on every frame update // Causes torn state and race conditions with Fabric reconciler const gesture = Gesture.Pan().onUpdate((event) => { setPosition({ x: event.translationX, y: event.translationY, }); }); return ( <GestureDetector gesture={gesture}> <Animated.View style={{ transform: [{ translateX: position.x }, { translateY: position.y }] }} /> </GestureDetector> ); }; ``` #### Production Standard (Correct) > **Standard**: The gesture mutations execute exclusively on the UI thread worklet runtime via useSharedValue and useAnimatedStyle. Fiber state is only updated on the terminal boundary (onEnd) via runOnJS wrapped in startTransition, safeguarding the Fabric ShadowNode tree from concurrent desynchronization. ```typescript import React, { startTransition, useState } from 'react'; import { Gesture, GestureDetector } from 'react-native-gesture-handler'; import Animated, { useSharedValue, useAnimatedStyle, runOnJS, } from 'react-native-reanimated'; export const ThreadSafePanComponent = () => { const translateX = useSharedValue(0); const translateY = useSharedValue(0); const [, setCommittedPosition] = useState({ x: 0, y: 0 }); const commitSettledPosition = (x: number, y: number) => { // De-prioritize React Fiber reconciliation to avoid blocking the UI thread startTransition(() => { setCommittedPosition({ x, y }); }); }; // GOOD: High-frequency frame mutations remain isolated on UI runtime; // Fiber reconciliation happens only upon gesture completion via runOnJS. const gesture = Gesture.Pan() .onUpdate((event) => { 'worklet'; translateX.value = event.translationX; translateY.value = event.translationY; }) .onEnd((event) => { 'worklet'; runOnJS(commitSettledPosition)(event.translationX, event.translationY); }); const animatedStyle = useAnimatedStyle(() => ({ transform: [ { translateX: translateX.value }, { translateY: translateY.value }, ], })); return ( <GestureDetector gesture={gesture}> <Animated.View style={animatedStyle} /> </GestureDetector> ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native 0.78 Bridgeless Fabric Thread-Safe Mutation Barrier

React Native 0.78 Bridgeless Fabric Thread-Safe Mutation Barrier defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic, thread-safe state mutation barriers across JSI boundaries in React Native 0.78 Bridgeless Fabric architecture. Eliminates torn frames, layout desynchronization, and crashes induced by concurrent native gesture driver events mutating React Fiber trees outside the worklet-to-UI shadow tree pipeline. Mandates strict separation between synchronous UI runtime worklet mutations and asynchronous React state commits. 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: Mutating React Fiber state synchronously within concurrent native gesture JSI callbacks, triggering shadow tree race conditions and torn frames. 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	Mutating React Fiber state synchronously within concurrent native gesture JSI callbacks, triggering shadow tree race conditions and torn frames.	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 isolate high-frequency gesture updates to the UI runtime using Reanimated SharedValues or direct Fabric ShadowNode mutations via Worklets.

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.