Nav Tab Registration Drift Agent Skill

Navigation tab registration drift

An app with more than one form factor grows more than one navigation surface: a bottom bar for a

compact window, a rail for a wide one, often a stylized bar behind a setting. Each builds its own:

val bottomNavScreens = listOfNotNull(
    BottomNavScreen.Home,
    BottomNavScreen.MixForYou.takeIf { showMixForYouTab },   // conditional
    BottomNavScreen.Analytics.takeIf { showAnalyticsTab },   // conditional
    BottomNavScreen.Library, BottomNavScreen.Search,
)

That literal appears once per surface, and the host picks between them on window width and on a user

setting — so the surface you tested is the one you happened to be looking at.

The tab type is a sealed hierarchy whose ordinal is declared, not derived:

sealed class BottomNavScreen(val ordinal: Int, val destination: Any, /* title, icon */) {
    data object Home : BottomNavScreen(ordinal = 0, destination = HomeDestination, /* … */)
    data object Search : BottomNavScreen(1, /* … */); data object Library : BottomNavScreen(2, /* … */)
    data object Analytics : BottomNavScreen(3); data object MixForYou : BottomNavScreen(4)  // gated
}

Compare with the list: declared they run 0,1,2,3,4 while the rendered order is 0,4,3,2,1, and two

conditional tabs change the rendered *length* too — the number is not a position in anything. An

enum would derive these same five today; declaring pays off on the *next* edit. The selection is

persisted as this number, per surface, in a rememberSaveable int, outliving a config change

and a process death and restored into whatever build is running by then — so a derived ordinal,

which renumbers on any reorder or insertion, would select a *different* tab than the user left,

while a declared one makes a reorder a no-op and an insertion take the next free number. In saved

state the value is an identity, and an identity must not be derived from source order.

Traps

Registering in fewer surfaces than exist. The symptom is not an error: the tab is fully built,

its route resolves, and it never appears on the surface you did not edit. Enumerate first — step 1

below — but count list literals, not files and not surfaces; none of the three numbers agree.

Four files here: one declares the type, one is the indicator widget, and two hold four

listOfNotNull literals between them (bottom bar and rail; the stylized bar's two) feeding three

surfaces — four is the edit count. Same shape as guard-on-every-trigger-path.

One surface keeps two lists, and they are not the same list. The stylized bar splits the tabs:

one renders as a floating button beside the capsule rather than inside it:

val bottomNavScreens = listOfNotNull(/* … all five … */)   // selection + routing
val barTabs = listOfNotNull(/* … all but Search … */)      // what the capsule draws

Update only barTabs and the tab draws while tapping does nothing whatsoever: the handler resolves

the tapped ordinal against the *other* list — `bottomNavScreens.find { it.ordinal == index } ?:

return` — and returns without navigating, moving the highlight, logging or throwing. Update only the

full list and it is routable but never drawn. The sliding indicator forces the split: it needs

contiguous, evenly sized slots, and the floating button is neither.

The ordinal is an identity; the widget wants a position. Every conversion lives at one boundary

— the call into the indicator widget, which speaks positions in its own tabs list:

LiquidGlassTabBar(
    tabs = barTabs,                                                       // identity → position
    selectedTab = barTabs.indexOfFirst { it.ordinal == selectedIndex },
    onTabSelected = { position -> selectTab(barTabs[position].ordinal) }, // position → identity
)

Comparing a stored selection against a loop index (selected == index) works only while the two

systems coincide; reordering exposes it — the family of queue-index-vs-shuffle-space.

A variable named index that holds an identity. The stylized bar's selection function takes

index: Int and resolves it as an ordinal, so its selectedIndex == index is correct despite reading

like the bug above — selectedOrdinal / tabPosition removes the only reason to trace a call chain.

A conditional tab needs a fallback in every surface *and* at the host. Switching the feature off

removes the tab from the list and leaves two things dangling. The selection highlight, per surface:

LaunchedEffect(showAnalyticsTab, showMixForYouTab) {
    if ((!showAnalyticsTab && selectedIndex == BottomNavScreen.Analytics.ordinal) ||
        (!showMixForYouTab && selectedIndex == BottomNavScreen.MixForYou.ordinal)
    ) { selectedIndex = BottomNavScreen.Home.ordinal }
}

And the user, who may be standing on that screen — handled once at the host, which navigates away

when the flag drops and the back-stack entry still matches. Neither substitutes: fix only the

highlight and someone is stranded where no tab points; fix only the navigation and nothing is

highlighted.

A bar that sizes itself per tab breaks when the count grows. The capsule divides the width it is

actually given — ((availableWidth - inset * 2) / tabsCount), capped so a two-tab bar on a wide

window does not stretch into slabs — and its row fills its parent rather than wrapping. History for

both: a fixed per-tab width plus a wrapping row grew the bar past the window once an extra tab

appeared, and the sibling button fell off. A fixed item width, total width or wrapping container

each make a surface a new tab can overflow.

The graph entry is a separate registration. The tab's destination is just an object, so a tab

with no composable<ThatDestination> block in the graph compiles clean and fails at the tap.

A status entry point drifts exactly like a tab, and it is worse when it does. An icon carried by

more than one top app bar — into a running session, a sync, a download queue — hits the same

silence: badge one bar and the other keeps a plain icon. That badge is often the *only* sign the

session is still live once the user navigates away, so the bar missing it looks like nothing is

running. Give every bar one shared composable owning icon, click and badge — never its parts —

reading the repository directly (one boolean off a flow: koin-viewmodel-scoping-traps).

A badge dot needs a ring of the page colour. Bare on a glyph, a 7 dp dot merges with the icon's

own dark shapes; an 11 dp circle of colorScheme.background behind it survives any glyph and theme.

Verifying it

# 1. Which files know about the tab type — four here, and that is NOT the edit count. One declares
#    it, one merely accepts a list (the indicator widget), the rest BUILD lists: count literals.
grep -rln --include="*.kt" "BottomNavScreen" . | grep -v "/build/"

# 2. One tab's destination everywhere: route file, graph entry, tab declaration, every surface's
#    start-destination map, and the host effect that navigates away when a gating flag drops.
grep -rn --include="*.kt" "AnalyticsDestination" . | grep -v "/build/"

# 3. Comparisons mixing the two numbering systems — read each and name the right-hand side's space.
grep -rn --include="*.kt" -E "selected(Index|Tab) == (index|it)\b" . | grep -v "/build/"

# 4. Status entry points in a top app bar — every hit must name the SAME shared composable.
grep -rnE --include="*.kt" "[A-Za-z]+IconButton \{ navController\.navigate" . | grep -v "/build/"

Then exercise both form factors — launch narrow, launch wide, resize across the breakpoint with the

new tab selected. Turn the conditional tab's feature off *while standing on its screen*: the app

must move you and highlight a different tab, on every surface. Then add a throwaway sixth tab —

anything falling off the edge has a hardcoded count.