React 19 Activity WebGL/WebGPU Context Suspension & Resource Teardown Invariant

--- description: React 19 Activity WebGL/WebGPU Context Suspension & Resource Teardown Invariant - Enforces proactive suspension of WebGL/WebGPU render loops and transient GPU memory deallocation when component subtrees transition into hidden React 19 Activity boundaries. Prevents host OS VRAM exhaustion, hardware context loss (webglcontextlost), and GPU thread starvation during background navigation. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-activity-webgl-context-suspension" --- # React 19 Activity WebGL/WebGPU Context Suspension & Resource Teardown Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Active WebGL/WebGPU Contexts and Render Loops Inside Hidden React 19 Activity Subtrees ## System Constraints You are a Principal Software Architect enforcing WebGL/WebGPU lifecycle invariants in React 19 applications. React 19 introduces the Activity component (formerly Offscreen), which preserves component state in memory while detaching views. You must mandate that all WebGL, WebGPU, Three.js, and Canvas render loops proactively suspend execution and release transient GPU memory allocations (textures, framebuffers, compute buffers) whenever their containing Activity subtree transitions to hidden. Failure to suspend these resources exhausts platform context limits (typically 8–16 concurrent contexts per domain) and induces catastrophic context loss across the entire application. ## Strict Guidelines - Engineers MUST NOT rely on component unmount lifecycle cleanup (standard useEffect return) for GPU resource disposal when components may be encapsulated by React 19 `<Activity>` boundaries. - Engineers MUST ALWAYS hook into the visibility state of the enclosing Activity boundary to explicitly cancel active `requestAnimationFrame` loops when `mode === 'hidden'`. - Engineers MUST purge transient textures, render targets, and large vertex/compute buffers to CPU-side cache when an Activity subtree is hidden, releasing VRAM back to the system. - Engineers MUST register explicit `webglcontextlost` and `webglcontextrestored` event handlers to guarantee graceful degradation if background context eviction occurs. - Code SHOULD utilize a unified GPU context registry or visibility provider that automatically throttles or halts Canvas draw calls for offscreen Activity trees. - Components NEVER execute WebGL or WebGPU draw calls (`gl.drawArrays`, `gl.drawElements`, `device.queue.submit`) while detached or marked hidden in an Activity container. ## Bad vs Good Implementations ### WebGL Canvas within React 19 Activity Lifecycle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When wrapped in React 19's `<Activity mode="hidden">`, the component does not unmount. Its `useEffect` cleanup hook never executes. The render loop continuously triggers `requestAnimationFrame` offscreen, consuming GPU/CPU cycles and retaining a 4K texture in VRAM, which eventually forces mobile/desktop browsers to kill the WebGL context across the application. ```typescript import React, { useEffect, useRef } from 'react'; interface CanvasProps { isActive: boolean; } export const SceneCanvas: React.FC<CanvasProps> = () => { const canvasRef = useRef<HTMLCanvasElement | null>(null); // BUG: useEffect cleanup only fires when component unmounts entirely. // In React 19 <Activity mode="hidden">, the component stays mounted in memory. // The rAF loop continues spinning and heavy textures remain allocated in VRAM. useEffect(() => { const canvas = canvasRef.current; if (!canvas) return; const gl = canvas.getContext('webgl2'); if (!gl) return; let animationFrameId: number; const texture = gl.createTexture(); // Heavy 4K texture allocation gl.bindTexture(gl.TEXTURE_2D, texture); gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 4096, 4096, 0, gl.RGBA, gl.UNSIGNED_BYTE, null); const render = () => { gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); // Render pipeline... animationFrameId = requestAnimationFrame(render); }; render(); return () => { cancelAnimationFrame(animationFrameId); gl.deleteTexture(texture); }; }, []); return <canvas ref={canvasRef} />; }; ``` #### Production Standard (Correct) > **Standard**: The component subscribes to `ActivityVisibilityContext` (reflecting React 19 `<Activity mode="visible" | "hidden">`). When hidden, it immediately halts `requestAnimationFrame` and purges the heavy 4K VRAM texture. When the Activity becomes visible again, textures and render loops are restored on demand, while preserving component DOM identity and local React state. ```typescript import React, { useEffect, useRef, createContext, useContext } from 'react'; // Context provided by enclosing React 19 Activity boundary wrapper export const ActivityVisibilityContext = createContext<boolean>(true); export const SceneCanvas: React.FC = () => { const canvasRef = useRef<HTMLCanvasElement | null>(null); const isVisible = useContext(ActivityVisibilityContext); const glRef = useRef<WebGL2RenderingContext | null>(null); const textureRef = useRef<WebGLTexture | null>(null); const rafIdRef = useRef<number | null>(null); // Handle Context Loss Resiliency useEffect(() => { const canvas = canvasRef.current; if (!canvas) return; const handleContextLost = (e: Event) => { e.preventDefault(); if (rafIdRef.current) cancelAnimationFrame(rafIdRef.current); textureRef.current = null; }; const handleContextRestored = () => { // Reinitialize base state when context recovers }; canvas.addEventListener('webglcontextlost', handleContextLost, false); canvas.addEventListener('webglcontextrestored', handleContextRestored, false); return () => { canvas.removeEventListener('webglcontextlost', handleContextLost); canvas.removeEventListener('webglcontextrestored', handleContextRestored); }; }, []); // React 19 Activity-Aware GPU Resource and Loop Lifecycle useEffect(() => { const canvas = canvasRef.current; if (!canvas) return; if (!isVisible) { // 1. Proactively suspend RAF render loop if (rafIdRef.current !== null) { cancelAnimationFrame(rafIdRef.current); rafIdRef.current = null; } // 2. Evict transient heavy allocations from VRAM during hidden activity state const gl = glRef.current; if (gl && textureRef.current) { gl.deleteTexture(textureRef.current); textureRef.current = null; } return; } // Subtree is visible: allocate or restore resources const gl = glRef.current ?? canvas.getContext('webgl2'); if (!gl || gl.isContextLost()) return; glRef.current = gl; if (!textureRef.current) { const texture = gl.createTexture(); gl.bindTexture(gl.TEXTURE_2D, texture); gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 4096, 4096, 0, gl.RGBA, gl.UNSIGNED_BYTE, null); textureRef.current = texture; } const render = () => { gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT); // Render pipeline... rafIdRef.current = requestAnimationFrame(render); }; rafIdRef.current = requestAnimationFrame(render); return () => { if (rafIdRef.current !== null) { cancelAnimationFrame(rafIdRef.current); rafIdRef.current = null; } }; }, [isVisible]); return <canvas ref={canvasRef} />; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Activity WebGL/WebGPU Context Suspension & Resource Teardown Invariant

React 19 Activity WebGL/WebGPU Context Suspension & Resource Teardown Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces proactive suspension of WebGL/WebGPU render loops and transient GPU memory deallocation when component subtrees transition into hidden React 19 Activity boundaries. Prevents host OS VRAM exhaustion, hardware context loss (webglcontextlost), and GPU thread starvation during background navigation. 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 Active WebGL/WebGPU Contexts and Render Loops Inside Hidden React 19 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	Leaking Active WebGL/WebGPU Contexts and Render Loops Inside Hidden React 19 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 NOT rely on component unmount lifecycle cleanup (standard useEffect return) for GPU resource disposal when components may be encapsulated by React 19 `<Activity>` boundaries.

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.