ruby_everywhere 0.3.0 → 0.5.0

data/lib/everywhere/builders/desktop.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../paths"
+require_relative "../ui"
+require_relative "../version"
+
+module Everywhere
+  module Builders
+    # Resolves where cargo should run for the desktop shell, and stamps a
+    # per-app copy of it when the app declares `native.desktop`.
+    #
+    # Two paths, deliberately:
+    #
+    #   no native.desktop   the gem's own support/desktop/src-tauri, compiled
+    #                       against the SHARED ~/.rubyeverywhere/shell-target.
+    #                       Identical source for every app, so one warm target
+    #                       dir serves all of them. This is what every app did
+    #                       before extensions existed, and it stays free.
+    #
+    #   native.desktop      a stamped copy under ~/.rubyeverywhere/desktop/<id>
+    #                       with its own target dir, exactly like the iOS and
+    #                       Android work dirs. Costs one cold Tauri compile
+    #                       (minutes) and a couple of GB, which is why it is not
+    #                       the default.
+    #
+    # The stamped list, and nothing else:
+    #
+    #   Cargo.toml                  the template's, with native.desktop.crates
+    #                               substituted into the __EVERYWHERE_APP_CRATES__
+    #                               marker
+    #   src/extensions/**           native/desktop/**/*.rs, plus a generated
+    #                               mod.rs per directory
+    #
+    # Everything else in the work dir is the frozen template, copied as-is. In
+    # particular src/main.rs, src/extension_host.rs and capabilities/ are never
+    # rewritten — see support/desktop/README.md.
+    class Desktop
+      # The generated module file, at every level of src/extensions. Reserved:
+      # an app shipping its own would be silently overwritten, so we refuse.
+      MODULE_FILE = "mod.rs"
+      STAGE_MARKER = ".everywhere-template"
+      CRATES_MARKER = "# __EVERYWHERE_APP_CRATES__"
+
+      # Where the app keeps its Rust, relative to the app root.
+      SOURCE_DIR = File.join("native", "desktop")
+
+      Prepared = Struct.new(:dir, :target_dir, :stamped, keyword_init: true) do
+        def stamped? = stamped
+      end
+
+      def initialize(config:, root:, template_dir: nil)
+        @config = config
+        @root = root
+        @template_dir = template_dir
+      end
+
+      # Returns where to run cargo and what to set CARGO_TARGET_DIR to. Callers
+      # (`every dev`, `every build`) don't need to care which path they got.
+      def prepare!
+        template = @template_dir || Paths.shell_dir!
+        unless @config.native_desktop?
+          return Prepared.new(dir: template, target_dir: Paths.cargo_target_dir, stamped: false)
+        end
+
+        preflight!
+        src_tauri = stage(template)
+        stamp!(src_tauri)
+        Prepared.new(dir: src_tauri, target_dir: Paths.desktop_target_dir(bundle_id), stamped: true)
+      end
+
+      private
+
+      def bundle_id = @config.bundle_id
+
+      # Config errors first: they're free to check, and everything below either
+      # interpolates these values into generated Rust or spends minutes on cargo.
+      def preflight!
+        errors = @config.native_desktop_errors
+        return if errors.empty?
+
+        UI.die!("native.desktop in config/everywhere.yml:\n#{errors.join("\n")}")
+      end
+
+      # Merge-copy the template over the work dir, NOT a wipe like the iOS
+      # stage: cargo's incremental state (target/ is elsewhere, but .fingerprint
+      # data and the lock file are not) plus a resolved Cargo.lock live here, and
+      # a cold Tauri build is minutes against a warm one's seconds. The one
+      # directory the stamp regenerates wholesale (src/extensions/) is cleared by
+      # its own writer, so deleted app files stop compiling.
+      #
+      # A gem upgrade wipes it: the template's own sources changed, and merging
+      # new files over old ones would leave whatever the new template deleted.
+      # `template` points at src-tauri (that's what --shell-dir means), but the
+      # whole shell root has to come along: tauri.conf.json's frontendDist is
+      # "../splash", a sibling of src-tauri, and generate_context! panics at
+      # compile time if it isn't there. So we copy the parent and hand back the
+      # src-tauri inside it.
+      def stage(template)
+        work = Paths.desktop_work_dir(bundle_id)
+        FileUtils.rm_rf(work) unless staged_version(work) == Everywhere::VERSION
+        FileUtils.mkdir_p(work)
+        FileUtils.cp_r(File.join(File.dirname(template), "."), work)
+        File.write(File.join(work, STAGE_MARKER), "#{Everywhere::VERSION}\n")
+        File.join(work, File.basename(template))
+      end
+
+      def staged_version(work)
+        marker = File.join(work, STAGE_MARKER)
+        File.read(marker).strip if File.file?(marker)
+      end
+
+      def stamp!(work)
+        write_cargo_toml(work)
+        write_extensions(work)
+      end
+
+      # Cargo has no include mechanism, so the crate list can't be its own file
+      # the way Android's native-packages.gradle.kts is — the template carries a
+      # marker comment as the last line of [dependencies] and we replace it here.
+      # In the STAMPED copy: the gem's Cargo.toml is never touched.
+      def write_cargo_toml(work)
+        path = File.join(work, "Cargo.toml")
+        source = File.read(path)
+        unless source.include?(CRATES_MARKER)
+          UI.die!("the shell's Cargo.toml has no #{CRATES_MARKER} marker — " \
+                  "reinstall ruby_everywhere or pass --shell-dir at your own risk")
+        end
+
+        crates = @config.native_desktop_crates
+        UI.step("desktop crates: #{crates.keys.join(", ")}") unless crates.empty?
+        File.write(path, source.sub(CRATES_MARKER, render_crates(crates)))
+      end
+
+      def render_crates(crates)
+        return "# (no native.desktop.crates declared)" if crates.empty?
+
+        lines = ["# from native.desktop.crates in config/everywhere.yml"]
+        lines += crates.map { |name, spec| "#{name} = #{render_spec(spec)}" }
+        lines.join("\n")
+      end
+
+      # A lone version renders as cargo's short form; anything else as an inline
+      # table. Key order is fixed so a rebuild with unchanged config produces a
+      # byte-identical Cargo.toml — cargo re-resolves on any change to this file.
+      TABLE_KEYS = %w[version git branch tag rev path features default_features optional].freeze
+
+      def render_spec(spec)
+        return toml_string(spec["version"]) if spec.keys == ["version"]
+
+        pairs = TABLE_KEYS.filter_map do |key|
+          value = spec[key]
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          # default_features is the only key whose YAML spelling differs from
+          # cargo's; everything else is verbatim.
+          "#{key.tr("_", "-")} = #{toml_value(value)}"
+        end
+        "{ #{pairs.join(", ")} }"
+      end
+
+      def toml_value(value)
+        case value
+        when true, false then value.to_s
+        when Array then "[#{value.map { |item| toml_string(item) }.join(", ")}]"
+        else toml_string(value)
+        end
+      end
+
+      # Config validation already rejects quotes, backslashes and newlines in
+      # every string that reaches here; escaping anyway is belt-and-braces, so a
+      # future key added to TABLE_KEYS can't become an injection by omission.
+      def toml_string(value)
+        %("#{value.to_s.gsub("\\", "\\\\\\\\").gsub('"', '\"')}")
+      end
+
+      # native/desktop/**/*.rs → src/extensions/, preserving relative paths, plus
+      # a generated mod.rs per directory. Rust needs a module declaration for
+      # every file, so the directory tree IS the module tree.
+      def write_extensions(work)
+        dest = File.join(work, "src", "extensions")
+        # Regenerated wholesale: a file deleted from the app repo has to stop
+        # compiling, and a stale module declaration would fail the build in a
+        # way that points at the wrong place.
+        FileUtils.rm_rf(dest)
+        FileUtils.mkdir_p(dest)
+
+        source = File.join(@root, SOURCE_DIR)
+        sources = File.directory?(source) ? Dir.glob(File.join(source, "**", "*.rs")).sort : []
+        sources.each do |path|
+          relative = path.delete_prefix("#{source}/")
+          if File.basename(relative) == MODULE_FILE
+            UI.die!("#{File.join(SOURCE_DIR, relative)} is generated by `every build` — " \
+                    "remove it and let the CLI write the module declarations")
+          end
+
+          target = File.join(dest, relative)
+          FileUtils.mkdir_p(File.dirname(target))
+          FileUtils.cp(path, target)
+        end
+
+        modules = module_tree(sources.map { |path| path.delete_prefix("#{source}/") })
+        write_module_files(dest, modules)
+        report(sources, modules)
+      end
+
+      # Directory → the child modules declared in its mod.rs. "" is the root.
+      # A .rs file contributes its basename; a sub-directory contributes itself
+      # and gets a mod.rs of its own.
+      def module_tree(relatives)
+        tree = Hash.new { |hash, key| hash[key] = [] }
+        tree[""] # the root always exists, even with no sources
+        relatives.each do |relative|
+          parts = relative.delete_suffix(".rs").split(File::SEPARATOR)
+          parts.each_with_index do |part, index|
+            parent = parts[0...index].join(File::SEPARATOR)
+            tree[parent] << part unless tree[parent].include?(part)
+          end
+        end
+        tree.transform_values(&:sort)
+      end
+
+      def write_module_files(dest, modules)
+        modules.each do |dir, children|
+          path = dir.empty? ? File.join(dest, MODULE_FILE) : File.join(dest, dir, MODULE_FILE)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, dir.empty? ? root_module(modules) : child_module(children))
+        end
+      end
+
+      def child_module(children)
+        <<~RUST
+          // GENERATED by `every build` — edits are overwritten.
+          // Declares the .rs files this directory holds in native/desktop/.
+          #{children.map { |name| "pub mod #{name};" }.join("\n")}
+        RUST
+      end
+
+      # Everything reachable from the root, as `self::a::b` paths, so the
+      # dispatcher can glob-import them all.
+      def module_paths(modules)
+        modules.flat_map do |dir, children|
+          prefix = dir.empty? ? [] : dir.split(File::SEPARATOR)
+          children.map { |name| (prefix + [name]).join("::") }
+        end.sort
+      end
+
+      def root_module(modules)
+        commands = @config.native_desktop_commands
+        paths = module_paths(modules)
+
+        <<~RUST
+          // GENERATED by `every build` / `every dev` from `native.desktop` in
+          // config/everywhere.yml, alongside the app's own .rs files copied from
+          // native/desktop/. Edits are overwritten — see support/desktop/README.md.
+
+          use crate::commands;
+
+          #{modules.fetch("", []).map { |name| "pub mod #{name};" }.join("\n")}
+
+          // Command names are global, the same way iOS screen types and asset
+          // names are: you declare `scan_ports`, not `serial::scan_ports`. Two
+          // modules defining the same name is a compile error naming both, which
+          // is the right way to find out.
+          #{glob_imports(paths)}
+
+          // The shell's own commands. App extensions answer over events instead —
+          // see extension_host.rs for why invoke isn't available to them.
+          pub fn handler() -> impl Fn(tauri::ipc::Invoke<tauri::Wry>) -> bool + Send + Sync + 'static {
+              tauri::generate_handler![commands::notify_command]
+          }
+
+          pub fn setup(app: &tauri::App) -> Result<(), Box<dyn std::error::Error>> {
+              crate::extension_host::install_command_bridge(app, dispatch);
+          #{setup_call}    Ok(())
+          }
+
+          fn dispatch(
+              app: &tauri::AppHandle,
+              name: &str,
+              payload: serde_json::Value,
+          ) -> Result<serde_json::Value, String> {
+              match name {
+          #{dispatch_arms(commands)}        _ => Err(format!(
+                      "no desktop command named {name:?} — declare it under native.desktop.commands"
+                  )),
+              }
+          }
+        RUST
+      end
+
+      # One attribute per import, not one for the block: #[allow] applies to the
+      # item that follows it, so a single leading attribute would leave every
+      # import after the first warning. Most of these ARE unused — a module of
+      # helpers with no command in it is normal.
+      def glob_imports(paths)
+        paths.map { |path| "#[allow(unused_imports)]\nuse self::#{path}::*;" }.join("\n")
+      end
+
+      # `setup: true` means the app defines setup() in native/desktop/setup.rs.
+      # One fixed location rather than a configurable one: it's called exactly
+      # once from exactly here, so a second way to spell it buys nothing.
+      def setup_call
+        return "" unless @config.native_desktop_setup?
+
+        "    setup::setup(app)?;\n"
+      end
+
+      def dispatch_arms(commands)
+        commands.map { |name| "        #{name.inspect} => #{name}(app, payload),\n" }.join
+      end
+
+      def report(sources, modules)
+        commands = @config.native_desktop_commands
+        if sources.empty? && !commands.empty?
+          UI.warn("native.desktop declares #{commands.join(", ")} but #{SOURCE_DIR}/ has no .rs files")
+          return
+        end
+        return if sources.empty?
+
+        UI.step("desktop extensions: #{sources.length} file#{"s" unless sources.length == 1} " \
+                "(#{modules.fetch("", []).join(", ")})#{" → #{commands.join(", ")}" unless commands.empty?}")
+      end
+    end
+  end
+end

data/lib/everywhere/builders/ios.rb

@@ -5,6 +5,7 @@ require_relative "../paths"
 require_relative "../shellout"
 require_relative "../log_filter"
 require_relative "../icon"
+require_relative "../asset_catalog"
 require_relative "../ui"
 
 module Everywhere
@@ -72,9 +73,9 @@ module Everywhere
       end
 
       # The whole per-app surface: one xcconfig (identity), two JSON resources
-      # (runtime config + path configuration with baked tabs), one PNG (icon),
-      # and the Extensions/ buildable folder (app-authored Swift + generated
-      # registry). The pbxproj is never touched.
+      # (runtime config + path configuration with baked tabs), the asset catalog
+      # (icon + app images), and the Extensions/ buildable folder (app-authored
+      # Swift + generated registry). The pbxproj is never touched.
       def stamp!(work)
         UI.step("stamping shell #{UI.dim("(#{bundle_id} → #{UI.short_path(work)})")}")
         write_xcconfig(work)
@@ -86,8 +87,10 @@ module Everywhere
                    @config.path_configuration_json("ios"))
         write_launch_background(work)
         write_usage_strings(work)
+        write_url_scheme(work)
         write_entitlements(work)
         write_app_icon(work)
+        write_asset_catalog(work)
         write_extensions(work)
         write_native_packages(work)
       end
@@ -291,6 +294,25 @@ module Everywhere
         end
       end
 
+      # The custom URL scheme third-party sign-in returns through
+      # (everywhere.yml auth:) → Info.plist. ASWebAuthenticationSession claims
+      # the callback for itself while it's running, so this registration isn't
+      # what makes the flow work — it's what stops another app from quietly
+      # owning the scheme, and what makes `xcrun simctl openurl` usable for
+      # testing the return leg by hand.
+      def write_url_scheme(work)
+        errors = @config.auth_errors
+        UI.die!("auth in config/everywhere.yml:\n#{errors.join("\n")}") unless errors.empty?
+        return unless @config.oauth?
+
+        require "json"
+        scheme = @config.auth_scheme
+        UI.step("stamping sign-in callback scheme #{UI.dim("(#{scheme}://)")}")
+        Shellout.run!({}, "plutil", "-replace", "CFBundleURLTypes", "-json",
+                      JSON.generate([{ "CFBundleURLName" => bundle_id, "CFBundleURLSchemes" => [scheme] }]),
+                      File.join(work, "App", "Info.plist"))
+      end
+
       # The launch-screen (and splash overlay) background — the storyboard's
       # LaunchBackground named color, stamped from appearance.background_color
       # so the launch frame matches the app instead of the template default.
@@ -357,6 +379,21 @@ module Everywhere
         UI.warn "couldn't read #{File.basename(source)} — shipping the placeholder icon"
       end
 
+      # App-supplied images: native/ios/assets/** → imagesets in the template's
+      # Assets.xcassets, so native/ios Swift code reaches them by filename with
+      # Image("logo") / UIImage(named: "logo").
+      def write_asset_catalog(work)
+        source = File.join(@root, "native", "ios", "assets")
+        return unless File.directory?(source)
+
+        names, errors = AssetCatalog.write!(source, File.join(work, "App", "Assets.xcassets"))
+        UI.die!("native/ios/assets:\n#{errors.join("\n")}") unless errors.empty?
+        return if names.empty?
+
+        listed = names.length > 6 ? "#{names.take(6).join(", ")}, …" : names.join(", ")
+        UI.step("bundling image assets #{UI.dim("(#{names.length} from native/ios/assets: #{listed})")}")
+      end
+
       def xcodebuild!(work, configuration, dist_dir)
         UI.step("building iOS shell #{UI.dim("(xcodebuild, #{configuration}, first run compiles HotwireNative)")}")
         FileUtils.mkdir_p(dist_dir)

data/lib/everywhere/child_processes.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Everywhere
+  # A thread-scoped registry of the long-running children a task spawned, so the
+  # task can be cancelled without hunting pids by hand.
+  #
+  # `every dev` runs each build in its own thread. When the session ends (or a
+  # build has to be abandoned) we need to kill *that* thread's xcodebuild or
+  # gradlew and nothing else — a global list would leak entries from threads
+  # that died unexpectedly and would make "which build does this pid belong to?"
+  # unanswerable. Registering against the spawning thread answers it for free.
+  #
+  # Only genuinely long-running children register (see Shellout.run_logged!).
+  # Short probes — simctl, adb, xcrun — deliberately stay in the CLI's own
+  # process group, where a Ctrl-C at the terminal kills them as it always has.
+  module ChildProcesses
+    LOCK = Mutex.new
+    PIDS = :everywhere_child_pids
+    ISOLATE = :everywhere_isolate_children
+
+    module_function
+
+    # Mark this thread's long-running children as needing their own process
+    # group — set by TaskPool for every worker. Outside a worker this is false
+    # and `every build` / `every release` keep today's behavior, where a Ctrl-C
+    # at the terminal reaches the compiler directly.
+    def isolate! = Thread.current.thread_variable_set(ISOLATE, true)
+
+    def isolated? = !!Thread.current.thread_variable_get(ISOLATE)
+
+    def track(pid)   = LOCK.synchronize { list << pid }
+    def untrack(pid) = LOCK.synchronize { list.delete(pid) }
+
+    # TERM every child `thread` spawned, escalating to KILL for anything still
+    # alive after `grace`. Returns the pids that had to be killed.
+    def terminate(thread, grace: 5)
+      pids = LOCK.synchronize { (thread.thread_variable_get(PIDS) || []).dup }
+      return [] if pids.empty?
+
+      pids.each { |pid| signal(pid, "TERM") }
+      deadline = now + grace
+      sleep(0.1) while pids.any? { |pid| alive?(pid) } && now < deadline
+      pids.select { |pid| alive?(pid) }.each { |pid| signal(pid, "KILL") }
+    end
+
+    # Signal a child's whole process group, falling back to the bare pid when it
+    # doesn't lead one. Never raises: callers are teardown paths.
+    def signal(pid, sig)
+      Process.kill(sig, -Process.getpgid(pid))
+    rescue StandardError
+      begin
+        Process.kill(sig, pid)
+      rescue StandardError
+        nil
+      end
+    end
+
+    def alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def list
+      Thread.current.thread_variable_get(PIDS) ||
+        Thread.current.thread_variable_set(PIDS, [])
+    end
+  end
+end

data/lib/everywhere/commands/build.rb

@@ -9,7 +9,10 @@ require_relative "../log_filter"
 require_relative "../png"
 require_relative "../icon"
 require_relative "../paths"
+require_relative "../desktop_assets"
 require_relative "../builders/ios"
+require_relative "../builders/android"
+require_relative "../builders/desktop"
 
 module Everywhere
   module Commands
@@ -24,34 +27,57 @@ module Everywhere
     class Build < Dry::CLI::Command
       SHIM = File.expand_path("~/.tebako-shims/clang++")
 
-      desc "Package the app natively — desktop (tebako press + shell + .app) or iOS (--target ios-arm64)"
+      DEFAULT_TARGET = "macos-arm64"
+      IOS_TARGET = "ios-arm64"
+      # The APK/AAB is universal, so the arch half is nominal — it exists only
+      # so every target reads as os-arch.
+      ANDROID_TARGET = "android-arm64"
+
+      # The --ios/--android shorthands and the os they stand for, so adding a
+      # mobile platform is one entry rather than a third copy of resolve_target.
+      SHORTHAND_TARGETS = { ios: IOS_TARGET, android: ANDROID_TARGET }.freeze
+
+      desc "Package the app natively — desktop (tebako press + shell + .app), iOS (--ios) or Android (--android)"
 
       option :root,       default: ".",              desc: "App root directory"
       option :output,     default: nil,              desc: "Output binary path (default: dist/<app>)"
       option :ruby,       default: "4.0.6",          desc: "Ruby version to package"
       option :entry,      default: "native_boot.rb", desc: "Entry point script relative to root"
       option :app_name,   default: nil,              desc: "Bundle name (default: capitalized app dir)"
-      option :target,     default: "macos-arm64",    desc: "Build target (os-arch) — selects any platforms: overrides"
+      option :target,     default: nil,              desc: "Build target (os-arch) — selects any platforms: overrides, default: \"#{DEFAULT_TARGET}\""
       option :shell_dir,  default: nil,              desc: "Path to the shell's src-tauri directory"
+      option :ios,        type: :boolean, default: false, desc: "Build the iOS shell (shorthand for --target #{IOS_TARGET})"
+      option :android,    type: :boolean, default: false, desc: "Build the Android shell (shorthand for --target #{ANDROID_TARGET})"
       option :skip_press, type: :boolean, default: false, desc: "Reuse the existing pressed binary, only rebuild the .app"
 
       def call(root: ".", output: nil, ruby: "4.0.6", entry: "native_boot.rb",
-               app_name: nil, target: "macos-arm64", shell_dir: nil, skip_press: false, **)
+               app_name: nil, target: nil, shell_dir: nil, ios: false, android: false, skip_press: false, **)
+        target = resolve_target(target, ios: ios, android: android)
         root_path = File.expand_path(root)
         config = Everywhere::Config.load(root_path)
 
         # Builder dispatch on the target's os (build-engine.md §5): macOS is
-        # the tebako+tauri path below; iOS is a Hotwire Native shell built by
-        # its own builder. Anything else has no builder yet.
+        # the tebako+tauri path below; the mobile targets are Hotwire Native
+        # shells, each built by its own builder. Anything else has no builder yet.
         case Everywhere::Config.os_of(target)
-        when "ios"
-          app = Builders::Ios.new(config: config, root: root_path, target: target)
-                             .build!(dist_dir: File.expand_path("dist", root_path))
+        when "ios", "android"
+          app = mobile_builder(target).new(config: config, root: root_path, target: target)
+                                      .build!(dist_dir: File.expand_path("dist", root_path))
           UI.success("built #{rel(app, root_path)}")
           return
         when "macos" # the rest of this method
         else
-          UI.die!("no builder for target #{target} — macos-* and ios-* are supported")
+          UI.die!("no builder for target #{target} — macos-*, ios-* and android-* are supported")
+        end
+
+        # Desktop chrome is validated here rather than in the shell: a typo in
+        # `window:` would otherwise fall through Rust's match arms as a silent
+        # default, and you'd learn about it by squinting at a title bar after a
+        # full press+compile. The mobile builders validate their own sections
+        # the same way (Builders::Ios#write_extensions).
+        window_errors = config.window_errors
+        unless window_errors.empty?
+          UI.die!("window: in config/everywhere.yml:\n#{window_errors.join("\n")}")
         end
 
         # The os of `target` selects any per-platform overrides (bundle id,
@@ -95,6 +121,34 @@ module Everywhere
 
       private
 
+      # `--ios` is the shorthand `every dev` already has; --target stays the
+      # general escape hatch. Both given is only an error when they disagree —
+      # `--ios --target ios-arm64` is redundant, not wrong.
+      def mobile_builder(target)
+        Everywhere::Config.os_of(target) == "android" ? Builders::Android : Builders::Ios
+      end
+
+      # --ios/--android are shorthand for their target, and disagreeing with an
+      # explicit --target is a mistake worth naming rather than silently
+      # resolving one way: both spellings were deliberate, so we can't know
+      # which one the user meant.
+      def resolve_target(target, ios:, android:)
+        asked = { ios: ios, android: android }.select { |_flag, given| given }.keys
+        if asked.length > 1
+          UI.die!("#{asked.map { |f| "--#{f}" }.join(" and ")} are separate builds — run one at a time")
+        end
+
+        flag = asked.first or return target || DEFAULT_TARGET
+        shorthand = SHORTHAND_TARGETS.fetch(flag)
+        return shorthand if target.nil?
+
+        unless Everywhere::Config.os_of(target) == flag.to_s
+          UI.die!("--#{flag} and --target #{target} disagree — drop one " \
+                  "(--#{flag} means --target #{shorthand})")
+        end
+        target
+      end
+
       def rel(path, root_path) = UI.short_path(path.sub("#{root_path}/", "").sub("#{Dir.pwd}/", ""))
 
       # The precompile step runs against the HOST Ruby — unlike tebako press,
@@ -111,7 +165,7 @@ module Everywhere
       # EVERY_BUNDLE_PATH (set by `every platform runner`) redirects the app's
       # gems to a stable per-user dir so CI can cache them across builds. It
       # must be merged EXPLICITLY into each host-side bundler command:
-      # Shellout.unbundled strips inherited BUNDLE_* vars, so an inherited
+      # Shellout.child_env strips inherited BUNDLE_* vars, so an inherited
       # BUNDLE_PATH would never survive to the child process.
       def bundle_env
         path = ENV["EVERY_BUNDLE_PATH"]
@@ -162,7 +216,12 @@ module Everywhere
       # Rails binary (as "app-server") + Info.plist + icon. An .app bundle is
       # just a directory layout, so we build it by hand — no tauri-cli needed.
       def bundle_app(server_binary, app_name, shell_dir, config, target: "macos-arm64", dist_dir: nil)
-        shell_dir ||= Everywhere::Paths.shell_dir!
+        # An app with native.desktop gets a stamped per-app shell; everyone else
+        # compiles the gem's copy against the shared target dir, exactly as
+        # before. Builders::Desktop decides which, and the rest of this method
+        # doesn't need to know.
+        prepared = Builders::Desktop.new(config: config, root: config.root, template_dir: shell_dir).prepare!
+        shell_dir = prepared.dir
         dist_dir ||= File.dirname(server_binary)
 
         icon_source = config.icon
@@ -193,6 +252,12 @@ module Everywhere
         # shell must be COMPILED with the app's icon. Swap in the shaped master
         # for the build, restore the placeholder after; touch build.rs so
         # tauri-build re-embeds.
+        #
+        # The restore only matters on the fast path, where shell_dir is the
+        # INSTALLED GEM and every app shares it — leaving one app's icon there
+        # would brand the next app's build. A stamped work dir belongs to this
+        # app alone, so its icon can stay: restoring would only force another
+        # re-embed on the next build.
         shell_icon = File.join(shell_dir, "icons", "icon.png")
         placeholder_backup = "#{shell_icon}.placeholder"
         if icon_source
@@ -212,12 +277,12 @@ module Everywhere
           FileUtils.touch(File.join(shell_dir, "build.rs"))
         end
 
-        UI.step("building shell #{UI.dim("(cargo release)")}")
-        target_dir = Everywhere::Paths.cargo_target_dir
+        UI.step("building shell #{UI.dim(prepared.stamped? ? "(cargo release, per-app)" : "(cargo release)")}")
+        target_dir = prepared.target_dir
         begin
           Shellout.run!({ "CARGO_TARGET_DIR" => target_dir }, "cargo", "build", "--release", chdir: shell_dir)
         ensure
-          if icon_source && File.exist?(placeholder_backup)
+          if !prepared.stamped? && icon_source && File.exist?(placeholder_backup)
             FileUtils.mv(placeholder_backup, shell_icon)
             FileUtils.touch(File.join(shell_dir, "build.rs"))
           end
@@ -238,6 +303,7 @@ module Everywhere
         FileUtils.cp(server_binary, File.join(macos, "app-server")) if server_binary
 
         File.write(File.join(resources, "everywhere.json"), config.to_shell_json(target: target))
+        write_desktop_assets(config, resources)
         if (splash = config.splash)
           if File.exist?(splash)
             FileUtils.cp(splash, File.join(resources, "splash.html"))
@@ -264,6 +330,21 @@ module Everywhere
         FileUtils.remove_entry(work) if work && File.directory?(work)
       end
 
+      # native/desktop/assets/** → Contents/Resources/assets/, where the shell
+      # finds the tray icon and extension Rust finds anything it draws. The
+      # mobile builders compile their assets into a platform resource format;
+      # desktop has none, so this is a validated copy (Everywhere::DesktopAssets).
+      def write_desktop_assets(config, resources)
+        source = File.join(config.root, "native", "desktop", "assets")
+        names, errors = Everywhere::DesktopAssets.write!(source, File.join(resources, "assets"))
+        unless errors.empty?
+          UI.die!("native/desktop/assets:\n#{errors.join("\n")}")
+        end
+        return if names.empty?
+
+        UI.step("desktop assets: #{names.join(", ")}")
+      end
+
       # Write Resources/AppIcon.icns from a (shaped) PNG. Pure Ruby — no sips or
       # iconutil — so it produces the same icns on any build host.
       def make_icns(png, resources_dir)