Tauri 2.0 Webview Compositor GPU Fault Isolation Standard

--- description: Tauri 2.0 Webview Compositor GPU Fault Isolation Standard - Enforces automatic fallback to software rasterization and headless layer degradation upon detecting platform compositor panics or repeated WebGL context losses in Tauri 2.0. Prevents unrecoverable native WebKit/WebView2/Android WebView render process crash loops across desktop and mobile targets. globs: src/**/*.{ts,tsx}, src-tauri/src/**/*.{rs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tauri2-compositor-gpu-fault-isolation-standard" --- # Tauri 2.0 Webview Compositor GPU Fault Isolation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unchecked WebGL Context Loss & Compositor Crashes Causing Native App Crash Loops ## System Constraints You are a Principal Engineer enforcing the Tauri 2.0 Webview Compositor GPU Fault Isolation Standard. You must ensure that all client-side WebGL/WebGPU and platform Webview configurations include deterministic failure isolation, circuit-breaking context restores, and persistent fallback flags for software rasterization before triggering webview reloads. ## Strict Guidelines - Engineers MUST ALWAYS implement circuit-breaking context restoration on 'webglcontextlost' events to avoid infinite re-render loops. - Engineers MUST NOT invoke event.preventDefault() unconditionally on 'webglcontextlost' without checking maximum failure frequency thresholds. - Code SHOULD persist GPU crash counters to persistent client storage (localStorage or Tauri Store) with an automated decay epoch. - Services MUST invoke a native Tauri command to activate platform software rasterizer fallback flags (e.g., --disable-gpu) when context crash thresholds are exceeded. - Components NEVER re-initialize canvas rendering contexts synchronously inside context loss event handlers. ## Bad vs Good Implementations ### GPU Context Loss Watchdog & Software Fallback Trigger #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Unconditionally calling preventDefault() without crash counting triggers rapid context re-acquisition during driver instability, leading to native platform compositor crashes and OS-level termination of the Tauri WebView. ```typescript // Anti-pattern: Blindly re-acquiring GPU context causes infinite crash loops on compositor panic export function setupCanvas(canvas: HTMLCanvasElement): void { canvas.addEventListener('webglcontextlost', (event) => { event.preventDefault(); // Unconditionally prevents default context teardown console.warn('WebGL context lost, attempting immediate restore...'); // Blindly recreating context triggers native WebView render process crash setTimeout(() => { canvas.getContext('webgl2'); }, 100); }); } ``` #### Production Standard (Correct) > **Standard**: Implements an isolated circuit breaker tracking crash frequency within a rolling time window. When failures exceed the threshold, it stops transient re-acquisition and alerts the Tauri native layer to enable software rasterization on subsequent restarts. ```typescript // Production standard: Circuit-breaker pattern with automated fallback flag dispatch import { invoke } from '@tauri-apps/api/core'; interface GpuCrashState { failures: number; lastFailureTimestamp: number; } const CRASH_WINDOW_MS = 60_000; const MAX_CRASH_THRESHOLD = 3; const STORAGE_KEY = 'tauri_gpu_crash_guard'; export function registerGpuFaultGuard(canvas: HTMLCanvasElement): void { canvas.addEventListener('webglcontextlost', async (event: Event) => { const now = Date.now(); const rawState = localStorage.getItem(STORAGE_KEY); const state: GpuCrashState = rawState ? JSON.parse(rawState) : { failures: 0, lastFailureTimestamp: 0 }; const isWithinWindow = now - state.lastFailureTimestamp < CRASH_WINDOW_MS; const failureCount = isWithinWindow ? state.failures + 1 : 1; localStorage.setItem( STORAGE_KEY, JSON.stringify({ failures: failureCount, lastFailureTimestamp: now }) ); if (failureCount >= MAX_CRASH_THRESHOLD) { // Prevent infinite loop: do NOT preventDefault(); activate software rasterization console.error('Excessive GPU context loss detected. Triggering software rasterization fallback.'); await invoke('enable_software_rasterization_fallback', { reason: 'EXCESSIVE_CONTEXT_LOSS' }); return; } // Within acceptable tolerance for transient recovery event.preventDefault(); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 Webview Compositor GPU Fault Isolation Standard

Tauri 2.0 Webview Compositor GPU Fault Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces automatic fallback to software rasterization and headless layer degradation upon detecting platform compositor panics or repeated WebGL context losses in Tauri 2.0. Prevents unrecoverable native WebKit/WebView2/Android WebView render process crash loops across desktop and mobile targets. 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: Unchecked WebGL Context Loss & Compositor Crashes Causing Native App Crash Loops 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	Unchecked WebGL Context Loss & Compositor Crashes Causing Native App Crash Loops	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 implement circuit-breaking context restoration on 'webglcontextlost' events to avoid infinite re-render loops.

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.