@mmerterden/multi-agent-pipeline 20.0.0 → 20.2.0

package/pipeline/skills/shared/external/compose-components/references/patterns.md

@@ -0,0 +1,200 @@
+# Jetpack Compose Components Patterns
+
+Full code examples backing the guidance in `SKILL.md`. Headings mirror the
+SKILL.md sections.
+
+## Contents
+
+- [Two-Layer Design Tokens](#two-layer-design-tokens)
+- [Bridging Tokens to Material 3](#bridging-tokens-to-material-3)
+- [Component Catalog](#component-catalog)
+
+## Two-Layer Design Tokens
+
+Layer 1 is a machine-generated raw-token source: one file, never hand-edited,
+the single source of truth for every primitive value. Layer 2 is a hand-authored
+semantic wrapper: `@Immutable` data classes that name each role and reference the
+raw tokens, never a literal hex or `sp`. Each semantic model exposes a `light()`
+and a `dark()` variant.
+
+```kotlin
+// Layer 1: generated, do not edit. Produced by the token codegen pipeline.
+object RawTokens {
+    val neutral0 = Color(0xFFFFFFFF)
+    val neutral900 = Color(0xFF1C1B1F)
+    val neutral1000 = Color(0xFF000000)
+    val red600 = Color(0xFFBA1A1A)
+    val red200 = Color(0xFFFFB4AB)
+    val fontSizeBody = 16.sp
+    val lineHeightBody = 24.sp
+    val fontSizeTitle = 22.sp
+    val lineHeightTitle = 28.sp
+}
+```
+
+```kotlin
+// Layer 2: hand-authored semantic wrapper.
+@Immutable
+data class AppColors(
+    val background: Color,
+    val onBackground: Color,
+    val brandPrimary: Color,
+    val brandOnPrimary: Color,
+    val surface: Color,
+    val danger: Color,
+) {
+    companion object {
+        fun light() = AppColors(
+            background = RawTokens.neutral0,
+            onBackground = RawTokens.neutral900,
+            brandPrimary = RawTokens.red600,
+            brandOnPrimary = RawTokens.neutral0,
+            surface = RawTokens.neutral0,
+            danger = RawTokens.red600,
+        )
+
+        fun dark() = AppColors(
+            background = RawTokens.neutral1000,
+            onBackground = RawTokens.neutral0,
+            brandPrimary = RawTokens.red200,
+            brandOnPrimary = RawTokens.neutral900,
+            surface = RawTokens.neutral1000,
+            danger = RawTokens.red200,
+        )
+    }
+}
+
+@Immutable
+data class AppTypography(
+    val body: TextStyle,
+    val title: TextStyle,
+) {
+    companion object {
+        fun default() = AppTypography(
+            body = TextStyle(
+                fontSize = RawTokens.fontSizeBody,
+                lineHeight = RawTokens.lineHeightBody,
+            ),
+            title = TextStyle(
+                fontSize = RawTokens.fontSizeTitle,
+                lineHeight = RawTokens.lineHeightTitle,
+                fontWeight = FontWeight.Medium,
+            ),
+        )
+    }
+}
+```
+
+The codegen pipeline that produces Layer 1 is a separate concern; see the
+`android-design-tokens-codegen` skill. This skill covers the consumption side
+only.
+
+## Bridging Tokens to Material 3
+
+Bridge the semantic tokens to both worlds. Select an M3
+`light`/`darkColorScheme` built from the tokens so stock Material components
+(`Button`, `TopAppBar`, `Card`) inherit the brand colors, and expose the richer
+token set through `CompositionLocalProvider`. Read the rich set through a
+`Theme.colors` / `Theme.typography` accessor marked `@ReadOnlyComposable`.
+
+```kotlin
+val LocalAppColors = staticCompositionLocalOf { AppColors.light() }
+val LocalAppTypography = staticCompositionLocalOf { AppTypography.default() }
+
+private fun AppColors.toMaterialColorScheme(darkTheme: Boolean): ColorScheme {
+    val base = if (darkTheme) darkColorScheme() else lightColorScheme()
+    return base.copy(
+        primary = brandPrimary,
+        onPrimary = brandOnPrimary,
+        background = background,
+        onBackground = onBackground,
+        surface = surface,
+        error = danger,
+    )
+}
+
+private fun AppTypography.toMaterialTypography(): Typography =
+    Typography(bodyLarge = body, titleLarge = title)
+
+@Composable
+fun AppTheme(
+    darkTheme: Boolean = isSystemInDarkTheme(),
+    content: @Composable () -> Unit,
+) {
+    val colors = if (darkTheme) AppColors.dark() else AppColors.light()
+    val typography = AppTypography.default()
+
+    CompositionLocalProvider(
+        LocalAppColors provides colors,
+        LocalAppTypography provides typography,
+    ) {
+        MaterialTheme(
+            colorScheme = colors.toMaterialColorScheme(darkTheme),
+            typography = typography.toMaterialTypography(),
+            content = content,
+        )
+    }
+}
+
+object Theme {
+    val colors: AppColors
+        @Composable @ReadOnlyComposable get() = LocalAppColors.current
+    val typography: AppTypography
+        @Composable @ReadOnlyComposable get() = LocalAppTypography.current
+}
+```
+
+Stock Material components read `MaterialTheme.colorScheme`; custom components read
+the richer set:
+
+```kotlin
+@Composable
+fun PriceTag(text: String) {
+    Text(
+        text = text,
+        color = Theme.colors.brandPrimary,
+        style = Theme.typography.title,
+    )
+}
+```
+
+## Component Catalog
+
+A component-catalog module (for example Showkase) renders every annotated
+composable and color/typography token in a browsable in-app gallery. Keep the
+annotation cheap and universal so it can sit on previews across every module, but
+gate the KSP processor behind a build flag so the browser codegen costs nothing
+on a normal build.
+
+```kotlin
+// A preview, annotated for the catalog. The annotation dependency is universal.
+@ShowkaseComposable(name = "InfoCard", group = "Cards")
+@Preview
+@Composable
+private fun InfoCardCatalog() {
+    AppTheme { InfoCard(/* sample slots */) }
+}
+```
+
+```kotlin
+// ui module build.gradle.kts
+dependencies {
+    implementation(libs.showkase.annotation) // cheap, always present
+    if (providers.gradleProperty("enableShowkase").isPresent) {
+        ksp(libs.showkase.processor)          // browser codegen only when asked
+    }
+}
+```
+
+```kotlin
+// The catalog entry point, compiled only when the processor ran.
+class CatalogActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent { ShowkaseBrowser(getMetadata()) }
+    }
+}
+```
+
+Build the catalog on demand with `./gradlew :app:installDebug -PenableShowkase`;
+routine builds skip the processor entirely.

package/pipeline/skills/shared/external/compose-navigation/SKILL.md

@@ -16,6 +16,9 @@ passing.
 - [NavHost Setup](#navhost-setup)
 - [Navigating Between Screens](#navigating-between-screens)
 - [Arguments (Type-Safe)](#arguments-type-safe)
+- [Custom NavType for Complex Arguments](#custom-navtype-for-complex-arguments)
+- [SafeNavController via CompositionLocal](#safenavcontroller-via-compositionlocal)
+- [Navigation as a One-Shot Effect](#navigation-as-a-one-shot-effect)
 - [Nested Navigation Graphs](#nested-navigation-graphs)
 - [Bottom Navigation](#bottom-navigation)
 - [Deep Links](#deep-links)
@@ -163,10 +166,70 @@ composable<FlightDetailRoute> { backStackEntry ->
 | `Int`, `Long`, `Float`, `Boolean` | Native | Serialized directly |
 | `Enum` | Via `@Serializable` | Add `@Serializable` to enum class |
 | `List<String>` | Via serialization | Works with kotlinx.serialization |
-| Custom objects | Not recommended | Pass ID and fetch from ViewModel instead |
+| Custom objects | Via custom `NavType` | Register in a `typeMap` (see below) |
 
-Rule: Pass only primitive identifiers via routes. Let the destination ViewModel
-fetch the full object. Do not serialize complex objects into the route.
+Rule: Prefer primitive IDs and fetch the full object in the destination
+ViewModel; when a small value object must ride in the route, use a custom
+`NavType` (below) rather than flattening it into primitives.
+
+## Custom NavType for Complex Arguments
+
+Passing a complex `@Serializable` type through a route needs a custom `NavType`
+in a `typeMap` shared by `composable<>()` and every `toRoute` read (else only primitives resolve).
+
+```kotlin
+val searchTypeMap = mapOf(typeOf<PassengerFilter>() to PassengerFilterNavType)
+
+composable<SearchRoute>(typeMap = searchTypeMap) { entry ->
+    val route = entry.toRoute<SearchRoute>(typeMap = searchTypeMap)
+    SearchScreen(filter = route.filter)
+}
+```
+
+A shared holder owns the one `typeMap`; the ViewModel reads the arg back with
+`savedStateHandle.toRoute<SearchRoute>(typeMap = searchTypeMap)`. Full `NavType`
++ holder: [references/patterns.md#custom-navtype-type-map](references/patterns.md#custom-navtype-type-map).
+
+## SafeNavController via CompositionLocal
+
+Never give feature code a raw `NavHostController`. Wrap it to expose only the
+methods features need, each in `runCatching` to swallow rapid-tap double-navigation / illegal-state crashes, and provide it via a `CompositionLocal`.
+
+```kotlin
+class SafeNavController(private val controller: NavHostController) {
+    fun navigate(route: Any) = runCatching { controller.navigate(route) }
+    fun navigateReplacing(route: Any, popUpToType: KClass<*>) = runCatching {
+        controller.navigate(route) { popUpTo(popUpToType) { inclusive = true }; launchSingleTop = true }
+    }
+    fun back() = runCatching { controller.popBackStack() }
+}
+
+val LocalSafeNavController = staticCompositionLocalOf<SafeNavController> { error("not provided") }
+```
+
+Provide once at the NavHost; screens read `LocalSafeNavController.current`. Full
+setup + helpers: [references/patterns.md#safenavcontroller](references/patterns.md#safenavcontroller).
+
+## Navigation as a One-Shot Effect
+
+Keep navigation types out of the ViewModel: it emits `NavigateX` events (a
+`sealed interface`) on a one-shot `Channel`; the owning composable translates
+each into a call, keeping the ViewModel navigation-free and unit-testable.
+
+```kotlin
+LaunchedEffect(Unit) {                      // in the composable that owns the NavController
+    viewModel.navEvents.collect { event ->
+        when (event) {
+            is HomeNavEvent.ToDetail -> nav.navigate(DetailRoute(event.id))
+            HomeNavEvent.ToSearch -> nav.navigate(SearchRoute())
+        }
+    }
+}
+```
+
+Full `sealed interface` + ViewModel channel wiring:
+[references/patterns.md#navigation-as-a-one-shot-effect](references/patterns.md#navigation-as-a-one-shot-effect).
+Complements the event seam in the `android-mvi-viewmodel` skill.
 
 ## Nested Navigation Graphs
 

package/pipeline/skills/shared/external/compose-navigation/references/patterns.md

@@ -0,0 +1,191 @@
+# Compose Navigation -- Reference Patterns
+
+Full code for the patterns summarized in `SKILL.md`. Load the section you need
+when implementing that specific navigation feature.
+
+## Contents
+
+- [Custom NavType Type-Map](#custom-navtype-type-map)
+- [SafeNavController](#safenavcontroller)
+- [Navigation as a One-Shot Effect](#navigation-as-a-one-shot-effect)
+
+## Custom NavType Type-Map
+
+Type-safe routes serialize primitives out of the box. A complex `@Serializable`
+argument needs a custom `NavType` plus a `typeMap` shared by the
+`composable<>()` registration and every `toRoute` read. Without the type-map,
+only primitive nav args resolve and the route fails to build.
+
+```kotlin
+@Serializable
+data class PassengerFilter(val cabin: String, val adults: Int, val children: Int)
+
+@Serializable
+data class SearchRoute(val filter: PassengerFilter)
+
+val PassengerFilterNavType = object : NavType<PassengerFilter>(isNullableAllowed = false) {
+    override fun get(bundle: Bundle, key: String): PassengerFilter? =
+        bundle.getString(key)?.let { Json.decodeFromString(it) }
+
+    override fun parseValue(value: String): PassengerFilter =
+        Json.decodeFromString(Uri.decode(value))
+
+    override fun serializeAsValue(value: PassengerFilter): String =
+        Uri.encode(Json.encodeToString(value))
+
+    override fun put(bundle: Bundle, key: String, value: PassengerFilter) {
+        bundle.putString(key, Json.encodeToString(value))
+    }
+}
+```
+
+### Shared holder
+
+One holder owns the map so the registration and every read agree:
+
+```kotlin
+object NavTypeMaps {
+    val search: Map<KType, NavType<*>> =
+        mapOf(typeOf<PassengerFilter>() to PassengerFilterNavType)
+}
+```
+
+### Registration and read
+
+```kotlin
+composable<SearchRoute>(typeMap = NavTypeMaps.search) { entry ->
+    val route = entry.toRoute<SearchRoute>(typeMap = NavTypeMaps.search)
+    SearchScreen(filter = route.filter)
+}
+```
+
+### Reading in the ViewModel
+
+`SavedStateHandle.toRoute` takes the same map:
+
+```kotlin
+@HiltViewModel
+class SearchViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+) : ViewModel() {
+    private val filter: PassengerFilter =
+        savedStateHandle.toRoute<SearchRoute>(typeMap = NavTypeMaps.search).filter
+}
+```
+
+## SafeNavController
+
+Feature code should never hold a raw `NavHostController`. Wrap it so features see
+only the methods they need, and wrap each call in `runCatching` so a
+double-navigation or illegal-state exception from a rapid double tap is
+swallowed instead of crashing.
+
+```kotlin
+class SafeNavController(private val controller: NavHostController) {
+
+    fun navigate(route: Any) {
+        runCatching { controller.navigate(route) }
+    }
+
+    fun navigateReplacing(route: Any, popUpToType: KClass<*>) {
+        runCatching {
+            controller.navigate(route) {
+                popUpTo(popUpToType) { inclusive = true }
+                launchSingleTop = true
+            }
+        }
+    }
+
+    fun navigateClearingStack(route: Any) {
+        runCatching {
+            controller.navigate(route) { popUpTo(0) { inclusive = true } }
+        }
+    }
+
+    fun back() {
+        runCatching { controller.popBackStack() }
+    }
+}
+
+val LocalSafeNavController = staticCompositionLocalOf<SafeNavController> {
+    error("SafeNavController not provided")
+}
+```
+
+### Providing it once at the NavHost
+
+```kotlin
+@Composable
+fun AppNavHost(navController: NavHostController = rememberNavController()) {
+    val safeNav = remember(navController) { SafeNavController(navController) }
+    CompositionLocalProvider(LocalSafeNavController provides safeNav) {
+        NavHost(navController = navController, startDestination = HomeRoute) {
+            composable<HomeRoute> { HomeRoute() }
+            composable<DetailRoute> { DetailRoute() }
+        }
+    }
+}
+```
+
+Feature screens read `LocalSafeNavController.current` and never receive the raw
+controller as a parameter.
+
+## Navigation as a One-Shot Effect
+
+The ViewModel emits navigation intents as one-shot events; the composable that
+owns the `NavController` translates each into a navigation call. This keeps the
+ViewModel free of navigation types and unit-testable (assert emitted events, no
+`NavController` mock needed).
+
+### ViewModel side
+
+```kotlin
+sealed interface HomeNavEvent {
+    data class ToDetail(val id: String) : HomeNavEvent
+    data object ToSearch : HomeNavEvent
+}
+
+@HiltViewModel
+class HomeViewModel @Inject constructor() : ViewModel() {
+
+    private val _navEvents = Channel<HomeNavEvent>(Channel.BUFFERED)
+    val navEvents: Flow<HomeNavEvent> = _navEvents.receiveAsFlow()
+
+    fun onItemClick(id: String) {
+        viewModelScope.launch { _navEvents.send(HomeNavEvent.ToDetail(id)) }
+    }
+
+    fun onSearchClick() {
+        viewModelScope.launch { _navEvents.send(HomeNavEvent.ToSearch) }
+    }
+}
+```
+
+### Composable side
+
+```kotlin
+@Composable
+fun HomeRoute(viewModel: HomeViewModel = hiltViewModel()) {
+    val nav = LocalSafeNavController.current
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+
+    LaunchedEffect(Unit) {
+        viewModel.navEvents.collect { event ->
+            when (event) {
+                is HomeNavEvent.ToDetail -> nav.navigate(DetailRoute(event.id))
+                HomeNavEvent.ToSearch -> nav.navigate(SearchRoute(PassengerFilter("ECONOMY", 1, 0)))
+            }
+        }
+    }
+
+    HomeScreen(
+        state = uiState,
+        onItemClick = viewModel::onItemClick,
+        onSearchClick = viewModel::onSearchClick,
+    )
+}
+```
+
+The `Channel` (not a `StateFlow`) guarantees each navigation fires once and is
+not replayed on recomposition or config change. This complements the event seam
+in the `android-mvi-viewmodel` skill.