React 19 Activity Offscreen Suspense Restoration Standard

--- description: React 19 Activity Offscreen Suspense Restoration Standard - Enforces strict layout measurement isolation and effect lifecycle guards when utilizing React 19 Activity primitives for backgrounded subtrees. Prevents cascading synchronous reflows, ResizeObserver thrash loops, and destructive DOM ref destruction during hidden-to-visible transitions. Guarantees deterministic DOM state restoration, scroll persistence, and stable hydration across concurrent boundaries. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-activity-suspense-restoration-guardrail" --- # React 19 Activity Offscreen Suspense Restoration Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unconditioned Layout Observers and Unstable Effect Lifecycles in Backgrounded Activity Subtrees ## System Constraints You are a Principal Frontend Architect enforcing the React 19 Activity Offscreen Suspense Restoration Standard. Backgrounded subtrees managed via React 19's <Activity> primitive preserve DOM nodes and fiber state while unmounting passive effects. You must strictly mandate that all DOM measurements, ResizeObserver bindings, and Suspense fallback integrations defend against zero-dimension states, prevent synchronous setState cascades during visibility restoration, and avoid layout thrashing. ## Strict Guidelines - Engineers MUST ALWAYS disconnect or pause ResizeObserver, IntersectionObserver, and window resize listeners when a parent Activity boundary transitions to mode='hidden'. - Engineers MUST NOT execute unconditional DOM layout reads (e.g., getBoundingClientRect, offsetWidth, scrollHeight) inside useLayoutEffect without verifying that the root node has non-zero client dimensions and is currently visible. - Code SHOULD guard layout-dependent state updates with a minimum threshold delta to break cyclic layout invalidation loops triggered by concurrent Activity hydration. - Services and hooks MUST encapsulate DOM restoration (scroll positions, cursor offsets, canvas buffers) inside explicit visibility transitions rather than relying on automatic mount-time passive effects. - Components NEVER trigger synchronous setState inside layout effects or observer callbacks when restoring an Activity subtree from hidden to visible mode. ## Bad vs Good Implementations ### Guarded Layout Measurement & Observer Lifecycle in React 19 Activity Subtree #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In React 19, an Activity in 'hidden' mode retains its DOM elements with collapsed display styles. Unconditionally reading getBoundingClientRect or observing resize events without visibility checks forces layout evaluation against empty rects (0x0). Upon reactivation, the rapid succession of layout-effect state dispatches triggers ResizeObserver loop limits, synchronous reflow cycles, and broken restoration states. ```typescript import React, { useLayoutEffect, useState, useRef } from 'react'; interface ContainerProps { children: React.ReactNode; } export const MeasuredSubtree: React.FC<ContainerProps> = ({ children }) => { const ref = useRef<HTMLDivElement>(null); const [width, setWidth] = useState<number>(0); // CRITICAL BUG: When hidden via React 19 <Activity mode="hidden">, // DOM nodes remain with display: none. getBoundingClientRect() returns 0. // This triggers a state update to 0 while hidden, and another synchronous // update when restored to visible, causing layout calculation ping-pong. useLayoutEffect(() => { const observer = new ResizeObserver((entries) => { for (const entry of entries) { setWidth(entry.contentRect.width); } }); if (ref.current) { observer.observe(ref.current); setWidth(ref.current.getBoundingClientRect().width); } return () => observer.disconnect(); }, []); return ( <div ref={ref} data-measured-width={width}> {children} </div> ); }; ``` #### Production Standard (Correct) > **Standard**: The refactored component guards observer initialization against backgrounded mode, explicitly checks for non-zero bounding rects before mutating dimensions, establishes a threshold check (> 1px delta) to avoid sub-pixel layout thrashing, and executes property application concurrently via startTransition and CSS custom properties. ```typescript import React, { useLayoutEffect, useRef, useTransition } from 'react'; interface ContainerProps { children: React.ReactNode; isActive?: boolean; } export const MeasuredSubtree: React.FC<ContainerProps> = ({ children, isActive = true }) => { const ref = useRef<HTMLDivElement>(null); const [, startTransition] = useTransition(); const lastWidthRef = useRef<number>(0); useLayoutEffect(() => { if (!isActive || !ref.current) return; const element = ref.current; const initialRect = element.getBoundingClientRect(); // Prevent zero-dimension state writes while backgrounded if (initialRect.width > 0 && Math.abs(initialRect.width - lastWidthRef.current) > 1) { lastWidthRef.current = initialRect.width; } const observer = new ResizeObserver((entries) => { for (const entry of entries) { const newWidth = entry.contentRect.width; // Guard against zero-width reports from hidden trees and sub-pixel thrash loops if (newWidth > 0 && Math.abs(newWidth - lastWidthRef.current) > 1) { lastWidthRef.current = newWidth; startTransition(() => { element.style.setProperty('--subtree-width', `${newWidth}px`); }); } } }); observer.observe(element); return () => { observer.disconnect(); }; }, [isActive]); return ( <div ref={ref}> {children} </div> ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Activity Offscreen Suspense Restoration Standard

React 19 Activity Offscreen Suspense Restoration Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict layout measurement isolation and effect lifecycle guards when utilizing React 19 Activity primitives for backgrounded subtrees. Prevents cascading synchronous reflows, ResizeObserver thrash loops, and destructive DOM ref destruction during hidden-to-visible transitions. Guarantees deterministic DOM state restoration, scroll persistence, and stable hydration across concurrent boundaries. 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: Unconditioned Layout Observers and Unstable Effect Lifecycles in Backgrounded 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	Unconditioned Layout Observers and Unstable Effect Lifecycles in Backgrounded 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 disconnect or pause ResizeObserver, IntersectionObserver, and window resize listeners when a parent Activity boundary transitions to mode='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.