Compose Multiplatform Skiko Frame-Pacing & VSync Invariant

--- description: Compose Multiplatform Skiko Frame-Pacing & VSync Invariant - Enforces hardware VSync synchronization across Compose Multiplatform targets using Skiko (iOS CADisplayLink, Android Choreographer, desktop refresh hooks). Prevents GPU buffer queue exhaustion and frame dropping by disallowing unmetered manual redraw dispatch and decoupled coroutine render loops. globs: **/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt, **/jvmMain/**/*.kt, **/commonMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/compose-skiko-vsync-frame-pacing-invariant" --- # Compose Multiplatform Skiko Frame-Pacing & VSync Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Decoupled Timed Coroutine Polling and Unthrottled needRedraw() Invocation in Skiko Render Loop ## System Constraints You are a Principal Software Architect enforcing the Compose Multiplatform Skiko Frame-Pacing & VSync Invariant. Compose Multiplatform relies on Skiko for low-level Skia rendering. Engineers often introduce micro-stutter, jank, 120Hz ProMotion failure, or GPU swapchain memory exhaustion by driving UI updates through unconstrained coroutine loops (e.g., while(isActive) { delay(8); needRedraw() }) or misconfiguring Skiko's render delegates. You MUST enforce direct binding between native platform display links (CADisplayLink on iOS, Choreographer on Android) and the Skiko rendering pipeline, guaranteeing exactly one in-flight frame per display refresh tick. ## Strict Guidelines - Engineers MUST NEVER drive Skiko redraw requests (`needRedraw()`) via fixed-delay coroutine loops (`delay(8)` or `delay(16)`). - Engineers MUST bind render loop invalidations to platform-native hardware VSync primitives (`CADisplayLink` on Apple targets, `Choreographer` on Android, presentation clock on Desktop). - Engineers MUST cap in-flight GPU swapchain frames to a maximum depth of 1 or 2 (triple buffering max), dropping stale redraw requests when a frame is currently in transit to Skia surface presentation. - Engineers MUST configure `SkikoProperties.vsyncEnabled` to `true` and verify that ProMotion (120Hz) dynamic display modes pass continuous frame duration metadata through `DisplayLink.preferredFrameRateRange`. - Engineers MUST NOT execute blocking computations or synchronous disk/network I/O inside the Skiko rendering callback or `onRender` surface pass. - Components MUST delegate dirty-region invalidation through the platform Compose snapshot system rather than forcing global Canvas redraw passes. ## Bad vs Good Implementations ### Hardware VSync Frame Pacing vs. Unconstrained Polling Loop #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using a coroutine ticker with fixed delay decouples rendering from the hardware rasterization scanout. It leads to tearing, dropped frames at 120Hz, and runaway memory usage when Skia cannot drain queued render commands fast enough. ```kotlin // Anti-pattern: Synthetic ticker coroutine loop driving render updates // Causes severe GPU buffer thrashing, breaks 120Hz ProMotion, and desyncs with hardware VSync class CustomSkikoRenderer(private val skiaLayer: SkiaLayer, private val scope: CoroutineScope) { fun startRenderLoop() { scope.launch(Dispatchers.Default) { while (isActive) { // Blindly requesting redraw at fixed intervals skiaLayer.needRedraw() delay(8) // Fails to hit variable refresh rate (60Hz-120Hz) synchronously } } } } ``` #### Production Standard (Correct) > **Standard**: Binds frame invalidation directly to CADisplayLink synchronized with NSRunLoopCommonModes. Utilizes an atomic in-flight guard to prevent Skiko queue flooding and respects native 120Hz ProMotion timing intervals. ```kotlin // Production Standard: Native CADisplayLink / Choreographer synchronization with single in-flight guard import platform.QuartzCore.CADisplayLink import platform.Foundation.NSRunLoop import platform.Foundation.NSRunLoopCommonModes import org.jetbrains.skiko.SkiaLayer import kotlinx.atomicfu.atomic class HardwareVsyncSkikoPacer( private val skiaLayer: SkiaLayer ) { private val isFrameInFlight = atomic(false) private var displayLink: CADisplayLink? = null fun attachDisplayLink() { displayLink = CADisplayLink.displayLinkWithTarget( target = this, selector = platform.objc.sel_registerName("onVsyncTick:") ).apply { // Opt-in to high refresh rates (120Hz ProMotion) addToRunLoop(NSRunLoop.mainRunLoop, NSRunLoopCommonModes) } } @platform.objc.ObjCSignatureOverride fun onVsyncTick(link: CADisplayLink) { // Guard against GPU buffer queue exhaustion if (isFrameInFlight.compareAndSet(expect = false, update = true)) { skiaLayer.needRedraw() } } fun onFrameRendered() { isFrameInFlight.value = false } fun detach() { displayLink?.invalidate() displayLink = null } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Skiko Frame-Pacing & VSync Invariant

Compose Multiplatform Skiko Frame-Pacing & VSync Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces hardware VSync synchronization across Compose Multiplatform targets using Skiko (iOS CADisplayLink, Android Choreographer, desktop refresh hooks). Prevents GPU buffer queue exhaustion and frame dropping by disallowing unmetered manual redraw dispatch and decoupled coroutine render loops. 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: Decoupled Timed Coroutine Polling and Unthrottled needRedraw() Invocation in Skiko Render Loop 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	Decoupled Timed Coroutine Polling and Unthrottled needRedraw() Invocation in Skiko Render Loop	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 NEVER drive Skiko redraw requests (`needRedraw()`) via fixed-delay coroutine loops (`delay(8)` or `delay(16)`).

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.