@momo-kits/native-kits 0.167.1-duo.7 → 0.167.1-duo.8

package/CLAUDE.md

@@ -65,10 +65,13 @@ Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do
 
 - `layout/ScreenLayout.kt`: `getScreenLayout()` returns window size, raw top/bottom + side insets, `contentWidth`, header geometry, the iPhone Duo `sideBar` and `duoTopInset`. `NavigationContainer` computes it once and provides `LocalScreenLayout`; reactive to fold/unfold and rotation (window size + `WindowInsets`). Metrics (`DuoMetrics`, 72pt iPhone header floor, 20pt status-bar threshold) mirror RN `Layout/utils.ts` — change both together.
 - iPhone-only: everything gates on `isPhoneIdiom()` (`platform/`), never on "iOS", so iPad windows keep the regular layout. Two detectors, as in RN: `isIPhoneDuo` (window aspect < 1.6 or asymmetric side insets) drives layout; `isIPhoneDuoDevice` (short side of screen or window > 440, RN `device.ts`) drives popups, modal and bottom sheet.
-- Header height is `headerHeight` (not `AppStatusBar + HEADER_HEIGHT`); the bar row is `headerBarHeight`. When the status bar is off the top edge (iPhone landscape, iPhone Duo) `headerStatusBarHeight` is 0 so the title stays centered.
-- iPhone Duo with a side strip ≥ 60pt: back + toolkit leave the bar for `HeaderSideBar` (`navigation/component/SideBar.kt`, 48pt glass controls); custom header-right stays in the bar. The column starts at 120pt when the inner display is landscape (height ≥ 600), else 170pt, or below the header when the status bar is on top; UIKit's `statusBarFrame` is useless on Duo. Unlike RN it is clamped 24pt above footer / tab bar / rail.
-- Tab bar on Duo is `bottomtab/DuoTabBar.kt`: a rail in the side strip (anchored 24pt from the bottom, QR below it) or, without a side bar, a floating bar spanning 6/8 grid columns. Both overlay the content; `duoFloatingTabBarInset` pads tab content, footer and FAB.
-- Glass header: on Duo with a side bar, Default/Extended headers without search and with a `ScrollState` let content scroll under the bar (`usesDuoGlassHeader`); the bar fades in a translucent surface + hairline over 16pt (Compose has no backdrop blur — RN's fallback look), the gradient scrolls away / collapses.
+- Header height is `headerHeight` (not `AppStatusBar + HEADER_HEIGHT`); the bar row is `headerBarHeight` and starts `headerStatusBarHeight` below the window top. When the status bar is off the top edge (iPhone landscape, iPhone Duo) `headerStatusBarHeight` is 0 so the title stays centered — except on the Duo outer display in portrait, where the header is 76pt and the row starts at 14pt so the title centers on the camera punchout.
+- iPhone Duo with a side strip ≥ 60pt: back + toolkit leave the bar for `HeaderSideBar` (`navigation/component/SideBar.kt`, 48pt glass controls); custom header-right stays in the bar. `sideBar.top` is 170pt in portrait, 120pt on the inner display in landscape (height ≥ 600), 24pt on the outer display in landscape, or below the header when the status bar is on top; UIKit's `statusBarFrame` is useless on Duo. Unlike RN the column is clamped above footer (24pt gap) / rail (12pt gap).
+- Reserved regions (iOS 27.1 `reservedRegionsOfKind:`, reached through the ObjC runtime so older SDKs still build): a probe `UIView` (`platform/ReservedRegions.ios.kt` on the Compose root view; `ReservedRegionsProbe` inside SwiftUI `momoScreenLayout()`) re-reads them in `layoutSubviews`, which UIKit re-runs when they change. They push `sideBar.top` below the status cluster as it grows for calls / Live Activities, and `sideBar.bottom` (≥ 24pt) above a camera at the bottom end of the strip.
+- Tab bar on Duo is `bottomtab/DuoTabBar.kt`: a rail in the side strip (`sideBar.bottom` above the window bottom, QR below it) or, without a side bar, a floating bar spanning 6/8 grid columns. Both overlay the content; `duoFloatingTabBarInset` pads tab content, footer and FAB.
+- Bar compression (`bottomtab/DuoBarCompression.kt`, HIG "Vertical controls"): when toolbar + rail don't fit in the strip, one is compressed — the toolkit into a `navigation_menu` button, the rail into one button showing the current tab — and tapping it swaps them; `BottomTab(compressionBehavior)` picks which starts compressed. If neither fits beside the other compressed, both rest compressed and a tap opens one for a moment. Side bar columns report their full height so the decision follows each screen's toolkit.
+- Glass header: on Duo with a side bar, Default/Extended headers without search and with a `ScrollState` let content scroll under the bar (`usesDuoGlassHeader`); the bar fades in a translucent surface + hairline over 16pt (Compose has no backdrop blur — RN's fallback look), the gradient leaves with the content.
+- Quick return header: glass headers and Animated headers (with a `ScrollState`) on the Duo side bar layout slide out with the content and back in on a reverse scroll; a half-shown header settles in or out once the scroll stops. The side bar is drawn apart from the header, so it stays put.
 - Overlays on Duo: popups cap at 440pt wide and the room between `duoTopInset` and the bottom inset (body scrolls, actions stay); modal centers inside that room; bottom sheet uses the window height, centers at width ≥ 600 and pads by side insets in landscape.
 - Font scale deliberately uses the short side (`min(w, h)`), unlike RN which reads the window width — landscape must not inflate every font.
 - `StackScreen` pads content/footer/search/FAB by the side insets and provides an inset-consumed layout to its content; a bottom-tab root stays full width (tab bar + each tab's StackScreen handle insets). Grid columns use `contentWidth`.

package/ios/Application/Layout/ScreenLayout.swift

@@ -18,6 +18,8 @@ public struct SideBarLayout: Equatable {
     public let width: CGFloat
     /// Preferred window y of the first control; StackScreen still keeps the column above the bottom bars.
     public let top: CGFloat
+    /// Room kept free above the window bottom, clear of a camera at the bottom end of the strip.
+    public let bottom: CGFloat
 }
 
 public struct ScreenLayout: Equatable {
@@ -47,6 +49,13 @@ enum DuoMetrics {
     static let itemPitch: CGFloat = 50
     static let firstItemTop: CGFloat = 170
     static let firstItemTopLandscape: CGFloat = 120
+    // Outer display in portrait: the header is 4pt taller than the iPhone floor and its title
+    // lines up with the camera punchout (y 24–66 at the top of the strip).
+    static let outerHeaderHeight: CGFloat = 76
+    static let outerCameraCenterY: CGFloat = 45
+    // Outer display in landscape has no status bar in the strip: controls keep this far from
+    // both ends unless a reserved region (the camera at either end) asks for more.
+    static let edgeInset: CGFloat = 24
     // Widest short side of any single-display iPhone.
     static let iPhoneMaxShortSide: CGFloat = 440
 }
@@ -79,10 +88,15 @@ extension ScreenLayout {
         )
     }
 
-    static func make(size: CGSize, insets: EdgeInsets, isPhone: Bool = isPhoneIdiom) -> ScreenLayout {
+    static func make(
+        size: CGSize,
+        insets: EdgeInsets,
+        reservedRegions: [CGRect] = ReservedRegions.current,
+        isPhone: Bool = isPhoneIdiom
+    ) -> ScreenLayout {
         let width = size.width
         let height = size.height
-        let (headerHeight, headerStatusBarHeight) = headerGeometry(topInset: insets.top, isPhone: isPhone)
+        var (headerHeight, headerStatusBarHeight) = headerGeometry(topInset: insets.top, isPhone: isPhone)
         let isDuo = isPhone && isIPhoneDuoWindow(width: width, height: height, insets: insets)
         guard isDuo else {
             return ScreenLayout(
@@ -99,13 +113,32 @@ extension ScreenLayout {
             var top = insets.top + HeaderMetrics.barHeight + Spacing.M
             if insets.top < HeaderMetrics.statusBarMinInset {
                 // status bar lives in the strip: start under its cluster, as the native bar does
-                let isInnerLandscape = width > height && height >= DuoMetrics.innerMinHeight
-                top = isInnerLandscape ? DuoMetrics.firstItemTopLandscape : DuoMetrics.firstItemTop
+                if width <= height {
+                    top = DuoMetrics.firstItemTop
+                } else if height >= DuoMetrics.innerMinHeight {
+                    top = DuoMetrics.firstItemTopLandscape
+                } else {
+                    // outer display in landscape: no status bar in the strip
+                    top = DuoMetrics.edgeInset
+                }
+
+                if height > width && width < DuoMetrics.innerMinHeight {
+                    // outer display: the row starts below the top so the title centers on the camera
+                    headerHeight = DuoMetrics.outerHeaderHeight
+                    headerStatusBarHeight = DuoMetrics.outerCameraCenterY * 2 - DuoMetrics.outerHeaderHeight
+                }
             }
+
+            let edge: SideBarEdge = insets.trailing >= insets.leading ? .right : .left
+            let stripLeft = edge == .right ? width - sideInset : 0
+            // clear of the camera and of the status bar cluster, which grows for calls and Live
+            // Activities; region frames already include the system's margin
+            let occlusion = stripOcclusion(reservedRegions, stripLeft: stripLeft, stripRight: stripLeft + sideInset, windowHeight: height)
             sideBar = SideBarLayout(
-                edge: insets.trailing >= insets.leading ? .right : .left,
+                edge: edge,
                 width: sideInset,
-                top: top
+                top: max(top, occlusion.top),
+                bottom: max(DuoMetrics.edgeInset, occlusion.bottom)
             )
         }
 
@@ -126,6 +159,24 @@ extension ScreenLayout {
         )
     }
 
+    /// How far system regions reach into a side strip from its top and from its bottom end
+    /// (e.g. the camera, which sits at either end depending on the rotation).
+    private static func stripOcclusion(
+        _ regions: [CGRect],
+        stripLeft: CGFloat,
+        stripRight: CGFloat,
+        windowHeight: CGFloat
+    ) -> (top: CGFloat, bottom: CGFloat) {
+        regions.reduce(into: (top: CGFloat(0), bottom: CGFloat(0))) { occlusion, region in
+            guard region.minX < stripRight && region.maxX > stripLeft else { return }
+            if region.midY < windowHeight / 2 {
+                occlusion.top = max(occlusion.top, region.maxY)
+            } else {
+                occlusion.bottom = max(occlusion.bottom, windowHeight - region.minY)
+            }
+        }
+    }
+
     // Slab iPhones report equal side insets in landscape; iPhone Duo moves the status bar to one side.
     private static func isIPhoneDuoWindow(width: CGFloat, height: CGFloat, insets: EdgeInsets) -> Bool {
         let shortSide = min(width, height)
@@ -148,6 +199,70 @@ public func isIPhoneDuoDevice(windowSize: CGSize? = nil) -> Bool {
     return max(min(screen.width, screen.height), min(window.width, window.height)) > DuoMetrics.iPhoneMaxShortSide
 }
 
+// MARK: - Reserved regions
+
+/// System occlusion regions (iOS 27.1+) in window coordinates: the iPhone Duo camera, and the
+/// status bar cluster as it grows for a call or a Live Activity. Empty before iOS 27.1.
+enum ReservedRegions {
+    // last report of the probe, so `ScreenLayout.current` includes it
+    static var current: [CGRect] = []
+}
+
+/// Invisible probe: reading the regions in layoutSubviews makes UIKit run it again when they
+/// change, so nothing polls. Port of RN `@momo-kits/reserved-regions`.
+private final class ReservedRegionsProbe: UIView {
+    var onChange: (() -> Void)?
+    private var last: [CGRect]?
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        isUserInteractionEnabled = false
+    }
+
+    required init?(coder: NSCoder) { nil }
+
+    override func layoutSubviews() {
+        super.layoutSubviews()
+        let regions = occlusionRegions()
+        guard regions != last else { return }
+        last = regions
+        ReservedRegions.current = regions
+        // layout pass: publish on the next turn instead of mutating SwiftUI state mid-update
+        DispatchQueue.main.async { [weak self] in self?.onChange?() }
+    }
+
+    override func didMoveToWindow() {
+        super.didMoveToWindow()
+        setNeedsLayout()
+    }
+
+    // The API is newer than the SDKs hosts may build with, so it is reached through the runtime.
+    private func occlusionRegions() -> [CGRect] {
+        let regionsOfKind = NSSelectorFromString("reservedRegionsOfKind:")
+        guard window != nil, responds(to: regionsOfKind),
+              let kindType = NSClassFromString("UIViewReservedRegionKind") as? NSObject.Type,
+              let kind = (kindType as AnyObject).perform(NSSelectorFromString("occlusionRegionKind"))?.takeUnretainedValue(),
+              let regions = perform(regionsOfKind, with: kind)?.takeUnretainedValue() as? [NSObject]
+        else { return [] }
+        return regions.compactMap { ($0.value(forKey: "frame") as? NSValue)?.cgRectValue }
+            .map { convert($0, to: nil) }
+    }
+}
+
+private struct ReservedRegionsProbeView: UIViewRepresentable {
+    let onChange: () -> Void
+
+    func makeUIView(context: Context) -> ReservedRegionsProbe {
+        let probe = ReservedRegionsProbe()
+        probe.onChange = onChange
+        return probe
+    }
+
+    func updateUIView(_ probe: ReservedRegionsProbe, context: Context) {
+        probe.onChange = onChange
+    }
+}
+
 // MARK: - Environment
 
 private struct ScreenLayoutKey: EnvironmentKey {
@@ -177,6 +292,7 @@ private struct ScreenLayoutReader: ViewModifier {
                         .onChange(of: proxy.safeAreaInsets) { _ in refresh() }
                 }
             )
+            .background(ReservedRegionsProbeView { refresh() }.ignoresSafeArea())
             .onReceive(NotificationCenter.default.publisher(for: UIDevice.orientationDidChangeNotification)) { _ in
                 refresh()
             }

package/ios/Application/Navigation/BottomTab/BottomTab.swift

@@ -14,14 +14,25 @@ import SwiftUI
 public struct BottomTab: View {
     private let items: [BottomTabItem]
     private let floatingButton: BottomTabFloatingButton?
+    private let compressionBehavior: DuoBarCompressionBehavior
 
     @EnvironmentObject private var navigator: Navigator
     @Environment(\.screenLayout) private var layout
     @State private var selectedIndex: Int = 0
+    @State private var toolbarHeight = DuoBarCompression.defaultToolbarHeight
+    @State private var expandedBar: DuoBar?
+    @State private var openedBar: DuoBar?
 
-    public init(items: [BottomTabItem], floatingButton: BottomTabFloatingButton? = nil) {
+    /// `compressionBehavior`: on iPhone Duo, when the side bar can't hold both bars, which one
+    /// starts compressed; tapping the compressed one swaps them.
+    public init(
+        items: [BottomTabItem],
+        floatingButton: BottomTabFloatingButton? = nil,
+        compressionBehavior: DuoBarCompressionBehavior = .toolbar
+    ) {
         self.items = items
         self.floatingButton = floatingButton
+        self.compressionBehavior = compressionBehavior
     }
 
     private var bottomInset: CGFloat { safeAreaBottomInset() }
@@ -30,11 +41,34 @@ public struct BottomTab: View {
         layout.isIPhoneDuo ? layout.insets.bottom : BOTTOM_TAB_BAR_HEIGHT + bottomInset + Spacing.S
     }
 
-    private var duoInsets: DuoTabBarInsets {
-        layout.duoTabBarInsets(itemCount: items.count, hasFloatingButton: floatingButton != nil)
+    private var compression: DuoBarCompression {
+        DuoBarCompression.resolve(
+            layout: layout,
+            tabCount: items.count,
+            hasQr: floatingButton != nil,
+            toolbarHeight: toolbarHeight,
+            // 'toolbar' compression keeps the tab bar whole until the toolbar is tapped
+            expanded: Binding(
+                get: { expandedBar ?? (compressionBehavior == .toolbar ? .tabBar : .toolbar) },
+                set: { expandedBar = $0 }
+            ),
+            opened: $openedBar,
+            setToolbarHeight: { height in
+                if toolbarHeight != height { toolbarHeight = height }
+            }
+        )
+    }
+
+    private func duoInsets(_ compression: DuoBarCompression) -> DuoTabBarInsets {
+        layout.duoTabBarInsets(
+            itemCount: items.count,
+            hasFloatingButton: floatingButton != nil,
+            tabBarCompressed: compression.tabBarCompressed
+        )
     }
 
     public var body: some View {
+        let compression = compression
         ZStack(alignment: .bottom) {
             // Tab content area, inset above the bar.
             ZStack {
@@ -46,7 +80,8 @@ public struct BottomTab: View {
                 }
             }
             .padding(.bottom, reservedBottom)
-            .environment(\.duoTabBarInsets, duoInsets)
+            .environment(\.duoTabBarInsets, duoInsets(compression))
+            .environment(\.duoBarCompression, compression)
             .animation(.easeInOut(duration: 0.2), value: selectedIndex)
 
             if layout.isIPhoneDuo {
@@ -54,7 +89,8 @@ public struct BottomTab: View {
                     items: items,
                     floatingButton: floatingButton,
                     selectedIndex: selectedIndex,
-                    onTabSelected: selectTab
+                    onTabSelected: selectTab,
+                    compression: compression
                 )
             } else {
                 // Tab bar + home-indicator filler.

package/ios/Application/Navigation/BottomTab/DuoBarCompression.swift

@@ -0,0 +1,105 @@
+//
+//  DuoBarCompression.swift
+//  MoMoUIKits
+//
+//  Port of RN `BottomTab/DuoBarCompression.tsx` (HIG, Designing for iPhone Duo: Vertical controls):
+//  keeps the side bar's toolbar and tab bar clear of each other.
+//
+
+import SwiftUI
+
+/// iPhone Duo: which side bar bar starts compressed when the strip cannot hold both whole.
+public enum DuoBarCompressionBehavior {
+    case toolbar, tabBar
+}
+
+enum DuoBar {
+    case toolbar, tabBar
+}
+
+struct DuoBarCompression {
+    var toolbarCompressed = false
+    var tabBarCompressed = false
+    /// The open rail needs the toolbar button slot too: only Back stays.
+    var toolbarHidden = false
+    var expandToolbar: () -> Void = {}
+    var expandTabBar: () -> Void = {}
+    /// A rail opened from the compressed state closes once a tab is picked.
+    var onTabSelected: () -> Void = {}
+    /// Side bar toolkits report their full height so the tab bar knows what is left.
+    var setToolbarHeight: (CGFloat) -> Void = { _ in }
+
+    /// Space kept between the top and the bottom groups (HIG Vertical controls).
+    static let groupGap = Spacing.M
+    /// Back, then the right toolkit: help + home capsule.
+    static let defaultToolbarHeight = DuoMetrics.controlSize + Spacing.M + 2 * DuoMetrics.itemPitch
+    /// Back, then the single button the toolbar folds into.
+    private static let compressedToolbarHeight = 2 * DuoMetrics.controlSize + Spacing.M
+    /// Back alone, while a rail opened from the compressed state takes the toolbar slot.
+    private static let backOnlyHeight = DuoMetrics.controlSize
+
+    /// - both fit: both stay whole
+    /// - one fits whole beside the other compressed: one is compressed, tapping it swaps them
+    /// - otherwise both rest compressed; tapping one opens it for a moment (the rail closes
+    ///   again once a tab is picked)
+    static func resolve(
+        layout: ScreenLayout,
+        tabCount: Int,
+        hasQr: Bool,
+        toolbarHeight: CGFloat,
+        expanded: Binding<DuoBar>,
+        opened: Binding<DuoBar?>,
+        setToolbarHeight: @escaping (CGFloat) -> Void
+    ) -> DuoBarCompression {
+        guard let sideBar = layout.sideBar else { return DuoBarCompression() }
+        let room = layout.height - sideBar.bottom - sideBar.top - groupGap
+        let tabBar = duoRailHeight(itemCount: tabCount, hasQr: hasQr)
+        let compressedTabBar = duoRailHeight(itemCount: 1, hasQr: hasQr, compressed: true)
+        func fits(_ toolbar: CGFloat, _ tabs: CGFloat) -> Bool { toolbar + tabs <= room }
+
+        if fits(toolbarHeight, tabBar) {
+            return DuoBarCompression(setToolbarHeight: setToolbarHeight)
+        }
+        if fits(compressedToolbarHeight, tabBar) && fits(toolbarHeight, compressedTabBar) {
+            return DuoBarCompression(
+                toolbarCompressed: expanded.wrappedValue == .tabBar,
+                tabBarCompressed: expanded.wrappedValue == .toolbar,
+                expandToolbar: { expanded.wrappedValue = .toolbar },
+                expandTabBar: { expanded.wrappedValue = .tabBar },
+                setToolbarHeight: setToolbarHeight
+            )
+        }
+
+        let expandToolbar = { opened.wrappedValue = .toolbar }
+        let expandTabBar = { opened.wrappedValue = .tabBar }
+        if opened.wrappedValue == .tabBar && fits(backOnlyHeight, tabBar) {
+            return DuoBarCompression(
+                toolbarCompressed: true,
+                tabBarCompressed: false,
+                toolbarHidden: true,
+                expandToolbar: expandToolbar,
+                expandTabBar: expandTabBar,
+                onTabSelected: { opened.wrappedValue = nil },
+                setToolbarHeight: setToolbarHeight
+            )
+        }
+        return DuoBarCompression(
+            toolbarCompressed: opened.wrappedValue != .toolbar,
+            tabBarCompressed: true,
+            expandToolbar: expandToolbar,
+            expandTabBar: expandTabBar,
+            setToolbarHeight: setToolbarHeight
+        )
+    }
+}
+
+private struct DuoBarCompressionKey: EnvironmentKey {
+    static let defaultValue = DuoBarCompression()
+}
+
+extension EnvironmentValues {
+    var duoBarCompression: DuoBarCompression {
+        get { self[DuoBarCompressionKey.self] }
+        set { self[DuoBarCompressionKey.self] = newValue }
+    }
+}

package/ios/Application/Navigation/BottomTab/DuoTabBar.swift

@@ -28,7 +28,7 @@ private let tabSpring = Animation.interpolatingSpring(mass: 0.8, stiffness: 220,
 struct DuoTabBarInsets: Equatable {
     /// Floating bar overlays the content: scroll content, footer and FAB keep clear of it.
     var overlay: CGFloat = 0
-    /// Rail sits at the bottom of the side strip: the header side bar stays above it.
+    /// Rail sits at the bottom of the side strip: the header side bar stays this far above the window bottom.
     var sideBarReserve: CGFloat = 0
 }
 
@@ -43,16 +43,21 @@ extension EnvironmentValues {
     }
 }
 
+/// Rail plus the QR button under it; compressed, the rail is a single button.
+func duoRailHeight(itemCount: Int, hasQr: Bool, compressed: Bool = false) -> CGFloat {
+    let count = CGFloat(itemCount)
+    let rail = compressed ? itemSize : railPadding * 2 + count * itemSize + max(count - 1, 0) * railGap
+    return rail + (hasQr ? Spacing.M + itemSize : 0)
+}
+
 extension ScreenLayout {
-    func duoTabBarInsets(itemCount: Int, hasFloatingButton: Bool) -> DuoTabBarInsets {
+    func duoTabBarInsets(itemCount: Int, hasFloatingButton: Bool, tabBarCompressed: Bool = false) -> DuoTabBarInsets {
         guard isIPhoneDuo else { return DuoTabBarInsets() }
-        guard sideBar != nil else {
+        guard let sideBar else {
             return DuoTabBarInsets(overlay: duoFloatingTabBarHeight + Spacing.M)
         }
-        let count = CGFloat(itemCount)
-        let rail = railPadding * 2 + count * itemSize + max(count - 1, 0) * railGap
-        let qr = hasFloatingButton ? Spacing.M + itemSize : 0
-        return DuoTabBarInsets(sideBarReserve: rail + qr + Spacing.XL)
+        let rail = duoRailHeight(itemCount: itemCount, hasQr: hasFloatingButton, compressed: tabBarCompressed)
+        return DuoTabBarInsets(sideBarReserve: sideBar.bottom + rail + DuoBarCompression.groupGap)
     }
 }
 
@@ -95,13 +100,14 @@ struct DuoTabBar: View {
     let floatingButton: BottomTabFloatingButton?
     let selectedIndex: Int
     let onTabSelected: (Int) -> Void
+    var compression = DuoBarCompression()
 
     @Environment(\.screenLayout) private var layout
 
     var body: some View {
         if let sideBar = layout.sideBar {
             DuoRailTabBar(sideBar: sideBar, items: items, floatingButton: floatingButton,
-                          selectedIndex: selectedIndex, onTabSelected: onTabSelected)
+                          selectedIndex: selectedIndex, onTabSelected: onTabSelected, compression: compression)
         } else {
             DuoFloatingTabBar(items: items, floatingButton: floatingButton,
                               selectedIndex: selectedIndex, onTabSelected: onTabSelected)
@@ -110,12 +116,15 @@ struct DuoTabBar: View {
 }
 
 /// Vertical bar anchored to the bottom of the side bar, QR button below it (Figma MT1-C/E).
+/// When the side bar is short it can shrink to one button showing the current tab
+/// (HIG "Tab bar compressed"); tapping it expands the rail and compresses the toolbar.
 private struct DuoRailTabBar: View {
     let sideBar: SideBarLayout
     let items: [BottomTabItem]
     let floatingButton: BottomTabFloatingButton?
     let selectedIndex: Int
     let onTabSelected: (Int) -> Void
+    let compression: DuoBarCompression
 
     @Environment(\.appTheme) private var theme
 
@@ -123,30 +132,19 @@ private struct DuoRailTabBar: View {
 
     var body: some View {
         VStack(spacing: Spacing.M) {
-            ZStack(alignment: .top) {
-                Capsule()
-                    .fill(theme.colors.background.selected)
-                    .frame(width: railBubbleWidth, height: railBubbleHeight)
-                    .offset(y: railPadding - (railBubbleHeight - itemSize) / 2
-                        + CGFloat(selectedIndex) * (itemSize + railGap))
-                    .animation(tabSpring, value: selectedIndex)
-
-                VStack(spacing: railGap) {
-                    ForEach(items.indices, id: \.self) { index in
-                        SwiftUI.Button { onTabSelected(index) } label: {
-                            DuoTabIcon(item: items[index], selected: index == selectedIndex)
-                                .frame(width: itemSize, height: itemSize)
-                                .contentShape(Rectangle())
-                        }
-                        .buttonStyle(.plain)
-                        .accessibilityLabel(items[index].label)
-                    }
+            if compression.tabBarCompressed, items.indices.contains(selectedIndex) {
+                SwiftUI.Button(action: compression.expandTabBar) {
+                    DuoTabIcon(item: items[selectedIndex], selected: true)
+                        .frame(width: itemSize, height: itemSize)
+                        .contentShape(Circle())
                 }
-                .padding(.vertical, railPadding)
+                .buttonStyle(.plain)
+                .modifier(DuoBarMaterial(shape: Circle()))
+                .accessibilityLabel(items[selectedIndex].label)
+                .accessibilityIdentifier("bottom_tab_bar")
+            } else {
+                rail
             }
-            .frame(width: itemSize)
-            .modifier(DuoBarMaterial(shape: RoundedRectangle(cornerRadius: Radius.XL)))
-            .accessibilityIdentifier("bottom_tab_bar")
 
             if let floatingButton {
                 DuoQrButton(data: floatingButton, size: itemSize)
@@ -154,10 +152,41 @@ private struct DuoRailTabBar: View {
         }
         .padding(isRight ? .leading : .trailing, Spacing.M)
         .frame(width: sideBar.width, alignment: isRight ? .leading : .trailing)
-        .padding(.bottom, Spacing.XL)
+        .padding(.bottom, sideBar.bottom)
         .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: isRight ? .bottomTrailing : .bottomLeading)
         .ignoresSafeArea()
     }
+
+    /// Glass column of tab items with the sliding selection bubble.
+    private var rail: some View {
+        ZStack(alignment: .top) {
+            Capsule()
+                .fill(theme.colors.background.selected)
+                .frame(width: railBubbleWidth, height: railBubbleHeight)
+                .offset(y: railPadding - (railBubbleHeight - itemSize) / 2
+                    + CGFloat(selectedIndex) * (itemSize + railGap))
+                .animation(tabSpring, value: selectedIndex)
+
+            VStack(spacing: railGap) {
+                ForEach(items.indices, id: \.self) { index in
+                    SwiftUI.Button {
+                        onTabSelected(index)
+                        compression.onTabSelected()
+                    } label: {
+                        DuoTabIcon(item: items[index], selected: index == selectedIndex)
+                            .frame(width: itemSize, height: itemSize)
+                            .contentShape(Rectangle())
+                    }
+                    .buttonStyle(.plain)
+                    .accessibilityLabel(items[index].label)
+                }
+            }
+            .padding(.vertical, railPadding)
+        }
+        .frame(width: itemSize)
+        .modifier(DuoBarMaterial(shape: RoundedRectangle(cornerRadius: Radius.XL)))
+        .accessibilityIdentifier("bottom_tab_bar")
+    }
 }
 
 /// Floating labelled bar for the unfolded portrait display, QR in the middle cell (Figma MT1-M).

package/ios/Application/Navigation/component/DuoScrollGradient.swift

@@ -17,39 +17,38 @@ struct DuoScrollGradient: View {
     let scrollOffset: CGFloat
     let headerHeight: CGFloat
     let extended: Bool
+    /// Quick return header: the gradient leaves with the content instead of fading.
+    var followScroll = false
 
     @Environment(\.appTheme) private var theme
-    @Environment(\.screenLayout) private var layout
 
     private var scroll: CGFloat { max(scrollOffset, 0) }
 
-    private var gradient: LinearGradient {
-        LinearGradient(
-            colors: [theme.colors.gradient, theme.colors.gradient.opacity(0)],
-            startPoint: .top,
-            endPoint: .bottom
-        )
-    }
-
     var body: some View {
         Group {
-            if extended {
-                // extended squeezes the whole fade into its box and fades out
-                let progress = min(scroll / extendedCollapseDistance, 1)
+            if followScroll {
                 gradient
-                    .frame(height: headerHeight + extendedGradientExtra * (1 - progress))
-                    .opacity(1 - min(scroll / extendedGradientExtra, 1))
+                    .frame(height: headerHeight + (extended ? extendedGradientExtra : 0))
+                    .offset(y: -scroll)
             } else {
-                // default keeps the off-Duo 375:154 shape, the header clips it, and scrolls away
+                // fades out on scroll as the extended header does off Duo; extended also collapses
+                let progress = min(scroll / extendedCollapseDistance, 1)
                 gradient
-                    .frame(height: layout.width * 154 / 375)
-                    .frame(height: headerHeight, alignment: .top)
-                    .clipped()
-                    .offset(y: -scroll)
+                    .frame(height: headerHeight + (extended ? extendedGradientExtra * (1 - progress) : 0))
+                    .opacity(1 - min(scroll / extendedGradientExtra, 1))
             }
         }
         .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
         .ignoresSafeArea()
         .allowsHitTesting(false)
     }
+
+    /// The fade spans the gradient box.
+    private var gradient: LinearGradient {
+        LinearGradient(
+            colors: [theme.colors.gradient, theme.colors.gradient.opacity(0)],
+            startPoint: .top,
+            endPoint: .bottom
+        )
+    }
 }

package/ios/Application/Navigation/component/Header.swift

@@ -113,8 +113,9 @@ public struct NavigationHeader: View {
             }
             .frame(height: layout.headerBarHeight)
             .overlay(alignment: .bottom) { VerticalShadow(opacity: opacity) }
-            // status bar off the top edge: the row spans the whole header from the window top
-            .padding(.top, min(layout.headerStatusBarHeight - layout.insets.top, 0))
+            // the row starts headerStatusBarHeight below the window top: 0 with the status bar off
+            // the top edge, lower on the iPhone Duo outer display to center on the camera
+            .padding(.top, layout.headerStatusBarHeight - layout.insets.top)
         }
     }
 

package/ios/Application/Navigation/component/NavigationHeaderRight.swift

@@ -31,6 +31,7 @@ struct ToolkitNavigationHeaderRight: View {
     @State private var isFavorite: Bool = false
     @State private var isLoading: Bool = false
     @Environment(\.applicationEnvironment) private var environment
+    @Environment(\.duoBarCompression) private var compression
 
     private func apiValue(_ value: Any?) -> Any {
         value ?? NSNull()
@@ -169,7 +170,38 @@ struct ToolkitNavigationHeaderRight: View {
         } ?? false
     }
 
+    /// Back slot, the optional shortcut, then the help/home capsule.
+    private var fullToolbarHeight: CGFloat {
+        DuoMetrics.controlSize + Spacing.M
+            + (shouldShowShortcut ? DuoMetrics.controlSize + Spacing.M : 0)
+            + (showHelpCenter ? 2 * DuoMetrics.itemPitch : DuoMetrics.controlSize)
+    }
+
+    @ViewBuilder
     private var verticalBody: some View {
+        Group {
+            if compression.toolbarHidden {
+                // an open tab rail takes this slot for a moment
+                EmptyView()
+            } else if compression.toolbarCompressed {
+                // HIG "Toolbar compressed": tools fold into one button, distinct from the useMore icon
+                SideBarButton(
+                    icon: "navigation_menu",
+                    tintColor: tintColor,
+                    showBadge: showBadge,
+                    accessibilityId: "btn_navigation_toolbar",
+                    action: compression.expandToolbar
+                )
+            } else {
+                toolbarColumn
+            }
+        }
+        // full height, so the tab bar compression decision matches this screen's toolkit
+        .onAppear { compression.setToolbarHeight(fullToolbarHeight) }
+        .onChange(of: fullToolbarHeight) { compression.setToolbarHeight($0) }
+    }
+
+    private var toolbarColumn: some View {
         let navButtonConfig = getNavigationButtonConfig()
         return VStack(spacing: Spacing.M) {
             if shouldShowShortcut {

package/ios/Application/Navigation/component/SideBar.swift

@@ -24,7 +24,7 @@ struct HeaderSideBar: View {
     let goBack: (() -> Void)?
     let toolkit: (data: HeaderRightData?, tintColor: Color?)?
     let headerColor: HeaderColor
-    /// What footer / tab bar / home indicator take from the bottom; the column stays above it.
+    /// What footer / tab bar / home indicator take from the bottom, gap included; the column stays above it.
     let bottomInset: CGFloat
 
     @Environment(\.screenLayout) private var layout
@@ -33,7 +33,7 @@ struct HeaderSideBar: View {
     private var isRight: Bool { sideBar.edge == .right }
 
     private var top: CGFloat {
-        let maxY = layout.height - bottomInset - Spacing.XL - columnHeight
+        let maxY = layout.height - bottomInset - columnHeight
         return max(min(sideBar.top, maxY), 0)
     }
 

package/ios/Application/StackScreen.swift

@@ -102,6 +102,9 @@ public struct StackScreen<Content: View>: View {
     @State private var keyboardHeight: CGFloat = 0
     @State private var headerRightWidth: CGFloat = 0
     @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>?
 
     @Environment(\.applicationEnvironment) private var appEnv
     @Environment(\.screenLayout) private var layout
@@ -140,11 +143,44 @@ public struct StackScreen<Content: View>: View {
             && inputSearchProps == nil && !headerTransparent && !fullScreenContent
     }
 
-    /// Height the footer, tab bar or home indicator takes from the bottom of the window.
+    /// iPhone Duo: the header leaves with the content and slides back in on a reverse scroll
+    /// (RN DuoQuickReturnHeader). The side bar is drawn apart from the header, so it stays put.
+    private var useQuickReturn: Bool {
+        layout.sideBar != nil && scrollable && (useDuoGlass || animatedHeader != nil)
+    }
+
+    private func updateHeaderHide(_ offset: CGFloat) {
+        let delta = offset - lastScrollOffset
+        lastScrollOffset = offset
+        guard useQuickReturn, offset > 0 else {
+            if headerHide != 0 { headerHide = 0 }
+            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
+            }
+        }
+    }
+
+    /// What the footer, tab bar or home indicator takes from the bottom of the window, gap included.
     private var bottomBarsHeight: CGFloat {
-        if footer != nil { return footerHeight + NavigationFooter.safeAreaBottom }
-        if duoTabBarInsets.sideBarReserve > 0 { return duoTabBarInsets.sideBarReserve - Spacing.XL }
-        return NavigationFooter.navigationBarInset
+        if footer != nil { return footerHeight + NavigationFooter.safeAreaBottom + Spacing.XL }
+        if duoTabBarInsets.sideBarReserve > 0 { return duoTabBarInsets.sideBarReserve }
+        return NavigationFooter.navigationBarInset + Spacing.XL
     }
 
     /// Keyboard frames are in screen coordinates; UIScreen stays on the outer display on iPhone Duo.
@@ -234,6 +270,7 @@ public struct StackScreen<Content: View>: View {
                 }
             }
             .ignoresSafeArea(.keyboard, edges: .bottom)
+            .onChange(of: scrollOffset) { updateHeaderHide($0) }
             .onPreferenceChange(HeaderRightWidthKey.self) { width in
                 if headerRightWidth != width { headerRightWidth = width }
             }
@@ -319,6 +356,7 @@ public struct StackScreen<Content: View>: View {
                         }
                         .edgesIgnoringSafeArea([.top, .horizontal])
                     )
+                    .offset(y: -headerHide)
                     .zIndex(100)
             }
         } else if headerTransparent && fullScreenContent {
@@ -342,7 +380,8 @@ public struct StackScreen<Content: View>: View {
                 DuoScrollGradient(
                     scrollOffset: scrollOffset,
                     headerHeight: layout.headerHeight,
-                    extended: headerType == .extended
+                    extended: headerType == .extended,
+                    followScroll: useQuickReturn
                 )
 
                 StackScreenContent(
@@ -360,6 +399,7 @@ public struct StackScreen<Content: View>: View {
                             .modifier(DuoBarMaterial(shape: Rectangle(), visible: scrollOffset > 0))
                             .edgesIgnoringSafeArea([.top, .horizontal])
                     )
+                    .offset(y: -headerHide)
                     .zIndex(100)
             }
         } else {
@@ -526,7 +566,7 @@ private struct SearchAnimatedHeader: View {
         let scroll = max(scrollOffset, 0)
 
         // Insets are measured from the safe-area top; collapsed, the search is centered in the bar row.
-        let rowTop = min(layout.headerStatusBarHeight - layout.insets.top, 0)
+        let rowTop = layout.headerStatusBarHeight - layout.insets.top
         let minTop = rowTop + (layout.headerBarHeight - headerHeight) / 2
         let maxTop = layout.headerHeight - layout.insets.top
         let minSide = Spacing.M

package/ios-demo/Sources/MoMoUIKitsDemo/SampleDemos/DuoTabDemo.swift

@@ -4,7 +4,8 @@
 //
 //  Mirrors RN `app/screens/IPhoneDuo/DuoTabUsage`: glass rail in the Duo side bar, floating
 //  glass bar when unfolded portrait. `useShortcut` gives the tallest side bar header, for the
-//  overlap review.
+//  overlap review; `compressTabBar` folds the tab bar instead of the toolbar when the side bar
+//  is short (HIG "Tab bar compressed").
 //
 
 import MoMoUIKits
@@ -15,10 +16,11 @@ private let history = (1...18).map { "Giao dịch #\($0)" }
 
 struct DuoTabDemo: View {
     let useShortcut: Bool
+    var compressTabBar = false
 
     var body: some View {
         if #available(iOS 16.0, *) {
-            DuoTabDemoContent(useShortcut: useShortcut)
+            DuoTabDemoContent(useShortcut: useShortcut, compressTabBar: compressTabBar)
         } else {
             Text("Requires iOS 16+").padding()
         }
@@ -28,6 +30,7 @@ struct DuoTabDemo: View {
 @available(iOS 16.0, *)
 private struct DuoTabDemoContent: View {
     let useShortcut: Bool
+    let compressTabBar: Bool
 
     var body: some View {
         BottomTab(
@@ -37,7 +40,8 @@ private struct DuoTabDemoContent: View {
                 tab("DuoHistory", label: "Lịch sử GD", icon: "time_clock_reset", title: "Lịch sử giao dịch", badge: "3"),
                 tab("DuoMe", label: "Tôi", icon: "basic_person", title: "Tôi"),
             ],
-            floatingButton: BottomTabFloatingButton(icon: "navigation_full_screen", label: "Quét mọi QR", onPress: {})
+            floatingButton: BottomTabFloatingButton(icon: "navigation_full_screen", label: "Quét mọi QR", onPress: {}),
+            compressionBehavior: compressTabBar ? .tabBar : .toolbar
         )
     }
 

package/ios-demo/Sources/MoMoUIKitsDemo/SampleDemos/IPhoneDuoDemo.swift

@@ -53,6 +53,9 @@ private struct IPhoneDuoDemoContent: View {
                 demoButton("Glass tab bar + useShortcut") {
                     navigator.push({ DuoTabDemo(useShortcut: true) }, options: tabOptions)
                 }
+                demoButton("Glass tab bar + compress tab bar") {
+                    navigator.push({ DuoTabDemo(useShortcut: true, compressTabBar: true) }, options: tabOptions)
+                }
                 demoButton("Bottom sheet: iPhone Duo safe area") {
                     navigator.showBottomSheet({ BottomSheetSafeArea() }, isSurface: true, header: .title("Safe area"))
                 }

package/package.json

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