android-sdd 1.0.0

package/skills/Navigation/Deep Navigation/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: deep-navigation
+description: >
+  Deep link handling in Android with Jetpack Compose Navigation.
+  Load this skill when implementing URI-based deep links, handling
+  incoming intents from notifications or external apps, defining
+  deep link patterns, or testing deep link navigation.
+---
+
+# Deep Navigation
+
+## Overview
+Deep links allow the app to navigate directly to a specific screen from an external source — a notification, a web URL, another app, or an NFC tag. Navigation Compose supports deep links via `deepLinks` parameter on composable destinations.
+
+---
+
+## Core Principles
+
+- Define deep link URIs in a central constants object — never inline strings
+- Always verify deep links in the manifest with `android:autoVerify="true"` for App Links
+- Handle deep link arguments the same way as regular nav arguments — via `toRoute()`
+- Deep links must be **tested with adb** before release
+- Provide fallback navigation when a deep link destination requires authentication
+
+---
+
+## Manifest Setup
+
+```xml
+<!-- AndroidManifest.xml -->
+<activity
+    android:name=".MainActivity"
+    android:exported="true">
+
+    <intent-filter android:autoVerify="true">
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data android:scheme="https"
+              android:host="example.com"
+              android:pathPrefix="/users" />
+    </intent-filter>
+
+    <!-- Custom scheme for internal deep links -->
+    <intent-filter>
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data android:scheme="myapp" />
+    </intent-filter>
+
+</activity>
+```
+
+---
+
+## Route with Deep Link
+
+```kotlin
+// ✅ Define deep link URIs centrally
+object DeepLinks {
+    const val BASE = "https://example.com"
+    const val USER_DETAIL = "$BASE/users/{userId}"
+    const val ORDER_DETAIL = "$BASE/orders/{orderId}"
+
+    // Custom scheme
+    const val NOTIFICATION_BASE = "myapp://notification"
+    const val NOTIFICATION_DETAIL = "$NOTIFICATION_BASE/{notificationId}"
+}
+
+// ✅ Attach deep links to composable destination
+composable<UserDetailRoute>(
+    deepLinks = listOf(
+        navDeepLink<UserDetailRoute>(
+            basePath = "https://example.com/users"
+        )
+    )
+) { backStackEntry ->
+    val route: UserDetailRoute = backStackEntry.toRoute()
+    UserDetailScreen(userId = route.userId)
+}
+
+// ✅ Legacy string-based deep link (if not using type-safe routes)
+composable(
+    route = "user/{userId}",
+    deepLinks = listOf(
+        navDeepLink {
+            uriPattern = DeepLinks.USER_DETAIL
+        }
+    ),
+    arguments = listOf(navArgument("userId") { type = NavType.StringType })
+) { backStackEntry ->
+    val userId = backStackEntry.arguments?.getString("userId") ?: return@composable
+    UserDetailScreen(userId = userId)
+}
+```
+
+---
+
+## Handling Incoming Intent in Activity
+
+```kotlin
+// ✅ Pass intent to NavHost for deep link handling
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            AppTheme {
+                val navController = rememberNavController()
+                AppNavHost(navController = navController)
+            }
+        }
+    }
+}
+
+// Navigation Compose handles intent automatically when
+// NavHost is set up — no manual intent parsing needed
+```
+
+---
+
+## Notification Deep Links
+
+```kotlin
+// ✅ Build PendingIntent with deep link URI
+fun buildNotificationIntent(context: Context, userId: String): PendingIntent {
+    val deepLinkUri = Uri.parse("https://example.com/users/$userId")
+
+    val intent = Intent(Intent.ACTION_VIEW, deepLinkUri).apply {
+        setPackage(context.packageName)
+        flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP
+    }
+
+    return TaskStackBuilder.create(context).run {
+        addNextIntentWithParentStack(intent)
+        getPendingIntent(
+            userId.hashCode(),
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+        )!!
+    }
+}
+```
+
+---
+
+## Auth Guard for Deep Links
+
+```kotlin
+// ✅ Redirect unauthenticated deep link to login
+@Composable
+fun AppNavHost(navController: NavHostController) {
+    val authState by authViewModel.state.collectAsStateWithLifecycle()
+
+    NavHost(navController = navController, startDestination = HomeRoute) {
+
+        composable<UserDetailRoute> { backStackEntry ->
+            if (authState !is AuthState.Authenticated) {
+                LaunchedEffect(Unit) {
+                    navController.navigate(LoginRoute) {
+                        // store original destination for post-login redirect
+                        navController.currentBackStackEntry
+                            ?.savedStateHandle
+                            ?.set("pending_route", "user_detail")
+                    }
+                }
+            } else {
+                val route: UserDetailRoute = backStackEntry.toRoute()
+                UserDetailScreen(userId = route.userId)
+            }
+        }
+    }
+}
+```
+
+---
+
+## Testing Deep Links with ADB
+
+```bash
+# Test HTTPS deep link
+adb shell am start \
+  -W -a android.intent.action.VIEW \
+  -d "https://example.com/users/123" \
+  com.example.app
+
+# Test custom scheme
+adb shell am start \
+  -W -a android.intent.action.VIEW \
+  -d "myapp://notification/456" \
+  com.example.app
+```
+
+---
+
+## Anti-Patterns
+
+- Inline URI strings in `navDeepLink {}` — define in a constants object
+- Not adding `autoVerify="true"` for HTTPS App Links — won't be verified by Google
+- Parsing the intent URI manually in `onCreate` — Navigation Compose handles this
+- Not handling the unauthenticated deep link case — sends user to a broken state
+- Using deep links for in-app navigation between features — use regular routes
+
+---
+
+## Related Skills
+- `navigation` — core navigation setup
+- `nested-navigation` — deep links into nested graphs
+- `notification` — building notifications with deep link intents
+- `manifest` — intent filter configuration

package/skills/Navigation/Navigation/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: navigation
+description: >
+  Navigation setup and patterns in Jetpack Compose using Navigation Compose.
+  Load this skill when setting up the NavHost, defining routes, passing
+  arguments between screens, handling back stack, or structuring navigation
+  in a single-activity architecture.
+---
+
+# Navigation
+
+## Overview
+Navigation Compose is the standard navigation library for Jetpack Compose. It manages the back stack, screen transitions, and argument passing within a single-activity architecture. Routes are defined as type-safe objects using Kotlin serialization.
+
+---
+
+## Core Principles
+
+- One `NavHost` per app — never nest multiple NavHosts at the top level
+- Routes must be **type-safe** using `@Serializable` data objects/classes — never string literals
+- Navigation logic belongs in the **ViewModel or event callbacks** — never inside composables directly
+- Pass only **IDs** between screens — never full objects
+- Always use `launchSingleTop = true` for bottom navigation items
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+navigation-compose = "2.8.0"
+
+[libraries]
+navigation-compose = { module = "androidx.navigation:navigation-compose", version.ref = "navigation-compose" }
+```
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation(libs.navigation.compose)
+}
+```
+
+---
+
+## Type-Safe Routes
+
+```kotlin
+// ✅ Define routes as serializable objects/classes
+@Serializable
+data object HomeRoute
+
+@Serializable
+data object SettingsRoute
+
+@Serializable
+data class UserDetailRoute(val userId: String)
+
+@Serializable
+data class EditUserRoute(val userId: String, val mode: String = "edit")
+```
+
+---
+
+## NavHost Setup
+
+```kotlin
+// ✅ NavHost at the app root
+@Composable
+fun AppNavHost(
+    navController: NavHostController = rememberNavController()
+) {
+    NavHost(
+        navController = navController,
+        startDestination = HomeRoute
+    ) {
+        composable<HomeRoute> {
+            HomeScreen(
+                onNavigateToUser = { userId ->
+                    navController.navigate(UserDetailRoute(userId))
+                }
+            )
+        }
+
+        composable<UserDetailRoute> { backStackEntry ->
+            val route: UserDetailRoute = backStackEntry.toRoute()
+            UserDetailScreen(
+                userId = route.userId,
+                onNavigateBack = { navController.popBackStack() },
+                onNavigateToEdit = {
+                    navController.navigate(EditUserRoute(route.userId))
+                }
+            )
+        }
+
+        composable<EditUserRoute> { backStackEntry ->
+            val route: EditUserRoute = backStackEntry.toRoute()
+            EditUserScreen(
+                userId = route.userId,
+                onNavigateBack = { navController.popBackStack() }
+            )
+        }
+
+        composable<SettingsRoute> {
+            SettingsScreen(
+                onNavigateBack = { navController.popBackStack() }
+            )
+        }
+    }
+}
+```
+
+---
+
+## Bottom Navigation
+
+```kotlin
+// ✅ Bottom navigation with launchSingleTop
+@Composable
+fun AppScaffold(navController: NavHostController) {
+    val navBackStackEntry by navController.currentBackStackEntryAsState()
+    val currentDestination = navBackStackEntry?.destination
+
+    Scaffold(
+        bottomBar = {
+            NavigationBar {
+                bottomNavItems.forEach { item ->
+                    NavigationBarItem(
+                        icon = { Icon(item.icon, contentDescription = null) },
+                        label = { Text(item.label) },
+                        selected = currentDestination?.hierarchy?.any {
+                            it.hasRoute(item.route::class)
+                        } == true,
+                        onClick = {
+                            navController.navigate(item.route) {
+                                popUpTo(navController.graph.findStartDestination().id) {
+                                    saveState = true
+                                }
+                                launchSingleTop = true   // ✅ avoid duplicates
+                                restoreState = true      // ✅ restore tab state
+                            }
+                        }
+                    )
+                }
+            }
+        }
+    ) { padding ->
+        AppNavHost(
+            navController = navController,
+            modifier = Modifier.padding(padding)
+        )
+    }
+}
+```
+
+---
+
+## Passing Results Back
+
+```kotlin
+// ✅ Pass result back via SavedStateHandle
+// In destination screen
+navController.previousBackStackEntry
+    ?.savedStateHandle
+    ?.set("selected_item_id", selectedItemId)
+navController.popBackStack()
+
+// ✅ Observe in source screen's ViewModel
+class SourceViewModel(
+    savedStateHandle: SavedStateHandle
+) : ViewModel() {
+    val selectedItemId = savedStateHandle
+        .getStateFlow<String?>("selected_item_id", null)
+}
+```
+
+---
+
+## Navigation Extensions
+
+```kotlin
+// ✅ Extension to reduce boilerplate
+fun NavController.navigateSingleTop(route: Any) {
+    navigate(route) {
+        launchSingleTop = true
+    }
+}
+
+fun NavController.navigateAndClearStack(route: Any) {
+    navigate(route) {
+        popUpTo(0) { inclusive = true }
+        launchSingleTop = true
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using raw string routes — loses type safety and refactoring support
+- Passing full objects (Parcelable/Serializable) as nav arguments — pass IDs only
+- Calling `navController.navigate()` directly inside a composable body — use callbacks or events
+- Nesting `NavHost` inside another `NavHost` at the top level — use nested graphs instead
+- Not using `launchSingleTop` for bottom nav — creates duplicate back stack entries
+- Holding `NavController` reference in ViewModel — pass navigation events as lambdas
+
+---
+
+## Related Skills
+- `compose-navigation` — advanced NavHost patterns and animations
+- `deep-navigation` — deep links and external navigation
+- `nested-navigation` — nested graphs and feature module navigation
+- `savedstatehandle` — passing data between screens

package/skills/Navigation/Nested Navigation/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: nested-navigation
+description: >
+  Nested navigation graphs in Jetpack Compose Navigation.
+  Load this skill when organizing routes into feature-scoped graphs,
+  implementing tab-based navigation with independent back stacks,
+  isolating feature module navigation, or structuring auth vs main flows.
+---
+
+# Nested Navigation
+
+## Overview
+Nested navigation graphs group related destinations into a sub-graph with its own start destination. This enables feature isolation, independent back stacks per tab, and clean separation between flows (e.g. auth flow vs main flow).
+
+---
+
+## Core Principles
+
+- Each feature or flow gets its own nested graph — never dump all routes into one flat NavHost
+- Nested graphs have their own `startDestination` — the entry point is the only public route
+- Tab-based navigation uses `saveState`/`restoreState` to preserve independent back stacks
+- Auth flow and main flow must be separate nested graphs — not mixed in the same graph
+- Never navigate directly to an internal route of another feature's graph
+
+---
+
+## Basic Nested Graph
+
+```kotlin
+// ✅ Define feature graph routes
+@Serializable data object UserGraph
+@Serializable data object UserListRoute
+@Serializable data class UserDetailRoute(val userId: String)
+@Serializable data class UserEditRoute(val userId: String)
+
+// ✅ Register nested graph in NavHost
+NavHost(navController = navController, startDestination = UserGraph) {
+
+    navigation<UserGraph>(startDestination = UserListRoute) {
+
+        composable<UserListRoute> {
+            UserListScreen(
+                onNavigateToDetail = { userId ->
+                    navController.navigate(UserDetailRoute(userId))
+                }
+            )
+        }
+
+        composable<UserDetailRoute> { backStackEntry ->
+            val route: UserDetailRoute = backStackEntry.toRoute()
+            UserDetailScreen(
+                userId = route.userId,
+                onNavigateToEdit = {
+                    navController.navigate(UserEditRoute(route.userId))
+                },
+                onNavigateBack = { navController.popBackStack() }
+            )
+        }
+
+        composable<UserEditRoute> { backStackEntry ->
+            val route: UserEditRoute = backStackEntry.toRoute()
+            UserEditScreen(
+                userId = route.userId,
+                onNavigateBack = { navController.popBackStack() }
+            )
+        }
+    }
+}
+```
+
+---
+
+## Auth vs Main Flow
+
+```kotlin
+// ✅ Separate auth and main flows as nested graphs
+@Serializable data object AuthGraph
+@Serializable data object LoginRoute
+@Serializable data object RegisterRoute
+
+@Serializable data object MainGraph
+@Serializable data object HomeRoute
+@Serializable data object SettingsRoute
+
+@Composable
+fun AppNavHost(
+    navController: NavHostController,
+    isAuthenticated: Boolean
+) {
+    NavHost(
+        navController = navController,
+        startDestination = if (isAuthenticated) MainGraph else AuthGraph
+    ) {
+
+        navigation<AuthGraph>(startDestination = LoginRoute) {
+            composable<LoginRoute> {
+                LoginScreen(
+                    onLoginSuccess = {
+                        navController.navigate(MainGraph) {
+                            popUpTo(AuthGraph) { inclusive = true }  // ✅ clear auth stack
+                        }
+                    },
+                    onNavigateToRegister = {
+                        navController.navigate(RegisterRoute)
+                    }
+                )
+            }
+            composable<RegisterRoute> {
+                RegisterScreen(
+                    onRegisterSuccess = {
+                        navController.navigate(MainGraph) {
+                            popUpTo(AuthGraph) { inclusive = true }
+                        }
+                    },
+                    onNavigateBack = { navController.popBackStack() }
+                )
+            }
+        }
+
+        navigation<MainGraph>(startDestination = HomeRoute) {
+            composable<HomeRoute> { HomeScreen() }
+            composable<SettingsRoute> { SettingsScreen() }
+        }
+    }
+}
+```
+
+---
+
+## Tab Navigation with Independent Back Stacks
+
+```kotlin
+// ✅ Each tab is a nested graph with its own back stack
+@Serializable data object HomeGraph
+@Serializable data object HomeRootRoute
+
+@Serializable data object SearchGraph
+@Serializable data object SearchRootRoute
+
+@Serializable data object ProfileGraph
+@Serializable data object ProfileRootRoute
+
+@Composable
+fun MainScreen() {
+    val navController = rememberNavController()
+
+    Scaffold(
+        bottomBar = {
+            BottomNavBar(navController = navController)
+        }
+    ) { padding ->
+        NavHost(
+            navController = navController,
+            startDestination = HomeGraph,
+            modifier = Modifier.padding(padding)
+        ) {
+            navigation<HomeGraph>(startDestination = HomeRootRoute) {
+                composable<HomeRootRoute> { HomeScreen() }
+                // more home destinations...
+            }
+
+            navigation<SearchGraph>(startDestination = SearchRootRoute) {
+                composable<SearchRootRoute> { SearchScreen() }
+                // more search destinations...
+            }
+
+            navigation<ProfileGraph>(startDestination = ProfileRootRoute) {
+                composable<ProfileRootRoute> { ProfileScreen() }
+                // more profile destinations...
+            }
+        }
+    }
+}
+
+// ✅ Bottom nav switching with state save/restore
+fun NavController.switchTab(route: Any) {
+    navigate(route) {
+        popUpTo(graph.findStartDestination().id) {
+            saveState = true     // ✅ save current tab's back stack
+        }
+        launchSingleTop = true
+        restoreState = true      // ✅ restore destination tab's back stack
+    }
+}
+```
+
+---
+
+## Popping to Graph Start
+
+```kotlin
+// ✅ Pop back to the start of a nested graph
+navController.popBackStack(route = UserListRoute, inclusive = false)
+
+// ✅ Pop the entire graph off the stack
+navController.popBackStack(route = UserGraph, inclusive = true)
+```
+
+---
+
+## Anti-Patterns
+
+- Flat NavHost with all routes at the same level — hard to maintain and reason about
+- Navigating directly to an internal route of another feature graph from outside it
+- Not using `saveState`/`restoreState` for tab navigation — back stack lost on tab switch
+- Not clearing the auth graph when navigating to main — user can back-navigate to login
+- Sharing a single `NavController` across nested `NavHost` composables
+
+---
+
+## Related Skills
+- `navigation` — core navigation setup and route definitions
+- `deep-navigation` — deep links into nested graphs
+- `compose-navigation` — transitions and animations between graphs