android-sdd 1.0.0

package/skills/Android Platform/Process Death Recovery/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: process-death-recovery
+description: >
+  Process death detection, prevention, and recovery strategies for Android.
+  Load this skill when designing state that must survive system-initiated
+  process kills, implementing session recovery, or testing background kill scenarios.
+---
+
+# Process Death Recovery
+
+## Overview
+
+Android can kill an app's process at any time when it's in the background — to free memory. When the user returns, Android recreates the Activity and restores the back stack, but all in-memory state (including ViewModel) is gone. A well-designed app recovers seamlessly without data loss.
+
+---
+
+## Core Principles
+
+- Assume process death can happen **at any time** — design accordingly
+- ViewModel does **not** survive process death — only configuration change
+- SavedStateHandle survives process death — use it for critical UI state
+- Persistent storage (Room, DataStore) always survives — use for important data
+- Never show a blank or broken screen after process death recovery
+
+---
+
+## What Survives What
+
+| Storage           | Config Change | Process Death | App Kill (swipe) |
+| ----------------- | ------------- | ------------- | ---------------- |
+| ViewModel         | ✅             | ❌             | ❌                |
+| SavedStateHandle  | ✅             | ✅             | ❌                |
+| Room / DataStore  | ✅             | ✅             | ✅                |
+| SharedPreferences | ✅             | ✅             | ✅                |
+| In-memory cache   | ✅             | ❌             | ❌                |
+
+---
+
+## Recovery Strategy by State Type
+
+```kotlin
+// ✅ User input — save in SavedStateHandle
+@HiltViewModel
+class FormViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle
+) : ViewModel() {
+    val name = savedStateHandle.getStateFlow("name", "")
+    val email = savedStateHandle.getStateFlow("email", "")
+
+    fun onNameChanged(value: String) { savedStateHandle["name"] = value }
+    fun onEmailChanged(value: String) { savedStateHandle["email"] = value }
+}
+
+// ✅ Loaded data — reload from Room/repository on init
+@HiltViewModel
+class UserListViewModel @Inject constructor(
+    private val repository: UserRepository
+) : ViewModel() {
+    val users: StateFlow<List<User>> = repository
+        .observeUsers()  // Room Flow — always fresh after process death
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), emptyList())
+}
+
+// ✅ Current screen/selection — save ID in SavedStateHandle, reload data
+@HiltViewModel
+class UserDetailViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val repository: UserRepository
+) : ViewModel() {
+    private val userId: String = checkNotNull(savedStateHandle["userId"])
+
+    val user: StateFlow<User?> = repository
+        .observeUser(userId)  // reload data using saved ID
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)
+}
+```
+
+---
+
+## Detecting Process Death vs Fresh Start
+
+```kotlin
+// ✅ Detect if Activity was restored after process death
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        if (savedInstanceState != null) {
+            // Restored — either config change or process death recovery
+            // ViewModel + SavedStateHandle already restored
+        } else {
+            // Fresh start
+        }
+    }
+}
+
+// ✅ In ViewModel — check if state needs initialization
+@HiltViewModel
+class OnboardingViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val repository: OnboardingRepository
+) : ViewModel() {
+
+    private val currentStep = savedStateHandle.getStateFlow("step", 0)
+
+    init {
+        // Don't reset step — it may have been restored from SavedStateHandle
+        if (currentStep.value == 0) {
+            viewModelScope.launch { loadInitialState() }
+        }
+    }
+}
+```
+
+---
+
+## Incomplete Operations Recovery
+
+```kotlin
+// ✅ For critical operations (payment, upload) — use WorkManager
+// WorkManager survives process death and system reboots
+class UploadWorker(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) {
+    override suspend fun doWork(): Result {
+        val fileUri = inputData.getString("file_uri") ?: return Result.failure()
+        return try {
+            uploadFile(fileUri)
+            Result.success()
+        } catch (e: Exception) {
+            Result.retry()
+        }
+    }
+}
+
+// Enqueue — survives process death
+WorkManager.getInstance(context)
+    .enqueueUniqueWork(
+        "upload_${fileId}",
+        ExistingWorkPolicy.KEEP,
+        OneTimeWorkRequestBuilder<UploadWorker>()
+            .setInputData(workDataOf("file_uri" to uri))
+            .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30, TimeUnit.SECONDS)
+            .build()
+    )
+```
+
+---
+
+## Session State Recovery
+
+```kotlin
+// ✅ Persist session-critical state to DataStore immediately on change
+class SessionRepository @Inject constructor(
+    private val dataStore: DataStore<Preferences>
+) {
+    suspend fun saveLastViewedUserId(userId: String) {
+        dataStore.edit { prefs ->
+            prefs[LAST_USER_ID] = userId
+        }
+    }
+
+    fun observeLastViewedUserId(): Flow<String?> =
+        dataStore.data.map { it[LAST_USER_ID] }
+
+    companion object {
+        val LAST_USER_ID = stringPreferencesKey("last_user_id")
+    }
+}
+```
+
+---
+
+## Testing Process Death
+
+```bash
+# ✅ Simulate process death via ADB — put app in background first
+adb shell am kill <package_name>
+
+# Then return to app from Recents — should recover gracefully
+
+# ✅ Android Studio — use "Terminate Application" button
+# while app is in background (minimized)
+```
+
+```kotlin
+// ✅ Write tests for SavedStateHandle restoration
+@Test
+fun `state is restored after process death`() {
+    val savedState = SavedStateHandle(mapOf("search_query" to "kotlin"))
+    val viewModel = SearchViewModel(savedState, fakeRepository)
+
+    assertThat(viewModel.query.value).isEqualTo("kotlin")
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Assuming ViewModel survives process death — it doesn't
+- Storing non-Parcelable objects in SavedStateHandle — crashes on restore
+- Not testing process death — the most common untested scenario
+- Saving too much in SavedStateHandle — it has a size limit (~500KB total)
+- Relying on `onSaveInstanceState` in Activity instead of SavedStateHandle in ViewModel
+- Starting critical operations (payments, uploads) without WorkManager fallback
+
+---
+
+## Related Skills
+
+- `savedstatehandle` — key-value persistence across process death
+- `state-restoration` — full state restoration strategy
+- `workmanager` — durable background work across process death
+- `datastore` — persisting session state
+- `room` — persistent data that always survives

package/skills/Android Platform/Resources/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: resources
+description: >
+  Android resource system — strings, colors, dimensions, drawables, styles, and qualifiers.
+  Load this skill when working with res/ directory, defining or accessing resources,
+  supporting multiple screen sizes, locales, or themes.
+---
+
+# Resources
+
+## Overview
+
+Android resources are external files and static values used by the app — strings, colors, dimensions, drawables, layouts, styles, and more. They live in `res/` and are accessed via generated `R` class. Resources support qualifiers that allow automatic selection based on device configuration.
+
+---
+
+## Core Principles
+
+- Never hardcode strings, colors, or dimensions in code or layouts — always use resources
+- Use qualifiers for configuration-specific resources — don't detect configuration in code
+- All user-facing strings must be in `strings.xml` — enables localization
+- Colors must be defined in `colors.xml` and referenced via theme attributes — not directly
+- Dimensions must be in `dimens.xml` — enables density-independent scaling
+
+---
+
+## Directory Structure
+
+```
+res/
+├── drawable/          ← vector drawables, shape drawables
+├── drawable-xxhdpi/   ← raster images (prefer vectors)
+├── layout/            ← XML layouts (if using View system)
+├── mipmap-*/          ← launcher icons only
+├── values/
+│   ├── strings.xml
+│   ├── colors.xml
+│   ├── dimens.xml
+│   ├── styles.xml
+│   └── themes.xml
+├── values-night/      ← dark theme overrides
+├── values-fa/         ← Persian strings
+├── values-land/       ← landscape overrides
+└── xml/               ← network_security_config, file_paths, etc.
+```
+
+---
+
+## Strings
+
+```xml
+<!-- ✅ strings.xml -->
+<resources>
+    <!-- Simple string -->
+    <string name="app_name">MyApp</string>
+    <string name="action_save">Save</string>
+
+    <!-- ✅ Formatted string with argument -->
+    <string name="welcome_message">Welcome, %1$s!</string>
+
+    <!-- ✅ Plural strings -->
+    <plurals name="item_count">
+        <item quantity="one">%d item</item>
+        <item quantity="other">%d items</item>
+    </plurals>
+
+    <!-- ✅ String array -->
+    <string-array name="days_of_week">
+        <item>Monday</item>
+        <item>Tuesday</item>
+    </string-array>
+</resources>
+```
+
+```kotlin
+// ✅ Accessing strings in code
+val welcome = getString(R.string.welcome_message, userName)
+val itemCount = resources.getQuantityString(R.plurals.item_count, count, count)
+
+// ✅ In Compose
+Text(text = stringResource(R.string.welcome_message, userName))
+Text(text = pluralStringResource(R.plurals.item_count, count, count))
+```
+
+---
+
+## Colors
+
+```xml
+<!-- ✅ colors.xml — raw color palette -->
+<resources>
+    <color name="purple_500">#FF6200EE</color>
+    <color name="purple_700">#FF3700B3</color>
+    <color name="teal_200">#FF03DAC5</color>
+    <color name="white">#FFFFFFFF</color>
+    <color name="black">#FF000000</color>
+</resources>
+
+<!-- ✅ themes.xml — semantic color attributes referencing palette -->
+<style name="Theme.App" parent="Theme.Material3.DayNight">
+    <item name="colorPrimary">@color/purple_500</item>
+    <item name="colorOnPrimary">@color/white</item>
+    <item name="colorSurface">@color/white</item>
+</style>
+
+<!-- ✅ values-night/themes.xml — dark theme overrides -->
+<style name="Theme.App" parent="Theme.Material3.DayNight">
+    <item name="colorPrimary">@color/purple_200</item>
+    <item name="colorSurface">@color/black</item>
+</style>
+```
+
+```kotlin
+// ✅ Always access color via theme attribute — not directly
+val color = MaterialColors.getColor(view, com.google.android.material.R.attr.colorPrimary)
+
+// ✅ In Compose — use MaterialTheme tokens
+Surface(color = MaterialTheme.colorScheme.surface) { ... }
+
+// ❌ Never hardcode or access raw color directly in code
+view.setBackgroundColor(Color.parseColor("#FF6200EE"))
+```
+
+---
+
+## Dimensions
+
+```xml
+<!-- ✅ dimens.xml -->
+<resources>
+    <dimen name="spacing_small">8dp</dimen>
+    <dimen name="spacing_medium">16dp</dimen>
+    <dimen name="spacing_large">24dp</dimen>
+    <dimen name="corner_radius">12dp</dimen>
+    <dimen name="text_size_body">14sp</dimen>
+    <dimen name="text_size_title">20sp</dimen>
+</resources>
+```
+
+```kotlin
+// ✅ Accessing dimensions
+val spacing = resources.getDimensionPixelSize(R.dimen.spacing_medium)
+
+// ✅ In Compose — use dp/sp directly or define as constants
+val SpacingMedium = 16.dp
+val TextSizeBody = 14.sp
+```
+
+---
+
+## Drawables
+
+```xml
+<!-- ✅ Use vector drawables — scale perfectly on all densities -->
+<!-- res/drawable/ic_arrow_back.xml -->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="?attr/colorOnSurface">
+    <path android:fillColor="@android:color/white"
+        android:pathData="M20,11H7.83l5.59-5.59L12,4l-8,8 8,8 1.41-1.41L7.83,13H20v-2z"/>
+</vector>
+```
+
+```
+// ✅ Raster images — use only when vector isn't suitable
+// Place in density buckets:
+drawable-mdpi/    (1x)
+drawable-hdpi/    (1.5x)
+drawable-xhdpi/   (2x)
+drawable-xxhdpi/  (3x)
+drawable-xxxhdpi/ (4x)
+```
+
+---
+
+## Configuration Qualifiers
+
+```
+values/              ← default
+values-fa/           ← Persian locale
+values-night/        ← dark mode
+values-land/         ← landscape
+values-sw600dp/      ← tablets (600dp+ smallest width)
+values-v33/          ← API 33+
+
+layout/              ← default layout
+layout-land/         ← landscape layout
+layout-sw600dp/      ← tablet layout
+```
+
+---
+
+## Accessing Resources in Code
+
+```kotlin
+// ✅ From Activity/Fragment
+val text = getString(R.string.app_name)
+val color = ContextCompat.getColor(this, R.color.purple_500)
+val drawable = ContextCompat.getDrawable(this, R.drawable.ic_arrow_back)
+val dimen = resources.getDimensionPixelSize(R.dimen.spacing_medium)
+
+// ✅ From ViewModel (via injected Context — use ApplicationContext only)
+class MyViewModel(private val appContext: Context) : ViewModel() {
+    fun getLabel(): String = appContext.getString(R.string.app_name)
+}
+
+// ✅ Compose
+Text(stringResource(R.string.app_name))
+Icon(painterResource(R.drawable.ic_arrow_back), contentDescription = null)
+```
+
+---
+
+## Anti-Patterns
+
+- Hardcoded strings in XML or code — breaks localization
+- Accessing colors directly (`R.color.x`) instead of via theme attributes — breaks dark mode
+- Using `px` instead of `dp`/`sp` in dimensions — breaks across densities
+- Placing launcher icons in `drawable/` instead of `mipmap/` — incorrect scaling
+- Using raster images where vectors would work — increases APK size
+- Storing sensitive data (keys, tokens) as string resources — visible in decompiled APK
+- Duplicate string keys — silent override, hard to debug
+
+---
+
+## Related Skills
+
+- `manifest` — referencing resources in manifest
+- `material3` — Material 3 theme and color system
+- `rtl` — RTL-specific resource qualifiers
+- `design-system` — design tokens as Android resources

package/skills/Android Platform/SavedStateHandle/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: savedstatehandle
+description: >
+  SavedStateHandle usage in ViewModel for surviving process death and
+  configuration changes. Load this skill when persisting ViewModel state
+  across process kill, reading navigation arguments, or deciding what
+  state needs to be saved vs what can be reloaded.
+---
+
+# SavedStateHandle
+
+## Overview
+
+SavedStateHandle is a key-value store provided to ViewModel that survives both configuration changes and process death. Unlike ViewModel which only survives rotation, SavedStateHandle persists through system-initiated process kills and is restored when the user returns to the app.
+
+---
+
+## Core Principles
+
+- Use SavedStateHandle for state that must survive **process death** — not just rotation
+- Don't save everything — only save what can't be easily reloaded (user input, scroll position, selected IDs)
+- Data stored in SavedStateHandle must be **Parcelable or primitive**
+- Prefer `saveable { }` in Compose for local UI state — use SavedStateHandle for ViewModel state
+- Navigation arguments are automatically available via SavedStateHandle
+
+---
+
+## What to Save vs What to Reload
+
+| State Type                           | Strategy                               |
+| ------------------------------------ | -------------------------------------- |
+| User input (text fields, selections) | ✅ SavedStateHandle                     |
+| Scroll position                      | ✅ SavedStateHandle or rememberSaveable |
+| Selected item ID                     | ✅ SavedStateHandle                     |
+| Loaded list from network/DB          | ❌ Reload from repository               |
+| Loading/error state                  | ❌ Derive from data loading             |
+| Navigation arguments                 | ✅ Read from SavedStateHandle           |
+
+---
+
+## Basic Usage
+
+```kotlin
+// ✅ Inject via Hilt — automatic with @HiltViewModel
+@HiltViewModel
+class UserDetailViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val repository: UserRepository
+) : ViewModel() {
+
+    // ✅ Read navigation argument (set by NavController)
+    private val userId: String = checkNotNull(savedStateHandle["userId"])
+
+    // ✅ StateFlow backed by SavedStateHandle — survives process death
+    val searchQuery: StateFlow<String> = savedStateHandle
+        .getStateFlow("search_query", initialValue = "")
+
+    fun onSearchQueryChanged(query: String) {
+        savedStateHandle["search_query"] = query
+    }
+}
+```
+
+---
+
+## Reading Navigation Arguments
+
+```kotlin
+// ✅ Compose Navigation — argument passed via route
+// NavHost setup
+composable("user/{userId}") { backStackEntry ->
+    val viewModel: UserDetailViewModel = hiltViewModel()
+    UserDetailScreen(viewModel)
+}
+
+// ✅ ViewModel reads it from SavedStateHandle
+@HiltViewModel
+class UserDetailViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle
+) : ViewModel() {
+    val userId: String = checkNotNull(savedStateHandle["userId"]) {
+        "userId argument is required"
+    }
+}
+
+// ✅ Type-safe navigation (Compose Navigation 2.8+)
+@Serializable
+data class UserDetailRoute(val userId: String)
+
+@HiltViewModel
+class UserDetailViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle
+) : ViewModel() {
+    private val route = savedStateHandle.toRoute<UserDetailRoute>()
+    val userId = route.userId
+}
+```
+
+---
+
+## StateFlow from SavedStateHandle
+
+```kotlin
+@HiltViewModel
+class SearchViewModel @Inject constructor(
+    private val savedStateHandle: SavedStateHandle,
+    private val repository: SearchRepository
+) : ViewModel() {
+
+    // ✅ Backed by SavedStateHandle — survives process death
+    val query: StateFlow<String> = savedStateHandle
+        .getStateFlow(KEY_QUERY, initialValue = "")
+
+    // ✅ Derive results from the saved query
+    val results: StateFlow<List<Result>> = query
+        .debounce(300)
+        .flatMapLatest { q -> repository.search(q) }
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),
+            initialValue = emptyList()
+        )
+
+    fun onQueryChanged(newQuery: String) {
+        savedStateHandle[KEY_QUERY] = newQuery
+    }
+
+    companion object {
+        private const val KEY_QUERY = "search_query"
+    }
+}
+```
+
+---
+
+## Saving Complex Types
+
+```kotlin
+// ✅ Parcelable types work directly
+@Parcelize
+data class FilterState(
+    val category: String,
+    val sortOrder: String,
+    val minPrice: Int
+) : Parcelable
+
+@HiltViewModel
+class ProductViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle
+) : ViewModel() {
+
+    var filterState: StateFlow<FilterState> = savedStateHandle
+        .getStateFlow("filter", FilterState("all", "asc", 0))
+
+    fun applyFilter(filter: FilterState) {
+        savedStateHandle["filter"] = filter
+    }
+}
+
+// ✅ Primitive types — no Parcelable needed
+savedStateHandle["page"] = 1
+savedStateHandle["isExpanded"] = true
+savedStateHandle["selectedId"] = "user_123"
+```
+
+---
+
+## Combining SavedStateHandle with Repository
+
+```kotlin
+@HiltViewModel
+class UserListViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val repository: UserRepository
+) : ViewModel() {
+
+    // Persisted: selected filter
+    private val selectedFilter = savedStateHandle
+        .getStateFlow("filter", "all")
+
+    // Not persisted: loaded data — reload from DB
+    val users: StateFlow<List<User>> = selectedFilter
+        .flatMapLatest { filter ->
+            repository.observeUsers(filter)
+        }
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),
+            initialValue = emptyList()
+        )
+
+    fun onFilterSelected(filter: String) {
+        savedStateHandle["filter"] = filter
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Saving large objects (bitmaps, full lists) in SavedStateHandle — use DB or files instead
+- Not using SavedStateHandle for user input — it's lost on process death
+- Reading navigation args from `Intent` in Activity when ViewModel is available
+- Using `onSaveInstanceState` in Activity/Fragment when SavedStateHandle covers it
+- Saving non-Parcelable custom types — causes crash at restore time
+- Duplicating state between SavedStateHandle and a separate StateFlow
+
+---
+
+## Related Skills
+
+- `process-death-recovery` — full process death survival strategy
+- `state-restoration` — broader state restoration patterns
+- `navigation` — passing arguments via NavController
+- `lifecycle` — when process death occurs
+- `viewmodel` — ViewModel lifecycle and scope