React 19 Concurrent Activity Boundary State Preservation Standard

--- description: React 19 Concurrent Activity Boundary State Preservation Standard - Governs state preservation, effect lifecycle invariants, and DOM isolation within React 19 Concurrent Activity boundaries. Enforces idempotent effect cleanups, prevents uncommitted background fiber side-effect leaks, and eliminates state desynchronization during hidden pre-rendering and route transitions. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-concurrent-activity-boundary-preservation" --- # React 19 Concurrent Activity Boundary State Preservation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking background subscriptions or corrupting external state during hidden Activity boundary lifecycles ## System Constraints You are a Principal Frontend Architect enforcing the React 19 Concurrent Activity Boundary State Preservation Standard. You must mandate strict adherence to fiber tree lifecycle guarantees, ensuring that background pre-rendered components (such as those wrapped in React 19 <Activity mode="hidden">) pause active side effects, cleanly sever imperative listeners, and do not mutate external stores or unmounted DOM nodes during background rendering. ## Strict Guidelines - Engineers MUST ALWAYS structure passive effects (useEffect) to be fully idempotent, recognizing that React 19 Activity boundaries tear down effects when hidden and re-run them upon becoming visible without unmounting internal fiber state. - Engineers MUST NOT initiate imperative external network calls, audio/video playback, analytics beacons, or polling loops in components while their Activity tree is hidden. - Components NEVER query or mutate raw DOM nodes via imperative refs or document queries assuming permanent tree placement, as hidden Activity boundaries disconnect layout nodes or mark them inert. - Engineers MUST use useSyncExternalStore with resilient snapshot equality for external store subscriptions to avoid tearing when background fibers evaluate state while hidden. - Services MUST suspend active push pipelines (e.g., WebSockets, WebRTC data channels, sensor observers) when their hosting Activity boundary signals hidden status, resuming cleanly upon re-activation. - Code SHOULD leverage useEffectEvent to encapsulate effect dependencies so that boundary transitions do not trigger spurious re-synchronizations. ## Bad vs Good Implementations ### Handling Subscriptions in React 19 Activity Boundaries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When placed inside a React 19 Activity boundary marked as hidden (such as pre-rendered tab or preserved route), the unmount/remount cycle re-runs effects repeatedly, or if kept active without visibility checks, it continues to mutate document globals and consume network resources for off-screen fibers. ```typescript import React, { useEffect, useState } from 'react'; interface StreamProps { channelId: string; } // ANTI-PATTERN: Direct socket setup assuming mount/unmount is a 1:1 single lifecycle. // In React 19 Activity (mode="hidden"), this keeps active socket connections consuming // bandwidth and firing setMessages in the background fiber without pausing. export const BadChatStream: React.FC<StreamProps> = ({ channelId }) => { const [messages, setMessages] = useState<string[]>([]); useEffect(() => { const socket = new WebSocket(`wss://api.service.internal/channels/${channelId}`); socket.onmessage = (event) => { // Modifies state in an uncommitted or hidden fiber setMessages((prev) => [...prev, event.data]); // Leaks side-effects like DOM notifications while hidden document.title = `New message in ${channelId}`; }; return () => { socket.close(); }; }, [channelId]); return <div>{messages.length} messages</div>; }; ``` #### Production Standard (Correct) > **Standard**: Decouples state storage from fiber mounting via useSyncExternalStore and guards network transport with visibility awareness, ensuring hidden Activity boundaries maintain state snapshots without executing background side-effects or leaking DOM updates. ```typescript import React, { useEffect, useSyncExternalStore } from 'react'; import { channelStore } from './channelStore'; interface StreamProps { channelId: string; isActive?: boolean; // Controlled directly or inferred from Activity context } // PRODUCTION FIX: Bind to an external store via useSyncExternalStore // and control active subscriptions based on visibility state. export const GoodChatStream: React.FC<StreamProps> = ({ channelId, isActive = true }) => { const messages = useSyncExternalStore( (callback) => channelStore.subscribe(channelId, callback), () => channelStore.getSnapshot(channelId), () => [] ); useEffect(() => { if (!isActive) { return; } // Establish active transport only when boundary is visible/active const disconnect = channelStore.connectTransport(channelId); return () => { disconnect(); }; }, [channelId, isActive]); return <div>{messages.length} messages</div>; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Concurrent Activity Boundary State Preservation Standard

React 19 Concurrent Activity Boundary State Preservation Standard defines an industrial-grade behavioral standard for frontend engineering. Governs state preservation, effect lifecycle invariants, and DOM isolation within React 19 Concurrent Activity boundaries. Enforces idempotent effect cleanups, prevents uncommitted background fiber side-effect leaks, and eliminates state desynchronization during hidden pre-rendering and route transitions. 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: Leaking background subscriptions or corrupting external state during hidden Activity boundary lifecycles 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	Leaking background subscriptions or corrupting external state during hidden Activity boundary lifecycles	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 structure passive effects (useEffect) to be fully idempotent, recognizing that React 19 Activity boundaries tear down effects when hidden and re-run them upon becoming visible without unmounting internal fiber state.

Engineers MUST ALWAYS structure passive effects (useEffect) to be fully idempotent, recognizing that React 19 Activity boundaries tear down effects when hidden and re-run them upon becoming visible without unmounting internal fiber state.

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.