Android 15 Predictive Back Gesture State Preservation Standard

--- description: Android 15 Predictive Back Gesture State Preservation Standard - Enforces deterministic multi-stack state restoration and cancelable transitions for Android 15 predictive back navigation. Guarantees that transient UI state, focus hierarchies, and hardware-accelerated surfaces remain intact during back-gesture progress, preventing premature state commits, surface tearing, and view model corruption when gestures are cancelled. globs: **/*.kt, **/navigation/**/*.kt, **/ui/**/*.kt, **/presentation/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-predictive-back-gesture-state-preservation-standard" --- # Android 15 Predictive Back Gesture State Preservation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Mutating Backstack State or Triggering Terminal Side Effects During Gesture Progress ## System Constraints You are a Principal Mobile Architect enforcing the Android 15 Predictive Back Gesture State Preservation Standard. You must ensure that all navigation transitions, back handlers, and UI layers respect the two-phase gesture lifecycle (progress vs. commit). Prevent state mutations during gesture execution, guarantee zero surface tearing or composition drops during cancellation, and ensure navigation graphs retain deterministic state across all back-gesture trajectories. ## Strict Guidelines - Engineers MUST ALWAYS isolate gesture progress transforms (scale, offset, alpha) from terminal domain and navigation state mutations. - Engineers MUST NOT invoke `NavController.popBackStack()`, mutate state hoisted in ViewModels, or dispatch analytics events inside progress or cancellation blocks. - Code MUST handle the `CancellationException` in `PredictiveBackHandler` to smoothly animate transient progress offsets back to neutral rest positions when a gesture is aborted. - Services and custom layout components MUST synchronize hardware-accelerated surfaces (such as `SurfaceView` or MapView layers) using `SurfaceSyncGroup` during predictive back transitions to prevent visual tearing. - Components NEVER drop composition nodes or release retained graphics memory while a predictive back gesture is in the `onBackStarted` or `onBackProgressed` phase. ## Bad vs Good Implementations ### Predictive Back Gesture Handling in Jetpack Compose #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy BackHandler or immediate backstack mutations ignore the cancelable progress stream of Android 15. Calling terminal side effects or synchronous state commits prevents previewing the underlying destination and causes UI jank or corrupted state if the gesture is aborted. ```kotlin import androidx.activity.compose.BackHandler import androidx.compose.runtime.* import androidx.navigation.NavController @Composable fun FlawedDetailScreen(navController: NavController, viewModel: DetailViewModel) { // ANTI-PATTERN: Standard BackHandler fires eagerly with no predictive progress control, // or mutating business state eagerly causes tearing if cancelled at the system level. BackHandler(enabled = true) { viewModel.saveDraftSync() // Premature side effect navController.popBackStack() // Direct jump without predictive frame interpolation } DetailContent(viewModel = viewModel) } ``` #### Production Standard (Correct) > **Standard**: The PredictiveBackHandler consumes the backEvent stream, mapping progress to local graphical transforms without touching business state. Cancellation is caught via CancellationException to restore the UI to rest, and destructive mutations are executed only upon completed invocation. ```kotlin import androidx.activity.compose.PredictiveBackHandler import androidx.compose.animation.core.Animatable import androidx.compose.runtime.* import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.graphicsLayer import androidx.navigation.NavController import kotlinx.coroutines.CancellationException @Composable fun RobustDetailScreen(navController: NavController, viewModel: DetailViewModel) { val progressAnim = remember { Animatable(0f) } // INVARIANT: Collect progress safely; mutate terminal state ONLY when flow completes. PredictiveBackHandler(enabled = true) { progressFlow -> try { progressFlow.collect { backEvent -> // Continuous, non-destructive interpolation based on system touch input progressAnim.snapTo(backEvent.progress) } // Gesture completed successfully: Commit terminal navigation viewModel.persistDraft() navController.popBackStack() } catch (e: CancellationException) { // Gesture aborted by user: Animate smoothly back to resting frame progressAnim.animateTo(0f) } } DetailContent( viewModel = viewModel, modifier = Modifier.graphicsLayer { val scale = 1f - (progressAnim.value * 0.1f) scaleX = scale scaleY = scale alpha = 1f - (progressAnim.value * 0.2f) } ) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 Predictive Back Gesture State Preservation Standard

Android 15 Predictive Back Gesture State Preservation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic multi-stack state restoration and cancelable transitions for Android 15 predictive back navigation. Guarantees that transient UI state, focus hierarchies, and hardware-accelerated surfaces remain intact during back-gesture progress, preventing premature state commits, surface tearing, and view model corruption when gestures are cancelled. 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: Mutating Backstack State or Triggering Terminal Side Effects During Gesture Progress 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	Mutating Backstack State or Triggering Terminal Side Effects During Gesture Progress	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 gesture progress transforms (scale, offset, alpha) from terminal domain and navigation state mutations.

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.