KMP Skiko Hardware Canvas Direct Frame Budget and Thread Deadlock Guardrail

--- description: KMP Skiko Hardware Canvas Direct Frame Budget and Thread Deadlock Guardrail - Enforces strict sub-millisecond draw allocations, lock-free render pipelines, and asynchronous GPU texture synchronization across iOS (Metal) and Android (Vulkan/GLES) targets using Skiko and Compose Multiplatform. Prevents main-thread starvation, display-link deadlocks, and missed 120Hz VSYNC frame budgets during direct hardware canvas interop. globs: **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt, **/*Canvas*.kt, **/*Renderer*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-skiko-hardware-canvas-frame-budget-guardrail" --- # KMP Skiko Hardware Canvas Direct Frame Budget and Thread Deadlock Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Allocating Skia native objects and acquiring synchronous locks inside direct Skiko hardware canvas draw passes. ## System Constraints You are a Principal Mobile Systems Architect specializing in Kotlin Multiplatform and Skiko GPU graphics pipelines. Your mandate is to enforce zero-allocation hardware canvas loops, deterministic 8.33ms (120Hz) frame budgets, and complete immunity against native platform dispatch deadlocks between iOS CADisplayLink/Metal command queues and Android Choreographer/Vulkan renderers. ## Strict Guidelines - Engineers MUST ALWAYS pre-allocate and reuse native Skiko/Skia primitives (`org.jetbrains.skia.Paint`, `Path`, `Shader`, `ColorFilter`) outside the composable drawing phase or cache them via keyed remember/render lifecycle states. - Engineers MUST NOT invoke `runBlocking`, blocking Mutex locks, or synchronous thread barriers within `drawWithContent`, `Canvas`, or Skiko `SkiaLayer.render` callbacks. - Code MUST isolate mutable graphics state transfers onto double-buffered, lock-free ring buffers or atomic state holders before dispatching to the native VSYNC draw pass. - Engineers MUST NOT invoke blocking image decodes or native file/network I/O inside the direct canvas frame lifecycle; all pixel buffers must be uploaded to GPU textures ahead of time. - Platform interop bridges (Metal Layer on iOS and SurfaceView on Android) MUST yield the GPU context back within a strict 4.0ms rasterization window to maintain the 8.33ms hardware display budget. - Components NEVER bridge coroutine dispatchers using `Dispatchers.Main` inside a raw Skiko frame render cycle, as iOS Metal presentation loops can deadlock the UI thread during touch event dispatch. ## Bad vs Good Implementations ### Skiko Direct Canvas Rendering: Allocation & Deadlock Elimination #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Instantiating native Skia objects (Paint, Path) on every frame triggers continuous JNI/Kotlin-Native memory bridging and forces GC pressure, blowing past the 8.33ms (120Hz) frame budget. Calling `runBlocking` inside the frame loop starves the native display pump (CADisplayLink/Choreographer), causing severe jank and rendering deadlocks when GPU resources are acquired. ```kotlin import androidx.compose.foundation.Canvas import androidx.compose.runtime.Composable import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.drawscope.drawIntoCanvas import androidx.compose.ui.graphics.nativeCanvas import kotlinx.coroutines.runBlocking import org.jetbrains.skia.Paint import org.jetbrains.skia.Path @Composable fun RadarScanView(state: RadarTelemetryState, modifier: Modifier = Modifier) { Canvas(modifier = modifier) { // CRITICAL BUG 1: Allocating Skia C++ native wrapper objects inside the hot draw path val nativePaint = Paint().apply { color = 0xFF00FF00.toInt() strokeWidth = 4f } val path = Path() // CRITICAL BUG 2: Synchronous blocking lock on the UI/Render thread causing frame drops & deadlocks val points = runBlocking { state.fetchCurrentPointsSync() } drawIntoCanvas { canvas -> points.forEachIndexed { i, pt -> if (i == 0) path.moveTo(pt.x, pt.y) else path.lineTo(pt.x, pt.y) } canvas.nativeCanvas.drawPath(path, nativePaint) } // Leaking native Skia C++ peer memory every frame } } ``` #### Production Standard (Correct) > **Standard**: Skia native primitives are allocated once and tied to the composable lifecycle with explicit deterministic native cleanup (`close()`). State is accessed via an atomic lock-free snapshot with zero blocking operations, and paths are reset without reallocating native buffers, sustaining deterministic execution under 1ms total frame budget. ```kotlin import androidx.compose.foundation.Canvas import androidx.compose.runtime.Composable import androidx.compose.runtime.DisposableEffect import androidx.compose.runtime.remember import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.drawscope.drawIntoCanvas import androidx.compose.ui.graphics.nativeCanvas import org.jetbrains.skia.Paint import org.jetbrains.skia.Path private class RenderBufferState { val nativePaint = Paint().apply { color = 0xFF00FF00.toInt() strokeWidth = 4f isAntiAlias = true } val path = Path() fun release() { nativePaint.close() path.close() } } @Composable fun RadarScanView(state: RadarTelemetryState, modifier: Modifier = Modifier) { val cache = remember { RenderBufferState() } DisposableEffect(cache) { onDispose { cache.release() } } // Pre-sampled, non-blocking lock-free state access val frameSnapshot = state.atomicSnapshot.get() Canvas(modifier = modifier) { drawIntoCanvas { canvas -> val skiaPath = cache.path skiaPath.reset() val points = frameSnapshot.points for (i in points.indices) { val pt = points[i] if (i == 0) skiaPath.moveTo(pt.x, pt.y) else skiaPath.lineTo(pt.x, pt.y) } canvas.nativeCanvas.drawPath(skiaPath, cache.nativePaint) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Skiko Hardware Canvas Direct Frame Budget and Thread Deadlock Guardrail

KMP Skiko Hardware Canvas Direct Frame Budget and Thread Deadlock Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict sub-millisecond draw allocations, lock-free render pipelines, and asynchronous GPU texture synchronization across iOS (Metal) and Android (Vulkan/GLES) targets using Skiko and Compose Multiplatform. Prevents main-thread starvation, display-link deadlocks, and missed 120Hz VSYNC frame budgets during direct hardware canvas interop. 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: Allocating Skia native objects and acquiring synchronous locks inside direct Skiko hardware canvas draw 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	Allocating Skia native objects and acquiring synchronous locks inside direct Skiko hardware canvas draw 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 pre-allocate and reuse native Skiko/Skia primitives (`org.jetbrains.skia.Paint`, `Path`, `Shader`, `ColorFilter`) outside the composable drawing phase or cache them via keyed remember/render lifecycle states.

Engineers MUST ALWAYS pre-allocate and reuse native Skiko/Skia primitives (`org.jetbrains.skia.Paint`, `Path`, `Shader`, `ColorFilter`) outside the composable drawing phase or cache them via keyed remember/render lifecycle states.

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.