ruby_everywhere 0.3.0 → 0.5.0

data/lib/everywhere/commands/dev.rb

@@ -3,10 +3,22 @@
 require "dry/cli"
 require "socket"
 require "shellwords"
+require "fileutils"
 require_relative "../shellout"
 require_relative "../paths"
+require_relative "../icon"
+require_relative "../desktop_assets"
 require_relative "../builders/ios"
+require_relative "../builders/android"
+require_relative "../builders/desktop"
 require_relative "../simulator"
+require_relative "../emulator"
+require_relative "../console"
+require_relative "../child_processes"
+require_relative "../task_pool"
+require_relative "../relay"
+require_relative "../dock"
+require_relative "../log_filter"
 require_relative "logs"
 
 module Everywhere
@@ -18,23 +30,49 @@ module Everywhere
     #
     # Target flags are additive (--desktop --ios --browser opens all three);
     # with no flags the server boots and a key menu launches shells on demand.
+    #
+    # Everything runs concurrently and nothing a shell does can end the session:
+    # each build owns a TaskPool thread that catches its own failures, each
+    # child's output is relayed through Console tagged with its source, and a
+    # Dock keeps the keymap and every target's state pinned to the bottom of the
+    # terminal while the logs scroll above it.
     class Dev < Dry::CLI::Command
       desc "Run the dev server with native shells on demand (live reload, no packaging)"
 
+      IOS_TARGET = "ios-arm64"
+      ANDROID_TARGET = "android-arm64"
+
+      # Key → the target it acts on, for the "press i to try again" hints.
+      KEY_FOR = { ios: "i", android: "a", desktop: "d", web: "r" }.freeze
+
       option :port,      default: "3000", desc: "Dev server port"
       option :shell_dir, default: nil,    desc: "Path to the shell's src-tauri directory"
-      option :target,    default: nil,    desc: "Single shell to open: macos (desktop) or ios (Simulator)"
+      option :target,    default: nil,    desc: "Single shell to open: macos (desktop), ios (Simulator) or android (emulator)"
       option :desktop,   type: :boolean, default: false, desc: "Open the desktop shell"
       option :ios,       type: :boolean, default: false, desc: "Open the iOS Simulator shell"
+      option :android,   type: :boolean, default: false, desc: "Open the Android emulator shell"
+      option :mobile,    type: :boolean, default: false, desc: "Open both mobile shells (same as --ios --android)"
       option :browser,   type: :boolean, default: false, desc: "Open the app in the default browser"
+      option :dev_url,   default: nil,    desc: "Explicit URL for the device to load (e.g. a LAN address for a physical Android device)"
 
-      def call(port: "3000", shell_dir: nil, target: nil, desktop: false, ios: false, browser: false, **)
+      def call(port: "3000", shell_dir: nil, target: nil, desktop: false, ios: false, android: false,
+               mobile: false, browser: false, dev_url: nil, **)
         @shell_dir = shell_dir
-        targets = requested_targets(target, desktop: desktop, ios: ios, browser: browser)
-        framework, @config = detect_app
+        @port = port
+        @dev_url_override = dev_url
+        # Children are spawned from pool threads as well as the main one.
+        @pids = {}
+        @relays = {}
+        @children = Mutex.new
+        targets = requested_targets(target, desktop: desktop, ios: ios, android: android,
+                                            mobile: mobile, browser: browser)
+        @framework, @config = detect_app
 
-        start_server(framework, port)
-        @dev_url = if framework
+        @pool = TaskPool.new(on_error: method(:report_failure))
+        @dock = Dock.open(dock_targets(targets), keys: $stdin.tty?)
+
+        start_server(@framework, port)
+        @dev_url = if @framework
                      "http://127.0.0.1:#{port}#{@config.entry_path}"
                    else
                      "#{@config.remote_url}#{@config.entry_path}"
@@ -45,7 +83,7 @@ module Everywhere
         targets << "desktop" if targets.empty? && !$stdin.tty?
         targets.each { |t| launch(t) }
 
-        $stdin.tty? ? interact : wait_for_children
+        $stdin.tty? ? interact : run_headless
       rescue Interrupt
         nil
       ensure
@@ -54,14 +92,28 @@ module Everywhere
 
       private
 
-      def requested_targets(target, desktop:, ios:, browser:)
+      # --target names ONE shell; the boolean flags are additive. Desktop is the
+      # fallback for any --target that isn't a mobile os, which keeps
+      # `--target macos-arm64` (and a bare `--target`) meaning what it always did.
+      # --mobile is exactly --ios --android.
+      def requested_targets(target, desktop:, ios:, android:, mobile:, browser:)
+        target_os = target && Everywhere::Config.os_of(target)
         targets = []
-        targets << "desktop" if desktop || (target && Everywhere::Config.os_of(target) != "ios")
-        targets << "ios"     if ios     || (target && Everywhere::Config.os_of(target) == "ios")
+        targets << "desktop" if desktop || (target && !%w[ios android].include?(target_os))
+        targets << "ios"     if ios     || mobile || target_os == "ios"
+        targets << "android" if android || mobile || target_os == "android"
         targets << "browser" if browser
         targets
       end
 
+      # What the dock lists. On a terminal every shell is one keypress away, so
+      # show them all and let the idle ones sit dim; headless, only show what was
+      # actually asked for.
+      def dock_targets(requested)
+        shells = $stdin.tty? ? %i[desktop ios android] : requested.map(&:to_sym)
+        ([@framework ? :web : nil] + shells).compact.uniq
+      end
+
       # The framework (nil for remote-only roots) and config. A root with
       # neither a framework nor remote.url is a genuine error.
       def detect_app
@@ -78,6 +130,8 @@ module Everywhere
         [framework, config]
       end
 
+      # --- the dev server -------------------------------------------------------
+
       def start_server(framework, port)
         unless framework
           # Remote-mode app with no local code (just everywhere.yml): nothing
@@ -89,33 +143,220 @@ module Everywhere
         if port_open?(port)
           UI.warn "something is ALREADY RUNNING on port #{port} — attaching to it instead of starting"
           UI.warn "#{UI.dim("your Procfile.dev/watchers are NOT running; stop that server or use --port if this isn't yours")}"
+          @dock.set(:web, :running, detail: "port #{port} (attached)")
         else
           UI.step("starting #{UI.bold(framework.name)} dev server #{UI.dim("(" + framework.dev_command + ")")}")
-          @server_pid = Shellout.spawn({ "PORT" => port.to_s }, framework.dev_command, chdir: framework.root)
-          @server_thread = Process.detach(@server_pid)
+          @dock.set(:web, :booting)
+          supervise(:web, { "PORT" => port.to_s }, framework.dev_command, chdir: framework.root)
           wait_for_port(port)
+          @dock.set(:web, :running, detail: ":#{port}")
         end
       end
 
+      # Kill and respawn just the dev server — for a Gemfile or initializer
+      # change, where a full restart of the session would mean rebuilding the
+      # native shells for nothing.
+      def restart_server
+        return UI.warn("nothing to restart — this app runs in remote mode") unless @framework
+
+        @dock.set(:web, :booting, detail: "restarting")
+        UI.step("restarting the dev server")
+        stop_child(:web)
+        start_server(@framework, @port)
+      end
+
+      # --- shells ---------------------------------------------------------------
+
       def launch(target)
         case target
-        when "ios"     then launch_ios
+        when "ios"     then background(:ios)     { launch_ios }
+        when "android" then background(:android) { launch_android }
         when "browser" then launch_browser
-        else                launch_desktop
+        else                background(:desktop) { launch_desktop }
         end
       end
 
+      # A second press while a build is still running is refused, not queued:
+      # Builders::Ios rm_rf's and re-copies a shared work dir on every run, so
+      # two overlapping builds would corrupt each other.
+      def background(name, &block)
+        case @pool.start(name, &block)
+        when :busy
+          UI.warn "#{Dock::State::LABELS[name]} is already working — #{UI.dim("give it a moment")}"
+        end
+      end
+
+      # `d` relaunches, the same way `i` and `a` do — quit the running window and
+      # open a fresh one. Refusing with "already running" made the desktop the
+      # odd one out, and left no way to restart a shell that had wedged or was
+      # holding stale NATIVE_CONFIG.
+      #
+      # The rebuild is free either way: a warm `cargo run` re-checks the crate
+      # graph in well under a second before handing off.
+      # native/desktop/assets/** → the staged flat folder the running shell
+      # reads. Runs the same compiler `every build` does, so an asset that
+      # resolves in dev resolves in the packaged app too. Returns
+      # [dir, errors]; the dir is returned even when the app ships no assets,
+      # because the shell only has to cope with it not existing.
+      def stage_desktop_assets
+        dest = Everywhere::Paths.desktop_assets_dir(@config.bundle_id)
+        source = File.join(@config.root, "native", "desktop", "assets")
+        _names, errors = Everywhere::DesktopAssets.write!(source, dest)
+        [dest, errors]
+      end
+
+      # A minimal .app around the dev binary, so macOS has a CFBundleName to
+      # read. Without it every menu that names the app says "example-shell" —
+      # the crate name — because an unbundled process has nothing else to go on.
+      # (Setting NSProcessInfo's processName at runtime does NOT fix this: the
+      # menu bar and the predefined About/Hide/Quit items are built from the
+      # bundle, and macOS has already decided by the time any Rust runs.)
+      #
+      # Only the plist matters here. No icon is stamped: the shell sets the Dock
+      # icon at runtime from NATIVE_ICON_PATH, because Tauri applies its own
+      # compiled-in icon after launch and would win over a bundle icns anyway.
+      # `every build` writes the real, complete plist — this is the dev subset.
+      def stage_dev_bundle
+        app = File.join(Everywhere::Paths.desktop_dev_app_dir(@config.bundle_id),
+                        "#{@config.name}.app")
+        macos = File.join(app, "Contents", "MacOS")
+        FileUtils.mkdir_p(macos)
+        File.write(File.join(app, "Contents", "Info.plist"), dev_info_plist)
+        [app, File.join(macos, dev_exe_name)]
+      end
+
+      # Spaces are legal in CFBundleExecutable but a nuisance in every shell
+      # command that names it, so the executable follows the packaged app's
+      # convention and drops them.
+      def dev_exe_name = @config.name.gsub(/\s+/, "")
+
+      def dev_info_plist
+        <<~PLIST
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>CFBundleName</key><string>#{@config.name}</string>
+            <key>CFBundleDisplayName</key><string>#{@config.name}</string>
+            <key>CFBundleExecutable</key><string>#{dev_exe_name}</string>
+            <key>CFBundleIdentifier</key><string>#{@config.bundle_id}</string>
+            <key>CFBundlePackageType</key><string>APPL</string>
+            <key>CFBundleShortVersionString</key><string>#{@config.version}</string>
+            <key>NSHighResolutionCapable</key><true/>
+          </dict>
+          </plist>
+        PLIST
+      end
+
+      # The Dock icon for the running shell. `cargo run` produces a bare binary
+      # with no .app around it, so macOS has nothing to read an icon from and
+      # Tauri's compiled-in placeholder wins — which is how you end up staring
+      # at the gem's icon while testing your own app.
+      #
+      # Shaped with the same Big Sur inset + squircle the packaged .icns gets
+      # (Icon.macos_master), so the Dock looks identical in dev and in a release
+      # build rather than subtly rounder in one of them. Returns "" when the app
+      # has no icon — the shell reads that as "leave it alone".
+      def stage_desktop_icon
+        source = @config.icon
+        return "" unless source && File.exist?(source)
+
+        dest = File.join(Everywhere::Paths.desktop_icon_dir(@config.bundle_id), "icon.png")
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(source, dest) unless Everywhere::Icon.macos_master(source, dest)
+        dest
+      rescue StandardError => e
+        # A Dock icon is never worth failing a dev session over.
+        UI.warn("couldn't prepare the Dock icon (#{e.class}) — using the default")
+        ""
+      end
+
       def launch_desktop
-        if @desktop_pid && alive?(@desktop_pid)
-          UI.warn "desktop shell already running"
+        # A bad `window:` or a broken assets/ tree marks the desktop red and
+        # leaves the dev server and the mobile shells alone — the same deal
+        # every other target gets when its build fails. Dying here would take
+        # the whole session down over a misspelled title bar, and you'd fix it
+        # and have to start over.
+        errors = @config.window_errors
+        unless errors.empty?
+          errors.each { |error| UI.warn(error) }
+          @dock.set(:desktop, :failed, detail: "window: in config/everywhere.yml")
           return
         end
-        dir = @shell_dir || Everywhere::Paths.shell_dir!
-        UI.step("opening desktop shell → #{UI.cyan(@dev_url)}")
-        @desktop_pid = Shellout.spawn({ "NATIVE_DEV_URL" => @dev_url, "NATIVE_CONFIG" => @config.to_shell_json,
-                                        "CARGO_TARGET_DIR" => Everywhere::Paths.cargo_target_dir },
-                                      "cargo run", chdir: dir)
-        @desktop_thread = Process.detach(@desktop_pid)
+
+        assets_dir, asset_errors = stage_desktop_assets
+        unless asset_errors.empty?
+          asset_errors.each { |error| UI.warn(error) }
+          @dock.set(:desktop, :failed, detail: "native/desktop/assets")
+          return
+        end
+
+        # Stamps the per-app shell when the app declares native.desktop, and
+        # hands back the gem's copy when it doesn't. Done before the restart
+        # dance so a config error doesn't first kill a working window.
+        prepared = Builders::Desktop.new(config: @config, root: @config.root,
+                                         template_dir: @shell_dir).prepare!
+
+        pid = child_pid(:desktop)
+        restarting = pid && ChildProcesses.alive?(pid)
+        if restarting
+          @dock.set(:desktop, :booting, detail: "restarting")
+          UI.step("quitting the running desktop shell")
+          stop_child(:desktop, grace: 3)
+        end
+
+        UI.step("#{restarting ? "reopening" : "opening"} desktop shell → #{UI.cyan(@dev_url)}")
+        # A cold cargo build is minutes long, so the dock says "building" until
+        # cargo itself reports it has handed off to the app. There is no other
+        # signal that the compile turned into a running window.
+        @dock.set(:desktop, :building)
+        # CARGO_TERM_COLOR: cargo drops color when its stdout isn't a terminal.
+        # It IS one here (we relay over a pty), but the variable costs nothing
+        # and keeps the output right if the pty path ever falls back to a pipe.
+        # NATIVE_ASSETS_DIR: `cargo run` has no .app around it, so there's no
+        # Resources/assets for the shell to find. It gets the staged copy
+        # instead, which is re-stamped just above on every launch — so editing a
+        # PNG and pressing `d` is enough to see it.
+        supervise(:desktop,
+                  { "NATIVE_DEV_URL" => @dev_url, "NATIVE_CONFIG" => @config.to_shell_json,
+                    "NATIVE_ASSETS_DIR" => assets_dir,
+                    "NATIVE_ICON_PATH" => stage_desktop_icon,
+                    "CARGO_TARGET_DIR" => prepared.target_dir,
+                    "CARGO_TERM_COLOR" => "always" },
+                  desktop_command(prepared), chdir: prepared.dir,
+                  filter: LogFilter.for(:cargo), log: dist_log("desktop-dev.log"),
+                  # cargo colors its status lines, so the marker has to be
+                  # matched past the escape codes. "Finished" is cargo's last
+                  # word before we hand off to the app; on the `cargo run` path
+                  # it was "Running".
+                  on_line: lambda { |line|
+                    @dock.set(:desktop, :running) if UI.strip_ansi(line).match?(/\A\s*(Running|Finished)\b/)
+                  })
+      end
+
+      # macOS runs the shell from inside a throwaway .app so it has a name;
+      # everywhere else `cargo run` is still the whole story.
+      #
+      # Three steps in one command rather than three Ruby calls, because the
+      # link has to happen between the compile and the launch and we want ONE
+      # supervised child: cargo's progress relays into the dock, and exec then
+      # replaces it with the app, so the pid we're tracking is the window.
+      #
+      # A hard link, not a copy: same volume (both under ~/.rubyeverywhere), so
+      # it's free and instant, where copying a debug Tauri binary is ~100MB on
+      # every launch. cargo replaces the file on rebuild rather than writing
+      # through it, so the link is remade each time — hence `ln -f`.
+      def desktop_command(prepared)
+        return "cargo run" unless RUBY_PLATFORM.include?("darwin")
+
+        _app, exe = stage_dev_bundle
+        built = File.join(prepared.target_dir, "debug", "example-shell")
+        [
+          "cargo build",
+          "{ ln -f #{built.shellescape} #{exe.shellescape} 2>/dev/null || " \
+            "cp -f #{built.shellescape} #{exe.shellescape}; }",
+          "exec #{exe.shellescape}"
+        ].join(" && ")
       end
 
       # Build the shell (Debug, warm after the first run), put it on a booted
@@ -124,14 +365,43 @@ module Everywhere
       # covers plain http for local networking. Pressing i again rebuilds and
       # relaunches, so it doubles as a native-shell reload.
       def launch_ios
-        app = Builders::Ios.new(config: @config, root: @config.root, target: "ios-arm64")
+        @dock.set(:ios, :building)
+        app = Builders::Ios.new(config: @config, root: @config.root, target: IOS_TARGET)
                            .build!(dist_dir: File.expand_path("dist", @config.root), dev: true)
 
+        @dock.set(:ios, :booting, detail: "Simulator")
         udid = Simulator.boot_default!
+        @dock.set(:ios, :installing)
         UI.step("installing #{UI.bold(File.basename(app))}")
         Simulator.install(udid, app)
         UI.step("launching → #{UI.cyan(@dev_url)}")
-        Simulator.launch(udid, @config.bundle_id(target: "ios-arm64"), env: { "EVERYWHERE_DEV_URL" => @dev_url })
+        Simulator.launch(udid, @config.bundle_id(target: IOS_TARGET),
+                         env: { "EVERYWHERE_DEV_URL" => @dev_url })
+        @dock.set(:ios, :running, detail: "Simulator")
+      end
+
+      # The Android counterpart of launch_ios: build Debug (warm after the first
+      # run), put it on a booted emulator and launch it. Unlike the Simulator,
+      # which shares the Mac's loopback, an Android device reaches the host
+      # through `adb reverse` — so the URL is resolved per-device rather than
+      # reused from @dev_url (see Emulator.dev_url for the fallback ladder).
+      # Pressing a again rebuilds and relaunches, so it doubles as a reload.
+      def launch_android
+        @dock.set(:android, :booting, detail: "emulator")
+        serial = Emulator.boot_default!
+        url = Emulator.dev_url(@dev_url, serial: serial, port: @port, override: @dev_url_override)
+
+        @dock.set(:android, :building)
+        app = Builders::Android.new(config: @config, root: @config.root, target: ANDROID_TARGET)
+                               .build!(dist_dir: File.expand_path("dist", @config.root), dev: true, dev_url: url)
+
+        application_id = @config.bundle_id(target: ANDROID_TARGET)
+        @dock.set(:android, :installing)
+        UI.step("installing #{UI.bold(File.basename(app))}")
+        Emulator.install(serial, app, application_id: application_id)
+        UI.step("launching → #{UI.cyan(url)}")
+        Emulator.launch(serial, application_id)
+        @dock.set(:android, :running, detail: serial)
       end
 
       def launch_browser
@@ -140,12 +410,12 @@ module Everywhere
         Shellout.run?(opener, @dev_url, quiet: true)
       end
 
-      # Toggle the `every logs --ios` stream, interleaved with the server
-      # output on this same terminal.
+      # Toggle the `every logs --ios` stream, tagged and interleaved with the
+      # server output on this same terminal.
       def toggle_logs
-        if @logs_pid && alive?(@logs_pid)
-          stop(@logs_pid)
-          @logs_pid = nil
+        pid = child_pid(:logs)
+        if pid && ChildProcesses.alive?(pid)
+          stop_child(:logs)
           UI.step("stopped iOS Simulator logs")
           return
         end
@@ -156,24 +426,98 @@ module Everywhere
           return
         end
         UI.step("watching iOS Simulator logs #{UI.dim("(press l again to stop)")}")
-        @logs_pid = Shellout.spawn({}, Logs.new.argv(udid).shelljoin, chdir: Dir.pwd)
+        supervise(:logs, {}, Logs.new.argv(udid).shelljoin, chdir: Dir.pwd)
+      end
+
+      # --- child supervision ----------------------------------------------------
+
+      # Spawn a long-lived child on a pty and relay its output, one tagged line
+      # at a time. A pty rather than a pipe so foreman, cargo and friends still
+      # believe they're on a terminal and keep their colors; PTY.spawn also
+      # setsids, so a Ctrl-C at our terminal can't reach them and teardown
+      # decides when they die.
+      def supervise(key, env, cmd, chdir:, filter: nil, log: nil, on_line: nil)
+        if Shellout.pty?
+          io, pid = Shellout.spawn_pty(env, cmd, chdir: chdir)
+          thread = relay_thread(key, io, pid, filter: filter, log: log, on_line: on_line)
+        else
+          # Windows, or any platform without a pty: fall back to inherited fds.
+          # No tags and no dock framing, but everything else works.
+          pid = Shellout.spawn(env, cmd, chdir: chdir)
+        end
+        Process.detach(pid)
+        @children.synchronize do
+          @pids[key] = pid
+          @relays[key] = thread if thread
+        end
+        pid
       end
 
-      # Key menu. io/console's getch holds full raw mode while blocked, which
-      # clears OPOST and stair-steps every log line the server prints; stty
-      # -icanon -echo disables only line buffering and echo, leaving output
-      # processing (and Ctrl-C as SIGINT) intact.
+      def relay_thread(key, io, pid, filter:, log:, on_line:)
+        Thread.new do
+          Thread.current.name = "relay-#{key}"
+          Thread.current.report_on_exception = false
+          begin
+            Relay.new(io, source: key, log: log, filter: filter, on_line: on_line).run
+          rescue StandardError => e
+            # Losing a relay costs us that child's output, nothing more. It must
+            # not surface later out of the join in teardown.
+            Kernel.warn("#{key} output relay stopped: #{e.class}: #{e.message}")
+          end
+          # Only report a death we didn't ask for. stop_child removes the pid
+          # BEFORE it signals, so a deliberate restart can never match here —
+          # what does match is a shell that quit or crashed on its own, which is
+          # exactly what the dock should show.
+          @dock.set(key, :stopped) if !@stopping && @children.synchronize { @pids[key] } == pid
+        end
+      end
+
+      # TERM the child's whole process group, escalate to KILL, and wait for the
+      # relay to drain so its last lines aren't lost. The pid is dropped from
+      # the registry FIRST, so the relay knows this death was asked for.
+      def stop_child(key, grace: 5)
+        pid, thread = @children.synchronize { [@pids.delete(key), @relays.delete(key)] }
+        return unless pid
+
+        reap([pid], grace: grace)
+        thread&.join(1)
+      end
+
+      # TERM each process group, wait for them together rather than serially,
+      # then KILL the stragglers.
+      def reap(pids, grace: 5)
+        live = pids.compact.select { |pid| ChildProcesses.alive?(pid) }
+        return if live.empty?
+
+        live.each { |pid| ChildProcesses.signal(pid, "TERM") }
+        deadline = monotonic + grace
+        sleep(0.1) while live.any? { |pid| ChildProcesses.alive?(pid) } && monotonic < deadline
+        live.select { |pid| ChildProcesses.alive?(pid) }.each { |pid| ChildProcesses.signal(pid, "KILL") }
+      end
+
+      def child_pid(key) = @children.synchronize { @pids[key] }
+
+      # --- the key menu ---------------------------------------------------------
+
+      # io/console's getch holds full raw mode while blocked, which clears OPOST
+      # and stair-steps every log line we relay; stty -icanon -echo disables only
+      # line buffering and echo, leaving output processing (and Ctrl-C as SIGINT)
+      # intact. Builds no longer run on this thread, so the menu stays responsive
+      # while one is going — including `q`.
       def interact
-        UI.note("press #{UI.bold("d")} desktop · #{UI.bold("i")} iOS Simulator · #{UI.bold("b")} browser · " \
-                "#{UI.bold("l")} iOS logs · #{UI.bold("q")} quit", marker: "⌨", color: :cyan)
+        @dock.announce_keys
         saved_tty = `stty -g`.chomp
         system("stty", "-icanon", "-echo")
+        trap_exit_signals
         loop do
           case $stdin.getc
-          when "d"               then launch("desktop")
-          when "i"               then launch("ios")
-          when "b"               then launch("browser")
-          when "l"               then toggle_logs
+          when "d"                then background(:desktop) { launch_desktop }
+          when "i"                then background(:ios)     { launch_ios }
+          when "a"                then background(:android) { launch_android }
+          when "b"                then launch_browser
+          when "l"                then toggle_logs
+          when "r"                then background(:web)     { restart_server }
+          when "?"                then @dock.toggle_help
           when "q", "\u0004", nil then break # q, Ctrl-D, EOF (Ctrl-C stays a real SIGINT)
           end
         end
@@ -181,33 +525,94 @@ module Everywhere
         system("stty", saved_tty) unless saved_tty.to_s.empty?
       end
 
-      def wait_for_children
-        (@server_thread || @desktop_thread)&.join
+      # The dock hides the cursor and the key loop puts the tty in -icanon
+      # -echo; a SIGTERM that skipped our ensure blocks would leave the user's
+      # shell in that state. exit(1) from a trap unwinds normally, which is all
+      # this needs to do — a handler must stay this small, because anything that
+      # takes a lock (Console, the dock) raises ThreadError in trap context.
+      def trap_exit_signals
+        %w[TERM HUP].each { |sig| Signal.trap(sig) { exit(1) } }
+      rescue ArgumentError
+        nil
       end
 
-      def teardown
-        [@server_pid, @desktop_pid, @logs_pid].compact.each { |pid| stop(pid) }
+      # --- headless -------------------------------------------------------------
+
+      # No terminal to take keystrokes from, so there's no menu to return to:
+      # wait for the builds, and make a failure an actual non-zero exit.
+      def run_headless
+        @pool.wait_all
+        failed = @pool.failed
+        UI.die!("#{failed.join(", ")} failed — see the log above") if failed.any?
+
+        watcher = @children.synchronize { @relays[:web] || @relays[:desktop] }
+        return watcher.join if watcher
+
+        # No pty (or no relay): fall back to waiting on the process itself.
+        pid = child_pid(:web) || child_pid(:desktop)
+        sleep(1) while pid && ChildProcesses.alive?(pid)
       end
 
-      def stop(pid)
-        return unless alive?(pid)
+      # --- failure --------------------------------------------------------------
 
-        begin
-          Process.kill("TERM", -Process.getpgid(pid))
-        rescue StandardError
-          Process.kill("TERM", pid) rescue nil
+      # A build failing is news, not the end of the session. UI.die! has already
+      # printed the red ✗ at the point of failure, correctly interleaved with the
+      # build's own output, so a Fatal needs no second message — just the dock
+      # state and a reminder that everything else is still up.
+      def report_failure(name, error, stopping)
+        return if stopping
+
+        @dock.set(name, :failed, detail: failure_detail(name))
+        UI.bad("#{Dock::State::LABELS[name]} failed: #{error.message}") unless error.is_a?(Everywhere::Fatal)
+        return unless (key = KEY_FOR[name])
+
+        UI.note("everything else is still running — press #{UI.bold(key)} to try again",
+                marker: "⌨", color: :cyan)
+      end
+
+      # nil for targets with no build log of their own — the dock's ✗ already
+      # says "failed", so repeating the word adds nothing.
+      def failure_detail(name)
+        log = { ios: "dist/ios-build.log", android: "dist/android-build.log" }[name]
+        "see #{log}" if log
+      end
+
+      # --- teardown -------------------------------------------------------------
+
+      # Teardown must never raise — it runs from an ensure, where an exception
+      # would mask whatever actually ended the session — and one failed step
+      # must not skip the rest, or a child survives the CLI that spawned it.
+      def teardown
+        @stopping = true
+        pids, relays = @children ? @children.synchronize { [@pids.values, @relays.values] } : [[], []]
+        [
+          -> { @dock&.close },
+          -> { @pool&.shutdown },
+          # TERM everything, then give it a moment and KILL whatever is left.
+          # The CLI exits the instant this returns, so anything still alive is
+          # orphaned — and a windowed shell is exactly the kind of child that
+          # doesn't drop dead on the first signal.
+          -> { reap(pids, grace: 2) },
+          -> { relays.each { |thread| thread.join(1) } }
+        ].each do |step|
+          step.call
+        rescue StandardError => e
+          Kernel.warn("teardown: #{e.class}: #{e.message}")
         end
       end
 
-      def alive?(pid)
-        Process.kill(0, pid)
-        true
-      rescue Errno::ESRCH
-        false
-      rescue Errno::EPERM
-        true
+      # --- helpers --------------------------------------------------------------
+
+      def dist_log(name)
+        dir = File.expand_path("dist", @config.root)
+        FileUtils.mkdir_p(dir)
+        File.join(dir, name)
+      rescue StandardError
+        nil
       end
 
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
       def port_open?(port)
         TCPSocket.new("127.0.0.1", Integer(port)).close
         true