Compose Multiplatform Metal/Skia iOS Surface Presentation Synchronization Guardrail

--- description: Compose Multiplatform Metal/Skia iOS Surface Presentation Synchronization Guardrail - Enforces deterministic synchronization between Apple Metal command buffer presentation and Skia GPU drawing contexts in Compose Multiplatform. Prevents CAMetalLayer surface deadlocks, command queue starvation, and catastrophic frame pacing drops during concurrent UIKit navigation controller transitions and active Canvas invalidate loops. globs: **/iosMain/**/*.kt, **/iosApp/**/*.swift, **/skiko/**/*.kt, **/ui/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cmp-metal-skia-sync-pipeline-guardrail" --- # Compose Multiplatform Metal/Skia iOS Surface Presentation Synchronization Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unsynchronized CAMetalDrawable acquisition on the main runloop during concurrent UIKit transitions causing Metal thread deadlocks ## System Constraints You are a Principal Mobile Architect specializing in Compose Multiplatform, Skiko, and iOS Metal graphics pipelines. You mandate rock-solid frame synchronization and non-blocking CAMetalDrawable acquisition. Prevent all presentation deadlocks between Skia rendering passes and native UIKit/SwiftUI interactive transition coordinators. ## Strict Guidelines - Engineers MUST ALWAYS configure Skiko Metal render delegate with non-blocking drawable acquisition timeouts (maximum 16.6ms frame deadline) using `nextDrawable()` with timeout or async render passes. - Engineers MUST NOT block UIKit main dispatch queue while waiting for Metal command buffer commits or Skia GPU rasterization completions (`waitUntilCompleted()` or synchronous GPU flush on main thread is strictly forbidden). - Components undergoing interactive navigation transitions (e.g., UINavigationController interactivePopGestureRecognizer) MUST throttle or pause intensive Skia `Canvas` draw loops via state-driven render fences. - Services MUST route Metal command buffer presentation via `presentDrawable:afterMinimumDuration:` or coordinate with `CADisplayLink` targets using timestamped synchronization tokens. - Code MUST explicitly synchronize surface bounds resizes with `CATransaction` actions during view controller containment changes to prevent Skia surface invalidation race conditions. ## Bad vs Good Implementations ### Synchronizing Metal Surface Presentation During Native iOS Transitions #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing unthrottled Compose Canvas operations during native transitions while CAMetalLayer attempts synchronous drawable allocation locks the main thread, leading to Skia command queue starvation, UI freeze, and watchdog crash (0x8badf00d). ```kotlin // BAD: Blocking main thread on Metal drawable acquisition and unbounded Canvas invalidation during navigation @OptIn(ExperimentalComposeUiApi::class) fun configureComposeViewController(viewController: UIViewController) { val composeController = ComposeUIViewController { // Canvas continuously triggers recomposition at unthrottled rates Canvas(modifier = Modifier.fillMaxSize()) { // Triggers heavy Skia rendering on every tick drawPath(path = complexSkiaPath, brush = gradientBrush) } } // Blocking Skiko render loop causes CAMetalLayer deadlocks during interactive pop viewController.presentViewController(composeController, animated = true, completion = null) } ``` #### Production Standard (Correct) > **Standard**: Isolates Skia draw passes during native transition gestures using snapshot caching and non-blocking view controllers, avoiding concurrent lock contention on the CAMetalDrawable queue. ```kotlin // GOOD: Managed lifecycle-aware Skia rendering pipeline with transition fence and CADisplayLink coordination @OptIn(ExperimentalComposeUiApi::class) fun createSafeComposeViewController(coordinator: TransitionCoordinator): UIViewController { return ComposeUIViewController( configure = { // Ensure non-blocking drawable lifecycle opaque = false } ) { val isTransitionActive by coordinator.isTransitionActive.collectAsState() Canvas( modifier = Modifier .fillMaxSize() // Pause continuous invalidation during native navigation push/pop gestures .drawWithCache { if (isTransitionActive) { // Render cached snapshot to eliminate Metal command buffer contention onDrawBehind { drawImage(cachedFrameBitmap) } } else { onDrawBehind { drawPath(path = complexSkiaPath, brush = gradientBrush) } } } ) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Metal/Skia iOS Surface Presentation Synchronization Guardrail

Compose Multiplatform Metal/Skia iOS Surface Presentation Synchronization Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic synchronization between Apple Metal command buffer presentation and Skia GPU drawing contexts in Compose Multiplatform. Prevents CAMetalLayer surface deadlocks, command queue starvation, and catastrophic frame pacing drops during concurrent UIKit navigation controller transitions and active Canvas invalidate loops. 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: Unsynchronized CAMetalDrawable acquisition on the main runloop during concurrent UIKit transitions causing Metal thread deadlocks 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	Unsynchronized CAMetalDrawable acquisition on the main runloop during concurrent UIKit transitions causing Metal thread deadlocks	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 configure Skiko Metal render delegate with non-blocking drawable acquisition timeouts (maximum 16.6ms frame deadline) using `nextDrawable()` with timeout or async render passes.

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.