android-sdd 1.0.0

package/skills/Performance/Memory Leak Prevention/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: memory-leak-prevention
+description: >
+  Memory leak detection and prevention in Android.
+  Load this skill when investigating memory leaks, auditing code for
+  common leak patterns, using LeakCanary, fixing Context leaks,
+  or ensuring proper cleanup of listeners and callbacks.
+---
+
+# Memory Leak Prevention
+
+## Overview
+A memory leak occurs when an object is no longer needed but cannot be garbage collected because something still holds a reference to it. On Android, the most common leaks involve holding a reference to an Activity or Fragment beyond their lifecycle. LeakCanary is the standard tool for detection.
+
+---
+
+## Core Principles
+
+- Never store `Activity` or `Fragment` references in long-lived objects (ViewModel, singleton)
+- Always unregister listeners, observers, and callbacks in the symmetric lifecycle callback
+- Use `applicationContext` in singletons — not `Activity` context
+- Clear ViewBinding references in `onDestroyView`
+- Use `WeakReference` only as a last resort — fix the design instead
+
+---
+
+## LeakCanary Setup
+
+```toml
+# libs.versions.toml
+[libraries]
+leakcanary = { module = "com.squareup.leakcanary:leakcanary-android", version = "2.14" }
+```
+
+```kotlin
+// build.gradle.kts — debug only
+dependencies {
+    debugImplementation(libs.leakcanary)
+}
+// No code needed — LeakCanary auto-installs via ContentProvider
+```
+
+---
+
+## Common Leak Patterns and Fixes
+
+```kotlin
+// ❌ Storing Activity in a singleton — leak
+object ImageLoader {
+    var context: Context? = null  // holds Activity reference
+}
+
+// ✅ Use ApplicationContext
+object ImageLoader {
+    lateinit var appContext: Context
+
+    fun init(context: Context) {
+        appContext = context.applicationContext  // safe
+    }
+}
+
+// ❌ Anonymous listener holding Activity reference
+class UserActivity : AppCompatActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        someManager.setListener(object : SomeListener {
+            override fun onEvent() {
+                updateUi()  // captures Activity implicitly
+            }
+        })
+        // listener never removed — Activity leaked
+    }
+}
+
+// ✅ Remove listener in onDestroy
+class UserActivity : AppCompatActivity() {
+    private val listener = SomeListener { updateUi() }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        someManager.addListener(listener)
+    }
+
+    override fun onDestroy() {
+        someManager.removeListener(listener)
+        super.onDestroy()
+    }
+}
+```
+
+---
+
+## ViewBinding Leak
+
+```kotlin
+// ❌ Binding held past onDestroyView — Fragment leak
+class UserFragment : Fragment() {
+    private lateinit var binding: FragmentUserBinding  // never cleared
+
+    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
+        binding = FragmentUserBinding.bind(view)
+    }
+    // Fragment view destroyed but binding still holds reference to views
+}
+
+// ✅ Clear binding in onDestroyView
+class UserFragment : Fragment() {
+    private var _binding: FragmentUserBinding? = null
+    private val binding get() = _binding!!
+
+    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
+        super.onViewCreated(view, savedInstanceState)
+        _binding = FragmentUserBinding.bind(view)
+    }
+
+    override fun onDestroyView() {
+        _binding = null  // ✅ clear reference
+        super.onDestroyView()
+    }
+}
+```
+
+---
+
+## Coroutine Scope Leak
+
+```kotlin
+// ❌ Custom scope not cancelled — coroutine leak
+class MyManager {
+    private val scope = CoroutineScope(Dispatchers.IO)
+
+    fun start() {
+        scope.launch { doWork() }
+    }
+    // scope never cancelled — coroutines run forever
+}
+
+// ✅ Cancel scope when no longer needed
+class MyManager {
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+    fun start() {
+        scope.launch { doWork() }
+    }
+
+    fun stop() {
+        scope.cancel()  // ✅ cancels all children
+    }
+}
+```
+
+---
+
+## Handler and Runnable Leak
+
+```kotlin
+// ❌ Handler posting to Activity that may be destroyed
+class UserActivity : AppCompatActivity() {
+    private val handler = Handler(Looper.getMainLooper())
+
+    override fun onStart() {
+        super.onStart()
+        handler.postDelayed({ updateUi() }, 5_000)  // captures Activity
+    }
+    // runnable runs even after Activity destroyed
+}
+
+// ✅ Cancel pending callbacks in onStop
+class UserActivity : AppCompatActivity() {
+    private val handler = Handler(Looper.getMainLooper())
+    private val updateRunnable = Runnable { updateUi() }
+
+    override fun onStart() {
+        super.onStart()
+        handler.postDelayed(updateRunnable, 5_000)
+    }
+
+    override fun onStop() {
+        handler.removeCallbacks(updateRunnable)  // ✅
+        super.onStop()
+    }
+}
+```
+
+---
+
+## ViewModel Holding View Reference
+
+```kotlin
+// ❌ ViewModel holding Composable lambda or View reference
+class UserViewModel : ViewModel() {
+    var onSuccess: (() -> Unit)? = null  // holds UI reference — leak
+}
+
+// ✅ Use events via Channel or SharedFlow — no direct reference
+class UserViewModel : ViewModel() {
+    private val _events = Channel<UserEvent>(Channel.BUFFERED)
+    val events = _events.receiveAsFlow()
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Passing `Activity` context to a singleton or ViewModel
+- Not removing `BroadcastReceiver` registered dynamically
+- Not unregistering `SensorManager` or `LocationManager` listeners
+- Storing references to Composable lambdas in ViewModel
+- Using `registerForActivityResult` outside of `onCreate` or composable
+
+---
+
+## Related Skills
+- `lifecycle` — symmetric resource acquisition and release
+- `viewmodel` — ViewModel scope and what it should not hold
+- `coroutine` — scope cancellation to prevent coroutine leaks
+- `compose` — DisposableEffect for Compose-specific cleanup

package/skills/Performance/Rendering Performance/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: rendering-performance
+description: >
+  UI rendering performance optimization in Android.
+  Load this skill when diagnosing dropped frames, reducing overdraw,
+  optimizing custom view drawing, improving scroll performance,
+  or profiling with GPU Overdraw and Frame Pacing tools.
+---
+
+# Rendering Performance
+
+## Overview
+Android targets 60fps (16ms per frame) or 120fps (8ms per frame) on high-refresh devices. Dropped frames cause visible jank. The main causes are: work on the main thread during frame rendering, overdraw, expensive layout passes, and large hierarchies. The key tool is the **System Trace** and **GPU Overdraw** visualizer.
+
+---
+
+## Core Principles
+
+- Keep the **main thread free** during frame rendering — offload work to coroutines
+- Avoid **overdraw** — drawing the same pixel multiple times wastes GPU time
+- Flatten view hierarchies — deep nesting causes expensive measure/layout passes
+- Avoid `invalidate()` calls that trigger full redraws — invalidate only dirty regions
+- Use hardware acceleration — it's on by default, don't disable it
+
+---
+
+## Frame Budget
+
+```
+60fps target  → 16ms per frame
+120fps target → 8ms per frame
+
+Frame work breakdown:
+  Input handling     ~2ms
+  Animation         ~2ms
+  Measure/Layout    ~4ms
+  Draw              ~4ms
+  Sync & Upload     ~2ms
+  GPU work          ~2ms
+```
+
+---
+
+## Detecting Jank
+
+```kotlin
+// ✅ FrameMetrics API — detect dropped frames programmatically
+class PerformanceMonitor(private val activity: Activity) {
+
+    private val frameMetricsListener = Window.OnFrameMetricsAvailableListener { _, frameMetrics, _ ->
+        val totalDuration = frameMetrics.getMetric(FrameMetrics.TOTAL_DURATION) / 1_000_000L // ns to ms
+        if (totalDuration > 16) {
+            Timber.w("Slow frame: ${totalDuration}ms")
+        }
+    }
+
+    fun start() {
+        activity.window.addOnFrameMetricsAvailableListener(
+            frameMetricsListener,
+            Handler(Looper.getMainLooper())
+        )
+    }
+
+    fun stop() {
+        activity.window.removeOnFrameMetricsAvailableListener(frameMetricsListener)
+    }
+}
+```
+
+---
+
+## Reducing Overdraw
+
+```kotlin
+// ✅ Remove redundant backgrounds
+// In Compose — don't set background on every layer
+@Composable
+fun Screen() {
+    // ❌ Both Scaffold and Column have background — overdraw
+    Scaffold {
+        Column(modifier = Modifier.background(Color.White)) { ... }
+    }
+
+    // ✅ Only one background needed — Scaffold handles it
+    Scaffold {
+        Column { ... }
+    }
+}
+
+// ✅ In XML theme — remove window background if screen has its own
+// android:windowBackground="@null" in theme (if screen fills the window)
+```
+
+---
+
+## Compose Rendering Tips
+
+```kotlin
+// ✅ Use graphicsLayer for hardware-accelerated transformations
+Box(
+    modifier = Modifier
+        .graphicsLayer {
+            scaleX = scale
+            scaleY = scale
+            alpha = opacity
+            // GPU-accelerated — doesn't trigger recomposition
+        }
+)
+
+// ✅ Avoid clip + shadow on the same composable — expensive
+// Instead, use separate layers
+Box(
+    modifier = Modifier
+        .shadow(elevation = 4.dp, shape = RoundedCornerShape(8.dp))
+        // shadow handles clipping internally
+)
+
+// ✅ Use drawWithCache for custom drawing that doesn't change every frame
+Modifier.drawWithCache {
+    val path = Path()
+    path.addRoundRect(...)  // computed once, reused across frames
+    onDrawBehind {
+        drawPath(path, color = Color.Blue)
+    }
+}
+```
+
+---
+
+## Main Thread Protection
+
+```kotlin
+// ✅ Never block main thread during scroll/animation
+@Composable
+fun UserList(viewModel: UserListViewModel) {
+    val users by viewModel.users.collectAsStateWithLifecycle()
+
+    LazyColumn {
+        items(users, key = { it.id }) { user ->
+            // ❌ Don't do I/O or heavy computation here
+            // val data = File(user.avatarPath).readBytes()  // blocks main thread
+
+            // ✅ Data already loaded — just render
+            UserItem(user = user)
+        }
+    }
+}
+```
+
+---
+
+## Custom View — Dirty Region Invalidation
+
+```kotlin
+// ✅ Invalidate only the changed region — not the entire view
+class ProgressView(context: Context) : View(context) {
+    private var progress = 0f
+    private val dirtyRect = Rect()
+
+    fun setProgress(value: Float) {
+        val oldRight = (progress * width).toInt()
+        progress = value
+        val newRight = (progress * width).toInt()
+
+        // Invalidate only the changed horizontal strip
+        dirtyRect.set(minOf(oldRight, newRight), 0, maxOf(oldRight, newRight), height)
+        invalidate(dirtyRect)  // ✅ partial invalidation
+    }
+}
+```
+
+---
+
+## Profiling Tools
+
+```
+GPU Overdraw (Developer Options → Debug GPU overdraw):
+  Blue   = 1x overdraw  (acceptable)
+  Green  = 2x overdraw  (minor issue)
+  Pink   = 3x overdraw  (investigate)
+  Red    = 4x+ overdraw (fix immediately)
+
+System Trace (Android Studio Profiler → CPU → System Trace):
+  - See exact frame timing
+  - Identify which method causes the long frame
+  - Find binder calls, lock contention on main thread
+```
+
+---
+
+## Anti-Patterns
+
+- Performing disk or network I/O on the main thread — causes frame drops
+- Deep nested `ConstraintLayout` inside `ConstraintLayout` — expensive measure passes
+- Setting background on every layout level — causes overdraw
+- Calling `invalidate()` on every frame when nothing changed
+- Using `wrap_content` on `RecyclerView` — measures all items unnecessarily
+
+---
+
+## Related Skills
+- `compose-optimization` — Compose-specific recomposition and stability
+- `allocation-optimization` — reducing GC pauses during rendering
+- `benchmark` — measuring frame rendering with Macrobenchmark
+- `anr-prevention` — keeping the main thread free from blocking work

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

@@ -0,0 +1,219 @@
+---
+name: startup-optimization
+description: >
+  App startup time optimization for Android.
+  Load this skill when reducing cold/warm start time, using App Startup
+  library, deferring heavy initialization, measuring startup performance,
+  or eliminating unnecessary work during application launch.
+---
+
+# Startup Optimization
+
+## Overview
+App startup time directly impacts user retention. Cold start (process not in memory) is the most expensive. The goal is to do the minimum work needed before the first frame is drawn, and defer everything else. Tools include the App Startup library, baseline profiles, and Macrobenchmark.
+
+---
+
+## Core Principles
+
+- Do **minimal work** in `Application.onCreate()` — defer everything non-essential
+- Use **App Startup library** to control and sequence initializer order
+- Never run **network calls or disk I/O** synchronously during startup
+- Use **Baseline Profiles** to pre-compile critical code paths
+- Measure with **Macrobenchmark** — not manual timing
+
+---
+
+## What Happens During Cold Start
+
+```
+1. Process creation
+2. Application.onCreate()       ← most startup time spent here
+3. Activity.onCreate()
+4. Layout inflation / Compose composition
+5. First frame drawn             ← TTFD (Time To First Display)
+```
+
+---
+
+## App Startup Library
+
+```toml
+# libs.versions.toml
+[libraries]
+androidx-startup = { module = "androidx.startup:startup-runtime", version = "1.1.1" }
+```
+
+```kotlin
+// ✅ Replace manual SDK init in Application.onCreate with Initializers
+class TimberInitializer : Initializer<Unit> {
+    override fun create(context: Context) {
+        if (BuildConfig.DEBUG) Timber.plant(Timber.DebugTree())
+    }
+    override fun dependencies(): List<Class<out Initializer<*>>> = emptyList()
+}
+
+class AnalyticsInitializer : Initializer<Unit> {
+    override fun create(context: Context) {
+        FirebaseApp.initializeApp(context)
+    }
+    override fun dependencies(): List<Class<out Initializer<*>>> = emptyList()
+}
+```
+
+```xml
+<!-- AndroidManifest.xml — register initializers -->
+<provider
+    android:name="androidx.startup.InitializationProvider"
+    android:authorities="${applicationId}.androidx-startup"
+    android:exported="false">
+    <meta-data
+        android:name="com.example.TimberInitializer"
+        android:value="androidx.startup" />
+    <meta-data
+        android:name="com.example.AnalyticsInitializer"
+        android:value="androidx.startup" />
+</provider>
+```
+
+---
+
+## Deferring Non-Critical Work
+
+```kotlin
+// ✅ Defer non-critical init to after first frame
+class App : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        // Only critical init here
+        initCrashReporting()
+
+        // Defer everything else
+        ProcessLifecycleOwner.get().lifecycle.addObserver(
+            object : DefaultLifecycleObserver {
+                override fun onStart(owner: LifecycleOwner) {
+                    owner.lifecycle.removeObserver(this)
+                    initNonCriticalSdks()
+                }
+            }
+        )
+    }
+
+    private fun initCrashReporting() {
+        FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(!BuildConfig.DEBUG)
+    }
+
+    private fun initNonCriticalSdks() {
+        // Analytics, feature flags, etc.
+    }
+}
+```
+
+---
+
+## Lazy Dependency Initialization with Hilt
+
+```kotlin
+// ✅ Use @Singleton with lazy injection — initialized on first use
+@HiltViewModel
+class HomeViewModel @Inject constructor(
+    private val analyticsRepository: AnalyticsRepository  // injected lazily
+) : ViewModel()
+
+// ✅ Lazy provider for expensive dependencies
+@Provides
+@Singleton
+fun provideExpensiveSdk(
+    @ApplicationContext context: Context
+): Lazy<ExpensiveSdk> = lazy { ExpensiveSdk.init(context) }
+```
+
+---
+
+## Splash Screen API
+
+```kotlin
+// ✅ Use SplashScreen API — replaces custom splash Activity
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        val splashScreen = installSplashScreen()
+
+        // Keep splash visible while loading initial data
+        splashScreen.setKeepOnScreenCondition {
+            !viewModel.isReady.value
+        }
+
+        super.onCreate(savedInstanceState)
+        setContent { AppContent() }
+    }
+}
+```
+
+```xml
+<!-- res/values/themes.xml -->
+<style name="Theme.App.Starting" parent="Theme.SplashScreen">
+    <item name="windowSplashScreenBackground">@color/primary</item>
+    <item name="windowSplashScreenAnimatedIcon">@drawable/ic_logo</item>
+    <item name="postSplashScreenTheme">@style/Theme.App</item>
+</style>
+```
+
+---
+
+## Measuring Startup
+
+```kotlin
+// ✅ Macrobenchmark for startup measurement
+@RunWith(AndroidJUnit4::class)
+class StartupBenchmark {
+    @get:Rule
+    val benchmarkRule = MacrobenchmarkRule()
+
+    @Test
+    fun coldStartup() = benchmarkRule.measureRepeated(
+        packageName = "com.example.app",
+        metrics = listOf(StartupTimingMetric()),
+        iterations = 5,
+        startupMode = StartupMode.COLD
+    ) {
+        pressHome()
+        startActivityAndWait()
+    }
+}
+```
+
+---
+
+## StrictMode for Development
+
+```kotlin
+// ✅ Enable StrictMode in debug to catch startup violations
+if (BuildConfig.DEBUG) {
+    StrictMode.setThreadPolicy(
+        StrictMode.ThreadPolicy.Builder()
+            .detectDiskReads()
+            .detectDiskWrites()
+            .detectNetwork()
+            .penaltyLog()
+            .build()
+    )
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Running SharedPreferences reads synchronously in `Application.onCreate()`
+- Initializing all SDKs eagerly — most can be deferred or lazy-initialized
+- Custom splash Activity — use the SplashScreen API instead
+- Not measuring startup before and after optimizations — can't prove improvement
+- Doing Room database creation synchronously on the main thread at startup
+
+---
+
+## Related Skills
+- `baseline-profile` — pre-compiling critical code paths
+- `app-startup` — App Startup library details
+- `macrobenchmark` — measuring startup and runtime performance
+- `hilt` — lazy dependency injection at startup