Configuring Lazy Prefetch

Configuring Lazy Prefetch — Cache Window and Pausable Composition

Lazy layouts pre-compose items just outside the viewport so they're ready when the user scrolls. Compose Foundation 1.9 added LazyLayoutCacheWindow for configurable ahead/behind extents. Compose Foundation 1.10 made prefetch composition pausable by default — work spreads across multiple frames instead of one. Most apps still rely on legacy single-frame prefetch and unknowingly pay for it during heavy scrolling. This skill teaches Claude when (and only when) to widen the window or implement nested prefetch, and how to validate the change with Macrobenchmark.

When to use this skill

• Macrobenchmark FrameTimingMetric shows dropped frames at high scroll velocity even though item composables are skippable.
• Items are content-heavy: large images, decoded videos, nested grids, or expensive measurement work.
• The developer wants composition retained for items the user scrolled past briefly (e.g. flick-back gesture).
• An outer lazy layout contains items with their own inner lazy layouts (e.g. LazyColumn rows that each host a HorizontalPager or inner LazyRow).
• The developer mentions LazyLayoutCacheWindow, NestedPrefetchScope, "prefetch window", "ahead extent", or "pausable composition for prefetch".

When NOT to use this skill

• Items are cheap and short; default behavior is sufficient — do not pre-emptively configure a window.
• Item composables are non-skippable / unstable; widening the window only spreads the same waste over more frames. First fix ../optimizing-lazy-layouts/SKILL.md and the underlying stability via ../../stability/diagnosing-compose-stability/SKILL.md.
• The bottleneck is per-item layout or draw rather than composition. Use Android Studio Profiler / Layout Inspector to confirm; if measure or draw dominates, prefetch tuning will not help — adjust item content instead.
• Wrong-phase state reads inside items (animation reads state.value in Composition) — use ../../recomposition/deferring-state-reads/SKILL.md.

Prerequisites

• Compose Foundation 1.9+ for the LazyLayoutCacheWindow API. The cache window is a @ExperimentalFoundationApi factory LazyLayoutCacheWindow(ahead: Dp, behind: Dp) plumbed through rememberLazyListState(cacheWindow = ...) (or the equivalent grid/staggered-grid state). It is NOT a parameter on LazyColumn / LazyRow / LazyVerticalGrid / LazyHorizontalGrid directly. Every call site requires @OptIn(ExperimentalFoundationApi::class).
• Compose Foundation 1.10+ for pausable composition in prefetch by default. On 1.10+ the prefetch composer can pause and resume across frames, so a single heavy item no longer blows a frame budget.
• Item-level hygiene already in place: key, contentType, stable item composables. Run ../optimizing-lazy-layouts/SKILL.md first and confirm before tuning the window.
• Macrobenchmark module set up for FrameTimingMetric. See ../../measurement/generating-baseline-profiles/SKILL.md for the Macrobenchmark scaffold.

Workflow

• 1. Confirm Compose Foundation version. In gradle/libs.versions.toml or the relevant build.gradle.kts, verify androidx.compose.foundation:foundation is at 1.9.0+ (cache window) or 1.10.0+ (pausable prefetch on by default). If on 1.10+ and not measuring jank yet, MUST stop here — the default is good enough for most apps.

• 2. Re-validate item-level fixes are in place. Open ../optimizing-lazy-layouts/SKILL.md. Every items(...) call has stable key, mixed feeds have contentType, item composables are skippable. Without this baseline, prefetch tuning is treating the symptom.

• 3. Measure the baseline with Macrobenchmark FrameTimingMetric before changing anything. Skydoves hot take #5: debug builds lie. Always measure release + R8 + real device. Capture frameDurationCpuMs p50/p95/p99 over a fixed scroll journey so the after-comparison is meaningful. See ../../measurement/generating-baseline-profiles/SKILL.md.

• 4. Construct a LazyLayoutCacheWindow only after measurement justifies it. Build the window with the top-level factory LazyLayoutCacheWindow(ahead: Dp, behind: Dp) and plumb it through rememberLazyListState(cacheWindow = window), then pass that state to LazyColumn(state = state) { ... }. The cache window is not a parameter on LazyColumn itself. Every call site needs @OptIn(ExperimentalFoundationApi::class).

// RIGHT — measured tall, image-heavy items benefit from a deeper ahead extent
@OptIn(ExperimentalFoundationApi::class)
@Composable
fun HeavyFeed(items: ImmutableList<HeavyItem>) {
    val state = rememberLazyListState(
        cacheWindow = LazyLayoutCacheWindow(ahead = 200.dp, behind = 100.dp)
    )
    LazyColumn(state = state) {
        items(items, key = { it.id }, contentType = { it::class }) { item ->
            HeavyItemRow(item, Modifier.animateItem())
        }
    }
}

• 5. Implement NestedPrefetchScope for items that host inner lazy layouts. When a LazyColumn row contains a HorizontalPager, inner LazyRow, or inner LazyVerticalGrid, the outer prefetch can warm only the row's outer composition by default. Implementing nested prefetch chains the work so the inner layout's first item composes during the outer prefetch slot, not on the user's first horizontal swipe.

• 6. Re-measure with the same Macrobenchmark journey. Compare frameDurationCpuMs p95/p99 before and after. If the rate did not decrease, MUST revert the window change and look elsewhere — likely measure or draw dominates, or item composition was already keeping up.

• 7. If still dropping frames on Compose Foundation 1.10+ with pausable prefetch, profile to confirm the bottleneck. Use Android Studio CPU profiler / system trace to determine whether composition, measurement, or draw is the dominant phase per frame. Prefetch tuning only addresses composition cost; for measure/draw, simplify item content (smaller images, fewer subcompositions, graphicsLayer for alpha/scale) instead.

• 8. Change one variable at a time. MUST NOT combine cache-window tuning with stability/key fixes in the same commit or PR. Profiling needs an isolated cause-and-effect comparison; bundling two changes makes the regression bisect impossible.