ruby_everywhere 0.4.0 → 0.5.0

data/lib/everywhere/commands/install.rb

@@ -158,6 +158,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 +188,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:

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

data/lib/everywhere/desktop_assets.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Everywhere
+  # Compiles an app's native/desktop/assets/ tree into the flat assets/ folder
+  # the desktop shell reads at runtime — Resources/assets/ inside a packaged
+  # .app, or the source tree itself under `every dev` (NATIVE_ASSETS_DIR).
+  #
+  # Unlike iOS and Android there is no platform resource format to generate:
+  # macOS has no catalog for a Tauri bundle's loose resources, so "compiling"
+  # here means validating the names and copying. The filenames stay exactly as
+  # written, because the shell resolves variants itself (see assets_dir /
+  # asset_path in the shell's main.rs) — it is the one consumer, and it can read
+  # a suffix as cheaply as we can rewrite one.
+  #
+  # Filenames are the whole API, matching AssetCatalog: <name>[@2x|@3x][~dark].<ext>.
+  # Sub-directories organise the tree but do NOT namespace it — names are global,
+  # so assets/branding/logo.png is still "logo". That also means the destination
+  # can be flat, which is what keeps the Rust side a plain directory read.
+  #
+  # These assets are for the SHELL, not for your pages: window and tray icons,
+  # splash artwork, and anything extension Rust loads. Images your HTML
+  # references should keep coming from the asset pipeline, which already
+  # fingerprints and serves them.
+  module DesktopAssets
+    # What the shell can actually decode. Deliberately narrower than
+    # AssetCatalog's: these are handed to tauri::image::Image or read by
+    # extension Rust, and neither speaks PDF or SVG.
+    RASTER = %w[.png .jpg .jpeg].freeze
+    # Windows tray icons are conventionally .ico; it's passed through untouched
+    # for an extension that wants to hand one to the platform directly.
+    PASSTHROUGH = %w[.ico].freeze
+    EXTENSIONS = (RASTER + PASSTHROUGH).freeze
+    VECTOR = %w[.pdf .svg].freeze
+
+    # Names the shell gives meaning to on its own. Not reserved — providing one
+    # is exactly how you override a default — but worth naming here so the list
+    # has one home.
+    #
+    #   tray           the menu-bar / system-tray icon, drawn as-is
+    #   tray-template  same, but declared a macOS template image: black + alpha,
+    #                  recoloured by the system so it stays legible in a light
+    #                  menu bar, a dark one, and under a highlight. Wins over
+    #                  `tray` when both are present.
+    SHELL_NAMES = %w[tray tray-template].freeze
+
+    VALID_NAME = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/
+
+    class << self
+      # Copy every image under `source` into `dest`. Returns [names, errors];
+      # nothing is written when errors is non-empty, so a broken assets/ tree
+      # can't half-stamp a bundle.
+      #
+      # `dest` is regenerated wholesale — this module owns that directory, and
+      # an asset deleted from the app repo has to stop shipping.
+      def write!(source, dest)
+        files, errors = plan(source)
+        return [[], errors] unless errors.empty?
+
+        FileUtils.rm_rf(dest)
+        return [[], []] if files.empty?
+
+        FileUtils.mkdir_p(dest)
+        files.each { |file| FileUtils.cp(file[:path], File.join(dest, File.basename(file[:path]))) }
+
+        [files.map { |file| file[:name] }.uniq.sort, []]
+      end
+
+      private
+
+      # Errors are collected rather than raised so one `every build` reports
+      # every problem in the tree, not just the first.
+      def plan(source)
+        return [[], []] unless File.directory?(source)
+
+        errors = []
+        found = Dir.glob(File.join(source, "**", "*"))
+                   .select { |path| File.file?(path) && !File.basename(path).start_with?(".") }
+                   .sort
+        images, other = found.partition { |path| EXTENSIONS.include?(File.extname(path).downcase) }
+
+        other.each { |path| errors << unsupported_error(path, source) }
+        files = images.filter_map { |path| variant(path, source, errors) }
+
+        files.group_by { |file| file[:name] }.each do |name, group|
+          dirs = group.map { |file| file[:dir] }.uniq
+          if dirs.length > 1
+            errors << "#{name}: same asset name in #{dirs.map { |dir| label(dir) }.join(" and ")} — " \
+                      "names are global (the shell reads one flat folder), so rename one"
+          end
+          group.group_by { |file| [file[:scale], file[:dark]] }.each_value do |clash|
+            next if clash.length < 2
+
+            errors << "#{name}: #{clash.map { |file| file[:relative] }.join(" and ")} both claim the same slot"
+          end
+        end
+
+        [files, errors]
+      end
+
+      # A vector gets its own message: "unsupported image type" reads like the
+      # file is broken, when the real answer is a one-line export.
+      def unsupported_error(path, source)
+        relative = relative(path, source)
+        if VECTOR.include?(File.extname(path).downcase)
+          "#{relative}: the desktop shell can't rasterize vectors — export a PNG " \
+            "(at @2x, so it stays sharp on a Retina display)"
+        else
+          "#{relative}: unsupported image type — use #{EXTENSIONS.join(", ")}"
+        end
+      end
+
+      def variant(path, source, errors)
+        relative = relative(path, source)
+        name, scale, dark = parse(File.basename(path, File.extname(path)))
+
+        unless name.match?(VALID_NAME)
+          errors << "#{relative}: #{name.inspect} isn't a usable asset name — use letters, digits, _, - and ."
+          return nil
+        end
+
+        { name: name, dir: File.dirname(relative), scale: scale, dark: dark, path: path, relative: relative }
+      end
+
+      # Trailing @2x/@3x and ~dark markers, in either order, off the stem.
+      # Identical to AssetCatalog#parse on purpose: one filename convention
+      # across all three platforms is the whole point of the suffix API.
+      def parse(base)
+        name = base.dup
+        scale = nil
+        dark = false
+        loop do
+          if name.sub!(/~dark\z/, "")
+            dark = true
+          elsif name.sub!(/@([23])x\z/, "")
+            scale = "#{Regexp.last_match(1)}x"
+          else
+            break
+          end
+        end
+        [name, scale, dark]
+      end
+
+      def label(dir) = dir == "." ? "assets/" : "assets/#{dir}/"
+
+      def relative(path, source) = path.delete_prefix("#{source}/")
+    end
+  end
+end