React 19 <Activity> Offscreen State Reconciliation and Subscription Guardrail

--- description: React 19 <Activity> Offscreen State Reconciliation and Subscription Guardrail - Enforces strict memory reclamation and explicit subscription teardowns for subtrees managed by React 19's <Activity> (Offscreen) API. Offscreen subtrees preserve internal state while detaching DOM nodes; failing to decouple long-lived event emitters, timers, WebSocket listeners, and canvas render loops leads to massive memory leaks, phantom state updates, and CPU saturation. globs: src/**/*.{ts,tsx}, apps/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react19-activity-offscreen-reconciliation-guardrail" --- # React 19 <Activity> Offscreen State Reconciliation and Subscription Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Persisting Active Subscriptions and Continuous Render Loops in Deactivated <Activity> Subtrees ## System Constraints You are a Principal Frontend Architect enforcing strict architectural guardrails around React 19 <Activity> (Offscreen) reconciliation. The <Activity mode="hidden"> API retains fiber subtrees in memory while unmounting DOM representations. You must ensure that components nested within or managing <Activity> contexts correctly suspend resource-heavy operations (WebSockets, animation loops, hardware sensors, timers) via layout effects and activity-aware hooks to prevent memory retention bugs and offscreen CPU cycles. ## Strict Guidelines - Engineers MUST ALWAYS suspend hardware timers, ResizeObservers, IntersectionObservers, and requestAnimationFrame loops when <Activity> mode transitions to 'hidden'. - Engineers MUST NOT maintain active WebSocket, EventSource, or broadcast channel subscriptions inside hidden subtrees unless explicitly scoped to a global singleton store designed for offscreen buffering. - Components nested in dynamic activities MUST consume an ActivityContext or explicit `mode` prop to gate side effects using standard lifecycle hooks. - Effects that attach to window or document event listeners MUST tear down immediately upon deactivation to prevent retained detached DOM nodes referenced via closure scopes. - State dispatchers (e.g., `setState`, `dispatch`) MUST NOT execute from background microtasks or async calls if the target fiber subtree is inactive, avoiding wasteful background reconciliation cascades. ## Bad vs Good Implementations ### Subtree Activity-Aware Subscription Teardown and Loop Control #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When <Activity mode='hidden'> hides the subtree, React does not unmount the component state. The WebSocket remains connected, continuously appending messages to state and retaining stale DOM references, creating an offscreen memory leak. ```typescript import React, { useEffect, useState, Activity } from 'react'; interface StreamProps { channelId: string; isActive: boolean; } export const StreamPanel: React.FC<StreamProps> = ({ channelId, isActive }) => { return ( <Activity mode={isActive ? 'visible' : 'hidden'}> <DataStreamViewer channelId={channelId} /> </Activity> ); }; const DataStreamViewer: React.FC<{ channelId: string }> = ({ channelId }) => { const [data, setData] = useState<any[]>([]); // BAD: Effect only runs on mount/unmount and channel change. // In React 19 <Activity mode="hidden">, this component remains mounted in memory. // The WebSocket continues to receive frames and trigger setState for detached DOM elements, // causing CPU burn and unbounded memory growth. useEffect(() => { const ws = new WebSocket(`wss://api.example.com/stream/${channelId}`); ws.onmessage = (event) => { setData((prev) => [...prev, JSON.parse(event.data)]); }; return () => { ws.close(); }; }, [channelId]); return <div>{data.length} messages received</div>; }; ``` #### Production Standard (Correct) > **Standard**: By tying the resource-heavy subscription to the ActivityContext, the WebSocket cleanly disconnects when hidden and re-establishes when restored, preventing offscreen heap bloat and phantom rendering. ```typescript import React, { useEffect, useState, Activity, createContext, useContext } from 'react'; const ActivityContext = createContext<boolean>(true); interface StreamProps { channelId: string; isActive: boolean; } export const StreamPanel: React.FC<StreamProps> = ({ channelId, isActive }) => { return ( <ActivityContext.Provider value={isActive}> <Activity mode={isActive ? 'visible' : 'hidden'}> <DataStreamViewer channelId={channelId} /> </Activity> </ActivityContext.Provider> ); }; const DataStreamViewer: React.FC<{ channelId: string }> = ({ channelId }) => { const isVisible = useContext(ActivityContext); const [data, setData] = useState<any[]>([]); // GOOD: Subscription binds to visibility context. // When mode shifts to 'hidden', the effect cleans up immediately, closing the socket // or detaching listeners to preserve memory and stop redundant CPU cycles. useEffect(() => { if (!isVisible) { return; } const ws = new WebSocket(`wss://api.example.com/stream/${channelId}`); ws.onmessage = (event) => { setData((prev) => [...prev, JSON.parse(event.data)]); }; return () => { ws.close(); }; }, [channelId, isVisible]); return <div>{data.length} messages received</div>; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 <Activity> Offscreen State Reconciliation and Subscription Guardrail

React 19 <Activity> Offscreen State Reconciliation and Subscription Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict memory reclamation and explicit subscription teardowns for subtrees managed by React 19's <Activity> (Offscreen) API. Offscreen subtrees preserve internal state while detaching DOM nodes; failing to decouple long-lived event emitters, timers, WebSocket listeners, and canvas render loops leads to massive memory leaks, phantom state updates, and CPU saturation. 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: Persisting Active Subscriptions and Continuous Render Loops in Deactivated <Activity> Subtrees 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	Persisting Active Subscriptions and Continuous Render Loops in Deactivated <Activity> Subtrees	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 suspend hardware timers, ResizeObservers, IntersectionObservers, and requestAnimationFrame loops when <Activity> mode transitions to 'hidden'.

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.