Compose Multiplatform SKIKO VSync Pipeline Synchronization Standard

--- description: Compose Multiplatform SKIKO VSync Pipeline Synchronization Standard - Mandates deterministic thread dispatch and VSync lock synchronization between platform display clocks (iOS CADisplayLink and Android Choreographer) and the SKIKO rendering engine in Compose Multiplatform. Prevents main-thread priority inversion, rendering deadlocks, and dropped frame deadlines across variable refresh rate displays. globs: **/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt, **/composeApp/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cmp-skiko-vsync-render-pipeline-standard" --- # Compose Multiplatform SKIKO VSync Pipeline Synchronization Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Uncoordinated VSync dispatch, blocking calls in display callbacks, and unsynchronized SKIKO render requests across native runtimes ## System Constraints You are a Principal Software Architect enforcing the Compose Multiplatform SKIKO Render Pipeline VSync Lock Standard. You must reject any blocking operations, manual lock acquisitions, or out-of-sync redraw scheduling inside VSync callbacks, Kotlin Native render loops, or MonotonicFrameClock implementations. Mandate lock-free message passing, explicit CADisplayLink CommonModes scheduling with ProMotion support, and Dispatchers.Main.immediate synchronization. ## Strict Guidelines - Engineers MUST ALWAYS schedule platform VSync listeners (iOS CADisplayLink) on NSRunLoopCommonModes to prevent UI animation freezing during platform scrolling or gesture tracking. - Engineers MUST NEVER execute blocking calls (such as runBlocking, Mutex.lock, or synchronous file/network I/O) inside MonotonicFrameClock.withFrameNanos or platform VSync callback selectors. - Engineers MUST ALWAYS dispatch frame invalidation and redraw requests (skiaLayer.needRedraw()) through Dispatchers.Main.immediate to eliminate thread hops on the platform native main thread. - Engineers MUST ALWAYS configure dynamic display refresh rate ranges (such as CAFrameRateRange for ProMotion displays on iOS) when instantiating custom SKIKO view controllers or layers. - Engineers MUST NEVER invoke native Metal or OpenGL render calls directly from worker coroutines or background threads without SKIKO RenderDelegate coordination. - Engineers MUST coordinate state reads within Compose snapshot boundaries before VSync deadlines to eliminate tearing and thread contention with the Kotlin/Native garbage collector. ## Bad vs Good Implementations ### DisplayLink VSync Synchronization with SKIKO Layer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Scheduling CADisplayLink exclusively on NSDefaultRunLoopMode pauses rendering during user interactions (scrolls/gestures). Furthermore, invoking runBlocking inside the platform VSync callback starves the main runloop, introduces severe frame jank, and risks hard deadlocks between Kotlin Native runtime locks and the platform Metal compositor. ```kotlin // VIOLATION: Attaches to default runloop mode, blocks VSync thread with runBlocking, // and causes deadlocks between Kotlin/Native GC and the iOS Metal render pipeline. class SkikoVsyncBridge(private val layer: SkiaLayer) { private var displayLink: CADisplayLink? = null fun start() { displayLink = CADisplayLink.displayLinkWithTarget( target = this, selector = NSSelectorFromString("step:") ) // Freezes during UIScrollView tracking because it lacks NSRunLoopCommonModes displayLink?.addToRunLoop(NSRunLoop.currentRunLoop(), NSDefaultRunLoopMode) } @ObjCAction fun step(link: CADisplayLink) { runBlocking(Dispatchers.Default) { // Deadlock risk: Synchronously blocking platform render clock val state = evaluateUiStateBlocking() layer.needRedraw() } } } ``` #### Production Standard (Correct) > **Standard**: The compliant implementation hooks into NSRunLoopCommonModes to ensure rendering persists through active gestures, declares explicit CAFrameRateRange for variable refresh rate displays, and dispatches asynchronously without blocking the platform render thread via Dispatchers.Main.immediate. ```kotlin // COMPLIANT: Uses NSRunLoopCommonModes, configures ProMotion frame rates, // and leverages non-blocking Dispatchers.Main.immediate with MonotonicFrameClock. class SkikoVsyncBridge( private val layer: SkiaLayer, private val scope: CoroutineScope ) { private var displayLink: CADisplayLink? = null fun start() { displayLink = CADisplayLink.displayLinkWithTarget( target = this, selector = NSSelectorFromString("step:") ).apply { // Support iOS ProMotion (120Hz dynamic refresh rates) preferredFrameRateRange = CAFrameRateRangeMake(minimum = 60f, maximum = 120f, preferred = 120f) addToRunLoop(NSRunLoop.mainRunLoop(), NSRunLoopCommonModes) } } @ObjCAction fun step(link: CADisplayLink) { val targetTimestampNanos = (link.targetTimestamp * 1_000_000_000).toLong() scope.launch(Dispatchers.Main.immediate) { layer.update(targetTimestampNanos) layer.needRedraw() } } fun stop() { displayLink?.invalidate() displayLink = null } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform SKIKO VSync Pipeline Synchronization Standard

Compose Multiplatform SKIKO VSync Pipeline Synchronization Standard defines an industrial-grade behavioral standard for mobile engineering. Mandates deterministic thread dispatch and VSync lock synchronization between platform display clocks (iOS CADisplayLink and Android Choreographer) and the SKIKO rendering engine in Compose Multiplatform. Prevents main-thread priority inversion, rendering deadlocks, and dropped frame deadlines across variable refresh rate 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: Uncoordinated VSync dispatch, blocking calls in display callbacks, and unsynchronized SKIKO render requests across native runtimes 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	Uncoordinated VSync dispatch, blocking calls in display callbacks, and unsynchronized SKIKO render requests across native runtimes	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 schedule platform VSync listeners (iOS CADisplayLink) on NSRunLoopCommonModes to prevent UI animation freezing during platform scrolling or gesture 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.