AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
mobilecritical PriorityID: capacitor7-android15-edge-to-edge-windowinsets-invariant

Capacitor 7 Android 15 Edge-to-Edge Dynamic WindowInsets and IME Synchronization Invariant

Android 15 (API 35) strictly enforces edge-to-edge display by default, causing Capacitor 7 WebViews to render behind system bars and the soft keyboard (IME). This guardrail mandates binding platform WindowInsetsCompat events to atomic CSS custom properties via coordinated requestAnimationFrame updates to prevent viewport occlusion, layout jumps, and visual thrashing.

Prohibited Anti-Pattern: Relying on Stale env(safe-area-inset-*) or Unsynchronized Window Resizing During Android 15 Edge-to-Edge Transitions

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Capacitor 7 Android 15 Edge-to-Edge Dynamic WindowInsets and IME Synchronization Invariant - Android 15 (API 35) strictly enforces edge-to-edge display by default, causing Capacitor 7 WebViews to render behind system bars and the soft keyboard (IME). This guardrail mandates binding platform WindowInsetsCompat events to atomic CSS custom properties via coordinated requestAnimationFrame updates to prevent viewport occlusion, layout jumps, and visual thrashing.
globs: android/**/*.kt, android/**/*.java, capacitor.config.ts, src/**/*.{ts,tsx,vue,svelte}, src/styles/**/*.css
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/capacitor7-android15-edge-to-edge-windowinsets-invariant"
---

# Capacitor 7 Android 15 Edge-to-Edge Dynamic WindowInsets and IME Synchronization Invariant

> **Severity**: CRITICAL | **Category**: mobile
> **Anti-Pattern Warning**: Relying on Stale env(safe-area-inset-*) or Unsynchronized Window Resizing During Android 15 Edge-to-Edge Transitions

## System Constraints
You are a Principal Mobile Architect specializing in Capacitor 7 and Android 15 (API level 35) runtime dynamics. You enforce zero-jank edge-to-edge system insets and IME (keyboard) handling by requiring native WindowInsetsCompat observables to synchronize dynamically with atomic CSS custom properties, strictly rejecting assumptions that CSS env(safe-area-inset-*) will accurately track keyboard animations or Android 15 edge-to-edge changes.

## Strict Guidelines
- Engineers MUST ALWAYS synchronize Android 15 platform WindowInsetsCompat (systemBars, displayCutout, and ime) with atomic CSS custom properties (e.g., --safe-area-top, --safe-area-bottom, --ime-height) rather than relying solely on static env(safe-area-inset-*).
- Engineers MUST configure Capacitor 7 Android plugins to use KeyboardResize.None or manual layout coordination when targeting Android 15, preventing native WebView height resizing conflicts with Edge-to-Edge layouts.
- Code MUST batch viewport and inset mutations inside a single requestAnimationFrame to prevent multiple reflows during IME open/close transitions.
- Services MUST listen to both Capacitor Keyboard lifecycle events and native WindowInsets callbacks to calculate accurate non-overlapping bottom offsets.
- Components NEVER hardcode pixel padding for system bars or use raw window.innerHeight deltas, which break under predictive back gestures and split-screen mode on Android 15.

## Bad vs Good Implementations
### Unsynchronized Static Insets & Automatic Keyboard Resize (Broken on Android 15)

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Android 15 mandates edge-to-edge layouts where the WebView draws behind both navigation bars and the IME. Relying on default Capacitor keyboard resize modes combined with CSS env() safe areas causes compounding bottom padding, erratic layout thrashing, and occluded input fields.
```typescript
import { Plugins } from '@capacitor/core';
// ANTI-PATTERN: Relying on native WebView automatic resizing and CSS env variables
// On Android 15 Edge-to-Edge, KeyboardResize.Body causes dual-inset jumps and cuts off inputs.

export function setupLayout() {
  // In Capacitor 7 / Android 15, static env() fails to update for IME animations
  const style = document.createElement('style');
  style.textContent = `
    .screen-container {
      padding-top: env(safe-area-inset-top);
      padding-bottom: env(safe-area-inset-bottom);
      height: 100vh; /* Fails when keyboard triggers layout shifts */
    }
  `;
  document.head.appendChild(style);

  window.addEventListener('resize', () => {
    console.log('Window resized:', window.innerHeight);
  });
}
```

#### Production Standard (Correct)
> **Standard**: Sets KeyboardResize mode to None to maintain control over the edge-to-edge canvas, prevents multiple recalculation reflows using requestAnimationFrame, and calculates a synchronized CSS variable (--viewport-inset-bottom) that seamlessly reflects either the system nav bar or the dynamic keyboard height.
```typescript
import { Keyboard, KeyboardResize } from '@capacitor/keyboard';
import { Capacitor } from '@capacitor/core';

interface SystemInsets {
  top: number;
  bottom: number;
  imeHeight: number;
}

class EdgeToEdgeInsetsCoordinator {
  private static insets: SystemInsets = { top: 0, bottom: 0, imeHeight: 0 };
  private static rafId: number | null = null;

  public static async initialize(): Promise<void> {
    if (Capacitor.getPlatform() !== 'android') return;

    // Disable native window resizing to allow fluid edge-to-edge CSS coordination
    await Keyboard.setResizeMode({ mode: KeyboardResize.None });

    Keyboard.addListener('keyboardWillShow', (info) => {
      this.scheduleUpdate({ imeHeight: info.keyboardHeight });
    });

    Keyboard.addListener('keyboardWillHide', () => {
      this.scheduleUpdate({ imeHeight: 0 });
    });
  }

  public static setSystemInsets(topPx: number, bottomPx: number): void {
    this.scheduleUpdate({ top: topPx, bottom: bottomPx });
  }

  private static scheduleUpdate(partial: Partial<SystemInsets>): void {
    this.insets = { ...this.insets, ...partial };

    if (this.rafId !== null) {
      cancelAnimationFrame(this.rafId);
    }

    this.rafId = requestAnimationFrame(() => {
      const root = document.documentElement;
      const effectiveBottom = Math.max(this.insets.bottom, this.insets.imeHeight);
      
      root.style.setProperty('--safe-area-top', `${this.insets.top}px`);
      root.style.setProperty('--safe-area-bottom', `${this.insets.bottom}px`);
      root.style.setProperty('--ime-height', `${this.insets.imeHeight}px`);
      root.style.setProperty('--viewport-inset-bottom', `${effectiveBottom}px`);
      this.rafId = null;
    });
  }
}

export { EdgeToEdgeInsetsCoordinator };
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Android ADB Insets Inspector
Inspects live WindowInsetsCompat and IME animation frames on connected Android 15 emulators and devices.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Capacitor CLI Runner
Synchronizes plugins, builds Android assets, and runs target APKs on API 35 testbeds.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Android 15 Edge-to-Edge Dynamic WindowInsets and IME Synchronization Invariant

Capacitor 7 Android 15 Edge-to-Edge Dynamic WindowInsets and IME Synchronization Invariant defines an industrial-grade behavioral standard for mobile engineering. Android 15 (API 35) strictly enforces edge-to-edge display by default, causing Capacitor 7 WebViews to render behind system bars and the soft keyboard (IME). This guardrail mandates binding platform WindowInsetsCompat events to atomic CSS custom properties via coordinated requestAnimationFrame updates to prevent viewport occlusion, layout jumps, and visual thrashing. 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: Relying on Stale env(safe-area-inset-*) or Unsynchronized Window Resizing During Android 15 Edge-to-Edge 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftRelying on Stale env(safe-area-inset-*) or Unsynchronized Window Resizing During Android 15 Edge-to-Edge TransitionsCritical
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 InconsistencyAI 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:

1

Engineers MUST ALWAYS synchronize Android 15 platform WindowInsetsCompat (systemBars, displayCutout, and ime) with atomic CSS custom properties (e.g., --safe-area-top, --safe-area-bottom, --ime-height) rather than relying solely on static env(safe-area-inset-*).

Engineers MUST ALWAYS synchronize Android 15 platform WindowInsetsCompat (systemBars, displayCutout, and ime) with atomic CSS custom properties (e.g., --safe-area-top, --safe-area-bottom, --ime-height) rather than relying solely on static env(safe-area-inset-*).

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST configure Capacitor 7 Android plugins to use KeyboardResize.None or manual layout coordination when targeting Android 15, preventing native WebView height resizing conflicts with Edge-to-Edge layouts.

Engineers MUST configure Capacitor 7 Android plugins to use KeyboardResize.None or manual layout coordination when targeting Android 15, preventing native WebView height resizing conflicts with Edge-to-Edge layouts.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Code MUST batch viewport and inset mutations inside a single requestAnimationFrame to prevent multiple reflows during IME open/close transitions.

Code MUST batch viewport and inset mutations inside a single requestAnimationFrame to prevent multiple reflows during IME open/close 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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Services MUST listen to both Capacitor Keyboard lifecycle events and native WindowInsets callbacks to calculate accurate non-overlapping bottom offsets.

Services MUST listen to both Capacitor Keyboard lifecycle events and native WindowInsets callbacks to calculate accurate non-overlapping bottom offsets.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Components NEVER hardcode pixel padding for system bars or use raw window.innerHeight deltas, which break under predictive back gestures and split-screen mode on Android 15.

Components NEVER hardcode pixel padding for system bars or use raw window.innerHeight deltas, which break under predictive back gestures and split-screen mode on Android 15.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Capacitor 7 Android 15 Edge-to-Edge Dynamic WindowInsets and IME Synchronization Invariant critical for AI coding assistants?

Android 15 (API 35) strictly enforces edge-to-edge display by default, causing Capacitor 7 WebViews to render behind system bars and the soft keyboard (IME). This guardrail mandates binding platform WindowInsetsCompat events to atomic CSS custom properties via coordinated requestAnimationFrame updates to prevent viewport occlusion, layout jumps, and visual thrashing. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Relying on Stale env(safe-area-inset-*) or Unsynchronized Window Resizing During Android 15 Edge-to-Edge Transitions) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related MOBILE Rules

View all rules →
mobile
106

Tauri 2.0 Mobile IPC & Capabilities Permissions Matrix Standard

Tauri v2 introduces a capability-driven permissions system replacing legacy v1 allowlists across iOS and Android runtimes. Failure to constrain IPC command handlers with typed schemas and explicit mobile capability definitions exposes native mobile OS surfaces to arbitrary code execution, permission leakage, and silent serialization failures. Production mobile deployments require strictly typed IPC boundary validation, granular capability scopes, and graceful permission degradation.

mobile
70

Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard

Capacitor 7 enforces strict bridge lifecycle contracts, asynchronous native plugin interop, and mandatory Android 15 edge-to-edge window inset handling. Storing sensitive authentication tokens in unencrypted web storage or failing to bind biometric authentication directly to hardware-backed Keystore or Secure Enclave mechanisms compromises app integrity and causes fatal crash or viewport occlusion issues on modern mobile operating systems.

mobile
58

Tauri 2.0 Mobile IPC Isolation and Capabilities Permission Scoping

Enforces strict capability permission boundaries, payload validation, and secure IPC invoke scoping for Tauri v2 Android and iOS environments. Prevents arbitrary IPC command execution, excessive native privilege granting, and deserialization vulnerabilities across the mobile webview-native boundary.

1 Rule in Stack

Capacitor