Compose Multiplatform iOS Native Surface Synchronization Invariant

--- description: Compose Multiplatform iOS Native Surface Synchronization Invariant - Prevents main-thread micro-stutter, frame hitching, and visual tearing by strictly synchronizing Skiko rendering frames with CADisplayLink and iOS CATransaction state transitions. Eliminates out-of-phase Metal surface presentation when embedding UIKit views or coordinating animations between Compose and UIKit layer hierarchies. Mandates explicit frame-pacing hooks and transaction boundaries for all cross-platform surface interactions. globs: **/iosMain/**/*.kt, **/*.ios.kt, **/iosApp/**/*.swift, **/iosApp/**/*.m alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/compose-ios-surface-cadisplaylink-sync" --- # Compose Multiplatform iOS Native Surface Synchronization Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Asynchronous Unsynchronized Skiko Metal Frame Submission Across UIKit Transitions ## System Constraints You are a Principal Engineer enforcing the Compose Multiplatform iOS Native Surface Synchronization Invariant. Mandate invariants that eliminate UI hitches, frame drops, and visual tearing during Skiko rendering and UIKit layer synchronization. You must enforce explicit CADisplayLink frame pacing, disable implicit CoreAnimation actions during interop layout passes, and guarantee atomic CATransaction commits between native views and Skiko Metal surfaces. ## Strict Guidelines - Engineers MUST ALWAYS wrap native UIKit layer mutations occurring within or alongside Compose rendering passes in an explicit CATransaction block with actions disabled (CATransaction.setDisableActions(true)). - Engineers MUST NOT invoke asynchronous Skiko surface redraw requests outside of CADisplayLink VSYNC callbacks or active UI event cycles. - Engineers MUST configure CADisplayLink targetTimestamp and preferredFrameRateRange to respect ProMotion displays (120Hz dynamic refresh) and synchronize Skiko's draw loop with the display hardware. - Code SHOULD enforce atomic layout transitions when resizing ComposeUIViewController host surfaces by invoking CATransaction.flush() and coordinating redraw cycles before UIKit layer presentation. - Components NEVER bridge UIKitView or UIKitViewController without synchronizing frame bounds within the same run-loop turn as the Skiko Metal layer layout pass. ## Bad vs Good Implementations ### Synchronizing Skiko Rendering and UIKit Layer Bounds with CADisplayLink and CATransaction #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating view frames without disabling implicit CATransaction actions causes a mismatch between UIKit's layout animation and the underlying Skiko Metal surface. Firing redraws via DispatchQueue.main.async decouples rendering from CADisplayLink VSYNC, resulting in visible tearing, frame drops, and jitter on 120Hz ProMotion screens. ```swift // BAD: Mutating UIKit frame and scheduling Skiko rendering asynchronously without transaction boundaries final class ComposeSurfaceBridge: UIViewController { private var displayLink: CADisplayLink? private var composeView: UIView! func updateBounds(newFrame: CGRect) { // Implicit CA animations trigger mismatch between Metal buffer and UIKit frame composeView.frame = newFrame // Unsynchronized async rendering schedules out-of-order Metal commit DispatchQueue.main.async { self.triggerSkikoRender() } } private func triggerSkikoRender() { // Unthrottled render call out-of-sync with hardware VSYNC phase } } ``` #### Production Standard (Correct) > **Standard**: Disabling implicit CATransaction actions ensures UIKit layers and Skiko Metal buffers update atomically. Integrating CADisplayLink with explicit ProMotion support (CAFrameRateRange) and .common runloop mode prevents dropped frames and micro-stutter during scrolling and interactive transitions. ```swift // GOOD: Deterministic CATransaction encapsulation synchronized with CADisplayLink VSYNC final class ComposeSurfaceBridge: UIViewController { private var displayLink: CADisplayLink? private var composeView: UIView! func updateBounds(newFrame: CGRect) { CATransaction.begin() CATransaction.setDisableActions(true) composeView.frame = newFrame composeView.layoutIfNeeded() // Force synchronous Metal surface resizing before transaction commit CATransaction.setCompletionBlock { // Optional post-transition synchronization hook } CATransaction.commit() } func setupDisplayLink() { displayLink = CADisplayLink(target: self, selector: #selector(onDisplayLinkTick)) // Support ProMotion dynamic refresh rates displayLink?.preferredFrameRateRange = CAFrameRateRange(minimum: 60, maximum: 120, preferred: 120) displayLink?.add(to: .main, forMode: .common) } @objc private func onDisplayLinkTick(link: CADisplayLink) { CATransaction.begin() CATransaction.setDisableActions(true) // Drive frame dispatch precisely within the hardware VSYNC window link.targetTimestamp CATransaction.commit() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform iOS Native Surface Synchronization Invariant

Compose Multiplatform iOS Native Surface Synchronization Invariant defines an industrial-grade behavioral standard for mobile engineering. Prevents main-thread micro-stutter, frame hitching, and visual tearing by strictly synchronizing Skiko rendering frames with CADisplayLink and iOS CATransaction state transitions. Eliminates out-of-phase Metal surface presentation when embedding UIKit views or coordinating animations between Compose and UIKit layer hierarchies. Mandates explicit frame-pacing hooks and transaction boundaries for all cross-platform surface interactions. 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: Asynchronous Unsynchronized Skiko Metal Frame Submission Across UIKit Transitions 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	Asynchronous Unsynchronized Skiko Metal Frame Submission Across UIKit Transitions	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 wrap native UIKit layer mutations occurring within or alongside Compose rendering passes in an explicit CATransaction block with actions disabled (CATransaction.setDisableActions(true)).

Engineers MUST ALWAYS wrap native UIKit layer mutations occurring within or alongside Compose rendering passes in an explicit CATransaction block with actions disabled (CATransaction.setDisableActions(true)).

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.