Compose Multiplatform Skiko Render Frame Pacing on Heterogeneous LTPO Displays

--- description: Compose Multiplatform Skiko Render Frame Pacing on Heterogeneous LTPO Displays - Enforces strict synchronization between Skiko rendering passes and platform vsync pulse mechanisms (CADisplayLink and Choreographer) across 120Hz LTPO and dynamic refresh displays. Prevents frame buffer bloat, micro-stutter, and unbound Skia GPU command allocation caused by unsynchronized recomposition and redraw loops. globs: **/src/**/skiko/**/*.kt, **/src/**/graphics/**/*.kt, **/src/**/platform/**/*.kt, **/src/iosMain/**/*.kt, **/src/androidMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cmp-skiko-render-frame-pacing-invariant" --- # Compose Multiplatform Skiko Render Frame Pacing on Heterogeneous LTPO Displays > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unsynchronized frame ticking and unthrottled redraw scheduling causing frame pacing divergence and Skia surface buffer explosion ## System Constraints You are a Principal Mobile Architect specializing in Compose Multiplatform, Skiko, and low-level graphics subsystems. Mandate strict synchronization between Skiko render execution and native hardware vsync pulses. Reject any unbounded draw loops, unthrottled redraw requests, fixed-interval coroutine tickers, or unconfigured ProMotion/LTPO frame intervals. ## Strict Guidelines - Engineers MUST ALWAYS bind Skiko's `SkiaLayer.needRedraw()` cycles directly to platform-native vsync primitives (`CADisplayLink` on Apple targets, `Choreographer.postFrameCallback` on Android targets). - Engineers MUST NOT utilize synthetic software timers, coroutine-based `delay()` tickers, or detached dispatchers to trigger Skia canvas draw passes. - Engineers MUST configure explicit `CAFrameRateRange` bounds (minimum, preferred, maximum) for Apple ProMotion displays to eliminate frame hitching on dynamic 10Hz-120Hz LTPO rate adjustments. - Components NEVER trigger secondary `needRedraw()` dispatches while a Skiko hardware swap chain frame transaction is actively in-flight on the GPU. - Services MUST throttle dirty region compositions during rapid gesture-driven animations to match the actual display refresh deadline rather than intermediate input polling rates. ## Bad vs Good Implementations ### ProMotion Vsync Integration on iOS Skia Backend #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fixed-interval coroutine loops drift against hardware vsync phases on variable-refresh LTPO displays. This causes multi-frame queuing in Skia, memory bloat from unreleased Metal/Vulkan command buffers, and catastrophic visual micro-stutter. ```kotlin // Anti-pattern: Naive coroutine loop driving render ticks at fixed frequency class PlatformRenderer(private val skiaLayer: org.jetbrains.skiko.SkiaLayer) { private val scope = kotlinx.coroutines.CoroutineScope(kotlinx.coroutines.Dispatchers.Default) fun startRenderLoop() { scope.launch { while (isActive) { skiaLayer.needRedraw() // Fires out of phase with ProMotion refresh deadlines kotlinx.coroutines.delay(8) // Hardcoded 120Hz approximation, creates queue pileup } } } } ``` #### Production Standard (Correct) > **Standard**: Direct CADisplayLink binding locks rendering explicitly to hardware vsync timings. The CAFrameRateRange ensures native dynamic refresh control on LTPO screens without GPU command queue overrun. ```kotlin // Production standard: Hardware-locked CADisplayLink with CAFrameRateRange configuration import platform.QuartzCore.CADisplayLink import platform.QuartzCore.CAFrameRateRangeMake import platform.Foundation.NSRunLoop import platform.Foundation.NSRunLoopCommonModes import org.jetbrains.skiko.SkiaLayer class PlatformRenderer(private val skiaLayer: SkiaLayer) { private var displayLink: CADisplayLink? = null private var isFrameInFlight: Boolean = false fun startRenderLoop() { displayLink = CADisplayLink.displayLinkWithTarget( target = this, selector = platform.objc.sel_registerName("onVsyncTick:") ).apply { // Configure 120Hz ProMotion range for Apple LTPO displays setPreferredFrameRateRange( CAFrameRateRangeMake(minimum = 60.0f, maximum = 120.0f, preferred = 120.0f) ) addToRunLoop(NSRunLoop.mainRunLoop, NSRunLoopCommonModes) } } @platform.objc.ObjCAction fun onVsyncTick(sender: CADisplayLink) { if (!isFrameInFlight) { isFrameInFlight = true skiaLayer.needRedraw() isFrameInFlight = false } } fun stopRenderLoop() { displayLink?.invalidate() displayLink = null } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Skiko Render Frame Pacing on Heterogeneous LTPO Displays

Compose Multiplatform Skiko Render Frame Pacing on Heterogeneous LTPO Displays defines an industrial-grade behavioral standard for mobile engineering. Enforces strict synchronization between Skiko rendering passes and platform vsync pulse mechanisms (CADisplayLink and Choreographer) across 120Hz LTPO and dynamic refresh displays. Prevents frame buffer bloat, micro-stutter, and unbound Skia GPU command allocation caused by unsynchronized recomposition and redraw 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: Unsynchronized frame ticking and unthrottled redraw scheduling causing frame pacing divergence and Skia surface buffer explosion 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 frame ticking and unthrottled redraw scheduling causing frame pacing divergence and Skia surface buffer explosion	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 bind Skiko's `SkiaLayer.needRedraw()` cycles directly to platform-native vsync primitives (`CADisplayLink` on Apple targets, `Choreographer.postFrameCallback` on Android targets).

Engineers MUST ALWAYS bind Skiko's `SkiaLayer.needRedraw()` cycles directly to platform-native vsync primitives (`CADisplayLink` on Apple targets, `Choreographer.postFrameCallback` on Android targets).

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.