ruby_everywhere 0.2.0 → 0.4.0

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")
+}

data/support/mobile/android/app/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Bridge components are instantiated reflectively through
+# BridgeComponentFactory and named by string from the page, so R8 has no call
+# graph reaching them. Without this the release build strips every component
+# and the page's `everywhere--*` messages silently go nowhere.
+-keep class com.rubyeverywhere.shell.bridge.** { *; }
+
+# App-provided native code (native/android/*.kt), same reasoning: it is
+# referenced by identifier from the path configuration, not from Kotlin.
+-keep class com.rubyeverywhere.shell.extensions.** { *; }
+
+# Fragment destinations are resolved from the navigation graph by class name.
+-keep class * extends androidx.fragment.app.Fragment { *; }
+
+# kotlinx.serialization generates a companion `serializer()` per @Serializable
+# class; the plugin's own rules cover its runtime, these cover our models.
+-keepclassmembers class com.rubyeverywhere.shell.** {
+    *** Companion;
+}
+-keepclasseswithmembers class com.rubyeverywhere.shell.** {
+    kotlinx.serialization.KSerializer serializer(...);
+}

data/support/mobile/android/app/src/debug/res/xml/network_security_config.xml

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Debug only. The analogue of iOS's NSAllowsLocalNetworking: enough cleartext
+  to reach a Rails server on the developer's machine, and not one host more.
+  Never `cleartextTrafficPermitted="true"` on the base config — that would
+  quietly downgrade every request the app makes while debugging, including the
+  ones going to the real, deployed app.
+
+  * 127.0.0.1 / localhost — correct on emulators AND physical devices once
+    `adb reverse tcp:<port> tcp:<port>` is set up. The preferred rung.
+  * 10.0.2.2 — the Android emulator's alias for the host's loopback, used when
+    `adb reverse` is unavailable.
+  * .local — a Bonjour hostname, which is how most LAN setups are reachable.
+
+  network-security-config takes hostnames and IP literals only; there is no
+  CIDR syntax, so the private ranges cannot be expressed here. An explicit
+  `dev_url` of http://192.168.1.20:3000 therefore needs its host added, and
+  appending a domain entry to this file for that case is the one edit the
+  builder is allowed to make here.
+-->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="false">127.0.0.1</domain>
+        <domain includeSubdomains="false">localhost</domain>
+        <domain includeSubdomains="false">10.0.2.2</domain>
+        <domain includeSubdomains="true">local</domain>
+    </domain-config>
+</network-security-config>

data/support/mobile/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  FROZEN. Nothing per-app belongs in this file. The app label arrives as a
+  manifest placeholder from everywhere.properties; deep-link intent filters,
+  the auth callback scheme and runtime permissions are merged in from
+  src/stamped/AndroidManifest.xml.
+-->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application
+        android:name=".EverywhereApplication"
+        android:allowBackup="false"
+        android:enableOnBackInvokedCallback="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="${everywhereLabel}"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.Everywhere"
+        android:networkSecurityConfig="@xml/network_security_config"
+        tools:ignore="GoogleAppIndexingWarning,UnusedAttribute">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:configChanges="orientation|screenSize"
+            android:theme="@style/Theme.Everywhere.Splash"
+            android:windowSoftInputMode="adjustResize"
+            android:launchMode="singleTask">
+
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+
+        </activity>
+
+    </application>
+
+</manifest>

data/support/mobile/android/app/src/main/assets/everywhere.json

@@ -0,0 +1,9 @@
+{
+  "name": "RubyEverywhere",
+  "bundle_id": "com.rubyeverywhere.app",
+  "version": "0.1.0",
+  "mode": "remote",
+  "remote_url": "https://rubyeverywhere.com",
+  "entry_path": "/",
+  "lazy_load_tabs": true
+}