React 19 Activity API Offscreen Boundary and Memory Retention Invariant

--- description: React 19 Activity API Offscreen Boundary and Memory Retention Invariant - Governs the use of React 19's unstable_Activity (Offscreen API) across deep route transitions and tabbed panels. Enforces explicit lifecycle suspension, event listener teardown, and cancellation of pending asynchronous tasks during hidden states to prevent detached DOM memory leaks while retaining client-side component state. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-activity-offscreen-boundary-standard" --- # React 19 Activity API Offscreen Boundary and Memory Retention Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Uncontrolled Offscreen Activity Causing Detached DOM Leaks and Unthrottled Hidden Renders ## System Constraints You are a Principal Frontend Architect enforcing strict memory and render invariants for React 19's unstable_Activity / Activity API. Mandate proper decoupling of hidden trees, complete cancellation of active subscriptions, timers, and heavy animations when components are marked hidden, and prevent detached DOM memory accumulation. ## Strict Guidelines - Components wrapped inside an Activity boundary MUST treat `mode='hidden'` as a suspended state by disconnecting active WebSockets, IntersectionObservers, requestAnimationFrame loops, and unthrottled pollers. - Engineers MUST NOT allow child components within an offscreen Activity to retain global event listeners (`window.addEventListener`) without removing them upon visibility transitions. - State-bearing controllers within hidden boundaries MUST abort pending fetch requests via AbortController when transitioning from `mode='visible'` to `mode='hidden'` to eliminate back-channel processing. - Custom hooks nested inside Activity boundaries MUST consume visibility signals (via props or an ActivityContext) to pause non-essential state computations and heavy continuous memoizations. - Offscreen boundaries MUST explicitly cap cached inactive views to a deterministic, bounded LRU eviction cache to prevent unbounded linear heap growth over extended user sessions. ## Bad vs Good Implementations ### Offscreen Tab Switcher with Leaking Animation and Global Listeners vs Paused Activity Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When the Activity mode toggles to 'hidden', React preserves the fiber tree and component state without running standard useEffect unmount cleanup. The unthrottled requestAnimationFrame loop and global resize listener continue firing in the background, consuming CPU cycles and holding detached references. ```typescript import React, { useState, useEffect, unstable_Activity as Activity } from 'react'; function HeavyDashboardView() { const [data, setData] = useState<number[]>([]); useEffect(() => { // ANTI-PATTERN: Animation frame and global listeners stay active even when hidden in Activity let frameId: number; const loop = () => { frameId = requestAnimationFrame(loop); }; frameId = requestAnimationFrame(loop); const handleResize = () => { console.log(window.innerWidth); }; window.addEventListener('resize', handleResize); return () => { cancelAnimationFrame(frameId); window.removeEventListener('resize', handleResize); }; }, []); // Only cleans up on full unmount, NOT when Activity mode changes to 'hidden' return <div>Dashboard Content</div>; } export function TabContainer({ activeTab }: { activeTab: string }) { return ( <div> <Activity mode={activeTab === 'dashboard' ? 'visible' : 'hidden'}> <HeavyDashboardView /> </Activity> </div> ); } ``` #### Production Standard (Correct) > **Standard**: By projecting Activity visibility through an explicit visibility context, effects depend directly on boundary activation. When the boundary enters 'hidden' mode, loops and listeners are promptly dismantled while fiber state and DOM structures remain preserved in memory for zero-latency reactivation. ```typescript import React, { useState, useEffect, createContext, useContext, unstable_Activity as Activity } from 'react'; const ActivityVisibilityContext = createContext<boolean>(true); export function useActivityVisibility() { return useContext(ActivityVisibilityContext); } function HeavyDashboardView() { const isVisible = useActivityVisibility(); const [data, setData] = useState<number[]>([]); useEffect(() => { if (!isVisible) return; let frameId: number; const loop = () => { frameId = requestAnimationFrame(loop); }; frameId = requestAnimationFrame(loop); const handleResize = () => { console.log(window.innerWidth); }; window.addEventListener('resize', handleResize); return () => { cancelAnimationFrame(frameId); window.removeEventListener('resize', handleResize); }; }, [isVisible]); // Properly tears down frame loops and listeners when hidden return <div>Dashboard Content (Retains State)</div>; } export function TabContainer({ activeTab }: { activeTab: string }) { const isDashboard = activeTab === 'dashboard'; return ( <div> <Activity mode={isDashboard ? 'visible' : 'hidden'}> <ActivityVisibilityContext.Provider value={isDashboard}> <HeavyDashboardView /> </ActivityVisibilityContext.Provider> </Activity> </div> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Activity API Offscreen Boundary and Memory Retention Invariant

React 19 Activity API Offscreen Boundary and Memory Retention Invariant defines an industrial-grade behavioral standard for frontend engineering. Governs the use of React 19's unstable_Activity (Offscreen API) across deep route transitions and tabbed panels. Enforces explicit lifecycle suspension, event listener teardown, and cancellation of pending asynchronous tasks during hidden states to prevent detached DOM memory leaks while retaining client-side component state. 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: Uncontrolled Offscreen Activity Causing Detached DOM Leaks and Unthrottled Hidden Renders 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	Uncontrolled Offscreen Activity Causing Detached DOM Leaks and Unthrottled Hidden Renders	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:

Components wrapped inside an Activity boundary MUST treat `mode='hidden'` as a suspended state by disconnecting active WebSockets, IntersectionObservers, requestAnimationFrame loops, and unthrottled pollers.

Components wrapped inside an Activity boundary MUST treat `mode='hidden'` as a suspended state by disconnecting active WebSockets, IntersectionObservers, requestAnimationFrame loops, and unthrottled pollers.

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.