ruby_everywhere 0.7.0 → 0.8.0

data/lib/everywhere/config/native_desktop.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "native_mobile"
+
+module Everywhere
+  class Config
+    module NativeDesktop
+      # 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 —
+      # named through NativeMobile because a sibling section module's constants
+      # aren't in scope here the way they were when both lived in Config.
+      CRATE_GIT_URL = NativeMobile::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
+
+      private
+
+      # 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
+    end
+  end
+end

data/lib/everywhere/config/native_mobile.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module NativeMobile
+      # Native code extensions ("supernative"): Swift the app repo carries in
+      # native/ios/ that `every build` compiles into the shell, plus this
+      # declaration of what to hook up. Build-time only — stores forbid
+      # downloading native code, so extensions ship with the app binary.
+      #
+      #   native:
+      #     ios:
+      #       components: [ChartComponent]   # BridgeComponent subclasses to register
+      #       screens:                       # path rules with view_controller: <id>
+      #         map: MapScreen               #   SwiftUI View or UIViewController, init(url:)
+      #       splash: LaunchSplash           # SwiftUI View or UIViewController, init()
+      #       splash_min_seconds: 1.0        # how long the custom splash stays up at minimum
+      #       lazy_load_tabs: true           # defer each tab's first visit until it's selected
+      def native_ios = native_section("ios")
+
+      def native_ios_components = native_components("ios")
+
+      def native_ios_screens = native_screens("ios")
+
+      def native_ios_splash = native_splash("ios")
+
+      # Minimum seconds a custom splash stays on screen (default 1.0 shell-side;
+      # a fast server would otherwise dismiss a branded splash in a ~50ms flash).
+      # Clamped to the shell's 8s give-up timeout.
+      def native_ios_splash_min_seconds = native_splash_seconds("ios")
+
+      # Whether the native tab bar defers each non-selected tab's initial visit
+      # until the tab is first selected (Hotwire Native `lazyLoadTabs`). Tri-state
+      # so apps can opt in or opt out explicitly: `true` lazy-loads, `false` loads
+      # every tab up front, and an absent key leaves the shell on its default
+      # (eager).
+      def native_ios_lazy_load_tabs = native_lazy_load("ios")
+
+      # Third-party Swift packages this app pins for its native/ios code. Each
+      # entry is one SPM dependency; `every build` writes them into the shell's
+      # local NativeExtensions package and re-exports every product, so native/ios
+      # code reaches them with a single `import NativeExtensions`.
+      #
+      #   packages:
+      #     - url: https://github.com/simibac/ConfettiSwiftUI
+      #       from: "1.1.0"                 # or exact: / branch: / revision:
+      #       products: [ConfettiSwiftUI]   # optional; defaults to the repo name
+      #
+      # Returns normalized entries: { "url", "requirement" => { "kind", "value" },
+      # "products" => [...] }. Assumes the config validated clean (see
+      # native_ios_package_errors) — the requirement is always present here.
+      PACKAGE_REQUIREMENT_KEYS = %w[from exact branch revision].freeze
+
+      def native_ios_packages
+        Array(native_ios["packages"]).filter_map do |entry|
+          next unless entry.is_a?(Hash)
+
+          url = entry["url"].to_s.strip
+          kind = PACKAGE_REQUIREMENT_KEYS.find { |k| entry.key?(k) && !entry[k].to_s.strip.empty? }
+          products = Array(entry["products"]).map { |p| p.to_s.strip }.reject(&:empty?)
+          products = [package_identity(url)] if products.empty?
+
+          { "url" => url,
+            "requirement" => (kind && { "kind" => kind, "value" => entry[kind].to_s.strip }),
+            "products" => products }
+        end
+      end
+
+      def native_ios_packages? = !native_ios_packages.empty?
+
+      # SPM's package identity: the URL's last path segment without a .git suffix
+      # (github.com/simibac/ConfettiSwiftUI → "ConfettiSwiftUI"). Used as the
+      # default product name and as the `package:` key in .product(name:package:).
+      def package_identity(url) = File.basename(url.to_s.sub(%r{/+\z}, "")).sub(/\.git\z/, "")
+
+      def native_ios? = native_declared?("ios")
+
+      # Everything declared here is interpolated into generated Swift, so names
+      # are validated hard: type names must be plain Swift identifiers, screen
+      # identifiers must be safe inside a Swift string literal.
+      SWIFT_TYPE_NAME = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+      SCREEN_IDENTIFIER = /\A[A-Za-z0-9_-]+\z/
+
+      def native_ios_errors = native_type_errors("ios") + native_ios_package_errors
+
+      # A URL SPM accepts (https for the common case, git@ for SSH remotes) and a
+      # loose semver for from:/exact: — enough to catch typos without reimplementing
+      # SPM's resolver, which reports anything subtler at build time.
+      PACKAGE_URL = %r{\A(https?://|git@).+}
+      PACKAGE_VERSION = /\A\d+(\.\d+){0,2}(-[0-9A-Za-z.-]+)?\z/
+
+      def native_ios_package_errors
+        raw = native_ios["packages"]
+        return [] if raw.nil?
+        return ["native.ios.packages must be a list"] unless raw.is_a?(Array)
+
+        raw.each_with_index.flat_map do |entry, i|
+          at = "native.ios.packages[#{i}]"
+          next ["#{at} must be a mapping with a url:"] unless entry.is_a?(Hash)
+
+          errors = []
+          url = entry["url"].to_s.strip
+          if url.empty?
+            errors << "#{at}.url is required"
+          elsif !url.match?(PACKAGE_URL)
+            errors << "#{at}.url #{url.inspect} must be an https:// or git@ URL"
+          end
+
+          present = PACKAGE_REQUIREMENT_KEYS.select { |k| entry.key?(k) && !entry[k].to_s.strip.empty? }
+          if present.empty?
+            errors << "#{at} needs one version requirement (#{PACKAGE_REQUIREMENT_KEYS.join(" / ")})"
+          elsif present.length > 1
+            errors << "#{at} sets conflicting requirements (#{present.join(", ")}) — pick one"
+          elsif %w[from exact].include?(present.first) && !entry[present.first].to_s.strip.match?(PACKAGE_VERSION)
+            errors << "#{at}.#{present.first} #{entry[present.first].to_s.inspect} must be a version like \"1.2.0\""
+          end
+
+          Array(entry["products"]).each do |product|
+            next if product.to_s.match?(SWIFT_TYPE_NAME)
+
+            errors << "#{at}.products: #{product.to_s.inspect} is not a module name (letters, digits, _)"
+          end
+          errors
+        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 = native_section("android")
+
+      def native_android_components = native_components("android")
+
+      def native_android_screens = native_screens("android")
+
+      def native_android_splash = native_splash("android")
+
+      # 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 = native_splash_seconds("android")
+
+      # 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 = native_lazy_load("android")
+
+      # 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_declared?("android")
+
+      # 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
+        native_type_errors("android") + 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 language each shell's extensions are written in, named in the
+      # messages because that's what the app author is looking at, and the
+      # pattern their type names must match — one entry per platform so the two
+      # can still diverge without either one's half changing.
+      NATIVE_LANGUAGES = { "ios" => "Swift", "android" => "Kotlin" }.freeze
+      NATIVE_TYPE_NAMES = { "ios" => SWIFT_TYPE_NAME, "android" => KOTLIN_TYPE_NAME }.freeze
+
+      private
+
+      # The two `native:` halves are declared the same way and read the same
+      # way, so the readers above are one line each over these. What genuinely
+      # differs — SPM packages vs Maven coordinates, the Android icon font —
+      # stays spelled out per platform.
+      def native_section(os)
+        section = @data.dig("native", os)
+        section.is_a?(Hash) ? section : {}
+      end
+
+      def native_components(os) = Array(native_section(os)["components"]).map(&:to_s)
+
+      def native_screens(os)
+        entries = native_section(os)["screens"]
+        return {} unless entries.is_a?(Hash)
+
+        entries.to_h { |id, type| [id.to_s, type.to_s] }
+      end
+
+      def native_splash(os) = native_section(os)["splash"]&.to_s
+
+      def native_splash_seconds(os)
+        value = native_section(os)["splash_min_seconds"]
+        value.to_f.clamp(0.0, 8.0) if value.is_a?(Numeric)
+      end
+
+      def native_lazy_load(os)
+        value = native_section(os)["lazy_load_tabs"]
+        value if value == true || value == false
+      end
+
+      def native_declared?(os)
+        !(native_components(os).empty? && native_screens(os).empty? && native_splash(os).nil?)
+      end
+
+      # The type/identifier half of one platform's errors — everything both
+      # shells validate identically. Each platform's public *_errors appends
+      # what only it has (packages, and Android's icon font).
+      def native_type_errors(os)
+        types = native_components(os) + native_screens(os).values + [native_splash(os)].compact
+        errors = types.reject { |t| t.match?(NATIVE_TYPE_NAMES[os]) }.map do |t|
+          "native.#{os}: #{t.inspect} is not a #{NATIVE_LANGUAGES[os]} type name (letters, digits, _)"
+        end
+        errors += native_screens(os).keys.reject { |id| id.match?(SCREEN_IDENTIFIER) }.map do |id|
+          "native.#{os}.screens: identifier #{id.inspect} must match #{SCREEN_IDENTIFIER.inspect}"
+        end
+
+        raw = native_section(os)["splash_min_seconds"]
+        errors << "native.#{os}.splash_min_seconds must be a number (seconds)" if raw && !raw.is_a?(Numeric)
+        errors
+      end
+    end
+  end
+end

data/lib/everywhere/config/shell.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module Shell
+      # 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).
+      def to_shell_hash(target: nil)
+        {
+          "name" => name(target: target),
+          "bundle_id" => bundle_id(target: target),
+          "version" => version(target: target),
+          "mode" => mode,
+          "remote_url" => remote_url,
+          "remote_instances" => (true if remote_instances?),
+          "entry_path" => entry_path,
+          "tint_color" => tint_color,
+          "background_color" => background_color,
+          "menu" => (menu unless menu.empty?),
+          "tray" => (tray unless tray.empty?),
+          "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?)
+        }.compact
+      end
+
+      def to_shell_json(target: nil)
+        require "json"
+        JSON.generate(to_shell_hash(target: target))
+      end
+    end
+  end
+end

data/lib/everywhere/config/updates.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Config
+    module Updates
+      # The `updates:` section — self-hosted auto-updates. Two halves:
+      # a client half (url/channel/public_key/auto/interval) that ships to the
+      # shell, and a publish-side `s3:` half that NEVER leaves the dev machine.
+      # `channel` here is a *release channel* (stable/beta) — not the receipt's
+      # `distribution_channel` (direct vs app stores).
+      def updates = @data.fetch("updates", nil) || {}
+
+      def updates_s3 = updates.fetch("s3", nil) || {}
+
+      def updates_channel = updates["channel"] || "stable"
+
+      def updates_url = updates["url"]&.chomp("/")
+
+      def updates_public_key = updates["public_key"]
+
+      # off — never check; check — check + notify (default); download — also
+      # fetch/verify in the background; install — silent auto-update.
+      def updates_auto = updates["auto"] || "check"
+
+      def updates_interval = [(updates["interval"] || 21_600).to_i, 300].max
+
+      # A dev machine serving a feed to itself is the one case http is fine.
+      UPDATES_LOOPBACK = /\A(localhost|127(\.\d+){3}|::1)\z/
+
+      # An http updates.url is not a smaller version of a working updater: the
+      # shell refuses to fetch it and silently stops checking, so the app ships
+      # looking fine and never updates again. Say so at build/publish time.
+      def updates_errors
+        url = updates_url.to_s
+        return [] if url.empty?
+
+        require "uri"
+        uri = URI.parse(url)
+        return [] if uri.scheme == "https"
+        return [] if uri.scheme == "http" && uri.host.to_s.delete("[]").match?(UPDATES_LOOPBACK)
+
+        ["updates.url #{url.inspect} must be https — the shell disables the updater otherwise"]
+      rescue URI::Error => e
+        ["updates.url #{url.inspect} is not a URL (#{e.message})"]
+      end
+
+      # The client subset for the shell; nil (and thus absent from
+      # everywhere.json) until both url and public_key are configured — an
+      # unsigned update feed is not a thing.
+      def updates_shell_hash
+        return nil unless updates_url && updates_public_key
+
+        {
+          "url" => updates_url,
+          "channel" => updates_channel,
+          "public_key" => updates_public_key,
+          "auto" => updates_auto,
+          "interval" => updates_interval
+        }
+      end
+    end
+  end
+end