ruby_everywhere 0.4.0 → 0.6.0

data/lib/everywhere/commands/install.rb

@@ -3,6 +3,8 @@
 require "dry/cli"
 require "fileutils"
 require_relative "../shellout"
+require_relative "../config"
+require_relative "../agents_guide"
 
 module Everywhere
   module Commands
@@ -13,8 +15,9 @@ module Everywhere
 
       option :root, default: ".", desc: "App root directory"
       option :local, type: :boolean, default: false, desc: "Configure local mode (compile & ship the app) instead of remote mode"
+      option :agents, type: :boolean, default: false, desc: "Write an AGENTS.md guide so AI coding agents understand this app"
 
-      def call(root: ".", local: false, **)
+      def call(root: ".", local: false, agents: false, **)
         @mode = local ? "local" : "remote"
         @framework = Framework.detect(root)
         @root = @framework.root
@@ -29,6 +32,13 @@ module Everywhere
         # Framework-specific config surgery.
         send("install_#{@framework.name}")
 
+        if agents
+          write_agents_guide
+          write_claude_pointer
+        else
+          UI.step(UI.dim("tip: `every install --agents` writes an AGENTS.md guide for AI coding agents"))
+        end
+
         UI.success("installed — run `every dev` to open the app, `every build` to package it")
       end
 
@@ -158,6 +168,17 @@ module Everywhere
           #   - label: Quit
           #     action: quit
 
+          # Desktop window chrome. title_bar: overlay floats the macOS traffic
+          # lights over your page with no title text (reserve the space with the
+          # .everywhere-titlebar-inset class from everywhere/native.css);
+          # frameless removes the system chrome entirely, and the page draws its
+          # own title bar and calls Everywhere.window.* for the controls.
+          # window:
+          #   title_bar: overlay     # decorated (default) | overlay | frameless
+          #   title: false           # draw the title text
+          #   size: [1100, 750]
+          #   min_size: [600, 400]
+
           # Mobile tab bar (iOS today, Android soon). Served live from
           # /everywhere/ios_v1.json too, so tab changes deploy with the app —
           # no app-store release. Icons: ios = SF Symbol name.
@@ -177,6 +198,15 @@ module Everywhere
           #   ios:
           #     lazy_load_tabs: true   # defer each tab's first load until it's tapped
           #                            # (false = load every tab up front; omit = default)
+          #
+          #   Rust you keep in native/desktop/ and compile into the desktop
+          #   shell. Declaring anything here switches the desktop build to a
+          #   per-app cargo compile — the first one takes minutes.
+          #   desktop:
+          #     commands: [scan_ports]   # reachable as Everywhere.desktop.invoke("scan_ports")
+          #     setup: true              # run native/desktop/setup.rs at boot
+          #     crates:
+          #       serialport: "4.3"
 
           # Durable build knobs (CLI flags still override per-run).
           # build:
@@ -227,6 +257,68 @@ module Everywhere
         change("create native_boot.rb", true)
       end
 
+      # --- AGENTS.md (--agents) --------------------------------------------------
+
+      FRESH_HEADER = "# AGENTS.md\n\nGuidance for AI coding agents working in this repository.\n\n"
+
+      # AGENTS.md is the app's file, not ours — most apps that have one already
+      # have notes in it. So we own only what's between the markers, and a re-run
+      # refreshes that region in place.
+      def write_agents_guide
+        path = app_file("AGENTS.md")
+        block = AgentsGuide.block(framework: @framework.name, mode: guide_mode)
+
+        unless File.exist?(path)
+          File.write(path, FRESH_HEADER + block)
+          return change("create AGENTS.md", true)
+        end
+
+        existing = File.read(path)
+        updated = merge_agents_block(existing, block) or return # markers are broken; warned
+        File.write(path, updated) unless updated == existing
+        change("refresh the RubyEverywhere section of AGENTS.md", updated != existing)
+      end
+
+      # Returns the merged file, or nil when the markers are malformed — a lone
+      # BEGIN would make the next run's region match swallow everything the app's
+      # authors wrote after it, so we refuse rather than guess at a repair.
+      def merge_agents_block(existing, block)
+        begins = existing.scan(AgentsGuide::BEGIN_MARKER).size
+        ends = existing.scan(AgentsGuide::END_MARKER).size
+
+        if begins.zero? && ends.zero?
+          return existing.strip.empty? ? block : "#{existing.chomp}\n\n#{block}"
+        end
+
+        if begins != 1 || ends != 1 ||
+           existing.index(AgentsGuide::BEGIN_MARKER) > existing.index(AgentsGuide::END_MARKER)
+          UI.warn("AGENTS.md has unbalanced #{AgentsGuide::BEGIN_MARKER} / #{AgentsGuide::END_MARKER} " \
+                  "markers — leaving it alone; fix them by hand and re-run")
+          return nil
+        end
+
+        region = /^#{Regexp.escape(AgentsGuide::BEGIN_MARKER)}\n.*?^#{Regexp.escape(AgentsGuide::END_MARKER)}\n?/m
+        existing.sub(region) { block }
+      end
+
+      # Claude Code reads AGENTS.md on its own; the pointer is for the setups that
+      # only look at CLAUDE.md. An app that already has one has its own reasons for
+      # what's in it — leave it alone and let AGENTS.md be found the normal way.
+      def write_claude_pointer
+        claude = app_file("CLAUDE.md")
+        return change("create CLAUDE.md pointer", false) if File.exist?(claude)
+
+        File.write(claude, "See @AGENTS.md for how this app works and how RubyEverywhere packages it.\n")
+        change("create CLAUDE.md pointer", true)
+      end
+
+      # --local only describes what THIS run configured. Once config/everywhere.yml
+      # exists it is the truth, so a re-run without the flag can't mislabel a
+      # local-mode app as remote.
+      def guide_mode
+        File.exist?(app_file(Config::FILE)) ? Config.load(@root).mode : @mode
+      end
+
       def guard_bootsnap
         boot = app_file("config", "boot.rb")
         contents = File.read(boot)

data/lib/everywhere/commands/release.rb

@@ -12,7 +12,7 @@ module Everywhere
     # Produce a signed, notarized, stapled, distributable artifact + release.json.
     #
     # `every release` wraps the existing signing engine
-    # (cli/support/macos/notarize.sh) rather than reimplementing
+    # (cli/support/release/macos/notarize.sh) rather than reimplementing
     # codesign/notarytool, and emits the machine-readable receipt every build
     # surface (local, CI, Platform) must produce. See
     # platform/docs/build-engine.md §4, §7, §9.
@@ -20,7 +20,7 @@ module Everywhere
     # Today only the macos builder is live; the target is parameterized so
     # ios/android/windows/linux slot in as builders later.
     class Release < Dry::CLI::Command
-      NOTARIZE = File.expand_path("../../../support/macos/notarize.sh", __dir__)
+      NOTARIZE = File.expand_path("../../../support/release/macos/notarize.sh", __dir__)
 
       desc "Sign, notarize, staple, and emit release.json for a distributable build"
 

data/lib/everywhere/config.rb

@@ -92,18 +92,45 @@ module Everywhere
       HTML
     end
 
-    # :ios, :android or nil, from a User-Agent string. The shells prepend
-    # "RubyEverywhere/<version> (<os>)" to Hotwire Native's own marker; this
-    # reads the marker, which is present from the very first request. Shared by
-    # the view helpers and the auth middleware.
+    # The desktop shell's marker. WKWebView APPENDS
+    # `applicationNameForUserAgent` to the real system UA, so this arrives
+    # alongside a normal Safari UA rather than replacing it — hence a pattern
+    # rather than a prefix check. The version is absent when everywhere.yml
+    # declares none.
+    #
+    # macOS only for now: the marker is set in macos_webview_configuration, and
+    # Windows/Linux have no append-only equivalent (their user_agent() REPLACES
+    # the string, and fabricating a whole UA is worse than not marking it).
+    # Desktop only ships macOS today; revisit when it doesn't.
+    DESKTOP_UA = %r{\bRubyEverywhere(?:/[\w.\-]+)? \((?:macos|windows|linux)\)}
+
+    MOBILE_PLATFORMS = %i[ios android].freeze
+
+    # :ios, :android, :desktop or nil, from a User-Agent string. Present from
+    # the very first request, before any JS has run. Shared by the view helpers
+    # and the auth middleware.
+    #
+    # Mobile is checked FIRST and the order matters: the mobile shells prepend
+    # the same "RubyEverywhere/<version> (<os>)" marker to Hotwire Native's own,
+    # so a mobile UA matches DESKTOP_UA too.
     def native_platform_of(user_agent)
       ua = user_agent.to_s
       return :ios if ua.include?("Hotwire Native iOS")
       return :android if ua.include?("Hotwire Native Android")
+      return :desktop if ua.match?(DESKTOP_UA)
 
       nil
     end
 
+    # Just the phone shells. Anything that leans on a mobile-only affordance —
+    # the OAuth handoff to ASWebAuthenticationSession / Custom Tabs, biometric
+    # gating — has to ask for this rather than "is this a native shell", because
+    # the desktop shell answers yes to that and has neither.
+    def mobile_platform_of(user_agent)
+      platform = native_platform_of(user_agent)
+      platform if MOBILE_PLATFORMS.include?(platform)
+    end
+
     # Test/reset hook.
     attr_writer :tabs_filter
   end
@@ -796,6 +823,115 @@ module Everywhere
        "one of: #{ANDROID_ICON_FONTS.keys.join(", ")}"]
     end
 
+    # The desktop half of "supernative": Rust the app repo carries in
+    # native/desktop/ that `every build` compiles into the Tauri shell.
+    #
+    # The shape differs from ios/android because desktop differs: the whole UI
+    # is a webview, so there are no native screens or splash views to register.
+    # What an app actually wants down here is the machine — a serial port, a USB
+    # device, an FFI library, a Tauri plugin — reached from the page.
+    #
+    #   native:
+    #     desktop:
+    #       commands: [scan_ports]        # fns reachable from the page
+    #       setup: true                   # run native/desktop/setup.rs at boot
+    #       crates:
+    #         serialport: "4.3"
+    #         reqwest: { version: "0.12", features: [json] }
+    #
+    # A command is a plain function, NOT a #[tauri::command] — Tauri's typed
+    # commands only arrive through invoke, and invoke is unavailable to our
+    # pages (they're served over http; see extension_host.rs in the shell). The
+    # signature is uniform:
+    #
+    #   pub fn scan_ports(app: &tauri::AppHandle, payload: serde_json::Value)
+    #       -> Result<serde_json::Value, String>
+    #
+    # Declaring anything here has a real cost the mobile sections don't have:
+    # the shell stops being one prebuilt crate shared by every app and gets
+    # stamped and compiled per app (see Builders::Desktop). Apps that declare
+    # nothing keep the fast path.
+    def native_desktop
+      section = @data.dig("native", "desktop")
+      section.is_a?(Hash) ? section : {}
+    end
+
+    def native_desktop_commands = Array(native_desktop["commands"]).map { |name| name.to_s.strip }
+
+    def native_desktop_setup? = native_desktop["setup"] == true
+
+    # Cargo dependencies, normalized to { "name" => {...table} } so the
+    # generator has one shape to write. The short form (a bare version string)
+    # becomes { "version" => "4.3" }.
+    def native_desktop_crates
+      entries = native_desktop["crates"]
+      return {} unless entries.is_a?(Hash)
+
+      entries.to_h do |name, spec|
+        table = spec.is_a?(Hash) ? spec : { "version" => spec.to_s }
+        [name.to_s.strip, table]
+      end
+    end
+
+    def native_desktop? = !(native_desktop_commands.empty? && native_desktop_crates.empty?) ||
+                          native_desktop_setup?
+
+    # Everything here is interpolated into generated Rust and TOML, so names are
+    # validated hard — same reasoning as MAVEN_COORDINATE above. A command name
+    # becomes a path segment in a generate_handler! list; a crate name and its
+    # features become bare TOML keys and quoted strings.
+    RUST_FN_NAME = /\A[a-z_][a-z0-9_]*\z/
+    CRATE_NAME = /\A[a-zA-Z0-9_][a-zA-Z0-9_-]*\z/
+    # Cargo's requirement syntax, loosely: ^1.2, ~1.2, >=1.0, 1.*, 1.2.3-beta.1.
+    # Deliberately no spaces and no commas — a multi-requirement string would
+    # need quoting rules we don't want to own, and cargo reports anything
+    # subtler at build time.
+    CRATE_VERSION = /\A[\^~<>=]{0,2}\d+(\.\d+){0,2}(\.\*)?(-[0-9A-Za-z.-]+)?\z/
+    CRATE_FEATURE = /\A[A-Za-z0-9_][A-Za-z0-9_+-]*\z/
+    # Where a git dependency may point. Same rule the SPM packages use.
+    CRATE_GIT_URL = PACKAGE_URL
+
+    def native_desktop_errors
+      raw = @data.dig("native", "desktop")
+      return [] if raw.nil?
+      return ["native.desktop must be a mapping"] unless raw.is_a?(Hash)
+
+      errors = []
+      commands = raw["commands"]
+      if !commands.nil? && !commands.is_a?(Array)
+        errors << "native.desktop.commands must be a list of function names"
+      else
+        errors += native_desktop_commands.reject { |name| name.match?(RUST_FN_NAME) }.map do |name|
+          "native.desktop.commands: #{name.inspect} is not a Rust function name — " \
+            "snake_case (letters, digits, _), matching the fn in native/desktop/"
+        end
+        duplicates = native_desktop_commands.tally.select { |_name, count| count > 1 }.keys
+        errors += duplicates.map do |name|
+          "native.desktop.commands: #{name.inspect} is listed twice"
+        end
+      end
+
+      setup = raw["setup"]
+      errors << "native.desktop.setup must be true or false" unless setup.nil? || boolean_or_nil(setup) == setup
+
+      errors + native_desktop_crate_errors
+    end
+
+    def native_desktop_crate_errors
+      raw = native_desktop["crates"]
+      return [] if raw.nil?
+      return ["native.desktop.crates must be a mapping of crate name to version"] unless raw.is_a?(Hash)
+
+      raw.flat_map do |name, spec|
+        at = "native.desktop.crates.#{name}"
+        errors = []
+        unless name.to_s.strip.match?(CRATE_NAME)
+          errors << "#{at}: #{name.to_s.inspect} is not a crate name (letters, digits, _, -)"
+        end
+        errors + crate_spec_errors(at, spec)
+      end
+    end
+
     # Third-party sign-in (Sign in with Apple / Google / GitHub / anything
     # OmniAuth speaks). Providers refuse to run — or run badly — inside an app's
     # web view, so the mobile shell hands these paths to an
@@ -931,6 +1067,99 @@ module Everywhere
       end
     end
 
+    # Desktop window chrome. Desktop-only: on mobile the OS owns the frame, so
+    # mobile builds ignore this section entirely.
+    #
+    #   window:
+    #     title_bar: overlay   # decorated (default) | overlay | frameless
+    #     title: false         # draw the title text (default true)
+    #     size: [1100, 750]    # initial inner size
+    #     min_size: [600, 400]
+    #     resizable: true
+    #     drag_height: 28      # top strip that drags the window; 0 turns it off
+    #
+    # Every reader returns nil when the key is absent so `to_shell_hash` drops it
+    # and the shell keeps its own default — there is exactly one place each
+    # default lives, and it's the Rust side.
+    #
+    # `overlay` is the macOS "traffic lights floating over your content" look
+    # (TitleBarStyle::Overlay + hidden title). Windows and Linux have no such
+    # style, so the shell falls back to frameless there and the page draws its
+    # own controls via Everywhere.window.
+    WINDOW_TITLE_BARS = %w[decorated overlay frameless].freeze
+
+    def window
+      section = @data["window"]
+      section.is_a?(Hash) ? section : {}
+    end
+
+    def window_title_bar
+      value = window["title_bar"].to_s
+      value if WINDOW_TITLE_BARS.include?(value)
+    end
+
+    # Tri-state, like native_ios_lazy_load_tabs: an absent key leaves the shell
+    # on its default rather than forcing one.
+    def window_title = boolean_or_nil(window["title"])
+    def window_resizable = boolean_or_nil(window["resizable"])
+
+    def window_size = window_dimensions("size")
+    def window_min_size = window_dimensions("min_size")
+
+    # How much of the top of the page drags the window, in CSS pixels. Only
+    # meaningful for overlay/frameless, where there's no system title bar left
+    # to grab. nil leaves the shell's 28px default (the height of the macOS
+    # traffic-light band); 0 turns dragging off for an app that wants to place
+    # its own drag regions.
+    def window_drag_height
+      value = window["drag_height"]
+      value.to_f if value.is_a?(Numeric) && !value.negative?
+    end
+
+    # The window subset the shell needs. nil (absent from everywhere.json) when
+    # the app declares nothing, so the shell's own defaults stand untouched.
+    def window_shell_hash
+      hash = {
+        "title_bar" => window_title_bar,
+        "title" => window_title,
+        "resizable" => window_resizable,
+        "size" => window_size,
+        "min_size" => window_min_size,
+        "drag_height" => window_drag_height
+      }.compact
+      hash unless hash.empty?
+    end
+
+    def window_errors
+      raw = @data["window"]
+      return [] if raw.nil?
+      return ["window: must be a mapping"] unless raw.is_a?(Hash)
+
+      errors = []
+      bar = raw["title_bar"]
+      if bar && !WINDOW_TITLE_BARS.include?(bar.to_s)
+        errors << "window.title_bar #{bar.to_s.inspect} must be one of " \
+                  "#{WINDOW_TITLE_BARS.join(" / ")}"
+      end
+
+      errors += %w[size min_size].filter_map do |key|
+        next if raw[key].nil? || window_dimensions(key)
+
+        "window.#{key} must be two positive numbers, like [1100, 750]"
+      end
+
+      drag = raw["drag_height"]
+      unless drag.nil? || (drag.is_a?(Numeric) && !drag.negative?)
+        errors << "window.drag_height must be a number of pixels (0 turns dragging off)"
+      end
+
+      errors + %w[title resizable].filter_map do |key|
+        next if raw[key].nil? || boolean_or_nil(raw[key]) == raw[key]
+
+        "window.#{key} must be true or false"
+      end
+    end
+
     # Deep linking / universal links. Declares the app's association with its
     # web domains so the OS can hand matching URLs to the app instead of the
     # browser. The gem serves the two well-known association files this needs —
@@ -1064,6 +1293,7 @@ module Everywhere
         "background_color" => background_color,
         "menu" => (menu unless menu.empty?),
         "tray" => (tray unless tray.empty?),
+        "window" => window_shell_hash,
         "lazy_load_tabs" => native_lazy_load_tabs(target: target),
         "splash_min_seconds" => native_splash_min_seconds(target: target),
         "updates" => updates_shell_hash,
@@ -1085,6 +1315,70 @@ module Everywhere
     def app = @data.fetch("app", nil) || {}
     def appearance = @data.fetch("appearance", nil) || {}
 
+    # One crate's dependency spec: either a bare version string or a table.
+    def crate_spec_errors(at, spec)
+      return version_errors(at, spec) unless spec.is_a?(Hash)
+
+      errors = []
+      # A crate needs somewhere to come from. version: is the common case; git:
+      # and path: are the two escape hatches cargo itself offers.
+      unless %w[version git path].any? { |key| !spec[key].to_s.strip.empty? }
+        errors << "#{at} needs a version: (or git: / path:)"
+      end
+      errors += version_errors("#{at}.version", spec["version"]) if spec.key?("version")
+
+      git = spec["git"].to_s.strip
+      unless git.empty? || git.match?(CRATE_GIT_URL)
+        errors << "#{at}.git #{git.inspect} must be an https:// or git@ URL"
+      end
+
+      # branch/tag/rev/path have no useful shape to check, but they DO end up
+      # inside quoted TOML strings — so the one thing that matters is that they
+      # can't close the quote or start a new line.
+      errors += %w[branch tag rev path].filter_map do |key|
+        value = spec[key].to_s
+        next if value.empty? || !value.match?(/["\\\n\r]/)
+
+        "#{at}.#{key} can't contain quotes, backslashes or newlines"
+      end
+
+      features = spec["features"]
+      if !features.nil? && !features.is_a?(Array)
+        errors << "#{at}.features must be a list"
+      else
+        errors += Array(features).reject { |f| f.to_s.match?(CRATE_FEATURE) }.map do |feature|
+          "#{at}.features: #{feature.to_s.inspect} is not a feature name (letters, digits, _, +, -)"
+        end
+      end
+      errors
+    end
+
+    def version_errors(at, value)
+      version = value.to_s.strip
+      return [] if version.empty?
+      return [] if version.match?(CRATE_VERSION)
+
+      ["#{at} #{version.inspect} is not a cargo version requirement — like \"1.2\", \"^1.2.3\" or \"~0.4\""]
+    end
+
+    # YAML's `yes`/`on` already parse as true, so anything that reaches here
+    # still not a boolean is a genuine mistake rather than a spelling of one.
+    # Deliberately not an endless def: `def f(v) = v if cond` parses as
+    # `(def f(v) = v) if cond`, which would define nothing when cond is false.
+    def boolean_or_nil(value)
+      value if value == true || value == false
+    end
+
+    # A [width, height] pair. Rejects the near-misses (one number, three, a
+    # negative) rather than silently building a 0-pixel window.
+    def window_dimensions(key)
+      value = window[key]
+      return unless value.is_a?(Array) && value.length == 2
+      return unless value.all? { |n| n.is_a?(Numeric) && n.positive? }
+
+      value.map(&:to_f)
+    end
+
     def android_target?(target) = self.class.os_of(target) == "android"
 
     # Per-platform overrides, keyed by os (macos / ios / android / windows /

data/lib/everywhere/console.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Everywhere
+  # The one place anything writes to the terminal.
+  #
+  # `every dev` runs the iOS and Android builds concurrently, each streaming
+  # xcodebuild/Gradle output, while the dev server and desktop shell relay their
+  # own output and the main thread prints its own chrome. Without a lock those
+  # writes tear into each other mid-line. Everything goes through here, and when
+  # more than one task is producing output each line is prefixed with its source
+  # so you can tell who said what.
+  #
+  # A Dock can install itself as the sink (Console.dock =); it then gets the
+  # chance to erase and repaint its pinned footer around each write. With no
+  # dock — every other command, CI, a pipe — writes go straight to $stdout and
+  # the output is byte-identical to what it always was.
+  #
+  # Three rules this file exists to enforce:
+  #
+  #   * $stdout/$stderr are resolved at WRITE time, never memoized. Minitest's
+  #     capture_io swaps the globals, and a good chunk of the suite asserts on
+  #     what it captured.
+  #   * The lock is a Monitor, not a Mutex. Monitor is reentrant, so a UI helper
+  #     or LogFilter that ends up writing from inside a write can't deadlock.
+  #   * Nothing calls Console from a Signal.trap handler. Taking a held lock in
+  #     trap context raises ThreadError. Traps set a flag; the main loop draws.
+  module Console
+    LOCK = Monitor.new
+
+    # Short, fixed-width source tags. Colored so a glance separates the streams;
+    # padded so the "│" gutter lines up regardless of which task is talking.
+    TAGS = {
+      web: ["web", :cyan],
+      desktop: ["desktop", :magenta],
+      ios: ["ios", :blue],
+      android: ["android", :green],
+      logs: ["logs", :gray]
+    }.freeze
+
+    TAG_WIDTH = TAGS.values.map { |label, _| label.length }.max
+
+    module_function
+
+    def synchronize(&block) = LOCK.synchronize(&block)
+
+    # The installed Dock, or nil for the plain path. Never assume it is set —
+    # every command other than `every dev` runs without one.
+    def dock = LOCK.synchronize { @dock }
+
+    def dock=(value)
+      LOCK.synchronize { @dock = value }
+    end
+
+    def write(str)
+      LOCK.synchronize do
+        text = tagged(str)
+        next @dock.emit(text) if @dock
+
+        io = $stdout
+        io.write(text)
+        io.flush
+      end
+    end
+
+    def print(str) = write(str)
+    def puts(str)  = write("#{str}\n")
+
+    # Only UI.die! goes to stderr — UI.warn and friends have always been on
+    # stdout and the suite asserts them there. It bypasses the dock: an error is
+    # the one thing that must survive even if the dock is wedged.
+    def error(str)
+      LOCK.synchronize do
+        @dock&.clear
+        io = $stderr
+        io.write(tagged("#{str}\n"))
+        io.flush
+      end
+    end
+
+    # --- per-thread source tagging -------------------------------------------
+
+    # thread_variable_set (thread-scoped), not Thread#[] (fiber-local): tags are
+    # set by TaskPool in one place and read by the relay threads it owns.
+    def tag=(name)
+      Thread.current.thread_variable_set(:everywhere_console_tag, name&.to_sym)
+    end
+
+
+    def tag = Thread.current.thread_variable_get(:everywhere_console_tag)
+
+    # Tagging switches on only while two or more sources are live, so a single
+    # `every dev --ios` (and every existing test that asserts on stdout) sees
+    # byte-identical output to before.
+    def multiplexed=(bool)
+      LOCK.synchronize { @multiplexed = bool }
+    end
+
+    def multiplexed? = LOCK.synchronize { !!@multiplexed }
+
+    def tagged(str)
+      return str unless @multiplexed
+
+      prefix = prefix_for(tag) or return str
+      # Prefix every non-empty line, including inside a multi-line chunk.
+      str.gsub(/^(?=.)/) { prefix }
+    end
+
+    def prefix_for(name)
+      label, color = TAGS[name]
+      return nil unless label
+
+      "#{UI.public_send(color, label.ljust(TAG_WIDTH))} #{UI.gray("│")} "
+    end
+  end
+end