KMP Compose Multiplatform Skia/Metal Surface Render Sync & Disposal Barrier Standard

--- description: KMP Compose Multiplatform Skia/Metal Surface Render Sync & Disposal Barrier Standard - Enforces deterministic synchronization barriers between Skia render loops and native graphics surfaces (Metal CAMetalLayer / Android SurfaceView) across Kotlin Multiplatform viewports. Guarantees that native surface teardown waits on in-flight GPU command buffers and disposes GrDirectContext/Skia resources cleanly, preventing GPU memory leaks, command buffer race panics, and dangling drawable crashes during rapid view recycling. globs: **/iosMain/**/MetalRender*.kt, **/iosMain/**/*Surface*.kt, **/androidMain/**/Surface*.kt, **/androidMain/**/SkiaRender*.kt, **/commonMain/**/graphics/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-skia-metal-render-sync-standard" --- # KMP Compose Multiplatform Skia/Metal Surface Render Sync & Disposal Barrier Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Asynchronous Surface Teardown and Dangling GPU Command Buffer Execution During Lifecycle Disposal ## System Constraints You are a Principal Mobile Graphics Systems Architect enforcing deterministic Skia/Metal rendering synchronization barriers and resource lifecycle disposal in Kotlin Compose Multiplatform. You mandate that all platform bridge layers handle native graphics allocations, in-flight command buffer completion waits, and explicit context invalidation synchronously upon viewport detachment to eliminate GPU deadlocks and out-of-memory memory panics. ## Strict Guidelines - Engineers MUST ALWAYS invoke GrDirectContext.flushAndSubmit() or explicit Metal waitUntilCompleted() fences before releasing CAMetalDrawable or backing Android Surface instances. - Engineers MUST NOT synchronously dispose native C/C++ pointers or Skia GrDirectContext handles while a rendering command buffer pass is scheduled or actively processing on the GPU. - Engineers MUST wrap all native view teardown lifecycle hooks (UIViewController.viewWillDisappear, SurfaceHolder.Callback.surfaceDestroyed) with deterministic GPU synchronization barriers that block surface recycling until in-flight draws commit. - Engineers MUST explicitly call context.resetContext() and abandonContext() on Skia DirectContext bindings during final surface release rather than relying on Kotlin Garbage Collection or ARC finalizers. - Components NEVER reallocate a Skia SkSurface on a background thread while native surface configuration changes (such as orientation or resizing) are executing on the main render thread. ## Bad vs Good Implementations ### Metal CAMetalLayer Surface Teardown Barrier in iOS Target #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly clearing the CAMetalLayer and disposing the renderer without awaiting command buffer execution or flushing the Skia queue leads to EXCEPTION_ACCESS_VIOLATION / Metal Command Buffer panics when Skia tries to present to a destroyed surface. ```kotlin // Flawed iOS Metal View Controller teardown relying on GC/ARC class SkiaMetalViewController(private val skiaRenderer: SkiaMetalRenderer) : UIViewController(null, null) { private var metalLayer: CAMetalLayer? = null override fun viewDidLoad() { super.viewDidLoad() metalLayer = CAMetalLayer().apply { device = MTLCreateSystemDefaultDevice() view.layer.addSublayer(this) } } override fun viewDidDisappear(animated: Boolean) { super.viewDidDisappear(animated) // ANTI-PATTERN: Native layer is dereferenced while command buffers are in-flight. // Skia GrDirectContext still holds references to the CAMetalDrawable, leading to GPU crashes. metalLayer?.removeFromSuperlayer() metalLayer = null skiaRenderer.dispose() } } ``` #### Production Standard (Correct) > **Standard**: Synchronously flushes in-flight Skia work, executes a Metal synchronization barrier, detaches the drawable target, and releases the direct context deterministically, completely preventing dangling GPU memory leaks. ```kotlin // Deterministic Metal Surface Sync and Teardown Barrier class SkiaMetalViewController(private val skiaRenderer: SkiaMetalRenderer) : UIViewController(null, null) { private var metalLayer: CAMetalLayer? = null override fun viewDidLoad() { super.viewDidLoad() metalLayer = CAMetalLayer().apply { device = MTLCreateSystemDefaultDevice() view.layer.addSublayer(this) } skiaRenderer.attachSurface(metalLayer!!) } override fun viewWillDisappear(animated: Boolean) { // INVARIANT: Drain in-flight commands and synchronize GPU before releasing surface skiaRenderer.flushAndSynchronizeBarrier() super.viewWillDisappear(animated) } override fun viewDidDisappear(animated: Boolean) { super.viewDidDisappear(animated) metalLayer?.let { layer -> skiaRenderer.detachSurface(layer) layer.removeFromSuperlayer() } metalLayer = null skiaRenderer.releaseDirectContext() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Compose Multiplatform Skia/Metal Surface Render Sync & Disposal Barrier Standard

KMP Compose Multiplatform Skia/Metal Surface Render Sync & Disposal Barrier Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic synchronization barriers between Skia render loops and native graphics surfaces (Metal CAMetalLayer / Android SurfaceView) across Kotlin Multiplatform viewports. Guarantees that native surface teardown waits on in-flight GPU command buffers and disposes GrDirectContext/Skia resources cleanly, preventing GPU memory leaks, command buffer race panics, and dangling drawable crashes during rapid view recycling. 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 Dangling GPU Command Buffer Execution During Lifecycle Disposal 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 Dangling GPU Command Buffer Execution During Lifecycle Disposal	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 invoke GrDirectContext.flushAndSubmit() or explicit Metal waitUntilCompleted() fences before releasing CAMetalDrawable or backing Android Surface instances.

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.