@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.0

package/pipeline/skills/shared/external/android-performance/references/patterns.md

@@ -0,0 +1,659 @@
+# Android Performance Patterns
+
+Full code examples for the Android Performance skill. Each section mirrors a
+heading in `SKILL.md`. Load the section named in the guide when implementing or
+reviewing that area.
+
+## Contents
+
+- [Baseline Profiles](#baseline-profiles)
+- [Compose Stability](#compose-stability)
+- [Recomposition Debugging](#recomposition-debugging)
+- [Lazy Layout Performance](#lazy-layout-performance)
+- [R8 Optimization](#r8-optimization)
+- [Memory Leak Detection](#memory-leak-detection)
+- [Startup Optimization](#startup-optimization)
+- [Image Loading with Coil](#image-loading-with-coil)
+- [General Performance Patterns](#general-performance-patterns)
+
+## Baseline Profiles
+
+### Setup
+
+```kotlin
+// build.gradle.kts (:app)
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.baselineprofile)
+}
+
+dependencies {
+    baselineProfile(project(":baselineprofile"))
+}
+
+baselineProfile {
+    automaticGenerationDuringBuild = true
+}
+```
+
+### Generator Module
+
+```kotlin
+// :baselineprofile/build.gradle.kts
+plugins {
+    alias(libs.plugins.android.test)
+    alias(libs.plugins.baselineprofile)
+}
+
+android {
+    namespace = "com.example.baselineprofile"
+    targetProjectPath = ":app"
+}
+
+baselineProfile {
+    useConnectedDevices = true
+}
+```
+
+### Profile Generator
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+@LargeTest
+class BaselineProfileGenerator {
+
+    @get:Rule
+    val rule = BaselineProfileRule()
+
+    @Test
+    fun generateBaselineProfile() {
+        rule.collect(
+            packageName = "com.example.app",
+            includeInStartupProfile = true,
+        ) {
+            // Cold start
+            pressHome()
+            startActivityAndWait()
+
+            // Critical user journeys
+            device.findObject(By.text("Search")).click()
+            device.waitForIdle()
+
+            device.findObject(By.res("search_field")).text = "Istanbul"
+            device.waitForIdle()
+
+            device.findObject(By.res("flight_card")).click()
+            device.waitForIdle()
+        }
+    }
+}
+```
+
+### Generate and Apply
+
+```bash
+# Generate baseline profile
+./gradlew :app:generateBaselineProfile
+
+# Profile is written to app/src/main/baseline-prof.txt
+# Startup profile to app/src/main/startup-prof.txt
+```
+
+## Compose Stability
+
+### @Immutable and @Stable Annotations
+
+```kotlin
+// Mark a class as truly immutable (all properties never change after construction)
+@Immutable
+data class FlightUiModel(
+    val id: String,
+    val route: String,
+    val price: String,
+    val status: String,
+)
+
+// Mark a class as stable (Compose can track changes via equals)
+@Stable
+data class FilterState(
+    val origin: String = "",
+    val destination: String = "",
+    val date: LocalDate? = null,
+)
+```
+
+### Use kotlinx.collections.immutable
+
+Replace `List`, `Set`, `Map` with immutable variants for stable parameters:
+
+```kotlin
+// build.gradle.kts
+implementation("org.jetbrains.kotlinx:kotlinx-collections-immutable:0.3.8")
+
+// Usage
+@Immutable
+data class FlightListUiState(
+    val flights: ImmutableList<FlightUiModel> = persistentListOf(),
+    val isLoading: Boolean = false,
+)
+
+// Convert in ViewModel
+val uiState: StateFlow<FlightListUiState> = repository.getFlights()
+    .map { flights ->
+        FlightListUiState(
+            flights = flights.map(::toUiModel).toImmutableList(),
+        )
+    }
+    .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), FlightListUiState())
+```
+
+### Strong Skipping Mode (Kotlin 2.0+)
+
+With the Compose Compiler plugin for Kotlin 2.0+, strong skipping is enabled
+by default. This makes more composables skippable:
+
+- Unstable parameters are compared by instance equality (`===`)
+- Lambdas are memoized by default
+- Less need for manual `@Stable` / `@Immutable` annotations
+
+Verify in Compose compiler reports:
+
+```properties
+# gradle.properties
+composeCompiler.reportsDestination=build/compose-reports
+composeCompiler.metricsDestination=build/compose-metrics
+```
+
+```bash
+./gradlew assembleRelease
+# Check build/compose-reports/app_release-composables.txt for skippability
+```
+
+## Recomposition Debugging
+
+### Layout Inspector (Android Studio)
+
+1. Run app in debug mode
+2. Open Layout Inspector: View > Tool Windows > Layout Inspector
+3. Enable "Show Recomposition Counts" in the toolbar
+4. Interact with the app and observe which composables recompose
+
+High recomposition counts on composables that should not change indicate
+unnecessary invalidation.
+
+### Recomposition Highlighter
+
+```kotlin
+// Debug utility -- remove before release
+@Composable
+fun RecompositionCounter(label: String) {
+    val count = remember { mutableIntStateOf(0) }
+    count.intValue++
+    SideEffect {
+        Log.d("Recomposition", "$label: ${count.intValue}")
+    }
+}
+```
+
+### Compose Compiler Metrics
+
+Generate stability reports to identify unstable composables:
+
+```bash
+./gradlew assembleRelease \
+    -PcomposeCompiler.reportsDestination=build/compose-reports \
+    -PcomposeCompiler.metricsDestination=build/compose-metrics
+```
+
+Key files:
+- `*-composables.txt`: Lists all composables with restartable/skippable status
+- `*-classes.txt`: Lists all classes with stability status
+- `*-module.json`: Summary metrics
+
+Look for composables marked `restartable` but NOT `skippable` -- these are
+recomposition hotspots.
+
+## Lazy Layout Performance
+
+### LazyColumn/LazyRow Keys
+
+Always provide stable keys for lazy layouts. Without keys, Compose cannot
+efficiently diff items.
+
+```kotlin
+// CORRECT: stable key from item ID
+LazyColumn {
+    items(
+        items = flights,
+        key = { flight -> flight.id },
+    ) { flight ->
+        FlightCard(flight = flight)
+    }
+}
+
+// WRONG: no key -- full list diff on every change
+LazyColumn {
+    items(flights) { flight ->
+        FlightCard(flight = flight)
+    }
+}
+```
+
+### contentType for Heterogeneous Lists
+
+```kotlin
+LazyColumn {
+    items(
+        items = feedItems,
+        key = { it.id },
+        contentType = { item ->
+            when (item) {
+                is FeedItem.Flight -> "flight"
+                is FeedItem.Hotel -> "hotel"
+                is FeedItem.Ad -> "ad"
+            }
+        },
+    ) { item ->
+        when (item) {
+            is FeedItem.Flight -> FlightCard(item)
+            is FeedItem.Hotel -> HotelCard(item)
+            is FeedItem.Ad -> AdBanner(item)
+        }
+    }
+}
+```
+
+`contentType` enables Compose to reuse view holders of the same type,
+similar to RecyclerView's view type system.
+
+### Avoid Heavy Computation in Item Scope
+
+```kotlin
+// WRONG: formatting on every recomposition
+items(flights, key = { it.id }) { flight ->
+    val formatted = SimpleDateFormat("HH:mm", Locale.getDefault())
+        .format(Date(flight.departureTime))
+    Text(formatted)
+}
+
+// CORRECT: precompute in ViewModel or UiModel
+data class FlightUiModel(
+    val id: String,
+    val formattedDeparture: String, // precomputed
+)
+```
+
+### Prefetch Configuration
+
+```kotlin
+LazyColumn(
+    state = rememberLazyListState(),
+    // Default prefetch is usually sufficient
+    // For custom behavior:
+    flingBehavior = ScrollableDefaults.flingBehavior(),
+) {
+    items(flights, key = { it.id }) { flight ->
+        FlightCard(flight = flight)
+    }
+}
+```
+
+## R8 Optimization
+
+### Enable Full Optimization
+
+```kotlin
+android {
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+        }
+    }
+}
+```
+
+### R8 Full Mode
+
+R8 full mode enables more aggressive optimizations:
+
+```properties
+# gradle.properties
+android.enableR8.fullMode=true
+```
+
+Full mode may require additional keep rules for reflection-based code.
+
+### Measuring R8 Impact
+
+```bash
+# Before R8 (debug APK)
+./gradlew assembleDebug
+ls -la app/build/outputs/apk/debug/app-debug.apk
+
+# After R8 (release APK)
+./gradlew assembleRelease
+ls -la app/build/outputs/apk/release/app-release.apk
+
+# Compare sizes
+```
+
+## Memory Leak Detection
+
+### LeakCanary Setup
+
+```kotlin
+// build.gradle.kts
+debugImplementation("com.squareup.leakcanary:leakcanary-android:2.14")
+```
+
+LeakCanary runs automatically in debug builds. It detects:
+- Activity leaks
+- Fragment leaks
+- ViewModel leaks
+- Service leaks
+- Custom watched objects
+
+### Common Leak Patterns
+
+```kotlin
+// LEAK: Activity reference in singleton
+object Analytics {
+    private var context: Context? = null // holds Activity reference
+    fun init(context: Context) { this.context = context }
+}
+
+// FIX: Use application context
+object Analytics {
+    private var context: Context? = null
+    fun init(context: Context) { this.context = context.applicationContext }
+}
+
+// LEAK: Coroutine scope outlives lifecycle
+class MyActivity : ComponentActivity() {
+    init {
+        GlobalScope.launch { // outlives Activity
+            // long-running work
+        }
+    }
+}
+
+// FIX: Use lifecycleScope
+class MyActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        lifecycleScope.launch {
+            // cancelled when Activity is destroyed
+        }
+    }
+}
+
+// LEAK: Anonymous inner class holds reference
+class MyViewModel : ViewModel() {
+    val callback = object : Callback {
+        override fun onResult(data: Data) {
+            // this holds implicit reference to MyViewModel
+        }
+    }
+}
+```
+
+### Manual Object Watching
+
+```kotlin
+// Watch custom objects for leaks
+val watcher = LeakCanary.objectWatcher
+watcher.expectWeaklyReachable(myObject, "MyObject should be GC'd")
+```
+
+## Startup Optimization
+
+### Macrobenchmark for Startup Tracing
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class StartupBenchmark {
+
+    @get:Rule
+    val benchmarkRule = MacrobenchmarkRule()
+
+    @Test
+    fun startupCompilation() {
+        benchmarkRule.measureRepeated(
+            packageName = "com.example.app",
+            metrics = listOf(StartupTimingMetric()),
+            iterations = 5,
+            startupMode = StartupMode.COLD,
+        ) {
+            pressHome()
+            startActivityAndWait()
+        }
+    }
+
+    @Test
+    fun startupWithScrolling() {
+        benchmarkRule.measureRepeated(
+            packageName = "com.example.app",
+            metrics = listOf(
+                StartupTimingMetric(),
+                FrameTimingMetric(),
+            ),
+            iterations = 5,
+            startupMode = StartupMode.COLD,
+        ) {
+            pressHome()
+            startActivityAndWait()
+
+            val list = device.findObject(By.res("flight_list"))
+            list.setGestureMargin(device.displayWidth / 5)
+            list.fling(Direction.DOWN)
+            device.waitForIdle()
+        }
+    }
+}
+```
+
+### Startup Best Practices
+
+```kotlin
+@HiltAndroidApp
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        // Only initialize essentials here
+        // Defer non-critical init to background
+    }
+}
+
+// Use App Startup library for lazy initialization
+class AnalyticsInitializer : Initializer<Analytics> {
+    override fun create(context: Context): Analytics {
+        return Analytics.init(context)
+    }
+
+    override fun dependencies(): List<Class<out Initializer<*>>> = emptyList()
+}
+```
+
+### Defer Heavy Initialization
+
+```kotlin
+// WRONG: blocking startup
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        Database.initialize(this)      // slow
+        ImageLoader.setup(this)        // slow
+        CrashReporting.setup(this)     // slow
+    }
+}
+
+// CORRECT: defer to background
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        ProcessLifecycleOwner.get().lifecycleScope.launch(Dispatchers.Default) {
+            Database.initialize(this@MyApplication)
+            ImageLoader.setup(this@MyApplication)
+        }
+        // Crash reporting can stay on main (usually lightweight)
+        CrashReporting.setup(this)
+    }
+}
+```
+
+## Image Loading with Coil
+
+### Basic Setup
+
+```kotlin
+// build.gradle.kts
+implementation("io.coil-kt:coil-compose:2.7.0")
+
+// Composable
+@Composable
+fun FlightImage(imageUrl: String, modifier: Modifier = Modifier) {
+    AsyncImage(
+        model = ImageRequest.Builder(LocalContext.current)
+            .data(imageUrl)
+            .crossfade(true)
+            .memoryCacheKey(imageUrl)
+            .diskCacheKey(imageUrl)
+            .build(),
+        contentDescription = "Flight image",
+        modifier = modifier,
+        contentScale = ContentScale.Crop,
+    )
+}
+```
+
+### Global Image Loader Configuration
+
+```kotlin
+@HiltAndroidApp
+class MyApplication : Application(), ImageLoaderFactory {
+
+    override fun newImageLoader(): ImageLoader =
+        ImageLoader.Builder(this)
+            .memoryCache {
+                MemoryCache.Builder(this)
+                    .maxSizePercent(0.25) // 25% of app memory
+                    .build()
+            }
+            .diskCache {
+                DiskCache.Builder()
+                    .directory(cacheDir.resolve("image_cache"))
+                    .maxSizePercent(0.02) // 2% of disk
+                    .build()
+            }
+            .crossfade(true)
+            .respectCacheHeaders(true)
+            .build()
+}
+```
+
+### Image Size Optimization
+
+```kotlin
+// Downscale to view size -- prevents loading full-resolution images
+AsyncImage(
+    model = ImageRequest.Builder(LocalContext.current)
+        .data(imageUrl)
+        .size(Size(200, 200)) // Request specific size
+        .scale(Scale.FILL)
+        .build(),
+    contentDescription = null,
+    modifier = Modifier.size(100.dp), // Display size
+)
+```
+
+### Placeholder and Error States
+
+```kotlin
+AsyncImage(
+    model = imageUrl,
+    contentDescription = "Airline logo",
+    placeholder = painterResource(R.drawable.placeholder_airline),
+    error = painterResource(R.drawable.error_airline),
+    fallback = painterResource(R.drawable.default_airline),
+    modifier = Modifier
+        .size(48.dp)
+        .clip(CircleShape),
+)
+```
+
+## General Performance Patterns
+
+### derivedStateOf for Expensive Computations
+
+```kotlin
+@Composable
+fun FlightList(flights: List<Flight>) {
+    val listState = rememberLazyListState()
+
+    // Only recalculates when the derived condition changes
+    val showScrollToTop by remember {
+        derivedStateOf { listState.firstVisibleItemIndex > 5 }
+    }
+
+    Box {
+        LazyColumn(state = listState) {
+            items(flights, key = { it.id }) { FlightCard(it) }
+        }
+
+        if (showScrollToTop) {
+            FloatingActionButton(
+                onClick = { /* scroll to top */ },
+                modifier = Modifier.align(Alignment.BottomEnd),
+            ) {
+                Icon(Icons.Default.ArrowUpward, contentDescription = "Scroll to top")
+            }
+        }
+    }
+}
+```
+
+### remember for Expensive Objects
+
+```kotlin
+// WRONG: recreated every recomposition
+@Composable
+fun DateDisplay(timestamp: Long) {
+    val formatter = SimpleDateFormat("dd MMM yyyy", Locale.getDefault())
+    Text(formatter.format(Date(timestamp)))
+}
+
+// CORRECT: remembered across recompositions
+@Composable
+fun DateDisplay(timestamp: Long) {
+    val formatter = remember { SimpleDateFormat("dd MMM yyyy", Locale.getDefault()) }
+    Text(formatter.format(Date(timestamp)))
+}
+```
+
+### Debounce for Search
+
+```kotlin
+@HiltViewModel
+class SearchViewModel @Inject constructor(
+    private val searchUseCase: SearchFlightsUseCase,
+) : ViewModel() {
+
+    private val searchQuery = MutableStateFlow("")
+
+    val searchResults: StateFlow<List<Flight>> = searchQuery
+        .debounce(300) // Wait 300ms after last keystroke
+        .distinctUntilChanged()
+        .filter { it.length >= 2 }
+        .flatMapLatest { query -> searchUseCase(query) }
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
+
+    fun onQueryChange(query: String) {
+        searchQuery.value = query
+    }
+}
+```