React Native 0.76 Bridgeless Fabric C++ Shadow-Tree Synchronization Standard

--- description: React Native 0.76 Bridgeless Fabric C++ Shadow-Tree Synchronization Standard - Enforces strict mutation semantics and non-blocking JSI host object boundaries during concurrent asynchronous component mounting in React Native 0.76 Bridgeless architecture. Prohibits synchronous cross-thread UI mutations and unsafe direct ShadowNode access from JS runtimes that trigger C++ mutex deadlocks and layout race conditions in Fabric's commit lifecycle. Mandates state updates through the React scheduler and C++ StateUpdate pipelines to guarantee thread-safe layout trees. globs: **/*.{ts,tsx,cpp,h,mm} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-bridgeless-fabric-shadow-tree-sync" --- # React Native 0.76 Bridgeless Fabric C++ Shadow-Tree Synchronization Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Synchronous JSI layout mutations and unsafe ShadowNode lock inversion during concurrent component mounting ## System Constraints You are a Principal Software Architect enforcing React Native 0.76+ Bridgeless Fabric C++ Shadow-Tree Synchronization Standard. In React Native 0.76, Bridgeless mode executes JavaScript on a dedicated runtime thread while Fabric handles UI mounting, C++ ShadowTree calculation, and Yoga layout mutations asynchronously across multiple background and UI threads. You must ruthlessly identify and eliminate synchronous JSI calls that attempt to directly modify the native view hierarchy, unsafe cross-thread mutex acquisition that causes lock inversions with the Fabric UIManager commit lock, and unbatched direct component state mutations during concurrent transitions. Mandate the use of asynchronous C++ ShadowNode clones, React 18/19 startTransition primitives, and thread-safe JSI HostFunction boundaries. ## Strict Guidelines - Engineers MUST ALWAYS schedule layout-affecting state transitions within startTransition or batched updates to allow Fabric's C++ ShadowTree commit pipeline to resolve concurrently without blocking the main UI thread. - Engineers MUST NOT invoke synchronous JSI host methods that query or mutate UIManager layout metrics during an active component mount or layout phase, as this causes UI thread and JS thread mutex deadlocks. - Custom Fabric C++ ComponentDescriptors MUST ALWAYS use `cloneNode()` with immutable state structs when mutating ShadowNode properties rather than mutating node attributes in-place or holding raw references to ShadowNode pointers. - Native TurboModules and JSI HostFunctions MUST NEVER acquire native UI locks synchronously from the JS runtime thread while emitting events or updating ShadowNode state. - Components MUST NOT use legacy `measure()`, `measureInWindow()`, or synchronous `findNodeHandle` operations over JSI; components MUST use `onLayout` or asynchronous `UIManager.measure` with decoupled completion callbacks. - C++ custom view managers MUST execute shadow-tree revisions strictly via `UIManager::dispatchBatch()` or `StateUpdate` mechanisms provided by `ConcreteComponentDescriptor` to avoid race conditions with Yoga tree generation. ## Bad vs Good Implementations ### Asynchronous Concurrent Component Measurement vs Synchronous JSI Layout Block #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing native tags synchronously via legacy findNodeHandle and executing a synchronous JSI host function during useLayoutEffect forces the JavaScript thread to block on the native UI thread mutex, causing an immediate deadlock if Fabric's C++ commit pipeline is concurrently traversing the Yoga ShadowTree. ```typescript import React, { useLayoutEffect, useRef } from 'react'; import { View, findNodeHandle, NativeModules } from 'react-native'; export const ConcurrentWidget = ({ dynamicHeight }: { dynamicHeight: number }) => { const viewRef = useRef<View>(null); useLayoutEffect(() => { // ANTI-PATTERN: Synchronous JSI lookup and imperative layout lock during Fabric mount const tag = findNodeHandle(viewRef.current); if (tag) { // Blocking synchronous JSI call to native module acquiring UI thread lock (global as any).__turboModuleProxy('CustomLayoutModule').syncUpdateLayout(tag, dynamicHeight); } }, [dynamicHeight]); return <View ref={viewRef} style={{ height: dynamicHeight }} />; }; ``` #### Production Standard (Correct) > **Standard**: Adheres to the Fabric Bridgeless synchronization standard by delegating layout calculations to the asynchronous onLayout notification pipeline and wrapping subsequent component transitions in startTransition. This prevents JSI thread locking and enables Fabric's C++ ShadowTree manager to commit without mutex contention. ```typescript import React, { useRef, useTransition, useCallback } from 'react'; import { LayoutChangeEvent, View } from 'react-native'; interface ConcurrentWidgetProps { onLayoutComplete?: (layout: { width: number; height: number }) => void; } export const ConcurrentWidget: React.FC<ConcurrentWidgetProps> = ({ onLayoutComplete }) => { const [isPending, startTransition] = useTransition(); const lastDimensions = useRef<{ width: number; height: number }>({ width: 0, height: 0 }); const handleLayout = useCallback((event: LayoutChangeEvent) => { const { width, height } = event.nativeEvent.layout; // PROD STANDARD: Defer shadow tree reconciliations asynchronously through React transition scheduler startTransition(() => { lastDimensions.current = { width, height }; if (onLayoutComplete) { onLayoutComplete({ width, height }); } }); }, [onLayoutComplete]); return ( <View collapsable={false} onLayout={handleLayout} style={{ flex: 1 }} /> ); }; ``` ### C++ Custom Fabric ComponentDescriptor Thread-Safe ShadowNode State Update #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Violates Fabric ShadowTree immutability by casting away constness and acquiring a local lock on a raw pointer, causing layout race conditions and deadlocks with Yoga's commit cycle. ```cpp // ANTI-PATTERN: Direct in-place mutation and cross-thread lock acquisition #include <react/renderer/components/view/ViewShadowNode.h> namespace facebook::react { void updateCustomNodeLayout(ShadowNode::Shared node, float newDimension) { // Flaw: Mutating internal state directly bypassing ShadowNode immutability auto* rawNode = const_cast<ShadowNode*>(node.get()); // Flaw: Synchronous wait on UI thread lock from JSI background thread std::lock_guard<std::mutex> lock(rawNode->getMutex()); rawNode->getStyle().dimensions[0] = YogaValue::points(newDimension); } } ``` #### Production Standard (Correct) > **Standard**: Guarantees thread-safe ShadowTree synchronization by dispatching an immutable StateUpdate through the ComponentDescriptor. Fabric automatically schedules and merges the cloned node in the next background commit pass. ```cpp // PROD STANDARD: Immutable clone via StateUpdate pipeline #include <react/renderer/core/ComponentDescriptor.h> #include <react/renderer/core/ShadowNode.h> namespace facebook::react { void updateCustomNodeLayoutSafe( const ComponentDescriptor& descriptor, const ShadowNode& shadowNode, const LayoutConstraints& constraints) { // PROD STANDARD: Immutable State update triggering proper Fabric commit pipeline descriptor.updateState( shadowNode, std::make_shared<ShadowNode::State>( [constraints](const State::Shared& prevState) -> State::Shared { return std::make_shared<ConcreteCustomState>(constraints); })); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native 0.76 Bridgeless Fabric C++ Shadow-Tree Synchronization Standard

React Native 0.76 Bridgeless Fabric C++ Shadow-Tree Synchronization Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict mutation semantics and non-blocking JSI host object boundaries during concurrent asynchronous component mounting in React Native 0.76 Bridgeless architecture. Prohibits synchronous cross-thread UI mutations and unsafe direct ShadowNode access from JS runtimes that trigger C++ mutex deadlocks and layout race conditions in Fabric's commit lifecycle. Mandates state updates through the React scheduler and C++ StateUpdate pipelines to guarantee thread-safe layout trees. 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: Synchronous JSI layout mutations and unsafe ShadowNode lock inversion during concurrent component mounting 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	Synchronous JSI layout mutations and unsafe ShadowNode lock inversion during concurrent component mounting	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 schedule layout-affecting state transitions within startTransition or batched updates to allow Fabric's C++ ShadowTree commit pipeline to resolve concurrently without blocking the main UI thread.

Engineers MUST ALWAYS schedule layout-affecting state transitions within startTransition or batched updates to allow Fabric's C++ ShadowTree commit pipeline to resolve concurrently without blocking the main UI thread.

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.