@momo-kits/native-kits 0.300.3-debug → 0.300.4-debug

package/compose/src/commonMain/kotlin/vn/momo/kits/platform/ReservedRegions.kt

@@ -0,0 +1,20 @@
+package vn.momo.kits.platform
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.Immutable
+import androidx.compose.ui.unit.Dp
+
+@Immutable
+internal data class ReservedRegion(val x: Dp, val y: Dp, val width: Dp, val height: Dp)
+
+// occlusion: regions the system occludes (iOS 27.1+), in the coordinates of the Compose root view:
+// the iPhone Duo camera, and the status bar cluster as it grows for a call or a Live Activity.
+// isFoldable: the device reports a `.division` (hinge) region, Apple's foldable check.
+@Immutable
+internal data class ReservedRegions(
+    val occlusion: List<ReservedRegion> = emptyList(),
+    val isFoldable: Boolean = false,
+)
+
+@Composable
+internal expect fun rememberReservedRegions(): ReservedRegions

package/compose/src/commonMain/kotlin/vn/momo/kits/utils/Utils.kt

@@ -1,6 +1,11 @@
 package vn.momo.kits.utils
 
 import androidx.compose.foundation.layout.WindowInsets
+import androidx.compose.foundation.layout.WindowInsetsSides
+import androidx.compose.foundation.layout.displayCutout
+import androidx.compose.foundation.layout.only
+import androidx.compose.foundation.layout.union
+import androidx.compose.foundation.layout.windowInsetsPadding
 import androidx.compose.foundation.layout.asPaddingValues
 import androidx.compose.foundation.layout.systemBars
 import androidx.compose.runtime.Composable
@@ -90,6 +95,14 @@ fun getAppStatusBarHeight(): Dp {
     }
 }
 
+internal val horizontalSafeAreaInsets: WindowInsets
+    @Composable get() = WindowInsets.systemBars.union(WindowInsets.displayCutout).only(WindowInsetsSides.Horizontal)
+
+// Left/right safe area like SwiftUI (landscape camera/notch); consumed, so nested StackScreens don't pad twice.
+internal fun Modifier.horizontalSafeAreaPadding(): Modifier = composed {
+    windowInsetsPadding(horizontalSafeAreaInsets)
+}
+
 @Composable
 internal fun getNavigationBarHeight(): Dp {
     return if (AppNavigationBar.current == 0.dp) {

package/compose/src/commonTest/kotlin/vn/momo/kits/navigation/component/HelpCenterRequestTest.kt

@@ -0,0 +1,44 @@
+// File: HelpCenterRequestTest.kt
+// Created At: 2026-10-19 +07:00
+// Created By: AI | AI Agent: Codex | Model: GPT-6
+// AI-GENERATED START: verify Help Center identity and localized payload preservation
+package vn.momo.kits.navigation.component
+
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import vn.momo.kits.application.MiniAppContext
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNull
+
+class HelpCenterRequestTest {
+    @Test
+    fun preservesApplicationIdentityAndLocalizedObjects() {
+        val context = MiniAppContext(
+            appId = "app-id",
+            appCode = "app-code",
+            appIcon = "app-icon",
+            appName = mapOf("vi" to "Tên ứng dụng", "en" to "App name"),
+            description = mapOf("vi" to "Mô tả", "en" to "Description"),
+        )
+        val request = context.helpCenterRequest().context
+        assertEquals(context.appId, request.appId)
+        assertEquals(context.appCode, request.code)
+        assertEquals(context.appIcon, request.icon)
+        assertEquals(JsonObject(mapOf("vi" to JsonPrimitive("Tên ứng dụng"),
+            "en" to JsonPrimitive("App name"))), request.name)
+        assertEquals(JsonObject(mapOf("vi" to JsonPrimitive("Mô tả"),
+            "en" to JsonPrimitive("Description"))), request.description)
+        assertNull(request.support)
+        assertNull(request.toolkitConfig)
+        assertNull(request.permissions)
+    }
+
+    @Test
+    fun preservesPlainStringsAndAbsentValues() {
+        val request = MiniAppContext(appName = "App name").helpCenterRequest().context
+        assertEquals(JsonPrimitive("App name"), request.name)
+        assertNull(request.description)
+    }
+}
+// AI-GENERATED END: verify Help Center identity and localized payload preservation

package/compose/src/commonTest/kotlin/vn/momo/kits/navigation/component/ToolkitRequestsTest.kt

@@ -38,6 +38,21 @@ class ToolkitRequestsTest {
         assertEquals(1, results)
     }
 
+    @Test
+    fun sheetEventsKeepTheirSubscriptionUntilTheOwnerCloses() {
+        val owner = ToolkitRequests()
+        val handle = Handle()
+        var callback: ApiCallback<Boolean> = {}
+        var results = 0
+        owner.observe<Boolean>({ callback = it; handle }) { results++ }
+        callback(ApiResult.Success(true))
+        callback(ApiResult.Success(false))
+        owner.close()
+        callback(ApiResult.Success(true))
+        assertEquals(2, results)
+        assertEquals(1, handle.cancellations)
+    }
+
     private class Handle : ApiRequestHandle {
         override val requestId = "toolkit-test"
         var cancellations = 0

package/compose/src/iosMain/kotlin/vn/momo/kits/const/HostFont.ios.kt

@@ -5,6 +5,7 @@ package vn.momo.kits.const
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.remember
 import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.platform.Font
 import kotlinx.cinterop.ExperimentalForeignApi
 import kotlinx.cinterop.addressOf
@@ -15,7 +16,7 @@ import platform.Foundation.dataWithContentsOfFile
 import platform.posix.memcpy
 
 @Composable
-internal actual fun hostFontFamily(fileName: String): FontFamily? = remember(fileName) {
+internal actual fun hostFontFamily(fileName: String, weight: FontWeight): FontFamily? = remember(fileName, weight) {
     val name = fileName.substringBeforeLast('.')
     val ext = fileName.substringAfterLast('.', "")
     // Font từ font-source nằm rời ở bundle root, không nằm trong compose-resources.
@@ -26,6 +27,7 @@ internal actual fun hostFontFamily(fileName: String): FontFamily? = remember(fil
             getData = {
                 NSData.dataWithContentsOfFile(path)?.toByteArray() ?: ByteArray(0)
             },
+            weight = weight,
         ),
     )
 }

package/compose/src/iosMain/kotlin/vn/momo/kits/platform/Platform.ios.kt

@@ -39,11 +39,15 @@ import platform.Foundation.NSBundle
 import platform.UIKit.UIColor
 import platform.UIKit.UIDevice
 import platform.UIKit.UIScreen
+import platform.UIKit.UIUserInterfaceIdiomPhone
 import vn.momo.kits.navigation.AttachHostBackGesture
 import vn.momo.kits.navigation.Navigator
 
 actual fun getPlatformName(): String = "iOS"
 
+actual fun isPhoneIdiom(): Boolean =
+    UIDevice.currentDevice.userInterfaceIdiom == UIUserInterfaceIdiomPhone
+
 @OptIn(ExperimentalForeignApi::class)
 @Composable
 actual fun getScreenDimensions(): ScreenDimension = memScoped {

package/compose/src/iosMain/kotlin/vn/momo/kits/platform/ReservedRegions.ios.kt

@@ -0,0 +1,138 @@
+package vn.momo.kits.platform
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.uikit.LocalUIViewController
+import androidx.compose.ui.unit.dp
+import kotlinx.cinterop.BetaInteropApi
+import kotlinx.cinterop.CFunction
+import kotlinx.cinterop.COpaquePointer
+import kotlinx.cinterop.ExperimentalForeignApi
+import kotlinx.cinterop.interpretCPointer
+import kotlinx.cinterop.interpretObjCPointer
+import kotlinx.cinterop.interpretObjCPointerOrNull
+import kotlinx.cinterop.invoke
+import kotlinx.cinterop.objcPtr
+import kotlinx.cinterop.reinterpret
+import kotlinx.cinterop.readValue
+import kotlinx.cinterop.useContents
+import platform.CoreGraphics.CGRectZero
+import platform.Foundation.NSArray
+import platform.Foundation.NSSelectorFromString
+import platform.Foundation.NSValue
+import platform.Foundation.valueForKey
+import platform.UIKit.CGRectValue
+import platform.UIKit.UIView
+import platform.UIKit.UIViewAutoresizingFlexibleHeight
+import platform.UIKit.UIViewAutoresizingFlexibleWidth
+import platform.darwin.NSObject
+import platform.Foundation.NSClassFromString
+import platform.posix.RTLD_DEFAULT
+import platform.posix.dlsym
+
+// The API is newer than the SDK Kotlin/Native binds, so it is reached through the runtime.
+@OptIn(ExperimentalForeignApi::class)
+private val regionsOfKind = NSSelectorFromString("reservedRegionsOfKind:")
+
+@OptIn(ExperimentalForeignApi::class)
+private val regionsOfKindOptions = NSSelectorFromString("reservedRegionsOfKind:options:")
+
+// a hinge never goes away, so a positive answer is kept for every later container
+private var isKnownFoldable = false
+
+@OptIn(ExperimentalForeignApi::class, BetaInteropApi::class)
+private fun regionKind(name: String): Any? {
+    // a class object fails `as? NSObjectProtocol` (K/N checks it as an instance), so it is reinterpreted
+    val kindClass = NSClassFromString("UIViewReservedRegionKind")
+        ?.let { interpretObjCPointer<NSObject>(it.objcPtr()) } ?: return null
+    return kindClass.performSelector(NSSelectorFromString(name))
+}
+
+// performSelector cannot pass the NSUInteger options, so objc_msgSend is called with the method's own signature.
+@OptIn(ExperimentalForeignApi::class)
+private val msgSendRegionsOfKindOptions = dlsym(RTLD_DEFAULT, "objc_msgSend")
+    ?.reinterpret<CFunction<(COpaquePointer?, COpaquePointer?, COpaquePointer?, ULong) -> COpaquePointer?>>()
+
+// Apple's foldable check: only a device with a hinge reports a `.division` region, inactive while
+// flat (UIViewReservedRegionQueryOptionsIncludeInactive) but still there. Screen size cannot tell it
+// apart from a large iPhone in landscape or a narrowed window.
+@OptIn(ExperimentalForeignApi::class)
+private fun UIView.hasDivisionRegion(): Boolean {
+    if (window == null || !respondsToSelector(regionsOfKindOptions)) return false
+    val msgSend = msgSendRegionsOfKindOptions ?: return false
+    val kind = regionKind("divisionRegionKind") as? NSObject ?: return false
+    val result = msgSend(
+        interpretCPointer(objcPtr()),
+        regionsOfKindOptions,
+        interpretCPointer(kind.objcPtr()),
+        1uL,
+    )
+    val regions = interpretObjCPointerOrNull<NSArray>(result?.rawValue ?: return false)
+    return (regions?.count ?: 0uL) > 0uL
+}
+
+@OptIn(ExperimentalForeignApi::class)
+private fun UIView.occlusionRegions(target: UIView): List<ReservedRegion> {
+    if (window == null || !respondsToSelector(regionsOfKind)) return emptyList()
+    val kind = regionKind("occlusionRegionKind") ?: return emptyList()
+    val regions = when (val result = performSelector(regionsOfKind, withObject = kind)) {
+        is List<*> -> result
+        is NSArray -> List(result.count.toInt()) { result.objectAtIndex(it.toULong()) }
+        else -> return emptyList()
+    }
+    return regions.mapNotNull { region ->
+        val frame = ((region as? NSObject)?.valueForKey("frame") as? NSValue)?.CGRectValue ?: return@mapNotNull null
+        convertRect(frame, toView = target).useContents {
+            ReservedRegion(origin.x.dp, origin.y.dp, size.width.dp, size.height.dp)
+        }
+    }
+}
+
+// Invisible full-size probe: reading the regions in layoutSubviews makes UIKit run it again
+// when they change, so nothing polls.
+@OptIn(ExperimentalForeignApi::class)
+private class ReservedRegionsProbe(
+    private val onChange: (ReservedRegions) -> Unit,
+) : UIView(frame = CGRectZero.readValue()) {
+    private var last: ReservedRegions? = null
+
+    init {
+        userInteractionEnabled = false
+        autoresizingMask = UIViewAutoresizingFlexibleWidth or UIViewAutoresizingFlexibleHeight
+    }
+
+    override fun layoutSubviews() {
+        super.layoutSubviews()
+        // re-read until found: the window may not report the hinge on the first pass
+        if (!isKnownFoldable) isKnownFoldable = hasDivisionRegion()
+        val regions = ReservedRegions(superview?.let { occlusionRegions(it) } ?: emptyList(), isKnownFoldable)
+        if (regions != last) {
+            last = regions
+            onChange(regions)
+        }
+    }
+
+    override fun didMoveToWindow() {
+        super.didMoveToWindow()
+        setNeedsLayout()
+    }
+}
+
+@OptIn(ExperimentalForeignApi::class)
+@Composable
+internal actual fun rememberReservedRegions(): ReservedRegions {
+    if (!isPhoneIdiom()) return ReservedRegions()
+    val host = LocalUIViewController.current.view
+    var regions by remember { mutableStateOf(ReservedRegions(isFoldable = isKnownFoldable)) }
+    DisposableEffect(host) {
+        val probe = ReservedRegionsProbe { regions = it }
+        probe.setFrame(host.bounds)
+        host.insertSubview(probe, atIndex = 0)
+        onDispose { probe.removeFromSuperview() }
+    }
+    return regions
+}

package/gradle/libs.versions.toml

@@ -1,7 +1,5 @@
 [versions]
-# AI-GENERATED START: align Kits and its samples with the approved SDK 36 toolchain
-android-compileSdk = "36"
-# AI-GENERATED END: align Kits and its samples with the approved SDK 36 toolchain
+android-compileSdk = "37"
 android-minSdk = "24"
 android-targetSdk = "36"
 ktor-version = "3.0.0-rc-1"
@@ -11,9 +9,7 @@ kSerialize = "1.7.1"
 compose = "1.10.3"
 navigation-multiplatform = "2.9.2"
 coil3-multiplatform = "3.0.0-alpha10"
-# AI-GENERATED START: align the Android toolchain with the integrating app
 androidGradlePlugin = "9.2.1"
-# AI-GENERATED END: align the Android toolchain with the integrating app
 r8 = "8.9.35"
 kotlinx-datetime = "0.7.1"
 airbnb-lottie = "5.2.0"
@@ -21,12 +17,9 @@ compottie = "2.1.0"
 androidx-activity = "1.9.1"
 androidx-appcompat = "1.7.0"
 material = "1.10.0"
-maxapi = "0.1.1"
 vanniktechMavenPublish = "0.34.0"
-# AI-GENERATED START: identify the SDK 36 compatible Kits release
-kits = "0.300.3"
-# AI-GENERATED END: identify the SDK 36 compatible Kits release
-nativemaxapi = "0.3.1"
+kits = "0.167.1-duo.1"
+nativemaxapi = "0.3.9"
 gif-image = "0.1.2"
 
 [libraries]
@@ -46,14 +39,12 @@ coil-multiplatform-compose = { module = "io.coil-kt.coil3:coil-compose", version
 coil-multiplatform-network-ktor = { module = "io.coil-kt.coil3:coil-network-ktor3", version.ref = "coil3-multiplatform" }
 r8 = { module = "com.android.tools:r8", version.ref = "r8" }
 airbnb-lottie = { group = "com.airbnb.android", name = "lottie-compose", version.ref = "airbnb-lottie" }
-# AI-GENERATED START
 # Depend on compottie-core (not the `compottie` umbrella). The umbrella drags in the
 # separate `keight` umbrella artifact, which collides with `keight-core` on the
 # `findRoot__at__ScriptRuntime` symbol (duplicate symbol at the iOS `ld` link of
 # shared.framework). compottie-core pulls only `keight-core` (which declares
 # keight.js.JsAny, so the earlier unlinked-symbol error stays fixed too).
 compottie = { module = "io.github.alexzhirkevich:compottie-core", version.ref = "compottie" }
-# AI-GENERATED END
 native-max-api = { group = "vn.momo.maxapi", name = "NativeMaxApi", version.ref = "nativemaxapi" }
 kits = { module = "vn.momo.kits:kits", version.ref = "kits" }
 androidx-appcompat = { module = "androidx.appcompat:appcompat", version.ref = "androidx-appcompat" }
@@ -74,6 +65,4 @@ android-library = { id = "com.android.library", version.ref = "androidGradlePlug
 android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }
 vanniktech-mavenPublish = { id = "com.vanniktech.maven.publish", version.ref = "vanniktechMavenPublish" }
 
-# AI-GENERATED START: use the AGP Android target for Kotlin Multiplatform libraries
 android-kotlin-multiplatform-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "androidGradlePlugin" }
-# AI-GENERATED END: use the AGP Android target for Kotlin Multiplatform libraries

package/gradle/wrapper/gradle-wrapper.properties

@@ -1,9 +1,7 @@
 #Thu Jul 31 17:05:40 ICT 2025
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-# AI-GENERATED START: align the Gradle wrapper with the integrating app
 distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.0-bin.zip
-# AI-GENERATED END: align the Gradle wrapper with the integrating app
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

package/gradle.properties

@@ -18,11 +18,9 @@ kotlin.apple.xcodeCompatibility.nowarn=true
 name="ComposeKits"
 group=vn.momo.kits
 artifact.id=kits
-# AI-GENERATED START: publish the SDK 36 compatible Kits under a new version
-version=0.300.3
-# AI-GENERATED END: publish the SDK 36 compatible Kits under a new version
+version=0.300.4
 
 repo=GitLab
 url=https://gitlab.mservice.com.vn/api/v4/projects/5400/packages/maven
-gitlab.user=upload_packages
-gitlab.password=gldt-CtTSGmzz57sUL9cnjdaQ
+gitlab.user=
+gitlab.password=

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)
+    }
 }