@momo-kits/native-kits 0.167.1-duo.21-debug → 0.167.1-duo.22-debug

package/compose/build.gradle.kts

@@ -40,7 +40,7 @@ kotlin {
     }
 
     cocoapods {
-        version = "0.167.1-duo.21-debug"
+        version = "0.167.1-duo.22-debug"
         summary = "IOS Shared module"
         homepage = "https://momo.vn"
         ios.deploymentTarget = "15.0"

package/compose/src/commonMain/kotlin/vn/momo/kits/navigation/Navigator.kt

@@ -55,6 +55,12 @@ class Navigator(
     }
 
     fun onBackSafe(callBack: (() -> Unit)? = null) {
+        // An open modal or bottom sheet takes the back first, as its BackHandler does for gestures.
+        val overplayType = OverplayComponentRegistry.getOverplayType()
+        if (overplayType != null && overplayType != OverplayComponentType.SNACK_BAR) {
+            pop(1, callBack)
+            return
+        }
         tabBackHandler?.let {
             it()
             return

package/ios/Application/MaxApi.swift

@@ -5,8 +5,8 @@
 //  Swift mirror of the host-app bridge exposed on Kotlin as `vn.momo.maxapi.IMaxApi`
 //  (`LocalMaxApi`). `IMaxApi` itself is an external compiled dependency with no
 //  source in this repo, so this protocol intentionally exposes only the methods
-//  this kit's Kotlin source actually calls (`track`, `dismiss`, `getLanguage`,
-//  `triggerEventVibration`) — not a full guess at IMaxApi's real surface.
+//  this kit's Kotlin source actually calls — not a full guess at IMaxApi's real surface.
+//  Callbacks carry IMaxApi's `["response": …]` payload.
 //
 
 import UIKit
@@ -17,6 +17,13 @@ public protocol MaxApi {
     func getLanguage(callback: @escaping ([String: Any?]?) -> Void)
     /// `type` is the IMaxApi vibration name (`"light"`, …).
     func triggerEventVibration(_ type: String)
+    // Toolkit (Compose `HeaderRight.Toolkit`).
+    func isFavoriteApp(_ params: [String: Any?], callback: @escaping ([String: Any?]?) -> Void)
+    func onToolAction(_ params: [String: Any?], callback: @escaping ([String: Any?]?) -> Void)
+    func showTools(_ params: [String: Any?], callback: @escaping ([String: Any?]?) -> Void)
+    func showHelpCenter(_ params: [String: Any?], callback: @escaping ([String: Any?]?) -> Void)
+    /// Back to the host home, closing every mini app.
+    func dismissAll(completion: (() -> Void)?)
 }
 
 public extension MaxApi {
@@ -24,4 +31,15 @@ public extension MaxApi {
     func triggerEventVibration(_ type: String) {
         UIImpactFeedbackGenerator(style: .light).impactOccurred()
     }
+
+    // Hosts that don't bridge the toolkit keep it inert, as before these joined the protocol.
+    func isFavoriteApp(_ params: [String: Any?], callback: @escaping ([String: Any?]?) -> Void) {}
+    func onToolAction(_ params: [String: Any?], callback: @escaping ([String: Any?]?) -> Void) {}
+    func showTools(_ params: [String: Any?], callback: @escaping ([String: Any?]?) -> Void) {}
+    func showHelpCenter(_ params: [String: Any?], callback: @escaping ([String: Any?]?) -> Void) {}
+
+    /// Without a home to return to, closing this mini app is the closest thing.
+    func dismissAll(completion: (() -> Void)?) {
+        dismiss(completion: completion)
+    }
 }

package/ios/Input/InputSearch.swift

@@ -45,6 +45,8 @@ public struct InputSearchProps {
     var placeholder: String = ""
     var onChangeText: (String) -> Void = { _ in }
     var onPressButtonText: () -> Void = {}
+    /// Without one, a header search's button text pops the screen (Compose `SearchAnimated`).
+    var hasButtonTextAction = false
     var error: String = ""
     var disabled: Bool = false
     var icon: String = ""
@@ -70,7 +72,7 @@ public struct InputSearchProps {
                 showBorder: Bool = true,
                 placeholder: String = "",
                 onChangeText: @escaping (String) -> Void = { _ in },
-                onPressButtonText: @escaping () -> Void = {},
+                onPressButtonText: (() -> Void)? = nil,
                 error: String = "",
                 disabled: Bool = false,
                 icon: String = "",
@@ -93,7 +95,8 @@ public struct InputSearchProps {
         self.showBorder = showBorder
         self.placeholder = placeholder
         self.onChangeText = onChangeText
-        self.onPressButtonText = onPressButtonText
+        self.onPressButtonText = onPressButtonText ?? {}
+        self.hasButtonTextAction = onPressButtonText != nil
         self.error = error
         self.disabled = disabled
         self.icon = icon

package/ios/Navigation/BottomSheet.swift

@@ -36,6 +36,7 @@ public struct BottomSheetHeader {
 // MARK: - Bottom sheet view
 
 struct BottomSheetView<Content: View>: View {
+    let overplayId: UUID
     let header: BottomSheetHeader
     let isSurface: Bool
     let barrierDismissible: Bool
@@ -56,6 +57,7 @@ struct BottomSheetView<Content: View>: View {
     @State private var backgroundAlpha: CGFloat = 0
     @State private var sheetHeight: CGFloat = 0
     @State private var didAppear = false
+    @State private var isClosing = false
     @State private var keyboardHeight: CGFloat = 0
     /// Live drag offset, isolated from `sheetOffset` so a touch-move only invalidates
     /// this gesture-scoped value instead of forcing the whole body (including
@@ -95,7 +97,6 @@ struct BottomSheetView<Content: View>: View {
         isDuo && !isDuoCentered && layout.width > layout.height ? layout.insets.trailing : 0
     }
 
-    /// The keyboard filler is part of the sheet, so capping the sheet shrinks the content by it.
     private var maxHeight: CGFloat {
         isDuo ? layout.height - max(layout.duoTopInset, Spacing.XL) : screenHeight - 90
     }
@@ -160,43 +161,47 @@ struct BottomSheetView<Content: View>: View {
 
     private var sheet: some View {
         VStack(spacing: 0) {
-            // Drag handle + header (the draggable region).
             VStack(spacing: 0) {
-                Spacer().frame(height: 8)
-                Capsule()
-                    .fill(Colors.black06)
-                    .frame(width: 40, height: 4)
-                Spacer().frame(height: 4)
-                headerView
-                    .frame(height: 56)
-                    .padding(.horizontal, Spacing.M)
+                // Drag handle + header (the draggable region).
+                VStack(spacing: 0) {
+                    Spacer().frame(height: 8)
+                    Capsule()
+                        .fill(Colors.black06)
+                        .frame(width: 40, height: 4)
+                    Spacer().frame(height: 4)
+                    headerView
+                        .frame(height: 56)
+                        .padding(.horizontal, Spacing.M)
+                        .padding(.leading, sideInsetLeading)
+                        .padding(.trailing, sideInsetTrailing)
+                }
+                .frame(maxWidth: .infinity)
+                .frame(height: 72)
+                .contentShape(Rectangle())
+                .gesture(dragGesture, including: draggable ? .all : .subviews)
+
+                Rectangle()
+                    .fill(theme.colors.border.default)
+                    .frame(height: 1)
+
+                content()
                     .padding(.leading, sideInsetLeading)
                     .padding(.trailing, sideInsetTrailing)
+                    // a tall sheet keeps its header (and footer) and gives the content what is left
+                    .layoutPriority(-1)
+
+                if let footer {
+                    BottomSheetFooter(content: footer)
+                }
             }
-            .frame(maxWidth: .infinity)
-            .frame(height: 72)
-            .contentShape(Rectangle())
-            .gesture(dragGesture, including: draggable ? .all : .subviews)
-
-            Rectangle()
-                .fill(theme.colors.border.default)
-                .frame(height: 1)
-
-            content()
-                .padding(.leading, sideInsetLeading)
-                .padding(.trailing, sideInsetTrailing)
-                // a tall sheet keeps its header (and footer) and gives the content what is left
-                .layoutPriority(-1)
-
-            if let footer {
-                BottomSheetFooter(content: footer)
-            }
+            // The filler stays outside the cap, which shrinks by it instead: the sheet still ends at
+            // `maxHeight`, and the iOS 15 fallback never measures the keyboard as content.
+            .modifier(CapHeight(maxHeight: maxHeight - effectiveBottomInset))
 
             (footer != nil ? theme.colors.background.surface : backgroundColor)
                 .frame(height: effectiveBottomInset)
         }
         .frame(maxWidth: isDuoCentered ? duoCenteredWidth : .infinity)
-        .modifier(CapHeight(maxHeight: maxHeight))
         .clipped()
         .background(
             GeometryReader { geo in
@@ -241,14 +246,16 @@ struct BottomSheetView<Content: View>: View {
                 // same bottom-anchored top edge — is still in flight doesn't fight a
                 // moving target. Without this, the live drag value chases an animated
                 // one, producing a couple of corrective jumps before it settles.
-                if sheetOffset != 0 {
+                // A closing sheet keeps going down.
+                if sheetOffset != 0 && !isClosing {
                     sheetOffset = 0
                 }
             }
             .updating($dragTranslation) { value, state, _ in
-                state = max(value.translation.height, 0)
+                state = isClosing ? 0 : max(value.translation.height, 0)
             }
             .onEnded { value in
+                guard !isClosing else { return }
                 let finalOffset = max(value.translation.height, 0)
                 // Capture into persisted state BEFORE @GestureState resets to 0,
                 // avoiding a one-frame snap back to rest before close()'s own
@@ -276,6 +283,8 @@ struct BottomSheetView<Content: View>: View {
     /// Mirrors Compose's `closeEvent`: slide out over 200ms, then fade the scrim
     /// out over 100ms only after the slide finishes, then dismiss.
     private func close() {
+        guard !isClosing else { return }
+        isClosing = true
         withAnimation(.timingCurve(0.3, 0, 0.8, 0.15, duration: 0.2)) {
             sheetOffset = max(sheetHeight, screenHeight)
         }
@@ -285,7 +294,7 @@ struct BottomSheetView<Content: View>: View {
             }
         }
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) {
-            navigator.finishOverplayDismiss()
+            navigator.finishOverplayDismiss(id: overplayId)
         }
     }
 }
@@ -306,10 +315,12 @@ private struct CapHeight: ViewModifier {
 }
 
 /// iOS 15 has no `Layout`: the sheet hugs its ideal height until that outgrows the cap, then is
-/// held at the cap (the ideal height can't be read again without a second copy of the content).
+/// held at the cap. A capped sheet can't read its ideal height (that needs a second copy of the
+/// content), so it is re-measured only when the cap grows, e.g. once the keyboard goes down.
 private struct CapHeightFallback: ViewModifier {
     let maxHeight: CGFloat
     @State private var capped = false
+    @State private var idealHeight: CGFloat = 0
 
     func body(content: Content) -> some View {
         content
@@ -318,15 +329,25 @@ private struct CapHeightFallback: ViewModifier {
             .background(
                 GeometryReader { proxy in
                     Color.clear
-                        .onAppear { cap(proxy.size.height) }
-                        .onChange(of: proxy.size.height) { cap($0) }
+                        .onAppear { measure(proxy.size.height) }
+                        .onChange(of: proxy.size.height) { measure($0) }
                 }
             )
             .frame(height: capped ? maxHeight : nil, alignment: .top)
+            .onChange(of: maxHeight) { cap in
+                if capped {
+                    // the ideal height was over the old cap, so only a taller cap can release it
+                    if cap > idealHeight { capped = false }
+                } else if idealHeight > cap {
+                    capped = true
+                }
+            }
     }
 
-    private func cap(_ height: CGFloat) {
-        if !capped, height > maxHeight { capped = true }
+    private func measure(_ height: CGFloat) {
+        guard !capped else { return }
+        idealHeight = height
+        if height > maxHeight { capped = true }
     }
 }
 

package/ios/Navigation/BottomTab/BottomTab.swift

@@ -8,11 +8,14 @@
 //
 
 import SwiftUI
+import UIKit
 
 public struct BottomTab: View {
     private let items: [BottomTabItem]
     private let floatingButton: BottomTabFloatingButton?
     private let compressionBehavior: DuoBarCompressionBehavior
+    private let onTabPress: ((_ index: Int, _ switchTab: @escaping () -> Void) -> Void)?
+    private let backToInitialTab: Bool
 
     @EnvironmentObject private var navigator: Navigator
     /// The screen hosting the tabs (Compose's `LocalNavigation` in BottomTab).
@@ -20,21 +23,33 @@ public struct BottomTab: View {
     @Environment(\.screenLayout) private var layout
     @Environment(\.appTheme) private var theme
     @StateObject private var tabNavigations = TabNavigations()
-    @State private var selectedIndex: Int = 0
+    /// Compose's `startRoute`: picked once from `initialRouteName`.
+    @State private var startIndex: Int
+    @State private var selectedIndex: Int
     @State private var toolbarHeight = DuoBarCompression.defaultToolbarHeight
     @State private var expandedBar: DuoBar?
     @State private var openedBar: DuoBar?
 
     /// `compressionBehavior`: on iPhone Duo, when the side bar can't hold both bars, which one
     /// starts compressed; tapping the compressed one swaps them.
+    /// `onTabPress` gets every tab press with the switch to perform, e.g. after a login gate.
+    /// `backToInitialTab`: back off another tab returns to the initial one before leaving the screen.
     public init(
         items: [BottomTabItem],
         floatingButton: BottomTabFloatingButton? = nil,
-        compressionBehavior: DuoBarCompressionBehavior = .toolbar
+        compressionBehavior: DuoBarCompressionBehavior = .toolbar,
+        initialRouteName: String? = nil,
+        onTabPress: ((_ index: Int, _ switchTab: @escaping () -> Void) -> Void)? = nil,
+        backToInitialTab: Bool = true
     ) {
         self.items = items
         self.floatingButton = floatingButton
         self.compressionBehavior = compressionBehavior
+        self.onTabPress = onTabPress
+        self.backToInitialTab = backToInitialTab
+        let start = items.firstIndex { $0.name == initialRouteName } ?? 0
+        _startIndex = State(initialValue: start)
+        _selectedIndex = State(initialValue: start)
     }
 
     private var bottomInset: CGFloat { safeAreaBottomInset() }
@@ -73,18 +88,12 @@ public struct BottomTab: View {
         let compression = compression
         ZStack(alignment: .bottom) {
             // Tab content area, inset above the bar.
-            ZStack {
-                ForEach(items.indices, id: \.self) { index in
-                    if index == selectedIndex {
-                        tabScreen(for: index)
-                            .transition(.scale(scale: 0.97).combined(with: .opacity))
-                    }
-                }
-            }
-            .padding(.bottom, reservedBottom)
-            .environment(\.duoTabBarInsets, duoInsets(compression))
-            .environment(\.duoBarCompression, compression)
-            .animation(.easeInOut(duration: 0.2), value: selectedIndex)
+            TabHost(selectedIndex: selectedIndex, count: items.count) { index in AnyView(tabScreen(for: index)) }
+                // each tab hosts itself, so it needs the window's safe area to draw its header under the status bar
+                .ignoresSafeArea(.container, edges: [.top, .horizontal])
+                .padding(.bottom, reservedBottom)
+                .environment(\.duoTabBarInsets, duoInsets(compression))
+                .environment(\.duoBarCompression, compression)
 
             if layout.isIPhoneDuo {
                 DuoTabBar(
@@ -128,14 +137,15 @@ public struct BottomTab: View {
     }
 
     private func selectTab(_ index: Int) {
-        if index != selectedIndex { selectedIndex = index }
+        let switchTab = { if index != selectedIndex { selectedIndex = index } }
+        if let onTabPress { onTabPress(index, switchTab) } else { switchTab() }
     }
 
-    /// Back off the first tab returns to it; the host shows its floating arrow there (RN parity).
+    /// Back off the initial tab returns to it; the host shows its floating arrow there (RN parity).
     private func updateTabBack() {
-        let isFirstTab = selectedIndex == 0
+        let isFirstTab = selectedIndex == startIndex || !backToInitialTab
         HostBackGestureBridge.shared.shouldUseFloatingArrowBack = !isFirstTab
-        navigator.tabBackHandler = isFirstTab ? nil : (hostNavigation?.id ?? -1, { selectedIndex = 0 })
+        navigator.tabBackHandler = isFirstTab ? nil : (hostNavigation?.id ?? -1, { selectedIndex = startIndex })
     }
 
     private func tabScreen(for index: Int) -> some View {
@@ -176,6 +186,143 @@ private struct TabScreenHost: View {
     }
 }
 
+// MARK: - Tab host
+
+/// Compose's tab NavHost with `saveState` / `restoreState`. A tab gets its own UIHostingController
+/// on first selection and keeps it, so its state and scroll survive a switch; while hidden it is
+/// out of the window, so it gets onDisappear / onAppear (and re-runs screen tracking) like a NavHost
+/// destination or a UITabBarController tab. Same scheme as `StackController`.
+private struct TabHost: UIViewControllerRepresentable {
+    let selectedIndex: Int
+    let count: Int
+    let content: (Int) -> AnyView
+
+    func makeUIViewController(context: Context) -> TabController {
+        TabController()
+    }
+
+    func updateUIViewController(_ controller: TabController, context: Context) {
+        controller.update(selectedIndex: selectedIndex, count: count, environment: context.environment, content: content)
+    }
+}
+
+private final class TabController: UIViewController {
+    private final class Tab {
+        let motion = TabMotion()
+        var host: UIHostingController<AnyView>!
+    }
+
+    private static let switchDuration: TimeInterval = 0.2
+
+    private var tabs: [Int: Tab] = [:]
+    private var selectedIndex: Int?
+    private var environment = EnvironmentValues()
+    private var content: (Int) -> AnyView = { _ in AnyView(EmptyView()) }
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        view.backgroundColor = .clear
+    }
+
+    override func viewDidLayoutSubviews() {
+        super.viewDidLayoutSubviews()
+        for subview in view.subviews { subview.frame = view.bounds }
+    }
+
+    func update(
+        selectedIndex index: Int,
+        count: Int,
+        environment: EnvironmentValues,
+        content: @escaping (Int) -> AnyView
+    ) {
+        self.environment = environment
+        self.content = content
+        for (stale, removed) in tabs where stale >= count {
+            tabs[stale] = nil
+            tearDown(removed)
+        }
+        if let selectedIndex, tabs[selectedIndex] == nil { self.selectedIndex = nil }
+        // hidden tabs too, so a tab coming back already shows the latest items and environment
+        for (tabIndex, existing) in tabs { existing.host.rootView = rootView(tabIndex, existing) }
+        guard (0..<count).contains(index), index != selectedIndex else { return }
+
+        let previous = selectedIndex.flatMap { tabs[$0] }
+        selectedIndex = index
+        let selected = tabs[index] ?? makeTab(index)
+        attach(selected)
+
+        guard let previous, view.window != nil else {
+            selected.motion.visible = true
+            previous.map(leave)
+            return
+        }
+        previous.host.view.isUserInteractionEnabled = false
+        // a frame at the start values first, so a tab created just now fades in too
+        DispatchQueue.main.async {
+            selected.motion.visible = true
+            previous.motion.visible = false
+        }
+        DispatchQueue.main.asyncAfter(deadline: .now() + Self.switchDuration) { [weak self] in
+            self?.leave(previous)
+        }
+    }
+
+    private func makeTab(_ index: Int) -> Tab {
+        let tab = Tab()
+        let host = UIHostingController(rootView: rootView(index, tab))
+        host.view.backgroundColor = .clear
+        addChild(host)
+        host.didMove(toParent: self)
+        tab.host = host
+        tabs[index] = tab
+        return tab
+    }
+
+    private func rootView(_ index: Int, _ tab: Tab) -> AnyView {
+        AnyView(TabCard(motion: tab.motion, content: content(index)).environment(\.self, environment))
+    }
+
+    private func attach(_ tab: Tab) {
+        let hostView: UIView = tab.host.view
+        hostView.isUserInteractionEnabled = true
+        hostView.frame = view.bounds
+        if hostView.superview === view {
+            view.bringSubviewToFront(hostView)
+        } else {
+            view.addSubview(hostView)
+        }
+    }
+
+    /// Off the window once hidden; a tab selected again in the meantime stays.
+    private func leave(_ tab: Tab) {
+        guard selectedIndex.flatMap({ tabs[$0] }) !== tab else { return }
+        tab.host.view.removeFromSuperview()
+    }
+
+    private func tearDown(_ tab: Tab) {
+        tab.host.willMove(toParent: nil)
+        tab.host.view.removeFromSuperview()
+        tab.host.removeFromParent()
+    }
+}
+
+private final class TabMotion: ObservableObject {
+    @Published var visible = false
+}
+
+/// The tab switch: 0.97 scale + fade over 200ms, both ways (Compose's tab enter / exit transitions).
+private struct TabCard: View {
+    @ObservedObject var motion: TabMotion
+    let content: AnyView
+
+    var body: some View {
+        content
+            .opacity(motion.visible ? 1 : 0)
+            .scaleEffect(motion.visible ? 1 : 0.97)
+            .animation(.easeInOut(duration: 0.2), value: motion.visible)
+    }
+}
+
 /// Bottom safe-area inset (home indicator).
 private func safeAreaBottomInset() -> CGFloat {
     let bottomInset = UIApplication.shared.connectedScenes

package/ios/Navigation/BottomTab/BottomTabBar.swift

@@ -20,6 +20,7 @@ public struct BottomTabItem: Identifiable {
     public let showDot: Bool
     public let badgeLabel: String?
     public let options: NavigationOptions?
+    public let initialParams: Any?
     public let screen: () -> AnyView
 
     public init(
@@ -29,6 +30,7 @@ public struct BottomTabItem: Identifiable {
         showDot: Bool = false,
         badgeLabel: String? = nil,
         options: NavigationOptions? = nil,
+        initialParams: Any? = nil,
         @ViewBuilder screen: @escaping () -> some View
     ) {
         self.name = name
@@ -37,6 +39,7 @@ public struct BottomTabItem: Identifiable {
         self.showDot = showDot
         self.badgeLabel = badgeLabel
         self.options = options
+        self.initialParams = initialParams
         self.screen = { AnyView(screen()) }
     }
 }

package/ios/Navigation/Component/FloatingButton.swift

@@ -7,7 +7,6 @@
 //
 
 import SwiftUI
-import Combine
 
 public enum FABSize {
     case small
@@ -66,14 +65,10 @@ public struct FabProps {
 }
 
 public struct FloatingButton: View {
+    @State private var isExpanded: Bool = true
     @State private var lastScrollOffset: CGFloat = 0
-    @State private var isExpanded: Bool = false
-    @State private var internalScrollOffset: CGFloat = 0
-    @State private var showText: Bool = true
-    @State private var fullWidth: CGFloat? = nil
-    @State private var currentWidth: CGFloat = 0
-    @State private var lastDirection: String? = nil
-    
+    @State private var settleScroll: Task<Void, Never>?
+
     private let props: FabProps
     private var keyboardOffset: CGFloat
     private var scrollOffset: CGFloat
@@ -129,57 +124,40 @@ public struct FloatingButton: View {
         .onTapGesture {
             onClick?()
         }
+        .accessibilityElement(children: .combine)
+        .accessibilityAddTraits(.isButton)
         .padding(.bottom, bottomPadding)
         .frame(alignment: position == .center ? .center : .trailing)
-        .onAppear {
-            internalScrollOffset = scrollOffset
-            isExpanded = label != nil
-        }
-        .onReceive(Just(scrollOffset)) { newValue in
-            let direction = newValue > internalScrollOffset ? "down" : "up"
+        .onAppear { lastScrollOffset = scrollOffset }
+        .onChange(of: scrollOffset, perform: updateExpanded)
+        .onDisappear { settleScroll?.cancel() }
+    }
 
-            if direction != lastDirection {
-                lastDirection = direction
-                if direction == "down" {
-                    withAnimation(.easeOut(duration: 0.1)) {
-                        isExpanded = false
-                    }
-                    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
-                        showText = false
-                    }
-                } else {
-                    showText = true
-                    withAnimation(.easeIn(duration: 0.1)) {
-                        isExpanded = true
-                    }
-                    
-                }
-            }
+    /// Compose's `collectLatest { isExpanded = new <= last; delay(100); last = new }`: the label
+    /// shows while the content scrolls back up, and the reference only moves once the scroll pauses.
+    private func updateExpanded(_ offset: CGFloat) {
+        let expanded = offset <= lastScrollOffset
+        if expanded != isExpanded {
+            withAnimation(.linear(duration: 0.1)) { isExpanded = expanded }
+        }
+        settleScroll?.cancel()
+        settleScroll = Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 100_000_000)
+            guard !Task.isCancelled else { return }
+            lastScrollOffset = offset
         }
     }
-    
+
     private var content: some View {
         HStack(spacing: 0) {
-            ImageView(icon ?? "")
-                .scaledToFit()
-                .frame(width: iconSize, height: iconSize)
-                .foregroundColor(iconColor)
-            
-            if let label = label {
-                if showText {
-                    Spacer().frame(width: 8)
-                    MomoText(label, typography: .actionDefaultBold, color: .white, maxLines: 1)
-                        .background(
-                            GeometryReader { geo in
-                                Color.clear.onAppear {
-                                    fullWidth = geo.size.width
-                                }
-                            }
-                        )
-                        .opacity(isExpanded ? 1 : 0)
-                }
-            }
+            // Compose `Icon`: an icon key or an https URL, tinted
+            Icon(source: icon ?? "", size: iconSize ?? defaultIconSize, color: iconColor)
 
+            if let label, isExpanded {
+                MomoText(label, typography: .actionDefaultBold, color: .white, maxLines: 1)
+                    .padding(.leading, 12)
+                    .transition(.opacity.combined(with: .move(edge: .leading)))
+            }
         }
     }
 }

package/ios/Navigation/Component/Header.swift

@@ -273,11 +273,18 @@ public struct HeaderRightWidthKey: PreferenceKey {
 }
 
 /// Compose `SearchAnimated`: a header search fills from surface to the screen background over
-/// the scroll that lifts it into the bar.
-func headerSearchProps(_ props: InputSearchProps, scroll: CGFloat, layout: ScreenLayout, theme: Theme) -> InputSearchProps {
-    guard props.backgroundColor == nil else { return props }
-    let collapsedTop = max(layout.headerStatusBarHeight + (layout.headerBarHeight - HEADER_HEIGHT) / 2, 1)
+/// the scroll that lifts it into the bar, and its button text pops the screen.
+func headerSearchProps(
+    _ props: InputSearchProps,
+    scroll: CGFloat,
+    layout: ScreenLayout,
+    theme: Theme,
+    pop: (() -> Void)?
+) -> InputSearchProps {
     var themed = props
+    if !props.hasButtonTextAction, let pop { themed.onPressButtonText = pop }
+    guard props.backgroundColor == nil else { return themed }
+    let collapsedTop = max(layout.headerStatusBarHeight + (layout.headerBarHeight - HEADER_HEIGHT) / 2, 1)
     themed.backgroundColor = theme.colors.background.surface
         .lerp(to: theme.colors.background.default, max(scroll, 0) / collapsedTop)
     return themed
@@ -338,6 +345,7 @@ public struct NavigationHeader: View {
 
     @Environment(\.screenLayout) private var layout
     @Environment(\.appTheme) private var theme
+    @OptionalEnvironmentObject private var navigator: Navigator?
     @State private var headerRightWidth: CGFloat = 0
 
     /// iPhone Duo side bar holds back and the toolkit; a custom header right stays in the bar.
@@ -437,7 +445,13 @@ public struct NavigationHeader: View {
     @ViewBuilder
     private func titleArea(centered: Bool) -> some View {
         if let inputSearchProps {
-            InputSearch(props: headerSearchProps(inputSearchProps, scroll: scrollState, layout: layout, theme: theme))
+            InputSearch(props: headerSearchProps(
+                inputSearchProps,
+                scroll: scrollState,
+                layout: layout,
+                theme: theme,
+                pop: navigator.map { navigator in { navigator.pop() } }
+            ))
         } else {
             switch headerTitle {
             case let .user(data)?:

package/ios/Navigation/Component/HeaderRight.swift

@@ -191,38 +191,64 @@ struct Toolkit: View {
         return json["response"]
     }
 
+    private typealias MaxApiRequest = (MaxApi, [String: Any?], @escaping ([String: Any?]?) -> Void) -> Void
+
+    /// Through `composeApi` while the host still passes one, else `maxApi` (Compose `IMaxApi`).
+    /// Hosts may answer off the main thread, so the response is handed back on it.
+    private func request(
+        _ funcName: String,
+        _ params: [String: Any],
+        maxApi maxApiRequest: MaxApiRequest,
+        onResponse: @escaping (Any?) -> Void = { _ in }
+    ) {
+        if let composeApi = environment.composeApi {
+            _ = composeApi.request(funcName: funcName, params: params) { response in
+                let value = parseResponse(response)
+                DispatchQueue.main.async { onResponse(value) }
+            }
+        } else if let maxApi = environment.maxApi {
+            maxApiRequest(maxApi, params.mapValues { $0 as Any? }) { data in
+                let value = data?["response"] ?? nil
+                DispatchQueue.main.async { onResponse(value) }
+            }
+        }
+    }
+
     // MARK: Actions
 
     private func loadFavoriteState() {
-        _ = environment.composeApi?.request(
-            funcName: "isFavoriteApp",
-            params: ["code": apiValue(context?.appCode)]
+        request(
+            "isFavoriteApp",
+            ["code": apiValue(context?.appCode)],
+            maxApi: { $0.isFavoriteApp($1, callback: $2) }
         ) { response in
-            isFavorite = parseResponse(response) as? Bool == true
+            isFavorite = response as? Bool == true
         }
     }
 
     private func onPressShortcut() {
-        _ = environment.composeApi?.request(
-            funcName: "onToolAction",
-            params: ["item": ["key": "onFavorite"], "context": contextMap]
+        request(
+            "onToolAction",
+            ["item": ["key": "onFavorite"], "context": contextMap],
+            maxApi: { $0.onToolAction($1, callback: $2) }
         ) { response in
-            if let result = parseResponse(response) as? [String: Any], result["success"] as? Bool == true {
+            if let result = response as? [String: Any], result["success"] as? Bool == true {
                 isFavorite.toggle()
             }
         }
     }
 
     private func onPressMore() {
-        _ = environment.composeApi?.request(
-            funcName: "showTools",
-            params: [
+        request(
+            "showTools",
+            [
                 "useSystemTools": headerRight.useSystemTools,
                 "tools": headerRight.tools.map { $0.toMap() },
                 "context": contextMap
-            ]
+            ],
+            maxApi: { $0.showTools($1, callback: $2) }
         ) { response in
-            if let tool = parseResponse(response) as? String {
+            if let tool = response as? String {
                 headerRight.toolCallback?(tool)
             }
         }
@@ -230,23 +256,26 @@ struct Toolkit: View {
 
     private func onPressHelpCenter() {
         guard context != nil else { return }
-        _ = environment.composeApi?.request(
-            funcName: "showHelpCenter",
-            params: [
+        request(
+            "showHelpCenter",
+            [
                 "appId": apiValue(context?.appId),
                 "code": apiValue(context?.appCode),
                 "name": apiValue(context?.appName),
                 "icon": apiValue(context?.appIcon),
                 "description": apiValue(context?.description)
-            ]
-        ) { _ in }
+            ],
+            maxApi: { $0.showHelpCenter($1, callback: $2) }
+        )
     }
 
     private func onPressClose() {
         if headerRight.useCloseIcon {
             environment.requestDismiss()
+        } else if let composeApi = environment.composeApi {
+            _ = composeApi.request(funcName: "dismissAll", params: nil) { _ in }
         } else {
-            _ = environment.composeApi?.request(funcName: "dismissAll", params: nil) { _ in }
+            environment.maxApi?.dismissAll(completion: nil)
         }
     }
 

package/ios/Navigation/Component/SnackBar.swift

@@ -50,6 +50,7 @@ public struct SnackBar {
 /// Self-animating container. Slides the content up on appear, schedules an
 /// auto-dismiss after `duration`, and animates out before removing the overplay.
 struct SnackBarView: View {
+    let overplayId: UUID
     let snackBar: SnackBar
     /// Distance from the window bottom to the top of the screen's footer, or the navigation bar
     /// inset without one (Compose's `footerHeight` offset).
@@ -121,7 +122,7 @@ struct SnackBarView: View {
             offsetY = max(contentHeight, 200) + bottomInset
         }
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
-            navigator.finishOverplayDismiss()
+            navigator.finishOverplayDismiss(id: overplayId)
         }
     }
 
@@ -133,7 +134,7 @@ struct SnackBarView: View {
         guard let duration = snackBar.duration else { return }
         let workItem = DispatchWorkItem {
             // Only auto-dismiss if this snack bar is still the active overplay.
-            if navigator.overplay?.type == .snackBar {
+            if navigator.overplay?.id == overplayId {
                 navigator.hideSnackBar()
             }
         }

package/ios/Navigation/ModalScreen.swift

@@ -10,6 +10,7 @@
 import SwiftUI
 
 struct ModalScreen<Content: View>: View {
+    let overplayId: UUID
     let barrierDismissible: Bool
     let content: () -> Content
 
@@ -74,7 +75,7 @@ struct ModalScreen<Content: View>: View {
             contentOpacity = 0
         }
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
-            navigator.finishOverplayDismiss()
+            navigator.finishOverplayDismiss(id: overplayId)
         }
     }
 }

package/ios/Navigation/NavigationContainer.swift

@@ -168,12 +168,13 @@ private struct OverplayHost: View {
         // the Navigator before the item is removed (mirrors Compose's overplay).
         switch item.type {
         case .modal:
-            ModalScreen(barrierDismissible: item.barrierDismissible) {
+            ModalScreen(overplayId: item.id, barrierDismissible: item.barrierDismissible) {
                 item.content()
             }
             .id(item.id)
         case .bottomSheet:
             BottomSheetView(
+                overplayId: item.id,
                 header: item.header ?? .title(),
                 isSurface: item.isSurface,
                 barrierDismissible: item.barrierDismissible,
@@ -186,7 +187,7 @@ private struct OverplayHost: View {
             .id(item.id)
         case .snackBar:
             if let snackBar = item.snackBar {
-                SnackBarView(snackBar: snackBar, bottomInset: navigator.snackBarBottomInset())
+                SnackBarView(overplayId: item.id, snackBar: snackBar, bottomInset: navigator.snackBarBottomInset())
                     .id(item.id)
             }
         }

package/ios/Navigation/Navigator.swift

@@ -238,20 +238,19 @@ public final class Navigator: ObservableObject {
             // Mirrors Kotlin: a snackbar doesn't block back-navigation, so popping
             // while one is showing pops the screen underneath and clears the
             // snackbar immediately, without playing its dismiss animation.
-            overplayDismissHandler = nil
-            overplay = nil
+            replaceOverplay(with: nil)
             guard popScreen() else {
                 callback?()
                 return
             }
             popStep(remaining: remaining - 1, callback: callback)
-        } else if overplay != nil {
+        } else if let closing = overplay?.id {
             hideOverplay()
             DispatchQueue.main.asyncAfter(deadline: .now() + Self.overplayDismissDelay) { [weak self] in
                 guard let self else { return }
                 // The component reports back through `finishOverplayDismiss` once its exit
                 // animation ends; clear it here if it never did, so the step is not wasted.
-                if self.overplay != nil { self.finishOverplayDismiss() }
+                self.finishOverplayDismiss(id: closing)
                 self.popStep(remaining: remaining - 1, callback: callback)
             }
         } else {
@@ -302,6 +301,11 @@ public final class Navigator: ObservableObject {
     }
 
     public func onBackSafe(callback: (() -> Void)? = nil) {
+        // An open modal or bottom sheet takes the back first (their BackHandler in Compose).
+        if let overplay, overplay.type != .snackBar {
+            pop(1, callback: callback)
+            return
+        }
         let latest = currentScreen()
         if let tabBackHandler, tabBackHandler.screenId == -1 || tabBackHandler.screenId == latest?.id {
             tabBackHandler.handler()
@@ -420,14 +424,13 @@ public final class Navigator: ObservableObject {
         barrierDismissible: Bool = true,
         onDismiss: (() -> Void)? = nil
     ) {
-        overplayDismissHandler = nil
-        overplay = OverplayItem(
+        replaceOverplay(with: OverplayItem(
             type: .modal,
             content: { AnyView(content()) },
             barrierDismissible: barrierDismissible,
             onDismiss: onDismiss,
             screenId: entries.last?.id
-        )
+        ))
     }
 
     public func showBottomSheet<V: View>(
@@ -440,8 +443,7 @@ public final class Navigator: ObservableObject {
         useBottomInset: Bool = true,
         footer: (() -> AnyView)? = nil
     ) {
-        overplayDismissHandler = nil
-        overplay = OverplayItem(
+        replaceOverplay(with: OverplayItem(
             type: .bottomSheet,
             content: { AnyView(content()) },
             barrierDismissible: barrierDismissible,
@@ -452,20 +454,19 @@ public final class Navigator: ObservableObject {
             useBottomInset: useBottomInset,
             footer: footer,
             screenId: entries.last?.id
-        )
+        ))
     }
 
     /// Mirrors Compose's `showSnackBar(snackBar:)`.
     public func showSnackBar(_ snackBar: SnackBar, onDismiss: (() -> Void)? = nil) {
-        overplayDismissHandler = nil
-        overplay = OverplayItem(
+        replaceOverplay(with: OverplayItem(
             type: .snackBar,
             content: { AnyView(EmptyView()) },
             barrierDismissible: false,
             onDismiss: onDismiss,
             snackBar: snackBar,
             screenId: entries.last?.id
-        )
+        ))
     }
 
     // MARK: Overplay dismissal
@@ -480,10 +481,23 @@ public final class Navigator: ObservableObject {
     /// `hardClearAfterDismiss`). Called by a component once its exit animation
     /// has completed.
     public func finishOverplayDismiss() {
-        let dismissCallback = overplay?.onDismiss
+        replaceOverplay(with: nil)
+    }
+
+    /// Same, but only while `id` is still the overplay: an exit that ends after a newer overplay
+    /// took its place must not take that one down.
+    public func finishOverplayDismiss(id: UUID) {
+        guard overplay?.id == id else { return }
+        replaceOverplay(with: nil)
+    }
+
+    /// A replaced overplay counts as dismissed (Compose disposes it), so its `onDismiss` fires once,
+    /// whether it was still closing or not.
+    private func replaceOverplay(with item: OverplayItem?) {
+        let replaced = overplay
         overplayDismissHandler = nil
-        overplay = nil
-        dismissCallback?()
+        overplay = item
+        replaced?.onDismiss?()
     }
 
     public func hideOverplay() {

package/ios/Navigation/StackScreen.swift

@@ -116,7 +116,6 @@ public struct StackScreen<Content: View>: View {
     @State private var isBottomTabRoot: Bool = false
     @State private var headerHide: CGFloat = 0
     @State private var lastScrollOffset: CGFloat = 0
-    @State private var headerSettle: Task<Void, Never>?
     @State private var footerHeight: CGFloat = 0
 
     @Environment(\.applicationEnvironment) private var appEnv
@@ -126,9 +125,7 @@ public struct StackScreen<Content: View>: View {
     @Environment(\.appTheme) private var theme
     @OptionalEnvironmentObject private var navigation: Navigation?
 
-    // Auto-tracking state (Compose's `remember { ScreenTrackingState() }` + the once-computed action).
-    @State private var trackingState = ScreenTrackingState()
-    @State private var trackingAction: String = ScreenTracker.getLastScreenName() != nil ? "push" : "back"
+    @State private var tracking: Task<Void, Never>?
 
     /// Compose's `headerOpacity()`: 0 over a banner or transparent header, 1 once the bar is opaque.
     private var opacity: CGFloat {
@@ -189,25 +186,21 @@ public struct StackScreen<Content: View>: View {
             return
         }
         headerHide = min(max(headerHide + delta, 0), layout.headerHeight)
-        settleHeaderWhenScrollStops()
-    }
-
-    /// A half-shown header settles fully in or out. SwiftUI before iOS 18 reports no scroll
-    /// phase, so the scroll counts as ended once the offset stops changing.
-    private func settleHeaderWhenScrollStops() {
-        headerSettle?.cancel()
-        headerSettle = Task { @MainActor in
-            try? await Task.sleep(nanoseconds: 150_000_000)
-            guard !Task.isCancelled else { return }
-            let height = layout.headerHeight
-            // within the first header height the header still sits on the content
-            guard scrollOffset >= height, headerHide > 0, headerHide < height else { return }
-            withAnimation(.easeOut(duration: 0.2)) {
-                headerHide = headerHide > height / 2 ? height : 0
-            }
+    }
+
+    /// A half-shown header settles fully in or out once the scroll comes to rest.
+    private func settleHeader() {
+        let height = layout.headerHeight
+        // within the first header height the header still sits on the content
+        guard useQuickReturn, scrollOffset >= height, headerHide > 0, headerHide < height else { return }
+        withAnimation(.easeOut(duration: 0.2)) {
+            headerHide = headerHide > height / 2 ? height : 0
         }
     }
 
+    /// Compose snaps the animated search fully in or out when the scroll stops.
+    private var searchSnapDistance: CGFloat? { inputSearchType == .animated ? HEADER_HEIGHT : nil }
+
     private var keyboardSize: CGFloat { useAvoidKeyboard ? max(keyboardHeight, 0) : 0 }
 
     /// What the footer, tab bar or home indicator takes from the bottom of the window, gap included.
@@ -338,35 +331,50 @@ public struct StackScreen<Content: View>: View {
         }
         .onAppear(perform: reportBottomObstruction)
         .onChange(of: bottomObstruction) { _ in reportBottomObstruction() }
-        .task(id: screenName) {
+        .onAppear(perform: startTracking)
+        .onChange(of: screenName) { _ in startTracking() }
+        .onDisappear { tracking?.cancel() }
+    }
+
+    /// Compose tracks from a `LaunchedEffect` with `remember`ed state, so every visit — first show, a
+    /// pop back, a tab switch — starts over with fresh state. A covered hosting controller keeps its
+    /// `@State` and doesn't re-run `.task`, so the run hangs off appear / disappear instead.
+    private func startTracking() {
+        tracking?.cancel()
+        let state = ScreenTrackingState()
+        let action = ScreenTracker.getLastScreenName() != nil ? "push" : "back"
+        let maxApi = appEnv.maxApi
+        let context = appEnv.applicationContext
+        let screenName = screenName
+        tracking = Task { @MainActor in
             ScreenTracker.trackScreenNavigated(
-                maxApi: appEnv.maxApi,
-                context: appEnv.applicationContext,
+                maxApi: maxApi,
+                context: context,
                 screenName: screenName,
-                action: trackingAction,
-                state: trackingState
+                action: action,
+                state: state
             )
             do {
                 try await Task.sleep(nanoseconds: 2_000_000_000)
             } catch {
                 return
             }
-            let loadTime = ScreenTracker.now() - trackingState.time
+            let loadTime = ScreenTracker.now() - state.time
             ScreenTracker.trackScreenDisplayed(
-                maxApi: appEnv.maxApi,
-                context: appEnv.applicationContext,
+                maxApi: maxApi,
+                context: context,
                 screenName: screenName,
                 duration: loadTime,
-                state: trackingState
+                state: state
             )
-            let interactionTime = ScreenTracker.now() - trackingState.time
+            let interactionTime = ScreenTracker.now() - state.time
             ScreenTracker.trackScreenInteracted(
-                maxApi: appEnv.maxApi,
-                context: appEnv.applicationContext,
+                maxApi: maxApi,
+                context: context,
                 screenName: screenName,
                 duration: interactionTime - loadTime,
                 totalDuration: interactionTime,
-                state: trackingState
+                state: state
             )
         }
     }
@@ -385,6 +393,8 @@ public struct StackScreen<Content: View>: View {
                     scrollToTopCallback: scrollToTopCallback,
                     animatedSearchInset: animatedSearchInset,
                     bottomInset: duoTabBarInsets.overlay,
+                    snapDistance: searchSnapDistance,
+                    onScrollIdle: settleHeader,
                     content: { animatedHeroBody(animatedHeader) }
                 )
                 .edgesIgnoringSafeArea(.all)
@@ -419,6 +429,8 @@ public struct StackScreen<Content: View>: View {
                     scrollToTopCallback: scrollToTopCallback,
                     animatedSearchInset: animatedSearchInset,
                     bottomInset: duoTabBarInsets.overlay,
+                    snapDistance: searchSnapDistance,
+                    onScrollIdle: settleHeader,
                     content: { duoInsetContent }
                 )
                 .edgesIgnoringSafeArea(.all)
@@ -438,6 +450,8 @@ public struct StackScreen<Content: View>: View {
                     scrollToTopCallback: scrollToTopCallback,
                     topInset: layout.headerHeight - layout.insets.top,
                     bottomInset: duoTabBarInsets.overlay,
+                    snapDistance: searchSnapDistance,
+                    onScrollIdle: settleHeader,
                     content: content
                 )
 
@@ -483,6 +497,8 @@ public struct StackScreen<Content: View>: View {
                 scrollToTopCallback: scrollToTopCallback,
                 animatedSearchInset: animatedSearchInset,
                 bottomInset: duoTabBarInsets.overlay,
+                snapDistance: searchSnapDistance,
+                onScrollIdle: settleHeader,
                 content: content
             )
         }
@@ -563,11 +579,30 @@ private struct StackScreenContent<Content: View>: View {
     var topInset: CGFloat = 0
     /// Room for a bar that overlays the content (iPhone Duo floating tab bar).
     var bottomInset: CGFloat = 0
+    /// Compose's animated-search snap: a scroll that comes to rest part way through this distance
+    /// finishes the move, up or back down.
+    var snapDistance: CGFloat? = nil
+    var onScrollIdle: (() -> Void)? = nil
     let content: () -> Content
 
     private let topAnchorID = "stack_screen_top_anchor"
     private let scrollSpace = "stack_screen_scroll_space"
 
+    @State private var scrollView = WeakScrollView()
+
+    private func scrollDidRest() {
+        onScrollIdle?()
+        guard let snapDistance, scrollOffset > 0, scrollOffset < snapDistance,
+              let scrollView = scrollView.value else { return }
+        // UIKit, not `ScrollViewProxy.scrollTo`: SwiftUI keeps re-applying a scrollTo target while the
+        // content above it resizes, which this content does as the search inset shrinks with the scroll
+        let target = scrollOffset < snapDistance / 2 ? 0 : snapDistance
+        scrollView.setContentOffset(
+            CGPoint(x: scrollView.contentOffset.x, y: target - scrollView.adjustedContentInset.top),
+            animated: true
+        )
+    }
+
     var body: some View {
         if scrollable {
             ScrollViewReader { proxy in
@@ -587,6 +622,7 @@ private struct StackScreenContent<Content: View>: View {
                                         scrollOffset = -minY
                                     }
                             })
+                            .background(ScrollViewProbe { scrollView.value = $0 })
 
                         if animatedSearchInset + topInset > 0 {
                             Spacer().frame(height: animatedSearchInset + topInset)
@@ -602,6 +638,7 @@ private struct StackScreenContent<Content: View>: View {
                     }
                 }
                 .coordinateSpace(name: scrollSpace)
+                .modifier(ScrollRest(offset: scrollOffset, onRest: scrollDidRest))
                 // Status-bar tap (MoMoStatusBarTap swizzle) scrolls to top and notifies the consumer.
                 .onReceive(NotificationCenter.default.publisher(for: MoMoStatusBarTap.notificationName)) { _ in
                     withAnimation {
@@ -618,6 +655,74 @@ private struct StackScreenContent<Content: View>: View {
     }
 }
 
+private final class WeakScrollView {
+    weak var value: UIScrollView?
+}
+
+/// Finds the UIScrollView behind the enclosing SwiftUI `ScrollView` once placed in its content.
+private struct ScrollViewProbe: UIViewRepresentable {
+    let found: (UIScrollView) -> Void
+
+    func makeUIView(context: Context) -> Probe { Probe(found: found) }
+
+    func updateUIView(_ uiView: Probe, context: Context) {}
+
+    final class Probe: UIView {
+        let found: (UIScrollView) -> Void
+
+        init(found: @escaping (UIScrollView) -> Void) {
+            self.found = found
+            super.init(frame: .zero)
+            isUserInteractionEnabled = false
+        }
+
+        required init?(coder: NSCoder) { nil }
+
+        override func didMoveToWindow() {
+            super.didMoveToWindow()
+            var view = superview
+            while let current = view, !(current is UIScrollView) { view = current.superview }
+            if let scrollView = view as? UIScrollView { found(scrollView) }
+        }
+    }
+}
+
+/// Calls `onRest` once the scroll comes to rest. Scroll phases need iOS 18; before that the scroll
+/// counts as ended once the offset stops changing, which a finger held still also looks like.
+private struct ScrollRest: ViewModifier {
+    let offset: CGFloat
+    let onRest: () -> Void
+
+    @State private var pending: Task<Void, Never>?
+
+    func body(content: Content) -> some View {
+        #if compiler(>=6.0)
+        if #available(iOS 18.0, *) {
+            content.onScrollPhaseChange { _, phase in
+                if phase == .idle { onRest() }
+            }
+        } else {
+            debounced(content)
+        }
+        #else
+        debounced(content)
+        #endif
+    }
+
+    private func debounced(_ content: Content) -> some View {
+        content
+            .onChange(of: offset) { _ in
+                pending?.cancel()
+                pending = Task { @MainActor in
+                    try? await Task.sleep(nanoseconds: 150_000_000)
+                    guard !Task.isCancelled else { return }
+                    onRest()
+                }
+            }
+            .onDisappear { pending?.cancel() }
+    }
+}
+
 // MARK: - Animated search header
 
 /// Compose's `SearchAnimated`: the search slides from below the header (scroll 0) up into the bar
@@ -633,6 +738,7 @@ private struct SearchAnimatedHeader: View {
 
     @Environment(\.screenLayout) private var layout
     @Environment(\.appTheme) private var theme
+    @OptionalEnvironmentObject private var navigator: Navigator?
 
     var body: some View {
         let scroll = max(scrollOffset, 0)
@@ -650,12 +756,20 @@ private struct SearchAnimatedHeader: View {
             ? Spacing.M
             : headerRightWidth + (hasHeaderRight ? Spacing.M * 2 : Spacing.M))
 
-        let top = min(max(maxTop - scroll, minTop), maxTop)
-        let start = min(max(minSide + scroll, minSide), maxStart)
-        let end = min(max(minSide + scroll, minSide), maxEnd)
+        // one progress for all three, so the field docks with its final insets and never covers the toolkit
+        let progress = min(scroll / HEADER_HEIGHT, 1)
+        let top = maxTop + (minTop - maxTop) * progress
+        let start = minSide + (maxStart - minSide) * progress
+        let end = minSide + (maxEnd - minSide) * progress
 
         // padding, not a Spacer: on the iPhone Duo status bar row the collapsed top is above the safe area
-        InputSearch(props: headerSearchProps(props, scroll: scroll, layout: layout, theme: theme))
+        InputSearch(props: headerSearchProps(
+            props,
+            scroll: scroll,
+            layout: layout,
+            theme: theme,
+            pop: navigator.map { navigator in { navigator.pop() } }
+        ))
             .frame(height: HEADER_HEIGHT)
             .padding(.leading, start)
             .padding(.trailing, end)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@momo-kits/native-kits",
-  "version": "0.167.1-duo.21-debug",
+  "version": "0.167.1-duo.22-debug",
   "private": false,
   "dependeNavigationncies": {},
   "devDependencies": {},