@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.1

package/pipeline/skills/shared/external/android-jetpack-compose-expert/SKILL.md

@@ -1,215 +1,140 @@
 ---
 name: android-jetpack-compose-expert
-description: "Expert guidance for building modern Android UIs with Jetpack Compose, covering state management, navigation, performance, and Material Design 3. Use when building or reviewing Compose UI, state handling or navigation."
-risk: safe
-source: community
-date_added: "2026-02-27"
+description: "Compose runtime expertise: state ownership, recomposition and stability, side-effect APIs, lazy lists, modifier order, Modifier.Node. Use when writing or reviewing composables, or when a screen recomposes too often or loses state."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
+  not-for: compose-components, android-performance
 ---
 
-# Android Jetpack Compose Expert
+# Jetpack Compose Runtime Expertise
 
-## Overview
+Compose calls your functions again whenever state they read changes. Almost
+every Compose bug is a disagreement between what the author thought would be
+re-run and what the runtime actually re-runs. This skill is about that model.
 
-A comprehensive guide for building production-quality Android applications using Jetpack Compose. This skill covers architectural patterns, state management with ViewModels, navigation type-safety, and performance optimization techniques.
+Sibling skills cover the rest: Material components and theming in
+`compose-components`, routes and back stack in `compose-navigation`, UI and
+ViewModel tests in `compose-testing`, layering and DI in `android-architecture`,
+the MVI base class in `android-mvi-viewmodel`, and profiling, Baseline Profiles
+and R8 in `android-performance`.
 
-## When to Use This Skill
+## The three phases
 
-- Use when starting a new Android project with Jetpack Compose.
-- Use when migrating legacy XML layouts to Compose.
-- Use when implementing complex UI state management and side effects.
-- Use when optimizing Compose performance (recomposition counts, stability).
-- Use when setting up Navigation with type safety.
+A frame runs composition (what to show), layout (where and how big), then
+drawing. A state read is tracked in the phase where it happens, and only that
+phase and the ones after it re-run when the value changes.
 
-## Step-by-Step Guide
+| Read happens in | Re-runs on change | Typical API |
+|---|---|---|
+| Composable body | composition, layout, draw | `Text(text = state.title)` |
+| Layout lambda | layout, draw | `Modifier.offset { IntOffset(x, 0) }` |
+| Draw lambda | draw only | `Modifier.drawBehind { drawRect(color) }` |
 
-### 1. Project Setup & Dependencies
-
-Ensure your `libs.versions.toml` includes the necessary Compose BOM and libraries.
-
-```kotlin
-[versions]
-composeBom = "2024.02.01"
-activityCompose = "1.8.2"
-
-[libraries]
-androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
-androidx-ui = { group = "androidx.compose.ui", name = "ui" }
-androidx-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
-androidx-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
-androidx-material3 = { group = "androidx.compose.material3", name = "material3" }
-androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
-```
-
-### 2. State Management Pattern (MVI/MVVM)
-
-Use `ViewModel` with `StateFlow` to expose UI state. Avoid exposing `MutableStateFlow`.
+Move fast-changing reads (scroll offsets, animation values) into the lambda
+variants so they skip composition entirely:
 
 ```kotlin
-// UI State Definition
-data class UserUiState(
-    val isLoading: Boolean = false,
-    val user: User? = null,
-    val error: String? = null
-)
-
-// ViewModel
-class UserViewModel @Inject constructor(
-    private val userRepository: UserRepository
-) : ViewModel() {
-
-    private val _uiState = MutableStateFlow(UserUiState())
-    val uiState: StateFlow<UserUiState> = _uiState.asStateFlow()
-
-    fun loadUser() {
-        viewModelScope.launch {
-            _uiState.update { it.copy(isLoading = true) }
-            try {
-                val user = userRepository.getUser()
-                _uiState.update { it.copy(user = user, isLoading = false) }
-            } catch (e: Exception) {
-                _uiState.update { it.copy(error = e.message, isLoading = false) }
-            }
-        }
-    }
-}
-```
-
-Reduce state with `.update { copy(...) }` (atomic read-modify-write; safe under concurrent emissions) rather than assigning `_uiState.value = ...`.
+// Recomposes the whole header on every scroll pixel
+Header(modifier = Modifier.alpha(1f - listState.firstVisibleItemScrollOffset / 300f))
 
-For a stream-backed screen, expose the state with `.stateIn` and let the first load fire lazily from `onStart` instead of `init {}`. `onStart` runs when the UI actually starts collecting, so a screen that is created but never shown does no work, and the fetch restarts correctly with the subscription.
-
-```kotlin
-private val _uiState = MutableStateFlow(UserUiState())
-
-val uiState: StateFlow<UserUiState> = _uiState
-    .onStart { loadInitialData() }
-    .stateIn(
-        scope = viewModelScope,
-        started = SharingStarted.WhileSubscribed(5_000),
-        initialValue = UserUiState()
-    )
+// Reads the value in the draw phase only
+Header(modifier = Modifier.graphicsLayer {
+    alpha = 1f - listState.firstVisibleItemScrollOffset / 300f
+})
 ```
 
-Prefer `WhileSubscribed(5_000)` over `Lazily` or `Eagerly`. The 5-second stop timeout keeps the upstream alive across a configuration change (rotation, night-mode toggle) so the flow is not torn down and re-collected for a transient loss of subscribers, while still cancelling upstream work when the screen truly goes away. `Eagerly`/`Lazily` never stop, so they hold upstream resources for the ViewModel's whole life.
+## Derived values
 
-### 3. Creating the Screen Composable
+Computing something from state inside the body is fine when it is cheap. Two
+cases need care:
 
-Consume the state in a "Screen" composable and pass data down to stateless components.
+- **Expensive work** keyed on inputs: `val sorted = remember(products, sortKey) { products.sortedWith(sortKey.comparator) }`.
+- **A value that changes less often than its source**: wrap it in
+  `derivedStateOf` so readers recompose only when the result flips.
 
 ```kotlin
-@Composable
-fun UserScreen(
-    viewModel: UserViewModel = hiltViewModel()
-) {
-    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
-
-    UserContent(
-        uiState = uiState,
-        onRetry = viewModel::loadUser
-    )
-}
-
-@Composable
-fun UserContent(
-    uiState: UserUiState,
-    onRetry: () -> Unit
-) {
-    Scaffold { padding ->
-        Box(modifier = Modifier.padding(padding)) {
-            when {
-                uiState.isLoading -> CircularProgressIndicator()
-                uiState.error != null -> ErrorView(uiState.error, onRetry)
-                uiState.user != null -> UserProfile(uiState.user)
-            }
-        }
-    }
+val showScrollToTop by remember {
+    derivedStateOf { listState.firstVisibleItemIndex > 0 }
 }
 ```
 
-## Examples
-
-### Example 1: Type-Safe Navigation
+Do not use `derivedStateOf` to combine two ordinary parameters; it only helps
+when the source changes more often than the output.
 
-Using the new Navigation Compose Type Safety (available in recent versions).
+## Stability and skipping
 
-```kotlin
-// Define Destinations
-@Serializable
-object Home
-
-@Serializable
-data class Profile(val userId: String)
-
-// Setup NavHost
-@Composable
-fun AppNavHost(navController: NavHostController) {
-    NavHost(navController, startDestination = Home) {
-        composable<Home> {
-            HomeScreen(onNavigateToProfile = { id ->
-                navController.navigate(Profile(userId = id))
-            })
-        }
-        composable<Profile> { backStackEntry ->
-            val profile: Profile = backStackEntry.toRoute()
-            ProfileScreen(userId = profile.userId)
-        }
-    }
-}
-```
+With strong skipping mode (default since Kotlin 2.0.20 with the Compose compiler
+Gradle plugin), a restartable composable skips when every argument is equal to
+the previous one: `equals` for stable types, reference identity for unstable
+ones. Lambdas are remembered automatically. So the practical rules are:
 
-### Example 2: One-Shot Events (Navigation, Toast, Snackbar)
-
-Keep navigation commands, snackbars and toasts out of the state class. State is a value that survives and is re-read on every recomposition, so an event stored in state fires again after a config change (a duplicated navigation, a re-shown snackbar). Model one-shot events as a `Channel` and expose them as a flow.
-
-```kotlin
-sealed interface UserEvent {
-    data class ShowMessage(val text: String) : UserEvent
-    data class NavigateToProfile(val userId: String) : UserEvent
-}
+- Pass immutable data. `data class Product(val id: String, val name: String)`
+  with `val` properties of stable types is stable.
+- `List`, `Set` and `Map` are interfaces and count as unstable. Use
+  `kotlinx.collections.immutable` (`ImmutableList`) or list them in a
+  compiler stability configuration file if they are never mutated.
+- Classes from modules without the Compose compiler (domain modules) are
+  unstable unless listed in the stability config or wrapped in a UI model.
+- Do not allocate a new list or object in the parent body just to pass it down;
+  identity changes and the child cannot skip.
 
-private val _events = Channel<UserEvent>(Channel.RENDEZVOUS)
-val events: Flow<UserEvent> = _events.receiveAsFlow()
+Mark a class `@Immutable` only when it truly never changes after construction,
+and `@Stable` when changes are notified through snapshot state. A wrong
+annotation causes stale UI, which is worse than an extra recomposition.
 
-fun onSaved(userId: String) {
-    viewModelScope.launch {
-        _events.send(UserEvent.NavigateToProfile(userId))
-    }
-}
-```
+Measure before annotating: the Layout Inspector recomposition counts and the
+compiler reports (`reportsDestination`) show what is skipping. Tooling detail
+lives in `android-performance`.
 
-Collect lifecycle-aware so events are only delivered while the screen is at least `STARTED`.
+## Lazy lists
 
 ```kotlin
-@Composable
-fun UserScreen(viewModel: UserViewModel = hiltViewModel()) {
-    val lifecycleOwner = LocalLifecycleOwner.current
-    LaunchedEffect(Unit) {
-        lifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
-            viewModel.events.collect { event ->
-                when (event) {
-                    is UserEvent.ShowMessage -> snackbarHostState.showSnackbar(event.text)
-                    is UserEvent.NavigateToProfile -> onNavigateToProfile(event.userId)
-                }
-            }
-        }
+LazyColumn(state = listState) {
+    items(
+        items = state.notes,
+        key = { note -> note.id },
+        contentType = { note -> if (note.isPinned) "pinned" else "regular" },
+    ) { note ->
+        NoteRow(note = note, onClick = { onNoteClick(note.id) }, modifier = Modifier.animateItem())
     }
-    // ...
 }
 ```
 
-A `Channel` with `RENDEZVOUS` capacity buffers events while there is no active collector and hands each to exactly one consumer, so nothing is lost and nothing is replayed. `SharedFlow(replay = 0)` drops any event emitted while the collector is paused (for example during a config change), which loses one-shot events; that is why the channel is the safer default here.
-
-For the full MVI base-ViewModel pattern (intent reduction, effect plumbing, a reusable base class), see the `android-mvi-viewmodel` skill.
-
-## Best Practices
-
-- ✅ **Do:** Use `remember` and `derivedStateOf` to minimize unnecessary calculations during recomposition.
-- ✅ **Do:** Mark data classes used in UI state as `@Immutable` or `@Stable` if they contain `List` or other unstable types to enable smart recomposition skipping.
-- ✅ **Do:** Use `LaunchedEffect` for one-off side effects (like showing a Snackbar) triggered by state changes.
-- ❌ **Don't:** Perform expensive operations (like sorting a list) directly inside the Composable function body without `remember`.
-- ❌ **Don't:** Pass `ViewModel` instances down to child components. Pass only the data (state) and lambda callbacks (events).
-
-## Troubleshooting
-
-**Problem:** Infinite Recomposition loop.
-**Solution:** Check if you are creating new object instances (like `List` or `Modifier`) inside the composition without `remember`, or if you are updating state inside the composition phase instead of a side-effect or callback. Use Layout Inspector to debug recomposition counts.
+- `key` keeps item state and scroll position attached to the right row when
+  the list reorders or items are inserted. It must be stable and unique, and
+  `Bundle`-saveable (String, Int, Long).
+- `contentType` lets the list reuse compositions between rows of the same shape.
+- `Modifier.animateItem()` animates insertion, removal and moves; it needs keys.
+- Never nest a vertically scrolling lazy list inside `verticalScroll`; give the
+  inner list a fixed height or flatten it into the outer list with `item {}`
+  blocks.
+
+## CompositionLocal
+
+Use a `CompositionLocal` for values that are ambient to a subtree and rarely
+change: theme tokens, a formatter, analytics sink. Do not use it to smuggle
+screen data or ViewModels past parameter lists; that hides dependencies and
+makes previews fail at runtime.
+
+- `staticCompositionLocalOf` for values that almost never change (whole subtree
+  recomposes on change, reads are cheap).
+- `compositionLocalOf` when the value changes and only readers should recompose.
+- Always provide a sensible default or throw with a message naming the provider.
+
+## Review checklist
+
+- Screen composable receives state and lambdas, not a ViewModel.
+- State collected with `collectAsStateWithLifecycle`.
+- No side effect, logging or allocation-heavy work in a composable body.
+- Every effect has keys that match its real dependencies.
+- Fast-changing values read in layout or draw lambdas.
+- Lazy list items have stable keys; no nested same-direction scrolling.
+- Parameters are stable or the instability is measured and accepted.
+- Custom modifiers use `Modifier.Node`; `modifier` parameter applied once.
+- User-facing strings via `stringResource`, sizes via theme or dimension tokens.
+
+## References
+
+- `references/patterns.md`: state holders and hoisting, the side-effect API table with key rules, and modifier order plus Modifier.Node. Load it when the task reaches those topics.

package/pipeline/skills/shared/external/android-jetpack-compose-expert/references/patterns.md

@@ -0,0 +1,147 @@
+# Compose runtime patterns
+
+Loaded on demand from `../SKILL.md`.
+
+## Who owns a piece of state
+
+Decide ownership before writing the composable. The rule of thumb: state lives
+in the lowest common parent of everything that reads or writes it, and no lower.
+
+| Kind of state | Owner | Survives |
+|---|---|---|
+| Screen data from a repository | ViewModel, exposed as `StateFlow` | configuration change |
+| User input the ViewModel must validate | ViewModel | configuration change |
+| Pure UI element state (expanded, scroll) | composable via `remember` / `rememberSaveable` | depends on the API |
+| Shared by a group of UI elements | a plain state holder class, remembered | same as `remember` |
+
+Collect ViewModel state with the lifecycle-aware collector so collection stops
+when the screen is not visible:
+
+```kotlin
+@Composable
+fun OrderListRoute(viewModel: OrderListViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    OrderListScreen(
+        state = state,
+        onRefresh = viewModel::refresh,
+        onOrderClick = viewModel::openOrder,
+    )
+}
+```
+
+`OrderListScreen` takes only values and lambdas. That split keeps the screen
+previewable and testable without a ViewModel, and it stops the ViewModel from
+leaking into child composables.
+
+### remember versus rememberSaveable
+
+- `remember` keeps a value across recompositions; it is lost when the
+  composable leaves the composition or the activity is recreated.
+- `rememberSaveable` also writes to the saved-instance bundle, so it survives
+  rotation and process death. Use it for text field contents, selected tab,
+  expanded flags. Custom types need a `Saver` or `@Parcelize`.
+- Pass keys when the remembered value depends on an input:
+  `remember(noteId) { NoteDraft(noteId) }` rebuilds when `noteId` changes.
+
+### A plain state holder
+
+When several related UI values move together, group them in a class rather
+than scattering `mutableStateOf` calls:
+
+```kotlin
+@Stable
+class FilterBarState(initial: Set<Category>) {
+    var selected by mutableStateOf(initial)
+        private set
+    var isExpanded by mutableStateOf(false)
+        private set
+
+    fun toggle(category: Category) {
+        selected = if (category in selected) selected - category else selected + category
+    }
+    fun expand(value: Boolean) { isExpanded = value }
+}
+
+@Composable
+fun rememberFilterBarState(initial: Set<Category> = emptySet()) =
+    remember { FilterBarState(initial) }
+```
+
+## Side effects
+
+The body of a composable must be free of side effects because it can run many
+times, out of order, or be discarded. Every effect goes through one of these:
+
+| Need | API | Restarts when |
+|---|---|---|
+| Run a suspend block tied to the composable | `LaunchedEffect(key)` | key changes |
+| Register and unregister a listener | `DisposableEffect(key)` with `onDispose` | key changes |
+| Launch from a click handler | `rememberCoroutineScope()` | never; scope dies with the composable |
+| Publish Compose state to non-Compose code after every successful recomposition | `SideEffect` | every recomposition |
+| Turn a callback-based source into state | `produceState` | key changes |
+| Observe state as a Flow inside an effect | `snapshotFlow { ... }` | emits on change |
+| Use the latest lambda inside a long effect without restarting it | `rememberUpdatedState(lambda)` | never |
+
+```kotlin
+@Composable
+fun AutoSaveDraft(draft: String, onSave: suspend (String) -> Unit) {
+    val currentDraft by rememberUpdatedState(draft)
+    val latestOnSave by rememberUpdatedState(onSave)
+    LaunchedEffect(Unit) {
+        snapshotFlow { currentDraft }
+            .debounce(500)
+            .distinctUntilChanged()
+            .collect { latestOnSave(it) }
+    }
+}
+```
+
+`snapshotFlow` only sees changes to snapshot state it reads, so the plain
+`draft` parameter is wrapped in `rememberUpdatedState` first; reading the bare
+parameter would capture its first value and never emit again.
+
+Choosing keys: use the identity the effect depends on (`LaunchedEffect(orderId)`),
+never `true` to mean "once" if the dependency can change, and never a fresh
+object allocated in the body, which restarts the effect every recomposition.
+
+One-shot events from a ViewModel (show a snackbar, navigate) are collected in a
+`LaunchedEffect` with `repeatOnLifecycle` semantics, or modelled as state the UI
+consumes and acknowledges. `android-mvi-viewmodel` covers the channel approach.
+
+## Modifiers
+
+Order matters because each modifier wraps the ones after it.
+
+```kotlin
+Modifier
+    .padding(16.dp)          // outer spacing, not clickable
+    .clip(RoundedCornerShape(12.dp))
+    .background(MaterialTheme.colorScheme.surfaceVariant)
+    .clickable(onClick = onClick)  // ripple is clipped to the shape
+    .padding(12.dp)          // inner spacing, inside the touch target
+```
+
+- Every public composable takes `modifier: Modifier = Modifier` as its first
+  optional parameter and applies it to the root, once.
+- Write custom modifiers with `Modifier.Node` and a `ModifierNodeElement`;
+  `Modifier.composed` is discouraged because it allocates per call site and
+  cannot skip.
+
+```kotlin
+private class DimWhenNode(var dimmed: Boolean) : Modifier.Node(), DrawModifierNode {
+    override fun ContentDrawScope.draw() {
+        drawContent()
+        if (dimmed) drawRect(Color.Black.copy(alpha = 0.4f))
+    }
+}
+
+private data class DimWhenElement(val dimmed: Boolean) : ModifierNodeElement<DimWhenNode>() {
+    override fun create() = DimWhenNode(dimmed)
+    override fun update(node: DimWhenNode) {
+        node.dimmed = dimmed
+        node.invalidateDraw()
+    }
+}
+
+fun Modifier.dimWhen(dimmed: Boolean) = this then DimWhenElement(dimmed)
+```

package/pipeline/skills/shared/external/android-mvi-viewmodel/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: android-mvi-viewmodel
-description: "A reusable generic BaseViewModel<State, Intent, Event> for MVI Compose apps: StateFlow state, one-shot events over a rendezvous Channel, a single intent dispatch, and a use-case executor with shared loading and error routing. Use when building or reviewing an MVI ViewModel base, intent-to-state reduction, or one-shot navigation and snackbar events."
-risk: safe
-source: multi-agent-pipeline
-date_added: "2026-09-21"
+description: "A reusable generic BaseViewModel typed on State, Intent and Event for MVI Compose apps: StateFlow state, one-shot events over a rendezvous Channel, a single intent dispatch, and a use-case executor with shared loading and error routing. Use when building or reviewing an MVI ViewModel base, intent-to-state reduction, or one-shot navigation and snackbar events."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-21"
 ---
 
 # Android MVI BaseViewModel
@@ -25,6 +26,7 @@ complete implementation to adapt; each heading there mirrors a section below.
 - [State as StateFlow](#state-as-stateflow)
 - [One-shot events over a rendezvous channel](#one-shot-events-over-a-rendezvous-channel)
 - [Single intent entry point](#single-intent-entry-point)
+- [Same-frame input intents](#same-frame-input-intents)
 - [Use-case executor](#use-case-executor)
 - [Reference-counted loading](#reference-counted-loading)
 - [Active job registry](#active-job-registry)
@@ -119,6 +121,38 @@ override fun handleIntent(intent: SearchIntent) = when (intent) {
 }
 ```
 
+## Same-frame input intents
+
+A base that launches every intent in a coroutine (so handlers can suspend) must
+not send all of them to `Dispatchers.Default`. The hop costs a frame, and for an
+intent that edits input state (a `TextField` value, a toggle, a radio selection)
+that frame is visible: the cursor jumps or the text flickers, because Compose
+renders the old value once more before the new one arrives.
+
+Give the intent contract a flag, and run flagged intents on the ViewModel's own
+context, which is `Dispatchers.Main.immediate` for `viewModelScope`:
+
+```kotlin
+interface UiIntent {
+    val immediateDispatch: Boolean get() = false
+}
+
+fun processIntent(intent: Intent) {
+    val context = if (intent.immediateDispatch) EmptyCoroutineContext else Dispatchers.Default
+    viewModelScope.launch(context) { handleIntent(intent) }
+}
+
+data class QueryChanged(val text: String) : SearchIntent {
+    override val immediateDispatch = true
+}
+```
+
+The flag only decides where the state write happens. A flagged handler that
+needs I/O still moves that work off the main thread with `withContext`. The
+same contract can carry per-intent loading flags (show a blocking loader,
+allow tap-to-cancel), so the executor below reads them from the intent instead
+of taking extra arguments.
+
 ## Use-case executor
 
 A single protected helper wraps every suspending call so error handling is not
@@ -147,6 +181,12 @@ protected fun <T> execute(
 }
 ```
 
+To stop a use case from being invoked outside this helper, which would bypass
+loading and error routing, declare its `invoke` with a context parameter the
+base class provides (`context(executor: UseCaseExecutor) operator fun invoke(...)`,
+Kotlin 2.2+ with `-Xcontext-parameters`). Only code inside the executor scope
+can call it. Tests call it inside a faked executor with `with(executor) { ... }`.
+
 Error routing has two tiers: a per-call `onError` for screen-specific handling,
 falling back to a global `routeError` that maps the throwable to an `Event`
 (snackbar) or an error field in state. Define `routeError` once in the base or
@@ -242,6 +282,7 @@ full body is in [references/patterns.md](references/patterns.md).
   them.
 - **Don't** pass the ViewModel to child composables; pass state + lambdas.
 - **Don't** toggle a boolean for loading when calls overlap; count references.
+- **Don't** dispatch input-editing intents through `Dispatchers.Default`; flag them for same-frame dispatch.
 
 ## Related skills
 

package/pipeline/skills/shared/external/android-performance/SKILL.md

@@ -17,6 +17,7 @@ or review that area; the guidance here is enough to decide what to do.
 
 - [Baseline Profiles](#baseline-profiles)
 - [Compose Stability](#compose-stability)
+- [Deferred State Reads](#deferred-state-reads)
 - [Recomposition Debugging](#recomposition-debugging)
 - [Lazy Layout Performance](#lazy-layout-performance)
 - [R8 Optimization](#r8-optimization)
@@ -55,6 +56,7 @@ For this to work, parameters must be **stable** (immutable or observable).
 | `data class` with `List<T>` field | No | `List` is an interface; could be mutable |
 | `class` (non-data) | No | Compose cannot infer stability |
 | Lambda `() -> Unit` | Unstable by default | Captured variables may change |
+| Class from a module not compiled with the Compose compiler (e.g. a domain module) | No | Compose cannot see its fields; map it to a UI model in the feature module, annotate it, or list it in a stability configuration file |
 
 Mark truly immutable models `@Immutable` and observable-but-stable state
 `@Stable`. Replace `List`/`Set`/`Map` parameters with
@@ -68,6 +70,27 @@ See `references/patterns.md` -> "Compose Stability" for the annotation
 examples, the immutable-collections `StateFlow` mapping, and the
 `gradle.properties` report settings.
 
+## Deferred State Reads
+
+Where a state is read decides which phase re-runs when it changes. An animated
+value read during composition recomposes the whole enclosing scope every frame.
+The same value read in a layout or draw lambda re-runs only that phase.
+
+| Phase the read happens in | Example | Re-runs |
+|---|---|---|
+| Composition | `Modifier.offset(x = v)`, `Modifier.alpha(v)`, `Modifier.scale(v)` | composition, layout, draw |
+| Layout | `Modifier.offset { IntOffset(v.roundToPx(), 0) }` | layout, draw |
+| Draw | `Modifier.graphicsLayer { alpha = v; translationX = px }`, `drawBehind { }` | draw only |
+
+- Delegate animation state with `by` (`val offset by animateDpAsState(...)`) and
+  read it inside the latest phase that can use it.
+- Animate colors through `drawBehind { drawRect(color) }` rather than a
+  `background(color)` read in composition.
+- Hoist a `rememberInfiniteTransition` above a list instead of creating one per
+  item.
+- Applies to `animate*AsState`, `Animatable`, `InfiniteTransition` and any state
+  that changes every frame (scroll offsets, drag positions).
+
 ## Recomposition Debugging
 
 Use Android Studio's Layout Inspector with "Show Recomposition Counts" enabled
@@ -88,8 +111,8 @@ Compose cannot diff efficiently and re-renders the whole list on any change.
 
 ```kotlin
 LazyColumn {
-    items(items = flights, key = { it.id }) { flight ->
-        FlightCard(flight = flight)
+    items(items = orders, key = { it.id }) { order ->
+        OrderCard(order = order)
     }
 }
 ```
@@ -212,6 +235,8 @@ debounced search `StateFlow`.
 - [ ] No object allocations inside composable body (formatters, regex)
 - [ ] `derivedStateOf` used for computed scroll/visibility state
 - [ ] `remember` used for expensive objects
+- [ ] Animated values read in `offset { }` / `graphicsLayer { }` / `drawBehind { }`, not in composition
+- [ ] No cross-module domain type in a composable parameter or UI state
 - [ ] R8 enabled with `isMinifyEnabled = true` for release
 - [ ] LeakCanary included as `debugImplementation` only
 - [ ] Coil configured with memory and disk cache limits