KMP Compose Skiko Render Thread GPU Surface Loss Recovery Standard

--- description: KMP Compose Skiko Render Thread GPU Surface Loss Recovery Standard - Enforces deterministic teardown and re-instantiation of hardware-accelerated Skia surfaces during Android configuration changes and iOS lifecycle suspensions. Prevents fatal native GPU context corruption, driver deadlocks, and Metal/Vulkan memory leaks across cross-platform render delegate transitions. globs: **/src/commonMain/**/*.kt, **/src/androidMain/**/*.kt, **/src/iosMain/**/*.kt, **/skiko/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-skiko-gpu-surface-loss-recovery-standard" --- # KMP Compose Skiko Render Thread GPU Surface Loss Recovery Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Asynchronous Surface Teardown and Leaked Skia DirectContext Across Lifecycle Transitions ## System Constraints You are a Principal Software Architect enforcing the KMP Compose Multiplatform Skiko Render Thread GPU Surface Loss Recovery Standard. You must mandate deterministic, synchronous destruction and re-creation of Skia DirectContext, VkDevice/MTLDevice references, and platform surface wrappers. Reject any code that leaves Skiko render threads active during surface detachment, retains dead native window handles across configuration changes, or neglects explicit context abandonment upon GPU surface loss. ## Strict Guidelines - Engineers MUST ALWAYS synchronize GPU surface destruction with the Skiko render thread using blocking rendezvous primitives before returning from Android `SurfaceHolder.Callback.surfaceDestroyed` or iOS `applicationDidEnterBackground`. - Engineers MUST synchronously call `DirectContext.abandon()` or `DirectContext.flushAndSubmit(syncCpu = true)` followed by release routines before destroying native `ANativeWindow` or unbinding `CAMetalLayer` instances. - Engineers MUST NOT execute rendering calls on a background coroutine or detached thread without acquiring the target surface lifecycle lock. - Code SHOULD encapsulate Skia `DirectContext` and backing target `RenderTarget` creation inside an idempotent, transactional factory that cleanly handles `VK_ERROR_SURFACE_LOST_KHR` and Metal drawable acquisition failures. - Components NEVER store persistent static references to `SkiaLayer`, `GrDirectContext`, `MTLCommandQueue`, or `VkQueue` across Android Activity recreation or iOS UIWindow scene disconnection. ## Bad vs Good Implementations ### Android Skiko Surface Lifecycle Management #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Destroying the surface asynchronously permits the Skiko rendering thread to issue draw and present calls against an already invalidated native window handle. This triggers fatal GPU driver panics (e.g., VK_ERROR_DEVICE_LOST or SIGSEGV inside libvulkan.so) and leaks native context allocations. ```kotlin import android.view.SurfaceHolder import org.jetbrains.skiko.SkiaLayer class UnsafeSkikoSurfaceCallback( private val skiaLayer: SkiaLayer ) : SurfaceHolder.Callback { override fun surfaceCreated(holder: SurfaceHolder) { // Asynchronously initialize without surface validation skiaLayer.attachTo(holder) } override fun surfaceChanged(holder: SurfaceHolder, format: Int, width: Int, height: Int) { skiaLayer.update(width, height) } override fun surfaceDestroyed(holder: SurfaceHolder) { // CRITICAL BUG: Asynchronous detach leaves Skiko render thread running. // The underlying ANativeWindow is destroyed immediately upon method return, // causing subsequent Vulkan/EGL swapchain submissions to crash with SIGSEGV // or VK_ERROR_SURFACE_LOST_KHR. Thread { skiaLayer.detach() }.start() } } ``` #### Production Standard (Correct) > **Standard**: Guarantees synchronous render thread termination and explicit CPU-GPU synchronization prior to the surface destruction callback return. The Skia DirectContext is flushed and abandoned, preventing race conditions against invalidated OS window handles and eliminating Vulkan swapchain context leaks. ```kotlin import android.view.SurfaceHolder import org.jetbrains.skia.DirectContext import org.jetbrains.skiko.SkiaLayer import java.util.concurrent.CountDownLatch import java.util.concurrent.TimeUnit class SafeSkikoSurfaceCallback( private val skiaLayer: SkiaLayer, private val directContextRef: () -> DirectContext? ) : SurfaceHolder.Callback { private val lifecycleLock = Any() override fun surfaceCreated(holder: SurfaceHolder) { synchronized(lifecycleLock) { skiaLayer.attachTo(holder) } } override fun surfaceChanged(holder: SurfaceHolder, format: Int, width: Int, height: Int) { synchronized(lifecycleLock) { if (holder.surface.isValid) { skiaLayer.update(width, height) } } } override fun surfaceDestroyed(holder: SurfaceHolder) { // INVARIANT: Halt rendering and flush Skia contexts synchronously // BEFORE the OS reclaims the backing ANativeWindow surface. val latch = CountDownLatch(1) synchronized(lifecycleLock) { try { directContextRef()?.let { ctx -> if (!ctx.isClosed) { ctx.flushAndSubmit(syncCpu = true) ctx.abandon() } } skiaLayer.detach() } finally { latch.countDown() } } check(latch.await(500, TimeUnit.MILLISECONDS)) { "GPU render thread teardown timed out during surface destruction." } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Compose Skiko Render Thread GPU Surface Loss Recovery Standard

KMP Compose Skiko Render Thread GPU Surface Loss Recovery Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic teardown and re-instantiation of hardware-accelerated Skia surfaces during Android configuration changes and iOS lifecycle suspensions. Prevents fatal native GPU context corruption, driver deadlocks, and Metal/Vulkan memory leaks across cross-platform render delegate 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: Asynchronous Surface Teardown and Leaked Skia DirectContext Across Lifecycle 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 Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Asynchronous Surface Teardown and Leaked Skia DirectContext Across Lifecycle Transitions	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 synchronize GPU surface destruction with the Skiko render thread using blocking rendezvous primitives before returning from Android `SurfaceHolder.Callback.surfaceDestroyed` or iOS `applicationDidEnterBackground`.

Engineers MUST ALWAYS synchronize GPU surface destruction with the Skiko render thread using blocking rendezvous primitives before returning from Android `SurfaceHolder.Callback.surfaceDestroyed` or iOS `applicationDidEnterBackground`.

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.