@rdlabo/capacitor-native-ui 0.0.0-stage → 2.0.0-1

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

@@ -0,0 +1,119 @@
+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
+    }
+
+    override func responds(to selector: Selector!) -> Bool {
+        super.responds(to: selector) || original?.responds(to: selector) == true
+    }
+
+    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
+    }
+
+    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,
+              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)
+        }
+        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/NativeUIPlugin/Overlays/NativeUIOverlayHost.swift

@@ -0,0 +1,75 @@
+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
+    private var dismissalCompletions: [() -> Void]?
+    private var dismissalTimeout: DispatchWorkItem?
+
+    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/NativeUIPlugin/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/NativeUIPlugin/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/NativeUIPlugin/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/NativeUIPlugin/Shared/NativeUISnapshot.swift

@@ -0,0 +1,161 @@
+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 NativeUISnapshot: Decodable {
+    let revision: Int
+    let transitionDuration: Double?
+    let viewportWidth: Double
+    let verticalBarFrame: NativeUIFrame?
+    let verticalBarEdge: String?
+    let controls: [NativeUIControl]
+
+    var isValid: Bool {
+        revision >= 0 && (transitionDuration.map { $0.isFinite && $0 >= 0 && $0 <= 500 } ?? true) && viewportWidth.isFinite && viewportWidth > 0 && controls.count <= 100 &&
+        (verticalBarFrame.map { $0.isValid } ?? 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 frame: NativeUIFrame
+    let items: [NativeUIItem]
+    let dark: Bool
+    let rtl: Bool
+    let tabBarAnchor: NativeUITabBar.Anchor?
+    let search: NativeUISearch?
+    let extensionContent: NativeUIExtensionContent?
+
+    private enum CodingKeys: String, CodingKey {
+        case id, kind, placement, toolbarSlot, items, dark, rtl, tabBarAnchor, search
+        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)
+        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)
+        tabBarAnchor = try values.decodeIfPresent(NativeUITabBar.Anchor.self, forKey: .tabBarAnchor)
+        search = try values.decodeIfPresent(NativeUISearch.self, forKey: .search)
+        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
+        }
+        return 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
+    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/NativeUIPlugin/Shared/NativeUIVerticalBarsGeometry.swift

@@ -0,0 +1,52 @@
+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.
+                    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
+    }
+}

package/ios/Tests/NativeUIPluginTests/NativeUIExtensionTests.swift

@@ -0,0 +1,165 @@
+import XCTest
+import SwiftUI
+import WebKit
+@testable import NativeUIPlugin
+
+final class NativeUIExtensionTests: XCTestCase {
+    struct Props: Decodable { let title: String }
+
+    private func context(width: Double = 120, dark: Bool = false, accessory: Bool = false) throws -> NativeUIContext {
+        var content: [String: Any] = ["name": "fixture", "props": "{}", "actions": [:]]
+        if accessory { content["tabBarId"] = "tabs" }
+        let json: [String: Any] = ["id": "source", "kind": "extension", "x": -4, "y": 30,
+            "width": width, "height": 44, "dark": dark, "rtl": dark, "items": [], "extension": content]
+        let node = try JSONDecoder().decode(NativeUIControl.self, from: JSONSerialization.data(withJSONObject: json))
+        return NativeUIContext(node: node, viewportWidth: 600, pointsPerCSSPixel: 0.5)
+    }
+
+    @MainActor func testContextUpdatesGeometryEnvironmentAndAccessoryPlacement() throws {
+        let name = UUID().uuidString
+        var received: [NativeUIContext] = []
+        try NativeUI.register(name) { (props: Props, actions: NativeUIActions, context: NativeUIContext) in
+            received.append(context)
+            XCTAssertTrue(actions.isAvailable("open"))
+            XCTAssertFalse(actions.isAvailable("disabled"))
+            return Text(props.title)
+        }
+        let data = NativeUIExtensionContent(name: name, props: "{\"title\":\"Ready\"}", actions: ["open": "button"], tabBarId: nil)
+        let actions = NativeUIActions(availableNames: ["open"]) { _ in }
+        _ = try NativeUI.content(data, actions: actions, context: context())
+        _ = try NativeUI.content(data, actions: actions, context: context(width: 220, dark: true, accessory: true))
+        XCTAssertEqual(received.count, 2)
+        XCTAssertEqual(received[0].sourceID, "source")
+        XCTAssertEqual(received[0].sourceFrame, CGRect(x: -4, y: 30, width: 120, height: 44))
+        XCTAssertEqual(received[0].sourceFrameInWebView, CGRect(x: -2, y: 15, width: 60, height: 22))
+        XCTAssertEqual(received[0].placement, .element)
+        XCTAssertEqual(received[0].colorScheme, .light)
+        XCTAssertEqual(received[0].layoutDirection, .leftToRight)
+        XCTAssertEqual(received[1].sourceFrameInWebView.width, 110)
+        XCTAssertEqual(received[1].viewportWidth, 600)
+        XCTAssertEqual(received[1].pointsPerCSSPixel, 0.5)
+        XCTAssertEqual(received[1].placement, .tabAccessory)
+        XCTAssertEqual(received[1].colorScheme, .dark)
+        XCTAssertEqual(received[1].layoutDirection, .rightToLeft)
+        XCTAssertThrowsError(try NativeUI.register(name) { (_: Props, _: NativeUIActions) in Text("Duplicate") })
+    }
+
+    @MainActor func testPublicRenderingSharesArtworkAndComputedColors() throws {
+        let image = UIGraphicsImageRenderer(size: CGSize(width: 16, height: 16)).image { context in
+            UIColor.red.setFill()
+            context.fill(CGRect(x: 0, y: 0, width: 16, height: 16))
+        }
+        let data = try XCTUnwrap(image.pngData()).base64EncodedString()
+        let artwork = NativeUIImage(data: data, width: 16, height: 16, template: true)
+        let decoded = try XCTUnwrap(NativeUIRendering.image(artwork))
+        XCTAssertEqual(decoded.size, CGSize(width: 16, height: 16))
+        XCTAssertEqual(decoded.renderingMode, .alwaysTemplate)
+        let legacy: [String: Any] = ["id": "icon", "label": "Icon", "accessibilityLabel": "Icon",
+            "disabled": false, "selected": false, "fontSize": 16, "fontWeight": 400,
+            "color": "rgb(0, 0, 0)", "icon": data, "iconWidth": 16]
+        let item = try JSONDecoder().decode(NativeUIItemContent.self, from: JSONSerialization.data(withJSONObject: legacy))
+        XCTAssertEqual(try XCTUnwrap(NativeUIControlRendering().image(item)).size, CGSize(width: 16, height: 16))
+        XCTAssertNil(NativeUIRendering.image(NativeUIImage(data: "invalid", width: 16, height: 16)))
+        XCTAssertNil(NativeUIRendering.image(NativeUIImage(data: data, width: .nan, height: 16)))
+        let color = NativeUIRendering.color("rgba(255, 0, 128, 0.5)")
+        var red: CGFloat = 0, green: CGFloat = 0, blue: CGFloat = 0, alpha: CGFloat = 0
+        XCTAssertTrue(color.getRed(&red, green: &green, blue: &blue, alpha: &alpha))
+        XCTAssertEqual(red, 1)
+        XCTAssertEqual(blue, 128.0 / 255.0, accuracy: 0.001)
+        XCTAssertEqual(alpha, 0.5)
+        XCTAssertEqual(NativeUIRendering.color("currentColor", fallback: .red), .red)
+        XCTAssertEqual(NativeUIControlRendering().color("rgba(255, 0, 128, 0.5)"), color)
+    }
+
+    @MainActor func testLocalRegistrationDecodesPropsAndRejectsDuplicateAndMissingRenderers() throws {
+        let name = UUID().uuidString
+        var title = ""
+        try NativeUI.register(name) { (props: Props, _: NativeUIActions) in
+            title = props.title
+            return Text(props.title)
+        }
+        let actions = NativeUIActions { _ in }
+        let context = try context()
+        _ = try NativeUI.content(NativeUIExtensionContent(name: name, props: "{\"title\":\"Local View\"}", actions: [:], tabBarId: nil), actions: actions, context: context)
+        XCTAssertEqual(title, "Local View")
+        XCTAssertThrowsError(try NativeUI.register(name) { (props: Props, _: NativeUIActions) in Text(props.title) })
+        XCTAssertThrowsError(try NativeUI.content(NativeUIExtensionContent(name: name, props: "{}", actions: [:], tabBarId: nil), actions: actions, context: context))
+        XCTAssertThrowsError(try NativeUI.content(NativeUIExtensionContent(name: "missing", props: "{}", actions: [:], tabBarId: nil), actions: actions, context: context))
+    }
+
+    @MainActor func testExtensionSnapshotAcceptsEmptyActionsButRejectsInvalidProps() throws {
+        func decode(_ props: String) throws -> NativeUIControl {
+            let json: [String: Any] = ["id": "counter", "kind": "extension", "x": 0, "y": 0, "width": 100, "height": 44,
+                "dark": false, "rtl": false, "items": [], "extension": ["name": "app.counter", "props": props, "actions": [:]]]
+            return try JSONDecoder().decode(NativeUIControl.self, from: JSONSerialization.data(withJSONObject: json))
+        }
+        XCTAssertTrue(try decode("{\"title\":\"Ready\"}").isValid)
+        XCTAssertFalse(try decode("[]").isValid)
+        XCTAssertFalse(try decode("broken").isValid)
+    }
+
+    @MainActor func testActionWaitsForWebAcknowledgementAndIgnoresDuplicateReplies() async throws {
+        let broker = NativeUIExtensionActions()
+        var request: String?
+        var completed = false
+        let sent = expectation(description: "Web action sent")
+        let task = Task { @MainActor in
+            try await broker.perform(owner: "source") { request = $0; sent.fulfill() }
+            completed = true
+        }
+        defer { task.cancel() }
+        await fulfillment(of: [sent], timeout: 2)
+        let requestID = try XCTUnwrap(request)
+        XCTAssertFalse(completed)
+        broker.finish(requestID)
+        broker.finish(requestID, error: NativeUIError.rejected)
+        try await task.value
+        XCTAssertTrue(completed)
+    }
+
+    @MainActor func testRetirementRejectsPendingCallsOnlyForThatSource() async throws {
+        let broker = NativeUIExtensionActions()
+        var requests: [String: String] = [:]
+        let sent = expectation(description: "Both actions sent")
+        sent.expectedFulfillmentCount = 2
+        let first = Task { @MainActor in try await broker.perform(owner: "first") { requests["first"] = $0; sent.fulfill() } }
+        let second = Task { @MainActor in try await broker.perform(owner: "second") { requests["second"] = $0; sent.fulfill() } }
+        defer { first.cancel(); second.cancel() }
+        await fulfillment(of: [sent], timeout: 2)
+        broker.cancel(owner: "first")
+        do { try await first.value; XCTFail("Retired source must reject") } catch NativeUIError.unavailable {} catch { XCTFail("\(error)") }
+        broker.finish(try XCTUnwrap(requests["second"]))
+        try await second.value
+    }
+
+    @MainActor func testBridgeLossAndTaskCancellationAlwaysSettle() async {
+        let broker = NativeUIExtensionActions()
+        do {
+            try await broker.perform(owner: "lost", timeout: 0.01) { _ in }
+            XCTFail("Lost bridge must time out")
+        } catch NativeUIError.timedOut {} catch { XCTFail("\(error)") }
+        let sent = expectation(description: "Cancelable action sent")
+        let task = Task { @MainActor in try await broker.perform(owner: "canceled") { _ in sent.fulfill() } }
+        await fulfillment(of: [sent], timeout: 2)
+        task.cancel()
+        do { try await task.value; XCTFail("Canceled task must reject") } catch is CancellationError {} catch { XCTFail("\(error)") }
+        broker.cancel()
+    }
+
+    @MainActor func testHostedViewUsesControllerContainmentAndDetaches() {
+        let owner = UIViewController()
+        owner.view = WKWebView()
+        let window = UIWindow(frame: CGRect(x: 0, y: 0, width: 400, height: 800))
+        window.rootViewController = owner
+        window.makeKeyAndVisible()
+        defer { window.isHidden = true }
+        let host = NativeUIExtensionController(content: AnyView(Text("Local content")), owner: owner)
+        XCTAssertTrue(host.view.superview === owner.view)
+        XCTAssertTrue(host.controller.parent === owner)
+        host.update(AnyView(Text("Updated")))
+        host.detach(duration: 0)
+        XCTAssertNil(host.controller.parent)
+        XCTAssertNil(host.view.superview)
+        XCTAssertTrue(owner.children.isEmpty)
+    }
+}