ruby_everywhere 0.1.15 → 0.3.0

data/lib/everywhere/mobile_config_endpoint.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Everywhere
+  # Rack middleware serving the mobile shells' remote path configuration:
+  #
+  #   GET /everywhere/ios_v1.json      (android_v1.json when that shell lands)
+  #
+  # The JSON is built from config/everywhere.yml on each request (it's a tiny
+  # file, and re-reading means tab changes deploy with the app — the whole
+  # point: no app-store release to change tabs). This middleware is the
+  # SINATRA/HANAMI strategy — add it to config.ru:
+  #
+  #   use Everywhere::MobileConfigEndpoint
+  #
+  # Rails apps don't need it: Everywhere::Engine appends a real route to
+  # MobileConfigsController instead (logging, instrumentation, overridable).
+  #
+  # The native shells load it as a Hotwire Native path-configuration source
+  # (after their bundled copy), so both rules and settings.tabs can be
+  # overridden server-side.
+  class MobileConfigEndpoint
+    PATH = %r{\A/everywhere/(ios|android)_v1\.json\z}
+    RESET = "/everywhere/reset"
+    AASA = "/.well-known/apple-app-site-association"
+    ASSETLINKS = "/.well-known/assetlinks.json"
+
+    def initialize(app, root: Dir.pwd)
+      @app = app
+      @root = root
+    end
+
+    def call(env)
+      return @app.call(env) unless env["REQUEST_METHOD"] == "GET"
+
+      if env["PATH_INFO"] == RESET
+        require "rack/utils"
+        to = Rack::Utils.parse_query(env["QUERY_STRING"])["to"]
+        return html(Everywhere.mobile_reset_html(to))
+      end
+
+      # Deep-linking association files (generated from everywhere.yml). Pass
+      # through when not configured so the host app can serve its own.
+      if env["PATH_INFO"] == AASA
+        body = Config.load(@root).apple_app_site_association_json
+        return body ? json(body) : @app.call(env)
+      end
+      if env["PATH_INFO"] == ASSETLINKS
+        body = Config.load(@root).asset_links_json
+        return body ? json(body) : @app.call(env)
+      end
+
+      match = PATH.match(env["PATH_INFO"]) or return @app.call(env)
+
+      os = match[1]
+      config = Config.load(@root)
+      tabs = Everywhere.resolve_tabs(config.tabs_for(os), request_for(env))
+      json(config.path_configuration_json(os, tabs: tabs))
+    end
+
+    private
+
+    def json(body)
+      [200, { "content-type" => "application/json", "cache-control" => cache_control }, [body]]
+    end
+
+    def html(body)
+      [200, { "content-type" => "text/html; charset=utf-8", "cache-control" => "no-store" }, [body]]
+    end
+
+    # A Rack::Request the tab filter can read (session/cookies) when the host
+    # app has it; otherwise the raw env is enough for header-based checks.
+    def request_for(env)
+      require "rack/request"
+      Rack::Request.new(env)
+    rescue LoadError
+      env
+    end
+
+    # Never cache: the response depends on the session (filter_tabs), so a
+    # public cache could leak one user's tabs to another and a client cache
+    # would serve stale tabs across sign-in/out. It's a couple of ms anyway.
+    def cache_control
+      "no-store"
+    end
+  end
+end

data/lib/everywhere/mobile_configs_controller.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Everywhere
+  # Serves the mobile shells' remote path configuration in Rails apps:
+  #
+  #   GET /everywhere/ios_v1.json      -> MobileConfigsController#show
+  #
+  # The route is appended by Everywhere::Engine, so it shows up in
+  # `rails routes` and the app can override it by drawing its own. Inherits
+  # ActionController::API on purpose:
+  #   * never the app's ApplicationController — its before_actions
+  #     (authentication!) would lock the shells out, and
+  #   * not ActionController::Base — its `helper :all` resolution reaches
+  #     into the host app's helpers, which aren't loadable when the gem is
+  #     required during boot. A JSON endpoint needs none of that.
+  #
+  # everywhere.yml is re-read on every request: tab changes go live with a
+  # deploy — or a plain file save in development, where responses are
+  # explicitly uncached so the dev shell's reload polling sees them instantly.
+  class MobileConfigsController < ActionController::API
+    def show
+      config = Config.load(::Rails.root.to_s)
+
+      # Never cache: the response depends on the session (filter_tabs can hide
+      # tabs when signed out), so a shared/public cache could serve one user's
+      # tabs to another, and a client cache would serve stale tabs across
+      # sign-in/out. The endpoint is a couple of milliseconds — no cache needed.
+      response.headers["cache-control"] = "no-store"
+
+      os = params[:platform_v1].delete_suffix("_v1")
+      tabs = Everywhere.resolve_tabs(config.tabs_for(os), request)
+      render json: config.path_configuration_hash(os, tabs: tabs)
+    end
+
+    # GET /.well-known/apple-app-site-association — the iOS universal-links
+    # association file, generated from everywhere.yml. Extension-less and
+    # application/json, per Apple. 404 when deep linking isn't configured.
+    def apple_app_site_association
+      json = Config.load(::Rails.root.to_s).apple_app_site_association_json
+      return head(:not_found) unless json
+
+      render json: json
+    end
+
+    # GET /.well-known/assetlinks.json — the Android Digital Asset Links file.
+    def asset_links
+      json = Config.load(::Rails.root.to_s).asset_links_json
+      return head(:not_found) unless json
+
+      render json: json
+    end
+
+    # GET /everywhere/reset?to=/path — the native "reset the app" page. Auth
+    # flows redirect the shell here so it rebuilds cleanly before landing on
+    # `to`. Never cached (it must run every time).
+    def reset
+      response.headers["cache-control"] = "no-store"
+      render html: Everywhere.mobile_reset_html(params[:to]).html_safe,
+             layout: false, content_type: "text/html"
+    end
+  end
+end

data/lib/everywhere/native_helper.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+
+module Everywhere
+  # Server-side view helpers mirroring the JS bridge's platform detection, so
+  # ERB can branch on the native shell the same way `Everywhere.platform`
+  # does on the client:
+  #
+  #   <%= link_to "Install the app", … unless native_app? %>
+  #   <div class="<%= "native-inset" if native_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.
+  module NativeHelper
+    # True inside any RubyEverywhere native shell (iOS or Android).
+    def native_app?
+      !native_platform.nil?
+    end
+
+    # :ios, :android, or nil in a plain browser. Reads Hotwire Native's UA
+    # marker, so it's correct even before the JS bridge has booted.
+    def native_platform
+      ua = _everywhere_user_agent or return nil
+      return :ios if ua.include?("Hotwire Native iOS")
+      return :android if ua.include?("Hotwire Native Android")
+
+      nil
+    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.
+    def native_version
+      ua = _everywhere_user_agent or return nil
+      match = ua.match(%r{RubyEverywhere/([\w.\-]+)}) or return nil
+
+      Gem::Version.new(match[1])
+    rescue ArgumentError
+      nil
+    end
+
+    # Where to send the user after an auth change. In a native shell, route
+    # through the reset page (/everywhere/reset) so the app rebuilds cleanly —
+    # fresh web views, re-fetched tabs — then lands on `to`. In a browser it's
+    # just `to`. Use it in controllers:
+    #
+    #   redirect_to everywhere_auth_redirect(after_authentication_url)
+    #
+    # `to` may be a full URL or a path; only the same-origin path is forwarded.
+    def everywhere_auth_redirect(to)
+      return to unless native_app? && respond_to?(:everywhere_reset_path)
+
+      path = to.to_s.sub(%r{\Ahttps?://[^/]+}, "")
+      path = "/" if path.empty? || !path.start_with?("/")
+      everywhere_reset_path(to: path)
+    end
+
+    # App icon badge count, server-rendered. Emits a meta tag the JS bridge
+    # applies on every Turbo visit — CSP-safe (no inline script) and correct
+    # on the first paint. 0 clears the badge. Put it in the layout <head>:
+    #
+    #   <%= everywhere_badge Current.user.unread_count %>
+    #
+    # In the mobile shell this badges the app icon; in an installed PWA the
+    # Badging API; elsewhere it renders inert metadata.
+    def everywhere_badge(count)
+      tag.meta(name: "everywhere:badge", content: count.to_i)
+    end
+
+    # Native tab bar badge for the tab whose everywhere.yml path is `path`.
+    # Same delivery as everywhere_badge; 0 clears. Mobile shell only.
+    #
+    #   <%= everywhere_tab_badge "/inbox", Current.user.unread_count %>
+    def everywhere_tab_badge(path, count)
+      tag.meta(name: "everywhere:tab-badge",
+               content: JSON.generate({ path: path, count: count.to_i }))
+    end
+
+    # Biometric gate: wraps sensitive markup so the mobile shell keeps it
+    # hidden until Face ID / Touch ID passes — but only when the user has the
+    # device-local lock turned on (everywhere_biometric_toggle, or
+    # Everywhere.biometrics.setLockEnabled). Browsers and the desktop shell
+    # render the content plainly. Requires `biometrics` in everywhere.yml's
+    # permissions.
+    #
+    #   <%= everywhere_biometric_lock reason: "Unlock account settings" do %>
+    #     ...profile, password, sessions...
+    #   <% end %>
+    #
+    # `name` keys the once-per-session unlock (defaults to the page path).
+    # For a fully custom overlay, hand-write the contract this emits:
+    #
+    #   <div data-everywhere-biometric-lock="<name>"
+    #        data-everywhere-biometric-reason="…" data-everywhere-biometric-passcode>
+    #     <div data-everywhere-biometric-content hidden>…</div>
+    #     <div data-everywhere-biometric-locked hidden>
+    #       <button data-everywhere-biometric-unlock>Unlock</button>
+    #     </div>
+    #   </div>
+    def everywhere_biometric_lock(reason: nil, name: nil, allow_passcode: true,
+                                  unlock_label: "Unlock", locked_message: nil,
+                                  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?
+
+      attrs = [%(data-everywhere-biometric-lock="#{_everywhere_attr(name)}")]
+      attrs << %(data-everywhere-biometric-reason="#{_everywhere_attr(reason)}") if reason
+      attrs << "data-everywhere-biometric-passcode" if allow_passcode
+      attrs << %(class="#{_everywhere_attr(wrapper_class)}") if wrapper_class
+
+      html = +"<div #{attrs.join(" ")}>"
+      html << %(<div data-everywhere-biometric-content hidden>#{content}</div>)
+      html << %(<div data-everywhere-biometric-locked hidden#{%( class="#{_everywhere_attr(locked_class)}") if locked_class}>)
+      html << %(<p#{%( class="#{_everywhere_attr(message_class)}") if message_class}>#{_everywhere_attr(locked_message)}</p>) if locked_message
+      html << %(<button type="button" data-everywhere-biometric-unlock#{%( class="#{_everywhere_attr(unlock_class)}") if unlock_class}>#{_everywhere_attr(unlock_label)}</button>)
+      html << "</div></div>"
+      html.respond_to?(:html_safe) ? html.html_safe : html
+    end
+
+    # The settings switch for the device-local biometric lock. Renders hidden
+    # and disabled; the bridge reveals and enables it only in the mobile shell
+    # with working biometrics (toggling runs the biometric check first). Put
+    # `data-everywhere-biometric-toggle-row` + `hidden` on the surrounding row
+    # to reveal the whole thing together:
+    #
+    #   <div data-everywhere-biometric-toggle-row hidden>
+    #     <label>Require Face ID <%= everywhere_biometric_toggle %></label>
+    #   </div>
+    def everywhere_biometric_toggle(css_class: nil, id: nil)
+      attrs = +""
+      attrs << %( id="#{_everywhere_attr(id)}") if id
+      attrs << %( class="#{_everywhere_attr(css_class)}") if css_class
+      html = %(<input type="checkbox" hidden disabled data-everywhere-biometric-toggle#{attrs}>)
+      html.respond_to?(:html_safe) ? html.html_safe : html
+    end
+
+    # A navigation-bar button. Renders a normal link (or a submit button with
+    # type: :submit) that the mobile shell lifts into the top navigation bar —
+    # tapping the native button just clicks this element, so a link navigates
+    # and a submit submits, defined once. In a browser it's the plain link it
+    # already is (the shell hides the in-page copy). Icons are per-platform like
+    # tabs: icon: is the shared fallback, icons: {ios:, android:} the specifics
+    # (SF Symbol / Material name).
+    #
+    #   <%= everywhere_nav_button "New", new_note_path, icons: { ios: "plus", android: "add" } %>
+    #   <%= everywhere_nav_button "Save", type: :submit, style: "done" %>
+    def everywhere_nav_button(title, href = nil, icon: nil, icons: nil, side: "right",
+                              style: "plain", type: nil, form: nil, disabled: false,
+                              method: nil, css_class: nil, id: nil)
+      nav = _everywhere_nav_attrs("data-everywhere-nav-button", title: title, icon: icon,
+                                  icons: icons, side: side, style: style, disabled: disabled)
+      _everywhere_clickable(title, href, type: type, form: form, method: method,
+                            disabled: disabled, css_class: css_class, id: id, extra: nav)
+    end
+
+    # A form's submit control mirrored into the navigation bar (right side,
+    # "done" style by default). Place it inside the <form>, or aim it at one
+    # with form: "<form-id>".
+    #
+    #   <%= form_with model: @note do |f| %>
+    #     <%= everywhere_submit_button "Save" %>
+    #     ...
+    #   <% end %>
+    def everywhere_submit_button(title = "Save", side: "right", style: "done", form: nil,
+                                 icon: nil, icons: nil, css_class: nil, id: nil)
+      everywhere_nav_button(title, type: :submit, side: side, style: style, form: form,
+                            icon: icon, icons: icons, css_class: css_class, id: id)
+    end
+
+    # A navigation-bar pull-down / overflow menu (defaults to the ⋯ ellipsis
+    # icon). Yields the items — build them with everywhere_menu_item; in the
+    # shell they become a native UIMenu, in a browser a plain list of links.
+    #
+    #   <%= everywhere_nav_menu do %>
+    #     <%= everywhere_menu_item "Share", share_path, icons: { ios: "square.and.arrow.up" } %>
+    #     <%= everywhere_menu_item "Delete", note_path(@note), method: :delete, style: "destructive" %>
+    #   <% end %>
+    def everywhere_nav_menu(title = nil, icon: nil, icons: nil, side: "right",
+                            css_class: nil, id: nil, &block)
+      content = _everywhere_capture(&block)
+      attrs = _everywhere_nav_attrs("data-everywhere-nav-menu", title: title, icon: icon,
+                                    icons: icons, side: side)
+      common = +""
+      common << %( id="#{_everywhere_attr(id)}") if id
+      common << %( class="#{_everywhere_attr(css_class)}") if css_class
+      _everywhere_safe(%(<div#{common} #{attrs}>#{content}</div>))
+    end
+
+    # One item inside an everywhere_nav_menu or everywhere_menu. A link by
+    # default; type: :submit (with form:) submits a form, and method: (:delete,
+    # …) makes a Turbo method link. style: "destructive" tints it in the native
+    # menu / action sheet.
+    def everywhere_menu_item(title, href = nil, icon: nil, icons: nil, style: nil,
+                             type: nil, form: nil, method: nil, css_class: nil, id: nil)
+      extra = +"data-everywhere-menu-item"
+      extra << %( data-everywhere-menu-title="#{_everywhere_attr(title)}")
+      extra << _everywhere_icon_attrs("data-everywhere-menu-icon", icon, icons)
+      extra << %( data-everywhere-menu-style="#{_everywhere_attr(style)}") if style
+      _everywhere_clickable(title, href, type: type, form: form, method: method,
+                            css_class: css_class, id: id, extra: extra)
+    end
+
+    # An in-content action sheet: a trigger and the items it opens. In the
+    # mobile shell the trigger presents a native action sheet; in a browser it
+    # toggles the items as an inline menu (styled by everywhere/native.css).
+    # Choosing an item clicks it, so behavior lives in the items themselves.
+    #
+    #   <%= everywhere_menu "Options" do %>
+    #     <%= everywhere_menu_item "Edit", edit_post_path(@post) %>
+    #     <%= everywhere_menu_item "Delete", post_path(@post), method: :delete, style: "destructive" %>
+    #   <% end %>
+    def everywhere_menu(trigger = "Options", title: nil, trigger_class: nil,
+                        items_class: nil, css_class: nil, id: nil, &block)
+      content = _everywhere_capture(&block)
+      wrap = +""
+      wrap << %( id="#{_everywhere_attr(id)}") if id
+      wrap << %( class="#{_everywhere_attr(css_class)}") if css_class
+      wrap << %( data-everywhere-menu-title="#{_everywhere_attr(title)}") if title
+
+      trig = %(<button type="button" data-everywhere-menu-trigger#{%( class="#{_everywhere_attr(trigger_class)}") if trigger_class}>#{_everywhere_attr(trigger)}</button>)
+      items = %(<div data-everywhere-menu-items#{%( class="#{_everywhere_attr(items_class)}") if items_class}>#{content}</div>)
+      _everywhere_safe(%(<div data-everywhere-menu#{wrap}>#{trig}#{items}</div>))
+    end
+
+    # A floating action button: a fixed, safe-area-aware circular control (see
+    # everywhere/native.css). A real link (or button) that shows in a browser
+    # too and gains a tap haptic in the shell. Pass a block for custom content,
+    # or icon: for a built-in line glyph; label: sets the accessible name and,
+    # with extended: true, a visible label pill.
+    #
+    #   <%= everywhere_fab new_note_path, icon: :plus, label: "New note" %>
+    #   <%= everywhere_fab compose_path, icon: :pencil, label: "Compose", extended: true %>
+    def everywhere_fab(href = nil, icon: :plus, label: nil, haptic: "light", side: "right",
+                       extended: false, type: nil, form: nil, method: nil,
+                       css_class: nil, id: nil, &block)
+      classes = ["everywhere-fab"]
+      classes << "everywhere-fab-left" if side.to_s == "left"
+      classes << "everywhere-fab-extended" if extended
+      classes << css_class if css_class
+
+      inner = block ? _everywhere_capture(&block) : _everywhere_fab_icon(icon)
+      inner = "#{inner}<span class=\"everywhere-fab-label\">#{_everywhere_attr(label)}</span>" if extended && label
+
+      extra = %(class="#{classes.join(" ")}")
+      extra << %( aria-label="#{_everywhere_attr(label)}") if label
+      extra << %( data-everywhere-haptic="#{_everywhere_attr(haptic)}") if haptic
+
+      _everywhere_clickable(inner, href, type: type, form: form, method: method,
+                            id: id, extra: extra, raw_content: true)
+    end
+
+    private
+
+    # Build a link or button carrying `extra` attributes. `raw_content: true`
+    # trusts pre-built inner HTML (icon SVG); otherwise the text is escaped.
+    def _everywhere_clickable(content, href, type: nil, form: nil, method: nil,
+                              disabled: false, css_class: nil, id: nil, extra: "",
+                              raw_content: false)
+      common = +""
+      common << %( id="#{_everywhere_attr(id)}") if id
+      common << %( class="#{_everywhere_attr(css_class)}") if css_class
+      inner = raw_content ? content.to_s : _everywhere_attr(content)
+
+      html =
+        if type.to_s == "submit"
+          %(<button type="submit"#{%( form="#{_everywhere_attr(form)}") if form}#{" disabled" if disabled}#{common} #{extra}>#{inner}</button>)
+        elsif href.nil? && type
+          %(<button type="#{_everywhere_attr(type)}"#{" disabled" if disabled}#{common} #{extra}>#{inner}</button>)
+        else
+          meth = method ? %( data-turbo-method="#{_everywhere_attr(method)}") : ""
+          %(<a href="#{_everywhere_attr(href || "#")}"#{meth}#{common} #{extra}>#{inner}</a>)
+        end
+      _everywhere_safe(html)
+    end
+
+    # The data-* attribute run shared by nav buttons and nav menus.
+    def _everywhere_nav_attrs(marker, title:, icon: nil, icons: nil, side: "right",
+                              style: nil, disabled: false)
+      out = +marker.to_s
+      out << %( data-everywhere-nav-title="#{_everywhere_attr(title)}") if title
+      out << _everywhere_icon_attrs("data-everywhere-nav-icon", icon, icons)
+      out << %( data-everywhere-nav-side="left") if side.to_s == "left"
+      out << %( data-everywhere-nav-style="#{_everywhere_attr(style)}") if style && style.to_s != "plain"
+      out << " data-everywhere-nav-disabled" if disabled
+      out
+    end
+
+    # Per-platform icon attributes: the shared `<base>` plus `<base>-ios` /
+    # `<base>-android` from an icons: {ios:, android:} hash (string or symbol keys).
+    def _everywhere_icon_attrs(base, icon, icons)
+      out = +""
+      out << %( #{base}="#{_everywhere_attr(icon)}") if icon
+      if icons.is_a?(Hash)
+        %i[ios android].each do |os|
+          value = icons[os] || icons[os.to_s]
+          out << %( #{base}-#{os}="#{_everywhere_attr(value)}") if value
+        end
+      end
+      out
+    end
+
+    def _everywhere_capture(&block)
+      return "" unless block
+
+      respond_to?(:capture) ? capture(&block) : block.call
+    end
+
+    def _everywhere_safe(html)
+      html.respond_to?(:html_safe) ? html.html_safe : html
+    end
+
+    # Built-in line glyphs for everywhere_fab (24×24, currentColor stroke). SF
+    # Symbol / Material names don't render on the web, so the FAB carries its own.
+    FAB_ICONS = {
+      plus: "M12 5v14M5 12h14",
+      pencil: "M12 20h9M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4z",
+      camera: "M23 19a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h4l2-3h6l2 3h4a2 2 0 0 1 2 2zM12 17a4 4 0 1 0 0-8 4 4 0 0 0 0 8z",
+      search: "M21 21l-4.35-4.35M11 19a8 8 0 1 0 0-16 8 8 0 0 0 0 16z",
+      share: "M4 12v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8M16 6l-4-4-4 4M12 2v14",
+      check: "M20 6L9 17l-5-5",
+      close: "M18 6L6 18M6 6l12 12",
+      trash: "M3 6h18M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6",
+      arrow_up: "M12 19V5M5 12l7-7 7 7",
+      chevron_up: "M18 15l-6-6-6 6"
+    }.freeze
+
+    def _everywhere_fab_icon(icon)
+      return "" if icon.nil?
+
+      path = FAB_ICONS[icon.to_sym] || FAB_ICONS[:plus]
+      %(<svg class="everywhere-fab-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" ) +
+        %(stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="#{path}"/></svg>)
+    end
+
+    def _everywhere_attr(value)
+      ERB::Util.html_escape(value.to_s)
+    end
+
+    def _everywhere_user_agent
+      return unless respond_to?(:request) && request
+
+      ua = request.user_agent
+      ua unless ua.nil? || ua.empty?
+    end
+  end
+end

data/lib/everywhere/paths.rb

@@ -33,11 +33,52 @@ module Everywhere
                            "reinstall ruby_everywhere or pass --shell-dir")
     end
 
+    # The Hotwire Native iOS shell template bundled inside the gem:
+    # support/mobile/ios/ holds a frozen Xcode project the CLI stamps per-app
+    # (xcconfig + everywhere.json + AppIcon — never the pbxproj). The mobile/
+    # parent leaves room for support/mobile/android later.
+    def bundled_ios_dir
+      File.join(gem_root, "support", "mobile", "ios")
+    end
+
+    # Absolute path to the iOS template, or nil if the bundled copy is missing
+    # (a corrupt/partial install).
+    def ios_dir
+      bundled_ios_dir if File.exist?(File.join(bundled_ios_dir, "App.xcodeproj", "project.pbxproj"))
+    end
+
+    # Like #ios_dir but aborts with a helpful message when the template is
+    # missing. The --template-dir hint covers dev on a modified template.
+    def ios_dir!
+      ios_dir or UI.die!("couldn't find the bundled iOS template at #{bundled_ios_dir}; " \
+                         "reinstall ruby_everywhere or pass --template-dir")
+    end
+
     # Per-user cache dir. Keeps heavy build state out of the gem and the app.
     def cache_dir
       File.expand_path(ENV["RUBYEVERYWHERE_HOME"] || "~/.rubyeverywhere")
     end
 
+    # The stamped copy of the iOS template for one app. Persistent (not a
+    # tmpdir) on purpose: a stable project path keeps Xcode's incremental state
+    # valid across builds, and users can open the stamped project in Xcode.
+    def ios_work_dir(bundle_id)
+      File.join(cache_dir, "ios", bundle_id)
+    end
+
+    # Where xcodebuild writes DerivedData for iOS shell builds. Shared across
+    # apps like cargo_target_dir — safe because the product is always App.app;
+    # worst case a mismatch is a cache miss, never a wrong artifact.
+    def ios_derived_data_dir
+      File.join(cache_dir, "ios-derived-data")
+    end
+
+    # Where SPM clones the shell's package dependencies (hotwire-native-ios),
+    # so resolution is warm/offline after the first build.
+    def ios_packages_dir
+      File.join(cache_dir, "ios-packages")
+    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

data/lib/everywhere/raster.rb

@@ -25,6 +25,23 @@ module Everywhere
       new(width, height)
     end
 
+    # A copy composited over an opaque background color ([r, g, b] bytes) —
+    # straight alpha blend, result fully opaque. Flattens icons for stores
+    # that reject alpha channels (the iOS App Store).
+    def flatten_onto(rgb)
+      out = "\x00".b * (width * height * 4)
+      (width * height).times do |p|
+        i = p * 4
+        a = pixels.getbyte(i + 3)
+        3.times do |c|
+          out.setbyte(i + c, a == 255 ? pixels.getbyte(i + c)
+                             : ((pixels.getbyte(i + c) * a + rgb[c] * (255 - a)) / 255.0).round)
+        end
+        out.setbyte(i + 3, 255)
+      end
+      self.class.new(width, height, out)
+    end
+
     # Decode a PNG file into a Raster, or nil if it's a flavor PNG.decode_rgba
     # can't read (palette, 16-bit, interlaced, grayscale).
     def self.decode_png(path)

data/lib/everywhere/shellout.rb

@@ -72,8 +72,10 @@ module Everywhere
     end
     private_class_method :emit
 
+    # pgroup: the child leads its own process group so teardown can TERM the
+    # whole tree (foreman + watchers) without signalling the CLI itself.
     def spawn(env, cmd, chdir:)
-      unbundled { Process.spawn(env, cmd, chdir: chdir) }
+      unbundled { Process.spawn(env, cmd, chdir: chdir, pgroup: true) }
     end
   end
 end

data/lib/everywhere/simulator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "shellout"
+require_relative "ui"
+
+module Everywhere
+  # Thin wrappers around `xcrun simctl` — just enough to boot a Simulator,
+  # install the stamped shell and launch it. Anything fancier (choosing
+  # devices, multiple simulators) belongs in the user's own Xcode workflow.
+  module Simulator
+    module_function
+
+    # UDID of a booted iPhone Simulator, or nil.
+    def booted_udid
+      devices.find { |d| d["state"] == "Booted" }&.fetch("udid", nil)
+    end
+
+    # Boot the newest available iPhone (or reuse a booted one) and bring the
+    # Simulator app to the foreground. Returns the UDID.
+    def boot_default!
+      if (udid = booted_udid)
+        Shellout.run?("open", "-a", "Simulator", quiet: true)
+        return udid
+      end
+
+      device = devices.reverse.find { |d| d["name"].to_s.match?(/\AiPhone/) } || devices.last
+      UI.die!("no iOS Simulator devices — open Xcode once to install a Simulator runtime") unless device
+
+      UI.step("booting simulator #{UI.bold(device["name"])}")
+      Shellout.run?("xcrun", "simctl", "boot", device["udid"], quiet: true) # races `open` starting it; harmless
+      Shellout.run?("open", "-a", "Simulator", quiet: true)
+      wait_until_booted(device["udid"])
+      device["udid"]
+    end
+
+    def install(udid, app_path)
+      out, status = Shellout.capture("xcrun", "simctl", "install", udid, app_path)
+      UI.die!("simctl install failed: #{out.strip}") unless status&.success?
+    end
+
+    # Launch (relaunching if already running). Env vars are forwarded into the
+    # app's process via simctl's SIMCTL_CHILD_ prefix — how the dev URL
+    # reaches the shell without restamping the bundle.
+    def launch(udid, bundle_id, env: {})
+      child_env = env.transform_keys { |k| "SIMCTL_CHILD_#{k}" }
+      out, status = Shellout.capture(child_env,
+                                     "xcrun", "simctl", "launch",
+                                     "--terminate-running-process", udid, bundle_id)
+      UI.die!("simctl launch failed: #{out.strip}") unless status&.success?
+    end
+
+    # Available devices of the current runtime set, oldest runtime first —
+    # `.last` / `reverse.find` therefore prefer the newest.
+    def devices
+      out, status = Shellout.capture("xcrun", "simctl", "list", "devices", "available", "-j")
+      return [] unless status&.success?
+
+      JSON.parse(out).fetch("devices", {}).sort.flat_map { |_runtime, list| list }
+    rescue JSON::ParserError
+      []
+    end
+
+    def wait_until_booted(udid, timeout: 60)
+      deadline = Time.now + timeout
+      until Time.now > deadline
+        return if devices.any? { |d| d["udid"] == udid && d["state"] == "Booted" }
+
+        sleep 1
+      end
+      UI.die!("simulator never finished booting")
+    end
+  end
+end