Kotlin Wasm-GC CanvasKit Context Confinement & Linear Memory Teardown

--- description: Kotlin Wasm-GC CanvasKit Context Confinement & Linear Memory Teardown - Enforces strict lexical lifecycle confinement and deterministic teardown for Skiko/CanvasKit native backing resources within Kotlin Wasm-GC runtimes. WebAssembly Garbage Collection collects managed references but does not trace or reclaim CanvasKit C++ linear memory allocations, causing unbounded cross-heap memory leaks during high-refresh multiplatform canvas rendering. globs: **/wasmJsMain/**/*.kt, **/skiko/**/*.kt, **/*Canvas*.kt, **/*Renderer*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kotlin-wasm-canvaskit-context-confinement" --- # Kotlin Wasm-GC CanvasKit Context Confinement & Linear Memory Teardown > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Leaking CanvasKit C++ Linear Memory via Unscoped Wasm-GC Allocation in Render Loops ## System Constraints You are a Principal Mobile and WebAssembly Systems Architect enforcing strict memory invariants in Kotlin Wasm-GC and CanvasKit runtimes. In Kotlin Wasm-GC, references to CanvasKit/Skiko objects (such as Surface, Paint, Path, PictureRecorder, and Image) bridge the managed Wasm-GC heap with unmanaged Emscripten/C++ linear memory. The Wasm-GC collector NEVER frees Skia C++ linear memory backing buffers. You MUST mandate deterministic resource acquisition and release via lexical scopes, prevent per-frame transient allocations, and guarantee immediate surface teardown during resize or component disposal. ## Strict Guidelines - Engineers MUST ALWAYS invoke `.close()` or `.delete()` deterministically within a `finally` block or use scoped resource blocks (e.g., `use { ... }`) for every Skiko/CanvasKit native wrapper (Path, Paint, Surface, Image, Picture). - Engineers MUST NOT instantiate new `Paint`, `Path`, `Surface`, or `TextBlob` instances inside continuous animation, high-refresh render passes, or `onDraw` callbacks. - Transient path mutations MUST reuse pre-allocated scratch objects via `.reset()` or `.rewind()` to maintain zero-allocation render cycles. - CanvasKit surfaces and Skia contexts MUST be detached and deleted immediately upon DOM resizing, canvas detachment, or Compose `DisposableEffect` disposal. - Interop wrappers bridging JavaScript CanvasKit handles MUST NEVER rely on finalizers or phantom references for unmanaged C++ memory reclamation. ## Bad vs Good Implementations ### Deterministic CanvasKit Native Resource Disposal #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Each invocation allocates C++ structs and raster buffers inside CanvasKit's Emscripten linear heap. Kotlin Wasm-GC manages the Kotlin proxy instance but cannot deallocate the underlying WebAssembly C++ linear memory. At 60-120fps, this leaks hundreds of megabytes within seconds. ```kotlin import org.jetbrains.skia.* class CanvasRenderer { // ANTI-PATTERN: Instantiating Skia native wrappers per frame inside Kotlin Wasm-GC. // Wasm-GC collects the Kotlin wrapper object, but the underlying CanvasKit C++ // linear memory allocation remains uncollected, causing catastrophic OOM crashes. fun renderFrame(canvas: Canvas, width: Float, height: Float) { val paint = Paint().apply { color = Color.RED isAntiAlias = true } val path = Path().apply { moveTo(0f, 0f) lineTo(width, height) } canvas.drawPath(path, paint) // paint and path are abandoned to Wasm-GC; linear memory leaks instantly } } ``` #### Production Standard (Correct) > **Standard**: Reuses native `Paint` and `Path` allocations across frames via `.reset()`, eliminating per-frame linear heap growth. Implements `AutoCloseable` to deterministically invoke `.close()` (which delegates to C++ `delete()`) when the renderer lifecycle terminates. ```kotlin import org.jetbrains.skia.* class CanvasRenderer : AutoCloseable { // PRODUCTION FIX: Pre-allocate scratch native resources and reuse across frames. private val framePaint = Paint().apply { color = Color.RED isAntiAlias = true } private val scratchPath = Path() fun renderFrame(canvas: Canvas, width: Float, height: Float) { scratchPath.reset() scratchPath.moveTo(0f, 0f) scratchPath.lineTo(width, height) canvas.drawPath(scratchPath, framePaint) } // Deterministic teardown of backing C++ linear memory allocations override fun close() { scratchPath.close() framePaint.close() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Wasm-GC CanvasKit Context Confinement & Linear Memory Teardown

Kotlin Wasm-GC CanvasKit Context Confinement & Linear Memory Teardown defines an industrial-grade behavioral standard for mobile engineering. Enforces strict lexical lifecycle confinement and deterministic teardown for Skiko/CanvasKit native backing resources within Kotlin Wasm-GC runtimes. WebAssembly Garbage Collection collects managed references but does not trace or reclaim CanvasKit C++ linear memory allocations, causing unbounded cross-heap memory leaks during high-refresh multiplatform canvas rendering. 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: Leaking CanvasKit C++ Linear Memory via Unscoped Wasm-GC Allocation in Render Loops 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	Leaking CanvasKit C++ Linear Memory via Unscoped Wasm-GC Allocation in Render Loops	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 invoke `.close()` or `.delete()` deterministically within a `finally` block or use scoped resource blocks (e.g., `use { ... }`) for every Skiko/CanvasKit native wrapper (Path, Paint, Surface, Image, Picture).

Engineers MUST ALWAYS invoke `.close()` or `.delete()` deterministically within a `finally` block or use scoped resource blocks (e.g., `use { ... }`) for every Skiko/CanvasKit native wrapper (Path, Paint, Surface, Image, Picture).

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.