ruby_everywhere 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97a5e572306841f37118d70c1b5702efc0fc1d48d9377e8ad325e551b7b720b2
-  data.tar.gz: 9ffbcd6323f81374f94b1237cdf06a13c50dc2c3466479c8fbb0cfdedfa6ddbd
+  metadata.gz: effe761f70b4c3220e02788d26a8fc49278a52f3e3876c331e3f9f484867592f
+  data.tar.gz: 9e589059bea3245ad9540696a24edfb9261736e0d1f30467698aad051c78541e
 SHA512:
-  metadata.gz: 66071e14c65bec691891622e1133253e77437cf5ce1d1c43d6785e3b70568ad12c9bcd7155d932a2bf27b313779b562082bdf9fb9f38a1c7468ccff1006c04e2
-  data.tar.gz: '068d02e32db302d5b48e1325e9f789e460ede9e18a15e30b20fee7d2ac22a100858577f7ba2fd138d0a2655eaa5e50532058527921b8a29abd3dc727aeb02339'
+  metadata.gz: ca496e477bd712bc8a8687916f8f9c17e1a3736d944f245bd633812a479d7771e1457107dd3e7135a2536657e70c4a5aecebe6a5c3df5ee5d12428fe70b423ba
+  data.tar.gz: 28e6a3a1c4a6c6c90a455ad545354a1d6812ea3bd1c3ef57a6a1d252c7e7ddf30d5edf7375a7b99e53dd15e6e059c70b11c55ef7070f2df90906b9ca2b13f36b

data/lib/everywhere/commands/preview.rb

@@ -1,18 +1,23 @@
 # frozen_string_literal: true
 
 require "dry/cli"
+require "fileutils"
 require "socket"
 require "securerandom"
 require "shellwords"
 require "timeout"
 require "uri"
+require "yaml"
 require_relative "../shellout"
 require_relative "../console"
 require_relative "../child_processes"
 require_relative "../child_supervision"
+require_relative "../dock/info"
 require_relative "../framework"
 require_relative "../config"
 require_relative "../jump"
+require_relative "../paths"
+require_relative "../raw_tty"
 
 module Everywhere
   module Commands
@@ -70,12 +75,18 @@ module Everywhere
 
         start_server(port)
         warn_if_loopback_only if lan
+        # Everything below this line scrolls: the dev server's log starts
+        # flowing the moment a device connects, and the invitation was gone off
+        # the top of the screen with it. The dock pins it instead.
+        @dock = Dock::Info.open(keys: $stdin.tty?)
         announce
         wait
       rescue Interrupt
         nil
       ensure
-        teardown_children
+        # The dock has to let go of the terminal before anything else prints —
+        # teardown_children's own warnings included.
+        teardown_children(before: [-> { @dock&.close }])
       end
 
       private
@@ -115,6 +126,7 @@ module Everywhere
       def start_tunnel
         if @tunnel_name
           UI.step("starting named tunnel #{UI.bold(@tunnel_name)} → #{UI.cyan("https://#{@tunnel_host}")}")
+          warn_if_ingress_mismatch
           spawn_tunnel("cloudflared tunnel run --url http://127.0.0.1:#{@port} #{@tunnel_name.shellescape}")
           "https://#{@tunnel_host}"
         else
@@ -128,7 +140,7 @@ module Everywhere
       # and the on_line hook fishes out the URL.
       def quick_tunnel_url
         found = Queue.new
-        spawn_tunnel("cloudflared tunnel --url http://127.0.0.1:#{@port}",
+        spawn_tunnel("cloudflared --config #{blank_config.shellescape} tunnel --url http://127.0.0.1:#{@port}",
                      on_line: ->(line) { (url = line[TRYCLOUDFLARE_URL]) && found << url },
                      quiet: true)
         begin
@@ -139,6 +151,62 @@ module Everywhere
         end
       end
 
+      # Where cloudflared looks for a local config, in its own search order.
+      CLOUDFLARED_CONFIGS = ["~/.cloudflared/config.yml", "~/.cloudflared/config.yaml",
+                             "/etc/cloudflared/config.yml", "/usr/local/etc/cloudflared/config.yml"].freeze
+
+      # A named tunnel keeps the user's cloudflared config on purpose — its
+      # credentials live there — but when that config declares ingress rules
+      # they beat our --url: cloudflared routes by Host header. A host with no
+      # matching rule falls to the catch-all (conventionally http_status:404);
+      # a rule aimed at another port reaches the wrong server. Both look like
+      # a dead preview with no hint of why, so say so before it happens.
+      # Best-effort: a config we can't read just means cloudflared honors --url.
+      def warn_if_ingress_mismatch
+        rules = cloudflared_ingress
+        return if rules.nil? || rules.empty?
+
+        rule = rules.find { |r| r["hostname"].nil? || host_matches?(r["hostname"], @tunnel_host) }
+        service = rule&.fetch("service", nil).to_s
+        if rule.nil? || service.start_with?("http_status:")
+          UI.warn("your cloudflared config's ingress has no rule for #{@tunnel_host}, so requests will get " \
+                  "the catch-all#{" (#{service})" unless service.empty?} — add " \
+                  "{hostname: #{@tunnel_host}, service: http://localhost:#{@port}} above it")
+        elsif (svc_port = service[/:(\d+)\z/, 1]) && Integer(svc_port) != @port
+          UI.warn("your cloudflared config's ingress routes #{@tunnel_host} to #{service}, but this preview " \
+                  "runs on port #{@port} — point that rule at the preview, or match it with --port #{svc_port}")
+        end
+      end
+
+      def cloudflared_ingress(paths: CLOUDFLARED_CONFIGS)
+        path = paths.map { |p| File.expand_path(p) }.find { |p| File.file?(p) }
+        return nil unless path
+
+        config = YAML.safe_load(File.read(path))
+        rules = config.is_a?(Hash) ? config["ingress"] : nil
+        rules.is_a?(Array) ? rules.grep(Hash) : nil
+      rescue StandardError
+        nil
+      end
+
+      # cloudflared ingress hostnames may hold a * wildcard; fnmatch covers it.
+      def host_matches?(pattern, host)
+        File.fnmatch?(pattern.to_s, host.to_s, File::FNM_CASEFOLD)
+      end
+
+      # cloudflared reads ~/.cloudflared/config.yml even in quick-tunnel mode,
+      # and config ingress rules win over --url: a leftover named-tunnel config
+      # sees a *.trycloudflare.com Host, matches nothing, and its catch-all
+      # (conventionally http_status:404) answers every request. A blank config
+      # keeps the quick tunnel self-contained. Named tunnels (--tunnel-name)
+      # still read the user's config on purpose — their credentials live there.
+      def blank_config
+        path = File.join(Paths.cache_dir, "cloudflared-blank.yml")
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "")
+        path
+      end
+
       # quiet drops the child's routine chatter but always lets errors
       # through — a quick tunnel that can't connect must say why.
       def spawn_tunnel(cmd, on_line: nil, quiet: false)
@@ -205,13 +273,26 @@ module Everywhere
       end
 
       def announce
-        link = share_link || connect_url
+        @link = share_link || connect_url
         UI.step("preview of #{UI.bold(@config.name)} is live → #{UI.cyan(@url)}")
-        Console.print(qr_ansi(link)) if $stdout.tty?
-        Console.print("  Scan with your phone's camera, or send:\n\n    #{UI.cyan(link)}\n\n")
+        show_qr
         Console.print("  #{UI.dim("Manual entry in Jump:")} #{@url}  #{UI.dim("token:")} #{@token}\n")
         Console.print(UI.dim("  The link and QR die with this session — Ctrl-C to stop.\n"))
         UI.note("waiting for devices…", marker: "⌁", color: :cyan)
+        @dock.show(footer_facts)
+      end
+
+      # What stays on screen. The QR is ~17 rows — far too tall to pin — so the
+      # footer carries what a person can act on without it: the link to forward,
+      # and the URL and token for Jump's manual entry form.
+      def footer_facts = [["link", @link], ["url", @url], ["token", @token]]
+
+      # Printed at announce time and again on `s`, once the logs have scrolled
+      # the code away. A non-tty stdout gets the link alone — an ANSI QR down a
+      # pipe is noise.
+      def show_qr
+        Console.print(qr_ansi(@link)) if $stdout.tty?
+        Console.print("  Scan with your phone's camera, or send:\n\n    #{UI.cyan(@link)}\n\n")
       end
 
       # Half-block rendering: ▀ painted fg-for-top-module, bg-for-bottom packs
@@ -246,14 +327,23 @@ module Everywhere
 
       # --- the wait loop --------------------------------------------------------
 
+      # RawTty only when the dock is offering keys: it puts the terminal in
+      # -icanon -echo for the whole process, which a piped or CI run has no use
+      # for — and its ensure is what puts the terminal back, so the watch loop
+      # has to run inside it rather than beside it.
+      def wait
+        @dock.keys? ? RawTty.with { watch } : watch
+      end
+
       # The server's death ends the session; the tunnel's doesn't. Quick
       # tunnels are explicitly best-effort — Cloudflare recycles them — so a
       # dead tunnel is restarted and the fresh URL re-announced. (The token
       # survives, but the origin changed, so recents/short links need the new
-      # invitation.)
-      def wait
+      # invitation — including the copy pinned in the footer.)
+      def watch
         loop do
-          sleep 1
+          break if pause == :quit
+
           web = @children.synchronize { @pids[:web] }
           UI.die!("the dev server exited — scroll up for its output") unless ChildProcesses.alive?(web)
 
@@ -267,7 +357,45 @@ module Everywhere
         end
       end
 
-      # --- child supervision (dev.rb's pattern, without the dock) ---------------
+      # A second between checks, spent waiting on a keystroke when there is a
+      # terminal to take one from — so a key is acted on the moment it's pressed
+      # rather than up to a second later, and the loop keeps its one pacing
+      # point either way.
+      def pause
+        return sleep(1) unless @dock.keys?
+        return unless IO.select([$stdin], nil, nil, 1)
+
+        case $stdin.getc
+        when "s"                then show_qr
+        when "r"                then restart_server
+        when "q", "\u0004", nil then :quit # q, Ctrl-D, EOF (Ctrl-C stays a real SIGINT)
+        end
+      end
+
+      # Replace just the dev server, keeping the tunnel and the pairing token —
+      # how a gem update or an everywhere.yml change gets picked up without
+      # invalidating the invitation everyone already scanned. start_server
+      # rebuilds the env, so the same @token rides back in; connected devices
+      # see a blip, not a disconnect. The config is reloaded so a renamed app
+      # announces under its new name if the tunnel later restarts.
+      def restart_server
+        UI.step("restarting the dev server #{UI.dim("(the tunnel, link and token stay)")}")
+        stop_child(:web)
+        wait_for_port_close
+        @config = Everywhere::Config.load(@framework.root)
+        start_server(@port.to_s)
+        UI.note("server is back — same URL, same token", marker: "⌁", color: :cyan)
+      end
+
+      # stop_child has reaped the process, but the kernel can hold its listener
+      # a beat longer; start_server's already-running guard would read that as
+      # a stranger's server and kill the whole session.
+      def wait_for_port_close(timeout: 10)
+        deadline = Clock.monotonic + timeout
+        sleep 0.1 while port_open?(@port) && Clock.monotonic < deadline
+      end
+
+      # --- child supervision (dev.rb's pattern, its own no-pty fallback) --------
 
       def spawn_child(env, cmd, chdir:)
         return Shellout.spawn_pty(env, cmd, chdir: chdir) if Shellout.pty?

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/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/dock/footer.rb

@@ -95,6 +95,49 @@ module Everywhere
 
       def plain_width(segments) = segments.sum { |s| plain(s).length } + (GAP.length * [segments.size - 1, 0].max)
 
+      # --- info rows -----------------------------------------------------------
+
+      # `every preview`'s footer: labelled facts (the share link, the tunnel
+      # URL, the pairing token) instead of target states. items: [[label,
+      # value], …].
+      #
+      # Packed across as many rows as it takes rather than truncated to one,
+      # which is the one place this parts ways with status_row: these values
+      # exist to be scanned, read aloud and typed in by hand, and half a URL or
+      # a clipped token is worse than useless.
+      def info(items, cols:, keys: nil, rule: true)
+        cols = [cols.to_i, 1].max
+        lines = []
+        lines << UI.gray("─" * cols) if rule
+        lines.concat(pack(items.map { |label, value| info_pair(label, value) }, cols))
+        lines << keys_row(keys, cols) if keys
+        lines
+      end
+
+      # Greedy: keep adding facts to the current row while they fit, start a new
+      # row when they don't. A single fact wider than the terminal is the only
+      # thing that ever gets cut (by fit).
+      def pack(pairs, cols)
+        rows = []
+        row = []
+        pairs.each do |pair|
+          if row.any? && row_width(row + [pair]) > cols
+            rows << fit(row, cols)
+            row = [pair]
+          else
+            row << pair
+          end
+        end
+        rows << fit(row, cols) if row.any?
+        rows
+      end
+
+      def info_pair(label, value)
+        ["#{label} #{value}", "#{UI.dim(label)} #{UI.cyan(value)}"]
+      end
+
+      def row_width(pairs) = pairs.sum { |plain, _| plain.length } + (GAP.length * [pairs.size - 1, 0].max)
+
       # --- keys row ------------------------------------------------------------
 
       # Named keys with dot separators, then named keys packed tighter, then

data/lib/everywhere/dock/info.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../dock"
+
+module Everywhere
+  class Dock
+    # The pinned footer for `every preview`.
+    #
+    # Same machinery as the dev dock — it owns the terminal through Console and
+    # repaints around every write (see Dock::Screen) — but what it pins is a
+    # handful of facts rather than a set of running targets: the share link, the
+    # URL to type in by hand and the pairing token. Preview prints those once
+    # and then relays the dev server's log, which used to bury them within
+    # seconds; the whole point of the command is that someone can still see how
+    # to connect five minutes in.
+    #
+    # It carries no state of its own to spin, so the base class's ticker only
+    # ever redraws it on a resize.
+    class Info < Dock
+      KEYS = [
+        ["s", "show the QR"],
+        ["r", "restart server"],
+        ["q", "quit"]
+      ].freeze
+
+      def self.open(items = [], io: $stdout, keys: true, size: nil)
+        return Null.new unless drawable?(io, size)
+
+        new(items, io: io, keys: keys, size: size).tap(&:install)
+      end
+
+      def initialize(items = [], io: $stdout, keys: true, size: nil)
+        super([], io: io, keys: keys, size: size)
+        @items = items
+      end
+
+      # Whether the keymap in the footer is a promise we can keep — the caller
+      # owns the key loop, so it has to know whether to read stdin at all.
+      def keys? = @keys
+
+      # Replace the facts and repaint now. A quick tunnel that dropped comes
+      # back on a different hostname, so the footer must not outlive its URL.
+      def show(items)
+        @items = items
+        @dirty = true
+        refresh
+      end
+
+      private
+
+      def footer_rows
+        Footer.info(@items,
+                    cols: [@screen.cols - 1, 1].max,
+                    keys: (@keys ? KEYS : nil),
+                    rule: @screen.rows >= 24)
+      end
+
+      # The headless stand-in, as with Dock::Null: no escape sequences, and
+      # never installed as Console's sink, so a piped or CI run prints exactly
+      # what it printed before the footer existed.
+      class Null
+        def install = self
+        def keys? = false
+        def show(_items) = nil
+        def emit(_text) = nil
+        def refresh = nil
+        def clear = nil
+        def close = nil
+      end
+    end
+  end
+end

data/lib/everywhere/version.rb

@@ -3,7 +3,7 @@
 require "json"
 
 module Everywhere
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 
   # 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

@@ -169,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
     }
 

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> =

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
     // ------------------------------------------------------------------------
@@ -162,6 +178,13 @@ class MainActivity : HotwireActivity() {
         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 {
@@ -212,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
@@ -580,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)
 
@@ -623,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)
     }
 
     /**
@@ -773,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)
     }
 
     /**
@@ -838,10 +904,39 @@ class MainActivity : HotwireActivity() {
     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
@@ -1008,6 +1103,7 @@ 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

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

@@ -1,7 +1,11 @@
 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
@@ -20,6 +24,54 @@ import dev.hotwire.navigation.fragments.HotwireWebFragment
 @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()
@@ -60,4 +112,9 @@ open class WebFragment : HotwireWebFragment() {
     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/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/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) {
@@ -663,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.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Andrea Fomera
@@ -156,6 +156,7 @@ files:
 - lib/everywhere/desktop_dev_app.rb
 - lib/everywhere/dock.rb
 - lib/everywhere/dock/footer.rb
+- lib/everywhere/dock/info.rb
 - lib/everywhere/dock/screen.rb
 - lib/everywhere/dock/state.rb
 - lib/everywhere/emulator.rb