ruby_everywhere 0.3.0 → 0.4.0

data/support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/MainActivity.kt

@@ -0,0 +1,975 @@
+package com.rubyeverywhere.shell
+
+import android.content.Intent
+import android.net.Uri
+import android.os.Bundle
+import android.os.SystemClock
+import android.util.Log
+import android.util.TypedValue
+import android.view.LayoutInflater
+import android.view.View
+import android.view.ViewGroup
+import android.webkit.CookieManager
+import android.webkit.WebStorage
+import android.widget.FrameLayout
+import android.widget.ImageView
+import android.widget.LinearLayout
+import android.widget.TextView
+import androidx.activity.enableEdgeToEdge
+import androidx.appcompat.app.AlertDialog
+import androidx.core.content.ContextCompat
+import androidx.core.graphics.drawable.DrawableCompat
+import androidx.core.view.isVisible
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.lifecycleScope
+import androidx.lifecycle.repeatOnLifecycle
+import com.google.android.material.bottomnavigation.BottomNavigationView
+import com.google.android.material.bottomsheet.BottomSheetDialog
+import com.rubyeverywhere.shell.extensions.EverywhereExtensions
+import dev.hotwire.core.config.Hotwire
+import dev.hotwire.core.turbo.config.PathConfiguration
+import dev.hotwire.core.turbo.config.PathConfigurationLoadState
+import dev.hotwire.navigation.activities.HotwireActivity
+import dev.hotwire.navigation.navigator.Navigator
+import dev.hotwire.navigation.navigator.NavigatorConfiguration
+import dev.hotwire.navigation.tabs.HotwireBottomNavigationController
+import dev.hotwire.navigation.tabs.HotwireBottomTab
+import dev.hotwire.navigation.util.applyDefaultImeWindowInsets
+import kotlinx.coroutines.launch
+
+/**
+ * The shell's only Activity — the Android counterpart of iOS's SceneDelegate,
+ * carrying the same responsibilities: build the tab bar from the auth-aware
+ * path configuration, keep it in sync as that configuration changes, hold the
+ * splash until first content, act on the page's control messages, route deep
+ * links, and run third-party sign-in outside the web view.
+ */
+class MainActivity : HotwireActivity() {
+
+    private val config = EverywhereConfig.shared
+
+    private lateinit var bottomNav: BottomNavigationView
+    private lateinit var tabController: HotwireBottomNavigationController
+    private lateinit var splash: FrameLayout
+
+    /** The bar item that stands for every tab past the fourth. See [MainTabs.arrange]. */
+    private val moreTitle: String by lazy { getString(R.string.everywhere_more_tab) }
+
+    /**
+     * The tab set this Activity was built around. Frozen for the Activity's
+     * lifetime on purpose: `navigatorConfigurations()` is read by
+     * `HotwireActivityDelegate`'s constructor and again by each of the five
+     * `NavigatorHost.onCreate`s, and every one of them must see the same five
+     * configurations. A list that changed underneath them is the
+     * `IllegalStateException("No configuration found for NavigatorHost")` case.
+     */
+    private val initialArrangement: MainTabs.Arrangement by lazy {
+        MainTabs.arrange(MainTabs.entries(), moreTitle)
+    }
+
+    private val pooledConfigurations: List<NavigatorConfiguration> by lazy {
+        MainTabs.tabs(config, initialArrangement).map { it.configuration }
+    }
+
+    /** The arrangement backing whatever is on screen right now. */
+    private var currentArrangement: MainTabs.Arrangement =
+        MainTabs.Arrangement(emptyList(), emptyList(), emptyList())
+
+    /**
+     * Fingerprints of what is on screen, so an unchanged config refresh
+     * rebuilds nothing. [loadedPathsFingerprint] is the expensive one: when it
+     * changes, the hosts were built against the wrong start locations and only
+     * `recreate()` can fix that.
+     */
+    private var loadedFingerprint: String? = null
+    private var loadedPathsFingerprint: String? = null
+
+    /**
+     * Last badge per tab path. Pages usually set badges from the first page
+     * load — often before the auth-gated tab bar exists — so badges are stored
+     * here and re-applied whenever the tab bar is (re)built. They have to be:
+     * `loadMenu()` opens with `view.menu.clear()`, which drops every badge
+     * drawable along with the menu.
+     */
+    private val tabBadges = mutableMapOf<String, Int>()
+
+    /** Cold-launch splash timing; see [dismissSplash]. */
+    private var splashShownAt = 0L
+    private var splashIsCustom = false
+    private var splashDismissScheduled = false
+
+    /**
+     * Set while the web view is spending a handoff token. The visit that
+     * follows carries the Set-Cookie headers that sign the app in, so the
+     * auth-gated tab list can only be fetched once it has finished.
+     */
+    private var awaitingAuthHandoff = false
+
+    /**
+     * A location that arrived before any navigator was ready — a deep link on a
+     * cold launch, or the landing page after an instance switch rebuilt the
+     * Activity. Held until the host it belongs to reports in, then routed.
+     *
+     * [pendingRouteHostId] pins it to one host when the destination is an
+     * overflow tab: that route was aimed at the More host specifically, and a
+     * different host reporting ready first would otherwise swallow it.
+     */
+    private var pendingRoute: String? = null
+    private var pendingRouteHostId: Int? = null
+
+    /**
+     * Set while the More tab is being selected in code rather than by a tap.
+     * Selecting an item programmatically runs the same listeners a tap does, and
+     * this is the one case where selecting More is meant literally: a route to
+     * an overflow path (a picked sheet row, a deep link, `Everywhere.visit`)
+     * needs the host to come forward and receive it — not to be refused, and not
+     * to be answered with the sheet.
+     */
+    private var selectingMoreForRoute = false
+
+    /** The open More sheet, so a second tap doesn't stack a second one. */
+    private var moreSheet: BottomSheetDialog? = null
+
+    // ------------------------------------------------------------------------
+    // Lifecycle
+    // ------------------------------------------------------------------------
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        // The manifest launches this Activity with Theme.Everywhere.Splash so
+        // the system's starting window is already the app's background colour.
+        // Swap to the real theme before the content view inflates.
+        setTheme(R.style.Theme_Everywhere)
+        enableEdgeToEdge()
+        super.onCreate(savedInstanceState)
+
+        setContentView(R.layout.activity_main)
+        findViewById<View>(R.id.root).applyDefaultImeWindowInsets()
+
+        splash = findViewById(R.id.splash)
+        showSplash()
+
+        initializeTabs(savedInstanceState?.getInt(STATE_SELECTED_TAB) ?: 0)
+
+        observeEvents()
+        observePathConfiguration()
+
+        // Survives `recreate()` — the Intent does, fields don't. See
+        // [rebuildAndRoute].
+        intent.getStringExtra(EXTRA_ROUTE)?.let {
+            intent.removeExtra(EXTRA_ROUTE)
+            // Through route() rather than straight into pendingRoute, so a
+            // landing page that happens to be an overflow tab still selects the
+            // More host on the way in.
+            route(it)
+        }
+
+        // A deep link that launched the app, routed once a navigator exists.
+        handleIntent(intent)
+    }
+
+    override fun onSaveInstanceState(outState: Bundle) {
+        super.onSaveInstanceState(outState)
+        // Saved rather than kept in a field precisely because of the
+        // `recreate()` a tab-path change forces: the user should come back to
+        // the tab they were on.
+        outState.putInt(STATE_SELECTED_TAB, bottomNav.selectedItemId)
+    }
+
+    /**
+     * Refetch the server path configuration on every foreground, so a config
+     * change lands without a relaunch. Server-only: it is the auth-aware source
+     * of truth, and skipping the bundled copy avoids a flash of the baked
+     * (all-tabs) config before the server's answer arrives.
+     */
+    override fun onResume() {
+        super.onResume()
+        reloadPathConfiguration()
+    }
+
+    /** `launchMode="singleTask"`, so deep links and auth callbacks arrive here. */
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        setIntent(intent)
+        handleIntent(intent)
+    }
+
+    override fun onDestroy() {
+        // A BottomSheetDialog holds a window on this Activity, and the shell
+        // calls `recreate()` for its own reasons (a tab-path change, an instance
+        // switch). One left open across that is a leaked window.
+        dismissMoreSheet()
+        super.onDestroy()
+    }
+
+    override fun navigatorConfigurations(): List<NavigatorConfiguration> = pooledConfigurations
+
+    /**
+     * A host finished building its start destination. Used to flush a route
+     * captured before any navigator existed — at `onCreate` there is nothing to
+     * route through yet.
+     */
+    override fun onNavigatorReady(navigator: Navigator) {
+        super.onNavigatorReady(navigator)
+
+        val route = pendingRoute ?: return
+        // A route aimed at a specific host waits for that host. Only overflow
+        // routes are pinned this way, and only because the More host is lazy:
+        // it builds its navigator when the tab is first selected, which can be
+        // after another host has already reported in.
+        pendingRouteHostId?.let { if (navigator.configuration.navigatorHostId != it) return }
+
+        pendingRoute = null
+        pendingRouteHostId = null
+        navigator.route(route)
+    }
+
+    // ------------------------------------------------------------------------
+    // Tabs
+    // ------------------------------------------------------------------------
+
+    private fun initializeTabs(selectedIndex: Int) {
+        bottomNav = findViewById(R.id.bottom_nav)
+
+        tabController = HotwireBottomNavigationController(
+            activity = this,
+            view = bottomNav,
+            // Mandatory, not a preference. With eager loading all five pooled
+            // hosts cold-boot a WebView and fetch their start location at
+            // launch — including the hidden ones, whose URLs are exactly the
+            // auth-gated pages the config was hiding.
+            lazyLoadTabs = true
+        )
+
+        val arrangement = initialArrangement
+        loadedFingerprint = MainTabs.fingerprint(arrangement.entries)
+        loadedPathsFingerprint = MainTabs.pathsFingerprint(arrangement)
+
+        applyTabs(arrangement, selectedIndex)
+    }
+
+    /**
+     * The one place `load()` is ever called, because a second `load()` on a
+     * live controller has three side effects that all have to be undone in the
+     * same breath:
+     *
+     *   1. `loadMenu()` starts with `view.menu.clear()`, which drops every
+     *      badge — and every icon, since it re-reads `iconResId`.
+     *   2. `menu.clear()` resets Material's `selectedItemId` to 0, so
+     *      `selectTab(0)` takes the *reselect* path, which upstream wires to
+     *      `navigator.clearAll()`. The user is silently returned to the tab's
+     *      start location, and only when the selected tab is the first one —
+     *      the default, so it is invisible in casual testing. Nulling the
+     *      reselect listener first is enough; `load()` reinstalls it.
+     *   3. `selectTab()` runs through the still-installed item-selected
+     *      listener, so the tab-selected callback fires for a selection the
+     *      user never made.
+     *
+     * Fragments and WebViews are NOT recreated by this — that part of the cheap
+     * path holds.
+     */
+    private fun applyTabs(arrangement: MainTabs.Arrangement, selectedIndex: Int) {
+        val tabs = MainTabs.tabs(config, arrangement)
+        currentArrangement = arrangement
+
+        // The sheet lists the arrangement it was opened against; a rebuild has
+        // just replaced that. Cheaper to close it than to reconcile it, and a
+        // tab bar changing underneath an open sheet is an auth change — the one
+        // moment the user should not be handed a stale list of destinations.
+        dismissMoreSheet()
+
+        // The item-SELECTED listener is nulled for the same reason the reselect
+        // one is: `load()` selects a tab while it runs, and a listener still
+        // installed from the previous arrangement would answer for a selection
+        // the user never made — including, with a stale More index, refusing it.
+        bottomNav.setOnItemSelectedListener(null)
+        bottomNav.setOnItemReselectedListener(null)
+        tabController.setOnTabSelectedListener(null)
+
+        tabController.load(tabs, selectedIndex)
+
+        applyTabIcons(arrangement)
+        applyTabBadges(arrangement)
+        // AFTER load(), never before: load() reinstalls upstream's own
+        // listeners over anything set here (that is the whole reason the
+        // reselect listener has to be nulled first), so ours have to go on last
+        // or the More tap does nothing.
+        installTabListeners(arrangement)
+
+        // Nothing to switch between means no tab bar. The first host is still
+        // the current navigator and shows the app's start URL, which is the
+        // single-navigator shape iOS falls back to.
+        tabController.visibility = if (arrangement.slots.isEmpty()) {
+            HotwireBottomNavigationController.Visibility.HIDDEN
+        } else {
+            HotwireBottomNavigationController.Visibility.DEFAULT
+        }
+    }
+
+    /**
+     * `HotwireBottomTab.iconResId` is an `@DrawableRes Int` — there is no
+     * Drawable or Bitmap overload — so a font-rendered icon can only be applied
+     * by overwriting the menu item afterwards. Every tab is therefore built
+     * with `ic_tab_placeholder` and corrected here, after every `load()`.
+     */
+    private fun applyTabIcons(arrangement: MainTabs.Arrangement) {
+        val sizePx = (ICON_SIZE_DP * resources.displayMetrics.density).toInt()
+
+        // Over the slots, not the entries: the More slot has an icon of its own
+        // (`more_horiz`) and no entry to take one from.
+        arrangement.slots.forEachIndexed { index, slot ->
+            bottomNav.menu.getItem(index).icon = IconFont.drawable(this, slot.icon, sizePx)
+        }
+    }
+
+    /**
+     * Overflow tabs have no bar item of their own, so their badges are summed
+     * onto More — the same aggregation iOS's More tab does. Every slot is
+     * re-derived from [tabBadges] rather than patched in place, because a badge
+     * on any one overflow tab changes the More total, and because [applyTabs]
+     * has to re-apply all of them after `load()` anyway.
+     */
+    private fun applyTabBadges(arrangement: MainTabs.Arrangement) {
+        for (index in 0 until MainTabs.size) {
+            val count = when {
+                arrangement.isMoreIndex(index) ->
+                    arrangement.overflow.sumOf { tabBadges[it.path] ?: 0 }
+                else -> arrangement.entryAt(index)?.let { tabBadges[it.path] } ?: 0
+            }
+            applyTabBadge(index, count)
+        }
+    }
+
+    private fun applyTabBadge(index: Int, count: Int) {
+        if (index < 0 || index >= bottomNav.menu.size()) return
+
+        if (count > 0) {
+            bottomNav.getOrCreateBadge(index).apply {
+                number = count
+                isVisible = true
+            }
+        } else {
+            bottomNav.removeBadge(index)
+        }
+    }
+
+    // ------------------------------------------------------------------------
+    // The More tab
+    // ------------------------------------------------------------------------
+
+    /**
+     * Both tab listeners, reinstalled after every `load()` — but only when there
+     * is a More slot. With five tabs or fewer, upstream's own listeners (which
+     * `load()` just installed) are exactly right and are left alone.
+     *
+     * **More is a menu, not a destination.** Tapping it must open the sheet and
+     * navigate nowhere: the user has not chosen anything yet, so nothing should
+     * load and the tab they were on should stay the tab they are on. Material
+     * selects an item the instant it is tapped, and the only hook early enough
+     * to stop that is the item-selected listener's return value — `false` means
+     * "I handled it, don't select it", and the previous item keeps the bar with
+     * no flicker. Waiting for the sheet's dismiss callback to put it back would
+     * show the user a round trip through the More state.
+     *
+     * Owning that listener means reimplementing what it displaces for the other
+     * tabs, which is [switchToSlot]. The same goes for reselection: upstream
+     * clears the reselected tab's backstack, right for a real tab and wrong for
+     * More, whose "content" is the sheet.
+     *
+     * Selection and reselection are separate callbacks, and More has to answer
+     * to both — the first tap after a row was chosen is a reselection, and only
+     * handling selection would make More a one-shot.
+     */
+    private fun installTabListeners(arrangement: MainTabs.Arrangement) {
+        if (!arrangement.hasMore) return
+
+        bottomNav.setOnItemSelectedListener { item ->
+            val index = item.itemId
+            // selectingMoreForRoute is the one case where selecting More IS the
+            // intent: something routed to an overflow path and the host has to
+            // come forward to receive it.
+            if (arrangement.isMoreIndex(index) && !selectingMoreForRoute) {
+                showMoreSheet(arrangement)
+                false
+            } else {
+                switchToSlot(index)
+                true
+            }
+        }
+
+        bottomNav.setOnItemReselectedListener { item ->
+            if (arrangement.isMoreIndex(item.itemId)) {
+                showMoreSheet(arrangement)
+            } else {
+                // What upstream's listener would have done.
+                MainTabs.hostIds.getOrNull(item.itemId)?.let {
+                    delegate.findNavigatorHost(it)?.navigator?.clearAll()
+                }
+            }
+        }
+    }
+
+    /**
+     * Bring a slot's host forward — upstream `HotwireBottomNavigationController`'s
+     * private `switchTab`, which taking over the item-selected listener costs us.
+     * Both halves matter: `setCurrentNavigator` is what routes and the back
+     * button follow (and what lazily builds a host's graph the first time), and
+     * the visibility pass is what stops five stacked hosts from drawing at once.
+     */
+    private fun switchToSlot(index: Int) {
+        val tabs = tabController.tabs
+        val selected = tabs.getOrNull(index) ?: return
+
+        delegate.setCurrentNavigator(selected.configuration)
+        tabs.forEach { tab ->
+            findViewById<View>(tab.configuration.navigatorHostId)?.isVisible = tab === selected
+        }
+    }
+
+    /**
+     * The overflow tabs, as a bottom sheet — iOS gets this list free from
+     * UITabBarController and Android has no equivalent at all, so it is built by
+     * hand. Icons come from [IconFont], the shell's only icon path, so a name
+     * that renders on a tab renders here identically.
+     *
+     * Dismissing without choosing is a complete no-op by construction: the sheet
+     * changes nothing on its way up, so there is nothing to undo on its way
+     * down. Only a row does anything, and what it does is [route].
+     */
+    private fun showMoreSheet(arrangement: MainTabs.Arrangement) {
+        // A programmatic selection en route to an overflow tab runs these same
+        // listeners. The user asked to go somewhere; don't answer with a menu.
+        if (selectingMoreForRoute) return
+        if (moreSheet?.isShowing == true) return
+
+        val inflater = LayoutInflater.from(this)
+        val root = inflater.inflate(R.layout.tab_more_sheet, null) as ViewGroup
+        val dialog = BottomSheetDialog(this)
+
+        root.findViewById<TextView>(R.id.tab_more_sheet_title).text = moreTitle
+
+        val sizePx = (ICON_SIZE_DP * resources.displayMetrics.density).toInt()
+        val tint = themeColor(CONTROL_ATTR, ICON_FALLBACK)
+        val list = root.findViewById<LinearLayout>(R.id.tab_more_sheet_items)
+
+        for (entry in arrangement.overflow) {
+            val row = inflater.inflate(R.layout.tab_more_sheet_item, list, false)
+            row.findViewById<TextView>(R.id.tab_more_sheet_item_title).text = entry.title
+
+            // IconFont draws opaque white and leaves colour to the host, so the
+            // tint is required, not decorative: untinted is invisible in light
+            // mode. (The tab bar gets this from its ColorStateList; a plain
+            // ImageView has none.)
+            row.findViewById<ImageView>(R.id.tab_more_sheet_item_icon).setImageDrawable(
+                DrawableCompat.wrap(IconFont.drawable(this, entry.icon, sizePx)).mutate()
+                    .also { DrawableCompat.setTint(it, tint) }
+            )
+
+            row.setOnClickListener {
+                dialog.dismiss()
+                route(config.url(forPath = entry.path))
+            }
+            list.addView(row)
+        }
+
+        dialog.setOnDismissListener { moreSheet = null }
+        dialog.setContentView(root)
+        moreSheet = dialog
+        dialog.show()
+    }
+
+    private fun dismissMoreSheet() {
+        moreSheet?.dismiss()
+        moreSheet = null
+    }
+
+    /**
+     * Claim a location for the More host when it is an overflow tab's path.
+     *
+     * Every other way into the app — a deep link, a universal link,
+     * `Everywhere.visit` — routes through the current navigator, which for an
+     * overflow tab is whatever tab the user happens to be standing in. That is
+     * how a destination with no bar item goes missing. Selecting the More host
+     * first is what gives it somewhere to land.
+     *
+     * Returns whether the selection happened, because the caller then has to
+     * wait a frame: selecting a lazy host is what builds its navigator.
+     */
+    private fun selectMoreHostForOverflow(location: String): Boolean {
+        val arrangement = currentArrangement
+        if (!arrangement.hasMore) return false
+
+        val path = config.pathAndQuery(location)
+        if (arrangement.overflow.none { it.path == path }) return false
+
+        val index = arrangement.moreIndex
+        selectingMoreForRoute = true
+        try {
+            // Setting selectedItemId runs the item-selected (or, if More is
+            // already selected, the item-reselected) listener synchronously,
+            // which is exactly why the flag above wraps it.
+            bottomNav.selectedItemId = index
+        } finally {
+            selectingMoreForRoute = false
+        }
+        return true
+    }
+
+    private fun themeColor(attr: Int, fallback: Int): Int {
+        val value = TypedValue()
+        if (!theme.resolveAttribute(attr, value, true)) return fallback
+        return if (value.resourceId != 0) ContextCompat.getColor(this, value.resourceId) else value.data
+    }
+
+    // ------------------------------------------------------------------------
+    // Path configuration
+    // ------------------------------------------------------------------------
+
+    /**
+     * The tabs are auth-gated server-side, so the shell reacts to the
+     * configuration landing rather than reading it once. `loadState` emits for
+     * each source (bundled, cached, remote); the fingerprints make the
+     * redundant emissions free.
+     */
+    private fun observePathConfiguration() {
+        lifecycleScope.launch {
+            repeatOnLifecycle(Lifecycle.State.STARTED) {
+                Hotwire.config.pathConfiguration.loadState.collect { state ->
+                    if (state is PathConfigurationLoadState.Loaded) applyPathConfiguration()
+                }
+            }
+        }
+    }
+
+    private fun applyPathConfiguration() {
+        val entries = MainTabs.entries()
+        val fingerprint = MainTabs.fingerprint(entries)
+        if (fingerprint == loadedFingerprint) return
+
+        val arrangement = MainTabs.arrange(entries, moreTitle)
+
+        if (MainTabs.pathsFingerprint(arrangement) != loadedPathsFingerprint) {
+            // A tab's start location changed, so its NavigatorHost was built
+            // against the wrong URL — and the host resolved that configuration
+            // once, in onCreate, then cached it inside its Navigator. Nothing
+            // short of rebuilding the Activity re-reads it. The selected tab
+            // survives through onSaveInstanceState.
+            //
+            // Guarded, because `recreate()` here is a loop waiting to happen:
+            // every rebuild re-runs onCreate, which re-reads the configuration
+            // and can land right back in this branch. When it does, the Activity
+            // is destroyed and rebuilt faster than it can draw, input dispatch
+            // never gets a turn, and Android kills the app with an ANR — a hard
+            // freeze that looks nothing like a config problem from the outside.
+            //
+            // The wall clock is the only honest signal: fields die with the
+            // Activity, so the timestamp lives on the Intent, which survives.
+            val now = SystemClock.elapsedRealtime()
+            val since = now - intent.getLongExtra(EXTRA_LAST_REBUILD, 0L)
+            if (since < REBUILD_DEBOUNCE_MS) {
+                // Take the cheap path instead. Tab paths will be stale until the
+                // next clean rebuild, but a slightly wrong tab bar is a far
+                // better outcome than an app the user has to force-quit.
+                Log.w(TAG, "tab paths changed again after ${since}ms — skipping rebuild to avoid " +
+                    "a recreate loop; tab start locations may be stale")
+                loadedFingerprint = fingerprint
+                loadedPathsFingerprint = MainTabs.pathsFingerprint(arrangement)
+                applyTabs(arrangement, safeSelectedIndex(arrangement))
+                return
+            }
+
+            Log.d(TAG, "tab paths changed — rebuilding the activity")
+            intent.putExtra(EXTRA_LAST_REBUILD, now)
+            recreate()
+            return
+        }
+
+        loadedFingerprint = fingerprint
+        applyTabs(arrangement, safeSelectedIndex(arrangement))
+    }
+
+    /**
+     * The selected tab, clamped into the list we are about to load.
+     *
+     * `selectedItemId` doubles as an index only because upstream builds the menu
+     * with `menu.add(0, index, index, …)` — and upstream then does `tabs[itemId]`
+     * on every selection. So when a tab set SHRINKS (signing out drops the
+     * auth-gated tabs), a selection left pointing past the new end is an
+     * IndexOutOfBounds waiting for the next tap, inside framework code we don't
+     * own. Clamping here is the whole fix.
+     *
+     * Clamped to the SLOTS, which is what the bar actually shows: eleven tabs
+     * still only ever occupy five, so the entry count is not the bound.
+     */
+    private fun safeSelectedIndex(arrangement: MainTabs.Arrangement): Int =
+        bottomNav.selectedItemId.coerceIn(0, (arrangement.slots.size - 1).coerceAtLeast(0))
+
+    private fun reloadPathConfiguration(serverOnly: Boolean = true) {
+        val remoteUrl = config.pathConfigurationUrl
+
+        Hotwire.loadPathConfiguration(
+            context = this,
+            location = PathConfiguration.Location(
+                // Server-only after launch. The bundled copy is the baked,
+                // all-tabs document; re-reading it would flash tabs a
+                // signed-out user isn't entitled to before the server says so.
+                assetFilePath = if (serverOnly) null else BUNDLED_PATH_CONFIGURATION,
+                remoteFileUrl = remoteUrl
+            ),
+            options = PathConfiguration.LoaderOptions(httpHeaders = cookieHeaders(remoteUrl))
+        )
+    }
+
+    /**
+     * The tab list is auth-gated and the framework fetches the configuration
+     * with OkHttp — which has no cookie jar and knows nothing about the
+     * WebView's. Without mirroring the session cookie across, the config
+     * request is anonymous and a signed-in user gets a signed-out tab bar.
+     *
+     * (iOS needs a whole `getAllCookies` round trip and a full re-sync for
+     * this. Android's CookieManager is one process-wide store, so it is one
+     * synchronous call.)
+     */
+    private fun cookieHeaders(url: String): Map<String, String> {
+        val cookie = runCatching { CookieManager.getInstance().getCookie(url) }.getOrNull()
+        return if (cookie.isNullOrEmpty()) emptyMap() else mapOf("Cookie" to cookie)
+    }
+
+    // ------------------------------------------------------------------------
+    // Page → shell control messages
+    // ------------------------------------------------------------------------
+
+    private fun observeEvents() {
+        lifecycleScope.launch {
+            repeatOnLifecycle(Lifecycle.State.STARTED) {
+                EverywhereEvents.events.collect { handle(it) }
+            }
+        }
+    }
+
+    private fun handle(event: EverywhereEvents.Event) {
+        when (event) {
+            is EverywhereEvents.Event.ReloadConfig -> reloadPathConfiguration()
+            is EverywhereEvents.Event.ResetApp -> resetApp(resetTarget(event.to))
+            is EverywhereEvents.Event.SetTabBadge -> setTabBadge(event.path, event.count)
+            is EverywhereEvents.Event.SetBadge -> setAppBadge(event.count)
+            is EverywhereEvents.Event.SetInstance -> setInstance(event.url, event.to)
+            is EverywhereEvents.Event.ClearInstance -> clearInstance(event.to)
+            is EverywhereEvents.Event.NativeVisit -> nativeVisit(event.path)
+            is EverywhereEvents.Event.AuthFlow -> startAuthFlow(event.to)
+        }
+    }
+
+    private fun setTabBadge(path: String, count: Int) {
+        if (count > 0) tabBadges[path] = count else tabBadges.remove(path)
+
+        // Every slot re-derived rather than the one that matched: a badge on an
+        // overflow tab lands on More as part of a sum, and a sum can only be
+        // recomputed, not patched.
+        applyTabBadges(currentArrangement)
+    }
+
+    /**
+     * There is no Android equivalent of iOS's `setBadgeCount`. Launcher badges
+     * are derived from active notifications, and every "badge count" library is
+     * a per-OEM broadcast the AOSP launcher ignores. Logged rather than faked:
+     * the page's call is not an error, it simply has nowhere to land here.
+     */
+    private fun setAppBadge(count: Int) {
+        Log.d(TAG, "setBadge($count): Android has no launcher badge API; ignoring")
+    }
+
+    /**
+     * `everywhereVisit(path)` from extension code: routed through the active
+     * navigator so the visit gets the full path-configuration treatment
+     * (modals, native screens) like any web-driven visit.
+     */
+    private fun nativeVisit(path: String) {
+        val location = if (path.startsWith("/")) config.url(forPath = path) else path
+        route(location)
+    }
+
+    /**
+     * Every location the shell routes itself passes through here: deep links,
+     * universal links, `Everywhere.visit`, the reset landing page, and a pick
+     * from the More sheet.
+     *
+     * An overflow tab is claimed by the More host first. That selection is what
+     * builds the host's navigator (the pool is lazy), so delivery waits a frame
+     * — and if the navigator still isn't ready, [pendingRoute] carries it,
+     * pinned to that host so no other one answers for it.
+     */
+    private fun route(location: String) {
+        if (selectMoreHostForOverflow(location)) {
+            val hostId = MainTabs.hostIds[currentArrangement.moreIndex]
+            bottomNav.post { deliver(location, hostId) }
+            return
+        }
+
+        deliver(location, hostId = null)
+    }
+
+    private fun deliver(location: String, hostId: Int?) {
+        val navigator = delegate.currentNavigator
+        if (navigator != null) {
+            navigator.route(location)
+        } else {
+            pendingRoute = location
+            pendingRouteHostId = hostId
+        }
+    }
+
+    // ------------------------------------------------------------------------
+    // Reset (auth changes) and instance switching
+    // ------------------------------------------------------------------------
+
+    private fun resetTarget(path: String?): String =
+        path?.let { config.url(forPath = it) } ?: config.startUrl
+
+    /**
+     * Full app reset for an auth change. Deterministic and self-contained — it
+     * does NOT depend on the reset page's JavaScript running:
+     *   1. abandon any sign-in still in flight; it is answering a question the
+     *      app no longer has,
+     *   2. clear cached web content, so no page is served from its pre-auth
+     *      state,
+     *   3. reset every live navigator — new Session, new WebView, backstack
+     *      cleared — and route the current one at `target`,
+     *   4. refetch the auth-aware config, which shows or hides the auth-gated
+     *      tabs to match whoever the user is now.
+     */
+    private fun resetApp(target: String) {
+        AuthFlow.cancel()
+        awaitingAuthHandoff = false
+        clearWebContentCache()
+
+        delegate.resetNavigators()
+
+        // resetNavigators rebuilds each host's graph; routing has to wait for
+        // that to land or the visit is swallowed by the rebuild.
+        bottomNav.post { route(target) }
+
+        reloadPathConfiguration()
+    }
+
+    /**
+     * `Everywhere.instance.set(url)`: persist the picked instance as the app's
+     * root, then rebuild onto it. Ignored unless everywhere.yml opts in
+     * (`remote.instances: true`) — for every other app, a page that posts
+     * setInstance must not be able to re-root the shell.
+     *
+     * A reset is not enough here, unlike iOS: every pooled host's
+     * `startLocation` is an absolute URL built against the OLD root and cached
+     * in its Navigator, so the Activity has to go.
+     */
+    private fun setInstance(url: String, to: String?) {
+        if (!config.remoteInstances) return
+        if (!config.setInstanceUrl(url)) return
+
+        rebuildAndRoute(resetTarget(to))
+    }
+
+    /** `Everywhere.instance.clear()`: back to the stamped root — the picker. */
+    private fun clearInstance(to: String?) {
+        if (!config.remoteInstances) return
+
+        config.setInstanceUrl(null)
+        rebuildAndRoute(resetTarget(to))
+    }
+
+    /**
+     * `recreate()` loses every field, so the landing page rides along on the
+     * Intent — which `recreate()` does preserve — and is picked up by the next
+     * `onCreate`.
+     */
+    private fun rebuildAndRoute(target: String) {
+        AuthFlow.cancel()
+        clearWebContentCache()
+        intent.putExtra(EXTRA_ROUTE, target)
+        recreate()
+    }
+
+    /**
+     * Drop web storage so a page isn't served from its pre-auth state. Cookies
+     * are left intact — the server has already invalidated the session on
+     * sign-out, and the fresh cookie has to survive a sign-in.
+     *
+     * Slightly broader than iOS, which drops only the HTTP and offline caches:
+     * Android's per-WebView `clearCache` needs a live WebView, while
+     * `WebStorage` is process-wide. Both err in the same direction — dropping
+     * state that belonged to the previous user.
+     */
+    private fun clearWebContentCache() {
+        WebStorage.getInstance().deleteAllData()
+    }
+
+    // ------------------------------------------------------------------------
+    // Deep links and the sign-in callback
+    // ------------------------------------------------------------------------
+
+    private fun handleIntent(intent: Intent?) {
+        val data: Uri = intent?.data ?: return
+
+        // The Custom Tab handed the token back through the app's own scheme.
+        // Checked first and unconditionally: after a process death there is no
+        // pending flow, but the token is still good and the user still expects
+        // to end up signed in.
+        if (AuthFlow.handleCallback(data)) return
+
+        val url = data.toString()
+        if (!config.handlesUniversalLink(url)) return
+
+        // Re-rooted through the app's own effective root: a link to the
+        // production host must still open the dev server, or the picked
+        // instance, when that is what the app is running against.
+        route(config.url(forPath = config.pathAndQuery(url)))
+    }
+
+    // ------------------------------------------------------------------------
+    // Third-party sign-in
+    // ------------------------------------------------------------------------
+
+    /**
+     * Open a provider sign-in in a Custom Tab. Nothing is loaded in the web
+     * view: the whole point is that this URL never touches it — Google rejects
+     * OAuth from an embedded WebView outright (`disallowed_useragent`), and the
+     * rest degrade badly there.
+     */
+    private fun startAuthFlow(to: String) {
+        // Belt and braces: the control channel already rejects a `to` that
+        // isn't an absolute same-origin path, but this is the one message that
+        // sends the user out to a browser, so it is re-checked here.
+        if (!to.startsWith("/") || to.startsWith("//")) return
+
+        val scheme = config.authScheme ?: return
+        val start = config.authStartUrl(to = to, returnTo = currentPath())
+
+        AuthFlow.start(this, start, scheme) { result ->
+            when (result) {
+                is AuthFlow.Result.Success -> finishAuthFlow(result.token)
+                // They closed the tab; they are still on the page they started
+                // from, which is where they belong.
+                is AuthFlow.Result.Canceled -> Unit
+                is AuthFlow.Result.Failed -> presentAuthFailure(result.message)
+            }
+        }
+    }
+
+    /**
+     * Spend the handoff token in the web view and rebuild around whatever it
+     * signs the app in as.
+     *
+     * The token exists because the Custom Tab's cookie jar is not the WebView's
+     * and is unreachable from here: the gem seals the browser session into a
+     * one-time token, and visiting the handoff endpoint IN THE WEB VIEW is what
+     * puts the resulting Set-Cookie in the jar that matters. Only once that
+     * request has finished can the auth-gated config be refetched — earlier and
+     * the fetch races the cookie.
+     */
+    private fun finishAuthFlow(token: String) {
+        clearWebContentCache()
+        awaitingAuthHandoff = true
+        route(config.authHandoffUrl(token))
+    }
+
+    private fun presentAuthFailure(message: String) {
+        Log.e(TAG, "authFlow failed: $message")
+
+        AlertDialog.Builder(this)
+            .setTitle(R.string.everywhere_auth_failed_title)
+            .setMessage(R.string.everywhere_auth_failed_message)
+            .setPositiveButton(R.string.everywhere_ok, null)
+            .show()
+    }
+
+    /** Where the user is, for the flow to return to if the app doesn't say. */
+    private fun currentPath(): String? =
+        delegate.currentNavigator?.location?.let { config.pathAndQuery(it) }
+
+    // ------------------------------------------------------------------------
+    // Splash
+    // ------------------------------------------------------------------------
+
+    /**
+     * Continues the themed launch background until the first request finishes,
+     * so there is no blank frame while the first page loads over the network.
+     * An app-provided splash (everywhere.yml `native.android.splash`) replaces
+     * the default spinner wholesale.
+     */
+    private fun showSplash() {
+        splashShownAt = System.currentTimeMillis()
+
+        EverywhereExtensions.splashView(this)?.let { view ->
+            splashIsCustom = true
+            splash.removeAllViews()
+            splash.addView(view)
+        }
+
+        // Safety net: never trap the user behind the splash.
+        splash.postDelayed({ dismissSplash() }, SPLASH_TIMEOUT_MS)
+    }
+
+    /**
+     * Called by [WebFragment] when a visit finishes or fails — as close as this
+     * platform gets to iOS's `requestDidFinish`.
+     */
+    fun onWebContentSettled() {
+        dismissSplash()
+
+        // The handoff has landed, so its cookies are in the WebView's jar: now
+        // the tab list can be fetched as the signed-in user.
+        if (awaitingAuthHandoff) {
+            awaitingAuthHandoff = false
+            reloadPathConfiguration()
+        }
+    }
+
+    private fun dismissSplash() {
+        if (!splash.isVisible) return
+
+        // A branded splash that flashes for 50 ms reads as a glitch. Against a
+        // local dev server the first request finishes before the first frame is
+        // presented, so a custom splash is held to its minimum — while the
+        // default spinner is allowed to vanish instantly.
+        if (splashIsCustom) {
+            val remaining = config.splashMinimumDisplay - (System.currentTimeMillis() - splashShownAt)
+            if (remaining > 0) {
+                if (splashDismissScheduled) return
+                splashDismissScheduled = true
+                splash.postDelayed({
+                    splashDismissScheduled = false
+                    dismissSplash()
+                }, remaining)
+                return
+            }
+        }
+
+        splash.animate()
+            .alpha(0f)
+            .setDuration(SPLASH_FADE_MS)
+            .withEndAction { splash.isVisible = false }
+            .start()
+    }
+
+    private companion object {
+        const val TAG = "Everywhere"
+        const val STATE_SELECTED_TAB = "everywhere.selectedTab"
+        const val EXTRA_ROUTE = "everywhere.route"
+        const val EXTRA_LAST_REBUILD = "everywhere.lastRebuild"
+
+        /**
+         * How close two path-change rebuilds have to be before the second is
+         * treated as a loop rather than a legitimate config change. Generous
+         * enough to cover a slow cold start, far below the 5s input-dispatch
+         * timeout that turns a loop into an ANR.
+         */
+        const val REBUILD_DEBOUNCE_MS = 3_000L
+        const val BUNDLED_PATH_CONFIGURATION = "json/path-configuration.json"
+        const val ICON_SIZE_DP = 24
+        const val SPLASH_TIMEOUT_MS = 8_000L
+        const val SPLASH_FADE_MS = 250L
+
+        /** Tint for the More sheet's icons; see MenuComponent for the same pair. */
+        val CONTROL_ATTR = androidx.appcompat.R.attr.colorControlNormal
+        const val ICON_FALLBACK = 0xFF444444.toInt()
+    }
+}