ruby_everywhere 0.2.0 → 0.3.0

data/lib/everywhere/builders/ios.rb

@@ -86,11 +86,39 @@ module Everywhere
                    @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-
@@ -300,6 +328,9 @@ module Everywhere
       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.
@@ -308,6 +339,7 @@ module Everywhere
           CURRENT_PROJECT_VERSION = 1
           INFOPLIST_KEY_CFBundleDisplayName = #{name}
           DEVELOPMENT_TEAM =
+          #{entitlements}
         XCCONFIG
       end
 

data/lib/everywhere/config.rb

@@ -555,6 +555,106 @@ module Everywhere
       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 —
+    # /.well-known/apple-app-site-association and /.well-known/assetlinks.json —
+    # generated from this config (Everywhere::Engine in Rails; MobileConfigEndpoint
+    # for Sinatra/Hanami). The iOS builder stamps the matching Associated Domains
+    # entitlement, and the shell routes an incoming link to its path.
+    #
+    #   deep_linking:
+    #     team_id: ABCDE12345          # derives the iOS app id from bundle_id
+    #     # or set app ids explicitly:
+    #     # apple_app_id: ABCDE12345.com.example.app
+    #     # apple_app_ids: ["ABCDE12345.com.example.app"]
+    #     paths: ["/*"]                # which paths open the app (default: all)
+    #     domains: ["www.example.com"] # extra applinks: domains (remote host is implicit)
+    #     android:
+    #       package: com.example.app
+    #       sha256_cert_fingerprints: ["AB:CD:EF:..."]
+    def deep_linking = @data.fetch("deep_linking", nil) || {}
+
+    # The iOS/tvOS/... app identifiers (TeamID.bundleID) the association file
+    # advertises. Explicit ids win; otherwise team_id + the app's iOS bundle id.
+    def deep_linking_apple_app_ids
+      explicit = Array(deep_linking["apple_app_ids"]) + [deep_linking["apple_app_id"]].compact
+      return explicit.map(&:to_s).uniq unless explicit.empty?
+
+      team = deep_linking["team_id"].to_s.strip
+      team.empty? ? [] : ["#{team}.#{bundle_id(target: "ios")}"]
+    end
+
+    # URL path patterns that open the app. Modern (iOS 14+) component form;
+    # defaults to every path.
+    def deep_linking_paths
+      paths = Array(deep_linking["paths"]).map(&:to_s).reject(&:empty?)
+      paths.empty? ? ["*"] : paths
+    end
+
+    def deep_linking_android = deep_linking["android"].is_a?(Hash) ? deep_linking["android"] : {}
+    def deep_linking_android_package = deep_linking_android["package"]&.to_s
+
+    def deep_linking_android_fingerprints
+      Array(deep_linking_android["sha256_cert_fingerprints"]).map { |f| f.to_s.strip }.reject(&:empty?)
+    end
+
+    def deep_linking_android? = !deep_linking_android_package.to_s.empty? && !deep_linking_android_fingerprints.empty?
+
+    def deep_linking_apple? = !deep_linking_apple_app_ids.empty?
+
+    def deep_linking? = deep_linking_apple? || deep_linking_android?
+
+    # Domains for the iOS Associated Domains entitlement (applinks:<host>) and
+    # the shell's universal-link host allowlist: the remote host plus any extra
+    # `domains:`. Bare hostnames (no scheme, no path).
+    def deep_linking_domains
+      hosts = []
+      if remote_url
+        require "uri"
+        hosts << URI(remote_url).host
+      end
+      hosts += Array(deep_linking["domains"]).map { |d| d.to_s.sub(%r{\Ahttps?://}, "").sub(%r{/.*\z}, "") }
+      hosts.compact.reject(&:empty?).uniq
+    rescue URI::InvalidURIError
+      Array(deep_linking["domains"]).map(&:to_s).reject(&:empty?).uniq
+    end
+
+    # The apple-app-site-association document (a Hash), or nil when no Apple app
+    # ids are configured. `applinks` for universal links; `webcredentials` so
+    # associated-domains password autofill / Face ID credentials work too.
+    def apple_app_site_association
+      ids = deep_linking_apple_app_ids
+      return nil if ids.empty?
+
+      { "applinks" => {
+          "details" => [{ "appIDs" => ids, "components" => deep_linking_paths.map { |p| { "/" => p } } }]
+        },
+        "webcredentials" => { "apps" => ids } }
+    end
+
+    def apple_app_site_association_json
+      require "json"
+      doc = apple_app_site_association or return nil
+      JSON.generate(doc)
+    end
+
+    # The Digital Asset Links document (an Array), or nil without an Android app.
+    def asset_links
+      return nil unless deep_linking_android?
+
+      [{ "relation" => ["delegate_permission/common.handle_all_urls"],
+         "target" => { "namespace" => "android_app",
+                       "package_name" => deep_linking_android_package,
+                       "sha256_cert_fingerprints" => deep_linking_android_fingerprints } }]
+    end
+
+    def asset_links_json
+      require "json"
+      doc = asset_links or return nil
+      JSON.generate(doc)
+    end
+
     # The subset the shell needs, shipped as JSON (env var in dev,
     # Resources/everywhere.json inside a bundled .app). Pass `target:` so the
     # packaged config reflects the platform being built (its bundle id / name).
@@ -574,7 +674,10 @@ module Everywhere
         "lazy_load_tabs" => native_ios_lazy_load_tabs,
         "splash_min_seconds" => native_ios_splash_min_seconds,
         "updates" => updates_shell_hash,
-        "permissions" => (permissions.keys unless permissions.empty?)
+        "permissions" => (permissions.keys unless permissions.empty?),
+        # Hosts the shell treats as its own for incoming universal links, so a
+        # tapped link to any associated domain opens in-app rather than Safari.
+        "universal_link_hosts" => (deep_linking_domains if deep_linking? && !deep_linking_domains.empty?)
       }.compact
     end
 

data/lib/everywhere/engine.rb

@@ -56,6 +56,15 @@ module Everywhere
                                         constraints: { platform_v1: /(?:ios|android)_v1/ },
                                         defaults: { format: "json" },
                                         as: :everywhere_mobile_config
+
+        # Deep-linking association files, generated from everywhere.yml's
+        # deep_linking: section. Served only when configured (404 otherwise, so
+        # an app can draw its own). Apple's file is intentionally extension-less
+        # and must be application/json.
+        get "/.well-known/apple-app-site-association",
+            to: Everywhere::MobileConfigsController.action(:apple_app_site_association)
+        get "/.well-known/assetlinks.json",
+            to: Everywhere::MobileConfigsController.action(:asset_links)
       end
     end
   end

data/lib/everywhere/mobile_config_endpoint.rb

@@ -23,6 +23,8 @@ module Everywhere
   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
@@ -38,6 +40,17 @@ module Everywhere
         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]

data/lib/everywhere/mobile_configs_controller.rb

@@ -34,6 +34,24 @@ module Everywhere
       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).

data/lib/everywhere/native_helper.rb

@@ -140,8 +140,204 @@ module Everywhere
       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

data/lib/everywhere/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Everywhere
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 
   # Version of the @rubyeverywhere/bridge JS this gem ships. bridge/ in the
   # gem IS the npm package (served to Rails apps by Everywhere::Engine,

data/support/mobile/ios/App/AppDelegate.swift

@@ -45,7 +45,8 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
             HapticsComponent.self,
             PermissionsComponent.self,
             BiometricsComponent.self,
-            StorageComponent.self
+            StorageComponent.self,
+            MenuComponent.self
         ] + EverywhereExtensions.components)
 
         // Handles Everywhere.reloadTabs() from the page (a dedicated message

data/support/mobile/ios/App/Bridge/MenuComponent.swift

@@ -0,0 +1,192 @@
+import Foundation
+import HotwireNative
+import UIKit
+import WebKit
+
+/// Bridge component backing `everywhere--menu`: the native chrome the page
+/// declares with `data-everywhere-nav-*` / `data-everywhere-menu` (the
+/// everywhere_nav_button / everywhere_nav_menu / everywhere_menu Rails helpers).
+///
+/// Two events, both replied to by echoing back the tapped item's id so the web
+/// half can `.click()` the element it mirrors — behavior stays defined once, in
+/// the page:
+///   * `navItems` — install left/right `UIBarButtonItem`s on THIS screen's
+///     navigation bar (plain buttons, and pull-down `UIMenu`s for overflow
+///     menus). Native re-replies to the same message on every tap.
+///   * `menu` — present a `UIAlertController` action sheet, replying once with
+///     the selection (or a cancel).
+///
+/// Installs onto `delegate?.destination` — the visitable view controller this
+/// component instance belongs to — so buttons land on the right screen and go
+/// away with it, exactly like the framework's own per-page bridge components.
+final class MenuComponent: BridgeComponent {
+    override nonisolated class var name: String { "everywhere--menu" }
+
+    override func onReceive(message: Message) {
+        switch message.event {
+        case "navItems":
+            handleNavItems(message: message)
+        case "menu":
+            handleMenu(message: message)
+        default:
+            break
+        }
+    }
+
+    // MARK: Private
+
+    private var viewController: UIViewController? {
+        delegate?.destination as? UIViewController
+    }
+
+    // MARK: Nav bar items
+
+    private func handleNavItems(message: Message) {
+        guard let viewController, let data: NavItemsData = message.data() else { return }
+
+        var left: [UIBarButtonItem] = []
+        var right: [UIBarButtonItem] = []
+        for item in data.items {
+            let barButton = barButtonItem(for: item)
+            if item.side == "left" { left.append(barButton) } else { right.append(barButton) }
+        }
+
+        // Right-side items read right-to-left in a nav bar; reverse so the page
+        // order ("Edit", "Share") lands left-to-right as authored.
+        viewController.navigationItem.leftBarButtonItems = left.isEmpty ? nil : left
+        viewController.navigationItem.rightBarButtonItems = right.isEmpty ? nil : right.reversed()
+    }
+
+    private func barButtonItem(for item: NavItem) -> UIBarButtonItem {
+        let image = item.image.flatMap { UIImage(systemName: $0) }
+
+        // A pull-down / overflow menu: children become a native UIMenu, each
+        // echoing its own id back on selection.
+        if let children = item.children, !children.isEmpty {
+            let actions = children.map { child in
+                UIAction(
+                    title: child.title,
+                    image: child.image.flatMap { UIImage(systemName: $0) },
+                    attributes: child.style == "destructive" ? .destructive : []
+                ) { [weak self] _ in
+                    self?.replyTap(id: child.id)
+                }
+            }
+            let menu = UIMenu(title: item.title.isEmpty ? "" : item.title, children: actions)
+            let barButton = UIBarButtonItem(
+                title: item.title.isEmpty ? nil : item.title,
+                image: image ?? UIImage(systemName: "ellipsis.circle"),
+                menu: menu
+            )
+            return barButton
+        }
+
+        // A plain button: echo its id back so the web half clicks the element.
+        let action = UIAction(title: item.title, image: image) { [weak self] _ in
+            self?.replyTap(id: item.id)
+        }
+        let barButton: UIBarButtonItem
+        if let image {
+            barButton = UIBarButtonItem(image: image, primaryAction: action)
+        } else {
+            barButton = UIBarButtonItem(title: item.title, primaryAction: action)
+        }
+        barButton.style = item.style == "done" ? .done : .plain
+        barButton.isEnabled = !(item.disabled ?? false)
+        return barButton
+    }
+
+    private func replyTap(id: String) {
+        reply(to: "navItems", with: NavReply(action: "tap", id: id))
+    }
+
+    // MARK: Action sheet
+
+    private func handleMenu(message: Message) {
+        guard let viewController, let data: MenuData = message.data() else { return }
+
+        let sheet = UIAlertController(title: data.title, message: data.message, preferredStyle: .actionSheet)
+        for item in data.items {
+            let style: UIAlertAction.Style = item.style == "destructive" ? .destructive : .default
+            let action = UIAlertAction(title: item.title, style: style) { [weak self] _ in
+                self?.reply(to: "menu", with: MenuReply(action: "select", id: item.id))
+            }
+            action.isEnabled = !(item.disabled ?? false)
+            sheet.addAction(action)
+        }
+        sheet.addAction(UIAlertAction(title: "Cancel", style: .cancel) { [weak self] _ in
+            self?.reply(to: "menu", with: MenuReply(action: "cancel", id: nil))
+        })
+
+        // iPad / iOS 26 present action sheets as popovers, which need an anchor.
+        // The web sends the trigger's rect in page coordinates; offset by the
+        // web view's top content inset (the nav bar) to reach view coordinates.
+        if let popover = sheet.popoverPresentationController {
+            popover.sourceView = viewController.view
+            if let source = data.source {
+                var y = source.y
+                if let visitable = viewController as? Visitable,
+                   let webView = visitable.visitableView.webView {
+                    y += Double(webView.scrollView.adjustedContentInset.top)
+                }
+                popover.sourceRect = CGRect(x: source.x, y: y, width: source.width, height: source.height)
+            } else {
+                popover.sourceRect = CGRect(x: viewController.view.bounds.midX,
+                                            y: viewController.view.bounds.midY, width: 0, height: 0)
+                popover.permittedArrowDirections = []
+            }
+        }
+
+        viewController.present(sheet, animated: true)
+    }
+}
+
+// MARK: - Message data
+
+private extension MenuComponent {
+    struct NavItemsData: Decodable {
+        let items: [NavItem]
+    }
+
+    struct NavItem: Decodable {
+        let id: String
+        let title: String
+        let image: String?
+        let side: String?
+        let style: String?
+        let disabled: Bool?
+        let children: [MenuItem]?
+    }
+
+    struct MenuData: Decodable {
+        let title: String?
+        let message: String?
+        let items: [MenuItem]
+        let source: Source?
+    }
+
+    struct MenuItem: Decodable {
+        let id: String
+        let title: String
+        let image: String?
+        let style: String?
+        let disabled: Bool?
+    }
+
+    struct Source: Decodable {
+        let x: Double
+        let y: Double
+        let width: Double
+        let height: Double
+    }
+
+    struct NavReply: Encodable {
+        let action: String
+        let id: String
+    }
+
+    struct MenuReply: Encodable {
+        let action: String
+        let id: String?
+    }
+}