Compose Multiplatform iOS CADisplayLink & ProMotion VSync Cadence Synchronization

--- description: Compose Multiplatform iOS CADisplayLink & ProMotion VSync Cadence Synchronization - Enforces rigid synchronization between Skiko's Metal rendering pipeline and iOS CADisplayLink VSync pulses. Prevents continuous unthrottled GPU render loops and frame pacing jitter by binding redraw invalidations strictly to ProMotion refresh rate targets and on-demand dirty state transitions. globs: **/iosMain/**/*.kt, **/*Ios*.kt, **/*Redrawer*.kt, **/*ViewController*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/compose-ios-cadisplaylink-cadence-sync" --- # Compose Multiplatform iOS CADisplayLink & ProMotion VSync Cadence Synchronization > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Free-Running Dispatch Loops and Unsynchronized VSync Invalidation in Skiko Metal ViewControllers ## System Constraints You are a Principal Mobile Architect enforcing Compose Multiplatform rendering invariants on iOS. Mandate deterministic CADisplayLink synchronization with Skiko's Metal pipeline, proper CAFrameRateRange configuration for ProMotion dynamic refresh rates (10Hz-120Hz), and strict idle state pausing to eliminate thermal runaway and micro-stutter. ## Strict Guidelines - Engineers MUST ALWAYS attach CADisplayLink instances to NSRunLoop.mainRunLoop using NSRunLoopCommonModes to ensure continuous rendering during touch tracking and scrolling. - Engineers MUST NOT invoke Skiko redraw routines via free-running coroutine loops, NSTimer, or unconstrained DispatchQueue calls. - Engineers MUST configure preferredFrameRateRange (minimum, preferred, maximum) via CAFrameRateRange on iOS 15+ to properly leverage Apple ProMotion high-refresh screens without locking the GPU to an inefficient static 60Hz or draining battery at static 120Hz. - Code MUST pause CADisplayLink (isPaused = true) whenever Compose reports no pending snapshot mutations, layout passes, or running animations. - Code MUST coordinate Metal command buffer presentation with CADisplayLink targetTimestamp to prevent presentation deadline misses and temporal jank. - Components NEVER trigger needRedraw() inside draw callbacks without an active transient animation state, preventing infinite invalidation loops. ## Bad vs Good Implementations ### Configuring Synchronized CADisplayLink with ProMotion Frame Pacing in Kotlin/Native #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using a coroutine loop with delay(16) disregards the iOS hardware VSync cycle, causes presentation tearing, drifts relative to the display scanout, forces 60 FPS on 120 FPS ProMotion devices, and fails to yield cycles when the scene is static. ```kotlin // BAD: Polling render loop using coroutine delays without CADisplayLink synchronization class NaiveIosComposeRedrawer( private val onRender: () -> Unit ) { private val scope = CoroutineScope(Dispatchers.Main) private var running = false fun start() { running = true scope.launch { while (running) { // Causes severe micro-stutter, ignores VSync, and wastes GPU/CPU cycles onRender() delay(16) // Hardcoded 60 FPS assumption; breaks ProMotion 120Hz & drains power } } } fun stop() { running = false } } ``` #### Production Standard (Correct) > **Standard**: Attaches to NSRunLoopCommonModes for uninterrupted tracking, configures CAFrameRateRange for ProMotion 120Hz support, synchronizes execution with the target VSync timestamp, and pauses CADisplayLink immediately when the scene returns to idle. ```kotlin // GOOD: Production CADisplayLink binding with ProMotion dynamic refresh and idle pausing import platform.QuartzCore.CADisplayLink import platform.Foundation.NSRunLoop import platform.Foundation.NSRunLoopCommonModes import platform.QuartzCore.CAFrameRateRangeMake import platform.darwin.NSObject import kotlinx.cinterop.ExperimentalForeignApi import kotlinx.cinterop.ObjCAction @OptIn(ExperimentalForeignApi::class) class SynchronizedMetalRedrawer( private val drawFrame: (targetTimestamp: Double) -> Boolean // Returns true if subsequent frame requested ) : NSObject() { private var displayLink: CADisplayLink? = null private var isDirty: Boolean = false fun start() { if (displayLink != null) return val link = CADisplayLink.displayLinkWithTarget( target = this, selector = platform.objc.sel_registerName("step:") ) // Support dynamic ProMotion display ranges (minimum, preferred, maximum) link.preferredFrameRateRange = CAFrameRateRangeMake( minimum = 60f, preferred = 120f, maximum = 120f ) // NSRunLoopCommonModes ensures callbacks continue during touch tracking/scroll gestures link.addToRunLoop(NSRunLoop.mainRunLoop, NSRunLoopCommonModes) link.paused = false displayLink = link } fun scheduleRedraw() { isDirty = true displayLink?.paused = false } @ObjCAction fun step(link: CADisplayLink) { if (!isDirty) { link.paused = true return } // Render synchronized with hardware VSync and re-evaluate dirty state val needsNextFrame = drawFrame(link.targetTimestamp) isDirty = needsNextFrame if (!needsNextFrame) { link.paused = true } } fun dispose() { displayLink?.invalidate() displayLink = null } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform iOS CADisplayLink & ProMotion VSync Cadence Synchronization

Compose Multiplatform iOS CADisplayLink & ProMotion VSync Cadence Synchronization defines an industrial-grade behavioral standard for mobile engineering. Enforces rigid synchronization between Skiko's Metal rendering pipeline and iOS CADisplayLink VSync pulses. Prevents continuous unthrottled GPU render loops and frame pacing jitter by binding redraw invalidations strictly to ProMotion refresh rate targets and on-demand dirty state transitions. 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 Dispatch Loops and Unsynchronized VSync Invalidation in Skiko Metal ViewControllers 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 Dispatch Loops and Unsynchronized VSync Invalidation in Skiko Metal ViewControllers	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 instances to NSRunLoop.mainRunLoop using NSRunLoopCommonModes to ensure continuous rendering during touch tracking and scrolling.

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.