React 19 Activity WebGL Context Lifecycle and Resource Preservation Guardrail

--- description: React 19 Activity WebGL Context Lifecycle and Resource Preservation Guardrail - Mandates explicit WebGL context preservation, tick loop suspension, and resource lifecycle management when wrapping Three.js, Babylon.js, or raw WebGL renderers inside React 19 `<Activity>` boundaries. Components hidden via the Activity API remain mounted in memory with DOM attachment preserved or detached into an offscreen state, necessitating immediate RAF cancellation, buffer preservation, and idempotent context restoration upon visibility reactivation. globs: src/**/*.{ts,tsx}, components/**/*.{ts,tsx}, features/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react19-activity-webgl-context-preservation-boundary" --- # React 19 Activity WebGL Context Lifecycle and Resource Preservation Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded RAF loops and naive canvas unmount cleansers during React 19 Activity state transitions ## System Constraints You are a Principal Frontend Architect enforcing strict memory and hardware-acceleration invariants under React 19's `<Activity>` (formerly Offscreen) prerender API. Your mandate is to prevent GPU memory exhaustions, context-loss panics, and orphan `requestAnimationFrame` render loops when views transition between 'visible' and 'hidden' states without unmounting. ## Strict Guidelines - Engineers MUST ALWAYS isolate WebGL canvas instances within an explicit context-preservation boundary that intercepts React 19 `Activity` mode transitions. - Engineers MUST pause `requestAnimationFrame` loops, worker dispatchers, and physics tickers synchronously when the enclosing `<Activity mode="hidden">` boundary deactivates visibility. - Engineers MUST NOT rely exclusively on standard component unmount cleanup functions (`useEffect` return callbacks) to release or pause WebGL resources, as hidden Activity subtrees remain mounted. - Engineers MUST preserve GPU textures, geometry buffers, and program caches during Activity suspension while explicitly discarding transient framebuffers to prevent VRAM bloat. - Code MUST listen to the `webglcontextlost` and `webglcontextrestored` events on canvas elements managed inside Activity boundaries, re-initializing lost shader programs idempotently on restore. - Components NEVER execute GPU draw calls (`gl.drawArrays`, `gl.drawElements`, `renderer.render()`) while an Activity boundary's computed mode evaluates to `hidden`. ## Bad vs Good Implementations ### WebGL Context and Loop Management inside React 19 Activity #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Under React 19's `<Activity mode="hidden">`, effects do not run unmount cleanups in the traditional manner. The `requestAnimationFrame` loop executes continuously in the background, rendering to an offscreen canvas and starving the main thread and GPU of resources while risking context loss due to unbounded unthrottled draw calls. ```typescript import React, { useEffect, useRef } from 'react'; import * as THREE from 'three'; interface CanvasProps { isActive: boolean; } export const BadWebGLView: React.FC<CanvasProps> = ({ isActive }) => { const canvasRef = useRef<HTMLCanvasElement | null>(null); // ANTI-PATTERN: Relies solely on unmount cleanup. // In React 19 <Activity mode="hidden">, this component remains mounted. // The animation frame loop continues running in the background, consuming 100% GPU/CPU. useEffect(() => { if (!canvasRef.current) return; const renderer = new THREE.WebGLRenderer({ canvas: canvasRef.current }); const scene = new THREE.Scene(); const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000); let frameId: number; const animate = () => { frameId = requestAnimationFrame(animate); renderer.render(scene, camera); }; animate(); return () => { cancelAnimationFrame(frameId); renderer.dispose(); }; }, []); return <canvas ref={canvasRef} />; }; ``` #### Production Standard (Correct) > **Standard**: Decouples the WebGL context initialization lifecycle from the React 19 Activity visibility mode. When mode shifts to 'hidden', the animation loop halts cleanly via `cancelAnimationFrame`, preventing GPU utilization and avoiding context thrashing while retaining VRAM state (buffers, textures). Context restoration listeners guard against device loss during background suspension. ```typescript import React, { useEffect, useRef } from 'react'; import * as THREE from 'three'; interface WebGLActivityBoundaryProps { mode: 'visible' | 'hidden'; children?: React.ReactNode; } export const SafeWebGLViewport: React.FC<{ mode: 'visible' | 'hidden' }> = ({ mode }) => { const canvasRef = useRef<HTMLCanvasElement | null>(null); const rendererRef = useRef<THREE.WebGLRenderer | null>(null); const rafIdRef = useRef<number | null>(null); const sceneRef = useRef<THREE.Scene | null>(null); const cameraRef = useRef<THREE.PerspectiveCamera | null>(null); // Initialize Engine & Handle Context Loss Lifecycle useEffect(() => { const canvas = canvasRef.current; if (!canvas) return; const renderer = new THREE.WebGLRenderer({ canvas, powerPreference: 'high-performance', preserveDrawingBuffer: false, }); rendererRef.current = renderer; sceneRef.current = new THREE.Scene(); cameraRef.current = new THREE.PerspectiveCamera(75, canvas.clientWidth / canvas.clientHeight, 0.1, 1000); const handleContextLost = (e: Event) => { e.preventDefault(); if (rafIdRef.current !== null) { cancelAnimationFrame(rafIdRef.current); rafIdRef.current = null; } }; const handleContextRestored = () => { // Recompile shaders and restore static GPU memory renderer.resetState(); }; canvas.addEventListener('webglcontextlost', handleContextLost, false); canvas.addEventListener('webglcontextrestored', handleContextRestored, false); return () => { canvas.removeEventListener('webglcontextlost', handleContextLost); canvas.removeEventListener('webglcontextrestored', handleContextRestored); if (rafIdRef.current !== null) cancelAnimationFrame(rafIdRef.current); renderer.dispose(); rendererRef.current = null; }; }, []); // React 19 Activity Visibility Sync: Throttle loop without destroying GPU context useEffect(() => { if (mode === 'hidden') { if (rafIdRef.current !== null) { cancelAnimationFrame(rafIdRef.current); rafIdRef.current = null; } return; } let running = true; const renderLoop = () => { if (!running || !rendererRef.current || !sceneRef.current || !cameraRef.current) return; rendererRef.current.render(sceneRef.current, cameraRef.current); rafIdRef.current = requestAnimationFrame(renderLoop); }; rafIdRef.current = requestAnimationFrame(renderLoop); return () => { running = false; if (rafIdRef.current !== null) { cancelAnimationFrame(rafIdRef.current); rafIdRef.current = null; } }; }, [mode]); return <canvas ref={canvasRef} style={{ display: mode === 'hidden' ? 'none' : 'block' }} />; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Activity WebGL Context Lifecycle and Resource Preservation Guardrail

React 19 Activity WebGL Context Lifecycle and Resource Preservation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Mandates explicit WebGL context preservation, tick loop suspension, and resource lifecycle management when wrapping Three.js, Babylon.js, or raw WebGL renderers inside React 19 `<Activity>` boundaries. Components hidden via the Activity API remain mounted in memory with DOM attachment preserved or detached into an offscreen state, necessitating immediate RAF cancellation, buffer preservation, and idempotent context restoration upon visibility reactivation. 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: Unbounded RAF loops and naive canvas unmount cleansers during React 19 Activity state transitions 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	Unbounded RAF loops and naive canvas unmount cleansers during React 19 Activity state transitions	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 isolate WebGL canvas instances within an explicit context-preservation boundary that intercepts React 19 `Activity` mode transitions.

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.