Kotlin Multiplatform Skia Native RenderPass Context Lifecycle Guardrail

--- description: Kotlin Multiplatform Skia Native RenderPass Context Lifecycle Guardrail - Enforces strict acquisition, synchronization, and tear-down barriers for native Skia DirectContext (GrDirectContext) and Metal/Vulkan hardware render targets across iOS and Android lifecycle shifts. Prevents SIGSEGV crashes, invalid surface access, and unrecoverable GPU driver memory leaks during rapid background-to-foreground transitions. globs: **/render/**/*.kt, **/skia/**/*.kt, **/graphics/**/*.kt, **/ui/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-skia-renderpass-lifecycle-guardrail" --- # Kotlin Multiplatform Skia Native RenderPass Context Lifecycle Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Dangling Native GPU Surfaces and Context Execution During Lifecycle Suspensions ## System Constraints You are a Principal Mobile Graphics Engineer enforcing strict native lifecycle boundaries for Skia render passes in Kotlin Multiplatform (targeting iOS Metal and Android Vulkan/OpenGL). You must mandate immediate cessation of hardware draw commands, atomic invalidation of GrDirectContext and SkSurface handles upon OS backgrounding, and thread-safe surface recreation upon foreground return. Never permit async drawing routines to reference native pointers without holding an explicit lifecycle lock. ## Strict Guidelines - Engineers MUST ALWAYS suspend render dispatch loops synchronously within the OS lifecycle callback (UIApplicationDidEnterBackgroundNotification on iOS / onStop on Android) before native window surfaces are destroyed by the compositor. - Engineers MUST NOT maintain strong references to SkSurface, SkImage, or GrDirectContext across lifecycle pauses; hardware-backed contexts must invoke context.abandonContext() or flushAndSubmit() followed by surface.close() prior to background suspension. - Code SHOULD isolate native render passes inside an atomic state machine (e.g., Active, Suspended, Disposed) protected by a platform-level mutex or Mutex to block ongoing render pass loops while contexts are tearing down. - Services MUST route Android ANativeWindow and iOS CAMetalLayer frame submission through an explicit release barrier that drops cached framebuffers before releasing the platform window handle. - Components NEVER execute skiaCanvas.draw* calls without asserting that the underlying native hardware context is attached and valid for the current platform frame. ## Bad vs Good Implementations ### Skia Native Surface Management During OS Backgrounding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Failing to flush, synchronously block, and release the underlying Skia Surface and DirectContext triggers immediate native crashes (SIGSEGV or Metal command buffer assertions) when the operating system reclaims the backing hardware framebuffers during background transitions. ```kotlin // ANTI-PATTERN: Render loop continues asynchronously without lifecycle locking, // holding dangling Metal/Vulkan pointers when the OS tears down the backing surface. class NativeSkiaRenderer { private var surface: org.jetbrains.skia.Surface? = null private var context: org.jetbrains.skia.DirectContext? = null fun onSurfaceCreated(directContext: org.jetbrains.skia.DirectContext, newSurface: org.jetbrains.skia.Surface) { this.context = directContext this.surface = newSurface } fun onAppBackgrounded() { // Defective: Just clearing references without abandoning context or syncing draw queue surface = null context = null } fun renderFrame(drawBlock: (org.jetbrains.skia.Canvas) -> Unit) { // SIGSEGV / Metal validation crash: Surface may be invalidated mid-execution by the OS surface?.canvas?.let { canvas -> drawBlock(canvas) context?.flush() } } } ``` #### Production Standard (Correct) > **Standard**: Synchronizes state transitions across native threads, cleanly flushes and closes GPU-backed allocations via flushAndSubmit(syncCpu = true), and explicitly releases Skia resources before the platform window is dismantled. ```kotlin // PRODUCTION-GRADE: Explicit state locking, native context abandonment, and synchronous barrier. import kotlinx.atomicfu.locks.SynchronizedObject import kotlinx.atomicfu.locks.synchronized import org.jetbrains.skia.DirectContext import org.jetbrains.skia.Surface class NativeSkiaRenderer : SynchronizedObject() { private enum class State { ACTIVE, SUSPENDED, DESTROYED } private var state = State.SUSPENDED private var surface: Surface? = null private var context: DirectContext? = null fun attachSurface(directContext: DirectContext, newSurface: Surface) = synchronized(this) { context = directContext surface = newSurface state = State.ACTIVE } fun onAppBackgrounded() = synchronized(this) { if (state != State.ACTIVE) return state = State.SUSPENDED try { context?.flushAndSubmit(syncCpu = true) surface?.close() context?.abandon() } finally { surface = null context = null } } fun renderFrame(drawBlock: (org.jetbrains.skia.Canvas) -> Unit): Boolean = synchronized(this) { if (state != State.ACTIVE) return false val currentSurface = surface ?: return false val currentContext = context ?: return false val canvas = currentSurface.canvas drawBlock(canvas) currentContext.flushAndSubmit(syncCpu = false) return true } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Skia Native RenderPass Context Lifecycle Guardrail

Kotlin Multiplatform Skia Native RenderPass Context Lifecycle Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict acquisition, synchronization, and tear-down barriers for native Skia DirectContext (GrDirectContext) and Metal/Vulkan hardware render targets across iOS and Android lifecycle shifts. Prevents SIGSEGV crashes, invalid surface access, and unrecoverable GPU driver memory leaks during rapid background-to-foreground transitions. 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: Dangling Native GPU Surfaces and Context Execution During Lifecycle Suspensions 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	Dangling Native GPU Surfaces and Context Execution During Lifecycle Suspensions	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 suspend render dispatch loops synchronously within the OS lifecycle callback (UIApplicationDidEnterBackgroundNotification on iOS / onStop on Android) before native window surfaces are destroyed by the compositor.

Engineers MUST ALWAYS suspend render dispatch loops synchronously within the OS lifecycle callback (UIApplicationDidEnterBackgroundNotification on iOS / onStop on Android) before native window surfaces are destroyed by the compositor.

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.