@webview-native-ui/engine 1.0.1 → 1.0.2

package/ios/Sources/WebViewNativeUIControls/Overlays/NativeUIOverlayController.swift

@@ -0,0 +1,131 @@
+import UIKit
+import WebKit
+
+/// Intercepts only a prepared blank window. Other requests keep Capacitor's behavior.
+final class NativeUIOverlayController: NSObject, WKUIDelegate {
+    private weak var source: WKWebView?
+    private weak var owner: UIViewController?
+    private let original: WKUIDelegate?
+    private let automaticallyOpensWindows: Bool
+    private var prepared: String?
+    private let event: (String, String) -> Void
+    private var id: String?
+    private var host: NativeUIOverlayHost?
+
+    init(source: WKWebView, owner: UIViewController, event: @escaping (String, String) -> Void) {
+        self.source = source
+        self.owner = owner
+        self.event = event
+        original = source.uiDelegate
+        automaticallyOpensWindows = source.configuration.preferences.javaScriptCanOpenWindowsAutomatically
+        super.init()
+        source.uiDelegate = self
+    }
+
+    // swiftlint:disable:next implicitly_unwrapped_optional
+    override func responds(to selector: Selector!) -> Bool {
+        super.responds(to: selector) || original?.responds(to: selector) == true
+    }
+
+    // swiftlint:disable:next implicitly_unwrapped_optional
+    override func forwardingTarget(for selector: Selector!) -> Any? {
+        original?.responds(to: selector) == true ? original : super.forwardingTarget(for: selector)
+    }
+
+    func prepare(_ id: String) -> Bool {
+        guard prepared == nil, host == nil else { return false }
+        prepared = id
+        source?.configuration.preferences.javaScriptCanOpenWindowsAutomatically = true
+        return true
+    }
+
+    func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration,
+                 for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
+        // WebKit percent-encodes '#' inside about: URLs; compare the decoded form.
+        guard webView === source, navigationAction.sourceFrame.isMainFrame,
+              let prepared, navigationAction.targetFrame == nil,
+              navigationAction.request.url?.absoluteString.removingPercentEncoding == "about:blank#\(prepared)" else {
+            return original?.webView?(webView, createWebViewWith: configuration,
+                                      for: navigationAction, windowFeatures: windowFeatures)
+        }
+        self.prepared = nil
+        source?.configuration.preferences.javaScriptCanOpenWindowsAutomatically = automaticallyOpensWindows
+        id = prepared
+        let host = NativeUIOverlayHost(configuration: configuration, options: nil) { [weak self] action in
+            self?.event(prepared, action)
+        }
+        host.webView.uiDelegate = self
+        host.webView.frame = source?.bounds ?? .zero
+        self.host = host
+        return host.webView
+    }
+
+    // Read ownership without layout or geometry work. Keep the terminal state
+    // until Web closes this connection, so a lost event can be reconciled.
+    var connectionState: [String: String]? {
+        guard let id, let host else { return nil }
+        let state = host.disappeared ? "dismissed" :
+            (host.anchoredVisible && host.viewIfLoaded?.window != nil ? "presented" : "missing")
+        return ["id": id, "state": state]
+    }
+
+    func present(_ id: String, options: [String: Any]?, anchored: (String, NativeUIOverlayHost, @escaping (Bool) -> Void) -> Bool,
+                 completion: @escaping (Bool) -> Void) {
+        guard self.id == id, let host, let owner else { completion(false); return }
+        if host.anchoredVisible && host.viewIfLoaded?.window != nil { completion(true); return }
+        guard owner.presentedViewController == nil else { completion(false); return }
+        host.apply(options)
+        var settled = false
+        var timeout: DispatchWorkItem?
+        let complete: (Bool) -> Void = { presented in
+            guard !settled else { return }
+            settled = true
+            timeout?.cancel()
+            timeout = nil
+            completion(presented)
+        }
+        timeout = DispatchWorkItem { [weak host] in
+            host?.cancelAnchored?()
+            complete(false)
+        }
+        // swiftlint:disable:next force_unwrapping
+        DispatchQueue.main.asyncAfter(deadline: .now() + NativeUIOverlayHost.completionTimeout, execute: timeout!)
+        if host.options?["kind"] as? String == "popover",
+           let anchor = host.options?["anchorId"] as? String,
+           anchored(anchor, host, complete) { return }
+        complete(false)
+    }
+
+    // Keep the WebView alive until JavaScript has restored the adopted nodes and listeners.
+    func dismiss(_ id: String, animated: Bool, completion: @escaping () -> Void) {
+        guard self.id == id, let host else { completion(); return }
+        host.dismissPopover(animated: animated, completion: completion)
+    }
+
+    func close(_ id: String, completion: @escaping () -> Void) {
+        if prepared == id {
+            prepared = nil
+            source?.configuration.preferences.javaScriptCanOpenWindowsAutomatically = automaticallyOpensWindows
+        }
+        guard self.id == id, let host else { completion(); return }
+        let finish = { [self] in
+            host.webView.uiDelegate = nil
+            self.host = nil
+            self.id = nil
+            completion()
+        }
+        host.dismissPopover(animated: false, completion: finish)
+    }
+
+    func stop(completion: @escaping () -> Void) {
+        let finish = { [self] in
+            prepared = nil
+            if let source, source.uiDelegate === self {
+                source.uiDelegate = original
+                source.configuration.preferences.javaScriptCanOpenWindowsAutomatically = automaticallyOpensWindows
+            }
+            completion()
+        }
+        if let id { close(id, completion: finish) } else { finish() }
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Overlays/NativeUIOverlayHost.swift

@@ -0,0 +1,85 @@
+import UIKit
+import WebKit
+
+/// Hosts only the live content of a Vertical Bars popover.
+final class NativeUIOverlayHost: UIViewController {
+    let webView: WKWebView
+    private(set) var options: [String: Any]?
+    let event: (String) -> Void
+    // Settle native presentation before the JS bridge's five-second deadline.
+    static let completionTimeout: TimeInterval = 4
+    var dismissAnchored: (() -> Void)?
+    var cancelAnchored: (() -> Void)?
+    var anchoredVisible = false
+    var disappeared = false
+    private var dismissalCompletions: [() -> Void]?
+    private var dismissalTimeout: DispatchWorkItem?
+
+    func presentationDidDisappear() {
+        // SwiftUI may disappear before (or without) updating isPresented.
+        // Notify through this retained host, not the model's already-cleared host.
+        // Web-initiated dismissal already owns Ionic's lifecycle; do not echo it.
+        let nativeDismissal = anchoredVisible && dismissalCompletions == nil
+        if nativeDismissal { disappeared = true }
+        completeDismissal()
+        if nativeDismissal { event("dismiss") }
+    }
+
+    func completeDismissal() {
+        dismissalTimeout?.cancel()
+        dismissalTimeout = nil
+        anchoredVisible = false
+        let completions = dismissalCompletions ?? []
+        dismissalCompletions = nil
+        completions.forEach { $0() }
+    }
+
+    // Dismiss, close and stop may overlap while SwiftUI is still disappearing.
+    // Start dismissal once and deliver its completion to every waiting caller.
+    func dismissPopover(animated: Bool, completion: @escaping () -> Void) {
+        if dismissalCompletions != nil {
+            dismissalCompletions?.append(completion)
+            return
+        }
+        dismissalCompletions = [completion]
+        let finish = { [self] in completeDismissal() }
+        let timeout = DispatchWorkItem { [weak self] in
+            guard let self, self.dismissalCompletions != nil else { return }
+            // Remove the owning rail if SwiftUI never reports disappearance.
+            // Its detach path settles waiters before any replacement can attach.
+            self.cancelAnchored?()
+            self.completeDismissal()
+        }
+        dismissalTimeout = timeout
+        DispatchQueue.main.asyncAfter(deadline: .now() + Self.completionTimeout, execute: timeout)
+        if let dismissAnchored {
+            if anchoredVisible { dismissAnchored() } else { dismissAnchored(); finish() }
+        } else if presentingViewController != nil {
+            dismiss(animated: animated, completion: finish)
+        } else { finish() }
+    }
+
+    init(configuration: WKWebViewConfiguration, options: [String: Any]?, event: @escaping (String) -> Void) {
+        webView = WKWebView(frame: .zero, configuration: configuration)
+        self.event = event
+        super.init(nibName: nil, bundle: nil)
+        apply(options)
+    }
+    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
+
+    func apply(_ options: [String: Any]?) {
+        guard let options else { return }
+        self.options = options
+        preferredContentSize = CGSize(width: options["width"] as? Double ?? 280, height: options["height"] as? Double ?? 200)
+        overrideUserInterfaceStyle = options["dark"] as? Bool == true ? .dark : .light
+    }
+
+    override func loadView() {
+        webView.isOpaque = false
+        webView.backgroundColor = .clear
+        webView.scrollView.backgroundColor = .clear
+        webView.scrollView.contentInsetAdjustmentBehavior = .never
+        view = webView
+        view.accessibilityViewIsModal = true
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Shared/NativeUIControlRendering.swift

@@ -0,0 +1,21 @@
+import UIKit
+
+final class NativeUIControlRendering {
+    private var images: [String: UIImage] = [:]
+    func clear() { images.removeAll() }
+
+    func image(_ item: NativeUIItemContent) -> UIImage? {
+        guard let data = item.icon, let width = item.iconWidth else { return nil }
+        let template = item.iconTemplate == true
+        let key = "\(width):" + (template ? "template:" : "original:") + data
+        if let cached = images[key] { return cached }
+        guard let result = NativeUIRendering.image(NativeUIImage(data: data, width: width, height: item.iconHeight ?? width, template: template)) else { return nil }
+        if images.count >= 128 { images.removeAll() }
+        images[key] = result
+        return result
+    }
+
+    func color(_ css: String?) -> UIColor {
+        NativeUIRendering.color(css)
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Shared/NativeUICoveredSnapshots.swift

@@ -0,0 +1,14 @@
+import SwiftUI
+import WebViewNativeUIEngine
+typealias NativeUICoveredSnapshots = WebViewNativeUIEngine.NativeUICoveredSnapshots
+
+/// A public, non-interactive layout anchor for content hosted inside the system tab accessory.
+struct NativeUICoveredSnapshotAnchor: UIViewRepresentable {
+    let id: String
+    func makeUIView(context: Context) -> UIView {
+        let view = UIView()
+        view.isUserInteractionEnabled = false
+        return view
+    }
+    func updateUIView(_ view: UIView, context: Context) { view.accessibilityIdentifier = id }
+}

package/ios/Sources/WebViewNativeUIControls/Shared/NativeUICrossfade.swift

@@ -0,0 +1,35 @@
+import UIKit
+
+@MainActor enum NativeUICrossfade {
+    static func duration(_ milliseconds: Double?) -> TimeInterval {
+        UIAccessibility.isReduceMotionEnabled ? 0 : (milliseconds ?? 0) / 1000
+    }
+
+    static func enter(_ view: UIView, duration: TimeInterval) {
+        guard duration > 0 else { return }
+        view.alpha = 0
+        UIView.animate(withDuration: duration, delay: 0, options: [.curveEaseInOut, .allowUserInteraction]) {
+            view.alpha = 1
+        }
+    }
+
+    static func retire(_ view: UIView, duration: TimeInterval) {
+        // The outgoing copy is visual only: it cannot keep accepting actions or
+        // VoiceOver focus once the Web source has been restored.
+        if duration > 0, let host = view.superview, let parent = host.superview,
+           !view.isHidden, !host.isHidden, let copy = view.snapshotView(afterScreenUpdates: false) {
+            copy.frame = host.convert(view.frame, to: parent)
+            copy.alpha = CGFloat(view.layer.presentation()?.opacity ?? Float(view.alpha))
+            copy.isUserInteractionEnabled = false
+            copy.isAccessibilityElement = false
+            copy.accessibilityElementsHidden = true
+            parent.insertSubview(copy, aboveSubview: host)
+            UIView.animate(withDuration: duration, delay: 0, options: [.curveEaseInOut]) {
+                copy.alpha = 0
+            } completion: { _ in
+                copy.removeFromSuperview()
+            }
+        }
+        view.removeFromSuperview()
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Shared/NativeUIHost.swift

@@ -0,0 +1,8 @@
+import UIKit
+
+final class NativeUIHost: UIView {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        let hit = super.hitTest(point, with: event)
+        return hit === self ? nil : hit
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Shared/NativeUIScrollTracker.swift

@@ -0,0 +1,2 @@
+import WebViewNativeUIEngine
+typealias NativeUIScrollPlacement = WebViewNativeUIEngine.NativeUIScrollPlacement

package/ios/Sources/WebViewNativeUIControls/Shared/NativeUISnapshot.swift

@@ -0,0 +1,206 @@
+import Foundation
+import CoreGraphics
+
+// Standard renderer names are independent of DOM tags and Web frameworks.
+enum NativeUIComponent: String, Decodable {
+    case `extension`
+    case button, buttons = "button-group"
+    case backButton = "back-button", menuButton = "menu-button"
+    case tabBar = "tab-bar", segment, fab = "floating-action-button"
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        let value = try container.decode(String.self)
+        // Accept previous clients during native/Web bundle upgrades.
+        let legacy: [String: NativeUIComponent] = [
+            "ion-button": .button, "ion-buttons": .buttons,
+            "ion-back-button": .backButton, "ion-menu-button": .menuButton,
+            "ion-tab-bar": .tabBar, "ion-segment": .segment, "ion-fab": .fab
+        ]
+        guard let kind = NativeUIComponent(rawValue: value) ?? legacy[value] else {
+            throw DecodingError.dataCorruptedError(in: container, debugDescription: "Unknown native control kind")
+        }
+        self = kind
+    }
+}
+
+struct NativeUIToolbarTransitionSnapshot: Decodable {
+    let id: Int
+    let sourceIds: [String]
+    let destination: [NativeUIControl]
+    var isValid: Bool {
+        id > 0 && sourceIds.count <= 100 && Set(sourceIds).count == sourceIds.count && destination.count <= 100 &&
+            Set(destination.map(\.id)).count == destination.count && destination.allSatisfy {
+                $0.isValid && $0.placement == nil && (NativeUIButton.kinds + [.buttons]).contains($0.kind)
+            }
+    }
+}
+
+struct NativeUIModalAnimation: Decodable {
+    let id: Int
+    let startedAt: Double
+    let duration: Double
+    let fromY: Double
+    let opacity: Double
+    let easing: [Double]
+    var isValid: Bool {
+        id > 0 && [startedAt, duration, fromY, opacity].allSatisfy(\.isFinite) &&
+            duration > 0 && duration <= 60_000 && opacity >= 0 && opacity <= 1 &&
+            easing.count == 4 && easing.allSatisfy(\.isFinite) &&
+            (0...1).contains(easing[0]) && (0...1).contains(easing[2])
+    }
+}
+
+struct NativeUISnapshot: Decodable {
+    let revision: Int
+    var coveredSnapshotToken: String?
+    let transitionDuration: Double?
+    let toolbarTransition: NativeUIToolbarTransitionSnapshot?
+    let viewportWidth: Double
+    let verticalBarFrame: NativeUIFrame?
+    let modalAnimation: NativeUIModalAnimation?
+    let verticalBarEdge: String?
+    let verticalBarNavigation: [String]?
+    let verticalBarNavigationPhase: String?
+    let controls: [NativeUIControl]
+
+    var isValid: Bool {
+        (toolbarTransition.map { $0.isValid && Set($0.sourceIds).isSubset(of: Set(controls.map(\.id))) } ?? true) &&
+            revision >= 0 && (transitionDuration.map { $0.isFinite && $0 >= 0 && $0 <= 500 } ?? true) && viewportWidth.isFinite && viewportWidth > 0 && controls.count <= 100 &&
+            (verticalBarNavigationPhase == nil || verticalBarNavigationPhase == "tracking" || verticalBarNavigationPhase == "settling") &&
+            (verticalBarNavigation.map { Set($0).count == $0.count && $0.allSatisfy { !$0.isEmpty } } ?? true) &&
+            (verticalBarFrame.map { $0.isValid } ?? true) &&
+            (modalAnimation.map { $0.isValid && verticalBarFrame != nil } ?? true) &&
+            (verticalBarEdge == nil || verticalBarEdge == "left" || verticalBarEdge == "right") &&
+            Set(controls.map(\.id)).count == controls.count && controls.allSatisfy(\.isValid)
+    }
+}
+
+// Frames and content decode from the same flat wire object. Keeping them separate
+// lets FABs compare artwork without treating movement or visibility as new content.
+struct NativeUIFrame: Decodable, Equatable {
+    let x: Double
+    let y: Double
+    let width: Double
+    let height: Double
+    var rect: CGRect { CGRect(x: x, y: y, width: width, height: height) }
+    var isValid: Bool { [x, y, width, height].allSatisfy(\.isFinite) && width > 0 && height > 0 }
+}
+
+struct NativeUIControl: Decodable, Equatable {
+    enum Placement: String, Decodable { case verticalBars = "vertical-bars" }
+    enum ToolbarSlot: String, Decodable { case start, end }
+    let id: String
+    let kind: NativeUIComponent
+    let placement: Placement?
+    let toolbarSlot: ToolbarSlot?
+    let transitionId: String?
+    let frame: NativeUIFrame
+    let items: [NativeUIItem]
+    let dark: Bool
+    let rtl: Bool
+    let tabTint: String?
+    let tabBarAnchor: NativeUITabBar.Anchor?
+    let search: NativeUISearch?
+    let extensionContent: NativeUIExtensionContent?
+    let scroll: NativeUIScrollPlacement?
+
+    private enum CodingKeys: String, CodingKey {
+        case id, kind, placement, toolbarSlot, transitionId, items, dark, rtl, tabBarAnchor, tabTint, search
+        case scroll
+        case extensionContent = "extension"
+    }
+
+    init(from decoder: Decoder) throws {
+        let values = try decoder.container(keyedBy: CodingKeys.self)
+        id = try values.decode(String.self, forKey: .id)
+        kind = try values.decode(NativeUIComponent.self, forKey: .kind)
+        placement = try values.decodeIfPresent(Placement.self, forKey: .placement)
+        toolbarSlot = try values.decodeIfPresent(ToolbarSlot.self, forKey: .toolbarSlot)
+        transitionId = try values.decodeIfPresent(String.self, forKey: .transitionId)
+        frame = try NativeUIFrame(from: decoder)
+        items = try values.decode([NativeUIItem].self, forKey: .items)
+        dark = try values.decode(Bool.self, forKey: .dark)
+        rtl = try values.decode(Bool.self, forKey: .rtl)
+        tabTint = try values.decodeIfPresent(String.self, forKey: .tabTint)
+        tabBarAnchor = try values.decodeIfPresent(NativeUITabBar.Anchor.self, forKey: .tabBarAnchor)
+        search = try values.decodeIfPresent(NativeUISearch.self, forKey: .search)
+        scroll = try values.decodeIfPresent(NativeUIScrollPlacement.self, forKey: .scroll)
+        extensionContent = try values.decodeIfPresent(NativeUIExtensionContent.self, forKey: .extensionContent)
+    }
+
+    var isValid: Bool {
+        if kind == .extension {
+            return !id.isEmpty && frame.isValid && items.isEmpty && placement == nil && toolbarSlot == nil &&
+                search == nil && tabBarAnchor == nil && extensionContent?.isValid == true &&
+                (scroll.map { $0.isValid && extensionContent?.tabBarId == nil } ?? true)
+        }
+        return scroll == nil && extensionContent == nil && NativeUIComponents.supported.contains(kind) && !id.isEmpty && frame.isValid && !items.isEmpty && items.count <= 30 &&
+            (!NativeUIButton.kinds.contains(kind) || items.count == 1) &&
+            (toolbarSlot == nil || (placement == .verticalBars && [.button, .buttons, .menuButton].contains(kind))) &&
+            Set(items.map(\.id)).count == items.count && items.allSatisfy(\.isValid) &&
+            (tabBarAnchor.map { kind == .tabBar && $0.isValid } ?? true) &&
+            (search.map { kind == .tabBar && $0.isValid } ?? true)
+    }
+}
+
+struct NativeUIItem: Decodable, Equatable {
+    let frame: NativeUIFrame
+    let content: NativeUIItemContent
+    let visible: Bool?
+    var id: String { content.id }
+
+    private enum CodingKeys: String, CodingKey { case visible }
+
+    init(from decoder: Decoder) throws {
+        frame = try NativeUIFrame(from: decoder)
+        content = try NativeUIItemContent(from: decoder)
+        visible = try decoder.container(keyedBy: CodingKeys.self).decodeIfPresent(Bool.self, forKey: .visible)
+    }
+
+    var isValid: Bool { frame.isValid && content.isValid }
+}
+
+struct NativeUIBadge: Decodable, Equatable {
+    let value: String
+    let color: String
+    let textColor: String
+}
+
+struct NativeUIItemContent: Decodable, Equatable {
+    enum IconPosition: String, Decodable { case leading, trailing, top }
+    enum ButtonFill: String, Decodable { case clear, solid, outline }
+    let id: String
+    let transitionId: String?
+    var label: String
+    let accessibilityLabel: String
+    let disabled: Bool
+    let selected: Bool
+    let fontSize: Double
+    let fontWeight: Double
+    let color: String
+    let buttonFill: ButtonFill?
+    let backgroundColor: String?
+    let borderColor: String?
+    let borderWidth: CGFloat?
+    let badge: NativeUIBadge?
+    var icon: String?
+    var iconWidth: Double?
+    var iconHeight: Double?
+    let iconPosition: IconPosition?
+    let imagePadding: Double?
+    let contentInsetLeading: Double?
+    let contentInsetTrailing: Double?
+    let iconTemplate: Bool?
+    let closeIcon: String?
+    let closeIconWidth: Double?
+    let closeIconHeight: Double?
+    let iconTransition: Double?
+
+    var isValid: Bool {
+        !id.isEmpty && fontSize.isFinite && fontSize >= 0 && fontWeight.isFinite &&
+            [iconWidth, iconHeight, closeIconWidth, closeIconHeight].compactMap { $0 }.allSatisfy { $0.isFinite && $0 > 0 } &&
+            [imagePadding, contentInsetLeading, contentInsetTrailing].compactMap { $0 }.allSatisfy { $0.isFinite } &&
+            (iconTransition.map { $0.isFinite && $0 >= 0 } ?? true)
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Shared/NativeUIVerticalBarsGeometry.swift

@@ -0,0 +1,93 @@
+import UIKit
+
+/// Reads public accessibility geometry after the system has laid out its rail.
+/// IDs bind measurements to current DOM controls without private class names.
+/// Compact square ancestors approximate the system button surface; this remains
+/// a layout heuristic and invalid measurements fall back to Web CSS.
+enum NativeUIVerticalBarsGeometry {
+    static func measure(in root: UIView, relativeTo webView: UIView, ids: Set<String>) -> [String: CGRect] {
+        guard let window = root.window, window === webView.window else { return [:] }
+        root.layoutIfNeeded()
+        var result: [String: CGRect] = [:]
+        var visited = Set<ObjectIdentifier>()
+        func visit(_ object: NSObject, depth: Int) {
+            guard depth < 40, visited.count < 2000, visited.insert(ObjectIdentifier(object)).inserted else { return }
+            if let id = (object as? UIView)?.accessibilityIdentifier ?? (object as? UIAccessibilityElement)?.accessibilityIdentifier, ids.contains(id) {
+                let screenFrame = object.accessibilityFrame
+                let frame = (object as? UIView).map { view -> CGRect in
+                    var surface = view
+                    var ancestor = view.superview
+                    while let current = ancestor, current !== root,
+                          current.bounds.width < 100, current.bounds.height < 100 {
+                        if current.bounds.width >= max(surface.bounds.width, 1), current.bounds.height >= max(surface.bounds.height, 1),
+                           abs(current.bounds.width - current.bounds.height) < 1 { surface = current }
+                        ancestor = current.superview
+                    }
+                    return surface.convert(surface.bounds, to: webView)
+                } ?? webView.convert(screenFrame, from: window.screen.coordinateSpace)
+                if !frame.isNull, !frame.isInfinite, frame.width > 0, frame.height > 0,
+                   webView.bounds.intersects(frame), frame.width < webView.bounds.width * 0.75 {
+                    // UIKit may expose a label and its larger button with the same ID.
+                    // swiftlint:disable:next force_unwrapping
+                    if result[id] == nil || frame.width * frame.height > result[id]!.width * result[id]!.height {
+                        result[id] = frame
+                    }
+                }
+            }
+            if let view = object as? UIView { view.subviews.forEach { visit($0, depth: depth + 1) } }
+            if object === webView { return }
+            if let elements = object.accessibilityElements {
+                elements.compactMap { $0 as? NSObject }.forEach { visit($0, depth: depth + 1) }
+            } else {
+                let count = object.accessibilityElementCount()
+                if count > 0 && count < 200 {
+                    for index in 0..<count {
+                        if let element = object.accessibilityElement(at: index) as? NSObject { visit(element, depth: depth + 1) }
+                    }
+                }
+            }
+        }
+        visit(root, depth: 0)
+        return result
+    }
+    /// When AX is lazy, bind the visible UIKit controls by the same start/end
+    /// ordering used by our toolbar. A count mismatch declines the measurement.
+    static func componentFrames(in root: UIView, relativeTo webView: UIView, controls: [NativeUIControl]) -> [String: CGRect] {
+        guard controls.allSatisfy({ [.button, .buttons, .backButton, .menuButton, .tabBar].contains($0.kind) }),
+              controls.allSatisfy({ $0.search == nil }) else { return [:] }
+        let ordered = controls.filter { $0.kind != .tabBar && ($0.toolbarSlot == .start || $0.kind == .backButton) }
+            + controls.filter { $0.kind != .tabBar && $0.toolbarSlot != .start && $0.kind != .backButton }
+            + controls.filter { $0.kind == .tabBar }
+        var frames: [CGRect] = []
+        func visit(_ view: UIView) {
+            guard !view.isHidden, view.alpha > 0.05 else { return }
+            if view is UIControl {
+                var surface = view
+                var ancestor = view.superview
+                while let current = ancestor, current !== root, current.bounds.width < 100, current.bounds.height < 100 {
+                    if current.bounds.width >= surface.bounds.width, current.bounds.height >= surface.bounds.height,
+                       abs(current.bounds.width - current.bounds.height) < 1 { surface = current }
+                    ancestor = current.superview
+                }
+                let frame = surface.convert(surface.bounds, to: webView)
+                if frame.width > 0, frame.height > 0, frame.width < 100, frame.height < 100,
+                   webView.bounds.contains(frame), !frames.contains(frame) { frames.append(frame) }
+                return
+            }
+            view.subviews.forEach(visit)
+        }
+        visit(root)
+        guard frames.count == ordered.reduce(0, { $0 + $1.items.count }) else { return [:] }
+        frames.sort { $0.midY < $1.midY }
+        guard let first = frames.first, frames.allSatisfy({ abs($0.midX - first.midX) < 2 }),
+              zip(frames, frames.dropFirst()).allSatisfy({ $0.midY < $1.midY }) else { return [:] }
+        var result: [String: CGRect] = [:]
+        var offset = 0
+        for control in ordered {
+            result[control.id] = frames[offset..<(offset + control.items.count)].reduce(CGRect.null) { $0.union($1) }
+            offset += control.items.count
+        }
+        return result
+    }
+
+}

package/ios/Sources/WebViewNativeUIEngine/CoveredSnapshots.swift

@@ -60,7 +60,7 @@ public final class NativeUICoveredSnapshots {
             complete(["shown": restore(in: webView, token: token, frames: destination)])
         case "painted", "restored":
             retireCopy(token, entry: request["action"] as? String == "painted")
-            complete([:])
+            complete(request["action"] as? String == "painted" ? ["shown": captures[token] != nil] : [:])
         case "release": release(token); complete([:])
         case "reset": reset(); complete([:])
         default: complete([:])
@@ -257,7 +257,7 @@ public final class NativeUICoveredSnapshots {
         // A lost cleanup message must never leave an obsolete cover on live UI.
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
             guard self?.restoration?.views.first === views.first else { return }
-            self?.clearRestoration()
+            if entry { self?.release(token) } else { self?.clearRestoration() }
         }
         return true
     }

package/ios/Sources/WebViewNativeUIEngine/NativeUIProjection.swift

@@ -320,7 +320,7 @@ public final class NativeUIProjection: NSObject, WKScriptMessageHandler {
                 }
             }
             complete([:])
-        case "painted": snapshots.retireCopy(token); complete([:])
+        case "painted": snapshots.retireCopy(token); complete(["shown": !snapshots.identifiers(for: token).isEmpty])
         case "restored": snapshots.retireCopy(token, entry: false); complete([:])
         case "release": snapshots.release(token); captured.removeValue(forKey: token); anchors.removeValue(forKey: token); complete([:])
         case "reset": snapshots.reset(); captured.removeAll(); anchors.removeAll(); complete([:])