ruby_everywhere 0.8.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1644d6c9be14fdb8ef738eaee6f33225e5916ea401945f7c6c494e8963a2c16
-  data.tar.gz: 03621b7846f16b5621a352e7d4fc42ac38c8859095fc1be1098eef48b081fb0f
+  metadata.gz: d36d2151f58701a6eab470774617b2c81dd99b78caa9829a152017e9840652e9
+  data.tar.gz: 1315f5032b754d7a45418604850cd96f9168ddeb25a7faf24df91608df7ede8c
 SHA512:
-  metadata.gz: 4de42927fa8a53c136e0f9a3015ee1f930199642a26504d198673d0fe3e8cc24e32e9db219d34a170023809db8a9fb20715a6577e13cc6bb030fc9e3a8600b45
-  data.tar.gz: 58da2af357a422bd9dd87badf31175ba71767a5c3364d52f875690fd217a0be15cf1b12296bb195332ebec015ede65b7f486e3c1bf65ff66d5d0cb6831a20e3f
+  metadata.gz: a2a6201f5ecae1781fecca6750a8952250d78e22e8b45c224c696fab8717a4ff2bb173b591d1e8724d69c695633358a8fb5320e74e2e849fcab738d5f2870b68
+  data.tar.gz: acaed9ef6364a807dcdf85378e33bac32f99e5309be5e9fcc404c257f6c2dc348f5f61b5e2482582a4bfca56495677da97dcf9de51f308ef9522b8919854185f

data/lib/everywhere/builders/android.rb

@@ -287,10 +287,49 @@ module Everywhere
         write_drawables(work)
         write_icon_font(work)
         write_manifest(work)
+        write_network_security(work)
         write_extensions(work)
         write_native_packages(work)
       end
 
+      # The template's baseline forbids cleartext everywhere (debug overlays
+      # loopback + .local only — see the two res/xml/network_security_config.xml
+      # files and their comments). An instance app (`remote.instances: true`)
+      # exists to load OTHER apps, and `every preview --lan` serves those as
+      # plain http on whatever LAN address the laptop has that day — an address
+      # no config written at build time can enumerate, and Android's
+      # network-security-config has no CIDR syntax to scope a private-range
+      # exception the way iOS's NSAllowsLocalNetworking does. So instance apps
+      # get cleartext permitted wholesale, in both build types (the debug
+      # overlay REPLACES main's resource, so leaving it standing would make
+      # debug builds stricter than release). The shell's own traffic to
+      # remote.url stays https; the alternative is a picker that cannot open
+      # what it picked.
+      #
+      # Written only when instances is on: stage() re-copies the template over
+      # the work dir every build, so switching it off restores the strict
+      # default without a writer for that side of the toggle.
+      def write_network_security(work)
+        return unless @config.remote_instances?
+
+        UI.step("allowing cleartext http #{UI.dim("(remote.instances: previewed apps live on LAN addresses)")}")
+        xml = <<~XML
+          <?xml version="1.0" encoding="utf-8"?>
+          <!-- Written by `every build` because config/everywhere.yml sets
+               remote.instances: true — previewed apps arrive as plain http on
+               LAN addresses that cannot be enumerated at build time. Do not
+               edit; the template's strict default returns if instances is
+               turned off. -->
+          <network-security-config>
+              <base-config cleartextTrafficPermitted="true" />
+          </network-security-config>
+        XML
+        [File.join(work, "app", "src", "main", "res", "xml", "network_security_config.xml"),
+         File.join(work, "app", "src", "debug", "res", "xml", "network_security_config.xml")].each do |path|
+          File.write(path, xml)
+        end
+      end
+
       # --- identity -------------------------------------------------------------
 
       # app/build.gradle.kts reads these four values, so identity is stamped

data/lib/everywhere/config/app.rb

@@ -114,6 +114,18 @@ module Everywhere
         @data.dig("remote", "instances") == true
       end
 
+      # Whether the shell offers its built-in escape hatch while re-rooted on
+      # an instance: a "back to start" toolbar action on screens where the tab
+      # bar (and the injected leave tab it carries) is hidden — every
+      # modal-context screen, and an instance serving no tabs at all. On by
+      # default because stranding is inherent to the picker pattern (a
+      # previewed app's whole signed-out surface can be modal); an instance
+      # app that wants no shell chrome opts out with
+      # `remote: { instances_escape: false }`.
+      def remote_instances_escape?
+        remote_instances? && @data.dig("remote", "instances_escape") != false
+      end
+
       def tint_color
         normalize_color(appearance["tint_color"])
       end

data/lib/everywhere/config/mobile.rb

@@ -182,12 +182,24 @@ module Everywhere
       # `uri` pointing at a Fragment this build doesn't contain resolves to
       # nothing and the visit dead-ends. An explicit `uri:` always wins — that's
       # the escape hatch for a screen whose annotation says something else.
+      #
+      # `fallback_uri` rides along for the shell that ISN'T this app's own
+      # build: a Jump-style instance shell fetches this same document live, and
+      # the derived uri names a Fragment compiled into the app's build, not the
+      # picker's. Hotwire falls back per rule when the primary uri resolves to
+      # no registered destination, and every gem-built shell registers the
+      # missing-screen placeholder at this address — so the previewing shell
+      # says "this screen is native" instead of spinning forever, while the
+      # app's own build never consults the fallback at all.
+      MISSING_SCREEN_URI = "hotwire://fragment/everywhere-missing"
+
       def android_screen_properties(properties)
         id = properties["view_controller"]
         return properties if id.nil? || properties.key?("uri")
         return properties unless native_android_screens.key?(id.to_s)
 
-        properties.merge("uri" => "hotwire://fragment/#{id}")
+        fallback = properties.key?("fallback_uri") ? {} : { "fallback_uri" => MISSING_SCREEN_URI }
+        properties.merge("uri" => "hotwire://fragment/#{id}", **fallback)
       end
 
       # The full path-configuration document for one mobile platform — rules plus

data/lib/everywhere/config/shell.rb

@@ -31,6 +31,7 @@ module Everywhere
           "mode" => mode,
           "remote_url" => remote_url,
           "remote_instances" => (true if remote_instances?),
+          "instances_escape" => (true if remote_instances_escape?),
           "entry_path" => entry_path,
           "tint_color" => tint_color,
           "background_color" => background_color,

data/lib/everywhere/version.rb

@@ -3,7 +3,7 @@
 require "json"
 
 module Everywhere
-  VERSION = "0.8.0"
+  VERSION = "0.9.1"
 
   # Version of the @rubyeverywhere/bridge JS this gem ships. bridge/ in the
   # gem IS the npm package (served to Rails apps by Everywhere::Engine,

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

@@ -2,6 +2,8 @@ package com.rubyeverywhere.shell
 
 import android.app.Application
 import android.webkit.CookieManager
+import android.webkit.WebSettings
+import android.widget.Toast
 import androidx.core.net.toUri
 import com.rubyeverywhere.shell.bridge.BiometricsComponent
 import com.rubyeverywhere.shell.bridge.HapticsComponent
@@ -20,6 +22,7 @@ import dev.hotwire.core.turbo.visit.VisitProposal
 import dev.hotwire.core.turbo.webview.HotwireWebView
 import dev.hotwire.navigation.activities.HotwireActivity
 import dev.hotwire.navigation.config.defaultFragmentDestination
+import dev.hotwire.navigation.destinations.HotwireDestinationDeepLink
 import dev.hotwire.navigation.config.registerBridgeComponents
 import dev.hotwire.navigation.config.registerFragmentDestinations
 import dev.hotwire.navigation.config.registerRouteDecisionHandlers
@@ -55,12 +58,22 @@ class EverywhereApplication : Application() {
 
         Hotwire.defaultFragmentDestination = WebFragment::class
 
-        Hotwire.registerFragmentDestinations(
+        val fragmentDestinations = listOf(
             WebFragment::class,
             WebBottomSheetFragment::class,
-            // App-provided native screens (everywhere.yml native.android.screens).
-            *EverywhereExtensions.fragmentDestinations.toTypedArray()
-        )
+            // Where a rule's fallback_uri lands when its primary uri names a
+            // Fragment this build doesn't contain (previewing another app).
+            MissingExtensionFragment::class
+        ) + EverywhereExtensions.fragmentDestinations // everywhere.yml native.android.screens
+        Hotwire.registerFragmentDestinations(*fragmentDestinations.toTypedArray())
+
+        // Every uri those destinations answer to, read from the same
+        // annotation Hotwire itself matches against — handed to the
+        // missing-screen guard below so it can tell a resolvable rule from
+        // one that would go nowhere.
+        val registeredUris = fragmentDestinations
+            .mapNotNull { it.java.getAnnotation(HotwireDestinationDeepLink::class.java)?.uri }
+            .toSet()
 
         Hotwire.registerBridgeComponents(
             BridgeComponentFactory("everywhere--notification", ::NotificationComponent),
@@ -78,6 +91,7 @@ class EverywhereApplication : Application() {
         Hotwire.registerRouteDecisionHandlers(
             ResetRouteDecisionHandler(),
             AuthFlowRouteDecisionHandler(),
+            MissingScreenRouteDecisionHandler(registeredUris),
             AppNavigationRouteDecisionHandler(),
             BrowserTabRouteDecisionHandler(),
             SystemNavigationRouteDecisionHandler()
@@ -99,6 +113,16 @@ class EverywhereApplication : Application() {
         Hotwire.config.makeCustomWebView = { context ->
             HotwireWebView(context, null).also { webView ->
                 WebControlChannel.install(webView, config.webConfigJson)
+                // Instance apps pair with LAN-hosted previews: the picker page
+                // is https but the app it probes is plain http, which WebView
+                // blocks as mixed content — and then the picker reports a live
+                // preview as "not answering". Scoped to remote.instances so
+                // ordinary apps keep the strict default. The main-frame http
+                // load itself is governed by network_security_config.xml,
+                // which `every build` opens up under the same flag.
+                if (config.remoteInstances) {
+                    webView.settings.mixedContentMode = WebSettings.MIXED_CONTENT_ALWAYS_ALLOW
+                }
             }
         }
     }
@@ -145,7 +169,18 @@ private class ResetRouteDecisionHandler : Router.RouteDecisionHandler {
         activity: HotwireActivity
     ): Router.Decision {
         val to = proposal.location.toUri().getQueryParameter("to")
-        EverywhereEvents.emit(EverywhereEvents.Event.ResetApp(to))
+        // Directly, not through EverywhereEvents: the event collector is a
+        // coroutine that can lose the race to the tab-path watcher when a
+        // sign-in changes the auth-gated tabs, and the watcher's plain
+        // recreate() restores the half-dismissed pre-auth back stack — a
+        // framework crash. Calling in synchronously puts the reset (and its
+        // pendingResetTarget) in place before the config refresh can land.
+        val main = activity as? MainActivity
+        if (main != null) {
+            main.resetAppNow(to)
+        } else {
+            EverywhereEvents.emit(EverywhereEvents.Event.ResetApp(to))
+        }
         return Router.Decision.CANCEL
     }
 
@@ -154,6 +189,43 @@ private class ResetRouteDecisionHandler : Router.RouteDecisionHandler {
     }
 }
 
+/**
+ * The last line of defence for a native-screen rule this build can't serve.
+ *
+ * A previewed app on a current gem serves `fallback_uri` pointing at
+ * [MissingExtensionFragment], and the visit lands there — this handler never
+ * matches. An app on an older gem serves only `uri: hotwire://fragment/<id>`,
+ * and Hotwire's answer to a uri no registered destination claims is to do
+ * nothing at all — which reads as a spinner that never ends. Refuse the visit
+ * loudly instead: a toast naming the screen, and the user stays on the page
+ * they tapped from.
+ */
+private class MissingScreenRouteDecisionHandler(
+    private val registeredUris: Set<String>
+) : Router.RouteDecisionHandler {
+    override val name = "everywhere-missing-screen"
+
+    override fun matches(proposal: VisitProposal, configuration: NavigatorConfiguration): Boolean {
+        val uri = proposal.properties["uri"]?.toString() ?: return false
+        val fallback = proposal.properties["fallback_uri"]?.toString()
+        return uri !in registeredUris && (fallback == null || fallback !in registeredUris)
+    }
+
+    override fun handle(
+        proposal: VisitProposal,
+        configuration: NavigatorConfiguration,
+        activity: HotwireActivity
+    ): Router.Decision {
+        val identifier = proposal.properties["view_controller"]?.toString() ?: "native"
+        Toast.makeText(
+            activity,
+            activity.getString(R.string.everywhere_missing_screen_toast, identifier),
+            Toast.LENGTH_LONG
+        ).show()
+        return Router.Decision.CANCEL
+    }
+}
+
 /**
  * A provider sign-in: hand it to a Custom Tab instead of loading it in the web
  * view. Cancelling leaves the user on the page they tapped from, which is where

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

@@ -114,6 +114,10 @@ class EverywhereConfig private constructor(
     val version: String? = json.string("version")
     val entryPath: String? = json.string("entry_path")
     val remoteInstances: Boolean = json["remote_instances"]?.jsonPrimitive?.booleanOrNull == true
+
+    /** `remote.instances_escape` — the built-in "back to start" toolbar action
+     *  offered while re-rooted, on screens whose tab bar is hidden. */
+    val instancesEscape: Boolean = json["instances_escape"]?.jsonPrimitive?.booleanOrNull == true
     val permissions: List<String> =
         json["permissions"]?.jsonArray?.mapNotNull { it.jsonPrimitive.contentOrNull } ?: emptyList()
     val universalLinkHosts: List<String> =
@@ -189,6 +193,27 @@ class EverywhereConfig private constructor(
             return if (path.isNullOrEmpty() || path == "/") rootUrl else url(forPath = path)
         }
 
+    /**
+     * Every origin the shell's own pages can be served from: the stamped
+     * root, the dev override, and a picked instance. The control channel is
+     * offered to all of them, not just the current [rootUrl] — while rooted
+     * on an instance, the picker's pages still come from the stamped origin,
+     * and without the channel there they could switch in but never switch
+     * again (`Everywhere.instance.*` would fall back to a plain navigation).
+     */
+    val trustedRootOrigins: Set<String>
+        get() = listOfNotNull(stampedRemoteUrl, devUrl, instanceUrl)
+            .mapNotNull(::originOf)
+            .toSet()
+
+    private fun originOf(url: String): String? {
+        val uri = url.toUri()
+        val scheme = uri.scheme ?: return null
+        val host = uri.host ?: return null
+        val port = if (uri.port > 0) ":${uri.port}" else ""
+        return "$scheme://$host$port"
+    }
+
     /**
      * The server half of the path configuration (rules + settings.tabs),
      * generated from everywhere.yml by the gem's MobileConfigEndpoint — so tab

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

@@ -130,6 +130,22 @@ class MainActivity : HotwireActivity() {
     /** The open More sheet, so a second tap doesn't stack a second one. */
     private var moreSheet: BottomSheetDialog? = null
 
+    /**
+     * Single-flight guard for `recreate()`: a reset and the tab-path watcher
+     * can both want a rebuild within the same beat (a sign-in changes the
+     * auth-gated tabs moments after the reset route fires), and two stacked
+     * relaunches with navigation mid-teardown is a framework crash. Dies with
+     * the Activity, which is exactly the right lifetime.
+     */
+    private var rebuildScheduled = false
+
+    /**
+     * Where the in-flight reset is headed, so a tab-path change caused BY that
+     * reset rebuilds fresh (EXTRA_ROUTE, no state restoration) instead of
+     * restoring the pre-auth back stack. Null when no reset is in flight.
+     */
+    private var pendingResetTarget: String? = null
+
     // ------------------------------------------------------------------------
     // Lifecycle
     // ------------------------------------------------------------------------
@@ -140,7 +156,16 @@ class MainActivity : HotwireActivity() {
         // Swap to the real theme before the content view inflates.
         setTheme(R.style.Theme_Everywhere)
         enableEdgeToEdge()
-        super.onCreate(savedInstanceState)
+
+        // A rebuild ([rebuildAndRoute]: reset, sign-in/out, instance switch)
+        // arrives with EXTRA_ROUTE on the Intent and must start from scratch:
+        // handing the saved state to super restores every navigator's back
+        // stack, climbing the page the user just left back on top of the new
+        // root. Dropped here, the recreate behaves like a fresh launch — while
+        // a real config change or process death (no EXTRA_ROUTE) restores
+        // normally.
+        val state = if (intent.hasExtra(EXTRA_ROUTE)) null else savedInstanceState
+        super.onCreate(state)
 
         setContentView(R.layout.activity_main)
         findViewById<View>(R.id.root).applyDefaultImeWindowInsets()
@@ -148,11 +173,18 @@ class MainActivity : HotwireActivity() {
         splash = findViewById(R.id.splash)
         showSplash()
 
-        initializeTabs(savedInstanceState?.getInt(STATE_SELECTED_TAB) ?: 0)
+        initializeTabs(state?.getInt(STATE_SELECTED_TAB) ?: 0)
 
         observeEvents()
         observePathConfiguration()
 
+        // A rebuild chain in progress (see rebuildAndRoute): the config that
+        // motivated it may land after this Activity built its tabs, and the
+        // paths watcher needs to know to rebuild fresh again, aimed at the
+        // same landing page. Cleared by applyPathConfiguration once a config
+        // pass finds the tabs already correct.
+        pendingResetTarget = intent.getStringExtra(EXTRA_RESET_TARGET)
+
         // Survives `recreate()` — the Intent does, fields don't. See
         // [rebuildAndRoute].
         intent.getStringExtra(EXTRA_ROUTE)?.let {
@@ -203,6 +235,13 @@ class MainActivity : HotwireActivity() {
 
     override fun navigatorConfigurations(): List<NavigatorConfiguration> = pooledConfigurations
 
+    /**
+     * Whether a tab bar is on screen at all — [WebFragment] uses this to
+     * decide if the instance-escape toolbar action is needed. Modal screens
+     * hide the bar regardless; the fragment checks its own context for that.
+     */
+    val hasTabBar: Boolean get() = currentArrangement.slots.isNotEmpty()
+
     /**
      * A host finished building its start destination. Used to flush a route
      * captured before any navigator existed — at `onCreate` there is nothing to
@@ -220,7 +259,14 @@ class MainActivity : HotwireActivity() {
 
         pendingRoute = null
         pendingRouteHostId = null
-        navigator.route(route)
+        // Post, don't call: this callback fires from onAttachFragment while
+        // the host's start fragment is still mid-transaction — no view, no
+        // web delegate — and routing into it synchronously crashes Hotwire
+        // ("lateinit property webDelegate has not been initialized"). One
+        // trip through the main queue lets the transaction finish first.
+        window.decorView.post {
+            if (!isFinishing && !isDestroyed) navigator.route(route)
+        }
     }
 
     // ------------------------------------------------------------------------
@@ -380,19 +426,32 @@ class MainActivity : HotwireActivity() {
      * handling selection would make More a one-shot.
      */
     private fun installTabListeners(arrangement: MainTabs.Arrangement) {
-        if (!arrangement.hasMore) return
+        val hasLeaveSlot = arrangement.slots.any { isLeaveTab(it.entry?.path) }
+        if (!arrangement.hasMore && !hasLeaveSlot) 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
+            when {
+                // The Jump leave tab is a native action, exactly as on iOS
+                // (EverywhereTabBarController): the page behind it is a
+                // gem-served Turbo-less fallback, so selecting its host could
+                // only end at the error view. The tap clears the picked
+                // instance directly and never becomes a selection.
+                isLeaveTab(arrangement.entryAt(index)?.path) -> {
+                    leaveInstance()
+                    false
+                }
+                // 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.
+                arrangement.isMoreIndex(index) && !selectingMoreForRoute -> {
+                    showMoreSheet(arrangement)
+                    false
+                }
+                else -> {
+                    switchToSlot(index)
+                    true
+                }
             }
         }
 
@@ -408,6 +467,19 @@ class MainActivity : HotwireActivity() {
         }
     }
 
+    /**
+     * The injected "leave preview" tab (a Jump instance's way home), matched
+     * by its gem-reserved path. Only meaningful for instance apps — for
+     * everyone else no such tab is ever injected, and the guard keeps an
+     * unlucky app path from being swallowed.
+     */
+    private fun isLeaveTab(path: String?): Boolean =
+        config.remoteInstances && path == JUMP_LEAVE_PATH
+
+    private fun leaveInstance() {
+        EverywhereEvents.emit(EverywhereEvents.Event.ClearInstance(null))
+    }
+
     /**
      * Bring a slot's host forward — upstream `HotwireBottomNavigationController`'s
      * private `switchTab`, which taking over the item-selected listener costs us.
@@ -466,7 +538,11 @@ class MainActivity : HotwireActivity() {
 
             row.setOnClickListener {
                 dialog.dismiss()
-                route(config.url(forPath = entry.path))
+                // The leave row is the same native action as a leave SLOT —
+                // see installTabListeners; routing it would load the
+                // Turbo-less fallback page and end at the error view.
+                if (isLeaveTab(entry.path)) leaveInstance()
+                else route(config.url(forPath = entry.path))
             }
             list.addView(row)
         }
@@ -534,16 +610,27 @@ class MainActivity : HotwireActivity() {
         lifecycleScope.launch {
             repeatOnLifecycle(Lifecycle.State.STARTED) {
                 Hotwire.config.pathConfiguration.loadState.collect { state ->
-                    if (state is PathConfigurationLoadState.Loaded) applyPathConfiguration()
+                    if (state is PathConfigurationLoadState.Loaded) {
+                        // Only a fresh server answer can settle a rebuild
+                        // chain: bundled/cached passes reflect the OLD root
+                        // and match trivially right after a re-root, before
+                        // the config that motivated the rebuild has landed.
+                        applyPathConfiguration(
+                            fresh = state is PathConfigurationLoadState.Loaded.RemoteLoaded
+                        )
+                    }
                 }
             }
         }
     }
 
-    private fun applyPathConfiguration() {
+    private fun applyPathConfiguration(fresh: Boolean = false) {
         val entries = MainTabs.entries()
         val fingerprint = MainTabs.fingerprint(entries)
-        if (fingerprint == loadedFingerprint) return
+        if (fingerprint == loadedFingerprint) {
+            if (fresh) settleRebuildChain()
+            return
+        }
 
         val arrangement = MainTabs.arrange(entries, moreTitle)
 
@@ -577,14 +664,38 @@ class MainActivity : HotwireActivity() {
                 return
             }
 
-            Log.d(TAG, "tab paths changed — rebuilding the activity")
+            // ALWAYS the fresh-start rebuild, never a state-restoring
+            // recreate(): the restored back stacks belong to hosts whose
+            // start locations just changed, and restoring them mid-flight —
+            // during a reset's teardown, an instance switch's cold boot —
+            // is every framework crash this file has collected ("No
+            // configuration found for NavigatorHost", empty-URL proposals,
+            // clearAll pop-loops). iOS rebuilds its navigators fresh on a
+            // tab change too. Land where the in-flight reset was headed, or
+            // where the user is standing, or at the start.
+            val target = pendingResetTarget
+                ?: delegate.currentNavigator?.location
+                ?: config.startUrl
+            Log.d(TAG, "tab paths changed — fresh rebuild to $target")
             intent.putExtra(EXTRA_LAST_REBUILD, now)
-            recreate()
+            rebuildAndRoute(target)
             return
         }
 
         loadedFingerprint = fingerprint
         applyTabs(arrangement, safeSelectedIndex(arrangement))
+        if (fresh) settleRebuildChain()
+    }
+
+    /**
+     * The tabs now match the loaded config with no rebuild needed — whatever
+     * rebuild chain was in flight (a reset, an instance switch) has landed.
+     * Clearing the mark stops a LATER unrelated tab-path change from being
+     * misread as part of it and redirected to a stale landing page.
+     */
+    private fun settleRebuildChain() {
+        pendingResetTarget = null
+        intent.removeExtra(EXTRA_RESET_TARGET)
     }
 
     /**
@@ -727,28 +838,29 @@ class MainActivity : HotwireActivity() {
 
     /**
      * 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.
+     * does NOT depend on the reset page's JavaScript running: refetch the
+     * auth-aware config (shows or hides the auth-gated tabs to match whoever
+     * the user is now) and rebuild the Activity fresh, landing on `target`.
+     * rebuildAndRoute abandons any in-flight sign-in and clears cached web
+     * content on the way.
      */
     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) }
 
+        // NOT delegate.resetNavigators() + route: the in-place reset detaches
+        // every WebView asynchronously, and each detach continuation ends in
+        // Hotwire's clearAll pop-loop — which, once the recreate that follows
+        // has made the FragmentManager save its state, spins forever on
+        // ignored popBackStack() calls and ANRs the app. A fresh Activity IS
+        // the reset (new sessions, new WebViews, empty back stacks), with no
+        // async teardown left behind to race it.
+        //
+        // The refetch starts first so the auth-aware tab set has a head start;
+        // if it still lands after the new Activity built its tabs, the
+        // EXTRA_RESET_TARGET chain (see rebuildAndRoute) finishes the job with
+        // a second fresh rebuild.
         reloadPathConfiguration()
+        rebuildAndRoute(target)
     }
 
     /**
@@ -777,17 +889,54 @@ class MainActivity : HotwireActivity() {
     }
 
     /**
-     * `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`.
+     * `recreate()` for an in-place rebuild — a CLEAR_TASK relaunch tears the
+     * task down first, which plays as the app closing and cold-starting on
+     * every reset (sign-in, sign-out, instance switch). recreate() keeps the
+     * window; the landing page rides along on the Intent, which recreate()
+     * preserves while fields are lost.
+     *
+     * The saved instance state, however, must NOT come back: it carries every
+     * navigator's back stack, and restoring it climbs the page the user just
+     * left (Jump's connect screen, a pre-sign-in page) right back on top of
+     * the new root. `onCreate` treats the presence of [EXTRA_ROUTE] as the
+     * fresh-start flag and drops the state — see the top of [onCreate].
      */
     private fun rebuildAndRoute(target: String) {
         AuthFlow.cancel()
         clearWebContentCache()
+        // The extras go on unconditionally: if a relaunch is already scheduled
+        // (the tab-path watcher got there first), it reuses this same Intent,
+        // and EXTRA_ROUTE upgrades it from a state-restoring recreate to the
+        // fresh-start rebuild a reset needs.
+        //
+        // EXTRA_RESET_TARGET marks the whole chain: the next Activity boots
+        // its tabs from whatever config is loaded NOW, and the refreshed
+        // config (an instance's tabs, the post-auth tab set) usually lands
+        // moments later. When that changes the tab paths, the watcher must
+        // rebuild fresh again, aimed here — never restore. The mark is
+        // cleared when a config pass finds nothing left to rebuild.
+        pendingResetTarget = target
         intent.putExtra(EXTRA_ROUTE, target)
+        intent.putExtra(EXTRA_RESET_TARGET, target)
+        if (rebuildScheduled) return
+        rebuildScheduled = true
         recreate()
     }
 
+    /**
+     * The reset route (`/everywhere/reset` after a sign-in or sign-out) calls
+     * this DIRECTLY from its route decision handler rather than through
+     * [EverywhereEvents]: a sign-in changes the auth-gated tab paths moments
+     * later, and if the event collector loses the race to the tab-path
+     * watcher's `recreate()`, the app restores the half-dismissed pre-sign-in
+     * back stack — mid-flight WebView teardown included — and crashes inside
+     * the framework. Scheduling the fresh-start relaunch synchronously, before
+     * the config refresh can land, makes the ordering deterministic.
+     */
+    fun resetAppNow(to: String?) {
+        resetApp(resetTarget(to))
+    }
+
     /**
      * 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
@@ -954,8 +1103,13 @@ class MainActivity : HotwireActivity() {
         const val TAG = "Everywhere"
         const val STATE_SELECTED_TAB = "everywhere.selectedTab"
         const val EXTRA_ROUTE = "everywhere.route"
+        const val EXTRA_RESET_TARGET = "everywhere.resetTarget"
         const val EXTRA_LAST_REBUILD = "everywhere.lastRebuild"
 
+        /** The injected leave tab's path — same constant iOS keeps on
+         *  EverywhereTabBarController.jumpLeavePath. */
+        const val JUMP_LEAVE_PATH = "/everywhere/jump/leave"
+
         /**
          * How close two path-change rebuilds have to be before the second is
          * treated as a loop rather than a legitimate config change. Generous

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

@@ -0,0 +1,105 @@
+package com.rubyeverywhere.shell
+
+import android.graphics.drawable.Drawable
+import android.os.Bundle
+import android.util.TypedValue
+import android.view.Gravity
+import android.view.LayoutInflater
+import android.view.View
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import android.widget.ImageView
+import android.widget.LinearLayout
+import android.widget.TextView
+import androidx.appcompat.widget.Toolbar
+import androidx.core.graphics.drawable.DrawableCompat
+import com.google.android.material.appbar.AppBarLayout
+import dev.hotwire.navigation.destinations.HotwireDestinationDeepLink
+import dev.hotwire.navigation.fragments.HotwireFragment
+
+/**
+ * The per-rule fallback destination for native screens this build doesn't
+ * contain — the Android half of iOS's `MissingExtensionScreen`.
+ *
+ * The gem writes `fallback_uri: hotwire://fragment/everywhere-missing` next to
+ * every derived screen `uri` (see the gem's Config::Mobile), so when a
+ * Jump-style shell previews an app whose rules name Fragments compiled into
+ * THAT app's build, the visit lands here and says so — instead of Hotwire
+ * finding no destination and leaving the user on a spinner forever. An app's
+ * own build resolves the primary uri and never consults the fallback.
+ */
+@HotwireDestinationDeepLink(uri = "hotwire://fragment/everywhere-missing")
+class MissingExtensionFragment : HotwireFragment() {
+    private lateinit var toolbar: Toolbar
+
+    override fun onCreateView(
+        inflater: LayoutInflater,
+        container: ViewGroup?,
+        savedInstanceState: Bundle?
+    ): View {
+        val context = requireContext()
+        // The rule that routed here still carries the screen's identifier.
+        val identifier = pathProperties["view_controller"]?.toString() ?: "native"
+
+        toolbar = Toolbar(context).apply {
+            title = getString(R.string.everywhere_missing_screen_nav_title)
+        }
+        val appBar = AppBarLayout(context).apply {
+            fitsSystemWindows = true
+            addView(toolbar, ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT)
+        }
+
+        val secondary = TypedValue().let {
+            context.theme.resolveAttribute(android.R.attr.textColorSecondary, it, true)
+            requireNotNull(context.getColorStateList(it.resourceId)).defaultColor
+        }
+
+        val icon = ImageView(context).apply {
+            setImageDrawable(tinted(IconFont.drawable(context, "extension", dp(44)), secondary))
+        }
+        val title = TextView(context).apply {
+            text = getString(R.string.everywhere_missing_screen_title)
+            textSize = 20f
+            setTypeface(typeface, android.graphics.Typeface.BOLD)
+            gravity = Gravity.CENTER
+        }
+        val body = TextView(context).apply {
+            text = getString(R.string.everywhere_missing_screen_body, identifier)
+            textSize = 15f
+            setTextColor(secondary)
+            gravity = Gravity.CENTER
+        }
+
+        val column = LinearLayout(context).apply {
+            orientation = LinearLayout.VERTICAL
+            gravity = Gravity.CENTER_HORIZONTAL
+            setPadding(dp(32), 0, dp(32), 0)
+            addView(icon)
+            addView(title, spaced(dp(14)))
+            addView(body, spaced(dp(14)))
+        }
+        val content = FrameLayout(context).apply {
+            addView(column, FrameLayout.LayoutParams(
+                ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT,
+                Gravity.CENTER
+            ))
+        }
+
+        return LinearLayout(context).apply {
+            orientation = LinearLayout.VERTICAL
+            addView(appBar, ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT)
+            addView(content, LinearLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, 0, 1f))
+        }
+    }
+
+    override fun toolbarForNavigation(): Toolbar = toolbar
+
+    private fun tinted(drawable: Drawable, color: Int): Drawable =
+        DrawableCompat.wrap(drawable).mutate().also { DrawableCompat.setTint(it, color) }
+
+    private fun spaced(marginTop: Int) = LinearLayout.LayoutParams(
+        ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT
+    ).apply { topMargin = marginTop }
+
+    private fun dp(value: Int): Int = (value * resources.displayMetrics.density).toInt()
+}

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

@@ -1,5 +1,12 @@
 package com.rubyeverywhere.shell
 
+import android.os.Bundle
+import android.view.Menu
+import android.view.MenuItem
+import android.view.View
+import android.widget.TextView
+import androidx.core.graphics.drawable.DrawableCompat
+import androidx.core.view.isVisible
 import dev.hotwire.core.turbo.errors.VisitError
 import dev.hotwire.navigation.destinations.HotwireDestinationDeepLink
 import dev.hotwire.navigation.fragments.HotwireWebFragment
@@ -8,14 +15,63 @@ import dev.hotwire.navigation.fragments.HotwireWebFragment
  * The default destination for every web visit.
  *
  * Deliberately thin — the framework's own fragment already does the work. Its
- * one job is telling [MainActivity] when there is content on screen, which is
- * how the splash comes down. Android has no `NavigatorDelegate.requestDidFinish`
- * the way iOS does; the visit callbacks on the fragment are where that
- * information surfaces.
+ * jobs are telling [MainActivity] when there is content on screen (how the
+ * splash comes down — Android has no `NavigatorDelegate.requestDidFinish` the
+ * way iOS does; the visit callbacks on the fragment are where that information
+ * surfaces) and swapping the library's button-less error view for one the user
+ * can act on.
  */
 @HotwireDestinationDeepLink(uri = "hotwire://fragment/web")
 open class WebFragment : HotwireWebFragment() {
 
+    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
+        super.onViewCreated(view, savedInstanceState)
+        addLeavePreviewAction()
+    }
+
+    /**
+     * While a picked instance is active, screens whose TAB BAR is hidden get
+     * the way home in their toolbar instead. The injected leave TAB alone is
+     * not enough: Hotwire hides the tab bar on modal-context screens, and a
+     * previewed app's whole signed-out surface can be modal (`/session/new`
+     * under a `/new$` rule) — leaving no escape at all once a sign-out lands
+     * there. Where the bar IS showing, its Jump tab already covers this, so
+     * the toolbar stays the app's own. `remote.instances_escape: false`
+     * turns the whole affordance off.
+     */
+    private fun addLeavePreviewAction() {
+        val config = EverywhereConfig.shared
+        if (!config.instancesEscape || config.instanceUrl == null) return
+
+        val modal = pathProperties["context"]?.toString() == "modal"
+        val barAvailable = (activity as? MainActivity)?.hasTabBar == true
+        if (!modal && barAvailable) return
+
+        val toolbar = toolbarForNavigation() ?: return
+        if (toolbar.menu.findItem(MENU_LEAVE_PREVIEW) != null) return
+
+        val sizePx = (22 * resources.displayMetrics.density).toInt()
+        val tint = requireContext().let { context ->
+            val value = android.util.TypedValue()
+            context.theme.resolveAttribute(
+                com.google.android.material.R.attr.colorOnSurface, value, true
+            )
+            context.getColor(value.resourceId)
+        }
+        toolbar.menu.add(
+            Menu.NONE, MENU_LEAVE_PREVIEW, Menu.NONE, R.string.everywhere_error_leave
+        ).apply {
+            icon = DrawableCompat.wrap(
+                IconFont.drawable(requireContext(), "u_turn_left", sizePx)
+            ).mutate().also { DrawableCompat.setTint(it, tint) }
+            setShowAsAction(MenuItem.SHOW_AS_ACTION_ALWAYS)
+            setOnMenuItemClickListener {
+                EverywhereEvents.emit(EverywhereEvents.Event.ClearInstance(null))
+                true
+            }
+        }
+    }
+
     override fun onVisitRequestFinished(location: String) {
         super.onVisitRequestFinished(location)
         settled()
@@ -30,7 +86,35 @@ open class WebFragment : HotwireWebFragment() {
         settled()
     }
 
+    /**
+     * The library's error view is a message with no controls — its only retry
+     * is pull-to-refresh, invisible exactly when the user is staring at a dead
+     * page. Ours adds an explicit retry, and — inside a picked instance, where
+     * retrying can only knock on the same dead host — the way home: clear the
+     * instance and re-root onto the app's own start page, exactly what the
+     * page's own `Everywhere.instance.clear()` would do if it could load.
+     */
+    override fun createErrorView(error: VisitError): View {
+        val view = layoutInflater.inflate(R.layout.everywhere_error, null)
+        view.findViewById<TextView>(R.id.everywhere_error_description).text = error.description()
+        view.findViewById<View>(R.id.everywhere_error_retry).setOnClickListener {
+            refresh(displayProgress = true)
+        }
+        view.findViewById<View>(R.id.everywhere_error_leave).apply {
+            isVisible = EverywhereConfig.shared.instanceUrl != null
+            setOnClickListener {
+                EverywhereEvents.emit(EverywhereEvents.Event.ClearInstance(null))
+            }
+        }
+        return view
+    }
+
     private fun settled() {
         (activity as? MainActivity)?.onWebContentSettled()
     }
+
+    private companion object {
+        /** Stable menu id so re-created toolbars don't stack duplicates. */
+        const val MENU_LEAVE_PREVIEW = 0x00EE01
+    }
 }

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

@@ -189,16 +189,12 @@ class WebControlChannel : WebViewCompat.WebMessageListener {
         }
 
         /**
-         * The app's own origin, derived from the *effective* root — so a dev
-         * build against 127.0.0.1 and a picked instance both work without a
-         * second list to keep in sync.
+         * Every origin the shell's own pages come from — stamped root, dev
+         * override, picked instance (EverywhereConfig.trustedRootOrigins).
+         * All of them, not just the effective root: while the shell is rooted
+         * on an instance, the picker's own pages are still served from the
+         * stamped origin, and they need the channel to switch or leave.
          */
-        private fun originRules(): Set<String> {
-            val uri = EverywhereConfig.shared.rootUrl.toUri()
-            val scheme = uri.scheme ?: return emptySet()
-            val host = uri.host ?: return emptySet()
-            val port = if (uri.port > 0) ":${uri.port}" else ""
-            return setOf("$scheme://$host$port")
-        }
+        private fun originRules(): Set<String> = EverywhereConfig.shared.trustedRootOrigins
     }
 }

data/support/mobile/android/app/src/main/res/layout/everywhere_error.xml

@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  FROZEN. The failed-visit screen WebFragment.createErrorView inflates in
+  place of the library's hotwire_error.xml, which has no controls at all —
+  its only retry is pull-to-refresh, invisible exactly when the user is
+  staring at a dead page. Same typography as the library's version, plus an
+  explicit retry button and an escape hatch for picked instances (shown by
+  WebFragment only when an instance override is active).
+-->
+<FrameLayout
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:background="?android:colorBackground">
+
+    <LinearLayout
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:layout_gravity="center"
+        android:orientation="vertical"
+        android:gravity="center_horizontal"
+        android:paddingStart="24dp"
+        android:paddingEnd="24dp">
+
+        <com.google.android.material.textview.MaterialTextView
+            style="@style/TextAppearance.MaterialComponents.Headline6"
+            android:id="@+id/everywhere_error_title"
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:gravity="center_horizontal"
+            android:text="@string/everywhere_error_title" />
+
+        <com.google.android.material.textview.MaterialTextView
+            style="@style/TextAppearance.MaterialComponents.Caption"
+            android:id="@+id/everywhere_error_description"
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:layout_marginTop="8dp"
+            android:gravity="center_horizontal"
+            android:textSize="14sp" />
+
+        <com.google.android.material.button.MaterialButton
+            android:id="@+id/everywhere_error_retry"
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:layout_marginTop="24dp"
+            android:text="@string/everywhere_error_retry" />
+
+        <com.google.android.material.button.MaterialButton
+            style="@style/Widget.MaterialComponents.Button.TextButton"
+            android:id="@+id/everywhere_error_leave"
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:layout_marginTop="8dp"
+            android:text="@string/everywhere_error_leave"
+            android:visibility="gone" />
+
+    </LinearLayout>
+
+</FrameLayout>

data/support/mobile/android/app/src/main/res/values/strings.xml

@@ -15,4 +15,23 @@
       names its own overflow tab on iOS.
     -->
     <string name="everywhere_more_tab">More</string>
+    <!--
+      The failed-visit screen (WebFragment.createErrorView). "Back to start"
+      shows only inside a picked instance, where retrying the same dead host
+      is the only other move — it clears the instance and re-roots.
+    -->
+    <string name="everywhere_error_title">Error loading page</string>
+    <string name="everywhere_error_retry">Try again</string>
+    <string name="everywhere_error_leave">Back to start</string>
+    <!--
+      MissingExtensionFragment — the fallback destination when a previewed
+      app's rule names a native screen compiled into ITS build, not this
+      shell. Copy mirrors iOS's MissingExtensionScreen.
+    -->
+    <string name="everywhere_missing_screen_nav_title">Preview</string>
+    <string name="everywhere_missing_screen_title">This screen is native</string>
+    <string name="everywhere_missing_screen_body">In the full build, “%1$s” is a native screen compiled into the app. Jump can\'t run another app\'s native code — everything else in this preview works.</string>
+    <!-- Older previewed apps serve no fallback_uri; their native-screen visits
+         are refused with this toast instead of a spinner that never ends. -->
+    <string name="everywhere_missing_screen_toast">“%1$s” is a native screen in the full build — Jump can\'t run another app\'s native code.</string>
 </resources>

data/support/mobile/ios/App/Bridge/MenuComponent.swift

@@ -55,6 +55,10 @@ final class MenuComponent: BridgeComponent {
         // order ("Edit", "Share") lands left-to-right as authored.
         viewController.navigationItem.leftBarButtonItems = left.isEmpty ? nil : left
         viewController.navigationItem.rightBarButtonItems = right.isEmpty ? nil : right.reversed()
+
+        // The wholesale replacement above just dropped the shell's
+        // instance-escape action, if this screen carries one — put it back.
+        (viewController as? EverywhereWebViewController)?.appendLeaveItemIfMissing()
     }
 
     private func barButtonItem(for item: NavItem) -> UIBarButtonItem {

data/support/mobile/ios/App/ErrorViewController.swift

@@ -1,14 +1,19 @@
 import UIKit
 
 /// A full-screen error page with a retry button, presented when a visit fails
-/// (e.g. the server is unreachable).
+/// (e.g. the server is unreachable). When the failure happened inside a picked
+/// instance — where retrying can only knock on the same dead host — a second
+/// button offers the way home (SceneDelegate passes `leaveHandler` exactly
+/// then, and it clears the instance and re-roots).
 final class ErrorViewController: UIViewController {
     private let error: Error
     private let retryHandler: (() -> Void)?
+    private let leaveHandler: (() -> Void)?
 
-    init(error: Error, retryHandler: (() -> Void)?) {
+    init(error: Error, retryHandler: (() -> Void)?, leaveHandler: (() -> Void)? = nil) {
         self.error = error
         self.retryHandler = retryHandler
+        self.leaveHandler = leaveHandler
         super.init(nibName: nil, bundle: nil)
     }
 
@@ -41,7 +46,15 @@ final class ErrorViewController: UIViewController {
         })
         retryButton.isHidden = retryHandler == nil
 
-        let stackView = UIStackView(arrangedSubviews: [imageView, messageLabel, retryButton])
+        var leaveConfiguration = UIButton.Configuration.plain()
+        leaveConfiguration.title = "Back to start"
+        leaveConfiguration.buttonSize = .large
+        let leaveButton = UIButton(configuration: leaveConfiguration, primaryAction: UIAction { [weak self] _ in
+            self?.leave()
+        })
+        leaveButton.isHidden = leaveHandler == nil
+
+        let stackView = UIStackView(arrangedSubviews: [imageView, messageLabel, retryButton, leaveButton])
         stackView.axis = .vertical
         stackView.alignment = .center
         stackView.spacing = 16
@@ -61,4 +74,9 @@ final class ErrorViewController: UIViewController {
         retryHandler?()
         dismiss(animated: true)
     }
+
+    private func leave() {
+        dismiss(animated: true)
+        leaveHandler?()
+    }
 }

data/support/mobile/ios/App/EverywhereConfig.swift

@@ -77,6 +77,10 @@ struct EverywhereConfig: Decodable {
     let mode: String?
     let remoteUrl: String?
     let remoteInstances: Bool?
+    /// `remote.instances_escape` — the built-in "back to start" nav-bar action
+    /// offered while re-rooted, on screens the tab bar (and its injected
+    /// leave tab) can't reach: modals, and instances serving no tabs.
+    let instancesEscape: Bool?
     let entryPath: String?
     let tintColor: ThemedColor?
     let backgroundColor: ThemedColor?
@@ -92,6 +96,7 @@ struct EverywhereConfig: Decodable {
         case mode
         case remoteUrl = "remote_url"
         case remoteInstances = "remote_instances"
+        case instancesEscape = "instances_escape"
         case entryPath = "entry_path"
         case tintColor = "tint_color"
         case backgroundColor = "background_color"

data/support/mobile/ios/App/SceneDelegate.swift

@@ -570,7 +570,10 @@ extension SceneDelegate: NavigatorDelegate {
                 return .acceptCustom(everywhereHost(MissingExtensionScreen(identifier: identifier)))
             }
         }
-        return .accept
+        // The shell's own web controller rather than the framework default —
+        // it carries the instance-escape nav action on screens the tab bar
+        // can't reach (see EverywhereWebViewController).
+        return .acceptCustom(EverywhereWebViewController(url: proposal.url))
     }
 
     func requestDidFinish(at url: URL) {
@@ -599,7 +602,18 @@ extension SceneDelegate: NavigatorDelegate {
     }
 
     private func presentError(_ error: HotwireNativeError, retryHandler: RetryBlock?) {
-        let errorViewController = ErrorViewController(error: error, retryHandler: retryHandler)
+        // Inside a picked instance whose server has gone away, Retry can only
+        // knock on the same dead host — offer the way home too: clear the
+        // instance and re-root, exactly what the leave tab does when it can load.
+        var leaveHandler: (() -> Void)?
+        if config.remoteInstances == true, EverywhereConfig.instanceURL != nil {
+            leaveHandler = { [weak self] in
+                guard let self else { return }
+                EverywhereConfig.setInstanceURL(nil)
+                self.resetApp(to: self.config.startURL)
+            }
+        }
+        let errorViewController = ErrorViewController(error: error, retryHandler: retryHandler, leaveHandler: leaveHandler)
         errorViewController.modalPresentationStyle = .fullScreen
         activeNavigator.activeNavigationController.present(errorViewController, animated: true)
     }
@@ -652,3 +666,60 @@ struct MissingExtensionScreen: View {
         .navigationTitle("Preview")
     }
 }
+
+/// The shell's web view controller — `handle(proposal:)` returns it for every
+/// accepted web visit instead of the framework default.
+///
+/// Its one addition: while a picked instance is active
+/// (`remote.instances: true` + `Everywhere.instance.set`), screens the tab bar
+/// can't reach carry the way home as a nav-bar action. The injected leave TAB
+/// alone is not enough — modals present over the tab bar, and a previewed
+/// app's whole signed-out surface can be modal (`/session/new` under a `/new$`
+/// rule), leaving no escape once a sign-out lands there. Where the tab bar IS
+/// visible its Jump tab already covers this, so the nav bar stays the app's
+/// own. `remote: { instances_escape: false }` turns the affordance off.
+final class EverywhereWebViewController: HotwireWebViewController {
+    /// Exposed so MenuComponent can re-append it after a page's own
+    /// `everywhere_nav_button`s replace `rightBarButtonItems` wholesale.
+    private(set) var leaveBarButtonItem: UIBarButtonItem?
+
+    override func viewWillAppear(_ animated: Bool) {
+        super.viewWillAppear(animated)
+        addLeavePreviewActionIfNeeded()
+    }
+
+    private func addLeavePreviewActionIfNeeded() {
+        let config = EverywhereConfig.shared
+        guard config.remoteInstances == true,
+              config.instancesEscape == true,
+              EverywhereConfig.instanceURL != nil,
+              // A reachable tab bar means the leave tab is available — stand
+              // down. Modals (their own nav stack) and bar-less roots land here.
+              tabBarController == nil
+        else { return }
+
+        if leaveBarButtonItem == nil {
+            let item = UIBarButtonItem(
+                image: UIImage(systemName: "arrow.uturn.backward"),
+                primaryAction: UIAction { _ in
+                    NotificationCenter.default.post(name: .everywhereClearInstance, object: nil)
+                }
+            )
+            item.accessibilityLabel = "Back to start"
+            leaveBarButtonItem = item
+        }
+
+        appendLeaveItemIfMissing()
+    }
+
+    /// Idempotent: the page's own nav buttons may have replaced the items —
+    /// MenuComponent calls this again after it rebuilds them.
+    func appendLeaveItemIfMissing() {
+        guard let item = leaveBarButtonItem else { return }
+        let items = navigationItem.rightBarButtonItems ?? []
+        guard !items.contains(item) else { return }
+        // First in the array is the rightmost slot — the escape stays at the
+        // far edge, clear of the page's own actions.
+        navigationItem.rightBarButtonItems = [item] + items
+    }
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_everywhere
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Andrea Fomera
@@ -240,6 +240,7 @@ files:
 - support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/IconFont.kt
 - support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/MainActivity.kt
 - support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/MainTabs.kt
+- support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/MissingExtensionFragment.kt
 - support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/WebBottomSheetFragment.kt
 - support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/WebFragment.kt
 - support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/bridge/BiometricsComponent.kt
@@ -257,6 +258,7 @@ files:
 - support/mobile/android/app/src/main/res/layout/activity_main.xml
 - support/mobile/android/app/src/main/res/layout/bridge_menu_sheet.xml
 - support/mobile/android/app/src/main/res/layout/bridge_menu_sheet_item.xml
+- support/mobile/android/app/src/main/res/layout/everywhere_error.xml
 - support/mobile/android/app/src/main/res/layout/tab_more_sheet.xml
 - support/mobile/android/app/src/main/res/layout/tab_more_sheet_item.xml
 - support/mobile/android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml