Skiko Frame Pacing and Native VSync Lock Invariant

--- description: Skiko Frame Pacing and Native VSync Lock Invariant - Enforces deterministic VSync synchronization between native hardware refresh cycles (CADisplayLink on iOS, platform display clocks on Desktop) and Skiko's Skia-backed rendering pipelines. Prevents frame tearing, dropped redraw buffers, jitter, and excessive GPU queue depth caused by unsynchronized polling loops or decoupled coroutine render drivers. globs: **/iosApp/**/*.kt, **/desktopMain/**/*.kt, **/skikoMain/**/*.kt, **/ui/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/skiko-vsync-frame-pacing-guardrail" --- # Skiko Frame Pacing and Native VSync Lock Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Decoupled Coroutine Loop or Unthrottled Polling Driving Skiko Canvas Redraws ## System Constraints You are a Principal Mobile Architect specializing in Compose Multiplatform and graphics engines. You must enforce strict hardware-bound VSync pacing between native display pipelines and the Skiko rendering engine. Reject any implementation that uses arbitrary coroutine delays (e.g., delay(16)), timer loops, or unconstrained render invalidation calls outside the platform's synchronized display callbacks. ## Strict Guidelines - Engineers MUST ALWAYS bind Skiko draw invalidation directly to native display signals (CADisplayLink on iOS, CVDisplayLink on macOS, or platform-managed swap chains). - Engineers MUST NOT trigger Skiko render passes inside autonomous coroutines using fixed time steps like `delay(16)` or unconstrained `while(isActive)` loops. - Code MUST throttle Skia canvas invalidations when the window or view is hidden, occluded, or running in background state to eliminate GPU wake-locks. - Services MUST ensure that frame timestamps passed to animations originate from native hardware clock ticks rather than host system wall time (`currentTimeMillis()`). - Components NEVER execute blocking operations, file I/O, or heavy recomposition allocations within the synchronized `onRender` or Skiko draw callbacks. ## Bad vs Good Implementations ### Decoupled Coroutine Loop vs. Hardware-Synchronized Render Driver #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using arbitrary coroutine delays causes phase drift relative to the native refresh rate, missing VSync boundaries. It ignores variable refresh displays (such as Apple ProMotion at 120Hz) and triggers redundant buffer allocations or frame drops. ```kotlin class CoroutineRenderDriver(private val layer: SkiaLayer) { private val scope = CoroutineScope(Dispatchers.Default) fun startRendering() { scope.launch { while (isActive) { // Anti-pattern: Fixed delay introduces drift, frame pacing jitter, and GPU queue bloat layer.needRedraw() delay(16) // Assumes 60Hz and ignores ProMotion (120Hz) or 90Hz hardware displays } } } } ``` #### Production Standard (Correct) > **Standard**: Synchronizing Skiko redraws with `CADisplayLink` guarantees deterministic alignment with iOS hardware refresh cycles (including 60Hz and 120Hz ProMotion), minimizes GPU queue latency, and eliminates micro-stutters. ```kotlin import platform.QuartzCore.CADisplayLink import platform.Foundation.NSRunLoop import platform.Foundation.NSRunLoopCommonModes import org.jetbrains.skiko.SkiaLayer class HardwareVsyncRenderDriver( private val layer: SkiaLayer ) { private var displayLink: CADisplayLink? = null fun startRendering() { // Production Invariant: Synchronize redraw requests directly with native CADisplayLink ticks displayLink = CADisplayLink.displayLinkWithTarget( target = this, selector = platform.objc.sel_registerName("onDisplayTick:") ).apply { addToRunLoop(NSRunLoop.mainRunLoop, NSRunLoopCommonModes) } } @platform.objc.ObjCAction fun onDisplayTick(link: CADisplayLink) { // Skiko consumes the hardware frame timestamp, maintaining zero phase drift layer.needRedraw() } fun stopRendering() { displayLink?.invalidate() displayLink = null } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Skiko Frame Pacing and Native VSync Lock Invariant

Skiko Frame Pacing and Native VSync Lock Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic VSync synchronization between native hardware refresh cycles (CADisplayLink on iOS, platform display clocks on Desktop) and Skiko's Skia-backed rendering pipelines. Prevents frame tearing, dropped redraw buffers, jitter, and excessive GPU queue depth caused by unsynchronized polling loops or decoupled coroutine render drivers. 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 Coroutine Loop or Unthrottled Polling Driving Skiko Canvas Redraws 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 Coroutine Loop or Unthrottled Polling Driving Skiko Canvas Redraws	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 draw invalidation directly to native display signals (CADisplayLink on iOS, CVDisplayLink on macOS, or platform-managed swap chains).

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.