ruby_everywhere 0.7.0 → 0.8.0

data/lib/everywhere/config/auth.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module Auth
+      # 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)
+        # Compiled once per Config, not once per request: the middleware calls
+        # this on every navigation, and the instance it holds lives until
+        # everywhere.yml changes on disk. An unparseable pattern matches nothing
+        # (auth_errors is what reports it).
+        @oauth_regexps ||= oauth_paths.filter_map do |pattern|
+          Regexp.new(pattern)
+        rescue RegexpError
+          nil
+        end
+        @oauth_regexps.any? { |regexp| regexp.match?(path.to_s) }
+      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
+    end
+  end
+end

data/lib/everywhere/config/data.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    # The plumbing every other section reads through: the raw `app:` and
+    # `appearance:` hashes, the per-platform overrides that sit on top of them,
+    # and the two value coercions shared across sections. Included first, so
+    # everything below it can call these.
+    module Data
+      private
+
+      def app = @data.fetch("app", nil) || {}
+      def appearance = @data.fetch("appearance", nil) || {}
+
+      # 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
+
+      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) || {}
+
+      # The app-level keys with the target's platform override merged on top.
+      # Blank override values are dropped (`.compact`) so they don't erase a
+      # default. Without a target — or without an override for that os — this is
+      # just the plain `app:` hash.
+      def resolved(target)
+        override = target && platforms[self.class.os_of(target)]
+        override.is_a?(Hash) ? app.merge(override.compact) : app
+      end
+
+      def normalize_color(value)
+        case value
+        when String
+          { "light" => value, "dark" => value }
+        when Hash
+          light = value["light"] || value["dark"]
+          dark  = value["dark"] || value["light"]
+          { "light" => light, "dark" => dark } if light
+        end
+      end
+    end
+  end
+end

data/lib/everywhere/config/deep_linking.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module DeepLinking
+      # 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 —
+      # /.well-known/apple-app-site-association and /.well-known/assetlinks.json —
+      # generated from this config (Everywhere::Engine in Rails; MobileConfigEndpoint
+      # for Sinatra/Hanami). The iOS builder stamps the matching Associated Domains
+      # entitlement, and the shell routes an incoming link to its path.
+      #
+      #   deep_linking:
+      #     team_id: ABCDE12345          # derives the iOS app id from bundle_id
+      #     # or set app ids explicitly:
+      #     # apple_app_id: ABCDE12345.com.example.app
+      #     # apple_app_ids: ["ABCDE12345.com.example.app"]
+      #     paths: ["/*"]                # which paths open the app (default: all)
+      #     domains: ["www.example.com"] # extra applinks: domains (remote host is implicit)
+      #     android:
+      #       package: com.example.app
+      #       sha256_cert_fingerprints: ["AB:CD:EF:..."]
+      def deep_linking = @data.fetch("deep_linking", nil) || {}
+
+      # The iOS/tvOS/... app identifiers (TeamID.bundleID) the association file
+      # advertises. Explicit ids win; otherwise team_id + the app's iOS bundle id.
+      def deep_linking_apple_app_ids
+        explicit = Array(deep_linking["apple_app_ids"]) + [deep_linking["apple_app_id"]].compact
+        return explicit.map(&:to_s).uniq unless explicit.empty?
+
+        team = deep_linking["team_id"].to_s.strip
+        team.empty? ? [] : ["#{team}.#{bundle_id(target: "ios")}"]
+      end
+
+      # URL path patterns that open the app. Modern (iOS 14+) component form;
+      # defaults to every path.
+      def deep_linking_paths
+        paths = Array(deep_linking["paths"]).map(&:to_s).reject(&:empty?)
+        paths.empty? ? ["*"] : paths
+      end
+
+      def deep_linking_android = deep_linking["android"].is_a?(Hash) ? deep_linking["android"] : {}
+      def deep_linking_android_package = deep_linking_android["package"]&.to_s
+
+      def deep_linking_android_fingerprints
+        Array(deep_linking_android["sha256_cert_fingerprints"]).map { |f| f.to_s.strip }.reject(&:empty?)
+      end
+
+      def deep_linking_android? = !deep_linking_android_package.to_s.empty? && !deep_linking_android_fingerprints.empty?
+
+      def deep_linking_apple? = !deep_linking_apple_app_ids.empty?
+
+      def deep_linking? = deep_linking_apple? || deep_linking_android?
+
+      # Domains for the iOS Associated Domains entitlement (applinks:<host>) and
+      # the shell's universal-link host allowlist: the remote host plus any extra
+      # `domains:`. Bare hostnames (no scheme, no path).
+      def deep_linking_domains
+        hosts = []
+        if remote_url
+          require "uri"
+          hosts << URI(remote_url).host
+        end
+        hosts += Array(deep_linking["domains"]).map { |d| d.to_s.sub(%r{\Ahttps?://}, "").sub(%r{/.*\z}, "") }
+        hosts.compact.reject(&:empty?).uniq
+      rescue URI::InvalidURIError
+        Array(deep_linking["domains"]).map(&:to_s).reject(&:empty?).uniq
+      end
+
+      # The apple-app-site-association document (a Hash), or nil when no Apple app
+      # ids are configured. `applinks` for universal links; `webcredentials` so
+      # associated-domains password autofill / Face ID credentials work too.
+      def apple_app_site_association
+        ids = deep_linking_apple_app_ids
+        return nil if ids.empty?
+
+        { "applinks" => {
+            "details" => [{ "appIDs" => ids, "components" => deep_linking_paths.map { |p| { "/" => p } } }]
+          },
+          "webcredentials" => { "apps" => ids } }
+      end
+
+      def apple_app_site_association_json
+        require "json"
+        doc = apple_app_site_association or return nil
+        JSON.generate(doc)
+      end
+
+      # The Digital Asset Links document (an Array), or nil without an Android app.
+      def asset_links
+        return nil unless deep_linking_android?
+
+        [{ "relation" => ["delegate_permission/common.handle_all_urls"],
+           "target" => { "namespace" => "android_app",
+                         "package_name" => deep_linking_android_package,
+                         "sha256_cert_fingerprints" => deep_linking_android_fingerprints } }]
+      end
+
+      def asset_links_json
+        require "json"
+        doc = asset_links or return nil
+        JSON.generate(doc)
+      end
+    end
+  end
+end

data/lib/everywhere/config/desktop_ui.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module DesktopUi
+      # 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.
+      def menu
+        entries = @data["menu"]
+        return [] unless entries.is_a?(Array)
+
+        entries.filter_map do |item|
+          if item == "separator" || (item.is_a?(Hash) && item["separator"])
+            { "separator" => true }
+          elsif item.is_a?(Hash) && item["label"] && item["path"]
+            { "label" => item["label"], "path" => item["path"],
+              "accelerator" => item["accelerator"] }.compact
+          end
+        end
+      end
+
+      # System tray: same entry shape as `menu:` plus `action: quit | show`.
+      #
+      #   tray:
+      #     - label: "Open My App"
+      #       action: show
+      #     - label: "New Note"
+      #       path: /notes/new
+      #     - separator
+      #     - label: Quit
+      #       action: quit
+      def tray
+        entries = @data["tray"]
+        return [] unless entries.is_a?(Array)
+
+        entries.filter_map do |item|
+          if item == "separator" || (item.is_a?(Hash) && item["separator"])
+            { "separator" => true }
+          elsif item.is_a?(Hash) && item["label"] && (item["path"] || item["action"])
+            { "label" => item["label"], "path" => item["path"],
+              "action" => item["action"] }.compact
+          end
+        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
+
+      private
+
+      # 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
+    end
+  end
+end

data/lib/everywhere/config/mobile.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module Mobile
+      # Mobile tab bar, platform-neutral. Icons are per-platform (ios = SF
+      # Symbol, android = Material icon later), with a shared `icon:` fallback:
+      #
+      #   tabs:
+      #     - name: Builds
+      #       path: /builds
+      #       icons:
+      #         ios: hammer
+      #         android: build
+      #
+      # Tabs ship two ways from the same source: baked into the app's bundled
+      # path-configuration.json at build time (offline/first-launch), and served
+      # live from /everywhere/<platform>_v1.json (MobileConfigEndpoint) so tab
+      # changes deploy with the web app — no app-store release.
+      def tabs
+        entries = @data["tabs"]
+        return [] unless entries.is_a?(Array)
+
+        entries.filter_map do |tab|
+          next unless tab.is_a?(Hash) && tab["name"] && tab["path"]
+
+          path = tab["path"].start_with?("/") ? tab["path"] : "/#{tab["path"]}"
+          { "name" => tab["name"], "path" => path,
+            "icon" => tab["icon"], "icons" => (tab["icons"] if tab["icons"].is_a?(Hash)) }.compact
+        end
+      end
+
+      # Tabs with the icon resolved for one platform: icons.<os>, then the
+      # shared icon, then a safe default.
+      def tabs_for(os)
+        tabs.map do |tab|
+          { "title" => tab["name"], "path" => tab["path"],
+            "icon" => tab.dig("icons", os.to_s) || tab["icon"] || DEFAULT_TAB_ICONS[os.to_s] }.compact
+        end
+      end
+
+      DEFAULT_TAB_ICONS = { "ios" => "circle", "android" => "circle" }.freeze
+
+      # The Hotwire Native path-configuration rules every RubyEverywhere mobile
+      # shell starts from. Single source of truth: the builder bakes this into
+      # the app bundle and MobileConfigEndpoint serves it live.
+      MOBILE_PATH_RULES = [
+        { "patterns" => [".*"],
+          "properties" => { "context" => "default", "pull_to_refresh_enabled" => true } },
+        { "patterns" => ["/new$", "/edit$"],
+          "properties" => { "context" => "modal", "pull_to_refresh_enabled" => false } }
+      ].freeze
+
+      # Native permissions the app declares (top-level `permissions:`). Only
+      # declared permissions can be requested at runtime — the shell answers
+      # `undeclared` for everything else, so an app that doesn't need a
+      # permission can never prompt for it. For camera and location the value is
+      # the user-facing usage string iOS shows in the permission prompt (the
+      # "why"); it's mandatory there because requesting without one crashes the
+      # app. Notifications need no string — declare with `true`.
+      #
+      #   permissions:
+      #     notifications: true
+      #     camera: "Scan QR codes to pair devices."
+      #     location:
+      #       ios: "Find build agents near you."
+      #     biometrics: "Unlock your account with Face ID."
+      #
+      # Returns { name => { "ios" => usage-or-nil, ... } }.
+      MOBILE_PERMISSIONS = %w[notifications camera location biometrics].freeze
+
+      # Info.plist usage-description keys per permission. Presence here makes
+      # the usage string mandatory on iOS.
+      IOS_USAGE_KEYS = {
+        "camera" => "NSCameraUsageDescription",
+        "location" => "NSLocationWhenInUseUsageDescription",
+        "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)
+
+        entries.each_with_object({}) do |(name, value), acc|
+          next if value.nil? || value == false
+
+          acc[name.to_s] =
+            case value
+            when String then { "ios" => value }
+            when Hash then value.transform_keys(&:to_s).transform_values(&:to_s)
+            else {}
+            end
+        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)
+            next ["unknown permission #{name.inspect} — supported: #{MOBILE_PERMISSIONS.join(", ")}"]
+          end
+
+          if os == "ios" && IOS_USAGE_KEYS.key?(name) && usage["ios"].to_s.strip.empty?
+            next ["#{name} needs a usage string — the sentence iOS shows when asking. " \
+                  "In config/everywhere.yml:\n  permissions:\n    #{name}: \"Why the app needs #{name}.\""]
+          end
+
+          []
+        end
+      end
+
+      # App-declared Hotwire Native path-configuration rules (everywhere.yml
+      # top-level `rules:`), appended after MOBILE_PATH_RULES — later rules win
+      # per property, so apps can make routes modal, disable pull-to-refresh,
+      # or set any other Hotwire path property without touching native code:
+      #
+      #   rules:
+      #     - patterns: ["/preferences$"]
+      #       properties:
+      #         context: default        # not a modal, unlike other /edit routes
+      #     - patterns: ["/live/"]
+      #       properties:
+      #         pull_to_refresh_enabled: false
+      # 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)
+
+          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
+      # passes a per-request-filtered list; build-time stamping omits it and
+      # bakes them all).
+      def path_configuration_hash(os, tabs: nil)
+        settings = {}
+        platform_tabs = tabs || tabs_for(os)
+        settings["tabs"] = platform_tabs unless platform_tabs.empty?
+        { "settings" => settings, "rules" => MOBILE_PATH_RULES + mobile_rules(os) }
+      end
+
+      def path_configuration_json(os, tabs: nil)
+        require "json"
+        JSON.generate(path_configuration_hash(os, tabs: tabs))
+      end
+    end
+  end
+end