Tauri 2.0 Mobile Multi-WebView Memory Pressure Dynamic Eviction Guardrail

--- description: Tauri 2.0 Mobile Multi-WebView Memory Pressure Dynamic Eviction Guardrail - Enforces deterministic lifecycle-aware state hydration and background WKWebView/Android WebView eviction in Tauri 2.0 multi-webview mobile architectures. Prevents aggressive OS watchdog termination (iOS Jetsam/EXC_RESOURCE and Android LMK kill) by intercepting native memory pressure notifications, persisting ephemeral DOM state to IndexedDB/Rust disk stores, and tearing down detached WebViews prior to background suspension. globs: src-tauri/src/**/*.rs, src/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tauri-v2-mobile-multi-webview-memory-eviction" --- # Tauri 2.0 Mobile Multi-WebView Memory Pressure Dynamic Eviction Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Retaining Multiple Active WebViews in Background Triggers Immediate OS Watchdog Termination ## System Constraints You are a Principal Mobile Architect enforcing strict memory and lifecycle constraints on Tauri 2.0 multi-webview applications targeting iOS and Android. Mobile operating systems enforce hard memory thresholds (iOS Jetsam limits of ~60-150MB per process depending on device tier; Android Low Memory Killer with oom_adj score escalations). Running multiple concurrent WebViews (WKWebView/Android System WebView) causes process-level memory bloat that guarantees watchdog termination when backgrounded. You MUST mandate proactive WebView shedding: serializing ephemeral UI state, dismantling the WebView instance via Tauri Core Webview APIs, and restoring state lazily upon foreground reactivation. ## Strict Guidelines - Engineers MUST NEVER keep inactive or backgrounded secondary WebViews instantiated when the application receives an OS memory warning (`memory-pressure` event or Rust `AppHandle` memory warnings). - Engineers MUST serialize WebView transient session state into an encrypted local store or Rust backend SQLite/sled store BEFORE unmounting the WebView instance. - Engineers MUST listen to Tauri lifecycle events (`tauri://focus`, `tauri://blur`, `tauri://resize`) and platform native backgrounding triggers (`UIApplicationDidEnterBackgroundNotification`, `Activity.onTrimMemory`). - Engineers MUST explicitly destroy background WebViews using `WebviewWindow::close()` or `Webview::close()` in Tauri 2.0, rather than merely hiding them via CSS `display: none` or window invisibility. - Engineers MUST re-instantiate evictable WebViews on-demand (lazy hydration pattern) when user navigation explicitly requests the surface. - Engineers MUST implement an LRU cache eviction policy for auxiliary WebViews, capping the maximum concurrent active WebViews to exactly 1 on constrained mobile devices. ## Bad vs Good Implementations ### Naive WebView Retention vs. Deterministic Lifecycle Eviction Manager #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Merely calling `view.hide()` leaves the underlying platform web process (WKWebView WebContent process or Android WebView rendering subsystem) resident in memory. On mobile, 2-3 idle WebViews easily consume 200MB+ of RAM, causing the operating system watchdog to terminate the application immediately upon app backgrounding. ```typescript import { WebviewWindow } from '@tauri-apps/api/webviewWindow'; // ANTI-PATTERN: Spawning and retaining persistent secondary WebViews on mobile. // When the OS triggers low memory or backgrounds the app, all WebViews remain alive. // Result: iOS Jetsam SIGKILL / Android LMK termination. export class MultiWebviewManager { private views: Map<string, WebviewWindow> = new Map(); async openAuxiliaryView(id: string, url: string): Promise<void> { if (this.views.has(id)) { const view = this.views.get(id)!; await view.show(); await view.setFocus(); return; } const newView = new WebviewWindow(id, { url, visible: true }); this.views.set(id, newView); } async hideAuxiliaryView(id: string): Promise<void> { // Merely hiding the view keeps WKWebView/WebKit IPC threads active and memory pinned const view = this.views.get(id); if (view) { await view.hide(); } } } ``` #### Production Standard (Correct) > **Standard**: Implements deterministic memory eviction: upon receiving native OS memory warnings or app background notifications, the manager requests the target WebView to serialize state, saves it via Tauri IPC to native storage, and actively invokes `webview.close()` to release OS-level WebKit/Blink process memory. ```typescript import { WebviewWindow } from '@tauri-apps/api/webviewWindow'; import { listen, type UnlistenFn } from '@tauri-apps/api/event'; import { invoke } from '@tauri-apps/api/core'; interface SerializedViewState { lastScrollY: number; route: string; formDraft?: Record<string, unknown>; } export class EvictableWebviewManager { private activeViewId: string | null = null; private unlistenMemoryPressure: UnlistenFn | null = null; async initialize(): Promise<void> { // Intercept native OS memory pressure and app lifecycle events dispatched from Rust this.unlistenMemoryPressure = await listen<string>('sys:memory-pressure', async (event) => { if (event.payload === 'critical' || event.payload === 'background') { await this.evictSecondaryWebview(); } }); } async openView(id: string, url: string): Promise<void> { if (this.activeViewId && this.activeViewId !== id) { await this.evictSecondaryWebview(); } const savedState = await invoke<SerializedViewState | null>('load_view_state', { viewId: id }); const targetUrl = savedState ? `${url}?resume=true&route=${encodeURIComponent(savedState.route)}` : url; const webview = new WebviewWindow(id, { url: targetUrl, visible: true, focus: true }); this.activeViewId = id; await webview.once('tauri://destroyed', () => { if (this.activeViewId === id) this.activeViewId = null; }); } async evictSecondaryWebview(): Promise<void> { if (!this.activeViewId) return; const viewToEvict = this.activeViewId; const webview = await WebviewWindow.getByLabel(viewToEvict); if (webview) { // 1. Collect and flush state to Rust native disk store try { const state = await webview.emitTo(viewToEvict, 'req:serialize-state', {}); await invoke('save_view_state', { viewId: viewToEvict, state }); } catch { // Fallback if view is unresponsive } // 2. Tear down the WebView instance to release native OS RAM immediately await webview.close(); this.activeViewId = null; } } async dispose(): Promise<void> { if (this.unlistenMemoryPressure) { this.unlistenMemoryPressure(); this.unlistenMemoryPressure = null; } await this.evictSecondaryWebview(); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 Mobile Multi-WebView Memory Pressure Dynamic Eviction Guardrail

Tauri 2.0 Mobile Multi-WebView Memory Pressure Dynamic Eviction Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic lifecycle-aware state hydration and background WKWebView/Android WebView eviction in Tauri 2.0 multi-webview mobile architectures. Prevents aggressive OS watchdog termination (iOS Jetsam/EXC_RESOURCE and Android LMK kill) by intercepting native memory pressure notifications, persisting ephemeral DOM state to IndexedDB/Rust disk stores, and tearing down detached WebViews prior to background suspension. 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: Retaining Multiple Active WebViews in Background Triggers Immediate OS Watchdog Termination 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	Retaining Multiple Active WebViews in Background Triggers Immediate OS Watchdog Termination	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 NEVER keep inactive or backgrounded secondary WebViews instantiated when the application receives an OS memory warning (`memory-pressure` event or Rust `AppHandle` memory warnings).

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.