compose-agent 4.2.1: Navigation 3 decision table

[hamen]

What

Adds a "when to use" decision table to skills/compose-agent/references/navigation.md as a workflow entry point, in the same shape as the paging.md decision table, plus revised Nav3 guidance.

The table routes the agent to the right approach before it writes nav code:

• Nav3 vs Nav2 type-safe vs plain state (single stateful screen needs no nav library)
• Arguments via @Serializable NavKey fields (Nav3) / toRoute() (Nav2), never string interpolation
• ViewModel-triggered navigation: the route mutates the back stack (backStack.add / removeLastOrNull); the back stack is never injected into a screen ViewModel
• Results handed back between screens via Nav3's official ResultEventBus (state conflateAsState or one-shot ResultEffect — both official; state is not process-death-safe)
• Per-entry ViewModel scope (rememberViewModelStoreNavEntryDecorator(), re-listing the saveable default), BackHandler, deep links, ListDetailSceneStrategy vs SinglePaneSceneStrategy

Plus an LLM tell: reaching for NavController / NavHost / navigate(route) in new Nav3 code, or a nav library for a screen whose "navigation" is internal state.

Verification

Every API shape was checked against the official android/nav3-recipes samples (which compile) and developer.android.com. Two cross-review rounds with docs context caught a real one — rememberNavBackStack is not generic (vararg NavKey), so the example now calls rememberNavBackStack(Home). Nav3 is flagged as alpha (1.x-alpha).

Why

From android/skills#50: Navigation 3 guidance was index-only without a workflow entry point.

Versions

compose-agent → 4.2.1. jetpack-compose-audit unchanged at 4.2.0. bin/ci passes.

🤖 Generated with Claude Code

[hamen]

🟢 Codex docs-verified review (Nav3 against official sources)

Blocker

• skills/compose-agent/references/navigation.md:41 — rememberNavBackStack<NavKey>(Home) does not match the official API. The API is rememberNavBackStack(vararg elements: NavKey): NavBackStack<NavKey>, with no type parameter, and the official samples call rememberNavBackStack(RouteA) / rememberNavBackStack(key). Use rememberNavBackStack(Home) instead. (developer.android.com)

Should-Fix

• skills/compose-agent/references/navigation.md:77 — “pick state when the result must not be lost” overstates ResultEventBus state semantics. The state result recipe says conflateAsState is for latest-result state, but that result state does not survive configuration change or process death. The APIs named are correct, but the guidance should say state is for latest-value consumption within the current navigation lifetime, not durable delivery.

• skills/compose-agent/references/navigation.md:76 / :118 — “never in a ViewModel” is good guidance for not injecting/mutating backStack from screen ViewModels, but it is slightly broader than the save-state doc, which explicitly lists storing a back stack in a ViewModel as an alternative if serialization/deserialization is handled manually. Narrow this to “don’t inject the back stack into feature/screen ViewModels as a navigation command surface.” (developer.android.com)

Nit

• skills/compose-agent/references/navigation.md:24 — the deep-link table says “push it onto the back stack.” The detailed section at :125 is accurate, but the table should say “resolve the intent to a key and seed or push it,” because the official basic deeplink recipe seeds rememberNavBackStack(key) for initial launch.

Accurate

• Artifact/package names are correct for the APIs used: androidx.navigation3:navigation3-runtime, androidx.navigation3:navigation3-ui, androidx.lifecycle:lifecycle-viewmodel-navigation3, and androidx.compose.material3.adaptive:adaptive-navigation3. (developer.android.com)

• The Nav3 model is otherwise right: NavKey + @Serializable, owned back stack, NavDisplay, entryProvider { entry<T> { ... } }, and arguments as key fields all match docs/samples. (developer.android.com)

• Decorator guidance for per-entry ViewModels is correct: adding rememberViewModelStoreNavEntryDecorator() requires listing rememberSaveableStateHolderNavEntryDecorator() as well.

• Scene strategy guidance is correct: pass sceneStrategies, mark entries with ListDetailSceneStrategy metadata, and use the adaptive artifact for Material list-detail scenes.

• Deep-link guidance at :125 is accurate: Nav3 resolves intent Uri to a NavKey; scene strategies do not register URIs.

_{re-review with android/nav3-recipes + developer.android.com context · requested by author}

[hamen]

🔵 Cursor docs-verified review (Nav3 against official sources)

PR #8 verification — navigation.md vs official sources

Checked against live developer.android.com pages (basics, save-state, scenes), androidx/androidx source (RememberNavBackStack.android.kt, NavDisplay.kt), and compiling android/nav3-recipes @ main.

---

Accurate (matches official sources)

Claim	Verdict
Nav3 is alpha (1.x-alpha; recipes pin 1.2.0-alpha02)	✅
Artifacts: navigation3-runtime, navigation3-ui, lifecycle-viewmodel-navigation3, adaptive-navigation3	✅ (nav3-recipes/gradle/libs.versions.toml)
@Serializable types implementing NavKey; args as key fields	✅ (save-state doc + all saveable recipes)
entryProvider { entry<T> { … } } DSL	✅ (basicdsl/BasicDslActivity.kt)
backStack.add / removeLastOrNull; no NavController in Nav3	✅
VM must not own stack; UI/route mutates stack	✅ (recipes + conditional/Navigator.kt — navigator holds stack, called from composables)
dropUnlessResumed { backStack.add(...) }	✅ (every basic recipe)
entryDecorators replaces defaults; re-add rememberSaveableStateHolderNavEntryDecorator() when adding VM decorator	✅ (save-state doc snippet + BasicViewModelsActivity.kt comment)
rememberViewModelStoreNavEntryDecorator() import/package	✅ (androidx.lifecycle.viewmodel.navigation3)
ListDetailSceneStrategy + pane metadata; adaptive artifact	✅ (material/listdetail/MaterialListDetailActivity.kt)
SinglePaneSceneStrategy is default	✅ (NavDisplay.kt default sceneStrategies = listOf(SinglePaneSceneStrategy()); scenes doc)
ResultEventBus: conflateAsState and ResultEffect both official	✅ (results/state/, results/event/)
Deep links: intent Uri → match → decode NavKey → rememberNavBackStack(key); no Nav3 deep-link DSL; scenes don't register URIs	✅ (deeplink/basic/MainActivity.kt, docs/deeplink-guide.md)
Nav2: composable<T>, toRoute(), no string routes, navDeepLink	✅
Decision table Nav3/Nav2 labeling	✅ — rows are scoped; LLM tell is helpful
Deep Links section fix (old “register on entry via scene strategies” removed)	✅ — now correct

---

Blocker

None for factual/API misrepresentation. The doc is substantially aligned with official guidance.

---

Should-fix

1. rememberNavBackStack<NavKey>(Home) in the main example — navigation.md:41

Library API (Android):

fun rememberNavBackStack(vararg elements: NavKey): NavBackStack<NavKey>

Official samples call rememberNavBackStack(Home) with no type argument (basicsaveable, save-state doc). The generic call rememberNavBackStack<NavKey>(Home) is not the library signature; it would not compile against androidx.navigation3. The typed form exists only as a recipe-local extension in conditional/ConditionalActivity.kt (with an issuetracker note).

Fix: use rememberNavBackStack(Home). If you want NavBackStack<MyAppNavKey>, document the custom rememberMyAppNavBackStack wrapper from the save-state doc — don't imply the library overload is generic.

2. Result decorator + saveable default — navigation.md:77–79

You correctly warn that custom entryDecorators replace defaults for the VM case. Official result recipes use only rememberResultEventBusNavEntryDecorator() (no saveable decorator). That means rememberSaveable inside entries may not work unless saveable is re-listed — same rule as VM, but unstated for results.

3. README / PR body wording — README.md (not navigation.md)

README says “ViewModel-driven navigation as durable state”; navigation.md:76 says the route mutates the stack and the VM must not get backStack. PR description also still mentions Flow<NavEvent> while the reference removed that pattern. Misleading metadata, not a Nav3 API error.

---

Nit

Item	Note
navigation.md:68	rememberListDetailSceneStrategy() compiles (optional directive); recipes pass directive for adaptive pane layout — fine as shorthand.
navigation.md:84	Predictive back + “override TransitionSpec” is directionally right; details live in animations recipes.
Decision table list-detail row	Doesn't mention extraPane() (used in material list-detail recipe for a third pane) — optional enhancement.
Open polymorphism	Save-state doc requires a SerializersModule on non-Android / open hierarchies; doc doesn't mention it — edge case.
Nav2 “2.8+”	Correct floor; recipes use Nav2 2.9.7.
Result process death	Doc correctly nudges toward flows.md for durable outcomes; could explicitly say ResultEventBus state is not process-death safe (your verified extract) — one line would tighten it.

---

Section-by-section

• Decision table — Accurate and well-scoped Nav3 vs Nav2 vs plain state. Bottom-nav → Nav3 matches multiplestacks recipe.
• Nav3 model + guardrails — Accurate except the rememberNavBackStack example syntax (Should-fix docs: add Codex install symlink instructions #1).
• Nav2 type-safe — Accurate example and guardrails.
• Common mistakes — Accurate; VM/backStack split is correct.
• Deep links — Accurate after this PR's rewrite.
• Primary sources — Good links; nav3-recipes callout is appropriate.

Bottom line: The PR's Nav3 guidance is largely docs-verified and fixes a real prior error on deep links/scene strategies. The one substantive code-shape issue is rememberNavBackStack<NavKey>(…) — change to the library's non-generic call. Everything else is polish or PR/README copy consistency.

_{link-mode re-review: reviewer fetched PR #8 + android/nav3-recipes + developer.android.com · requested by author}

[hamen]

🔵 Cursor review (automated cross-review)

PR #8 review — Navigation 3 decision table

Verified against android/nav3-recipes@main (BasicDsl, BasicSaveable, MaterialListDetail, ResultState/Event, BasicViewModels, deeplink MainActivity) and Android docs snippets (save-state, scenes). No blockers found.

---

Blocker

None. The prior rememberNavBackStack<NavKey>(Home) bug is fixed; the live example uses rememberNavBackStack(Home).

---

Should-fix

1. entryDecorators replaces defaults for any custom list, not only ViewModel
   Line 80 correctly warns that adding rememberViewModelStoreNavEntryDecorator() requires re-listing rememberSaveableStateHolderNavEntryDecorator(). Line 78 tells agents to set entryDecorators = listOf(rememberResultEventBusNavEntryDecorator()) without the same caveat. The official Result recipes do exactly that (ResultState/Event only list the result decorator), so they work only because those screens don't rely on the saveable decorator. An agent that adds rememberSaveable inside entries while following line 78 literally will break save/restore. Generalize the rule once: any non-default entryDecorators list drops all built-in decorators unless you re-add them.

2. Golden-path example vs dropUnlessResumed guardrail
   Guardrails (line 79) say every official recipe wraps tap navigation in dropUnlessResumed { backStack.add(...) }. The main Nav3 example (lines 48–50) uses bare onClick = { backStack.add(...) }. Not wrong, but it contradicts the guardrail and is the pattern LLMs copy most often.

---

Nit

1. Scene strategy snippet — Recipes use rememberListDetailSceneStrategy<NavKey>(…) (MaterialListDetail also passes directive). Parameterless rememberListDetailSceneStrategy() is valid per the scenes doc, but showing <NavKey> matches recipes and avoids inference confusion. Material recipe also uses extraPane() metadata; doc mentions only listPane() / detailPane().

2. Artifacts — Alpha caveat and adaptive-navigation3 / lifecycle-viewmodel-navigation3 are named; a one-line deps hint (navigation3-runtime, navigation3-ui, 1.x-alpha) would help agents that jump straight to Gradle.

3. Nav2 ViewModel pattern — Removing Channel<NavEvent> / Flow<NavEvent> is fine for the new invariant-focused guidance; a brief Nav2 note (“collect VM events in the composable, call navController.navigate there”) would mirror the Nav3 row without reintroducing controller-in-VM.

---

Checklist (your 8 points)

#	Claim	Verdict
1	Artifacts / packages / API names	Correct (navigation3-runtime/ui, lifecycle-viewmodel-navigation3, adaptive-navigation3, ResultEventBus, decorators, entryProvider, NavDisplay)
2	rememberNavBackStack — no type param in examples	Correct in code; explicitly warns against <NavKey>
3	NavKey + @Serializable, args as fields, entryProvider DSL	Matches BasicDsl / BasicSaveable / deeplink recipes
4	Decorators replace defaults; re-list saveable	Correct for ViewModel path; incomplete for ResultEventBus-only path (see Should-fix #1)
5	sceneStrategies + entry metadata; adaptive artifact	Matches MaterialListDetail; SinglePaneSceneStrategy default matches scenes doc
6	VM doesn't own stack; results via bus; conflateAsState not process-death-safe	Matches recipes + your verified extracts; app-level navigator carve-out is accurate
7	Deep links: intent→key, no DSL; scenes don't register URIs	Fixes prior wrong guidance; matches deeplink MainActivity
8	Nav2/Nav3 cross-misapplication	Rows are clearly labeled; Nav2 toRoute() / navDeepLink kept separate; no invented Nav3 APIs spotted

---

Overall: Looks good — ship after tightening the entryDecorators-replaces-defaults guidance for ResultEventBus (and ideally aligning the example with dropUnlessResumed).

_{via pr-review-relay · author: claude · context: nav3-context.md}

[hamen]

🟠 Antigravity review (automated cross-review)

The PR looks excellent and perfectly matches the official Nav3 documentation and nav3-recipes; no issues found!

_{via pr-review-relay · author: claude · context: nav3-context.md}

[hamen]

🟢 Codex review (automated cross-review)

Blocker
None.

Should-fix

• skills/compose-agent/references/navigation.md, navigation.md, README.md, CHANGELOG.md: The main guardrail at navigation.md:79 correctly narrows this to feature/screen ViewModels and carves out a dedicated app-level navigation holder, but these shorter references still say “never” mutate/own the back stack in a ViewModel. That overstates the official save-state doc, which explicitly lists storing the back stack in a ViewModel as an alternative if serialization/deserialization is handled manually. Narrow these to “screen/feature ViewModel” or point back to the app-level holder carve-out.

Nit
None.

Everything else I checked lines up with the official sources: non-generic rememberNavBackStack(Home), NavKey + @Serializable, entryProvider, decorator replacement/re-listing saveable state, scene metadata via sceneStrategies, ResultEventBus state/event variants, non-durable conflateAsState, and Nav3 deep links as intent-to-key mapping with no DSL. Sources checked included the live Android docs for save-state, scenes, Nav2 type safety, and the official android/nav3-recipes samples.

_{via pr-review-relay · author: claude · context: nav3-context.md}