Compose Multiplatform iOS CADisplayLink ProMotion Render Loop Synchronization

--- description: Compose Multiplatform iOS CADisplayLink ProMotion Render Loop Synchronization - Enforces strict synchronization between Skiko's Metal surface flushes and iOS CADisplayLink frame callbacks. Mandates the binding of Compose Multiplatform render loops to NSRunLoop common modes with dynamic CAFrameRateRange configurations to eliminate frame tearing, sub-frame jitter, and micro-stutter on Apple ProMotion displays. globs: **/iosMain/**/*.kt, **/iosApp/**/*.swift, **/iosApp/**/*.m alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cmp-ios-cadisplaylink-sync-production-standard" --- # Compose Multiplatform iOS CADisplayLink ProMotion Render Loop Synchronization > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unsynchronized Free-Running Compose Render Dispatchers Decoupled from ProMotion VSync ## System Constraints You are a Principal Mobile Architect specializing in Compose Multiplatform, Skiko, and iOS Graphics Subsystems. Enforce absolute synchronization between Skiko Metal presentation surfaces and Apple's CADisplayLink. Never allow decoupled timer dispatchers, unthrottled coroutine frame pacing, or standard-mode runloop registrations that stall Compose redraws during iOS touch tracking. Ensure ProMotion 120Hz dynamic frame-rate ranges are explicitly negotiated and respected. ## Strict Guidelines - Engineers MUST ALWAYS attach CADisplayLink to NSRunLoop.mainRunLoop using NSRunLoopCommonModes to prevent rendering lockup during UI interactions and scroll tracking. - Engineers MUST configure CAFrameRateRange on iOS 15+ devices with explicit minimum, preferred, and maximum frame rates (e.g., 60-120-120) to support Apple ProMotion dynamic refresh displays natively. - Engineers MUST drive Compose Multiplatform frame dispatchers (e.g., MonotonicFrameClock or Skiko's redraw dispatcher) exclusively through CADisplayLink timestamps (targetTimestamp) rather than monotonic sleep or unthrottled coroutine delays. - Engineers MUST NOT trigger manual or asynchronous surface flush calls outside of the CADisplayLink frame callback cycle. - Engineers MUST invalidate and pause CADisplayLink instances whenever the view controller transitions out of view hierarchy (viewDidDisappear) or when the application enters the background to avoid battery drain and GPU thermal throttling. - Components NEVER instantiate detached DispatchSourceTimer or NSTimer loops to pump Compose recomposition on iOS targets. ## Bad vs Good Implementations ### CADisplayLink Render Loop Configuration for Skiko on iOS #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using arbitrary coroutine delays drift away from hardware VSync, resulting in double-buffering race conditions, dropped frames, and severe micro-stutter. Registering CADisplayLink on NSDefaultRunLoopMode freezes the render loop whenever the user scrolls or interacts with native UI touches, breaking continuity. ```kotlin // BAD: Arbitrary frame pacing via uncoordinated coroutine loop or default runloop mode import kotlinx.coroutines.* import platform.darwin.NSDefaultRunLoopMode import platform.QuartzCore.CADisplayLink import platform.Foundation.NSRunLoop class BadComposeRenderer(private val onFrame: () -> Unit) { // Anti-pattern 1: Launching unthrottled coroutine loop disconnected from VSync private val scope = CoroutineScope(Dispatchers.Main) fun startRenderLoop() { scope.launch { while (isActive) { onFrame() // Misses ProMotion intervals; causes severe micro-stutter delay(8) // Naive 120Hz approximation, guarantees phase drift and frame drops } } } // Anti-pattern 2: Default runloop halts rendering during scroll/touch gestures fun bindDisplayLink() { val displayLink = CADisplayLink.displayLinkWithTarget( target = this, selector = platform.objc.sel_registerName("renderStep:") ) displayLink.addToRunLoop(NSRunLoop.mainRunLoop, forMode = NSDefaultRunLoopMode) } } ``` #### Production Standard (Correct) > **Standard**: Attaches CADisplayLink to NSRunLoopCommonModes to prevent UI freezes during touch gestures. Utilizes CAFrameRateRange to negotiate ProMotion 120Hz display refresh capabilities dynamically and accurately feeds targetTimestamp to Skiko for sub-frame VSync alignment. ```kotlin // GOOD: Production-grade CADisplayLink with ProMotion support and CommonModes registration import kotlinx.cinterop.ExportObjCClass import kotlinx.cinterop.ObjCAction import platform.darwin.NSRunLoopCommonModes import platform.Foundation.NSRunLoop import platform.QuartzCore.CADisplayLink import platform.QuartzCore.CAFrameRateRangeMake import platform.darwin.NSObject @ExportObjCClass class SynchronizedComposeRenderer( private val onFrame: (targetTimestamp: Double) -> Unit ) : NSObject() { private var displayLink: CADisplayLink? = null fun start() { if (displayLink != null) return val link = CADisplayLink.displayLinkWithTarget( target = this, selector = platform.objc.sel_registerName("step:") ) // Configure dynamic ProMotion frame pacing (iOS 15+) link.preferredFrameRateRange = CAFrameRateRangeMake( minimum = 60.0f, maximum = 120.0f, preferred = 120.0f ) // Bind to common modes to ensure rendering persists through gesture interactions link.addToRunLoop(NSRunLoop.mainRunLoop, forMode = NSRunLoopCommonModes) displayLink = link } @ObjCAction fun step(link: CADisplayLink) { // Forward precise hardware target timestamp into Skiko frame pacer onFrame(link.targetTimestamp) } fun stop() { displayLink?.invalidate() displayLink = null } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform iOS CADisplayLink ProMotion Render Loop Synchronization

Compose Multiplatform iOS CADisplayLink ProMotion Render Loop Synchronization defines an industrial-grade behavioral standard for mobile engineering. Enforces strict synchronization between Skiko's Metal surface flushes and iOS CADisplayLink frame callbacks. Mandates the binding of Compose Multiplatform render loops to NSRunLoop common modes with dynamic CAFrameRateRange configurations to eliminate frame tearing, sub-frame jitter, and micro-stutter on Apple ProMotion displays. 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 Free-Running Compose Render Dispatchers Decoupled from ProMotion VSync 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 Free-Running Compose Render Dispatchers Decoupled from ProMotion VSync	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 attach CADisplayLink to NSRunLoop.mainRunLoop using NSRunLoopCommonModes to prevent rendering lockup during UI interactions and scroll tracking.

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.