KMP Compose Multiplatform Offscreen Surface Invalidation & Lifecycle Guardrail

--- description: KMP Compose Multiplatform Offscreen Surface Invalidation & Lifecycle Guardrail - Enforces lifecycle-bound texture pooling, dirty-state synchronization, and explicit teardown for offscreen rendering surfaces in Compose Multiplatform across iOS (Metal) and Android (Vulkan). Eliminates unthrottled VSync invalidation loops and GPU VRAM exhaustion caused by orphaned hardware buffers, unreleased Skia surfaces, and asynchronous swapchain deadlocks. globs: **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-compose-offscreen-surface-invalidation-guardrail" --- # KMP Compose Multiplatform Offscreen Surface Invalidation & Lifecycle Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded VSync Invalidation Loops and Leaked Metal/Vulkan Native Surfaces in Compose Multiplatform Custom Drawing Pipelines ## System Constraints You are a Principal Mobile Graphics Architect enforcing strict hardware surface resource management in Kotlin Multiplatform (Compose Multiplatform) applications targeting iOS (Metal) and Android (Vulkan). You mandate that any offscreen rendering surface, Skia Image/Surface, or platform-native hardware buffer must be lifecycle-bound, throttled to actual state changes, and explicitly disposed of upon leaving composition. ## Strict Guidelines - Engineers MUST ALWAYS tie custom native graphics resources (CAMetalLayer, Vulkan HardwareBuffers, Skia SkSurface) to Compose lifecycle via DisposableEffect or rememberObserver with explicit deallocation routines. - Engineers MUST NOT trigger surface invalidation on unconstrained VSync loops or Compose recomposition passes without verifying dirty render state or explicit input changes. - Code SHOULD implement dual-buffered texture swapping with deterministic size matching, ensuring reallocation occurs only when container dimensions mutate rather than on every draw phase pass. - Components NEVER instantiate Skia Surfaces or hardware framebuffers directly inside the DrawScope lambda or DrawModifierNode.draw() invocation path. - Services MUST monitor native application lifecycle (background/foreground transitions) and release offscreen VRAM allocations immediately upon background entry to avert OS-level OOM kills. ## Bad vs Good Implementations ### Offscreen Surface Lifecycle & Invalidation in Compose Multiplatform #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Allocates a new raster/GPU surface on every frame inside DrawScope, generating massive VRAM churn and GC pressure. Continuously animates and redraws regardless of whether the underlying payload changed, causing thermal throttling and high battery drain on Metal and Vulkan pipelines without freeing native C++ pointers. ```kotlin // BAD: Allocating offscreen SkSurface in draw phase and invalidating continuously on VSync @Composable fun MetalVulkanOffscreenRenderer( modifier: Modifier = Modifier, payload: RenderPayload ) { val infiniteTransition = rememberInfiniteTransition() val phase by infiniteTransition.animateFloat( initialValue = 0f, targetValue = 1f, animationSpec = infiniteRepeatable(tween(1000, easing = LinearEasing)) ) Canvas(modifier = modifier.fillMaxSize()) { // Re-allocating surface on every draw pass exhausts GPU VRAM rapidly val surface = org.jetbrains.skia.Surface.makeRasterN32Premul( size.width.toInt().coerceAtLeast(1), size.height.toInt().coerceAtLeast(1) ) val canvas = surface.canvas canvas.clear(org.jetbrains.skia.Color.TRANSPARENT) // Drawing without checking dirty rects or caching hardware textures renderCustomPass(canvas, payload, phase) val image = surface.makeImageSnapshot() drawImage(image.toComposeImageBitmap()) // Memory leak: surface and image native handles are abandoned to GC } } ``` #### Production Standard (Correct) > **Standard**: Moves surface creation out of the draw cycle into a cached, reusable holder using `drawWithCache`. Surfaces are reallocated only when bounds change, rendered only when marked dirty, and natively freed immediately when leaving the composition hierarchy via `DisposableEffect`. ```kotlin // GOOD: Pre-allocated, lifecycle-bound surface with dirty-flag checking and deterministic disposal @Composable fun MetalVulkanOffscreenRenderer( modifier: Modifier = Modifier, payload: RenderPayload ) { val density = LocalDensity.current // Retain and manage lifecycle of native graphics surface val surfaceHolder = remember { ManagedSurfaceHolder() } DisposableEffect(surfaceHolder) { onDispose { surfaceHolder.releaseResources() } } // Invalidate solely when payload content actually changes LaunchedEffect(payload) { surfaceHolder.markDirty() } Spacer( modifier = modifier .fillMaxSize() .drawWithCache { val width = size.width.toInt().coerceAtLeast(1) val height = size.height.toInt().coerceAtLeast(1) surfaceHolder.ensureCapacity(width, height) onDrawWithContent { if (surfaceHolder.isDirty) { surfaceHolder.renderOffscreen(payload) } surfaceHolder.drawToTarget(drawContext.canvas) } } ) } private class ManagedSurfaceHolder : AutoCloseable { private var surface: org.jetbrains.skia.Surface? = null var isDirty: Boolean = true private set fun ensureCapacity(width: Int, height: Int) { if (surface == null || surface?.width != width || surface?.height != height) { surface?.close() // Release native C++ / GPU backing surface = org.jetbrains.skia.Surface.makeRenderTarget( org.jetbrains.skia.DirectContext.makeMetal(), // Or platform-abstracted context org.jetbrains.skia.Budgeted.YES, org.jetbrains.skia.ImageInfo.makeN32Premul(width, height) ) isDirty = true } } fun markDirty() { isDirty = true } fun renderOffscreen(payload: RenderPayload) { val s = surface ?: return s.canvas.clear(org.jetbrains.skia.Color.TRANSPARENT) // Perform drawing into cached surface isDirty = false } fun drawToTarget(canvas: androidx.compose.ui.graphics.Canvas) { surface?.makeImageSnapshot()?.use { snapshot -> canvas.drawImage(snapshot.toComposeImageBitmap(), androidx.compose.ui.geometry.Offset.Zero, androidx.compose.ui.graphics.Paint()) } } fun releaseResources() { surface?.close() surface = null } override fun close() = releaseResources() } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Compose Multiplatform Offscreen Surface Invalidation & Lifecycle Guardrail

KMP Compose Multiplatform Offscreen Surface Invalidation & Lifecycle Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces lifecycle-bound texture pooling, dirty-state synchronization, and explicit teardown for offscreen rendering surfaces in Compose Multiplatform across iOS (Metal) and Android (Vulkan). Eliminates unthrottled VSync invalidation loops and GPU VRAM exhaustion caused by orphaned hardware buffers, unreleased Skia surfaces, and asynchronous swapchain deadlocks. 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: Unbounded VSync Invalidation Loops and Leaked Metal/Vulkan Native Surfaces in Compose Multiplatform Custom Drawing Pipelines 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	Unbounded VSync Invalidation Loops and Leaked Metal/Vulkan Native Surfaces in Compose Multiplatform Custom Drawing Pipelines	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 tie custom native graphics resources (CAMetalLayer, Vulkan HardwareBuffers, Skia SkSurface) to Compose lifecycle via DisposableEffect or rememberObserver with explicit deallocation routines.

Engineers MUST ALWAYS tie custom native graphics resources (CAMetalLayer, Vulkan HardwareBuffers, Skia SkSurface) to Compose lifecycle via DisposableEffect or rememberObserver with explicit deallocation routines.

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.