ruby_everywhere 0.3.0 → 0.4.0

data/lib/everywhere/builders/android.rb

@@ -0,0 +1,844 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "set"
+require_relative "../paths"
+require_relative "../shellout"
+require_relative "../log_filter"
+require_relative "../icon"
+require_relative "../android_resources"
+require_relative "../android_sdk"
+require_relative "../version"
+require_relative "../ui"
+
+module Everywhere
+  module Builders
+    # Assembles a Hotwire Native Android app around an already-deployed (remote
+    # mode) app — the Android half of Builders::Ios, and deliberately the same
+    # five steps: copy the gem's frozen Gradle template, stamp an explicit list
+    # of per-app files (never a build script), and hand it to Gradle.
+    #
+    # The stamped list, and nothing else:
+    #
+    #   app/everywhere.properties                       identity (app/build.gradle.kts reads it)
+    #   app/native-packages.gradle.kts                  native.android.packages
+    #   app/src/stamped/AndroidManifest.xml             deep links, auth scheme, permissions
+    #   app/src/main/assets/everywhere.json             Config#to_shell_json
+    #   app/src/main/assets/json/path-configuration.json baked tabs + rules
+    #   app/src/main/assets/fonts/                      the selected Material icon font
+    #   app/src/main/res/values/colors.xml              tint / background, light (replaced in place)
+    #   app/src/main/res/values-night/colors.xml        tint / background, dark
+    #   app/src/main/res/mipmap-*/                      launcher icon layers + anydpi-v26
+    #   app/src/stamped/res/drawable*/                  native/android/assets/** as drawables
+    #   app/src/main/java/com/rubyeverywhere/shell/extensions/   native/android/*.kt + registry
+    #
+    # MVP scope is a debug/unsigned-release APK. Keystore signing, AAB and Play
+    # upload hang off the same seam later — see docs/android-plan.md §9.
+    class Android
+      # Fixed by the template contract: one Gradle module, always :app, so
+      # build paths and task names never depend on per-app values.
+      GRADLE_MODULE = ":app"
+
+      # The Kotlin package the shell's sources live in. NOT the applicationId:
+      # the app id is stamped per app, the code's package is frozen, and mixing
+      # them up is the classic Android manifest mistake — so anything we
+      # generate that names a class spells the package out in full.
+      SHELL_PACKAGE = "com.rubyeverywhere.shell"
+      EXTENSIONS_PACKAGE = "#{SHELL_PACKAGE}.extensions"
+
+      # The activity every stamped intent-filter attaches to. Its <activity>
+      # element already exists in the frozen main manifest; the stamped source
+      # set only adds filters to it.
+      MAIN_ACTIVITY = "#{SHELL_PACKAGE}.MainActivity"
+
+      # google/material-design-icons, pinned by commit for the same reason the
+      # iOS side pins Package.resolved: an icon set that silently changes under
+      # a cached build is a rendering bug nobody can reproduce. Each entry
+      # carries the SHA-256 of both files, so a corrupted or substituted
+      # download fails loudly instead of shipping.
+      ICON_FONT_COMMIT = "528cb964c01fb2b09bc3b9208f82b6d8f8c1c1e2"
+      ICON_FONT_BASE = "https://raw.githubusercontent.com/google/material-design-icons"
+
+      # Keyed by the asset filename Config::ANDROID_ICON_FONTS names; "path" is
+      # the repo path without an extension (upstream spells the variable fonts
+      # with their axis list in brackets — we ship them under the plain name the
+      # shell asks Typeface for).
+      FETCHED_ICON_FONTS = {
+        "MaterialSymbolsOutlined.ttf" => {
+          "path" => "variablefont/MaterialSymbolsOutlined[FILL,GRAD,opsz,wght]",
+          "ttf" => "b5126c4655e0756f334d684104156b98b82ef7d61212a81c041b9e6cfa8ba925",
+          "codepoints" => "8567a3d0512ce8a735a739d325e83ee7010d9bf7f6f8ed6a699c07c817ea907d"
+        },
+        "MaterialSymbolsRounded.ttf" => {
+          "path" => "variablefont/MaterialSymbolsRounded[FILL,GRAD,opsz,wght]",
+          "ttf" => "8817f9df195b582d45a6031c1d9e1533595dd7a6f0e76abc309bdc3cc4d72ee1",
+          "codepoints" => "8567a3d0512ce8a735a739d325e83ee7010d9bf7f6f8ed6a699c07c817ea907d"
+        },
+        "MaterialSymbolsSharp.ttf" => {
+          "path" => "variablefont/MaterialSymbolsSharp[FILL,GRAD,opsz,wght]",
+          "ttf" => "c56a37227b580aa30bcbf352a770a2598dc86bca43bf060ff8d0550c081827e6",
+          "codepoints" => "8567a3d0512ce8a735a739d325e83ee7010d9bf7f6f8ed6a699c07c817ea907d"
+        }
+      }.freeze
+
+      # Where the bundled (classic) font sits inside the template. Two spellings
+      # because the template ships it as the default asset, and a template that
+      # keeps its fonts out of assets/ still resolves.
+      BUNDLED_FONT_DIRS = [%w[app src main assets fonts], %w[fonts]].freeze
+
+      # Marks which template a work dir was staged from. A gem upgrade can add,
+      # rename or delete template files, and staging merges rather than wipes
+      # (see #stage), so a stale Kotlin file from an older template would keep
+      # compiling in. Version mismatch = wipe once, then merge as usual.
+      STAGE_MARKER = ".everywhere-template"
+
+      # What AGP accepts as an applicationId: two or more segments, each a Java
+      # identifier starting with a letter. No hyphens, unlike a bundle id.
+      APPLICATION_ID = /\A[a-zA-Z]\w*(\.[a-zA-Z]\w*)+\z/
+
+      def initialize(config:, root:, target:, template_dir: nil)
+        @config = config
+        @root = root
+        @target = target
+        @template_dir = template_dir
+      end
+
+      # Build the APK and copy it into dist_dir. `dev` builds the debug variant
+      # and relaxes the remote-mode requirement (the dev URL is stamped into a
+      # debug asset each run — Android has no SIMCTL_CHILD_* equivalent).
+      # Returns the path of the collected APK.
+      def build!(dist_dir:, dev: false, dev_url: nil)
+        # The template is resolved before preflight, not after it like iOS:
+        # preflight has to settle the icon font, and the bundled font lives in
+        # the template. Everything that can fail slowly (a font download) or
+        # cheaply (a typo'd icon name) is therefore decided before Gradle — the
+        # difference between a 5-second error and one that lands 90 seconds in.
+        template = @template_dir ? File.expand_path(@template_dir) : Paths.android_dir!
+        preflight!(dev: dev, template: template)
+        work = stage(template)
+        stamp!(work)
+        stamp_dev_url!(work, dev_url)
+        variant = dev ? "debug" : "release"
+        gradle!(work, variant, dist_dir)
+        collect(work, variant, dist_dir)
+      end
+
+      private
+
+      def name = @config.name(target: @target)
+      def application_id = @config.bundle_id(target: @target)
+
+      # The dev-server URL, for the debug source set only (EverywhereConfig's
+      # devUrl reads it, and release builds never look). This is the whole of
+      # Android's answer to SIMCTL_CHILD_EVERYWHERE_DEV_URL: there is no launch
+      # environment to read, so the URL is baked — which also makes it survive a
+      # relaunch from the launcher, the case iOS papers over with UserDefaults.
+      #
+      # Always rewritten, and REMOVED when there's no dev URL: a stale file from
+      # yesterday's `every dev` would otherwise quietly point a plain
+      # `every build --android` debug APK at a laptop that isn't listening.
+      def stamp_dev_url!(work, dev_url)
+        asset = File.join(work, "app", "src", "debug", "assets", "dev-url.txt")
+        unless dev_url
+          FileUtils.rm_f(asset)
+          return
+        end
+
+        FileUtils.mkdir_p(File.dirname(asset))
+        File.write(asset, "#{dev_url}\n")
+        UI.step("pointing the shell at #{UI.cyan(dev_url)}")
+      end
+
+      def preflight!(dev:, template:)
+        # Config shape first, machine state second: a typo in everywhere.yml is
+        # the app author's to fix wherever they are, while "no Android SDK"
+        # depends on the machine they happen to be sitting at.
+        errors = @config.native_android_errors
+        UI.die!("native.android in config/everywhere.yml:\n#{errors.join("\n")}") unless errors.empty?
+
+        unless dev || @config.remote?
+          UI.die!("Android apps are remote mode only for now — set remote.url in config/everywhere.yml " \
+                  "(the shell wraps your deployed app; nothing is packaged locally)")
+        end
+
+        # AGP rejects an applicationId that isn't two-or-more dot-separated
+        # Java identifiers — and the default derived from the app's name
+        # ("com.rubyeverywhere.my-notes") is exactly the shape it rejects,
+        # because a hyphen is legal in a macOS bundle id and never in a
+        # package name. Caught here so the answer is a config key, not a
+        # Gradle stacktrace.
+        unless application_id.match?(APPLICATION_ID)
+          UI.die!("#{application_id.inspect} can't be an Android applicationId — it needs two or " \
+                  "more dot-separated segments of letters, digits and _, each starting with a " \
+                  "letter. Set platforms.android.bundle_id in config/everywhere.yml")
+        end
+
+        # Resolve by location, never off PATH: Android Studio provisions the
+        # whole toolchain and exports none of it, so `which adb` reports a
+        # broken machine that in fact builds fine. Each of these names its own
+        # fix — the analogue of the iOS xcode-select message.
+        @sdk_root = AndroidSdk.sdk_root!
+        @java_home = AndroidSdk.java_home!
+        AndroidSdk.adb!
+        # A missing compile SDK surfaces from Gradle as "Failed to find target
+        # with hash string android-35", minutes in and after the AGP download.
+        AndroidSdk.platform!
+        report_tab_overflow!
+        resolve_icon_font!(template)
+      end
+
+      # Copy the template into the app's persistent work dir. Merged over
+      # whatever is already there, NOT wiped like the iOS stage: Gradle's
+      # incremental state (app/build/, .gradle/) lives *inside* this directory,
+      # and a cold build is 1m37s against a warm one's 7s. The two dirs the
+      # stamp regenerates wholesale (extensions/, assets/fonts/) are cleared by
+      # their own writers, so nothing accumulates there either.
+      def stage(template)
+        work = Paths.android_work_dir(application_id)
+        FileUtils.rm_rf(work) unless staged_version(work) == Everywhere::VERSION
+        FileUtils.mkdir_p(work)
+        FileUtils.cp_r(File.join(template, "."), work)
+        # A gem install doesn't reliably preserve the executable bit, and a
+        # non-executable gradlew fails with a bare "Permission denied".
+        wrapper = File.join(work, "gradlew")
+        FileUtils.chmod("u+x", wrapper) if File.file?(wrapper)
+        File.write(File.join(work, STAGE_MARKER), "#{Everywhere::VERSION}\n")
+        work
+      end
+
+      def staged_version(work)
+        marker = File.join(work, STAGE_MARKER)
+        File.read(marker).strip if File.file?(marker)
+      end
+
+      # The whole per-app surface: identity properties, two JSON assets, colors,
+      # launcher icons, the icon font, the merged-in manifest, the Extensions
+      # sources + generated registry, and the Maven coordinate script. No build
+      # script and no layout is ever touched — that half of the freeze contract
+      # is what lets the template be tested standalone.
+      def stamp!(work)
+        UI.step("stamping shell #{UI.dim("(#{application_id} → #{UI.short_path(work)})")}")
+        write_properties(work)
+        assets = File.join(work, "app", "src", "main", "assets")
+        FileUtils.mkdir_p(File.join(assets, "json"))
+        File.write(File.join(assets, "everywhere.json"), @config.to_shell_json(target: @target))
+        # Same document MobileConfigEndpoint serves live — this baked copy is
+        # the offline/first-launch fallback the shell loads synchronously.
+        File.write(File.join(assets, "json", "path-configuration.json"),
+                   @config.path_configuration_json("android"))
+        write_colors(work)
+        write_launcher_icons(work)
+        write_drawables(work)
+        write_icon_font(work)
+        write_manifest(work)
+        write_extensions(work)
+        write_native_packages(work)
+      end
+
+      # --- identity -------------------------------------------------------------
+
+      # app/build.gradle.kts reads these four values, so identity is stamped
+      # without ever editing a build script — the direct analogue of the iOS
+      # App.xcconfig. The `everywhere.` prefix is the template's namespace:
+      # its stamped(key) helper looks up "everywhere.$key", and the label
+      # travels on to the frozen manifest as a placeholder.
+      def write_properties(work)
+        File.write(File.join(work, "app", "everywhere.properties"), <<~PROPERTIES)
+          # Written by `every build --target #{@target}` — do not edit; changes
+          # belong in config/everywhere.yml.
+          everywhere.applicationId=#{properties_value(application_id)}
+          everywhere.versionName=#{properties_value(@config.version(target: @target))}
+          everywhere.versionCode=#{version_code}
+          everywhere.label=#{properties_value(name)}
+        PROPERTIES
+      end
+
+      # Play rejects an upload whose versionCode isn't higher than the last, so
+      # deriving it from the version the app already maintains beats asking for
+      # a second number nobody remembers to bump. 1.2.3 → 10203, which stays
+      # monotonic as long as minor/patch stay under 100.
+      def version_code
+        major, minor, patch = @config.version(target: @target).to_s.split(".").map(&:to_i)
+        code = ((major || 0) * 10_000) + ((minor || 0) * 100) + (patch || 0)
+        [code, 1].max
+      end
+
+      # java.util.Properties reads a byte stream as ISO-8859-1 and treats
+      # `=`, `:`, `#`, `!` and backslash as syntax — so an app called
+      # "Café: Notes" would arrive mangled or split. \uXXXX escapes are the one
+      # spelling that survives both, whatever charset the build script reads with.
+      def properties_value(value)
+        value.to_s.gsub(/[\\=:#!]/) { |c| "\\#{c}" }
+             .gsub(/[^\x20-\x7E]/) { |c| format("\\u%04X", c.ord) }
+      end
+
+      # --- resources ------------------------------------------------------------
+
+      # appearance.tint_color / background_color → the two colors the frozen
+      # themes derive everything else from, in both appearances: the light half
+      # in values/colors.xml, the dark half in values-night/colors.xml, under
+      # the same resource names (that IS the mechanism — the resource system
+      # picks the file, not the name).
+      #
+      # Values are replaced *in place* rather than the files being rewritten
+      # (the Info.plist plutil -replace pattern), because each file also carries
+      # derived colors — on_tint, error, transparent — that are the template's
+      # to own, and the template's own defaults are the right answer for
+      # anything the app didn't declare.
+      def write_colors(work)
+        tint = @config.tint_color
+        background = @config.background_color
+        return if tint.nil? && background.nil?
+
+        values = File.join(work, "app", "src", "main", "res")
+        { "values" => "light", "values-night" => "dark" }.each do |dir, appearance|
+          colors = { "everywhere_tint" => tint&.fetch(appearance, nil),
+                     "everywhere_background" => background&.fetch(appearance, nil) }
+
+          path = File.join(values, dir, "colors.xml")
+          xml = File.file?(path) ? File.read(path) : "<resources>\n</resources>\n"
+          colors.each do |resource, value|
+            hex = Icon.hex_rgb(value) or next
+
+            xml = replace_color(xml, resource, format("#%02X%02X%02X", *hex))
+          end
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, xml)
+        end
+      end
+
+      def replace_color(xml, resource, hex)
+        pattern = %r{(<color\s+name="#{Regexp.escape(resource)}"[^>]*>)[^<]*(</color>)}
+        return xml.sub(pattern, "\\1#{hex}\\2") if xml.match?(pattern)
+
+        xml.sub(%r{</resources>}, "    <color name=\"#{resource}\">#{hex}</color>\n</resources>")
+      end
+
+      def write_launcher_icons(work)
+        source = @config.icon
+        unless source && File.exist?(source)
+          UI.warn "no app icon (set app.icon or add icon.png) — shipping the placeholder"
+          return
+        end
+
+        background = Icon.hex_rgb(@config.background_color&.fetch("light", nil))
+        res = File.join(work, "app", "src", "main", "res")
+        return if Icon.write_android_mipmaps(source, res, background: background)
+
+        UI.warn "couldn't read #{File.basename(source)} — shipping the placeholder icon"
+      end
+
+      # App-supplied images: native/android/assets/** → drawable resources, so
+      # native/android Kotlin reaches them by name with R.drawable.logo. The iOS
+      # analogue is write_asset_catalog, and the filename API is identical.
+      #
+      # They land in their own source set (src/stamped/res, registered as a res
+      # srcDir by the frozen build script) rather than in main/res, for the
+      # reason the manifest does: the whole directory can be regenerated
+      # wholesale — an asset the app deleted must stop shipping — and staging
+      # merges rather than wipes, so anything written into main/res would
+      # survive its source file being removed. Cleared unconditionally, before
+      # the early return, so dropping the assets/ dir entirely also takes
+      # yesterday's drawables with it.
+      def write_drawables(work)
+        dest = File.join(work, "app", "src", "stamped", "res")
+        FileUtils.rm_rf(dest)
+
+        source = File.join(@root, "native", "android", "assets")
+        return unless File.directory?(source)
+
+        names, errors = AndroidResources.write!(source, dest)
+        UI.die!("native/android/assets:\n#{errors.join("\n")}") unless errors.empty?
+        return if names.empty?
+
+        listed = names.length > 6 ? "#{names.take(6).join(", ")}, …" : names.join(", ")
+        UI.step("bundling image assets #{UI.dim("(#{names.length} from native/android/assets: #{listed})")}")
+      end
+
+      # --- tabs -----------------------------------------------------------------
+
+      # Material's bottom navigation holds five destinations and no more, and
+      # unlike iOS's UITabBarController it synthesises nothing past that. The
+      # shell hand-builds the analogue: from the sixth tab on, the last bar slot
+      # becomes "More" and everything from the fifth tab onwards opens from a
+      # sheet behind it, badges included (More's badge is their sum).
+      BAR_SLOTS = 5
+
+      # Slots left for tabs of their own once More claims one.
+      BAR_TABS_WITH_MORE = BAR_SLOTS - 1
+
+      # Where a More sheet stops being a menu and starts being a scroll. Well
+      # clear of the ten a large app plausibly declares: the point is to catch a
+      # tabs: list that grew by accident, not to second-guess a deliberate one.
+      CROWDED_TABS = 15
+
+      # Nothing is dropped, so this is a note about layout rather than a
+      # warning about loss — but the layout is different enough from iOS's, and
+      # from what the config looks like, to be worth stating before a device
+      # shows it.
+      def report_tab_overflow!
+        tabs = @config.tabs_for("android")
+        return if tabs.length <= BAR_SLOTS
+
+        overflow = tabs.drop(BAR_TABS_WITH_MORE).map { |tab| tab["title"] }
+        UI.detail "#{tabs.length} tabs: Android's bar holds #{BAR_TABS_WITH_MORE} plus a \"More\" tab — " \
+                  "#{overflow.map(&:inspect).join(", ")} open from there (iOS does the same past five)"
+
+        return if tabs.length <= CROWDED_TABS
+
+        UI.warn "#{overflow.length} tabs behind \"More\" is a long list to scroll on a phone — " \
+                "consider moving the rarer ones into the app's own navigation"
+      end
+
+      # --- icon font ------------------------------------------------------------
+
+      # Settle which font ships and prove every declared icon name exists in it,
+      # before anything slow starts. Two failure modes this ordering exists for:
+      # a fetch that can't reach the network (say so now, name the offline
+      # answer) and a typo'd icon name (fails here naming the tab, instead of
+      # rendering a blank icon on a device).
+      def resolve_icon_font!(template)
+        file = @config.native_android_icon_font_file
+        @icon_font = nil
+        return unless file # icon_font: none — the app brings its own drawables
+
+        @icon_font = if @config.native_android_icon_font_fetched?
+                       fetch_icon_font!(file)
+                     else
+                       bundled_icon_font!(template, file)
+                     end
+        validate_icon_names!(@icon_font)
+      end
+
+      def bundled_icon_font!(template, file)
+        codepoints = @config.native_android_icon_font_codepoints
+        dir = BUNDLED_FONT_DIRS.map { |parts| File.join(template, *parts) }
+                               .find { |candidate| File.file?(File.join(candidate, file)) }
+        unless dir
+          UI.die!("the Android template has no #{file} — reinstall ruby_everywhere, or set " \
+                  "native.android.icon_font: symbols in config/everywhere.yml to fetch one instead")
+        end
+
+        { "file" => file, "ttf" => File.join(dir, file), "codepoints" => File.join(dir, codepoints) }
+      end
+
+      # The Symbols fonts are 8.8–15 MB, which is why they aren't in a 229 KB
+      # gem: they're fetched once and reused by every later build of every app.
+      # Existence at the cache path IS the proof of integrity — #fetch! renames
+      # into place only after the SHA-256 matches, so a half-finished or
+      # tampered download never becomes the cache, and no build after the first
+      # pays to re-hash 10 MB.
+      def fetch_icon_font!(file)
+        pin = FETCHED_ICON_FONTS.fetch(file)
+        dir = Paths.android_fonts_dir
+        ttf = File.join(dir, file)
+        codepoints = File.join(dir, @config.native_android_icon_font_codepoints)
+        resolved = { "file" => file, "ttf" => ttf, "codepoints" => codepoints }
+        return resolved if File.file?(ttf) && File.file?(codepoints)
+
+        FileUtils.mkdir_p(dir)
+        UI.step("fetching the #{@config.native_android_icon_font} icon font " \
+                "#{UI.dim("(one time, cached in #{UI.short_path(dir)})")}")
+        self.class.fetch!(icon_font_url(pin["path"], ".ttf"), ttf, sha256: pin["ttf"])
+        self.class.fetch!(icon_font_url(pin["path"], ".codepoints"), codepoints, sha256: pin["codepoints"])
+        resolved
+      rescue StandardError => e
+        UI.die!("couldn't fetch the #{@config.native_android_icon_font} icon font (#{e.message}) — " \
+                "set native.android.icon_font: classic in config/everywhere.yml to use the 2,235-icon " \
+                "set bundled in the gem, which needs no download and works offline")
+      end
+
+      # The upstream filenames carry their variable-axis list in brackets —
+      # "MaterialSymbolsOutlined[FILL,GRAD,opsz,wght].ttf". Percent-encoded by
+      # hand rather than through URI.escape, whose default unsafe set leaves
+      # brackets and commas alone: those are exactly the three characters here.
+      def icon_font_url(path, extension)
+        encoded = "#{path}#{extension}".gsub(/[\[\],]/) { |char| format("%%%02X", char.ord) }
+        "#{ICON_FONT_BASE}/#{ICON_FONT_COMMIT}/#{encoded}"
+      end
+
+      # Download to a sibling .part file, verify, then rename — the atomicity
+      # the cache-hit rule above depends on. A class method so tests (and the
+      # offline path) have one seam to stub instead of a live socket.
+      def self.fetch!(url, dest, sha256:, redirects: 3)
+        require "net/http"
+        require "uri"
+        require "digest"
+
+        uri = URI.parse(url)
+        part = "#{dest}.part"
+        Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http.request(Net::HTTP::Get.new(uri)) do |response|
+            case response
+            when Net::HTTPRedirection
+              raise "too many redirects for #{url}" if redirects <= 0
+
+              return fetch!(response["location"], dest, sha256: sha256, redirects: redirects - 1)
+            when Net::HTTPSuccess
+              File.open(part, "wb") { |f| response.read_body { |chunk| f.write(chunk) } }
+            else
+              raise "HTTP #{response.code} for #{url}"
+            end
+          end
+        end
+
+        digest = Digest::SHA256.file(part).hexdigest
+        raise "#{File.basename(dest)} checksum mismatch (got #{digest[0, 12]}…)" unless digest == sha256
+
+        File.rename(part, dest)
+        dest
+      ensure
+        FileUtils.rm_f("#{dest}.part")
+      end
+
+      # Every declared icons.android name must exist in the font that ships, or
+      # the tab renders blank on device with nothing in the log to explain it.
+      # Checked against the .codepoints file *shipped beside the .ttf*: 282
+      # names exist in both fonts at different codepoints, so the pair has to
+      # stay together.
+      def validate_icon_names!(font)
+        names = codepoint_names(font["codepoints"])
+        # Only the variable Symbols fonts carry an fvar/FILL axis; the classic
+        # set has no fvar at all, so `favorite.fill` there can only ever render
+        # the outline — better to say so than to ship a lie.
+        fillable = @config.native_android_icon_font_fetched?
+
+        problems = @config.tabs_for("android").filter_map do |tab|
+          icon = tab["icon"].to_s
+          base = icon.sub(/\.fill\z/, "")
+          if base != icon && !fillable
+            "tab #{tab["title"].inspect}: #{icon.inspect} — icon_font: #{@config.native_android_icon_font} " \
+              "has no FILL axis; use #{base.inspect}, or switch to icon_font: symbols"
+          elsif !names.include?(base)
+            "tab #{tab["title"].inspect}: #{icon.inspect} isn't an icon in #{font["file"]}"
+          end
+        end
+        return if problems.empty?
+
+        UI.die!("icons.android in config/everywhere.yml (#{names.size} icons in " \
+                "#{font["file"]} — browse them at https://fonts.google.com/icons):\n#{problems.join("\n")}")
+      end
+
+      # "name<space>hex" per line. Parsed in Ruby rather than shelled out to awk
+      # (macOS awk has no strtonum) and stored as a name set: the codepoint
+      # itself is the shell's business, ours is only "does this name exist".
+      def codepoint_names(path)
+        return Set.new unless File.file?(path)
+
+        File.readlines(path).each_with_object(Set.new) do |line, set|
+          name = line.split(/\s+/).first
+          set << name unless name.nil? || name.empty?
+        end
+      end
+
+      # Exactly one font ships. The dir is cleared first because the template
+      # carries the bundled classic set as its default — an app on `symbols`
+      # would otherwise pay 357 KB for a font it never reads, and an app on
+      # `none` would ship one it explicitly declined.
+      def write_icon_font(work)
+        dest = File.join(work, "app", "src", "main", "assets", "fonts")
+        FileUtils.mkdir_p(dest)
+        Dir.glob(File.join(dest, "*.{ttf,otf,codepoints}")).each { |stale| FileUtils.rm_f(stale) }
+        return unless @icon_font
+
+        FileUtils.cp(@icon_font["ttf"], File.join(dest, @icon_font["file"]))
+        FileUtils.cp(@icon_font["codepoints"],
+                     File.join(dest, @config.native_android_icon_font_codepoints))
+      end
+
+      # --- manifest -------------------------------------------------------------
+
+      # Deep links, the auth callback scheme and runtime permissions go into a
+      # separate `stamped` source set that the manifest merger folds in, so the
+      # main manifest stays frozen and the default build stays clean — the
+      # analogue of the optional iOS App.entitlements. Unlike that file this one
+      # is always written: the frozen build script declares the source set, and
+      # a declared manifest that isn't there fails the merge.
+      def write_manifest(work)
+        errors = @config.permission_errors("android") + @config.auth_errors
+        UI.die!("config/everywhere.yml:\n#{errors.join("\n")}") unless errors.empty?
+
+        body = [permission_elements, activity_element].compact.join("\n\n")
+        path = File.join(work, "app", "src", "stamped", "AndroidManifest.xml")
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, <<~XML)
+          <?xml version="1.0" encoding="utf-8"?>
+          <!-- Written by `every build` for target #{@target} from config/everywhere.yml.
+               Do not edit; this source set is merged into app/src/main/AndroidManifest.xml.
+               Note for whoever edits this header next: XML forbids a double hyphen
+               anywhere inside a comment, so the flag spelling of the target must not
+               appear here. aapt2 does not warn — the manifest merger just fails to
+               parse the file, minutes into a Gradle run. -->
+          <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+          #{body.empty? ? "    <!-- nothing declared: no permissions, deep links or sign-in scheme -->" : body}
+          </manifest>
+        XML
+      end
+
+      def permission_elements
+        entries = @config.android_manifest_permissions
+        return nil if entries.empty?
+
+        entries.map { |entry| "    <uses-permission android:name=\"#{entry}\" />" }.join("\n")
+      end
+
+      # Both filter kinds hang off MainActivity: it's the activity the launcher
+      # starts and the one the shell routes URLs through, so a link and a
+      # sign-in callback arrive at the same place a cold start would.
+      def activity_element
+        filters = [deep_link_filters, auth_filter].compact
+        return nil if filters.empty?
+
+        ["    <application>",
+         "        <activity android:name=\"#{MAIN_ACTIVITY}\">",
+         filters.join("\n"),
+         "        </activity>",
+         "    </application>"].join("\n")
+      end
+
+      # autoVerify makes Android fetch /.well-known/assetlinks.json (which the
+      # gem already serves) and open matching links straight in the app, with no
+      # chooser. Verification failing is not fatal — the links simply keep
+      # opening in the browser — so the filter is stamped whenever deep linking
+      # is configured at all, and the missing Android half is a warning.
+      def deep_link_filters
+        domains = @config.deep_linking_domains
+        return nil unless @config.deep_linking? && domains.any?
+
+        UI.step("stamping deep links #{UI.dim("(#{domains.join(", ")})")}")
+        unless @config.deep_linking_android?
+          UI.warn "deep links won't auto-verify until deep_linking.android.package and " \
+                  ".sha256_cert_fingerprints are set — until then they open in the browser"
+        end
+
+        domains.map do |host|
+          ["            <intent-filter android:autoVerify=\"true\">",
+           "                <action android:name=\"android.intent.action.VIEW\" />",
+           "                <category android:name=\"android.intent.category.DEFAULT\" />",
+           "                <category android:name=\"android.intent.category.BROWSABLE\" />",
+           "                <data android:scheme=\"https\" android:host=\"#{xml_attr(host)}\"#{path_attribute} />",
+           "            </intent-filter>"].join("\n")
+        end.join("\n")
+      end
+
+      # deep_linking.paths is written in Apple's component syntax; Android wants
+      # one of path / pathPrefix / pathPattern. Only the two shapes that
+      # translate exactly are translated — "/*" (and the default "*") mean every
+      # path, which on Android is simply no path attribute at all.
+      def path_attribute
+        paths = @config.deep_linking_paths
+        return "" if paths.length != 1 || ["*", "/*"].include?(paths.first)
+
+        path = xml_attr(paths.first)
+        path.end_with?("*") ? " android:pathPrefix=\"#{path.chomp("*")}\"" : " android:path=\"#{path}\""
+      end
+
+      # Hosts and paths are app-authored strings landing in XML attributes;
+      # everything else stamped into the manifest comes from a fixed map or a
+      # validated pattern. A quote here would rewrite the element, so escape the
+      # five characters that can.
+      def xml_attr(value)
+        value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+             .gsub('"', "&quot;").gsub("'", "&apos;")
+      end
+
+      # The custom scheme third-party sign-in returns through (everywhere.yml
+      # auth:). The Custom Tab hands the callback back by Intent, so unlike iOS
+      # — where ASWebAuthenticationSession claims the callback itself — this
+      # registration is what actually makes the return leg work.
+      def auth_filter
+        return nil unless @config.oauth?
+
+        scheme = @config.auth_scheme
+        UI.step("stamping sign-in callback scheme #{UI.dim("(#{scheme}://)")}")
+        ["            <intent-filter>",
+         "                <action android:name=\"android.intent.action.VIEW\" />",
+         "                <category android:name=\"android.intent.category.DEFAULT\" />",
+         "                <category android:name=\"android.intent.category.BROWSABLE\" />",
+         "                <data android:scheme=\"#{scheme}\" />",
+         "            </intent-filter>"].join("\n")
+      end
+
+      # --- native extensions ----------------------------------------------------
+
+      # The app repo's native/android/*.kt copied into the template's
+      # extensions/ package, plus a generated registry naming what
+      # everywhere.yml declares (native.android). The package is a plain source
+      # directory in the frozen module, so dropping files in IS the integration
+      # — the stamp-only contract holds.
+      def write_extensions(work)
+        dest = File.join(work, "app", "src", "main", "java", *SHELL_PACKAGE.split("."), "extensions")
+        # Regenerated wholesale: a .kt the app deleted must stop compiling in.
+        FileUtils.rm_rf(dest)
+        FileUtils.mkdir_p(dest)
+
+        source = File.join(@root, "native", "android")
+        sources = File.directory?(source) ? Dir.glob(File.join(source, "**", "*.kt")).sort : []
+        sources.each do |file|
+          relative = file.delete_prefix("#{source}/")
+          if File.basename(file) == "EverywhereExtensions.kt"
+            UI.die!("native/android/#{relative}: EverywhereExtensions.kt is generated by " \
+                    "`every build` — declare your types under native.android in config/everywhere.yml instead")
+          end
+          check_package!(file, relative)
+          target_file = File.join(dest, relative)
+          FileUtils.mkdir_p(File.dirname(target_file))
+          FileUtils.cp(file, target_file)
+        end
+
+        if @config.native_android?
+          UI.step("bundling native extensions #{UI.dim("(#{sources.length} Kotlin files from native/android)")}")
+        elsif sources.any?
+          UI.warn "native/android has Kotlin files but everywhere.yml declares nothing under " \
+                  "native.android — they compile in, but no components/screens/splash are hooked up"
+        end
+        File.write(File.join(dest, "EverywhereExtensions.kt"), extensions_registry)
+      end
+
+      # The generated registry names app types unqualified, so they have to
+      # compile into the same package it does. Kotlin doesn't tie a package to a
+      # directory, so the copy alone can't establish it — and a file with no
+      # `package` line lands in the default package, which nothing outside it can
+      # import at all. Both mistakes surface from Kotlin as "unresolved
+      # reference: AboutFragment" pointing at generated code the author never
+      # wrote, so they're caught here instead, naming the line to add.
+      #
+      # No Swift equivalent: Swift has no package declaration, which is why the
+      # iOS side of this seam needs nothing.
+      def check_package!(file, relative)
+        declared = File.foreach(file).lazy
+                       .filter_map { |line| line[/\A\s*package\s+([\w.]+)/, 1] }
+                       .first
+        return if declared == EXTENSIONS_PACKAGE
+
+        found = declared ? "declares package #{declared}" : "declares no package"
+        UI.die!("native/android/#{relative} #{found} — every Kotlin file here compiles into the " \
+                "shell's extension package, so it has to start with:\n\n  package #{EXTENSIONS_PACKAGE}\n")
+      end
+
+      # The generated half of the extension seam — member for member the shape
+      # the template ships as its empty default, because EverywhereApplication
+      # and MainActivity read these three names directly. Declared types are
+      # validated as Kotlin identifiers in preflight, so interpolation is safe;
+      # a declared-but-missing type fails the build with a Kotlin error naming
+      # it — the honest signal, exactly as on iOS.
+      def extensions_registry
+        components = @config.native_android_components
+        # A screen's identifier lives in the Fragment's own
+        # @HotwireDestinationDeepLink annotation ("hotwire://fragment/<id>"),
+        # so Hotwire only needs the classes; everywhere.yml keeps the ids to
+        # document and validate what the path rules may point at.
+        screens = @config.native_android_screens.values.uniq
+        splash = @config.native_android_splash
+
+        <<~KOTLIN
+          // Written by `every build` from config/everywhere.yml (native.android) — do
+          // not edit; changes belong in native/android/ and everywhere.yml.
+          //
+          // A declared component is registered under the name its own class states:
+          //
+          //   class ChartComponent(name: String, delegate: BridgeDelegate<HotwireDestination>) :
+          //       BridgeComponent<HotwireDestination>(name, delegate) {
+          //       companion object { const val NAME = "chart" }   // matches the JS side
+          //   }
+          package #{EXTENSIONS_PACKAGE}
+
+          import android.content.Context
+          import android.view.View
+          import androidx.fragment.app.Fragment
+          import dev.hotwire.core.bridge.BridgeComponent
+          import dev.hotwire.core.bridge.BridgeComponentFactory
+          import dev.hotwire.navigation.destinations.HotwireDestination
+          import kotlin.reflect.KClass
+
+          object EverywhereExtensions {
+              val bridgeComponents: List<BridgeComponentFactory<HotwireDestination, BridgeComponent<HotwireDestination>>> =
+                  #{kotlin_list(components.map { |type| "BridgeComponentFactory(#{type}.NAME, ::#{type})" })}
+
+              val fragmentDestinations: List<KClass<out Fragment>> =
+                  #{kotlin_list(screens.map { |type| "#{type}::class" })}
+
+              fun splashView(context: Context): View? = #{splash ? "#{splash}(context)" : "null"}
+          }
+        KOTLIN
+      end
+
+      # "emptyList()" or a listOf() with one element per line, indented to sit
+      # under the property it initializes.
+      def kotlin_list(elements)
+        return "emptyList()" if elements.empty?
+
+        "listOf(\n#{elements.map { |element| "            #{element}" }.join(",\n")}\n        )"
+      end
+
+      # Third-party Maven coordinates → a generated script the frozen
+      # app/build.gradle.kts applies. Written as `add("implementation", …)`
+      # rather than `implementation(…)`: the Kotlin DSL's typed accessors are
+      # generated for the build script itself, not for a script pulled in with
+      # apply(from = …), where only the DependencyHandler API exists.
+      # Coordinates are validated by Config#native_android_package_errors, so
+      # nothing here can escape its string literal.
+      def write_native_packages(work)
+        packages = @config.native_android_packages
+        lines = packages.map { |coordinate| "    add(\"implementation\", \"#{coordinate}\")" }
+        File.write(File.join(work, "app", "native-packages.gradle.kts"), <<~KOTLIN)
+          // Written by `every build` from config/everywhere.yml (native.android.packages)
+          // — do not edit; changes belong in config/everywhere.yml.
+          dependencies {
+          #{lines.join("\n")}
+          }
+        KOTLIN
+        return if packages.empty?
+
+        UI.step("pinning native packages #{UI.dim("(#{packages.length} Maven " \
+                "dependenc#{packages.length == 1 ? "y" : "ies"})")}")
+      end
+
+      # --- gradle ---------------------------------------------------------------
+
+      def gradle!(work, variant, dist_dir)
+        UI.step("building Android shell #{UI.dim("(Gradle, #{variant}, first run downloads " \
+                                                "Gradle and the Android Gradle Plugin)")}")
+        FileUtils.mkdir_p(dist_dir)
+        log = File.join(dist_dir, "android-build.log")
+        task = "#{GRADLE_MODULE}:assemble#{variant.capitalize}"
+        # -p instead of a chdir: the wrapper finds its own jar from $0, so an
+        # absolute gradlew with an explicit project dir works from anywhere
+        # (Shellout.run_logged! has no chdir). --console=plain keeps the stream
+        # line-oriented for LogFilter whether or not a TTY is attached.
+        Shellout.run_logged!(gradle_env,
+                             [File.join(work, "gradlew"), "-p", work, "--console=plain", task],
+                             log: log, filter: LogFilter.for(:gradle))
+      end
+
+      # The whole toolchain is handed to Gradle explicitly. ANDROID_HOME is what
+      # AGP reads when there's no local.properties — and we never write one, so
+      # the stamped project stays clean and Android Studio can resolve its own
+      # SDK. GRADLE_USER_HOME redirects the 1.4 GB of Gradle distribution, AGP
+      # and Hotwire artifacts out of the gem and into a cache shared by every app.
+      def gradle_env
+        { "JAVA_HOME" => @java_home,
+          "ANDROID_HOME" => @sdk_root,
+          "ANDROID_SDK_ROOT" => @sdk_root,
+          "GRADLE_USER_HOME" => Paths.android_gradle_home }
+      end
+
+      # Copy the APK out of the module's build dir. Release is unsigned until
+      # keystore signing lands (docs/android-plan.md §9), and AGP spells that
+      # variant app-release-unsigned.apk — accept either name so the collect
+      # step doesn't have to be revisited when signing arrives.
+      def collect(work, variant, dist_dir)
+        dir = File.join(work, "app", "build", "outputs", "apk", variant)
+        built = ["app-#{variant}.apk", "app-#{variant}-unsigned.apk"]
+                .map { |file| File.join(dir, file) }
+                .find { |path| File.file?(path) }
+        UI.die!("Gradle reported success but no APK in #{UI.short_path(dir)}") unless built
+
+        dest = File.join(dist_dir, "#{name}.apk")
+        FileUtils.rm_f(dest)
+        FileUtils.cp(built, dest)
+        dest
+      end
+    end
+  end
+end