Tauri 2.0 Webview Hardware Acceleration Isolation and Surface Composition Boundary

--- description: Tauri 2.0 Webview Hardware Acceleration Isolation and Surface Composition Boundary - Enforces strict process isolation for GPU surface compositing across multi-window Tauri 2.0 mobile and desktop shells. Mandates offscreen rendering pipelines communicate via native cross-process texture primitives or shared memory handles rather than raw UI-thread canvas synchronization, eliminating frame jank and main thread deadlock. globs: src/**/*.{ts,tsx,js,jsx}, src-tauri/src/**/*.{rs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tauri2-gpu-surface-composition-boundary-guardrail" --- # Tauri 2.0 Webview Hardware Acceleration Isolation and Surface Composition Boundary > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: UI-Thread Stalling via Direct Webview Shared Canvas Contexts and Unbuffered Texture Blitting ## System Constraints You are a Principal Systems Engineer enforcing GPU boundary isolation in Tauri 2.0 multi-window applications. You must prevent direct UI-thread canvas synchronization, blocking IPC readbacks (glReadPixels/getImageData), and uninsulated surface sharing across Webview windows. You must strictly mandate native cross-process swapchain handles, hardware-accelerated OffscreenCanvas pipelines, and non-blocking asynchronous zero-copy buffer transfers. ## Strict Guidelines - Engineers MUST ALWAYS isolate heavy WebGL or WebGPU contexts inside dedicated Web Workers utilizing OffscreenCanvas, ensuring zero frame lock on the UI thread. - Engineers MUST NOT marshal canvas pixel buffers or ImageData payloads over standard Tauri JSON IPC channels between windows. - Code SHOULD utilize native OS swapchain primitives (e.g., AHardwareBuffer on Android, IOSurface on macOS/iOS, or DirectComposition handles) exposed via Rust Tauri plugins for cross-window surface composition. - Services MUST route multi-window rendering updates using non-blocking asynchronous event dispatchers without holding lock guards across GPU presentation calls. - Components NEVER execute synchronous pixel readbacks (e.g., gl.readPixels or ctx.getImageData) during animation loops or active surface composition frames. ## Bad vs Good Implementations ### Offscreen Canvas Transfer via Dedicated Worker vs Blocking Main-Thread Buffer Serialization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling gl.readPixels blocks the mobile UI thread until the GPU pipeline flushes. Serializing megabytes of raw RGBA pixel arrays through standard JSON IPC introduces severe garbage collection churn and freezes the window compositor. ```typescript import { invoke } from '@tauri-apps/api/core'; export class ViewportRenderer { private canvas: HTMLCanvasElement; private gl: WebGL2RenderingContext; constructor(canvas: HTMLCanvasElement) { this.canvas = canvas; this.gl = canvas.getContext('webgl2')!; } public renderAndSync(): void { // ANTI-PATTERN: Synchronous GPU readback on the UI thread const pixels = new Uint8Array(this.canvas.width * this.canvas.height * 4); this.gl.readPixels(0, 0, this.canvas.width, this.canvas.height, this.gl.RGBA, this.gl.UNSIGNED_BYTE, pixels); // ANTI-PATTERN: Serializing raw texture frames across the Tauri JSON IPC boundary stalls compositor invoke('sync_surface_frame', { windowLabel: 'auxiliary-window', payload: Array.from(pixels) }); } } ``` #### Production Standard (Correct) > **Standard**: The rendering surface is transferred completely to an OffscreenCanvas running on a separate worker thread. Canvas compositing runs asynchronously from the UI loop, and synchronization targets are referenced via zero-copy native handles rather than marshaled pixel buffers. ```typescript export class ViewportRenderer { private worker: Worker; private offscreenCanvas: OffscreenCanvas; constructor(canvas: HTMLCanvasElement) { // INVARIANT: Transfer render surface execution off the UI thread this.offscreenCanvas = canvas.transferControlToOffscreen(); this.worker = new Worker(new URL('./gpu-compositor.worker.ts', import.meta.url), { type: 'module' }); this.worker.postMessage( { type: 'INIT_SURFACE', canvas: this.offscreenCanvas }, [this.offscreenCanvas] ); } public requestAuxiliarySync(surfaceId: string): void { // INVARIANT: Request GPU swapchain handle exchange via lightweight native ID pointer this.worker.postMessage({ type: 'SYNC_SURFACE_HANDLE', targetSurfaceId: surfaceId }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 Webview Hardware Acceleration Isolation and Surface Composition Boundary

Tauri 2.0 Webview Hardware Acceleration Isolation and Surface Composition Boundary defines an industrial-grade behavioral standard for mobile engineering. Enforces strict process isolation for GPU surface compositing across multi-window Tauri 2.0 mobile and desktop shells. Mandates offscreen rendering pipelines communicate via native cross-process texture primitives or shared memory handles rather than raw UI-thread canvas synchronization, eliminating frame jank and main thread deadlock. 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: UI-Thread Stalling via Direct Webview Shared Canvas Contexts and Unbuffered Texture Blitting 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	UI-Thread Stalling via Direct Webview Shared Canvas Contexts and Unbuffered Texture Blitting	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 heavy WebGL or WebGPU contexts inside dedicated Web Workers utilizing OffscreenCanvas, ensuring zero frame lock on the UI thread.

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.