Compose Multiplatform Skiko Rendering Thread Decoupling Standard

--- description: Compose Multiplatform Skiko Rendering Thread Decoupling Standard - Enforces strict isolation between Compose snapshot state mutations, heavy data transformations, and Skiko's hardware vsync render dispatch loop (CADisplayLink on iOS and Choreographer on Android). Prevents hitching, dropped frames, and Skia draw command bottlenecks by deferring heavy calculations off the main rendering path and restricting drawing blocks to pure Skiko operations. globs: **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cmp-skiko-rendering-thread-decoupling" --- # Compose Multiplatform Skiko Rendering Thread Decoupling Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Executing Non-Visual State Computation, Blocking Layout Logic, or Heavy Math Inside Compose Draw Phases and Direct Skiko Render Passes ## System Constraints You are a Principal Mobile Architect specializing in Compose Multiplatform (CMP) and Skiko graphics engine internals. Your objective is to enforce strict decoupling of state calculation, snapshot updates, and background I/O from the Skiko hardware vsync presentation loop across iOS and Android. Prevent any operations that block CADisplayLink or Choreographer ticks, ensure derived state memoization, and isolate canvas draw pipelines. ## Strict Guidelines - Engineers MUST ALWAYS offload heavy computations, filtering, sorting, and serialization to Dispatchers.Default, pushing only ready-to-render immutable state models to the UI layer. - Engineers MUST NOT invoke state transformations, dynamic allocations, or snapshot writes inside DrawScope, Canvas, or onDrawModifier lambdas. - Engineers MUST wrap fine-grained frequent state reads inside derivedStateOf or snapshotFlow to prevent redundant Skiko draw passes during fast-changing inputs (e.g., scroll offsets, sensor inputs). - Services MUST ensure that platform-specific Skiko rendering contexts (such as SkikoUIView or Metal render targets) are never blocked by synchronous locks or blocking runBlocking calls. - Components NEVER execute file I/O, network reads, or heavy image decodes synchronously on the Main/Rendering thread before feeding Skia textures. ## Bad vs Good Implementations ### Decoupling Heavy Data Mapping and Canvas Path Computation from the Draw Pass #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Sorting and allocating UI paths inside or immediately upstream of the Canvas scope triggers garbage collection pressure and CPU contention on the rendering thread, blocking Skiko's draw loop and missing hardware vsync deadlines. ```kotlin import androidx.compose.foundation.Canvas import androidx.compose.runtime.* import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Path @Composable fun AnalyticsGraph(rawPoints: List<Double>, modifier: Modifier = Modifier) { // ANTI-PATTERN: Heavy transformation and allocation executed during recomposition/draw phase, // blocking the Skiko CADisplayLink rendering tick. Canvas(modifier = modifier) { val sortedPoints = rawPoints.sorted().takeLast(100) val path = Path().apply { sortedPoints.forEachIndexed { index, value -> val x = index * (size.width / 100f) val y = size.height - (value.toFloat() * size.height) if (index == 0) moveTo(x, y) else lineTo(x, y) } } drawPath(path, color = androidx.compose.ui.graphics.Color.Blue) } } ``` #### Production Standard (Correct) > **Standard**: Calculations are moved off the main rendering loop using coroutines (Dispatchers.Default) and memoized with derivedStateOf/remember. Canvas execution only performs hardware-accelerated drawing with pre-computed structures. ```kotlin import androidx.compose.foundation.Canvas import androidx.compose.runtime.* import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color import androidx.compose.ui.graphics.Path import kotlinx.collections.immutable.ImmutableList import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.withContext @Immutable data class NormalizedPoint(val xRatio: Float, val yRatio: Float) @Composable fun AnalyticsGraph(normalizedPoints: ImmutableList<NormalizedPoint>, modifier: Modifier = Modifier) { // GUARDRAIL: Path is pre-calculated or memoized; allocations inside draw loop are eliminated. val cachedPath by remember(normalizedPoints) { derivedStateOf { Path().apply { normalizedPoints.forEachIndexed { index, point -> if (index == 0) moveTo(point.xRatio, point.yRatio) else lineTo(point.xRatio, point.yRatio) } } } } Canvas(modifier = modifier) { // Skiko draw pass executes strictly precomputed vector commands scaled to canvas bounds drawPath(path = cachedPath, color = Color.Blue) } } // Compute pipeline decoupled to background dispatcher suspend fun processGraphPoints(raw: List<Double>): ImmutableList<NormalizedPoint> = withContext(Dispatchers.Default) { // Heavy sorting and calculations decoupled from UI/Render thread buildNormalizedPoints(raw) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Skiko Rendering Thread Decoupling Standard

Compose Multiplatform Skiko Rendering Thread Decoupling Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation between Compose snapshot state mutations, heavy data transformations, and Skiko's hardware vsync render dispatch loop (CADisplayLink on iOS and Choreographer on Android). Prevents hitching, dropped frames, and Skia draw command bottlenecks by deferring heavy calculations off the main rendering path and restricting drawing blocks to pure Skiko operations. 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: Executing Non-Visual State Computation, Blocking Layout Logic, or Heavy Math Inside Compose Draw Phases and Direct Skiko Render 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	Executing Non-Visual State Computation, Blocking Layout Logic, or Heavy Math Inside Compose Draw Phases and Direct Skiko Render 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 offload heavy computations, filtering, sorting, and serialization to Dispatchers.Default, pushing only ready-to-render immutable state models to the UI layer.

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.