KMP Compose Skiko Render Surface Concurrency Isolation

--- description: KMP Compose Skiko Render Surface Concurrency Isolation - Enforces strict temporal decoupling between concurrent reactive state emissions and hardware-synced Skiko rendering surfaces across iOS (CADisplayLink/MetalLayer) and Android (Choreographer/SurfaceView). Prevents main-thread frame pacing anomalies, surface tearing, and mutex deadlocks by isolating hot state transformations to dedicated confinement dispatchers before sampling on the platform render loop. globs: **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-compose-skiko-surface-concurrency-isolation" --- # KMP Compose Skiko Render Surface Concurrency Isolation > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Direct In-Band State Mutation and Unconfined Recomposition on the Hardware VSync Thread ## System Constraints You are a Principal Engineer enforcing Kotlin Multiplatform Compose Skiko Render Surface Concurrency Isolation. Mandate invariants that completely decouple asynchronous upstream event streams from Skiko's hardware rendering loop (CADisplayLink / CAMetalLayer on Apple platforms; Choreographer / SurfaceView on Android). Prevent UI thread stalls, dropped presentation timestamps, and graphic pipeline starvation by isolating state collection into snapshot-buffered down-sampling pipelines. ## Strict Guidelines - Engineers MUST ALWAYS isolate high-frequency state updates (sensors, network sockets, canvas updates) onto a background CoroutineDispatcher using conflation or windowed throttling before emission to Compose State. - Engineers MUST NEVER invoke synchronous blocking operations, heavy allocations, or lock acquisitions within Skiko's onRender draw phase or inside DrawScope lambdas. - Engineers MUST ALWAYS collect raw asynchronous flows via `produceState` or derived snapshot states that decouple the ingestion frequency from the platform presentation refresh rate (60Hz/120Hz ProMotion). - Engineers MUST ensure that native surface bridges (such as Skia-backed Metal or Vulkan contexts) are mutated strictly within the Compose Skiko rendering context and never concurrently accessed across threads. - Engineers MUST configure custom Skiko render targets with double or triple buffering semantics and explicitly synchronize platform view lifecycles using disposal hooks to prevent dangling GPU render passes. ## Bad vs Good Implementations ### High-Frequency Flow Consumption in Compose Skiko Canvas #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly collecting high-frequency reactive states without confinement forces Skiko to invalidate snapshots on every raw packet. Performing data filtering directly in the Canvas draw pass blocks the CADisplayLink/Choreographer thread, dropping frames and causing render surface desynchronization. ```kotlin import androidx.compose.runtime.* import androidx.compose.foundation.Canvas import kotlinx.coroutines.flow.* @Composable fun SensorMonitorView(highFrequencySensorFlow: StateFlow<SensorReading>) { // ANTI-PATTERN: Direct observation of unthrottled high-frequency events directly on the Compose/Skiko rendering thread. // Bypassing dispatcher isolation causes catastrophic frame drops and CAMetalLayer tearing. val reading by highFrequencySensorFlow.collectAsState() Canvas(modifier = androidx.compose.ui.Modifier) { // Heavy computation performed during hardware-synced drawing pass val processedData = heavyFiltering(reading.rawPoints) drawPoints(processedData) } } private fun heavyFiltering(points: List<Float>): List<Float> = points.map { it * 2f } ``` #### Production Standard (Correct) > **Standard**: Decouples sensor stream ingestion from Skiko's display link. Heavy mathematical transformation is isolated to Dispatchers.Default, while .conflate() ensures that Skiko only processes the latest state snapshot at VSync cadence, preventing render pipeline starvation and frame drops. ```kotlin import androidx.compose.runtime.* import androidx.compose.foundation.Canvas import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.flow.* @Composable fun SensorMonitorView(highFrequencySensorFlow: StateFlow<SensorReading>) { // PRODUCTION FIX: Conflate, compute off-thread via dedicated dispatcher, and sample at display sync intervals. val renderState by produceState<RenderModel>(initialValue = RenderModel.Empty, highFrequencySensorFlow) { highFrequencySensorFlow .conflate() .flowOn(Dispatchers.Default) .map { raw -> computeRenderPrimitives(raw.rawPoints) } .flowOn(Dispatchers.Default) .collect { calculatedModel -> value = calculatedModel } } Canvas(modifier = androidx.compose.ui.Modifier) { // Zero calculation; pure Skiko render target drawing drawPoints(renderState.points) } } private fun computeRenderPrimitives(points: List<Float>): RenderModel = RenderModel(points = points.map { it * 2f }) data class RenderModel(val points: List<Float>) { companion object { val Empty = RenderModel(emptyList()) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Compose Skiko Render Surface Concurrency Isolation

KMP Compose Skiko Render Surface Concurrency Isolation defines an industrial-grade behavioral standard for mobile engineering. Enforces strict temporal decoupling between concurrent reactive state emissions and hardware-synced Skiko rendering surfaces across iOS (CADisplayLink/MetalLayer) and Android (Choreographer/SurfaceView). Prevents main-thread frame pacing anomalies, surface tearing, and mutex deadlocks by isolating hot state transformations to dedicated confinement dispatchers before sampling on the platform render loop. 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: Direct In-Band State Mutation and Unconfined Recomposition on the Hardware VSync Thread 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	Direct In-Band State Mutation and Unconfined Recomposition on the Hardware VSync Thread	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 isolate high-frequency state updates (sensors, network sockets, canvas updates) onto a background CoroutineDispatcher using conflation or windowed throttling before emission to Compose State.

Engineers MUST ALWAYS isolate high-frequency state updates (sensors, network sockets, canvas updates) onto a background CoroutineDispatcher using conflation or windowed throttling before emission to Compose State.

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.