@momo-kits/native-kits 0.162.30 → 0.162.31

package/CLAUDE.md

@@ -53,6 +53,25 @@ Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do
 - Access in a `@Composable`: `LocalLocalize.current.translate("errorCode")`. Language is host-controlled, never read from the OS locale. `AppLanguage` is still provided (derived from `Localize.currentLanguage`) for older components that read it.
 - Some older components still do ad-hoc `AppLanguage.current` + `Map` lookups; new/changed code should use `LocalLocalize`.
 
+### SwiftUI (`ios/Application/Localize.swift`)
+
+The SwiftUI port differs from Compose in one important way: **it follows the host app language by itself.**
+
+- `Localize.init` takes `languageSource: LanguageSource? = UserDefaultsLanguageSource()`. The default source KVO-observes `UserDefaults.standard["language"]` — the key the MoMo host writes from all three of its writers (the `RNResource` RN bridge, `JSONLocalization`, and the KMP `LocalizationProvider`) — so a language switch anywhere in the app republishes to every consumer. Pass `languageSource: nil` to opt out. The host key literal lives only in `UserDefaultsLanguageSource.defaultKey`.
+- Use `Localize.shared` unless a screen genuinely needs an isolated dictionary; it is also the `\.localize` environment default. Note `addTranslations` on it merges into a process-wide dictionary.
+- **Never set `\.localize` directly.** `EnvironmentValues.localize` stores a `LocalizeBox` snapshot, so consumers invalidate only when the injecting view re-runs its body. Always inject via `.momoLocalize(_:)` (`ios/Application/LocalizeModifier.swift`), which holds the object as `@ObservedObject` — that is what makes the snapshot refresh. `NavigationContainer` already does this; any bare `UIHostingController` root must do it too.
+- Read it with `@Environment(\.localize)`, not `@EnvironmentObject` — the environment default never traps, `@EnvironmentObject` fatal-errors when un-injected.
+- `Localize.normalize(_:)` is the single place that copes with the legacy JSON-quoted values (`"\"vi\""`) the host persists; anything that is not `en` resolves to `vi`.
+
+## Font scale (`scaleSize`)
+
+One formula, both platforms: the device-width scale (`width / 375`, capped at `+5pt`) and the OS Dynamic Type scale (capped at `1.5×`) are computed independently and the **larger wins**. When `useOSScaleRate` is false neither applies — the size is just multiplied by `userScaleRate`. Max font scale is fixed at 1.5; the old per-call/per-scope override is deprecated and ignored on both sides.
+
+- **Compose** — `const/Typography.kt` (`scaleSize` overloads for `Float`/`Dp`/`TextUnit`/`TextStyle`). The `TextUnit` overload divides by `density.fontScale` so Compose's own `sp` scaling isn't applied twice. Inputs: `LocalContext.current` (`MiniAppContext.userScaleRate` / `useOSScaleRate`, per-field) falling back to the `KitFontScale` global. On iOS, `platform/OsFontScale.ios.kt` observes `UIContentSizeCategoryDidChangeNotification` and overrides `LocalDensity` — Compose MP otherwise reads `fontScale` once at `ComposeUIViewController` creation. Wired at `NavigationContainer`.
+- **SwiftUI** — `ios/Typography/FontScale.swift`. `FontScale` is an immutable snapshot with `callAsFunction`, so a view reads `@Environment(\.momoFontScale) private var fontScale` and calls `fontScale(16)`. `FontScaleStore.shared` is the `ObservableObject` holding both inputs and the OS factor (it observes `UIContentSizeCategory.didChangeNotification`); the host pushes its preference with `update(userScaleRate:useOSScaleRate:)`.
+- **Never set `\.momoFontScale` directly** — same trap as `\.localize`. Inject via `.momoFontScale(_:context:)`, which holds the store as `@ObservedObject`; that is what re-publishes the snapshot. `NavigationContainer` does it (passing `MiniAppContext` so the per-mini-app override applies); a bare `UIHostingController` root must too. The environment default reads the live store, so an un-injected subtree still gets correct values — just not live ones.
+- The global `scaleSize(_:)` and `Font.appFont(size:)` remain for call sites that can't read the environment (UIKit bridges, free functions). They are **not** reactive. `Font.header_default_bold` & friends are computed `static var`s for the same reason — as stored `static let`s they froze the scale at first access. `UIViewRepresentable`s should read `context.environment.momoFontScale` instead, and re-apply the font in `updateUIView`, not only in `makeUIView`.
+
 ## Code conventions
 
 - **Tokens, not literals:** use `Colors`, `Typography`, `Spacing`, `Radius` objects and `AppTheme.current` for colors/styles. Per-component sizing is bundled in enums (e.g. `Button.Size(val value: ButtonSpecs)`).

package/ios/Application/ApplicationEnvironment.swift

@@ -17,8 +17,12 @@ public class MiniAppContext {
     public var toolkitConfig: [String: Any] = [:]
     public var providerId: String = "momo"
     public var permissions: [[String: Any]] = []
-    
-    public init(appId: String, appCode: String, appName: Any? = nil, appIcon: String, description: Any? = nil, support: [String: Any] = [:], toolkitConfig: [String: Any] = [:], providerId: String = "momo", 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.
+    public var userScaleRate: CGFloat? = nil
+    public var useOSScaleRate: Bool? = nil
+
+    public init(appId: String, appCode: String, appName: Any? = nil, appIcon: String, description: Any? = nil, support: [String: Any] = [:], toolkitConfig: [String: Any] = [:], providerId: String = "momo", permissions: [[String: Any]] = [], userScaleRate: CGFloat? = nil, useOSScaleRate: Bool? = nil) {
         self.appId = appId
         self.appCode = appCode
         self.appName = appName
@@ -28,6 +32,8 @@ public class MiniAppContext {
         self.toolkitConfig = toolkitConfig
         self.providerId = providerId
         self.permissions = permissions
+        self.userScaleRate = userScaleRate
+        self.useOSScaleRate = useOSScaleRate
     }
 }
 
@@ -38,10 +44,12 @@ public class KitConfig {
 }
 
 public class ApplicationEnvironment: ObservableObject {
-    let applicationContext: MiniAppContext?
-    let composeApi: KitComposeApi?
-    let config: KitConfig?
-    let maxApi: MaxApi?
+    // AI-GENERATED START: expose the host bridge to modules outside MoMoUIKits (e.g. the demo pod)
+    public let applicationContext: MiniAppContext?
+    public let composeApi: KitComposeApi?
+    public let config: KitConfig?
+    public let maxApi: MaxApi?
+    // AI-GENERATED END: expose the host bridge to modules outside MoMoUIKits (e.g. the demo pod)
 
     public init(applicationContext: MiniAppContext? = nil, composeApi: KitComposeApi? = nil, config: KitConfig? = nil, maxApi: MaxApi? = nil) {
         self.applicationContext = applicationContext

package/ios/Application/LanguageSource.swift

@@ -0,0 +1,93 @@
+// File: ios/Application/LanguageSource.swift
+// Created At: 2026-07-29 10:00:00 +07:00
+// Created By: AI
+// AI Agent: Claude Code
+// Model: claude-opus-5[1m]
+
+// AI-GENERATED START: observe the host app's active language so Localize can follow it
+import Foundation
+
+/// Read-only view of the host app's active language, plus change delivery.
+/// Values handed to `onChange` are already normalized to `Localize.VI` / `Localize.EN`.
+public protocol LanguageSource: AnyObject {
+    var currentLanguage: String { get }
+    /// `onChange` may be invoked on any thread; `Localize` dedupes and hops to main.
+    func startObserving(_ onChange: @escaping (String) -> Void)
+    func stopObserving()
+}
+
+/// Reads the language the MoMo host app persists in `UserDefaults`. All three host writers
+/// (the `RNResource` RN bridge, `JSONLocalization`, and the KMP `LocalizationProvider`) write the
+/// same key on `UserDefaults.standard` in-process, so KVO on it sees every one of them.
+public final class UserDefaultsLanguageSource: NSObject, LanguageSource {
+    public static let defaultKey = "language"
+
+    private let defaults: UserDefaults
+    private let key: String
+    private var onChange: ((String) -> Void)?
+    private var isObserving = false
+    private var kvoContext = 0
+
+    /// - Note: `key` must not contain `.` — `forKeyPath:` would read it as a key path.
+    public init(
+        defaults: UserDefaults = .standard,
+        key: String = UserDefaultsLanguageSource.defaultKey
+    ) {
+        self.defaults = defaults
+        self.key = key
+        super.init()
+    }
+
+    public var currentLanguage: String {
+        Localize.normalize(defaults.string(forKey: key))
+    }
+
+    public func startObserving(_ onChange: @escaping (String) -> Void) {
+        guard !isObserving else { return }
+        isObserving = true
+        self.onChange = onChange
+        defaults.addObserver(self, forKeyPath: key, options: [.new], context: &kvoContext)
+        // Safety net for writes KVO can miss (e.g. `removeObject`). Double delivery is free:
+        // `Localize` dedupes before touching `@Published`.
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(emit),
+            name: UserDefaults.didChangeNotification,
+            object: defaults
+        )
+    }
+
+    public func stopObserving() {
+        guard isObserving else { return }
+        isObserving = false
+        defaults.removeObserver(self, forKeyPath: key, context: &kvoContext)
+        NotificationCenter.default.removeObserver(
+            self,
+            name: UserDefaults.didChangeNotification,
+            object: defaults
+        )
+        onChange = nil
+    }
+
+    deinit {
+        stopObserving()
+    }
+
+    public override func observeValue(
+        forKeyPath keyPath: String?,
+        of object: Any?,
+        change: [NSKeyValueChangeKey: Any]?,
+        context: UnsafeMutableRawPointer?
+    ) {
+        guard context == &kvoContext else {
+            super.observeValue(forKeyPath: keyPath, of: object, change: change, context: context)
+            return
+        }
+        emit()
+    }
+
+    @objc private func emit() {
+        onChange?(currentLanguage)
+    }
+}
+// AI-GENERATED END: observe the host app's active language so Localize can follow it

package/ios/Application/Localize.swift

@@ -28,16 +28,69 @@ public final class Localize: ObservableObject {
     public static let VI = "vi"
     public static let EN = "en"
 
+    // AI-GENERATED START: follow the host app language and publish dictionary changes
+    /// App-wide instance bound to the host language; the environment default uses it too,
+    /// so every screen agrees on one language.
+    public static let shared = Localize()
+    // AI-GENERATED END: follow the host app language and publish dictionary changes
+
     private var assets: LocalizationObject
     @Published public private(set) var currentLanguage: String = Localize.VI
 
-    public init(_ translations: LocalizationObject = LocalizationObject()) {
+    // AI-GENERATED START: follow the host app language and publish dictionary changes
+    /// Bumped by `addTranslations` — `assets` is not published, so without this the dictionary
+    /// can change without any consumer re-rendering.
+    @Published public private(set) var revision: Int = 0
+
+    private let languageSource: LanguageSource?
+
+    /// `NavigationContainer` uses this to skip its legacy one-shot `MaxApi` pull.
+    var observesAppLanguage: Bool { languageSource != nil }
+
+    /// Pass `languageSource: nil` to opt out and keep the old "starts at vi" behavior.
+    public init(
+        _ translations: LocalizationObject = LocalizationObject(),
+        languageSource: LanguageSource? = UserDefaultsLanguageSource()
+    ) {
         self.assets = Localize.merge(base: Localize.defaultLanguage, override: translations)
+        self.languageSource = languageSource
+        guard let languageSource else { return }
+        // Seed synchronously so the first frame is already correct (no vi -> en flash).
+        currentLanguage = languageSource.currentLanguage
+        languageSource.startObserving { [weak self] language in self?.apply(language) }
+    }
+
+    deinit {
+        languageSource?.stopObserving()
+    }
+
+    /// Host values are sometimes legacy JSON-quoted (`"\"vi\""`); anything that is not `en` is `vi`.
+    public static func normalize(_ raw: String?) -> String {
+        let cleaned = (raw ?? "")
+            .replacingOccurrences(of: "\"", with: "")
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+        return cleaned == Localize.EN ? Localize.EN : Localize.VI
+    }
+
+    private func apply(_ language: String) {
+        // KVO and didChangeNotification both fire for one write; publish once, on main.
+        onMain {
+            guard self.currentLanguage != language else { return }
+            self.currentLanguage = language
+        }
+    }
+
+    /// Synchronous when already on main — an async hop would defer the switch by a frame.
+    private func onMain(_ work: @escaping () -> Void) {
+        if Thread.isMainThread { work() } else { DispatchQueue.main.async(execute: work) }
     }
 
+    /// A local override: the next host language change supersedes it.
     public func changeLanguage(_ language: String?) {
-        currentLanguage = (language == Localize.EN) ? Localize.EN : Localize.VI
+        apply(Localize.normalize(language))
     }
+    // AI-GENERATED END: follow the host app language and publish dictionary changes
 
     public func translate(_ key: String) -> String {
         let dictionary = currentLanguage == Localize.EN ? assets.en : assets.vi
@@ -58,6 +111,9 @@ public final class Localize: ObservableObject {
     /// Existing keys win (mirrors Compose: `merge(translations, assets)`).
     public func addTranslations(_ translations: LocalizationObject) {
         assets = Localize.merge(base: translations, override: assets)
+        // AI-GENERATED START: publish dictionary changes so consumers re-render
+        onMain { self.revision &+= 1 }
+        // AI-GENERATED END: publish dictionary changes so consumers re-render
     }
 
     private static func merge(base: LocalizationObject, override: LocalizationObject) -> LocalizationObject {
@@ -283,14 +339,22 @@ public final class Localize: ObservableObject {
 private struct LocalizeBox: Equatable {
     let localize: Localize
     let language: String
+    // AI-GENERATED START: invalidate consumers when the dictionary changes, not just the language
+    let revision: Int
+    // AI-GENERATED END: invalidate consumers when the dictionary changes, not just the language
 
     init(_ localize: Localize) {
         self.localize = localize
         self.language = localize.currentLanguage
+        // AI-GENERATED START: invalidate consumers when the dictionary changes, not just the language
+        self.revision = localize.revision
+        // AI-GENERATED END: invalidate consumers when the dictionary changes, not just the language
     }
 
     static func == (lhs: LocalizeBox, rhs: LocalizeBox) -> Bool {
-        lhs.localize === rhs.localize && lhs.language == rhs.language
+        // AI-GENERATED START: invalidate consumers when the dictionary changes, not just the language
+        lhs.localize === rhs.localize && lhs.language == rhs.language && lhs.revision == rhs.revision
+        // AI-GENERATED END: invalidate consumers when the dictionary changes, not just the language
     }
 }
 
@@ -298,7 +362,12 @@ private struct LocalizeKey: EnvironmentKey {
     /// A default-constructed `Localize` already carries the full kit dictionary, so a
     /// consumer that never injects one renders untranslated-but-correct text instead of
     /// trapping the way `@EnvironmentObject` does.
-    static let defaultValue = LocalizeBox(Localize())
+    // AI-GENERATED START: default to the app-language-observing shared instance
+    /// `defaultValue` is a `static let`, so this box is never rebuilt: without a provider the
+    /// language is right on first render but does not live-update. Wrap the root in
+    /// `.momoLocalize()` (or use `NavigationContainer`) to get updates.
+    static let defaultValue = LocalizeBox(Localize.shared)
+    // AI-GENERATED END: default to the app-language-observing shared instance
 }
 
 public extension EnvironmentValues {

package/ios/Application/LocalizeModifier.swift

@@ -0,0 +1,30 @@
+// File: ios/Application/LocalizeModifier.swift
+// Created At: 2026-07-29 10:00:00 +07:00
+// Created By: AI
+// AI Agent: Claude Code
+// Model: claude-opus-5[1m]
+
+// AI-GENERATED START: inject a language-observing Localize into any SwiftUI subtree
+import SwiftUI
+
+public extension View {
+    /// Injects an app-language-observing `Localize` and re-renders this subtree on change.
+    /// Use at every `UIHostingController` root that is not inside a `NavigationContainer`.
+    func momoLocalize(_ localize: Localize = .shared) -> some View {
+        modifier(MomoLocalizeModifier(localize: localize))
+    }
+}
+
+/// `@ObservedObject` is load-bearing: `@Environment(\.localize)` only invalidates when the boxed
+/// value changes, which requires *this* body to re-run on every publish. A plain helper that just
+/// set `\.localize` would inject a snapshot that never updates.
+private struct MomoLocalizeModifier: ViewModifier {
+    @ObservedObject var localize: Localize
+
+    func body(content: Content) -> some View {
+        content
+            .environmentObject(localize)
+            .environment(\.localize, localize)
+    }
+}
+// AI-GENERATED END: inject a language-observing Localize into any SwiftUI subtree

package/ios/Application/Navigation/NavigationContainer.swift

@@ -46,7 +46,9 @@ public struct NavigationContainer<Initial: View>: View {
                 maxApi: maxApi
             )
         )
-        _localize = StateObject(wrappedValue: localize ?? Localize())
+        // AI-GENERATED START: default to the app-language-observing shared Localize
+        _localize = StateObject(wrappedValue: localize ?? Localize.shared)
+        // AI-GENERATED END: default to the app-language-observing shared Localize
         self.composeApi = composeApi
         self.maxApi = maxApi
         self.setNavigator = setNavigator
@@ -62,15 +64,19 @@ public struct NavigationContainer<Initial: View>: View {
         .environmentObject(navigator)
         .environmentObject(applicationEnvironment)
         .environment(\.applicationEnvironment, applicationEnvironment)
-        .environmentObject(localize)
-        .environment(\.localize, localize)
+        // AI-GENERATED START: route Localize + font-scale injection through the observing modifiers
+        .momoLocalize(localize)
+        .momoFontScale(context: applicationEnvironment.applicationContext)
+        // AI-GENERATED END: route Localize + font-scale injection through the observing modifiers
         .fullScreenCover(item: $navigator.presented) { route in
             screenView(forDialog: route)
                 .environmentObject(navigator)
                 .environmentObject(applicationEnvironment)
                 .environment(\.applicationEnvironment, applicationEnvironment)
-                .environmentObject(localize)
-                .environment(\.localize, localize)
+                // AI-GENERATED START: route Localize + font-scale injection through the observing modifiers
+                .momoLocalize(localize)
+                .momoFontScale(context: applicationEnvironment.applicationContext)
+                // AI-GENERATED END: route Localize + font-scale injection through the observing modifiers
         }
         .overlay {
             if let item = navigator.overplay {
@@ -78,8 +84,10 @@ public struct NavigationContainer<Initial: View>: View {
                     .environmentObject(navigator)
                     .environmentObject(applicationEnvironment)
                     .environment(\.applicationEnvironment, applicationEnvironment)
-                    .environmentObject(localize)
-                    .environment(\.localize, localize)
+                    // AI-GENERATED START: route Localize + font-scale injection through the observing modifiers
+                    .momoLocalize(localize)
+                    .momoFontScale(context: applicationEnvironment.applicationContext)
+                    // AI-GENERATED END: route Localize + font-scale injection through the observing modifiers
             }
         }
         .onAppear {
@@ -87,13 +95,21 @@ public struct NavigationContainer<Initial: View>: View {
                 navigator.composeApi = composeApi
             }
             setNavigator?(navigator)
-            // Mirrors Compose's LaunchedEffect(maxApi, resolvedLocalize): host-reported
-            // language wins over the default "vi" only when it resolves to English.
+            // Register with the host swipe-back bridge (mirrors ComposeAppContainer's
+            // ComposeNavigatorManager.push). Idempotent, so a re-appear won't double-count.
+            NavigatorManager.shared.push(navigator)
+            // AI-GENERATED START: demote the MaxApi language pull to a seed of last resort
+            // Only a seed: a Localize with a language source already tracks the host in both
+            // directions, so asking maxApi would just race it. `changeLanguage` normalizes the
+            // raw response and hops to main itself.
+            guard !localize.observesAppLanguage else { return }
             maxApi?.getLanguage { data in
-                if parseLanguage(data) == Localize.EN {
-                    localize.changeLanguage(Localize.EN)
-                }
+                localize.changeLanguage(data?["response"] as? String)
             }
+            // AI-GENERATED END: demote the MaxApi language pull to a seed of last resort
+        }
+        .onDisappear {
+            NavigatorManager.shared.remove(navigator)
         }
     }
 
@@ -195,9 +211,3 @@ private func safeAreaBottomInset() -> CGFloat {
         .compactMap { ($0 as? UIWindowScene)?.keyWindow?.safeAreaInsets.bottom }
         .first ?? 0
 }
-
-private func parseLanguage(_ raw: [String: Any?]?) -> String? {
-    guard let response = (raw?["response"] as? String)?.trimmingCharacters(in: .whitespaces).lowercased(),
-          !response.isEmpty else { return nil }
-    return response.hasPrefix(Localize.EN) ? Localize.EN : Localize.VI
-}

package/ios/Application/Navigation/Navigator.swift

@@ -89,7 +89,11 @@ public struct OverplayItem: Identifiable {
 
 @available(iOS 16.0, *)
 public final class Navigator: ObservableObject {
-    @Published public var path: [DynamicScreenRoute] = []
+    @Published public var path: [DynamicScreenRoute] = [] {
+        // Disposal hangs off the path so every route that leaves the stack — pop,
+        // replace, reset — is released the same way, after its exit transition.
+        didSet { disposeScreens(droppedFrom: oldValue) }
+    }
     @Published public var presented: DynamicDialogRoute?
     @Published public var overplay: OverplayItem?
 
@@ -147,8 +151,7 @@ public final class Navigator: ObservableObject {
 
     public func replace<V: View>(@ViewBuilder _ content: @escaping () -> V, options: NavigationOptions? = nil) {
         guard !path.isEmpty else { return }
-        let removed = path.removeLast()
-        registry.unregister(id: removed.id)
+        path.removeLast()
         push(content, options: options)
     }
 
@@ -158,14 +161,12 @@ public final class Navigator: ObservableObject {
         options: NavigationOptions? = nil
     ) {
         guard !path.isEmpty else { return }
-        let removed = path.removeLast()
-        registry.unregister(id: removed.id)
+        path.removeLast()
         push(screenName: screenName, content, options: options)
     }
 
     public func reset<V: View>(@ViewBuilder _ content: @escaping () -> V, options: NavigationOptions? = nil) {
-        for route in path { registry.unregister(id: route.id) }
-        registry.unregister(id: rootRoute.id)
+        let previousRoot = rootRoute.id
         path.removeAll()
         let route = registry.register(
             screenName: options?.screenName ?? "",
@@ -173,6 +174,7 @@ public final class Navigator: ObservableObject {
             options: options
         )
         rootRoute = route
+        disposeScreens([previousRoot])
     }
 
     public func reset<V: View>(
@@ -180,8 +182,7 @@ public final class Navigator: ObservableObject {
         @ViewBuilder _ content: @escaping () -> V,
         options: NavigationOptions? = nil
     ) {
-        for route in path { registry.unregister(id: route.id) }
-        registry.unregister(id: rootRoute.id)
+        let previousRoot = rootRoute.id
         path.removeAll()
         let route = registry.register(
             screenName: screenName,
@@ -189,26 +190,50 @@ public final class Navigator: ObservableObject {
             options: options
         )
         rootRoute = route
+        disposeScreens([previousRoot])
     }
 
     public func pop(_ count: Int = 1, callback: (() -> Void)? = nil) {
-        var remaining = count
-        while remaining > 0 {
-            if overplay?.type == .snackBar {
-                // Mirrors Kotlin: a snackbar doesn't block back-navigation, so popping
-                // while one is showing pops the screen underneath and clears the
-                // snackbar immediately, without playing its dismiss animation.
-                overplayDismissHandler = nil
-                overplay = nil
-                if !popScreen() { break }
-            } else if overplay != nil {
-                hideOverplay()
-            } else if !popScreen() {
-                break
+        popStep(remaining: count, callback: callback)
+    }
+
+    /// One `pop` iteration. Compose runs the loop in a coroutine and suspends over the
+    /// overplay's exit animation before the next step; the same wait is needed here, or
+    /// a `pop(2)` (prevent-back: close the popup, then leave) would spend both steps on
+    /// the overplay that is still animating out and never pop the screen.
+    private func popStep(remaining: Int, callback: (() -> Void)?) {
+        guard remaining > 0 else {
+            callback?()
+            return
+        }
+
+        if overplay?.type == .snackBar {
+            // Mirrors Kotlin: a snackbar doesn't block back-navigation, so popping
+            // while one is showing pops the screen underneath and clears the
+            // snackbar immediately, without playing its dismiss animation.
+            overplayDismissHandler = nil
+            overplay = nil
+            guard popScreen() else {
+                callback?()
+                return
+            }
+            popStep(remaining: remaining - 1, callback: callback)
+        } else if overplay != nil {
+            hideOverplay()
+            DispatchQueue.main.asyncAfter(deadline: .now() + Self.overplayDismissDelay) { [weak self] in
+                guard let self else { return }
+                // The component reports back through `finishOverplayDismiss` once its exit
+                // animation ends; clear it here if it never did, so the step is not wasted.
+                if self.overplay != nil { self.finishOverplayDismiss() }
+                self.popStep(remaining: remaining - 1, callback: callback)
             }
-            remaining -= 1
+        } else {
+            guard popScreen() else {
+                callback?()
+                return
+            }
+            popStep(remaining: remaining - 1, callback: callback)
         }
-        callback?()
     }
 
     /// Pops the topmost presented screen or stack entry. Returns `false` (and requests
@@ -218,11 +243,10 @@ public final class Navigator: ObservableObject {
         if presented != nil {
             let dismissedId = presented?.id
             presented = nil
-            if let id = dismissedId { registry.unregister(id: id) }
+            if let id = dismissedId { disposeScreens([id]) }
             return true
         } else if !path.isEmpty {
-            let removed = path.removeLast()
-            registry.unregister(id: removed.id)
+            path.removeLast()
             return true
         } else {
             composeApi?.requestCallback(funcName: "dismiss", params: nil, onResponse: nil)
@@ -231,42 +255,54 @@ public final class Navigator: ObservableObject {
     }
 
     public func popToRoot() {
-        for route in path { registry.unregister(id: route.id) }
         path.removeAll()
     }
 
+    /// The entry a back action applies to — mirrors Compose's `currentScreen()`
+    /// (`navController.currentBackStackEntry`): a presented screen sits on top of
+    /// the stack, otherwise it is the last pushed screen, otherwise the root.
+    private func currentScreen() -> DynamicScreen? {
+        registry.getScreen(id: presented?.id ?? path.last?.id ?? rootRoute.id)
+    }
+
     public func onBackSafe(callback: (() -> Void)? = nil) {
-        let latest = registry.latest()
+        let latest = currentScreen()
         if let onBack = latest?.options?.onBackHandler {
             onBack()
             return
         }
         if let preventBack = latest?.options?.headerBackProps?.preventBack {
             showModal {
-                PopupDisplay(
-                    isPresented: .constant(true),
-                    title: preventBack.title,
-                    description: preventBack.description,
-                    url: preventBack.image,
-                    buttonDirection: preventBack.buttonDirection,
-                    buttonType: .button,
-                    actionButtonTitle: preventBack.primary?.title ?? "",
-                    closeButtonTitle: preventBack.secondary?.title ?? "",
-                    onPressAction: { [weak self] in
-                        preventBack.primary?.onPress?()
-                        // Close the popup, then leave the screen (matches Compose's pop(2)).
-                        self?.pop(2, callback: callback)
-                    },
-                    onPressCloseButton: { [weak self] in
-                        preventBack.secondary?.onPress?()
-                        self?.hideOverplay()
-                    },
-                    onClose: { [weak self] in
-                        preventBack.onIconClose?()
-                        self?.hideOverplay()
-                    },
-                    errorCode: preventBack.error,
-                    isShowCloseIcon: preventBack.isShowCloseIcon
+                PopupNotify(
+                    props: PopupNotifyProps(
+                        image: preventBack.image,
+                        title: preventBack.title,
+                        description: preventBack.description,
+                        error: preventBack.error,
+                        primary: PopupAction(
+                            title: preventBack.primary?.title ?? "",
+                            onPress: { [weak self] in
+                                preventBack.primary?.onPress?()
+                                // Close the popup, then leave the screen (matches Compose's pop(2)).
+                                self?.pop(2, callback: callback)
+                            }
+                        ),
+                        secondary: preventBack.secondary.map { secondary in
+                            PopupAction(
+                                title: secondary.title,
+                                onPress: { [weak self] in
+                                    secondary.onPress?()
+                                    self?.hideOverplay()
+                                }
+                            )
+                        },
+                        buttonDirection: preventBack.buttonDirection,
+                        onIconClose: { [weak self] in
+                            preventBack.onIconClose?()
+                            self?.hideOverplay()
+                        },
+                        isShowCloseIcon: preventBack.isShowCloseIcon
+                    )
                 )
             }
             return
@@ -382,4 +418,36 @@ public final class Navigator: ObservableObject {
     public func hideSnackBar() {
         if overplay?.type == .snackBar { hideOverplay() }
     }
+
+    // MARK: Screen disposal
+
+    /// Matches the `delay(300)` Compose waits in `dismissScreen` before unregistering,
+    /// with a little headroom for the pop transition.
+    private static let screenDisposeDelay: TimeInterval = 0.35
+
+    /// Longest overplay exit animation (the bottom sheet's), so a queued pop step runs
+    /// after the component has taken itself down.
+    private static let overplayDismissDelay: TimeInterval = 0.3
+
+    private func disposeScreens(droppedFrom previous: [DynamicScreenRoute]) {
+        let live = Set(path.map(\.id))
+        disposeScreens(previous.map(\.id).filter { !live.contains($0) })
+    }
+
+    /// Screens are released only once the pop transition has played out: the outgoing
+    /// view is still on screen while it animates and the registry is what renders it —
+    /// dropping it right away blanks the screen mid-transition. Liveness is re-checked
+    /// when the timer fires, so a route pushed back before then keeps its screen.
+    private func disposeScreens(_ ids: [Int]) {
+        guard !ids.isEmpty else { return }
+        DispatchQueue.main.asyncAfter(deadline: .now() + Self.screenDisposeDelay) { [weak self] in
+            guard let self else { return }
+            var live = Set(self.path.map(\.id))
+            live.insert(self.rootRoute.id)
+            if let presented = self.presented { live.insert(presented.id) }
+            for id in ids where !live.contains(id) {
+                self.registry.unregister(id: id)
+            }
+        }
+    }
 }