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

architecture/references/state-boundaries.md

View on GitHub
# State Boundaries

Use this reference when UI work touches state ownership, presenter/coordinator boundaries, desktop lifecycle, flow
collection, `CompositionLocal`s, or where logic should be tested.

## Presenter vs State Holder vs Composition

Use the project rule from the relevant architecture docs:

| Logic | Where it belongs |
|---|---|
| Business decisions, RPC, persistence, settings, workspace, model/provider state | Presenter/coordinator |
| Screen projections and derived render models | Presenter/coordinator |
| UI-adjacent multi-step state machines needing layout signals | `@Stable` state holder |
| Thin effect bridges, focus, animation, hover, expansion | Composition |

State holders should usually take values, not Compose UI objects. Prefer:

```kotlin
val intent = controller.onLayoutChanged(totalItemCount = count, isAtBottom = atBottom)
when (intent) { is ScrollIntent.Snap -> listState.scrollToItem(intent.index) }
```

Avoid stuffing `LazyListState`, presenters, or long-lived scopes into state holders unless the tradeoff is deliberate
and tested.

## Desktop Architecture Patterns

Desktop Compose apps often use manual dependency wiring, long-lived tool-window or session state, Swing/AWT seams, and
runtime/service boundaries. That changes the default architecture instincts:

- **The application shell owns the process and session lifetime.** Application entry points and session wiring create
  and shut down presenters, select the active session, and manage runtime profiles. Reusable composables must not look
  up or instantiate these dependencies.
- **Presenter projections beat ad hoc collection.** A screen should prefer one coherent projected view model flow over
  several independently collected raw flows. This avoids stale pairings such as body state from one emission and
  workspace/model status from another.
- **Desktop lifecycle is explicit.** There is no Android `LifecycleOwner` safety net unless the project explicitly adds
  one. Start file watchers, subprocesses, autosync, and persistence from presenter/runtime objects with explicit
  close/cancel paths; compositions only subscribe and render.
- **Swing/AWT is an interop boundary.** File choosers, popups, clipboard/action-system hooks, and host components belong
  behind a small callback or interop helper. Use the `jewel` skill ([swing-interop](../../../jewel/swing-interop/GUIDE.md) guide) for the mechanics; do not leak AWT details into
  leaf composables.
- **Window, focus, and shortcuts are UI wiring.** The composition may request focus, execute scroll/focus commands,
  and bind keyboard shortcuts, but the decision that a shortcut means "abort", "archive", or "send" belongs in the
  presenter/app-state layer.
- **Density/theme are environment, not business state.** Theme and density locals are fine; model/provider/session state
  hidden in locals is not.
- **Long-running desktop work must be cancellable.** Anything tied to a session or app lifetime needs an owner with a
  close path. Avoid `GlobalScope`, unmanaged `Thread`, and composition-launched loops that outlive the surface.

## Desktop Flow Collection

Android guidance often says `collectAsStateWithLifecycle()`. Desktop Compose code usually does not have that lifecycle,
so do not cargo-cult it or add Android lifecycle dependencies unless the project already depends on them.

Use these rules instead:

- Collect presenter-owned `StateFlow`s at screen/root boundaries, not deep in leaf components.
- Prefer a single screen projection flow, such as a `*ScreenState`, when multiple raw values must stay coherent.
- Keep collection read-only in UI; events go back through callbacks/presenter APIs.
- If collection would start expensive upstream work, that upstream should be owned by a presenter/coordinator and tied
  to session/app lifetime, not to whether a leaf composable happens to be visible.
- One-shot UI events should stay explicit: presenter emits an event/command, composition executes the UI-only action
  such as scroll, focus, dialog display, or clipboard interaction.

If two `collectAsState()` calls must stay synchronized for the screen to render valid state, combine them into a single
presenter-projected view model.

## CompositionLocal Guardrails

Composition locals are for tree-scoped environment values with sensible defaults. Theme, density, and host-component
locals can be intentional. Business state and action routing usually should not be hidden in locals.

Avoid locals for actions or app state:

- no `LocalPresenter`
- no `LocalSessionModel`
- no `LocalOnClick`
- no `LocalShowSnackbar`
- no hidden RPC/settings/workspace accessors

Prefer explicit parameters or presenter-projected screen state.

Pick the factory by how often the value changes:

- `compositionLocalOf`: only the readers recompose when the value changes.
- `staticCompositionLocalOf`: the whole subtree recomposes. Use it only for a value that never or rarely changes.
- Give a safe default, or fail fast when no provider is present.

## Testing Implications

Architecture fixes should move logic into places that are cheap to test:

- Test presenter and coordinator decisions with plain unit tests, or use end-to-end tests when verifying RPC and event
  wiring.
- State holders: plain unit tests with method calls and command/intention assertions.
- Composition wiring: Compose UI tests only for visibility, callbacks, focus/scroll execution, and semantic behavior.

If a bug needs a full Compose UI test just to exercise business logic, the logic is probably still too low in the tree.
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: 472kUpdated 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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated 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