android-sdd 1.0.0

package/skills/Performance/Compose Optimization/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: compose-optimization
+description: >
+  Jetpack Compose performance optimization.
+  Load this skill when reducing unnecessary recompositions, using
+  stability annotations, optimizing LazyList performance, profiling
+  with Layout Inspector, or fixing skipped frames in Compose UI.
+---
+
+# Compose Optimization
+
+## Overview
+Compose performance is dominated by **recomposition** — the process of re-running composables when state changes. Unnecessary recompositions cause dropped frames. The goal is to ensure only the composables that actually depend on changed state are recomposed, using stable types, correct key usage, and proper state scoping.
+
+---
+
+## Core Principles
+
+- Recomposition is triggered by **state reads** — scope reads as narrowly as possible
+- Use **stable types** for parameters — unstable types cause recomposition on every parent recompose
+- Pass **lambdas** instead of state to leaf composables — reduces recomposition scope
+- Use `key()` in `LazyColumn` — helps Compose identify and reuse items correctly
+- Profile with **Compose Compiler Metrics** and **Layout Inspector** before optimizing
+
+---
+
+## Stability and @Stable / @Immutable
+
+```kotlin
+// ❌ Unstable class — List is not stable (Compose can't verify it won't change)
+data class UserListState(
+    val users: List<User>,  // mutable List — Compose treats as unstable
+    val isLoading: Boolean
+)
+
+// ✅ Use ImmutableList or @Immutable annotation
+@Immutable
+data class UserListState(
+    val users: ImmutableList<User>,  // kotlinx.collections.immutable
+    val isLoading: Boolean
+)
+
+// ✅ Or annotate domain model as stable
+@Stable
+data class User(
+    val id: String,
+    val name: String,
+    val email: String
+)
+```
+
+---
+
+## State Scoping — Read State as Low as Possible
+
+```kotlin
+// ❌ Reading state high in the tree — recomposes entire subtree
+@Composable
+fun UserScreen(viewModel: UserViewModel) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    // entire screen recomposes when any state field changes
+    UserList(users = state.users, isLoading = state.isLoading)
+    SearchBar(query = state.searchQuery)
+}
+
+// ✅ Pass lambdas to defer state reads to leaf composables
+@Composable
+fun UserScreen(viewModel: UserViewModel) {
+    UserList(
+        users = { viewModel.state.value.users },  // read inside UserList
+        isLoading = { viewModel.state.value.isLoading }
+    )
+}
+```
+
+---
+
+## LazyColumn Optimization
+
+```kotlin
+// ✅ Always provide stable keys
+LazyColumn {
+    items(
+        items = users,
+        key = { user -> user.id }  // ✅ stable key — enables item reuse
+    ) { user ->
+        UserItem(user = user)
+    }
+}
+
+// ✅ Use contentType for heterogeneous lists
+LazyColumn {
+    items(
+        items = feedItems,
+        key = { it.id },
+        contentType = { item -> item::class }  // ✅ different composables for different types
+    ) { item ->
+        when (item) {
+            is FeedItem.Post -> PostItem(item)
+            is FeedItem.Ad   -> AdItem(item)
+        }
+    }
+}
+
+// ✅ rememberLazyListState to preserve scroll position
+val listState = rememberLazyListState()
+LazyColumn(state = listState) { ... }
+```
+
+---
+
+## remember and derivedStateOf
+
+```kotlin
+// ✅ derivedStateOf — compute derived value only when inputs change
+@Composable
+fun UserList(users: List<User>, searchQuery: String) {
+    val filteredUsers by remember(users, searchQuery) {
+        derivedStateOf {
+            users.filter { it.name.contains(searchQuery, ignoreCase = true) }
+        }
+    }
+    // filteredUsers recomputes only when users or searchQuery change
+}
+
+// ✅ remember expensive computation
+@Composable
+fun ExpensiveScreen(data: List<Data>) {
+    val processed = remember(data) {
+        data.map { processExpensive(it) }  // only recomputes when data changes
+    }
+}
+```
+
+---
+
+## Avoiding Lambda Allocations
+
+```kotlin
+// ❌ New lambda on every recomposition
+@Composable
+fun UserItem(user: User, onDelete: (User) -> Unit) {
+    Button(onClick = { onDelete(user) }) { ... }  // new lambda every recompose
+}
+
+// ✅ remember the lambda
+@Composable
+fun UserItem(user: User, onDelete: (User) -> Unit) {
+    val onClick = remember(user.id) { { onDelete(user) } }
+    Button(onClick = onClick) { ... }
+}
+```
+
+---
+
+## Compose Compiler Metrics
+
+```kotlin
+// build.gradle.kts — enable compiler metrics
+tasks.withType<KotlinCompile>().configureEach {
+    kotlinOptions {
+        freeCompilerArgs += listOf(
+            "-P", "plugin:androidx.compose.compiler.plugins.kotlin:reportsDestination=${project.buildDir}/compose_metrics",
+            "-P", "plugin:androidx.compose.compiler.plugins.kotlin:metricsDestination=${project.buildDir}/compose_metrics"
+        )
+    }
+}
+// Then check build/compose_metrics/ for stability reports
+```
+
+---
+
+## Anti-Patterns
+
+- Passing unstable `List<T>` to composables — triggers recomposition unnecessarily
+- Reading `StateFlow.value` directly in composable body — doesn't trigger recomposition
+- No `key` in `LazyColumn` items — items are recreated instead of reused on scroll
+- Doing heavy computation directly in composable body — use `remember` or `derivedStateOf`
+- Deeply nested composables all reading the same state — scope reads lower in the tree
+
+---
+
+## Related Skills
+- `compose` — Compose fundamentals
+- `compose-performance` — profiling and measuring Compose performance
+- `state-management` — state hoisting and StateFlow patterns
+- `allocation-optimization` — reducing object creation in Compose

package/skills/Performance/Heap Management/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: heap-management
+description: >
+  Android heap memory management and optimization.
+  Load this skill when investigating OutOfMemoryError, reducing memory
+  footprint, understanding heap limits, managing large objects,
+  or profiling memory usage with Android Studio Memory Profiler.
+---
+
+# Heap Management
+
+## Overview
+Each Android app has a limited heap size (typically 128–512MB depending on device). Exceeding this limit causes `OutOfMemoryError`. Proper heap management involves avoiding large allocations, reusing objects, releasing memory under pressure, and profiling with Android Studio Memory Profiler.
+
+---
+
+## Core Principles
+
+- Never hold large objects (Bitmap, byte arrays) longer than necessary
+- Release memory in `onTrimMemory` — the system signals when memory is low
+- Use object pools for frequently created/destroyed objects
+- Profile memory with **Android Studio Memory Profiler** before optimizing
+- Prefer streaming over loading entire files into memory
+
+---
+
+## Heap Limits
+
+```kotlin
+// ✅ Check available heap at runtime
+val runtime = Runtime.getRuntime()
+val maxHeap = runtime.maxMemory()          // max heap the app can use
+val usedHeap = runtime.totalMemory() - runtime.freeMemory()
+val availableHeap = maxHeap - usedHeap
+
+Timber.d("Heap: used=${usedHeap/1024/1024}MB, max=${maxHeap/1024/1024}MB")
+
+// ✅ Request large heap in manifest (use sparingly)
+// android:largeHeap="true" in <application> — last resort
+```
+
+---
+
+## onTrimMemory — Release Under Pressure
+
+```kotlin
+// ✅ Release non-essential memory when system requests it
+class App : Application() {
+    override fun onTrimMemory(level: Int) {
+        super.onTrimMemory(level)
+        when (level) {
+            TRIM_MEMORY_UI_HIDDEN -> {
+                // App went to background — release UI caches
+                imageCache.evictAll()
+            }
+            TRIM_MEMORY_RUNNING_CRITICAL,
+            TRIM_MEMORY_COMPLETE -> {
+                // Critical — release everything possible
+                imageCache.evictAll()
+                dataCache.clear()
+            }
+        }
+    }
+}
+
+// ✅ Implement in ViewModel too
+class UserListViewModel : ViewModel(), ComponentCallbacks2 {
+    override fun onTrimMemory(level: Int) {
+        if (level >= ComponentCallbacks2.TRIM_MEMORY_MODERATE) {
+            cachedUsers.clear()
+        }
+    }
+    override fun onConfigurationChanged(newConfig: Configuration) {}
+    override fun onLowMemory() { cachedUsers.clear() }
+}
+```
+
+---
+
+## LruCache for Memory Caching
+
+```kotlin
+// ✅ LruCache — evicts least-recently-used entries when full
+class ImageMemoryCache {
+    private val maxMemory = (Runtime.getRuntime().maxMemory() / 1024).toInt()
+    private val cacheSize = maxMemory / 8  // use 1/8 of available heap
+
+    private val cache = object : LruCache<String, Bitmap>(cacheSize) {
+        override fun sizeOf(key: String, bitmap: Bitmap): Int {
+            return bitmap.byteCount / 1024  // size in KB
+        }
+    }
+
+    fun put(key: String, bitmap: Bitmap) = cache.put(key, bitmap)
+    fun get(key: String): Bitmap? = cache.get(key)
+    fun evictAll() = cache.evictAll()
+}
+```
+
+---
+
+## Avoiding Large Allocations
+
+```kotlin
+// ❌ Loading entire file into memory
+val bytes = File(path).readBytes()  // OOM for large files
+
+// ✅ Stream the file
+File(path).inputStream().use { stream ->
+    val buffer = ByteArray(8192)  // 8KB buffer
+    var bytesRead: Int
+    while (stream.read(buffer).also { bytesRead = it } != -1) {
+        process(buffer, bytesRead)
+    }
+}
+
+// ❌ Parsing entire JSON response before using it
+val json = response.body?.string()  // loads everything into memory
+
+// ✅ Stream JSON parsing with Kotlinx Serialization
+val users = json.decodeFromStream<List<UserDto>>(response.body!!.byteStream())
+```
+
+---
+
+## Object Pooling
+
+```kotlin
+// ✅ Reuse objects instead of creating new ones in tight loops
+class RectPool {
+    private val pool = ArrayDeque<RectF>()
+
+    fun acquire(): RectF = pool.removeFirstOrNull() ?: RectF()
+
+    fun release(rect: RectF) {
+        rect.setEmpty()
+        pool.addLast(rect)
+    }
+}
+
+// ✅ Usage
+val rectPool = RectPool()
+val rect = rectPool.acquire()
+try {
+    // use rect
+} finally {
+    rectPool.release(rect)
+}
+```
+
+---
+
+## Profiling Tools
+
+```
+Android Studio Memory Profiler:
+  - Heap dump: snapshot of all objects in memory
+  - Allocation tracking: which code allocates the most
+  - GC events: frequency indicates memory pressure
+
+Key metrics to watch:
+  - Java Heap: should not grow unboundedly
+  - Native Heap: images, bitmaps (decoded natively)
+  - Shallow size: size of object itself
+  - Retained size: size of object + everything it keeps alive
+```
+
+---
+
+## Anti-Patterns
+
+- Holding Bitmap references in static fields — never GC'd
+- Caching without size limits — unbounded cache grows until OOM
+- Loading full-resolution images for thumbnails — decode at required size
+- Creating many small objects in tight loops — GC pressure
+- Not implementing `onTrimMemory` — app doesn't release memory under pressure
+
+---
+
+## Related Skills
+- `bitmap-optimization` — efficient Bitmap loading and scaling
+- `memory-leak-prevention` — preventing reference leaks
+- `compose-optimization` — reducing recompositions and allocations
+- `startup-optimization` — reducing memory allocations at startup

package/skills/Performance/Macrobenchmark/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: macrobenchmark
+description: >
+  Macrobenchmark for end-to-end performance measurement in Android.
+  Load this skill when measuring app startup time, scroll jank,
+  navigation transitions, or any user journey performance metric
+  using the Macrobenchmark library.
+---
+
+# Macrobenchmark
+
+## Overview
+Macrobenchmark measures complete user journeys — startup, scroll performance, navigation — from outside the app using UI automation. Unlike microbenchmark, it measures the full system including rendering, I/O, and process startup. It is the standard tool for startup time regression testing and scroll jank measurement.
+
+---
+
+## Core Principles
+
+- Macrobenchmark runs in a **separate test process** — it instruments the app from outside
+- Always test in **release** or **benchmark** build type — not debug
+- Use `StartupMode.COLD` for startup measurement — ensures process is killed first
+- Test on **physical devices** — emulator performance is not representative
+- Run multiple iterations — Macrobenchmark reports min, median, and max automatically
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[libraries]
+androidx-benchmark-macro = { module = "androidx.benchmark:benchmark-macro-junit4", version = "1.3.0" }
+androidx-test-uiautomator = { module = "androidx.test.uiautomator:uiautomator", version = "2.3.0" }
+```
+
+```kotlin
+// macrobenchmark/build.gradle.kts
+plugins {
+    alias(libs.plugins.android.test)
+}
+
+android {
+    targetProjectPath = ":app"
+    experimentalProperties["android.experimental.self-instrumenting"] = true
+
+    defaultConfig {
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+        testInstrumentationRunnerArguments["androidx.benchmark.suppressErrors"] = "EMULATOR"
+    }
+
+    buildTypes {
+        create("benchmark") {
+            isDebuggable = true
+            signingConfig = signingConfigs.getByName("debug")
+            matchingFallbacks += listOf("release")
+        }
+    }
+}
+
+dependencies {
+    implementation(libs.androidx.benchmark.macro)
+    implementation(libs.androidx.test.uiautomator)
+}
+```
+
+---
+
+## Startup Benchmark
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class StartupBenchmark {
+
+    @get:Rule
+    val benchmarkRule = MacrobenchmarkRule()
+
+    @Test
+    fun coldStart() = benchmarkRule.measureRepeated(
+        packageName = "com.example.app",
+        metrics = listOf(StartupTimingMetric()),
+        compilationMode = CompilationMode.Partial(
+            baselineProfileMode = BaselineProfileMode.Require
+        ),
+        startupMode = StartupMode.COLD,   // kill process before each iteration
+        iterations = 5
+    ) {
+        pressHome()
+        startActivityAndWait()            // wait for first frame
+    }
+
+    @Test
+    fun warmStart() = benchmarkRule.measureRepeated(
+        packageName = "com.example.app",
+        metrics = listOf(StartupTimingMetric()),
+        compilationMode = CompilationMode.Partial(),
+        startupMode = StartupMode.WARM,   // process alive, Activity recreated
+        iterations = 5
+    ) {
+        startActivityAndWait()
+    }
+}
+```
+
+---
+
+## Scroll Jank Benchmark
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class ScrollBenchmark {
+
+    @get:Rule
+    val benchmarkRule = MacrobenchmarkRule()
+
+    @Test
+    fun scrollUserList() = benchmarkRule.measureRepeated(
+        packageName = "com.example.app",
+        metrics = listOf(FrameTimingMetric()),   // measures frame timing and jank
+        compilationMode = CompilationMode.Partial(),
+        startupMode = StartupMode.WARM,
+        iterations = 5
+    ) {
+        startActivityAndWait()
+
+        // Navigate to list screen
+        device.findObject(By.text("Users")).click()
+        device.waitForIdle()
+
+        // ✅ Scroll the list — FrameTimingMetric captures frame data
+        val list = device.findObject(By.scrollable(true))
+        repeat(3) {
+            list.fling(Direction.DOWN)
+            device.waitForIdle()
+        }
+    }
+}
+```
+
+---
+
+## Custom Metrics
+
+```kotlin
+// ✅ Measure time to specific state (e.g. data loaded)
+@Test
+fun timeToDataLoaded() = benchmarkRule.measureRepeated(
+    packageName = "com.example.app",
+    metrics = listOf(
+        StartupTimingMetric(),
+        TraceSectionMetric("data_loaded")   // custom trace section
+    ),
+    startupMode = StartupMode.COLD,
+    iterations = 5
+) {
+    pressHome()
+    startActivityAndWait()
+    // Wait for custom trace section to appear
+    device.wait(Until.hasObject(By.text("Users loaded")), 5_000)
+}
+
+// In app code — mark the trace section
+class UserListViewModel : ViewModel() {
+    fun loadUsers() {
+        viewModelScope.launch {
+            val users = repository.getUsers()
+            trace("data_loaded") {   // ✅ marks trace section for benchmark
+                _state.value = UiState.Success(users)
+            }
+        }
+    }
+}
+```
+
+---
+
+## Compilation Modes
+
+```kotlin
+// CompilationMode.None — no AOT, pure JIT (worst case baseline)
+// CompilationMode.Partial() — use existing baseline profile if present
+// CompilationMode.Partial(baselineProfileMode = BaselineProfileMode.Require) — must have profile
+// CompilationMode.Full — fully AOT compiled (best case)
+```
+
+---
+
+## Running and Reading Results
+
+```bash
+# Run benchmarks
+./gradlew :macrobenchmark:connectedBenchmarkAndroidTest
+
+# Results saved to:
+# build/outputs/connected_android_test_additional_output/benchmark/
+# Open in Android Studio via Profiler → Import benchmark results
+```
+
+---
+
+## Anti-Patterns
+
+- Running on emulator — performance not representative
+- Testing in debug build — JIT + debug overhead inflates results
+- Not using `startActivityAndWait()` — benchmark ends before first frame
+- Single iteration — statistical noise makes results unreliable
+- Not using `CompilationMode.None` as baseline — can't see profile improvement
+
+---
+
+## Related Skills
+- `baseline-profile` — generating profiles measured by Macrobenchmark
+- `benchmark` — microbenchmark for method-level measurement
+- `startup-optimization` — techniques to improve startup metrics
+- `rendering-performance` — understanding frame timing results