@momo-kits/native-kits 0.167.1-beta.9-debug → 0.167.1-duo-search.1

package/CLAUDE.md

@@ -35,6 +35,13 @@ No unit-test suite is configured. Validate changes by compiling the relevant tar
 ./gradlew :sample:androidApp:installDebug                 # run demo on device/emulator
 ```
 
+The SwiftUI kit (`ios/`, pod `MoMoUIKits`) compiles on its own through the sample's Pods project (`pod install` in `sample/iosApp` first when files are added):
+
+```bash
+xcodebuild -project sample/iosApp/Pods/Pods.xcodeproj -scheme MoMoUIKits -sdk iphonesimulator \
+  -destination 'generic/platform=iOS Simulator' build
+```
+
 Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do not publish manually unless asked: `sh publish.sh beta` / `sh publish.sh release` (Maven→GitLab + NPM).
 
 ## Architecture essentials
@@ -47,6 +54,28 @@ Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do
 - Navigation uses a runtime `DynamicScreenRegistry`; overlays (modal/bottom-sheet/snackbar) go through `Navigator` + `OverplayComponentRegistry`.
 - **iOS swipe-back:** the host owns the only edge-pan recogniser and replays it through `HostBackGestureBridge` (`navigation/HostBackGestureBridge.kt`; the kit framework is never exported, so the host reaches it through its own Koin-provided facade): `checkCanPop` / `canPopInner` / `pop` route the back into the kit stack, `started` / `progressed` / `completed` / `cancelled` seek the NavHost transition, `shouldUseFloatingArrowBack` is set by bottom tabs. `NavigationContainer` attaches itself automatically (`AttachHostBackGesture`, iOS only, detached by identity on dispose) — hosts need no wrapper and no `setNavigator`. `maxApi` is a required parameter of `NavigationContainer` — every container, nested or root, is handed its host bridge explicitly.
 
+## SwiftUI kit (`ios/`)
+
+- The pod's minimum is **iOS 15**, but the navigation shell (`NavigationContainer`, `Navigator`, `NavigatorManager`, `BottomTab`, overplay views) is **iOS 16+** (`@available(iOS 16.0, *)`) because it is built on `NavigationStack`. Keep components outside that shell iOS 15-compatible.
+- `present` opens one `fullScreenCover` that hosts its own `NavigationStack` (`Navigator.presentedPath`): pushes and pops act on the presented flow while it is up, and each overplay (modal / bottom sheet / snackbar) renders in the context it was shown over (`OverplayItem.presentedId`).
+- Icons are compiled in: `ios/Icon/Icons.swift` is generated from Compose `utils/Icons.kt` by `node scripts/gen-ios-icons.mjs` — don't hand-edit it. A host `icon.json` in the main bundle only adds keys the kit lacks.
+- Bundled assets (colors, Lottie JSON) live in `ios/Resources` and ship in the `MoMoUIKitsResources` bundle; load them through `MoMoUIKitsResources.bundle`, never `Bundle.main`.
+
+## Screen layout / iPhone Duo (port of RN `useScreenLayout`, momo-kits !664)
+
+- `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` 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`.
+
 ## i18n / Localize (port of RN `Localize`)
 
 - `application/Localize.kt`: everything i18n. `LocalizationObject` is a data class with required `vi` / `en` maps (`LocalizationObject(vi = mapOf(…), en = mapOf(…))`). `Localize` constructors take a `LocalizationObject` or a `(vi, en)` map pair; the constructor **merges** the kit defaults with the host data (host wins on key clash). Methods: `translate(key)` (missing/empty → returns the key), `translateData(map)` / `translateData(vi, en)`, `addTranslations` (existing keys win), `changeLanguage(lang)`. Default language `"vi"`, `"en"` only on exact match; language is snapshot state so a switch recomposes consumers.
@@ -97,3 +126,10 @@ Prefer one tight line at the surprising spot over a paragraph. Match the (low) c
 - **Resource qualifier drift:** the generated Compose `Res` namespace is `vn.momo.uikits.resources`, but `utils/Resources.kt` and `platform/Platform.ios.kt` reference `vn.momo.compose.resources`. Keep bundled strings/dictionaries as plain Kotlin (the `defaultLanguage` map in `Localize.kt`), not `composeResources/values`, to avoid iOS framework resource-loading issues.
 - Prefer `NavigationContainer` over the deprecated `ApplicationContainer`; prefer `IMaxApi`/`LocalMaxApi` over the deprecated `PlatformApi`.
 - iOS strings/maps must survive Kotlin/Native framework packaging — keep them compiled-in, not loaded from resource bundles.
+
+## Code comments
+- Only comment when necessary: non-obvious logic, workarounds, or the "why" behind a decision.
+- Don't comment on what the code already says clearly (no "// increment i", no restating function names).
+- Keep comments short: one line when possible, plain and easy to understand.
+- No long comment blocks, no line-by-line narration, no lines that overflow the editor width.
+- Don't leave comments about the change itself (e.g. "// updated this", "// new logic").

package/ios/Application/ApplicationEnvironment.swift

@@ -41,6 +41,12 @@ public class KitConfig {
     public var trustBanner: TrustBannerData? = nil
     public var headerBar: String? = nil
     public var headerGradient: String? = nil
+
+    public init(trustBanner: TrustBannerData? = nil, headerBar: String? = nil, headerGradient: String? = nil) {
+        self.trustBanner = trustBanner
+        self.headerBar = headerBar
+        self.headerGradient = headerGradient
+    }
 }
 
 public class ApplicationEnvironment: ObservableObject {

package/ios/Application/Components.swift

@@ -248,9 +248,7 @@ public struct Header: View {
                         if let inputProps = inputSearchProps {
                             InputSearch(props: inputProps)
                         } else if case let .user(userData)? = headerTitle {
-                            if #available(iOS 16.0, *) {
-                                HeaderUserView(userData)
-                            }
+                            HeaderUserView(userData)
                         } else {
                             MomoText(headerTitle?.defaultTitle ?? title, typography: .headerDefaultBold, color: tintColor ?? Colors.black17, maxLines: 1)
                                 .opacity(titleOpacity)

package/ios/Application/HeaderRight.swift

@@ -7,20 +7,31 @@ public struct HeaderRightData {
     var tools: [ToolGroup]
     var toolCallback: ((String) -> Void)?
     var useSystemTools: Bool
+    var useCloseIcon: Bool
     
     public init(
         useShortcut: Bool = false,
         useMore: Bool = false,
         tools: [ToolGroup] = [],
         toolCallback: ((String) -> Void)? = nil,
-        useSystemTools: Bool = true
+        useSystemTools: Bool = true,
+        useCloseIcon: Bool = false
     ) {
         self.useShortcut = useShortcut
         self.useMore = useMore
         self.tools = tools
         self.toolCallback = toolCallback
         self.useSystemTools = useSystemTools
+        self.useCloseIcon = useCloseIcon
     }
+
+    /// Close-circle instead of home, as RN `headerRight.useCloseIcon`.
+    var closeIcon: String { useCloseIcon ? "16_navigation_close_circle" : "16_basic_home" }
+}
+
+/// The Help Center mini-app hides its own help-center button.
+func showsHelpCenter(_ context: MiniAppContext?) -> Bool {
+    context?.appId != "vn.momo.helpcenter"
 }
 
 public struct Tool {
@@ -101,8 +112,13 @@ struct ToolkitHeaderRight: View {
     var tintColor: Color?
     @State private var isFavorite: Bool = false
     @State private var isLoading: Bool = false
-    @EnvironmentObject private var environment: ApplicationEnvironment
-    
+    // Legacy hosts inject with `.environmentObject`, containers with the keyed value; outside
+    // both this used to trap, so read the object optionally and fall back to the keyed one.
+    @OptionalEnvironmentObject private var injectedEnvironment: ApplicationEnvironment?
+    @Environment(\.applicationEnvironment) private var keyedEnvironment
+
+    private var environment: ApplicationEnvironment { injectedEnvironment ?? keyedEnvironment }
+
     // MARK: - Actions
     private func onPressShortcut() {
         // onToolAction needs the app context (appId/code) so the host knows which app to (un)favorite;
@@ -238,17 +254,19 @@ struct ToolkitHeaderRight: View {
             }
             
             HStack(alignment: .center, spacing: 0) {
-                Icon(source: "help_center", size: 20, color: tintColor ?? Colors.black17)
-                    .padding(4)
-                    .onTapGesture {
-                        onPressHelpCenter()
-                    }
-                
-                Rectangle()
-                    .fill(tintColor ?? Colors.black20)
-                    .frame(width: 0.5, height: 12)
-                
-                Icon(source: "16_basic_home", size: 20, color: tintColor ?? Colors.black17)
+                if showsHelpCenter(environment.applicationContext) {
+                    Icon(source: "help_center", size: 20, color: tintColor ?? Colors.black17)
+                        .padding(4)
+                        .onTapGesture {
+                            onPressHelpCenter()
+                        }
+
+                    Rectangle()
+                        .fill(tintColor ?? Colors.black20)
+                        .frame(width: 0.5, height: 12)
+                }
+
+                Icon(source: headerRight?.closeIcon ?? "16_basic_home", size: 20, color: tintColor ?? Colors.black17)
                     .padding(4)
                     .onTapGesture {
                         onPressClose()

package/ios/Application/Layout/ScreenLayout.swift

@@ -0,0 +1,312 @@
+//
+//  ScreenLayout.swift
+//  MoMoUIKits
+//
+//  Port of momo-kits RN `useScreenLayout` (Layout/utils.ts) and `Application/device.ts`:
+//  window size, safe-area insets, content width, header geometry and the iPhone Duo side bar.
+//
+
+import SwiftUI
+import UIKit
+
+public enum SideBarEdge: Equatable {
+    case left, right
+}
+
+public struct SideBarLayout: Equatable {
+    public let edge: SideBarEdge
+    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 {
+    public let width: CGFloat
+    public let height: CGFloat
+    public let isIPhoneDuo: Bool
+    public let insets: EdgeInsets
+    public let insetLeft: CGFloat
+    public let insetRight: CGFloat
+    public let contentWidth: CGFloat
+    public let headerHeight: CGFloat
+    /// 0 when the status bar is off the top edge, so the bar row fills the header and keeps the title centered.
+    public let headerStatusBarHeight: CGFloat
+    /// iPhone Duo moves back and toolkit into a column in the side safe area; nil while they stay in the bar.
+    public let sideBar: SideBarLayout?
+
+    public var headerBarHeight: CGFloat { headerHeight - headerStatusBarHeight }
+}
+
+// Measured by momo-kits RN (Layout/utils.ts) on the iOS 27.1 iPhone Duo simulator; keep both in sync.
+enum DuoMetrics {
+    // Inner display is ~1.42, outer ~1.45; every slab iPhone is 1.77 or taller.
+    static let maxAspectRatio: CGFloat = 1.6
+    // Outer display is 466pt tall in landscape, inner 669pt.
+    static let innerMinHeight: CGFloat = 600
+    static let controlSize: CGFloat = 48
+    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
+}
+
+enum HeaderMetrics {
+    static let barHeight: CGFloat = HEADER_HEIGHT
+    static let iPhoneMinHeight: CGFloat = 72
+    // A smaller top inset means the status bar is not on the top edge.
+    static let statusBarMinInset: CGFloat = 20
+}
+
+private var isPhoneIdiom: Bool { UIDevice.current.userInterfaceIdiom == .phone }
+
+private var keyWindow: UIWindow? {
+    UIApplication.shared.connectedScenes
+        .compactMap { ($0 as? UIWindowScene)?.keyWindow }
+        .first
+}
+
+extension ScreenLayout {
+    /// Snapshot of the key window; not reactive, so views read `\.screenLayout` instead.
+    public static var current: ScreenLayout {
+        guard let window = keyWindow else {
+            return make(size: UIScreen.main.bounds.size, insets: EdgeInsets())
+        }
+        let inset = window.safeAreaInsets
+        return make(
+            size: window.bounds.size,
+            insets: EdgeInsets(top: inset.top, leading: inset.left, bottom: inset.bottom, trailing: inset.right)
+        )
+    }
+
+    static func make(
+        size: CGSize,
+        insets: EdgeInsets,
+        reservedRegions: [CGRect] = ReservedRegions.current,
+        isPhone: Bool = isPhoneIdiom
+    ) -> ScreenLayout {
+        let width = size.width
+        let height = size.height
+        var (headerHeight, headerStatusBarHeight) = headerGeometry(topInset: insets.top, isPhone: isPhone)
+        let isDuo = isPhone && isIPhoneDuoWindow(width: width, height: height, insets: insets)
+        guard isDuo else {
+            return ScreenLayout(
+                width: width, height: height, isIPhoneDuo: false, insets: insets,
+                insetLeft: 0, insetRight: 0, contentWidth: width,
+                headerHeight: headerHeight, headerStatusBarHeight: headerStatusBarHeight, sideBar: nil
+            )
+        }
+
+        var sideBar: SideBarLayout?
+        let sideInset = max(insets.leading, insets.trailing)
+        // narrower strips cannot host a control 12pt from the inner edge
+        if sideInset >= DuoMetrics.controlSize + Spacing.M {
+            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
+                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: edge,
+                width: sideInset,
+                top: max(top, occlusion.top),
+                bottom: max(DuoMetrics.edgeInset, occlusion.bottom)
+            )
+        }
+
+        return ScreenLayout(
+            width: width, height: height, isIPhoneDuo: true, insets: insets,
+            insetLeft: insets.leading, insetRight: insets.trailing,
+            contentWidth: width - insets.leading - insets.trailing,
+            headerHeight: headerHeight, headerStatusBarHeight: headerStatusBarHeight, sideBar: sideBar
+        )
+    }
+
+    private static func headerGeometry(topInset: CGFloat, isPhone: Bool) -> (CGFloat, CGFloat) {
+        let height = topInset + HeaderMetrics.barHeight
+        guard isPhone else { return (height, topInset) }
+        return (
+            max(height, HeaderMetrics.iPhoneMinHeight),
+            topInset < HeaderMetrics.statusBarMinInset ? 0 : topInset
+        )
+    }
+
+    /// 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)
+        let isSquare = shortSide > 0 && max(width, height) / shortSide < DuoMetrics.maxAspectRatio
+        return isSquare || insets.leading != insets.trailing
+    }
+
+    /// Below the side status bar: in portrait it is about twice as tall as its inset is wide.
+    public var duoTopInset: CGFloat {
+        max(insets.top, height > width ? max(insets.leading, insets.trailing) * 2 : 0)
+    }
+}
+
+/// Port of RN `device.ts` `isIPhoneDuo()`: UIScreen stays on the outer display, so this
+/// still matches when Split View narrows the window. Used by popups and overlays.
+public func isIPhoneDuoDevice(windowSize: CGSize? = nil) -> Bool {
+    guard isPhoneIdiom else { return false }
+    let screen = UIScreen.main.bounds.size
+    let window = windowSize ?? keyWindow?.bounds.size ?? screen
+    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 {
+    // Computed so an un-injected subtree (bare UIHostingController) still reads the live window.
+    static var defaultValue: ScreenLayout { .current }
+}
+
+public extension EnvironmentValues {
+    var screenLayout: ScreenLayout {
+        get { self[ScreenLayoutKey.self] }
+        set { self[ScreenLayoutKey.self] = newValue }
+    }
+}
+
+/// Re-reads the window whenever this view's size changes (rotation, fold/unfold, Split View).
+private struct ScreenLayoutReader: ViewModifier {
+    @State private var layout: ScreenLayout = .current
+
+    func body(content: Content) -> some View {
+        content
+            .environment(\.screenLayout, layout)
+            .background(
+                GeometryReader { proxy in
+                    Color.clear
+                        .onAppear { refresh() }
+                        .onChange(of: proxy.size) { _ in refresh() }
+                        .onChange(of: proxy.safeAreaInsets) { _ in refresh() }
+                }
+            )
+            .background(ReservedRegionsProbeView { refresh() }.ignoresSafeArea())
+            .onReceive(NotificationCenter.default.publisher(for: UIDevice.orientationDidChangeNotification)) { _ in
+                refresh()
+            }
+    }
+
+    private func refresh() {
+        let next = ScreenLayout.current
+        if next != layout { layout = next }
+    }
+}
+
+public extension View {
+    /// Provides `\.screenLayout`; NavigationContainer applies it, a bare UIHostingController root should too.
+    func momoScreenLayout() -> some View {
+        modifier(ScreenLayoutReader())
+    }
+}

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

@@ -14,19 +14,61 @@ 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() }
-    private var reservedBottom: CGFloat { BOTTOM_TAB_BAR_HEIGHT + bottomInset + Spacing.S }
+    // the Duo bars overlay the content or sit in the side strip, so only the home indicator is kept clear
+    private var reservedBottom: CGFloat {
+        layout.isIPhoneDuo ? layout.insets.bottom : BOTTOM_TAB_BAR_HEIGHT + bottomInset + Spacing.S
+    }
+
+    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 {
@@ -38,20 +80,31 @@ public struct BottomTab: View {
                 }
             }
             .padding(.bottom, reservedBottom)
+            .environment(\.duoTabBarInsets, duoInsets(compression))
+            .environment(\.duoBarCompression, compression)
             .animation(.easeInOut(duration: 0.2), value: selectedIndex)
 
-            // Tab bar + home-indicator filler.
-            VStack(spacing: 0) {
-                BottomTabBar(
+            if layout.isIPhoneDuo {
+                DuoTabBar(
                     items: items,
                     floatingButton: floatingButton,
                     selectedIndex: selectedIndex,
-                    onTabSelected: { index in
-                        if index != selectedIndex { selectedIndex = index }
-                    }
+                    onTabSelected: selectTab,
+                    compression: compression
                 )
-                Colors.black01
-                    .frame(height: bottomInset + Spacing.S)
+            } else {
+                // Tab bar + home-indicator filler.
+                VStack(spacing: 0) {
+                    BottomTabBar(
+                        items: items,
+                        floatingButton: floatingButton,
+                        selectedIndex: selectedIndex,
+                        onTabSelected: selectTab
+                    )
+                    Colors.black01
+                        .frame(height: bottomInset + Spacing.S)
+                        .ignoresSafeArea(edges: .horizontal)
+                }
             }
         }
         .frame(maxWidth: .infinity, maxHeight: .infinity)
@@ -59,6 +112,10 @@ public struct BottomTab: View {
         .preference(key: IsBottomTabRootKey.self, value: true)
     }
 
+    private func selectTab(_ index: Int) {
+        if index != selectedIndex { selectedIndex = index }
+    }
+
     @ViewBuilder
     private func tabScreen(for index: Int) -> some View {
         let item = items[index]

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

@@ -65,7 +65,10 @@ struct BottomTabBar: View {
     let selectedIndex: Int
     let onTabSelected: (Int) -> Void
 
-    private var screenWidth: CGFloat { UIScreen.main.bounds.width }
+    @Environment(\.screenLayout) private var layout
+
+    // the bar sits between the side safe areas
+    private var screenWidth: CGFloat { layout.width - layout.insets.leading - layout.insets.trailing }
     private var mid: Int { items.count / 2 }
 
     private var tabWidth: CGFloat {
@@ -95,7 +98,7 @@ struct BottomTabBar: View {
             }
             .frame(maxWidth: .infinity)
             .frame(height: BOTTOM_TAB_BAR_HEIGHT)
-            .background(Colors.black01)
+            .background(Colors.black01.ignoresSafeArea(edges: .horizontal))
 
             // Animated selection indicator.
             RoundedRectangle(cornerRadius: 2)