RubyGems - ruby_everywhere - Versions diffs - 0.3.0 → 0.5.0 - Mend

ruby_everywhere 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (125) hide show

data/lib/everywhere/config.rb CHANGED Viewed

@@ -38,23 +38,99 @@ module Everywhere
     # 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?("//")
-      encoded = target.to_json
+      # 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 ch=window.webkit&&window.webkit.messageHandlers&&window.webkit.messageHandlers.everywhereControl;
-        if(ch){ch.postMessage({action:"reset",to:to});}else{window.location.replace(to);}})();
+        (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/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
+    # 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
     # Test/reset hook.
     attr_writer :tabs_filter
   end
@@ -139,16 +215,19 @@ module Everywhere
     end
     # The `build:` section — durable build knobs that were once `every build`
-    # flags (ruby, targets, permissions). CLI flags still override per-run.
+    # flags (ruby, targets, capabilities). CLI flags still override per-run.
     # See platform/docs/build-engine.md §2.
     def build = @data.fetch("build", nil) || {}
     # Ruby version to package. nil here means "let the CLI decide its default".
     def build_ruby = build["ruby"]
-    # OS-integration permissions the app declares. Recorded in the receipt and
-    # (later) used to generate the shell's capabilities.
-    def permissions = Array(build["permissions"])
+    # Desktop OS-integration capabilities the app declares (`build.capabilities`),
+    # as a plain list. Deliberately not called permissions: the top-level
+    # `permissions:` below is the mobile prompt declaration — a different shape
+    # for a different consumer — and while both were spelled "permissions" this
+    # accessor was silently redefined by that one and could never be read.
+    def build_capabilities = Array(build["capabilities"])
     # Build targets (os-arch strings) — the CI matrix, expressed once.
     def targets = Array(build["targets"])
@@ -293,6 +372,25 @@ module Everywhere
       "biometrics" => "NSFaceIDUsageDescription"
     }.freeze
+    # Manifest <uses-permission> names per permission, stamped into
+    # src/stamped/AndroidManifest.xml. Deliberately *not* the mirror of
+    # IOS_USAGE_KEYS: presence here mandates nothing, because Android has no
+    # Info.plist-style contract — a runtime request without a rationale string
+    # prompts normally instead of terminating the process, and the rationale is
+    # a dialog the app draws itself, not a manifest value. So the map only
+    # answers "which manifest entry does this permission need", and every
+    # declared name has one.
+    #
+    # ACCESS_FINE_LOCATION implies ACCESS_COARSE_LOCATION on API 31+ only when
+    # both are declared, but the shell asks for precise location, so the fine
+    # permission alone is the honest declaration.
+    ANDROID_PERMISSIONS = {
+      "notifications" => "android.permission.POST_NOTIFICATIONS",
+      "camera" => "android.permission.CAMERA",
+      "location" => "android.permission.ACCESS_FINE_LOCATION",
+      "biometrics" => "android.permission.USE_BIOMETRIC"
+    }.freeze
     def permissions
       entries = @data["permissions"]
       return {} unless entries.is_a?(Hash)
@@ -309,9 +407,21 @@ module Everywhere
       end
     end
+    # The manifest permissions an Android build declares, in declaration order.
+    # Only known names map to anything; permission_errors("android") has
+    # already failed the build on the rest by the time the builder asks.
+    def android_manifest_permissions
+      permissions.keys.filter_map { |name| ANDROID_PERMISSIONS[name] }.uniq
+    end
     # Problems with the permissions declaration for one platform, as
     # human-readable strings — unknown names, and camera/location missing the
     # mandatory usage string. Empty means buildable.
+    #
+    # Only the unknown-name half applies to Android: the usage string exists to
+    # satisfy iOS, which kills the app when a prompt has no Info.plist entry.
+    # Android just prompts, so requiring the sentence there would fail builds
+    # over a value nothing reads.
     def permission_errors(os)
       permissions.flat_map do |name, usage|
         unless MOBILE_PERMISSIONS.include?(name)
@@ -339,17 +449,42 @@ module Everywhere
     #     - patterns: ["/live/"]
     #       properties:
     #         pull_to_refresh_enabled: false
-    def mobile_rules
+    # Native screens are selected by a different property on each platform, so
+    # `os` decides how a rule's `view_controller:` is read (see
+    # #android_screen_properties).
+    def mobile_rules(os = nil)
       entries = @data["rules"]
       return [] unless entries.is_a?(Array)
       entries.filter_map do |rule|
         next unless rule.is_a?(Hash) && rule["patterns"].is_a?(Array) && rule["properties"].is_a?(Hash)
-        { "patterns" => rule["patterns"].map(&:to_s), "properties" => rule["properties"] }
+        properties = rule["properties"]
+        properties = android_screen_properties(properties) if android_target?(os)
+        { "patterns" => rule["patterns"].map(&:to_s), "properties" => properties }
       end
     end
+    # Hotwire Native iOS picks a native screen with `view_controller: <id>`;
+    # Android picks one with `uri: hotwire://fragment/<id>`, matched against the
+    # Fragment's own @HotwireDestinationDeepLink annotation. Same rule, same
+    # identifier, different property name — so the Android document derives the
+    # `uri` rather than making apps write the route twice and keep the two in
+    # sync by hand.
+    #
+    # Derived only for ids declared under native.android.screens: an id that
+    # names an iOS-only screen must fall through to the web fragment, because a
+    # `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.
+    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}")
+    end
     # The full path-configuration document for one mobile platform — rules plus
     # our settings (tabs live in settings, per Hotwire Native convention).
     # Pass `tabs:` to override the resolved list (the mobile config endpoint
@@ -359,7 +494,7 @@ module Everywhere
       settings = {}
       platform_tabs = tabs || tabs_for(os)
       settings["tabs"] = platform_tabs unless platform_tabs.empty?
-      { "settings" => settings, "rules" => MOBILE_PATH_RULES + mobile_rules }
+      { "settings" => settings, "rules" => MOBILE_PATH_RULES + mobile_rules(os) }
     end
     def path_configuration_json(os, tabs: nil)
@@ -514,6 +649,383 @@ module Everywhere
       end
     end
+    # The Android half of "supernative": Kotlin the app repo carries in
+    # native/android/ that `every build --android` compiles into the shell,
+    # declared the same way iOS declares Swift. Same build-time-only rule —
+    # Play forbids downloading executable code — and the same shape, so an app
+    # that already knows `native.ios:` knows this section too.
+    #
+    #   native:
+    #     android:
+    #       components: [ChartComponent]   # BridgeComponent subclasses to register
+    #       screens:                       # path rules with view_controller: <id>
+    #         map: MapFragment             #   Fragment with an (url) argument
+    #       splash: LaunchSplash           # Fragment/Activity shown while booting
+    #       splash_min_seconds: 1.0        # how long that splash stays up at minimum
+    #       lazy_load_tabs: true           # defer each tab's first visit until selected
+    #       icon_font: symbols             # which Material icon font resolves icon names
+    #       packages:                      # Maven coordinates, not SPM entries
+    #         - "com.airbnb.android:lottie:6.4.0"
+    def native_android
+      section = @data.dig("native", "android")
+      section.is_a?(Hash) ? section : {}
+    end
+    def native_android_components = Array(native_android["components"]).map(&:to_s)
+    def native_android_screens
+      entries = native_android["screens"]
+      return {} unless entries.is_a?(Hash)
+      entries.to_h { |id, type| [id.to_s, type.to_s] }
+    end
+    def native_android_splash = native_android["splash"]&.to_s
+    # Same contract as the iOS splash minimum, and the same clamp: the shell
+    # gives up waiting at 8s either way, so a larger number here would only
+    # promise something the shell won't honor.
+    def native_android_splash_min_seconds
+      value = native_android["splash_min_seconds"]
+      value.to_f.clamp(0.0, 8.0) if value.is_a?(Numeric)
+    end
+    # Tri-state like native_ios_lazy_load_tabs: true defers each non-selected
+    # tab's first visit, false loads them all up front, absent leaves the shell
+    # on its default. Android's bottom-nav hosts are created eagerly at
+    # onCreate, so this decides whether they *visit*, not whether they exist.
+    def native_android_lazy_load_tabs
+      value = native_android["lazy_load_tabs"]
+      value if value == true || value == false
+    end
+    # Third-party dependencies for native/android code, as Gradle sees them:
+    # plain Maven coordinates. There is no SPM-style url + requirement split —
+    # a coordinate already carries group, artifact and version — so this
+    # accessor returns strings, one per `implementation(…)` line the builder
+    # writes into native-packages.gradle.kts. Assumes the config validated
+    # clean (see native_android_package_errors).
+    def native_android_packages
+      Array(native_android["packages"]).filter_map do |entry|
+        next unless entry.is_a?(String)
+        coordinate = entry.strip
+        coordinate unless coordinate.empty?
+      end
+    end
+    def native_android_packages? = !native_android_packages.empty?
+    def native_android? = !(native_android_components.empty? && native_android_screens.empty? &&
+                            native_android_splash.nil?)
+    # Kotlin's identifier rules match Swift's across everything we generate
+    # (no backticked names, no unicode escapes), so one pattern validates both.
+    # Aliased rather than reused by name so the Android messages can say
+    # "Kotlin" and the two paths can diverge later without touching iOS.
+    KOTLIN_TYPE_NAME = SWIFT_TYPE_NAME
+    def native_android_errors
+      types = native_android_components + native_android_screens.values + [native_android_splash].compact
+      errors = types.reject { |t| t.match?(KOTLIN_TYPE_NAME) }.map do |t|
+        "native.android: #{t.inspect} is not a Kotlin type name (letters, digits, _)"
+      end
+      errors += native_android_screens.keys.reject { |id| id.match?(SCREEN_IDENTIFIER) }.map do |id|
+        "native.android.screens: identifier #{id.inspect} must match #{SCREEN_IDENTIFIER.inspect}"
+      end
+      raw = native_android["splash_min_seconds"]
+      errors << "native.android.splash_min_seconds must be a number (seconds)" if raw && !raw.is_a?(Numeric)
+      errors + native_android_icon_font_errors + native_android_package_errors
+    end
+    # group:artifact:version — Gradle's shorthand form, and the only one we
+    # accept. The charset is narrower than Maven strictly allows on purpose:
+    # every coordinate is interpolated into a generated Kotlin DSL file inside
+    # a double-quoted literal, so a quote, a backslash, a `$` (Kotlin string
+    # templates), a newline or a space would rewrite the build script rather
+    # than name a dependency. Version ranges ("[1.0,2.0)") and BOM-style
+    # two-part coordinates are rejected for the same reason and because Gradle
+    # resolves anything subtler at build time anyway.
+    MAVEN_SEGMENT = /[A-Za-z0-9_][A-Za-z0-9_.-]*/
+    MAVEN_COORDINATE = /\A#{MAVEN_SEGMENT}:#{MAVEN_SEGMENT}:[A-Za-z0-9_][A-Za-z0-9_.+-]*\z/
+    def native_android_package_errors
+      raw = native_android["packages"]
+      return [] if raw.nil?
+      return ["native.android.packages must be a list"] unless raw.is_a?(Array)
+      raw.each_with_index.filter_map do |entry, i|
+        at = "native.android.packages[#{i}]"
+        next "#{at} must be a Maven coordinate string like \"com.airbnb.android:lottie:6.4.0\"" unless entry.is_a?(String)
+        coordinate = entry.strip
+        next if coordinate.match?(MAVEN_COORDINATE)
+        "#{at} #{coordinate.inspect} is not a Maven coordinate — " \
+          "\"group:artifact:version\" (letters, digits, . _ -)"
+      end
+    end
+    # Which Material icon font `icons.android` names — and the per-platform
+    # icon names nav buttons and menu items carry in page HTML — resolve
+    # against. Android has no UIImage(systemName:), so the shell draws the
+    # icon's codepoint from a font; the choice is which font ships.
+    #
+    # `bundled` is the whole reason this is a map and not a list: only the
+    # classic set (357 KB) rides inside the gem, because `ruby_everywhere` is
+    # 229 KB today and Symbols is ~10.6 MB — a 48x install cost paid by every
+    # user, including the desktop-only ones. The Symbols variants are fetched
+    # once on first Android build and cached under ~/.rubyeverywhere, which is
+    # noise next to the Gradle and AGP downloads the same build already makes.
+    #
+    # `codepoints` is the name → codepoint map Ruby validates every declared
+    # icon name against at build time, so a typo fails the build naming the tab
+    # it came from instead of rendering a blank icon on device.
+    ANDROID_ICON_FONTS = {
+      "symbols" => { "file" => "MaterialSymbolsOutlined.ttf", "bundled" => false },
+      "symbols-rounded" => { "file" => "MaterialSymbolsRounded.ttf", "bundled" => false },
+      "symbols-sharp" => { "file" => "MaterialSymbolsSharp.ttf", "bundled" => false },
+      "classic" => { "file" => "MaterialIcons-Regular.ttf", "bundled" => true },
+      # No font at all: the app brings its own drawables in native/android/res/.
+      "none" => { "file" => nil, "bundled" => true }
+    }.freeze
+    DEFAULT_ANDROID_ICON_FONT = "symbols"
+    def native_android_icon_font
+      value = native_android["icon_font"].to_s.strip
+      value.empty? ? DEFAULT_ANDROID_ICON_FONT : value
+    end
+    # The font's asset filename (assets/fonts/<file>), or nil for "none".
+    def native_android_icon_font_file = ANDROID_ICON_FONTS.dig(native_android_icon_font, "file")
+    # The sidecar map the builder validates names against, alongside the font.
+    def native_android_icon_font_codepoints
+      native_android_icon_font_file&.sub(/\.ttf\z/, ".codepoints")
+    end
+    # True when the selected font has to be downloaded before the first build
+    # can stamp it — the only case that can fail offline, so the builder warns
+    # about it (and points at `classic`) rather than dying mid-Gradle.
+    def native_android_icon_font_fetched?
+      entry = ANDROID_ICON_FONTS[native_android_icon_font]
+      !entry.nil? && entry["bundled"] == false
+    end
+    def native_android_icons? = !native_android_icon_font_file.nil?
+    def native_android_icon_font_errors
+      return [] if ANDROID_ICON_FONTS.key?(native_android_icon_font)
+      ["native.android.icon_font #{native_android_icon_font.inspect} is not a known font — " \
+       "one of: #{ANDROID_ICON_FONTS.keys.join(", ")}"]
+    end
+    # The desktop half of "supernative": Rust the app repo carries in
+    # native/desktop/ that `every build` compiles into the Tauri shell.
+    #
+    # The shape differs from ios/android because desktop differs: the whole UI
+    # is a webview, so there are no native screens or splash views to register.
+    # What an app actually wants down here is the machine — a serial port, a USB
+    # device, an FFI library, a Tauri plugin — reached from the page.
+    #
+    #   native:
+    #     desktop:
+    #       commands: [scan_ports]        # fns reachable from the page
+    #       setup: true                   # run native/desktop/setup.rs at boot
+    #       crates:
+    #         serialport: "4.3"
+    #         reqwest: { version: "0.12", features: [json] }
+    #
+    # A command is a plain function, NOT a #[tauri::command] — Tauri's typed
+    # commands only arrive through invoke, and invoke is unavailable to our
+    # pages (they're served over http; see extension_host.rs in the shell). The
+    # signature is uniform:
+    #
+    #   pub fn scan_ports(app: &tauri::AppHandle, payload: serde_json::Value)
+    #       -> Result<serde_json::Value, String>
+    #
+    # Declaring anything here has a real cost the mobile sections don't have:
+    # the shell stops being one prebuilt crate shared by every app and gets
+    # stamped and compiled per app (see Builders::Desktop). Apps that declare
+    # nothing keep the fast path.
+    def native_desktop
+      section = @data.dig("native", "desktop")
+      section.is_a?(Hash) ? section : {}
+    end
+    def native_desktop_commands = Array(native_desktop["commands"]).map { |name| name.to_s.strip }
+    def native_desktop_setup? = native_desktop["setup"] == true
+    # Cargo dependencies, normalized to { "name" => {...table} } so the
+    # generator has one shape to write. The short form (a bare version string)
+    # becomes { "version" => "4.3" }.
+    def native_desktop_crates
+      entries = native_desktop["crates"]
+      return {} unless entries.is_a?(Hash)
+      entries.to_h do |name, spec|
+        table = spec.is_a?(Hash) ? spec : { "version" => spec.to_s }
+        [name.to_s.strip, table]
+      end
+    end
+    def native_desktop? = !(native_desktop_commands.empty? && native_desktop_crates.empty?) ||
+                          native_desktop_setup?
+    # Everything here is interpolated into generated Rust and TOML, so names are
+    # validated hard — same reasoning as MAVEN_COORDINATE above. A command name
+    # becomes a path segment in a generate_handler! list; a crate name and its
+    # features become bare TOML keys and quoted strings.
+    RUST_FN_NAME = /\A[a-z_][a-z0-9_]*\z/
+    CRATE_NAME = /\A[a-zA-Z0-9_][a-zA-Z0-9_-]*\z/
+    # Cargo's requirement syntax, loosely: ^1.2, ~1.2, >=1.0, 1.*, 1.2.3-beta.1.
+    # Deliberately no spaces and no commas — a multi-requirement string would
+    # need quoting rules we don't want to own, and cargo reports anything
+    # subtler at build time.
+    CRATE_VERSION = /\A[\^~<>=]{0,2}\d+(\.\d+){0,2}(\.\*)?(-[0-9A-Za-z.-]+)?\z/
+    CRATE_FEATURE = /\A[A-Za-z0-9_][A-Za-z0-9_+-]*\z/
+    # Where a git dependency may point. Same rule the SPM packages use.
+    CRATE_GIT_URL = PACKAGE_URL
+    def native_desktop_errors
+      raw = @data.dig("native", "desktop")
+      return [] if raw.nil?
+      return ["native.desktop must be a mapping"] unless raw.is_a?(Hash)
+      errors = []
+      commands = raw["commands"]
+      if !commands.nil? && !commands.is_a?(Array)
+        errors << "native.desktop.commands must be a list of function names"
+      else
+        errors += native_desktop_commands.reject { |name| name.match?(RUST_FN_NAME) }.map do |name|
+          "native.desktop.commands: #{name.inspect} is not a Rust function name — " \
+            "snake_case (letters, digits, _), matching the fn in native/desktop/"
+        end
+        duplicates = native_desktop_commands.tally.select { |_name, count| count > 1 }.keys
+        errors += duplicates.map do |name|
+          "native.desktop.commands: #{name.inspect} is listed twice"
+        end
+      end
+      setup = raw["setup"]
+      errors << "native.desktop.setup must be true or false" unless setup.nil? || boolean_or_nil(setup) == setup
+      errors + native_desktop_crate_errors
+    end
+    def native_desktop_crate_errors
+      raw = native_desktop["crates"]
+      return [] if raw.nil?
+      return ["native.desktop.crates must be a mapping of crate name to version"] unless raw.is_a?(Hash)
+      raw.flat_map do |name, spec|
+        at = "native.desktop.crates.#{name}"
+        errors = []
+        unless name.to_s.strip.match?(CRATE_NAME)
+          errors << "#{at}: #{name.to_s.inspect} is not a crate name (letters, digits, _, -)"
+        end
+        errors + crate_spec_errors(at, spec)
+      end
+    end
+    # Third-party sign-in (Sign in with Apple / Google / GitHub / anything
+    # OmniAuth speaks). Providers refuse to run — or run badly — inside an app's
+    # web view, so the mobile shell hands these paths to an
+    # ASWebAuthenticationSession instead, and the gem bridges the resulting
+    # session back into the app (see AuthHandoff).
+    #
+    #   auth:
+    #     oauth_paths:                # paths that begin a provider flow
+    #       - ^/auth/                 # unanchored regexes, like `rules:`
+    #     scheme: com.example.app     # callback scheme (default: the iOS bundle id)
+    #     cookies:                    # which cookies cross back into the app
+    #       except: ["_ga"]           #   (default: all of them)
+    #
+    # The app keeps its own auth: `auth:` declares nothing about providers,
+    # only which paths the shell must not open in its web view.
+    def auth = @data.fetch("auth", nil) || {}
+    # Paths that begin a third-party auth flow, as regex source strings matched
+    # against the request path. Declaring `auth:` at all opts in, defaulting to
+    # OmniAuth's `/auth/…` convention.
+    DEFAULT_OAUTH_PATHS = ["^/auth/"].freeze
+    def oauth_paths
+      return [] unless @data.key?("auth")
+      paths = Array(auth["oauth_paths"]).map { |p| p.to_s.strip }.reject(&:empty?)
+      paths.empty? ? DEFAULT_OAUTH_PATHS.dup : paths
+    end
+    def oauth?  = !oauth_paths.empty?
+    # Whether a request path starts a provider flow. Both halves of the system
+    # ask this — the middleware per request, the shell per visit proposal — so
+    # the patterns are compiled the same way on both sides (unanchored regex).
+    def oauth_path?(path)
+      oauth_paths.any? { |pattern| Regexp.new(pattern).match?(path.to_s) }
+    rescue RegexpError
+      false
+    end
+    # The custom URL scheme ASWebAuthenticationSession returns through. Defaults
+    # to the iOS bundle id — the convention, and already unique per app. Only
+    # the characters RFC 3986 allows in a scheme.
+    URL_SCHEME = /\A[a-zA-Z][a-zA-Z0-9+.-]*\z/
+    def auth_scheme
+      explicit = auth["scheme"].to_s.strip
+      explicit.empty? ? bundle_id(target: "ios") : explicit
+    end
+    # Cookie names to carry from the auth browser back into the app's web view,
+    # filtered by an optional allow/deny list. Everything the flow set is
+    # carried by default: the gem can't know which cookie an app's auth library
+    # signs its session with.
+    def auth_cookie?(name)
+      cookies = auth["cookies"]
+      return true unless cookies.is_a?(Hash)
+      only = Array(cookies["only"]).map(&:to_s)
+      return only.include?(name.to_s) unless only.empty?
+      !Array(cookies["except"]).map(&:to_s).include?(name.to_s)
+    end
+    # How long a minted handoff token stays valid. It travels device-locally
+    # (browser sheet → shell → web view), so seconds are plenty.
+    def auth_token_ttl = [(auth["token_ttl"] || 60).to_i, 5].max
+    def auth_errors
+      return [] unless @data.key?("auth")
+      errors = oauth_paths.filter_map do |pattern|
+        Regexp.new(pattern)
+        nil
+      rescue RegexpError => e
+        "auth.oauth_paths: #{pattern.inspect} is not a valid pattern (#{e.message})"
+      end
+      unless auth_scheme.match?(URL_SCHEME)
+        errors << "auth.scheme #{auth_scheme.inspect} is not a URL scheme (letters, digits, +, -, .)"
+      end
+      errors
+    end
+    # The auth subset the shell needs: which visits to divert into the auth
+    # session, and the scheme to bring the answer back through. nil (absent from
+    # everywhere.json) when the app declares no `auth:` — a shell that can't
+    # divert anything is a shell with no new surface.
+    def auth_shell_hash
+      return nil unless oauth?
+      { "oauth_paths" => oauth_paths, "scheme" => auth_scheme }
+    end
     # Custom native menu items (macOS app menu). Each entry: label + path
     # (+ optional accelerator), or "separator". Clicks arrive in the page as
     # "everywhere:menu" events and navigate via Turbo.
@@ -555,6 +1067,99 @@ module Everywhere
       end
     end
+    # Desktop window chrome. Desktop-only: on mobile the OS owns the frame, so
+    # mobile builds ignore this section entirely.
+    #
+    #   window:
+    #     title_bar: overlay   # decorated (default) | overlay | frameless
+    #     title: false         # draw the title text (default true)
+    #     size: [1100, 750]    # initial inner size
+    #     min_size: [600, 400]
+    #     resizable: true
+    #     drag_height: 28      # top strip that drags the window; 0 turns it off
+    #
+    # Every reader returns nil when the key is absent so `to_shell_hash` drops it
+    # and the shell keeps its own default — there is exactly one place each
+    # default lives, and it's the Rust side.
+    #
+    # `overlay` is the macOS "traffic lights floating over your content" look
+    # (TitleBarStyle::Overlay + hidden title). Windows and Linux have no such
+    # style, so the shell falls back to frameless there and the page draws its
+    # own controls via Everywhere.window.
+    WINDOW_TITLE_BARS = %w[decorated overlay frameless].freeze
+    def window
+      section = @data["window"]
+      section.is_a?(Hash) ? section : {}
+    end
+    def window_title_bar
+      value = window["title_bar"].to_s
+      value if WINDOW_TITLE_BARS.include?(value)
+    end
+    # Tri-state, like native_ios_lazy_load_tabs: an absent key leaves the shell
+    # on its default rather than forcing one.
+    def window_title = boolean_or_nil(window["title"])
+    def window_resizable = boolean_or_nil(window["resizable"])
+    def window_size = window_dimensions("size")
+    def window_min_size = window_dimensions("min_size")
+    # How much of the top of the page drags the window, in CSS pixels. Only
+    # meaningful for overlay/frameless, where there's no system title bar left
+    # to grab. nil leaves the shell's 28px default (the height of the macOS
+    # traffic-light band); 0 turns dragging off for an app that wants to place
+    # its own drag regions.
+    def window_drag_height
+      value = window["drag_height"]
+      value.to_f if value.is_a?(Numeric) && !value.negative?
+    end
+    # The window subset the shell needs. nil (absent from everywhere.json) when
+    # the app declares nothing, so the shell's own defaults stand untouched.
+    def window_shell_hash
+      hash = {
+        "title_bar" => window_title_bar,
+        "title" => window_title,
+        "resizable" => window_resizable,
+        "size" => window_size,
+        "min_size" => window_min_size,
+        "drag_height" => window_drag_height
+      }.compact
+      hash unless hash.empty?
+    end
+    def window_errors
+      raw = @data["window"]
+      return [] if raw.nil?
+      return ["window: must be a mapping"] unless raw.is_a?(Hash)
+      errors = []
+      bar = raw["title_bar"]
+      if bar && !WINDOW_TITLE_BARS.include?(bar.to_s)
+        errors << "window.title_bar #{bar.to_s.inspect} must be one of " \
+                  "#{WINDOW_TITLE_BARS.join(" / ")}"
+      end
+      errors += %w[size min_size].filter_map do |key|
+        next if raw[key].nil? || window_dimensions(key)
+        "window.#{key} must be two positive numbers, like [1100, 750]"
+      end
+      drag = raw["drag_height"]
+      unless drag.nil? || (drag.is_a?(Numeric) && !drag.negative?)
+        errors << "window.drag_height must be a number of pixels (0 turns dragging off)"
+      end
+      errors + %w[title resizable].filter_map do |key|
+        next if raw[key].nil? || boolean_or_nil(raw[key]) == raw[key]
+        "window.#{key} must be true or false"
+      end
+    end
     # Deep linking / universal links. Declares the app's association with its
     # web domains so the OS can hand matching URLs to the app instead of the
     # browser. The gem serves the two well-known association files this needs —
@@ -655,6 +1260,23 @@ module Everywhere
       JSON.generate(doc)
     end
+    # The two `native:` knobs that ship inside everywhere.json rather than
+    # being compiled in, resolved for the platform being stamped. They read the
+    # target's own section: everywhere.json is written once per target, so an
+    # Android build that inherited native.ios.lazy_load_tabs would silently
+    # apply a decision the app made about a different shell — and the two
+    # platforms load tabs differently enough that the answer legitimately
+    # differs. Without a target (the desktop dev loop, and every caller written
+    # before Android existed) the iOS answer stands, which is what those
+    # callers have always gotten.
+    def native_lazy_load_tabs(target: nil)
+      android_target?(target) ? native_android_lazy_load_tabs : native_ios_lazy_load_tabs
+    end
+    def native_splash_min_seconds(target: nil)
+      android_target?(target) ? native_android_splash_min_seconds : native_ios_splash_min_seconds
+    end
     # The subset the shell needs, shipped as JSON (env var in dev,
     # Resources/everywhere.json inside a bundled .app). Pass `target:` so the
     # packaged config reflects the platform being built (its bundle id / name).
@@ -671,10 +1293,12 @@ module Everywhere
         "background_color" => background_color,
         "menu" => (menu unless menu.empty?),
         "tray" => (tray unless tray.empty?),
-        "lazy_load_tabs" => native_ios_lazy_load_tabs,
-        "splash_min_seconds" => native_ios_splash_min_seconds,
+        "window" => window_shell_hash,
+        "lazy_load_tabs" => native_lazy_load_tabs(target: target),
+        "splash_min_seconds" => native_splash_min_seconds(target: target),
         "updates" => updates_shell_hash,
         "permissions" => (permissions.keys unless permissions.empty?),
+        "auth" => auth_shell_hash,
         # Hosts the shell treats as its own for incoming universal links, so a
         # tapped link to any associated domain opens in-app rather than Safari.
         "universal_link_hosts" => (deep_linking_domains if deep_linking? && !deep_linking_domains.empty?)
@@ -691,6 +1315,72 @@ module Everywhere
     def app = @data.fetch("app", nil) || {}
     def appearance = @data.fetch("appearance", nil) || {}
+    # One crate's dependency spec: either a bare version string or a table.
+    def crate_spec_errors(at, spec)
+      return version_errors(at, spec) unless spec.is_a?(Hash)
+      errors = []
+      # A crate needs somewhere to come from. version: is the common case; git:
+      # and path: are the two escape hatches cargo itself offers.
+      unless %w[version git path].any? { |key| !spec[key].to_s.strip.empty? }
+        errors << "#{at} needs a version: (or git: / path:)"
+      end
+      errors += version_errors("#{at}.version", spec["version"]) if spec.key?("version")
+      git = spec["git"].to_s.strip
+      unless git.empty? || git.match?(CRATE_GIT_URL)
+        errors << "#{at}.git #{git.inspect} must be an https:// or git@ URL"
+      end
+      # branch/tag/rev/path have no useful shape to check, but they DO end up
+      # inside quoted TOML strings — so the one thing that matters is that they
+      # can't close the quote or start a new line.
+      errors += %w[branch tag rev path].filter_map do |key|
+        value = spec[key].to_s
+        next if value.empty? || !value.match?(/["\\\n\r]/)
+        "#{at}.#{key} can't contain quotes, backslashes or newlines"
+      end
+      features = spec["features"]
+      if !features.nil? && !features.is_a?(Array)
+        errors << "#{at}.features must be a list"
+      else
+        errors += Array(features).reject { |f| f.to_s.match?(CRATE_FEATURE) }.map do |feature|
+          "#{at}.features: #{feature.to_s.inspect} is not a feature name (letters, digits, _, +, -)"
+        end
+      end
+      errors
+    end
+    def version_errors(at, value)
+      version = value.to_s.strip
+      return [] if version.empty?
+      return [] if version.match?(CRATE_VERSION)
+      ["#{at} #{version.inspect} is not a cargo version requirement — like \"1.2\", \"^1.2.3\" or \"~0.4\""]
+    end
+    # YAML's `yes`/`on` already parse as true, so anything that reaches here
+    # still not a boolean is a genuine mistake rather than a spelling of one.
+    # Deliberately not an endless def: `def f(v) = v if cond` parses as
+    # `(def f(v) = v) if cond`, which would define nothing when cond is false.
+    def boolean_or_nil(value)
+      value if value == true || value == false
+    end
+    # A [width, height] pair. Rejects the near-misses (one number, three, a
+    # negative) rather than silently building a 0-pixel window.
+    def window_dimensions(key)
+      value = window[key]
+      return unless value.is_a?(Array) && value.length == 2
+      return unless value.all? { |n| n.is_a?(Numeric) && n.positive? }
+      value.map(&:to_f)
+    end
+    def android_target?(target) = self.class.os_of(target) == "android"
     # Per-platform overrides, keyed by os (macos / ios / android / windows /
     # linux). Each value overrides the matching `app:` keys for that platform.
     def platforms = @data.fetch("platforms", nil) || {}