ruby_everywhere 0.4.0 → 0.6.0

data/lib/everywhere/dock.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require_relative "ui"
+require_relative "console"
+require_relative "dock/state"
+require_relative "dock/footer"
+require_relative "dock/screen"
+
+module Everywhere
+  # The pinned status bar at the bottom of `every dev`.
+  #
+  # The old key menu was printed once, before the loop, and was gone from the
+  # screen within seconds of the Rails server starting to log. The dock keeps
+  # the keymap — and what each target is actually doing — permanently visible,
+  # while the logs scroll normally above it.
+  #
+  # It installs itself as Console's sink, so every write in the process (CLI
+  # chrome, relayed server output, filtered build output) is framed by an erase
+  # and a repaint. See Dock::Screen for why it repaints rather than reserving
+  # rows with a scroll region.
+  class Dock
+    TICK = 0.2
+
+    KEYS = [
+      ["d", "desktop"],
+      ["i", "iOS"],
+      ["a", "Android"],
+      ["b", "browser"],
+      ["l", "logs"],
+      ["r", "restart"],
+      ["?", "help"],
+      ["q", "quit"]
+    ].freeze
+
+    HELP = [
+      ["d", "relaunch the desktop shell (opens it if it isn't running)"],
+      ["i", "rebuild, reinstall and relaunch on the iOS Simulator"],
+      ["a", "rebuild, reinstall and relaunch on the Android emulator"],
+      ["b", "open the app in your default browser"],
+      ["l", "start/stop streaming iOS Simulator logs"],
+      ["r", "restart the dev server only"],
+      ["?", "hide this help"],
+      ["q", "quit (Ctrl-C works too)"]
+    ].freeze
+
+    # A dock needs room to be worth having, and a terminal that understands
+    # cursor movement. NO_COLOR is deliberately NOT a disqualifier: it governs
+    # SGR, not cursor control, and the footer's glyphs carry the meaning on
+    # their own.
+    MIN_ROWS = 12
+    MIN_COLS = 40
+
+    def self.open(targets, io: $stdout, keys: true, size: nil)
+      return Null.new(targets, keys: keys) unless drawable?(io, size)
+
+      new(targets, io: io, keys: keys, size: size).tap(&:install)
+    end
+
+    def self.drawable?(io, size)
+      return false if ENV["EVERY_NO_DOCK"]
+      return false unless io.respond_to?(:tty?) && io.tty?
+      return false if ENV["TERM"].to_s.empty? || ENV["TERM"] == "dumb"
+
+      rows, cols = size || Screen.new(io: io).size
+      rows >= MIN_ROWS && cols >= MIN_COLS
+    end
+
+    def initialize(targets, io: $stdout, keys: true, size: nil)
+      @state = State.new(targets)
+      @screen = Screen.new(io: io, size: size)
+      @keys = keys
+      @help = false
+      @frame = 0
+      @dirty = true
+      @open = false
+    end
+
+    attr_reader :state
+
+    def install
+      @open = true
+      @screen.open
+      Console.dock = self
+      trap_resize
+      start_ticker
+      self
+    end
+
+    # --- state --------------------------------------------------------------
+
+    def set(key, state, detail: nil)
+      @state.set(key, state, detail: detail)
+      @dirty = true
+      refresh
+    end
+
+    def detail(key, text)
+      @state.detail(key, text)
+      @dirty = true
+    end
+
+    def toggle_help
+      @help = !@help
+      @dirty = true
+      refresh
+    end
+
+    # The dock draws the keymap permanently, so there is nothing to announce.
+    # Null overrides this to print the one-shot hint the old command used.
+    def announce_keys = nil
+
+    # --- drawing ------------------------------------------------------------
+
+    # Called by Console, which already holds the lock. Content must end at
+    # column 1, or the erase math for the next frame is off by a row.
+    def emit(text)
+      body = text.end_with?("\n") ? text : "#{text}\n"
+      @screen.frame(body, footer_rows)
+      @dirty = false
+    end
+
+    def refresh
+      Console.synchronize do
+        next unless @open
+
+        @screen.frame("", footer_rows)
+        @dirty = false
+      end
+    end
+
+    # Wipe the footer and leave it wiped — for stderr, or an interactive child
+    # that needs the screen to itself.
+    def clear = @screen.clear
+
+    def close
+      return unless @open
+
+      # Order matters: drop the flag so the ticker stops drawing, let it finish
+      # the frame it may be mid-way through, and only then unhook and restore.
+      @open = false
+      @ticker&.join(TICK * 2)
+      @ticker&.kill
+      Console.dock = nil
+      Console.synchronize { @screen.close }
+    end
+
+    private
+
+    # One column short of the terminal on purpose. A row filled to the last
+    # column leaves the cursor in a pending-wrap state whose handling varies
+    # between terminals, and a footer row that wraps costs the erase math a row.
+    def footer_rows
+      lines = Footer.render(@state.targets,
+                            cols: [@screen.cols - 1, 1].max,
+                            keys: (@keys ? KEYS : nil),
+                            frame: @frame,
+                            elapsed: ->(target) { @state.elapsed(target) },
+                            rule: @screen.rows >= 24)
+      @help ? lines + help_rows : lines
+    end
+
+    def help_rows
+      width = HELP.map { |key, _| key.length }.max
+      HELP.map { |key, desc| "  #{UI.bold(key.ljust(width))}  #{UI.dim(desc)}" }
+    end
+
+    # An idle dev session should emit zero bytes per second, so only redraw when
+    # something changed or a spinner is actually turning.
+    def start_ticker
+      @ticker = Thread.new do
+        Thread.current.name = "dock"
+        Thread.current.report_on_exception = false
+        while @open
+          sleep TICK
+          next unless @open
+
+          # Screen#size re-reads the ioctl every frame, so a resize needs
+          # nothing more than a redraw.
+          if @resized
+            @resized = false
+            @dirty = true
+          end
+          busy = @state.busy?
+          @frame += 1 if busy
+          refresh if busy || @dirty
+        end
+      rescue StandardError
+        # A dock that can't draw must never be the reason a dev session dies.
+        @open = false
+        Console.dock = nil
+      end
+    end
+
+    # Trap handlers must not take a lock (Ruby raises ThreadError when the lock
+    # is held in trap context), so this only sets a flag; the ticker draws.
+    def trap_resize
+      Signal.trap("WINCH") { @resized = true }
+    rescue ArgumentError, StandardError
+      nil
+    end
+
+    # The headless stand-in: same API, no escape sequences ever. Used for CI,
+    # pipes, `| tee`, dumb terminals and windows too small to spare the rows.
+    # It narrates transitions as ordinary lines so a piped log still reads.
+    #
+    # Note it never installs itself as Console's sink — output keeps going
+    # straight to $stdout, exactly as it did before the dock existed.
+    class Null
+      def initialize(targets, keys: true)
+        @state = State.new(targets)
+        @keys = keys
+      end
+
+      attr_reader :state
+
+      def install = self
+
+      def set(key, state, detail: nil)
+        target = @state.set(key, state, detail: detail) or return
+        UI.step("#{target.label} → #{[state, detail].compact.join(" ")}")
+      end
+
+      def detail(_key, _text) = nil
+      def toggle_help = nil
+      def emit(text) = nil
+      def refresh = nil
+      def clear = nil
+      def close = nil
+
+      # The one-shot keymap the old command printed, kept for headless runs.
+      def announce_keys
+        return unless @keys
+
+        UI.note(KEYS.map { |key, desc| "#{UI.bold(key)} #{desc}" }.join(" · "), marker: "⌨", color: :cyan)
+      end
+    end
+  end
+end

data/lib/everywhere/emulator.rb

@@ -372,7 +372,7 @@ module Everywhere
     # 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) }
+      pid = Process.spawn(Shellout.child_env, *argv, pgroup: true, out: File::NULL, err: File::NULL)
       Process.detach(pid)
       pid
     end
@@ -384,7 +384,7 @@ module Everywhere
     # 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) }
+      pid = Process.spawn(Shellout.child_env, *argv, out: File::NULL, err: File::NULL)
       deadline = Time.now + timeout
       loop do
         return true if Process.waitpid(pid, Process::WNOHANG)

data/lib/everywhere/fatal.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Everywhere
+  # A failure that ends the current unit of work — not necessarily the process.
+  #
+  # It subclasses SystemExit deliberately. At the top level Ruby exits with
+  # #status and prints nothing (UI.die! has already written the ✗ line), so an
+  # uncaught Fatal behaves exactly like the Kernel#abort it replaces. Inside
+  # `every dev` a worker thread catches it instead and returns to the key menu,
+  # which is the whole point: a Swift typo must not take the Rails server down
+  # with it.
+  #
+  # CAUTION for anyone catching this in a thread: MRI enqueues a SystemExit that
+  # escapes a non-main thread onto the MAIN thread, which re-raises it wherever
+  # that thread happens to be. A worker must therefore `rescue Exception`, not
+  # `rescue Everywhere::Fatal` — see TaskPool.
+  class Fatal < SystemExit
+    def initialize(status = 1, message = nil) = super
+  end
+end

data/lib/everywhere/line_pump.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Everywhere
+  # Turns the raw byte stream off a pty master into whole lines.
+  #
+  # `every dev` relays the dev server and the desktop shell itself so it can tag
+  # each line with its source. That relay has to be line-oriented — a half-line
+  # written to the terminal would leave the cursor mid-row and the dock repaints
+  # from column 1 — but a pty hands over arbitrary chunks, so this buffers.
+  #
+  # Two pty-specific quirks it exists to absorb:
+  #
+  #   * ONLCR. The slave's line discipline turns every LF into CRLF, so lines
+  #     arrive as "text\r\n". The trailing CR is an artifact, not content.
+  #   * In-place rewrites. cargo (and anything with a progress bar) redraws a
+  #     row by writing CR and the new text without a newline. What the terminal
+  #     would have shown is whatever followed the LAST CR, so that is what gets
+  #     emitted — one settled line instead of thirty flickering ones.
+  #
+  # Pure: feed it strings, get lines back. No IO, no threads, no clock beyond
+  # the idle deadline the caller passes in.
+  class LinePump
+    # How long a partial line may sit unterminated before it is emitted anyway.
+    # Without this a progress bar that never writes a newline — or a prompt like
+    # "Overwrite? [Yn]" — would be invisible for as long as it mattered.
+    IDLE_FLUSH = 0.2
+
+    def initialize(idle_flush: IDLE_FLUSH, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      # Bytes in, text out. A pty hands over BINARY, and a chunk boundary can
+      # land in the middle of a multi-byte character, so buffering and splitting
+      # happen on bytes — UTF-8 is self-synchronizing, so a newline is never
+      # inside a character — and each settled line is transcoded on the way out.
+      @buffer = String.new(encoding: Encoding::BINARY)
+      @idle_flush = idle_flush
+      @clock = clock
+      @touched = nil
+    end
+
+    # Feed a chunk; returns the complete lines it produced (without newlines).
+    def <<(chunk)
+      @buffer << chunk.b
+      @touched = @clock.call
+      lines = []
+      while (index = @buffer.index("\n"))
+        raw = @buffer.slice!(0, index + 1)
+        line = settle(raw.chomp("\n"))
+        lines << line if line
+      end
+      lines
+    end
+
+    # Emit a still-unterminated partial line once it has gone quiet. Call this
+    # from the relay loop whenever a read times out.
+    def flush_idle
+      return [] if @buffer.empty?
+      return [] if @touched && (@clock.call - @touched) < @idle_flush
+
+      lines = drain
+      @touched = @clock.call
+      lines
+    end
+
+    # Emit whatever is left, terminated or not. For end-of-stream.
+    def drain
+      return [] if @buffer.empty?
+
+      line = settle(@buffer)
+      @buffer = +""
+      line ? [line] : []
+    end
+
+    def pending? = !@buffer.empty?
+
+    private
+
+    # chomp the ONLCR artifact first, THEN collapse an in-place rewrite —
+    # order matters. Doing it the other way round reads "bar\r" as a rewrite to
+    # the empty string and swallows the line.
+    #
+    # scrub, not just force_encoding: a build tool can emit a stray byte that is
+    # not valid UTF-8, and a String that claims an encoding it doesn't satisfy
+    # raises the moment anything tries to concatenate a tag onto it.
+    def settle(raw)
+      line = raw.chomp("\r")
+      line = line[(line.rindex("\r") + 1)..] if line.include?("\r")
+      line.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+  end
+end

data/lib/everywhere/log_filter.rb

@@ -31,6 +31,7 @@ module Everywhere
       when :tebako     then tebako(line)
       when :xcodebuild then xcodebuild(line)
       when :gradle     then gradle(line)
+      when :cargo      then cargo(line)
       end
     end
 
@@ -227,6 +228,42 @@ module Everywhere
     end
     # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
 
+    # --- `every dev`'s desktop shell (cargo) ----------------------------------
+
+    # A cold `cargo run` compiles ~300 crates, one "Compiling foo v0.1.0" line
+    # each, plus a progress bar it redraws several times a second. None of that
+    # is actionable while you're waiting on your own app — but warnings, errors
+    # and the moment the shell actually starts very much are.
+    #
+    # Unlike xcodebuild and Gradle (which we run with --console=plain), cargo is
+    # talking to a pty here and colors everything, so its status lines start
+    # with SGR codes and carry OSC-8 hyperlinks. Match on the stripped text;
+    # print the original, since that color is cargo's and worth keeping.
+    #
+    # The fall-through returns the line verbatim rather than nil, so it is NOT
+    # dimmed as background detail: once the shell is up, everything arriving on
+    # this stream is the app's own output, and the body of a Rust compile error
+    # is exactly what you need to read in full.
+    def cargo(line)
+      plain = UI.strip_ansi(line)
+      case plain
+      when /\A\s*error(\[E\d+\])?[:\[]/
+        "    #{UI.red(UI.short_path(plain))}"
+      when /\A\s*warning: /
+        "    #{UI.yellow(UI.short_path(plain))}"
+      when /\A\s*Compiling /
+        once(:compiling) { UI.note_line("compiling the desktop shell (first run is slow)") }
+      when /\A\s*(Downloaded|Downloading|Updating|Building \[|Blocking|Locking)/
+        :drop
+      when /\A\s*Finished\b/
+        UI.note_line("desktop shell compiled", marker: "✓", color: :green)
+      when /\A\s*Running\b/
+        UI.note_line("desktop shell running", marker: "✓", color: :green)
+      else
+        line
+      end
+    end
+
     # 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

@@ -10,25 +10,52 @@ module Everywhere
   # does on the client:
   #
   #   <%= link_to "Install the app", … unless native_app? %>
-  #   <div class="<%= "native-inset" if native_app? %>">
+  #   <div class="<%= "native-inset" if mobile_app? %>">
   #   <% if native_version && native_version >= Gem::Version.new("1.2") %>
   #
   # Detection is by User-Agent: the RubyEverywhere shells prepend
   # "RubyEverywhere/<version> (<os>)" to Hotwire Native's own
   # "Hotwire Native iOS/Android" marker. Included into all Rails views by
   # Everywhere::Engine.
+  #
+  # Pick the narrowest one that's true of what you're branching on. `native_app?`
+  # means "not a browser tab" and covers the desktop shell; `mobile_app?` means
+  # a phone, with a tab bar and safe-area insets; `desktop_app?` means a window,
+  # with a title bar and a menu bar. Safe-area padding is mobile_app?; hiding a
+  # web nav in favour of native chrome is usually mobile_app? too — the desktop
+  # shell has no native navigation to replace it with.
   module NativeHelper
-    # True inside any RubyEverywhere native shell (iOS or Android).
+    # True inside any RubyEverywhere native shell — iOS, Android or desktop.
+    # Mirrors the bridge's `Everywhere.native`.
     def native_app?
       !native_platform.nil?
     end
 
-    # :ios, :android, or nil in a plain browser. Reads Hotwire Native's UA
+    # :ios, :android, :desktop, or nil in a plain browser. Reads the shell's UA
     # marker, so it's correct even before the JS bridge has booted.
     def native_platform
       Everywhere.native_platform_of(_everywhere_user_agent)
     end
 
+    # True in the Tauri desktop shell. Use it for window chrome — reserving room
+    # for an overlay title bar, say — and for anything that assumes a pointer
+    # and a resizable window.
+    def desktop_app?
+      native_platform == :desktop
+    end
+
+    # True in the iOS or Android shell, and the one to reach for when the
+    # affordance is a phone's: safe-area insets, the native tab bar, biometrics,
+    # the OAuth handoff. Mirrors the bridge's `Everywhere.platform === "mobile"`.
+    def mobile_app?
+      !mobile_platform.nil?
+    end
+
+    # :ios, :android, or nil (including in the desktop shell).
+    def mobile_platform
+      Everywhere.mobile_platform_of(_everywhere_user_agent)
+    end
+
     # The shell's version as a Gem::Version (from the "RubyEverywhere/<ver>"
     # UA prefix), or nil outside the shell / when unparseable. Use it to gate
     # features that need a newer shell than some users have installed.
@@ -49,8 +76,11 @@ module Everywhere
     #   redirect_to everywhere_auth_redirect(after_authentication_url)
     #
     # `to` may be a full URL or a path; only the same-origin path is forwarded.
+    # mobile_app?, not native_app?: the reset page exists to rebuild a phone
+    # shell's web views and re-fetch its tab bar. The desktop shell has neither,
+    # so a plain redirect is both correct and what it already did.
     def everywhere_auth_redirect(to)
-      return to unless native_app? && respond_to?(:everywhere_reset_path)
+      return to unless mobile_app? && respond_to?(:everywhere_reset_path)
 
       path = to.to_s.sub(%r{\Ahttps?://[^/]+}, "")
       path = "/" if path.empty? || !path.start_with?("/")
@@ -104,7 +134,10 @@ module Everywhere
                                   wrapper_class: nil, locked_class: nil,
                                   message_class: nil, unlock_class: nil, &block)
       content = respond_to?(:capture) ? capture(&block) : block.call
-      return content unless native_app?
+      # mobile_app?: there's no Face ID on the desktop shell, so emitting the
+      # locked wrapper there would hide the content behind an unlock nothing can
+      # satisfy. Browsers and the desktop shell render it plainly.
+      return content unless mobile_app?
 
       attrs = [%(data-everywhere-biometric-lock="#{_everywhere_attr(name)}")]
       attrs << %(data-everywhere-biometric-reason="#{_everywhere_attr(reason)}") if reason

data/lib/everywhere/paths.rb

@@ -12,24 +12,28 @@ module Everywhere
       File.expand_path("../..", __dir__)
     end
 
-    # The generic Tauri shell bundled inside the gem: support/shell/ holds the
-    # src-tauri app and the splash/ dir it serves. This is the CANONICAL copy of
-    # the shell — external consumers (e.g. the build-runner repo) resolve it via
+    # The generic Tauri shell bundled inside the gem: support/desktop/ holds the
+    # src-tauri app and the splash/ dir it serves, alongside support/mobile/ios
+    # and support/mobile/android. This is the CANONICAL copy of the shell —
+    # external consumers (e.g. the build-runner repo) resolve it via
     # `every shell-dir`. The CLI uses it unless the caller passes --shell-dir.
-    def bundled_shell_dir
-      File.join(gem_root, "support", "shell", "src-tauri")
+    #
+    # The directory is named for the platform; the reader keeps the "shell"
+    # wording because that's what the flag, the command and every caller call it.
+    def bundled_desktop_dir
+      File.join(gem_root, "support", "desktop", "src-tauri")
     end
 
     # Absolute path to the shell's src-tauri directory, or nil if the bundled
     # copy is missing (a corrupt/partial install).
     def shell_dir
-      bundled_shell_dir if File.exist?(File.join(bundled_shell_dir, "tauri.conf.json"))
+      bundled_desktop_dir if File.exist?(File.join(bundled_desktop_dir, "tauri.conf.json"))
     end
 
     # Like #shell_dir but aborts with a helpful message when the shell is
     # missing. The --shell-dir hint covers dev on a modified shell checkout.
     def shell_dir!
-      shell_dir or UI.die!("couldn't find the bundled shell at #{bundled_shell_dir}; " \
+      shell_dir or UI.die!("couldn't find the bundled shell at #{bundled_desktop_dir}; " \
                            "reinstall ruby_everywhere or pass --shell-dir")
     end
 
@@ -126,10 +130,57 @@ module Everywhere
       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
-    # everyone, so one shared target dir is safe to reuse.
+    # The stamped copy of the Tauri shell for one app, keyed by bundle id.
+    # Only apps that declare `native.desktop` get one — everyone else compiles
+    # the gem's own copy, which is identical for them and stays warm across
+    # projects (see cargo_target_dir). Persistent for the same reason the mobile
+    # work dirs are: cargo's incremental state lives inside it, and a cold Tauri
+    # build is minutes where a warm one is seconds.
+    def desktop_work_dir(bundle_id)
+      File.join(cache_dir, "desktop", bundle_id)
+    end
+
+    # CARGO_TARGET_DIR for a stamped shell. Per-app rather than shared, because
+    # the whole point of stamping is that this app's crate graph differs from
+    # every other app's — pointing them at one target dir would make cargo
+    # rebuild the world on every alternating build.
+    def desktop_target_dir(bundle_id)
+      File.join(cache_dir, "desktop-target", bundle_id)
+    end
+
+    # Where `every dev` keeps the throwaway .app wrapper it runs the shell
+    # inside. macOS reads the application name from CFBundleName, so a bare
+    # `cargo run` binary shows up as the crate name — "example-shell" — in the
+    # menu bar, the About/Hide/Quit items and the Dock. The wrapper exists only
+    # to carry an Info.plist; the binary inside it is a hard link to cargo's.
+    def desktop_dev_app_dir(bundle_id)
+      File.join(cache_dir, "desktop-app", bundle_id)
+    end
+
+    # Where `every dev` stages the app's Dock icon for the running shell. The
+    # shaped master is derived from app.icon, so it's a build product, not the
+    # app's own file — it belongs in the cache next to the rest of them.
+    def desktop_icon_dir(bundle_id)
+      File.join(cache_dir, "desktop-icon", bundle_id)
+    end
+
+    # Where `every dev` stages native/desktop/assets for the running shell.
+    # A staged copy rather than the source tree on purpose: the packaged app
+    # reads ONE flat Resources/assets folder, and pointing dev at the nested
+    # source would quietly resolve assets/branding/logo.png in a build and not
+    # in dev. Staging runs the same DesktopAssets compiler both ways, so the two
+    # can't drift. Keyed by bundle id like the mobile work dirs.
+    def desktop_assets_dir(bundle_id)
+      File.join(cache_dir, "desktop-assets", bundle_id)
+    end
+
+    # Where cargo writes the shell's build output (CARGO_TARGET_DIR) for apps on
+    # the fast path — the ones that declare no `native.desktop`. Redirected here
+    # so cargo never dumps a multi-GB target/ into the installed gem, and so the
+    # shell compiles warm across projects: with no app Rust in it the shell
+    # source really is identical for everyone, so one shared target dir is safe
+    # to reuse. An app that declares extensions gets desktop_target_dir instead,
+    # because that premise stops holding the moment its crate graph differs.
     def cargo_target_dir
       File.join(cache_dir, "shell-target")
     end

data/lib/everywhere/relay.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "console"
+require_relative "line_pump"
+require_relative "ui"
+
+module Everywhere
+  # Reads one child's output off a pty and republishes it, one whole line at a
+  # time, tagged with its source.
+  #
+  # `every dev` used to hand the dev server and desktop shell its own stdout and
+  # let them write straight to the terminal. That made two things impossible:
+  # telling which of four concurrent things printed a line, and keeping anything
+  # pinned to the bottom of the screen. Relaying costs a thread per child and
+  # buys both.
+  #
+  # The full raw stream is also tee'd to a log file, matching what the builders
+  # already do with dist/ios-build.log — so nothing a filter hides is lost.
+  class Relay
+    CHUNK = 4096
+    POLL = 0.1
+
+    # on_line: an optional callback given every settled line before filtering.
+    # `every dev` uses it to notice the moment cargo actually starts the desktop
+    # shell — there is no other signal that the build turned into a running app.
+    def initialize(io, source:, log: nil, filter: nil, on_line: nil)
+      @io = io
+      @source = source
+      @filter = filter
+      @on_line = on_line
+      @log = log && File.open(log, "w")
+    end
+
+    # Blocking; run it in a thread. Returns when the child closes the pty.
+    def run
+      Console.tag = @source
+      pump = LinePump.new
+      loop do
+        if @io.wait_readable(POLL)
+          chunk = @io.read_nonblock(CHUNK, exception: false)
+          break if chunk.nil? # EOF
+
+          publish(pump << chunk) unless chunk == :wait_readable
+        else
+          publish(pump.flush_idle)
+        end
+      end
+      publish(pump.drain)
+    rescue Errno::EIO, IOError, Errno::EBADF
+      # A pty master raises EIO (not EOF) once the last slave closes, which is
+      # simply how a child exiting looks from this side.
+      publish(pump.drain) if pump
+    ensure
+      @log&.close
+      begin
+        @io.close
+      rescue StandardError
+        nil
+      end
+    end
+
+    private
+
+    def publish(lines)
+      lines.each do |line|
+        @log&.puts(line)
+        @on_line&.call(line)
+        shown = @filter ? @filter.call(line) : line
+        case shown
+        when :drop, false then nil
+        when nil          then Console.puts("    #{UI.gray(UI.short_path(line))}")
+        else                   Console.puts(shown)
+        end
+      end
+    end
+  end
+end