@vvedantb/native-ui 0.9.0 → 0.11.0

package/README.md

@@ -65,8 +65,9 @@ The root entry exports everything. It still imports `BottomSheetContainer` and `
 | `@vvedantb/native-ui/tab-bar` | `FloatingTabBar`, `FloatingTabBarProps`, `FLOATING_INSET`, `FLOATING_TAB_BAR_HEIGHT`, `FLOATING_TAB_BAR_HEIGHT_LARGE`, `tabBarReserve` | `expo-blur`, `expo-haptics` (loaders) |
 | `@vvedantb/native-ui/brand` | `AppMark`, `AppWordmark`, `GoogleMark` (from 0.3.15), `APP_ICONS`, `IconVibot` and the other `Icon*`, the SVG helpers (`APP_MARKS`, `appMarkSvg`, `appTileSvg` and the rest), `FAMILY_APPS`, `familyApp`, `V_PRO_APP_BENEFITS` | none |
 | `@vvedantb/native-ui/button` | `Button`, `ButtonProps`, `ButtonShape` (0.6.0), `ButtonSize`, `ButtonVariant` | none |
-| `@vvedantb/native-ui/primitives` | `Button`, `Input`, `SearchInput`, `Textarea`, `Label`, `Select`, `Switch`, `LabeledSwitchRow`, `Checkbox`, `Card` and its parts, `Badge`, `StatusDot`, `Avatar`, `Separator`, `Progress`, `Spinner`, `Skeleton`, `EmptyState`, `ListRow`, `Chip`, `HeaderIconButton`, `ThemeToggle` (from 0.3.16), `Tabs`, `PillTabs`, `Dialog`, `AlertDialog`, `ConfirmDialog`, `Sheet`, `toast`, `Toaster`. From 0.5.0: `Text` and `TextClassContext` (only here, not on the root), `ColorSwatches`, `StatGrid`, `SectionLabel`, `SheetRow`, `PageIndicator`, `IconButton`, `CaptureButton`, and the `ListRowProps` and `CardProps` types. From 0.6.0: the `ButtonShape` type. Unreleased: `DropdownMenu` and its parts, `BulkActionBar` | `expo-blur`, `expo-haptics` (loaders) |
+| `@vvedantb/native-ui/primitives` | `Button`, `Input`, `SearchInput`, `PasswordInput` (0.11.0), `Textarea`, `Label`, `Select`, `Switch`, `LabeledSwitchRow`, `Checkbox`, `Card` and its parts, `Badge`, `StatusDot`, `Avatar`, `Separator`, `Progress`, `Spinner`, `Skeleton`, `EmptyState`, `ListRow`, `Chip`, `HeaderIconButton`, `ThemeToggle` (from 0.3.16), `Tabs`, `PillTabs`, `Dialog`, `AlertDialog`, `ConfirmDialog`, `Sheet`, `toast`, `Toaster`. From 0.5.0: `Text` and `TextClassContext` (only here, not on the root), `ColorSwatches`, `StatGrid`, `SectionLabel`, `SheetRow`, `PageIndicator`, `IconButton`, `CaptureButton`, and the `ListRowProps` and `CardProps` types. From 0.6.0: the `ButtonShape` type. Unreleased: `DropdownMenu` and its parts, `BulkActionBar` | `expo-blur`, `expo-haptics` (loaders) |
 | `@vvedantb/native-ui/search-input` | `SearchInput`, `SearchInputProps` | none |
+| `@vvedantb/native-ui/password-input` | `PasswordInput`, `PasswordInputProps` (from 0.11.0) | none |
 | `@vvedantb/native-ui/page-title` | `PageTitle`, `PageHeader`, `PageTitleProps`, `PageHeaderProps` (from 0.3.13), `StackPageHeader`, `StackPageHeaderProps` (from 0.5.0; it brings the Tabler package for its chevron) | none |
 | `@vvedantb/native-ui/toast` | `toast`, `Toaster`, `ToastOptions`, `ToastVariant` | none (from 0.3.12) |
 | `@vvedantb/native-ui/theme` | `NativeUiProvider`, `useNativeUi`, `useLargerText`, `useAccentColor`, `DEFAULT_ACCENT`, `tokens`, `palette`, `withAlpha`, `configureTheme` (with the `ThemeConfig`, `ThemeColors` and `ThemePalette` types), `fontClass`, `cn`, `Colors` and the colour constants | none |
@@ -80,7 +81,7 @@ The root entry exports everything. It still imports `BottomSheetContainer` and `
 | `@vvedantb/native-ui/date-time` | `DateTimeField`, `DateTimeFieldProps` (0.5.0) | `@react-native-community/datetimepicker`, `dayjs` (import) |
 | `@vvedantb/native-ui/ai` | The AI chat parts (from 0.4.0): `Conversation`, `Message`, `Reasoning`, `AgentTrace`, `ChainOfThought`, `ActivityStep`, `PromptInput`, `Suggestions`, `Sources`, `FileChip`, `Attachments`, `CodeBlock`, `ResponseText`, `Shimmer`, `Collapsible`, `useStreamingDisclosure` and their parts. See [AI chat](#ai-chat-040). Not on the root entry. | none |
 | `@vvedantb/native-ui/ai-gallery` | `AiChatGallery`, `AiChatSamples` (from 0.4.0) | none |
-| `@vvedantb/native-ui/auth` | From 0.7.0: `AuthProviders`, `SignInScreen`, `SignUpScreen`, `GoogleSignInButton`, `useGoogleSignIn`, `AuthScreen`, `OrDivider`, `FieldError`, `authErrorMessage` and their props types. See [Auth](#auth-070). Not on the root entry. | `@clerk/clerk-expo`, `convex`, `expo-auth-session`, `expo-web-browser`, `expo-router` (import) |
+| `@vvedantb/native-ui/auth` | From 0.7.0: `AuthProviders`, `SignInScreen`, `SignUpScreen`, `GoogleSignInButton`, `useGoogleSignIn`, `AuthScreen`, `OrDivider`, `FieldError`, `authErrorMessage`, `SecondFactorScreen`, `useSecondFactor`, `submitTotpSecondFactor`, `submitSecondFactor`, `prepareSecondFactorIfNeeded`, `prepareFirstFactorIfNeeded`, `submitFirstFactor`, `pickFirstFactorStrategy`, `TOTP_MESSAGES` and their props types. See [Auth](#auth-070). Not on the root entry. | `@clerk/clerk-expo`, `convex`, `expo-auth-session`, `expo-web-browser`, `expo-router` (import) |
 | `@vvedantb/native-ui/expo-web-root` | From 0.7.0: `ExpoWebRoot`, `ExpoWebRootProps`, `ExpoWebRootViewport`, `EXPO_WEB_VIEWPORT`, `expoWebBackgroundCss`. Not on the root entry. | `expo-router` (import of `expo-router/html`) |
 | `@vvedantb/native-ui/tailwind-preset` | From 0.7.0, CommonJS for `tailwind.config.js`: `nativeUiPreset`, `nativeUiContent`, `cssVar`, `hslVar`, `rgbAlpha`, `cssVariables`, `schemeColors` and a default preset. See [Expo / NativeWind](#expo--nativewind). | `nativewind` (`require`, when installed) |
 
@@ -211,10 +212,53 @@ export default function SignUp() {
 - `title`, `subtitle`, `showGoogle`, `googleLabel`, `errorDisplay` (`"toast"`, default, needs a `<Toaster />`; or `"inline"`), `testIDPrefix` (default the mode: `sign-in-email`, `sign-in-password`, `sign-in-submit`, `sign-in-google` and the rest).
 - `header` and `footer` slots for app chrome, such as a brand header or credit. The screen itself is neutral: background fill, title, subtitle, fields.
 - Messages are generic ("Sign in failed", "Invalid email or password", "Could not continue with Google") and never name the auth provider. `authErrorMessage(error, fallback)` shows an API error's own text only when it does not name it.
+- Two-step verification: when sign-in returns `needs_second_factor` or `needs_client_trust`, the screen shows `SecondFactorScreen` with the account's default method: authenticator app (`totp`), then `email_code`, `phone_code`, `backup_code`. Email and text codes are sent first. A "Use a backup code" link (and a link back) switches method. A valid code runs the same success path. Back returns to the email and password form.
+- `needs_first_factor`: when the account has an `email_code` or `phone_code` first factor (with its `emailAddressId` or `phoneNumberId`), the screen sends the code (`prepareFirstFactor`), shows `SecondFactorScreen`, and checks it with `attemptFirstFactor`. The result then runs the usual path: session, new password, or second factor. Email is preferred; a link switches to phone, and back. Back returns to the email and password form.
+- `needs_new_password` shows a new-password step (`signIn.resetPassword`), then starts the session.
+- `onIncomplete(signIn)`: optional. Called only for statuses the built-in UI cannot finish: `needs_identifier`, `needs_first_factor` without an `email_code` or `phone_code` first factor, unknown statuses, and `needs_second_factor` or `needs_client_trust` when no supported strategy (totp, backup code, phone code, email code) exists. The built-in screen always runs `needs_second_factor`, `needs_client_trust` and `needs_new_password`, and runs `needs_first_factor` when an email or phone code exists. When `onIncomplete` is called, the screen shows no message. Without it, those statuses show "This account needs another step to sign in. Finish it on the web." and log the status and strategy ids with `console.warn`. Ignored in `sign-up`.
+- Keyboard: `AuthScreen` (and so every screen here) pads for the soft keyboard on iOS and Android, including edge-to-edge Android, and scrolls the focused field and the button above it.
 - No forgot-password step. An app that needs one keeps its own screen.
 
 `GoogleSignInButton` (`scheme`, `redirectPath`, `afterAuthHref`, `replaceOptions`, `onSuccess`, `onError`, `label` and the `Button` props), `AuthScreen`, `OrDivider` and `FieldError` build custom screens. The module calls `WebBrowser.maybeCompleteAuthSession()` once when it loads, so the app no longer needs its own call.
 
+### Second factor (0.10.0)
+
+`SecondFactorScreen` is a one-time code step with no Clerk import. The caller owns the check.
+
+| Prop | Default | Use |
+| --- | --- | --- |
+| `title` | required | Screen title, through `AuthScreen` |
+| `description` | none | Text under the title |
+| `codeLength` | `6` | Digits in the code |
+| `onSubmit(code)` | required | Called with the full code |
+| `error` | none | Inline error under the field |
+| `loading` | `false` | Verify spinner; blocks a second submit |
+| `onBack` | none | Shows a ghost Back button |
+| `backLabel` | `"Back"` | Back button text |
+| `header` | none | Above the title |
+| `testIDPrefix` | `"second-factor"` | `-screen`, `-code`, `-error`, `-verify`, `-back` |
+| `footer` | none | Below the buttons, such as a "Use a backup code" switch |
+| `digitsOnly` | `true` | `false` takes any characters (backup codes) |
+| `placeholder` | `"Code"` | Field placeholder when `digitsOnly` is `false` |
+
+For Clerk, `useSecondFactor({ strategy? })` (default `"totp"`) returns `{ submit(code), prepare(strategy?, factor?), strategy, setStrategy, loading, error, clearError }`. `submit` calls `signIn.attemptSecondFactor({ strategy, code })`, then `setActive({ session: createdSessionId })`. `submit` never throws: it resolves `{ ok: true }` or `{ ok: false, error }`.
+
+```tsx
+const { submit, loading, error } = useSecondFactor();
+
+<SecondFactorScreen
+  title="Two-step verification"
+  description="Enter the code from your authenticator app."
+  onSubmit={async (code) => {
+    if ((await submit(code)).ok) router.replace("/");
+  }}
+  error={error}
+  loading={loading}
+/>
+```
+
+`submitTotpSecondFactor({ signIn, setActive, code })` is the TOTP call without the hook; `submitSecondFactor({ signIn, setActive, code, strategy })` takes any of `totp`, `backup_code`, `phone_code`, `email_code`. `prepareSecondFactorIfNeeded({ signIn, strategy, factor? })` sends the `email_code` or `phone_code` first (no call for the others). `pickSecondFactorStrategy(factors)` gives the default. `TOTP_MESSAGES` holds `invalidCode`, `invalidCodeGeneric`, `sendFailed`, `needsAnotherStep` and `notReady`. An API error shows its own text unless it names the provider.
+
 ## Theme
 
 Wrap the tree (inside your colour-scheme provider):
@@ -267,7 +311,7 @@ Limits: a call after the first render does not redraw mounted components. Only t
 
 | Area | Exports |
 | --- | --- |
-| Actions and fields | `Button` (`default`/`primary`, `secondary`, `outline`, `destructive`, `ghost`, `link`, `tinted`; `sm`/`small`, `default`/`medium`, `lg`/`large`, `icon`; `shape` `pill`/`rounded` from 0.6.0), `IconButton` (0.5.0), `CaptureButton` (0.5.0), `Input`, `SearchInput` (0.3.9), `Textarea`, `Label`, `Select`, `Switch`, `Checkbox`, `LabeledSwitchRow`, `ColorSwatches` (0.5.0), `DateTimeField` (date-only, empty and clearable from 0.5.0) |
+| Actions and fields | `Button` (`default`/`primary`, `secondary`, `outline`, `destructive`, `ghost`, `link`, `tinted`; `sm`/`small`, `default`/`medium`, `lg`/`large`, `icon`; `shape` `pill`/`rounded` from 0.6.0), `IconButton` (0.5.0), `CaptureButton` (0.5.0), `Input`, `SearchInput` (0.3.9), `PasswordInput` (0.11.0), `Textarea`, `Label`, `Select`, `Switch`, `Checkbox`, `LabeledSwitchRow`, `ColorSwatches` (0.5.0), `DateTimeField` (date-only, empty and clearable from 0.5.0) |
 | Display | `Card` (+ `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`; `onPress` from 0.5.0), `Badge`, `StatusDot` (`info` from 0.5.0), `Avatar` (+ `AvatarImage`, `AvatarFallback`, `initials()`), `Separator`, `Progress`, `Spinner`, `CenteredSpinner`, `Skeleton`, `EmptyState` (+ `EmptyState.Root` and parts), `ListRow` (`leading`, `titleEnd`, `control`, `onLongPress` from 0.5.0), `StatGrid` (0.5.0), `SectionLabel` (0.5.0), `Chip`, `Text` (0.5.0, `/primitives` only) |
 | Navigation | `Tabs` (+ `TabsList`, `TabsTrigger`, `TabsContent`), `PillTabs`, `PageIndicator` (0.5.0), `FloatingTabBar`, `FloatingFAB`, `HeaderIconButton`, `ThemeToggle` (0.3.16), `StackPageHeader` (0.5.0) |
 | Overlays | `Dialog`, `AlertDialog`, `ConfirmDialog`, `Sheet` (RN `Modal`, each with the web part names), `SheetRow` (0.5.0), `BottomSheetContainer` (`@gorhom/bottom-sheet`), `DropdownMenu` (Unreleased; see below) |
@@ -318,6 +362,12 @@ const [query, setQuery] = useState("");
 <SearchInput value={query} onChange={setQuery} label="Search apps" />
 ```
 
+From 0.11.0 `PasswordInput` is `Input` with a show/hide eye button at the end (`IconEye` and `IconEyeOff`). The password is hidden at first. The button is labelled "Show password" or "Hide password" to match, has the test ID `${testID}-toggle` (`password-input-toggle` without a `testID`), is painted at 24 and reaches 44 with its hit slop. It flips `secureTextEntry` on the same mounted field, so focus and the cursor stay. The component owns `secureTextEntry`, so that prop is not accepted. Other `Input` props and `ref` pass through; the button is hidden when `editable={false}`. The `SignInScreen` password, new-password and confirm-password fields use it. Inside a `ScrollView`, set `keyboardShouldPersistTaps="handled"`.
+
+```tsx
+<PasswordInput value={password} onChangeText={setPassword} placeholder="Password" autoComplete="password" textContentType="password" />
+```
+
 From 0.3.13 `PageTitle` is the web page title, the type on the web `Breadcrumb` (`text-xl font-semibold leading-tight tracking-tight`): Instrument Sans 600 at 20 / 25 with -0.5 letter spacing (-0.025em), in the foreground colour. It sets the semibold face class and `fontWeight: "600"` together, so it is not drawn Regular on Android or Expo web. It is a header for VoiceOver and TalkBack, one line (pass `numberOfLines={0}` to wrap), and scales with the system font size. `PageHeader` is a tab-root title row: `PageTitle` at the start and an optional `action` at the end, which keeps its width while a long title is cut off. It has the `ScreenContainer` side padding (`px-4`) and a row at least 56 high, so tabs with and without an action put their titles at the same height. It pads the top by the safe-area inset; pass `safeTop={false}` under a native header or inside a view that already pads it. Give a `Button` in `action` `fullWidth={false}`.
 
 ```tsx
@@ -512,7 +562,7 @@ The bar is the glass `FloatingSurface` at radius 16 with `px-2.5 py-2`. It holds
 
 ## Phones and accessibility
 
-The components keep the web sizes on screen and reach a 44 pt touch target with `hitSlop` (`touchSlop` in `src/controlStyles.ts`): `Checkbox` (16), `Switch` (36 × 20), tab triggers (30 high), the `Select` trigger (40 high), the `SearchInput` clear button (24), the `UpgradeToProCard` pill (32 high, slop 8) and `Button` (the slop brings each size to at least 48). From 0.5.0 so do `ColorSwatches` swatches and `IconButton` (32 and 40); the `DateTimeField` clear button and the pressable `PageIndicator` dots are 44 squares. Controls set their role and state for VoiceOver and TalkBack: `Button` (`disabled`, `busy` while loading), `Checkbox` (`checked`, `mixed`), `Switch` (`checked`), `Tabs` and `PillTabs` (`tablist`, `tab`, `selected`) and the `Select` trigger (`combobox`, with an `accessibilityLabel` prop). Give a `Button` with no text child an `accessibilityLabel`.
+The components keep the web sizes on screen and reach a 44 pt touch target with `hitSlop` (`touchSlop` in `src/controlStyles.ts`): `Checkbox` (16), `Switch` (36 × 20), tab triggers (30 high), the `Select` trigger (40 high), the `SearchInput` clear button (24), the `PasswordInput` show/hide button (24), the `UpgradeToProCard` pill (32 high, slop 8) and `Button` (the slop brings each size to at least 48). From 0.5.0 so do `ColorSwatches` swatches and `IconButton` (32 and 40); the `DateTimeField` clear button and the pressable `PageIndicator` dots are 44 squares. Controls set their role and state for VoiceOver and TalkBack: `Button` (`disabled`, `busy` while loading), `Checkbox` (`checked`, `mixed`), `Switch` (`checked`), `Tabs` and `PillTabs` (`tablist`, `tab`, `selected`) and the `Select` trigger (`combobox`, with an `accessibilityLabel` prop). Give a `Button` with no text child an `accessibilityLabel`.
 
 Text scales with the system font size. Labelled controls have minimum heights, so a large Dynamic Type size grows them instead of clipping the label (the `SearchInput` lock grows with the font scale); only the `FloatingTabBar` labels are capped (1.5×), to fit the fixed bar. With Reduce Motion on, dialogs, sheets, toasts, the `Select` popover, `PricingModal`, `Progress`, `Skeleton` and the `FloatingTabBar` pill do not animate. Dialogs, sheets, toasts, `FloatingTabBar` and `FloatingFAB` stay inside the safe-area insets, and dialog and sheet fields stay above the keyboard on iOS and Android.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/native-ui",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "license": "MIT",
   "description": "Shared React Native / Expo UI primitives. Floating surfaces, forms, overlays, toasts, settings chrome, tab bar, AI chat parts, the family app marks, a NativeWind preset, the Expo web root and Clerk + Convex auth screens.",
   "type": "module",
@@ -37,6 +37,10 @@
       "types": "./src/entries/search-input.ts",
       "default": "./src/entries/search-input.ts"
     },
+    "./password-input": {
+      "types": "./src/entries/password-input.ts",
+      "default": "./src/entries/password-input.ts"
+    },
     "./page-title": {
       "types": "./src/entries/page-title.ts",
       "default": "./src/entries/page-title.ts"

package/src/PasswordInput.tsx

@@ -0,0 +1,101 @@
+import * as React from "react";
+import { Pressable, View } from "react-native";
+import { IconEye, IconEyeOff } from "@tabler/icons-react-native";
+import { Input } from "./Input";
+import { cn } from "./cn";
+import { fieldStyle, fieldTextStyle, touchSlop, typeStyle } from "./controlStyles";
+import { tokens } from "./tokens";
+import { useLargerText } from "./theme";
+import { useScheme } from "./useScheme";
+
+type PasswordInputProps = Omit<React.ComponentPropsWithoutRef<typeof Input>, "secureTextEntry"> & {
+  /** Classes for the `View` around the field and the toggle. */
+  wrapperClassName?: string;
+};
+
+/** Toggle metrics: painted 24 (32 with larger text), 44 with its hit slop. */
+function passwordToggleSize(largerText: boolean) {
+  return largerText
+    ? ({ button: 32, icon: 20, right: 12, paddingRight: 56 } as const)
+    : ({ button: 24, icon: 18, right: 8, paddingRight: 44 } as const);
+}
+
+/**
+ * `Input` for a password, with a show/hide eye button at the end. The text is
+ * hidden at first. The toggle flips `secureTextEntry` on the same mounted
+ * field, so focus and the cursor stay where they were. The `secureTextEntry`
+ * prop is not accepted: the toggle owns it. Every other `Input` prop, `ref`
+ * and `testID` pass through. The toggle is labelled "Show password" while the
+ * text is hidden and "Hide password" while it shows, has the test ID
+ * `${testID}-toggle` (`password-input-toggle` without a `testID`), is painted
+ * at 24 and reaches 44 with its hit slop (`touchSlop`). It is hidden when the
+ * field is not editable. Inside a `ScrollView`, set
+ * `keyboardShouldPersistTaps="handled"` so the first tap toggles while the
+ * keyboard is up.
+ */
+const PasswordInput = React.forwardRef<
+  React.ElementRef<typeof Input>,
+  PasswordInputProps
+>(({ wrapperClassName, className, style, testID, ...props }, ref) => {
+  const largerText = useLargerText();
+  const scheme = useScheme();
+  const [visible, setVisible] = React.useState(false);
+  const metrics = passwordToggleSize(largerText);
+  const muted = tokens.color.muted[scheme];
+  const Icon = visible ? IconEyeOff : IconEye;
+  return (
+    <View className={cn("relative w-full", wrapperClassName)}>
+      <Input
+        {...props}
+        ref={ref}
+        testID={testID}
+        // The same size and font classes as `Input`, so the field has the same
+        // height and type. `Input` adds them too; `cn` merges the repeat.
+        // The type comes from these classes only (no style `fontSize`), so it
+        // cannot diverge from NativeWind's `text-base` / `text-xl`.
+        className={cn(
+          "min-h-10 border px-3.5 py-2 text-base font-instrument-sans",
+          largerText && "min-h-16 px-4 py-4 text-xl font-instrument-sans-medium",
+          className,
+        )}
+        // After the spread, so a caller cannot fight the toggle.
+        secureTextEntry={!visible}
+        // The `Input` styles. `fontSize` and `lineHeight` are not set: the field
+        // inherits `Input`'s type through the same className. Then room for the
+        // toggle, so text does not run under it.
+        style={[
+          fieldStyle(scheme),
+          fieldTextStyle(scheme),
+          largerText ? typeStyle("medium") : null,
+          { paddingRight: metrics.paddingRight },
+          style,
+        ]}
+      />
+      {props.editable !== false ? (
+        <View
+          pointerEvents="box-none"
+          className="absolute bottom-0 top-0 justify-center"
+          style={{ right: metrics.right }}
+        >
+          <Pressable
+            testID={testID ? `${testID}-toggle` : "password-input-toggle"}
+            accessibilityRole="button"
+            accessibilityLabel={visible ? "Hide password" : "Show password"}
+            hitSlop={touchSlop(metrics.button)}
+            onPress={() => setVisible((current) => !current)}
+            className="items-center justify-center rounded-md active:opacity-70"
+            style={{ width: metrics.button, height: metrics.button }}
+          >
+            {/* `strokeWidth`, not `stroke`: here `stroke` is the colour. */}
+            <Icon size={metrics.icon} color={muted} strokeWidth={1.75} />
+          </Pressable>
+        </View>
+      ) : null}
+    </View>
+  );
+});
+
+PasswordInput.displayName = "PasswordInput";
+
+export { PasswordInput };
+export type { PasswordInputProps };

package/src/auth/AuthScreen.tsx

@@ -1,5 +1,5 @@
-import type { ReactNode } from "react";
-import { KeyboardAvoidingView, Platform, ScrollView, StyleSheet, Text, View } from "react-native";
+import { useEffect, useState, type ReactNode } from "react";
+import { Keyboard, KeyboardAvoidingView, ScrollView, StyleSheet, Text, View } from "react-native";
 import { cn } from "../cn";
 import { textStyle, typeStyle } from "../controlStyles";
 import { palette } from "../palette";
@@ -18,23 +18,51 @@ export type AuthScreenProps = {
   className?: string;
 };
 
+/** Space under the form while the keyboard is open, on top of its height. */
+const KEYBOARD_EXTRA = 24;
+
+/** The height of the open soft keyboard, or 0. Edge-to-edge Android ignores `adjustResize`, so the screen pads itself. */
+function useKeyboardHeight(): number {
+  const [height, setHeight] = useState(0);
+  useEffect(() => {
+    const show = (event: { endCoordinates: { height: number } }) => setHeight(event.endCoordinates.height);
+    const hide = () => setHeight(0);
+    const subs = [
+      Keyboard.addListener("keyboardWillShow", show),
+      Keyboard.addListener("keyboardDidShow", show),
+      Keyboard.addListener("keyboardWillHide", hide),
+      Keyboard.addListener("keyboardDidHide", hide),
+    ];
+    return () => subs.forEach((sub) => sub.remove());
+  }, []);
+  return height;
+}
+
 /**
  * The sign-in and sign-up frame: a keyboard-avoiding scroll view on the
  * background colour, with a title, subtitle and the form in a column of 16.
+ * The form is centred until the keyboard opens. Then it aligns to the top and
+ * the scroll content gains the keyboard height as bottom space, so the focused
+ * field and the submit button scroll above the keyboard.
  */
 export function AuthScreen({ title, subtitle, children, header, footer, testID, className }: AuthScreenProps) {
   const scheme = useScheme();
+  const keyboardHeight = useKeyboardHeight();
+  const keyboardOpen = keyboardHeight > 0;
   return (
     <KeyboardAvoidingView
-      behavior={Platform.OS === "ios" ? "padding" : "height"}
+      // Padding on both platforms, as OverlayModal and PromptInput: Android `height` does nothing edge-to-edge.
+      behavior="padding"
       className="flex-1"
       style={{ backgroundColor: tokens.color.background[scheme] }}
     >
       <ScrollView
         testID={testID}
         className="flex-1"
-        contentContainerClassName={cn("grow justify-center px-6 py-12", className)}
+        contentContainerClassName={cn("grow px-6 py-12", keyboardOpen ? "justify-start" : "justify-center", className)}
+        contentContainerStyle={keyboardOpen ? { paddingBottom: keyboardHeight + KEYBOARD_EXTRA } : undefined}
         keyboardShouldPersistTaps="handled"
+        keyboardDismissMode="on-drag"
       >
         <View className="w-full max-w-sm self-center gap-6">
           {header}

package/src/auth/SecondFactorScreen.tsx

@@ -0,0 +1,87 @@
+// Clerk-free: a one-time code step. The caller owns the verification call and
+// its errors (`useSecondFactor` does both for Clerk).
+import { useState, type ReactNode } from "react";
+import { Button } from "../Button";
+import { Input } from "../Input";
+import { AuthScreen, FieldError } from "./AuthScreen";
+
+export type SecondFactorScreenProps = {
+  title: string;
+  description?: string;
+  /** Digits in the code. Default 6. */
+  codeLength?: number;
+  /** Called with the full code. A rejected promise is the caller's to handle. */
+  onSubmit: (code: string) => Promise<void> | void;
+  /** Inline error under the field, such as "Incorrect code". */
+  error?: string;
+  /** Shows the Verify spinner and blocks a second submit. */
+  loading?: boolean;
+  /** Shows a ghost back button when set. */
+  onBack?: () => void;
+  /** Default "Back". */
+  backLabel?: string;
+  /** Above the title. App brand chrome goes here. */
+  header?: ReactNode;
+  /** Prefix for every `testID`. Default "second-factor". */
+  testIDPrefix?: string;
+  /** Below the buttons, such as a "Use a backup code" switch. Passed to `AuthScreen`. */
+  footer?: ReactNode;
+  /** Default `true`: digits only, number pad. `false` takes any characters (backup codes). */
+  digitsOnly?: boolean;
+  /** Placeholder when `digitsOnly` is `false`. Default "Code". */
+  placeholder?: string;
+};
+
+/** A one-time code step: digits only, a Verify button, an inline error and a back link. */
+export function SecondFactorScreen({
+  title,
+  description,
+  codeLength = 6,
+  onSubmit,
+  error,
+  loading = false,
+  onBack,
+  backLabel = "Back",
+  header,
+  testIDPrefix = "second-factor",
+  footer,
+  digitsOnly = true,
+  placeholder,
+}: SecondFactorScreenProps) {
+  const [code, setCode] = useState("");
+  const ready = code.length === codeLength && !loading;
+
+  const submit = () => {
+    if (ready) void onSubmit(code);
+  };
+
+  return (
+    <AuthScreen testID={`${testIDPrefix}-screen`} title={title} subtitle={description} header={header} footer={footer}>
+      <Input
+        testID={`${testIDPrefix}-code`}
+        accessibilityLabel="Verification code"
+        value={code}
+        placeholder={digitsOnly ? "0".repeat(codeLength) : (placeholder ?? "Code")}
+        keyboardType={digitsOnly ? "number-pad" : "default"}
+        autoCapitalize="none"
+        autoCorrect={false}
+        autoComplete="one-time-code"
+        textContentType="oneTimeCode"
+        maxLength={codeLength}
+        autoFocus
+        returnKeyType="go"
+        onChangeText={(text) => setCode(digitsOnly ? text.replace(/\D/g, "") : text.trim())}
+        onSubmitEditing={submit}
+      />
+      <FieldError testID={`${testIDPrefix}-error`} message={error} />
+      <Button testID={`${testIDPrefix}-verify`} loading={loading} disabled={!ready} onPress={submit}>
+        Verify
+      </Button>
+      {onBack ? (
+        <Button testID={`${testIDPrefix}-back`} variant="ghost" onPress={onBack}>
+          {backLabel}
+        </Button>
+      ) : null}
+    </AuthScreen>
+  );
+}

package/src/auth/SignInScreen.tsx

@@ -5,10 +5,25 @@ import { useRouter } from "expo-router";
 import { Button } from "../Button";
 import { textStyle } from "../controlStyles";
 import { Input } from "../Input";
+import { PasswordInput } from "../PasswordInput";
 import { toast } from "../toastStore";
 import { useScheme } from "../useScheme";
 import { AuthScreen, FieldError, OrDivider } from "./AuthScreen";
-import { authErrorMessage } from "./authErrors";
+import { authErrorMessage, logAuthFailure } from "./authErrors";
+import { SecondFactorScreen } from "./SecondFactorScreen";
+import {
+  pickFirstFactorStrategy,
+  pickSecondFactorStrategy,
+  prepareFirstFactorIfNeeded,
+  submitFirstFactor,
+  supportedFirstFactorStrategies,
+  supportedSecondFactorStrategies,
+  useSecondFactor,
+  type FirstFactor,
+  type FirstFactorStrategy,
+  type SecondFactor,
+  type SecondFactorStrategy,
+} from "./totp";
 import { GoogleSignInButton, type AuthNavigationOptions } from "./GoogleSignInButton";
 
 export type SignInMode = "sign-in" | "sign-up";
@@ -22,8 +37,66 @@ export const AUTH_MESSAGES = {
   verifyFailed: "Invalid code",
   missingCode: "Enter the code from the email",
   needsAnotherStep: "This account needs another step to sign in. Finish it on the web.",
+  secondFactorTitle: "Two-step verification",
+  secondFactorDescription: "Enter the code from your authenticator app.",
+  emailCodeTitle: "Check your email",
+  emailCodeDescription: "Enter the code we sent to your email.",
+  phoneCodeTitle: "Check your phone",
+  phoneCodeDescription: "Enter the code we sent by text message.",
+  backupCodeTitle: "Enter a backup code",
+  backupCodeDescription: "Use one of the backup codes you saved when you set up two-step verification.",
+  clientTrustTitle: "Verify it's you",
+  clientTrustEmailDescription: "This device is new. Enter the code we sent to your email.",
+  clientTrustPhoneDescription: "This device is new. Enter the code we sent by text message.",
+  useBackupCode: "Use a backup code",
+  useAuthenticator: "Use authenticator app",
+  useEmailCode: "Email me a code",
+  usePhoneCode: "Text me a code",
+  newPasswordTitle: "Set a new password",
+  newPasswordDescription: "Your password must change before you can sign in.",
+  newPasswordLabel: "New password",
+  confirmPasswordLabel: "Confirm new password",
+  passwordMismatch: "The passwords do not match",
+  passwordTooShort: "Use a longer password",
+  resetPasswordFailed: "Could not set the new password",
+  setPassword: "Set password",
 } as const;
 
+/**
+ * A sign-in that is not complete, as `signIn.create` returns it. Passed to
+ * `onIncomplete` so the app can run the step itself.
+ */
+export type IncompleteSignIn = {
+  status: string | null;
+  createdSessionId: string | null;
+  supportedFirstFactors?: Array<{ strategy: string; [key: string]: unknown }> | null;
+  supportedSecondFactors?: SecondFactor[] | null;
+};
+
+const METHOD_LABEL: Record<SecondFactorStrategy, string> = {
+  totp: AUTH_MESSAGES.useAuthenticator,
+  email_code: AUTH_MESSAGES.useEmailCode,
+  phone_code: AUTH_MESSAGES.usePhoneCode,
+  backup_code: AUTH_MESSAGES.useBackupCode,
+};
+
+function secondFactorCopy(strategy: SecondFactorStrategy, clientTrust: boolean) {
+  if (strategy === "email_code") {
+    return clientTrust
+      ? { title: AUTH_MESSAGES.clientTrustTitle, description: AUTH_MESSAGES.clientTrustEmailDescription }
+      : { title: AUTH_MESSAGES.emailCodeTitle, description: AUTH_MESSAGES.emailCodeDescription };
+  }
+  if (strategy === "phone_code") {
+    return clientTrust
+      ? { title: AUTH_MESSAGES.clientTrustTitle, description: AUTH_MESSAGES.clientTrustPhoneDescription }
+      : { title: AUTH_MESSAGES.phoneCodeTitle, description: AUTH_MESSAGES.phoneCodeDescription };
+  }
+  if (strategy === "backup_code") {
+    return { title: AUTH_MESSAGES.backupCodeTitle, description: AUTH_MESSAGES.backupCodeDescription };
+  }
+  return { title: AUTH_MESSAGES.secondFactorTitle, description: AUTH_MESSAGES.secondFactorDescription };
+}
+
 export type SignInScreenProps = AuthNavigationOptions & {
   /** Default `"sign-in"`. `"sign-up"` creates the account and checks an emailed code. */
   mode?: SignInMode;
@@ -53,6 +126,19 @@ export type SignInScreenProps = AuthNavigationOptions & {
   header?: ReactNode;
   /** Below the footer link row, such as an app credit. */
   footer?: ReactNode;
+  /**
+   * Called with the sign-in when the built-in UI cannot finish it:
+   * `needs_identifier`, any unknown status, `needs_first_factor` when no
+   * `email_code` or `phone_code` first factor exists (with its id), and
+   * `needs_second_factor` or `needs_client_trust` when no supported strategy
+   * (totp, backup code, phone code, email code) exists. The built-in screen
+   * runs `needs_first_factor` with an email or phone code, and always runs
+   * `needs_second_factor`, `needs_client_trust` and `needs_new_password`
+   * itself. When called, the web-fallback message is not
+   * shown. Without it, the screen shows the web fallback and logs
+   * `console.warn`. Ignored in `sign-up`.
+   */
+  onIncomplete?: (signIn: IncompleteSignIn) => void;
 };
 
 /**
@@ -80,6 +166,7 @@ export function SignInScreen({
   testIDPrefix,
   header,
   footer,
+  onIncomplete,
 }: SignInScreenProps) {
   const signInState = useSignIn();
   const signUpState = useSignUp();
@@ -89,6 +176,18 @@ export function SignInScreen({
   const [password, setPassword] = useState("");
   const [code, setCode] = useState("");
   const [pendingVerification, setPendingVerification] = useState(false);
+  const [pendingSecondFactor, setPendingSecondFactor] = useState(false);
+  const [pendingFirstFactor, setPendingFirstFactor] = useState(false);
+  const [firstFactors, setFirstFactors] = useState<FirstFactor[]>([]);
+  const [firstStrategy, setFirstStrategy] = useState<FirstFactorStrategy>("email_code");
+  const [firstLoading, setFirstLoading] = useState(false);
+  const [firstError, setFirstError] = useState("");
+  const [factors, setFactors] = useState<SecondFactor[]>([]);
+  const [clientTrust, setClientTrust] = useState(false);
+  const [pendingNewPassword, setPendingNewPassword] = useState(false);
+  const [newPassword, setNewPassword] = useState("");
+  const [confirmPassword, setConfirmPassword] = useState("");
+  const secondFactor = useSecondFactor();
   const [error, setError] = useState("");
   const [submitting, setSubmitting] = useState(false);
   const signUp = mode === "sign-up";
@@ -104,27 +203,174 @@ export function SignInScreen({
     else router.replace(afterAuthHref, replaceOptions);
   };
 
-  const onSignIn = async () => {
+  const warnIncomplete = (attempt: IncompleteSignIn) => {
+    console.warn(
+      `[native-ui] Sign-in not complete: status=${attempt.status}, ` +
+        `secondFactors=${JSON.stringify((attempt.supportedSecondFactors ?? []).map((f) => f.strategy))}, ` +
+        `firstFactors=${JSON.stringify((attempt.supportedFirstFactors ?? []).map((f) => f.strategy))}. ` +
+        "Pass onIncomplete to handle it in the app.",
+    );
+  };
+
+  // A status the built-in UI cannot finish: the app's `onIncomplete`, or the web fallback.
+  const unhandled = (attempt: IncompleteSignIn) => {
+    if (onIncomplete) return onIncomplete(attempt);
+    warnIncomplete(attempt);
+    fail(AUTH_MESSAGES.signInFailed, AUTH_MESSAGES.needsAnotherStep);
+  };
+
+  const chooseStrategy = async (strategy: SecondFactorStrategy, list: SecondFactor[]) => {
+    secondFactor.clearError();
+    secondFactor.setStrategy(strategy);
+    setPendingSecondFactor(true);
+    await secondFactor.prepare(
+      strategy,
+      list.find((factor) => factor.strategy === strategy),
+    );
+  };
+
+  const startSecondFactor = async (attempt: IncompleteSignIn, trust: boolean) => {
+    const list = attempt.supportedSecondFactors ?? [];
+    const strategy = pickSecondFactorStrategy(list);
+    if (!strategy) return unhandled(attempt);
+    setFactors(list);
+    setClientTrust(trust);
+    await chooseStrategy(strategy, list);
+  };
+
+  const chooseFirstStrategy = async (strategy: FirstFactorStrategy, list: FirstFactor[]) => {
+    const { signIn } = signInState;
+    if (!signIn) return;
+    setFirstError("");
+    setFirstStrategy(strategy);
+    setPendingFirstFactor(true);
+    setFirstLoading(true);
+    const sent = await prepareFirstFactorIfNeeded({
+      signIn,
+      strategy,
+      factor: list.find((factor) => factor.strategy === strategy),
+    });
+    if (!sent.ok) setFirstError(sent.error);
+    setFirstLoading(false);
+  };
+
+  const startFirstFactor = async (attempt: IncompleteSignIn) => {
+    const list = attempt.supportedFirstFactors ?? [];
+    const strategy = pickFirstFactorStrategy(list);
+    if (!strategy) return unhandled(attempt);
+    setFirstFactors(list);
+    await chooseFirstStrategy(strategy, list);
+  };
+
+  // Routes a sign-in attempt. `needs_first_factor` is built in only after `signIn.create`.
+  const routeAttempt = async (attempt: IncompleteSignIn, afterCreate: boolean) => {
+    const { setActive } = signInState;
+    // Clerk's `SignInStatus` omits `needs_client_trust`: widen before comparing.
+    const status: string | null = attempt.status;
+    if (status === "complete" && attempt.createdSessionId && setActive) {
+      await setActive({ session: attempt.createdSessionId });
+      done();
+    } else if (status === "needs_new_password") {
+      setPendingFirstFactor(false);
+      setPendingNewPassword(true);
+    } else if (status === "needs_second_factor" || status === "needs_client_trust") {
+      setPendingFirstFactor(false);
+      await startSecondFactor(attempt, status === "needs_client_trust");
+    } else if (status === "needs_first_factor" && afterCreate) {
+      await startFirstFactor(attempt);
+    } else {
+      unhandled(attempt);
+    }
+  };
+
+  const onFirstFactor = async (firstCode: string) => {
+    const { isLoaded, signIn } = signInState;
+    if (!isLoaded || !signIn || firstLoading) return;
+    setFirstLoading(true);
+    setFirstError("");
+    const result = await submitFirstFactor({ signIn, code: firstCode, strategy: firstStrategy });
+    if (!result.ok) {
+      setFirstError(result.error);
+      setFirstLoading(false);
+      return;
+    }
+    try {
+      await routeAttempt(result.attempt, false);
+    } catch (caught) {
+      setFirstError(authErrorMessage(caught, AUTH_MESSAGES.verifyFailed));
+    } finally {
+      setFirstLoading(false);
+    }
+  };
+
+  const onNewPassword = async () => {
     const { isLoaded, signIn, setActive } = signInState;
     if (!isLoaded || !signIn || !setActive || submitting) return;
-    if (!email || !password) return fail(AUTH_MESSAGES.signInFailed, AUTH_MESSAGES.missingFields);
+    if (!newPassword) return fail(AUTH_MESSAGES.resetPasswordFailed, AUTH_MESSAGES.missingFields);
+    if (minPasswordLength && newPassword.length < minPasswordLength) {
+      return fail(AUTH_MESSAGES.resetPasswordFailed, `Use at least ${minPasswordLength} characters for the password`);
+    }
+    if (newPassword !== confirmPassword) {
+      return fail(AUTH_MESSAGES.resetPasswordFailed, AUTH_MESSAGES.passwordMismatch);
+    }
     setSubmitting(true);
     setError("");
     try {
-      const attempt = await signIn.create({ identifier: email, password });
-      if (attempt.status === "complete" && attempt.createdSessionId) {
-        await setActive({ session: attempt.createdSessionId });
+      const result = await signIn.resetPassword({ password: newPassword });
+      if (result.status === "complete" && result.createdSessionId) {
+        await setActive({ session: result.createdSessionId });
         done();
+      } else if (onIncomplete) {
+        onIncomplete(result);
       } else {
-        fail(AUTH_MESSAGES.signInFailed, AUTH_MESSAGES.needsAnotherStep);
+        warnIncomplete(result);
+        fail(AUTH_MESSAGES.resetPasswordFailed, AUTH_MESSAGES.needsAnotherStep);
       }
     } catch (caught) {
-      fail(AUTH_MESSAGES.signInFailed, authErrorMessage(caught, AUTH_MESSAGES.invalidCredentials));
+      fail(AUTH_MESSAGES.resetPasswordFailed, authErrorMessage(caught, AUTH_MESSAGES.resetPasswordFailed));
     } finally {
       setSubmitting(false);
     }
   };
 
+  const onSignIn = async () => {
+    const { isLoaded, signIn, setActive } = signInState;
+    if (!isLoaded || !signIn || !setActive || submitting) return;
+    if (!email || !password) return fail(AUTH_MESSAGES.signInFailed, AUTH_MESSAGES.missingFields);
+    setSubmitting(true);
+    setError("");
+    try {
+      const attempt = await signIn.create({ identifier: email, password });
+      await routeAttempt(attempt, true);
+    } catch (caught) {
+      logAuthFailure("create", caught);
+      fail(
+        AUTH_MESSAGES.signInFailed,
+        authErrorMessage(caught, AUTH_MESSAGES.invalidCredentials, { credentials: true }),
+      );
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const onSecondFactor = async (secondFactorCode: string) => {
+    const result = await secondFactor.submit(secondFactorCode);
+    if (result.ok) done();
+  };
+
+  const onSecondFactorBack = () => {
+    // The pending attempt stays; the next `signIn.create` replaces it.
+    setPendingSecondFactor(false);
+    setPendingFirstFactor(false);
+    setFirstError("");
+    setPendingNewPassword(false);
+    setNewPassword("");
+    setConfirmPassword("");
+    setPassword("");
+    setError("");
+    secondFactor.clearError();
+  };
+
   const onSignUp = async () => {
     const { isLoaded, signUp: attempt } = signUpState;
     if (!isLoaded || !attempt || submitting) return;
@@ -190,6 +436,129 @@ export function SignInScreen({
   );
   const hasFooter = Boolean((linkHref && !pendingVerification) || footer);
 
+  if (pendingNewPassword) {
+    return (
+      <AuthScreen
+        testID={id("new-password-screen")}
+        title={AUTH_MESSAGES.newPasswordTitle}
+        subtitle={AUTH_MESSAGES.newPasswordDescription}
+        header={header}
+      >
+        <PasswordInput
+          testID={id("new-password")}
+          accessibilityLabel={AUTH_MESSAGES.newPasswordLabel}
+          autoCapitalize="none"
+          autoComplete="new-password"
+          textContentType="newPassword"
+          autoFocus
+          returnKeyType="next"
+          value={newPassword}
+          placeholder={AUTH_MESSAGES.newPasswordLabel}
+          onChangeText={setNewPassword}
+        />
+        <PasswordInput
+          testID={id("confirm-password")}
+          accessibilityLabel={AUTH_MESSAGES.confirmPasswordLabel}
+          autoCapitalize="none"
+          autoComplete="new-password"
+          textContentType="newPassword"
+          returnKeyType="go"
+          value={confirmPassword}
+          placeholder={AUTH_MESSAGES.confirmPasswordLabel}
+          onChangeText={setConfirmPassword}
+          onSubmitEditing={() => void onNewPassword()}
+        />
+        <FieldError testID={id("error")} message={error} />
+        <Button testID={id("new-password-submit")} loading={submitting} onPress={() => void onNewPassword()}>
+          {AUTH_MESSAGES.setPassword}
+        </Button>
+        <Button testID={id("new-password-back")} variant="ghost" onPress={onSecondFactorBack}>
+          Use a different account
+        </Button>
+      </AuthScreen>
+    );
+  }
+
+  if (pendingFirstFactor && !pendingSecondFactor && !pendingNewPassword) {
+    const others = supportedFirstFactorStrategies(firstFactors).filter((strategy) => strategy !== firstStrategy);
+    const switchTo = others[0] ?? null;
+    const copy = secondFactorCopy(firstStrategy, false);
+    return (
+      <SecondFactorScreen
+        key={`first-${firstStrategy}`}
+        title={copy.title}
+        description={copy.description}
+        footer={
+          switchTo ? (
+            <Button
+              testID={id("first-factor-switch")}
+              variant="link"
+              size="sm"
+              fullWidth={false}
+              disabled={firstLoading}
+              onPress={() => void chooseFirstStrategy(switchTo, firstFactors)}
+            >
+              {METHOD_LABEL[switchTo]}
+            </Button>
+          ) : undefined
+        }
+        onSubmit={onFirstFactor}
+        error={firstError}
+        loading={firstLoading}
+        onBack={onSecondFactorBack}
+        backLabel="Use a different account"
+        header={header}
+        testIDPrefix={id("first-factor")}
+      />
+    );
+  }
+
+  if (pendingSecondFactor) {
+    const active = secondFactor.strategy;
+    const available = supportedSecondFactorStrategies(factors);
+    const others = available.filter((strategy) => strategy !== active);
+    // From a backup code, go back to the default non-backup method. Otherwise offer a backup code.
+    const switchTo =
+      active === "backup_code"
+        ? pickSecondFactorStrategy(factors.filter((factor) => factor.strategy !== "backup_code"))
+        : others.includes("backup_code")
+          ? "backup_code"
+          : null;
+    const copy = secondFactorCopy(active, clientTrust);
+    const backup = active === "backup_code";
+    return (
+      <SecondFactorScreen
+        key={active}
+        title={copy.title}
+        description={copy.description}
+        codeLength={backup ? 8 : 6}
+        digitsOnly={!backup}
+        placeholder="Backup code"
+        footer={
+          switchTo ? (
+            <Button
+              testID={id("second-factor-switch")}
+              variant="link"
+              size="sm"
+              fullWidth={false}
+              disabled={secondFactor.loading}
+              onPress={() => void chooseStrategy(switchTo, factors)}
+            >
+              {METHOD_LABEL[switchTo]}
+            </Button>
+          ) : undefined
+        }
+        onSubmit={onSecondFactor}
+        error={secondFactor.error}
+        loading={secondFactor.loading}
+        onBack={onSecondFactorBack}
+        backLabel="Use a different account"
+        header={header}
+        testIDPrefix={id("second-factor")}
+      />
+    );
+  }
+
   if (pendingVerification) {
     return (
       <AuthScreen
@@ -267,13 +636,12 @@ export function SignInScreen({
         placeholder="Email"
         onChangeText={setEmail}
       />
-      <Input
+      <PasswordInput
         testID={id("password")}
         accessibilityLabel="Password"
         autoCapitalize="none"
         autoComplete={signUp ? "new-password" : "password"}
         textContentType={signUp ? "newPassword" : "password"}
-        secureTextEntry
         returnKeyType="go"
         value={password}
         placeholder="Password"

package/src/auth/authErrors.ts

@@ -1,19 +1,97 @@
 import { isClerkAPIResponseError } from "@clerk/clerk-expo";
 
 /** Words that must not reach the user: the auth provider and stack names. */
-const PRODUCT_NAMES = /\b(clerk|convex)\b/i;
+const PRODUCT_NAMES = /\b(clerk|convex)\b/gi;
+
+/** The only Clerk codes that mean "Invalid email or password". */
+export const CREDENTIAL_ERROR_CODES = ["form_password_incorrect", "form_identifier_not_found"] as const;
+
+type ClerkErrorItem = {
+  code?: unknown;
+  message?: unknown;
+  longMessage?: unknown;
+  meta?: { paramName?: unknown } | null;
+};
+
+type ParsedAuthError = {
+  errors: ClerkErrorItem[];
+  status?: number;
+  clerkTraceId?: string;
+  errorName?: string;
+};
+
+const asString = (value: unknown): string | undefined =>
+  typeof value === "string" && value.length > 0 ? value : undefined;
+
+/** Reads a Clerk API error, or a plain `{ errors: [...] }` object. No `zod`. */
+function parseAuthError(error: unknown): ParsedAuthError | null {
+  if (typeof error !== "object" || error === null) return null;
+  const record = error as Record<string, unknown>;
+  if (!isClerkAPIResponseError(error) && !Array.isArray(record.errors)) return null;
+  const errors = Array.isArray(record.errors)
+    ? (record.errors as unknown[]).filter((item): item is ClerkErrorItem => typeof item === "object" && item !== null)
+    : [];
+  return {
+    errors,
+    status: typeof record.status === "number" ? record.status : undefined,
+    clerkTraceId: asString(record.clerkTraceId),
+    errorName: asString(record.name),
+  };
+}
+
+function firstError(parsed: ParsedAuthError | null) {
+  const first = parsed?.errors[0];
+  return {
+    code: asString(first?.code),
+    message: asString(first?.message),
+    longMessage: asString(first?.longMessage),
+    paramName: asString(first?.meta?.paramName),
+  };
+}
+
+/**
+ * Logs a failed auth call as one structured `console.error`. It holds the
+ * Clerk code, message, longMessage and meta.paramName, plus stage, errorName,
+ * status and clerkTraceId when present. Only the error object is read, so a
+ * password or one-time code is never logged.
+ */
+export function logAuthFailure(stage: string, error: unknown): void {
+  const parsed = parseAuthError(error);
+  const { code, message, longMessage, paramName } = firstError(parsed);
+  const errorName = parsed?.errorName ?? (error instanceof Error ? error.name : undefined);
+  console.error("[sign-in] failure", {
+    stage,
+    ...(errorName ? { errorName } : {}),
+    ...(parsed?.status !== undefined ? { status: parsed.status } : {}),
+    ...(parsed?.clerkTraceId ? { clerkTraceId: parsed.clerkTraceId } : {}),
+    code,
+    message,
+    longMessage,
+    meta: { paramName },
+  });
+}
+
+export type AuthErrorOptions = {
+  /**
+   * Sign-in with email and password. `form_password_incorrect` and
+   * `form_identifier_not_found` (only these) return `fallback`.
+   */
+  credentials?: boolean;
+};
 
 /**
- * A message to show for an auth error. An API error gives its first
- * `longMessage` or `message` (such as "Password is incorrect."); anything
- * else, or a message that names the provider, gives `fallback`. Never shows
- * a raw exception message.
+ * A message to show for an auth error. For a Clerk error it gives the first
+ * `longMessage` or `message`, with `clerk` and `convex` written as "the
+ * sign-in service", then `(code: <code>)`. With no text it gives `fallback`,
+ * still followed by the code when there is one. With `credentials: true`, the
+ * two credential codes give `fallback` alone. Anything that is not a Clerk
+ * error gives `fallback`. Never shows a raw exception message.
  */
-export function authErrorMessage(error: unknown, fallback: string): string {
-  if (isClerkAPIResponseError(error)) {
-    const first = error.errors[0];
-    const message = first?.longMessage ?? first?.message;
-    if (message && !PRODUCT_NAMES.test(message)) return message;
-  }
-  return fallback;
+export function authErrorMessage(error: unknown, fallback: string, options: AuthErrorOptions = {}): string {
+  const parsed = parseAuthError(error);
+  if (!parsed) return fallback;
+  const { code, message, longMessage } = firstError(parsed);
+  if (options.credentials && code && (CREDENTIAL_ERROR_CODES as readonly string[]).includes(code)) return fallback;
+  const text = (longMessage ?? message)?.replace(PRODUCT_NAMES, "the sign-in service") ?? fallback;
+  return code ? `${text} (code: ${code})` : text;
 }

package/src/auth/index.ts

@@ -6,7 +6,8 @@ export { AuthProviders } from "./AuthProviders";
 export type { AuthProvidersProps } from "./AuthProviders";
 export { AuthScreen, OrDivider, FieldError } from "./AuthScreen";
 export type { AuthScreenProps } from "./AuthScreen";
-export { authErrorMessage } from "./authErrors";
+export { authErrorMessage, logAuthFailure, CREDENTIAL_ERROR_CODES } from "./authErrors";
+export type { AuthErrorOptions } from "./authErrors";
 export {
   GoogleSignInButton,
   useGoogleSignIn,
@@ -19,4 +20,35 @@ export type {
   GoogleSignInButtonProps,
 } from "./GoogleSignInButton";
 export { SignInScreen, SignUpScreen, AUTH_MESSAGES } from "./SignInScreen";
-export type { SignInMode, SignInScreenProps, SignUpScreenProps } from "./SignInScreen";
+export type { IncompleteSignIn, SignInMode, SignInScreenProps, SignUpScreenProps } from "./SignInScreen";
+export { SecondFactorScreen } from "./SecondFactorScreen";
+export type { SecondFactorScreenProps } from "./SecondFactorScreen";
+export {
+  submitTotpSecondFactor,
+  submitSecondFactor,
+  prepareSecondFactorIfNeeded,
+  prepareFirstFactorIfNeeded,
+  submitFirstFactor,
+  pickFirstFactorStrategy,
+  supportedFirstFactorStrategies,
+  FIRST_FACTOR_PREFERENCE,
+  pickSecondFactorStrategy,
+  supportedSecondFactorStrategies,
+  SECOND_FACTOR_PREFERENCE,
+  useSecondFactor,
+  TOTP_MESSAGES,
+} from "./totp";
+export type {
+  FirstFactor,
+  FirstFactorResult,
+  FirstFactorSignIn,
+  FirstFactorStrategy,
+  SecondFactor,
+  SecondFactorSignIn,
+  SecondFactorStrategy,
+  TotpResult,
+  TotpSignIn,
+  TotpSetActive,
+  UseSecondFactorOptions,
+  UseSecondFactorResult,
+} from "./totp";

package/src/auth/totp.ts

@@ -0,0 +1,300 @@
+import { useState } from "react";
+import { useSignIn } from "@clerk/clerk-expo";
+import { authErrorMessage } from "./authErrors";
+
+/** The messages the second-factor step can show. Generic: none names a provider. */
+export const TOTP_MESSAGES = {
+  invalidCode: "Incorrect code. Check your authenticator app and try again.",
+  invalidCodeGeneric: "Incorrect code. Check it and try again.",
+  sendFailed: "Could not send the code. Try again.",
+  needsAnotherStep: "This account needs another step to sign in. Finish it on the web.",
+  notReady: "Sign in is not ready yet. Try again in a moment.",
+} as const;
+
+/** The second-factor strategies the built-in step handles. */
+export type SecondFactorStrategy = "totp" | "backup_code" | "phone_code" | "email_code";
+
+/** Default order: the first one the account supports wins. */
+export const SECOND_FACTOR_PREFERENCE: readonly SecondFactorStrategy[] = [
+  "totp",
+  "email_code",
+  "phone_code",
+  "backup_code",
+];
+
+/** One entry of `signIn.supportedSecondFactors`. */
+export type SecondFactor = {
+  strategy: string;
+  emailAddressId?: string;
+  phoneNumberId?: string;
+  safeIdentifier?: string;
+};
+
+type AttemptResult = { status: string | null; createdSessionId: string | null };
+
+/** The part of the sign-in resource that TOTP needs. Tests pass a mock. */
+export type TotpSignIn = {
+  attemptSecondFactor(params: { strategy: "totp"; code: string }): Promise<AttemptResult>;
+};
+
+/** The part of the sign-in resource that any second factor needs. Tests pass a mock. */
+export type SecondFactorSignIn = {
+  supportedSecondFactors?: SecondFactor[] | null;
+  prepareSecondFactor?(params: {
+    strategy: "phone_code" | "email_code";
+    phoneNumberId?: string;
+    emailAddressId?: string;
+  }): Promise<unknown>;
+  attemptSecondFactor(params: { strategy: SecondFactorStrategy; code: string }): Promise<AttemptResult>;
+};
+
+export type TotpSetActive = (params: { session: string }) => Promise<void>;
+
+export type TotpResult = { ok: true } | { ok: false; error: string };
+
+/** The strategies in `factors` that the built-in step handles, in the order given. */
+export function supportedSecondFactorStrategies(
+  factors: readonly SecondFactor[] | null | undefined,
+): SecondFactorStrategy[] {
+  const found = new Set((factors ?? []).map((factor) => factor.strategy));
+  return SECOND_FACTOR_PREFERENCE.filter((strategy) => found.has(strategy));
+}
+
+/** The default strategy: `totp`, then `email_code`, `phone_code`, `backup_code`. `null` when none is supported. */
+export function pickSecondFactorStrategy(
+  factors: readonly SecondFactor[] | null | undefined,
+): SecondFactorStrategy | null {
+  return supportedSecondFactorStrategies(factors)[0] ?? null;
+}
+
+/**
+ * Sends the code for `phone_code` and `email_code`, with the `phoneNumberId` or
+ * `emailAddressId` of the matching factor. `totp` and `backup_code` need no
+ * prepare: it returns `{ ok: true }` without a call. Never throws.
+ */
+export async function prepareSecondFactorIfNeeded(args: {
+  signIn: Pick<SecondFactorSignIn, "supportedSecondFactors" | "prepareSecondFactor">;
+  strategy: SecondFactorStrategy;
+  factor?: SecondFactor;
+}): Promise<TotpResult> {
+  const { signIn, strategy } = args;
+  if (strategy !== "phone_code" && strategy !== "email_code") return { ok: true };
+  if (!signIn.prepareSecondFactor) return { ok: false, error: TOTP_MESSAGES.sendFailed };
+  const factor = args.factor ?? signIn.supportedSecondFactors?.find((item) => item.strategy === strategy);
+  try {
+    if (strategy === "phone_code") {
+      await signIn.prepareSecondFactor({
+        strategy,
+        ...(factor?.phoneNumberId ? { phoneNumberId: factor.phoneNumberId } : {}),
+      });
+    } else {
+      await signIn.prepareSecondFactor({
+        strategy,
+        ...(factor?.emailAddressId ? { emailAddressId: factor.emailAddressId } : {}),
+      });
+    }
+    return { ok: true };
+  } catch (caught) {
+    return { ok: false, error: authErrorMessage(caught, TOTP_MESSAGES.sendFailed) };
+  }
+}
+
+/**
+ * Checks a second-factor code and starts the session. Call
+ * `prepareSecondFactorIfNeeded` first for `phone_code` and `email_code`.
+ * Never throws: a failure is `{ ok: false, error }`. An API error shows its
+ * own text (such as "Incorrect code") unless it names the provider; anything
+ * else gives `TOTP_MESSAGES.invalidCode` (`totp`) or `invalidCodeGeneric`.
+ */
+export async function submitSecondFactor(args: {
+  signIn: Pick<SecondFactorSignIn, "attemptSecondFactor">;
+  setActive: TotpSetActive;
+  code: string;
+  strategy: SecondFactorStrategy;
+}): Promise<TotpResult> {
+  try {
+    const attempt = await args.signIn.attemptSecondFactor({ strategy: args.strategy, code: args.code });
+    if (attempt.status === "complete" && attempt.createdSessionId) {
+      await args.setActive({ session: attempt.createdSessionId });
+      return { ok: true };
+    }
+    return { ok: false, error: TOTP_MESSAGES.needsAnotherStep };
+  } catch (caught) {
+    const fallback = args.strategy === "totp" ? TOTP_MESSAGES.invalidCode : TOTP_MESSAGES.invalidCodeGeneric;
+    return { ok: false, error: authErrorMessage(caught, fallback) };
+  }
+}
+
+/** The first-factor code strategies the built-in step handles. */
+export type FirstFactorStrategy = "email_code" | "phone_code";
+
+/** Default order: `email_code`, then `phone_code`. */
+export const FIRST_FACTOR_PREFERENCE: readonly FirstFactorStrategy[] = ["email_code", "phone_code"];
+
+/** One entry of `signIn.supportedFirstFactors`. */
+export type FirstFactor = {
+  strategy: string;
+  emailAddressId?: string;
+  phoneNumberId?: string;
+  safeIdentifier?: string;
+};
+
+/** The part of the sign-in resource that a first-factor code needs. Tests pass a mock. */
+export type FirstFactorSignIn = {
+  supportedFirstFactors?: FirstFactor[] | null;
+  prepareFirstFactor?(params: {
+    strategy: FirstFactorStrategy;
+    phoneNumberId?: string;
+    emailAddressId?: string;
+  }): Promise<unknown>;
+  attemptFirstFactor(params: { strategy: FirstFactorStrategy; code: string }): Promise<AttemptResult>;
+};
+
+/** A first-factor result: the attempt, for the caller to route, or an error. */
+export type FirstFactorResult = { ok: true; attempt: AttemptResult } | { ok: false; error: string };
+
+/**
+ * The first-factor strategies in `factors` that the built-in step handles, in
+ * preference order. A factor counts only when it has the id that
+ * `prepareFirstFactor` needs (`emailAddressId` or `phoneNumberId`).
+ */
+export function supportedFirstFactorStrategies(
+  factors: readonly FirstFactor[] | null | undefined,
+): FirstFactorStrategy[] {
+  const list = factors ?? [];
+  return FIRST_FACTOR_PREFERENCE.filter((strategy) =>
+    list.some(
+      (factor) =>
+        factor.strategy === strategy &&
+        Boolean(strategy === "email_code" ? factor.emailAddressId : factor.phoneNumberId),
+    ),
+  );
+}
+
+/** The default first-factor strategy: `email_code`, then `phone_code`. `null` when none is supported. */
+export function pickFirstFactorStrategy(
+  factors: readonly FirstFactor[] | null | undefined,
+): FirstFactorStrategy | null {
+  return supportedFirstFactorStrategies(factors)[0] ?? null;
+}
+
+/**
+ * Sends the first-factor code with the `emailAddressId` or `phoneNumberId` of
+ * the matching factor. Without that id it returns an error and makes no call.
+ * Never throws.
+ */
+export async function prepareFirstFactorIfNeeded(args: {
+  signIn: Pick<FirstFactorSignIn, "supportedFirstFactors" | "prepareFirstFactor">;
+  strategy: FirstFactorStrategy;
+  factor?: FirstFactor;
+}): Promise<TotpResult> {
+  const { signIn, strategy } = args;
+  if (!signIn.prepareFirstFactor) return { ok: false, error: TOTP_MESSAGES.sendFailed };
+  const factor = args.factor ?? signIn.supportedFirstFactors?.find((item) => item.strategy === strategy);
+  try {
+    if (strategy === "phone_code") {
+      if (!factor?.phoneNumberId) return { ok: false, error: TOTP_MESSAGES.sendFailed };
+      await signIn.prepareFirstFactor({ strategy, phoneNumberId: factor.phoneNumberId });
+    } else {
+      if (!factor?.emailAddressId) return { ok: false, error: TOTP_MESSAGES.sendFailed };
+      await signIn.prepareFirstFactor({ strategy, emailAddressId: factor.emailAddressId });
+    }
+    return { ok: true };
+  } catch (caught) {
+    return { ok: false, error: authErrorMessage(caught, TOTP_MESSAGES.sendFailed) };
+  }
+}
+
+/**
+ * Checks a first-factor code. It does not start the session: the attempt may
+ * need a second factor or a new password, so the caller routes it. Never
+ * throws: a failure is `{ ok: false, error }`.
+ */
+export async function submitFirstFactor(args: {
+  signIn: Pick<FirstFactorSignIn, "attemptFirstFactor">;
+  code: string;
+  strategy: FirstFactorStrategy;
+}): Promise<FirstFactorResult> {
+  try {
+    const attempt = await args.signIn.attemptFirstFactor({ strategy: args.strategy, code: args.code });
+    return { ok: true, attempt };
+  } catch (caught) {
+    return { ok: false, error: authErrorMessage(caught, TOTP_MESSAGES.invalidCodeGeneric) };
+  }
+}
+
+/** Checks a TOTP code and starts the session. TOTP needs no `prepareSecondFactor`. Same as `submitSecondFactor` with `strategy: "totp"`. */
+export function submitTotpSecondFactor(args: {
+  signIn: TotpSignIn;
+  setActive: TotpSetActive;
+  code: string;
+}): Promise<TotpResult> {
+  return submitSecondFactor({ signIn: args.signIn, setActive: args.setActive, code: args.code, strategy: "totp" });
+}
+
+export type UseSecondFactorOptions = {
+  /** The strategy `submit` uses until `setStrategy` changes it. Default `"totp"`. */
+  strategy?: SecondFactorStrategy;
+};
+
+export type UseSecondFactorResult = {
+  /** Checks the code and starts the session. Never throws. Sets `error` on failure. */
+  submit: (code: string) => Promise<TotpResult>;
+  /** Sends the code for `phone_code` and `email_code` (no call for the others). Never throws. Sets `error` on failure. */
+  prepare: (strategy?: SecondFactorStrategy, factor?: SecondFactor) => Promise<TotpResult>;
+  /** The strategy `submit` uses. */
+  strategy: SecondFactorStrategy;
+  setStrategy: (strategy: SecondFactorStrategy) => void;
+  /** True while `submit` or `prepare` runs. */
+  loading: boolean;
+  /** The last failure message, or `""`. */
+  error: string;
+  clearError: () => void;
+};
+
+/**
+ * Completes a sign-in that returned `needs_second_factor`. Default strategy
+ * `"totp"` (an authenticator-app code); pass `{ strategy }` or call
+ * `setStrategy` for the others. Pair with `SecondFactorScreen`:
+ * `onSubmit={submit}`, `error={error}`, `loading={loading}`. After
+ * `{ ok: true }` the session is active: navigate in the caller.
+ */
+export function useSecondFactor(options: UseSecondFactorOptions = {}): UseSecondFactorResult {
+  const { isLoaded, signIn, setActive } = useSignIn();
+  const [chosen, setChosen] = useState<SecondFactorStrategy | null>(null);
+  const strategy = chosen ?? options.strategy ?? "totp";
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+
+  const submit = async (code: string): Promise<TotpResult> => {
+    if (loading) return { ok: false, error };
+    if (!isLoaded || !signIn || !setActive) {
+      setError(TOTP_MESSAGES.notReady);
+      return { ok: false, error: TOTP_MESSAGES.notReady };
+    }
+    setLoading(true);
+    setError("");
+    const result = await submitSecondFactor({ signIn, setActive, code, strategy });
+    if (!result.ok) setError(result.error);
+    setLoading(false);
+    return result;
+  };
+
+  const prepare = async (
+    prepareStrategy: SecondFactorStrategy = strategy,
+    factor?: SecondFactor,
+  ): Promise<TotpResult> => {
+    if (!isLoaded || !signIn) {
+      setError(TOTP_MESSAGES.notReady);
+      return { ok: false, error: TOTP_MESSAGES.notReady };
+    }
+    setLoading(true);
+    setError("");
+    const result = await prepareSecondFactorIfNeeded({ signIn, strategy: prepareStrategy, factor });
+    if (!result.ok) setError(result.error);
+    setLoading(false);
+    return result;
+  };
+
+  return { submit, prepare, strategy, setStrategy: setChosen, loading, error, clearError: () => setError("") };
+}

package/src/entries/password-input.ts

@@ -0,0 +1,4 @@
+// `@vvedantb/native-ui/password-input`: `PasswordInput` on its own. Reaches no
+// optional peer, not even a loader.
+export { PasswordInput } from "../PasswordInput";
+export type { PasswordInputProps } from "../PasswordInput";

package/src/entries/primitives.ts

@@ -9,6 +9,8 @@ export { Input } from "../Input";
 export type { InputProps } from "../Input";
 export { SearchInput } from "../SearchInput";
 export type { SearchInputProps } from "../SearchInput";
+export { PasswordInput } from "../PasswordInput";
+export type { PasswordInputProps } from "../PasswordInput";
 export { Textarea } from "../Textarea";
 export type { TextareaProps } from "../Textarea";
 export { Label } from "../Label";

package/src/index.ts

@@ -45,6 +45,8 @@ export { Input } from "./Input";
 export type { InputProps } from "./Input";
 export { SearchInput } from "./SearchInput";
 export type { SearchInputProps } from "./SearchInput";
+export { PasswordInput } from "./PasswordInput";
+export type { PasswordInputProps } from "./PasswordInput";
 export { Textarea } from "./Textarea";
 export type { TextareaProps } from "./Textarea";
 export { Label } from "./Label";