@webview-native-ui/engine 1.0.0 → 1.0.2-0

package/docs/configuration/ionic-overlays.md

@@ -5,10 +5,17 @@ above Engine-managed native content. Native registration handles capture and
 restoration, but it cannot infer Ionic's presentation lifecycle from a native
 view. This shared monitor supplies that coverage decision for all registrations.
 
-Integrate the plugin through the [Capacitor](../getting-started/capacitor.md) or
-[Cordova](../getting-started/cordova.md) guide first. Non-Ionic applications use their own
+Applications use this adapter with an Engine-enabled plugin. Plugin authors first
+integrate through the [Capacitor](../getting-started/capacitor.md) or
+[Cordova](../getting-started/cordova.md) guide. Non-Ionic applications use their own
 lifecycle notifications and do not install this adapter.
 
+The `/ionic` entry point provides shared framework integration. It observes Ionic
+overlays and determines which registered surfaces they cover. A plugin's explicit
+presentation controls remain part of that plugin's API, connected through
+[projection notifications](events.md) or its existing
+[renderer API](../advanced/renderer.md).
+
 For example, opening an Ionic settings modal should cover the background native
 tab bar while leaving the modal's own native close button usable. A blanket hide
 notification cannot express that relationship. The shared monitor evaluates each
@@ -32,6 +39,10 @@ One monitor is shared per document, including between the npm module and the run
 
 The default covers Modal, Popover, Alert, Action Sheet, Loading, Picker, Toast and Menu lifecycle events. It compares each projection's DOM with the active overlay stack: content inside the front modal stays native, while covered content temporarily uses its prepared image. Toasts and inactive sheet backdrops do not cover a surface. Nested overlays keep it covered until the remaining stack permits restoration. Missing images retain the normal Web fallback. This temporary coverage never overwrites a plugin's explicit `web` or `none` destination. Projections registered later read the current state.
 
+Here, Alert means Ionic's `ion-alert`. This adapter does not intercept
+`window.alert()`, detect HTML `<dialog>` automatically, or observe native dialogs.
+Custom Web overlays can supply lifecycle events through `additional`, below.
+
 A popover displayed in a native window is different from a popover rendered in
 the WebView: its DOM placeholder must not be treated as a covering Web overlay.
 The `@rdlabo/capacitor-native-ui` plugin reports this native presentation ownership
@@ -42,6 +53,8 @@ explicit integration; it is not inferred from the popover's DOM alone.
 ## Customize unusual layouts
 
 Optional settings are document-wide. Keep the defaults for ordinary Ionic overlays.
+`IonicOverlayOptions`, exported from the same `/ionic` entry point, is the TypeScript
+type for these settings; it is not another initialization function.
 Use `exclude` for an application overlay that should not cover native content, and
 `additional` when the same app also uses a custom dialog with its own lifecycle
 events. Use `covers` only when DOM containment and backdrop state do not describe
@@ -63,3 +76,24 @@ enableSupportIonicOverlays({
 ```
 
 Use `covers(overlay, target)` only when a registered DOM projection needs a custom coverage rule; return `undefined` for the default, or a boolean to override it. Exclusions and explicit native-window ownership take precedence. The standard relationship uses overlay order, DOM containment and backdrop state, rather than attempting to interpret arbitrary CSS stacking contexts. Configure unusual layouts explicitly.
+
+## When a plugin needs to know which modal is behind another
+
+For ordinary application setup, use `enableSupportIonicOverlays()` as shown above.
+The Engine then handles Ionic overlay coverage without additional calls.
+
+A plugin that places native controls inside Ionic modals may also need to know
+which modal lies behind the one being opened. Two helpers from the same `/ionic`
+entry point let the plugin read the modal order already tracked by the Engine.
+
+For example, open modal A, then modal B above it:
+
+- `ionicModalStack(document)` returns `[A, B]`, from back to front.
+- `coveredIonicSurface(B)` returns A, the modal beneath B.
+- If a popover opens above B, `coveredIonicSurface(popover)` returns B.
+- `coveredIonicSurface(A)` returns `undefined`: the page behind A is not a modal.
+
+A and B here are the actual `ion-modal` DOM elements. These helpers only read the
+tracked modal order; they do not open or close overlays, switch projection, or
+start monitoring. Call them after `enableSupportIonicOverlays()` has enabled the
+monitor and the relevant overlay has entered its presentation lifecycle.

package/docs/configuration/pause-resume.md

@@ -0,0 +1,51 @@
+# Cover native UI with a custom Web overlay
+
+Use `pause()` before presenting a custom modal or `div` over native UI and
+`resume()` when it closes. For Ionic overlays, use the automatic
+[Ionic integration](ionic-overlays.md), which shares this coordination but only
+covers surfaces behind the overlay.
+
+## Plugin authors: re-export the Engine functions
+
+```ts
+export { pause, resume } from '@webview-native-ui/engine';
+```
+
+The functions share one pause count across Engine-enabled plugins and bundles in
+the same document. No wrapper or native plugin method is needed.
+
+## Application authors: pair each pause with a resume
+
+```ts
+import { pause, resume } from 'your-plugin';
+
+pause();
+try {
+  await showCustomModal();
+} finally {
+  resume();
+}
+```
+
+`showCustomModal()` must resolve when the modal closes. With event-driven modals,
+call `resume()` on dismissal, cancellation or failure. Use one pair per overlay,
+even with multiple plugins; nested overlays each need their own pair.
+
+A pause replaces visible native surfaces with prepared Web images or their normal
+Web fallback. Hidden surfaces stay hidden. The final `resume()` releases
+the request, preserving each plugin's presentation intent and remaining Ionic
+overlay coverage.
+
+The counter does not track callers or pair individual calls. An extra `resume()`
+while paused can release another overlay's request; only a `resume()` at zero has
+no effect. Each owner must release exactly once for each pause it requested.
+
+Both functions return immediately, without waiting for native acknowledgments or
+painting. Returning from `pause()` does not mean native UI has already moved
+behind the Web overlay; it may remain in front until the handoff completes.
+The final `resume()` defers native restoration until the second animation frame,
+allowing overlay removal to paint without guaranteeing compositor completion.
+Call it after removing the overlay or completing
+its dismissal animation. A new `pause()` cancels a pending restoration.
+Calling `pause()` just before a blocking `window.alert()` therefore does
+not guarantee a completed handoff. They do not detect custom overlays automatically.

package/docs/controls.md

@@ -0,0 +1,39 @@
+# Shared controls for native adapters
+
+The existing Engine package also owns the control implementation used by Capacitor Native UI.
+No additional npm package or workspace is required.
+
+- `@webview-native-ui/engine`: generic projection API; unchanged dependency boundary.
+- `@webview-native-ui/engine/controls`: control runtime and transport contract.
+- `@webview-native-ui/engine/controls/ionic`: optional Ionic overlay implementation.
+- `@webview-native-ui/engine/integration`: the single shared transition/search integration state.
+
+An adapter creates one `createNativeUI({ plugin, getPlatform, isAvailable })` instance and keeps it
+for its lifetime. The plugin implements the `NativeUIPlugin` transport interface. The adapter owns
+host registration, method dispatch, listener delivery, and lifecycle hooks; Engine owns rendering,
+DOM ownership, extension acknowledgement, and teardown sequencing. Cordova can supply this same
+transport without importing Capacitor. The Cordova Native UI plugin itself is a subsequent change.
+
+SwiftPM exposes the optional `WebViewNativeUIControls` product, depending on `WebViewNativeUIEngine`.
+CocoaPods exposes `WebViewNativeUIControls` with the same dependency. Android exposes the optional
+`io.github.webview-native-ui:controls` artifact from `android/controls`; it depends on `engine` and
+Compose. Generic Engine consumers keep their existing dependencies and Android minimum SDK 23.
+Controls require Android API 24. Native adapters create `NativeUIController` and forward requests
+and events. iOS receives JSON dictionaries and completion closures; Android receives JSONObjects.
+
+The Ionic theme imports Engine integration directly. The Capacitor compatibility integration export
+re-exports that module. Resolve a single Engine version in the application; do not bundle a private
+copy of integration into the theme or adapter. The `/controls` entry does not load Ionic runtime code;
+load `/controls/ionic` only when opting into Ionic overlays.
+
+## Verification and release order
+
+Run `npm run test:controls` for the migrated control tests and `npm test` for generic projection.
+SwiftPM's `WebViewNativeUIEngine-Package` scheme covers both native targets. Android's
+`:controls:testReleaseUnitTest` covers the migrated snapshot parser. Existing Capacitor transport
+and hosted lifecycle tests remain in its repository, and the theme retains the real demo E2E suite.
+
+Build and verify Engine first, including both signed Maven artifacts in the same Central bundle and
+both npm-distributed podspecs. Release the Engine native artifacts and npm package at the same version
+before refreshing the Capacitor and theme registry lockfiles. Candidate verification uses local npm
+tarballs and a temporary SwiftPM path or local Maven repository; do not commit these temporary paths.

package/docs/getting-started/capacitor.md

@@ -1,6 +1,6 @@
 # Capacitor plugin integration
 
-Add Web projection and restoration to an existing Capacitor plugin without changing its public `registerPlugin()` export. The plugin keeps its native renderer and application API; the Engine coordinates its native view with a DOM fallback.
+Let an existing Capacitor plugin's native components coexist with Web layouts, navigation and overlays without changing its public `registerPlugin()` export. The plugin keeps its native renderer and application API; registration connects each native view to its DOM container using the [shared presentation model](../concepts.md).
 
 This guide covers dependencies, registration, notifications and teardown. Start with
 [native initialization](initialization.md) for the minimal call, required inputs
@@ -40,9 +40,9 @@ The primary native distribution is Swift Package Manager. Depend on the reposito
 .product(name: "WebViewNativeUIEngine", package: "engine")
 ```
 
-While the API is pre-1.0, pin the same Engine release across npm, SwiftPM, Gradle and CocoaPods, and upgrade deliberately. Applications should retain their dependency lockfiles for reproducible builds.
+Use the same Engine release across npm, SwiftPM, Gradle and CocoaPods, and upgrade deliberately. Applications should retain their dependency lockfiles for reproducible builds.
 
-SwiftPM resolves this repository's version tags such as `v0.0.1`. For unreleased integration tests, use a local checkout or an explicit tested commit.
+SwiftPM resolves this repository's version tags such as `v1.0.0`. For unreleased integration tests, use a local checkout or an explicit tested commit.
 
 `import WebViewNativeUIEngine` requires no Capacitor registration. The npm companion supplies DOM measurement and Web image handoff; SwiftPM resolves the native dependency independently of npm hoisting.
 

package/docs/getting-started/cordova.md

@@ -1,5 +1,7 @@
 # Cordova plugin integration
 
+Let a Cordova plugin's native components coexist with Web layouts, navigation and overlays using the [same presentation model](../concepts.md) as Capacitor.
+
 The same npm package, Swift library and Android AAR support Capacitor and Cordova. Engine is a library used by plugin maintainers, not a separately registered Cordova plugin. A Cordova application does not need `@capacitor/core` or a Capacitor native SDK.
 
 The consuming plugin still owns its native view and the corresponding DOM, including placement, size and stacking order. Supply an existing selector such as `native-ad` or `#player`. The DOM may be added after initialization. Image preparation, scroll handling, overlays and restoration use the common Engine implementation.
@@ -32,7 +34,7 @@ frameworks report their own transition lifecycle through notifications.
 Replace `<engine-version>` in every dependency below with the same published
 release. Read that release tag’s documentation so the examples match its APIs.
 
-Use the same Engine release for the Web package and native libraries. The API is pre-1.0; pin versions and retain dependency lockfiles.
+Use the same Engine release for the Web package and native libraries. Pin matching versions and retain dependency lockfiles for reproducible builds.
 
 ```sh
 npm install --save-exact '@webview-native-ui/engine@<engine-version>'

package/docs/getting-started/initialization.md

@@ -2,7 +2,10 @@
 
 Start with `NativeUIProjection` when a plugin owns a native view and a corresponding
 Web container. Registration starts the runtime, binds that container and coordinates
-image handoff and restoration. You do not need the renderer APIs for this route.
+presentation between the native view and the Web layout. This is the same starting
+point for a component in a scrolling feed or beneath a Web overlay. You do not need
+the renderer APIs for this route. See [the shared model](../concepts.md) for how
+these situations relate and where platform limits apply.
 
 Use the [Capacitor](capacitor.md) or [Cordova](cordova.md) guide for
 dependency installation, plugin lifecycle hooks and notification forwarding.
@@ -46,7 +49,20 @@ projection = NativeUIProjection(
 )
 ```
 
-Both snippets belong inside the integration guide's error boundary; retain the
+Java can use the same defaults without supplying every optional argument:
+
+```java
+NativeUIProjection.install(getBridge().getWebView());
+projection = new NativeUIProjection(
+    getActivity().getWindow(),
+    getBridge().getWebView(),
+    getPluginHandle().getId(),
+    "#native-ui-fallback",
+    () -> nativeView
+);
+```
+
+These snippets belong inside the integration guide's error boundary; retain the
 existing Web fallback if initialization fails. `projection` and `nativeView` are
 properties of your plugin. Dispose the registration with `destroy()` on iOS or
 `close()` on Android when that renderer is retired. All native lifecycle calls

package/docs/reference/platforms.md

@@ -100,8 +100,8 @@ precision alone does not resolve this difference.
 Left: **iPhone 15 Pro Max, iOS 27.2**. Right: **iPad mini (6th generation),
 iPadOS 27.2**. Each device screenshot shows the captured **16-bit Display P3 PNG
 in WKWebView above** and the **live UIKit tab bar below**, at the same size within
-that device. The screenshots were placed side by side without rescaling or changing
-their shared color profile. These are physical-device results, not Simulator captures.
+that device. For this comparison, the iPhone screenshot was resized to match the iPad
+screenshot's height; their shared color profile was preserved. These are physical-device results, not Simulator captures.
 
 The system screenshot preserves the live appearance, but the application-level
 capture does not reproduce it completely. On the tested iPhone, the difference was

package/docs/reference/projection.md

@@ -125,7 +125,7 @@ Listeners follow host reparenting and slot reassignment and are removed on teard
 
 Scrolling is internal: iOS uses a uniquely matched native scroll binding when available; otherwise, including Android, scrolling temporarily uses the prepared image and restores native content after motion settles. Automatic scroll handling never overrides explicit `web` or `none`. Unsupported capture or geometry keeps the normal DOM fallback; it does not wait for a new capture on the transition path. The latest explicit destination survives WebView reload, and old-document replies cannot complete a new document's requests.
 
-By default, the internal channel is limited to the main frame on Capacitor's localhost origins. Pass the application's exact `allowedOrigins` for a different configured origin. Android requires WebView's `WEB_MESSAGE_LISTENER` and `DOCUMENT_START_SCRIPT` features; registration fails explicitly on unsupported WebView implementations. Do not use wildcard origins for remotely navigable WebViews.
+The internal channel is limited to the main frame. Capacitor origins come from the bundled `capacitor.config.json`: `server.url` takes precedence over the local hostname/scheme. To override them, pass exact `allowedOrigins` (on Android, to `install` before navigation; registrations inherit them). Neither `allowNavigation` nor the current WebView URL expands this set. Android requires WebView's `WEB_MESSAGE_LISTENER` and `DOCUMENT_START_SCRIPT` features; registration fails explicitly on unsupported WebView implementations. Do not use wildcard origins for remotely navigable WebViews.
 
 For capture modes, translucent surfaces, image color and private storage, see
 [capture and platform limits](platforms.md). Custom renderer bridge and scroll

package/ios/Sources/WebViewNativeUIControls/Components/NativeUIButton.swift

@@ -0,0 +1,98 @@
+import UIKit
+
+enum NativeUIButton {
+    private final class BadgeLabel: UILabel {}
+    private static let activationID = UIAction.Identifier("native-ui-activate")
+
+    /// Reuse an unambiguous presentation slot while keeping action IDs source-specific.
+    @MainActor
+    static func reassociate(_ nodes: [NativeUIControl], controls: inout [String: UIView],
+                            fingerprints: inout [String: NativeUIControl]) -> Set<String> {
+        func identity(_ node: NativeUIControl) -> String? {
+            guard node.placement == nil, kinds.contains(node.kind), node.items.count == 1 else { return nil }
+            return node.items[0].content.transitionId
+        }
+        // swiftlint:disable:next force_unwrapping
+        let old = Dictionary(grouping: fingerprints.values.filter { identity($0) != nil }, by: { identity($0)! })
+        // swiftlint:disable:next force_unwrapping
+        let incoming = Dictionary(grouping: nodes.filter { identity($0) != nil }, by: { identity($0)! })
+        let retained = Set(nodes.map(\.id))
+        var reused = Set<String>()
+        for (key, matches) in incoming {
+            guard matches.count == 1, let node = matches.first, controls[node.id] == nil,
+                  let previous = old[key], previous.count == 1, let source = previous.first,
+                  !retained.contains(source.id), let button = controls[source.id] as? UIButton else { continue }
+            controls.removeValue(forKey: source.id)
+            fingerprints.removeValue(forKey: source.id)
+            controls[node.id] = button
+            reused.insert(node.id)
+        }
+        return reused
+    }
+    // These Ionic components share the same native UIButton presentation.
+    static let kinds: [NativeUIComponent] = [.button, .backButton, .menuButton]
+
+    @available(iOS 26.0, *)
+    static func make(_ node: NativeUIControl, existing: UIButton? = nil, rendering: NativeUIControlRendering, activate: @escaping (String) -> Void) -> UIButton? {
+        guard node.items.count == 1, let item = node.items.first else { return nil }
+        let control = render(item.content, glass: item.content.buttonFill != .clear, existing: existing, rendering: rendering, activate: activate)
+        control.semanticContentAttribute = node.rtl ? .forceRightToLeft : .forceLeftToRight
+        return control
+    }
+
+    @available(iOS 26.0, *)
+    static func render(_ item: NativeUIItemContent, glass: Bool, existing: UIButton? = nil, rendering: NativeUIControlRendering, activate: @escaping (String) -> Void) -> UIButton {
+        var configuration: UIButton.Configuration = glass ? .glass() : .plain()
+        configuration.title = item.label
+        configuration.image = rendering.image(item)
+        configuration.imagePadding = item.imagePadding ?? 4
+        configuration.contentInsets = NSDirectionalEdgeInsets(top: 0, leading: item.contentInsetLeading ?? 4,
+                                                              bottom: 0, trailing: item.contentInsetTrailing ?? 4)
+        configuration.imagePlacement = item.iconPosition == .trailing ? .trailing : .leading
+        configuration.baseForegroundColor = rendering.color(item.color)
+        configuration.titleLineBreakMode = .byTruncatingTail
+        let size = item.fontSize
+        let weight = item.fontWeight
+        configuration.titleTextAttributesTransformer = UIConfigurationTextAttributesTransformer { incoming in
+            var outgoing = incoming
+            outgoing.font = UIFont.systemFont(ofSize: size, weight: weight >= 600 ? .semibold : weight >= 500 ? .medium : .regular)
+            return outgoing
+        }
+        let button = existing ?? UIButton(configuration: configuration)
+        if existing != nil { button.configuration = configuration }
+        button.titleLabel?.numberOfLines = 1
+        // Web and UIKit can differ by a fraction of a point in text measurement.
+        // Absorb that rounding without widening the projected button.
+        button.titleLabel?.adjustsFontSizeToFitWidth = true
+        button.titleLabel?.minimumScaleFactor = 0.99
+        button.isEnabled = !item.disabled
+        button.accessibilityLabel = item.accessibilityLabel
+        button.accessibilityIdentifier = item.id
+        if item.selected { button.accessibilityTraits.insert(.selected) } else { button.accessibilityTraits.remove(.selected) }
+        if item.disabled { button.accessibilityTraits.insert(.notEnabled) } else { button.accessibilityTraits.remove(.notEnabled) }
+        button.subviews.filter { $0 is BadgeLabel }.forEach { $0.removeFromSuperview() }
+        button.accessibilityValue = item.badge?.value
+        if let badge = item.badge {
+            let label = BadgeLabel()
+            label.text = badge.value
+            label.font = .systemFont(ofSize: 11, weight: .semibold)
+            label.textColor = rendering.color(badge.textColor)
+            label.backgroundColor = rendering.color(badge.color)
+            label.textAlignment = .center
+            label.layer.cornerRadius = 8
+            label.clipsToBounds = true
+            label.isAccessibilityElement = false
+            label.translatesAutoresizingMaskIntoConstraints = false
+            button.addSubview(label)
+            NSLayoutConstraint.activate([
+                label.centerXAnchor.constraint(equalTo: button.centerXAnchor, constant: 14),
+                label.topAnchor.constraint(equalTo: button.topAnchor, constant: 1),
+                label.widthAnchor.constraint(greaterThanOrEqualToConstant: max(16, label.intrinsicContentSize.width + 6)),
+                label.heightAnchor.constraint(equalToConstant: 16)
+            ])
+        }
+        button.removeAction(identifiedBy: activationID, for: .touchUpInside)
+        button.addAction(UIAction(identifier: activationID) { _ in activate(item.id) }, for: .touchUpInside)
+        return button
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Components/NativeUIButtons.swift

@@ -0,0 +1,24 @@
+import UIKit
+
+enum NativeUIButtons {
+    static let kind = NativeUIComponent.buttons
+
+    @available(iOS 26.0, *)
+    static func make(_ node: NativeUIControl, scale: CGFloat, rendering: NativeUIControlRendering, activate: @escaping (String) -> Void) -> UIView {
+        let items = node.items
+        let rtl = node.rtl
+        let effect = UIGlassEffect(style: .regular)
+        let control = UIVisualEffectView(effect: effect)
+        control.layer.cornerRadius = node.frame.height * scale / 2
+        control.clipsToBounds = true
+        control.accessibilityIdentifier = node.id
+        for item in items {
+            let button = NativeUIButton.render(item.content, glass: false, rendering: rendering, activate: activate)
+            button.semanticContentAttribute = rtl ? .forceRightToLeft : .forceLeftToRight
+            let rect = item.frame.rect
+            button.frame = CGRect(x: rect.minX * scale, y: rect.minY * scale, width: rect.width * scale, height: rect.height * scale)
+            control.contentView.addSubview(button)
+        }
+        return control
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Components/NativeUIComponents.swift

@@ -0,0 +1,19 @@
+import UIKit
+
+// Static composition of supported wire kinds. Component files own their names and rendering.
+enum NativeUIComponents {
+    static let supported = Set(NativeUIButton.kinds + [NativeUIButtons.kind, NativeUITabBar.kind, NativeUISegment.kind, NativeUIFab.kind])
+
+    @available(iOS 26.0, *)
+    static func make(_ node: NativeUIControl, scale: CGFloat, rendering: NativeUIControlRendering,
+                     tabDelegate: UITabBarDelegate, activate: @escaping (String) -> Void) -> UIView? {
+        switch node.kind {
+        case .button, .backButton, .menuButton: return NativeUIButton.make(node, rendering: rendering, activate: activate)
+        case .buttons: return NativeUIButtons.make(node, scale: scale, rendering: rendering, activate: activate)
+        case .tabBar: return NativeUITabBar.make(node, rendering: rendering, delegate: tabDelegate)
+        case .segment: return NativeUISegment.make(node, scale: scale, rendering: rendering, activate: activate)
+        case .fab: return NativeUIFab()
+        case .extension: return nil // App-local SwiftUI content is hosted by the shell.
+        }
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Components/NativeUIFab.swift

@@ -0,0 +1,80 @@
+import UIKit
+
+final class NativeUIFab: UIView {
+    static let kind = NativeUIComponent.fab
+    var buttons: [String: UIButton] = [:]
+    var content: [String: NativeUIItemContent] = [:]
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        let hit = super.hitTest(point, with: event)
+        return hit === self ? nil : hit
+    }
+
+    @available(iOS 26.0, *)
+    func apply(_ node: NativeUIControl, scale: CGFloat, rendering: NativeUIControlRendering, activate: @escaping (String) -> Void) {
+        let items = node.items
+        let retained = Set(items.map(\.id))
+        var lostFocus = false
+        for id in Array(self.buttons.keys) where !retained.contains(id) {
+            lostFocus = lostFocus || self.buttons[id]?.accessibilityElementIsFocused() == true
+            self.buttons.removeValue(forKey: id)?.removeFromSuperview()
+            self.content.removeValue(forKey: id)
+        }
+        self.accessibilityIdentifier = node.id
+        for item in items {
+            let id = item.id
+            let artwork = item.content.fabArtwork
+            let previous = self.buttons[id]
+            let button = previous ?? NativeUIButton.render(artwork, glass: true, rendering: rendering, activate: activate)
+            if previous == nil {
+                self.buttons[id] = button
+                self.addSubview(button)
+            } else if self.content[id] != artwork {
+                let changedIcon = self.content[id]?.selected != item.content.selected
+                let duration = UIAccessibility.isReduceMotionEnabled ? 0 : min(item.content.iconTransition ?? 0, 1)
+                if changedIcon, let imageView = button.imageView, duration > 0 {
+                    UIView.transition(with: imageView, duration: duration,
+                                      options: [.transitionCrossDissolve, .beginFromCurrentState, .allowUserInteraction]) {
+                        _ = NativeUIButton.render(artwork, glass: true, existing: button, rendering: rendering, activate: activate)
+                    }
+                } else {
+                    UIView.performWithoutAnimation { _ = NativeUIButton.render(artwork, glass: true, existing: button, rendering: rendering, activate: activate) }
+                }
+            }
+            self.content[id] = artwork
+            button.accessibilityTraits.remove(.selected)
+            if id == items.first?.id && items.count > 1 {
+                button.accessibilityValue = item.content.selected
+                    ? NSLocalizedString("Expanded", comment: "FAB accessibility state")
+                    : NSLocalizedString("Collapsed", comment: "FAB accessibility state")
+            } else {
+                button.accessibilityValue = nil
+            }
+            let hidden = item.visible == false
+            if hidden && !button.isHidden && button.accessibilityElementIsFocused() { lostFocus = true }
+            button.isHidden = hidden
+            button.isUserInteractionEnabled = button.isEnabled && !hidden
+            button.semanticContentAttribute = node.rtl ? .forceRightToLeft : .forceLeftToRight
+            let rect = item.frame.rect
+            let frame = CGRect(x: rect.minX * scale, y: rect.minY * scale, width: rect.width * scale, height: rect.height * scale)
+            if button.frame != frame { button.frame = frame }
+        }
+        let ordered = items.compactMap { self.buttons[$0.id] }.filter { !$0.isHidden }
+        self.accessibilityElements = ordered
+        if lostFocus, let main = ordered.first, main.isEnabled, self.window != nil {
+            UIAccessibility.post(notification: .layoutChanged, argument: main)
+        }
+    }
+}
+
+extension NativeUIItemContent {
+    var fabArtwork: Self {
+        var artwork = self
+        if selected {
+            artwork.icon = closeIcon
+            artwork.iconWidth = closeIconWidth
+            artwork.iconHeight = closeIconHeight
+            artwork.label = ""
+        }
+        return artwork
+    }
+}