Skip to content

JetBrains/intellij-community / .agents/skills/compose-ui

compose-ui

Verified

Write or audit Compose Desktop UI state, effects, and boundaries.

FileKindSize
OWNERSHIPother20 B
SKILL.mdskill md532 B
architecture/GUIDE.mdmarkdown5.7 KB
architecture/evals/evals.jsonconfig6.5 KB
architecture/references/animation.mdmarkdown11.3 KB
architecture/references/component-api-lists-performance.mdmarkdown4.1 KB
architecture/references/desktop-seams-review-output.mdmarkdown1.5 KB
architecture/references/effects.mdmarkdown1.7 KB
architecture/references/state-boundaries.mdmarkdown5.4 KB
architecture/skill-source.jsonconfig2.0 KB
audit/GUIDE.mdmarkdown14.1 KB
audit/evals/evals.jsonconfig18.1 KB
audit/references/api-hygiene.mdmarkdown8.8 KB
audit/references/audit-search-patterns.mdmarkdown3.9 KB
audit/references/boundary-violations.mdmarkdown3.3 KB
audit/references/effects/derived-state-of-guide.mdmarkdown2.2 KB
audit/references/effects/effect-selection-guide.mdmarkdown2.7 KB
audit/references/effects/infinite-loop-patterns.mdmarkdown2.6 KB
audit/references/effects/overview.mdmarkdown7.7 KB
audit/references/lazy-layouts/animate-item.mdmarkdown2.0 KB
audit/references/lazy-layouts/cache-window-and-prefetch.mdmarkdown3.2 KB
audit/references/lazy-layouts/desktop-scroll-measurement.mdmarkdown2.0 KB
audit/references/lazy-layouts/keys-and-content-type.mdmarkdown2.2 KB
audit/references/lazy-layouts/nested-lazy-layouts.mdmarkdown1.6 KB
audit/references/lazy-layouts/overview.mdmarkdown7.5 KB
audit/references/measurement/benchmarking-methodology.mdmarkdown1.9 KB
audit/references/measurement/overview.mdmarkdown5.5 KB
audit/references/measurement/profiler-setup.mdmarkdown2.5 KB
audit/references/modifiers/custom-modifier-node.mdmarkdown3.4 KB
audit/references/modifiers/modifier-order.mdmarkdown2.1 KB
audit/references/modifiers/overview.mdmarkdown7.4 KB
audit/references/modifiers/phase-deferral.mdmarkdown2.6 KB
audit/references/reporting-guidance.mdmarkdown2.3 KB
audit/references/stability/ci-stability-gate.mdmarkdown2.0 KB
audit/references/stability/desktop-measurement.mdmarkdown2.2 KB
audit/references/stability/overview.mdmarkdown7.6 KB
audit/references/stability/reading-classes-txt.mdmarkdown2.1 KB
audit/references/stability/reading-composables-txt.mdmarkdown1.9 KB
audit/references/stability/stabilising-types.mdmarkdown3.1 KB
audit/references/stability/stability-config-syntax.mdmarkdown1.6 KB
audit/references/stability/stability-inference-algorithm.mdmarkdown3.4 KB
audit/references/stability/strong-skipping-escape-hatches.mdmarkdown2.6 KB
audit/references/subcomposition/desktop-subcomposition-measurement.mdmarkdown1.7 KB
audit/references/subcomposition/overview.mdmarkdown7.2 KB
audit/references/subcomposition/subcomposition-decision-tree.mdmarkdown1.8 KB
audit/references/subcomposition/swing-panel-subcomposition.mdmarkdown1.8 KB
audit/references/tracing-setup.mdmarkdown5.3 KB
audit/references/tracing-usage.mdmarkdown6.3 KB
audit/skill-source.jsonconfig2.5 KB

audit/references/effects/overview.md

View on GitHub
# Compose Effects — Correctness and Loop Prevention

**Core principle:** Use the smallest effect that fits.

- Use `LaunchedEffect` for one-shot async work.
- Use `SideEffect` to publish state to non-Compose code on every successful composition.
- Use `DisposableEffect` when setup and teardown manage a resource.
- Use `derivedStateOf` to derive state without cascading recompositions.
- Use `snapshotFlow` to convert Snapshot state into a `Flow`.

Never use an effect when a plain `remember` or direct state read suffices.

> **Routing:** Use this workflow when an audit finding points to effects running too often,
> failing to clean up, causing infinite recomposition loops, or questionable `derivedStateOf` use.

## Workflow

### Phase 1 — Measure

- [ ] **1. Add logging to the effect.**

```kotlin
LaunchedEffect(userId) {
    println("[Effect] LaunchedEffect started for $userId")
    val data = repository.fetch(userId)
    state.value = data
}
```

If the log prints repeatedly without `userId` changing, the effect is restarting too often.

- [ ] **2. Check for infinite loops.** If the UI freezes or CPU spikes, look for effects that
  write state whose change triggers recomposition and restarts the effect.

- [ ] **3. Check cleanup.** For `DisposableEffect`, verify `onDispose` runs:

```kotlin
DisposableEffect(listener) {
    listener.start()
    println("[Effect] started")
    onDispose {
        listener.stop()
        println("[Effect] disposed")
    }
}
```

Navigate away. If "disposed" never logs, the composition is retained unexpectedly.

### Phase 2 — Diagnose

- [ ] **4. Match the effect to the use case.**

| Effect | Use for | Misuse |
|--------|---------|--------|
| `LaunchedEffect(key)` | One-shot async work when `key` changes. | Restarting on every callback change because callback is not stabilised. |
| `SideEffect` | Run side code on every successful composition. | Running async work. |
| `DisposableEffect(key)` | Setup/teardown tied to `key` lifetime. | Forgetting `onDispose` or capturing a stale callback. |
| `rememberUpdatedState` | Wrap a callback so `LaunchedEffect`/`DisposableEffect` does not restart when callback changes. | Using it when the callback genuinely should restart the effect. |
| `derivedStateOf` | Derive a value from upstream state without recomposing when derived value hasn't changed. | Using it for transforms that never filter. |
| `snapshotFlow` | Convert Snapshot state to a cold Flow. | Using it when direct state observation suffices. |

For the full effect selection guide, read [effect-selection-guide.md](effect-selection-guide.md).

- [ ] **5. Check effect keys.** Keys decide when an effect restarts:
  - Passing an unstable object as a key restarts the effect on every recomposition.
  - Omitting a required key causes the effect to run once and never update.
  - Passing `true` or `Unit` to run once is valid when documented.

- [ ] **6. Check for infinite-loop signatures.**

```kotlin
// INFINITE LOOP — key changes on every write, so the effect restarts on every recomposition
var count by remember { mutableIntStateOf(0) }
LaunchedEffect(count) {      // key = count
    count++                  // writes count → recomposition → new key → LaunchedEffect restarts
}
// (LaunchedEffect(Unit) would NOT loop — it runs exactly once regardless of recomposition)
```

For loop patterns and fixes, read [infinite-loop-patterns.md](infinite-loop-patterns.md).

- [ ] **7. Check `derivedStateOf` necessity.**

```kotlin
// WRONG — derivedStateOf adds overhead for a trivial transform
val isEmpty by remember { derivedStateOf { items.isEmpty() } }

// RIGHT — direct read is cheaper
val isEmpty = items.isEmpty()
```

```kotlin
// RIGHT — derivedStateOf prevents recompositions when filter result is unchanged
val visibleItems by remember { derivedStateOf { items.filter { it.isVisible } } }
```

For the full `derivedStateOf` guide, read [derived-state-of-guide.md](derived-state-of-guide.md).

### Phase 3 — Fix

- [ ] **8. Stabilise effect keys.** Use primitives, stable ids, or `rememberUpdatedState`.

```kotlin
// WRONG — lambda is unstable, restarts on every recomposition
LaunchedEffect(onRefresh) { onRefresh() }

// RIGHT — method reference or rememberUpdatedState
val currentOnRefresh by rememberUpdatedState(onRefresh)
LaunchedEffect(Unit) { currentOnRefresh() }
```

- [ ] **9. Add missing `onDispose` body.**

```kotlin
// WRONG — leaks the channel: cleanup is forgotten
DisposableEffect(channel) {
    channel.open()
    onDispose { /* forgot to call channel.close() */ }
}

// RIGHT — cleans up
DisposableEffect(channel) {
    channel.open()
    onDispose { channel.close() }
}
```

- [ ] **10. Break infinite loops.** Move state writes outside the composition cycle or use
  `snapshotFlow` + `collect` with a termination condition.

- [ ] **11. Replace unnecessary `derivedStateOf`.**

### Phase 4 — Verify

- [ ] **12. Re-run logging.** Effects should start only when their keys change.
- [ ] **13. Verify cleanup.** Navigate away and check that resources are released.
- [ ] **14. Verify no infinite loops.** UI is responsive; CPU is idle.
- [ ] **15. Verify `derivedStateOf` filters correctly.** Upstream changes that don't affect the
  derived value should not cause recompositions.

## Patterns

### `rememberUpdatedState` for callbacks

```kotlin
@Composable
fun Timer(onTick: () -> Unit) {
    val currentOnTick by rememberUpdatedState(onTick)
    LaunchedEffect(Unit) {
        while (isActive) {
            delay(1000)
            currentOnTick() // always calls the latest callback
        }
    }
}
```

### `DisposableEffect` for lifecycle-bound resources

```kotlin
@Composable
fun ChatChannel(channelId: String) {
    DisposableEffect(channelId) {
        val channel = ChatClient.open(channelId)
        onDispose { channel.close() }
    }
}
```

### `derivedStateOf` for filtered lists

```kotlin
val visibleTodos by remember {
    derivedStateOf { todos.filter { !it.isCompleted } }
}
```

Adding a completed todo changes `todos`, while `visibleTodos` stays the same and skips recomposition.

### `snapshotFlow` for Flow interop

```kotlin
LaunchedEffect(Unit) {
    snapshotFlow { scrollState.value }
        .filter { it > 100 }
        .collect { showScrollToTop = true }
}
```

## Mandatory rules

- **MUST** use the smallest effect that fits.
- **MUST** stabilise `LaunchedEffect`/`DisposableEffect` keys.
- **MUST** provide a non-empty `onDispose` in every `DisposableEffect`. Missing cleanup is a memory leak.
- **MUST NOT** write to Snapshot state in a way that triggers immediate recomposition of the same
  composable without a suspension point.
- **MUST** use `rememberUpdatedState` when an effect must observe a frequently-changing callback
  without restarting.
- **MUST NOT** use `derivedStateOf` for trivial transformations that never filter.
- **MUST** use `derivedStateOf` when a derived value filters or collapses upstream changes.
- **MUST** verify `DisposableEffect` cleanup runs by testing composition leave.

## Verification checklist

- [ ] Effects start only when their keys change (logging confirms).
- [ ] `DisposableEffect` resources are cleaned up when the composable leaves composition.
- [ ] No infinite recomposition loops — UI is responsive, CPU is idle at rest.
- [ ] `derivedStateOf` is used only when the derived value filters upstream changes.
- [ ] `rememberUpdatedState` is used for callbacks inside long-lived effects.
- [ ] `SideEffect` is used only for publishing to non-Compose systems, not for async work.

## References

- [effect-selection-guide.md](effect-selection-guide.md) — cheat-sheet: which effect for which use case
- [infinite-loop-patterns.md](infinite-loop-patterns.md) — common infinite-loop signatures and fixes
- [derived-state-of-guide.md](derived-state-of-guide.md) — when to use `derivedStateOf`, when to skip it
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall