Compose Multiplatform Hardware VSync Render Pipeline Quarantine

--- description: Compose Multiplatform Hardware VSync Render Pipeline Quarantine - Enforces strict isolation between Compose Multiplatform layout measurement phases and Skiko hardware VSync presentation threads during high-frequency native list virtualization. Prohibits synchronous recomposition, expensive measure passes, and unbounded layout allocations directly inside Skiko rendering and CADisplayLink callbacks. Guarantees 60/120 FPS frame pacing across native iOS and Desktop targets by isolating frame rendering from layout evaluation. globs: **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/desktopMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cmp-skiko-vsync-render-pipeline-quarantine" --- # Compose Multiplatform Hardware VSync Render Pipeline Quarantine > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Saturating Skiko Presentation Loops with Synchronous Subcomposition and Layout Measure Passes ## System Constraints You are a Principal Software Architect enforcing zero-jank Skiko rendering invariants in Compose Multiplatform. You must quarantine the Skiko hardware VSync presentation pipeline from synchronous list layout measurement, subcomposition, and off-thread state thrashing. Mandate derived state memoization, stable item identity keys, asynchronous item pre-measuring, and strict avoidance of inline allocation in Skiko draw routines. ## Strict Guidelines - Engineers MUST ALWAYS supply explicit, immutable, and unique identity keys to LazyList items (e.g., `LazyColumn`, `LazyRow`) to prevent positional recomposition during rapid scroll velocities. - Engineers MUST NEVER invoke synchronous measurement blocks, un-memoized `SubcomposeLayout`, or dynamic layout tree queries inside draw dispatch or active VSync render intervals. - Engineers MUST isolate Skiko CADisplayLink ticks from item state evaluation by wrapping non-trivial scroll calculations in `derivedStateOf` with explicit structural equality contracts. - Code SHOULD pre-measure dynamic item dimensions using dedicated asynchronous measurement buffers or persistent item size heuristics before items cross the active Skiko viewport frustum. - Components NEVER perform synchronous I/O, regex parsing, heavy collection transformations, or object allocations inside `onDrawBehind`, `DrawScope`, or `LayoutModifierNode.measure` implementations executed during virtualization. ## Bad vs Good Implementations ### LazyColumn Item Virtualization with Skiko VSync Contention vs Quarantined Measure Pipeline #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting persistent item keys causes Compose Multiplatform to thrash node identity during fast scroll. Calling filter/sort directly in the composition body recalculates on every snapshot tick, and nesting `BoxWithConstraints` introduces nested `SubcomposeLayout` measure passes directly onto the Skiko rendering thread, dropping hardware VSync frames on iOS and Desktop. ```kotlin // BAD: Un-keyed LazyColumn with dynamic subcomposition and allocations inside measure phase @Composable fun VirtualizedEventFeed(feedState: FeedState, modifier: Modifier = Modifier) { // Recalculates dynamically every frame tick on the main UI/Skiko thread val items = feedState.events.filter { it.isVisible }.sortedBy { it.timestamp } LazyColumn(modifier = modifier) { // Missing stable keys forces CMP to rebuild layout nodes during rapid VSync ticks items(items.size) { index -> val item = items[index] // Dynamic subcomposition inside virtualization forces synchronous layout during CADisplayLink callback BoxWithConstraints { val dynamicPadding = if (maxWidth > 300.dp) 16.dp else 8.dp Text( text = "Event: ${item.title} - ${item.computeRelativeTime()}", // Allocates strings per frame modifier = Modifier.padding(dynamicPadding) ) } } } } ``` #### Production Standard (Correct) > **Standard**: Stable keys via `VirtualizedItemKey` and explicit `contentType` allow Skiko to reuse underlying layout slots across VSync pulses without re-measurement. Layout derivation is isolated using `derivedStateOf(structuralEqualityPolicy())`, and dynamic layout recalculations like `BoxWithConstraints` are replaced with pre-calculated, deterministic composable trees, keeping CADisplayLink frame delivery strictly under 8ms. ```kotlin // GOOD: Quarantined VSync pipeline with stable keys, memoized state, and zero in-frame allocations @Immutable data class VirtualizedItemKey(val id: String) @Composable fun VirtualizedEventFeed(feedState: FeedState, modifier: Modifier = Modifier) { // Isolated derivation: snapshot changes outside Skiko VSync pass do not invalidate item measure tree val preparedItems by remember(feedState) { derivedStateOf(structuralEqualityPolicy()) { feedState.events .filter { it.isVisible } .sortedBy { it.timestamp } .toImmutableList() } } LazyColumn( modifier = modifier, // Pre-allocates viewport buffering off the immediate CADisplayLink deadline flingBehavior = ScrollableDefaults.flingBehavior() ) { items( items = preparedItems, key = { item -> VirtualizedItemKey(item.id) }, contentType = { it.renderType } ) { item -> // Stable node hierarchy with fixed/pre-computed constraints, bypassing SubcomposeLayout EventFeedRowItem( title = item.title, formattedTime = item.cachedRelativeTime ) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Hardware VSync Render Pipeline Quarantine

Compose Multiplatform Hardware VSync Render Pipeline Quarantine defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation between Compose Multiplatform layout measurement phases and Skiko hardware VSync presentation threads during high-frequency native list virtualization. Prohibits synchronous recomposition, expensive measure passes, and unbounded layout allocations directly inside Skiko rendering and CADisplayLink callbacks. Guarantees 60/120 FPS frame pacing across native iOS and Desktop targets by isolating frame rendering from layout evaluation. 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: Saturating Skiko Presentation Loops with Synchronous Subcomposition and Layout Measure Passes 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	Saturating Skiko Presentation Loops with Synchronous Subcomposition and Layout Measure Passes	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 supply explicit, immutable, and unique identity keys to LazyList items (e.g., `LazyColumn`, `LazyRow`) to prevent positional recomposition during rapid scroll velocities.

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.