ruby_everywhere 0.3.0 → 0.4.0

data/lib/everywhere/log_filter.rb

@@ -30,6 +30,7 @@ module Everywhere
       when :notarize   then notarize(line)
       when :tebako     then tebako(line)
       when :xcodebuild then xcodebuild(line)
+      when :gradle     then gradle(line)
       end
     end
 
@@ -153,6 +154,79 @@ module Everywhere
       end
     end
 
+    # --- gradle (Android shell) -----------------------------------------------
+    #
+    # Gradle is the quiet one: a cold build is ~120 lines, ~83 of them
+    # "> Task :app:…". So this filter isn't fighting volume like the two above —
+    # it exists because of two specific noises that make a healthy build look
+    # broken. Gradle 9 ends every build with a four-line "incompatible with
+    # Gradle 10" deprecation banner earned by the Android Gradle Plugin, not by
+    # anything the user wrote; and hotwire-native-android 1.3.0 compiled with
+    # Kotlin 2.3.0 emits exactly 7 `w:` warnings from navigation-fragments
+    # (deprecated overrides, getParcelableArrayList, KT-73255) that no app can
+    # act on. Both are suppressed here and both stay in the on-disk log.
+    #
+    # The line that decides a warning's fate is its path: app-authored Kotlin is
+    # stamped into extensions/, and that's the only code the user can fix.
+    MILESTONES = {
+      /:process\w*Manifest\b/ => "merging manifests",
+      /:merge\w*Resources\b/ => "merging resources",
+      /:merge\w*Assets\b/ => "bundling assets",
+      /:compile\w*Kotlin\b/ => "compiling Kotlin",
+      /:compile\w*JavaWithJavac\b/ => "compiling Java",
+      /:package\w+\b/ => "packaging APK"
+    }.freeze
+
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+    def gradle(line)
+      short = UI.short_path(line)
+      case line
+      # Kotlin/javac/AAPT failures, and Gradle's own failure block.
+      when /\Ae: /, /\berror:/i, /\AFAILURE: /, /\A\* What went wrong:/, /\ABUILD FAILED/
+        "    #{UI.red(short)}"
+      when /\Aw: /
+        return "    #{UI.yellow(short)}" if line.include?("/extensions/")
+
+        once(:shell_warning) { UI.note_line("Kotlin warnings from the shell template — see the full log") }
+      when /\ABUILD SUCCESSFUL(?: in (.+))?/
+        UI.note_line("build succeeded#{Regexp.last_match(1) && " (#{Regexp.last_match(1)})"}",
+                     marker: "✓", color: :green)
+      when /\A\d+ actionable tasks?:/
+        UI.note_line(line)
+
+      # First-run downloads are the whole reason a cold build takes minutes.
+      when /\ADownloading https:\/\/services\.gradle\.org/
+        once(:gradle_dist) { UI.note_line("downloading Gradle (first run only)") }
+      when /\AStarting a Gradle Daemon/
+        once(:daemon) { UI.note_line("starting the Gradle daemon") }
+
+      # ~83 task lines. Milestones once each; the rest, including everything
+      # already up to date, is background.
+      when /\A> Task (\S+)/
+        task = Regexp.last_match(1)
+        return :drop if line.match?(/(UP-TO-DATE|FROM-CACHE|NO-SOURCE|SKIPPED)\s*\z/)
+
+        label = MILESTONES.find { |pattern, _| task.match?(pattern) }&.last or return :drop
+
+        once("task-#{label}") { UI.note_line(label) }
+
+      # Gradle 9's deprecation banner and its follow-on lines, the incubating
+      # problems report, the daemon's welcome, and any progress redraw that
+      # survives --console=plain.
+      when /Deprecated Gradle features were used in this build/,
+           /--warning-mode all/,
+           /\AFor more information[, ].*docs\.gradle\.org/,
+           /\A\[Incubating\] Problems report/,
+           /\AWelcome to Gradle /,
+           /\A<[=\-]+>/,
+           /\A> (Configure|Starting|Loading|Calculating|IDLE)/
+        :drop
+      else
+        nil # unrecognized -> caller shows it dimmed
+      end
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
+
     # Show a line only the first time its key is seen; :drop the repeats. Keeps a
     # long notarization from scrolling a wall of identical "waiting" lines (and
     # notarytool's thrice-echoed submission id from showing three times).

data/lib/everywhere/native_helper.rb

@@ -2,6 +2,7 @@
 
 require "erb"
 require "json"
+require_relative "config"
 
 module Everywhere
   # Server-side view helpers mirroring the JS bridge's platform detection, so
@@ -25,11 +26,7 @@ module Everywhere
     # :ios, :android, or nil in a plain browser. Reads Hotwire Native's UA
     # marker, so it's correct even before the JS bridge has booted.
     def native_platform
-      ua = _everywhere_user_agent or return nil
-      return :ios if ua.include?("Hotwire Native iOS")
-      return :android if ua.include?("Hotwire Native Android")
-
-      nil
+      Everywhere.native_platform_of(_everywhere_user_agent)
     end
 
     # The shell's version as a Gem::Version (from the "RubyEverywhere/<ver>"

data/lib/everywhere/omniauth.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "auth_handoff"
+
+module Everywhere
+  # OmniAuth 2 and the native sign-in flow, introduced to each other.
+  #
+  # Since CVE-2015-9284, OmniAuth only starts a provider flow from a POST
+  # carrying a CSRF token (omniauth-rails_csrf_protection). Right for browsers —
+  # and impossible for the native flow, which enters the provider path through
+  # /everywhere/auth/start's redirect: a GET, in a browser session that has no
+  # CSRF token to give. Without help, tapping "Sign in with GitHub" in the app
+  # ends on OmniAuth's failure page.
+  #
+  #   # config/initializers/omniauth.rb, after your provider setup
+  #   require "everywhere/omniauth"
+  #   Everywhere::OmniAuth.protect!
+  #
+  # Browsers keep exactly the validation they had — whatever
+  # request_validation_phase was set to keeps running. The one extra shape
+  # allowed through is the native flow's entry: a top-level, not-cross-site GET
+  # carrying a marker cookie that /everywhere/auth/start sealed seconds ago.
+  # Nobody else can mint that marker (AES-GCM under the app's secret), start
+  # refuses cross-site initiators outright, and the freshness window means a
+  # marker lingering in Safari's jar after a real sign-in stops vouching for
+  # anything almost immediately.
+  module OmniAuth
+    # How long after start seals the marker its GET still reads as the native
+    # flow arriving. The real gap is one redirect — milliseconds — but the
+    # sheet can sit on our page briefly on a slow network; anything past this
+    # is a browser wandering in.
+    ENTRY_WINDOW = 90
+
+    class << self
+      # Wire OmniAuth's global config: allow GET request phases (they're
+      # refused per-request by the validator unless they prove themselves),
+      # and wrap the configured validation phase so everything that isn't the
+      # native entry is judged exactly as before. Safe to call more than once —
+      # re-running replaces the wrapper, never stacks it.
+      def protect!(entry_window: ENTRY_WINDOW)
+        unless defined?(::OmniAuth) && ::OmniAuth.respond_to?(:config)
+          raise "Everywhere::OmniAuth.protect! needs OmniAuth loaded first — " \
+                "call it below your OmniAuth/Devise setup (config/initializers/omniauth.rb)"
+        end
+
+        config = ::OmniAuth.config
+        config.allowed_request_methods = Array(config.allowed_request_methods) | [:get]
+        config.silence_get_warning = true if config.respond_to?(:silence_get_warning=)
+
+        fallback = config.request_validation_phase
+        fallback = fallback.fallback if fallback.is_a?(RequestValidator)
+        config.request_validation_phase = RequestValidator.new(fallback: fallback, entry_window: entry_window)
+      end
+    end
+
+    # OmniAuth request_validation_phase: passes the native flow's entry,
+    # delegates everything else. A nil fallback means the app had no request
+    # validation configured, and it still has none — this never tightens.
+    class RequestValidator
+      attr_reader :fallback
+
+      def initialize(fallback: nil, entry_window: ENTRY_WINDOW)
+        @fallback = fallback
+        @entry_window = entry_window
+      end
+
+      def call(env)
+        return if native_entry?(env)
+
+        @fallback&.call(env)
+      end
+
+      private
+
+      # The one shape the native flow produces: a GET, not from a cross-site
+      # initiator, carrying a marker minted moments ago. POSTs never qualify —
+      # they come from rendered pages that have a CSRF token to present.
+      def native_entry?(env)
+        return false unless env["REQUEST_METHOD"] == "GET"
+        return false if env["HTTP_SEC_FETCH_SITE"] == "cross-site"
+
+        marker = AuthHandoff.marker(env)
+        issued = marker && marker["iat"]
+        !!issued && Time.now.to_i - issued.to_i <= @entry_window
+      end
+    end
+  end
+end

data/lib/everywhere/paths.rb

@@ -54,6 +54,30 @@ module Everywhere
                          "reinstall ruby_everywhere or pass --template-dir")
     end
 
+    # The Hotwire Native Android shell template bundled inside the gem:
+    # support/mobile/android/ holds a frozen Gradle project (wrapper committed)
+    # the CLI stamps per-app — everywhere.properties + assets + res, never a
+    # build script. Same freeze contract the iOS template has.
+    def bundled_android_dir
+      File.join(gem_root, "support", "mobile", "android")
+    end
+
+    # Absolute path to the Android template, or nil when it isn't there. Unlike
+    # #ios_dir, nil is the NORMAL state until the template lands — callers must
+    # read it as "Android isn't buildable in this release yet", not as a corrupt
+    # install. settings.gradle.kts is the marker because it's the one file every
+    # Gradle project must have at its root.
+    def android_dir
+      bundled_android_dir if File.exist?(File.join(bundled_android_dir, "settings.gradle.kts"))
+    end
+
+    # Like #android_dir but aborts with a helpful message when the template is
+    # missing. The --template-dir hint covers dev on a modified template.
+    def android_dir!
+      android_dir or UI.die!("couldn't find the bundled Android template at #{bundled_android_dir}; " \
+                             "reinstall ruby_everywhere or pass --template-dir")
+    end
+
     # Per-user cache dir. Keeps heavy build state out of the gem and the app.
     def cache_dir
       File.expand_path(ENV["RUBYEVERYWHERE_HOME"] || "~/.rubyeverywhere")
@@ -79,6 +103,29 @@ module Everywhere
       File.join(cache_dir, "ios-packages")
     end
 
+    # The stamped copy of the Android template for one app, keyed by
+    # applicationId. Persistent for the same reasons ios_work_dir is: Gradle's
+    # incremental state is path-sensitive, and the stamped project opens in
+    # Android Studio unmodified.
+    def android_work_dir(application_id)
+      File.join(cache_dir, "android", application_id)
+    end
+
+    # GRADLE_USER_HOME for shell builds. Redirected here so the multi-GB Gradle
+    # distribution, the Android Gradle Plugin and the Hotwire artifacts are
+    # downloaded once and stay warm across every app — and never land inside the
+    # installed gem. Same trick as cargo_target_dir.
+    def android_gradle_home
+      File.join(cache_dir, "android-gradle")
+    end
+
+    # Where the Material Symbols icon font is cached after its one-time fetch.
+    # The font is ~10 MB, so it's fetched on first Android build instead of
+    # riding along in a 229 KB gem that most users never build Android with.
+    def android_fonts_dir
+      File.join(cache_dir, "android-fonts")
+    end
+
     # Where cargo writes the shell's build output (CARGO_TARGET_DIR). Redirected
     # here so cargo never dumps a multi-GB target/ into the installed gem, and so
     # the shell compiles warm across projects — the shell source is identical for

data/lib/everywhere/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Everywhere
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 
   # Version of the @rubyeverywhere/bridge JS this gem ships. bridge/ in the
   # gem IS the npm package (served to Rails apps by Everywhere::Engine,

data/support/mobile/android/README.md

@@ -0,0 +1,217 @@
+# RubyEverywhere Android Shell Template
+
+A canonical [Hotwire Native Android][1] shell that wraps a deployed Ruby web app
+(remote URL). The RubyEverywhere CLI stamps a copy of this directory per app —
+the template itself is **never edited per-app**.
+
+The iOS template is the reference implementation; this one is a feature-for-feature
+port of `support/mobile/ios/`, and where the two differ the difference is forced
+by the platform and is explained in a comment at the site.
+
+## Freeze rules
+
+Every build script, layout, theme and Kotlin source here is written once and
+frozen. When `every build --target android-*` stamps a copy, it overwrites
+**exactly** these files and nothing else:
+
+1. `app/everywhere.properties` — applicationId, versionName, versionCode, app
+   label. The direct analogue of iOS's `App.xcconfig`: identity is stamped
+   without ever touching a build script. `app/build.gradle.kts` reads it at
+   configuration time.
+2. `app/src/main/assets/everywhere.json` — runtime config (remote URL, entry
+   path, colours, permissions, auth, universal-link hosts);
+   `Config#to_shell_json`.
+3. `app/src/main/assets/json/path-configuration.json` — baked rules +
+   `settings.tabs` (`Config#path_configuration_json("android")`). The same
+   document is served live at `/everywhere/android_v1.json` by the gem's
+   `MobileConfigEndpoint`, which the shell loads as its second, auth-aware
+   source.
+4. `app/src/main/assets/fonts/` — the selected Material icon font and its
+   `.codepoints` map. The bundled classic set
+   (`MaterialIcons-Regular.ttf`, 357 KB, 2,235 icons) is the offline fallback;
+   `icon_font: symbols` fetches the 10.6 MB variable font into
+   `~/.rubyeverywhere/android-fonts/` on first use. The two files must always
+   travel together — 282 names exist in both fonts with *different* codepoints.
+5. `app/src/main/res/values/colors.xml` and `values-night/colors.xml` — the
+   light and dark halves of `appearance.tint_color` / `background_color`.
+   Everything in the theme derives from those two colours.
+6. `app/src/main/res/values/ic_launcher_background.xml` and
+   `res/drawable-<dpi>/ic_launcher_foreground.png` — the adaptive launcher
+   icon's two layers. `minSdk 28` means there are no legacy
+   `mipmap-<dpi>/ic_launcher.png` fallbacks to generate.
+7. *(optionally)* `app/src/stamped/AndroidManifest.xml` — deep-link intent
+   filters, the auth callback scheme, and runtime `<uses-permission>` entries.
+   Written **only** when `everywhere.yml` declares `deep_linking:`, `auth:` or
+   `permissions:`. It is a separate manifest, folded in by the merger, so the
+   main manifest stays frozen — the analogue of iOS's optional
+   `App.entitlements`. See the note below on how it is wired.
+8. *(optionally)* `app/native-packages.gradle.kts` — Maven coordinates from
+   `native.android.packages`, and
+   `app/src/main/java/com/rubyeverywhere/shell/extensions/` — the app repo's
+   `native/android/*.kt` plus the generated `EverywhereExtensions.kt` registry.
+   Both ship as empty defaults so the raw template builds unchanged.
+9. `app/src/stamped/res/drawable*/` — the app's own images, generated from
+   `native/android/assets/**` by `Everywhere::AndroidResources`, reachable from
+   extension code as `R.drawable.<name>`. Registered as a second `res` srcDir on
+   `main` (see `sourceSets` in `app/build.gradle.kts`) and **cleared on every
+   build**, which is why it is its own directory rather than more files in
+   `main/res`: stamping merges over the work dir instead of wiping it, so an
+   asset the app deleted has to be removed by the generator that wrote it.
+   Filenames are the whole API and match iOS's exactly — `logo@2x~dark.png`
+   becomes `drawable-night-xhdpi/logo.png`.
+10. *(dev only)* `app/src/debug/assets/dev-url.txt` — the dev-server URL.
+   Android has no `SIMCTL_CHILD_*`, so `every dev --android` stamps this and
+   rebuilds, which it has to do anyway. Read only in debug builds; the debug
+   source set never ships in a release.
+
+**Structural changes** — new source files, new dependencies, a plugin bump, a
+new layout — mean deliberately editing this template and recommitting, never
+editing a stamped copy.
+
+### Why `src/stamped/` is wired the way it is
+
+AGP merges one manifest per *source set*, and without product flavours a variant
+has exactly two: `main` and its build type. The generated manifest is therefore
+registered as **both** build types' manifest in `app/build.gradle.kts`:
+
+```kotlin
+sourceSets {
+    getByName("debug") { manifest.srcFile("src/stamped/AndroidManifest.xml") }
+    getByName("release") { manifest.srcFile("src/stamped/AndroidManifest.xml") }
+}
+```
+
+A product flavour would have been the textbook answer, but it renames every task
+(`assembleStampedDebug`), and the builder, the dev loop and this README all
+depend on plain `:app:assembleDebug`.
+
+That leaves the build-type manifest slot occupied, so the debug-only cleartext
+policy is expressed as a **resource overlay** instead:
+`src/debug/res/xml/network_security_config.xml` overrides the release-safe
+`src/main/res/xml/network_security_config.xml` of the same name. The main
+manifest's `android:networkSecurityConfig` attribute never changes.
+
+## Dependency pin policy
+
+The SPM equivalent. Plugin versions are pinned in the root `build.gradle.kts`,
+library versions in `app/build.gradle.kts`, and both are **exact** — no ranges,
+no `+`, no version catalog. Moving a pin is a deliberate edit here.
+
+| | pinned at |
+| --- | --- |
+| Gradle | 9.2.0 (`-bin`, see below) |
+| Android Gradle Plugin | 8.13.2 |
+| Kotlin / kotlinx.serialization plugin | 2.3.0 |
+| `dev.hotwire:core`, `dev.hotwire:navigation-fragments` | 1.3.0 |
+| `compileSdk` / `targetSdk` | 35 |
+| `minSdk` | 28 — Hotwire Native Android's floor, not negotiable |
+| Java toolchain / JVM target | 17 |
+
+The wrapper deliberately uses `gradle-9.2.0-**bin**.zip`, not `-all`: the `-all`
+distribution unpacks to 522 MB in `GRADLE_USER_HOME` and the difference is
+Gradle's own sources and javadoc, which only an IDE indexing the Gradle API ever
+reads.
+
+`settings.gradle.kts` keeps the `foojay-resolver-convention` plugin so the Java
+toolchain can be provisioned independently of the launcher JVM — without it the
+build fails on a machine whose only JDK is 21.
+
+## Building standalone
+
+The raw template builds green with placeholder values, unsigned:
+
+```
+export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+export ANDROID_HOME=$HOME/Library/Android/sdk
+./gradlew :app:assembleDebug
+```
+
+Output: `app/build/outputs/apk/debug/app-debug.apk`.
+
+The first build downloads roughly 1.4 GB (Gradle, the Android Gradle Plugin, the
+Hotwire artifacts) and takes a couple of minutes, almost all of it network. Warm
+no-op rebuilds are around 7 seconds. The CLI redirects `GRADLE_USER_HOME` to
+`~/.rubyeverywhere/android-gradle` so that cache is shared across apps and never
+lands inside the installed gem.
+
+## Dev loop
+
+The shell is remote-mode only (`remote_url` in `everywhere.json`). For local
+development, `every dev --android` stamps `src/debug/assets/dev-url.txt`,
+rebuilds, reinstalls and relaunches — the Android equivalent of pressing `i` in
+the iOS loop. The URL resolves down a three-step ladder:
+
+1. `adb reverse tcp:<port> tcp:<port>`, then `http://127.0.0.1:<port>` — correct
+   on emulators *and* physical devices. Preferred.
+2. `http://10.0.2.2:<port>` — the emulator's alias for the host loopback, used
+   automatically when `adb reverse` fails.
+3. An explicit `--dev-url` LAN address, for physical devices.
+
+Cleartext to those hosts is allowed only in debug builds, and only for the hosts
+themselves — never `cleartextTrafficPermitted` globally. See
+`app/src/debug/res/xml/network_security_config.xml`.
+
+## Shape of the shell
+
+| file | role |
+| --- | --- |
+| `EverywhereApplication.kt` | Hotwire config, bridge + destination + route-handler registration, first path-configuration load |
+| `EverywhereConfig.kt` | `everywhere.json` decode; roots, dev override, instance override, auth, deep links |
+| `EverywhereEvents.kt` | page → shell control messages, replacing iOS's NotificationCenter |
+| `MainActivity.kt` | the SceneDelegate counterpart: tabs, splash, reset, badges, deep links, sign-in |
+| `MainTabs.kt` | `settings.tabs` → the fixed pool of five NavigatorHosts |
+| `IconFont.kt` | Material icons resolved by name from the bundled font |
+| `WebFragment.kt`, `WebBottomSheetFragment.kt` | the web destinations |
+| `bridge/` | the six `everywhere--*` bridge components and the control channel |
+| `AuthFlow.kt` | third-party sign-in in a Custom Tab |
+| `EverywhereHost.kt` | what app-authored `native/android/` code calls: `everywhereVisit`, `everywhereFetch` |
+| `extensions/EverywhereExtensions.kt` | generated app-extension registry (empty by default) |
+
+### What app-authored screens get
+
+`native/android/*.kt` compiles into `extensions/` and must declare
+`package com.rubyeverywhere.shell.extensions` — the generated registry names
+those types unqualified, and Kotlin ties nothing to the directory, so the package
+line is what makes them referenceable. `every build` refuses a file without it.
+
+The two helpers in `EverywhereHost.kt` are named to match iOS's
+`EverywhereHost.swift` so extension code reads the same on both platforms:
+
+* `everywhereVisit("/path")` — route through the active navigator, so a native
+  screen's links get the full path-configuration treatment (modals, other native
+  screens) like any web-driven visit.
+* `everywhereFetch("/builds.json")` — GET from the app's own server carrying the
+  WebView's session cookie and the native User-Agent, so `native_app?` holds
+  server-side and an authenticated endpoint answers. Suspending; throws
+  `EverywhereFetchError` on a non-2xx.
+
+Images live in `native/android/assets/**` and arrive as `R.drawable.<name>`
+(freeze rule 9). There is no `everywhereHost` counterpart to iOS's — a Hotwire
+Android destination is already a `Fragment`.
+
+### Three invariants that will break the app if they are violated
+
+Measured on a device during the Phase 0 spike, not inferred:
+
+1. **`navigatorConfigurations()` must return a configuration for all five hosts,
+   on every launch.** `NavigatorHost.onCreate` throws
+   `IllegalStateException("No configuration found for NavigatorHost")` for any
+   host in `activity_main.xml` it can't find one for. "Not a tab right now" is
+   `isVisible = false`, **never** a shorter list — `switchTab` only hides hosts
+   present in the new list, so a dropped host stays on screen.
+2. **`lazyLoadTabs = true` is mandatory.** With eager loading all five pooled
+   hosts cold-boot a WebView and fetch their start location at launch,
+   including the hidden auth-gated ones.
+3. **A second `load()` is cheap but lossy.** Fragments and WebViews survive
+   (~96 ms), but `loadMenu()` opens with `menu.clear()`, which destroys badges
+   and icons, and resets Material's `selectedItemId` to 0 — which then takes the
+   *reselect* path and clears the selected tab's backstack whenever the selected
+   tab is the first one. `MainActivity.applyTabs` is the only caller and does
+   all three fix-ups; nothing else may call `load()`.
+
+Tab **path** changes are not covered by any of that: `NavigatorHost` caches its
+configuration in `onCreate`, so a changed `startLocation` needs
+`Activity.recreate()`. `MainTabs` keeps two fingerprints so the cheap path is
+taken whenever it can be.
+
+[1]: https://github.com/hotwired/hotwire-native-android

data/support/mobile/android/app/build.gradle.kts

@@ -0,0 +1,156 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import java.util.Properties
+
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+    id("org.jetbrains.kotlin.plugin.serialization")
+}
+
+// Per-app identity, read from a properties file rather than written into this
+// script. `every build` overwrites everywhere.properties and nothing else here
+// — the same contract as iOS's App.xcconfig, for the same reason: a build
+// script the CLI edits is a build script that drifts.
+val everywhere = Properties().apply {
+    file("everywhere.properties").inputStream().use { load(it) }
+}
+
+fun stamped(key: String, default: String): String =
+    everywhere.getProperty("everywhere.$key")?.takeIf { it.isNotBlank() } ?: default
+
+android {
+    // The namespace is the R class / BuildConfig package and is frozen. It is
+    // deliberately NOT the applicationId: apps rename their bundle id freely,
+    // and a namespace change would move every generated class.
+    namespace = "com.rubyeverywhere.shell"
+    compileSdk = 35
+
+    defaultConfig {
+        applicationId = stamped("applicationId", "com.rubyeverywhere.app")
+        versionName = stamped("versionName", "0.1.0")
+        versionCode = stamped("versionCode", "1").toInt()
+
+        // minSdk 28 is Hotwire Native Android's floor and is not negotiable.
+        // It also clears API 26 for Typeface.Builder.setFontVariationSettings,
+        // which IconFont needs for the Material Symbols FILL axis.
+        minSdk = 28
+        targetSdk = 35
+
+        // Consumed by AndroidManifest.xml. The label is a placeholder so the
+        // manifest itself stays frozen when the app is renamed.
+        manifestPlaceholders["everywhereLabel"] = stamped("label", "RubyEverywhere")
+    }
+
+    sourceSets {
+        // Deep-link intent filters, the auth callback scheme and runtime
+        // <uses-permission> entries are generated into their own manifest so
+        // the main one never changes. AGP merges one manifest per build type,
+        // and the generated file is identical for both — hence the same path
+        // twice. See src/stamped/AndroidManifest.xml.
+        getByName("debug") { manifest.srcFile("src/stamped/AndroidManifest.xml") }
+        getByName("release") { manifest.srcFile("src/stamped/AndroidManifest.xml") }
+
+        // The app's own images (native/android/assets/**) are generated into
+        // src/stamped/res as drawables. A second res dir on `main` rather than
+        // more files in main/res, because the generator owns the directory
+        // outright and clears it every build — a deleted asset has to stop
+        // shipping, and stamping merges over the work dir instead of wiping it.
+        //
+        // On `main`, deliberately, not on a build type: same-variant duplicates
+        // are a merge ERROR, so an asset that collides with a template drawable
+        // fails the build instead of silently overriding it. AGP ignores the
+        // directory when it doesn't exist, which is how the raw template builds.
+        getByName("main") { res.srcDir("src/stamped/res") }
+    }
+
+    buildTypes {
+        getByName("debug") {
+            isDebuggable = true
+        }
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+
+    buildFeatures {
+        // BuildConfig.DEBUG gates web-view debugging, verbose logging and the
+        // dev-server asset. Nothing else in the shell branches on build type.
+        buildConfig = true
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    lint {
+        // `lintVitalRelease` crashes on this exact toolchain (AGP 8.13.2 +
+        // Kotlin 2.3.0). Its build-script visitor builds light classes for
+        // every `.gradle.kts` in the project and dies inside the Kotlin
+        // compiler with "findFirCompiledSymbol only works on compiled
+        // declarations" the moment one script `apply(from:)`s another — which
+        // native-packages.gradle.kts is, by design.
+        //
+        // Verified by bisection: commenting out the `apply(from:)` below makes
+        // lintVitalAnalyzeRelease pass, and nothing else does. So this disables
+        // a check that cannot run, not one that was failing us. Revisit when
+        // either version moves.
+        checkReleaseBuilds = false
+    }
+
+    packaging {
+        // The icon font is already a compressed container; deflating it again
+        // costs build time and saves nothing.
+        resources.excludes += "/META-INF/{AL2.0,LGPL2.1}"
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(JvmTarget.JVM_17)
+    }
+}
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(17)
+    }
+}
+
+dependencies {
+    // Hotwire Native. Pinned exactly, not to a range: this is the template's
+    // dependency pin policy, the analogue of iOS's Package.resolved.
+    implementation("dev.hotwire:core:1.3.0")
+    implementation("dev.hotwire:navigation-fragments:1.3.0")
+
+    // Material — BottomNavigationView, badges, bottom sheets, theming.
+    implementation("com.google.android.material:material:1.12.0")
+
+    // activity_main.xml's root.
+    implementation("androidx.constraintlayout:constraintlayout:2.2.1")
+
+    // WebViewCompat: addWebMessageListener (the control channel) and
+    // addDocumentStartJavaScript (window.__EVERYWHERE_CONFIG__). Android
+    // WebView has no user-script API of its own; these are the substitutes.
+    implementation("androidx.webkit:webkit:1.12.1")
+
+    // Custom Tabs — the ASWebAuthenticationSession stand-in for third-party
+    // sign-in, and what Hotwire's own BrowserTabRouteDecisionHandler uses.
+    implementation("androidx.browser:browser:1.8.0")
+
+    // Biometrics + the encrypted store they gate.
+    implementation("androidx.biometric:biometric:1.1.0")
+    implementation("androidx.security:security-crypto:1.1.0-alpha06")
+
+    // everywhere.json, the bridge components' message payloads, and the
+    // control channel's postMessage bodies.
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.1")
+}
+
+// GENERATED: Maven coordinates from `native.android.packages`. Applied last so
+// an app's own dependency can override a version above if it must.
+apply(from = "native-packages.gradle.kts")

data/support/mobile/android/app/everywhere.properties

@@ -0,0 +1,8 @@
+# STAMPED by `every build --android`. The direct analogue of iOS's
+# App.xcconfig: identity lives here so no build script is ever edited per app.
+# The values below are the template's placeholders — the raw template builds
+# green with them.
+everywhere.applicationId=com.rubyeverywhere.app
+everywhere.versionName=0.1.0
+everywhere.versionCode=1
+everywhere.label=RubyEverywhere

data/support/mobile/android/app/native-packages.gradle.kts

@@ -0,0 +1,16 @@
+// GENERATED by `every build --android` from `native.android.packages` in
+// config/everywhere.yml. The checked-in copy is the empty default, so the raw
+// template builds unchanged.
+//
+//   native:
+//     android:
+//       packages:
+//         - "com.airbnb.android:lottie:6.4.0"
+//
+// This is a script plugin applied from app/build.gradle.kts, so it has no
+// typed `implementation(...)` accessor — dependencies are added by
+// configuration name. Keeping the generated surface to a single file means
+// the frozen build script never changes shape when an app adds a package.
+dependencies {
+    // add("implementation", "group:artifact:version")
+}