@ramonclaudio/create-vexpo 0.1.3 → 0.1.5

package/dist/templates/default/.maestro/tour.yaml

@@ -0,0 +1,294 @@
+# Signed-in app tour: walk the authenticated surface without mutating auth.
+# Search -> Settings -> Preferences (appearance + haptics) -> Privacy
+# (analytics toggle) -> Profile (edit + save bio) -> Sessions, then screenshot.
+#
+# Requires an existing signed-in session: this flow launches WITHOUT clearState
+# and asserts the home tab. It does NOT sign in. Run `auth.yaml` first to seed a
+# session. On EAS folder runs Maestro executes flows alphabetically, and
+# `app-tour` sorts BEFORE `auth`, so this file is named `tour.yaml` ('t' > 'a')
+# to guarantee it runs AFTER auth.yaml. As a safety net the flow fails fast with
+# a clear message if it lands on the sign-in screen instead of the tabs.
+#
+# @expo/ui SwiftUI driving notes (same as auth.yaml/launch.yaml):
+#   - Inner SwiftUI Text testIDs do NOT surface to Maestro; only Host roots and
+#     real controls (TextField, Button, Toggle, Picker) do. Assert screens by
+#     their Host `id`, assert static copy by `text`.
+#   - Capsule list rows hold a Spacer in the middle, so tap them by label TEXT,
+#     not id. ProminentButtons and full-content Buttons hold content in the
+#     center, so tap those by `id`.
+#   - Segmented Picker segments put their label in the middle: tap by label TEXT
+#     (`tapOn: "Dark"`), not by the inner Text testID.
+#   - Toggles are real controls: tap by `id`.
+#   - The keyboard covers lower fields. Forms use
+#     scrollDismissesKeyboard("interactively"), so a downward swipe dismisses it
+#     (hideKeyboard is flaky on iOS, don't use it).
+#   - waitForAnimationToEnd between navigations; assert-then-tap for tab bars;
+#     extendedWaitUntil with generous timeouts after anything that hits Convex.
+#
+# Env vars:
+#   MAESTRO_APP_ID   bundle id (EAS injects from EXPO_PUBLIC_APP_BUNDLE_ID)
+#
+# Run locally (needs a JDK on PATH, and a signed-in simulator session):
+#   MAESTRO_APP_ID=$(grep '^EXPO_PUBLIC_APP_BUNDLE_ID=' .env.local | cut -d= -f2) \
+#     maestro test .maestro/tour.yaml
+#   Or run the whole suite in order (auth seeds the session for the tour):
+#   MAESTRO_APP_ID=... maestro test .maestro/
+# Run on EAS: via `.eas/workflows/e2e-tests.yml` (workflow_dispatch only).
+appId: ${MAESTRO_APP_ID}
+---
+# Resume on whatever was last open (no clearState). Give the JS bundle and the
+# auth guard time to settle.
+- launchApp
+- waitForAnimationToEnd:
+    timeout: 15000
+
+# Dev-client builds may show the one-time developer-menu intro sheet after a
+# relaunch. Drag it down to dismiss. Release builds skip this block.
+- runFlow:
+    when:
+      visible: "This is the developer menu.*"
+    commands:
+      - swipe:
+          start: 50%, 55%
+          end: 50%, 95%
+      - waitForAnimationToEnd:
+          timeout: 5000
+
+# The intro sheet can appear late while Metro is still bundling, so check a
+# second time after the bundle settles.
+- waitForAnimationToEnd:
+    timeout: 10000
+- runFlow:
+    when:
+      visible: "This is the developer menu.*"
+    commands:
+      - swipe:
+          start: 50%, 55%
+          end: 50%, 95%
+      - waitForAnimationToEnd:
+          timeout: 5000
+
+# Safety net: if the session is missing we land on sign-in. Fail loudly so the
+# failure points at "run auth.yaml first", not at a mystery missing element.
+- assertNotVisible:
+    id: "sign-in-screen"
+
+# launchApp may resume on a nested screen. Get back to the tabs root via the
+# Home tab, then assert the home Host id. Native tab taps can be flaky, so
+# assert-then-tap.
+- assertVisible: "Home"
+- tapOn: "Home"
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "home-screen"
+    timeout: 20000
+
+# --- 1. Search tab -------------------------------------------------------
+# Search is a native large-title Stack.SearchBar above a Host list. Tap the tab,
+# assert the screen root, then drive the search field by its placeholder.
+- assertVisible: "Search"
+- tapOn: "Search"
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "search-screen"
+    timeout: 15000
+
+# Tap the native search field (matched by its placeholder), type a query, then
+# swipe-dismiss the keyboard. The list filters live; assert the screen survives.
+- tapOn: "Search screens"
+- inputText: "privacy"
+- swipe:
+    start: 50%, 35%
+    end: 50%, 85%
+- waitForAnimationToEnd:
+    timeout: 3000
+- assertVisible:
+    id: "search-screen"
+# A result for "privacy" should rank. The result row carries a stable id.
+- assertVisible:
+    id: "search-result-privacy"
+# Active search replaces the tab bar, close it ("Close" a11y label) so the
+# tabs come back before navigating on.
+- tapOn: "Close"
+- waitForAnimationToEnd:
+    timeout: 3000
+
+# --- 2. Settings tab -----------------------------------------------------
+- assertVisible: "Settings"
+- tapOn: "Settings"
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "settings-screen"
+    timeout: 15000
+
+# --- 3. Preferences ------------------------------------------------------
+# Open via the settings row. Capsule row with a Spacer, so tap by label text.
+- assertVisible: "Preferences"
+- tapOn: "Preferences"
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "preferences-screen"
+    timeout: 15000
+- assertVisible: "APPEARANCE"
+
+# Appearance is a segmented Picker. Segment labels live in the middle of each
+# segment, so tap by text: System -> Dark -> back to System.
+- tapOn: "Dark"
+- waitForAnimationToEnd:
+    timeout: 3000
+- tapOn: "System"
+- waitForAnimationToEnd:
+    timeout: 3000
+
+# Haptics is a real Toggle in a capsule row, so tap by id. Toggle off, toggle
+# back on. The screen redraws under it but the Host id stays stable.
+- assertVisible: "HAPTICS"
+- tapOn:
+    id: "preferences-haptics"
+- waitForAnimationToEnd:
+    timeout: 2000
+- tapOn:
+    id: "preferences-haptics"
+- waitForAnimationToEnd:
+    timeout: 2000
+
+# Back to Settings.
+- swipe:
+    start: 2%, 50%
+    end: 90%, 50%
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "settings-screen"
+    timeout: 15000
+
+# --- 4. Privacy ----------------------------------------------------------
+# Open via the settings row (capsule, tap by text).
+- assertVisible: "Privacy"
+- tapOn: "Privacy"
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "privacy-screen"
+    timeout: 15000
+
+# Share Analytics is a real Toggle in a capsule row, so tap by id. This is a
+# persisted preference (useShareAnalytics). Flip it off, assert the screen
+# holds, flip it back on so the tour leaves no state behind.
+- assertVisible: "Share Analytics"
+- tapOn:
+    id: "privacy-share-analytics"
+- waitForAnimationToEnd:
+    timeout: 2000
+- assertVisible:
+    id: "privacy-screen"
+- tapOn:
+    id: "privacy-share-analytics"
+- waitForAnimationToEnd:
+    timeout: 2000
+
+# Back to Settings.
+- swipe:
+    start: 2%, 50%
+    end: 90%, 50%
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "settings-screen"
+    timeout: 15000
+
+# --- 5. Profile ----------------------------------------------------------
+# Open via the settings profile row. Full-content Button, so tap by id.
+- tapOn:
+    id: "settings-profile"
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "profile-screen"
+    timeout: 15000
+
+# Edit the Bio field. It is a plain TextField (no newPassword autofill, no eye
+# toggle needed). Tap to focus, append text so `hasChanges` flips true, then
+# swipe-dismiss the keyboard. The avatar button exists but the image picker
+# opens a system sheet Maestro can't drive, so it is left untouched.
+- tapOn:
+    id: "profile-bio"
+- inputText: " e2e tour"
+- swipe:
+    start: 50%, 35%
+    end: 50%, 85%
+- waitForAnimationToEnd:
+    timeout: 3000
+
+# Save. The inline Save button only renders once `hasChanges` is true and holds
+# its label in the center, so tap by id. (A toolbar Save button also exists, but
+# the inline ProminentButton is the reliable target.)
+- scrollUntilVisible:
+    element:
+      id: "profile-save"
+    direction: DOWN
+- tapOn:
+    id: "profile-save"
+
+# updateProfile hits Convex. SuccessText is an inner Text (no id surface), so
+# prove the save landed structurally: the inline Save button only renders while
+# hasChanges is true, so it disappears after a successful save.
+- extendedWaitUntil:
+    notVisible:
+      id: "profile-save"
+    timeout: 20000
+- assertVisible: ".*e2e tour.*"
+- assertVisible: "Saved"
+
+# Back to Settings.
+- swipe:
+    start: 2%, 50%
+    end: 90%, 50%
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "settings-screen"
+    timeout: 15000
+
+# --- 6. Sessions ---------------------------------------------------------
+# Open via the settings row (capsule, tap by text).
+- assertVisible: "Sessions"
+- tapOn: "Sessions"
+- waitForAnimationToEnd:
+    timeout: 5000
+
+# listSessions hits Convex; the list renders after the network round-trip.
+- extendedWaitUntil:
+    visible:
+      id: "sessions-screen"
+    timeout: 20000
+# The signed-in device row carries a "This device" badge (text surfaces).
+- extendedWaitUntil:
+    visible: "This device"
+    timeout: 20000
+
+# Back to Settings.
+- swipe:
+    start: 2%, 50%
+    end: 90%, 50%
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "settings-screen"
+    timeout: 15000
+
+- takeScreenshot: app-tour-final

package/dist/templates/default/.maestro/zz-delete-restore.yaml

@@ -0,0 +1,174 @@
+# Account soft-delete -> restore journey: delete the account from Settings, get
+# kicked to sign-in, sign back in within the 30-day grace window, land on the
+# restore screen, restore, and end up authed on home again.
+#
+# This deployment soft-deletes: `users.deleteAccount` stamps `deletedAt` instead
+# of hard-deleting, then signs out (see src/hooks/use-delete-account.ts). On the
+# next sign-in `getMe` returns the tombstoned user, so the `isAccountDeleted`
+# gate in (app)/_layout.tsx swaps the whole authed tree for `restore-account`.
+# Tapping Restore clears the tombstone and `router.replace("/")` drops us back on
+# the tabs root. Because this flow ends with the account restored and signed in,
+# it leaves the shared test account exactly as auth.yaml left it. The `zz-`
+# prefix makes it sort LAST in alphabetical folder runs so nothing downstream
+# inherits a half-deleted account.
+#
+# Face ID note: `deleteAccount` gates on LocalAuthentication.authenticateAsync
+# before the mutation. The simulator must have a matched/enrolled biometric
+# (Features > Face ID > Enrolled, then Matching Face after the prompt) or the
+# delete silently no-ops (`if (!result.success) return`). On EAS the device
+# profile handles this; locally, trigger "Matching Face" if the run stalls at
+# the delete step.
+#
+# Same @expo/ui SwiftUI conventions as auth.yaml: `testID` maps to the native
+# accessibilityIdentifier and surfaces to Maestro as `resource-id`, so id-based
+# asserts/taps resolve. Driving notes carry over:
+#   - Inner SwiftUI Text testIDs do NOT surface (Host roots and real controls
+#     do), so assert screens by Host id and static copy by its text.
+#   - Capsule rows hold their label left with a Spacer, so tap them by label
+#     text. ProminentButton centers its content, so tap it by id.
+#   - The delete confirm is a native Alert action; tap it by its exact label
+#     "Delete Account" (capital A), distinct from the row's "Delete account".
+#   - Dismiss the keyboard with a downward swipe, never hideKeyboard.
+#   - SecureField + strong-password autofill swallows typed input, so reveal via
+#     the `-visibility` eye toggle (which auto-focuses) before typing.
+#   - waitForAnimationToEnd between navigations; extendedWaitUntil after any
+#     live Convex network call (sign-in, delete, restore).
+#
+# Env vars (MUST match the account auth.yaml created and signed into):
+#   MAESTRO_APP_ID        bundle id (EAS injects from EXPO_PUBLIC_APP_BUNDLE_ID)
+#   MAESTRO_TEST_EMAIL    the same email auth.yaml signed in with
+#   MAESTRO_TEST_PASSWORD the same password (at least 10 chars)
+#
+# Requires a signed-in session: this runs AFTER auth.yaml/tour.yaml leave the
+# app authed, so it launches WITHOUT clearState. Runs LAST in folder order.
+#
+# Run locally (needs a JDK on PATH; run auth.yaml first to seed the session):
+#   MAESTRO_APP_ID=$(grep '^EXPO_PUBLIC_APP_BUNDLE_ID=' .env.local | cut -d= -f2) \
+#     MAESTRO_TEST_EMAIL="e2e+...@example.com" \
+#     MAESTRO_TEST_PASSWORD="maestro-test-pw" \
+#     maestro test .maestro/zz-delete-restore.yaml
+# Run on EAS: via `.eas/workflows/e2e-tests.yml` (folder run, sorts last).
+appId: ${MAESTRO_APP_ID}
+---
+# Resume the signed-in session left by auth.yaml. No clearState: this flow
+# depends on the live session and the seeded account.
+- launchApp
+- waitForAnimationToEnd:
+    timeout: 15000
+
+# Dev-client builds may show the one-time developer-menu intro sheet after a
+# relaunch. Drag it down to dismiss. Release builds skip this block.
+- runFlow:
+    when:
+      visible: "This is the developer menu.*"
+    commands:
+      - swipe:
+          start: 50%, 55%
+          end: 50%, 95%
+      - waitForAnimationToEnd:
+          timeout: 5000
+
+# The intro sheet can appear late while Metro is still bundling, so check a
+# second time after the bundle settles.
+- waitForAnimationToEnd:
+    timeout: 10000
+- runFlow:
+    when:
+      visible: "This is the developer menu.*"
+    commands:
+      - swipe:
+          start: 50%, 55%
+          end: 50%, 95%
+      - waitForAnimationToEnd:
+          timeout: 5000
+
+# Authenticated entry: the tabs root mounts on home.
+- extendedWaitUntil:
+    visible:
+      id: "home-screen"
+    timeout: 20000
+
+# Into Settings. Native tab taps can be flaky, so assert-then-tap.
+- assertVisible: "Settings"
+- tapOn: "Settings"
+- waitForAnimationToEnd:
+    timeout: 5000
+- extendedWaitUntil:
+    visible:
+      id: "settings-screen"
+    timeout: 15000
+
+# Delete the account. The row is a destructive capsule (label left, Spacer
+# center), so tap by text.
+- scrollUntilVisible:
+    element:
+      id: "settings-delete-account"
+    direction: DOWN
+- tapOn: "Delete account"
+- waitForAnimationToEnd:
+    timeout: 3000
+
+# Confirm in the native Alert. The action label is "Delete Account" (capital A),
+# distinct from the row's "Delete account". This triggers the Face ID gate (see
+# header) then the soft-delete mutation and sign-out.
+- assertVisible: "Delete Account"
+- tapOn: "Delete Account"
+
+# Soft-delete signs the user out, so the unauthenticated guard mounts the auth
+# group and lands on sign-in. Generous timeout: live network call + Face ID.
+- extendedWaitUntil:
+    visible:
+      id: "sign-in-screen"
+    timeout: 30000
+
+# Sign back in WITHIN the grace window with the same credentials. Method toggle
+# defaults to Email.
+- tapOn:
+    id: "sign-in-email"
+- inputText: ${MAESTRO_TEST_EMAIL}
+- swipe:
+    start: 50%, 35%
+    end: 50%, 85%
+# Strong-password autofill dodge: reveal via the eye toggle, which auto-focuses.
+- tapOn:
+    id: "sign-in-email-password-visibility"
+- waitForAnimationToEnd:
+    timeout: 3000
+- tapOn:
+    id: "sign-in-email-password"
+- inputText: ${MAESTRO_TEST_PASSWORD}
+- swipe:
+    start: 50%, 35%
+    end: 50%, 85%
+- scrollUntilVisible:
+    element:
+      id: "sign-in-submit"
+    direction: DOWN
+- tapOn:
+    id: "sign-in-submit"
+
+# Soft-deleted within the grace window: `getMe` returns the tombstoned user, so
+# the isAccountDeleted gate routes to restore-account instead of the tabs.
+# Generous timeout: live network call.
+- extendedWaitUntil:
+    visible:
+      id: "restore-account-screen"
+    timeout: 30000
+
+# Assert the grace-window copy by a stable text fragment. The full line reads
+# "Your account is set to be permanently deleted on <date>. Restore now to keep
+# your account and all of its data." Match the date-independent phrase.
+- assertVisible: ".*permanently deleted on.*"
+
+# Restore. The button is a ProminentButton (content centered), so tap by id.
+- tapOn:
+    id: "restore-account-restore"
+
+# Restore clears the tombstone and router.replace("/") drops us back on the tabs
+# root. Generous timeout: live network call.
+- extendedWaitUntil:
+    visible:
+      id: "home-screen"
+    timeout: 30000
+
+- takeScreenshot: delete-restore-final

package/dist/templates/default/AGENTS.md

@@ -76,8 +76,9 @@ rebrand` fills them in. App Review will reject builds with placeholder
 - **Pre-approved commands:** `.claude/settings.json` allows read-only
   `git`/`expo`/`eas`/`convex`/`vexpo` calls + the project's `npm run`
   scripts (`typecheck`, `lint`, `test`, `format`, `dev`, `fp`) without
-  per-step permission prompts. Destructive ops (`git push`, `git reset`,
-  `npm install`, `expo deploy`) still ask.
+  per-step permission prompts. The file carries only an allowlist, no
+  denylist, so anything not on it (`git push`, `git reset`, `npm install`,
+  `expo deploy`, and the rest) prompts by default.
 - **EAS Convex bootstrap:** `eas integrations:convex:connect` is the
   upstream SDK 56 path for provisioning a Convex backend, writing
   `CONVEX_DEPLOY_KEY` + `EXPO_PUBLIC_CONVEX_URL`, and registering the env

package/dist/templates/default/DESIGN.md

@@ -91,7 +91,7 @@ Calm, monochrome, native. The vexpo system pairs a shadcn neutral palette (prese
 
 The brand commits to Geist Variable as the single typeface for both UI and marketing assets. Color carries no brand meaning. `destructive` is the only chromatic token, reserved for irreversible actions and validation errors. Brand expression flows through type weight, spacing, rounding, and the iOS material system.
 
-Ground truth lives in `constants/theme.ts` (color palette as `DynamicColorIOS`), `constants/layout.ts` (spacing, font sizes, line heights, fonts), and `constants/ui.ts` (opacity, materials, shadows, durations, sizes). The tokens here are the public contract for agents and contributors. The constants files are the implementation.
+Ground truth lives in `constants/theme.ts` (color palette as `DynamicColorIOS`), `constants/layout.ts` (spacing, font sizes, line heights, fonts), `constants/ui.ts` (opacity, shadows, durations, sizes), and `components/ui/material.tsx` (the `BLUR_INTENSITY`, `BLUR_TINT`, and `GLASS_STYLE` maps that drive each material variant). The tokens here are the public contract for agents and contributors. The constants files are the implementation.
 
 ## Colors
 
@@ -214,7 +214,7 @@ Depth is signaled by surface tint and the iOS material system, not by drop shado
 
 Materials apply a vibrancy effect that lets background content show through with controlled blur and saturation. Apple's HIG calls this the "navigation layer" and explicitly reserves it for chrome. Don't put materials on form sections or content cards.
 
-The blur intensity values are calibrated. Don't lower them. The 35% tint overlay on the `BlurView` fallback path is also calibrated, the smallest tint that still reads as the requested color while preserving the blur.
+The blur intensity values (`ultraThin` 30, `thin` 50, `regular` 70, `thick` 90, `chrome` 100) live in the `BLUR_INTENSITY` map in `components/ui/material.tsx`. They are calibrated. Don't lower them. The 35% tint overlay on the `BlurView` fallback path is also calibrated, the smallest tint that still reads as the requested color while preserving the blur.
 
 ## Shapes / Radius
 
@@ -254,53 +254,53 @@ The system uses `@expo/ui/swift-ui` primitives exclusively for native rendering.
 
 ### Native primitives (use directly)
 
-| Primitive                   | What it is                                                                    | Where it lands                         |
-| :-------------------------- | :---------------------------------------------------------------------------- | :------------------------------------- |
-| `Host`                      | SwiftUI host view, top-level wrapper for any screen using `@expo/ui/swift-ui` | Every screen root                      |
-| `VStack` / `HStack`         | SwiftUI stacks with spacing + alignment                                       | Layout primitives                      |
-| `Form` / `Section`          | Native iOS Form with grouped sections                                         | Settings, profile editor, preferences  |
-| `Picker`                    | Segmented or wheel picker (use `pickerStyle("segmented")` for inline)         | Theme mode, motion preference          |
-| `Toggle`                    | Native iOS toggle                                                             | Boolean preferences                    |
-| `Button`                    | Native button with role variants (default, cancel, destructive)               | All actions                            |
-| `TextField` / `SecureField` | Native text input                                                             | Forms                                  |
-| `Text`                      | SwiftUI text with modifier composition                                        | All typography                         |
-| `Image`                     | SF Symbol renderer (`systemName="..."`)                                       | All inline icons                       |
-| `ConfirmationDialog`        | Native iOS action sheet                                                       | Sign-out, delete account, photo picker |
-| `BottomSheet`               | Native sheet with detents                                                     | Password change, secondary forms       |
-| `Spacer`                    | Flexible space                                                                | Layout                                 |
-| `ProgressView`              | Spinner or determinate progress                                               | Loading states                         |
-| `ContentUnavailableView`    | Empty state with SF Symbol + title + description                              | Empty home, no results                 |
+| Primitive                   | What it is                                                                    | Where it lands                                                                 |
+| :-------------------------- | :---------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
+| `Host`                      | SwiftUI host view, top-level wrapper for any screen using `@expo/ui/swift-ui` | Every screen root                                                              |
+| `VStack` / `HStack`         | SwiftUI stacks with spacing + alignment                                       | Layout primitives                                                              |
+| `Form` / `Section`          | Native iOS Form with grouped sections                                         | Available but unused. Screens hand-build capsule rows with `VStack` instead    |
+| `Picker`                    | Segmented or wheel picker (use `pickerStyle("segmented")` for inline)         | Theme mode, motion preference                                                  |
+| `Toggle`                    | Native iOS toggle                                                             | Boolean preferences                                                            |
+| `Button`                    | Native button with role variants (default, cancel, destructive)               | All actions                                                                    |
+| `TextField` / `SecureField` | Native text input                                                             | Forms                                                                          |
+| `Text`                      | SwiftUI text with modifier composition                                        | All typography                                                                 |
+| `Image`                     | SF Symbol renderer (`systemName="..."`)                                       | All inline icons                                                               |
+| `ConfirmationDialog`        | Native iOS action sheet                                                       | Sign-out, delete account, photo picker                                         |
+| `BottomSheet`               | Native sheet with detents                                                     | Available but unused. Modal screens use `presentation: "modal"` routes instead |
+| `Spacer`                    | Flexible space                                                                | Layout                                                                         |
+| `ProgressView`              | Spinner or determinate progress                                               | Loading states                                                                 |
+| `ContentUnavailableView`    | Empty state with SF Symbol + title + description                              | Empty home, no results                                                         |
 
 Text inputs bind `text` to a `useNativeState("")` and mask synchronously: a `"worklet"` `onTextChange` rewrites the field on the same frame the keystroke lands (digits-only OTP, lowercase usernames), so the raw character never paints. Reusable masks live in `lib/masks.ts`.
 
 ### Custom composition (in `components/ui/`)
 
-| Component                              | Purpose                                                                                                                                                                           | Notes                              |
-| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------- |
-| `Material`                             | Translucent surface with iOS 26+ Liquid Glass / iOS 16.4-25 BlurView fallback                                                                                                     | Reserve for navigation chrome only |
-| `OfflineBanner`                        | Top-of-screen notification banner using `Material` chrome variant                                                                                                                 | Shows when network unavailable     |
-| `LoadingScreen`                        | Brand-icon + spinner, themed by appearance                                                                                                                                        | Suspense fallback                  |
-| `ErrorBoundary`                        | Top-level crash boundary with brand recovery UI                                                                                                                                   | Wraps each route segment           |
-| `ConvexError`                          | Maps Convex errors to user-readable copy                                                                                                                                          | Used in error displays             |
-| `SkeletonProfile` / `SkeletonSessions` | Static loading placeholders. No animation, so nothing to suppress under Reduce Motion. Filler bars carry an empty `accessibilityLabel` so VoiceOver skips the placeholder shapes. | Profile loading, sessions loading  |
-| `StatusText`                           | `ErrorText` + `SuccessText` with accessibility announcements                                                                                                                      | Form feedback                      |
+| Component                              | Purpose                                                                                                                                                                           | Notes                                                   |
+| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ |
+| `Material`                             | Translucent surface with iOS 26+ Liquid Glass / iOS 16.4-25 BlurView fallback                                                                                                     | Reserve for navigation chrome only                      |
+| `OfflineBanner`                        | Top-of-screen notification banner using `Material` chrome variant                                                                                                                 | Shows when network unavailable                          |
+| `LoadingScreen`                        | Brand-icon + spinner, themed by appearance                                                                                                                                        | Suspense fallback                                       |
+| `ErrorBoundary`                        | Top-level crash boundary with brand recovery UI                                                                                                                                   | Wraps each route segment                                |
+| `formatError`                          | Maps a Convex error to user-readable copy (`components/ui/convex-error.tsx`)                                                                                                      | Used by `profile/index.tsx` and `use-delete-account.ts` |
+| `SkeletonProfile` / `SkeletonSessions` | Static loading placeholders. No animation, so nothing to suppress under Reduce Motion. Filler bars carry an empty `accessibilityLabel` so VoiceOver skips the placeholder shapes. | Profile loading, sessions loading                       |
+| `StatusText`                           | `ErrorText` + `SuccessText` with accessibility announcements                                                                                                                      | Form feedback                                           |
 
 ### Custom hooks (in `hooks/`)
 
-| Hook                              | Purpose                                                                                         |
-| :-------------------------------- | :---------------------------------------------------------------------------------------------- |
-| `useThemeMode` / `useColorScheme` | App-level light/dark/system override on top of OS appearance                                    |
-| `useColors`                       | Returns the `Colors` palette (currently constant, kept as a hook for future per-theme variants) |
-| `useThemedAsset`                  | Picks light or dark asset based on active appearance                                            |
-| `useDynamicFont`                  | Multiplies declared font sizes by accessibility fontScale before passing to `@expo/ui` `font()` |
-| `useReducedMotion`                | Combines OS Reduce Motion + in-app override. Drives animation duration / disable                |
-| `useNetwork`                      | Online / offline state for `OfflineBanner`                                                      |
-| `useNotifications`                | Push token registration + foreground handler                                                    |
-| `useDeepLinkHandler`              | Handles `applinks:` URLs from associated domains                                                |
-| `useUpdates`                      | EAS Update check + apply with branded UI                                                        |
-| `useOnboarding`                   | First-launch welcome flow gate                                                                  |
-| `useDebounce`                     | Standard debounce                                                                               |
-| `useNavigationTracking`           | Analytics / route logging                                                                       |
+| Hook                              | Purpose                                                                                                                    |
+| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
+| `useThemeMode` / `useColorScheme` | App-level light/dark/system override on top of OS appearance                                                               |
+| `useColors`                       | Returns the `Colors` palette (currently constant, kept as a hook for future per-theme variants)                            |
+| `useThemedAsset`                  | Picks light or dark asset based on active appearance                                                                       |
+| `useDynamicFont`                  | Maps the declared font size to a SwiftUI `textStyle` passed to `@expo/ui` `font()`, so iOS Dynamic Type scales it natively |
+| `useReducedMotion`                | Combines OS Reduce Motion + in-app override. Drives animation duration / disable                                           |
+| `useNetwork`                      | Online / offline state for `OfflineBanner`                                                                                 |
+| `useNotifications`                | Push token registration + foreground handler                                                                               |
+| `useDeepLinkHandler`              | Resumes a deep link the auth guard deferred until sign-in. Live applinks route through `+native-intent.tsx`                |
+| `useAppUpdates`                   | EAS Update check + apply with branded UI                                                                                   |
+| `useOnboarding`                   | First-launch welcome flow gate                                                                                             |
+| `useDebounce`                     | Standard debounce                                                                                                          |
+| `useNavigationTracking`           | Analytics / route logging                                                                                                  |
 
 ## Do's and Don'ts