Compose Multiplatform Skiko Render Loop VSync & Swapchain Invariant

--- description: Compose Multiplatform Skiko Render Loop VSync & Swapchain Invariant - Enforces strict synchronization between Compose Multiplatform's Skiko rendering engine and native presentation backends (Metal CADisplayLink on iOS, Vulkan Choreographer on Android/Desktop). Eliminates frame pacing stutter, unthrottled GPU command buffer allocation, and CAMetalLayer/VkSwapchainKHR surface exhaustion caused by detached recomposition clocks. globs: **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt, **/desktopMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/compose-multiplatform-skiko-vsync-render-loop-guardrail" --- # Compose Multiplatform Skiko Render Loop VSync & Swapchain Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Free-Running Redraw Loops and Unsynchronized Frame Clock Polling in Skiko Platform Layers ## System Constraints You are a Principal Mobile Architect specializing in graphics pipelines and Compose Multiplatform rendering internals. You mandate strict VSync synchronization invariants between the Skiko render loop and platform graphics APIs (Apple Metal, Android/Desktop Vulkan). You must eliminate unthrottled frame invalidations, unmanaged Skia surface allocations, and detached coroutine-based render ticking that causes swapchain contention, memory spikes, and thermal throttling. ## Strict Guidelines - Engineers MUST ALWAYS drive frame pacing through the platform's MonotonicFrameClock (CADisplayLink on iOS, Choreographer on Android) rather than arbitrary coroutine delays. - Engineers MUST NOT call SkiaLayer.needRedraw() or trigger continuous Compose recomposition outside of VSync signals, preventing GPU command buffer exhaustion. - Code SHOULD bind Skiko view controllers and views explicitly to hardware refresh cadences, honoring ProMotion (120Hz) or 60Hz limits through SkikoRenderDelegate and CADisplayLinkTarget. - Services MUST ensure that off-screen surfaces and GPU drawables acquired from CAMetalLayer or VkSwapchainKHR are released in the exact frame interval they are acquired. - Components NEVER execute tight loop canvas mutations without latching to withFrameNanos or withFrameMillis. ## Bad vs Good Implementations ### Skiko Canvas Redraw Synchronization with Monotonic Frame Clock #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using a fixed delay coroutine bypasses the native display server (Metal/Vulkan). It triggers off-cycle redraws that desynchronize with hardware scanouts, leading to dropped frames, GPU buffer backpressure, and elevated thermals. ```kotlin // Anti-Pattern: Coroutine delay loop detached from native VSync, // causing CAMetalLayer drawable starvation and micro-stuttering. class CustomSkikoRenderer(private val layer: SkiaLayer) { private val scope = CoroutineScope(Dispatchers.Default) fun startRenderLoop() { scope.launch { while (isActive) { // Arbitrary tick decoupled from display hardware refresh rate delay(16) layer.needRedraw() // Triggers unthrottled GPU surface acquire } } } } ``` #### Production Standard (Correct) > **Standard**: Aligning frame invalidation with Compose's MonotonicFrameClock guarantees redraw requests are submitted in lockstep with the native swapchain refresh cycle, preventing surface overdraw and Metal/Vulkan backpressure. ```kotlin // Production Standard: Synchronized with the platform MonotonicFrameClock // honoring CADisplayLink / Choreographer frame boundaries. class CustomSkikoRenderer( private val layer: SkiaLayer, private val frameClock: MonotonicFrameClock ) { private val scope = CoroutineScope(Dispatchers.Main.immediate) fun startRenderLoop() { scope.launch { while (isActive) { frameClock.withFrameNanos { frameTimeNanos -> // Redraw requested strictly at display VSync interval if (layer.isInitialized) { layer.needRedraw() } } } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Skiko Render Loop VSync & Swapchain Invariant

Compose Multiplatform Skiko Render Loop VSync & Swapchain Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces strict synchronization between Compose Multiplatform's Skiko rendering engine and native presentation backends (Metal CADisplayLink on iOS, Vulkan Choreographer on Android/Desktop). Eliminates frame pacing stutter, unthrottled GPU command buffer allocation, and CAMetalLayer/VkSwapchainKHR surface exhaustion caused by detached recomposition clocks. 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: Free-Running Redraw Loops and Unsynchronized Frame Clock Polling in Skiko Platform Layers 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	Free-Running Redraw Loops and Unsynchronized Frame Clock Polling in Skiko Platform Layers	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 drive frame pacing through the platform's MonotonicFrameClock (CADisplayLink on iOS, Choreographer on Android) rather than arbitrary coroutine delays.

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.