@rdlabo/ionic-theme-ios27 0.1.0-beta.pr154.shac3e35365120e → 0.1.0

package/ios/Sources/IonicNativeUIShellPlugin/Components/ShellTabBar.swift

@@ -11,7 +11,7 @@ enum ShellTabBar {
 
     static func make(_ node: ShellControl, rendering: ShellRendering, delegate: UITabBarDelegate) -> UITabBar {
         let control = UITabBar()
-        control.itemPositioning = .fill
+        configureLayout(control)
 #if DEBUG
         NSLog("[Native UI Shell] Created UITabBar %@", node.id)
 #endif
@@ -20,6 +20,16 @@ enum ShellTabBar {
         return control
     }
 
+    static func configureLayout(_ tabBar: UITabBar) {
+        // The reader accepts icon-top tabs. Keep that layout local to the native
+        // bar instead of letting the iPad idiom turn it into inline items.
+        if #available(iOS 17.0, *) {
+            tabBar.traitOverrides.horizontalSizeClass = .compact
+            tabBar.traitOverrides.verticalSizeClass = .regular
+        }
+        tabBar.itemPositioning = .fill
+    }
+
     static func update(_ tabBar: UITabBar, node: ShellControl, rendering: ShellRendering) {
         let items = node.items
         let ids = items.map(\.id)
@@ -40,6 +50,7 @@ enum ShellTabBar {
             if tab.selectedImage !== icon { tab.selectedImage = icon }
             tab.isEnabled = !item.content.disabled
             tab.accessibilityLabel = item.content.accessibilityLabel
+            applyTypography(item.content, to: tab)
             applyBadge(item.content.badge, to: tab, rendering: rendering)
         }
         let selectedItem = zip(nativeItems, items).first { $0.1.content.selected }?.0
@@ -48,6 +59,27 @@ enum ShellTabBar {
         tabBar.accessibilityIdentifier = node.id
     }
 
+    static func applyTypography(_ content: ShellItemContent, to item: UITabBarItem) {
+        let weight: UIFont.Weight
+        switch content.fontWeight {
+        case ..<150: weight = .ultraLight
+        case ..<250: weight = .thin
+        case ..<350: weight = .light
+        case ..<450: weight = .regular
+        case ..<550: weight = .medium
+        case ..<650: weight = .semibold
+        case ..<750: weight = .bold
+        case ..<850: weight = .heavy
+        default: weight = .black
+        }
+        let font = UIFont.systemFont(ofSize: content.fontSize, weight: weight)
+        for state in [UIControl.State.normal, .selected] {
+            if item.titleTextAttributes(for: state)?[.font] as? UIFont != font {
+                item.setTitleTextAttributes([.font: font], for: state)
+            }
+        }
+    }
+
     static func applyBadge(_ badge: ShellBadge?, to item: UITabBarItem, rendering: ShellRendering) {
         // nil removes a badge; an empty string keeps the native notification dot.
         item.badgeValue = badge?.value
@@ -59,8 +91,14 @@ enum ShellTabBar {
     }
 
     static func fit(_ tabBar: UITabBar, node: ShellControl, bounds: CGRect) -> Bool {
+        // Place a new bar before asking UIKit for its safe-area-dependent size.
+        // Measuring at the initial zero frame makes a restored iPad bar 5pt shorter.
+        if tabBar.bounds.isEmpty {
+            tabBar.frame = bounds
+            tabBar.layoutIfNeeded()
+        }
         let fitted = tabBar.sizeThatFits(bounds.size)
-        var size = CGSize(width: tabBar.bounds.width > 0 ? tabBar.bounds.width : bounds.width,
+        var size = CGSize(width: bounds.width,
                           height: max(bounds.height, fitted.height))
         if tabBar.bounds.size != size { tabBar.bounds.size = size }
         tabBar.layoutIfNeeded()
@@ -82,11 +120,8 @@ enum ShellTabBar {
             }
             content = measured
         }
-        // Some UIKit layouts cap the platter width (notably on iPad).
-        // Keep the original Web bar instead of changing its item widths.
-        guard abs(content.width - bounds.width) <= 1 else {
-            return false
-        }
+        // UIKit owns the adaptive platter size, including changes after badge/title updates.
+        // Preserve the DOM placement anchor instead of requiring identical item widths.
         let anchor = node.tabBarAnchor
         let x = anchor?.x ?? 0
         let y = anchor?.y ?? 0

package/ios/Sources/IonicNativeUIShellPlugin/IonicNativeUIShellPlugin.swift

@@ -95,16 +95,16 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
         }
     }
 
-    private func removeControl(_ id: String) {
+    private func removeControl(_ id: String, duration: TimeInterval = 0) {
         if #available(iOS 26.0, *) {
             (searchControllers.removeValue(forKey: id) as? ShellSearchController)?.detach()
         }
-        controls.removeValue(forKey: id)?.removeFromSuperview()
+        if let control = controls.removeValue(forKey: id) { ShellCrossfade.retire(control, duration: duration) }
         fingerprints.removeValue(forKey: id)
     }
 
-    private func removeControls() {
-        Array(controls.keys).forEach(removeControl)
+    private func removeControls(duration: TimeInterval = 0) {
+        Array(controls.keys).forEach { removeControl($0, duration: duration) }
         host?.removeFromSuperview()
         host = nil
         rendering.clear()
@@ -123,11 +123,13 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
             guard let snapshot = try? call.decode(ShellSnapshot.self), snapshot.isValid else {
                 call.reject("Invalid control snapshot"); return
             }
+            let duration = ShellCrossfade.duration(snapshot.transitionDuration)
+            let existing = Set(self.controls.keys)
             let snapshots = snapshot.controls
             let width = snapshot.viewportWidth
             self.revision = next
             if snapshots.isEmpty {
-                self.removeControls()
+                self.removeControls(duration: duration)
                 call.resolve(["revision": next]); return
             }
             let host = self.host ?? ShellHost()
@@ -139,7 +141,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
             let scale = webView.bounds.width / width
             let retained = Set(snapshots.map(\.id))
             for id in Array(self.controls.keys) where !retained.contains(id) {
-                self.removeControl(id)
+                self.removeControl(id, duration: duration)
             }
             var rejectedControls: [String] = []
             var fabs: [(ShellFab, ShellControl)] = []
@@ -203,6 +205,8 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
                             if fab.superview == nil { host.addSubview(fab) }
                             self.controls[id] = fab
                             fabs.append((fab, node))
+                        } else if let segment = self.controls[id] as? ShellSegment, node.kind == ShellSegment.kind {
+                            segment.update(node, scale: scale, rendering: self.rendering)
                         } else if let tabBar = self.controls[id] as? UITabBar, node.kind == ShellTabBar.kind {
                             ShellTabBar.update(tabBar, node: node, rendering: self.rendering)
                         } else {
@@ -240,6 +244,9 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
                     controller.surface.isHidden = self.keyboardVisible && !controller.ownsKeyboard
                 }
             }
+            for (id, control) in self.controls where !existing.contains(id) && self.searchControllers[id] == nil {
+                ShellCrossfade.enter(control, duration: duration)
+            }
             let complete = { call.resolve(["revision": next, "rejectedSearches": rejectedSearches, "rejectedControls": rejectedControls]) }
             if let coordinator = searches.first?.0.transitionCoordinator,
                coordinator.animate(alongsideTransition: nil, completion: { _ in complete() }) { return }

package/ios/Sources/IonicNativeUIShellPlugin/Shared/ShellCrossfade.swift

@@ -0,0 +1,35 @@
+import UIKit
+
+@MainActor enum ShellCrossfade {
+    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/IonicNativeUIShellPlugin/Shared/ShellSnapshot.swift

@@ -9,11 +9,12 @@ enum ShellComponent: String, Decodable {
 
 struct ShellSnapshot: Decodable {
     let revision: Int
+    let transitionDuration: Double?
     let viewportWidth: Double
     let controls: [ShellControl]
 
     var isValid: Bool {
-        revision >= 0 && viewportWidth.isFinite && viewportWidth > 0 && controls.count <= 100 &&
+        revision >= 0 && (transitionDuration.map { $0.isFinite && $0 >= 0 && $0 <= 500 } ?? true) && viewportWidth.isFinite && viewportWidth > 0 && controls.count <= 100 &&
         Set(controls.map(\.id)).count == controls.count && controls.allSatisfy(\.isValid)
     }
 }
@@ -100,6 +101,9 @@ struct ShellItemContent: Decodable, Equatable {
     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?
@@ -109,6 +113,7 @@ struct ShellItemContent: Decodable, Equatable {
     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/Tests/IonicNativeUIShellPluginTests/ShellSnapshotTests.swift

@@ -22,6 +22,65 @@ final class ShellSnapshotTests: XCTestCase {
         try JSValueDecoder().decode(ShellSnapshot.self, from: ["revision": 1, "viewportWidth": width, "controls": controls])
     }
 
+    @MainActor func testTabTypographyPreservesCSSWeightsAndSize() throws {
+        let weights: [UIFont.Weight] = [.ultraLight, .thin, .light, .regular, .medium, .semibold, .bold, .heavy, .black]
+        let tab = UITabBarItem()
+        for (index, weight) in weights.enumerated() {
+            let cssWeight = Double((index + 1) * 100)
+            let content = try decode([control(["items": [item(["fontSize": 19.0, "fontWeight": cssWeight])]])]).controls[0].items[0].content
+            ShellTabBar.applyTypography(content, to: tab)
+            for state in [UIControl.State.normal, .selected] {
+                let font = try XCTUnwrap(tab.titleTextAttributes(for: state)?[.font] as? UIFont)
+                XCTAssertEqual(font.pointSize, 19)
+                XCTAssertEqual(font, UIFont.systemFont(ofSize: 19, weight: weight), "CSS weight \(cssWeight)")
+            }
+        }
+    }
+
+    @MainActor func testSegmentSelectionEchoPreservesNativeViewsAndActionsUseUpdatedItems() throws {
+        guard #available(iOS 26.0, *) else { return }
+        func node(_ items: [JSObject]) throws -> ShellControl {
+            try XCTUnwrap(decode([control(["kind": "ion-segment", "width": 160.0, "items": items])]).controls.first)
+        }
+        let first = try node([item(["id": "left", "selected": true]), item(["id": "right"])])
+        var activated: [String] = []
+        let segment = try XCTUnwrap(ShellSegment.make(first, scale: 1, rendering: ShellRendering(),
+            activate: { activated.append($0) }) as? ShellSegment)
+        segment.frame = CGRect(x: 0, y: 0, width: 160, height: 48)
+        segment.layoutIfNeeded()
+        XCTAssertEqual(segment.widthForSegment(at: 0) + segment.widthForSegment(at: 1), 160)
+        segment.selectedSegmentIndex = 1
+        segment.layoutIfNeeded()
+        let children = segment.subviews
+        let animation = CABasicAnimation(keyPath: "opacity")
+        animation.fromValue = 0.5
+        animation.toValue = 1
+        animation.duration = 1
+        segment.layer.add(animation, forKey: "selection-in-flight")
+        let echo = try node([item(["id": "left"]), item(["id": "right", "selected": true])])
+        segment.update(echo, scale: 1, rendering: ShellRendering())
+        segment.layoutIfNeeded()
+        XCTAssertEqual(segment.selectedSegmentIndex, 1)
+        XCTAssertEqual(segment.subviews, children)
+        XCTAssertNotNil(segment.layer.animation(forKey: "selection-in-flight"))
+        segment.sendActions(for: .valueChanged)
+        XCTAssertEqual(activated, ["right"])
+
+        // Web can reject a selection, clear it, or replace the available actions.
+        segment.update(first, scale: 1, rendering: ShellRendering())
+        XCTAssertEqual(segment.selectedSegmentIndex, 0)
+        let replaced = try node([item(["id": "replacement", "label": "Updated", "disabled": true])])
+        segment.update(replaced, scale: 2, rendering: ShellRendering())
+        XCTAssertEqual(segment.numberOfSegments, 1)
+        XCTAssertEqual(segment.selectedSegmentIndex, UISegmentedControl.noSegment)
+        XCTAssertEqual(segment.titleForSegment(at: 0), "Updated")
+        XCTAssertFalse(segment.isEnabledForSegment(at: 0))
+        XCTAssertEqual(segment.widthForSegment(at: 0), 320)
+        segment.selectedSegmentIndex = 0
+        segment.sendActions(for: .valueChanged)
+        XCTAssertEqual(activated, ["right", "replacement"])
+    }
+
     func testFlatWireFormatAndOptionalFields() throws {
         let snapshot = try decode([control()])
         XCTAssertTrue(snapshot.isValid)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rdlabo/ionic-theme-ios27",
   "private": false,
-  "version": "0.1.0-beta.pr154.shac3e35365120e",
+  "version": "0.1.0",
   "description": "iOS27 Theme for Ionic Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/native/components/searchable-tabs.ts

@@ -224,6 +224,12 @@ export const createSearchSupport = (doc: Document, id: (element: Element) => str
           trigger.y,
           trigger.width,
           trigger.height,
+          candidate.control.items,
+          candidate.icons.map(({ source }) => source),
+          field,
+          trigger,
+          bar.placeholder,
+          bar.disabled,
         ]);
         if (state.rejectedLayout === state.layout) continue;
         candidate.control.search = {
@@ -259,7 +265,12 @@ export const createSearchSupport = (doc: Document, id: (element: Element) => str
     },
     reject(ids: string[]) {
       states.forEach((state) => {
-        if (ids.includes(id(state.binding.tabBar))) state.rejectedLayout = state.layout;
+        if (ids.includes(id(state.binding.tabBar))) {
+          state.rejectedLayout = state.layout;
+          // A rejected search surface has been removed by UIKit. Do not reuse its
+          // cached configuration on an inactive page; project ordinary tabs instead.
+          state.last = undefined;
+        }
       });
     },
     event(event: ShellSearchEvent) {

package/src/native/definitions.ts

@@ -42,6 +42,9 @@ export interface ShellItem extends Frame {
   iconWidth?: number;
   iconHeight?: number;
   iconPosition?: 'leading' | 'trailing' | 'top';
+  imagePadding?: number;
+  contentInsetLeading?: number;
+  contentInsetTrailing?: number;
   iconTemplate?: boolean;
   visible?: boolean;
   closeIcon?: string;
@@ -84,6 +87,7 @@ export interface ShellSearchEvent extends ShellActivation {
 
 export interface ShellSnapshot {
   revision: number;
+  transitionDuration?: number;
   viewportWidth: number;
   controls: ShellControl[];
 }

package/src/native/runtime.ts

@@ -2,12 +2,13 @@ import type { PluginListenerHandle } from '@capacitor/core';
 import { LIFECYCLE_WILL_ENTER, LIFECYCLE_WILL_LEAVE, LIFECYCLE_DID_ENTER, LIFECYCLE_DID_LEAVE } from '@ionic/core';
 import { getNativeSearchBindings, setNativeUIShellIntegration } from '../native-integration';
 import { createSearchSupport } from './components/searchable-tabs';
-import type { ShellSnapshot, NativeUIShellHandle, NativeUIShellPlugin, NativeUIShellStatus } from './definitions';
+import type { ShellActivation, ShellSnapshot, NativeUIShellHandle, NativeUIShellPlugin, NativeUIShellStatus } from './definitions';
 import { readCandidate, selector, shadowSelector, motionSelector } from './components';
 import { marker, unprojected } from './shared/dom';
 import { createIconRenderer } from './shared/icons';
 import type { Candidate } from './shared/candidate';
 import { CSS_MOTION_EVENTS } from './shared/events';
+import { createCrossfade, fadeMarker } from './shared/crossfade';
 
 const overlays = 'ion-modal, ion-popover, ion-alert, ion-action-sheet, ion-loading, ion-picker, ion-toast, ion-menu';
 const overlayNames = ['Modal', 'Popover', 'Alert', 'ActionSheet', 'Loading', 'Picker', 'Toast'];
@@ -22,6 +23,7 @@ const bounded = <T>(promise: Promise<T>): Promise<T> =>
 export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin): Promise<NativeUIShellHandle> => {
   const win = doc.defaultView!;
   const icons = createIconRenderer();
+  const crossfade = createCrossfade(win);
   const ids = new WeakMap<Element, string>();
   let rejected = new WeakMap<HTMLElement, string>();
   const sources = new Map<HTMLElement, string | null>();
@@ -35,6 +37,8 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
   let nextId = 0;
   let revision = 0;
   let acceptedRevision = 0;
+  let updatingRevision: number | undefined;
+  let pendingActivations: ShellActivation[] = [];
   let lastSequence = 0;
   let lastSnapshot = '';
   let viewport = `${win.innerWidth}:${win.innerHeight}`;
@@ -57,12 +61,15 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
     return value;
   };
   const style = doc.createElement('style');
-  style.textContent = `[${marker}], [${marker}] *, [${marker}]::before, [${marker}]::after, [${marker}]::part(native) { visibility: hidden !important; }`;
+  const hidden = `[${marker}]:not([${fadeMarker}])`;
+  style.textContent = `${hidden}, ${hidden} *, ${hidden}::before, ${hidden}::after, ${hidden}::part(native) { visibility: hidden !important; }
+    [${marker}], [${marker}] * { pointer-events: none !important; }`;
 
   const restore = (element: HTMLElement) => {
     lastSnapshot = '';
     search.release(element);
     element.removeAttribute(marker);
+    if (!stopped) crossfade.play(element, false);
     if (element.getAttribute('aria-hidden') === 'true') {
       const previous = sources.get(element);
       if (previous == null) element.removeAttribute('aria-hidden');
@@ -197,10 +204,11 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
       const data = { viewportWidth: win.innerWidth, controls: candidates.map((candidate) => candidate.control) };
       const serialized = JSON.stringify(data);
       if (serialized === lastSnapshot && !forceRefresh) return;
-      const snapshot: ShellSnapshot = { ...data, revision: ++revision };
+      const snapshot: ShellSnapshot = { ...data, revision: ++revision, transitionDuration: crossfade.duration() };
       // A native visibility notification during this update must survive its ack.
       forceRefresh = false;
       updates++;
+      updatingRevision = snapshot.revision;
       const result = await bounded(plugin.update(snapshot));
       if (stopped) return;
       if (result.revision !== snapshot.revision) throw new Error('Native UI Shell revision mismatch');
@@ -236,11 +244,16 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
       for (const element of accepted.flatMap(candidateSources)) {
         if (!sources.has(element)) {
           sources.set(element, element.getAttribute('aria-hidden'));
+          crossfade.play(element, true);
           element.setAttribute(marker, '');
           element.setAttribute('aria-hidden', 'true');
           element.dispatchEvent(new CustomEvent('nativeUIShellChange'));
         }
       }
+      const received = pendingActivations;
+      pendingActivations = [];
+      received.forEach(activate);
+      await crossfade.settled();
       if (invalidated) {
         dirty = true;
         // Sources that became ineligible must paint before their cover is removed.
@@ -249,6 +262,8 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
     } catch (error) {
       await fail(error);
     } finally {
+      updatingRevision = undefined;
+      pendingActivations = [];
       // A refresh received before the ack must also invalidate that ack's rejects.
       if (forceRefresh) rejected = new WeakMap();
       pending = false;
@@ -262,6 +277,7 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
       records.some(
         (record) =>
           record.attributeName !== marker &&
+          record.attributeName !== fadeMarker &&
           !(
             record.attributeName === 'aria-hidden' &&
             sources.has(record.target as HTMLElement) &&
@@ -369,7 +385,9 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
       resize.disconnect();
       observed.clear();
       actions.clear();
+      pendingActivations = [];
       search.destroy();
+      crossfade.destroy();
       restoreAll();
       if (!doc.hidden) await painted();
       try {
@@ -388,35 +406,40 @@ export const createRuntime = async (doc: Document, plugin: NativeUIShellPlugin):
       finishWaiters();
     },
   };
+  const activate = (event: ShellActivation) => {
+    if (
+      stopped ||
+      doc.hidden ||
+      event.revision < acceptedRevision ||
+      event.revision > revision ||
+      event.sequence <= lastSequence ||
+      overlayOpen()
+    )
+      return;
+    // Native may send input before update() resolves on the JS bridge.
+    // Revalidate it after ownership is accepted, using the same action path.
+    if (event.revision > acceptedRevision && event.revision === updatingRevision) {
+      pendingActivations.push(event);
+      return;
+    }
+    lastSequence = event.sequence;
+    const element = actions.get(event.id);
+    if (!element) return;
+    const owner = Array.from(sources.keys()).find((source) => source === element || source.contains(element));
+    if (!owner) return;
+    const direct = !blocked(owner) && unprojected(sources.keys(), () => readCandidate(owner, id));
+    const candidate = direct || read().find((candidate) => candidate.actions.has(event.id));
+    const item = candidate?.control.items.find((item) => item.id === event.id);
+    const searchAction =
+      candidate?.control.search && [candidate.control.search.trigger.id, candidate.control.search.closeId].includes(event.id);
+    if (!searchAction && (!item || item.disabled || item.visible === false)) return;
+    // The original Ionic host owns form submission, routerLink and selection events.
+    element.click();
+    lastSnapshot = ''; // Reconcile even if Ionic rejects the proposed native selection.
+    schedule();
+  };
   try {
-    listener = await bounded(
-      plugin.addListener('activate', (event) => {
-        if (
-          stopped ||
-          doc.hidden ||
-          event.revision < acceptedRevision ||
-          event.revision > revision ||
-          event.sequence <= lastSequence ||
-          overlayOpen()
-        )
-          return;
-        lastSequence = event.sequence;
-        const element = actions.get(event.id);
-        if (!element) return;
-        const owner = Array.from(sources.keys()).find((source) => source === element || source.contains(element));
-        if (!owner) return;
-        const direct = !blocked(owner) && unprojected(sources.keys(), () => readCandidate(owner, id));
-        const candidate = direct || read().find((candidate) => candidate.actions.has(event.id));
-        const item = candidate?.control.items.find((item) => item.id === event.id);
-        const searchAction =
-          candidate?.control.search && [candidate.control.search.trigger.id, candidate.control.search.closeId].includes(event.id);
-        if (!searchAction && (!item || item.disabled || item.visible === false)) return;
-        // The original Ionic host owns form submission, routerLink and selection events.
-        element.click();
-        lastSnapshot = ''; // Reconcile even if Ionic rejects the proposed native selection.
-        schedule();
-      }),
-    );
+    listener = await bounded(plugin.addListener('activate', activate));
     searchListener = await bounded(
       plugin.addListener('search', (event) => {
         if (stopped || doc.hidden || event.revision < acceptedRevision || event.revision > revision || overlayOpen()) return;

package/src/native/shared/candidate.ts

@@ -77,6 +77,25 @@ export const appendItem = (
     item.iconPosition = (icons[0] ?? svg).getAttribute('slot') === 'end' ? 'trailing' : 'leading';
     candidate.icons.push({ item, source });
   }
+  if (native && child.matches('ion-button, ion-back-button')) {
+    const style = getComputedStyle(native);
+    const icon = icons[0] ?? svg;
+    const iconStyle = icon && getComputedStyle(icon);
+    const leadingMargin = parseFloat(iconStyle?.marginInlineStart ?? '') || 0;
+    const trailingMargin = parseFloat(iconStyle?.marginInlineEnd ?? '') || 0;
+    const trailing = item.iconPosition === 'trailing';
+    const inner = native.querySelector('.button-inner');
+    const gap = inner ? parseFloat(getComputedStyle(inner).columnGap) || 0 : 0;
+    // UIKit centers the title/image pair using its insets. Include Ionic's
+    // border and negative outer icon margin instead of applying a fixed offset.
+    item.contentInsetLeading =
+      (parseFloat(style.paddingInlineStart) || 0) +
+      (parseFloat(style.borderInlineStartWidth) || 0) +
+      (!trailing || !label ? leadingMargin : 0);
+    item.contentInsetTrailing =
+      (parseFloat(style.paddingInlineEnd) || 0) + (parseFloat(style.borderInlineEndWidth) || 0) + (trailing || !label ? trailingMargin : 0);
+    item.imagePadding = label && icon ? gap + (trailing ? leadingMargin : trailingMargin) : 0;
+  }
   if (!label && !svg) return undefined;
   candidate.control.items.push(item);
   candidate.actions.set(item.id, child);

package/src/native/shared/crossfade.ts

@@ -0,0 +1,49 @@
+export const fadeMarker = 'data-native-ui-shell-fading';
+
+/** Only visual opacity animates; the runtime transfers input/accessibility ownership once. */
+export const createCrossfade = (win: Window) => {
+  const active = new Map<HTMLElement, Animation>();
+  const reduced = win.matchMedia('(prefers-reduced-motion: reduce)');
+  const finish = (element: HTMLElement, animation: Animation) => {
+    if (active.get(element) !== animation) return;
+    active.delete(element);
+    element.removeAttribute(fadeMarker);
+    animation.cancel();
+  };
+  const cancelAll = () => {
+    for (const [element, animation] of active) finish(element, animation);
+  };
+  reduced.addEventListener('change', cancelAll);
+  return {
+    duration: () => (reduced.matches ? 0 : 180),
+    play(element: HTMLElement, toNative: boolean) {
+      const previous = active.get(element);
+      const current = Number(win.getComputedStyle(element).opacity);
+      previous?.cancel();
+      active.delete(element);
+      const opacity = Number(win.getComputedStyle(element).opacity);
+      if (reduced.matches || !element.isConnected) {
+        element.removeAttribute(fadeMarker);
+        return;
+      }
+      element.setAttribute(fadeMarker, '');
+      const animation = element.animate([{ opacity: previous ? current : toNative ? opacity : 0 }, { opacity: toNative ? 0 : opacity }], {
+        duration: 180,
+        easing: 'ease-in-out',
+        fill: 'both',
+      });
+      active.set(element, animation);
+      void animation.finished.then(
+        () => finish(element, animation),
+        () => finish(element, animation),
+      );
+    },
+    async settled() {
+      await Promise.all(Array.from(active.values(), (animation) => animation.finished.catch(() => {})));
+    },
+    destroy() {
+      reduced.removeEventListener('change', cancelAll);
+      cancelAll();
+    },
+  };
+};

package/src/native/shared/dom.ts

@@ -1,3 +1,5 @@
+import { fadeMarker } from './crossfade';
+
 import type { Frame } from '../definitions';
 
 export const marker = 'data-native-ui-shell';
@@ -24,7 +26,8 @@ export const visible = (element: HTMLElement): boolean => {
   if (!element.isConnected || element.closest(excluded) || isShellDisabled(element)) return false;
   for (let current: HTMLElement | null = element; current; current = current.parentElement) {
     const style = getComputedStyle(current);
-    if (style.display === 'none' || style.visibility !== 'visible' || Number(style.opacity) === 0) return false;
+    if (style.display === 'none' || style.visibility !== 'visible' || (Number(style.opacity) === 0 && !current.hasAttribute(fadeMarker)))
+      return false;
     // Moving/collapsing/custom transformed surfaces stay in Web coordinates.
     if (
       style.transform !== 'none' &&