AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
mobilecritical PriorityID: kmp-skiko-cadisplaylink-promotion-sync

KMP Skiko Metal Surface CADisplayLink ProMotion Frame Synchronization Guardrail

Enforces strict temporal lockstep between Skiko's CAMetalLayer drawing pipeline and iOS CADisplayLink targets up to 120Hz ProMotion. Prevents frame dropping, micro-stutter, and torn presentation intervals during cross-platform Compose Multiplatform view transitions and interactive navigation gestures.

Prohibited Anti-Pattern: Decoupled Unsynchronized Metal Rendering Loop on iOS RunLoops Causing Jitter and 60Hz Caps

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: KMP Skiko Metal Surface CADisplayLink ProMotion Frame Synchronization Guardrail - Enforces strict temporal lockstep between Skiko's CAMetalLayer drawing pipeline and iOS CADisplayLink targets up to 120Hz ProMotion. Prevents frame dropping, micro-stutter, and torn presentation intervals during cross-platform Compose Multiplatform view transitions and interactive navigation gestures.
globs: **/iosMain/**/*.kt, **/iosApp/**/*.swift, **/skiko/**/*.kt, **/view/**/*.kt
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/kmp-skiko-cadisplaylink-promotion-sync"
---

# KMP Skiko Metal Surface CADisplayLink ProMotion Frame Synchronization Guardrail

> **Severity**: CRITICAL | **Category**: mobile
> **Anti-Pattern Warning**: Decoupled Unsynchronized Metal Rendering Loop on iOS RunLoops Causing Jitter and 60Hz Caps

## System Constraints
You are a Principal Mobile Systems Architect specializing in Kotlin Multiplatform (KMP), Compose Multiplatform, and Apple Metal graphics rendering. Your objective is to enforce frame-rate pacing invariants between the Skiko graphics backend and iOS CADisplayLink. You must eliminate all instances of arbitrary dispatch timers, desynchronized render loops, unbounded presentDrawable calls, and missing CAFrameRateRange configurations on Apple ProMotion displays.

## Strict Guidelines
- Engineers MUST ALWAYS configure `CAFrameRateRange` explicitly with `minimum`, `maximum`, and `preferred` set to 120.0f on supported ProMotion displays when initializing `CADisplayLink` for ComposeUIViewController or SkikoUIView.
- Engineers MUST ALWAYS attach the `CADisplayLink` instance to `NSRunLoop.mainRunLoop` using `NSRunLoopCommonModes` to prevent frame delivery starvation during user-driven scroll or interactive navigation gestures.
- Engineers MUST NOT invoke `CAMetalDrawable.present()` synchronously inside background dispatch queues without synchronization against the `CADisplayLink` timestamp and targetTimestamp delta.
- Render pipelines MUST synchronise Skiko draw passes with `CADisplayLink.targetTimestamp` using vsync alignment, ensuring that `MTLCommandBuffer.presentAtTime` is explicitly scheduled to prevent double-buffering race conditions.
- Engineers MUST ALWAYS tear down and invalidate `CADisplayLink` instances immediately upon `viewWillDisappear` or `deinit` to prevent cyclic retain references between Skiko target delegates and the native rendering engine.

## Bad vs Good Implementations
### Kotlin/Native Skiko CADisplayLink Setup for ProMotion Dynamic Refresh

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Using NSDefaultRunLoopMode halts rendering during touch tracking (user interaction), causing severe frame stutter during gestures. Omitting CAFrameRateRange locks the display link to a baseline 60Hz, failing to utilize iOS 120Hz ProMotion capabilities.
```kotlin
// BAD: Naive display timer using default 60Hz loop without ProMotion ranges
import platform.QuartzCore.CADisplayLink
import platform.Foundation.NSRunLoop
import platform.Foundation.NSDefaultRunLoopMode

class SkikoFramePacer(private val onRender: () -> Unit) {
    private var displayLink: CADisplayLink? = null

    fun start() {
        // Defaults to 60Hz, pauses during active touch tracking due to NSDefaultRunLoopMode
        displayLink = CADisplayLink.displayLinkWithTarget(
            target = this,
            selector = platform.objc.sel_registerName("step:")
        )
        displayLink?.addToRunLoop(NSRunLoop.currentRunLoop, NSDefaultRunLoopMode)
    }

    @platform.objc.ObjCAction
    fun step(link: CADisplayLink) {
        onRender()
    }
}
```

#### Production Standard (Correct)
> **Standard**: Configures CAFrameRateRange with a 120Hz ceiling and preferred targets for ProMotion hardware. Adding the link to NSRunLoopCommonModes prevents starvation during touch and navigation gestures, while targetTimestamp provides strict frame scheduling bounds for Metal command buffers.
```kotlin
// GOOD: ProMotion-aware CADisplayLink bound to NSRunLoopCommonModes with CAFrameRateRange
import platform.QuartzCore.*
import platform.Foundation.NSRunLoop
import platform.Foundation.NSRunLoopCommonModes
import platform.darwin.NSObject
import kotlinx.cinterop.ExperimentalForeignApi

@OptIn(ExperimentalForeignApi::class)
class SkikoMetalFrameSynchronizer(
    private val onVsync: (targetTimestamp: Double) -> Unit
) : NSObject() {
    private var displayLink: CADisplayLink? = null

    fun attach() {
        displayLink?.invalidate()
        val link = CADisplayLink.displayLinkWithTarget(
            target = this,
            selector = platform.objc.sel_registerName("renderFrame:")
        )

        // Explicitly set 120Hz ProMotion frame pacing range
        link.preferredFrameRateRange = CAFrameRateRangeMake(
            minimum = 60.0f,
            maximum = 120.0f,
            preferred = 120.0f
        )

        // NSRunLoopCommonModes guarantees ticks execute during scroll and gestures
        link.addToRunLoop(NSRunLoop.mainRunLoop, NSRunLoopCommonModes)
        displayLink = link
    }

    @platform.objc.ObjCAction
    fun renderFrame(sender: CADisplayLink) {
        onVsync(sender.targetTimestamp)
    }

    fun detach() {
        displayLink?.invalidate()
        displayLink = null
    }
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Xcode Instruments Trace Analyzer
Analyzes CoreAnimation and Metal System Traces for missed vsync deadlines and render thread preemption.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Metal CADisplayLink Inspector
Validates that all Kotlin/Native CADisplayLink bindings target NSRunLoopCommonModes and configure ProMotion frame rate ranges.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Skiko Metal Surface CADisplayLink ProMotion Frame Synchronization Guardrail

KMP Skiko Metal Surface CADisplayLink ProMotion Frame Synchronization Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict temporal lockstep between Skiko's CAMetalLayer drawing pipeline and iOS CADisplayLink targets up to 120Hz ProMotion. Prevents frame dropping, micro-stutter, and torn presentation intervals during cross-platform Compose Multiplatform view transitions and interactive navigation gestures. 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 Unsynchronized Metal Rendering Loop on iOS RunLoops Causing Jitter and 60Hz Caps 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftDecoupled Unsynchronized Metal Rendering Loop on iOS RunLoops Causing Jitter and 60Hz CapsCritical
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 InconsistencyAI 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:

1

Engineers MUST ALWAYS configure `CAFrameRateRange` explicitly with `minimum`, `maximum`, and `preferred` set to 120.0f on supported ProMotion displays when initializing `CADisplayLink` for ComposeUIViewController or SkikoUIView.

Engineers MUST ALWAYS configure `CAFrameRateRange` explicitly with `minimum`, `maximum`, and `preferred` set to 120.0f on supported ProMotion displays when initializing `CADisplayLink` for ComposeUIViewController or SkikoUIView.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST ALWAYS attach the `CADisplayLink` instance to `NSRunLoop.mainRunLoop` using `NSRunLoopCommonModes` to prevent frame delivery starvation during user-driven scroll or interactive navigation gestures.

Engineers MUST ALWAYS attach the `CADisplayLink` instance to `NSRunLoop.mainRunLoop` using `NSRunLoopCommonModes` to prevent frame delivery starvation during user-driven scroll or interactive navigation gestures.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Engineers MUST NOT invoke `CAMetalDrawable.present()` synchronously inside background dispatch queues without synchronization against the `CADisplayLink` timestamp and targetTimestamp delta.

Engineers MUST NOT invoke `CAMetalDrawable.present()` synchronously inside background dispatch queues without synchronization against the `CADisplayLink` timestamp and targetTimestamp delta.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Render pipelines MUST synchronise Skiko draw passes with `CADisplayLink.targetTimestamp` using vsync alignment, ensuring that `MTLCommandBuffer.presentAtTime` is explicitly scheduled to prevent double-buffering race conditions.

Render pipelines MUST synchronise Skiko draw passes with `CADisplayLink.targetTimestamp` using vsync alignment, ensuring that `MTLCommandBuffer.presentAtTime` is explicitly scheduled to prevent double-buffering race conditions.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Engineers MUST ALWAYS tear down and invalidate `CADisplayLink` instances immediately upon `viewWillDisappear` or `deinit` to prevent cyclic retain references between Skiko target delegates and the native rendering engine.

Engineers MUST ALWAYS tear down and invalidate `CADisplayLink` instances immediately upon `viewWillDisappear` or `deinit` to prevent cyclic retain references between Skiko target delegates and the native rendering engine.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is KMP Skiko Metal Surface CADisplayLink ProMotion Frame Synchronization Guardrail critical for AI coding assistants?

Enforces strict temporal lockstep between Skiko's CAMetalLayer drawing pipeline and iOS CADisplayLink targets up to 120Hz ProMotion. Prevents frame dropping, micro-stutter, and torn presentation intervals during cross-platform Compose Multiplatform view transitions and interactive navigation gestures. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Decoupled Unsynchronized Metal Rendering Loop on iOS RunLoops Causing Jitter and 60Hz Caps) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related MOBILE Rules

View all rules →
mobile
106

Tauri 2.0 Mobile IPC & Capabilities Permissions Matrix Standard

Tauri v2 introduces a capability-driven permissions system replacing legacy v1 allowlists across iOS and Android runtimes. Failure to constrain IPC command handlers with typed schemas and explicit mobile capability definitions exposes native mobile OS surfaces to arbitrary code execution, permission leakage, and silent serialization failures. Production mobile deployments require strictly typed IPC boundary validation, granular capability scopes, and graceful permission degradation.

mobile
70

Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard

Capacitor 7 enforces strict bridge lifecycle contracts, asynchronous native plugin interop, and mandatory Android 15 edge-to-edge window inset handling. Storing sensitive authentication tokens in unencrypted web storage or failing to bind biometric authentication directly to hardware-backed Keystore or Secure Enclave mechanisms compromises app integrity and causes fatal crash or viewport occlusion issues on modern mobile operating systems.

mobile
58

Tauri 2.0 Mobile IPC Isolation and Capabilities Permission Scoping

Enforces strict capability permission boundaries, payload validation, and secure IPC invoke scoping for Tauri v2 Android and iOS environments. Prevents arbitrary IPC command execution, excessive native privilege granting, and deserialization vulnerabilities across the mobile webview-native boundary.

1 Rule in Stack

KMP