@momo-kits/native-kits 0.300.3 → 0.300.4

package/CLAUDE.md

@@ -18,7 +18,7 @@ Guidance for working in this repo. Keep it accurate — update it when structure
 ## Source layout (`compose/src/commonMain/kotlin/vn/momo/kits/`)
 
 - `components/` — ~50 UI components, **one file per component** (`Button.kt`, `Input*.kt`, `PopupNotify.kt`, …).
-- `application/` — app-level context & config: `Context.kt` (CompositionLocals, `MiniAppContext`, `DesignSystemConfig`), `Localize.kt` (i18n: `LocalizationObject`, `Localize`, default dictionary), `Screen.kt`, header pieces. Also holds the **deprecated** `ApplicationContainer`.
+- `application/` — app-level context & config: `Context.kt` (CompositionLocals, `MiniAppContext`, `DesignSystemConfig`), `Localize.kt` (i18n: `LocalizationObject`, `Localize`, default dictionary), `LiteScreen.kt` (standalone lightweight screen with its own header), `WidgetContainer.kt`.
 - `navigation/` — `NavigationContainer.kt` (**canonical entry point**), `Navigator.kt`, `Navigation.kt`, `StackScreen.kt`, `bottomtab/`, `component/`, `tracking/`.
 - `const/` — design tokens: `Theme.kt`, `Colors.kt`, `Typography.kt`, `Spacing.kt`, `Radius.kt`.
 - `layout/`, `modifier/`, `utils/`.
@@ -35,18 +35,55 @@ Run `./gradlew :compose:testAndroidHostTest` for the request ownership tests in
 ./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
 
-- **Entry point:** wrap content in `NavigationContainer(...)` from `navigation/`. It builds the `Navigator`, takes a host-supplied `Localize` (falls back to an empty one), and provides the CompositionLocals below. **Do not use** `ApplicationContainer` (`application/NavigationContainer.kt`) — deprecated and does **not** wire `LocalLocalize` / `LocalNavigator` / `LocalMaxApi`.
+- **Entry point:** wrap content in `NavigationContainer(...)` from `navigation/`. It builds the `Navigator`, takes a host-supplied `Localize` (falls back to an empty one), and provides the CompositionLocals below. The legacy `Screen` / `ApplicationContainer` / `ComposeApi` stack has been removed on both sides — don't reintroduce it.
 - **Configuration flows via CompositionLocals**, not params. Public ones: `AppTheme`, `AppStatusBar`, `AppNavigationBar` (`const/Theme.kt`); `ApplicationContext`, `AppConfig`, `AppLanguage`, `LocalLocalize` (`application/`); `LocalNavigator`, `LocalMaxApi` (`navigation/`). Read with `X.current`.
-- **Design-system config** (`trustBanner`, `headerBar`, `headerGradient`): the host seeds `KitDesignSystemConfig.update(...)` once (same pattern as `KitFontScale`); `NavigationContainer` provides it as `LocalDesignSystemConfig` (param `designSystemConfig` → parent → global) and applies `headerBar` as the header image when the theme has none.
+- **`DesignSystemKits`** (`application/DesignSystemKits.kt`) is the single app-wide holder for the host-owned design-system inputs: font scale (`userScaleRate` / `useOSScaleRate`), whitelist (`isWhiteList`) and the remote `DesignSystemConfig`, bundled as `DesignSystemKitsConfigs`. The host calls `DesignSystemKits.init(source)` once at startup with its `DesignSystemKitsSource` (sync `getConfigs()` seed + `configsFlow`); `init` is idempotent. Without a source, call `setConfigs(...)` directly. Read with `getConfigs()` (snapshot state, recomposes); non-Compose observers use `configsFlow`.
+- **SwiftUI twin:** `ios/Application/DesignSystemKits.swift` mirrors it field for field (`DesignSystemKitsConfigs` with `designSystemConfig: KitConfig?`, `setConfigs` / `getConfigs`), plus the OS Dynamic Type factor (`osFontScale`). There is no `init(source:)` (Swift reserves `init`): the host observes its own bridge and pushes. A host that can't share Swift types (the KMP bridge) calls `DesignSystemKits.shared.setConfigs(json:)` (`ios/Application/DesignSystemKitsPayload.swift`); the JSON field names are a contract with momo-app's serializer (`HostDesignSystemKits.observeConfigsJson`, payload classes in `DesignSystemData.kt`) — change both together. Invalid JSON is ignored. The SwiftUI kit can't link the Kotlin `kits` framework (a second Kotlin/Native runtime would hold a second, never-initialized singleton), so the render-time logic — `FontScale` formula, Dynamic Type observation — is intentionally duplicated in Swift; only values flow across.
+- **Design-system config** (`trustBanner`, `headerBar`, `headerGradient`): `NavigationContainer` provides it as `LocalDesignSystemConfig` (param `designSystemConfig` → parent → `DesignSystemKits`) and applies `headerBar` as the header image when the theme has none.
 - **Platform code** goes through `expect`/`actual` in `platform/` — never reference Android/iOS APIs from `commonMain` directly.
 - **Native bridge:** typed `IMaxApi` from NativeMaxApi `0.3.1` (`vn.momo.maxapi`, exposed as `LocalMaxApi`) is the host-app bridge. Toolkit uses `ToolkitOptions` to preserve custom groups and system-tool policy; pending callbacks are cancelled when their composition is disposed. Containers borrow the host client and must not close it.
 - 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/`)
+
+- **Layout mirrors Compose:** `ios/Navigation/` follows `navigation/` file for file (`NavigationContainer`, `Navigator`, `Navigation` (options + per-screen `Navigation`), `StackScreen` (incl. `NavigationFooter`), `StackTransition`, `SwipeBackHaptic`, `BottomSheet`, `ModalScreen`, `HostBackGestureBridge`, `BottomTab/`, `Component/`, `Tracking/`); `ios/Layout/ScreenLayout.swift` mirrors `layout/`. `ios/Application/` keeps only context (`ApplicationEnvironment`), `Localize*` and `MaxApi` (Compose `application/`). Change a navigation piece on both sides together.
+- **File basenames must be unique across the pod** — Swift fails with "filename used twice" even in different folders. New folders under `ios/` must be added to `source_files` in `ios/native-kits.podspec`.
+- Screens update their own chrome at runtime through `@EnvironmentObject var navigation: Navigation` → `setOptions { $0.title = … }` (Compose `LocalNavigation`); bottom tabs keep one `Navigation` per tab. The host back bridge is `HostBackGestureBridge.shared` (`NavigatorManager` is a deprecated alias); a bottom tab off its first tab routes back to the first tab (`Navigator.tabBackHandler`, keyed by the hosting screen).
+- Everything, navigation shell included, supports the pod's minimum **iOS 15** — no `@available` gates on public types. iOS 16+ APIs only behind `#available` with an iOS 15 path (`Layout`: `BottomSheet` `CapHeight`, `GridFlow` → `_VariadicView` flow row).
+- **Usage is `NavigationContainer` + `Navigator` + `Navigation` only**; the kit owns the stack, transitions, overplays and back gesture. There is no `NavigationStack`: `StackTransition.swift` holds `StackHost` (representable) + `StackController`, the NavHost counterpart. Each entry gets its own `UIHostingController`, kept while on the stack and removed from the window while covered (state kept, onDisappear / onAppear like UINavigationController). Motion is a SwiftUI `offset` per card driven by one `coverage` value on a display link (a UIKit transform would move the safe area); it is Compose `StackTransition` 1:1 (RN `forStackTransitionWithOverlay`: linear 300ms slide, 0.3 parallax, `pink09` scrim to 0.6, 8pt edge shadow to 0.3). Card roots get the container environment via `.environment(\.self, …)` with the kit environment re-applied on top, so host environment objects reach screens.
+- One back stack, root first (`Navigator.entries`, Compose's back stack): `present` appends a dialog entry that rises (FastOutSlowIn 300ms) and later pushes stack on top of it; `dismiss` drops the topmost dialog and everything above it (slides down whole); `popToRoot` returns to the active flow's root. Overplays (modal / bottom sheet / snackbar) render inside the screen they were shown over (`OverplayItem.screenId`, Compose `currentRootId`), so a later push slides over them.
+- Host back gesture: `HostBackGestureBridge.started` / `progressed` / `completed` / `cancelled` scrub the pop (`Navigator.backStarted` …) only for a plain pop; tab back, `onBackHandler`, `preventBack`, an open overplay or a presented top wait for the release and go through `onBackSafe`. `SwipeBackHaptic` ticks at 50pt (`MaxApi.triggerEventVibration`, default = system light impact).
+- 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` (Apple's foldable check: a `.division` reserved region, queried with include-inactive; Swift also latches on `UIHingeInteraction`) 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 the header is 76pt and the row starts at 14pt so the title centers on the camera punchout; in landscape the row centers on the camera when it sits at the top end of the strip (else on the back button) and the header reaches 8pt below the back button.
+- iPhone Duo inner display in portrait (status bar on top): the header row shares the status bar band — `headerHeight` 94pt (2 × the clock digits' y 47), `headerStatusBarHeight` 0 — and `ScreenLayout.statusBarClearance` keeps it between the clock / battery clusters (from reserved regions, else 128pt on the right). Back and toolkit use the 48pt side bar controls laid out horizontally (`ToolkitLayout.SideBarRow`); the collapsed search and a centered title stay clear of the clusters. Port of momo-kits `90af33ba2`.
+- 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 (0 when the screen puts nothing there) 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.
@@ -69,9 +106,9 @@ The SwiftUI port differs from Compose in one important way: **it follows the hos
 
 One formula, both platforms: the device-width scale (`width / 375`, capped at `+5pt`) and the OS Dynamic Type scale (capped at `1.5×`) are computed independently and the **larger wins**. When `useOSScaleRate` is false neither applies — the size is just multiplied by `userScaleRate`. Max font scale is fixed at 1.5; the old per-call/per-scope override is deprecated and ignored on both sides.
 
-- **Compose** — `const/Typography.kt` (`scaleSize` overloads for `Float`/`Dp`/`TextUnit`/`TextStyle`). The `TextUnit` overload divides by `density.fontScale` so Compose's own `sp` scaling isn't applied twice. Inputs: `LocalContext.current` (`MiniAppContext.userScaleRate` / `useOSScaleRate`, per-field) falling back to the `KitFontScale` global. On iOS, `platform/OsFontScale.ios.kt` observes `UIContentSizeCategoryDidChangeNotification` and overrides `LocalDensity` — Compose MP otherwise reads `fontScale` once at `ComposeUIViewController` creation. Wired at `NavigationContainer`.
-- **SwiftUI** — `ios/Typography/FontScale.swift`. `FontScale` is an immutable snapshot with `callAsFunction`, so a view reads `@Environment(\.momoFontScale) private var fontScale` and calls `fontScale(16)`. `FontScaleStore.shared` is the `ObservableObject` holding both inputs and the OS factor (it observes `UIContentSizeCategory.didChangeNotification`); the host pushes its preference with `update(userScaleRate:useOSScaleRate:)`.
-- **Never set `\.momoFontScale` directly** — same trap as `\.localize`. Inject via `.momoFontScale(_:context:)`, which holds the store as `@ObservedObject`; that is what re-publishes the snapshot. `NavigationContainer` does it (passing `MiniAppContext` so the per-mini-app override applies); a bare `UIHostingController` root must too. The environment default reads the live store, so an un-injected subtree still gets correct values — just not live ones.
+- **Compose** — `const/Typography.kt` (`scaleSize` overloads for `Float`/`Dp`/`TextUnit`/`TextStyle`). The `TextUnit` overload divides by `density.fontScale` so Compose's own `sp` scaling isn't applied twice. Inputs: `LocalContext.current` (`MiniAppContext.userScaleRate` / `useOSScaleRate`, per-field) falling back to `DesignSystemKits.getConfigs()`. On iOS, `platform/OsFontScale.ios.kt` observes `UIContentSizeCategoryDidChangeNotification` and overrides `LocalDensity` — Compose MP otherwise reads `fontScale` once at `ComposeUIViewController` creation. Wired at `NavigationContainer`.
+- **SwiftUI** — `ios/Typography/FontScale.swift`. `FontScale` is an immutable snapshot with `callAsFunction`, so a view reads `@Environment(\.momoFontScale) private var fontScale` and calls `fontScale(16)`. `DesignSystemKits.shared` is the `ObservableObject` holding the host inputs and the OS factor (it observes `UIContentSizeCategory.didChangeNotification`); the host pushes them with `setConfigs(_:)`.
+- **Never set `\.momoFontScale` directly** — same trap as `\.localize`. Inject via `.momoFontScale(_:context:)`, which holds `DesignSystemKits` as `@ObservedObject`; that is what re-publishes the snapshot. It also injects `\.designSystemKitsConfigs`, which `MomoText` (whitelist font) and `TrustBanner` (fallback after `ApplicationEnvironment.config`) read so a host push re-renders them. `NavigationContainer` does it (passing `MiniAppContext` so the per-mini-app override applies); a bare `UIHostingController` root must too. The environment default reads the live store, so an un-injected subtree still gets correct values — just not live ones.
 - The global `scaleSize(_:)` and `Font.appFont(size:)` remain for call sites that can't read the environment (UIKit bridges, free functions). They are **not** reactive. `Font.header_default_bold` & friends are computed `static var`s for the same reason — as stored `static let`s they froze the scale at first access. `UIViewRepresentable`s should read `context.environment.momoFontScale` instead, and re-apply the font in `updateUIView`, not only in `makeUIView`.
 
 ## Code conventions
@@ -95,5 +132,12 @@ Prefer one tight line at the surprising spot over a paragraph. Match the (low) c
 ## Gotchas
 
 - **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`.
+- `LiteScreen` keeps its own `application.HeaderType` enum (`DEFAULT`/`EXTENDED`/`NONE`), unrelated to the sealed `navigation.component.HeaderType`; its toolkit is the navigation `Toolkit` (through `LocalMaxApi`).
 - 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/README.md

@@ -150,8 +150,8 @@ themeController(defaultTheme.copy(colors = defaultTheme.colors.copy(primary = Co
 ---
 
 ### Lưu ý khác
-- `Screen` composable cũ được đánh dấu `@Deprecated`; sử dụng `NavigationContainer + StackScreen` để hưởng lợi dynamic route và animation.
-- `DesignSystemWhiteList` trong `application/ApplicationContainer.kt` hỗ trợ fallback cho host cũ; đừng kích hoạt nếu không cần.
+- `Screen` / `ApplicationContainer` cũ (Compose và SwiftUI) đã bị gỡ; dùng `NavigationContainer + StackScreen`.
+- `KitDesignSystem.update(isWhiteList = …)` (`const/KitDesignSystem.kt`) bật font design system mới cho host trong whitelist; đừng kích hoạt nếu không cần.
 - Khi thêm tài nguyên mới, đặt trong `shared/src/commonMain/composeResources` để Compose Multiplatform plugin sinh accessor tự động.
 - Repo không bundle SDK bên thứ ba ngoại trừ `vn.momo.corex.maxapi`, Compose/Coil/Ktor **và Compottie** cho animation.
 

package/ios/Application/ApplicationEnvironment.swift

@@ -17,8 +17,8 @@ public class MiniAppContext {
     public var toolkitConfig: [String: Any] = [:]
     public var providerId: String = "momo"
     public var permissions: [[String: Any]] = []
-    // Per-mini-app font-scale override; nil falls back to FontScaleStore. Mirrors Compose's
-    // MiniAppContext.userScaleRate / useOSScaleRate, which win per field over KitFontScale.
+    // Per-mini-app font-scale override; nil falls back to DesignSystemKits. Mirrors Compose's
+    // MiniAppContext.userScaleRate / useOSScaleRate, which win per field over DesignSystemKits.
     public var userScaleRate: CGFloat? = nil
     public var useOSScaleRate: Bool? = nil
 
@@ -37,10 +37,17 @@ public class MiniAppContext {
     }
 }
 
-public class KitConfig {
-    public var trustBanner: TrustBannerData? = nil
-    public var headerBar: String? = nil
-    public var headerGradient: String? = nil
+// Value type so DesignSystemKitsConfigs can dedupe host pushes; mirrors Compose's DesignSystemConfig.
+public struct KitConfig: Equatable {
+    public var trustBanner: TrustBannerData?
+    public var headerBar: String?
+    public var headerGradient: String?
+
+    public init(trustBanner: TrustBannerData? = nil, headerBar: String? = nil, headerGradient: String? = nil) {
+        self.trustBanner = trustBanner
+        self.headerBar = headerBar
+        self.headerGradient = headerGradient
+    }
 }
 
 public class ApplicationEnvironment: ObservableObject {
@@ -59,6 +66,17 @@ public class ApplicationEnvironment: ObservableObject {
     }
 }
 
+extension ApplicationEnvironment {
+    /// Closes the mini app: through `composeApi` as before, else `maxApi` (Compose `maxApi.dismiss`).
+    func requestDismiss() {
+        if let composeApi {
+            composeApi.requestCallback(funcName: "dismiss", params: nil, onResponse: nil)
+        } else {
+            maxApi?.dismiss(completion: nil)
+        }
+    }
+}
+
 private struct ApplicationEnvironmentKey: EnvironmentKey {
     static let defaultValue = ApplicationEnvironment()
 }

package/ios/Application/DesignSystemKits.swift

@@ -0,0 +1,100 @@
+// File: ios/Application/DesignSystemKits.swift
+// Created At: 2026-10-02 14:17:29 +07:00
+// Created By: AI
+// AI Agent: Claude Code
+// Model: claude-opus-5-5
+
+// AI-GENERATED START: app-wide design-system holder mirroring Compose's DesignSystemKits
+import SwiftUI
+
+/// Host-owned design-system inputs; mirrors Compose's `DesignSystemKitsConfigs` field for field.
+public struct DesignSystemKitsConfigs: Equatable {
+    public var userScaleRate: CGFloat
+    public var useOSScaleRate: Bool
+    public var isWhiteList: Bool
+    public var designSystemConfig: KitConfig?
+
+    public init(
+        userScaleRate: CGFloat = 1,
+        useOSScaleRate: Bool = true,
+        isWhiteList: Bool = false,
+        designSystemConfig: KitConfig? = nil
+    ) {
+        self.userScaleRate = userScaleRate
+        self.useOSScaleRate = useOSScaleRate
+        self.isWhiteList = isWhiteList
+        self.designSystemConfig = designSystemConfig
+    }
+}
+
+/// App-wide holder for the SwiftUI kit, mirroring Compose's `DesignSystemKits`. The kit is sandboxed from the
+/// host, so the host pushes `setConfigs(_:)` at startup and on every change; the OS Dynamic Type factor is
+/// tracked here. Views re-render on change as long as the subtree got `.momoFontScale()` (`NavigationContainer`
+/// applies it). Swift reserves `init`, so there is no `init(source:)` twin: the host observes and pushes.
+public final class DesignSystemKits: ObservableObject {
+    public static let shared = DesignSystemKits()
+
+    @Published private var configs = DesignSystemKitsConfigs()
+    @Published public private(set) var osFontScale: CGFloat = DesignSystemKits.currentOsFontScale()
+
+    private init() {
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(contentSizeCategoryDidChange),
+            name: UIContentSizeCategory.didChangeNotification,
+            object: nil
+        )
+    }
+
+    public func setConfigs(_ configs: DesignSystemKitsConfigs) {
+        onMain {
+            // Re-assigning an unchanged value would still publish and invalidate every kit subtree.
+            guard self.configs != configs else { return }
+            self.configs = configs
+        }
+    }
+
+    public func getConfigs() -> DesignSystemKitsConfigs {
+        configs
+    }
+
+    public var fontScale: FontScale {
+        FontScale(
+            userScaleRate: configs.userScaleRate,
+            useOSScaleRate: configs.useOSScaleRate,
+            osFontScale: osFontScale
+        )
+    }
+
+    @objc private func contentSizeCategoryDidChange() {
+        let next = Self.currentOsFontScale()
+        guard next != osFontScale else { return }
+        osFontScale = next
+    }
+
+    /// Same factor Compose's iOS `ProvideOsFontScale` derives from
+    /// `UIFont.preferredFont(forTextStyle: .body).pointSize / 17`, so both iOS surfaces scale alike.
+    static func currentOsFontScale() -> CGFloat {
+        let base = UIFont.systemFont(ofSize: UIFont.labelFontSize)
+        return UIFontMetrics.default.scaledFont(for: base).pointSize / base.pointSize
+    }
+
+    /// Synchronous when already on main — an async hop would defer the change by a frame.
+    private func onMain(_ work: @escaping () -> Void) {
+        if Thread.isMainThread { work() } else { DispatchQueue.main.async(execute: work) }
+    }
+}
+
+private struct DesignSystemKitsConfigsKey: EnvironmentKey {
+    /// Computed, never stored: an un-injected subtree still reads the live holder, just not reactively.
+    static var defaultValue: DesignSystemKitsConfigs { DesignSystemKits.shared.getConfigs() }
+}
+
+public extension EnvironmentValues {
+    /// Injected by `.momoFontScale()`; never set it directly (same trap as `\.momoFontScale`).
+    var designSystemKitsConfigs: DesignSystemKitsConfigs {
+        get { self[DesignSystemKitsConfigsKey.self] }
+        set { self[DesignSystemKitsConfigsKey.self] = newValue }
+    }
+}
+// AI-GENERATED END: app-wide design-system holder mirroring Compose's DesignSystemKits

package/ios/Application/DesignSystemKitsPayload.swift

@@ -0,0 +1,68 @@
+// File: ios/Application/DesignSystemKitsPayload.swift
+// Created At: 2026-10-02 15:40:00 +07:00
+// Created By: AI
+// AI Agent: Claude Code
+// Model: claude-opus-5-5
+
+// AI-GENERATED START: JSON entry point for hosts that can't share Swift types with the kit
+import Foundation
+
+public extension DesignSystemKits {
+    /// Applies configs pushed as JSON by a host that can't share Swift types with the kit (e.g. the KMP bridge).
+    /// Invalid JSON is ignored and the current configs are kept.
+    func setConfigs(json: String) {
+        guard let data = json.data(using: .utf8),
+              let payload = try? JSONDecoder().decode(DesignSystemKitsPayload.self, from: data) else { return }
+        setConfigs(payload.configs)
+    }
+}
+
+// Wire format; field names match the host's serializer (momo-app HostDesignSystemKits / DesignSystemData.kt).
+private struct DesignSystemKitsPayload: Decodable {
+    let userScaleRate: CGFloat
+    let useOSScaleRate: Bool
+    let isWhiteList: Bool
+    let designSystemConfig: KitConfigPayload?
+
+    var configs: DesignSystemKitsConfigs {
+        DesignSystemKitsConfigs(
+            userScaleRate: userScaleRate,
+            useOSScaleRate: useOSScaleRate,
+            isWhiteList: isWhiteList,
+            designSystemConfig: designSystemConfig?.kitConfig
+        )
+    }
+}
+
+private struct KitConfigPayload: Decodable {
+    let trustBanner: TrustBannerPayload?
+    let headerBar: String?
+    let headerGradient: String?
+
+    var kitConfig: KitConfig {
+        KitConfig(trustBanner: trustBanner?.trustBannerData, headerBar: headerBar, headerGradient: headerGradient)
+    }
+}
+
+private struct TrustBannerPayload: Decodable {
+    let content: [String: String]
+    let subContent: [String: String]
+    let pciImage: String?
+    let sslImage: String?
+    let urlConfig: String?
+    let icons: [String]?
+    let momoImage: String?
+
+    var trustBannerData: TrustBannerData {
+        TrustBannerData(
+            content: content,
+            subContent: subContent,
+            pciImage: pciImage,
+            momoImage: momoImage,
+            sslImage: sslImage,
+            icons: icons,
+            urlConfig: urlConfig ?? ""
+        )
+    }
+}
+// AI-GENERATED END: JSON entry point for hosts that can't share Swift types with the kit

package/ios/Application/MaxApi.swift

@@ -5,14 +5,41 @@
 //  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`) —
-//  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 Foundation
+import UIKit
 
 public protocol MaxApi {
     func track(eventName: String, params: [String: Any?])
     func dismiss(completion: (() -> Void)?)
     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 {
+    /// Hosts that don't bridge haptics still get the system light tick.
+    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/Avatar/Avatar.swift

@@ -74,12 +74,12 @@ public struct Avatar: View {
             .clipShape(RoundedRectangle(cornerRadius: cornerRadius))
             .overlay(
                 RoundedRectangle(cornerRadius: cornerRadius)
-                    .stroke(theme.colors.border.default, lineWidth: 1)
+                    .strokeBorder(theme.colors.border.default, lineWidth: 1)
             )
 
             // Badge icons — outside clip so they are not cut by border
             if shouldShowIconTop {
-                ImageView(LOGO_MOMO_URL)
+                ImageView(LOGO_MOMO_URL, contentMode: .fill)
                     .frame(width: badgeSizeDp, height: badgeSizeDp)
                     .clipShape(RoundedRectangle(cornerRadius: badgeCornerRadius))
                     .offset(x: 1, y: -1)
@@ -92,7 +92,7 @@ public struct Avatar: View {
             }
 
             if shouldShowIconBottom {
-                ImageView(iconSupport)
+                ImageView(iconSupport, contentMode: .fill)
                     .frame(width: badgeSizeDp, height: badgeSizeDp)
                     .clipShape(RoundedRectangle(cornerRadius: badgeCornerRadius))
                     .offset(x: 1, y: 1)
@@ -107,6 +107,7 @@ public struct Avatar: View {
         .frame(width: size.sizeDp, height: size.sizeDp)
         .accessibilityElement(children: .ignore)
         .accessibilityLabel(automationId)
+        .accessibilityIdentifier(automationId)
     }
 
     // MARK: Internal

package/ios/Badge/Badge.swift

@@ -33,7 +33,8 @@ public struct Badge: View {
     }
     
     private func formatTitle(_ text: String) -> String {
-        if isNumber(text), let number = Int(text), number > 99 {
+        // Digits too long for Int are well over 99.
+        if isNumber(text), (Int(text) ?? .max) > 99 {
             return "99+"
         }
         return text
@@ -54,14 +55,15 @@ public struct Badge: View {
     }
     
     public var body: some View {
-        MomoText(formatTitle(label), typography: .actionXxsBold, color: Colors.black01)
+        MomoText(formatTitle(label), typography: .actionXxsBold, color: Colors.black01, maxLines: 1)
             .padding(.horizontal, Spacing.XS)
-            .frame(minWidth: fontScale(16), minHeight: fontScale(16))
+            .frame(minWidth: fontScale(16))
+            .frame(height: fontScale(16))
             .background(badgeColor)
             .cornerRadius(Radius.M)
             .overlay(
                 RoundedRectangle(cornerRadius: Radius.M)
-                    .stroke(Colors.black01, lineWidth: 1)
+                    .strokeBorder(Colors.black01, lineWidth: 1)
             )
     }
 }

package/ios/Badge/BadgeDot.swift

@@ -25,7 +25,7 @@ public struct BadgeDot: View {
             .frame(width: size.size, height: size.size)
             .overlay(
                 Circle()
-                    .stroke(Colors.black01, lineWidth: 1)
+                    .strokeBorder(Colors.black01, lineWidth: 1)
             )
     }
 }

package/ios/Badge/BadgeRibbon.swift

@@ -160,7 +160,6 @@ public struct BadgeRibbon: View {
             MomoText(label, typography: .labelXsMedium, color: Colors.black01, maxLines: 1)
                 .rotationEffect(rotation)
                 .frame(height: RibbonConstants.skewBodyHeight)
-                .padding(.horizontal, 8)
                 .background(backgroundColor)
             
             rightTail
@@ -204,7 +203,9 @@ public struct BadgeRibbon: View {
 /// rotation) — the label gets the same scale applied a second time so it stays right-reading
 /// while only the ribbon shape flips.
 public struct RoundedBadgeRibbon: View {
+    @Environment(\.appTheme) private var theme
     @Environment(\.momoFontScale) private var fontScale
+    @Environment(\.designSystemKitsConfigs) private var designSystemKitsConfigs
     let text: String
     let position: RibbonPosition
 
@@ -224,7 +225,12 @@ public struct RoundedBadgeRibbon: View {
 
     private var measuredTextSize: CGSize {
         let fontSize = fontScale(TypographyStyle.labelXsMedium.fontSize)
-        let font = UIFont.systemFont(ofSize: fontSize, weight: .medium)
+        let font = momoUIFont(
+            size: fontSize,
+            weight: .medium,
+            family: theme.font,
+            isWhiteList: designSystemKitsConfigs.isWhiteList
+        )
         return text.size(withAttributes: [.font: font])
     }
 

package/ios/Button/Button.swift

@@ -51,15 +51,17 @@ public extension ButtonType {
     }
 
     func contentColor(loading: Bool, theme: Theme) -> Color {
+        let color: Color
         switch self {
-        case .disabled: return theme.colors.text.disable.opacity(loading ? 0.75 : 1)
-        case .primary: return Colors.black01
-        case .secondary: return theme.colors.text.default
-        case .outline: return theme.colors.primary
-        case .tonal: return theme.colors.primary
-        case .danger: return Colors.black01
-        case .text: return theme.colors.primary
+        case .disabled: color = theme.colors.text.disable
+        case .primary: color = Colors.black01
+        case .secondary: color = theme.colors.text.default
+        case .outline: color = theme.colors.primary
+        case .tonal: color = theme.colors.primary
+        case .danger: color = Colors.black01
+        case .text: color = theme.colors.primary
         }
+        return color.opacity(loading ? 0.75 : 1)
     }
 
     var borderColor: Color? {
@@ -219,9 +221,8 @@ public struct Button: View {
         let color: Color? = useTintColor ? textColor : nil
 
         if forceLoading {
-            LottieView(name: "lottie_circle_loader", loopMode: .loop)
+            LottieView(name: "lottie_circle_loader", loopMode: .loop, tintColor: color.map { UIColor($0) })
                 .frame(width: size.iconSize, height: size.iconSize)
-                .colorMultiply(color ?? Colors.black01)
         } else if !icon.isEmpty {
             Icon(source: icon, size: size.iconSize, color: color)
         }
@@ -229,8 +230,8 @@ public struct Button: View {
 }
 
 /// Mirrors Compose's press feedback: the background shrinks via an animated
-/// horizontal inset while the content fades, rather than a plain opacity dim on
-/// the whole button (matching `animatedPadding`/`alpha` in Button.kt).
+/// horizontal inset and the whole button (background included) fades to 0.5,
+/// matching `animatedPadding`/`alpha` in Button.kt.
 private struct ButtonPressFeedbackStyle: ButtonStyle {
     let isEnabled: Bool
     let background: Color
@@ -245,7 +246,6 @@ private struct ButtonPressFeedbackStyle: ButtonStyle {
 
         configuration.label
             .modifier(HugContentOnLegacyOS(isFull: isFull))
-            .opacity(pressed ? 0.5 : 1)
             .background(
                 RoundedRectangle(cornerRadius: radius)
                     .fill(background)
@@ -257,6 +257,9 @@ private struct ButtonPressFeedbackStyle: ButtonStyle {
             )
             .frame(height: height)
             .clipShape(RoundedRectangle(cornerRadius: radius))
+            // `.text` has a clear background, which SwiftUI does not hit-test.
+            .contentShape(RoundedRectangle(cornerRadius: radius))
+            .opacity(pressed ? 0.5 : 1)
             .animation(.easeInOut(duration: 0.1), value: pressed)
     }
 }