Capacitor 7 Android 15 Predictive Back and Window Inset Synchronization Standard

--- description: Capacitor 7 Android 15 Predictive Back and Window Inset Synchronization Standard - Hardens hybrid mobile architectures against layout shifts, safe area collapse, and gesture navigation conflicts under Android 15 (API 35). Mandates edge-to-edge WindowInsets synchronization with Chromium viewport CSS environment variables while properly binding predictive back gesture state without breaking SPA routing lifecycles. globs: android/app/src/**/*.kt, android/app/src/**/*.java, android/app/src/main/AndroidManifest.xml, src/**/*.{ts,tsx,vue,svelte}, src/index.html, src/**/*.css alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-android-15-predictive-back-window-inset-standard" --- # Capacitor 7 Android 15 Predictive Back and Window Inset Synchronization Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unsynchronized Edge-to-Edge Insets and Monolithic Back Handlers Causing Viewport Clipping and Predictive Back Freezes ## System Constraints You are a Principal Mobile Architect enforcing Capacitor 7 Android 15 (API 35) Window Inset and Predictive Back Invariants. In Android 15, edge-to-edge layout is enforced by default; applications can no longer disable it via legacy flags. You must ensure that Capacitor 7 native bridges properly coordinate WindowInsetsAnimationCallback with WebKit/Chromium viewport dimensions, safe-area-inset-* CSS variables, and the OnBackAnimationCallback API. Never permit unconditional event.preventDefault() on Capacitor backButton listeners, as this deadlocks Android 15 predictive back animations. ## Strict Guidelines - Engineers MUST ALWAYS declare `android:enableOnBackInvokedCallback="true"` inside the `<application>` tag of `AndroidManifest.xml` to support Android 15 predictive back gesture orchestration. - Engineers MUST configure `<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">` in `index.html` to enable CSS `env(safe-area-inset-*)` under Android 15 mandatory edge-to-edge rendering. - Engineers MUST NOT hijack the Capacitor `App.addListener('backButton', ...)` with an unconditional synchronous interceptor; developers must only intercept when internal SPA history depth or overlay state strictly warrants it. - Code SHOULD leverage the modern AndroidX `OnBackPressedDispatcher` or `OnBackAnimationCallback` within custom Capacitor Android native plugins rather than overriding legacy `onBackPressed()`. - Services MUST synchronize native system bar cutout and navigation bar insets to CSS Custom Properties when standard `env(safe-area-inset-*)` values fail to react dynamically during Android 15 interactive keyboard and gesture transitions. - Components NEVER hardcode fixed pixel padding for headers, status bars, bottom navigation bars, or system bars. ## Bad vs Good Implementations ### Predictive Back & Inset Synchronization in Capacitor 7 / TypeScript #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Registering an unconditional global Capacitor backButton handler prevents Android 15 from executing Predictive Back gesture preview animations (such as cross-activity or cross-task previews) and traps the user in a desynchronized viewport state. ```typescript // BAD: Blindly captures the back button, breaking Android 15 predictive back transitions import { App } from '@capacitor/app'; export function setupBackNavigation(router: any) { // Unconditional listener disables Android OS predictive animation preview App.addListener('backButton', ({ canGoBack }) => { // Hardcoded logic prevents system from handling dismiss gestures if (router.canGoBack()) { router.back(); } else { App.exitApp(); } }); } ``` #### Production Standard (Correct) > **Standard**: By selectively registering the backButton listener only when custom web-tier overlay dismissals are required, the Android 15 OS retains native predictive back animation handling when navigating through native activity states. ```typescript // GOOD: Conditionally manages back callback registration matching active modal/history state import { App } from '@capacitor/app'; import type { PluginListenerHandle } from '@capacitor/core'; class PredictiveBackCoordinator { private backListener: PluginListenerHandle | null = null; private activeModals = 0; public registerModalOpen(): void { this.activeModals++; this.syncNativeBackState(); } public registerModalClose(): void { this.activeModals = Math.max(0, this.activeModals - 1); this.syncNativeBackState(); } private async syncNativeBackState(): Promise<void> { // Only intercept system back when an active modal layer exists if (this.activeModals > 0 && !this.backListener) { this.backListener = await App.addListener('backButton', () => { if (this.activeModals > 0) { this.dismissTopModal(); } }); } else if (this.activeModals === 0 && this.backListener) { // Release listener to restore Android 15 OS predictive back gesture preview await this.backListener.remove(); this.backListener = null; } } private dismissTopModal(): void { // Modal teardown logic here this.registerModalClose(); } } export const backCoordinator = new PredictiveBackCoordinator(); ``` ### Android 15 Native Edge-to-Edge Inset Propagation in MainActivity #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy SYSTEM_UI_FLAG and fitSystemWindows calls are deprecated and overridden in Android 15. The webview content renders behind navigation and status bars without inset margins, causing touch collisions with gesture pills. ```typescript // BAD: Legacy Android padding or disabling edge-to-edge via window flags (broken in API 35) // In MainActivity.kt: // window.decorView.systemUiVisibility = View.SYSTEM_UI_FLAG_FULLSCREEN; // (Deprecated and ignored by Android 15 enforcement, resulting in obscured web content) ``` #### Production Standard (Correct) > **Standard**: Invoking `enableEdgeToEdge()` through AndroidX guarantees compatibility with Android 15's default edge-to-edge mandate, ensuring Capacitor's WebView layout receives correct system bar and cutout insets without clipping. ```typescript // GOOD: MainActivity.kt edge-to-edge coordination for Capacitor 7 /* package com.example.app import android.os.Bundle import androidx.activity.enableEdgeToEdge import androidx.core.view.ViewCompat import androidx.core.view.WindowInsetsCompat import com.getcapacitor.BridgeActivity class MainActivity : BridgeActivity() { override fun onCreate(savedInstanceState: Bundle?) { // Mandate edge-to-edge configuration consistent with Android 15 API 35 enableEdgeToEdge() super.onCreate(savedInstanceState) ViewCompat.setOnApplyWindowInsetsListener(bridge.webView) { view, windowInsets -> val insets = windowInsets.getInsets(WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout()) // Forward accurate insets to webview padding or dynamic root styles if viewport-fit=cover requires compensation view.setPadding(0, 0, 0, 0) // Allows CSS env(safe-area-inset-*) to control layout cleanly windowInsets } } } */ ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Android 15 Predictive Back and Window Inset Synchronization Standard

Capacitor 7 Android 15 Predictive Back and Window Inset Synchronization Standard defines an industrial-grade behavioral standard for mobile engineering. Hardens hybrid mobile architectures against layout shifts, safe area collapse, and gesture navigation conflicts under Android 15 (API 35). Mandates edge-to-edge WindowInsets synchronization with Chromium viewport CSS environment variables while properly binding predictive back gesture state without breaking SPA routing lifecycles. 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: Unsynchronized Edge-to-Edge Insets and Monolithic Back Handlers Causing Viewport Clipping and Predictive Back Freezes 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	Unsynchronized Edge-to-Edge Insets and Monolithic Back Handlers Causing Viewport Clipping and Predictive Back Freezes	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 declare `android

Engineers MUST ALWAYS declare `android:enableOnBackInvokedCallback="true"` inside the `<application>` tag of `AndroidManifest.xml` to support Android 15 predictive back gesture orchestration.

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.