Skip to content

aldefy/compose-skill / skills/compose-expert

compose-expert

Unverified

Compose and Compose Multiplatform expert for UI development across Android, Desktop, iOS, and Web. Use whenever the user mentions Compose APIs (@Composable, remember, LaunchedEffect, NavHost, MaterialTheme, LazyColumn, Modifier, recomposition), Compose Multiplatform (commonMain, expect/actual, Res.*, ComposeUIViewController, UIKitView, ComposeViewport), Android TV (tv-material, D-pad, focus, Carousel), Material 3 motion, atomic design systems, design-to-code workflows, Paging 3, or navigation. Activates Review Mode on GitHub PR URLs and review phrases ("review this PR", "what's wrong with this"). Auto-detects Compose projects on session_start. Backed by actual androidx/androidx and JetBrains/compose-multiplatform-core source receipts. See "## When this skill applies" in SKILL.md for the full trigger surface.

FileKindSize
SKILL.mdskill md24.8 KB
agents/openai.yamlconfig278 B
references/accessibility.mdmarkdown11.2 KB
references/adaptive-layout-input.mdmarkdown5.2 KB
references/agentic-ui-a2ui.mdmarkdown4.7 KB
references/agsl-shaders.mdmarkdown11.5 KB
references/animation.mdmarkdown41.7 KB
references/appfunctions.mdmarkdown5.8 KB
references/appstate.mdmarkdown3.9 KB
references/atomic-design.mdmarkdown10.7 KB
references/auto-init.mdmarkdown1.6 KB
references/car-compose.mdmarkdown6.7 KB
references/composition-locals.mdmarkdown6.9 KB
references/deprecated-patterns.mdmarkdown8.3 KB
references/design-to-compose.mdmarkdown23.5 KB
references/graphics-modern.mdmarkdown2.6 KB
references/ink.mdmarkdown5.1 KB
references/lists-scrolling.mdmarkdown14.5 KB
references/material3-motion.mdmarkdown14.9 KB
references/media3-compose.mdmarkdown1.7 KB
references/ml-kit-agentic.mdmarkdown5.5 KB
references/modifiers.mdmarkdown13.6 KB
references/multiplatform.mdmarkdown21.1 KB
references/navigation-migration.mdmarkdown14.6 KB
references/navigation.mdmarkdown11.0 KB
references/official-android-skills.mdmarkdown2.7 KB
references/paging-mvi-testing.mdmarkdown6.4 KB
references/paging-offline.mdmarkdown6.4 KB
references/paging.mdmarkdown11.1 KB
references/performance.mdmarkdown22.7 KB
references/platform-specifics.mdmarkdown20.2 KB
references/pr-review.mdmarkdown14.1 KB
references/production-crash-playbook.mdmarkdown25.3 KB
references/remote-compose.mdmarkdown3.7 KB
references/side-effects.mdmarkdown13.0 KB
references/source-code/cmp-source.mdmarkdown17.8 KB
references/source-code/foundation-source.mdmarkdown560.9 KB
references/source-code/material3-source.mdmarkdown836.1 KB
references/source-code/navigation-source.mdmarkdown118.8 KB
references/source-code/runtime-source.mdmarkdown449.0 KB
references/source-code/ui-source.mdmarkdown313.1 KB
references/state-management.mdmarkdown17.6 KB
references/styles-experimental.mdmarkdown14.5 KB
references/text-editing.mdmarkdown3.8 KB
references/theming-material3.mdmarkdown13.0 KB
references/tv-compose.mdmarkdown30.2 KB
references/view-composition.mdmarkdown20.0 KB
references/wear-compose.mdmarkdown2.0 KB
references/xr-compose.mdmarkdown5.1 KB

references/paging-offline.md

View on GitHub
# Paging 3 — Offline-First with RemoteMediator

Local DB as the single source of truth, network as a refresh trigger. Builds on
the core setup in `paging.md`. Room itself sits outside this skill's scope —
this file documents only the parts where `RemoteMediator` shapes Compose UI
behaviour (LoadState semantics, refresh policies, what the UI sees).

## Compose Multiplatform note

Room is Android-only. In CMP `commonMain`, the equivalent stack is **SQLDelight**
(`app.cash.sqldelight`), which provides a `PagingSource` factory via
`app.cash.sqldelight:androidx-paging3-extensions`. The mental model below is
identical — local DB as source of truth, `RemoteMediator` writes to it, the UI
observes via the DB-backed `PagingSource`. Only the DAO/insert/transaction calls
change shape. The `LoadState` rules (use `loadState.source.refresh` over
`loadState.refresh`) apply identically because they're a property of the
Paging 3 contract, not of Room.

Where the snippets below say `db.itemDao()` / `db.withTransaction { ... }`, the
SQLDelight equivalent is `database.itemQueries.insertAll(...)` /
`database.transaction { ... }`.

## When RemoteMediator runs

`RemoteMediator.initialize()` controls whether a network refresh fires on first
load. This decides whether the user sees stale-but-instant data or a loading
state.

```kotlin
@OptIn(ExperimentalPagingApi::class)
override suspend fun initialize(): InitializeAction {
    val cacheTimeout = TimeUnit.HOURS.toMillis(1)
    val lastUpdated = db.remoteKeyDao().getLastUpdated("items") ?: 0L

    return if (System.currentTimeMillis() - lastUpdated < cacheTimeout) {
        InitializeAction.SKIP_INITIAL_REFRESH
    } else {
        InitializeAction.LAUNCH_INITIAL_REFRESH
    }
}
```

| Return value | UI effect |
|---|---|
| `LAUNCH_INITIAL_REFRESH` (default) | Triggers a `REFRESH` load before showing data — user sees a loading indicator first |
| `SKIP_INITIAL_REFRESH` | Shows cached rows immediately; network only fires on user-triggered refresh or `append` |

Pick `SKIP_INITIAL_REFRESH` when the cache is fresh enough that flashing a
spinner over existing data degrades perceived performance.

## RemoteMediator implementation

```kotlin
@OptIn(ExperimentalPagingApi::class)
class ItemRemoteMediator(
    private val api: ItemApi,
    private val db: AppDatabase,
) : RemoteMediator<Int, ItemEntity>() {

    override suspend fun initialize(): InitializeAction {
        val lastUpdated = db.remoteKeyDao().getLastUpdated("items") ?: 0L
        val cacheTimeout = TimeUnit.HOURS.toMillis(1)
        return if (System.currentTimeMillis() - lastUpdated < cacheTimeout) {
            InitializeAction.SKIP_INITIAL_REFRESH
        } else {
            InitializeAction.LAUNCH_INITIAL_REFRESH
        }
    }

    override suspend fun load(
        loadType: LoadType,
        state: PagingState<Int, ItemEntity>,
    ): MediatorResult {
        val page = when (loadType) {
            LoadType.REFRESH -> 1
            LoadType.PREPEND -> return MediatorResult.Success(endOfPaginationReached = true)
            LoadType.APPEND -> {
                val remoteKey = db.remoteKeyDao().getRemoteKey("items")
                remoteKey?.nextPage ?: return MediatorResult.Success(endOfPaginationReached = true)
            }
        }

        return try {
            val response = api.getItems(page = page, limit = state.config.pageSize)

            db.withTransaction {
                if (loadType == LoadType.REFRESH) {
                    db.itemDao().clearAll()
                    db.remoteKeyDao().delete("items")
                }
                db.itemDao().insertAll(response.items.map { it.toEntity() })
                db.remoteKeyDao().insert(
                    RemoteKey(
                        id = "items",
                        nextPage = if (response.items.isEmpty()) null else page + 1,
                        lastUpdated = System.currentTimeMillis(),
                    )
                )
            }

            MediatorResult.Success(endOfPaginationReached = response.items.isEmpty())
        } catch (e: IOException) {
            MediatorResult.Error(e)
        } catch (e: HttpException) {
            MediatorResult.Error(e)
        }
    }
}
```

<!-- source: not bundled — RemoteMediator lives in androidx.paging:paging-common -->

## Pager wiring

```kotlin
@OptIn(ExperimentalPagingApi::class)
val items: Flow<PagingData<ItemEntity>> = Pager(
    config = PagingConfig(pageSize = 20),
    remoteMediator = ItemRemoteMediator(api, db),
    pagingSourceFactory = { db.itemDao().pagingSource() },
).flow.cachedIn(viewModelScope)
```

The local `PagingSource` reads from the database. `RemoteMediator` writes to the
database. The UI observes the database-backed `PagingSource` — meaning UI updates
are driven by Room invalidation, not by the network response directly.

## LoadState with RemoteMediator (Compose-side gotcha)

Use `loadState.source.refresh` rather than the convenience `loadState.refresh`
in your Compose code:

```kotlin
val sourceRefresh = pagingItems.loadState.source.refresh
val mediatorRefresh = pagingItems.loadState.mediator?.refresh

when {
    sourceRefresh is LoadState.Loading -> FullScreenSpinner()
    mediatorRefresh is LoadState.Error -> InlineErrorBar(mediatorRefresh.error)
    pagingItems.itemCount == 0 -> EmptyState()
    else -> ItemList(pagingItems)
}
```

`loadState.refresh` collapses source + mediator into one signal. With Room as
source of truth that signal can flip to `NotLoading` while Room is still mid-
write, briefly hiding the spinner before the rows appear. Reading `source.refresh`
and `mediator.refresh` separately keeps the indicator honest.

<!-- source: references/source-code/foundation-source.md — search "LazyList" for how the rendered LazyColumn consumes the source-backed PagingData -->

## Remote keys (UI-relevant shape)

The remote-keys table is what makes pagination resumable across launches. The
table shape itself is a Room concern, but the UI behaviour depends on it being
present:

```kotlin
@Entity(tableName = "remote_keys")
data class RemoteKey(
    @PrimaryKey val id: String,
    val nextPage: Int?,
    val lastUpdated: Long = System.currentTimeMillis(),
)
```

Without a populated `nextPage`, `LoadType.APPEND` short-circuits to
`endOfPaginationReached = true` and the user sees no further pages even though
more exist on the server.

## Related

- Core Paging setup → `paging.md`
- MVI integration and tests → `paging-mvi-testing.md`
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall