mobile-ai-agents 1.0.23

package/agents/android/compose-screen-builder/example-output.md

@@ -0,0 +1,568 @@
+# Example Output — Compose Screen Builder
+
+Generated from [`example-input.md`](example-input.md).
+
+---
+
+## File: OrderHistoryUiState.kt
+
+```kotlin
+package com.example.app.ui.orders.history
+
+// One-shot events that should not be replayed on recomposition.
+sealed class OrderHistoryUiEvent {
+    data class NavigateToDetail(val orderId: String) : OrderHistoryUiEvent()
+    object NavigateToHome : OrderHistoryUiEvent()
+    object NavigateUp : OrderHistoryUiEvent()
+}
+
+// Single source of truth for the screen's visual state.
+sealed class OrderHistoryUiState {
+    object Loading : OrderHistoryUiState()
+    object Empty : OrderHistoryUiState()
+    data class Success(
+        val orders: List<OrderUiModel>,
+        val isRefreshing: Boolean = false
+    ) : OrderHistoryUiState()
+    data class Error(val message: String) : OrderHistoryUiState()
+}
+
+data class OrderUiModel(
+    val orderId: String,
+    val displayId: String,           // e.g. "#ORD-4821"
+    val status: OrderStatus,
+    val itemCount: Int,
+    val totalPrice: String,          // pre-formatted, e.g. "$48.50"
+    val orderDate: String            // pre-formatted, e.g. "May 12, 2025"
+)
+
+enum class OrderStatus { DELIVERED, PROCESSING, CANCELLED }
+```
+
+---
+
+## File: OrderHistoryViewModel.kt
+
+```kotlin
+package com.example.app.ui.orders.history
+
+import androidx.lifecycle.SavedStateHandle
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.receiveAsFlow
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+@HiltViewModel
+class OrderHistoryViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val getOrderHistory: GetOrderHistoryUseCase
+) : ViewModel() {
+
+    // Pulled from navigation args — NavController puts them in SavedStateHandle automatically.
+    private val userId: String = checkNotNull(savedStateHandle["userId"])
+
+    private val _uiState = MutableStateFlow<OrderHistoryUiState>(OrderHistoryUiState.Loading)
+    val uiState: StateFlow<OrderHistoryUiState> = _uiState.asStateFlow()
+
+    // Channel for one-shot events — SharedFlow would re-emit on new collectors (config change).
+    // Channel with BUFFERED capacity holds the event until the screen collects it.
+    private val _uiEvents = Channel<OrderHistoryUiEvent>(Channel.BUFFERED)
+    val uiEvents = _uiEvents.receiveAsFlow()
+
+    init {
+        loadOrders()
+    }
+
+    fun loadOrders() {
+        viewModelScope.launch {
+            _uiState.value = OrderHistoryUiState.Loading
+            try {
+                val orders = getOrderHistory(userId)
+                _uiState.value = if (orders.isEmpty()) {
+                    OrderHistoryUiState.Empty
+                } else {
+                    OrderHistoryUiState.Success(orders = orders.map { it.toUiModel() })
+                }
+            } catch (e: CancellationException) {
+                throw e  // Never swallow CancellationException
+            } catch (e: Exception) {
+                _uiState.value = OrderHistoryUiState.Error(
+                    message = e.message ?: "Failed to load orders"
+                )
+            }
+        }
+    }
+
+    fun refresh() {
+        val current = _uiState.value
+        if (current is OrderHistoryUiState.Success) {
+            // Mark as refreshing without losing the existing list.
+            _uiState.value = current.copy(isRefreshing = true)
+        }
+        viewModelScope.launch {
+            try {
+                val orders = getOrderHistory(userId)
+                _uiState.value = if (orders.isEmpty()) {
+                    OrderHistoryUiState.Empty
+                } else {
+                    OrderHistoryUiState.Success(orders = orders.map { it.toUiModel() })
+                }
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                // On refresh failure, keep the existing list but stop the spinner.
+                if (_uiState.value is OrderHistoryUiState.Success) {
+                    _uiState.value = (current as OrderHistoryUiState.Success).copy(isRefreshing = false)
+                } else {
+                    _uiState.value = OrderHistoryUiState.Error(e.message ?: "Refresh failed")
+                }
+            }
+        }
+    }
+
+    fun onOrderTapped(orderId: String) {
+        viewModelScope.launch {
+            _uiEvents.send(OrderHistoryUiEvent.NavigateToDetail(orderId))
+        }
+    }
+
+    fun onStartShoppingTapped() {
+        viewModelScope.launch {
+            _uiEvents.send(OrderHistoryUiEvent.NavigateToHome)
+        }
+    }
+
+    fun onNavigateUp() {
+        viewModelScope.launch {
+            _uiEvents.send(OrderHistoryUiEvent.NavigateUp)
+        }
+    }
+}
+
+// --- Domain stub (place in domain module, zero Android imports) ---
+
+class GetOrderHistoryUseCase @Inject constructor(
+    private val repository: OrderRepository
+) {
+    suspend operator fun invoke(userId: String): List<Order> =
+        repository.getOrderHistory(userId)
+}
+
+// --- Mapper (place in UI or data-ui mapping layer) ---
+
+fun Order.toUiModel() = OrderUiModel(
+    orderId    = id,
+    displayId  = "#ORD-${id.takeLast(4).uppercase()}",
+    status     = when (status) {
+        "DELIVERED"  -> OrderStatus.DELIVERED
+        "PROCESSING" -> OrderStatus.PROCESSING
+        "CANCELLED"  -> OrderStatus.CANCELLED
+        else         -> OrderStatus.PROCESSING
+    },
+    itemCount  = items.size,
+    totalPrice = "$${String.format("%.2f", totalPrice)}",
+    orderDate  = date.toDisplayString()   // your date formatting extension
+)
+```
+
+---
+
+## File: OrderHistoryScreen.kt
+
+```kotlin
+package com.example.app.ui.orders.history
+
+import android.content.res.Configuration.UI_MODE_NIGHT_YES
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.rounded.ArrowBack
+import androidx.compose.material.icons.rounded.ShoppingBag
+import androidx.compose.material3.*
+import androidx.compose.material3.pulltorefresh.PullToRefreshBox
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.tooling.preview.Preview
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import androidx.navigation.NavController
+import androidx.navigation.compose.rememberNavController
+
+// ─── Route definition ────────────────────────────────────────────────────────
+
+object OrderHistoryRoute {
+    const val ROUTE = "order_history/{userId}"
+    fun build(userId: String) = "order_history/$userId"
+}
+
+// ─── Screen entry point ──────────────────────────────────────────────────────
+
+@Composable
+fun OrderHistoryScreen(
+    navController: NavController,
+    viewModel: OrderHistoryViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+
+    // One-shot event handling — collected once per composition lifetime.
+    LaunchedEffect(Unit) {
+        viewModel.uiEvents.collect { event ->
+            when (event) {
+                is OrderHistoryUiEvent.NavigateToDetail ->
+                    navController.navigate("order_detail/${event.orderId}")
+                OrderHistoryUiEvent.NavigateToHome ->
+                    navController.navigate("home") { popUpTo("home") { inclusive = false } }
+                OrderHistoryUiEvent.NavigateUp ->
+                    navController.navigateUp()
+            }
+        }
+    }
+
+    OrderHistoryContent(
+        uiState   = uiState,
+        onRefresh = viewModel::refresh,
+        onOrderTapped = viewModel::onOrderTapped,
+        onStartShopping = viewModel::onStartShoppingTapped,
+        onRetry   = viewModel::loadOrders,
+        onNavigateUp = viewModel::onNavigateUp
+    )
+}
+
+// ─── Stateless content (testable in isolation) ───────────────────────────────
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun OrderHistoryContent(
+    uiState: OrderHistoryUiState,
+    onRefresh: () -> Unit,
+    onOrderTapped: (String) -> Unit,
+    onStartShopping: () -> Unit,
+    onRetry: () -> Unit,
+    onNavigateUp: () -> Unit
+) {
+    Scaffold(
+        topBar = {
+            CenterAlignedTopAppBar(
+                title = { Text("My Orders") },
+                navigationIcon = {
+                    IconButton(
+                        onClick = onNavigateUp,
+                        modifier = Modifier.minimumInteractiveComponentSize()
+                    ) {
+                        Icon(
+                            imageVector = Icons.Rounded.ArrowBack,
+                            contentDescription = "Go back"
+                        )
+                    }
+                }
+            )
+        }
+    ) { innerPadding ->
+        when (uiState) {
+            OrderHistoryUiState.Loading -> OrderHistoryLoading(innerPadding)
+
+            OrderHistoryUiState.Empty -> OrderHistoryEmpty(
+                modifier = Modifier.padding(innerPadding),
+                onStartShopping = onStartShopping
+            )
+
+            is OrderHistoryUiState.Error -> OrderHistoryError(
+                message = uiState.message,
+                onRetry = onRetry,
+                modifier = Modifier.padding(innerPadding)
+            )
+
+            is OrderHistoryUiState.Success -> OrderHistorySuccess(
+                orders = uiState.orders,
+                isRefreshing = uiState.isRefreshing,
+                onRefresh = onRefresh,
+                onOrderTapped = onOrderTapped,
+                modifier = Modifier.padding(innerPadding)
+            )
+        }
+    }
+}
+
+// ─── State renderers ─────────────────────────────────────────────────────────
+
+@Composable
+private fun OrderHistoryLoading(paddingValues: PaddingValues) {
+    Box(
+        modifier = Modifier
+            .fillMaxSize()
+            .padding(paddingValues),
+        contentAlignment = Alignment.Center
+    ) {
+        CircularProgressIndicator(
+            modifier = Modifier.semantics { contentDescription = "Loading orders" }
+        )
+    }
+}
+
+@Composable
+private fun OrderHistoryEmpty(
+    onStartShopping: () -> Unit,
+    modifier: Modifier = Modifier
+) {
+    Column(
+        modifier = modifier.fillMaxSize(),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.Center
+    ) {
+        Icon(
+            imageVector = Icons.Rounded.ShoppingBag,
+            contentDescription = null,   // decorative — message text provides context
+            modifier = Modifier.size(72.dp),
+            tint = MaterialTheme.colorScheme.onSurfaceVariant
+        )
+        Spacer(Modifier.height(16.dp))
+        Text(
+            text = "No orders yet",
+            style = MaterialTheme.typography.titleMedium,
+            color = MaterialTheme.colorScheme.onSurface
+        )
+        Spacer(Modifier.height(8.dp))
+        Text(
+            text = "Your completed orders will appear here.",
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant
+        )
+        Spacer(Modifier.height(24.dp))
+        FilledTonalButton(onClick = onStartShopping) {
+            Text("Start Shopping")
+        }
+    }
+}
+
+@Composable
+private fun OrderHistoryError(
+    message: String,
+    onRetry: () -> Unit,
+    modifier: Modifier = Modifier
+) {
+    Column(
+        modifier = modifier.fillMaxSize(),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.Center
+    ) {
+        Text(
+            text = "Something went wrong",
+            style = MaterialTheme.typography.titleMedium
+        )
+        Spacer(Modifier.height(8.dp))
+        Text(
+            text = message,
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurfaceVariant
+        )
+        Spacer(Modifier.height(24.dp))
+        Button(onClick = onRetry) { Text("Retry") }
+    }
+}
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+private fun OrderHistorySuccess(
+    orders: List<OrderUiModel>,
+    isRefreshing: Boolean,
+    onRefresh: () -> Unit,
+    onOrderTapped: (String) -> Unit,
+    modifier: Modifier = Modifier
+) {
+    PullToRefreshBox(
+        isRefreshing = isRefreshing,
+        onRefresh = onRefresh,
+        modifier = modifier.fillMaxSize()
+    ) {
+        LazyColumn(
+            contentPadding = PaddingValues(horizontal = 16.dp, vertical = 12.dp),
+            verticalArrangement = Arrangement.spacedBy(12.dp)
+        ) {
+            items(
+                items = orders,
+                key = { it.orderId },           // stable key prevents unnecessary recomposition
+                contentType = { "order_card" }  // allows Compose to reuse composition nodes
+            ) { order ->
+                OrderCard(order = order, onClick = { onOrderTapped(order.orderId) })
+            }
+        }
+    }
+}
+
+// ─── Order card component ────────────────────────────────────────────────────
+
+@Composable
+private fun OrderCard(
+    order: OrderUiModel,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier
+) {
+    val statusColor = when (order.status) {
+        OrderStatus.DELIVERED  -> Color(0xFF2E7D32)   // exception: semantic color not in M3 scheme
+        OrderStatus.PROCESSING -> Color(0xFFE65100)
+        OrderStatus.CANCELLED  -> MaterialTheme.colorScheme.error
+    }
+    val statusLabel = when (order.status) {
+        OrderStatus.DELIVERED  -> "Delivered"
+        OrderStatus.PROCESSING -> "Processing"
+        OrderStatus.CANCELLED  -> "Cancelled"
+    }
+
+    Card(
+        modifier = modifier
+            .fillMaxWidth()
+            .clickable(
+                onClickLabel = "View order ${order.displayId}",
+                onClick = onClick
+            ),
+        colors = CardDefaults.cardColors(
+            containerColor = MaterialTheme.colorScheme.surfaceContainerLow
+        )
+    ) {
+        Column(modifier = Modifier.padding(16.dp)) {
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                horizontalArrangement = Arrangement.SpaceBetween,
+                verticalAlignment = Alignment.CenterVertically
+            ) {
+                Text(
+                    text = order.displayId,
+                    style = MaterialTheme.typography.titleSmall
+                )
+                Surface(
+                    color = statusColor.copy(alpha = 0.12f),
+                    shape = MaterialTheme.shapes.small
+                ) {
+                    Text(
+                        text = statusLabel,
+                        modifier = Modifier.padding(horizontal = 8.dp, vertical = 2.dp),
+                        style = MaterialTheme.typography.labelSmall,
+                        color = statusColor
+                    )
+                }
+            }
+            Spacer(Modifier.height(8.dp))
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                horizontalArrangement = Arrangement.SpaceBetween
+            ) {
+                Text(
+                    text = "${order.itemCount} ${if (order.itemCount == 1) "item" else "items"}",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant
+                )
+                Text(
+                    text = order.totalPrice,
+                    style = MaterialTheme.typography.bodyMedium
+                )
+            }
+            Spacer(Modifier.height(4.dp))
+            Text(
+                text = order.orderDate,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant
+            )
+        }
+    }
+}
+
+// ─── Previews ────────────────────────────────────────────────────────────────
+
+private val previewOrders = listOf(
+    OrderUiModel("1", "#ORD-4821", OrderStatus.DELIVERED,  3, "$48.50",  "May 12, 2025"),
+    OrderUiModel("2", "#ORD-3917", OrderStatus.PROCESSING, 1, "$12.99",  "May 10, 2025"),
+    OrderUiModel("3", "#ORD-3105", OrderStatus.CANCELLED,  2, "$29.00",  "Apr 28, 2025"),
+)
+
+@Preview(showBackground = true, name = "Light — Success")
+@Composable
+private fun OrderHistorySuccessPreview() {
+    MaterialTheme {
+        OrderHistoryContent(
+            uiState = OrderHistoryUiState.Success(orders = previewOrders),
+            onRefresh = {}, onOrderTapped = {}, onStartShopping = {}, onRetry = {}, onNavigateUp = {}
+        )
+    }
+}
+
+@Preview(showBackground = true, uiMode = UI_MODE_NIGHT_YES, name = "Dark — Success")
+@Composable
+private fun OrderHistorySuccessDarkPreview() {
+    MaterialTheme {
+        OrderHistoryContent(
+            uiState = OrderHistoryUiState.Success(orders = previewOrders),
+            onRefresh = {}, onOrderTapped = {}, onStartShopping = {}, onRetry = {}, onNavigateUp = {}
+        )
+    }
+}
+
+@Preview(showBackground = true, name = "Empty")
+@Composable
+private fun OrderHistoryEmptyPreview() {
+    MaterialTheme {
+        OrderHistoryContent(
+            uiState = OrderHistoryUiState.Empty,
+            onRefresh = {}, onOrderTapped = {}, onStartShopping = {}, onRetry = {}, onNavigateUp = {}
+        )
+    }
+}
+
+@Preview(showBackground = true, name = "Error")
+@Composable
+private fun OrderHistoryErrorPreview() {
+    MaterialTheme {
+        OrderHistoryContent(
+            uiState = OrderHistoryUiState.Error("Unable to connect to server"),
+            onRefresh = {}, onOrderTapped = {}, onStartShopping = {}, onRetry = {}, onNavigateUp = {}
+        )
+    }
+}
+```
+
+---
+
+## Navigation Registration
+
+Add this block to your `NavHost` in your app's main `NavGraph.kt`:
+
+```kotlin
+composable(
+    route = OrderHistoryRoute.ROUTE,
+    arguments = listOf(navArgument("userId") { type = NavType.StringType })
+) {
+    OrderHistoryScreen(navController = navController)
+}
+```
+
+Navigate to this screen from anywhere:
+
+```kotlin
+navController.navigate(OrderHistoryRoute.build(userId = currentUserId))
+```
+
+---
+
+## Gradle Dependencies
+
+```kotlin
+// All required for this screen — add to app/build.gradle.kts if not already present:
+implementation("androidx.compose.material3:material3:1.3.1")
+implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.8.7")
+implementation("androidx.lifecycle:lifecycle-runtime-compose:2.8.7")  // collectAsStateWithLifecycle
+implementation("androidx.hilt:hilt-navigation-compose:1.2.0")
+implementation("androidx.navigation:navigation-compose:2.8.5")
+```

package/agents/android/compose-ui-reviewer/README.md

@@ -0,0 +1,73 @@
+# Android Compose UI Reviewer Agent
+
+> A focused Compose-only reviewer. Paste a `@Composable` function and get a recomposition scope analysis, state hoisting assessment, `remember`/`derivedStateOf` correctness check, and `LazyColumn` performance audit.
+
+---
+
+## What This Agent Does
+
+Specialized for Compose-specific issues that the general Android Code Reviewer misses. Analyzes:
+
+- **Recomposition scope** — is state read inside the smallest possible lambda to minimize rebuild cost?
+- **`remember` vs `rememberSaveable` vs `derivedStateOf`** — is the right tool being used? Are `remember` keys correct?
+- **State hoisting** — is mutable state owned at the right level? Is there split-brain state?
+- **`LazyColumn` / `LazyRow`** — `key`, `contentType`, expensive operations inside `items { }`, `Column { items.forEach }` anti-pattern
+- **Side effects** — `LaunchedEffect`, `SideEffect`, `DisposableEffect` placement and key correctness
+- **Slot API design** — is complex child content passed as a `@Composable () -> Unit` lambda?
+- **Stability** — are unstable types (`List`, `Map`, regular classes) causing unnecessary recompositions?
+
+---
+
+## When to Use This Instead of the General Code Reviewer
+
+| Situation | Agent to Use |
+|---|---|
+| Full file review (architecture, coroutines, Compose) | `agents/android/code-reviewer` |
+| Compose-specific performance issue (jank, recompositions) | **This agent** |
+| LazyColumn scrolling is slow | **This agent** |
+| Unexplained UI flicker or state loss | **This agent** |
+| Compose compiler metrics showing unstable types | **This agent** |
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| [`agent.md`](agent.md) | Input format, output format, full system prompt |
+| [`example-input.md`](example-input.md) | FeedScreen with LazyColumn and recomposition issues |
+| [`example-output.md`](example-output.md) | Full recomposition + state hoisting report |
+
+---
+
+## Quick Start
+
+```
+COMPOSE_VERSION: 1.7
+KOTLIN_VERSION: 2.0
+FILE_PATH: ui/feed/FeedScreen.kt
+CODE:
+[paste your @Composable function]
+```
+
+---
+
+## Output Preview
+
+```
+[CRITICAL] FeedScreen — SimpleDateFormat instantiated inside LazyColumn items lambda
+  Problem : Created fresh for every post on every recomposition — expensive object allocation.
+  Fix     : remember(post.createdAt) { SimpleDateFormat(...).format(post.createdAt) }
+            Or: format in the ViewModel and expose pre-formatted strings.
+
+[WARNING]  FeedScreen — LazyColumn items missing key parameter
+  Problem : Without key, any list change causes PostItem to lose its isExpanded state.
+  Fix     : items(posts, key = { it.id }) { post -> ... }
+```
+
+---
+
+## Related Agents
+
+- [`agents/android/code-reviewer`](../code-reviewer/) — full-file review including architecture and coroutines
+- [`agents/android/compose-screen-builder`](../compose-screen-builder/) — generate Compose screens that follow these patterns from the start