ruby_everywhere 0.3.0 → 0.4.0

data/lib/everywhere/emulator.rb

@@ -0,0 +1,405 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "android_sdk"
+require_relative "shellout"
+require_relative "ui"
+
+module Everywhere
+  # Thin wrappers around `adb` and `emulator` — just enough to boot a virtual
+  # device, put the stamped APK on it and launch it. The Android counterpart of
+  # Simulator, method for method, so `every dev` reads the same either way.
+  #
+  # Every binary comes from AndroidSdk, never from PATH: Android Studio
+  # provisions adb and the emulator and exports neither, so a machine that can
+  # build Android apps all day has no `adb` on PATH (see AndroidSdk's preamble).
+  module Emulator
+    module_function
+
+    # Phase 0 measured a headless cold boot of Medium_Phone_API_35 at 16s to
+    # sys.boot_completed, and a windowed cold boot — which is what we default
+    # to, see #boot_argv — at roughly two minutes. Four minutes is generous
+    # enough to cover a slower machine or an AVD whose Quick Boot snapshot is
+    # being rebuilt, without pretending a genuinely wedged emulator will
+    # eventually come good.
+    BOOT_TIMEOUT = 240
+
+    POLL_INTERVAL = 1
+
+    # The emulator's alias for the host's own loopback interface: inside the
+    # guest, 127.0.0.1 is the *guest*, and 10.0.2.2 is the machine running it.
+    # Rung 2 of the dev-URL ladder (plan §2.3).
+    LOOPBACK_ALIAS = "10.0.2.2"
+
+    # Hosts that mean "this machine" in a dev URL and therefore mean the wrong
+    # machine once the URL is loaded inside the guest. 0.0.0.0 is here because
+    # a server bound to every interface is often *printed* as http://0.0.0.0:3000.
+    LOOPBACK_HOSTS = ["127.0.0.1", "localhost", "::1", "0.0.0.0"].freeze
+
+    # The shell template's launcher activity, FULLY QUALIFIED on purpose.
+    #
+    # `am start -n <applicationId>/<activity>` resolves a leading dot against the
+    # applicationId — but the template's manifest says `android:name=".MainActivity"`,
+    # which Gradle resolves against the *namespace*, and the namespace is frozen
+    # at com.rubyeverywhere.shell precisely so an app can rename its bundle id
+    # freely. The two are different packages for every real app, so any relative
+    # spelling here is wrong the moment applicationId != namespace.
+    # (The Hotwire demo's `.main.MainActivity` is a fact about the demo, whose
+    # applicationId happens to equal its namespace. It does not transfer.)
+    DEFAULT_ACTIVITY = "com.rubyeverywhere.shell.MainActivity"
+
+    # --- devices --------------------------------------------------------------
+
+    # Serial of a device we can actually talk to, or nil.
+    #
+    # Emulators come first because they are what `every dev --android` boots and
+    # what the dev-URL ladder can rewrite for; a plugged-in phone is still
+    # accepted after them, since someone with a device attached and no emulator
+    # running clearly meant that device.
+    def booted_serial
+      ready = devices.select { |d| d[:state] == "device" }
+      (ready.find { |d| emulator?(d[:serial]) } || ready.first)&.fetch(:serial)
+    end
+
+    # Parsed `adb devices -l`. Lines look like:
+    #
+    #   List of devices attached
+    #   emulator-5554   device product:sdk_gphone64_arm64 model:… transport_id:1
+    #   emulator-5556   offline
+    #   3A2B1C0D4E      unauthorized usb:1-1
+    #
+    # `device` is the only state that can take a command. `offline` is a device
+    # the daemon has seen but can't talk to — an emulator still coming up, or one
+    # that wedged — and `unauthorized` is a phone whose owner hasn't tapped
+    # "Allow USB debugging" yet. Both are kept in the list (so callers can say
+    # *why* nothing is usable) but neither is ever picked by #booted_serial:
+    # installing against them fails with a message that reads like our bug.
+    def devices
+      exe = AndroidSdk.adb or return []
+
+      out, status = Shellout.capture(exe, "devices", "-l")
+      return [] unless status&.success?
+
+      out.lines.filter_map do |line|
+        # Skip the header and adb's own "* daemon started successfully" notes.
+        next if line.start_with?("List of devices", "*")
+
+        serial, state, = line.split
+        next unless serial && state&.match?(/\A[a-z]+\z/)
+
+        { serial: serial, state: state }
+      end
+    end
+
+    # adb names emulators after their console port (emulator-5554); physical
+    # devices carry a hardware serial. That prefix is the standard test and it's
+    # what decides whether the 10.0.2.2 rewrite is even meaningful.
+    def emulator?(serial) = serial.to_s.start_with?("emulator-")
+
+    # --- booting --------------------------------------------------------------
+
+    # Reuse a running device, else boot an AVD and wait for it to be usable.
+    # Returns the serial.
+    def boot_default!(avd: nil, headless: false, timeout: BOOT_TIMEOUT)
+      if (serial = booted_serial)
+        UI.step("reusing #{UI.bold(serial)}")
+        return serial
+      end
+
+      name = avd || AndroidSdk.avds!.last
+      UI.step("booting emulator #{UI.bold(name)}#{headless ? UI.dim(" (headless)") : ""}")
+      spawn_emulator(boot_argv(name, headless: headless))
+
+      deadline = Time.now + timeout
+      bounded_wait(adb_argv(nil, "wait-for-device"), timeout: timeout)
+      serial = booted_serial or
+        UI.die!("emulator #{name} never registered with adb — try booting it from Android " \
+                "Studio's Device Manager to see what it says")
+      wait_until_booted(serial, timeout: [deadline - Time.now, POLL_INTERVAL].max)
+      serial
+    end
+
+    # WINDOWED BY DEFAULT, deliberately, even though headless boots roughly
+    # eight times faster (16s vs ~2m in the Phase 0 measurements).
+    #
+    # The emulator window *is* the feedback surface of this dev loop — you press
+    # `a` to look at your app. A headless boot installs and launches a shell you
+    # cannot see, which is indistinguishable from a build that silently failed;
+    # that is not hypothetical, it is what happened the first time this was run
+    # by hand. The slow boot is a one-time cost per session, paid while other
+    # work (the Gradle build) is happening anyway, and Quick Boot amortises it
+    # away on every subsequent run. Invisibility is a cost paid *every* time,
+    # and it is paid in "is this broken?".
+    #
+    # `headless: true` stays available for CI and for anyone who really does
+    # only want logs.
+    #
+    # Notably absent: `-no-snapshot`. The spike passed it to force honest cold
+    # boots for measurement; for a dev loop the opposite is wanted — Quick Boot
+    # restores a saved state in seconds instead of running Android's whole
+    # startup again. `-no-audio` stays regardless: the emulator grabbing the
+    # host's audio device is a well-known source of hangs on macOS, and a web
+    # shell has nothing to play.
+    def boot_argv(avd, headless: false)
+      argv = [AndroidSdk.emulator!, "-avd", avd, "-no-boot-anim", "-no-audio"]
+      argv << "-no-window" if headless
+      argv
+    end
+
+    # `adb wait-for-device` returns as soon as the daemon can talk to the
+    # device, which Phase 0 clocked at 8s — a full 8s before the system is
+    # actually usable. So it's the *start* of the wait, not the end: what says
+    # "ready" is sys.boot_completed flipping to 1.
+    def wait_until_booted(serial, timeout: BOOT_TIMEOUT)
+      deadline = Time.now + timeout
+      bounded_wait(adb_argv(serial, "wait-for-device"), timeout: timeout)
+
+      until Time.now > deadline
+        return serial if boot_completed?(serial)
+
+        sleep POLL_INTERVAL
+      end
+      UI.die!("emulator #{serial} never finished booting " \
+              "(sys.boot_completed still unset after #{UI.elapsed(timeout)})")
+    end
+
+    def boot_completed?(serial)
+      out, status = Shellout.capture(*adb_argv(serial, "shell", "getprop", "sys.boot_completed"))
+      status&.success? && out.strip == "1"
+    end
+
+    # --- app lifecycle --------------------------------------------------------
+
+    # `-r` reinstalls over an existing copy, keeping its data — the fast path,
+    # and the one `every dev --android` takes on every press of `a`.
+    #
+    # It has one failure that no amount of retrying fixes: an APK signed by a
+    # different key than the copy already on the device is rejected with
+    # INSTALL_FAILED_UPDATE_INCOMPATIBLE, which is routine the first time a
+    # machine builds an app someone else's debug keystore installed. The only
+    # cure is removing the old package, so we do that once, out loud, rather
+    # than making the user decode the error.
+    #
+    # Old adb builds printed `Failure [...]` and still exited 0, so the output
+    # is checked as well as the status.
+    def install(serial, apk, application_id: nil)
+      out, status = capture_install(serial, apk)
+      return if status&.success? && !out.include?("Failure [")
+
+      if application_id && out.include?("INSTALL_FAILED_UPDATE_INCOMPATIBLE")
+        UI.warn "#{application_id} is installed with a different signing key — reinstalling " \
+                "from scratch #{UI.dim("(its app data is dropped)")}"
+        uninstall(serial, application_id)
+        out, status = capture_install(serial, apk)
+        return if status&.success? && !out.include?("Failure [")
+      end
+
+      UI.die!("adb install failed: #{out.strip}")
+    end
+
+    def capture_install(serial, apk)
+      Shellout.capture(*adb_argv(serial, "install", "-r", apk))
+    end
+
+    # Not fatal: "not installed for user 0" is the normal answer on a clean
+    # device, and every caller only wants the package gone.
+    def uninstall(serial, application_id)
+      _out, status = Shellout.capture(*adb_argv(serial, "uninstall", application_id))
+      !!status&.success?
+    end
+
+    # `am start` reports an unknown component as `Error: Activity class {…} does
+    # not exist.` on stdout *and still exits 0*, so the output is what decides.
+    def launch(serial, application_id, activity: DEFAULT_ACTIVITY)
+      component = "#{application_id}/#{activity}"
+      out, status = Shellout.capture(*adb_argv(serial, "shell", "am", "start", "-n", component))
+      return if started?(out, status)
+
+      # The APK on the device is the authority on its own launcher activity, so
+      # rather than dying on a stale constant, ask it. This costs one round trip
+      # only on the failure path, and it means moving MainActivity in the
+      # template can never silently break the dev loop again — which is exactly
+      # how this broke the first time.
+      resolved = launcher_activity(serial, application_id)
+      if resolved && resolved != activity
+        retry_component = "#{application_id}/#{resolved}"
+        retry_out, retry_status = Shellout.capture(
+          *adb_argv(serial, "shell", "am", "start", "-n", retry_component)
+        )
+        if started?(retry_out, retry_status)
+          UI.warn "launched #{resolved} — #{activity} is stale, update Emulator::DEFAULT_ACTIVITY"
+          return
+        end
+      end
+
+      UI.die!("couldn't launch #{component}: #{out.strip}")
+    end
+
+    # `am start` reports an unknown component on stdout and STILL exits 0, so a
+    # bare exit status is not an answer.
+    def started?(out, status)
+      !!status&.success? && !out.to_s.match?(/^Error:/)
+    end
+
+    # The launcher activity the installed APK actually declares. `cmd package
+    # resolve-activity --brief` prints `<package>/<activity>` on its last line;
+    # anything else (old adb, no match) answers nil so the caller can fail with
+    # the original, more useful error.
+    def launcher_activity(serial, application_id)
+      out, status = Shellout.capture(*adb_argv(serial, "shell", "cmd", "package", "resolve-activity",
+                                               "--brief", application_id))
+      return unless status&.success?
+
+      line = out.to_s.lines.map(&:strip).reject(&:empty?).last
+      return unless line&.include?("/")
+
+      package, activity = line.split("/", 2)
+      activity if package == application_id && !activity.to_s.empty?
+    end
+
+    # The app's process id on the device, or nil when it isn't running. `pidof`
+    # exits non-zero and prints nothing in that case, which is exactly the
+    # distinction `every logs --android` needs to make.
+    def pid_of(serial, application_id)
+      out, status = Shellout.capture(*adb_argv(serial, "shell", "pidof", application_id))
+      pid = out.to_s.split.first
+      pid if status&.success? && pid&.match?(/\A\d+\z/)
+    end
+
+    # Forward the device's <port> back to the host's <port>. Returns whether it
+    # took, because that answer *is* rung 1 of the dev-URL ladder below.
+    #
+    # It succeeds with nothing listening on the host port (verified in Phase 0),
+    # so it can run before the dev server is up. On success adb prints the port
+    # number to stdout — a wrapper that read non-empty output as failure would
+    # get this exactly backwards.
+    def reverse(serial, port)
+      _out, status = Shellout.capture(*adb_argv(serial, "reverse", "tcp:#{port}", "tcp:#{port}"))
+      !!status&.success?
+    end
+
+    # --- the dev-URL ladder (plan §2.3) --------------------------------------
+
+    # Resolve the URL the Android shell should be pointed at, given the URL the
+    # dev server is on *from the host's point of view*. Returns a URL string;
+    # `every dev --android` stamps whatever comes back into the debug build.
+    #
+    # Three rungs, so a failure at any one degrades instead of dead-ending:
+    #
+    #   0. `override` (--dev-url / --host) short-circuits everything. Someone who
+    #      typed an address knows something we don't — typically that the app is
+    #      being opened on a physical phone over the LAN.
+    #   1. `adb reverse tcp:<port> tcp:<port>`. Preferred, because it leaves the
+    #      URL *literally correct*: 127.0.0.1:3000 on the device is 127.0.0.1:3000
+    #      on the host, so cookies, redirects, OAuth callbacks and anything the
+    #      app prints all keep matching. Works on emulators and physical devices
+    #      alike.
+    #   2. The 10.0.2.2 rewrite, if reverse failed and the target is an emulator.
+    #      Automatic and announced — the user is told the URL changed and why,
+    #      because a silently different origin is a genuinely confusing thing to
+    #      debug an hour later.
+    #
+    # If none apply (a physical device, reverse failed, no override) the URL is
+    # returned unchanged with a warning naming the fix, rather than aborting a
+    # dev loop that is otherwise fine.
+    #
+    #   Emulator.dev_url("http://127.0.0.1:3000/", serial: "emulator-5554")
+    #   #=> "http://127.0.0.1:3000/"   (rung 1)  or  "http://10.0.2.2:3000/" (rung 2)
+    def dev_url(url, serial:, port: nil, override: nil)
+      unless override.to_s.empty?
+        UI.step("dev URL #{UI.cyan(override)} #{UI.dim("(explicit override)")}")
+        return override
+      end
+
+      # A URL that doesn't point at this machine needs no help: a LAN address or
+      # a deployed https:// origin is already reachable from the device.
+      return url unless loopback?(url)
+
+      port ||= port_of(url)
+      return url if port && reverse(serial, port)
+
+      rewritten = rewrite_loopback(url)
+      if emulator?(serial) && rewritten != url
+        UI.warn "adb reverse failed — pointing the shell at #{UI.cyan(rewritten)} instead " \
+                "#{UI.dim("(#{LOOPBACK_ALIAS} is the emulator's alias for this machine)")}"
+        return rewritten
+      end
+
+      UI.warn "adb reverse failed and #{serial || "this target"} isn't an emulator — " \
+              "#{UI.cyan(url)} will resolve to the device itself; pass a LAN address " \
+              "(--dev-url http://<this machine's IP>:#{port}) with the dev server bound to 0.0.0.0"
+      url
+    end
+
+    def loopback?(url) = LOOPBACK_HOSTS.include?(host_of(url))
+
+    def rewrite_loopback(url)
+      uri = URI.parse(url.to_s)
+      return url unless LOOPBACK_HOSTS.include?(uri.host)
+
+      uri.host = LOOPBACK_ALIAS
+      uri.to_s
+    rescue URI::InvalidURIError
+      url
+    end
+
+    def host_of(url)
+      URI.parse(url.to_s).host
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def port_of(url)
+      URI.parse(url.to_s).port
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    # --- plumbing -------------------------------------------------------------
+
+    # Every adb invocation goes through here so the `-s <serial>` targeting is
+    # never forgotten — an unqualified adb command with two devices attached
+    # fails with "more than one device", and with one emulator plus a phone it
+    # silently does the right thing on the wrong one. A nil serial means "any
+    # device", which is only ever wanted while waiting for the first one.
+    def adb_argv(serial, *args)
+      [AndroidSdk.adb!, *(serial ? ["-s", serial.to_s] : []), *args]
+    end
+
+    # The emulator has to outlive `every dev` the way the iOS Simulator app
+    # does — quitting the CLI should not tear down a device you were using — so
+    # it leads its own process group and is detached. Its INFO/WARNING banners
+    # go to /dev/null: they would otherwise land in the middle of the dev
+    # server's log, and nothing here reads them.
+    def spawn_emulator(argv)
+      pid = Shellout.unbundled { Process.spawn(*argv, pgroup: true, out: File::NULL, err: File::NULL) }
+      Process.detach(pid)
+      pid
+    end
+
+    # Run a command with a deadline, and report whether it finished in time.
+    #
+    # This exists for `adb wait-for-device`, which blocks forever by design: an
+    # AVD that fails to start would hang the dev loop with no output at all.
+    # Waiting on the child ourselves is the only way to put a ceiling on it, so
+    # the "never came up" path reaches a message a human can act on.
+    def bounded_wait(argv, timeout: BOOT_TIMEOUT)
+      pid = Shellout.unbundled { Process.spawn(*argv, out: File::NULL, err: File::NULL) }
+      deadline = Time.now + timeout
+      loop do
+        return true if Process.waitpid(pid, Process::WNOHANG)
+        break if Time.now > deadline
+
+        sleep POLL_INTERVAL
+      end
+
+      begin
+        Process.kill("TERM", pid)
+        Process.waitpid(pid)
+      rescue StandardError
+        nil
+      end
+      false
+    end
+  end
+end

data/lib/everywhere/engine.rb

@@ -39,6 +39,18 @@ module Everywhere
       end
     end
 
+    # Third-party sign-in for the native shells (everywhere.yml `auth:`). Middleware
+    # rather than routes: two thirds of the job is watching the app's *own* auth
+    # responses go by — see Everywhere::AuthHandoff. At the TOP of the stack,
+    # deliberately: a provider path from the web view must be diverted before any
+    # OmniAuth-family middleware (Devise's included) can answer it, and appended
+    # middleware sits below those or not depending on Gemfile order — which no
+    # app should have to know. Does nothing at all until the app declares `auth:`.
+    initializer "everywhere.auth" do |app|
+      require_relative "auth_handoff"
+      app.middleware.insert_before 0, Everywhere::AuthHandoff, root: app.root.to_s
+    end
+
     # /everywhere/ios_v1.json — the mobile shells' remote path configuration
     # (rules + settings.tabs), generated from config/everywhere.yml at request
     # time so tab changes ship with a normal deploy. A real controller (not

data/lib/everywhere/icon.rb

@@ -37,6 +37,83 @@ module Everywhere
     ICO_SIZES   = [16, 32, 48, 64, 128, 256].freeze
     LINUX_SIZES = [16, 32, 48, 64, 128, 256, 512].freeze
 
+    # The adaptive icon's foreground layer, one entry per density bucket (mdpi
+    # is 1x, the rest step 1.5/2/3/4x) of the 108dp layer. No legacy
+    # mipmap-<dpi>/ic_launcher.png companions: the shell's minSdk is 28, so
+    # every device that can install the app resolves @mipmap/ic_launcher to the
+    # anydpi-v26 adaptive icon and could never load them.
+    ANDROID_ADAPTIVE_SIZES = {
+      "mdpi" => 108, "hdpi" => 162, "xhdpi" => 216, "xxhdpi" => 324, "xxxhdpi" => 432
+    }.freeze
+
+    # Adaptive-icon safe-zone geometry, as a fraction of the 108dp layer.
+    #
+    # The launcher masks both layers to a shape *it* chooses and can parallax
+    # them, so only the centre 72dp is ever guaranteed visible — the outer 18dp
+    # on each side is headroom. The most aggressive stock mask is the circle
+    # inscribed in that 72dp viewport, and Google's keyline pulls the safe zone
+    # one step further in, to a 66dp circle. So a logo goes *inside* that
+    # circle, bounding box and all: side = 66/sqrt(2) = 46.7dp, i.e. 0.432 of
+    # the layer. Scaling a logo to the 72dp viewport instead is the usual
+    # mistake — it looks correct in a square preview and loses every corner on
+    # the round-mask launchers most devices ship with.
+    ADAPTIVE_ART = (66.0 / Math.sqrt(2)) / 108.0
+
+    # Alpha at or below this is background, not artwork — it survives PNG
+    # export slop and antialiased edges without counting them as content.
+    CONTENT_ALPHA = 8
+
+    # Opaque fraction of the source above which it is treated as full-bleed art
+    # rather than a logo. `config.icon` is one shared icon.png feeding macOS,
+    # iOS *and* Android, and the iOS path wants it opaque corner to corner, so
+    # in practice it usually is. Insetting that into the safe zone would render
+    # the source's own baked background as a shrunken tile floating inside the
+    # launcher's background colour — two nested backgrounds and a tiny logo.
+    #
+    # 0.95 sits in an empty gap. Shaped-but-full-bleed sources stay above it: a
+    # Big Sur squircle keeps ~99% of its bounding square, a 22%-rounded rect
+    # ~97%. Anything with a deliberate margin falls far below — even a mere 5%
+    # border leaves 81%. Nothing real lands near the line.
+    FULL_BLEED_COVERAGE = 0.95
+
+    # Both launcher aliases resolve to the same layers; ic_launcher_round exists
+    # only because the manifest's android:roundIcon asks for it by name. The
+    # layers are @mipmap, not the template placeholder's @drawable, because
+    # what gets stamped is a raster per density rather than one vector.
+    ANDROID_ADAPTIVE_ICON_XML = <<~XML
+      <?xml version="1.0" encoding="utf-8"?>
+      <adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+          <background android:drawable="@color/ic_launcher_background" />
+          <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+      </adaptive-icon>
+    XML
+
+    # Android 13+ themed ("Material You") icons tint the monochrome layer's
+    # *alpha* and throw its colour away, so the layer is only worth emitting
+    # when the alpha is already a silhouette — i.e. the inset branch, where the
+    # source arrived as a logo on transparency. Full-bleed art would tint as a
+    # solid filled square, which is worse than the launcher's own fallback, so
+    # that branch ships the icon without a monochrome layer and lets the
+    # fallback happen.
+    ANDROID_THEMED_ADAPTIVE_ICON_XML = <<~XML
+      <?xml version="1.0" encoding="utf-8"?>
+      <adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+          <background android:drawable="@color/ic_launcher_background" />
+          <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+          <monochrome android:drawable="@mipmap/ic_launcher_foreground" />
+      </adaptive-icon>
+    XML
+
+    # The background layer is a colour, not a bitmap: it has to survive being
+    # scaled and shifted by the launcher's parallax, which a PNG can't do
+    # without banding or seams at the edges.
+    ANDROID_BACKGROUND_XML = <<~XML
+      <?xml version="1.0" encoding="utf-8"?>
+      <resources>
+          <color name="ic_launcher_background">%s</color>
+      </resources>
+    XML
+
     # Modern (Xcode 14+) single-size asset catalog entry: one 1024px universal
     # image, iOS derives every size itself.
     IOS_APPICON_CONTENTS = <<~JSON
@@ -112,6 +189,48 @@ module Everywhere
       true
     end
 
+    # Write the Android launcher icon under `res_dir`: an adaptive icon's
+    # foreground layer per density, the solid-colour background resource, and
+    # the anydpi-v26 <adaptive-icon> pair that binds them (ic_launcher and the
+    # ic_launcher_round alias the manifest names). How large the artwork lands,
+    # and whether it can carry a themed-icon layer, both follow from what the
+    # source turns out to be — see android_art. `background` is an [r, g, b]
+    # triple as Icon.hex_rgb returns, default white. Returns true, or false if
+    # the source PNG can't be read — same contract as write_ios_appiconset, so
+    # the builder can warn and ship the placeholder.
+    def write_android_mipmaps(source, res_dir, background: nil)
+      raster = Raster.decode_png(source) or return false
+
+      rgb = Array(background || [255, 255, 255])[0, 3]
+      art, full_bleed = android_art(raster)
+
+      ANDROID_ADAPTIVE_SIZES.each do |density, layer|
+        dir = File.join(res_dir, "mipmap-#{density}")
+        FileUtils.mkdir_p(dir)
+
+        # The foreground keeps its alpha — the launcher composites it over the
+        # background layer, and its mask needs the surround empty to cut into.
+        foreground = if full_bleed
+                       filling(art, layer)
+                     else
+                       centred(art, layer, (layer * ADAPTIVE_ART).round)
+                     end
+        foreground.write_png(File.join(dir, "ic_launcher_foreground.png"))
+      end
+
+      xml = full_bleed ? ANDROID_ADAPTIVE_ICON_XML : ANDROID_THEMED_ADAPTIVE_ICON_XML
+      anydpi = File.join(res_dir, "mipmap-anydpi-v26")
+      FileUtils.mkdir_p(anydpi)
+      File.write(File.join(anydpi, "ic_launcher.xml"), xml)
+      File.write(File.join(anydpi, "ic_launcher_round.xml"), xml)
+
+      values = File.join(res_dir, "values")
+      FileUtils.mkdir_p(values)
+      File.write(File.join(values, "ic_launcher_background.xml"),
+                 format(ANDROID_BACKGROUND_XML, format("#%02X%02X%02X", *rgb)))
+      true
+    end
+
     # Build a macOS .icns from an already-shaped master PNG (ideally 1024px).
     # Returns true on success.
     def write_icns(master_png, dest)
@@ -167,6 +286,83 @@ module Everywhere
       m.captures.map { |c| c.to_i(16) }
     end
 
+    # How this source wants to be scaled onto a launcher layer. Returns
+    # [art, full_bleed] — either the raster untouched, to be scaled edge to
+    # edge because it is art designed to be cropped by the mask, or the source
+    # cropped to its opaque bounding box, to be inset into the safe zone.
+    #
+    # Cropping matters for the inset branch: scaling the whole canvas would let
+    # the source's own transparent padding eat into the 66dp circle and land
+    # the logo smaller than the safe zone actually allows. A source with no
+    # content at all is nothing to measure, so it takes the full-bleed path.
+    def android_art(raster)
+      bounds, coverage = content_bounds(raster)
+      return [raster, true] if bounds.nil? || coverage >= FULL_BLEED_COVERAGE
+
+      [crop(raster, *bounds), false]
+    end
+
+    # [[x0, y0, x1, y1], coverage] for the pixels above CONTENT_ALPHA — the
+    # half-open bounding box of the artwork and the fraction of the canvas it
+    # actually paints. [nil, 0.0] when the raster is entirely transparent.
+    def content_bounds(raster)
+      x0 = raster.width
+      y0 = raster.height
+      x1 = 0
+      y1 = 0
+      opaque = 0
+
+      raster.height.times do |y|
+        base = y * raster.width
+        raster.width.times do |x|
+          next if raster.pixels.getbyte(((base + x) * 4) + 3) <= CONTENT_ALPHA
+
+          opaque += 1
+          x0 = x if x < x0
+          x1 = x + 1 if x >= x1
+          y0 = y if y < y0
+          y1 = y + 1 if y >= y1
+        end
+      end
+
+      return [nil, 0.0] if opaque.zero?
+
+      [[x0, y0, x1, y1], opaque.to_f / (raster.width * raster.height)]
+    end
+
+    # The [x0, y0, x1, y1) region of `raster` as a new raster.
+    def crop(raster, x0, y0, x1, y1)
+      w = x1 - x0
+      h = y1 - y0
+      out = String.new(capacity: w * h * 4)
+      h.times { |y| out << raster.pixels.byteslice(((((y0 + y) * raster.width) + x0) * 4), w * 4) }
+      Raster.new(w, h, out)
+    end
+
+    # `raster` scaled to cover a `canvas`x`canvas` square and centre-cropped to
+    # it — no transparent border anywhere. Full-bleed art is meant to be
+    # cropped, so a non-square source loses its overhang rather than exposing
+    # bands of background the launcher's mask would read as a mistake.
+    def filling(raster, canvas)
+      fill = [canvas.to_f / raster.width, canvas.to_f / raster.height].max
+      sw = [(raster.width * fill).ceil, canvas].max
+      sh = [(raster.height * fill).ceil, canvas].max
+      crop(raster.resample(sw, sh), (sw - canvas) / 2, (sh - canvas) / 2,
+           ((sw - canvas) / 2) + canvas, ((sh - canvas) / 2) + canvas)
+    end
+
+    # `raster` scaled to fit a `box`-sized square (aspect preserved, never
+    # stretched) and centred on a transparent `canvas`x`canvas` raster.
+    def centred(raster, canvas, box)
+      fit = [box.to_f / raster.width, box.to_f / raster.height].min
+      sw = (raster.width * fit).round.clamp(1, box)
+      sh = (raster.height * fit).round.clamp(1, box)
+
+      out = Raster.transparent(canvas, canvas)
+      out.paste!(raster.resample(sw, sh), (canvas - sw) / 2, (canvas - sh) / 2)
+      out
+    end
+
     # PNG bytes of `master` at `size`x`size` (no-op resample when already sized).
     def sized_png(master, size)
       (size == master.width && size == master.height ? master : master.resample(size, size)).encode_png