@momo-kits/native-kits 0.168.1-beta.2-debug → 0.168.1-beta.3-debug

package/CLAUDE.md

@@ -7,7 +7,7 @@ Guidance for working in this repo. Keep it accurate — update it when structure
 `momo-native-kits` — MoMo's design-system / UI-kit as a **Kotlin Multiplatform + Compose Multiplatform** library, published for Android (AAR/Maven) and iOS (static framework + CocoaPods). It is the Compose port of the React Native `momo-kits`. Consumed by mini-apps embedded in the host MoMo app.
 
 - Artifact: `vn.momo.kits:kits` (version in `gradle.properties`). NPM mirror: `@momo-kits/native-kits`.
-- Targets: `androidTarget` (JVM 17, compile/min/target SDK 36/24/36), `iosArm64`, `iosSimulatorArm64` (framework `baseName = "kits"`, `isStatic = true`).
+- Targets: AGP KMP `android` target (JVM 17, compile/min SDK 36/24; AGP 9.2.1, Gradle 9.5.0), `iosArm64`, `iosSimulatorArm64` (framework `baseName = "kits"`, `isStatic = true`).
 - Kotlin 2.3.10, Compose MP 1.10.3.
 
 ## Modules
@@ -26,11 +26,11 @@ Guidance for working in this repo. Keep it accurate — update it when structure
 
 ## Build & verify
 
-No unit-test suite is configured. Validate changes by compiling the relevant target(s); use the sample app for visual checks.
+Run `./gradlew :compose:testAndroidHostTest` for the request ownership tests in `commonTest`. Compile the relevant Android/iOS targets and use the sample app for visual checks.
 
 ```bash
 ./gradlew :compose:compileCommonMainKotlinMetadata        # validate commonMain (fast, do this first)
-./gradlew :compose:compileDebugKotlinAndroid              # Android target
+./gradlew :compose:compileAndroidMain              # Android target
 ./gradlew :compose:linkDebugFrameworkIosSimulatorArm64    # iOS framework (slow)
 ./gradlew :sample:androidApp:installDebug                 # run demo on device/emulator
 ```
@@ -50,7 +50,7 @@ Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do
 - **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.
 - **Platform code** goes through `expect`/`actual` in `platform/` — never reference Android/iOS APIs from `commonMain` directly.
-- **Native bridge:** `IMaxApi` (`vn.momo.maxapi`, exposed as `LocalMaxApi`) is the host-app bridge (dismiss, tracking, device info, language).
+- **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.
 

package/README.md

@@ -53,7 +53,7 @@ ComposeKit là bộ UI Kit đa nền tảng phục vụ Mini App/SDK của MoMo.
 ---
 
 ### Yêu cầu môi trường
-- JDK 17+, Gradle 8, Android Studio Hedgehog+ với Android SDK (compileSdk xem `libs.versions.toml`).
+- JDK 17+ và Android SDK (compileSdk xem `libs.versions.toml`); wrapper Gradle `9.5.0`, AGP `9.2.1`.
 - Kotlin Multiplatform plugin + Compose Multiplatform (JetBrains 1.6.1+).
 - Xcode 15, CocoaPods 1.12+ để build `iosApp` hoặc publish Pod.
 - Truy cập mạng nội bộ GitLab Packages nếu cần publish/consume Maven repo `https://gitlab.mservice.com.vn/api/v4/projects/5400/packages/maven`.
@@ -174,4 +174,12 @@ fun SuccessState() {
 ```
 
 - `shared/build.gradle.kts` đã bật `coreLibraryDesugaringEnabled` để tương thích `compottie-dot`/`compottie-network` với `minSdk = 24`.
-- Nếu animation dùng asset/font nội bộ, kết hợp `compottie-resources` (`rememberResourcesAssetsManager`, `rememberResourcesFontManager`) để trỏ về `composeResources`.
+- Nếu animation dùng asset/font nội bộ, kết hợp `compottie-resources` (`rememberResourcesAssetsManager`, `rememberResourcesFontManager`) để trỏ về `composeResources`.
+### NativeMaxApi 0.3.1
+
+Compose dùng typed `vn.momo.maxapi.IMaxApi` do host truyền vào `NavigationContainer`.
+Toolkit dùng overload `showToolkit(ToolkitOptions, callback)` để giữ nhóm tool tùy chỉnh,
+nhãn đa ngôn ngữ, icon, badge và `useSystemTools`. Callback trả `actionKey`; request đang chờ
+được hủy khi composition bị gỡ. Kits không đóng client do host sở hữu.
+
+Chạy `./gradlew :compose:testAndroidHostTest` để kiểm tra hủy request và callback đến muộn.

package/build.gradle.kts

@@ -2,7 +2,9 @@ plugins {
     // this is necessary to avoid the plugins to be loaded multiple times
     // in each subproject's classloader
     alias(libs.plugins.android.application) apply false
-    alias(libs.plugins.android.library) apply false
+    // AI-GENERATED START: use the AGP 9 Kotlin Multiplatform Android library target
+    alias(libs.plugins.android.kotlin.multiplatform.library) apply false
+    // AI-GENERATED END: use the AGP 9 Kotlin Multiplatform Android library target
     alias(libs.plugins.compose) apply false
     alias(libs.plugins.kotlin.compose.compiler) apply false
     alias(libs.plugins.jetbrains.kotlin.multiplatform) apply false

package/compose/build.gradle.kts

@@ -4,7 +4,9 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
     alias(libs.plugins.jetbrains.kotlin.multiplatform)
-    alias(libs.plugins.android.library)
+    // AI-GENERATED START: use the AGP 9 Kotlin Multiplatform Android library target
+    alias(libs.plugins.android.kotlin.multiplatform.library)
+    // AI-GENERATED END: use the AGP 9 Kotlin Multiplatform Android library target
     alias(libs.plugins.compose)
     alias(libs.plugins.kotlin.compose.compiler)
 //         alias(libs.plugins.vanniktech.mavenPublish)
@@ -22,12 +24,18 @@ val gitlabUser: String = findProperty("gitlab.user") as String? ?: ""
 val gitlabKey: String = findProperty("gitlab.password") as String? ?: ""
 
 kotlin {
-    androidTarget {
+    // AI-GENERATED START: configure the AGP 9 Android target and host tests
+    android {
+        namespace = "vn.momo.kits.kits"
+        compileSdk = 35
+        minSdk = 24
+        androidResources.enable = true
+        withHostTest {}
         compilerOptions {
             jvmTarget.set(JvmTarget.JVM_17)
         }
-        publishLibraryVariants("release")
     }
+    // AI-GENERATED END: configure the AGP 9 Android target and host tests
 
     val fwName = gitlabArtifactId
     val iosTargets = listOf(iosArm64(), iosSimulatorArm64())
@@ -40,7 +48,7 @@ kotlin {
     }
 
     cocoapods {
-        version = "0.168.1-beta.2-debug"
+        version = "0.168.1-beta.3-debug"
         summary = "IOS Shared module"
         homepage = "https://momo.vn"
         ios.deploymentTarget = "15.0"
@@ -86,24 +94,14 @@ kotlin {
         iosMain.dependencies {
             implementation(libs.ktor.client.darwin)
         }
+        // AI-GENERATED START: verify toolkit request ownership
+        commonTest.dependencies {
+            implementation(kotlin("test"))
+        }
+        // AI-GENERATED END: verify toolkit request ownership
     }
 }
 
-android {
-    namespace = "vn.momo.kits.kits"
-    compileSdk = 35
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
-    }
-    defaultConfig {
-        minSdk = 24
-    }
-}
-
-dependencies {
-}
-
 repositories {
     google {
         mavenContent {
@@ -153,8 +151,9 @@ compose {
 //     configure(
 //         KotlinMultiplatform(
 //             javadocJar = JavadocJar.Empty(),
+//             // AI-GENERATED START: the AGP KMP target publishes a single Android variant
 //             sourcesJar = true,
-//             androidVariantsToPublish = listOf("release")
+//             // AI-GENERATED END: the AGP KMP target publishes a single Android variant
 //         )
 //     )
 // 

package/compose/build.gradle.kts.backup

@@ -4,7 +4,9 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
     alias(libs.plugins.jetbrains.kotlin.multiplatform)
-    alias(libs.plugins.android.library)
+    // AI-GENERATED START: use the AGP 9 Kotlin Multiplatform Android library target
+    alias(libs.plugins.android.kotlin.multiplatform.library)
+    // AI-GENERATED END: use the AGP 9 Kotlin Multiplatform Android library target
     alias(libs.plugins.compose)
     alias(libs.plugins.kotlin.compose.compiler)
     alias(libs.plugins.vanniktech.mavenPublish)
@@ -22,12 +24,18 @@ val gitlabUser: String = findProperty("gitlab.user") as String? ?: ""
 val gitlabKey: String = findProperty("gitlab.password") as String? ?: ""
 
 kotlin {
-    androidTarget {
+    // AI-GENERATED START: configure the AGP 9 Android target and host tests
+    android {
+        namespace = "$gitlabGroup.$gitlabArtifactId"
+        compileSdk = libs.versions.android.compileSdk.get().toInt()
+        minSdk = libs.versions.android.minSdk.get().toInt()
+        androidResources.enable = true
+        withHostTest {}
         compilerOptions {
             jvmTarget.set(JvmTarget.JVM_17)
         }
-        publishLibraryVariants("release")
     }
+    // AI-GENERATED END: configure the AGP 9 Android target and host tests
 
     val fwName = gitlabArtifactId
     val iosTargets = listOf(iosArm64(), iosSimulatorArm64())
@@ -86,24 +94,14 @@ kotlin {
         iosMain.dependencies {
             implementation(libs.ktor.client.darwin)
         }
+        // AI-GENERATED START: verify toolkit request ownership
+        commonTest.dependencies {
+            implementation(kotlin("test"))
+        }
+        // AI-GENERATED END: verify toolkit request ownership
     }
 }
 
-android {
-    namespace = "$gitlabGroup.$gitlabArtifactId"
-    compileSdk = libs.versions.android.compileSdk.get().toInt()
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
-    }
-    defaultConfig {
-        minSdk = libs.versions.android.minSdk.get().toInt()
-    }
-}
-
-dependencies {
-}
-
 repositories {
     google {
         mavenContent {
@@ -153,8 +151,9 @@ mavenPublishing {
     configure(
         KotlinMultiplatform(
             javadocJar = JavadocJar.Empty(),
+            // AI-GENERATED START: the AGP KMP target publishes a single Android variant
             sourcesJar = true,
-            androidVariantsToPublish = listOf("release")
+            // AI-GENERATED END: the AGP KMP target publishes a single Android variant
         )
     )
 

package/compose/src/commonMain/kotlin/vn/momo/kits/application/WidgetContainer.kt

@@ -2,13 +2,18 @@ package vn.momo.kits.application
 
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider
-import androidx.compose.runtime.LaunchedEffect
+// AI-GENERATED START: own the typed language request
+import androidx.compose.runtime.DisposableEffect
+// AI-GENERATED END: own the typed language request
 import androidx.compose.runtime.remember
 import vn.momo.kits.const.AppTheme
 import vn.momo.kits.const.Theme
 import vn.momo.kits.navigation.LocalMaxApi
 import vn.momo.kits.platform.ProvideOsFontScale
+// AI-GENERATED START: consume typed NativeMaxApi results
 import vn.momo.maxapi.IMaxApi
+import vn.momo.maxapi.runtime.ApiResult
+// AI-GENERATED END: consume typed NativeMaxApi results
 
 
 @Composable
@@ -27,15 +32,25 @@ fun WidgetContainer(
     val resolvedLocalize = localize ?: LocalLocalize.current
     val resolvedMaxApi = maxApi ?: LocalMaxApi.current
 
-    LaunchedEffect(resolvedMaxApi, localize) {
-        val api = resolvedMaxApi ?: return@LaunchedEffect
-        val target = localize ?: return@LaunchedEffect
-        runCatching {
-            api.getLanguage(callback = { data ->
-                if (parseLanguage(data) == Localize.EN) target.changeLanguage(Localize.EN)
-            })
+    // AI-GENERATED START: cancel language delivery when its composition owner changes
+    DisposableEffect(resolvedMaxApi, localize) {
+        val api = resolvedMaxApi
+        val target = localize
+        var active = true
+        val handle = runCatching {
+            api?.getLanguage { result ->
+                if (active && target != null && result is ApiResult.Success &&
+                    result.value.trim().lowercase().startsWith(Localize.EN)) {
+                    target.changeLanguage(Localize.EN)
+                }
+            }
+        }.getOrNull()
+        onDispose {
+            active = false
+            handle?.cancel()
         }
     }
+    // AI-GENERATED END: cancel language delivery when its composition owner changes
 
     ProvideOsFontScale {
         CompositionLocalProvider(
@@ -48,9 +63,3 @@ fun WidgetContainer(
         }
     }
 }
-
-private fun parseLanguage(raw: Map<String, Any?>?): String? {
-    val code = (raw?.get("response") as? String)?.trim()?.lowercase()
-    if (code.isNullOrEmpty()) return null
-    return if (code.startsWith(Localize.EN)) Localize.EN else Localize.VI
-}

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

@@ -37,7 +37,10 @@ import vn.momo.kits.platform.ProvideNavigationEventDispatcherOwner
 import vn.momo.kits.platform.ProvideOsFontScale
 import vn.momo.kits.utils.getAppStatusBarHeight
 import vn.momo.kits.utils.getNavigationBarHeight
+// AI-GENERATED START: consume typed NativeMaxApi results
 import vn.momo.maxapi.IMaxApi
+import vn.momo.maxapi.runtime.ApiResult
+// AI-GENERATED END: consume typed NativeMaxApi results
 import kotlin.time.Duration.Companion.milliseconds
 
 @Composable
@@ -55,7 +58,11 @@ fun NavigationContainer(
 ) {
     val navController = rememberNavController()
     val registry = remember { DynamicScreenRegistry() }
-    val navigator = remember { Navigator(navController = navController, maxApi = maxApi, registry = registry) }
+    // AI-GENERATED START: retain the current host client after recomposition
+    val navigator = remember(navController, maxApi, registry) {
+        Navigator(navController = navController, maxApi = maxApi, registry = registry)
+    }
+    // AI-GENERATED END: retain the current host client after recomposition
     val statusBarHeight = statusBarHeight ?: getAppStatusBarHeight()
     val navigationBarHeight = getNavigationBarHeight()
     val screenLayout = calculateScreenLayout(statusBarHeight, parent = LocalScreenLayout.current)
@@ -80,16 +87,25 @@ fun NavigationContainer(
 
     val resolvedLocalize = localize ?: fallbackLocalize
 
-    LaunchedEffect(maxApi, resolvedLocalize) {
-        val api = maxApi ?: return@LaunchedEffect
-        runCatching {
-            api.getLanguage(callback = { data ->
-                if (parseLanguage(data) == Localize.EN) {
-                    resolvedLocalize.changeLanguage(Localize.EN)
+    // AI-GENERATED START: cancel language delivery when its composition owner changes
+    DisposableEffect(maxApi, resolvedLocalize) {
+        val api = maxApi
+        val target = resolvedLocalize
+        var active = true
+        val handle = runCatching {
+            api.getLanguage { result ->
+                if (active && result is ApiResult.Success &&
+                    result.value.trim().lowercase().startsWith(Localize.EN)) {
+                    target.changeLanguage(Localize.EN)
                 }
-            })
+            }
+        }.getOrNull()
+        onDispose {
+            active = false
+            handle?.cancel()
         }
     }
+    // AI-GENERATED END: cancel language delivery when its composition owner changes
 
     val screenId = rememberSaveable { registry.nextId() }
     registry.bind(screenId, initialScreenName, initialScreen, options)
@@ -197,9 +213,3 @@ fun NavigationContainer(
 
 val LocalMaxApi = staticCompositionLocalOf<IMaxApi?> { null }
 
-private fun parseLanguage(raw: Map<String, Any?>?): String? {
-    val code = (raw?.get("response") as? String)?.trim()?.lowercase()
-    if (code.isNullOrEmpty()) return null
-    return if (code.startsWith(Localize.EN)) Localize.EN else Localize.VI
-}
-

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

@@ -22,6 +22,9 @@ import vn.momo.kits.components.PopupNotify
 import vn.momo.kits.navigation.BottomHeader.*
 import vn.momo.kits.navigation.component.SnackBar
 import vn.momo.maxapi.IMaxApi
+// AI-GENERATED START: dismiss through the typed navigator target
+import vn.momo.maxapi.contract.navigation.model.DismissTarget
+// AI-GENERATED END: dismiss through the typed navigator target
 import kotlin.time.Duration.Companion.milliseconds
 
 class Navigator(
@@ -125,7 +128,9 @@ class Navigator(
             delay(STACK_TRANSITION_DURATION.milliseconds)
             dismissing?.let { registry.unregisterScreen(it.id) }
         } else {
-            maxApi?.dismiss {  }
+            // AI-GENERATED START: preserve root-screen dismissal
+            maxApi?.dismiss(DismissTarget.Current()) {}
+            // AI-GENERATED END: preserve root-screen dismissal
         }
     }
 

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

@@ -6,6 +6,9 @@ import androidx.compose.runtime.snapshotFlow
 import vn.momo.kits.platform.getScreenDimensions
 import vn.momo.kits.platform.rememberBackGestureProgress
 import vn.momo.maxapi.IMaxApi
+// AI-GENERATED START: use the typed light vibration pattern
+import vn.momo.maxapi.contract.device.vibration.model.VibrateStyle
+// AI-GENERATED END: use the typed light vibration pattern
 
 // Unscaled, so the tick lands at the same physical distance on every device.
 private const val SWIPE_BACK_HAPTIC_THRESHOLD_DP = 50f
@@ -25,7 +28,9 @@ internal fun SwipeBackHaptic(maxApi: IMaxApi?) {
         snapshotFlow { progress.value }.collect { fraction ->
             val travelled = fraction ?: 0f
             if (travelled >= threshold && !isSendHaptic) {
-                runCatching { maxApi.triggerEventVibration("light", callback = null) }
+                // AI-GENERATED START: keep one light tick per threshold crossing
+                runCatching { maxApi.vibrate(VibrateStyle.LIGHT) }
+                // AI-GENERATED END: keep one light tick per threshold crossing
                 isSendHaptic = true
             } else if (travelled < threshold && isSendHaptic) {
                 isSendHaptic = false

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

@@ -39,6 +39,9 @@ import vn.momo.kits.platform.BackHandler
 import vn.momo.kits.platform.reportFloatingArrowBack
 import vn.momo.kits.layout.getScreenLayout
 import kotlinx.coroutines.launch
+// AI-GENERATED START: use the typed tab haptic pattern
+import vn.momo.maxapi.contract.device.vibration.model.VibrateStyle
+// AI-GENERATED END: use the typed tab haptic pattern
 
 private val inOutQuad = Easing { t -> if (t < 0.5f) 2 * t * t else 1 - 2 * (1 - t) * (1 - t) }
 internal val tabTimingSpec = tween<Float>(durationMillis = 200, easing = inOutQuad)
@@ -132,7 +135,9 @@ fun BottomTab(
         it.bottom + duoRailHeight(items.size, hasQr, compressed = compression.tabBarCompressed) + DUO_GROUP_GAP
     } ?: 0.dp
     val onTabSelected: (Int) -> Unit = { index ->
-        runCatching { maxApi?.triggerEventVibration("light", callback = null) }
+        // AI-GENERATED START: preserve the light haptic on tab selection
+        runCatching { maxApi?.vibrate(VibrateStyle.LIGHT) }
+        // AI-GENERATED END: preserve the light haptic on tab selection
         val switchTab = {
             if (index != selectedIndex) selectTab(index)
         }

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

@@ -17,6 +17,17 @@ import androidx.compose.foundation.shape.CircleShape
 import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
+// AI-GENERATED START: dispose toolkit requests with their UI owner
+import androidx.compose.runtime.DisposableEffect
+import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.jsonPrimitive
+import vn.momo.maxapi.contract.navigation.model.DismissTarget
+import vn.momo.maxapi.contract.toolkit.model.ToolAction
+import vn.momo.maxapi.contract.toolkit.model.ToolkitOptions
+import vn.momo.maxapi.contract.toolkit.model.ToolkitToolGroup
+import vn.momo.maxapi.contract.toolkit.model.ToolkitTool
+import vn.momo.maxapi.runtime.ApiResult
+// AI-GENERATED END: dispose toolkit requests with their UI owner
 import androidx.compose.runtime.derivedStateOf
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
@@ -95,53 +106,56 @@ internal fun Toolkit(
     var isFavorite by remember { mutableStateOf(false) }
     val isLoading by remember { mutableStateOf(false) }
 
-    LaunchedEffect(context?.appCode) {
-        api?.isFavoriteApp(mapOf("code" to context?.appCode)) { callback ->
-            val response = callback?.get("response") as? Boolean
-            isFavorite = response == true
+    // AI-GENERATED START: retain custom tool data and typed callback outcomes
+    val requests = remember(api, context?.appCode) { ToolkitRequests() }
+    DisposableEffect(requests) { onDispose { requests.close() } }
+
+    LaunchedEffect(requests) {
+        val client = api ?: return@LaunchedEffect
+        requests.launch<Boolean>({ callback -> client.checkFavorite(context?.appCode, callback) }) { result ->
+            if (result is ApiResult.Success) isFavorite = result.value
         }
     }
 
     fun onPressShortcut() {
-        api?.onToolAction(mapOf("item" to mapOf("key" to "onFavorite"), "context" to MiniAppContext.toMap(context))) { callback ->
-            val response = callback?.get("response") as? Map<*, *>?
-            val success = response?.get("success") as? Boolean
-            if (success == true){
-                isFavorite = !isFavorite
+        val client = api ?: return
+        requests.launch({ callback ->
+            client.performToolAction(ToolAction.FAVORITE, context?.appCode, callback)
+        }) { result ->
+            if (result is ApiResult.Success) {
+                result.value.jsonPrimitive.booleanOrNull?.let { isFavorite = it }
             }
         }
     }
 
     fun onPressMore() {
-        api?.showTools(
-            mapOf(
-                "useSystemTools" to headerRight.useSystemTools,
-                "tools" to headerRight.tools.map { it.toMap() },
-                "context" to MiniAppContext.toMap(context)
-            )
-        ) { callback ->
-            val response = callback?.get("response") as? String
-            if (response != null) {
-                headerRight.toolCallback?.invoke(response)
-            }
+        val client = api ?: return
+        val options = ToolkitOptions(
+            customToolGroups = headerRight.tools.map { group ->
+                ToolkitToolGroup(group.title, group.items.map { tool ->
+                    ToolkitTool(tool.key, tool.icon, tool.showBadge, tool.name, tool.showRightIcon)
+                })
+            },
+            useSystemTools = headerRight.useSystemTools,
+        )
+        requests.launch({ callback -> client.showToolkit(options, callback) }) { result ->
+            if (result is ApiResult.Success) headerRight.toolCallback?.invoke(result.value.actionKey)
         }
     }
+    // AI-GENERATED END: retain custom tool data and typed callback outcomes
 
     fun onPressHelpCenter() {
         if (context == null) return
-        api?.showHelpCenter(
-            mapOf(
-                "appId" to context.appId,
-                "code" to context.appCode,
-                "name" to context.appName,
-                "icon" to context.appIcon,
-                "description" to context.description
-            )
-        ) {}
+        // AI-GENERATED START: preserve Help Center context and own its event subscription
+        val client = api ?: return
+        requests.observe({ callback -> client.showBottomSheet(context.helpCenterRequest(), callback) }) {}
+        // AI-GENERATED END: preserve Help Center context and own its event subscription
     }
 
     fun onPressClose() {
-        if (headerRight.useCloseIcon) api?.dismiss { } else api?.dismissAll { }
+        // AI-GENERATED START: preserve current-container and whole-stack dismissal
+        api?.dismiss(if (headerRight.useCloseIcon) DismissTarget.Current() else DismissTarget.All) {}
+        // AI-GENERATED END: preserve current-container and whole-stack dismissal
     }
 
     val useHelpCenter = usesHelpCenter(context)

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

@@ -0,0 +1,37 @@
+// File: HelpCenterRequest.kt
+// Created At: 2026-10-19 +07:00
+// Created By: AI | AI Agent: Codex | Model: GPT-6
+// AI-GENERATED START: preserve the toolkit Help Center payload in the typed request
+package vn.momo.kits.navigation.component
+
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import vn.momo.kits.application.MiniAppContext
+import vn.momo.maxapi.contract.navigation.model.BottomSheetRequest
+import vn.momo.maxapi.contract.navigation.model.HelpCenterContext
+
+internal fun MiniAppContext.helpCenterRequest() = BottomSheetRequest.HelpCenter(
+    HelpCenterContext(
+        appId = appId,
+        code = appCode,
+        name = appName?.helpCenterJson(),
+        icon = appIcon,
+        description = description?.helpCenterJson(),
+    ),
+)
+
+private fun Any?.helpCenterJson(): JsonElement = when (this) {
+    null -> JsonNull
+    is JsonElement -> this
+    is String -> JsonPrimitive(this)
+    is Boolean -> JsonPrimitive(this)
+    is Number -> JsonPrimitive(this)
+    is Map<*, *> -> JsonObject(entries.associate { (key, value) -> key.toString() to value.helpCenterJson() })
+    is Iterable<*> -> JsonArray(map { it.helpCenterJson() })
+    is Array<*> -> JsonArray(map { it.helpCenterJson() })
+    else -> JsonPrimitive(toString())
+}
+// AI-GENERATED END: preserve the toolkit Help Center payload in the typed request

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

@@ -0,0 +1,41 @@
+// File: ToolkitRequests.kt
+// Created At: 2026-10-12 +07:00 | Created By: AI | AI Agent: Codex | Model: GPT-6
+// AI-GENERATED START: cancel only toolkit requests owned by this composition
+package vn.momo.kits.navigation.component
+
+import vn.momo.maxapi.runtime.ApiCallback
+import vn.momo.maxapi.runtime.ApiRequestHandle
+
+internal class ToolkitRequests {
+    private var active = true
+    private val handles = mutableSetOf<ApiRequestHandle>()
+
+    fun <T> launch(request: (ApiCallback<T>) -> ApiRequestHandle, onResult: ApiCallback<T>) {
+        if (!active) return
+        var completed = false
+        var handle: ApiRequestHandle? = null
+        val created = request { result ->
+            completed = true
+            handle?.let(handles::remove)
+            if (active) onResult(result)
+        }
+        handle = created
+        if (!active) created.cancel() else if (!completed) handles.add(created)
+    }
+
+    // AI-GENERATED START: retain subscriptions across nonterminal sheet events
+    fun <T> observe(request: (ApiCallback<T>) -> ApiRequestHandle, onResult: ApiCallback<T>) {
+        if (!active) return
+        val handle = request { result -> if (active) onResult(result) }
+        if (active) handles.add(handle) else handle.cancel()
+    }
+    // AI-GENERATED END: retain subscriptions across nonterminal sheet events
+
+    fun close() {
+        active = false
+        val pending = handles.toList()
+        handles.clear()
+        pending.forEach { it.cancel() }
+    }
+}
+// AI-GENERATED END: cancel only toolkit requests owned by this composition

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

@@ -2,6 +2,12 @@ package vn.momo.kits.navigation.tracking
 
 import vn.momo.kits.application.MiniAppContext
 import vn.momo.maxapi.IMaxApi
+// AI-GENERATED START: serialize tracking attributes with their existing value types
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+// AI-GENERATED END: serialize tracking attributes with their existing value types
 import kotlin.time.Clock
 import kotlin.time.ExperimentalTime
 
@@ -15,6 +21,7 @@ class ScreenTrackingState {
     var action: String = "push"
 }
 
+// AI-GENERATED START: retain screen event names and typed tracking attributes
 object ScreenTracker {
 
     private var lastScreenName: String? = null
@@ -31,13 +38,13 @@ object ScreenTracker {
         val previousScreen = lastScreenName
         lastScreenName = screenName
 
-        maxApi?.track(
+        maxApi?.trackEvent(
             eventName = "auto_screen_navigated",
-            params = buildBaseParams(context, screenName).apply {
-                put("pre_screen_name", previousScreen)
-                put("state", "navigated")
-                put("action", action)
-            }
+            attributes = JsonObject(buildBaseParams(context, screenName).apply {
+                put("pre_screen_name", JsonPrimitive(previousScreen))
+                put("state", JsonPrimitive("navigated"))
+                put("action", JsonPrimitive(action))
+            })
         )
 
         state.releaseNavigated = true
@@ -53,12 +60,12 @@ object ScreenTracker {
     ) {
         if (state.releaseLoad) return
 
-        maxApi?.track(
+        maxApi?.trackEvent(
             eventName = "auto_screen_displayed",
-            params = buildBaseParams(context, screenName).apply {
-                put("state", "load")
-                put("duration", duration)
-            }
+            attributes = JsonObject(buildBaseParams(context, screenName).apply {
+                put("state", JsonPrimitive("load"))
+                put("duration", JsonPrimitive(duration))
+            })
         )
 
         state.releaseLoad = true
@@ -74,13 +81,13 @@ object ScreenTracker {
     ) {
         if (state.releaseInteraction) return
 
-        maxApi?.track(
+        maxApi?.trackEvent(
             eventName = "auto_screen_interacted",
-            params = buildBaseParams(context, screenName).apply {
-                put("state", "interaction")
-                put("duration", duration)
-                put("total_duration", totalDuration)
-            }
+            attributes = JsonObject(buildBaseParams(context, screenName).apply {
+                put("state", JsonPrimitive("interaction"))
+                put("duration", JsonPrimitive(duration))
+                put("total_duration", JsonPrimitive(totalDuration))
+            })
         )
 
         state.releaseInteraction = true
@@ -90,13 +97,13 @@ object ScreenTracker {
         context: MiniAppContext?,
         screenName: String,
         componentName: String = "Screen"
-    ): MutableMap<String, Any?> {
+    ): MutableMap<String, JsonElement> {
         return mutableMapOf(
-            "app_id" to context?.appId,
-            "feature_code" to context?.appCode,
-            "screen_name" to screenName,
-            "component_name" to componentName,
-            "tracking_source" to 1
+            "app_id" to JsonPrimitive(context?.appId),
+            "feature_code" to JsonPrimitive(context?.appCode),
+            "screen_name" to JsonPrimitive(screenName),
+            "component_name" to JsonPrimitive(componentName),
+            "tracking_source" to JsonPrimitive(1)
         )
     }
 
@@ -105,16 +112,16 @@ object ScreenTracker {
         context: MiniAppContext?,
         parentScreenName: String?
     ) {
-        maxApi?.track(
+        maxApi?.trackEvent(
             eventName = "auto_popup_displayed",
-            params = mutableMapOf<String, Any?>(
-                "screen_name" to parentScreenName,
-                "tracking_source" to 1,
-                "app_id" to context?.appId,
-                "feature_code" to context?.appCode,
-                "kits_version" to null,
-                "component_name" to "Modal"
-            )
+            attributes = JsonObject(mapOf(
+                "screen_name" to JsonPrimitive(parentScreenName),
+                "tracking_source" to JsonPrimitive(1),
+                "app_id" to JsonPrimitive(context?.appId),
+                "feature_code" to JsonPrimitive(context?.appCode),
+                "kits_version" to JsonNull,
+                "component_name" to JsonPrimitive("Modal")
+            ))
         )
     }
 
@@ -125,3 +132,4 @@ object ScreenTracker {
         lastScreenName = null
     }
 }
+// AI-GENERATED END: retain screen event names and typed tracking attributes

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

@@ -0,0 +1,62 @@
+// File: ToolkitRequestsTest.kt
+// Created At: 2026-10-12 +07:00 | Created By: AI | AI Agent: Codex | Model: GPT-6
+// AI-GENERATED START: verify cancellation and late callback suppression for toolkit UI
+package vn.momo.kits.navigation.component
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import vn.momo.maxapi.runtime.ApiCallback
+import vn.momo.maxapi.runtime.ApiRequestHandle
+import vn.momo.maxapi.runtime.ApiResult
+
+class ToolkitRequestsTest {
+    @Test
+    fun closingCancelsPendingRequestsAndSuppressesLateCallbacks() {
+        val owner = ToolkitRequests()
+        val handle = Handle()
+        var callback: ApiCallback<Boolean> = {}
+        var results = 0
+        owner.launch<Boolean>({ callback = it; handle }) { results++ }
+        owner.close()
+        owner.close()
+        callback(ApiResult.Success(true))
+        assertEquals(1, handle.cancellations)
+        assertEquals(0, results)
+    }
+
+    @Test
+    fun completedRequestsAreReleasedAndClosedOwnersNeverStartNewRequests() {
+        val owner = ToolkitRequests()
+        val handle = Handle()
+        var starts = 0
+        var results = 0
+        owner.launch<Boolean>({ callback -> starts++; callback(ApiResult.Success(false)); handle }) { results++ }
+        owner.close()
+        owner.launch<Boolean>({ starts++; handle }) { results++ }
+        assertEquals(0, handle.cancellations)
+        assertEquals(1, starts)
+        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
+        override fun cancel() { cancellations++ }
+    }
+}
+// AI-GENERATED END: verify cancellation and late callback suppression for toolkit UI

package/compose/src/iosMain/kotlin/vn/momo/kits/navigation/ScrollToTop.ios.kt

@@ -12,7 +12,9 @@ private const val STATUS_BAR_TAPPED_NOTIFICATION = "statusBarSelected"
 @Composable
 internal actual fun RegisterScrollToTop(callback: (() -> Unit)?) {
     val maxApi = LocalMaxApi.current
-    DisposableEffect(callback) {
+    // AI-GENERATED START: capture the current typed logger client
+    DisposableEffect(callback, maxApi) {
+    // AI-GENERATED END: capture the current typed logger client
         val token: NSObjectProtocol? = if (callback != null) {
             NSNotificationCenter.defaultCenter.addObserverForName(
                 name = STATUS_BAR_TAPPED_NOTIFICATION,
@@ -20,7 +22,9 @@ internal actual fun RegisterScrollToTop(callback: (() -> Unit)?) {
                 queue = NSOperationQueue.mainQueue,
             ) { _: NSNotification? ->
                 runCatching { callback() }.onFailure {
-                    maxApi?.logFile("[ScrollToTop] callback threw: ${it.message}") {}
+                    // AI-GENERATED START: use typed host logging
+                    maxApi?.writeLog("[ScrollToTop] callback threw: ${it.message}")
+                    // AI-GENERATED END: use typed host logging
 
                 }
             }

package/gradle/libs.versions.toml

@@ -1,5 +1,7 @@
 [versions]
-android-compileSdk = "37"
+# 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-minSdk = "24"
 android-targetSdk = "36"
 ktor-version = "3.0.0-rc-1"
@@ -9,7 +11,9 @@ kSerialize = "1.7.1"
 compose = "1.10.3"
 navigation-multiplatform = "2.9.2"
 coil3-multiplatform = "3.0.0-alpha10"
-androidGradlePlugin = "8.13.2"
+# 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"
@@ -17,10 +21,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"
 kits = "0.167.1-duo.1"
-nativemaxapi = "0.0.6"
+nativemaxapi = "0.3.9"
 gif-image = "0.1.2"
 
 [libraries]
@@ -67,3 +70,7 @@ compose = { id = "org.jetbrains.compose", version.ref = "compose" }
 android-library = { id = "com.android.library", version.ref = "androidGradlePlugin" }
 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,7 +1,9 @@
 #Thu Jul 31 17:05:40 ICT 2025
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.1-bin.zip
+# 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,7 +18,7 @@ kotlin.apple.xcodeCompatibility.nowarn=true
 name="ComposeKits"
 group=vn.momo.kits
 artifact.id=kits
-version=0.167.1-duo.15
+version=0.300.4
 
 repo=GitLab
 url=https://gitlab.mservice.com.vn/api/v4/projects/5400/packages/maven

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@momo-kits/native-kits",
-  "version": "0.168.1-beta.2-debug",
+  "version": "0.168.1-beta.3-debug",
   "private": false,
   "dependeNavigationncies": {},
   "devDependencies": {},

package/publish.sh

@@ -374,8 +374,13 @@ phase_publish_npm() {
     echo ""
     # A bad token surfaces as a 404 on the PUT, after the working tree was already rewritten
     # below — so verify auth first, before anything is touched.
-    if ! npm whoami --registry https://registry.npmjs.org >/dev/null 2>&1; then
-        echo "❌ Error: npm auth failed (npm whoami). Renew the token in .npmrc / ~/.npmrc and retry."
+    if ! NPM_WHOAMI_OUTPUT=$(npm whoami --registry https://registry.npmjs.org 2>&1); then
+        echo "$NPM_WHOAMI_OUTPUT"
+        if echo "$NPM_WHOAMI_OUTPUT" | grep -qE "E401|ENEEDAUTH"; then
+            echo "❌ Error: npm auth failed (npm whoami). Renew the token in .npmrc / ~/.npmrc and retry."
+        else
+            echo "❌ Error: npm whoami failed (see above) — likely network / VPN to registry.npmjs.org. Retry in a moment."
+        fi
         exit 1
     fi
 

package/.claude/settings.local.json

@@ -1,9 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Read(//Users/trinh.ho2/**)",
-      "Bash(npm config *)",
-      "Bash(npm whoami *)"
-    ]
-  }
-}