@vvedantb/native-ui 0.10.0 → 0.11.1

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`, `SecondFactorScreen`, `useSecondFactor`, `submitTotpSecondFactor`, `submitSecondFactor`, `prepareSecondFactorIfNeeded`, `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/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) |
 
@@ -212,8 +213,9 @@ export default function SignUp() {
 - `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`, 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`. 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`.
+- `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.
 
@@ -309,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) |
@@ -360,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
@@ -554,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.10.0",
+  "version": "0.11.1",
   "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/SignInScreen.tsx

@@ -5,15 +5,28 @@ 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,
+  DEFAULT_STAGE_TIMEOUT_MS,
+  isAuthTimeoutError,
+  logAuthFailure,
+  withAuthTimeout,
+} from "./authErrors";
 import { SecondFactorScreen } from "./SecondFactorScreen";
 import {
+  pickFirstFactorStrategy,
   pickSecondFactorStrategy,
+  prepareFirstFactorIfNeeded,
+  submitFirstFactor,
+  supportedFirstFactorStrategies,
   supportedSecondFactorStrategies,
   useSecondFactor,
+  type FirstFactor,
+  type FirstFactorStrategy,
   type SecondFactor,
   type SecondFactorStrategy,
 } from "./totp";
@@ -121,15 +134,23 @@ export type SignInScreenProps = AuthNavigationOptions & {
   footer?: ReactNode;
   /**
    * Called with the sign-in when the built-in UI cannot finish it:
-   * `needs_identifier`, `needs_first_factor`, any unknown status, and
+   * `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
-   * always runs `needs_second_factor`, `needs_client_trust` and
-   * `needs_new_password` itself. When called, the web-fallback message is not
+   * 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;
+  /**
+   * Time for each Clerk call (create, prepare, attempt, reset password,
+   * set active), in milliseconds. A call that takes longer fails with code
+   * `auth_timeout`. Default 20000.
+   */
+  stageTimeoutMs?: number;
 };
 
 /**
@@ -158,6 +179,7 @@ export function SignInScreen({
   header,
   footer,
   onIncomplete,
+  stageTimeoutMs = DEFAULT_STAGE_TIMEOUT_MS,
 }: SignInScreenProps) {
   const signInState = useSignIn();
   const signUpState = useSignUp();
@@ -168,12 +190,17 @@ export function SignInScreen({
   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 secondFactor = useSecondFactor({ stageTimeoutMs });
   const [error, setError] = useState("");
   const [submitting, setSubmitting] = useState(false);
   const signUp = mode === "sign-up";
@@ -224,6 +251,78 @@ export function SignInScreen({
     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),
+      timeoutMs: stageTimeoutMs,
+    });
+    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 withAuthTimeout(setActive({ session: attempt.createdSessionId }), "set-active", stageTimeoutMs);
+      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,
+      timeoutMs: stageTimeoutMs,
+    });
+    if (!result.ok) {
+      setFirstError(result.error);
+      setFirstLoading(false);
+      return;
+    }
+    try {
+      await routeAttempt(result.attempt, false);
+    } catch (caught) {
+      if (isAuthTimeoutError(caught)) logAuthFailure("set-active", caught);
+      setFirstError(authErrorMessage(caught, AUTH_MESSAGES.verifyFailed));
+    } finally {
+      setFirstLoading(false);
+    }
+  };
+
   const onNewPassword = async () => {
     const { isLoaded, signIn, setActive } = signInState;
     if (!isLoaded || !signIn || !setActive || submitting) return;
@@ -237,9 +336,13 @@ export function SignInScreen({
     setSubmitting(true);
     setError("");
     try {
-      const result = await signIn.resetPassword({ password: newPassword });
+      const result = await withAuthTimeout(
+        signIn.resetPassword({ password: newPassword }),
+        "reset-password",
+        stageTimeoutMs,
+      );
       if (result.status === "complete" && result.createdSessionId) {
-        await setActive({ session: result.createdSessionId });
+        await withAuthTimeout(setActive({ session: result.createdSessionId }), "set-active", stageTimeoutMs);
         done();
       } else if (onIncomplete) {
         onIncomplete(result);
@@ -248,6 +351,7 @@ export function SignInScreen({
         fail(AUTH_MESSAGES.resetPasswordFailed, AUTH_MESSAGES.needsAnotherStep);
       }
     } catch (caught) {
+      if (isAuthTimeoutError(caught)) logAuthFailure("reset-password", caught);
       fail(AUTH_MESSAGES.resetPasswordFailed, authErrorMessage(caught, AUTH_MESSAGES.resetPasswordFailed));
     } finally {
       setSubmitting(false);
@@ -261,19 +365,18 @@ export function SignInScreen({
     setSubmitting(true);
     setError("");
     try {
-      const attempt = await signIn.create({ identifier: email, password });
-      if (attempt.status === "complete" && attempt.createdSessionId) {
-        await setActive({ session: attempt.createdSessionId });
-        done();
-      } else if (attempt.status === "needs_new_password") {
-        setPendingNewPassword(true);
-      } else if (attempt.status === "needs_second_factor" || attempt.status === "needs_client_trust") {
-        await startSecondFactor(attempt, attempt.status === "needs_client_trust");
-      } else {
-        unhandled(attempt);
-      }
+      const attempt = await withAuthTimeout(
+        signIn.create({ identifier: email, password }),
+        "create",
+        stageTimeoutMs,
+      );
+      await routeAttempt(attempt, true);
     } catch (caught) {
-      fail(AUTH_MESSAGES.signInFailed, authErrorMessage(caught, AUTH_MESSAGES.invalidCredentials));
+      logAuthFailure("create", caught);
+      fail(
+        AUTH_MESSAGES.signInFailed,
+        authErrorMessage(caught, AUTH_MESSAGES.invalidCredentials, { credentials: true }),
+      );
     } finally {
       setSubmitting(false);
     }
@@ -287,6 +390,8 @@ export function SignInScreen({
   const onSecondFactorBack = () => {
     // The pending attempt stays; the next `signIn.create` replaces it.
     setPendingSecondFactor(false);
+    setPendingFirstFactor(false);
+    setFirstError("");
     setPendingNewPassword(false);
     setNewPassword("");
     setConfirmPassword("");
@@ -368,26 +473,24 @@ export function SignInScreen({
         subtitle={AUTH_MESSAGES.newPasswordDescription}
         header={header}
       >
-        <Input
+        <PasswordInput
           testID={id("new-password")}
           accessibilityLabel={AUTH_MESSAGES.newPasswordLabel}
           autoCapitalize="none"
           autoComplete="new-password"
           textContentType="newPassword"
-          secureTextEntry
           autoFocus
           returnKeyType="next"
           value={newPassword}
           placeholder={AUTH_MESSAGES.newPasswordLabel}
           onChangeText={setNewPassword}
         />
-        <Input
+        <PasswordInput
           testID={id("confirm-password")}
           accessibilityLabel={AUTH_MESSAGES.confirmPasswordLabel}
           autoCapitalize="none"
           autoComplete="new-password"
           textContentType="newPassword"
-          secureTextEntry
           returnKeyType="go"
           value={confirmPassword}
           placeholder={AUTH_MESSAGES.confirmPasswordLabel}
@@ -405,6 +508,40 @@ export function SignInScreen({
     );
   }
 
+  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);
@@ -528,13 +665,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,145 @@
 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),
+  };
+}
+
+/** The code of a timed-out auth stage. */
+export const AUTH_TIMEOUT_CODE = "auth_timeout";
+
+/** Default time for one Clerk call, in milliseconds. */
+export const DEFAULT_STAGE_TIMEOUT_MS = 20000;
 
 /**
- * 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.
+ * The error `withAuthTimeout` rejects with. It is Clerk-shaped (`errors[0].code`
+ * is `auth_timeout`), so `authErrorMessage` and `logAuthFailure` read it.
  */
-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;
+export class AuthTimeoutError extends Error {
+  readonly code = AUTH_TIMEOUT_CODE;
+  readonly stage: string;
+  readonly errors: { code: string; message: string }[];
+  constructor(stage: string, ms: number) {
+    const message = `The ${stage} step timed out after ${Math.round(ms / 1000)} seconds. Try again.`;
+    super(message);
+    this.name = "AuthTimeoutError";
+    this.stage = stage;
+    this.errors = [{ code: AUTH_TIMEOUT_CODE, message }];
   }
-  return fallback;
+}
+
+export function isAuthTimeoutError(error: unknown): error is AuthTimeoutError {
+  return error instanceof AuthTimeoutError;
+}
+
+/**
+ * Rejects with `AuthTimeoutError` (code `auth_timeout`, message names `stage`)
+ * when `promise` has not settled after `ms`. The timer is cleared on settle.
+ */
+export function withAuthTimeout<T>(promise: Promise<T>, stage: string, ms: number = DEFAULT_STAGE_TIMEOUT_MS): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new AuthTimeoutError(stage, ms)), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * 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. For `AuthTimeoutError` the logged stage is the error's own stage. Only the error object is read, so a
+ * password or one-time code is never logged.
+ */
+export function logAuthFailure(stage: string, error: unknown): void {
+  if (isAuthTimeoutError(error)) stage = error.stage;
+  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. 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, 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,17 @@ 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,
+  withAuthTimeout,
+  AuthTimeoutError,
+  isAuthTimeoutError,
+  AUTH_TIMEOUT_CODE,
+  DEFAULT_STAGE_TIMEOUT_MS,
+  CREDENTIAL_ERROR_CODES,
+} from "./authErrors";
+export type { AuthErrorOptions } from "./authErrors";
 export {
   GoogleSignInButton,
   useGoogleSignIn,
@@ -26,6 +36,11 @@ export {
   submitTotpSecondFactor,
   submitSecondFactor,
   prepareSecondFactorIfNeeded,
+  prepareFirstFactorIfNeeded,
+  submitFirstFactor,
+  pickFirstFactorStrategy,
+  supportedFirstFactorStrategies,
+  FIRST_FACTOR_PREFERENCE,
   pickSecondFactorStrategy,
   supportedSecondFactorStrategies,
   SECOND_FACTOR_PREFERENCE,
@@ -33,6 +48,10 @@ export {
   TOTP_MESSAGES,
 } from "./totp";
 export type {
+  FirstFactor,
+  FirstFactorResult,
+  FirstFactorSignIn,
+  FirstFactorStrategy,
   SecondFactor,
   SecondFactorSignIn,
   SecondFactorStrategy,

package/src/auth/totp.ts

@@ -1,6 +1,17 @@
 import { useState } from "react";
 import { useSignIn } from "@clerk/clerk-expo";
-import { authErrorMessage } from "./authErrors";
+import {
+  authErrorMessage,
+  DEFAULT_STAGE_TIMEOUT_MS,
+  isAuthTimeoutError,
+  logAuthFailure,
+  withAuthTimeout,
+} from "./authErrors";
+
+/** Logs a timed-out stage. Other failures are not logged here. */
+const logTimeout = (stage: string, error: unknown) => {
+  if (isAuthTimeoutError(error)) logAuthFailure(stage, error);
+};
 
 /** The messages the second-factor step can show. Generic: none names a provider. */
 export const TOTP_MESSAGES = {
@@ -76,25 +87,37 @@ export async function prepareSecondFactorIfNeeded(args: {
   signIn: Pick<SecondFactorSignIn, "supportedSecondFactors" | "prepareSecondFactor">;
   strategy: SecondFactorStrategy;
   factor?: SecondFactor;
+  /** Time for the Clerk call. Default 20000 ms. */
+  timeoutMs?: number;
 }): Promise<TotpResult> {
   const { signIn, strategy } = args;
+  const ms = args.timeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS;
   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 } : {}),
-      });
+      await withAuthTimeout(
+        signIn.prepareSecondFactor({
+          strategy,
+          ...(factor?.phoneNumberId ? { phoneNumberId: factor.phoneNumberId } : {}),
+        }),
+        "prepare-second-factor",
+        ms,
+      );
     } else {
-      await signIn.prepareSecondFactor({
-        strategy,
-        ...(factor?.emailAddressId ? { emailAddressId: factor.emailAddressId } : {}),
-      });
+      await withAuthTimeout(
+        signIn.prepareSecondFactor({
+          strategy,
+          ...(factor?.emailAddressId ? { emailAddressId: factor.emailAddressId } : {}),
+        }),
+        "prepare-second-factor",
+        ms,
+      );
     }
     return { ok: true };
   } catch (caught) {
+    logTimeout("prepare-second-factor", caught);
     return { ok: false, error: authErrorMessage(caught, TOTP_MESSAGES.sendFailed) };
   }
 }
@@ -111,32 +134,166 @@ export async function submitSecondFactor(args: {
   setActive: TotpSetActive;
   code: string;
   strategy: SecondFactorStrategy;
+  /** Time for each Clerk call. Default 20000 ms. */
+  timeoutMs?: number;
 }): Promise<TotpResult> {
+  const ms = args.timeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS;
   try {
-    const attempt = await args.signIn.attemptSecondFactor({ strategy: args.strategy, code: args.code });
+    const attempt = await withAuthTimeout(
+      args.signIn.attemptSecondFactor({ strategy: args.strategy, code: args.code }),
+      "attempt-second-factor",
+      ms,
+    );
     if (attempt.status === "complete" && attempt.createdSessionId) {
-      await args.setActive({ session: attempt.createdSessionId });
+      await withAuthTimeout(args.setActive({ session: attempt.createdSessionId }), "set-active", ms);
       return { ok: true };
     }
     return { ok: false, error: TOTP_MESSAGES.needsAnotherStep };
   } catch (caught) {
+    logTimeout("attempt-second-factor", 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;
+  /** Time for the Clerk call. Default 20000 ms. */
+  timeoutMs?: number;
+}): Promise<TotpResult> {
+  const { signIn, strategy } = args;
+  const ms = args.timeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS;
+  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 withAuthTimeout(
+        signIn.prepareFirstFactor({ strategy, phoneNumberId: factor.phoneNumberId }),
+        "prepare-first-factor",
+        ms,
+      );
+    } else {
+      if (!factor?.emailAddressId) return { ok: false, error: TOTP_MESSAGES.sendFailed };
+      await withAuthTimeout(
+        signIn.prepareFirstFactor({ strategy, emailAddressId: factor.emailAddressId }),
+        "prepare-first-factor",
+        ms,
+      );
+    }
+    return { ok: true };
+  } catch (caught) {
+    logTimeout("prepare-first-factor", 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;
+  /** Time for the Clerk call. Default 20000 ms. */
+  timeoutMs?: number;
+}): Promise<FirstFactorResult> {
+  try {
+    const attempt = await withAuthTimeout(
+      args.signIn.attemptFirstFactor({ strategy: args.strategy, code: args.code }),
+      "attempt-first-factor",
+      args.timeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS,
+    );
+    return { ok: true, attempt };
+  } catch (caught) {
+    logTimeout("attempt-first-factor", 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;
+  timeoutMs?: number;
 }): Promise<TotpResult> {
-  return submitSecondFactor({ signIn: args.signIn, setActive: args.setActive, code: args.code, strategy: "totp" });
+  return submitSecondFactor({
+    signIn: args.signIn,
+    setActive: args.setActive,
+    code: args.code,
+    strategy: "totp",
+    timeoutMs: args.timeoutMs,
+  });
 }
 
 export type UseSecondFactorOptions = {
   /** The strategy `submit` uses until `setStrategy` changes it. Default `"totp"`. */
   strategy?: SecondFactorStrategy;
+  /** Time for each Clerk call, in milliseconds. Default 20000. */
+  stageTimeoutMs?: number;
 };
 
 export type UseSecondFactorResult = {
@@ -167,6 +324,7 @@ export function useSecondFactor(options: UseSecondFactorOptions = {}): UseSecond
   const strategy = chosen ?? options.strategy ?? "totp";
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState("");
+  const timeoutMs = options.stageTimeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS;
 
   const submit = async (code: string): Promise<TotpResult> => {
     if (loading) return { ok: false, error };
@@ -176,7 +334,7 @@ export function useSecondFactor(options: UseSecondFactorOptions = {}): UseSecond
     }
     setLoading(true);
     setError("");
-    const result = await submitSecondFactor({ signIn, setActive, code, strategy });
+    const result = await submitSecondFactor({ signIn, setActive, code, strategy, timeoutMs });
     if (!result.ok) setError(result.error);
     setLoading(false);
     return result;
@@ -192,7 +350,7 @@ export function useSecondFactor(options: UseSecondFactorOptions = {}): UseSecond
     }
     setLoading(true);
     setError("");
-    const result = await prepareSecondFactorIfNeeded({ signIn, strategy: prepareStrategy, factor });
+    const result = await prepareSecondFactorIfNeeded({ signIn, strategy: prepareStrategy, factor, timeoutMs });
     if (!result.ok) setError(result.error);
     setLoading(false);
     return result;

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";