ruby_everywhere 0.6.0 → 0.8.0

data/lib/everywhere/native_platform.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class << self
+    # The desktop shell's marker. WKWebView APPENDS
+    # `applicationNameForUserAgent` to the real system UA, so this arrives
+    # alongside a normal Safari UA rather than replacing it — hence a pattern
+    # rather than a prefix check. The version is absent when everywhere.yml
+    # declares none.
+    #
+    # macOS only for now: the marker is set in macos_webview_configuration, and
+    # Windows/Linux have no append-only equivalent (their user_agent() REPLACES
+    # the string, and fabricating a whole UA is worse than not marking it).
+    # Desktop only ships macOS today; revisit when it doesn't.
+    DESKTOP_UA = %r{\bRubyEverywhere(?:/[\w.\-]+)? \((?:macos|windows|linux)\)}
+
+    MOBILE_PLATFORMS = %i[ios android].freeze
+
+    # :ios, :android, :desktop or nil, from a User-Agent string. Present from
+    # the very first request, before any JS has run. Shared by the view helpers
+    # and the auth middleware.
+    #
+    # Mobile is checked FIRST and the order matters: the mobile shells prepend
+    # the same "RubyEverywhere/<version> (<os>)" marker to Hotwire Native's own,
+    # so a mobile UA matches DESKTOP_UA too.
+    def native_platform_of(user_agent)
+      ua = user_agent.to_s
+      return :ios if ua.include?("Hotwire Native iOS")
+      return :android if ua.include?("Hotwire Native Android")
+      return :desktop if ua.match?(DESKTOP_UA)
+
+      nil
+    end
+
+    # Just the phone shells. Anything that leans on a mobile-only affordance —
+    # the OAuth handoff to ASWebAuthenticationSession / Custom Tabs, biometric
+    # gating — has to ask for this rather than "is this a native shell", because
+    # the desktop shell answers yes to that and has neither.
+    def mobile_platform_of(user_agent)
+      platform = native_platform_of(user_agent)
+      platform if MOBILE_PLATFORMS.include?(platform)
+    end
+  end
+end

data/lib/everywhere/paths.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "error"
+require_relative "ui"
+
 module Everywhere
   # Filesystem locations the CLI resolves relative to the gem itself, so
   # `every dev`/`build`/`release` work in any project the gem is installed into.
@@ -83,15 +86,19 @@ module Everywhere
     end
 
     # Per-user cache dir. Keeps heavy build state out of the gem and the app.
+    # `~` needs a home to expand against, and a container run with --user has
+    # neither HOME nor a passwd entry.
     def cache_dir
       File.expand_path(ENV["RUBYEVERYWHERE_HOME"] || "~/.rubyeverywhere")
+    rescue ArgumentError
+      UI.die!("couldn't resolve your home directory — set HOME or RUBYEVERYWHERE_HOME")
     end
 
     # The stamped copy of the iOS template for one app. Persistent (not a
     # tmpdir) on purpose: a stable project path keeps Xcode's incremental state
     # valid across builds, and users can open the stamped project in Xcode.
     def ios_work_dir(bundle_id)
-      File.join(cache_dir, "ios", bundle_id)
+      File.join(cache_dir, "ios", segment!(bundle_id))
     end
 
     # Where xcodebuild writes DerivedData for iOS shell builds. Shared across
@@ -112,7 +119,7 @@ module Everywhere
     # incremental state is path-sensitive, and the stamped project opens in
     # Android Studio unmodified.
     def android_work_dir(application_id)
-      File.join(cache_dir, "android", application_id)
+      File.join(cache_dir, "android", segment!(application_id))
     end
 
     # GRADLE_USER_HOME for shell builds. Redirected here so the multi-GB Gradle
@@ -130,14 +137,15 @@ module Everywhere
       File.join(cache_dir, "android-fonts")
     end
 
-    # The stamped copy of the Tauri shell for one app, keyed by bundle id.
-    # Only apps that declare `native.desktop` get one — everyone else compiles
-    # the gem's own copy, which is identical for them and stays warm across
-    # projects (see cargo_target_dir). Persistent for the same reason the mobile
-    # work dirs are: cargo's incremental state lives inside it, and a cold Tauri
-    # build is minutes where a warm one is seconds.
+    # The staged copy of the Tauri shell for one app, keyed by bundle id.
+    # Every app builds from one of these — cargo never runs inside the
+    # installed gem, which may be root-owned — but only apps that declare
+    # `native.desktop` get their Rust stamped in; everyone else's copy is
+    # identical to the template and shares cargo_target_dir so the compile
+    # stays warm across projects. Persistent for the same reason the mobile
+    # work dirs are: a cold Tauri build is minutes where a warm one is seconds.
     def desktop_work_dir(bundle_id)
-      File.join(cache_dir, "desktop", bundle_id)
+      File.join(cache_dir, "desktop", segment!(bundle_id))
     end
 
     # CARGO_TARGET_DIR for a stamped shell. Per-app rather than shared, because
@@ -145,7 +153,7 @@ module Everywhere
     # every other app's — pointing them at one target dir would make cargo
     # rebuild the world on every alternating build.
     def desktop_target_dir(bundle_id)
-      File.join(cache_dir, "desktop-target", bundle_id)
+      File.join(cache_dir, "desktop-target", segment!(bundle_id))
     end
 
     # Where `every dev` keeps the throwaway .app wrapper it runs the shell
@@ -154,14 +162,14 @@ module Everywhere
     # menu bar, the About/Hide/Quit items and the Dock. The wrapper exists only
     # to carry an Info.plist; the binary inside it is a hard link to cargo's.
     def desktop_dev_app_dir(bundle_id)
-      File.join(cache_dir, "desktop-app", bundle_id)
+      File.join(cache_dir, "desktop-app", segment!(bundle_id))
     end
 
     # Where `every dev` stages the app's Dock icon for the running shell. The
     # shaped master is derived from app.icon, so it's a build product, not the
     # app's own file — it belongs in the cache next to the rest of them.
     def desktop_icon_dir(bundle_id)
-      File.join(cache_dir, "desktop-icon", bundle_id)
+      File.join(cache_dir, "desktop-icon", segment!(bundle_id))
     end
 
     # Where `every dev` stages native/desktop/assets for the running shell.
@@ -171,7 +179,7 @@ module Everywhere
     # in dev. Staging runs the same DesktopAssets compiler both ways, so the two
     # can't drift. Keyed by bundle id like the mobile work dirs.
     def desktop_assets_dir(bundle_id)
-      File.join(cache_dir, "desktop-assets", bundle_id)
+      File.join(cache_dir, "desktop-assets", segment!(bundle_id))
     end
 
     # Where cargo writes the shell's build output (CARGO_TARGET_DIR) for apps on
@@ -192,5 +200,20 @@ module Everywhere
     def app_bundle_dir
       File.join(cache_dir, "bundle")
     end
+
+    # Bundle ids and application ids come from the app's everywhere.yml and are
+    # used as ONE path segment under the cache — directories the builders rm_rf
+    # wholesale. Config#identity_errors rejects a malformed id before a build
+    # starts; this is the backstop for every other caller. Raise, not die!:
+    # Paths is reachable from the packaged app's runtime.
+    def segment!(value)
+      segment = value.to_s
+      if segment.empty? || segment.include?("/") || segment.include?("\\") || segment.include?("..")
+        raise Everywhere::Error, "#{segment.inspect} can't be a directory name (app.bundle_id in " \
+                                 "config/everywhere.yml must be reverse-DNS, like com.example.app)"
+      end
+
+      segment
+    end
   end
 end

data/lib/everywhere/platform/client.rb

@@ -3,6 +3,12 @@
 require "net/http"
 require "json"
 require "uri"
+begin
+  require "openssl" # optional stdlib; NETWORK_ERRORS below adapts if it's absent
+rescue LoadError
+  nil
+end
+require_relative "../error"
 require_relative "../version"
 
 module Everywhere
@@ -27,6 +33,19 @@ module Everywhere
     end
 
     class Client
+      # Everything a flaky link, a hung host or a TLS-intercepting proxy can
+      # throw at us. OpenSSL is an optional stdlib (net/http requires it
+      # best-effort), so its error class is only listed when it loaded.
+      NETWORK_ERRORS = [
+        SocketError, EOFError,
+        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT,
+        Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::EPIPE,
+        Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
+        *(defined?(OpenSSL::SSL::SSLError) ? [OpenSSL::SSL::SSLError] : [])
+      ].freeze
+
+      OPEN_TIMEOUT = 15
+
       def self.base_url(explicit = nil)
         (explicit || ENV["EVERYWHERE_PLATFORM_URL"] || DEFAULT_URL).chomp("/")
       end
@@ -56,8 +75,8 @@ module Everywhere
           req.body_stream = io
           http(uri) { |conn| conn.request(req) }
         end
-      rescue SocketError, Errno::ECONNREFUSED, Errno::ETIMEDOUT => e
-        raise Error, "upload to #{uri.host} failed (#{e.class})"
+      rescue *NETWORK_ERRORS => e
+        raise Error, "upload to #{uri.host} failed (#{e.class}: #{e.message})"
       end
 
       # GET a (possibly redirecting, signed) URL and stream it to dest. Sends the
@@ -74,7 +93,7 @@ module Everywhere
             when Net::HTTPRedirection
               raise Error, "too many redirects downloading #{url}" if redirects <= 0
 
-              return download(res["location"], dest, redirects: redirects - 1)
+              return download(redirect_target(uri, res["location"]), dest, redirects: redirects - 1)
             when Net::HTTPSuccess
               File.open(dest, "wb") { |f| res.read_body { |chunk| f.write(chunk) } }
             else
@@ -83,12 +102,32 @@ module Everywhere
           end
         end
         dest
+      rescue *NETWORK_ERRORS => e
+        raise Error, "download from #{uri.host} failed (#{e.class}: #{e.message})"
       end
 
       private
 
+      # A signed-blob redirect is expected to leave the platform host, but it
+      # may never leave TLS: an http:// hop would put the artifact — and the
+      # snapshot or credentials inside it — on the wire in the clear. Only a
+      # base that was already http (`every platform --url http://localhost`)
+      # has nothing to downgrade from. Location is resolved against the current
+      # hop, which is also what makes a relative one work.
+      def redirect_target(from, location)
+        target = URI.join(from, location.to_s)
+        if from.scheme == "https" && target.scheme != "https"
+          raise Error, "refusing an https → #{target.scheme} redirect to #{target.host}"
+        end
+
+        target.to_s
+      rescue URI::Error => e
+        raise Error, "bad redirect from #{from.host} (#{e.message})"
+      end
+
       def http(uri, &block)
-        Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", &block)
+        Net::HTTP.start(uri.hostname, uri.port,
+                        use_ssl: uri.scheme == "https", open_timeout: OPEN_TIMEOUT, &block)
       end
 
       def request(klass, path, body = nil)
@@ -102,10 +141,10 @@ module Everywhere
           req.body = JSON.generate(body)
         end
 
-        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
+        res = http(uri) { |conn| conn.request(req) }
         Response.new(res.code.to_i, parse(res.body))
-      rescue SocketError, Errno::ECONNREFUSED, Errno::ETIMEDOUT => e
-        raise Error, "couldn't reach the Platform at #{@base_url} (#{e.class})"
+      rescue *NETWORK_ERRORS => e
+        raise Error, "couldn't reach the Platform at #{@base_url} (#{e.class}: #{e.message})"
       end
 
       def parse(body)

data/lib/everywhere/platform/credentials.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "fileutils"
+require_relative "../ui"
 
 module Everywhere
   module Platform
@@ -22,15 +23,20 @@ module Everywhere
       end
 
       def self.load
-        data =
-          if File.exist?(path)
-            JSON.parse(File.read(path)) rescue {}
-          else
-            {}
-          end
+        data = File.exist?(path) ? read_or_warn(path) : {}
         new(data.is_a?(Hash) ? data : {})
       end
 
+      # A corrupt store used to look identical to "logged out", which sends
+      # people re-running login forever. Say which file to delete.
+      def self.read_or_warn(path)
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError, SystemCallError, IOError => e
+        Everywhere::UI.warn("ignoring unreadable credentials at #{path} (#{e.class}) — " \
+                            "delete it and run `every platform login`")
+        {}
+      end
+
       def initialize(data)
         @data = data
       end
@@ -63,8 +69,12 @@ module Everywhere
         dir = File.dirname(path)
         FileUtils.mkdir_p(dir)
         File.chmod(0o700, dir)
-        File.write(path, "#{JSON.pretty_generate(@data)}\n")
-        File.chmod(0o600, path)
+        # Create it 0600 rather than write-then-chmod: the token must never exist
+        # on disk world-readable, even for an instant.
+        File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |f|
+          f.write("#{JSON.pretty_generate(@data)}\n")
+        end
+        File.chmod(0o600, path) # the mode above only applies on create; tighten stores from older versions
       end
     end
   end

data/lib/everywhere/platform/snapshot.rb

@@ -4,6 +4,7 @@ require "rubygems/package"
 require "zlib"
 require "digest"
 require_relative "../ignore"
+require_relative "../ui"
 
 module Everywhere
   module Platform
@@ -38,10 +39,21 @@ module Everywhere
 
       def add(tar, root, rel)
         abs = File.join(root, rel)
+        # lstat, and never follow: File.stat would read through the link, so a
+        # dangling one (a deleted bundle path, a checked-in link to an absent
+        # sibling repo) raises Errno::ENOENT and aborts the whole snapshot —
+        # and a LIVE one pointing outside the tree (link → ~/.ssh/id_rsa) would
+        # pack and upload its target's contents under an innocent name.
+        return Everywhere::UI.warn("skipping symlink #{rel}") if File.lstat(abs).symlink?
+
         stat = File.stat(abs)
         tar.add_file_simple(rel, stat.mode & 0o777, stat.size) do |io|
           File.open(abs, "rb") { |f| IO.copy_stream(f, io) }
         end
+      rescue Errno::ENOENT, Errno::EACCES => e
+        # The listing is a snapshot in time; a dev server or watcher can delete a
+        # tmp/ file between the glob and here. Losing it beats losing the build.
+        Everywhere::UI.warn("skipping #{rel} (#{e.class.name.split("::").last})")
       end
     end
   end

data/lib/everywhere/plist.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Everywhere
+  # Escaping for the plists and entitlements the CLI writes by hand (there are
+  # four: `every build`'s Info.plist, `every dev`'s dev bundle, and the iOS
+  # builder's entitlements + export options). Every value interpolated into them
+  # comes from everywhere.yml or from Apple, so an unescaped `&` or `<` is at
+  # best a plist macOS refuses to parse and at worst extra keys of someone
+  # else's choosing.
+  module Plist
+    module_function
+
+    def escape(value)
+      value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+    end
+  end
+end

data/lib/everywhere/png.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "zlib"
+require_relative "error"
 
 module Everywhere
   # Minimal PNG surgery: Tauri requires RGBA icons, users hand us whatever

data/lib/everywhere/raw_tty.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "shellout"
+
+module Everywhere
+  # A terminal that reports keys as they're pressed, put back the way it was
+  # found on the way out.
+  #
+  # io/console's getch holds full raw mode while blocked, which clears OPOST
+  # and stair-steps every log line we relay; stty -icanon -echo disables only
+  # line buffering and echo, leaving output processing (and Ctrl-C as SIGINT)
+  # intact.
+  module RawTty
+    module_function
+
+    def with
+      # stty is POSIX-only, and the non-pty spawn path otherwise works on
+      # Windows: without it the menu simply stays line-buffered (press d,
+      # then Enter) rather than the session dying on Errno::ENOENT.
+      saved_tty = saved_tty_state
+      system("stty", "-icanon", "-echo") if saved_tty
+      trap_exit_signals
+      yield
+    ensure
+      system("stty", saved_tty) if saved_tty
+    end
+
+    # The tty settings to put back on the way out, or nil when there's no
+    # usable stty to read them with — the one signal both the raw-mode setup
+    # and its restore key off.
+    def saved_tty_state
+      return nil unless Shellout.tool?("stty")
+
+      state = `stty -g`.chomp
+      state.empty? ? nil : state
+    rescue StandardError
+      nil
+    end
+
+    # The dock hides the cursor and the key loop puts the tty in -icanon
+    # -echo; a SIGTERM that skipped our ensure blocks would leave the user's
+    # shell in that state. exit(1) from a trap unwinds normally, which is all
+    # this needs to do — a handler must stay this small, because anything that
+    # takes a lock (Console, the dock) raises ThreadError in trap context.
+    def trap_exit_signals
+      %w[TERM HUP].each { |sig| Signal.trap(sig) { exit(1) } }
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/everywhere/receipt.rb

@@ -5,6 +5,7 @@ require "digest"
 require_relative "version"
 require_relative "shellout"
 require_relative "ignore"
+require_relative "paths"
 
 module Everywhere
   # Builds the machine-readable build receipt (release.json) — the same shape
@@ -22,14 +23,20 @@ module Everywhere
   class Receipt
     SCHEMA = 1
 
-    def initialize(root:, config:, framework:, ruby:, target:, channel:, shell_dir: nil)
+    # source_checksum/lockfile_checksum are optional so a caller building one
+    # receipt per target hashes the tree ONCE and threads the digest through the
+    # rest — they describe the source, which is identical for every target.
+    def initialize(root:, config:, framework:, ruby:, target:, channel:, shell_dir: nil,
+                   source_checksum: nil, lockfile_checksum: nil)
       @root = File.expand_path(root)
       @config = config
       @framework = framework
       @ruby = ruby
-      @target_str = target                     # raw "os-arch" — selects platforms: overrides
+      @target_str = target                     # bare "os-arch" — selects platforms: overrides
       @target = parse_target(target, channel)
       @shell_dir = shell_dir
+      @source_checksum = source_checksum
+      @lockfile_checksum = lockfile_checksum
     end
 
     # The deterministic build request.
@@ -48,7 +55,9 @@ module Everywhere
           "lockfile_checksum" => lockfile_checksum
         },
         "target" => @target,
-        "permissions" => @config.permissions
+        "permissions" => @config.permissions,
+        "mode" => @config.mode,
+        "remote" => { "url" => @config.remote_url }.compact
       }
     end
 
@@ -105,10 +114,15 @@ module Everywhere
         "cli" => Everywhere::VERSION,
         "bridge" => bridge_version,
         "shell" => shell_version,
-        "tebako" => tebako_version
+        # Only macOS targets are tebako-pressed; spawning rbe-tebako for a
+        # mobile receipt would cost a process to learn nothing.
+        "tebako" => macos? ? tebako_version : nil,
+        "hotwire_native" => hotwire_native_version
       }
     end
 
+    def macos? = @target["os"] == "macos"
+
     def bridge_version
       # Package installs: read the version straight from package.json.
       [
@@ -145,11 +159,40 @@ module Everywhere
       out[/version\s+([\d.]+)/i, 1]
     end
 
+    # Which Hotwire Native the bundled mobile template pins. Read straight off
+    # the frozen templates in the gem (no spawn): iOS from the SPM lockfile,
+    # Android from the Gradle dependency line. Best-effort — a receipt is worth
+    # writing even when the template is missing or reshaped.
+    def hotwire_native_version
+      case @target["os"]
+      when "ios"     then hotwire_native_ios_revision
+      when "android" then hotwire_native_android_version
+      end
+    end
+
+    def hotwire_native_ios_revision
+      dir = Paths.ios_dir or return nil
+      resolved = File.join(dir, "App.xcodeproj", "project.xcworkspace", "xcshareddata", "swiftpm", "Package.resolved")
+      pin = JSON.parse(File.read(resolved))["pins"].find { |p| p["identity"].to_s.include?("hotwire-native-ios") }
+      pin&.dig("state", "revision")&.slice(0, 12)
+    rescue StandardError
+      nil
+    end
+
+    def hotwire_native_android_version
+      dir = Paths.android_dir or return nil
+      File.read(File.join(dir, "app", "build.gradle.kts"))[/dev\.hotwire:core:([\d.]+)/, 1]
+    rescue StandardError
+      nil
+    end
+
     # ---- checksums -----------------------------------------------------------
 
     def lockfile_checksum
-      lock = File.join(@root, "Gemfile.lock")
-      File.exist?(lock) ? "sha256:#{Digest::SHA256.file(lock).hexdigest}" : nil
+      @lockfile_checksum ||= begin
+        lock = File.join(@root, "Gemfile.lock")
+        File.exist?(lock) ? "sha256:#{Digest::SHA256.file(lock).hexdigest}" : nil
+      end
     end
 
     def lockfile_gem_version(gem_name)
@@ -164,11 +207,13 @@ module Everywhere
     # Uses the SAME ignore rules as the (future) snapshot, so the checksum
     # describes exactly what ships.
     def source_checksum
-      digest = Digest::SHA256.new
-      Ignore.for(@root).files(@root).each do |rel|
-        digest << rel << "\0" << Digest::SHA256.file(File.join(@root, rel)).hexdigest << "\n"
+      @source_checksum ||= begin
+        digest = Digest::SHA256.new
+        Ignore.for(@root).files(@root).each do |rel|
+          digest << rel << "\0" << Digest::SHA256.file(File.join(@root, rel)).hexdigest << "\n"
+        end
+        "sha256:#{digest.hexdigest}"
       end
-      "sha256:#{digest.hexdigest}"
     end
 
     # ---- helpers -------------------------------------------------------------

data/lib/everywhere/s3.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "openssl"
 require "uri"
 require "time"
+require_relative "error"
 
 module Everywhere
   # Minimal S3 client — just the four operations `every publish` needs

data/lib/everywhere/shell_pages.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class << self
+    # The tiny page served at /everywhere/reset. Auth flows redirect the native
+    # app here so it resets cleanly (fresh web views, re-fetched tabs) before
+    # continuing — the standard Hotwire Native "reset the app" pattern. It talks
+    # to the shell's control channel directly (no bridge/importmap dependency);
+    # in a plain browser it just forwards to the target. `to` is constrained to
+    # a same-origin path.
+    #
+    # Both shells are addressed inline, and differently, for the same reason
+    # the bridge normalizes them: WKWebView's message handler takes an object,
+    # while Android's WebMessageListener channel takes a string. Reaching for
+    # the bridge here instead would trade that one line for an importmap
+    # dependency on a page whose whole job is to work before anything loads.
+    def mobile_reset_html(to)
+      require "json"
+      target = to.to_s
+      target = "/" unless target.start_with?("/") && !target.start_with?("//")
+      # script_safe, not to_json: this lands inside <script>, and outside Rails
+      # nothing escapes "</script>" in a plain JSON string.
+      encoded = JSON.generate(target, script_safe: true)
+
+      <<~HTML
+        <!DOCTYPE html><html><head><meta charset="utf-8"><title>One moment…</title>
+        <meta name="viewport" content="width=device-width,initial-scale=1"></head>
+        <body><script>
+        (function(){var to=#{encoded};var msg={action:"reset",to:to};
+        var ios=window.webkit&&window.webkit.messageHandlers&&window.webkit.messageHandlers.everywhereControl;
+        var android=window.everywhereControl;
+        if(ios){ios.postMessage(msg);}
+        else if(android&&android.postMessage){android.postMessage(JSON.stringify(msg));}
+        else{window.location.replace(to);}})();
+        </script></body></html>
+      HTML
+    end
+
+    # The page served at /everywhere/jump/leave — the way OUT of a Jump
+    # preview. Once Jump re-roots onto a previewed app (instance.set), every
+    # Jump surface — launcher, scanner, tabs — resolves against the previewed
+    # app, so the escape hatch has to be served by the previewed app itself:
+    # this gem is the one thing guaranteed to be there. Posts clearInstance on
+    # the shell's control channel; shells that aren't multi-instance ignore
+    # it, and a plain browser just goes home.
+    # Fires clearInstance only once VISIBLE. This page rides in the previewed
+    # app's tab bar; shells preload tabs eagerly, but a preloaded webview is
+    # offscreen and reports visibilityState "hidden" — firing on load would
+    # bounce every preview the instant it connects, and a tap on the tab
+    # never re-proposes a visit, so visibility flipping is the ONLY signal a
+    # tab tap gives the page. The button is a belt for browsers and any
+    # webview that lies about visibility.
+    def mobile_jump_leave_html
+      <<~HTML
+        <!DOCTYPE html><html><head><meta charset="utf-8"><title>Jump</title>
+        <meta name="viewport" content="width=device-width,initial-scale=1">
+        <style>
+          body{font-family:-apple-system,system-ui,sans-serif;margin:0;min-height:100vh;
+               display:flex;flex-direction:column;align-items:center;justify-content:center;
+               gap:12px;padding:24px;text-align:center;background:#fff;color:#171717}
+          @media(prefers-color-scheme:dark){body{background:#171717;color:#fafafa}}
+          p{margin:0;opacity:.6}
+          button{font:inherit;font-weight:600;font-size:18px;color:#fff;background:#dc2626;
+                 border:0;border-radius:12px;padding:16px 32px}
+        </style></head>
+        <body>
+        <p>Returning to Jump…</p>
+        <button onclick="everywhereJumpLeave()">Return to Jump</button>
+        <script>
+        function everywhereJumpLeave(){var msg={action:"clearInstance"};
+        var ios=window.webkit&&window.webkit.messageHandlers&&window.webkit.messageHandlers.everywhereControl;
+        var android=window.everywhereControl;
+        if(ios){ios.postMessage(msg);}
+        else if(android&&android.postMessage){android.postMessage(JSON.stringify(msg));}
+        else{window.location.replace("/");}}
+        if(document.visibilityState==="visible"){everywhereJumpLeave();}
+        else{document.addEventListener("visibilitychange",function(){
+          if(document.visibilityState==="visible"){everywhereJumpLeave();}});}
+        </script></body></html>
+      HTML
+    end
+
+    # The page served at /everywhere/auth/native. The shell normally diverts a
+    # provider path natively, before the request is ever made; this covers the
+    # visits it can't see — a `data-turbo="false"` link, or the POST OmniAuth 2
+    # requires — by asking the shell, from the page, to open the auth session.
+    # In a browser it just continues to the provider.
+    def mobile_auth_html(to)
+      require "json"
+      target = to.to_s
+      target = "/" unless target.start_with?("/") && !target.start_with?("//")
+      # script_safe, as in mobile_reset_html: `to` is request input.
+      encoded = JSON.generate(target, script_safe: true)
+
+      <<~HTML
+        <!DOCTYPE html><html><head><meta charset="utf-8"><title>Signing in…</title>
+        <meta name="viewport" content="width=device-width,initial-scale=1"></head>
+        <body><p>Opening secure sign-in…</p><script>
+        (function(){var to=#{encoded};var msg={action:"authFlow",to:to};
+        var ios=window.webkit&&window.webkit.messageHandlers&&window.webkit.messageHandlers.everywhereControl;
+        var android=window.everywhereControl;
+        if(ios){ios.postMessage(msg);}
+        else if(android&&android.postMessage){android.postMessage(JSON.stringify(msg));}
+        else{window.location.replace(to);}})();
+        </script></body></html>
+      HTML
+    end
+  end
+end