@momo-kits/native-kits 0.162.34-debug → 0.162.35-debug

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

@@ -0,0 +1,106 @@
+package vn.momo.kits.navigation.component
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import vn.momo.kits.components.Icon
+import vn.momo.kits.components.Skeleton
+import vn.momo.kits.components.Text
+import vn.momo.kits.const.Spacing
+import vn.momo.kits.const.Typography
+import vn.momo.kits.modifier.activeOpacityClickable
+import vn.momo.kits.platform.getScreenDimensions
+
+@Composable
+internal fun HeaderJourney(
+    data: HeaderTitle,
+    tintIconColor: Color,
+) {
+    if (data !is HeaderTitle.Journey) return
+    if (data.isLoading) return TitleJourneyShimmer()
+
+    val maxWidth = getScreenDimensions().width.dp - 172.dp
+    val tint = parseHeaderTint(data.tintColor) ?: tintIconColor
+    val iconTint = parseHeaderTint(data.iconColor) ?: tint
+
+    Column(
+        modifier = Modifier
+            .widthIn(max = maxWidth)
+            .activeOpacityClickable(enabled = data.onPress != null, onClick = { data.onPress?.invoke() }),
+        verticalArrangement = Arrangement.Center,
+    ) {
+        Row(verticalAlignment = Alignment.CenterVertically) {
+            Text(
+                text = data.start,
+                color = tint,
+                style = Typography.actionXsBold,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+                modifier = Modifier.weight(1f, fill = false),
+            )
+            Spacer(Modifier.width(Spacing.S))
+            if (data.icon.isNotBlank()) {
+                Icon(source = data.icon, size = 16.dp, color = iconTint)
+            } else {
+                Spacer(Modifier.width(16.dp))
+            }
+            Spacer(Modifier.width(Spacing.S))
+            if (!data.end.isNullOrEmpty()) {
+                Text(
+                    text = data.end,
+                    color = tint,
+                    style = Typography.actionXsBold,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    modifier = Modifier.weight(1f, fill = false),
+                )
+            }
+            Spacer(Modifier.width(Spacing.XS))
+            Icon(source = "16_arrow_chevron_down_small", size = 16.dp, color = tint)
+        }
+        if (!data.description.isNullOrEmpty()) {
+            Text(
+                text = data.description,
+                color = tint,
+                style = Typography.descriptionXsRegular,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+            )
+        }
+    }
+}
+
+@Composable
+private fun TitleJourneyShimmer() {
+    Column(modifier = Modifier.fillMaxWidth()) {
+        Box(modifier = Modifier.height(18.dp).width(120.dp).clip(RoundedCornerShape(8.dp))) { Skeleton() }
+        Spacer(Modifier.height(Spacing.XXS))
+        Box(modifier = Modifier.height(12.dp).width(120.dp).clip(RoundedCornerShape(8.dp))) { Skeleton() }
+    }
+}
+
+internal fun parseHeaderTint(value: String?): Color? {
+    val raw = value?.trim()?.removePrefix("#") ?: return null
+    val hex = when (raw.length) {
+        3 -> "FF" + raw.map { "$it$it" }.joinToString("")
+        6 -> "FF$raw"
+        8 -> raw
+        else -> return null
+    }
+    val v = hex.toLongOrNull(16) ?: return null
+    return Color(v)
+}

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

@@ -0,0 +1,75 @@
+package vn.momo.kits.navigation.component
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import vn.momo.kits.components.Icon
+import vn.momo.kits.components.Skeleton
+import vn.momo.kits.components.Text
+import vn.momo.kits.const.Spacing
+import vn.momo.kits.const.Typography
+import vn.momo.kits.modifier.activeOpacityClickable
+import vn.momo.kits.platform.getScreenDimensions
+
+@Composable
+internal fun HeaderLocation(
+    data: HeaderTitle,
+    tintIconColor: Color,
+) {
+    if (data !is HeaderTitle.Location) return
+    if (data.isLoading) return TitleLocationShimmer()
+
+    val maxWidth = getScreenDimensions().width.dp - 172.dp
+    val tint = parseHeaderTint(data.tintColor) ?: tintIconColor
+
+    Column(
+        modifier = Modifier
+            .widthIn(max = maxWidth)
+            .activeOpacityClickable(enabled = data.onPress != null, onClick = { data.onPress?.invoke() }),
+        horizontalAlignment = Alignment.Start,
+    ) {
+        if (!data.description.isNullOrEmpty()) {
+            Text(
+                text = data.description,
+                color = tint,
+                style = Typography.descriptionXsRegular,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+            )
+        }
+        Row(verticalAlignment = Alignment.CenterVertically) {
+            Text(
+                text = data.location,
+                color = tint,
+                style = Typography.actionXsBold,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+                modifier = Modifier.weight(1f, fill = false),
+            )
+            Spacer(Modifier.width(Spacing.XS))
+            Icon(source = "16_arrow_chevron_down_small", size = 16.dp, color = tint)
+        }
+    }
+}
+
+@Composable
+private fun TitleLocationShimmer() {
+    Column(modifier = Modifier.fillMaxWidth()) {
+        Box(modifier = Modifier.height(12.dp).width(120.dp).clip(RoundedCornerShape(8.dp))) { Skeleton() }
+        Spacer(Modifier.height(Spacing.XXS))
+        Box(modifier = Modifier.height(18.dp).width(120.dp).clip(RoundedCornerShape(8.dp))) { Skeleton() }
+    }
+}

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

@@ -12,6 +12,8 @@ import vn.momo.kits.components.Text
 import vn.momo.kits.const.Typography
 import vn.momo.kits.modifier.setAutomationId
 
+internal const val HEADER_FONT_FAMILY = "MoMoTrustDisplay"
+
 @Composable
 internal fun HeaderTitle(
     title: String = "",
@@ -27,6 +29,7 @@ internal fun HeaderTitle(
             fontSize = 15.sp,
             lineHeight = 22.sp,
         ),
+        fontFamily = HEADER_FONT_FAMILY,
         color = color,
         maxLines = 1,
         overflow = TextOverflow.Ellipsis

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

@@ -16,6 +16,7 @@ import androidx.compose.ui.draw.clip
 import androidx.compose.ui.draw.clipToBounds
 import androidx.compose.ui.layout.ContentScale
 import androidx.compose.ui.text.TextStyle
+import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.Dp
 import androidx.compose.ui.unit.dp
@@ -28,6 +29,7 @@ import vn.momo.kits.const.AppTheme
 import vn.momo.kits.const.Colors
 import vn.momo.kits.const.Spacing
 import vn.momo.kits.const.Typography
+import vn.momo.kits.const.getFontFamily
 import vn.momo.kits.modifier.activeOpacityClickable
 import vn.momo.kits.navigation.component.HeaderTitle.User
 import vn.momo.kits.platform.getScreenDimensions
@@ -77,6 +79,7 @@ internal fun HeaderUser(
                         text = data.title,
                         color = data.tintColor,
                         style = Typography.actionXsBold,
+                        fontFamily = HEADER_FONT_FAMILY,
                         maxLines = 1,
                         overflow = TextOverflow.Ellipsis
                     )
@@ -303,7 +306,8 @@ private fun ManyAvatar(options: Options, modifier: Modifier = Modifier, urls: Av
             BasicText(
                 text = "+$more",
                 style = TextStyle(
-                    color = Colors.pink_03
+                    color = Colors.pink_03,
+                    fontFamily = getFontFamily(AppTheme.current.font, FontWeight.Normal)
                 ),
                 maxLines = 1,
                 autoSize = TextAutoSize.StepBased(

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

@@ -0,0 +1,12 @@
+package vn.momo.kits.platform
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.State
+
+/** Fraction of container width, `null` when idle. Observe only — consuming would steal the
+ *  gesture from NavHost. Always `null` on Android. */
+@Composable
+expect fun rememberBackGestureProgress(): State<Float?>
+
+/** Android is a no-op: no host-owned recogniser to hand the gesture to. */
+expect fun reportFloatingArrowBack(shouldUse: Boolean)

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

@@ -5,6 +5,7 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.NativePaint
 import androidx.compose.ui.unit.Dp
+import vn.momo.kits.navigation.Navigator
 
 data class ScreenDimension(
     val width: Int,
@@ -24,8 +25,9 @@ expect fun getStatusBarHeight(): Dp
 @Composable
 expect fun BackHandler(enabled: Boolean, onBack: () -> Unit)
 
+@Suppress("ParamsComparedByRef")
 @Composable
-expect fun ProvideNavigationEventDispatcherOwner(content: @Composable () -> Unit)
+expect fun ProvideNavigationEventDispatcherOwner(navigator: Navigator, content: @Composable () -> Unit)
 
 @Composable
 expect fun getScreenHeight(): Dp

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

@@ -0,0 +1,45 @@
+package vn.momo.kits.navigation
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.remember
+import androidx.navigationevent.NavigationEvent
+import androidx.navigationevent.NavigationEventDispatcher
+import androidx.navigationevent.NavigationEventInput
+
+@Suppress("ParamsComparedByRef")
+@Composable
+internal fun AttachHostBackGesture(dispatcher: NavigationEventDispatcher, navigator: Navigator) {
+    val input = remember(dispatcher) { HostNavigationEventInput() }
+    val target = remember(input, navigator) {
+        object : HostBackTarget {
+            override fun canPop() = navigator.canPop()
+            override fun onBack() = navigator.onBackSafe()
+            override fun backStarted() = input.backStarted()
+            override fun backProgressed(progress: Float) = input.backProgressed(progress)
+            override fun backCompleted() = input.backCompleted()
+            override fun backCancelled() = input.backCancelled()
+        }
+    }
+
+    DisposableEffect(dispatcher, target) {
+        dispatcher.addInput(input)
+        HostBackGestureBridge.attach(target)
+        onDispose {
+            HostBackGestureBridge.detach(target)
+            dispatcher.removeInput(input)
+        }
+    }
+}
+
+internal class HostNavigationEventInput : NavigationEventInput() {
+    fun backStarted() = dispatchOnBackStarted(NavigationEvent(swipeEdge = NavigationEvent.EDGE_LEFT))
+
+    fun backProgressed(progress: Float) = dispatchOnBackProgressed(
+        NavigationEvent(swipeEdge = NavigationEvent.EDGE_LEFT, progress = progress)
+    )
+
+    fun backCancelled() = dispatchOnBackCancelled()
+
+    fun backCompleted() = dispatchOnBackCompleted()
+}

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

@@ -0,0 +1,38 @@
+package vn.momo.kits.platform
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.State
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.ui.InternalComposeUiApi
+import androidx.compose.ui.backhandler.LocalCompatNavigationEventDispatcherOwner
+import androidx.navigationevent.NavigationEventTransitionState
+import vn.momo.kits.navigation.HostBackGestureBridge
+
+// transitionState is a passive observer; its progress is touch.x / view width.
+@OptIn(InternalComposeUiApi::class)
+@Composable
+actual fun rememberBackGestureProgress(): State<Float?> {
+    val dispatcher = LocalCompatNavigationEventDispatcherOwner.current?.navigationEventDispatcher
+    val progress = remember { mutableStateOf<Float?>(null) }
+
+    LaunchedEffect(dispatcher) {
+        if (dispatcher == null) {
+            progress.value = null
+            return@LaunchedEffect
+        }
+        dispatcher.transitionState.collect { state ->
+            progress.value = (state as? NavigationEventTransitionState.InProgress)
+                ?.takeIf { it.direction == NavigationEventTransitionState.TRANSITIONING_BACK }
+                ?.latestEvent
+                ?.progress
+        }
+    }
+
+    return progress
+}
+
+actual fun reportFloatingArrowBack(shouldUse: Boolean) {
+    HostBackGestureBridge.shouldUseFloatingArrowBack = shouldUse
+}

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

@@ -17,6 +17,7 @@ import androidx.compose.ui.ExperimentalComposeUiApi
 import androidx.compose.ui.InternalComposeUiApi
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.backhandler.LocalCompatNavigationEventDispatcherOwner
+import androidx.compose.ui.backhandler.BackHandler as ComposeBackHandler
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.NativePaint
 import androidx.compose.ui.graphics.toArgb
@@ -38,6 +39,8 @@ import platform.Foundation.NSBundle
 import platform.UIKit.UIColor
 import platform.UIKit.UIDevice
 import platform.UIKit.UIScreen
+import vn.momo.kits.navigation.AttachHostBackGesture
+import vn.momo.kits.navigation.Navigator
 
 actual fun getPlatformName(): String = "iOS"
 
@@ -60,21 +63,24 @@ actual fun getStatusBarHeight(): Dp {
     return WindowInsets.systemBars.asPaddingValues().calculateTopPadding()
 }
 
+@Suppress("DEPRECATION")
+@OptIn(ExperimentalComposeUiApi::class)
 @Composable
 actual fun BackHandler(enabled: Boolean, onBack: () -> Unit) {
+    ComposeBackHandler(enabled = enabled, onBack = onBack)
 }
 
 @OptIn(InternalComposeUiApi::class)
 @Composable
-actual fun ProvideNavigationEventDispatcherOwner(content: @Composable () -> Unit) {
+actual fun ProvideNavigationEventDispatcherOwner(navigator: Navigator, content: @Composable () -> Unit) {
     val navigationEventDispatcherOwner = remember {
         object : NavigationEventDispatcherOwner {
-            override val navigationEventDispatcher = NavigationEventDispatcher().apply {
-                isEnabled = false
-            }
+            override val navigationEventDispatcher = NavigationEventDispatcher()
         }
     }
 
+    AttachHostBackGesture(navigationEventDispatcherOwner.navigationEventDispatcher, navigator)
+
     CompositionLocalProvider(
         LocalCompatNavigationEventDispatcherOwner provides navigationEventDispatcherOwner,
         content = content

package/gradle/libs.versions.toml

@@ -1,5 +1,5 @@
 [versions]
-android-compileSdk = "36"
+android-compileSdk = "37"
 android-minSdk = "24"
 android-targetSdk = "36"
 ktor-version = "3.0.0-rc-1"

package/gradle.properties

@@ -18,7 +18,7 @@ kotlin.apple.xcodeCompatibility.nowarn=true
 name="ComposeKits"
 group=vn.momo.kits
 artifact.id=kits
-version=0.162.34
+version=0.162.35
 
 repo=GitLab
 url=https://gitlab.mservice.com.vn/api/v4/projects/5400/packages/maven

package/ios/Application/Navigation/NavigatorManager.swift

@@ -1,19 +1,3 @@
-//
-//  NavigatorManager.swift
-//  MoMoUIKits
-//
-//  Host bridge for the native iOS edge-swipe back — the SwiftUI mirror of Compose's
-//  `ComposeNavigatorManager` (momo-app `vn.momo.compose.uikits.ComposeNavigatorManager`).
-//
-//  The kit does NOT own the swipe gesture. In the host app a kit screen lives inside a
-//  `UIHostingController` hosted by the mini-app container VC, and that VC owns the
-//  `UIScreenEdgePanGestureRecognizer`. When the swipe fires the host asks this manager
-//  whether a kit stack is mounted (`checkCanPop`) and, if so, routes the back into it
-//  (`pop` → `Navigator.onBackSafe`) instead of dismissing the whole mini-app. Standalone
-//  (no such host, e.g. the demo app) there is no edge swipe — same as Compose on iOS,
-//  whose `BackHandler` is a no-op and which relies entirely on the host.
-//
-
 import Foundation
 
 @available(iOS 16.0, *)
@@ -21,28 +5,17 @@ public final class NavigatorManager {
     public static let shared = NavigatorManager()
     private init() {}
 
-    /// Stack of mounted navigators; the last one is the visible top (nested mini-apps
-    /// push more than one). Held strongly, mirroring `ComposeNavigatorManager` — entries
-    /// are released by `NavigationContainer` on disappear, not by ARC.
     private var navigators: [Navigator] = []
 
-    /// Idempotent: SwiftUI can re-run a view's `onAppear`, and a double push would need a
-    /// matching double remove to unwind.
     public func push(_ navigator: Navigator) {
         guard !navigators.contains(where: { $0 === navigator }) else { return }
         navigators.append(navigator)
     }
 
-    /// Removes by identity rather than `removeLast` so a spurious disappear of a covered
-    /// (non-top) container can't drop the wrong navigator.
     public func remove(_ navigator: Navigator) {
         navigators.removeAll { $0 === navigator }
     }
 
-    /// True while any kit stack is mounted — tells the host to route the back into the kit
-    /// instead of dismissing the mini-app. Matches `ComposeNavigatorManager.checkCanPop`:
-    /// it does not inspect stack depth; `onBackSafe` handles the at-root case itself by
-    /// asking the host to dismiss (via `composeApi`).
     public func checkCanPop() -> Bool { !navigators.isEmpty }
 
     public func pop() { navigators.last?.onBackSafe() }

package/ios/Colors+Radius+Spacing/Theme.swift

@@ -221,7 +221,7 @@ public let defaultTheme = Theme(
             container: Colors.blue08
         )
     ),
-    font: "SFProText",
+    font: "MomoTrustSans",
     assets: ThemeAssets(headerBackground: nil)
 )
 
@@ -277,7 +277,7 @@ public let darkTheme = Theme(
             container: Colors.blue08
         )
     ),
-    font: "SFProText",
+    font: "MomoTrustSans",
     assets: ThemeAssets(headerBackground: nil)
 )
 

package/ios/Typography/KitDesignSystem.swift

@@ -0,0 +1,17 @@
+import Foundation
+
+/// Design-system rollout flag for the SwiftUI kit, mirroring Compose's `KitDesignSystem`.
+/// The kit is sandboxed and can't read the host config, so the host writes `update(_:)` once at
+/// startup from `DesignSystemConfig`. Startup-only and non-reactive, like `FontScaleStore` was
+/// before it gained live updates: there is no SwiftUI navigation container to re-render from.
+public final class KitDesignSystem {
+    public static let shared = KitDesignSystem()
+
+    public private(set) var isWhiteList: Bool = false
+
+    private init() {}
+
+    public func update(isWhiteList: Bool) {
+        self.isWhiteList = isWhiteList
+    }
+}

package/ios/Typography/Text.swift

@@ -99,6 +99,30 @@ public extension TypographyStyle {
     }
 }
 
+private func momoFontName(family: String, weight: Font.Weight) -> String? {
+    // Ngoai whitelist thi tra nil de momoFont() roi ve .system(...), dung nhu truoc DS-791.
+    guard KitDesignSystem.shared.isWhiteList else { return nil }
+    guard family == "MomoTrustSans" else { return nil }
+    switch weight {
+    case .ultraLight, .thin: return "MomoTrustSans-ExtraLight"
+    case .light: return "MomoTrustSans-Light"
+    case .regular: return "MomoTrustSans-Regular"
+    case .medium: return "MomoTrustSans-Medium"
+    case .semibold: return "MomoTrustSans-SemiBold"
+    case .bold: return "MomoTrustSans-Bold"
+    case .heavy, .black: return "MomoTrustSans-ExtraBold"
+    default: return "MomoTrustSans-Regular"
+    }
+}
+
+private func momoFont(size: CGFloat, weight: Font.Weight, family: String) -> Font {
+    guard let name = momoFontName(family: family, weight: weight),
+          UIFont(name: name, size: size) != nil else {
+        return .system(size: size, weight: weight)
+    }
+    return .custom(name, fixedSize: size)
+}
+
 public struct MomoText: View {
     @Environment(\.appTheme) private var theme
     @Environment(\.momoFontScale) private var fontScale
@@ -159,7 +183,7 @@ public struct MomoText: View {
         let isStrikethrough = strikethrough || typography.isStrikethrough
 
         var text = SwiftUI.Text(content)
-            .font(fontScale.font(size: typography.fontSize, weight: typography.fontWeight))
+            .font(momoFont(size: fontScale(typography.fontSize), weight: typography.fontWeight, family: theme.font))
             .foregroundColor(textColor)
             .strikethrough(isStrikethrough, color: textColor)
             .underline(underline, color: textColor)

package/ios/native-kits.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'MoMoUIKits'
-  s.version          = '0.164.1-beta.2'
+  s.version          = '0.164.1-swipeback.1'
   s.summary          = 'MoMoUIKits for iOS'
   s.homepage         = 'https://momo.vn'
   s.license          = { :type => 'MIT' }

package/ios-demo/MoMoUIKitsDemo.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'MoMoUIKitsDemo'
-  s.version          = '0.164.1-beta.2'
+  s.version          = '0.164.1-swipeback.1'
   s.summary          = 'Demo browser for MoMoUIKits SwiftUI components'
   s.homepage         = 'https://momo.vn'
   s.license          = { :type => 'MIT' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@momo-kits/native-kits",
-  "version": "0.162.34-debug",
+  "version": "0.162.35-debug",
   "private": false,
   "dependeNavigationncies": {},
   "devDependencies": {},

package/publish.sh

@@ -372,10 +372,34 @@ phase_publish_npm() {
     # FIRST PUBLISH: DEBUG VERSION (with compose kits included)
     # ============================================================
     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."
+        exit 1
+    fi
+
     echo "🔧 Preparing debug version with compose kits..."
 
     # Create debug version
     DEBUG_VERSION="${VERSION}-debug"
+
+    # set -e aborts mid-phase on any failure; put the tree back no matter where it stopped.
+    # Idempotent: the happy path already moved the backups away and reset the version.
+    restore_npm_workspace() {
+        [ -f .npmignore.backup ] && mv .npmignore.backup .npmignore
+        [ -f compose/build.gradle.kts.backup ] && mv compose/build.gradle.kts.backup compose/build.gradle.kts
+        local pkg_version
+        pkg_version=$(node -p "require('./package.json').version")
+        if [ "$pkg_version" != "$VERSION" ]; then
+            if [[ "$OSTYPE" == "darwin"* ]]; then
+                sed -i '' "s/\"version\": \"$pkg_version\"/\"version\": \"$VERSION\"/" package.json
+            else
+                sed -i "s/\"version\": \"$pkg_version\"/\"version\": \"$VERSION\"/" package.json
+            fi
+        fi
+    }
+    trap restore_npm_workspace EXIT
     echo "📦 Debug version: $DEBUG_VERSION"
 
     # Get current version from package.json (in case it's different from $VERSION)
@@ -482,6 +506,7 @@ EOF
     npm publish --tag $NPM_TAG --access=public
 
     echo "✅ Normal version published successfully!"
+    trap - EXIT
 
     echo ""
     echo "✅ PHASE 3 COMPLETED"