@momo-kits/native-kits 0.162.2-sp.7-debug → 0.162.2-sp.8-debug

package/ios/PARITY_AUDIT.md

@@ -0,0 +1,641 @@
+# iOS Swift Kit Parity Audit
+
+Tracks the ongoing parity pass between `compose/src/commonMain/kotlin/vn/momo/kits/` (source of truth)
+and the hand-maintained native SwiftUI port under `ios/`. Appended to per tier/batch so the pass is
+resumable across sessions without re-deriving prior findings.
+
+## Tier 0 — Tokens
+
+- **Colors.swift**: fixed scrambled violet scale (violet04/05/06/09/10 held wrong Kotlin values, shifted
+  by 1-3 steps); added missing `violet04` value (`a03ff1`), `violet11`, `violet11Stroke`; added missing
+  `pinkMoMoBranding`; fixed `info` alias to reference `blue03` instead of a duplicated hardcoded hex.
+  No existing call sites used the wrong violet tokens (grepped, zero hits), so this was a pure bug fix
+  with no visual regression risk.
+- **Spacing.swift**: added missing `Size4XL`(56)/`Size5XL`(64); renamed `XXXL`→`Size3XL` to match Kotlin
+  (zero external call sites found, so the rename is safe, not just aliased).
+- **Typography.swift** (`ios/Typography/Typography.swift`): **no fix needed.** The initial audit flagged
+  missing strikethrough variants here, but this file's snake_case `Font` extension is dead code (zero
+  call sites anywhere in `ios/`). The actual typography system used throughout the port is
+  `TypographyStyle`/`MomoText` in `ios/Typography/Text.swift`, which already has full 1:1 parity with
+  Kotlin's `AppTypography`, including all three strikethrough variants. Flagged as stale/legacy, not
+  touched — removing dead code was out of scope for this pass.
+
+## Tier 1 — Navigation core
+
+- **`Navigator.pop()` snackbar bug — fixed.** Kotlin's `pop()` special-cases `SNACK_BAR` to fall through
+  and pop the screen underneath (confirmed at `Navigator.kt:84-91`); Swift's `pop()` previously treated
+  any `overplay != nil` (including snackbar) as fully consuming the pop via `hideOverplay()`, silently
+  swallowing back-navigation while a snackbar was showing. Fixed by special-casing `.snackBar` to clear
+  the overplay immediately (no exit animation, matching Kotlin's `hardClearAfterDismiss()`) and falling
+  through to pop the screen. Extracted the screen-pop branch into a `popScreen() -> Bool` helper to avoid
+  duplicating it between the snackbar and normal branches while preserving the original "nothing left to
+  pop → request host dismiss and break" behavior. Internal control-flow only, no signature change.
+- **`DynamicScreenRegistry` singleton → instance-scoped — fixed.** Was a process-wide `static let shared`
+  (`Navigator.swift:33`); Kotlin scopes one registry per `NavigationContainer` and disposes it
+  (`remember { DynamicScreenRegistry() }`). Converted to a `public let registry = DynamicScreenRegistry()`
+  owned by `Navigator`; disposal now happens implicitly via ARC when the `Navigator` (`@StateObject` in
+  `NavigationContainer`) deallocates, rather than needing an explicit teardown call. Contained to 2 files
+  (`Navigator.swift`, `NavigationContainer.swift` — the only two referencing the old singleton, confirmed
+  by repo-wide grep). **Behavior-changing**: multiple concurrent `NavigationContainer`s no longer share
+  global screen-ID state — call this out explicitly if this pass gets reviewed/merged.
+- **Deferred, documented gaps (not fixed this pass):** Kotlin's `Navigation.kt` (per-screen mutable
+  `NavigationOptions` + `setOptions()` + `LocalNavigation`, letting a pushed screen imperatively mutate
+  its own header at runtime) has no Swift port at all — new API surface, bigger scope than a parity fix.
+  The `IsShowBaseLineDebug` global debug-border flag also has no Swift equivalent — low priority.
+- Verified via full `iosApp` scheme build (`xcodebuild ... -scheme iosApp -destination 'id=EFD1594B-...'`,
+  iPhone 14 / iOS 16.4 simulator) — `** BUILD SUCCEEDED **`. This exercises the real `Demo/*.swift` call
+  sites, confirming no signature breakage from the registry/pop changes.
+
+## Tier 2 — Cross-cutting subsystems (Localize, ScreenTracker)
+
+- **`ios/Application/MaxApi.swift` (new).** Minimal `MaxApi` protocol (`track`, `dismiss`, `getLanguage`)
+  mirroring `vn.momo.maxapi.IMaxApi` — scoped to exactly the 3 methods actually called anywhere in the
+  Kotlin `kits` source (confirmed by a repo-wide grep for `maxApi?.`/`api.` call sites: `ScreenTracker.kt`
+  calls `track`, `Navigator.kt` calls `dismiss`, `NavigationContainer.kt` calls `getLanguage`). `IMaxApi`
+  itself is an external compiled dependency with no source in this repo, so this is intentionally not a
+  guess at its full surface.
+- **`ios/Application/Navigation/Tracking/ScreenTracker.swift` (new).** 1:1 port of `ScreenTracker.kt` —
+  `ScreenTrackingState`, `trackScreenNavigated/Displayed/Interacted`, `trackPopupDisplayed`,
+  `getLastScreenName`/`reset`. Pure logic, no platform dependency beyond `MaxApi`.
+- **`ios/Application/Localize.swift` (new).** 1:1 port of `Localize.kt` — `LocalizationObject`,
+  `Localize` (`ObservableObject`, `@Published currentLanguage` so a language switch republishes to
+  consumers), `translate`/`translateData`(×2)/`addTranslations`/`changeLanguage`, and the full 101-key
+  VI/EN default dictionary. **Verified via scripted key-set AND value diff against `Localize.kt`: 0
+  mismatches** (all 202 key/value pairs across both languages transcribed exactly).
+- **Wiring**: `ApplicationEnvironment` gained an additive `maxApi: MaxApi?` field (default `nil`).
+  `NavigationContainer` gained additive `maxApi`/`localize` params; on `.onAppear` it now calls
+  `maxApi?.getLanguage` and switches to `EN` only when the host reports it (mirrors Compose's
+  `LaunchedEffect(maxApi, resolvedLocalize)` + `parseLanguage`). `StackScreen` gained an additive
+  `screenName` param and a `.task(id: screenName)` that fires `trackScreenNavigated` immediately, then
+  `trackScreenDisplayed`/`trackScreenInteracted` after a 2s debounce — mirrors Compose's
+  `LaunchedEffect(name)` + `delay(2000ms)` exactly, including the once-computed push/back `action` value.
+  `ModalScreen`/`BottomSheetView` each gained `trackPopupDisplayed` in their existing `onAppear` guard.
+  `SnackBarView` intentionally gets **no** tracking call — confirmed Kotlin's `SnackBar.kt` doesn't call
+  `ScreenTracker` either, so this isn't a gap.
+- **Demo-only verification aid**: `sample/iosApp/iosApp/Demo/ConsoleMaxApi.swift` (new, demo target only,
+  not shipped in the pod) implements `MaxApi` by logging every call; wired into `Home.swift`'s root
+  `NavigationContainer`. Added to the `iosApp` Xcode target via the `xcodeproj` Ruby gem (safer than
+  hand-editing `project.pbxproj`).
+- **Verification**: `pod install` (new source files needed the Pods project regenerated to pick them up —
+  the podspec's `Application/**/*` glob already covered the new paths, just needed re-scanning), then both
+  `MoMoUIKits` and `iosApp` scheme builds — `** BUILD SUCCEEDED **`, zero signature-breakage. A live
+  simulator console-log smoke check was attempted (launch the demo app, capture stdout/stderr via
+  `simctl launch --stdout/--stderr` and via `log stream`) but did not surface `print()` output in this
+  sandboxed environment — GUI apps launched via `simctl` don't reliably pipe raw stdout the way a CLI
+  process does, independent of whether the tracking/localize code itself is correct. Not pursued further
+  since it's a documented "nice to have" per the plan, not the mandatory gate; the compile + dictionary-diff
+  verification already gives strong evidence the wiring is structurally correct.
+
+## Tier 3 — Component batches
+
+### Batch 1 — Static display atoms (Avatar, Badge, BadgeDot, BadgeRibbon, Divider, Icon, Image, Tag)
+
+- **Avatar, Badge, BadgeDot, Divider**: full parity, no findings (only the already-deferred
+  `IsShowBaseLineDebug` debug border gap, consistent with Tier 1's decision to leave that undone).
+- **BadgeRibbon**: `RoundedBadgeRibbon` (BadgeRibbon.kt:164-326) — a canvas-drawn ribbon shape sized to
+  its text — had **zero Swift port**. **Fixed**: added `ios/Badge/BadgeRibbon.swift`'s new
+  `RoundedBadgeRibbon` view, using SwiftUI `Canvas` + the file's existing `RoundedCorners` shape helper
+  for the per-corner-radius path math, and the file's pre-existing (previously unused)
+  `String.size(withAttributes:)` extension for text measurement — that extension being already present
+  but unused strongly suggests someone scaffolded this port before and didn't finish it. Colors
+  (`orange03`/`red01`) reference tokens instead of Kotlin's hardcoded hex literals. Flagged, not touched:
+  Swift's extra public `backgroundColor` param on `BadgeRibbon` (not in Kotlin's public API) — removing
+  would break existing callers for no parity benefit.
+- **Icon**: two findings.
+  1. Kotlin defaults `color` to the theme's text-default color (tinting every icon unless in
+     `noThemeIcons`); Swift defaults to `nil` (untinted). Changes rendering for most existing callers —
+     **flagged only**, not changed.
+  2. Swift's public `accessibilityLabel` param was accepted but never applied anywhere in `body`. **Fixed**
+     — wired via `.accessibilityLabel(accessibilityLabel ?? "img|\(uri)")`, mirroring Kotlin's
+     auto-generated `contentDescription = "img|$iconUrl"` default while still honoring an explicit
+     override. Non-breaking (previously-dead prop becoming live is a strict improvement, not a behavior
+     change for existing callers who weren't setting it).
+- **Image / ImageView**: several findings.
+  1. Default `contentMode` differs (Kotlin crops by default, Swift fits) — changes default visual fit for
+     unconfigured callers. **Flagged only**, not changed.
+  2. Hardcoded `Colors.black08` error-placeholder tint bypassing the theme (Kotlin uses
+     `theme.colors.text.disable`). **Fixed** — added `@Environment(\.appTheme)` and swapped in
+     `theme.colors.text.disable`.
+  3. Missing `loading: Bool` toggle (to suppress the skeleton placeholder) and `onStateChanged` callback +
+     `ImageState` enum. **Fixed** — both added additively (defaults preserve current behavior:
+     `loading` defaults `true`, `onStateChanged` defaults `nil`).
+  4. **Deferred, not fixed**: Kotlin's CDN size-optimization (`supportedDomains`/`sizeChart`/
+     `appendSizeQueryParam`, appending a `?size=` query param sized to the rendered width) and GIF
+     detection/`GifImage` support have no Swift equivalent. These are real feature gaps but substantially
+     larger scope than a parity bug fix (new URL-processing pipeline, new dependency for GIF playback) —
+     documented here rather than silently dropped.
+- **Tag**: Kotlin's public `customColor: Color?` param has no Swift equivalent — **but confirmed dead code
+  even in the Kotlin source itself**: `Tag.kt:58-61`'s `if (primaryColors.contains(customColor))` branch
+  reassigns `tagColor`/`labelColor` to the exact values they already held, regardless of the branch outcome.
+  Porting an inert param for signature-parity's sake would replicate a no-op rather than fix a gap —
+  **not ported**, documented as an intentional skip.
+- Verified via `MoMoUIKits` scheme build and full `iosApp` scheme build (exercises real Demo call sites) —
+  both `** BUILD SUCCEEDED **`.
+
+### Batch 2 — Typographic/status atoms (Text, Title, Tooltip, Information, ProgressInfo, Loader, Skeleton, BaselineView)
+
+- **Title, Loader, BaselineView**: full parity, no findings.
+- **Text/MomoText**: Kotlin's `Text` has a missing-ellipsis mode (`overflow = Clip` default, no truncation
+  indicator) that `MomoText`/SwiftUI's `truncationMode` can't express (always shows "…" when clipped) —
+  **flagged only**, would need a new API shape. Also missing `onTextLayout`, `inlineContent` (rich inline
+  spans), an `AnnotatedString` overload, and a `fontFamily` override — all real gaps but substantial new
+  capability (rich-text spans, layout measurement callbacks), not simple parity bugs. **Deferred**,
+  documented rather than partially implemented, consistent with the Image CDN/GIF deferral in Batch 1.
+- **Tooltip**: two findings.
+  1. Positioning architecture differs fundamentally (Compose: OS-level `Popup` with outside-tap dismiss +
+     no clipping; Swift: in-hierarchy overlay, no outside-tap dismiss, can be clipped by ancestors).
+     **Flagged only** — an architecture change, not a small fix.
+  2. Missing width-yielding constraint on the 2-button secondary action (Compose:
+     `Modifier.weight(1f, fill=false)`). **Fixed** — added `.layoutPriority(-1)` to
+     `TooltipSecondaryButton` so it shrinks before the primary button under width pressure. Low practical
+     impact since both buttons already pre-truncate their title to 16 chars, but cheap and correct to add.
+- **Information**: close-icon color was hardcoded to `Colors.black17` instead of following the theme
+  (Kotlin's icon has no explicit color, defaulting to `theme.colors.text.default`). Values coincide under
+  the default theme so no visible change today, but breaks for non-default themes. **Fixed** — added
+  `@Environment(\.appTheme)` and switched to `theme.colors.text.default`.
+- **ProgressInfo**: two findings, both **fixed**.
+  1. Vertical connector line color was hardcoded to the asset-catalog `Colors.primary` instead of
+     `theme.colors.primary.opacity(0.2)` — added `@Environment(\.appTheme)` to `ProgressInfoVertical` and
+     switched. Changes rendered output under non-default themes only (matches source-of-truth behavior).
+  2. `progressInfoAccentColor` duplicated the `pinkMoMoBranding` hex as a raw literal (with a comment
+     already noting what it was meant to be) instead of referencing the token added in Tier 0 — swapped to
+     `Colors.pinkMoMoBranding`.
+- **Skeleton**: two findings.
+  1. Extra public `durationMillis`/`angleOfAxisY` params not in Kotlin's zero-arg `Skeleton()`. **Flagged
+     only** — existing Swift callers may depend on these, can't remove.
+  2. Shimmer travel-distance formula differs from Kotlin's literal `durationMillis + widthOfShadowBrush`
+     (which mixes milliseconds with pixels). **Investigated, not changed**: the Swift file already carries
+     an explanatory comment showing this was a deliberate, reasoned substitution — Kotlin's formula is
+     dimensionally inconsistent and produces an arguably-unintended sweep distance/speed depending on
+     container width; Swift's `size.width + widthOfShadowBrush` is dimensionally consistent and always
+     produces a full-width sweep regardless of container size. Re-matching Kotlin's literal formula here
+     would reintroduce a questionable behavior rather than fix a real bug — left as is, documented rather
+     than silently reverted.
+- Verified via `MoMoUIKits` scheme build — `** BUILD SUCCEEDED **`.
+
+### Button / IconButton / Input — fixes from the initial (pre-plan) exploration round
+
+These three were audited before the formal plan existed; applying their fixes was deferred until now.
+
+- **Button.swift**:
+  1. Removed the dead unreachable `default:` case in `typographyStyle` (the switch over `.large/.medium/.small` was already exhaustive).
+  2. **Fixed the press-squeeze animation**: previously alpha-only; restructured so `ButtonPressFeedbackStyle`
+     builds the full background+content layering itself (background as a `ZStack` layer with an animated
+     0→2pt horizontal inset, content as `configuration.label` with the alpha fade) — mirrors Kotlin's
+     `animatedPadding`-on-background + separate content alpha exactly, rather than dimming the whole button
+     uniformly.
+  3. **Added a `String`-based icon initializer** alongside the existing `AnyView`-based one, resolving
+     icons through the shared `Icon` component like Kotlin's `iconLeft`/`iconRight: String` params. Made
+     `iconLeft` required (no default) on this new overload specifically to avoid an `init` ambiguity — a
+     call like `Button(action: {})` would otherwise match both overloads since both have all-defaulted
+     params past `action`. Verified via a full `iosApp` build that no existing call site broke.
+  4. Default title on the **new** String-icon overload matches Kotlin's `"Button"`; the original
+     `AnyView`-based init's default (`""`) was left untouched (Flag) — changing it would alter output for
+     any existing Swift caller omitting `title`.
+- **IconButton.swift**: added the missing `IconSize.medium` (36pt box / 16pt icon, matching Kotlin exactly)
+  and the missing `IconShape` (`.circle`/`.square`) enum + param (default `.circle`, matching Kotlin).
+  Fixed `.small`'s box size from a fabricated `40` to the correct `28`. The previous `Radius.XL`
+  rounded-rect shape (which matched neither Kotlin variant) is replaced by a real `Circle()`/`Radius.S`
+  rounded-rect switch via a small hand-rolled `Shape` type eraser (`AnyShape` needs iOS 17+, deployment
+  target is 15). This does change default rendering for existing callers (true circle instead of a
+  large-radius rounded rect) — treated as a Fix rather than a Flag since the old shape was never a
+  deliberate design choice, just an unlabeled placeholder value matching neither source-of-truth variant.
+  Left the extra public `color` override alone (Flag, unchanged from earlier audit).
+- **Input.swift** / **ErrorView.swift**:
+  1. Wired the previously-dead `autofocus` prop via `@FocusState` on the plain `TextField` path and
+     `textField.becomeFirstResponder()` (dispatched to next run loop) on the `SecureInputField` path.
+  2. Fixed the floating-label vertical offset from a hardcoded `-8` to `-(size == .small ? 48 : 56) / 2`,
+     matching Kotlin's `-size.values.height / 2` (24pt small / 28pt large instead of always 8pt).
+  3. Fixed the `maxLength` trim race: the text binding's setter now trims atomically before publishing
+     (`let limited = limitText(newValue); self.text = limited`) instead of setting the raw value and
+     correcting it a render later via a separate `.onChange` — removed that now-redundant correction block.
+  4. Fixed `ErrorView`'s hardcoded `Colors.red03`/`Colors.black12` to use `theme.colors.error.primary`/
+     `theme.colors.text.hint` (added `@Environment(\.appTheme)`).
+  5. **Investigated, not changed**: the "bold styling swaps the whole typography token" finding turned out
+     to be a non-issue in practice — `TypographyStyle.bodyDefaultRegular` and `.actionSBold` share the same
+     14pt font size and 20pt line height (differing only in weight), and `Input`'s `TextField`/`SecureField`
+     never applies `.lineSpacing()` at all, so the "different token" is functionally just a weight toggle
+     either way. Kotlin's own local text style (14sp/24sp, independent of the shared `Typography` object)
+     does differ in line-height from Swift's shared tokens (20pt), but that value has no visible effect on
+     a single-line field without explicit line-spacing — not touched.
+  6. **Flagged, not changed**: the dual-control-type architecture for password visibility toggling
+     (`SecureInputField` UIViewRepresentable ↔ SwiftUI `TextField`, swapped based on `isPasswordHidden`)
+     carries a real risk of focus/cursor loss on toggle, vs. Kotlin's single `BasicTextField` with a
+     `VisualTransformation` swap. Fixing this properly means unifying both modes behind one control
+     (e.g. a single `UIViewRepresentable` toggling `isSecureTextEntry` in place) — a larger, riskier
+     rewrite than this pass's other fixes; documented rather than attempted.
+  7. **Flagged, not changed**: `icon`/`iconColor` (Kotlin) vs `rightIcon`/`rightIconColor` (Swift) naming
+     — renaming the existing Swift params would break current callers for a cosmetic parity gain only.
+- Verified via `MoMoUIKits` scheme build and full `iosApp` scheme build — both `** BUILD SUCCEEDED **`.
+
+### Batch 3 — Selection controls (CheckBox, Radio, Switch, Slider, Rating, Stepper, Steps, Chip)
+
+- **Cross-cutting press-feedback gap — fixed.** Kotlin's `activeOpacityClickable` (fades the tappable
+  subtree to a target opacity while pressed) had no shared Swift equivalent; a private
+  `ActiveOpacityButtonStyle` existed only inside `Uploader.swift` (unshared). Extracted it to
+  `ios/Extensions/ActiveOpacityButtonStyle.swift` as a parameterized `ButtonStyle(activeOpacity:)`
+  (default 0.2, matching Kotlin's default), updated `Uploader.swift`'s 3 call sites to use the shared
+  version with its existing `0.5` value preserved (not a Batch 3 component; left its opacity value
+  untouched — that's Batch 6's scope). Wired the shared style into: `Checkbox` (0.8, matching Kotlin's
+  explicit override), `Radio`, `Chip`, `Stepper`'s +/- buttons, `Rating`'s star buttons (replacing
+  `.buttonStyle(.plain)`), and `Steps`'s two clickable-column variants (`column`/`row`, replacing
+  `.onTapGesture` with a conditional `Button` wrap so non-clickable steps still render with zero press
+  interaction, matching Kotlin's `if (clickable) activeOpacityClickable(...)`).
+- **Checkbox**: was using SF Symbols (`"checkmark"`/`"minus"`, 12×12) instead of the shared `Icon`
+  component with the design-system icon set (`ic_checked`/`navigation_minus`, 20×20, matching Kotlin
+  exactly). **Fixed** — swapped to `Icon(source:size:color:)`, and converted the tap target from
+  `.onTapGesture` to a `Button` + the shared `ActiveOpacityButtonStyle`.
+- **Switch — most significant fix in this batch.** Four real bugs, all internal/no signature change:
+  1. **On-state color was pink instead of green** (`Colors.pink03` used for both track and inner dot when
+     `value == true`; Kotlin uses `green_03`/`green_09`). **Fixed.**
+  2. **No disabled-specific palette** — Swift blanket-dimmed the whole control via `.opacity(0.4)`; Kotlin
+     uses distinct muted tokens (`green_09`/`black_05`) with no opacity overlay at all. **Fixed** — removed
+     the opacity dim, added a `(disabled, value)`-keyed color switch matching Kotlin's 4-way logic exactly.
+  3. **Track size was 40×24 instead of Kotlin's 38×20**, and the thumb inset was a hardcoded `5` instead of
+     `Spacing.XS` (4). **Fixed** — both corrected to match.
+  4. **`title`/`accessibilityId` params were entirely missing.** Re-reading Kotlin's `Switch.kt` closely:
+     these are **not** rendered as a visible label at all — they only feed an automation/test identifier
+     string (`"toggle_${title}_$value"`). Ported faithfully as two new optional params (default `""`,
+     non-breaking) building the same identifier string via `.accessibilityIdentifier(...)`, without adding
+     any visual label (there isn't one in the source of truth either).
+  Also fixed: the outer 14pt thumb-circle color didn't toggle with `value` at all (hardcoded `Colors.black01`
+  always) — now correctly switches `black01`/`black03` per Kotlin's `circleBackgroundColor`.
+- **Radio, Slider, Rating, Steps**: faithful ports beyond the shared press-feedback gap above — no other
+  findings.
+- **Stepper**: Kotlin's `Stepper` is uncontrolled (seeded once from `defaultValue`); Swift's `MomoStepper`
+  is a controlled `Binding<Int>` component. **Flagged only** — a deliberate-looking SwiftUI idiom, but a
+  genuine contract difference for anyone porting usage code 1:1; not changed since it'd be a breaking
+  redesign of the current, presumably-intentional Swift API.
+- **Chip**: no `scaleSize(...)` applied to any dimension (height/horizontal padding/icon size/icon
+  spacing/corner radius), unlike every other component in this pass — Dynamic Type scaling silently didn't
+  apply to Chips. **Fixed** — wrapped all five dimensions in `scaleSize(...)` at the point of use (the
+  static `Dimensions` structs themselves stay unscaled, matching how Kotlin's raw dp constants are only
+  scaled at composition time). Converted `.onTapGesture` to `Button` + `ActiveOpacityButtonStyle` in the
+  same pass since Chip was also missing the press-feedback fix.
+- Verified via `MoMoUIKits` scheme build and full `iosApp` scheme build — both `** BUILD SUCCEEDED **`.
+
+### Batch 4 — Text-entry family (InputDropDown, InputMoney, InputOTP, InputPhoneNumber, InputSearch, InputTextArea)
+
+- **InputDropDown, InputMoney**: both had the same bug — `RenderRightIcon` used `if loading { ... } else if
+  !icon.isEmpty { ... }`, suppressing the icon whenever `loading == true`; Kotlin's `RenderRightIcon` is two
+  independent `if` blocks (both can render at once). **Fixed** in both files.
+- **InputMoney**: also had the exact "floating-label offset doesn't scale with size" bug just fixed in base
+  `Input.swift` — hardcoded `-8` instead of `-(size == .small ? 48 : 56) / 2`. **Fixed.** (Its extra
+  `.fill(theme.colors.background.surface)` on the input box, absent in Kotlin, was left alone — it's a
+  proper theme-token addition consistent with how base `Input.swift`'s own input box is styled, not a bug.)
+- **InputOTP**: Kotlin's free-form (`length == null`) branch references a stray top-level constant
+  (`MAX_LENGTH = 300` from `InputTextArea.kt`) instead of its own computed `maxLength` (`length ?: 10`) —
+  a genuine bug in the Kotlin source itself, meaning caret/spacer logic there never triggers in practice.
+  Swift's `InputOTP.swift` correctly uses its own 10-char `maxLength` and does **not** reproduce this bug.
+  **Flagged, not changed** — "fixing" Swift to match would mean deliberately re-introducing broken
+  behavior; this needs a Kotlin-side/product decision, not a mechanical Swift edit.
+- **InputPhoneNumber**: two dead public params, both **fixed**.
+  1. `required` was accepted by the initializer but never even stored as a property — completely discarded.
+     Added the missing `public var required: Bool` and wired it to append `" *"` to the placeholder when
+     set (mirroring how base `Input.swift` renders its own `required` marker; Kotlin's
+     `InputPhoneNumber.kt` has no `required` param at all, so there's no source-of-truth rendering to
+     match exactly — this follows the sibling component's convention instead).
+  2. `autofocus` was stored but never wired to anything. Fixed via `@FocusState`, same pattern as base
+     `Input.swift`.
+  Also investigated the flagged divider-color "mismatch" (Kotlin hardcodes `Colors.black_04`; Swift uses
+  `theme.colors.border.default`): confirmed `defaultTheme.border.default = Colors.black_04` in Kotlin's own
+  `Theme.kt`, so under the default theme these are pixel-identical — Swift's theme-token approach is
+  actually more correct (Kotlin's hardcoded literal is the one that silently breaks under a non-default
+  theme). No change needed; not a real divergence today.
+- **InputSearch**: Kotlin's `InputSearchProps` exposes `backgroundColor`, `clearCondition`, `onClearPress`,
+  and `leftPosition` with no Swift equivalents — a real but substantial API-surface gap. **Flagged, not
+  added** (larger scope than a mechanical fix). Did fix the narrower, clearly-broken piece: the clear
+  button previously fired **no callback at all** on tap (just `text = ""`); now also calls `onChangeText("")`
+  so clearing isn't a silent no-op, even without porting the dedicated `onClearPress`/`clearCondition` API.
+- **InputTextArea**: three findings, all **fixed**.
+  1. Missing clear ("x") button entirely (Kotlin shows one when focused + non-empty).
+  2. `icon`/`iconColor`/`loading`/`onRightIconPressed` were declared, stored, and never referenced anywhere
+     in `body` — completely dead public props.
+  3. Floating-label offset used `-height / 10` instead of `-height / 2` — the same offset-scaling bug
+     class as base `Input.swift`, but with an outright wrong divisor rather than a fixed constant.
+  Restructured the text-field row into an `HStack` (text field + clear button + loading/right-icon, mirroring
+  Kotlin's `Row` layout) to fit the new controls in.
+- Verified via `MoMoUIKits` scheme build and full `iosApp` scheme build — both `** BUILD SUCCEEDED **`.
+
+### Batch 5 — Scroll/list/pagination (Carousel, Pagination family, LazyColumnWithBouncing, CupertinoOverscroll, ScaleSizeScope, TabView)
+
+- **PaginationDot, PaginationNumber, PaginationWhiteDot, PaginationScroll**: faithful parity, no
+  significant findings (PaginationScroll's missing outer-layout-customization param was flagged but is
+  low value with no direct SwiftUI equivalent to Compose's `Modifier` — not added).
+- **ScaleSizeScope**: confirmed no port needed — the Kotlin source itself is `@Deprecated`, a no-op
+  passthrough; `FontScaleStore`/`scaleSize` in `ios/Typography/` already provide the real functionality.
+- **Carousel**: real perf bug, **fixed**. `HStack(ForEach(0..<virtualPageCount))` instantiated every
+  virtual page eagerly — with `loop=true`, `virtualPageCount = itemCount * 1000`, so thousands of slide
+  views were built up front (Compose's `HorizontalPager` is lazy). Fixed by windowing the rendered range
+  to `currentPage ± 3` and padding the HStack with `Color.clear` spacers sized to the skipped width, so
+  the existing offset math (`baseOffset = -currentPage * step + ...`) is completely unchanged — only the
+  render cost drops. Deferred, documented (not fixed): autoplay doesn't restart its interval when the user
+  stops scrolling (Kotlin's `LaunchedEffect(autoplayInterval, isUserScrolling)` does); Swift's extra
+  `enableSnap` param and symmetric-only `contentPadding` (vs Kotlin's asymmetric `PaddingValues`) are
+  flagged API differences, not touched.
+- **TabView**: press feedback was plain `.onTapGesture` in both `CardTabBar` and `TabItemView` — Kotlin
+  uses `activeOpacityClickable` on both. **Fixed** — wired the shared `ActiveOpacityButtonStyle` (same
+  fix applied to CheckBox/Radio/Chip/Stepper/Rating/Steps in Batch 3) into both tap targets. Deferred,
+  documented: `userScrollEnabled: false` still animates a real page transition in Kotlin (only the swipe
+  gesture is disabled) but instant-swaps content with no transition in Swift — flagged, not changed since
+  it'd alter current output for existing callers of that flag. Also deferred: Kotlin lazily composes only
+  visited tab pages; Swift's `ForEach` builds `AnyView` content for every tab up front — a real perf gap,
+  same class as Carousel's, but not fixed this pass given the remaining batch scope.
+- **LazyColumnWithBouncing, CupertinoOverscroll**: confirmed **zero Swift port exists** for either — the
+  custom Cupertino rubber-band overscroll container and the bespoke segmented-ring pull-to-refresh spinner
+  (with haptic-at-threshold behavior) have no iOS equivalent anywhere in `ios/`. Native `UIScrollView`/
+  `.refreshable` covers baseline bounce/refresh but not the distinctive spinner visual or haptics. This is
+  a real, substantial feature gap — flagged for a dedicated follow-up rather than attempted as part of this
+  batch (building a custom pull-to-refresh spinner + haptic sequencing is new-component-scale work, not a
+  parity fix).
+- Verified via `MoMoUIKits` scheme build and full `iosApp` scheme build — both `** BUILD SUCCEEDED **`.
+
+### Batch 6 — Overlay & misc interaction (PopupPromotion, Collapse, Uploader, SuggestAction, Swipe)
+
+- **Uploader**: its 3 `ActiveOpacityButtonStyle` call sites (deduplicated to the shared style in Batch 3)
+  hardcoded `activeOpacity: 0.5`, a value that was carried over from the old private duplicate without
+  ever being checked against source. Confirmed Kotlin's 3 call sites all omit `activeOpacity`, using the
+  modifier's own default (0.2). **Fixed** — dropped the explicit `0.5` at all 3 sites to use the shared
+  style's default.
+- **Collapse**: three findings, all **fixed**.
+  1. Header row used `.buttonStyle(.plain)` instead of the shared `ActiveOpacityButtonStyle` (Kotlin uses
+     `activeOpacityClickable`) — swapped.
+  2. Missing `accessibilityId` entirely (Kotlin exposes it plus a 6-identifier hierarchy: `|touch`, `|img`,
+     `|text`, `|description-text`, `|sub-title-text`, `|icon`). Added the param (additive) and wired the
+     two most functionally significant identifiers — the outer container (`automationId`) and the header
+     touch target (`|touch`). **Deferred, documented**: the remaining 4 sub-element identifiers
+     (`|img`/`|text`/`|description-text`/`|sub-title-text`/`|icon`) were not wired individually — lower
+     marginal value for meaningfully more call-site plumbing across the header's sub-views.
+  3. **Deferred, documented** (not fixed): expand/collapse uses `.transition(.move + .opacity)` (slide+fade)
+     instead of Kotlin's true `expandVertically`/`shrinkVertically` height animation — same 0.3s duration,
+     different visual feel. Fixing this properly needs `GeometryReader`-based height measurement; left as
+     a documented gap rather than attempted this pass.
+- **PopupPromotion**: three findings, all **fixed**.
+  1. Image content scale used `.aspectRatio(0.72, contentMode: .fit)` (letterboxes) instead of matching
+     Kotlin's `Modifier.fillMaxWidth().aspectRatio(0.72f)` + `ContentScale.FillBounds` (a fixed-ratio box
+     the image stretches to exactly fill, ignoring its own aspect ratio). Fixed by giving the image an
+     explicit `.frame(width:height:)` with no `.aspectRatio` modifier, which is SwiftUI's equivalent of
+     "stretch to fill" for a `.resizable()` image.
+  2. Close-button circle was hardcoded `Colors.black01`/`Colors.black17`; Kotlin uses
+     `theme.colors.background.surface` (border + icon) / `theme.colors.text.default` (fill). Fixed —
+     added `@Environment(\.appTheme)` and swapped all three color usages.
+  3. Kotlin explicitly disables system press-highlight (`indication = null`) on the close button; Swift had
+     no `.buttonStyle`, showing the default system highlight. Fixed with `.buttonStyle(.plain)`.
+  Deferred, documented: Kotlin renders nothing for an empty `source` string; Swift shows a full-width
+  `media_fail` icon — a real behavior difference, flagged rather than changed since it'd alter output for
+  existing empty-string callers.
+- **SuggestAction**: close icon used plain `.onTapGesture` (no press feedback at all); Kotlin uses
+  `activeOpacityClickable`. **Fixed** — wrapped in a `Button` + the shared `ActiveOpacityButtonStyle`.
+- **Swipe**: `SwipeCell.swift`'s `Swipe` view never read `@Environment(\.appTheme)` at all, hardcoding
+  `Colors.primary`/`Colors.error`/`Colors.card` for the left/right action defaults and content background;
+  Kotlin uses `theme.colors.primary`/`theme.colors.error.primary`/`theme.colors.background.surface`.
+  **Fixed** — added theme access and swapped all three. Deferred, documented (not changed): a
+  `minimumDistance: 8` drag-gesture threshold that Kotlin doesn't have (changes real-time drag feel for
+  existing callers — Flag); and a large chunk of unused public API (`SwipeCellModel.swift` entirely, plus
+  `SwipeCellModifier`/`.swipeCell(...)` in `SwipeCell.swift`) with zero callers anywhere in the repo and no
+  Kotlin counterpart — vestigial, unrelated to `Swipe.kt` parity. Left in place since removing public API
+  during a parity pass risks breaking unknown external consumers; flagged for a separate removal decision.
+- Verified via `MoMoUIKits` scheme build and full `iosApp` scheme build — both `** BUILD SUCCEEDED **`.
+
+### Batch 7 — Localize-dependent (PopupDisplay, PopupNotify, TrustBanner)
+
+Deferred from Tier 2 until the `Localize` subsystem landed (it now has, see Tier 2 above). All three
+previously read language via an ad-hoc mechanism instead of any shared abstraction.
+
+- **PopupDisplay.swift**: read `UserDefaults.standard.string(forKey: "language")` directly and looked up
+  an inline `["vi": "Mã lỗi: ", "en": "Error code: "]` dict — values that happen to be character-for-character
+  identical to `Localize`'s own `"errorCode"` dictionary entry. **Fixed** — added
+  `@EnvironmentObject private var localize: Localize` and replaced both with `localize.translate("errorCode")`.
+- **PopupNotify.swift**: same pattern (`UserDefaults` read + inline `en`/`vi` ternary for the same error-code
+  prefix). **Fixed** — identical replacement with `localize.translate("errorCode")`.
+- **TrustBanner.swift**: **not actually reading `UserDefaults` at all** — closer inspection found
+  `var language: String? = "vi"` hardcoded and never reassigned anywhere, meaning the banner's content/
+  learn-more text was **permanently stuck in Vietnamese regardless of device or app language** — a real,
+  live bug, not just an architecture smell. **Fixed** — removed the dead hardcoded property, added
+  `@EnvironmentObject private var localize: Localize`, and switched both dictionary lookups
+  (`content`/`subContent`, which are already `[String: String]` keyed by language code, matching
+  `Localize`'s own dictionary shape) to key off `localize.currentLanguage`.
+- Verified via `MoMoUIKits` scheme build and full `iosApp` scheme build — both `** BUILD SUCCEEDED **`.
+
+### Batch 8 — DateTimePicker subsystem (DateTimePicker, DateTimePickerTypes, DateTimePickerUtils, WheelPicker) — final batch
+
+- **DateTimePicker.swift, WheelPicker.swift**: both bypassed the theme system entirely — neither file read
+  `@Environment(\.appTheme)` at all, using static asset constants (`Colors.background`, `Colors.border`,
+  `Colors.text`) instead of `theme.colors.background.surface`/`theme.colors.border.default`/
+  `theme.colors.text.default`. Every other component in this pass correctly reads the theme; these two
+  were outliers. **Fixed** — added `@Environment(\.appTheme)` to `DateTimePicker`, `WheelPicker`, and the
+  private `WheelPickerItem`, and swapped all 5 hardcoded color usages across the two files. (Note:
+  `WheelPicker.swift`'s `Colors.blue10` background accent was confirmed intentional — matches Kotlin's own
+  hardcoded `Colors.blue_10`, not a theme bypass.)
+- **DateTimePickerUtils.swift**: `getMinutes`'s interval guard (`max(1, interval)`) already correctly
+  avoids a Kotlin-source infinite-loop bug (Kotlin has no such guard) — confirmed as a case where Swift is
+  already better, not a gap. **Investigated, not changed**: `getDaysInMonth`/`getMonths`/`getYears` return
+  a single-element fallback array when given an inverted min/max range, where Kotlin's `for` loop would
+  produce an empty list. Judged this an intentional, reasonable defensive choice rather than a bug to
+  "fix" — an empty wheel-picker column (no scrollable values at all) is arguably a worse failure mode than
+  a one-item fallback, so matching Kotlin's literal empty-list behavior here would make the edge case
+  worse, not better. Left as is (same reasoning pattern as the Skeleton shimmer-formula judgment call in
+  Batch 2).
+- **WheelPicker.swift**: **deferred, documented** (not fixed) — the wheel currently reports
+  `onChange(name, value)` continuously on every scroll-position update during an active drag, and never
+  animates a snap-to-center after release; Kotlin only fires `onChange` once scrolling settles
+  (`!isScrollInProgress`) and then animates the list to precisely center the selected row. Confirmed
+  real and would need restructuring the scroll-tracking to distinguish "dragging" from "settled" plus a
+  genuine snap-to-center animation — a materially bigger rewrite than this pass's other fixes, flagged for
+  a dedicated follow-up rather than attempted here.
+- **DateTimePickerTypes.swift**: clean 1:1 port, no findings. No hardcoded locale strings found in this
+  subsystem needing a `Localize` hookup — the wheel columns render zero-padded numbers only, no month/
+  day names.
+- Verified via `MoMoUIKits` scheme build and full `iosApp` scheme build — both `** BUILD SUCCEEDED **`.
+
+**Post-pass fix — BottomSheet: keyboard avoidance, scrim alpha correction, drag-performance refactor**:
+three issues reported by the user, all in `ios/Application/Navigation/Overplay/BottomSheet.swift`.
+1. **Keyboard avoidance (real gap)**: `BottomSheetView` is rendered via `NavigationContainer`'s own
+   `.overlay { OverplayHost(...) }`, structurally outside any pushed `StackScreen`, so it never inherited
+   `StackScreen`'s existing keyboard-avoidance (`ios/Application/StackScreen.swift:102,195-201`). Fixed by
+   adding the same `keyboardWillChangeFrameNotification`-based tracking directly to `BottomSheetView`, and
+   replacing (not adding to) the bottom-inset filler with the keyboard height while it's up.
+2. **Scrim alpha — my own research was wrong at first, caught by the user.** Initially reported "BottomSheet
+   (peak 0.3) intentionally differs from Modal (peak 0.6), not a bug" — but Kotlin's `BottomSheet.kt:67-69`
+   is **additive** (`backgroundAlpha + dynamicAlpha`, each terming out at 0.3), so its true steady-state peak
+   is 0.3+0.3=**0.6**, exactly matching `ModalScreen.kt`. The user directly re-checked the Kotlin source and
+   caught this before I did. Swift's `BottomSheet.swift` only implemented the single `dynamicAlpha` term
+   (peaking at 0.3) — genuinely under-dimmed by half. **Fixed**: split into two terms
+   (`backgroundAlpha` state, only touched by open()/close(); `dynamicAlpha` computed property tracking
+   drag position) matching Kotlin's model exactly — scrim now peaks at 0.6 at rest and only fades to a 0.3
+   floor while dragging (never fully transparent until the sheet has completely left the screen). Verified
+   by pixel-sampling a screenshot: `(102,102,102)` = black-at-60%-opacity over white, exact match.
+3. **Drag jank**: the raw per-touch update mechanism already matched Kotlin's unanimated `Animatable.snapTo`
+   1:1 — not an animation-vs-no-animation gap. Root cause: two independent `@State` writes per touch-move
+   (`sheetOffset`, `scrimAlpha`) each forced the whole `body` (including `content()` and a `GeometryReader`)
+   to reconstruct at touch-move frequency. **Fixed** by refactoring to `@GestureState` for the live drag
+   value (isolated from `content()`'s reconstruction), combined with `sheetOffset` only for the settled
+   position — matching an idiom already established elsewhere in this codebase
+   (`ios/PopupView/PopupView.swift`'s `@GestureState dragState` + `lastDragPosition` capture-before-reset
+   pattern). **Honest limitation**: smoothness itself isn't screenshot-verifiable — confirmed clean compile
+   and correct rest/open/closed positions, but true "no more jank" confirmation needs the user's own
+   hands-on feel on a simulator/device, which I said explicitly rather than overclaim.
+Verified via `MoMoUIKits` + full `iosApp` scheme builds, plus a temporary root-view-swap reproduction
+(`BottomSheetView` wrapping an autofocused `Input`) — screenshotted keyboard-up state showing the sheet
+correctly staying above the keyboard. Reverted the temporary harness cleanly (confirmed via `git diff`,
+including restoring an accidental trailing-whitespace diff introduced by the revert itself).
+
+**Follow-up — drag still jerked twice before settling.** The `@GestureState` refactor above didn't fully
+fix the jank: the user reported a specific pattern (touch, drag, hold → 2 visible jerks → settles at the
+correct finger position). No touch-injection tooling is available in this environment (no `idb`, no
+XCUITest harness), so this couldn't be reproduced/observed directly — diagnosed by code inspection only.
+Found two plausible races that both fit the exact symptom shape:
+1. `open()` animates `sheetOffset` 0-target over 350ms; if a drag starts before that settles, the live
+   `dragTranslation` value gets added on top of a `sheetOffset` that's *also* mid-animation — two
+   competing sources of motion for the same frame.
+2. The keyboard-driven `effectiveBottomInset` swap (issue 1 fix) animates the bottom filler's height,
+   which changes the sheet's total height; since the sheet is bottom-anchored, that shifts its *top* edge
+   — exactly where the drag handle sits — via layout, independent of the offset-driven motion from the
+   drag itself.
+**Fixed** both: added `.onChanged` to the drag gesture that snaps `sheetOffset` to `0` (no animation) the
+instant a drag begins, settling any in-flight open/keyboard-resize animation immediately rather than
+having the live drag fight a moving target. Also (at the time) added `.onChange(of: geo.size.height)` to
+the `sheetHeight`-measuring `GeometryReader`, reasoning that its `.onAppear`-only measurement would go
+stale after the keyboard-driven resize changed the sheet's actual height.
+
+**Follow-up #2 — that `.onChange` addition was itself a regression.** User reported a *continuous* up/down
+jitter for the whole duration of a drag (not just a settle-in jerk at the start) — a materially different,
+more severe symptom. Prime suspect: `sheet` is a computed property re-evaluated on every touch-move (since
+`dragTranslation` changing forces `body` to re-render), which reconstructs the `GeometryReader` each time;
+the newly-added `.onChange(of: geo.size.height)` closure writing to `sheetHeight` on every such
+reconstruction is a plausible feedback-loop shape (state write → re-render → reconstruct → possible
+re-fire → state write again) that fits a *continuous* oscillation far better than the one-time settle-in
+case it was meant to fix. No `.animation()` (scoped or unscoped) exists anywhere in this file or
+`NavigationContainer.swift`, ruling out the other classic cause of "gesture updates chase an animated
+target." **Reverted** the `.onChange(of: geo.size.height)` addition back to `.onAppear`-only (accepting
+the minor, lower-severity `sheetHeight`-staleness-after-keyboard-resize issue rather than risk
+reintroducing a continuous jitter); kept the `.onChanged` drag-start snap fix, which is much lower-risk
+(fires once per drag, a no-op on every subsequent call). Verified clean compile on both schemes only —
+**still could not verify at runtime** whether the continuous jitter is actually resolved, since no
+touch-injection tooling (no `idb`, no XCUITest harness) is available in this environment. Told the user
+plainly rather than claim a fix that can't be felt from here, and asked for confirmation plus, if it
+persists, more precise repro details (does `content()`'s makeup matter — e.g. an `Input` field present or
+not — and does it happen from the very first touch-move or only after some movement).
+
+**Follow-up #3 — confirmed still jittery even with plain-text content**, ruling out anything specific to
+`Input`'s own internal measurement. Two more attempts, one of which caused a worse regression:
+- **Tried and reverted**: `.drawingGroup()` on `sheet`, reasoning that `RoundedCorner`'s clip path (built
+  via a `UIBezierPath` bridge call) plus the rest of `sheet`'s layout was being rebuilt on every touch-move
+  (since `sheet` is a computed property re-evaluated whenever `dragTranslation` changes) regardless of
+  `content()`'s complexity — consistent with the plain-text repro. **This introduced a worse, more visible
+  regression**: the header's close icon rendered as a blank gray box instead of the "X" glyph, screenshotted
+  and confirmed before reverting. Likely cause: the icon is loaded via an async image library
+  (SDWebImageSwiftUI-backed `ImageView`) that doesn't composite correctly once flattened into a
+  `drawingGroup`'s rasterized Metal-backed layer. Reverted immediately; re-screenshotted to confirm the
+  icon renders correctly again post-revert.
+- **Applied, not yet confirmed**: changed `DragGesture()` to `DragGesture(coordinateSpace: .global)`.
+  Reasoning: the gesture is attached to the drag handle, which is itself repositioned every frame by this
+  same gesture's own output (`sheet.offset(y: effectiveOffset)`, computed from `dragTranslation`) — the
+  default `.local` coordinate space ties gesture tracking to that same (continuously moving) view, a
+  known category of SwiftUI feedback-jitter source. `.global` anchors tracking to the window instead,
+  decoupling it from the view's own motion. Verified clean compile + no visual regression via screenshot
+  (icon renders fine, layout unchanged) — **have not been able to verify whether the continuous jitter
+  itself is resolved**, same tooling limitation as before (no touch-injection available in this
+  environment). Asked the user to retest.
+
+**Confirmed fixed** — user retested and reported the jitter is gone. Root cause: `DragGesture()`'s default
+`.local` coordinate space tied gesture tracking to the drag handle's own view, which was itself being
+repositioned every frame by that same gesture's output — a feedback loop between "where the view is now"
+and "where the gesture thinks the touch is relative to that view." Switching to
+`.global` (anchoring tracking to the window instead of the moving view) resolved it. This is the actual
+final state of the drag-jank issue from this whole BottomSheet follow-up thread; the `@GestureState`
+refactor, the drag-start `sheetOffset` snap, and this coordinate-space fix together are what shipped —
+`.onChange(of: geo.size.height)` and `.drawingGroup()` were both tried and reverted along the way (see
+above) as they either regressed or didn't address the root cause.
+
+## Pass summary
+
+All 8 Tier-3 batches (Batches 1–8) plus Tiers 0–2 (tokens, navigation core, Localize/ScreenTracker
+subsystems) and the original Button/IconButton/Input fixes are complete. Every fix in this log was
+verified via a real `xcodebuild` compile of both the `MoMoUIKits` library scheme and the full `iosApp`
+demo scheme (catching any public-signature breakage against real `Demo/*.swift` call sites), plus targeted
+value-diffs for the token and Localize dictionary ports. Deferred items (documented above, not silently
+dropped) worth a dedicated follow-up pass: Text's rich-text/inline-content API, Tooltip's popup-based
+positioning architecture, Input's dual-control-type password-toggle, TabView/Carousel's remaining
+lazy-render gaps, LazyColumnWithBouncing/CupertinoOverscroll (zero port), Collapse's true height-animation,
+WheelPicker's settle-only snap behavior, and Navigation.kt's per-screen `setOptions()` runtime API.
+
+**Post-pass addendum — Localize demo screen**: added `sample/iosApp/iosApp/Demo/LocalizeDemo.swift`,
+a SwiftUI port of the Compose sample's `sample/shared/.../screens/LocalizeUsage.kt` demo (same section
+structure: language switch, `translate(key)` on kit defaults, missing-key fallback, `{placeholder}`
+substitution, `translateData(vi:en:)`, `translateData(map:)`, `addTranslations` with app-specific keys,
+and a realistic error-code + Cancel/Confirm example). Registered in `Home.swift`'s `ScreenUsages` list.
+Verified at runtime (not just compiled) by temporarily swapping `NativeContentView`'s root to the new
+screen, screenshotting via the simulator, and reverting — confirmed via `git diff` that the revert left
+zero trace. Found and fixed one cosmetic layout bug during that check (a long key name like
+`voucherRemindHour` overlapped its value in a fixed-width `HStack` row; switched `TranslationRow` to a
+`VStack` layout).
+
+**Post-pass fix — BottomTab pushed up above the bottom safe-area inset**: reported by the user
+("bottom tab đang bị đẩy lên cao hơn chiều cao của inset bottom"). Root cause traced to the
+`Navigation.kt` gap already documented in Tier 1: Kotlin's `StackScreen.kt` skips its own bottom
+navigation-bar padding when hosting a `BottomTab` (`MainContent(... isBottomTab = navigation.isBottomTabRoot)`,
+`.padding(bottom = if (options.footerComponent != null || isBottomTab) 0.dp else navigationBar)`),
+where `isBottomTabRoot` is set by `BottomTab.kt` itself calling `navigation.markAsBottomTabRoot()` on
+mount. Swift's `StackScreen.swift` had no equivalent — its `contentBottomInset` only checked
+`footer == nil`, so whenever `BottomTab` was hosted inside a pushed screen (as the "Bottom Tab" demo
+entry is), the outer `StackScreen` added up to 21pt of extra bottom padding on top of `BottomTab`'s own
+internal safe-area handling, squeezing it into less than the full screen height and leaving an
+unreachable gap below the tab bar (`.ignoresSafeArea` can't undo a literal `.padding()` imposed by an
+ancestor). **Fixed** without porting the full `Navigation` class: added a `PreferenceKey`
+(`IsBottomTabRootKey` in `Components.swift`) that `BottomTab` sets via `.preference(...)` on appear and
+`StackScreen` reads via `.onPreferenceChange(...)`, mirroring Kotlin's self-registering
+`markAsBottomTabRoot()` mechanism (the closest existing precedent in this file is the
+`HeaderRightWidthKey` preference already used for header-right measurement) rather than requiring every
+call site to manually flag it. Verified by temporarily reproducing the exact push path from `Home.swift`
+(`navigator.push({ BottomTabDemo() }, options: NavigationOptions(title: "Bottom Tab", headerType: .none,
+scrollable: false))`) and screenshotting — tab bar now sits flush with the true bottom edge. Reverted the
+temporary root-view change cleanly (confirmed via `git diff`).
+
+**Post-pass fix — BottomSheet's bottom inset showed the backdrop color instead of the sheet's own
+background**: reported by the user. `BottomSheetView.sheet` already had an explicit
+`backgroundColor.frame(height: bottomInset)` filler row at the bottom of its `VStack` (matching the
+sheet's own `theme.colors.background.surface`/`.default`), but nothing in the view made it reach the true
+screen edge — so SwiftUI auto-reserved the real bottom safe-area padding *on top of* that filler, leaving
+a gap below it where the dimmed scrim (rendered full-screen behind the sheet) showed through instead of
+the sheet's background. Not a Kotlin parity gap — `BottomSheet.kt` has no equivalent inset handling at
+all, confirming this filler was bespoke (and incomplete) iOS-only code.
+**First attempt (did not work, verified by pixel-sampling the screenshot):** added
+`.ignoresSafeArea(edges: .bottom)` to the nested `sheet` view specifically. Compiled fine and looked
+plausible, but sampling actual pixel colors at the bottom of a screenshot showed a ~33pt strip of
+`(178,178,178)` — exactly black-at-30%-opacity over white, i.e. the scrim alpha value — proving the gap
+was untouched. `ignoresSafeArea` on a fixed-intrinsic-height child evidently doesn't reposition/resize it
+the way it does for a flexible one.
+**Actual fix:** moved `.ignoresSafeArea()` to wrap the *entire* outer `ZStack` in `body` (both scrim and
+sheet together) instead of applying it separately per child, and removed the now-redundant modifier on
+`sheet`. Re-verified the same way — pixel-sampled the new screenshot bottom strip: white
+`(255,255,255)` all the way to the true edge, with only the OS-drawn home-indicator pill
+(`(93,93,93)`→`(125,125,125)`, normal system chrome) visible on top, not a uniform scrim-gray band.
+Reverted the temporary root-view-swap reproduction cleanly (confirmed via `git diff`) both times.
+
+**Post-pass correction — floating-label offset fix from earlier in this pass was actually wrong**:
+reported by the user ("floatingValue của các Input, bị lệch so với trước khi sửa"). Screenshotting
+`InputDemo` showed the "Momo" floating label floating so high it overlapped completely unrelated content
+(the "Secure Text Entry" section header above the input), confirming a real regression from the
+`-(size == .small ? 48 : 56) / 2` change applied to `Input.swift`/`InputMoney.swift`/`InputTextArea.swift`
+earlier in this pass (Batches 3/4 area).
+**Root cause of the original mistake**: misread which layout anchor Kotlin's `offsetY = -size.values.height / 2`
+is relative to. Kotlin's `BasicTextField` `decorationBox` centers its children (the `FloatingLabel` and the
+input `Box`) vertically by default within the box-height-tall `BasicTextField` — so `-boxHeight/2` there
+nets out to centering the label exactly on the box's top border (spans `-labelHeight/2 … +labelHeight/2`
+around y=0). Swift's `ZStack(alignment: .topLeading)` anchors from the top instead, so applying the same
+`-boxHeight/2` formula there is a completely different, much larger offset — hence the label flying
+several times too far up. The original hardcoded `-8` (which I "fixed" away) was a reasonable
+approximation of `-labelHeight/2`, not related to box height at all — reverting to a hardcoded constant
+would have worked, but instead **measured the label's actual rendered height via a `GeometryReader`
+background** (`floatingLabelHeight` state) and offset by `-floatingLabelHeight / 2` in all three files, so
+it's correct regardless of font size/Dynamic Type scaling rather than relying on a magic constant tuned
+for one specific rendered size. Verified by reproducing `InputDemo` via a temporary root-view swap,
+screenshotting before/after, and confirming the label now sits correctly straddling each box's top border
+with no overlap into unrelated content. Reverted the temporary change cleanly (confirmed via `git diff`).
+
+**End-of-pass `pod lib lint` note**: `pod lib lint ios/native-kits.podspec --allow-warnings --quick` fails
+with `ERROR | name: The name of the spec should match the name of the file` (spec name `MoMoUIKits` vs
+filename `native-kits.podspec`). Confirmed pre-existing via `git diff` — neither podspec file was touched
+anywhere in this pass, so this isn't a regression, just a packaging/naming convention issue outside a
+Kotlin-vs-Swift parity pass's scope. Flagged here rather than silently ignored.