Compose Multiplatform 1.7 Skiko Render Loop & Hardware VSync Synchronization

--- description: Compose Multiplatform 1.7 Skiko Render Loop & Hardware VSync Synchronization - Enforces strict hardware VSync alignment for Skiko software and hardware-accelerated rasterization across non-JVM native targets such as iOS and macOS. Eliminates multi-buffering desynchronization, micro-stutters, and main-thread rendering stalls by replacing continuous coroutine-based render polling with platform-native display link callbacks and coalesced invalidations. globs: **/iosMain/**/*.kt, **/appleMain/**/*.kt, **/nativeMain/**/*.kt, **/*ViewController*.kt, **/*Redrawer*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cmp-skiko-vsync-render-loop-synchronization" --- # Compose Multiplatform 1.7 Skiko Render Loop & Hardware VSync Synchronization > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Bypassing Native Hardware VSync with Coroutine Delays or Continuous Polling Redrawers ## System Constraints You are a Principal Software Architect enforcing Compose Multiplatform 1.7 Skiko Render Loop VSync Synchronization. You must ensure that non-JVM native targets (especially iOS Metal and Darwin targets) strictly bind their rasterization cycles to hardware display refresh signals (e.g., CADisplayLink, MetalRedrawer) without spinning unthrottled render loops or using artificial coroutine delays. ## Strict Guidelines - Engineers MUST ALWAYS delegate draw invalidation to Skiko's platform-native redrawer or ComposeScene's native display link rather than invoking manual rendering from coroutines. - Engineers MUST NOT use unconstrained `delay(16)` or busy-wait loops in `CoroutineScope` to trigger frame redraws across non-JVM native targets. - Code SHOULD configure `CADisplayLink.preferredFrameRateRange` explicitly to support Apple ProMotion dynamic refresh rates (up to 120Hz) while permitting power downscaling down to 10Hz/24Hz when idle. - Services MUST coalesce multiple dirty-state mutations into a single `needRedraw()` invalidation mark before the subsequent VSync deadline. - Components NEVER execute blocking CPU-bound tasks, synchronous I/O, or broad lock acquisitions inside the Skiko rasterization and swap-chain presentation callback. ## Bad vs Good Implementations ### Hardware VSync DisplayLink Integration for Compose Multiplatform iOS #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Bypasses the underlying CADisplayLink hardware refresh cycle. Using fixed coroutine delays results in drift relative to the physical screen refresh phase, dropped presentation deadlines, tearing, and high idle battery drain on ProMotion screens. ```kotlin import kotlinx.coroutines.* import androidx.compose.ui.scene.ComposeScene class CustomIosRenderer(private val scene: ComposeScene) { private val scope = CoroutineScope(Dispatchers.Main) fun startRenderLoop() { // CRITICAL DEFECT: Artificial frame pacing via coroutine delay introduces // display drift, misses hardware VSync ticks, and causes severe frame judder. scope.launch { while (isActive) { scene.render() delay(16) // Drifts relative to 60Hz/120Hz ProMotion displays } } } } ``` #### Production Standard (Correct) > **Standard**: Leverages Compose Multiplatform 1.7's internal MetalRedrawer pipeline bound to CADisplayLink on the common runloop mode. Invalidations are queued to hardware VSync phase ticks, natively accommodating Apple ProMotion variable refresh rates. ```kotlin import platform.QuartzCore.CADisplayLink import platform.Foundation.NSRunLoop import platform.Foundation.NSRunLoopCommonModes import platform.darwin.NSObject import platform.objc.sel_registerName import androidx.compose.ui.window.ComposeUIViewController import androidx.compose.ui.uikit.OnFocusBehavior import platform.UIKit.UIViewController fun createOptimizedComposeViewController(): UIViewController { // Native ComposeUIViewController configures Skiko MetalRedrawer natively // hooked into CADisplayLink and ProMotion display targets. return ComposeUIViewController( configure = { onFocusBehavior = OnFocusBehavior.DoNothing // Skiko in CMP 1.7 internally delegates to DisplayLink-driven dirty invalidation // preserving hardware VSync alignment without manual coroutine render pumping. } ) { // App Composable hierarchy } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform 1.7 Skiko Render Loop & Hardware VSync Synchronization

Compose Multiplatform 1.7 Skiko Render Loop & Hardware VSync Synchronization defines an industrial-grade behavioral standard for mobile engineering. Enforces strict hardware VSync alignment for Skiko software and hardware-accelerated rasterization across non-JVM native targets such as iOS and macOS. Eliminates multi-buffering desynchronization, micro-stutters, and main-thread rendering stalls by replacing continuous coroutine-based render polling with platform-native display link callbacks and coalesced invalidations. 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: Bypassing Native Hardware VSync with Coroutine Delays or Continuous Polling Redrawers 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	Bypassing Native Hardware VSync with Coroutine Delays or Continuous Polling Redrawers	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 delegate draw invalidation to Skiko's platform-native redrawer or ComposeScene's native display link rather than invoking manual rendering from coroutines.

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.