@vvedantb/native-ui 0.6.1 → 0.8.0

package/README.md

@@ -23,6 +23,7 @@ Optional, only if you import those components:
 
 - `@gorhom/bottom-sheet` — `BottomSheetContainer`
 - `@react-native-community/datetimepicker` and `dayjs` — `DateTimeField`
+- `@clerk/clerk-expo`, `convex`, `expo-auth-session`, `expo-web-browser` and `expo-router` — `@vvedantb/native-ui/auth` (0.7.0). `expo-router` also for `@vvedantb/native-ui/expo-web-root`.
 - `react-native-svg` — the app marks (`APP_ICONS`, `Icon*`, `AppMark`, `AppWordmark`), `GoogleMark` and `PricingModal`. Apps with the icon peers above already have it: `lucide-react-native` and `@tabler/icons-react-native` both require it.
 
 Optional and loaded only when installed, so the package imports and runs without them:
@@ -67,7 +68,7 @@ The root entry exports everything. It still imports `BottomSheetContainer` and `
 | `@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`, `fontClass`, `cn`, `Colors` and the colour constants | none |
 | `@vvedantb/native-ui/floating` | `FloatingSurface`, `GlassSheetBackground`, `LiquidGlass`, `GlassBlurProvider`, `GlassBlurTarget`, `FloatingFAB`, `useReduceTransparency`, the floating metrics and styles | `expo-blur` (loader) |
-| `@vvedantb/native-ui/layout` | `ScreenContainer`, `SafeAreaContainer`, `PageTitle`, `PageHeader`, `StackPageHeader` (0.5.0) and their props types, `SectionLabel` (0.5.0), `SettingsSection`, `SettingsField`, `SettingsToggleRow`, `SettingsStack` | `expo-blur` (loader) |
+| `@vvedantb/native-ui/layout` | `ScreenContainer`, `SafeAreaContainer`, `PageTitle`, `PageHeader`, `StackPageHeader` (0.5.0) and their props types, `SectionLabel` (0.5.0), `SettingsSection`, `SettingsField`, `SettingsToggleRow`, `SettingsStack`, `MoreFromProjectV` and `FromProjectV` (0.8.0) | `expo-blur` (loader) |
 | `@vvedantb/native-ui/marketing` | `UpgradeToProCard`, `PricingModal` and the pricing types | none |
 | `@vvedantb/native-ui/ambient` | `AmbientBackground` | `expo-linear-gradient` (loader) |
 | `@vvedantb/native-ui/blur`, `/haptics` | the loaders | `expo-blur`, `expo-haptics` (loaders) |
@@ -75,10 +76,13 @@ 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/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) |
 
 "Loader" means the `require` inside `try` described above, so the entry bundles and runs without that peer. `@vvedantb/native-ui/gallery` imports the root entry; `@vvedantb/native-ui/ai-gallery` imports `/ai` only.
 
-The AI chat parts are only on `/ai`. Metro does not tree-shake by default, so on the root entry they would bundle into every app, with or without a chat.
+The AI chat parts are only on `/ai`, and the auth screens and Expo web root only on `/auth` and `/expo-web-root`. Metro does not tree-shake by default, so on the root entry they would bundle into every app, with or without a chat or sign-in.
 
 ```tsx
 import { FloatingTabBar } from "@vvedantb/native-ui/tab-bar";
@@ -93,18 +97,33 @@ The entries re-export the same source files, so they can be mixed: `NativeUiProv
 
 ## Expo / NativeWind
 
-Source-exported. Point Tailwind at the package so class names are generated, and set `darkMode: "class"` (see [Theme](#theme)):
+Source-exported. From 0.7.0 the preset sets up Tailwind for the package: it nests `nativewind/preset`, sets `darkMode: "class"` (see [Theme](#theme)), maps the Instrument Sans font classes and adds the colour keys the components and apps share. `nativeUiContent()` points Tailwind at the package source, at its real path, so class names are generated:
 
 ```js
 // tailwind.config.js
-darkMode: "class",
-content: [
-  "./app/**/*.{js,ts,tsx}",
-  "./components/**/*.{js,ts,tsx}",
-  "./node_modules/@vvedantb/native-ui/src/**/*.{js,ts,tsx}",
-],
+const { nativeUiPreset, nativeUiContent } = require("@vvedantb/native-ui/tailwind-preset");
+
+module.exports = {
+  content: ["./app/**/*.{js,ts,tsx}", "./components/**/*.{js,ts,tsx}", nativeUiContent()],
+  presets: [nativeUiPreset()],
+  // App colours, display fonts, keyframes and plugins (such as tailwindcss-animate) stay here.
+  theme: { extend: {} },
+};
 ```
 
+`nativeUiPreset(options)`:
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `darkMode` | `"class"` | `"media"` follows the system only. `ThemeToggle` and `setColorScheme` need `"class"`. |
+| `color` | `cssVar`, or `rgbAlpha` with `injectCssVariables` | Maps a variable name to a colour value. `cssVar` gives `var(--name)`, `hslVar` gives `hsl(var(--name))` and `rgbAlpha` gives `rgb(var(--name) / <alpha-value>)`. For another prefix, pass your own, such as ``(name) => `rgb(var(--color-${name}) / <alpha-value>)` ``. |
+| `injectCssVariables` | `false` | Writes every colour variable from `tokens.ts` and `palette.ts` as `r g b` channels, and `--radius` (16px), for light (`:root`) and dark (`.dark`, or the media query with `darkMode: "media"`). The app's `global.css` then needs no token block. |
+| `radiusVariable` | `injectCssVariables` | `rounded-lg`, `-md` and `-sm` from `var(--radius)`. |
+
+The colour keys are `background`, `foreground`, `border`, `input`, `ring`, `separator`, `surface` (`DEFAULT`, `foreground`, `secondary`, `tertiary`, `card`), `field` (`DEFAULT`, `placeholder`) and, each with `DEFAULT` and `foreground`, `primary`, `secondary`, `destructive`, `muted`, `accent`, `popover`, `card`, `danger`, `success`, `warning`, `default` and `overlay`. Each reads the variable of the same name (`surface.secondary` reads `--surface-secondary`; `muted.foreground` reads `--muted-foreground`). `borderWidth.hairline` is NativeWind's `hairlineWidth()`.
+
+Before 0.7.0, list the package in `content` by hand (`"./node_modules/@vvedantb/native-ui/src/**/*.{js,ts,tsx}"`) and set `darkMode: "class"`.
+
 Metro already resolves `node_modules`. In a pnpm monorepo, if a peer resolves to the wrong copy, add:
 
 ```js
@@ -116,7 +135,7 @@ config.resolver.nodeModulesPaths = [
 ];
 ```
 
-The app must define NativeWind tokens (`bg-surface`, `bg-secondary`, pink utilities) and Instrument Sans font classes (`font-instrument-sans-*`). Accent pink stays in the app stylesheet. `Button`, `Input`, `Textarea`, the `Select` trigger, `Switch`, `Checkbox`, `Badge`, `Tabs` and `PillTabs` take their colours from `tokens` and `palette`, so they do not need `primary`, `input` or other theme keys. From 0.3.3 so does component text (titles, descriptions, labels, rows, toasts): it no longer uses `text-foreground` or `text-muted-foreground`, which stay light-mode colours in dark mode when an app defines `foreground` with a nested `dark` key. Override those colours with `style`, not `className`. App text needs the same care: `tokens.color.foreground[scheme]` reads in both schemes. From 0.5.0 the `ListRow`, `DateTimeField` and `HeaderIconButton` fills are styles too, so `ThemeToggle` and the `StackPageHeader` back button follow the scheme.
+Without the preset, the app must define NativeWind tokens (`bg-surface`, `bg-secondary`, pink utilities) and Instrument Sans font classes (`font-instrument-sans-*`). Accent pink stays in the app stylesheet. `Button`, `Input`, `Textarea`, the `Select` trigger, `Switch`, `Checkbox`, `Badge`, `Tabs` and `PillTabs` take their colours from `tokens` and `palette`, so they do not need `primary`, `input` or other theme keys. From 0.3.3 so does component text (titles, descriptions, labels, rows, toasts): it no longer uses `text-foreground` or `text-muted-foreground`, which stay light-mode colours in dark mode when an app defines `foreground` with a nested `dark` key. Override those colours with `style`, not `className`. App text needs the same care: `tokens.color.foreground[scheme]` reads in both schemes. From 0.5.0 the `ListRow`, `DateTimeField` and `HeaderIconButton` fills are styles too, so `ThemeToggle` and the `StackPageHeader` back button follow the scheme.
 
 From 0.3.5 text that uses `font-instrument-sans-medium` or `-semibold` also sets `fontWeight` as a style (`typeStyle` in `src/controlStyles.ts`). Where an app maps every `font-instrument-sans-*` class to one family with no weight, as Expo web does, the class alone draws Regular. A weight without the face class does not pick the Instrument Sans Medium or Semibold file, so set both. From 0.3.13 every title in the package pairs the two, the internal primitives included, and `tests/fontWeight.test.ts` fails on a face class without its weight, a weight without its face class, or a bare Tailwind `font-medium`, `font-semibold` or `font-bold`.
 
@@ -136,6 +155,62 @@ fontFamily: {
 
 A class mapped to a family the browser does not have, such as `["System"]`, with no generic fallback draws in the browser default, often a serif.
 
+### Expo web root (0.7.0)
+
+`app/+html.tsx` can be one component:
+
+```tsx
+import { ExpoWebRoot } from "@vvedantb/native-ui/expo-web-root";
+
+export default function Root({ children }: { children: React.ReactNode }) {
+  return <ExpoWebRoot>{children}</ExpoWebRoot>;
+}
+```
+
+It renders `<html lang="en">`, the charset, `X-UA-Compatible` and viewport meta tags, `ScrollViewStyleReset` from `expo-router/html`, a body background style and `<body>`. Props: `lang`; `viewport` (`"native"`, the default, stops pinch-zoom; `"accessible"` allows it; both set `viewport-fit=cover`); `scrollReset` (default `true`); `lightBackground` and `darkBackground` (default `tokens.color.background`); `head` for more `<head>` nodes. The dark fill follows `prefers-color-scheme` and the `html.dark` class.
+
+## Auth (0.7.0)
+
+`@vvedantb/native-ui/auth` has the Clerk and Convex providers and a sign-in and sign-up screen. It needs `@clerk/clerk-expo`, `expo-auth-session`, `expo-web-browser` and `expo-router`, and `convex` when you pass a Convex client.
+
+```tsx
+// app/_layout.tsx
+import { useAuth } from "@clerk/clerk-expo";
+import { tokenCache } from "@clerk/clerk-expo/token-cache";
+import { AuthProviders } from "@vvedantb/native-ui/auth";
+
+<AuthProviders publishableKey={publishableKey} tokenCache={tokenCache} convex={convex} useAuth={useAuth}>
+  <Stack screenOptions={{ headerShown: false }} />
+</AuthProviders>
+```
+
+`AuthProviders` nests `ClerkProvider`, `ConvexProviderWithClerk` (only with `convex`) and `ClerkLoaded` (with `loaded`, default `true`). Without `convex` the children sit under Clerk only. `clerk={false}` gives a plain `ConvexProvider`, for UI preview builds. The app reads its own key; the component checks nothing.
+
+```tsx
+// app/(auth)/sign-in.tsx
+import { SignInScreen } from "@vvedantb/native-ui/auth";
+
+export default function SignIn() {
+  return <SignInScreen scheme="myapp" signUpHref="/sign-up" />;
+}
+
+// app/(auth)/sign-up.tsx
+import { SignUpScreen } from "@vvedantb/native-ui/auth";
+
+export default function SignUp() {
+  return <SignUpScreen scheme="myapp" signInHref="/sign-in" minPasswordLength={8} />;
+}
+```
+
+- Email and password, and "Continue with Google" (`useSSO`, `oauth_google`, redirect `AuthSession.makeRedirectUri({ scheme, path: redirectPath })`; `redirectPath` defaults to `"sso-callback"`). Sign-up sends an email code and checks it before the session starts.
+- On success: `onSuccess()`, or `router.replace(afterAuthHref, replaceOptions)` (default `"/"`; for example `replaceOptions={{ withAnchor: true }}`).
+- `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.
+- 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.
+
 ## Theme
 
 Wrap the tree (inside your colour-scheme provider):
@@ -227,6 +302,10 @@ From 0.3.12 a toast looks like the web `SonnerToaster` at its default density wi
 
 `@vvedantb/native-ui/gallery` exports `ParityGallery`, a screen that renders these components. Put it in a dev-only route to check them on a device.
 
+## More from Project V (0.8.0)
+
+`<MoreFromProjectV current="velth" />` is a settings section listing the other Project V phone apps (vibot, Verve, Velth, vmem, V Store). A row opens the app if installed, else V Store's home (`vstore://`), else its website. Add the other apps' schemes to `LSApplicationQueriesSchemes` (iOS) and `<queries>` (Android 11+), or `canOpenURL` returns `false`. `<FromProjectV />` (or `variant="footer"`) is a small "from Project V" line. `openProjectVApp(id, Linking, Platform.OS)` and `PROJECT_V_MOBILE_APPS` are exported for custom rows.
+
 ## App pieces (0.5.0)
 
 Components and props that the Verve, vibot and Velth apps need. They follow the rest of the package: Instrument Sans with its weight as a style, `tokens` and `palette` colours as styles in light and dark, a step up with larger text, 44 pt targets, and roles, names and states for VoiceOver and TalkBack.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@vvedantb/native-ui",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "license": "MIT",
-  "description": "Shared React Native / Expo UI primitives. Floating surfaces, forms, overlays, toasts, settings chrome, tab bar, AI chat parts and the family app marks.",
+  "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",
   "publishConfig": {
     "access": "public"
@@ -93,6 +93,19 @@
       "types": "./src/haptics.ts",
       "default": "./src/haptics.ts"
     },
+    "./auth": {
+      "types": "./src/entries/auth.ts",
+      "default": "./src/entries/auth.ts"
+    },
+    "./expo-web-root": {
+      "types": "./src/entries/expo-web-root.ts",
+      "default": "./src/entries/expo-web-root.ts"
+    },
+    "./tailwind-preset": {
+      "types": "./src/tailwind-preset.d.cts",
+      "require": "./src/tailwind-preset.cjs",
+      "default": "./src/tailwind-preset.cjs"
+    },
     "./package.json": "./package.json"
   },
   "types": "./src/index.ts",
@@ -108,6 +121,7 @@
     "prepack": "node -e \"require('node:fs').accessSync('src/index.ts')\""
   },
   "peerDependencies": {
+    "@clerk/clerk-expo": "*",
     "@expo/vector-icons": "*",
     "@gorhom/bottom-sheet": ">=5",
     "@react-native-community/datetimepicker": "*",
@@ -117,11 +131,14 @@
     "@tabler/icons-react-native": "*",
     "class-variance-authority": ">=0.7.0",
     "clsx": ">=2.0.0",
+    "convex": "*",
     "dayjs": ">=1.11.0",
+    "expo-auth-session": "*",
     "expo-blur": "*",
     "expo-haptics": "*",
     "expo-linear-gradient": "*",
     "expo-router": "*",
+    "expo-web-browser": "*",
     "lucide-react-native": "*",
     "nativewind": ">=4.0.0",
     "react": ">=19.0.0",
@@ -133,15 +150,24 @@
     "tailwind-merge": ">=2.0.0"
   },
   "peerDependenciesMeta": {
+    "@clerk/clerk-expo": {
+      "optional": true
+    },
     "@gorhom/bottom-sheet": {
       "optional": true
     },
     "@react-native-community/datetimepicker": {
       "optional": true
     },
+    "convex": {
+      "optional": true
+    },
     "dayjs": {
       "optional": true
     },
+    "expo-auth-session": {
+      "optional": true
+    },
     "expo-blur": {
       "optional": true
     },
@@ -154,6 +180,9 @@
     "expo-router": {
       "optional": true
     },
+    "expo-web-browser": {
+      "optional": true
+    },
     "react-native-svg": {
       "optional": true
     }

package/src/ExpoWebRoot.tsx

@@ -0,0 +1,81 @@
+import type { ReactNode } from "react";
+import { ScrollViewStyleReset } from "expo-router/html";
+import { tokens } from "./tokens";
+
+/** `"native"` stops pinch-zoom so the page acts like the app; `"accessible"` allows it (WCAG 1.4.4). Both cover the notch. */
+export type ExpoWebRootViewport = "native" | "accessible";
+
+export const EXPO_WEB_VIEWPORT: Record<ExpoWebRootViewport, string> = {
+  native: "width=device-width,initial-scale=1,minimum-scale=1,maximum-scale=1.00001,viewport-fit=cover",
+  accessible: "width=device-width, initial-scale=1.0, viewport-fit=cover",
+};
+
+export type ExpoWebRootProps = {
+  children: ReactNode;
+  /** `<html lang>`. Default `"en"`. */
+  lang?: string;
+  /** Default `"native"`. */
+  viewport?: ExpoWebRootViewport;
+  /** `ScrollViewStyleReset`: no body scroll, so `ScrollView` works as on native. Default `true`. */
+  scrollReset?: boolean;
+  /** Body fill in light. Default `tokens.color.background.light`. */
+  lightBackground?: string;
+  /** Body fill in dark. Default `tokens.color.background.dark`. */
+  darkBackground?: string;
+  /** More `<head>` nodes, after the defaults. */
+  head?: ReactNode;
+};
+
+/**
+ * The body fill as raw CSS, so the background does not flash in dark mode
+ * before the app paints. Dark follows the system, and the NativeWind `dark`
+ * class on `<html>` when the app sets the scheme (`darkMode: "class"`).
+ */
+export function expoWebBackgroundCss(light: string, dark: string): string {
+  return `
+body {
+  background-color: ${light};
+}
+@media (prefers-color-scheme: dark) {
+  body {
+    background-color: ${dark};
+  }
+}
+html.dark body {
+  background-color: ${dark};
+}`;
+}
+
+/**
+ * The root HTML for Expo web static rendering. Use it as the whole of
+ * `app/+html.tsx`:
+ *
+ *   export default function Root({ children }: { children: React.ReactNode }) {
+ *     return <ExpoWebRoot>{children}</ExpoWebRoot>;
+ *   }
+ *
+ * Runs in Node during the static render, with no DOM.
+ */
+export function ExpoWebRoot({
+  children,
+  lang = "en",
+  viewport = "native",
+  scrollReset = true,
+  lightBackground = tokens.color.background.light,
+  darkBackground = tokens.color.background.dark,
+  head,
+}: ExpoWebRootProps) {
+  return (
+    <html lang={lang}>
+      <head>
+        <meta charSet="utf-8" />
+        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
+        <meta name="viewport" content={EXPO_WEB_VIEWPORT[viewport]} />
+        {scrollReset ? <ScrollViewStyleReset /> : null}
+        <style dangerouslySetInnerHTML={{ __html: expoWebBackgroundCss(lightBackground, darkBackground) }} />
+        {head}
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}

package/src/ai/code-block.tsx

@@ -27,7 +27,7 @@ export type CodeBlockCopyButtonProps = {
 /** Ghost copy button: the copy icon, then a check for `timeout` after a copy. */
 export function CodeBlockCopyButton({ code, onCopy, timeout = 2000, label = "Copy code" }: CodeBlockCopyButtonProps) {
   const [copied, setCopied] = useState(false);
-  const timer = useRef<number | undefined>(undefined);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
 
   useEffect(() => () => clearTimeout(timer.current), []);
 

package/src/auth/AuthProviders.tsx

@@ -0,0 +1,55 @@
+import type { ReactNode } from "react";
+import { ClerkLoaded, ClerkProvider, useAuth as useClerkAuth, type TokenCache } from "@clerk/clerk-expo";
+import { ConvexProvider, type ConvexReactClient } from "convex/react";
+import { ConvexProviderWithClerk } from "convex/react-clerk";
+
+export type AuthProvidersProps = {
+  children: ReactNode;
+  /** The Clerk publishable key. The app reads it from its own config; this component does not check it. */
+  publishableKey?: string;
+  /** `tokenCache` from `@clerk/clerk-expo/token-cache`, so the session survives a restart. */
+  tokenCache?: TokenCache;
+  /** A Convex client. Without one, the children sit under Clerk only (vmem). */
+  convex?: ConvexReactClient | null;
+  /** `useAuth` from `@clerk/clerk-expo`, for `ConvexProviderWithClerk`. Default: the one this package imports. */
+  useAuth?: typeof useClerkAuth;
+  /** Wrap the children in `ClerkLoaded`, so they wait for the session. Default `true`. */
+  loaded?: boolean;
+  /**
+   * Default `true`. `false` drops Clerk: the children sit under a plain
+   * `ConvexProvider` (or nothing without `convex`), as the web
+   * `ConvexClerkProvider` does for UI preview builds.
+   */
+  clerk?: boolean;
+};
+
+/**
+ * The Clerk and Convex providers from the apps' root `_layout.tsx`:
+ * `ClerkProvider` › `ConvexProviderWithClerk` (with `convex`) › `ClerkLoaded`
+ * (with `loaded`) › children.
+ */
+export function AuthProviders({
+  children,
+  publishableKey,
+  tokenCache,
+  convex,
+  useAuth = useClerkAuth,
+  loaded = true,
+  clerk = true,
+}: AuthProvidersProps) {
+  if (!clerk) {
+    return convex ? <ConvexProvider client={convex}>{children}</ConvexProvider> : <>{children}</>;
+  }
+  const inner = loaded ? <ClerkLoaded>{children}</ClerkLoaded> : children;
+  return (
+    <ClerkProvider publishableKey={publishableKey} tokenCache={tokenCache}>
+      {convex ? (
+        <ConvexProviderWithClerk client={convex} useAuth={useAuth}>
+          {inner}
+        </ConvexProviderWithClerk>
+      ) : (
+        inner
+      )}
+    </ClerkProvider>
+  );
+}

package/src/auth/AuthScreen.tsx

@@ -0,0 +1,97 @@
+import type { ReactNode } from "react";
+import { KeyboardAvoidingView, Platform, ScrollView, StyleSheet, Text, View } from "react-native";
+import { cn } from "../cn";
+import { textStyle, typeStyle } from "../controlStyles";
+import { palette } from "../palette";
+import { tokens } from "../tokens";
+import { useScheme } from "../useScheme";
+
+export type AuthScreenProps = {
+  title: string;
+  subtitle?: string;
+  children: ReactNode;
+  /** Above the title, such as an app mark. App brand chrome goes here. */
+  header?: ReactNode;
+  /** Below the form, such as the "Don't have an account?" row. */
+  footer?: ReactNode;
+  testID?: string;
+  className?: string;
+};
+
+/**
+ * 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.
+ */
+export function AuthScreen({ title, subtitle, children, header, footer, testID, className }: AuthScreenProps) {
+  const scheme = useScheme();
+  return (
+    <KeyboardAvoidingView
+      behavior={Platform.OS === "ios" ? "padding" : "height"}
+      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)}
+        keyboardShouldPersistTaps="handled"
+      >
+        <View className="w-full max-w-sm self-center gap-6">
+          {header}
+          <View className="gap-2">
+            <Text
+              accessibilityRole="header"
+              className="font-instrument-sans-semibold text-2xl"
+              style={[textStyle("foreground", scheme), typeStyle("semibold")]}
+            >
+              {title}
+            </Text>
+            {subtitle ? (
+              <Text className="font-instrument-sans text-base" style={textStyle("muted", scheme)}>
+                {subtitle}
+              </Text>
+            ) : null}
+          </View>
+          <View className="gap-4">{children}</View>
+          {footer ? <View className="flex-row flex-wrap items-center justify-center gap-1">{footer}</View> : null}
+        </View>
+      </ScrollView>
+    </KeyboardAvoidingView>
+  );
+}
+
+/** A separator, "or", a separator: between Google and the email fields. */
+export function OrDivider({ label = "or" }: { label?: string }) {
+  const scheme = useScheme();
+  const line = { height: StyleSheet.hairlineWidth, backgroundColor: tokens.color.separator[scheme] };
+  return (
+    <View
+      className="flex-row items-center gap-3"
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+    >
+      <View className="flex-1" style={line} />
+      <Text className="font-instrument-sans text-sm" style={textStyle("muted", scheme)}>
+        {label}
+      </Text>
+      <View className="flex-1" style={line} />
+    </View>
+  );
+}
+
+/** An inline error under a form, read out when it appears. Nothing without a message. */
+export function FieldError({ message, testID }: { message?: string | null; testID?: string }) {
+  const scheme = useScheme();
+  if (!message) return null;
+  return (
+    <Text
+      testID={testID}
+      accessibilityLiveRegion="polite"
+      accessibilityRole="alert"
+      className="font-instrument-sans text-sm"
+      style={{ color: palette.danger[scheme] }}
+    >
+      {message}
+    </Text>
+  );
+}

package/src/auth/GoogleSignInButton.tsx

@@ -0,0 +1,116 @@
+import { useEffect, useState } from "react";
+import { Platform } from "react-native";
+import { useSSO } from "@clerk/clerk-expo";
+import * as AuthSession from "expo-auth-session";
+import * as WebBrowser from "expo-web-browser";
+import { useRouter } from "expo-router";
+import { GoogleMark } from "../brand/GoogleMark";
+import { Button, type ButtonProps } from "../Button";
+import { toast } from "../toastStore";
+import { authErrorMessage } from "./authErrors";
+
+// Completes the Google browser session when the app reopens on the redirect.
+WebBrowser.maybeCompleteAuthSession();
+
+export const GOOGLE_ERROR_MESSAGE = "Could not continue with Google";
+
+export type AuthNavigationOptions = {
+  /** Where to go after a session starts. Default `"/"`. */
+  afterAuthHref?: string;
+  /** Passed to `router.replace`, such as `{ withAnchor: true }`. */
+  replaceOptions?: object;
+  /** Called after a session starts, in place of `router.replace`. */
+  onSuccess?: () => void;
+};
+
+export type GoogleSignInOptions = AuthNavigationOptions & {
+  /** The app URL scheme, such as `"vibot"`, for the redirect `scheme://sso-callback`. */
+  scheme: string;
+  /** Default `"sso-callback"`. */
+  redirectPath?: string;
+  /** Called with a message for the user. Default: an error toast. */
+  onError?: (message: string) => void;
+};
+
+/** Warms the Android custom tab while the screen is up, as the Expo guide suggests. */
+export function useWarmUpBrowser() {
+  useEffect(() => {
+    if (Platform.OS !== "android") return;
+    void WebBrowser.warmUpAsync().catch(() => {});
+    return () => {
+      void WebBrowser.coolDownAsync().catch(() => {});
+    };
+  }, []);
+}
+
+/** Starts the Google flow, sets the session and navigates. Returns `[start, busy]`. */
+export function useGoogleSignIn({
+  scheme,
+  redirectPath = "sso-callback",
+  afterAuthHref = "/",
+  replaceOptions,
+  onSuccess,
+  onError,
+}: GoogleSignInOptions): [() => Promise<void>, boolean] {
+  const { startSSOFlow } = useSSO();
+  const router = useRouter();
+  const [busy, setBusy] = useState(false);
+  const start = async () => {
+    if (busy) return;
+    setBusy(true);
+    try {
+      const { createdSessionId, setActive } = await startSSOFlow({
+        strategy: "oauth_google",
+        redirectUrl: AuthSession.makeRedirectUri({ scheme, path: redirectPath }),
+      });
+      // No session: the user closed the browser, or more steps are needed.
+      if (createdSessionId && setActive) {
+        await setActive({ session: createdSessionId });
+        if (onSuccess) onSuccess();
+        else router.replace(afterAuthHref, replaceOptions);
+      }
+    } catch (error) {
+      const message = authErrorMessage(error, GOOGLE_ERROR_MESSAGE);
+      if (onError) onError(message);
+      else toast.error(message);
+    } finally {
+      setBusy(false);
+    }
+  };
+  return [start, busy];
+}
+
+export type GoogleSignInButtonProps = GoogleSignInOptions &
+  Omit<ButtonProps, "onPress" | "children" | "leftIcon" | "loading"> & {
+    /** Default "Continue with Google". */
+    label?: string;
+  };
+
+/** An outline button with the Google mark that runs `useGoogleSignIn`. */
+export function GoogleSignInButton({
+  scheme,
+  redirectPath,
+  afterAuthHref,
+  replaceOptions,
+  onSuccess,
+  onError,
+  label = "Continue with Google",
+  testID = "google-sign-in",
+  variant = "outline",
+  ...props
+}: GoogleSignInButtonProps) {
+  useWarmUpBrowser();
+  const [start, busy] = useGoogleSignIn({ scheme, redirectPath, afterAuthHref, replaceOptions, onSuccess, onError });
+  return (
+    <Button
+      {...props}
+      testID={testID}
+      variant={variant}
+      leftIcon={<GoogleMark />}
+      loading={busy}
+      onPress={() => void start()}
+    >
+      {label}
+    </Button>
+  );
+}