ruby_everywhere 0.1.15 → 0.3.0

data/bridge/everywhere/native.css

@@ -0,0 +1,203 @@
+/* @rubyeverywhere/bridge — safe-area utilities for the native shells.
+ *
+ * Pair with <meta name="viewport" content="…, viewport-fit=cover"> so the
+ * browser exposes the device's safe-area insets. These classes pad content
+ * clear of the status bar / Dynamic Island / home indicator without
+ * hardcoding device sizes. On the desktop shell and plain browsers the insets
+ * are 0, so the classes are inert — safe to apply unconditionally.
+ *
+ * Include in Rails: <%= stylesheet_link_tag "everywhere/native" %>
+ * (Sinatra/Hanami: it's vendored to public/ by `every install`.)
+ */
+
+:root {
+  --everywhere-inset-top: env(safe-area-inset-top, 0px);
+  --everywhere-inset-right: env(safe-area-inset-right, 0px);
+  --everywhere-inset-bottom: env(safe-area-inset-bottom, 0px);
+  --everywhere-inset-left: env(safe-area-inset-left, 0px);
+}
+
+/* Padding utilities — add safe-area room on top of any existing padding. */
+.native-inset {
+  padding-top: calc(var(--everywhere-inset-top) + var(--native-inset-pad, 0px));
+  padding-bottom: calc(var(--everywhere-inset-bottom) + var(--native-inset-pad, 0px));
+}
+.native-inset-top    { padding-top: calc(var(--everywhere-inset-top) + var(--native-inset-pad, 0px)); }
+.native-inset-bottom { padding-bottom: calc(var(--everywhere-inset-bottom) + var(--native-inset-pad, 0px)); }
+.native-inset-left   { padding-left: calc(var(--everywhere-inset-left) + var(--native-inset-pad, 0px)); }
+.native-inset-right  { padding-right: calc(var(--everywhere-inset-right) + var(--native-inset-pad, 0px)); }
+
+/* Margin variants, when padding would fight an existing background. */
+.native-inset-mt { margin-top: var(--everywhere-inset-top); }
+.native-inset-mb { margin-bottom: var(--everywhere-inset-bottom); }
+
+/* A bar pinned to the bottom edge that stays above the home indicator. */
+.native-safe-bottom {
+  padding-bottom: max(var(--everywhere-inset-bottom), var(--native-safe-min, 0.5rem));
+}
+
+/* Fixed/absolute elements anchored near the bottom (toasts, nudges, FABs):
+ * lifts them clear of the home indicator AND anything overlaying the webview
+ * from below — on iOS the floating tab bar contributes to the bottom inset.
+ * --native-bottom-gap is the visual gap above that (default 1rem). */
+.native-bottom {
+  bottom: calc(var(--everywhere-inset-bottom) + var(--native-bottom-gap, 1rem));
+}
+
+/* Full-height element that respects both vertical insets. */
+.native-safe-height {
+  min-height: calc(100dvh - var(--everywhere-inset-top) - var(--everywhere-inset-bottom));
+}
+
+/* ---------------------------------------------------------------------------
+ * Native chrome — styling for the everywhere_fab / everywhere_menu helpers and
+ * the bridge's DOM action-sheet fallback. Set --everywhere-tint in your own CSS
+ * to brand the accent (it defaults to the platform accent color).
+ * ------------------------------------------------------------------------- */
+
+:root {
+  --everywhere-tint: AccentColor;
+}
+
+/* Floating action button (everywhere_fab): fixed, safe-area-aware, above the
+ * home indicator and iOS floating tab bar. A real link/button, so it shows in
+ * a browser too. */
+.everywhere-fab {
+  position: fixed;
+  right: max(var(--everywhere-inset-right), 1rem);
+  bottom: calc(var(--everywhere-inset-bottom) + var(--native-bottom-gap, 1rem));
+  z-index: 1000;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  width: 3.5rem;
+  height: 3.5rem;
+  padding: 0;
+  border: 0;
+  border-radius: 9999px;
+  background: var(--everywhere-fab-bg, var(--everywhere-tint, #1a73e8));
+  color: var(--everywhere-fab-color, #fff);
+  box-shadow: 0 6px 16px rgba(0, 0, 0, 0.28);
+  cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+  transition: transform 0.1s ease, box-shadow 0.1s ease;
+}
+.everywhere-fab:active {
+  transform: scale(0.94);
+  box-shadow: 0 3px 10px rgba(0, 0, 0, 0.3);
+}
+.everywhere-fab-left {
+  right: auto;
+  left: max(var(--everywhere-inset-left), 1rem);
+}
+/* Extended FAB: pill with a visible label beside the icon. */
+.everywhere-fab-extended {
+  width: auto;
+  height: 3.25rem;
+  padding: 0 1.25rem;
+  font: inherit;
+  font-weight: 600;
+}
+.everywhere-fab-icon {
+  width: 1.5rem;
+  height: 1.5rem;
+  flex: none;
+}
+.everywhere-fab-label {
+  white-space: nowrap;
+}
+
+/* In-content action sheet (everywhere_menu) inline fallback: the items stay
+ * hidden until the trigger opens them. In the native shell the bridge shows a
+ * real action sheet instead and these never appear. */
+[data-everywhere-menu-items] {
+  display: none;
+}
+[data-everywhere-menu-open] > [data-everywhere-menu-items],
+[data-everywhere-menu-open] [data-everywhere-menu-items] {
+  display: block;
+}
+
+/* Nav-bar sources (everywhere_nav_button / everywhere_nav_menu) live in the
+ * top bar inside the shell, so hide the in-page copy there — but keep it in a
+ * browser, where there is no native bar. Keyed on the bridge's platform marker
+ * (set only by the mobile web bridge). */
+html[data-bridge-platform] [data-everywhere-nav-button],
+html[data-bridge-platform] [data-everywhere-nav-menu] {
+  display: none !important;
+}
+
+/* DOM action-sheet fallback rendered by the bridge (Everywhere.menu / the
+ * everywhere_menu trigger) when there is no native shell. */
+.everywhere-sheet-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 2000;
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+  padding: 0.75rem;
+  padding-bottom: calc(var(--everywhere-inset-bottom) + 0.75rem);
+  background: rgba(0, 0, 0, 0.4);
+  animation: everywhere-sheet-fade 0.15s ease;
+}
+.everywhere-sheet {
+  width: 100%;
+  max-width: 30rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  border-radius: 0.9rem;
+  overflow: hidden;
+  background: rgba(120, 120, 128, 0.2);
+  animation: everywhere-sheet-rise 0.2s cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+.everywhere-sheet-header {
+  padding: 0.85rem 1rem;
+  text-align: center;
+  background: Canvas;
+  color: color-mix(in srgb, CanvasText 60%, transparent);
+}
+.everywhere-sheet-title {
+  font-weight: 600;
+  color: CanvasText;
+}
+.everywhere-sheet-message {
+  font-size: 0.85rem;
+  margin-top: 0.15rem;
+}
+.everywhere-sheet-item {
+  appearance: none;
+  border: 0;
+  width: 100%;
+  padding: 1rem;
+  font: inherit;
+  font-size: 1.05rem;
+  text-align: center;
+  background: Canvas;
+  color: var(--everywhere-tint, #1a73e8);
+  cursor: pointer;
+}
+.everywhere-sheet-item:active {
+  background: color-mix(in srgb, CanvasText 8%, Canvas);
+}
+.everywhere-sheet-item:disabled {
+  color: color-mix(in srgb, CanvasText 30%, transparent);
+  cursor: default;
+}
+.everywhere-sheet-item-destructive {
+  color: #e5484d;
+}
+.everywhere-sheet-cancel {
+  margin-top: 0.5rem;
+  border-radius: 0.9rem;
+  font-weight: 600;
+  color: CanvasText;
+}
+@keyframes everywhere-sheet-fade {
+  from { opacity: 0; }
+}
+@keyframes everywhere-sheet-rise {
+  from { transform: translateY(1rem); opacity: 0; }
+}

data/bridge/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@rubyeverywhere/bridge",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "One API for browser, desktop, and mobile — the JS half of RubyEverywhere",
   "type": "module",
   "main": "everywhere/bridge.js",
-  "exports": { ".": "./everywhere/bridge.js" },
-  "files": ["everywhere/bridge.js", "README.md", "LICENSE"],
+  "exports": {
+    ".": "./everywhere/bridge.js",
+    "./native.css": "./everywhere/native.css"
+  },
+  "files": ["everywhere/bridge.js", "everywhere/native.css", "README.md", "LICENSE"],
   "sideEffects": false,
   "keywords": ["rubyeverywhere", "tauri", "hotwire", "turbo", "rails", "desktop", "native", "bridge"],
   "homepage": "https://rubyeverywhere.com",

data/lib/everywhere/builders/ios.rb

@@ -0,0 +1,396 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../paths"
+require_relative "../shellout"
+require_relative "../log_filter"
+require_relative "../icon"
+require_relative "../ui"
+
+module Everywhere
+  module Builders
+    # Assembles a Hotwire Native iOS app around an already-deployed (remote
+    # mode) app. No Tebako on iOS — the "build" is: copy the gem's frozen
+    # Xcode template, stamp it (xcconfig + everywhere.json + AppIcon; never
+    # the pbxproj), and hand it to xcodebuild.
+    #
+    # MVP scope is the Simulator (ad-hoc signed, no certs). Device signing,
+    # archive/.ipa export and store distribution hang off this same seam
+    # later — see platform/docs/build-engine.md §5.
+    class Ios
+      # Fixed by the template contract: the target/product is always "App"
+      # (App.app), so build paths never depend on per-app values.
+      SCHEME = "App"
+
+      def initialize(config:, root:, target:, template_dir: nil)
+        @config = config
+        @root = root
+        @target = target
+        @template_dir = template_dir
+      end
+
+      # Build the Simulator .app and copy it into dist_dir. `dev` builds Debug
+      # and relaxes the remote-mode requirement (the dev URL arrives at launch
+      # via SIMCTL_CHILD_EVERYWHERE_DEV_URL, not baked into the bundle).
+      # Returns the path of the built .app.
+      def build!(dist_dir:, dev: false)
+        preflight!(dev: dev)
+        template = @template_dir ? File.expand_path(@template_dir) : Paths.ios_dir!
+        work = stage(template)
+        stamp!(work)
+        configuration = dev ? "Debug" : "Release"
+        xcodebuild!(work, configuration, dist_dir)
+        collect(configuration, dist_dir)
+      end
+
+      private
+
+      def name = @config.name(target: @target)
+      def bundle_id = @config.bundle_id(target: @target)
+
+      def preflight!(dev:)
+        unless dev || @config.remote?
+          UI.die!("iOS apps are remote mode only for now — set remote.url in config/everywhere.yml " \
+                  "(the shell wraps your deployed app; nothing is packaged locally)")
+        end
+        UI.die!("iOS builds need macOS with Xcode installed") unless RUBY_PLATFORM.include?("darwin")
+        return if Shellout.run?("xcrun", "--sdk", "iphonesimulator", "--show-sdk-path", quiet: true)
+
+        UI.die!("no iOS Simulator SDK — install full Xcode (not just the Command Line Tools) " \
+                "and run: xcode-select --switch /Applications/Xcode.app")
+      end
+
+      # Copy the template into the app's persistent work dir. Persistent (not
+      # a tmpdir) so the project path is stable — Xcode's incremental state
+      # stays valid and users can open the stamped project directly.
+      def stage(template)
+        work = Paths.ios_work_dir(bundle_id)
+        FileUtils.mkdir_p(File.dirname(work))
+        FileUtils.rm_rf(work)
+        FileUtils.cp_r(template, work)
+        work
+      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.
+      def stamp!(work)
+        UI.step("stamping shell #{UI.dim("(#{bundle_id} → #{UI.short_path(work)})")}")
+        write_xcconfig(work)
+        File.write(File.join(work, "App", "Resources", "everywhere.json"),
+                   @config.to_shell_json(target: @target))
+        # Same document MobileConfigEndpoint serves live — this baked copy is
+        # the offline/first-launch fallback the shell loads synchronously.
+        File.write(File.join(work, "App", "Resources", "path-configuration.json"),
+                   @config.path_configuration_json("ios"))
+        write_launch_background(work)
+        write_usage_strings(work)
+        write_entitlements(work)
+        write_app_icon(work)
+        write_extensions(work)
+        write_native_packages(work)
+      end
+
+      # Associated Domains entitlement for deep linking (everywhere.yml
+      # deep_linking:). Written only when configured — the default build stays
+      # entitlement-free, so the frozen template still compiles unchanged. The
+      # matching CODE_SIGN_ENTITLEMENTS is set in the xcconfig (write_xcconfig).
+      # applinks: for universal links, webcredentials: to match the association
+      # file's webcredentials section (password autofill / associated credentials).
+      def write_entitlements(work)
+        domains = @config.deep_linking_domains
+        return unless @config.deep_linking? && domains.any?
+
+        values = domains.flat_map { |host| ["applinks:#{host}", "webcredentials:#{host}"] }
+        entries = values.map { |v| "\t\t<string>#{v}</string>" }.join("\n")
+        UI.step("stamping associated domains #{UI.dim("(#{domains.join(", ")})")}")
+        File.write(File.join(work, "App", "App.entitlements"), <<~PLIST)
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+          \t<key>com.apple.developer.associated-domains</key>
+          \t<array>
+          #{entries}
+          \t</array>
+          </dict>
+          </plist>
+        PLIST
+      end
+
+      # Native extensions: the app repo's native/ios/*.swift copied into the
+      # template's Extensions/ folder, plus a generated registry naming what
+      # everywhere.yml declares (native.ios). Extensions/ is a filesystem-
+      # synchronized (buildable) group, so dropping files in IS the
+      # integration — the stamp-only contract holds.
+      def write_extensions(work)
+        errors = @config.native_ios_errors
+        UI.die!("native.ios in config/everywhere.yml:\n#{errors.join("\n")}") unless errors.empty?
+
+        dest = File.join(work, "App", "Extensions")
+        source = File.join(@root, "native", "ios")
+        sources = File.directory?(source) ? Dir.glob(File.join(source, "**", "*.swift")).sort : []
+
+        sources.each do |file|
+          relative = file.delete_prefix("#{source}/")
+          if File.basename(file) == "EverywhereExtensions.swift"
+            UI.die!("native/ios/#{relative}: EverywhereExtensions.swift is generated by " \
+                    "`every build` — declare your types under native.ios in config/everywhere.yml instead")
+          end
+          target_file = File.join(dest, relative)
+          FileUtils.mkdir_p(File.dirname(target_file))
+          FileUtils.cp(file, target_file)
+        end
+
+        if @config.native_ios?
+          UI.step("bundling native extensions #{UI.dim("(#{sources.length} Swift files from native/ios)")}")
+          FileUtils.mkdir_p(dest)
+          File.write(File.join(dest, "EverywhereExtensions.swift"), extensions_registry)
+        elsif sources.any?
+          UI.warn "native/ios has Swift files but everywhere.yml declares nothing under native.ios — " \
+                  "they compile in, but no components/screens/splash are hooked up"
+        end
+      end
+
+      # The generated half of the extension seam (the template ships an empty
+      # default). Declared names are validated as Swift identifiers above, so
+      # interpolation is safe; a declared-but-missing type fails the build
+      # with a Swift error naming it — the honest signal.
+      def extensions_registry
+        components = @config.native_ios_components.map { |type| "#{type}.self" }.join(", ")
+        screens = @config.native_ios_screens
+        splash = @config.native_ios_splash
+
+        screen_body =
+          if screens.empty?
+            "        nil"
+          else
+            ["        switch identifier {",
+             *screens.map { |id, type| "        case #{id.inspect}: return everywhereHost(#{type}(url: url))" },
+             "        default: return nil",
+             "        }"].join("\n")
+          end
+
+        <<~SWIFT
+          // Written by `every build` from config/everywhere.yml (native.ios) — do
+          // not edit; changes belong in native/ios/ and everywhere.yml.
+          import HotwireNative
+          import SwiftUI
+          import UIKit
+
+          enum EverywhereExtensions {
+              static let components: [BridgeComponent.Type] = [#{components}]
+
+              static func screen(for identifier: String, url: URL) -> UIViewController? {
+          #{screen_body}
+              }
+
+              static func splashViewController() -> UIViewController? {
+                  #{splash ? "everywhereHost(#{splash}())" : "nil"}
+              }
+          }
+        SWIFT
+      end
+
+      # Third-party Swift packages → the template's local NativeExtensions
+      # package. The App target already links (a fixed, frozen pbxproj entry)
+      # this local package; we only regenerate its manifest and the re-export
+      # shim, so app-authored native/ios code reaches every pinned product with
+      # `import NativeExtensions` — and the stamp-only contract holds (the
+      # pbxproj is never touched, packages flow through Package.swift instead).
+      def write_native_packages(work)
+        packages = @config.native_ios_packages
+        pkg_dir = File.join(work, "NativeExtensions")
+        sources = File.join(pkg_dir, "Sources", "NativeExtensions")
+        FileUtils.mkdir_p(sources)
+        # A stray Xcode/SPM index cache in the template must not leak into the
+        # app's build (it pins a different dependency graph).
+        FileUtils.rm_rf(File.join(pkg_dir, ".build"))
+
+        File.write(File.join(pkg_dir, "Package.swift"), native_package_manifest(packages))
+        File.write(File.join(sources, "Exports.swift"), native_package_exports(packages))
+
+        return if packages.empty?
+
+        UI.step("pinning native packages #{UI.dim("(#{packages.length} SPM " \
+                "dependenc#{packages.length == 1 ? "y" : "ies"} in NativeExtensions)")}")
+      end
+
+      # The generated NativeExtensions/Package.swift. Every string interpolated
+      # here is validated by Config#native_ios_package_errors (URLs, semver,
+      # module names), and .inspect renders Swift-compatible string literals.
+      def native_package_manifest(packages)
+        dependencies = packages.map do |pkg|
+          ".package(url: #{pkg["url"].inspect}, #{swift_requirement(pkg["requirement"])})"
+        end
+        products = packages.flat_map do |pkg|
+          identity = @config.package_identity(pkg["url"])
+          pkg["products"].map { |name| ".product(name: #{name.inspect}, package: #{identity.inspect})" }
+        end
+
+        <<~SWIFT
+          // swift-tools-version:5.9
+          // Written by `every build` from config/everywhere.yml (native.ios.packages)
+          // — do not edit; changes belong in config/everywhere.yml.
+          import PackageDescription
+
+          let package = Package(
+              name: "NativeExtensions",
+              platforms: [.iOS(.v15)],
+              products: [
+                  .library(name: "NativeExtensions", targets: ["NativeExtensions"])
+              ],
+              dependencies: #{swift_array(dependencies, indent: 8)},
+              targets: [
+                  .target(name: "NativeExtensions", dependencies: #{swift_array(products, indent: 12)})
+              ]
+          )
+        SWIFT
+      end
+
+      # The re-export shim: one `@_exported import` per pinned product, so the
+      # App target's native/ios code sees every module through NativeExtensions.
+      def native_package_exports(packages)
+        header = <<~SWIFT
+          // Written by `every build` from config/everywhere.yml (native.ios.packages)
+          // — re-exports each pinned product so native/ios code reaches it with a
+          // single `import NativeExtensions`. Do not edit.
+        SWIFT
+        modules = packages.flat_map { |pkg| pkg["products"] }.uniq.sort
+        return header if modules.empty?
+
+        "#{header}#{modules.map { |m| "@_exported import #{m}" }.join("\n")}\n"
+      end
+
+      def swift_requirement(requirement)
+        value = requirement["value"].inspect
+        "#{requirement["kind"]}: #{value}"
+      end
+
+      # A Swift array literal: "[]" when empty, else one element per line at
+      # `indent` spaces with the closing bracket de-dented by four.
+      def swift_array(elements, indent:)
+        return "[]" if elements.empty?
+
+        pad = " " * indent
+        "[\n#{elements.map { |element| "#{pad}#{element}" }.join(",\n")}\n#{" " * (indent - 4)}]"
+      end
+
+      # Permission usage strings → Info.plist. iOS crashes a permission
+      # request whose usage-description key is missing, so declarations are
+      # validated here (good strings are mandatory) and stamped with plutil.
+      def write_usage_strings(work)
+        errors = @config.permission_errors("ios")
+        UI.die!("permissions in config/everywhere.yml:\n#{errors.join("\n")}") unless errors.empty?
+
+        plist = File.join(work, "App", "Info.plist")
+        @config.permissions.each do |name, usage|
+          key = Everywhere::Config::IOS_USAGE_KEYS[name] or next
+          Shellout.run!({}, "plutil", "-replace", key, "-string", usage["ios"], plist)
+        end
+      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.
+      def write_launch_background(work)
+        colors = @config.background_color
+        light = Icon.hex_rgb(colors&.fetch("light", nil)) or return
+        dark = Icon.hex_rgb(colors["dark"]) || light
+
+        entry = lambda do |rgb, appearances|
+          { "color" => {
+              "color-space" => "srgb",
+              "components" => {
+                "alpha" => "1.000",
+                "red" => format("0x%02X", rgb[0]),
+                "green" => format("0x%02X", rgb[1]),
+                "blue" => format("0x%02X", rgb[2])
+              }
+            },
+            "idiom" => "universal" }.merge(appearances)
+        end
+
+        require "json"
+        dest = File.join(work, "App", "Assets.xcassets", "LaunchBackground.colorset")
+        FileUtils.mkdir_p(dest)
+        File.write(
+          File.join(dest, "Contents.json"),
+          JSON.pretty_generate(
+            "colors" => [
+              entry.call(light, {}),
+              entry.call(dark, "appearances" => [{ "appearance" => "luminosity", "value" => "dark" }])
+            ],
+            "info" => { "author" => "xcode", "version" => 1 }
+          )
+        )
+      end
+
+      def write_xcconfig(work)
+        # Only point at an entitlements file when deep linking wrote one — an
+        # empty CODE_SIGN_ENTITLEMENTS would break the signing step.
+        entitlements = "CODE_SIGN_ENTITLEMENTS = App/App.entitlements\n" if @config.deep_linking? && @config.deep_linking_domains.any?
+        File.write(File.join(work, "App", "App.xcconfig"), <<~XCCONFIG)
+          // Written by `every build --target #{@target}` — do not edit; changes
+          // belong in config/everywhere.yml.
+          PRODUCT_BUNDLE_IDENTIFIER = #{bundle_id}
+          MARKETING_VERSION = #{@config.version(target: @target)}
+          CURRENT_PROJECT_VERSION = 1
+          INFOPLIST_KEY_CFBundleDisplayName = #{name}
+          DEVELOPMENT_TEAM =
+          #{entitlements}
+        XCCONFIG
+      end
+
+      def write_app_icon(work)
+        source = @config.icon
+        unless source && File.exist?(source)
+          UI.warn "no app icon (set app.icon or add icon.png) — shipping the placeholder"
+          return
+        end
+
+        background = Icon.hex_rgb(@config.background_color&.fetch("light", nil))
+        dest = File.join(work, "App", "Assets.xcassets", "AppIcon.appiconset")
+        return if Icon.write_ios_appiconset(source, dest, background: background)
+
+        UI.warn "couldn't read #{File.basename(source)} — shipping the placeholder icon"
+      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)
+        log = File.join(dist_dir, "ios-build.log")
+        Shellout.run_logged!({},
+                             ["xcodebuild", "build",
+                              "-project", File.join(work, "App.xcodeproj"),
+                              "-scheme", SCHEME,
+                              "-configuration", configuration,
+                              "-destination", "generic/platform=iOS Simulator",
+                              "-derivedDataPath", Paths.ios_derived_data_dir,
+                              "-clonedSourcePackagesDirPath", Paths.ios_packages_dir,
+                              # Ad-hoc sign (no certs needed on the Simulator).
+                              # CODE_SIGNING_ALLOWED=NO ships an UNSIGNED app,
+                              # and securityd rejects its data-protection
+                              # keychain writes (SecAccessControl items, e.g.
+                              # the Face ID login credential) with -34018.
+                              "CODE_SIGN_IDENTITY=-"],
+                             log: log, filter: LogFilter.for(:xcodebuild))
+      end
+
+      # Copy the product out of DerivedData. The ".simulator.app" suffix keeps
+      # it visibly distinct from the desktop dist/<Name>.app (and out of
+      # release.rb's dist/*.app glob).
+      def collect(configuration, dist_dir)
+        built = File.join(Paths.ios_derived_data_dir, "Build", "Products",
+                          "#{configuration}-iphonesimulator", "App.app")
+        UI.die!("xcodebuild reported success but #{built} is missing") unless File.directory?(built)
+
+        dest = File.join(dist_dir, "#{name}.simulator.app")
+        FileUtils.rm_rf(dest)
+        FileUtils.cp_r(built, dest)
+        dest
+      end
+    end
+  end
+end

data/lib/everywhere/cli.rb

@@ -6,6 +6,7 @@ require_relative "framework"
 require_relative "commands/build"
 require_relative "commands/clean"
 require_relative "commands/dev"
+require_relative "commands/logs"
 require_relative "commands/icon"
 require_relative "commands/doctor"
 require_relative "commands/install"
@@ -37,6 +38,7 @@ module Everywhere
     register "doctor",  Commands::Doctor
     register "install", Commands::Install
     register "dev",     Commands::Dev
+    register "logs",    Commands::Logs
     register "build",   Commands::Build
     register "clean",   Commands::Clean
     register "icon",    Commands::Icon

data/lib/everywhere/commands/build.rb

@@ -9,6 +9,7 @@ require_relative "../log_filter"
 require_relative "../png"
 require_relative "../icon"
 require_relative "../paths"
+require_relative "../builders/ios"
 
 module Everywhere
   module Commands
@@ -23,7 +24,7 @@ module Everywhere
     class Build < Dry::CLI::Command
       SHIM = File.expand_path("~/.tebako-shims/clang++")
 
-      desc "Package the app into a double-clickable desktop app (tebako press + shell + .app bundle)"
+      desc "Package the app natively — desktop (tebako press + shell + .app) or iOS (--target ios-arm64)"
 
       option :root,       default: ".",              desc: "App root directory"
       option :output,     default: nil,              desc: "Output binary path (default: dist/<app>)"
@@ -38,6 +39,21 @@ module Everywhere
                app_name: nil, target: "macos-arm64", shell_dir: nil, skip_press: false, **)
         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.
+        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))
+          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")
+        end
+
         # The os of `target` selects any per-platform overrides (bundle id,
         # version, name) — local builds always target the host, macOS today.
         app_name ||= config.name(target: target)