From b02bb5519ce75f449809e57e9c2c00b37d722861 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Sat, 9 May 2026 14:09:24 -0500
Subject: [PATCH 01/25] docs(plans): add email confirmation signup plan for
 #164

Plans a 3-commit sequence to require email confirmation on signup:
foundation (PKCE flow, callback route, OTP verification), resend
support, and friendly handling of unconfirmed sign-in attempts.
---
 docs/plans/164-email-confirmation-signup.md | 213 ++++++++++++++++++++
 1 file changed, 213 insertions(+)
 create mode 100644 docs/plans/164-email-confirmation-signup.md

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
new file mode 100644
index 0000000..a3ffab2
--- /dev/null
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -0,0 +1,213 @@
+# Plan — Issue #164: Require email confirmation on signup
+
+## Context
+
+Email confirmations are currently disabled in Supabase (`enable_confirmations = false` in `api/supabase/config.toml:176`). Anyone can sign up with any email and immediately be logged in — there's no proof of address ownership. The issue asks us to:
+
+1. Enable email confirmations
+2. Show a "pending confirmation" state after signup (since `signUp()` will no longer return a session)
+3. Allow the confirmation email to be resent
+4. Complete verification when the user clicks the email link
+5. Handle the case where an unconfirmed user later tries to sign in
+
+**Cross-issue ordering** — this issue should ship before #167 (change-email re-verification, which reuses the same `/auth/callback` route and OTP entry UI) and before #165 (sign-in/redirect audit, which standardizes destinations across all auth flows). 164 preserves today's destination logic; 165 will standardize it later.
+
+**Out of scope:**
+- Branded email template content (deferred to #22)
+- Standardizing post-auth redirect destinations (deferred to #165)
+- Production Supabase dashboard configuration (must be done manually after deploy: enable Confirm Email in Authentication → Providers → Email, add `https://<prod>/auth/callback` to redirect allowlist, upload custom template)
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Confirmation method | **Both magic link AND OTP code** in the email; user can use whichever | Resilient to corporate email scanners (Defender, Barracuda, Mimecast) that pre-fetch links and consume the token before users click. Supabase auth issue [#1214](https://github.com/supabase/auth/issues/1214) is open and unfixed; no clean recovery for affected users without an OTP fallback. Default Supabase template already emits both, so the email-side cost is near zero. |
+| OTP input component | shadcn/ui `<InputOTP>` (uses `input-otp` library) | Renders single invisible `<input autocomplete="one-time-code">` behind visual digit boxes — combines accessible single input (WCAG 1.3.5) with visual digit-box UX. Consistent with project's existing shadcn/ui usage. |
+| Pending-UI surface | Inline state + shared `<CheckEmailNotice>` component | No URL params (OWASP: PII like email shouldn't appear in URLs — leaks via browser history, server logs, Referer to Sentry). Refresh degrades benignly: link in inbox still works, resend reachable via signin path. |
+| Email passing | React state within form components | User never retypes — Supabase's confirmation token uniquely identifies the user. Email passed as prop from parent (`SignUpForm`, `SignInForm`) into `<CheckEmailNotice>`. |
+| Sign-in unconfirmed handling | In scope, same issue (commit 3) | Completes the verification story: signup → pending → resend → confirm AND signin → unconfirmed → resend. |
+| Post-confirmation destination | Preserve current logic per parent (`SignUpForm` → redirect-or-`/create-team`; `SignInForm` → redirect-or-`/leagues`; magic link callback uses URL `redirect` search param, else `/create-team`) | Standardization deferred to #165. |
+| Resend with redirect override | `AuthContext.resendConfirmation(email, { redirect? })` accepts the current redirect param so the resent email's link encodes the *current* destination (e.g., signin's `/leagues/123`) rather than whatever was baked in at signup time | Helps a user who hits the unconfirmed-signin path with a deep link, triggers Resend, and uses the new email's link. The original signup email's link still routes to `/create-team` (can't fix retroactively); the OTP path always routes correctly via the callsite. |
+| E2E approach | Existing admin-API fixture keeps `email_confirm: true` (auto-confirms); add ONE new test per new flow path (magic link in commit 1, OTP in commit 2) | Existing tests stay fast; targeted e2e covers the new wiring |
+| Email template | Custom template at `api/supabase/templates/confirmation.html` includes both `{{ .ConfirmationURL }}` and `{{ .Token }}` from commit 1 | Default Supabase template already has both; we're shipping our own to control wording and prep for #22's branding |
+| Cross-issue ordering | 164 → 167 → 165 (locked) | 164 builds verification primitives; 167 reuses callback route + OTP entry pattern for change-email re-verification; 165 audits all destinations after both new flows exist. |
+
+---
+
+## Commits
+
+Each commit is a gate. Each must independently build, lint, test, and format. Wait for approval before moving on. Note: these commits are sized for review/approval — they don't necessarily map 1:1 to production deploys. Recommendation is to land all three before flipping production confirmations on, so users always have the OTP fallback path.
+
+### Commit 1 — Enable confirmations + PKCE flow + signup pending state + magic link callback + OTP verification
+
+**Goal:** Signup goes end-to-end via either path: submit → "check your email, click link or enter code" UI → user clicks link OR types code → land back in app, logged in. (Resend deferred to commit 2; signin-unconfirmed deferred to commit 3.)
+
+**Supabase client flow change** (`web/src/lib/supabase.ts`):
+- Today: `createClient(url, key)` with no options → defaults to `flowType: 'implicit'` (verified in `auth-js` source — `DEFAULT_OPTIONS.flowType: 'implicit'`)
+- Required: pass `{ auth: { flowType: 'pkce' } }` so the magic link returns `?code=` (which `exchangeCodeForSession` consumes) instead of `#access_token=` (implicit hash flow)
+- This is a small but app-wide auth behavior change — covered by existing AuthContext tests
+
+**Supabase config** (`api/supabase/config.toml` and `e2e/supabase/config.toml`):
+- `[auth] site_url` → set to local web URL (`http://localhost:5173` for dev, `http://localhost:5273` for e2e). Existing `http://127.0.0.1:3000` is dead config; nothing in the codebase references it.
+- `[auth] additional_redirect_urls` → `["http://localhost:5173/auth/callback"]` for dev (and `5273` for e2e). Existing `https://127.0.0.1:3000` is HTTPS on a non-running port — wrong on multiple counts.
+- `[auth.email] enable_confirmations = true` (currently `false` at line 176)
+- `[auth.email.template.confirmation]` block pointing at `./templates/confirmation.html`. Both configs can reference the same file via relative path; mirrors how `e2e/supabase/migrations/` is symlinked to `api/supabase/migrations/`.
+
+**New email template** (`api/supabase/templates/confirmation.html`):
+- Includes both the magic link (`{{ .ConfirmationURL }}`) AND the 6-digit OTP code (`{{ .Token }}`)
+- Wording explicitly mentions "Click the link OR enter the 6-digit code in the app"
+- Plain HTML; references app name placeholder; #22 will brand it
+
+**New components:**
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — shared pending UI. Props:
+  - `email: string` — displayed in message
+  - `onVerified: () => void` — called after `verifyOtp` resolves successfully so parent can navigate
+  - `onResend?: () => Promise<void>` — wired in commit 2 (placeholder/no-op for commit 1)
+  - Renders: instructional copy ("We sent a link to <email>. Click the link in the email, or enter the 6-digit code below."), a shadcn/ui `<InputOTP maxLength={6}>` component (renders 6 visual digit slots with a single accessible input + `autocomplete="one-time-code"` underneath), a `<LoadingButton>` that calls `supabase.auth.verifyOtp({ email, token: code, type: 'signup' })` on submit. On error, render `<InlineError>`. On success, call `onVerified`. (`type: 'signup'` is the verified value from `auth-js` `EmailOtpType` for initial-signup confirmation.)
+  - Adds dependency: `input-otp` package via shadcn CLI (`npx shadcn@latest add input-otp` — installs to `web/src/components/ui/input-otp.tsx`, matching the project's existing shadcn vendoring per `web/components.json` aliases). Per `web/CLAUDE.md`, shadcn primitives are vendored — do not modify after install.
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx`
+- `web/src/components/auth/AuthCallback/AuthCallback.tsx` — handles the magic-link return: on mount, reads `code` and optional `redirect` from URL search params, calls `supabase.auth.exchangeCodeForSession(code)`, on success navigates to `redirect` if present else `/create-team`, on error renders `<InlineError>` with link back to `/sign-in`. Reuses the existing `redirectSearchSchema` Zod validator at `web/src/router.tsx:87-93` (validates `redirect` starts with `/` to prevent open redirects).
+- `web/src/components/auth/AuthCallback/AuthCallback.test.tsx`
+
+**New helper** (`web/src/lib/auth-destination.ts`):
+- `getPostSignupDestination(redirectParam?: string): string` — returns `redirectParam` if present, else `/create-team`. Search-param validation is already enforced upstream by `redirectSearchSchema` (router.tsx:87-93) when the route validates its search params, so this helper just chooses between two valid values. Used by `SignUpForm` (post-success when session is returned), `AuthCallback`, and `<CheckEmailNotice>`'s `onVerified` from the signup callsite. (`SignInForm`'s default destination stays as today's `/leagues`; this helper is the signup-flow default.)
+
+**Wiring:**
+- `web/src/contexts/AuthContext.tsx`:
+  - Update `signUp()` to pass `options: { data: { displayName }, emailRedirectTo: ${window.location.origin}/auth/callback?redirect=<encoded redirect> }`. The `redirect` is read from the current location and forwarded so deep-links survive the email gap on the magic-link path.
+  - No new context method this commit (resend in commit 2).
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx`:
+  - After successful `signUp()`, branch on `data.session`:
+    - If `session` is non-null (auto-confirm fallback if confirmations are ever disabled): existing navigate-to-destination logic at lines 68-72.
+    - If `session` is null: set local `pending` state, render `<CheckEmailNotice email={email} onVerified={handleVerified} />` instead of the form. `handleVerified` runs the same destination logic via `getPostSignupDestination`.
+- `web/src/router.tsx`:
+  - Add `/auth/callback` as a public child of root (sibling to `/sign-up`, `/sign-in`). Accepts `code` and optional `redirect` search params validated via Zod.
+
+**Tests:**
+- `SignUpForm.test.tsx`:
+  - When mocked `signUp` returns no session, `<CheckEmailNotice>` is rendered and no navigation occurs
+  - When mocked `signUp` returns a session (auto-confirm fallback), existing navigation behavior preserved
+- `CheckEmailNotice.test.tsx`:
+  - Renders email and code input
+  - Submitting valid code calls `supabase.auth.verifyOtp` with expected args
+  - On verify success, calls `onVerified` prop
+  - On verify error, renders `<InlineError>`
+  - Code input enforces 6 digits / numeric only (via `inputMode` and `pattern` — server is the source of truth)
+- `AuthCallback.test.tsx`:
+  - On mount with `code` param, calls `exchangeCodeForSession` and navigates to `redirect` or default
+  - On exchange error, renders `<InlineError>` with `/sign-in` link
+  - With no `code` param, renders error state
+- `AuthContext.test.tsx`:
+  - `signUp` calls Supabase with the expected `emailRedirectTo` (including the forwarded `redirect` query)
+- E2E (`e2e/tests/auth.spec.ts`): TWO new tests using Inbucket's REST API:
+  - List mailbox: `GET http://127.0.0.1:54424/api/v1/mailbox/<email>` returns JSON array of message metadata
+  - Fetch message: `GET http://127.0.0.1:54424/api/v1/mailbox/<email>/<id>` returns body
+  - Port 54424 = Inbucket dev port 54324 (`api/supabase/config.toml:96`) + 100 per the e2e port-shift rule
+  - Magic-link path: fill signup form via UI → assert `<CheckEmailNotice>` appears → fetch the latest mail → extract the magic link from the body → navigate Playwright to it → assert the app shows `/create-team`
+  - OTP path: fill signup form → assert `<CheckEmailNotice>` appears → fetch the same mail → extract the 6-digit token → type it into the OTP input → assert the app shows `/create-team`
+
+**Verification:**
+1. `cd e2e/supabase && supabase stop && supabase start` to pick up config changes (also `cd api/supabase && supabase stop && supabase start`)
+2. `npm run web:dev` + `npm run api:watch`; sign up with a fresh email; confirm `<CheckEmailNotice>` appears; open Inbucket at `http://127.0.0.1:54324`; both pathways work — clicking the link AND typing the code each result in landing on `/create-team`
+3. `npm run web:test` + `npm run api:test` + `npm run e2e` all green
+
+---
+
+### Commit 2 — Resend confirmation email
+
+**Goal:** "Resend" button on the pending UI re-sends the confirmation email (which contains both link and OTP).
+
+**Wiring:**
+- `web/src/contexts/AuthContext.ts` — add `resendConfirmation(email: string, options?: { redirect?: string }): Promise<void>` to interface
+- `web/src/contexts/AuthContext.tsx` — implement: calls `supabase.auth.resend({ type: 'signup', email, options: { emailRedirectTo: ${origin}/auth/callback${redirect ? '?redirect=' + encodeURIComponent(redirect) : ''} } })`; throws on error
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — add Resend button below the OTP form. On click, call `onResend()` (parent passes `auth.resendConfirmation(email, { redirect })`). Use existing `<LoadingButton>` for loading state. Use existing `LiveRegion` to announce success ("New confirmation email sent"). Use `<InlineError>` for errors, with friendly handling for Supabase's rate-limit error code (`over_email_send_rate_limit` → "Please wait a moment before requesting another email").
+- `SignUpForm.tsx` — pass `onResend={() => auth.resendConfirmation(email, { redirect })}` to `<CheckEmailNotice>`, where `redirect` is read from the current route's search params (same source as the existing `redirect` handling at `SignUpForm.tsx:68-72`)
+
+**Tests:**
+- `AuthContext.test.tsx`: `resendConfirmation` calls `supabase.auth.resend` with the correct args (type, email, emailRedirectTo); also tests the `redirect` option is encoded into emailRedirectTo correctly
+- `CheckEmailNotice.test.tsx`:
+  - Clicking Resend calls `onResend`
+  - Loading state visible during await
+  - Success message announced via `LiveRegion`
+  - Generic error rendered via `InlineError`
+  - Rate-limit error renders friendly text
+- `SignUpForm.test.tsx`: Resend button passes the current `redirect` param to `resendConfirmation`
+
+**Verification:**
+- Manual: sign up, click Resend, verify a second email appears in Inbucket; either email's link OR either email's most-recent OTP completes verification
+- Manual: rapid-fire Resend → rate-limit message
+- All test commands green
+
+---
+
+### Commit 3 — Friendly handling of unconfirmed-email sign-in
+
+**Goal:** If a user signs up but never confirms, then later tries to sign in, they see the same `<CheckEmailNotice>` (with OTP entry + Resend) instead of a generic auth error.
+
+**Wiring:**
+- `web/src/components/auth/SignInForm/SignInForm.tsx` — after `signIn()` throws, inspect the error: if it's Supabase's `email_not_confirmed` (check `error.code === 'email_not_confirmed'` — verified against `auth-js/src/lib/error-codes.ts`; `AuthApiError` has a string `code` property per `auth-js/src/lib/errors.ts`), set local `pending` state and render `<CheckEmailNotice email={email} onVerified={handleVerified} onResend={() => auth.resendConfirmation(email, { redirect })} />`, where `redirect` is the current route's `redirect` search param (same source as today's signin redirect handling at `SignInForm.tsx:33-37`). `handleVerified` here navigates to redirect-or-`/leagues`. For any other error, fall through to the existing `<InlineError>` at `SignInForm.tsx:39-43`. The Resend's `redirect` override means the resent email's magic link will encode the signin-time destination rather than the (potentially different) signup-time one.
+
+**Tests:**
+- `SignInForm.test.tsx`:
+  - Mocked `signIn` rejects with `email_not_confirmed` → `<CheckEmailNotice>` rendered, no navigation
+  - Mocked `signIn` rejects with any other error → existing `<InlineError>` behavior preserved
+  - On `<CheckEmailNotice>` `onVerified`, navigation runs with signin destination logic
+  - Resend from this context passes the signin-time `redirect` param to `resendConfirmation`
+
+**Verification:**
+- Manual: sign up, do NOT click the email link / enter the OTP, navigate to `/sign-in`, attempt sign-in with the unconfirmed credentials, verify pending UI appears with working OTP entry + Resend
+- All test commands green
+
+---
+
+## Critical files
+
+**Modified:**
+- `api/supabase/config.toml` (commit 1)
+- `e2e/supabase/config.toml` (commit 1)
+- `web/src/lib/supabase.ts` (commit 1 — add `flowType: 'pkce'`)
+- `web/src/contexts/AuthContext.tsx` (commits 1, 2)
+- `web/src/contexts/AuthContext.ts` (commit 2)
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commit 1, minor in commit 2)
+- `web/src/components/auth/SignInForm/SignInForm.tsx` (commit 3)
+- `web/src/router.tsx` (commit 1 — add `/auth/callback` route)
+
+**New:**
+- `api/supabase/templates/confirmation.html` (commit 1; includes both link and OTP from the start)
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` + `.test.tsx` (commit 1; expanded in commit 2)
+- `web/src/components/auth/AuthCallback/AuthCallback.tsx` + `.test.tsx` (commit 1)
+- `web/src/lib/auth-destination.ts` (commit 1)
+- `web/src/components/ui/input-otp.tsx` (commit 1; added via shadcn workflow — exact path matches existing shadcn components in the project)
+- `web/package.json` — adds `input-otp` dependency (commit 1)
+
+**Reused (existing components, no changes):**
+- `web/src/components/InlineError/InlineError.tsx` — error display in `<AuthCallback>`, `<CheckEmailNotice>`, existing forms
+- `web/src/components/LiveRegion/LiveRegion.tsx` — screen-reader announcements
+- `web/src/components/LoadingButton/LoadingButton.tsx` — Verify and Resend button loading states
+- `web/src/lib/supabase.ts` — Supabase client singleton
+- `web/src/hooks/useAuth.ts` — auth hook (gains `resendConfirmation` in commit 2)
+
+---
+
+## End-to-end verification (after all 3 commits)
+
+1. **Magic-link happy path:** Sign up with new email → see `<CheckEmailNotice>` → check Inbucket → click link → land on `/create-team` logged in
+2. **OTP happy path:** Sign up with new email → see `<CheckEmailNotice>` → check Inbucket → type 6-digit code into OTP field → land on `/create-team` logged in
+3. **Resend:** Sign up → click Resend → second email arrives in Inbucket → either email's link OR the latest OTP completes verification (older OTP is invalidated by the new send per Supabase's behavior)
+4. **Unconfirmed sign-in:** Sign up → DON'T confirm → go to `/sign-in` → submit credentials → see `<CheckEmailNotice>` → resend or OTP entry both work → land on `/leagues` (or wherever `redirect` param pointed)
+5. **Existing e2e tests:** `npm run e2e` all green (admin fixture continues working via `email_confirm: true`)
+6. **All tests + format + lint:** `npm run test:all` + `npm run web:lint` + `npm run web:format:check` + `npm run api:format:check` all green
+
+---
+
+## Production deployment notes (post-merge, manual)
+
+- Enable Confirm Email in Supabase dashboard: Authentication → Providers → Email
+- Add `https://<prod-domain>/auth/callback` to the redirect URL allowlist
+- Configure SMTP for outbound email (currently commented out in `api/supabase/config.toml:186-194`; production must use a real provider)
+- Upload the custom confirmation template (Supabase dashboard reads templates from the dashboard in production, not from the local config file)
+- **Raise email rate limit**: `[auth.rate_limit] email_sent = 2` (per hour) at `api/supabase/config.toml:149` is sane for local dev but far too low for production. Set in the Supabase dashboard to a value appropriate for expected signup volume.
+
+## Known preexisting concern (out of scope)
+
+- `on_auth_user_created` trigger in `api/supabase/migrations/20260108000000_create_user_profile_trigger.sql` fires on every `INSERT` into `auth.users`, regardless of whether the user has confirmed their email. With confirmations enabled, this means `Accounts` and `UserProfiles` rows are created at signup time even if the user never confirms. Result: orphan rows accumulate from abandoned signups. Cleanup (e.g., a periodic job to remove unconfirmed users older than N days, or moving the trigger to fire only after confirmation) is out of 164's scope but should be tracked as follow-up.

From 4c2ddd573774670b0451ec59b8a37d4fd18a1881 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Mon, 11 May 2026 08:01:10 -0500
Subject: [PATCH 02/25] docs(plans): split #164 plan into six commits; correct
 Mailpit API usage

- Re-sequence Commit 1 into four self-contained commits: PKCE+AuthCallback,
  CheckEmailNotice vendoring, config flip + SignUpForm wiring, e2e.
- Replace Inbucket REST paths with verified Mailpit endpoints
  (search?query=to:..., /message/{ID}, DELETE /messages) and embed real
  response shapes captured from the running container.
- Note Supabase kept the [inbucket] config block and container name for
  back-compat even though the image is now supabase/mailpit.
---
 docs/plans/164-email-confirmation-signup.md | 188 +++++++++++++-------
 1 file changed, 127 insertions(+), 61 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index a3ffab2..42a194d 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -25,28 +25,88 @@ Email confirmations are currently disabled in Supabase (`enable_confirmations =
 | OTP input component | shadcn/ui `<InputOTP>` (uses `input-otp` library) | Renders single invisible `<input autocomplete="one-time-code">` behind visual digit boxes — combines accessible single input (WCAG 1.3.5) with visual digit-box UX. Consistent with project's existing shadcn/ui usage. |
 | Pending-UI surface | Inline state + shared `<CheckEmailNotice>` component | No URL params (OWASP: PII like email shouldn't appear in URLs — leaks via browser history, server logs, Referer to Sentry). Refresh degrades benignly: link in inbox still works, resend reachable via signin path. |
 | Email passing | React state within form components | User never retypes — Supabase's confirmation token uniquely identifies the user. Email passed as prop from parent (`SignUpForm`, `SignInForm`) into `<CheckEmailNotice>`. |
-| Sign-in unconfirmed handling | In scope, same issue (commit 3) | Completes the verification story: signup → pending → resend → confirm AND signin → unconfirmed → resend. |
+| Sign-in unconfirmed handling | In scope, same issue (commit 6) | Completes the verification story: signup → pending → resend → confirm AND signin → unconfirmed → resend. |
 | Post-confirmation destination | Preserve current logic per parent (`SignUpForm` → redirect-or-`/create-team`; `SignInForm` → redirect-or-`/leagues`; magic link callback uses URL `redirect` search param, else `/create-team`) | Standardization deferred to #165. |
 | Resend with redirect override | `AuthContext.resendConfirmation(email, { redirect? })` accepts the current redirect param so the resent email's link encodes the *current* destination (e.g., signin's `/leagues/123`) rather than whatever was baked in at signup time | Helps a user who hits the unconfirmed-signin path with a deep link, triggers Resend, and uses the new email's link. The original signup email's link still routes to `/create-team` (can't fix retroactively); the OTP path always routes correctly via the callsite. |
-| E2E approach | Existing admin-API fixture keeps `email_confirm: true` (auto-confirms); add ONE new test per new flow path (magic link in commit 1, OTP in commit 2) | Existing tests stay fast; targeted e2e covers the new wiring |
-| Email template | Custom template at `api/supabase/templates/confirmation.html` includes both `{{ .ConfirmationURL }}` and `{{ .Token }}` from commit 1 | Default Supabase template already has both; we're shipping our own to control wording and prep for #22's branding |
+| E2E approach | Existing admin-API fixture keeps `email_confirm: true` (auto-confirms); add two new tests in commit 4 (magic-link path + OTP path) | Existing tests stay fast; targeted e2e covers the new wiring |
+| Email template | Custom template at `api/supabase/templates/confirmation.html` includes both `{{ .ConfirmationURL }}` and `{{ .Token }}`, lands in commit 3 alongside the config flip | Default Supabase template already has both; we're shipping our own to control wording and prep for #22's branding |
 | Cross-issue ordering | 164 → 167 → 165 (locked) | 164 builds verification primitives; 167 reuses callback route + OTP entry pattern for change-email re-verification; 165 audits all destinations after both new flows exist. |
 
 ---
 
 ## Commits
 
-Each commit is a gate. Each must independently build, lint, test, and format. Wait for approval before moving on. Note: these commits are sized for review/approval — they don't necessarily map 1:1 to production deploys. Recommendation is to land all three before flipping production confirmations on, so users always have the OTP fallback path.
+Each commit is a gate. Each must independently build, lint, test, and format. Wait for approval before moving on. Note: these commits are sized for review/approval — they don't necessarily map 1:1 to production deploys. Recommendation is to land all six before flipping production confirmations on, so users always have the OTP fallback path. The local-dev confirmation flip happens in commit 3; commits 1–2 are preparatory and safe under `enable_confirmations = false`.
 
-### Commit 1 — Enable confirmations + PKCE flow + signup pending state + magic link callback + OTP verification
+### Commit 1 — PKCE flow + `/auth/callback` route + AuthCallback handler
 
-**Goal:** Signup goes end-to-end via either path: submit → "check your email, click link or enter code" UI → user clicks link OR types code → land back in app, logged in. (Resend deferred to commit 2; signin-unconfirmed deferred to commit 3.)
+**Goal:** Stand up the magic-link landing page and switch the Supabase client to PKCE so the link returns `?code=` instead of an implicit hash. Safe to land while `enable_confirmations` is still `false`: the route exists but nothing emits a magic link yet, and PKCE is fully compatible with the existing implicit-flow happy path.
 
 **Supabase client flow change** (`web/src/lib/supabase.ts`):
 - Today: `createClient(url, key)` with no options → defaults to `flowType: 'implicit'` (verified in `auth-js` source — `DEFAULT_OPTIONS.flowType: 'implicit'`)
 - Required: pass `{ auth: { flowType: 'pkce' } }` so the magic link returns `?code=` (which `exchangeCodeForSession` consumes) instead of `#access_token=` (implicit hash flow)
 - This is a small but app-wide auth behavior change — covered by existing AuthContext tests
 
+**New components:**
+- `web/src/components/auth/AuthCallback/AuthCallback.tsx` — handles the magic-link return: on mount, reads `code` and optional `redirect` from URL search params, calls `supabase.auth.exchangeCodeForSession(code)`, on success navigates to `redirect` if present else `/create-team`, on error renders `<InlineError>` with link back to `/sign-in`. Reuses the existing `redirectSearchSchema` Zod validator at `web/src/router.tsx:87-93` (validates `redirect` starts with `/` to prevent open redirects).
+- `web/src/components/auth/AuthCallback/AuthCallback.test.tsx`
+
+**New helper** (`web/src/lib/auth-destination.ts`):
+- `getPostSignupDestination(redirectParam?: string): string` — returns `redirectParam` if present, else `/create-team`. Search-param validation is already enforced upstream by `redirectSearchSchema` (router.tsx:87-93) when the route validates its search params, so this helper just chooses between two valid values. Used by `AuthCallback` here, and later by `SignUpForm` and `<CheckEmailNotice>`'s `onVerified` from the signup callsite (commit 3). Lands here because AuthCallback is its first caller.
+
+**Wiring:**
+- `web/src/router.tsx` — add `/auth/callback` as a public child of root (sibling to `/sign-up`, `/sign-in`). Accepts `code` and optional `redirect` search params validated via Zod.
+
+**Tests:**
+- `AuthCallback.test.tsx`:
+  - On mount with `code` param, calls `exchangeCodeForSession` and navigates to `redirect` or default
+  - On exchange error, renders `<InlineError>` with `/sign-in` link
+  - With no `code` param, renders error state
+- `auth-destination.test.ts`:
+  - Returns the redirect param when provided
+  - Falls back to `/create-team` when redirect is missing/empty
+- Existing `AuthContext.test.tsx` keeps passing under PKCE (no behavioral change to the public API).
+
+**Verification:**
+1. `npm run web:test` green
+2. `npm run web:lint` + `npm run web:format:check` green
+3. Manual: existing signup/signin flow still works (auto-confirm path, no email sent because `enable_confirmations` is still `false`)
+
+---
+
+### Commit 2 — `<CheckEmailNotice>` component + `input-otp` vendoring
+
+**Goal:** Add the pending-state UI as a self-contained, tested component. Not yet wired into any form — that happens in commit 3.
+
+**New dependency:**
+- `input-otp` package via shadcn CLI: `npx shadcn@latest add input-otp` — installs to `web/src/components/ui/input-otp.tsx`, matching the project's existing shadcn vendoring per `web/components.json` aliases. Per `web/CLAUDE.md`, shadcn primitives are vendored — do not modify after install. Adds `input-otp` to `web/package.json`.
+
+**New components:**
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — shared pending UI. Props:
+  - `email: string` — displayed in message
+  - `onVerified: () => void` — called after `verifyOtp` resolves successfully so parent can navigate
+  - `onResend?: () => Promise<void>` — wired in commit 5 (placeholder/no-op for commits 2–4)
+  - Renders: instructional copy ("We sent a link to <email>. Click the link in the email, or enter the 6-digit code below."), a shadcn/ui `<InputOTP maxLength={6}>` component (renders 6 visual digit slots with a single accessible input + `autocomplete="one-time-code"` underneath), a `<LoadingButton>` that calls `supabase.auth.verifyOtp({ email, token: code, type: 'signup' })` on submit. On error, render `<InlineError>`. On success, call `onVerified`. (`type: 'signup'` is the verified value from `auth-js` `EmailOtpType` for initial-signup confirmation.)
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx`
+
+**Tests:**
+- `CheckEmailNotice.test.tsx`:
+  - Renders email and code input
+  - Submitting valid code calls `supabase.auth.verifyOtp` with expected args
+  - On verify success, calls `onVerified` prop
+  - On verify error, renders `<InlineError>`
+  - Code input enforces 6 digits / numeric only (via `inputMode` and `pattern` — server is the source of truth)
+
+**Verification:**
+1. `npm run web:test` + `npm run web:lint` + `npm run web:format:check` green
+2. Manual: nothing to verify in-app yet (component unwired); spot-check Storybook-style by importing into a scratch page if desired
+
+---
+
+### Commit 3 — Enable confirmations + wire SignUpForm into the pending UI
+
+**Goal:** Flip the feature on. Signup goes end-to-end via either path: submit → "check your email, click link or enter code" UI → user clicks link OR types code → land back in app, logged in. (Resend deferred to commit 5; signin-unconfirmed deferred to commit 6.) This is the load-bearing commit; commits 1–2 are preparatory.
+
 **Supabase config** (`api/supabase/config.toml` and `e2e/supabase/config.toml`):
 - `[auth] site_url` → set to local web URL (`http://localhost:5173` for dev, `http://localhost:5273` for e2e). Existing `http://127.0.0.1:3000` is dead config; nothing in the codebase references it.
 - `[auth] additional_redirect_urls` → `["http://localhost:5173/auth/callback"]` for dev (and `5273` for e2e). Existing `https://127.0.0.1:3000` is HTTPS on a non-running port — wrong on multiple counts.
@@ -58,62 +118,67 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - Wording explicitly mentions "Click the link OR enter the 6-digit code in the app"
 - Plain HTML; references app name placeholder; #22 will brand it
 
-**New components:**
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — shared pending UI. Props:
-  - `email: string` — displayed in message
-  - `onVerified: () => void` — called after `verifyOtp` resolves successfully so parent can navigate
-  - `onResend?: () => Promise<void>` — wired in commit 2 (placeholder/no-op for commit 1)
-  - Renders: instructional copy ("We sent a link to <email>. Click the link in the email, or enter the 6-digit code below."), a shadcn/ui `<InputOTP maxLength={6}>` component (renders 6 visual digit slots with a single accessible input + `autocomplete="one-time-code"` underneath), a `<LoadingButton>` that calls `supabase.auth.verifyOtp({ email, token: code, type: 'signup' })` on submit. On error, render `<InlineError>`. On success, call `onVerified`. (`type: 'signup'` is the verified value from `auth-js` `EmailOtpType` for initial-signup confirmation.)
-  - Adds dependency: `input-otp` package via shadcn CLI (`npx shadcn@latest add input-otp` — installs to `web/src/components/ui/input-otp.tsx`, matching the project's existing shadcn vendoring per `web/components.json` aliases). Per `web/CLAUDE.md`, shadcn primitives are vendored — do not modify after install.
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx`
-- `web/src/components/auth/AuthCallback/AuthCallback.tsx` — handles the magic-link return: on mount, reads `code` and optional `redirect` from URL search params, calls `supabase.auth.exchangeCodeForSession(code)`, on success navigates to `redirect` if present else `/create-team`, on error renders `<InlineError>` with link back to `/sign-in`. Reuses the existing `redirectSearchSchema` Zod validator at `web/src/router.tsx:87-93` (validates `redirect` starts with `/` to prevent open redirects).
-- `web/src/components/auth/AuthCallback/AuthCallback.test.tsx`
-
-**New helper** (`web/src/lib/auth-destination.ts`):
-- `getPostSignupDestination(redirectParam?: string): string` — returns `redirectParam` if present, else `/create-team`. Search-param validation is already enforced upstream by `redirectSearchSchema` (router.tsx:87-93) when the route validates its search params, so this helper just chooses between two valid values. Used by `SignUpForm` (post-success when session is returned), `AuthCallback`, and `<CheckEmailNotice>`'s `onVerified` from the signup callsite. (`SignInForm`'s default destination stays as today's `/leagues`; this helper is the signup-flow default.)
-
 **Wiring:**
 - `web/src/contexts/AuthContext.tsx`:
   - Update `signUp()` to pass `options: { data: { displayName }, emailRedirectTo: ${window.location.origin}/auth/callback?redirect=<encoded redirect> }`. The `redirect` is read from the current location and forwarded so deep-links survive the email gap on the magic-link path.
-  - No new context method this commit (resend in commit 2).
+  - No new context method this commit (resend in commit 5).
 - `web/src/components/auth/SignUpForm/SignUpForm.tsx`:
   - After successful `signUp()`, branch on `data.session`:
     - If `session` is non-null (auto-confirm fallback if confirmations are ever disabled): existing navigate-to-destination logic at lines 68-72.
     - If `session` is null: set local `pending` state, render `<CheckEmailNotice email={email} onVerified={handleVerified} />` instead of the form. `handleVerified` runs the same destination logic via `getPostSignupDestination`.
-- `web/src/router.tsx`:
-  - Add `/auth/callback` as a public child of root (sibling to `/sign-up`, `/sign-in`). Accepts `code` and optional `redirect` search params validated via Zod.
 
 **Tests:**
 - `SignUpForm.test.tsx`:
   - When mocked `signUp` returns no session, `<CheckEmailNotice>` is rendered and no navigation occurs
   - When mocked `signUp` returns a session (auto-confirm fallback), existing navigation behavior preserved
-- `CheckEmailNotice.test.tsx`:
-  - Renders email and code input
-  - Submitting valid code calls `supabase.auth.verifyOtp` with expected args
-  - On verify success, calls `onVerified` prop
-  - On verify error, renders `<InlineError>`
-  - Code input enforces 6 digits / numeric only (via `inputMode` and `pattern` — server is the source of truth)
-- `AuthCallback.test.tsx`:
-  - On mount with `code` param, calls `exchangeCodeForSession` and navigates to `redirect` or default
-  - On exchange error, renders `<InlineError>` with `/sign-in` link
-  - With no `code` param, renders error state
 - `AuthContext.test.tsx`:
   - `signUp` calls Supabase with the expected `emailRedirectTo` (including the forwarded `redirect` query)
-- E2E (`e2e/tests/auth.spec.ts`): TWO new tests using Inbucket's REST API:
-  - List mailbox: `GET http://127.0.0.1:54424/api/v1/mailbox/<email>` returns JSON array of message metadata
-  - Fetch message: `GET http://127.0.0.1:54424/api/v1/mailbox/<email>/<id>` returns body
-  - Port 54424 = Inbucket dev port 54324 (`api/supabase/config.toml:96`) + 100 per the e2e port-shift rule
-  - Magic-link path: fill signup form via UI → assert `<CheckEmailNotice>` appears → fetch the latest mail → extract the magic link from the body → navigate Playwright to it → assert the app shows `/create-team`
-  - OTP path: fill signup form → assert `<CheckEmailNotice>` appears → fetch the same mail → extract the 6-digit token → type it into the OTP input → assert the app shows `/create-team`
 
 **Verification:**
 1. `cd e2e/supabase && supabase stop && supabase start` to pick up config changes (also `cd api/supabase && supabase stop && supabase start`)
-2. `npm run web:dev` + `npm run api:watch`; sign up with a fresh email; confirm `<CheckEmailNotice>` appears; open Inbucket at `http://127.0.0.1:54324`; both pathways work — clicking the link AND typing the code each result in landing on `/create-team`
-3. `npm run web:test` + `npm run api:test` + `npm run e2e` all green
+2. `npm run web:dev` + `npm run api:watch`; sign up with a fresh email; confirm `<CheckEmailNotice>` appears; open the Mailpit UI at `http://127.0.0.1:54324` (served by the container Supabase still names `supabase_inbucket_*`); both pathways work — clicking the link AND typing the code each result in landing on `/create-team`
+3. `npm run web:test` + `npm run api:test` green
+4. `npm run e2e` green — existing tests continue working via the admin-API fixture's `email_confirm: true` (auto-confirms, bypassing the email step)
+
+---
+
+### Commit 4 — E2E coverage for magic-link and OTP signup paths
+
+**Goal:** Cross-system assertion that the wired-up flow from commit 3 actually works end-to-end through a real browser, against the local Supabase + Mailpit stack.
+
+**New fixture** (`e2e/fixtures/mailpit.ts`):
+- Helper functions: `searchByRecipient(email)`, `getMessage(id)`, `clearAll()`. Targets `http://127.0.0.1:54424` (e2e Mailpit).
+- **Note on naming:** Supabase CLI replaced Inbucket with Mailpit but kept the `[inbucket]` config block and the container name `supabase_inbucket_*` for backward compatibility. The actual image is `public.ecr.aws/supabase/mailpit` (verified via `docker inspect`), and the API surface is Mailpit's, not Inbucket's.
+- **Search by recipient:** `GET /api/v1/search?query=to:<urlencoded email>` — returns newest-first. Verified shape:
+  ```json
+  { "total": 15, "count": 1, "messages_count": 1,
+    "messages": [ { "ID": "Vqp696v5jB9384dNn4y8Pr",
+      "From": { "Name": "Admin", "Address": "admin@email.com" },
+      "To": [ { "Name": "", "Address": "bob2@test.com" } ],
+      "Subject": "Confirm your F1 Fantasy email",
+      "Created": "2026-05-10T04:29:00.864Z",
+      "Snippet": "Confirm your email Welcome to F1 Fantasy!..." } ] }
+  ```
+- **Fetch message body:** `GET /api/v1/message/{ID}` — note singular `message`. Returns `{ ID, Text, HTML, ... }`. The `Text` body of a Supabase signup email contains both the magic link and the OTP. Verified excerpt:
+  ```
+  Confirm your email ( http://127.0.0.1:54421/auth/v1/verify?token=pkce_49af69736d98ab8581cfb35402e76a84b69db32b81ec70fd4f78af8b&type=signup&redirect_to=http://localhost:5273/auth/callback )
+
+  Or enter this code in the app: *765877*
+  ```
+  The verify URL is *Supabase's* endpoint (port 54421 in e2e); hitting it 302s to the app callback (`http://localhost:5273/auth/callback?code=...`) which `<AuthCallback>` then exchanges for a session. The OTP is wrapped in `*…*` (markdown bold).
+- **Per-test isolation:** `DELETE /api/v1/messages` (no body) clears all mailboxes — call from a per-test `beforeEach` so prior tests' emails don't bleed in.
+- **Port arithmetic:** 54424 = Mailpit dev port 54324 (`api/supabase/config.toml:96`, under the still-named `[inbucket]` block) + 100 per the e2e port-shift rule.
+
+**New e2e tests** (`e2e/tests/auth.spec.ts`):
+- **Magic-link path:** fill signup form via UI → assert `<CheckEmailNotice>` appears → search Mailpit for the address → GET the message → regex `Text` for the verify URL → `page.goto(verifyUrl)` → assert the app shows `/create-team`.
+- **OTP path:** fill signup form → assert `<CheckEmailNotice>` appears → search Mailpit → GET the same message → regex `Text` for `/Or enter this code in the app: \*(\d{6})\*/` → type the 6 digits into the OTP input → assert the app shows `/create-team`.
+
+**Verification:**
+- `npm run e2e` green (existing suite + the two new tests)
 
 ---
 
-### Commit 2 — Resend confirmation email
+### Commit 5 — Resend confirmation email
 
 **Goal:** "Resend" button on the pending UI re-sends the confirmation email (which contains both link and OTP).
 
@@ -134,13 +199,13 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - `SignUpForm.test.tsx`: Resend button passes the current `redirect` param to `resendConfirmation`
 
 **Verification:**
-- Manual: sign up, click Resend, verify a second email appears in Inbucket; either email's link OR either email's most-recent OTP completes verification
+- Manual: sign up, click Resend, verify a second email appears in Mailpit; either email's link OR either email's most-recent OTP completes verification
 - Manual: rapid-fire Resend → rate-limit message
 - All test commands green
 
 ---
 
-### Commit 3 — Friendly handling of unconfirmed-email sign-in
+### Commit 6 — Friendly handling of unconfirmed-email sign-in
 
 **Goal:** If a user signs up but never confirms, then later tries to sign in, they see the same `<CheckEmailNotice>` (with OTP entry + Resend) instead of a generic auth error.
 
@@ -163,37 +228,38 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 ## Critical files
 
 **Modified:**
-- `api/supabase/config.toml` (commit 1)
-- `e2e/supabase/config.toml` (commit 1)
 - `web/src/lib/supabase.ts` (commit 1 — add `flowType: 'pkce'`)
-- `web/src/contexts/AuthContext.tsx` (commits 1, 2)
-- `web/src/contexts/AuthContext.ts` (commit 2)
-- `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commit 1, minor in commit 2)
-- `web/src/components/auth/SignInForm/SignInForm.tsx` (commit 3)
 - `web/src/router.tsx` (commit 1 — add `/auth/callback` route)
+- `api/supabase/config.toml` (commit 3)
+- `e2e/supabase/config.toml` (commit 3)
+- `web/src/contexts/AuthContext.tsx` (commits 3, 5)
+- `web/src/contexts/AuthContext.ts` (commit 5)
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commit 3, minor in commit 5)
+- `web/src/components/auth/SignInForm/SignInForm.tsx` (commit 6)
 
 **New:**
-- `api/supabase/templates/confirmation.html` (commit 1; includes both link and OTP from the start)
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` + `.test.tsx` (commit 1; expanded in commit 2)
 - `web/src/components/auth/AuthCallback/AuthCallback.tsx` + `.test.tsx` (commit 1)
-- `web/src/lib/auth-destination.ts` (commit 1)
-- `web/src/components/ui/input-otp.tsx` (commit 1; added via shadcn workflow — exact path matches existing shadcn components in the project)
-- `web/package.json` — adds `input-otp` dependency (commit 1)
+- `web/src/lib/auth-destination.ts` + `auth-destination.test.ts` (commit 1)
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` + `.test.tsx` (commit 2; expanded in commit 5)
+- `web/src/components/ui/input-otp.tsx` (commit 2; added via shadcn workflow — exact path matches existing shadcn components in the project)
+- `web/package.json` — adds `input-otp` dependency (commit 2)
+- `api/supabase/templates/confirmation.html` (commit 3; includes both link and OTP from the start)
+- `e2e/fixtures/mailpit.ts` (commit 4)
+- New tests in `e2e/tests/auth.spec.ts` (commit 4)
 
 **Reused (existing components, no changes):**
 - `web/src/components/InlineError/InlineError.tsx` — error display in `<AuthCallback>`, `<CheckEmailNotice>`, existing forms
 - `web/src/components/LiveRegion/LiveRegion.tsx` — screen-reader announcements
 - `web/src/components/LoadingButton/LoadingButton.tsx` — Verify and Resend button loading states
-- `web/src/lib/supabase.ts` — Supabase client singleton
-- `web/src/hooks/useAuth.ts` — auth hook (gains `resendConfirmation` in commit 2)
+- `web/src/hooks/useAuth.ts` — auth hook (gains `resendConfirmation` in commit 5)
 
 ---
 
-## End-to-end verification (after all 3 commits)
+## End-to-end verification (after all 6 commits)
 
-1. **Magic-link happy path:** Sign up with new email → see `<CheckEmailNotice>` → check Inbucket → click link → land on `/create-team` logged in
-2. **OTP happy path:** Sign up with new email → see `<CheckEmailNotice>` → check Inbucket → type 6-digit code into OTP field → land on `/create-team` logged in
-3. **Resend:** Sign up → click Resend → second email arrives in Inbucket → either email's link OR the latest OTP completes verification (older OTP is invalidated by the new send per Supabase's behavior)
+1. **Magic-link happy path:** Sign up with new email → see `<CheckEmailNotice>` → check Mailpit → click link → land on `/create-team` logged in
+2. **OTP happy path:** Sign up with new email → see `<CheckEmailNotice>` → check Mailpit → type 6-digit code into OTP field → land on `/create-team` logged in
+3. **Resend:** Sign up → click Resend → second email arrives in Mailpit → either email's link OR the latest OTP completes verification (older OTP is invalidated by the new send per Supabase's behavior)
 4. **Unconfirmed sign-in:** Sign up → DON'T confirm → go to `/sign-in` → submit credentials → see `<CheckEmailNotice>` → resend or OTP entry both work → land on `/leagues` (or wherever `redirect` param pointed)
 5. **Existing e2e tests:** `npm run e2e` all green (admin fixture continues working via `email_confirm: true`)
 6. **All tests + format + lint:** `npm run test:all` + `npm run web:lint` + `npm run web:format:check` + `npm run api:format:check` all green

From 8a4a2149575733463213182aa519187c776d4850 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Mon, 11 May 2026 08:18:19 -0500
Subject: [PATCH 03/25] docs: rename Inbucket label to Mailpit; link CLAUDE.md
 topology pointer

Supabase swapped the local email-testing binary to Mailpit while leaving
the [inbucket] config block name and supabase_inbucket_* container name in
place for back-compat. The runtime, REST API, and UI are 100% Mailpit, so
the README port table now labels the column accordingly. Convert the
CLAUDE.md pointer into a proper markdown link to the README section.
---
 CLAUDE.md | 2 +-
 README.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index c5908a5..231ec8b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -212,7 +212,7 @@ Open this folder in VSCode and use:
 
 ## Local Services Topology
 
-See `README.md` → "Local Services Topology" for the dev vs e2e stack layout, port-shift rule, and migration-sharing details. Quick recall: dev processes use Supabase `54321–54324` / web `5173` / API `5077`; e2e processes are all shifted by +100; `api/supabase/migrations/` is the source of truth and e2e symlinks to it.
+See [Local Services Topology](README.md#local-services-topology) in the README for the dev vs e2e stack layout, port-shift rule, and migration-sharing details. Quick recall: dev processes use Supabase `54321–54324` / web `5173` / API `5077`; e2e processes are all shifted by +100; `api/supabase/migrations/` is the source of truth and e2e symlinks to it.
 
 ## Production Infrastructure
 
diff --git a/README.md b/README.md
index fb99aee..62c36ec 100644
--- a/README.md
+++ b/README.md
@@ -109,7 +109,7 @@ npm run test:all               # Frontend + backend (unit + integration). Does n
 
 Two Supabase CLI stacks and two sets of web/API servers coexist on one machine so dev work and the e2e suite never touch the same state.
 
-| Stack | Config          | Supabase ports (API/DB/Studio/Inbucket) | Web port | API port |
+| Stack | Config          | Supabase ports (API/DB/Studio/Mailpit) | Web port | API port |
 | ----- | --------------- | --------------------------------------- | -------- | -------- |
 | Dev   | `api/supabase/` | `54321 / 54322 / 54323 / 54324`         | `5173`   | `5077`   |
 | E2E   | `e2e/supabase/` | `54421 / 54422 / 54423 / 54424`         | `5273`   | `5177`   |

From 23ca5ec8069eb19742d967065985f96ea7a230fd Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Mon, 11 May 2026 18:14:45 -0500
Subject: [PATCH 04/25] feat(web): add PKCE flow and /auth/callback loader
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Switches the Supabase client to `flowType: 'pkce'` so confirmation emails
return `?code=` instead of `#access_token=`, and adds a new
`/auth/callback` route that exchanges the code for a session via a route
loader. On success the loader redirects to the `redirect` search param
(else `/create-team`); on failure it captures to Sentry and rethrows so
the inline `errorComponent` renders the back-to-sign-in affordance.

Safe to land while `enable_confirmations` remains `false` — the route
exists but nothing emits a magic link yet, and PKCE is fully compatible
with the existing implicit-flow happy path.

Adds `getPostSignupDestination` helper, integration coverage over loader
branches (default destination, redirect param, missing code, supabase
error, supabase rejection), and unit coverage for the helper.

Refs #164
---
 web/src/lib/auth-destination.test.ts          |  25 ++
 web/src/lib/auth-destination.ts               |   8 +
 web/src/lib/supabase.test.ts                  |   6 +-
 web/src/lib/supabase.ts                       |   6 +-
 web/src/router.tsx                            |  78 ++++++
 .../auth-callback.integration.test.tsx        | 225 ++++++++++++++++++
 6 files changed, 346 insertions(+), 2 deletions(-)
 create mode 100644 web/src/lib/auth-destination.test.ts
 create mode 100644 web/src/lib/auth-destination.ts
 create mode 100644 web/src/tests/integration/auth-callback.integration.test.tsx

diff --git a/web/src/lib/auth-destination.test.ts b/web/src/lib/auth-destination.test.ts
new file mode 100644
index 0000000..873b384
--- /dev/null
+++ b/web/src/lib/auth-destination.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { getPostSignupDestination } from './auth-destination';
+
+describe('getPostSignupDestination', () => {
+  it('returns the redirect param when provided', () => {
+    expect(getPostSignupDestination('/leagues')).toBe('/leagues');
+  });
+
+  it('returns the redirect param for nested paths', () => {
+    expect(getPostSignupDestination('/leagues/123')).toBe('/leagues/123');
+  });
+
+  it('falls back to /create-team when redirect is undefined', () => {
+    expect(getPostSignupDestination(undefined)).toBe('/create-team');
+  });
+
+  it('falls back to /create-team when redirect is omitted', () => {
+    expect(getPostSignupDestination()).toBe('/create-team');
+  });
+
+  it('falls back to /create-team when redirect is an empty string', () => {
+    expect(getPostSignupDestination('')).toBe('/create-team');
+  });
+});
diff --git a/web/src/lib/auth-destination.ts b/web/src/lib/auth-destination.ts
new file mode 100644
index 0000000..68d8401
--- /dev/null
+++ b/web/src/lib/auth-destination.ts
@@ -0,0 +1,8 @@
+const DEFAULT_POST_SIGNUP_DESTINATION = '/create-team';
+
+export function getPostSignupDestination(redirectParam?: string): string {
+  if (redirectParam) {
+    return redirectParam;
+  }
+  return DEFAULT_POST_SIGNUP_DESTINATION;
+}
diff --git a/web/src/lib/supabase.test.ts b/web/src/lib/supabase.test.ts
index af07111..3a2a51f 100644
--- a/web/src/lib/supabase.test.ts
+++ b/web/src/lib/supabase.test.ts
@@ -77,6 +77,10 @@ describe('supabase module initialization', () => {
 
     await import('./supabase');
 
-    expect(createClient).toHaveBeenCalledWith('https://myproject.supabase.co', 'my-anon-key');
+    expect(createClient).toHaveBeenCalledWith('https://myproject.supabase.co', 'my-anon-key', {
+      auth: {
+        flowType: 'pkce',
+      },
+    });
   });
 });
diff --git a/web/src/lib/supabase.ts b/web/src/lib/supabase.ts
index 48eab95..23b6b80 100644
--- a/web/src/lib/supabase.ts
+++ b/web/src/lib/supabase.ts
@@ -11,4 +11,8 @@ if (!supabaseAnonKey) {
   throw new Error('Missing required environment variable: VITE_SUPABASE_ANON_KEY');
 }
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey);
+export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
+  auth: {
+    flowType: 'pkce',
+  },
+});
diff --git a/web/src/router.tsx b/web/src/router.tsx
index cdac3aa..5576977 100644
--- a/web/src/router.tsx
+++ b/web/src/router.tsx
@@ -2,6 +2,7 @@ import { Account } from '@/components/Account/Account';
 import { CreateTeam } from '@/components/CreateTeam/CreateTeam';
 import { ErrorBoundary } from '@/components/ErrorBoundary/ErrorBoundary';
 import { ErrorFallback } from '@/components/ErrorBoundary/ErrorFallback';
+import { InlineError } from '@/components/InlineError/InlineError';
 import { LandingPage } from '@/components/LandingPage/LandingPage';
 import { Layout } from '@/components/Layout/Layout';
 import { League } from '@/components/League/League';
@@ -9,10 +10,13 @@ import { LeagueList } from '@/components/LeagueList/LeagueList';
 import { MyTeamRoute, TeamRoute } from '@/components/Team/Team';
 import { SignInForm } from '@/components/auth/SignInForm/SignInForm';
 import { SignUpForm } from '@/components/auth/SignUpForm/SignUpForm';
+import { Button } from '@/components/ui/button';
 import type { Team as TeamType } from '@/contracts/Team';
 import type { UserProfile } from '@/contracts/UserProfile';
+import { getPostSignupDestination } from '@/lib/auth-destination';
 import { requireAuth, requireNoTeam, requireTeam } from '@/lib/route-guards';
 import type { RouterContext } from '@/lib/router-context';
+import { supabase } from '@/lib/supabase';
 import { getAvailableLeagues, getLeagueById, getMyLeagues } from '@/services/leagueService';
 import { getLeagueStandings } from '@/services/standingsService';
 import { getMyTeam, getTeamById } from '@/services/teamService';
@@ -20,6 +24,7 @@ import { userProfileService } from '@/services/userProfileService';
 import * as Sentry from '@sentry/react';
 import {
   ErrorComponent,
+  Link,
   Outlet,
   createRootRouteWithContext,
   createRoute,
@@ -92,6 +97,22 @@ const redirectSearchSchema = z.object({
     .catch(undefined),
 });
 
+/**
+ * Zod schema for validating the /auth/callback search params.
+ *
+ * The PKCE flow returns a `code` param from Supabase that must be exchanged for
+ * a session. `redirect` is forwarded through the email link so the user lands
+ * on the intended destination after confirmation.
+ */
+const authCallbackSearchSchema = z.object({
+  code: z.string().optional().catch(undefined),
+  redirect: z
+    .string()
+    .refine((url) => url.startsWith('/'), 'Redirect must be an internal path')
+    .optional()
+    .catch(undefined),
+});
+
 /**
  * Root route with context - wraps all routes in the application.
  *
@@ -223,6 +244,62 @@ const signUpRoute = createRoute({
   errorComponent: ({ error }) => <ErrorComponent error={error} />,
 });
 
+/**
+ * Auth callback route - public landing page for PKCE / magic-link returns.
+ *
+ * Supabase appends `code` (and optionally the forwarded `redirect`) to this URL
+ * when the user clicks a confirmation link. The loader exchanges the code for a
+ * session and throws a `redirect` to the post-confirmation destination. On any
+ * failure (missing code, expired/consumed code, network error) the loader
+ * captures to Sentry and rethrows so the `errorComponent` can render the
+ * back-to-sign-in affordance.
+ *
+ * @type {import('@tanstack/react-router').Route}
+ */
+const authCallbackRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/auth/callback',
+  validateSearch: authCallbackSearchSchema,
+  loaderDeps: ({ search }) => ({ code: search.code, redirect: search.redirect }),
+  loader: async ({ deps }) => {
+    try {
+      if (!deps.code) {
+        throw new Error('Missing confirmation code');
+      }
+      const { error } = await supabase.auth.exchangeCodeForSession(deps.code);
+      if (error) throw error;
+    } catch (err) {
+      const captured = err instanceof Error ? err : new Error('Auth callback failed');
+      Sentry.captureException(captured, {
+        tags: { component: 'authCallbackRoute', operation: 'exchangeCodeForSession' },
+      });
+      throw captured;
+    }
+
+    throw redirect({ to: getPostSignupDestination(deps.redirect) });
+  },
+  pendingComponent: () => (
+    <div role="status" className="flex w-full items-center justify-center p-8 md:min-h-screen">
+      <div className="text-center">
+        <div className="border-primary mx-auto mb-4 h-8 w-8 animate-spin rounded-full border-b-2"></div>
+        <p className="text-muted-foreground">Confirming your email...</p>
+      </div>
+    </div>
+  ),
+  errorComponent: () => (
+    <div className="flex w-full items-center justify-center p-8 md:min-h-screen">
+      <div className="w-full max-w-md space-y-4">
+        <InlineError message="We couldn't confirm your email. The link may have expired or already been used." />
+        <div className="text-center">
+          <Button variant="link" asChild className="text-sm">
+            <Link to="/sign-in">Back to sign in</Link>
+          </Button>
+        </div>
+      </div>
+    </div>
+  ),
+});
+
 /**
  * Join invite route - public route for previewing and joining leagues via invite link.
  *
@@ -708,6 +785,7 @@ const routeTree = rootRoute.addChildren([
   indexRoute,
   signInRoute,
   signUpRoute,
+  authCallbackRoute,
   joinInviteRoute,
   authenticatedLayoutRoute.addChildren([
     accountRoute,
diff --git a/web/src/tests/integration/auth-callback.integration.test.tsx b/web/src/tests/integration/auth-callback.integration.test.tsx
new file mode 100644
index 0000000..79cad33
--- /dev/null
+++ b/web/src/tests/integration/auth-callback.integration.test.tsx
@@ -0,0 +1,225 @@
+import { InlineError } from '@/components/InlineError/InlineError';
+import { Button } from '@/components/ui/button';
+import { getPostSignupDestination } from '@/lib/auth-destination';
+import type { RouterContext } from '@/lib/router-context';
+import { supabase } from '@/lib/supabase';
+import {
+  buildStubRoute,
+  createBaseRouterContext,
+  createUnauthAuth,
+  renderWithRouter,
+} from '@/tests/test-utils';
+import * as Sentry from '@sentry/react';
+import {
+  Link,
+  Outlet,
+  createRootRouteWithContext,
+  createRoute,
+  redirect,
+} from '@tanstack/react-router';
+import { screen } from '@testing-library/react';
+import type { MockedFunction } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+
+// Supabase is a third party we don't own — stub its client per the testing
+// strategy ("Stub third parties you don't own"). The auth.exchangeCodeForSession
+// call talks to Supabase's auth server, not our API, so MSW can't intercept it.
+vi.mock('@/lib/supabase', () => ({
+  supabase: {
+    auth: {
+      exchangeCodeForSession: vi.fn(),
+    },
+  },
+}));
+
+vi.mock('@sentry/react', () => ({
+  captureException: vi.fn(),
+}));
+
+const authCallbackSearchSchema = z.object({
+  code: z.string().optional().catch(undefined),
+  redirect: z
+    .string()
+    .refine((url) => url.startsWith('/'), 'Redirect must be an internal path')
+    .optional()
+    .catch(undefined),
+});
+
+// Mirrors `authCallbackRoute` from `router.tsx`. Per the integration-test
+// convention, production routes aren't exported so the route under test is
+// rebuilt inline — only what the test needs to mount.
+function buildAuthCallbackRouteTree() {
+  const rootRoute = createRootRouteWithContext<RouterContext>()({
+    component: () => <Outlet />,
+  });
+
+  const authCallbackRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/auth/callback',
+    validateSearch: authCallbackSearchSchema,
+    loaderDeps: ({ search }) => ({ code: search.code, redirect: search.redirect }),
+    loader: async ({ deps }) => {
+      try {
+        if (!deps.code) {
+          throw new Error('Missing confirmation code');
+        }
+        const { error } = await supabase.auth.exchangeCodeForSession(deps.code);
+        if (error) throw error;
+      } catch (err) {
+        const captured = err instanceof Error ? err : new Error('Auth callback failed');
+        Sentry.captureException(captured, {
+          tags: { component: 'authCallbackRoute', operation: 'exchangeCodeForSession' },
+        });
+        throw captured;
+      }
+      throw redirect({ to: getPostSignupDestination(deps.redirect) });
+    },
+    errorComponent: () => (
+      <div className="flex w-full items-center justify-center p-8 md:min-h-screen">
+        <div className="w-full max-w-md space-y-4">
+          <InlineError message="We couldn't confirm your email. The link may have expired or already been used." />
+          <div className="text-center">
+            <Button variant="link" asChild className="text-sm">
+              <Link to="/sign-in">Back to sign in</Link>
+            </Button>
+          </div>
+        </div>
+      </div>
+    ),
+  });
+
+  const createTeamStub = buildStubRoute(rootRoute, {
+    path: 'create-team',
+    heading: 'Create Team',
+  });
+
+  const leaguesStub = buildStubRoute(rootRoute, {
+    path: 'leagues',
+    heading: 'My Leagues',
+  });
+
+  const signInStub = buildStubRoute(rootRoute, {
+    path: 'sign-in',
+    heading: 'Sign In',
+  });
+
+  return rootRoute.addChildren([authCallbackRoute, createTeamStub, leaguesStub, signInStub]);
+}
+
+describe('/auth/callback', () => {
+  const exchangeMock = supabase.auth.exchangeCodeForSession as unknown as MockedFunction<
+    typeof supabase.auth.exchangeCodeForSession
+  >;
+  const captureExceptionMock = Sentry.captureException as unknown as MockedFunction<
+    typeof Sentry.captureException
+  >;
+
+  beforeEach(() => {
+    exchangeMock.mockReset();
+    captureExceptionMock.mockReset();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('exchanges the code and lands on /create-team by default', async () => {
+    exchangeMock.mockResolvedValueOnce({
+      data: { session: null, user: null },
+      error: null,
+    } as unknown as Awaited<ReturnType<typeof supabase.auth.exchangeCodeForSession>>);
+
+    renderWithRouter({
+      routeTree: buildAuthCallbackRouteTree(),
+      initialEntry: '/auth/callback?code=abc123',
+      auth: createUnauthAuth(),
+      routerContext: createBaseRouterContext(),
+    });
+
+    expect(await screen.findByRole('heading', { name: /create team/i })).toBeInTheDocument();
+    expect(exchangeMock).toHaveBeenCalledWith('abc123');
+    expect(captureExceptionMock).not.toHaveBeenCalled();
+  });
+
+  it('honors the redirect search param when present', async () => {
+    exchangeMock.mockResolvedValueOnce({
+      data: { session: null, user: null },
+      error: null,
+    } as unknown as Awaited<ReturnType<typeof supabase.auth.exchangeCodeForSession>>);
+
+    renderWithRouter({
+      routeTree: buildAuthCallbackRouteTree(),
+      initialEntry: '/auth/callback?code=abc123&redirect=%2Fleagues',
+      auth: createUnauthAuth(),
+      routerContext: createBaseRouterContext(),
+    });
+
+    expect(await screen.findByRole('heading', { name: /my leagues/i })).toBeInTheDocument();
+  });
+
+  it('renders the error UI and captures to Sentry when no code is present', async () => {
+    renderWithRouter({
+      routeTree: buildAuthCallbackRouteTree(),
+      initialEntry: '/auth/callback',
+      auth: createUnauthAuth(),
+      routerContext: createBaseRouterContext(),
+    });
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(/couldn't confirm your email/i);
+    expect(screen.getByRole('link', { name: /back to sign in/i })).toHaveAttribute(
+      'href',
+      '/sign-in',
+    );
+    expect(exchangeMock).not.toHaveBeenCalled();
+    expect(captureExceptionMock).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'Missing confirmation code' }),
+      expect.objectContaining({
+        tags: expect.objectContaining({ component: 'authCallbackRoute' }),
+      }),
+    );
+  });
+
+  it('renders the error UI and captures to Sentry when supabase returns an error', async () => {
+    const supabaseError = new Error('invalid code');
+    exchangeMock.mockResolvedValueOnce({
+      data: { session: null, user: null },
+      error: supabaseError,
+    } as unknown as Awaited<ReturnType<typeof supabase.auth.exchangeCodeForSession>>);
+
+    renderWithRouter({
+      routeTree: buildAuthCallbackRouteTree(),
+      initialEntry: '/auth/callback?code=abc123',
+      auth: createUnauthAuth(),
+      routerContext: createBaseRouterContext(),
+    });
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(/couldn't confirm your email/i);
+    expect(captureExceptionMock).toHaveBeenCalledWith(
+      supabaseError,
+      expect.objectContaining({
+        tags: expect.objectContaining({ component: 'authCallbackRoute' }),
+      }),
+    );
+  });
+
+  it('renders the error UI and captures to Sentry when supabase rejects', async () => {
+    const rejection = new Error('network down');
+    exchangeMock.mockRejectedValueOnce(rejection);
+
+    renderWithRouter({
+      routeTree: buildAuthCallbackRouteTree(),
+      initialEntry: '/auth/callback?code=abc123',
+      auth: createUnauthAuth(),
+      routerContext: createBaseRouterContext(),
+    });
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(/couldn't confirm your email/i);
+    expect(captureExceptionMock).toHaveBeenCalledWith(
+      rejection,
+      expect.objectContaining({
+        tags: expect.objectContaining({ component: 'authCallbackRoute' }),
+      }),
+    );
+  });
+});

From a02cf2d4d840d00f7bc1c6ec75859cc373ded2f2 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Mon, 11 May 2026 18:15:23 -0500
Subject: [PATCH 05/25] docs(plans): reflect loader-based auth callback design

Updates the #164 plan to match what actually landed in commit 1: the
auth-callback work uses a route loader and inline `errorComponent`
rather than a dedicated `AuthCallback` component with `useEffect`.

- New Decisions row documents the loader+inline-errorComponent choice
  (idiomatic for this codebase, avoids `useEffect` + `cancelled`-flag
  anti-pattern, `ErrorFallback` doesn't fit).
- New Decisions row records the manual Sentry-capture pattern in the
  loader and points at #180 for the broader observability gap.
- Commit 1 section rewritten: drops the AuthCallback component bullets,
  describes the loader/pendingComponent/errorComponent wiring directly,
  and replaces unit-test cases with integration-test coverage.
- Critical files updated to remove `AuthCallback/` and add the new
  integration test.
- Removes the redundant cross-issue ordering paragraph from Context
  (already captured in the Decisions table).
- Adds the loader-error observability gap to "Known preexisting
  concerns" with a pointer to #180.

Refs #164
---
 docs/plans/164-email-confirmation-signup.md | 46 ++++++++++++---------
 1 file changed, 26 insertions(+), 20 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index 42a194d..e94216a 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -10,8 +10,6 @@ Email confirmations are currently disabled in Supabase (`enable_confirmations =
 4. Complete verification when the user clicks the email link
 5. Handle the case where an unconfirmed user later tries to sign in
 
-**Cross-issue ordering** — this issue should ship before #167 (change-email re-verification, which reuses the same `/auth/callback` route and OTP entry UI) and before #165 (sign-in/redirect audit, which standardizes destinations across all auth flows). 164 preserves today's destination logic; 165 will standardize it later.
-
 **Out of scope:**
 - Branded email template content (deferred to #22)
 - Standardizing post-auth redirect destinations (deferred to #165)
@@ -31,6 +29,8 @@ Email confirmations are currently disabled in Supabase (`enable_confirmations =
 | E2E approach | Existing admin-API fixture keeps `email_confirm: true` (auto-confirms); add two new tests in commit 4 (magic-link path + OTP path) | Existing tests stay fast; targeted e2e covers the new wiring |
 | Email template | Custom template at `api/supabase/templates/confirmation.html` includes both `{{ .ConfirmationURL }}` and `{{ .Token }}`, lands in commit 3 alongside the config flip | Default Supabase template already has both; we're shipping our own to control wording and prep for #22's branding |
 | Cross-issue ordering | 164 → 167 → 165 (locked) | 164 builds verification primitives; 167 reuses callback route + OTP entry pattern for change-email re-verification; 165 audits all destinations after both new flows exist. |
+| Auth callback implementation | **Route loader + inline `errorComponent`, no separate component** | Async work belongs in a TanStack Router `loader` (matches every other async route in the codebase — `joinInviteRoute`, `accountRoute`, etc.); avoids the `useEffect` + `cancelled`-flag anti-pattern. Side effects (Sentry capture) live at the failure site inside the loader's `try/catch`, not in a render-time hook. The shared `ErrorFallback` doesn't fit (hardcoded copy + "Try again" button; reloading can't fix a consumed PKCE code), and the bespoke error UI is small enough to inline in `errorComponent` rather than warrant a dedicated component file. |
+| Sentry coverage for loader failures | Manual `Sentry.captureException` inside the loader's `try/catch` | The auth-callback failure mode is a Supabase SDK error that bypasses `apiClient`'s built-in HTTP-error capture, so without explicit capture in the loader, Sentry never sees PKCE failures. This is consistent with the existing pattern in `rootRoute.beforeLoad`. The codebase-wide observability gap (loader failures outside `apiClient` are silently rendered) is tracked separately in #180; commit 1 doesn't try to solve it here. |
 
 ---
 
@@ -38,7 +38,7 @@ Email confirmations are currently disabled in Supabase (`enable_confirmations =
 
 Each commit is a gate. Each must independently build, lint, test, and format. Wait for approval before moving on. Note: these commits are sized for review/approval — they don't necessarily map 1:1 to production deploys. Recommendation is to land all six before flipping production confirmations on, so users always have the OTP fallback path. The local-dev confirmation flip happens in commit 3; commits 1–2 are preparatory and safe under `enable_confirmations = false`.
 
-### Commit 1 — PKCE flow + `/auth/callback` route + AuthCallback handler
+### Commit 1 — PKCE flow + `/auth/callback` loader
 
 **Goal:** Stand up the magic-link landing page and switch the Supabase client to PKCE so the link returns `?code=` instead of an implicit hash. Safe to land while `enable_confirmations` is still `false`: the route exists but nothing emits a magic link yet, and PKCE is fully compatible with the existing implicit-flow happy path.
 
@@ -47,30 +47,35 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - Required: pass `{ auth: { flowType: 'pkce' } }` so the magic link returns `?code=` (which `exchangeCodeForSession` consumes) instead of `#access_token=` (implicit hash flow)
 - This is a small but app-wide auth behavior change — covered by existing AuthContext tests
 
-**New components:**
-- `web/src/components/auth/AuthCallback/AuthCallback.tsx` — handles the magic-link return: on mount, reads `code` and optional `redirect` from URL search params, calls `supabase.auth.exchangeCodeForSession(code)`, on success navigates to `redirect` if present else `/create-team`, on error renders `<InlineError>` with link back to `/sign-in`. Reuses the existing `redirectSearchSchema` Zod validator at `web/src/router.tsx:87-93` (validates `redirect` starts with `/` to prevent open redirects).
-- `web/src/components/auth/AuthCallback/AuthCallback.test.tsx`
-
 **New helper** (`web/src/lib/auth-destination.ts`):
-- `getPostSignupDestination(redirectParam?: string): string` — returns `redirectParam` if present, else `/create-team`. Search-param validation is already enforced upstream by `redirectSearchSchema` (router.tsx:87-93) when the route validates its search params, so this helper just chooses between two valid values. Used by `AuthCallback` here, and later by `SignUpForm` and `<CheckEmailNotice>`'s `onVerified` from the signup callsite (commit 3). Lands here because AuthCallback is its first caller.
+- `getPostSignupDestination(redirectParam?: string): string` — returns `redirectParam` if present, else `/create-team`. Search-param validation is already enforced upstream by the route's Zod schema, so this helper just chooses between two valid values. Used by the auth-callback loader here, and later by `SignUpForm` and `<CheckEmailNotice>`'s `onVerified` from the signup callsite (commit 3). Lands here because the auth-callback loader is its first caller.
 
-**Wiring:**
-- `web/src/router.tsx` — add `/auth/callback` as a public child of root (sibling to `/sign-up`, `/sign-in`). Accepts `code` and optional `redirect` search params validated via Zod.
+**Wiring** (`web/src/router.tsx`):
+- New Zod schema `authCallbackSearchSchema` validates `code` (optional string) and `redirect` (optional string, must start with `/` — same shape as the existing `redirectSearchSchema`).
+- New `authCallbackRoute` as a public child of root (sibling to `/sign-up`, `/sign-in`). Built as a loader-driven route:
+  - `loaderDeps` pulls `code` and `redirect` from the validated search params.
+  - `loader` wraps the exchange in `try/catch`: if `code` is missing or `supabase.auth.exchangeCodeForSession` returns/rejects with an error, capture to Sentry with `tags: { component: 'authCallbackRoute', operation: 'exchangeCodeForSession' }` and rethrow. On success, `throw redirect({ to: getPostSignupDestination(redirect) })`.
+  - `pendingComponent` renders a "Confirming your email..." spinner during the loader phase.
+  - `errorComponent` is inlined: renders `<InlineError>` with the user-friendly copy and a "Back to sign in" `<Link>`. No dedicated component file — the shared `ErrorFallback` doesn't fit (hardcoded copy, "Try again" button that can't recover a consumed PKCE code), and the bespoke UI is ~15 lines of JSX.
+  - No `component` field — the loader always throws (`redirect` on success, captured error otherwise), so the route never renders to a normal component.
 
 **Tests:**
-- `AuthCallback.test.tsx`:
-  - On mount with `code` param, calls `exchangeCodeForSession` and navigates to `redirect` or default
-  - On exchange error, renders `<InlineError>` with `/sign-in` link
-  - With no `code` param, renders error state
+- `web/src/tests/integration/auth-callback.integration.test.tsx` — covers loader branches via a real router mounted over an inline route-tree mirror (matches the convention in `account.integration.test.tsx`):
+  - Default destination: with `?code=abc`, loader exchanges and redirects to `/create-team`; no Sentry capture.
+  - `redirect` honored: with `?code=abc&redirect=/leagues`, loader redirects to `/leagues`.
+  - Missing `code`: renders error UI + `Sentry.captureException` called with `component: authCallbackRoute`.
+  - Supabase returns error: renders error UI + Sentry captured with the supabase error.
+  - Supabase rejects: renders error UI + Sentry captured with the rejection.
 - `auth-destination.test.ts`:
-  - Returns the redirect param when provided
-  - Falls back to `/create-team` when redirect is missing/empty
+  - Returns the redirect param when provided.
+  - Falls back to `/create-team` when redirect is missing/empty.
 - Existing `AuthContext.test.tsx` keeps passing under PKCE (no behavioral change to the public API).
 
 **Verification:**
 1. `npm run web:test` green
 2. `npm run web:lint` + `npm run web:format:check` green
-3. Manual: existing signup/signin flow still works (auto-confirm path, no email sent because `enable_confirmations` is still `false`)
+3. `npm run web:build` green (TypeScript compile)
+4. Manual: existing signup/signin flow still works (auto-confirm path, no email sent because `enable_confirmations` is still `false`)
 
 ---
 
@@ -229,7 +234,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 
 **Modified:**
 - `web/src/lib/supabase.ts` (commit 1 — add `flowType: 'pkce'`)
-- `web/src/router.tsx` (commit 1 — add `/auth/callback` route)
+- `web/src/router.tsx` (commit 1 — add `/auth/callback` route with loader, pendingComponent, and inline errorComponent)
 - `api/supabase/config.toml` (commit 3)
 - `e2e/supabase/config.toml` (commit 3)
 - `web/src/contexts/AuthContext.tsx` (commits 3, 5)
@@ -238,8 +243,8 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - `web/src/components/auth/SignInForm/SignInForm.tsx` (commit 6)
 
 **New:**
-- `web/src/components/auth/AuthCallback/AuthCallback.tsx` + `.test.tsx` (commit 1)
 - `web/src/lib/auth-destination.ts` + `auth-destination.test.ts` (commit 1)
+- `web/src/tests/integration/auth-callback.integration.test.tsx` (commit 1)
 - `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` + `.test.tsx` (commit 2; expanded in commit 5)
 - `web/src/components/ui/input-otp.tsx` (commit 2; added via shadcn workflow — exact path matches existing shadcn components in the project)
 - `web/package.json` — adds `input-otp` dependency (commit 2)
@@ -248,7 +253,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - New tests in `e2e/tests/auth.spec.ts` (commit 4)
 
 **Reused (existing components, no changes):**
-- `web/src/components/InlineError/InlineError.tsx` — error display in `<AuthCallback>`, `<CheckEmailNotice>`, existing forms
+- `web/src/components/InlineError/InlineError.tsx` — error display in the auth-callback `errorComponent`, `<CheckEmailNotice>`, existing forms
 - `web/src/components/LiveRegion/LiveRegion.tsx` — screen-reader announcements
 - `web/src/components/LoadingButton/LoadingButton.tsx` — Verify and Resend button loading states
 - `web/src/hooks/useAuth.ts` — auth hook (gains `resendConfirmation` in commit 5)
@@ -277,3 +282,4 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 ## Known preexisting concern (out of scope)
 
 - `on_auth_user_created` trigger in `api/supabase/migrations/20260108000000_create_user_profile_trigger.sql` fires on every `INSERT` into `auth.users`, regardless of whether the user has confirmed their email. With confirmations enabled, this means `Accounts` and `UserProfiles` rows are created at signup time even if the user never confirms. Result: orphan rows accumulate from abandoned signups. Cleanup (e.g., a periodic job to remove unconfirmed users older than N days, or moving the trigger to fire only after confirmation) is out of 164's scope but should be tracked as follow-up.
+- Non-HTTP errors thrown from route loaders and `beforeLoad` guards are silently rendered to the user via `errorComponent` and never reach Sentry — `apiClient` only captures HTTP failures, and React's error-boundary path doesn't see errors caught at the route layer. The auth-callback loader works around this with manual `Sentry.captureException`, but the broader codebase-wide gap (parsing errors, schema mismatches, third-party SDK errors, runtime bugs across every data-loading route) is tracked separately in #180.

From 7cc96008523fe1949879aaa7fcee58f404695cdc Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Tue, 12 May 2026 12:23:48 -0500
Subject: [PATCH 06/25] docs(plans): swap commit 2 to hand-rolled OtpInput
 primitive

Replaces the shadcn input-otp vendoring with a custom OtpInput at
components/OtpInput/, fixing the slot-retargeting bug from shadcn/ui
#4046 and dropping the input-otp dependency. Updates props/styling/a11y
specs, restricts the test list to behavioral coverage per web/CLAUDE.md,
and spells out the consumer-side and dev-artifact cleanups (REGEXP_ONLY_DIGITS,
elementFromPoint polyfill, /dev/check-email scratch route).
---
 docs/plans/164-email-confirmation-signup.md | 80 ++++++++++++++++-----
 1 file changed, 63 insertions(+), 17 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index e94216a..7564312 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -20,7 +20,7 @@ Email confirmations are currently disabled in Supabase (`enable_confirmations =
 | Decision | Choice | Rationale |
 |---|---|---|
 | Confirmation method | **Both magic link AND OTP code** in the email; user can use whichever | Resilient to corporate email scanners (Defender, Barracuda, Mimecast) that pre-fetch links and consume the token before users click. Supabase auth issue [#1214](https://github.com/supabase/auth/issues/1214) is open and unfixed; no clean recovery for affected users without an OTP fallback. Default Supabase template already emits both, so the email-side cost is near zero. |
-| OTP input component | shadcn/ui `<InputOTP>` (uses `input-otp` library) | Renders single invisible `<input autocomplete="one-time-code">` behind visual digit boxes — combines accessible single input (WCAG 1.3.5) with visual digit-box UX. Consistent with project's existing shadcn/ui usage. |
+| OTP input component | Custom `<OtpInput>` at `web/src/components/OtpInput/` | Hand-rolled single-input + overlay slot pattern (same architecture as `input-otp`) that fixes the slot-retargeting bug ([shadcn/ui #4046](https://github.com/shadcn-ui/ui/issues/4046)) where clicking a non-final slot focuses the last cell. Preserves every must-have: single accessible `<input>` for WCAG 1.3.5, iOS/Android SMS autofill via `autocomplete="one-time-code"`, native paste, full keyboard a11y, auto-submit. Lives outside `ui/` because `ui/` is reserved for vendored shadcn; sits next to the other custom primitives (`LoadingButton`, `InlineError`). Removes the `input-otp` dependency. |
 | Pending-UI surface | Inline state + shared `<CheckEmailNotice>` component | No URL params (OWASP: PII like email shouldn't appear in URLs — leaks via browser history, server logs, Referer to Sentry). Refresh degrades benignly: link in inbox still works, resend reachable via signin path. |
 | Email passing | React state within form components | User never retypes — Supabase's confirmation token uniquely identifies the user. Email passed as prop from parent (`SignUpForm`, `SignInForm`) into `<CheckEmailNotice>`. |
 | Sign-in unconfirmed handling | In scope, same issue (commit 6) | Completes the verification story: signup → pending → resend → confirm AND signin → unconfirmed → resend. |
@@ -79,32 +79,79 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 
 ---
 
-### Commit 2 — `<CheckEmailNotice>` component + `input-otp` vendoring
-
-**Goal:** Add the pending-state UI as a self-contained, tested component. Not yet wired into any form — that happens in commit 3.
-
-**New dependency:**
-- `input-otp` package via shadcn CLI: `npx shadcn@latest add input-otp` — installs to `web/src/components/ui/input-otp.tsx`, matching the project's existing shadcn vendoring per `web/components.json` aliases. Per `web/CLAUDE.md`, shadcn primitives are vendored — do not modify after install. Adds `input-otp` to `web/package.json`.
-
-**New components:**
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — shared pending UI. Props:
+### Commit 2 — `<OtpInput>` primitive + `<CheckEmailNotice>` component
+
+**Goal:** Add the pending-state UI as a self-contained, tested component, backed by a hand-rolled `<OtpInput>` primitive (no `input-otp` dependency). End result is visually identical to the prior shadcn-based version but fixes the slot-retargeting bug so a user can click any slot to edit just that digit. Not yet wired into any form — that happens in commit 3.
+
+**New primitive — `<OtpInput>`** (`web/src/components/OtpInput/OtpInput.tsx`):
+
+- **Architecture:** Single-input + overlay slots, stacked via CSS Grid (not `position: absolute`). One real `<input>` and one slot-row `<div>` are both children of a `grid` container, both placed at `col-start-1 row-start-1` so they occupy the same cell. The input is rendered with transparent text and caret (`text-transparent caret-transparent`) and sits on top of the slot row, which is the visible UI driven by `value` and `selectionStart`. The slot-row `<div>` is itself a flex row (`flex justify-center gap-2.5`) carrying the 6 slot children. Grid stacking is preferred over `position: absolute` here because the container intrinsic-sizes to the slot row automatically — no `relative` ancestor or hand-tuned insets needed. Same end behavior as the `input-otp` library's overlay approach; the only meaningful difference is the click-to-edit handler that the library gets wrong.
+- **Scope of this primitive:** numeric OTP input only. The non-digit filter and `inputMode="numeric"` default are baked in; this is not a generic OTP primitive (no `pattern` prop). Spell that out in the component's JSDoc so a future caller doesn't try to pass alpha codes.
+- **Why this shape, not N individual inputs:** `<input autocomplete="one-time-code">` SMS autofill on iOS only works with a single input ([web.dev — SMS OTP form](https://web.dev/articles/sms-otp-form), confirmed broken on multi-input in [Chakra #4095](https://github.com/chakra-ui/chakra-ui/issues/4095), [react-verification-input #57](https://github.com/andreaswilli/react-verification-input/issues/57)). Paste, backspace, and arrow nav also come free at the browser level instead of needing hand-coded ref coordination.
+- **Props** (minimal, mirrors what `CheckEmailNotice` actually uses):
+  - `id?: string` — forwarded to the underlying `<input>` so external `<Label htmlFor>` works
+  - `value: string`
+  - `onChange: (value: string) => void`
+  - `length?: number` (default `6`) — also forwarded to the underlying `<input>` as `maxLength={length}` so attribute-based assertions on the labeled input (`maxlength='6'` in the existing `CheckEmailNotice.test.tsx`) keep passing
+  - `disabled?: boolean`
+  - `'aria-label'?: string`
+  - `autoComplete?: string` (default `"one-time-code"`)
+  - `inputMode?: HTMLAttributes<HTMLInputElement>['inputMode']` (default `"numeric"`)
+  - `className?: string` — merged via `cn()` onto the **grid container**, intended for outer sizing (e.g., `w-full`). Slot-row internal layout (`flex justify-center gap-2.5`) is baked in and not consumer-overridable — there's no third style hook by design, since the primitive owns its internal structure
+  - `slotClassName?: string` — merged via `cn()` onto each slot so consumers can override per-slot styling (size, border, active state) without forking the component (matches the shadcn convention of baking in defaults + allowing class overrides)
+  - **Internal `data-slot="otp-slot"` attribute** is set on each visible slot `<div>` as a styling/structure marker (mirrors the shadcn convention in `ui/input-otp.tsx:49`). Not a public test hook — tests should query through the labeled `<input>` per the testing strategy
+- **Behavior:**
+  - `onChange` strips non-digit characters and slices to `length` before bubbling up — so a paste of `"abc123456xyz"` becomes `"123456"`.
+  - **Click-to-edit any slot (the bug fix):** on slot `onPointerDown`, `preventDefault()`, `focus()` the input, then `setSelectionRange(i, i+1)` if the slot has a character, else collapse the caret at `min(i, value.length)`. Order matters — Safari ignores `setSelectionRange` if the input is not yet focused.
+  - **Active slot indicator:** a single `onSelect` handler on the input updates a `selectionStart` state (it fires for focus, keyboard nav, mouse selection, and programmatic `setSelectionRange` — no need for parallel `onFocus`/`onKeyUp` listeners). Track an `isFocused` state via `onFocus`/`onBlur`; render `data-active` and the blinking caret only when `isFocused === true`, so an unfocused input doesn't paint a phantom active slot or caret. Caret animation uses `animate-caret-blink` (from `tw-animate-css`, already a dep).
+  - **Auto-submit at completion:** `onChange` of the consumer drives this — when value reaches `length`, the parent (`CheckEmailNotice`) calls `verifyOtp`. The primitive itself stays single-purpose.
+  - **Disabled:** propagates to the `<input>` (real disable) and the slot container (`opacity-50 pointer-events-none`).
+  - **Native behavior for free:** paste, backspace, arrow keys, iOS/Android SMS autofill — all handled by the underlying single `<input>`.
+- **Styling:** bakes in the visual treatment currently spread across the shadcn slots in `CheckEmailNotice.tsx:131-138` as defaults — slot `h-14 w-12 rounded-md border font-mono text-2xl font-medium tabular-nums`, active state `border-primary ring-2 ring-primary/40 ring-inset`. The slot-row layout (`flex justify-center gap-2.5`) is also baked in — these classes today live on the consumer's `<InputOTPGroup>` but logically belong to the primitive's internal structure, so they move inward as part of this swap. Defaults are merged with consumer-supplied `className` (grid container) and `slotClassName` (each slot) via `cn()` (Tailwind merge wins on conflicts, matching the shadcn pattern). **End result with `CheckEmailNotice`'s current usage is pixel-identical to today's rendering** — see the migration note below for the corresponding consumer-side cleanup.
+- **Accessibility:** the wrapper carries no `role` (the input is the single labeled control). Screen readers announce one input ("Confirmation code, edit text") rather than six. `aria-label` defaults via the consumer's `<Label htmlFor>` association. The visible slot-row `<div>` is marked `aria-hidden="true"` so assistive tech sees only the labeled input and never the six empty slot divs.
+- **Implementation gotchas to address** (from research):
+  - Safari requires `focus()` before `setSelectionRange` — same handler, in that order.
+  - Empty-slot caret uses a collapsed range at `i`; full-slot uses range `(i, i+1)`.
+  - Android Gboard composition events may cause flicker — only gate on `onCompositionEnd` if observed in manual testing; don't add preemptively.
+
+**New flow component — `<CheckEmailNotice>`** (`web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx`):
+
+- Props:
   - `email: string` — displayed in message
   - `onVerified: () => void` — called after `verifyOtp` resolves successfully so parent can navigate
   - `onResend?: () => Promise<void>` — wired in commit 5 (placeholder/no-op for commits 2–4)
-  - Renders: instructional copy ("We sent a link to <email>. Click the link in the email, or enter the 6-digit code below."), a shadcn/ui `<InputOTP maxLength={6}>` component (renders 6 visual digit slots with a single accessible input + `autocomplete="one-time-code"` underneath), a `<LoadingButton>` that calls `supabase.auth.verifyOtp({ email, token: code, type: 'signup' })` on submit. On error, render `<InlineError>`. On success, call `onVerified`. (`type: 'signup'` is the verified value from `auth-js` `EmailOtpType` for initial-signup confirmation.)
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx`
+- Renders: instructional copy ("We sent a link to <email>. Click the link in the email, or enter the 6-digit code below."), an `<OtpInput length={6} />`, and a `<LoadingButton>` that submits `supabase.auth.verifyOtp({ email, token: code, type: 'signup' })`. Auto-submits when the 6th digit lands. On error renders `<InlineError>`. On success calls `onVerified`. (`type: 'signup'` is the verified value from `auth-js` `EmailOtpType` for initial-signup confirmation.)
 
 **Tests:**
-- `CheckEmailNotice.test.tsx`:
+
+- `OtpInput.test.tsx` (new) — behavioral coverage only; per `web/CLAUDE.md` ("user interactions, callback invocations, accessibility attributes" — not structural JSX):
+  - Typing into the input updates `value` via `onChange` and filters non-digits
+  - Paste of `"abc123456xyz"` results in `onChange("123456")` (one call, fully sliced)
+  - Backspace removes the last digit
+  - After entering a full code, clicking slot 3 positions the caret at slot 3 (`selectionStart === 3`) — guards the bug fix. Queries the slot via `data-slot="otp-slot"` (the only test that legitimately needs a structural selector, because the bug it guards is structural-positional)
+  - `disabled` prevents typing
+  - The underlying `<input>` exposes `inputmode="numeric"`, `maxlength=6`, `autocomplete="one-time-code"` — this assertion also implicitly covers that `length` is plumbed through to `maxLength`, so no separate "renders N slots" test is needed
+- `CheckEmailNotice.test.tsx` (behaviorally unchanged from prior commit 2 — the existing tests query by `getByLabelText(/confirmation code/i)` and assert attributes on the labeled input, both of which the new `<OtpInput>` still satisfies):
   - Renders email and code input
   - Submitting valid code calls `supabase.auth.verifyOtp` with expected args
   - On verify success, calls `onVerified` prop
   - On verify error, renders `<InlineError>`
-  - Code input enforces 6 digits / numeric only (via `inputMode` and `pattern` — server is the source of truth)
+  - Code input enforces 6 digits / numeric only
 
 **Verification:**
+
 1. `npm run web:test` + `npm run web:lint` + `npm run web:format:check` green
-2. Manual: nothing to verify in-app yet (component unwired); spot-check Storybook-style by importing into a scratch page if desired
+2. Manual: spot-check via the working-tree `/dev/check-email` scratch route (already present at `web/src/router.tsx:304-313`) that (a) the input visually matches the prior shadcn version, (b) clicking a middle slot after entering a full code retargets the caret to that slot, (c) iOS Simulator one-time-code autofill still works against a test SMS-shaped message (sanity check that single-input architecture wasn't broken), (d) pasting `"abc123456xyz"` fills the slots with `123456`
+3. **Before committing, remove the `/dev/check-email` scratch route** (and its `CheckEmailNotice` import added solely for it) from `web/src/router.tsx`. The route is a working-tree dev artifact; it must not land in the commit. The comment at `router.tsx:304` already flags this with "Revert before commit" — this step is the enforcement of that note.
+
+**Note for reapplying over the prior shadcn-based commit 2:**
+
+- Delete `web/src/components/ui/input-otp.tsx`
+- Remove `input-otp` from `web/package.json` dependencies and run `npm install`
+- Remove the `document.elementFromPoint` polyfill from `web/src/setupTests.ts:25-30`. It was added solely because `input-otp` calls `document.elementFromPoint` in a deferred timeout to detect focus and jsdom doesn't implement it; with the library gone, the polyfill is dead code.
+- Strip the `import { REGEXP_ONLY_DIGITS } from 'input-otp'` line and the `pattern={REGEXP_ONLY_DIGITS}` prop from `CheckEmailNotice.tsx` (current `:8` and `:125`). `<OtpInput>` filters digits internally, so `pattern` is no longer a meaningful prop on the public surface.
+- Strip the slot-row layout classes from the consumer call site — what is today `<InputOTPGroup className="w-full justify-center gap-2.5">` becomes `<OtpInput className="w-full" … />`. `justify-center gap-2.5` now lives inside the primitive's slot row (see Styling above); only outer sizing (`w-full`) stays consumer-controlled.
+- The existing `CheckEmailNotice.test.tsx` assertions continue to pass against the new component, so no test churn there.
 
 ---
 
@@ -245,9 +292,8 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 **New:**
 - `web/src/lib/auth-destination.ts` + `auth-destination.test.ts` (commit 1)
 - `web/src/tests/integration/auth-callback.integration.test.tsx` (commit 1)
+- `web/src/components/OtpInput/OtpInput.tsx` + `OtpInput.test.tsx` (commit 2) — custom OTP input primitive; lives at the top level of `components/` alongside other custom primitives (`LoadingButton`, `InlineError`, etc.), not in `ui/` (reserved for vendored shadcn)
 - `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` + `.test.tsx` (commit 2; expanded in commit 5)
-- `web/src/components/ui/input-otp.tsx` (commit 2; added via shadcn workflow — exact path matches existing shadcn components in the project)
-- `web/package.json` — adds `input-otp` dependency (commit 2)
 - `api/supabase/templates/confirmation.html` (commit 3; includes both link and OTP from the start)
 - `e2e/fixtures/mailpit.ts` (commit 4)
 - New tests in `e2e/tests/auth.spec.ts` (commit 4)

From d4a632b7250a8e08eb0875cdabe3f6d235874815 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Tue, 12 May 2026 19:42:33 -0500
Subject: [PATCH 07/25] feat(web): add OtpInput primitive + CheckEmailNotice
 pending UI

Hand-rolled numeric OTP at components/OtpInput/ (single-input + overlay
slot row via CSS Grid; fixes the shadcn/ui #4046 slot-retargeting bug
where clicking a non-final slot focuses the last cell), plus the
pending-state UI at components/auth/CheckEmailNotice/ that consumes it.
Lands the building blocks for #164's signup-confirmation flow ahead of
wiring SignUpForm into it (commit 3).
---
 web/src/components/OtpInput/OtpInput.test.tsx |  99 +++++++++++
 web/src/components/OtpInput/OtpInput.tsx      | 158 +++++++++++++++++
 .../CheckEmailNotice.test.tsx                 |  89 ++++++++++
 .../CheckEmailNotice/CheckEmailNotice.tsx     | 160 ++++++++++++++++++
 4 files changed, 506 insertions(+)
 create mode 100644 web/src/components/OtpInput/OtpInput.test.tsx
 create mode 100644 web/src/components/OtpInput/OtpInput.tsx
 create mode 100644 web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
 create mode 100644 web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx

diff --git a/web/src/components/OtpInput/OtpInput.test.tsx b/web/src/components/OtpInput/OtpInput.test.tsx
new file mode 100644
index 0000000..5478e32
--- /dev/null
+++ b/web/src/components/OtpInput/OtpInput.test.tsx
@@ -0,0 +1,99 @@
+import { render, screen } from '@testing-library/react';
+import { userEvent } from '@testing-library/user-event';
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { OtpInput } from './OtpInput';
+
+function Controlled({
+  initialValue = '',
+  onChange,
+  ...rest
+}: {
+  initialValue?: string;
+  onChange?: (v: string) => void;
+} & Omit<React.ComponentProps<typeof OtpInput>, 'value' | 'onChange'>) {
+  const [value, setValue] = useState(initialValue);
+  return (
+    <OtpInput
+      value={value}
+      onChange={(v) => {
+        setValue(v);
+        onChange?.(v);
+      }}
+      aria-label="Confirmation code"
+      {...rest}
+    />
+  );
+}
+
+describe('OtpInput', () => {
+  it('forwards inputmode, maxlength, and autocomplete to the underlying input', () => {
+    render(<Controlled />);
+    const input = screen.getByLabelText('Confirmation code');
+    expect(input).toHaveAttribute('inputmode', 'numeric');
+    expect(input).toHaveAttribute('maxlength', '6');
+    expect(input).toHaveAttribute('autocomplete', 'one-time-code');
+  });
+
+  it('updates value via onChange and filters non-digits while typing', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(<Controlled onChange={onChange} />);
+    const input = screen.getByLabelText('Confirmation code');
+
+    await user.type(input, '12ab34');
+
+    expect(onChange).toHaveBeenLastCalledWith('1234');
+  });
+
+  it('handles paste by stripping non-digits and slicing to length in one onChange call', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(<Controlled onChange={onChange} />);
+    const input = screen.getByLabelText('Confirmation code');
+
+    input.focus();
+    await user.paste('abc123456xyz');
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith('123456');
+  });
+
+  it('removes the last digit on backspace', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(<Controlled onChange={onChange} />);
+    const input = screen.getByLabelText('Confirmation code');
+
+    await user.type(input, '12345');
+    onChange.mockClear();
+    await user.type(input, '{Backspace}');
+
+    expect(onChange).toHaveBeenLastCalledWith('1234');
+  });
+
+  it('positions the caret at a clicked slot index after a full code is entered', async () => {
+    const user = userEvent.setup();
+    render(<Controlled />);
+    const input = screen.getByLabelText('Confirmation code') as HTMLInputElement;
+
+    await user.type(input, '123456');
+    const slots = document.querySelectorAll('[data-slot="otp-slot"]');
+    await user.click(slots[3] as HTMLElement);
+
+    expect(input.selectionStart).toBe(3);
+    expect(input.selectionEnd).toBe(4);
+  });
+
+  it('prevents typing when disabled', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(<OtpInput value="" onChange={onChange} disabled aria-label="otp" />);
+    const input = screen.getByLabelText('otp');
+
+    await user.type(input, '123');
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
diff --git a/web/src/components/OtpInput/OtpInput.tsx b/web/src/components/OtpInput/OtpInput.tsx
new file mode 100644
index 0000000..c42ba79
--- /dev/null
+++ b/web/src/components/OtpInput/OtpInput.tsx
@@ -0,0 +1,158 @@
+import { cn } from '@/lib/utils';
+import {
+  type ChangeEvent,
+  type ClipboardEvent,
+  type ComponentPropsWithoutRef,
+  type PointerEvent,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+
+interface OtpInputProps {
+  id?: string;
+  value: string;
+  onChange: (value: string) => void;
+  length?: number;
+  disabled?: boolean;
+  'aria-label'?: string;
+  autoComplete?: string;
+  inputMode?: ComponentPropsWithoutRef<'input'>['inputMode'];
+  className?: string;
+  slotClassName?: string;
+}
+
+/**
+ * Numeric OTP input. One real <input> stacked under a row of slot <div>s via
+ * CSS Grid so the input owns paste, SMS autofill (autocomplete="one-time-code"),
+ * and screen-reader naming, while the slot row owns visual rendering and click
+ * targeting. Not a generic OTP primitive — non-digit filtering and
+ * inputMode="numeric" are baked in.
+ */
+export function OtpInput({
+  id,
+  value,
+  onChange,
+  length = 6,
+  disabled = false,
+  'aria-label': ariaLabel,
+  autoComplete = 'one-time-code',
+  inputMode = 'numeric',
+  className,
+  slotClassName,
+}: OtpInputProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [selectionStart, setSelectionStart] = useState<number | null>(null);
+  const [isFocused, setIsFocused] = useState(false);
+
+  // `selectionchange` is the only DOM event that fires for every selection
+  // mutation, including programmatic setSelectionRange that `onSelect` misses.
+  useEffect(() => {
+    if (!isFocused) return;
+    const handler = () => {
+      const input = inputRef.current;
+      if (input && document.activeElement === input) {
+        setSelectionStart(input.selectionStart);
+      }
+    };
+    document.addEventListener('selectionchange', handler);
+    return () => document.removeEventListener('selectionchange', handler);
+  }, [isFocused]);
+
+  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
+    const sanitized = e.target.value.replace(/\D/g, '').slice(0, length);
+    onChange(sanitized);
+  };
+
+  // Intercept paste so the input's maxLength can't truncate mixed-character
+  // pastes before we strip non-digits (e.g. "abc123456xyz" → "123456").
+  const handlePaste = (e: ClipboardEvent<HTMLInputElement>) => {
+    e.preventDefault();
+    const text = e.clipboardData.getData('text');
+    const sanitized = text.replace(/\D/g, '').slice(0, length);
+    onChange(sanitized);
+  };
+
+  const handleSlotPointerDown = (e: PointerEvent<HTMLDivElement>, index: number) => {
+    if (disabled) return;
+
+    e.preventDefault();
+
+    const input = inputRef.current;
+
+    if (!input) return;
+
+    // Safari requires focus() to land before setSelectionRange.
+    input.focus();
+
+    if (index < value.length) {
+      input.setSelectionRange(index, index + 1);
+      setSelectionStart(index);
+    } else {
+      const pos = Math.min(index, value.length);
+      input.setSelectionRange(pos, pos);
+      setSelectionStart(pos);
+    }
+  };
+
+  function computeActiveIndex(): number | null {
+    if (!isFocused) return null;
+    if (selectionStart === null) return Math.min(value.length, length - 1);
+    if (selectionStart >= length) return length - 1;
+    return selectionStart;
+  }
+  const activeIndex = computeActiveIndex();
+
+  return (
+    <div className={cn('grid', className)}>
+      <input
+        ref={inputRef}
+        id={id}
+        type="text"
+        inputMode={inputMode}
+        autoComplete={autoComplete}
+        maxLength={length}
+        value={value}
+        onChange={handleChange}
+        onPaste={handlePaste}
+        onFocus={() => setIsFocused(true)}
+        onBlur={() => setIsFocused(false)}
+        disabled={disabled}
+        aria-label={ariaLabel}
+        className="col-start-1 row-start-1 h-full w-full border-none bg-transparent text-transparent caret-transparent outline-none"
+      />
+      <div
+        aria-hidden="true"
+        className={cn(
+          'z-10 col-start-1 row-start-1 flex justify-center gap-2.5',
+          disabled && 'pointer-events-none opacity-50',
+        )}
+      >
+        {Array.from({ length }, (_, i) => {
+          const char = value[i] ?? '';
+          const isActive = activeIndex === i;
+          return (
+            <div
+              key={i}
+              data-slot="otp-slot"
+              data-active={isActive ? 'true' : undefined}
+              onPointerDown={(e) => handleSlotPointerDown(e, i)}
+              className={cn(
+                'relative flex h-14 w-12 items-center justify-center rounded-md border font-mono text-2xl font-medium tabular-nums',
+                isActive && 'border-primary ring-primary/40 ring-2 ring-inset',
+                slotClassName,
+              )}
+            >
+              {char}
+              {isActive && !char && (
+                <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
+                  <div className="bg-foreground animate-caret-blink h-4 w-px duration-1000" />
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
diff --git a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
new file mode 100644
index 0000000..ce87581
--- /dev/null
+++ b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
@@ -0,0 +1,89 @@
+import { supabase } from '@/lib/supabase';
+import type { AuthError } from '@supabase/supabase-js';
+import { render, screen, waitFor } from '@testing-library/react';
+import { userEvent } from '@testing-library/user-event';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { CheckEmailNotice } from './CheckEmailNotice';
+
+vi.mock('@/lib/supabase', () => ({
+  supabase: {
+    auth: {
+      verifyOtp: vi.fn(),
+    },
+  },
+}));
+
+describe('CheckEmailNotice', () => {
+  beforeEach(() => {
+    vi.mocked(supabase.auth.verifyOtp).mockReset();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const setup = (overrides: Partial<React.ComponentProps<typeof CheckEmailNotice>> = {}) => {
+    const props: React.ComponentProps<typeof CheckEmailNotice> = {
+      email: 'user@example.com',
+      onVerified: vi.fn(),
+      ...overrides,
+    };
+    render(<CheckEmailNotice {...props} />);
+    return props;
+  };
+
+  it('renders the email prop in the body', () => {
+    setup({ email: 'driver@example.com' });
+    expect(screen.getByText('driver@example.com')).toBeInTheDocument();
+  });
+
+  it('auto-submits and calls verifyOtp with the email + code when the 6th digit lands', async () => {
+    const user = userEvent.setup();
+    vi.mocked(supabase.auth.verifyOtp).mockResolvedValue({
+      data: { user: null, session: null },
+      error: null,
+    });
+    const props = setup();
+
+    await user.type(screen.getByLabelText(/confirmation code/i), '123456');
+
+    await waitFor(() => {
+      expect(supabase.auth.verifyOtp).toHaveBeenCalledWith({
+        email: 'user@example.com',
+        token: '123456',
+        type: 'signup',
+      });
+    });
+    await waitFor(() => {
+      expect(props.onVerified).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('renders the failure UI and skips onVerified when verification fails', async () => {
+    const user = userEvent.setup();
+    vi.mocked(supabase.auth.verifyOtp).mockResolvedValue({
+      data: { user: null, session: null },
+      error: new Error('Invalid code') as AuthError,
+    });
+    const props = setup();
+
+    await user.type(screen.getByLabelText(/confirmation code/i), '123456');
+
+    const alert = await screen.findByRole('alert');
+    expect(alert).toHaveTextContent(/that code didn't match/i);
+    expect(props.onVerified).not.toHaveBeenCalled();
+  });
+
+  it('keeps the Verify button disabled and verifyOtp uncalled until 6 digits land', async () => {
+    const user = userEvent.setup();
+    setup();
+
+    const button = screen.getByRole('button', { name: /verify/i });
+    expect(button).toBeDisabled();
+
+    await user.type(screen.getByLabelText(/confirmation code/i), '12345');
+    expect(button).toBeDisabled();
+    expect(supabase.auth.verifyOtp).not.toHaveBeenCalled();
+  });
+});
diff --git a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
new file mode 100644
index 0000000..67e3b6c
--- /dev/null
+++ b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
@@ -0,0 +1,160 @@
+import { InlineError } from '@/components/InlineError/InlineError';
+import { LoadingButton } from '@/components/LoadingButton/LoadingButton';
+import { OtpInput } from '@/components/OtpInput/OtpInput';
+import { Card, CardContent, CardHeader } from '@/components/ui/card';
+import { Label } from '@/components/ui/label';
+import { supabase } from '@/lib/supabase';
+import { cn } from '@/lib/utils';
+import { Check } from 'lucide-react';
+import { useState } from 'react';
+
+interface Props {
+  email: string;
+  onVerified: () => void;
+  onResend?: () => Promise<void>;
+  onChangeEmail?: () => void;
+}
+
+const OTP_LENGTH = 6;
+
+type Status = 'idle' | 'verifying' | 'success';
+
+export function CheckEmailNotice({ email, onVerified }: Props) {
+  const [code, setCode] = useState('');
+  const [error, setError] = useState<string | null>(null);
+  const [status, setStatus] = useState<Status>('idle');
+
+  const verify = async (token: string) => {
+    setStatus('verifying');
+    try {
+      const { error: verifyError } = await supabase.auth.verifyOtp({
+        email,
+        token,
+        type: 'signup',
+      });
+      if (verifyError) throw verifyError;
+      setError(null);
+      setStatus('success');
+      onVerified();
+    } catch {
+      setError("That code didn't match. Check your email for the latest one.");
+      setStatus('idle');
+    }
+  };
+
+  const handleCodeChange = (value: string) => {
+    setCode(value);
+    if (value.length === OTP_LENGTH && status === 'idle') {
+      verify(value);
+    }
+  };
+
+  return (
+    <Card
+      className={cn(
+        'w-full max-w-lg transition-all',
+        !!error && 'animate-[shake_0.42s_cubic-bezier(0.36,0.07,0.19,0.97)]',
+        status === 'success' && 'shadow-lg ring-1 shadow-emerald-500/10 ring-emerald-500/40',
+      )}
+    >
+      <CardHeader>
+        <div
+          className={cn(
+            'bg-secondary text-muted-foreground relative mb-4 flex size-12 items-center justify-center rounded-xl border transition-all',
+            status === 'success' && 'border-emerald-500/40 text-emerald-500',
+          )}
+        >
+          <EnvelopeMark className={cn('size-7', status === 'success' && 'text-emerald-500')} />
+        </div>
+        <h2 className="text-2xl font-semibold tracking-tight">Check your email</h2>
+        <div className="text-muted-foreground space-y-2 text-[14.5px] leading-[1.55]">
+          <p>
+            We sent a 6-digit code to{' '}
+            <span className="text-foreground bg-secondary rounded-sm border px-1.5 py-0.5 font-mono text-xs">
+              {email}
+            </span>
+            .
+          </p>
+          <p>Enter it below or click the link in the email to sign in to F1 Fantasy.</p>
+        </div>
+      </CardHeader>
+
+      <CardContent className="space-y-4">
+        <div className="space-y-3">
+          <div className="flex items-center justify-between">
+            <Label
+              htmlFor="confirmation-code"
+              className="text-muted-foreground text-[13px] font-medium tracking-[0.01em]"
+            >
+              Confirmation code
+            </Label>
+            <div className="bg-border h-0.75 w-20 overflow-hidden rounded-full">
+              <div
+                className="bg-primary h-full transition-all duration-200"
+                style={{ width: `${(code.length / OTP_LENGTH) * 100}%` }}
+              />
+            </div>
+          </div>
+
+          <OtpInput
+            id="confirmation-code"
+            length={OTP_LENGTH}
+            value={code}
+            onChange={handleCodeChange}
+            disabled={status === 'verifying' || status === 'success'}
+            className="w-full"
+          />
+
+          {error && <InlineError message={error} />}
+        </div>
+
+        <div className="flex justify-center">
+          <LoadingButton
+            type="button"
+            onClick={() => {
+              if (status === 'idle') verify(code);
+            }}
+            size="lg"
+            className="min-w-48"
+            isLoading={status === 'verifying'}
+            loadingText="Verifying..."
+            disabled={code.length < OTP_LENGTH || status === 'success'}
+          >
+            {status === 'success' ? (
+              <>
+                <Check />
+                Verified
+              </>
+            ) : (
+              'Verify'
+            )}
+          </LoadingButton>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+function EnvelopeMark({ className }: { className?: string }) {
+  return (
+    <svg viewBox="0 0 32 32" fill="none" aria-hidden="true" className={className}>
+      <rect
+        x="3.5"
+        y="7.5"
+        width="25"
+        height="17"
+        rx="3.5"
+        stroke="currentColor"
+        strokeWidth="1.6"
+      />
+      <path
+        d="M4.5 9.5L16 17.5L27.5 9.5"
+        stroke="currentColor"
+        strokeWidth="1.6"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <circle cx="25" cy="9" r="4.5" className="fill-primary stroke-card" strokeWidth="1.5" />
+    </svg>
+  );
+}

From 4bab4df389c51d97407926e39e956f149f394d8a Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Tue, 12 May 2026 19:52:33 -0500
Subject: [PATCH 08/25] docs(plans): sync #164 plan with what commit 2 actually
 shipped

Captures the structural drifts from commit 2's implementation as
Decisions rows, rewrites commit 2 to describe the end state in HEAD,
and updates commits 3/5/6 wiring instructions for the new starting
point. Notable: <CheckEmailNotice> is Card-only (parent provides page
chrome), no <form> wrapper, no <StatusLine>, generic failure copy,
centered Verify button, error below the slots. Commit 5 now marks the
CardFooter as a reintroduction; commits 3 and 6 swap in place of <Card>
rather than the whole form.
---
 docs/plans/164-email-confirmation-signup.md | 183 +++++++++++---------
 1 file changed, 104 insertions(+), 79 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index 7564312..4f56e10 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -11,26 +11,32 @@ Email confirmations are currently disabled in Supabase (`enable_confirmations =
 5. Handle the case where an unconfirmed user later tries to sign in
 
 **Out of scope:**
+
 - Branded email template content (deferred to #22)
 - Standardizing post-auth redirect destinations (deferred to #165)
 - Production Supabase dashboard configuration (must be done manually after deploy: enable Confirm Email in Authentication → Providers → Email, add `https://<prod>/auth/callback` to redirect allowlist, upload custom template)
 
 ## Decisions
 
-| Decision | Choice | Rationale |
-|---|---|---|
-| Confirmation method | **Both magic link AND OTP code** in the email; user can use whichever | Resilient to corporate email scanners (Defender, Barracuda, Mimecast) that pre-fetch links and consume the token before users click. Supabase auth issue [#1214](https://github.com/supabase/auth/issues/1214) is open and unfixed; no clean recovery for affected users without an OTP fallback. Default Supabase template already emits both, so the email-side cost is near zero. |
-| OTP input component | Custom `<OtpInput>` at `web/src/components/OtpInput/` | Hand-rolled single-input + overlay slot pattern (same architecture as `input-otp`) that fixes the slot-retargeting bug ([shadcn/ui #4046](https://github.com/shadcn-ui/ui/issues/4046)) where clicking a non-final slot focuses the last cell. Preserves every must-have: single accessible `<input>` for WCAG 1.3.5, iOS/Android SMS autofill via `autocomplete="one-time-code"`, native paste, full keyboard a11y, auto-submit. Lives outside `ui/` because `ui/` is reserved for vendored shadcn; sits next to the other custom primitives (`LoadingButton`, `InlineError`). Removes the `input-otp` dependency. |
-| Pending-UI surface | Inline state + shared `<CheckEmailNotice>` component | No URL params (OWASP: PII like email shouldn't appear in URLs — leaks via browser history, server logs, Referer to Sentry). Refresh degrades benignly: link in inbox still works, resend reachable via signin path. |
-| Email passing | React state within form components | User never retypes — Supabase's confirmation token uniquely identifies the user. Email passed as prop from parent (`SignUpForm`, `SignInForm`) into `<CheckEmailNotice>`. |
-| Sign-in unconfirmed handling | In scope, same issue (commit 6) | Completes the verification story: signup → pending → resend → confirm AND signin → unconfirmed → resend. |
-| Post-confirmation destination | Preserve current logic per parent (`SignUpForm` → redirect-or-`/create-team`; `SignInForm` → redirect-or-`/leagues`; magic link callback uses URL `redirect` search param, else `/create-team`) | Standardization deferred to #165. |
-| Resend with redirect override | `AuthContext.resendConfirmation(email, { redirect? })` accepts the current redirect param so the resent email's link encodes the *current* destination (e.g., signin's `/leagues/123`) rather than whatever was baked in at signup time | Helps a user who hits the unconfirmed-signin path with a deep link, triggers Resend, and uses the new email's link. The original signup email's link still routes to `/create-team` (can't fix retroactively); the OTP path always routes correctly via the callsite. |
-| E2E approach | Existing admin-API fixture keeps `email_confirm: true` (auto-confirms); add two new tests in commit 4 (magic-link path + OTP path) | Existing tests stay fast; targeted e2e covers the new wiring |
-| Email template | Custom template at `api/supabase/templates/confirmation.html` includes both `{{ .ConfirmationURL }}` and `{{ .Token }}`, lands in commit 3 alongside the config flip | Default Supabase template already has both; we're shipping our own to control wording and prep for #22's branding |
-| Cross-issue ordering | 164 → 167 → 165 (locked) | 164 builds verification primitives; 167 reuses callback route + OTP entry pattern for change-email re-verification; 165 audits all destinations after both new flows exist. |
-| Auth callback implementation | **Route loader + inline `errorComponent`, no separate component** | Async work belongs in a TanStack Router `loader` (matches every other async route in the codebase — `joinInviteRoute`, `accountRoute`, etc.); avoids the `useEffect` + `cancelled`-flag anti-pattern. Side effects (Sentry capture) live at the failure site inside the loader's `try/catch`, not in a render-time hook. The shared `ErrorFallback` doesn't fit (hardcoded copy + "Try again" button; reloading can't fix a consumed PKCE code), and the bespoke error UI is small enough to inline in `errorComponent` rather than warrant a dedicated component file. |
-| Sentry coverage for loader failures | Manual `Sentry.captureException` inside the loader's `try/catch` | The auth-callback failure mode is a Supabase SDK error that bypasses `apiClient`'s built-in HTTP-error capture, so without explicit capture in the loader, Sentry never sees PKCE failures. This is consistent with the existing pattern in `rootRoute.beforeLoad`. The codebase-wide observability gap (loader failures outside `apiClient` are silently rendered) is tracked separately in #180; commit 1 doesn't try to solve it here. |
+| Decision                                    | Choice                                                                                                                                                                                                                                  | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Confirmation method                         | **Both magic link AND OTP code** in the email; user can use whichever                                                                                                                                                                   | Resilient to corporate email scanners (Defender, Barracuda, Mimecast) that pre-fetch links and consume the token before users click. Supabase auth issue [#1214](https://github.com/supabase/auth/issues/1214) is open and unfixed; no clean recovery for affected users without an OTP fallback. Default Supabase template already emits both, so the email-side cost is near zero.                                                                                                                                                                                                                                |
+| OTP input component                         | Custom `<OtpInput>` at `web/src/components/OtpInput/`                                                                                                                                                                                   | Hand-rolled single-input + overlay slot pattern (same architecture as `input-otp`) that fixes the slot-retargeting bug ([shadcn/ui #4046](https://github.com/shadcn-ui/ui/issues/4046)) where clicking a non-final slot focuses the last cell. Preserves every must-have: single accessible `<input>` for WCAG 1.3.5, iOS/Android SMS autofill via `autocomplete="one-time-code"`, native paste, full keyboard a11y, auto-submit. Lives outside `ui/` because `ui/` is reserved for vendored shadcn; sits next to the other custom primitives (`LoadingButton`, `InlineError`). Removes the `input-otp` dependency. |
+| Pending-UI surface                          | Inline state + shared `<CheckEmailNotice>` component                                                                                                                                                                                    | No URL params (OWASP: PII like email shouldn't appear in URLs — leaks via browser history, server logs, Referer to Sentry). Refresh degrades benignly: link in inbox still works, resend reachable via signin path.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `<CheckEmailNotice>` shape                  | **Card-only component, not a full-page screen** — returns the `<Card>` directly; page chrome (centering, full-viewport height, background) is the caller's responsibility                                                               | The caller already provides a page wrapper (`SignUpForm`'s and `SignInForm`'s outer `flex w-full ... justify-center ... md:min-h-screen` div). A second wrapper inside `<CheckEmailNotice>` would double-wrap and made the Card's `w-full max-w-lg` resolve against a content-sized parent, which let the `<InlineError>`'s width feed back into the Card width. Card-only avoids both issues; commits 3 and 6 swap `<CheckEmailNotice>` in place of the existing `<Card>` inside the parent's wrapper.                                                                                                             |
+| Auto-submit vs. manual submit               | **Auto-submit on 6th digit AND a manual Verify button**, no `<form>` wrapper. Button is `type="button"` with `onClick`. No Enter-to-submit                                                                                              | Auto-submit covers every typed/pasted happy path (`onPaste` in `<OtpInput>` also fires `onChange`). The Verify button serves as the loading-state visual, the success-state visual ("Verified" + check), and the explicit retry affordance after a failure. The `<form>` was vestigial after we dropped HTML-form-validation; its only remaining job was Enter-to-submit, which would only ever re-fire the same already-failed code — a weak use case for OTP.                                                                                                                                                     |
+| Verify button shape                         | Centered, `size="lg" min-w-48`, not full-width                                                                                                                                                                                          | Centered slots above + centered button below reads visually balanced. Full-width would deviate less from `SignUpForm`/`SignInForm` but visually anchors the manual button more heavily than is warranted given auto-submit is the primary path. `min-w-48` keeps the tap target generous on mobile.                                                                                                                                                                                                                                                                                                                 |
+| Failure copy                                | Static generic message _"That code didn't match. Check your email for the latest one."_ — not the raw Supabase error string                                                                                                             | Supabase emits jargon ("Token has expired or is invalid"). Users typed a "code", not a "token", and the canonical follow-up is to enter a new code from the latest email. Also: `verify()` no longer optimistically clears the error at function entry (only on success), so re-attempts don't unmount/remount the `<InlineError>` and trigger a layout shift mid-flight.                                                                                                                                                                                                                                           |
+| Error placement inside `<CheckEmailNotice>` | `<InlineError>` sits _under_ the slot row, inside the same `space-y-3` group, replacing the idle-state status hint when present                                                                                                         | Keeps the eye path slots → error → button continuous. Originally placed above the slots; that path made the user snap up to the top, then back down to retype.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Email passing                               | React state within form components                                                                                                                                                                                                      | User never retypes — Supabase's confirmation token uniquely identifies the user. Email passed as prop from parent (`SignUpForm`, `SignInForm`) into `<CheckEmailNotice>`.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Sign-in unconfirmed handling                | In scope, same issue (commit 6)                                                                                                                                                                                                         | Completes the verification story: signup → pending → resend → confirm AND signin → unconfirmed → resend.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Post-confirmation destination               | Preserve current logic per parent (`SignUpForm` → redirect-or-`/create-team`; `SignInForm` → redirect-or-`/leagues`; magic link callback uses URL `redirect` search param, else `/create-team`)                                         | Standardization deferred to #165.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Resend with redirect override               | `AuthContext.resendConfirmation(email, { redirect? })` accepts the current redirect param so the resent email's link encodes the _current_ destination (e.g., signin's `/leagues/123`) rather than whatever was baked in at signup time | Helps a user who hits the unconfirmed-signin path with a deep link, triggers Resend, and uses the new email's link. The original signup email's link still routes to `/create-team` (can't fix retroactively); the OTP path always routes correctly via the callsite.                                                                                                                                                                                                                                                                                                                                               |
+| E2E approach                                | Existing admin-API fixture keeps `email_confirm: true` (auto-confirms); add two new tests in commit 4 (magic-link path + OTP path)                                                                                                      | Existing tests stay fast; targeted e2e covers the new wiring                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Email template                              | Custom template at `api/supabase/templates/confirmation.html` includes both `{{ .ConfirmationURL }}` and `{{ .Token }}`, lands in commit 3 alongside the config flip                                                                    | Default Supabase template already has both; we're shipping our own to control wording and prep for #22's branding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Cross-issue ordering                        | 164 → 167 → 165 (locked)                                                                                                                                                                                                                | 164 builds verification primitives; 167 reuses callback route + OTP entry pattern for change-email re-verification; 165 audits all destinations after both new flows exist.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Auth callback implementation                | **Route loader + inline `errorComponent`, no separate component**                                                                                                                                                                       | Async work belongs in a TanStack Router `loader` (matches every other async route in the codebase — `joinInviteRoute`, `accountRoute`, etc.); avoids the `useEffect` + `cancelled`-flag anti-pattern. Side effects (Sentry capture) live at the failure site inside the loader's `try/catch`, not in a render-time hook. The shared `ErrorFallback` doesn't fit (hardcoded copy + "Try again" button; reloading can't fix a consumed PKCE code), and the bespoke error UI is small enough to inline in `errorComponent` rather than warrant a dedicated component file.                                             |
+| Sentry coverage for loader failures         | Manual `Sentry.captureException` inside the loader's `try/catch`                                                                                                                                                                        | The auth-callback failure mode is a Supabase SDK error that bypasses `apiClient`'s built-in HTTP-error capture, so without explicit capture in the loader, Sentry never sees PKCE failures. This is consistent with the existing pattern in `rootRoute.beforeLoad`. The codebase-wide observability gap (loader failures outside `apiClient` are silently rendered) is tracked separately in #180; commit 1 doesn't try to solve it here.                                                                                                                                                                           |
 
 ---
 
@@ -43,14 +49,17 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 **Goal:** Stand up the magic-link landing page and switch the Supabase client to PKCE so the link returns `?code=` instead of an implicit hash. Safe to land while `enable_confirmations` is still `false`: the route exists but nothing emits a magic link yet, and PKCE is fully compatible with the existing implicit-flow happy path.
 
 **Supabase client flow change** (`web/src/lib/supabase.ts`):
+
 - Today: `createClient(url, key)` with no options → defaults to `flowType: 'implicit'` (verified in `auth-js` source — `DEFAULT_OPTIONS.flowType: 'implicit'`)
 - Required: pass `{ auth: { flowType: 'pkce' } }` so the magic link returns `?code=` (which `exchangeCodeForSession` consumes) instead of `#access_token=` (implicit hash flow)
 - This is a small but app-wide auth behavior change — covered by existing AuthContext tests
 
 **New helper** (`web/src/lib/auth-destination.ts`):
+
 - `getPostSignupDestination(redirectParam?: string): string` — returns `redirectParam` if present, else `/create-team`. Search-param validation is already enforced upstream by the route's Zod schema, so this helper just chooses between two valid values. Used by the auth-callback loader here, and later by `SignUpForm` and `<CheckEmailNotice>`'s `onVerified` from the signup callsite (commit 3). Lands here because the auth-callback loader is its first caller.
 
 **Wiring** (`web/src/router.tsx`):
+
 - New Zod schema `authCallbackSearchSchema` validates `code` (optional string) and `redirect` (optional string, must start with `/` — same shape as the existing `redirectSearchSchema`).
 - New `authCallbackRoute` as a public child of root (sibling to `/sign-up`, `/sign-in`). Built as a loader-driven route:
   - `loaderDeps` pulls `code` and `redirect` from the validated search params.
@@ -60,6 +69,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
   - No `component` field — the loader always throws (`redirect` on success, captured error otherwise), so the route never renders to a normal component.
 
 **Tests:**
+
 - `web/src/tests/integration/auth-callback.integration.test.tsx` — covers loader branches via a real router mounted over an inline route-tree mirror (matches the convention in `account.integration.test.tsx`):
   - Default destination: with `?code=abc`, loader exchanges and redirects to `/create-team`; no Sentry capture.
   - `redirect` honored: with `?code=abc&redirect=/leagues`, loader redirects to `/leagues`.
@@ -72,6 +82,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - Existing `AuthContext.test.tsx` keeps passing under PKCE (no behavioral change to the public API).
 
 **Verification:**
+
 1. `npm run web:test` green
 2. `npm run web:lint` + `npm run web:format:check` green
 3. `npm run web:build` green (TypeScript compile)
@@ -81,77 +92,62 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 
 ### Commit 2 — `<OtpInput>` primitive + `<CheckEmailNotice>` component
 
-**Goal:** Add the pending-state UI as a self-contained, tested component, backed by a hand-rolled `<OtpInput>` primitive (no `input-otp` dependency). End result is visually identical to the prior shadcn-based version but fixes the slot-retargeting bug so a user can click any slot to edit just that digit. Not yet wired into any form — that happens in commit 3.
+**Goal:** Add the pending-state UI as a self-contained, tested component, backed by a hand-rolled `<OtpInput>` primitive (no `input-otp` dependency). Fixes the slot-retargeting bug so a user can click any slot to edit just that digit. Not yet wired into any form — that happens in commit 3.
 
 **New primitive — `<OtpInput>`** (`web/src/components/OtpInput/OtpInput.tsx`):
 
-- **Architecture:** Single-input + overlay slots, stacked via CSS Grid (not `position: absolute`). One real `<input>` and one slot-row `<div>` are both children of a `grid` container, both placed at `col-start-1 row-start-1` so they occupy the same cell. The input is rendered with transparent text and caret (`text-transparent caret-transparent`) and sits on top of the slot row, which is the visible UI driven by `value` and `selectionStart`. The slot-row `<div>` is itself a flex row (`flex justify-center gap-2.5`) carrying the 6 slot children. Grid stacking is preferred over `position: absolute` here because the container intrinsic-sizes to the slot row automatically — no `relative` ancestor or hand-tuned insets needed. Same end behavior as the `input-otp` library's overlay approach; the only meaningful difference is the click-to-edit handler that the library gets wrong.
-- **Scope of this primitive:** numeric OTP input only. The non-digit filter and `inputMode="numeric"` default are baked in; this is not a generic OTP primitive (no `pattern` prop). Spell that out in the component's JSDoc so a future caller doesn't try to pass alpha codes.
-- **Why this shape, not N individual inputs:** `<input autocomplete="one-time-code">` SMS autofill on iOS only works with a single input ([web.dev — SMS OTP form](https://web.dev/articles/sms-otp-form), confirmed broken on multi-input in [Chakra #4095](https://github.com/chakra-ui/chakra-ui/issues/4095), [react-verification-input #57](https://github.com/andreaswilli/react-verification-input/issues/57)). Paste, backspace, and arrow nav also come free at the browser level instead of needing hand-coded ref coordination.
-- **Props** (minimal, mirrors what `CheckEmailNotice` actually uses):
+- **Architecture:** Single-input + overlay slots, stacked via CSS Grid (not `position: absolute`). One real `<input>` and one slot-row `<div>` are both children of a `grid` container, both placed at `col-start-1 row-start-1` so they occupy the same cell. The input is rendered with transparent text and caret (`text-transparent caret-transparent`) and sits _under_ the slot row (which has `z-10`), so the slot row intercepts clicks and the input owns keyboard input + SMS autofill + screen-reader naming.
+- **Scope:** numeric OTP only. The non-digit filter and `inputMode="numeric"` default are baked in; no `pattern` prop. Spelled out in the component's JSDoc.
+- **Why single input, not N individual inputs:** `<input autocomplete="one-time-code">` SMS autofill on iOS only works with a single input ([web.dev — SMS OTP form](https://web.dev/articles/sms-otp-form), confirmed broken on multi-input in [Chakra #4095](https://github.com/chakra-ui/chakra-ui/issues/4095), [react-verification-input #57](https://github.com/andreaswilli/react-verification-input/issues/57)). Paste, backspace, and arrow nav also come free at the browser level.
+- **Props:**
   - `id?: string` — forwarded to the underlying `<input>` so external `<Label htmlFor>` works
-  - `value: string`
-  - `onChange: (value: string) => void`
-  - `length?: number` (default `6`) — also forwarded to the underlying `<input>` as `maxLength={length}` so attribute-based assertions on the labeled input (`maxlength='6'` in the existing `CheckEmailNotice.test.tsx`) keep passing
+  - `value: string`, `onChange: (value: string) => void`
+  - `length?: number` (default `6`) — also forwarded as `maxLength`
   - `disabled?: boolean`
   - `'aria-label'?: string`
   - `autoComplete?: string` (default `"one-time-code"`)
-  - `inputMode?: HTMLAttributes<HTMLInputElement>['inputMode']` (default `"numeric"`)
-  - `className?: string` — merged via `cn()` onto the **grid container**, intended for outer sizing (e.g., `w-full`). Slot-row internal layout (`flex justify-center gap-2.5`) is baked in and not consumer-overridable — there's no third style hook by design, since the primitive owns its internal structure
-  - `slotClassName?: string` — merged via `cn()` onto each slot so consumers can override per-slot styling (size, border, active state) without forking the component (matches the shadcn convention of baking in defaults + allowing class overrides)
-  - **Internal `data-slot="otp-slot"` attribute** is set on each visible slot `<div>` as a styling/structure marker (mirrors the shadcn convention in `ui/input-otp.tsx:49`). Not a public test hook — tests should query through the labeled `<input>` per the testing strategy
+  - `inputMode?: ComponentPropsWithoutRef<'input'>['inputMode']` (default `"numeric"`)
+  - `className?: string` — merged via `cn()` onto the grid container (outer sizing only)
+  - `slotClassName?: string` — merged onto each slot for per-slot style overrides
+  - Each visible slot carries `data-slot="otp-slot"` as a styling/structure marker (mirrors the shadcn convention). Not a public test hook except for the one click-retargeting test that the bug it guards is structural-positional.
 - **Behavior:**
-  - `onChange` strips non-digit characters and slices to `length` before bubbling up — so a paste of `"abc123456xyz"` becomes `"123456"`.
-  - **Click-to-edit any slot (the bug fix):** on slot `onPointerDown`, `preventDefault()`, `focus()` the input, then `setSelectionRange(i, i+1)` if the slot has a character, else collapse the caret at `min(i, value.length)`. Order matters — Safari ignores `setSelectionRange` if the input is not yet focused.
-  - **Active slot indicator:** a single `onSelect` handler on the input updates a `selectionStart` state (it fires for focus, keyboard nav, mouse selection, and programmatic `setSelectionRange` — no need for parallel `onFocus`/`onKeyUp` listeners). Track an `isFocused` state via `onFocus`/`onBlur`; render `data-active` and the blinking caret only when `isFocused === true`, so an unfocused input doesn't paint a phantom active slot or caret. Caret animation uses `animate-caret-blink` (from `tw-animate-css`, already a dep).
-  - **Auto-submit at completion:** `onChange` of the consumer drives this — when value reaches `length`, the parent (`CheckEmailNotice`) calls `verifyOtp`. The primitive itself stays single-purpose.
-  - **Disabled:** propagates to the `<input>` (real disable) and the slot container (`opacity-50 pointer-events-none`).
-  - **Native behavior for free:** paste, backspace, arrow keys, iOS/Android SMS autofill — all handled by the underlying single `<input>`.
-- **Styling:** bakes in the visual treatment currently spread across the shadcn slots in `CheckEmailNotice.tsx:131-138` as defaults — slot `h-14 w-12 rounded-md border font-mono text-2xl font-medium tabular-nums`, active state `border-primary ring-2 ring-primary/40 ring-inset`. The slot-row layout (`flex justify-center gap-2.5`) is also baked in — these classes today live on the consumer's `<InputOTPGroup>` but logically belong to the primitive's internal structure, so they move inward as part of this swap. Defaults are merged with consumer-supplied `className` (grid container) and `slotClassName` (each slot) via `cn()` (Tailwind merge wins on conflicts, matching the shadcn pattern). **End result with `CheckEmailNotice`'s current usage is pixel-identical to today's rendering** — see the migration note below for the corresponding consumer-side cleanup.
-- **Accessibility:** the wrapper carries no `role` (the input is the single labeled control). Screen readers announce one input ("Confirmation code, edit text") rather than six. `aria-label` defaults via the consumer's `<Label htmlFor>` association. The visible slot-row `<div>` is marked `aria-hidden="true"` so assistive tech sees only the labeled input and never the six empty slot divs.
-- **Implementation gotchas to address** (from research):
-  - Safari requires `focus()` before `setSelectionRange` — same handler, in that order.
-  - Empty-slot caret uses a collapsed range at `i`; full-slot uses range `(i, i+1)`.
-  - Android Gboard composition events may cause flicker — only gate on `onCompositionEnd` if observed in manual testing; don't add preemptively.
+  - `onChange` strips non-digit characters and slices to `length`.
+  - **Paste interceptor (`onPaste`):** intercepts paste events, `preventDefault`s the browser default, sanitizes `clipboardData.getData('text')`, and calls `onChange` with the sliced result. Necessary because `maxLength` on the underlying input would otherwise truncate a mixed-character paste (e.g., `"abc123456xyz"`) to its first 6 characters (`"abc123"`) _before_ our digit filter can run. With the interceptor, paste yields `onChange("123456")` in a single call.
+  - **Click-to-edit any slot (the bug fix):** on slot `onPointerDown`, `preventDefault`, `focus()` the input, then `setSelectionRange(i, i+1)` if the slot has a character, else collapse the caret at `min(i, value.length)`. Safari requires `focus()` before `setSelectionRange`.
+  - **Active slot tracking:** uses a `document`-level `selectionchange` listener (gated on `isFocused`) — the only DOM event that fires for _every_ selection mutation, including programmatic `setSelectionRange`. `onSelect` would miss the click-retarget case. The listener updates a `selectionStart` state, and `activeIndex` is derived from `isFocused + selectionStart + value.length`. Caret animation uses `animate-caret-blink` (from `tw-animate-css`).
+  - **Disabled:** propagates to the `<input>` and the slot container (`pointer-events-none opacity-50`).
+- **Styling defaults baked in:** slot `h-14 w-12 rounded-md border font-mono text-2xl font-medium tabular-nums`; active state `border-primary ring-2 ring-primary/40 ring-inset`; slot-row `flex justify-center gap-2.5`. Consumer-supplied `className` / `slotClassName` merge via `cn()` (Tailwind merge wins on conflicts).
+- **Accessibility:** the grid container carries no `role`; the slot-row `<div>` is `aria-hidden="true"`. Screen readers see only the single labeled `<input>`.
 
 **New flow component — `<CheckEmailNotice>`** (`web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx`):
 
-- Props:
-  - `email: string` — displayed in message
-  - `onVerified: () => void` — called after `verifyOtp` resolves successfully so parent can navigate
-  - `onResend?: () => Promise<void>` — wired in commit 5 (placeholder/no-op for commits 2–4)
-- Renders: instructional copy ("We sent a link to <email>. Click the link in the email, or enter the 6-digit code below."), an `<OtpInput length={6} />`, and a `<LoadingButton>` that submits `supabase.auth.verifyOtp({ email, token: code, type: 'signup' })`. Auto-submits when the 6th digit lands. On error renders `<InlineError>`. On success calls `onVerified`. (`type: 'signup'` is the verified value from `auth-js` `EmailOtpType` for initial-signup confirmation.)
+- **Returns just a `<Card>`** — no outer page wrapper. Caller (commit 3's `SignUpForm`, commit 6's `SignInForm`, dev-route scaffolding) provides centering, full-viewport height, and background.
+- **Props:**
+  - `email: string` — rendered in the body
+  - `onVerified: () => void` — called after `verifyOtp` resolves successfully so caller can navigate
+  - `onResend?: () => Promise<void>` — declared in `Props` for commit 5; renders nothing in commit 2 (no `CardFooter` yet)
+  - `onChangeEmail?: () => void` — same; renders nothing until commit 5 reintroduces the `CardFooter`
+- **Layout:**
+  - `CardHeader`: envelope icon, "Check your email" heading, two-paragraph body (sentence 1 with the email chip; sentence 2 with "Enter it below or click the link…") wrapped in a `space-y-2` div so the two `<p>`s are visually separated.
+  - `CardContent` (`space-y-4`): a `space-y-3` group containing the label + progress bar, the `<OtpInput length={6} className="w-full" />`, and (when set) `<InlineError>`. Below the group, a centered `<LoadingButton size="lg" min-w-48>` that fires `verify(code)` on click.
+- **No `<form>` wrapper.** Verify button is `type="button"` with `onClick={() => { if (status === 'idle') verify(code); }}`. Auto-submit handles every code-completion path (`onChange` reaches `OTP_LENGTH`). The `status === 'idle'` guard on the button prevents a mid-verify re-click from re-firing.
+- **`verify(token)`:** sets status to `'verifying'`, awaits `supabase.auth.verifyOtp({ email, token, type: 'signup' })`. On success: clears `error`, sets status to `'success'`, calls `onVerified()`. On failure (rejection OR returned error): sets a static generic message _"That code didn't match. Check your email for the latest one."_ and resets status to `'idle'`. Notably, the error is _not_ optimistically cleared at function entry — so a re-attempt doesn't unmount/remount `<InlineError>` and trigger a layout shift while the new request is in flight.
+- **`Status` type:** `'idle' | 'verifying' | 'success'`. Drives the `<OtpInput disabled>`, the `<LoadingButton isLoading>`, the Card's success ring (`ring-1 ring-emerald-500/40`), and the button's "Verified" + check icon swap-in. No separate status-line component — `LoadingButton` and the Card visual state carry it.
 
 **Tests:**
 
-- `OtpInput.test.tsx` (new) — behavioral coverage only; per `web/CLAUDE.md` ("user interactions, callback invocations, accessibility attributes" — not structural JSX):
-  - Typing into the input updates `value` via `onChange` and filters non-digits
-  - Paste of `"abc123456xyz"` results in `onChange("123456")` (one call, fully sliced)
-  - Backspace removes the last digit
-  - After entering a full code, clicking slot 3 positions the caret at slot 3 (`selectionStart === 3`) — guards the bug fix. Queries the slot via `data-slot="otp-slot"` (the only test that legitimately needs a structural selector, because the bug it guards is structural-positional)
-  - `disabled` prevents typing
-  - The underlying `<input>` exposes `inputmode="numeric"`, `maxlength=6`, `autocomplete="one-time-code"` — this assertion also implicitly covers that `length` is plumbed through to `maxLength`, so no separate "renders N slots" test is needed
-- `CheckEmailNotice.test.tsx` (behaviorally unchanged from prior commit 2 — the existing tests query by `getByLabelText(/confirmation code/i)` and assert attributes on the labeled input, both of which the new `<OtpInput>` still satisfies):
-  - Renders email and code input
-  - Submitting valid code calls `supabase.auth.verifyOtp` with expected args
-  - On verify success, calls `onVerified` prop
-  - On verify error, renders `<InlineError>`
-  - Code input enforces 6 digits / numeric only
+- `OtpInput.test.tsx` (6 behavioral tests): attribute forwarding (`inputmode` / `maxlength` / `autocomplete`); typing filters non-digits; paste yields one `onChange` call with sanitized + sliced value; backspace removes last digit; click slot 3 after full code → `selectionStart === 3` (the bug fix); `disabled` prevents typing.
+- `CheckEmailNotice.test.tsx` (4 behavioral tests, trimmed per the testing strategy — no static-JSX assertions, no duplication of `OtpInput`'s attribute matrix, no separate test per error code path):
+  - Email prop renders in the body
+  - Auto-submit fires `verifyOtp` with `{ email, token, type: 'signup' }` and `onVerified` on success
+  - Failure path renders the generic `<InlineError>` text and skips `onVerified`
+  - Verify button stays disabled (and `verifyOtp` uncalled) until the 6th digit lands
 
 **Verification:**
 
-1. `npm run web:test` + `npm run web:lint` + `npm run web:format:check` green
-2. Manual: spot-check via the working-tree `/dev/check-email` scratch route (already present at `web/src/router.tsx:304-313`) that (a) the input visually matches the prior shadcn version, (b) clicking a middle slot after entering a full code retargets the caret to that slot, (c) iOS Simulator one-time-code autofill still works against a test SMS-shaped message (sanity check that single-input architecture wasn't broken), (d) pasting `"abc123456xyz"` fills the slots with `123456`
-3. **Before committing, remove the `/dev/check-email` scratch route** (and its `CheckEmailNotice` import added solely for it) from `web/src/router.tsx`. The route is a working-tree dev artifact; it must not land in the commit. The comment at `router.tsx:304` already flags this with "Revert before commit" — this step is the enforcement of that note.
-
-**Note for reapplying over the prior shadcn-based commit 2:**
-
-- Delete `web/src/components/ui/input-otp.tsx`
-- Remove `input-otp` from `web/package.json` dependencies and run `npm install`
-- Remove the `document.elementFromPoint` polyfill from `web/src/setupTests.ts:25-30`. It was added solely because `input-otp` calls `document.elementFromPoint` in a deferred timeout to detect focus and jsdom doesn't implement it; with the library gone, the polyfill is dead code.
-- Strip the `import { REGEXP_ONLY_DIGITS } from 'input-otp'` line and the `pattern={REGEXP_ONLY_DIGITS}` prop from `CheckEmailNotice.tsx` (current `:8` and `:125`). `<OtpInput>` filters digits internally, so `pattern` is no longer a meaningful prop on the public surface.
-- Strip the slot-row layout classes from the consumer call site — what is today `<InputOTPGroup className="w-full justify-center gap-2.5">` becomes `<OtpInput className="w-full" … />`. `justify-center gap-2.5` now lives inside the primitive's slot row (see Styling above); only outer sizing (`w-full`) stays consumer-controlled.
-- The existing `CheckEmailNotice.test.tsx` assertions continue to pass against the new component, so no test churn there.
+1. `npm run web:test` + `npm run web:lint` + `npm run web:format:check` + `npm run web:build` green.
+2. Manual via a working-tree `/dev/check-email` scratch route (added during implementation, removed before commit): (a) typing 6 digits triggers auto-submit, (b) clicking a middle slot after entering a full code retargets the caret to that slot, (c) pasting `"abc123456xyz"` fills the slots with `123456`, (d) iOS Simulator one-time-code autofill still works (sanity check that single-input wasn't broken).
+3. Scratch route + its `CheckEmailNotice` import removed from `web/src/router.tsx` before commit.
 
 ---
 
@@ -160,26 +156,31 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 **Goal:** Flip the feature on. Signup goes end-to-end via either path: submit → "check your email, click link or enter code" UI → user clicks link OR types code → land back in app, logged in. (Resend deferred to commit 5; signin-unconfirmed deferred to commit 6.) This is the load-bearing commit; commits 1–2 are preparatory.
 
 **Supabase config** (`api/supabase/config.toml` and `e2e/supabase/config.toml`):
+
 - `[auth] site_url` → set to local web URL (`http://localhost:5173` for dev, `http://localhost:5273` for e2e). Existing `http://127.0.0.1:3000` is dead config; nothing in the codebase references it.
 - `[auth] additional_redirect_urls` → `["http://localhost:5173/auth/callback"]` for dev (and `5273` for e2e). Existing `https://127.0.0.1:3000` is HTTPS on a non-running port — wrong on multiple counts.
 - `[auth.email] enable_confirmations = true` (currently `false` at line 176)
 - `[auth.email.template.confirmation]` block pointing at `./templates/confirmation.html`. Both configs can reference the same file via relative path; mirrors how `e2e/supabase/migrations/` is symlinked to `api/supabase/migrations/`.
 
 **New email template** (`api/supabase/templates/confirmation.html`):
+
 - Includes both the magic link (`{{ .ConfirmationURL }}`) AND the 6-digit OTP code (`{{ .Token }}`)
 - Wording explicitly mentions "Click the link OR enter the 6-digit code in the app"
 - Plain HTML; references app name placeholder; #22 will brand it
 
 **Wiring:**
+
 - `web/src/contexts/AuthContext.tsx`:
   - Update `signUp()` to pass `options: { data: { displayName }, emailRedirectTo: ${window.location.origin}/auth/callback?redirect=<encoded redirect> }`. The `redirect` is read from the current location and forwarded so deep-links survive the email gap on the magic-link path.
   - No new context method this commit (resend in commit 5).
 - `web/src/components/auth/SignUpForm/SignUpForm.tsx`:
   - After successful `signUp()`, branch on `data.session`:
     - If `session` is non-null (auto-confirm fallback if confirmations are ever disabled): existing navigate-to-destination logic at lines 68-72.
-    - If `session` is null: set local `pending` state, render `<CheckEmailNotice email={email} onVerified={handleVerified} />` instead of the form. `handleVerified` runs the same destination logic via `getPostSignupDestination`.
+    - If `session` is null: set local `pending` state, render `<CheckEmailNotice email={email} onVerified={handleVerified} />` _in place of the existing `<Card>`_ (not the whole component) — the outer page wrapper (`<div className="flex w-full items-center justify-center p-8 md:min-h-screen">` and the `<div className="w-full max-w-md space-y-4">` cap) stays. `handleVerified` runs the same destination logic via `getPostSignupDestination`.
+  - Width nuance: `<CheckEmailNotice>` Card is `max-w-lg` (512px), but the parent's `max-w-md` cap wins, so pending renders at 448px — same width as the form. If you want pending wider, raise the `SignUpForm` wrapper's cap to `max-w-lg`.
 
 **Tests:**
+
 - `SignUpForm.test.tsx`:
   - When mocked `signUp` returns no session, `<CheckEmailNotice>` is rendered and no navigation occurs
   - When mocked `signUp` returns a session (auto-confirm fallback), existing navigation behavior preserved
@@ -187,6 +188,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
   - `signUp` calls Supabase with the expected `emailRedirectTo` (including the forwarded `redirect` query)
 
 **Verification:**
+
 1. `cd e2e/supabase && supabase stop && supabase start` to pick up config changes (also `cd api/supabase && supabase stop && supabase start`)
 2. `npm run web:dev` + `npm run api:watch`; sign up with a fresh email; confirm `<CheckEmailNotice>` appears; open the Mailpit UI at `http://127.0.0.1:54324` (served by the container Supabase still names `supabase_inbucket_*`); both pathways work — clicking the link AND typing the code each result in landing on `/create-team`
 3. `npm run web:test` + `npm run api:test` green
@@ -199,33 +201,47 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 **Goal:** Cross-system assertion that the wired-up flow from commit 3 actually works end-to-end through a real browser, against the local Supabase + Mailpit stack.
 
 **New fixture** (`e2e/fixtures/mailpit.ts`):
+
 - Helper functions: `searchByRecipient(email)`, `getMessage(id)`, `clearAll()`. Targets `http://127.0.0.1:54424` (e2e Mailpit).
 - **Note on naming:** Supabase CLI replaced Inbucket with Mailpit but kept the `[inbucket]` config block and the container name `supabase_inbucket_*` for backward compatibility. The actual image is `public.ecr.aws/supabase/mailpit` (verified via `docker inspect`), and the API surface is Mailpit's, not Inbucket's.
 - **Search by recipient:** `GET /api/v1/search?query=to:<urlencoded email>` — returns newest-first. Verified shape:
   ```json
-  { "total": 15, "count": 1, "messages_count": 1,
-    "messages": [ { "ID": "Vqp696v5jB9384dNn4y8Pr",
-      "From": { "Name": "Admin", "Address": "admin@email.com" },
-      "To": [ { "Name": "", "Address": "bob2@test.com" } ],
-      "Subject": "Confirm your F1 Fantasy email",
-      "Created": "2026-05-10T04:29:00.864Z",
-      "Snippet": "Confirm your email Welcome to F1 Fantasy!..." } ] }
+  {
+    "total": 15,
+    "count": 1,
+    "messages_count": 1,
+    "messages": [
+      {
+        "ID": "Vqp696v5jB9384dNn4y8Pr",
+        "From": { "Name": "Admin", "Address": "admin@email.com" },
+        "To": [{ "Name": "", "Address": "bob2@test.com" }],
+        "Subject": "Confirm your F1 Fantasy email",
+        "Created": "2026-05-10T04:29:00.864Z",
+        "Snippet": "Confirm your email Welcome to F1 Fantasy!..."
+      }
+    ]
+  }
   ```
 - **Fetch message body:** `GET /api/v1/message/{ID}` — note singular `message`. Returns `{ ID, Text, HTML, ... }`. The `Text` body of a Supabase signup email contains both the magic link and the OTP. Verified excerpt:
+
   ```
   Confirm your email ( http://127.0.0.1:54421/auth/v1/verify?token=pkce_49af69736d98ab8581cfb35402e76a84b69db32b81ec70fd4f78af8b&type=signup&redirect_to=http://localhost:5273/auth/callback )
 
   Or enter this code in the app: *765877*
   ```
-  The verify URL is *Supabase's* endpoint (port 54421 in e2e); hitting it 302s to the app callback (`http://localhost:5273/auth/callback?code=...`) which `<AuthCallback>` then exchanges for a session. The OTP is wrapped in `*…*` (markdown bold).
+
+  The verify URL is _Supabase's_ endpoint (port 54421 in e2e); hitting it 302s to the app callback (`http://localhost:5273/auth/callback?code=...`) which `<AuthCallback>` then exchanges for a session. The OTP is wrapped in `*…*` (markdown bold).
+
 - **Per-test isolation:** `DELETE /api/v1/messages` (no body) clears all mailboxes — call from a per-test `beforeEach` so prior tests' emails don't bleed in.
 - **Port arithmetic:** 54424 = Mailpit dev port 54324 (`api/supabase/config.toml:96`, under the still-named `[inbucket]` block) + 100 per the e2e port-shift rule.
 
 **New e2e tests** (`e2e/tests/auth.spec.ts`):
+
 - **Magic-link path:** fill signup form via UI → assert `<CheckEmailNotice>` appears → search Mailpit for the address → GET the message → regex `Text` for the verify URL → `page.goto(verifyUrl)` → assert the app shows `/create-team`.
 - **OTP path:** fill signup form → assert `<CheckEmailNotice>` appears → search Mailpit → GET the same message → regex `Text` for `/Or enter this code in the app: \*(\d{6})\*/` → type the 6 digits into the OTP input → assert the app shows `/create-team`.
 
 **Verification:**
+
 - `npm run e2e` green (existing suite + the two new tests)
 
 ---
@@ -235,12 +251,14 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 **Goal:** "Resend" button on the pending UI re-sends the confirmation email (which contains both link and OTP).
 
 **Wiring:**
+
 - `web/src/contexts/AuthContext.ts` — add `resendConfirmation(email: string, options?: { redirect?: string }): Promise<void>` to interface
 - `web/src/contexts/AuthContext.tsx` — implement: calls `supabase.auth.resend({ type: 'signup', email, options: { emailRedirectTo: ${origin}/auth/callback${redirect ? '?redirect=' + encodeURIComponent(redirect) : ''} } })`; throws on error
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — add Resend button below the OTP form. On click, call `onResend()` (parent passes `auth.resendConfirmation(email, { redirect })`). Use existing `<LoadingButton>` for loading state. Use existing `LiveRegion` to announce success ("New confirmation email sent"). Use `<InlineError>` for errors, with friendly handling for Supabase's rate-limit error code (`over_email_send_rate_limit` → "Please wait a moment before requesting another email").
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — **reintroduce** the `<CardFooter>` (removed during commit 2's trim) and add a Resend button inside it, gated on the existing `onResend` prop being present. On click, call `onResend()` (parent passes `auth.resendConfirmation(email, { redirect })`). Use existing `<LoadingButton>` for loading state. Use existing `<LiveRegion>` to announce success ("New confirmation email sent"). Use `<InlineError>` for errors, with friendly handling for Supabase's rate-limit error code (`over_email_send_rate_limit` → "Please wait a moment before requesting another email"). The `onResend` prop and `handleResend` orchestrator already exist in `Props` from commit 2's interface but render nothing today.
 - `SignUpForm.tsx` — pass `onResend={() => auth.resendConfirmation(email, { redirect })}` to `<CheckEmailNotice>`, where `redirect` is read from the current route's search params (same source as the existing `redirect` handling at `SignUpForm.tsx:68-72`)
 
 **Tests:**
+
 - `AuthContext.test.tsx`: `resendConfirmation` calls `supabase.auth.resend` with the correct args (type, email, emailRedirectTo); also tests the `redirect` option is encoded into emailRedirectTo correctly
 - `CheckEmailNotice.test.tsx`:
   - Clicking Resend calls `onResend`
@@ -251,6 +269,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - `SignUpForm.test.tsx`: Resend button passes the current `redirect` param to `resendConfirmation`
 
 **Verification:**
+
 - Manual: sign up, click Resend, verify a second email appears in Mailpit; either email's link OR either email's most-recent OTP completes verification
 - Manual: rapid-fire Resend → rate-limit message
 - All test commands green
@@ -262,9 +281,11 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 **Goal:** If a user signs up but never confirms, then later tries to sign in, they see the same `<CheckEmailNotice>` (with OTP entry + Resend) instead of a generic auth error.
 
 **Wiring:**
-- `web/src/components/auth/SignInForm/SignInForm.tsx` — after `signIn()` throws, inspect the error: if it's Supabase's `email_not_confirmed` (check `error.code === 'email_not_confirmed'` — verified against `auth-js/src/lib/error-codes.ts`; `AuthApiError` has a string `code` property per `auth-js/src/lib/errors.ts`), set local `pending` state and render `<CheckEmailNotice email={email} onVerified={handleVerified} onResend={() => auth.resendConfirmation(email, { redirect })} />`, where `redirect` is the current route's `redirect` search param (same source as today's signin redirect handling at `SignInForm.tsx:33-37`). `handleVerified` here navigates to redirect-or-`/leagues`. For any other error, fall through to the existing `<InlineError>` at `SignInForm.tsx:39-43`. The Resend's `redirect` override means the resent email's magic link will encode the signin-time destination rather than the (potentially different) signup-time one.
+
+- `web/src/components/auth/SignInForm/SignInForm.tsx` — after `signIn()` throws, inspect the error: if it's Supabase's `email_not_confirmed` (check `error.code === 'email_not_confirmed'` — verified against `auth-js/src/lib/error-codes.ts`; `AuthApiError` has a string `code` property per `auth-js/src/lib/errors.ts`), set local `pending` state and render `<CheckEmailNotice email={email} onVerified={handleVerified} onResend={() => auth.resendConfirmation(email, { redirect })} />` _in place of the existing `<Card>`_ (the outer page wrapper stays, same shape as commit 3's `SignUpForm` wiring), where `redirect` is the current route's `redirect` search param (same source as today's signin redirect handling at `SignInForm.tsx:33-37`). `handleVerified` here navigates to redirect-or-`/leagues`. For any other error, fall through to the existing `<InlineError>` at `SignInForm.tsx:39-43`. The Resend's `redirect` override means the resent email's magic link will encode the signin-time destination rather than the (potentially different) signup-time one.
 
 **Tests:**
+
 - `SignInForm.test.tsx`:
   - Mocked `signIn` rejects with `email_not_confirmed` → `<CheckEmailNotice>` rendered, no navigation
   - Mocked `signIn` rejects with any other error → existing `<InlineError>` behavior preserved
@@ -272,6 +293,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
   - Resend from this context passes the signin-time `redirect` param to `resendConfirmation`
 
 **Verification:**
+
 - Manual: sign up, do NOT click the email link / enter the OTP, navigate to `/sign-in`, attempt sign-in with the unconfirmed credentials, verify pending UI appears with working OTP entry + Resend
 - All test commands green
 
@@ -280,6 +302,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 ## Critical files
 
 **Modified:**
+
 - `web/src/lib/supabase.ts` (commit 1 — add `flowType: 'pkce'`)
 - `web/src/router.tsx` (commit 1 — add `/auth/callback` route with loader, pendingComponent, and inline errorComponent)
 - `api/supabase/config.toml` (commit 3)
@@ -290,6 +313,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - `web/src/components/auth/SignInForm/SignInForm.tsx` (commit 6)
 
 **New:**
+
 - `web/src/lib/auth-destination.ts` + `auth-destination.test.ts` (commit 1)
 - `web/src/tests/integration/auth-callback.integration.test.tsx` (commit 1)
 - `web/src/components/OtpInput/OtpInput.tsx` + `OtpInput.test.tsx` (commit 2) — custom OTP input primitive; lives at the top level of `components/` alongside other custom primitives (`LoadingButton`, `InlineError`, etc.), not in `ui/` (reserved for vendored shadcn)
@@ -299,6 +323,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - New tests in `e2e/tests/auth.spec.ts` (commit 4)
 
 **Reused (existing components, no changes):**
+
 - `web/src/components/InlineError/InlineError.tsx` — error display in the auth-callback `errorComponent`, `<CheckEmailNotice>`, existing forms
 - `web/src/components/LiveRegion/LiveRegion.tsx` — screen-reader announcements
 - `web/src/components/LoadingButton/LoadingButton.tsx` — Verify and Resend button loading states

From ab7b47158abe722e4ddc83f41da1d8c850c05872 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Tue, 12 May 2026 20:07:19 -0500
Subject: [PATCH 09/25] docs(plans): reorder #164 commits and add integration
 tests

Move e2e coverage to commit 6 so it lands after every flow it asserts.
Add two frontend integration tests (signup-resend in commit 4,
signin-unconfirmed in commit 5) to cover the router + Supabase SDK
wiring that unit tests and the targeted e2e suite don't reach. Pin
down commit 6's OTP-input selector and Mailpit polling approach.
---
 docs/plans/164-email-confirmation-signup.md | 144 +++++++++++---------
 1 file changed, 77 insertions(+), 67 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index 4f56e10..a763cc2 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -29,10 +29,10 @@ Email confirmations are currently disabled in Supabase (`enable_confirmations =
 | Failure copy                                | Static generic message _"That code didn't match. Check your email for the latest one."_ — not the raw Supabase error string                                                                                                             | Supabase emits jargon ("Token has expired or is invalid"). Users typed a "code", not a "token", and the canonical follow-up is to enter a new code from the latest email. Also: `verify()` no longer optimistically clears the error at function entry (only on success), so re-attempts don't unmount/remount the `<InlineError>` and trigger a layout shift mid-flight.                                                                                                                                                                                                                                           |
 | Error placement inside `<CheckEmailNotice>` | `<InlineError>` sits _under_ the slot row, inside the same `space-y-3` group, replacing the idle-state status hint when present                                                                                                         | Keeps the eye path slots → error → button continuous. Originally placed above the slots; that path made the user snap up to the top, then back down to retype.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | Email passing                               | React state within form components                                                                                                                                                                                                      | User never retypes — Supabase's confirmation token uniquely identifies the user. Email passed as prop from parent (`SignUpForm`, `SignInForm`) into `<CheckEmailNotice>`.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Sign-in unconfirmed handling                | In scope, same issue (commit 6)                                                                                                                                                                                                         | Completes the verification story: signup → pending → resend → confirm AND signin → unconfirmed → resend.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Sign-in unconfirmed handling                | In scope, same issue (commit 5)                                                                                                                                                                                                         | Completes the verification story: signup → pending → resend → confirm AND signin → unconfirmed → resend.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | Post-confirmation destination               | Preserve current logic per parent (`SignUpForm` → redirect-or-`/create-team`; `SignInForm` → redirect-or-`/leagues`; magic link callback uses URL `redirect` search param, else `/create-team`)                                         | Standardization deferred to #165.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Resend with redirect override               | `AuthContext.resendConfirmation(email, { redirect? })` accepts the current redirect param so the resent email's link encodes the _current_ destination (e.g., signin's `/leagues/123`) rather than whatever was baked in at signup time | Helps a user who hits the unconfirmed-signin path with a deep link, triggers Resend, and uses the new email's link. The original signup email's link still routes to `/create-team` (can't fix retroactively); the OTP path always routes correctly via the callsite.                                                                                                                                                                                                                                                                                                                                               |
-| E2E approach                                | Existing admin-API fixture keeps `email_confirm: true` (auto-confirms); add two new tests in commit 4 (magic-link path + OTP path)                                                                                                      | Existing tests stay fast; targeted e2e covers the new wiring                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| E2E approach                                | Existing admin-API fixture keeps `email_confirm: true` (auto-confirms); add two new tests in commit 6 (magic-link path + OTP path)                                                                                                      | Existing tests stay fast; targeted e2e covers the new wiring                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | Email template                              | Custom template at `api/supabase/templates/confirmation.html` includes both `{{ .ConfirmationURL }}` and `{{ .Token }}`, lands in commit 3 alongside the config flip                                                                    | Default Supabase template already has both; we're shipping our own to control wording and prep for #22's branding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Cross-issue ordering                        | 164 → 167 → 165 (locked)                                                                                                                                                                                                                | 164 builds verification primitives; 167 reuses callback route + OTP entry pattern for change-email re-verification; 165 audits all destinations after both new flows exist.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | Auth callback implementation                | **Route loader + inline `errorComponent`, no separate component**                                                                                                                                                                       | Async work belongs in a TanStack Router `loader` (matches every other async route in the codebase — `joinInviteRoute`, `accountRoute`, etc.); avoids the `useEffect` + `cancelled`-flag anti-pattern. Side effects (Sentry capture) live at the failure site inside the loader's `try/catch`, not in a render-time hook. The shared `ErrorFallback` doesn't fit (hardcoded copy + "Try again" button; reloading can't fix a consumed PKCE code), and the bespoke error UI is small enough to inline in `errorComponent` rather than warrant a dedicated component file.                                             |
@@ -121,12 +121,12 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 
 **New flow component — `<CheckEmailNotice>`** (`web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx`):
 
-- **Returns just a `<Card>`** — no outer page wrapper. Caller (commit 3's `SignUpForm`, commit 6's `SignInForm`, dev-route scaffolding) provides centering, full-viewport height, and background.
+- **Returns just a `<Card>`** — no outer page wrapper. Caller (commit 3's `SignUpForm`, commit 5's `SignInForm`, dev-route scaffolding) provides centering, full-viewport height, and background.
 - **Props:**
   - `email: string` — rendered in the body
   - `onVerified: () => void` — called after `verifyOtp` resolves successfully so caller can navigate
-  - `onResend?: () => Promise<void>` — declared in `Props` for commit 5; renders nothing in commit 2 (no `CardFooter` yet)
-  - `onChangeEmail?: () => void` — same; renders nothing until commit 5 reintroduces the `CardFooter`
+  - `onResend?: () => Promise<void>` — declared in `Props` for commit 4; renders nothing in commit 2 (no `CardFooter` yet)
+  - `onChangeEmail?: () => void` — same; renders nothing until commit 4 reintroduces the `CardFooter`
 - **Layout:**
   - `CardHeader`: envelope icon, "Check your email" heading, two-paragraph body (sentence 1 with the email chip; sentence 2 with "Enter it below or click the link…") wrapped in a `space-y-2` div so the two `<p>`s are visually separated.
   - `CardContent` (`space-y-4`): a `space-y-3` group containing the label + progress bar, the `<OtpInput length={6} className="w-full" />`, and (when set) `<InlineError>`. Below the group, a centered `<LoadingButton size="lg" min-w-48>` that fires `verify(code)` on click.
@@ -153,7 +153,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 
 ### Commit 3 — Enable confirmations + wire SignUpForm into the pending UI
 
-**Goal:** Flip the feature on. Signup goes end-to-end via either path: submit → "check your email, click link or enter code" UI → user clicks link OR types code → land back in app, logged in. (Resend deferred to commit 5; signin-unconfirmed deferred to commit 6.) This is the load-bearing commit; commits 1–2 are preparatory.
+**Goal:** Flip the feature on. Signup goes end-to-end via either path: submit → "check your email, click link or enter code" UI → user clicks link OR types code → land back in app, logged in. (Resend deferred to commit 4; signin-unconfirmed deferred to commit 5.) This is the load-bearing commit; commits 1–2 are preparatory.
 
 **Supabase config** (`api/supabase/config.toml` and `e2e/supabase/config.toml`):
 
@@ -172,7 +172,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 
 - `web/src/contexts/AuthContext.tsx`:
   - Update `signUp()` to pass `options: { data: { displayName }, emailRedirectTo: ${window.location.origin}/auth/callback?redirect=<encoded redirect> }`. The `redirect` is read from the current location and forwarded so deep-links survive the email gap on the magic-link path.
-  - No new context method this commit (resend in commit 5).
+  - No new context method this commit (resend in commit 4).
 - `web/src/components/auth/SignUpForm/SignUpForm.tsx`:
   - After successful `signUp()`, branch on `data.session`:
     - If `session` is non-null (auto-confirm fallback if confirmations are ever disabled): existing navigate-to-destination logic at lines 68-72.
@@ -196,57 +196,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 
 ---
 
-### Commit 4 — E2E coverage for magic-link and OTP signup paths
-
-**Goal:** Cross-system assertion that the wired-up flow from commit 3 actually works end-to-end through a real browser, against the local Supabase + Mailpit stack.
-
-**New fixture** (`e2e/fixtures/mailpit.ts`):
-
-- Helper functions: `searchByRecipient(email)`, `getMessage(id)`, `clearAll()`. Targets `http://127.0.0.1:54424` (e2e Mailpit).
-- **Note on naming:** Supabase CLI replaced Inbucket with Mailpit but kept the `[inbucket]` config block and the container name `supabase_inbucket_*` for backward compatibility. The actual image is `public.ecr.aws/supabase/mailpit` (verified via `docker inspect`), and the API surface is Mailpit's, not Inbucket's.
-- **Search by recipient:** `GET /api/v1/search?query=to:<urlencoded email>` — returns newest-first. Verified shape:
-  ```json
-  {
-    "total": 15,
-    "count": 1,
-    "messages_count": 1,
-    "messages": [
-      {
-        "ID": "Vqp696v5jB9384dNn4y8Pr",
-        "From": { "Name": "Admin", "Address": "admin@email.com" },
-        "To": [{ "Name": "", "Address": "bob2@test.com" }],
-        "Subject": "Confirm your F1 Fantasy email",
-        "Created": "2026-05-10T04:29:00.864Z",
-        "Snippet": "Confirm your email Welcome to F1 Fantasy!..."
-      }
-    ]
-  }
-  ```
-- **Fetch message body:** `GET /api/v1/message/{ID}` — note singular `message`. Returns `{ ID, Text, HTML, ... }`. The `Text` body of a Supabase signup email contains both the magic link and the OTP. Verified excerpt:
-
-  ```
-  Confirm your email ( http://127.0.0.1:54421/auth/v1/verify?token=pkce_49af69736d98ab8581cfb35402e76a84b69db32b81ec70fd4f78af8b&type=signup&redirect_to=http://localhost:5273/auth/callback )
-
-  Or enter this code in the app: *765877*
-  ```
-
-  The verify URL is _Supabase's_ endpoint (port 54421 in e2e); hitting it 302s to the app callback (`http://localhost:5273/auth/callback?code=...`) which `<AuthCallback>` then exchanges for a session. The OTP is wrapped in `*…*` (markdown bold).
-
-- **Per-test isolation:** `DELETE /api/v1/messages` (no body) clears all mailboxes — call from a per-test `beforeEach` so prior tests' emails don't bleed in.
-- **Port arithmetic:** 54424 = Mailpit dev port 54324 (`api/supabase/config.toml:96`, under the still-named `[inbucket]` block) + 100 per the e2e port-shift rule.
-
-**New e2e tests** (`e2e/tests/auth.spec.ts`):
-
-- **Magic-link path:** fill signup form via UI → assert `<CheckEmailNotice>` appears → search Mailpit for the address → GET the message → regex `Text` for the verify URL → `page.goto(verifyUrl)` → assert the app shows `/create-team`.
-- **OTP path:** fill signup form → assert `<CheckEmailNotice>` appears → search Mailpit → GET the same message → regex `Text` for `/Or enter this code in the app: \*(\d{6})\*/` → type the 6 digits into the OTP input → assert the app shows `/create-team`.
-
-**Verification:**
-
-- `npm run e2e` green (existing suite + the two new tests)
-
----
-
-### Commit 5 — Resend confirmation email
+### Commit 4 — Resend confirmation email
 
 **Goal:** "Resend" button on the pending UI re-sends the confirmation email (which contains both link and OTP).
 
@@ -267,6 +217,9 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
   - Generic error rendered via `InlineError`
   - Rate-limit error renders friendly text
 - `SignUpForm.test.tsx`: Resend button passes the current `redirect` param to `resendConfirmation`
+- `web/src/tests/integration/signup-resend.integration.test.tsx` — frontend integration (real router over an inline route-tree mirror, same convention as `auth-callback.integration.test.tsx` and `account.integration.test.tsx`; mock only the Supabase SDK):
+  - Mount the app at `/sign-up?redirect=/leagues/123`, submit the form, assert `<CheckEmailNotice>` renders. Click Resend, assert `supabase.auth.resend` was called with `{ type: 'signup', email, options: { emailRedirectTo: 'http://localhost/auth/callback?redirect=%2Fleagues%2F123' } }` — proves the route's `redirect` search param actually threads through the form → context → SDK call.
+  - Same setup, mock `supabase.auth.resend` to return `{ error: { code: 'over_email_send_rate_limit' } }`, click Resend, assert the friendly rate-limit copy renders (catches the error-code → user-copy wiring in the router context).
 
 **Verification:**
 
@@ -276,7 +229,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 
 ---
 
-### Commit 6 — Friendly handling of unconfirmed-email sign-in
+### Commit 5 — Friendly handling of unconfirmed-email sign-in
 
 **Goal:** If a user signs up but never confirms, then later tries to sign in, they see the same `<CheckEmailNotice>` (with OTP entry + Resend) instead of a generic auth error.
 
@@ -291,6 +244,9 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
   - Mocked `signIn` rejects with any other error → existing `<InlineError>` behavior preserved
   - On `<CheckEmailNotice>` `onVerified`, navigation runs with signin destination logic
   - Resend from this context passes the signin-time `redirect` param to `resendConfirmation`
+- `web/src/tests/integration/signin-unconfirmed.integration.test.tsx` — frontend integration (real router over inline route-tree mirror; mock only the Supabase SDK):
+  - Mount at `/sign-in?redirect=/leagues/123`, mock `supabase.auth.signInWithPassword` to reject with `{ code: 'email_not_confirmed' }`, submit the form, assert `<CheckEmailNotice>` renders (proves the error-code → pending-state wiring in the real router context).
+  - Continue the same flow: mock `supabase.auth.verifyOtp` to resolve successfully, type 6 digits into the OTP input, assert navigation lands at `/leagues/123` (proves the signin-time `redirect` param threads through `handleVerified` rather than falling back to `/leagues`).
 
 **Verification:**
 
@@ -299,6 +255,58 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 
 ---
 
+### Commit 6 — E2E coverage for magic-link and OTP signup paths
+
+**Goal:** Cross-system assertion that the wired-up flow from commit 3 actually works end-to-end through a real browser, against the local Supabase + Mailpit stack.
+
+**New fixture** (`e2e/fixtures/mailpit.ts`):
+
+- Helper functions: `searchByRecipient(email)`, `getMessage(id)`, `clearAll()`. Thin HTTP wrappers, single-shot — no internal retry/polling. Targets `http://127.0.0.1:54424` (e2e Mailpit).
+- **Waiting for an email to arrive:** callsites wrap `searchByRecipient` in `expect.poll(...).toHaveProperty('count', 1)` (Playwright's built-in polling assertion). Polling lives in test code, not the fixture, so waits are visible at the callsite, integrate with Playwright's timeout reporting, and individual tests can vary the expected count (e.g., `2` for a resend test). No `sleep`-based waits anywhere.
+- **Note on naming:** Supabase CLI replaced Inbucket with Mailpit but kept the `[inbucket]` config block and the container name `supabase_inbucket_*` for backward compatibility. The actual image is `public.ecr.aws/supabase/mailpit` (verified via `docker inspect`), and the API surface is Mailpit's, not Inbucket's.
+- **Search by recipient:** `GET /api/v1/search?query=to:<urlencoded email>` — returns newest-first. Verified shape:
+  ```json
+  {
+    "total": 15,
+    "count": 1,
+    "messages_count": 1,
+    "messages": [
+      {
+        "ID": "Vqp696v5jB9384dNn4y8Pr",
+        "From": { "Name": "Admin", "Address": "admin@email.com" },
+        "To": [{ "Name": "", "Address": "bob2@test.com" }],
+        "Subject": "Confirm your F1 Fantasy email",
+        "Created": "2026-05-10T04:29:00.864Z",
+        "Snippet": "Confirm your email Welcome to F1 Fantasy!..."
+      }
+    ]
+  }
+  ```
+- **Fetch message body:** `GET /api/v1/message/{ID}` — note singular `message`. Returns `{ ID, Text, HTML, ... }`. The `Text` body of a Supabase signup email contains both the magic link and the OTP. Verified excerpt:
+
+  ```
+  Confirm your email ( http://127.0.0.1:54421/auth/v1/verify?token=pkce_49af69736d98ab8581cfb35402e76a84b69db32b81ec70fd4f78af8b&type=signup&redirect_to=http://localhost:5273/auth/callback )
+
+  Or enter this code in the app: *765877*
+  ```
+
+  The verify URL is _Supabase's_ endpoint (port 54421 in e2e); hitting it 302s to the app callback (`http://localhost:5273/auth/callback?code=...`) which `<AuthCallback>` then exchanges for a session. The OTP is wrapped in `*…*` (markdown bold).
+
+- **Per-test isolation:** `DELETE /api/v1/messages` (no body) clears all mailboxes — call from a per-test `beforeEach` so prior tests' emails don't bleed in.
+- **Port arithmetic:** 54424 = Mailpit dev port 54324 (`api/supabase/config.toml:96`, under the still-named `[inbucket]` block) + 100 per the e2e port-shift rule.
+
+**New e2e tests** (`e2e/tests/auth.spec.ts`):
+
+- **OTP-input selector note:** the `<OtpInput>` from commit 2 renders 6 visible slot `<div>`s overlaying a single real `<input autocomplete="one-time-code">`. Tests type the 6-digit code into the underlying input (queryable via its `aria-label`), not into individual slots — the slot `<div>`s are `aria-hidden`. This is the only commit-6-specific selector callout; everything else follows the project-wide semantic-selector discipline from `e2e/README`.
+- **Magic-link path:** fill signup form via UI → assert `<CheckEmailNotice>` appears → `expect.poll(() => mailpit.searchByRecipient(email)).toHaveProperty('count', 1)` → GET the message → regex `Text` for the verify URL → `page.goto(verifyUrl)` → assert the app shows `/create-team`.
+- **OTP path:** fill signup form → assert `<CheckEmailNotice>` appears → poll Mailpit for the message → GET it → regex `Text` for `/Or enter this code in the app: \*(\d{6})\*/` → type the 6 digits into the OTP input (the single underlying `<input>`, per the selector note above) → assert the app shows `/create-team`.
+
+**Verification:**
+
+- `npm run e2e` green (existing suite + the two new tests)
+
+---
+
 ## Critical files
 
 **Modified:**
@@ -307,27 +315,29 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - `web/src/router.tsx` (commit 1 — add `/auth/callback` route with loader, pendingComponent, and inline errorComponent)
 - `api/supabase/config.toml` (commit 3)
 - `e2e/supabase/config.toml` (commit 3)
-- `web/src/contexts/AuthContext.tsx` (commits 3, 5)
-- `web/src/contexts/AuthContext.ts` (commit 5)
-- `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commit 3, minor in commit 5)
-- `web/src/components/auth/SignInForm/SignInForm.tsx` (commit 6)
+- `web/src/contexts/AuthContext.tsx` (commits 3, 4)
+- `web/src/contexts/AuthContext.ts` (commit 4)
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commit 3, minor in commit 4)
+- `web/src/components/auth/SignInForm/SignInForm.tsx` (commit 5)
 
 **New:**
 
 - `web/src/lib/auth-destination.ts` + `auth-destination.test.ts` (commit 1)
 - `web/src/tests/integration/auth-callback.integration.test.tsx` (commit 1)
 - `web/src/components/OtpInput/OtpInput.tsx` + `OtpInput.test.tsx` (commit 2) — custom OTP input primitive; lives at the top level of `components/` alongside other custom primitives (`LoadingButton`, `InlineError`, etc.), not in `ui/` (reserved for vendored shadcn)
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` + `.test.tsx` (commit 2; expanded in commit 5)
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` + `.test.tsx` (commit 2; expanded in commit 4)
 - `api/supabase/templates/confirmation.html` (commit 3; includes both link and OTP from the start)
-- `e2e/fixtures/mailpit.ts` (commit 4)
-- New tests in `e2e/tests/auth.spec.ts` (commit 4)
+- `web/src/tests/integration/signup-resend.integration.test.tsx` (commit 4)
+- `web/src/tests/integration/signin-unconfirmed.integration.test.tsx` (commit 5)
+- `e2e/fixtures/mailpit.ts` (commit 6)
+- New tests in `e2e/tests/auth.spec.ts` (commit 6)
 
 **Reused (existing components, no changes):**
 
 - `web/src/components/InlineError/InlineError.tsx` — error display in the auth-callback `errorComponent`, `<CheckEmailNotice>`, existing forms
 - `web/src/components/LiveRegion/LiveRegion.tsx` — screen-reader announcements
 - `web/src/components/LoadingButton/LoadingButton.tsx` — Verify and Resend button loading states
-- `web/src/hooks/useAuth.ts` — auth hook (gains `resendConfirmation` in commit 5)
+- `web/src/hooks/useAuth.ts` — auth hook (gains `resendConfirmation` in commit 4)
 
 ---
 

From de592bc00a5929658f1ac9dcc32612df87b6b9c2 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Wed, 13 May 2026 00:19:05 -0500
Subject: [PATCH 10/25] feat(web): enable email confirmation on signup

Flip enable_confirmations on in both Supabase stacks, ship a custom
confirmation template that includes both magic link and OTP code, and
wire SignUpForm into the existing <CheckEmailNotice> pending UI when
signUp returns no session.

- AuthContext.signUp gains an options.redirect param and returns
  { session } so the form can branch on auto-confirm vs. pending; the
  redirect threads through to emailRedirectTo so deep-links survive
  the email gap on the magic-link path.
- supabase client disables detectSessionInUrl so the auth-callback
  loader owns the PKCE code exchange without racing the SDK's
  default URL watcher.
- requireAuth route guard falls back to supabase.auth.getSession()
  before redirecting; otherwise the moment between
  exchangeCodeForSession and the next AuthContext render bounces a
  freshly-confirmed user back to /.
- <OtpInput> gains an onComplete callback plus an onBeforeInput
  splice handler. The handler fixes the same-digit-replacement case
  in a full code (React's value tracker skips onChange when the new
  character matches the old). Slot sizing goes responsive so the row
  fits on ~320px phones.
- config-sync.spec.ts now ignores site_url and additional_redirect_urls
  since they encode the web port (5173 dev, 5273 e2e) which differs by
  the +100 e2e convention.
- e2e/supabase/templates symlinks to api/supabase/templates so both
  stacks read the same confirmation.html.
---
 api/supabase/config.toml                      |  10 +-
 api/supabase/templates/confirmation.html      | 255 ++++++++++++++++++
 e2e/supabase/config.toml                      |  10 +-
 e2e/supabase/templates                        |   1 +
 e2e/tests/_infra/config-sync.spec.ts          |  16 +-
 web/src/components/OtpInput/OtpInput.test.tsx |  41 +++
 web/src/components/OtpInput/OtpInput.tsx      |  59 +++-
 .../CheckEmailNotice.test.tsx                 |   1 +
 .../CheckEmailNotice/CheckEmailNotice.tsx     |  10 +-
 .../auth/SignUpForm/SignUpForm.test.tsx       |  47 +++-
 .../components/auth/SignUpForm/SignUpForm.tsx | 177 ++++++------
 web/src/contexts/AuthContext.test.tsx         |  29 +-
 web/src/contexts/AuthContext.ts               |   7 +-
 web/src/contexts/AuthContext.tsx              |  15 +-
 web/src/lib/route-guards.test.ts              | 121 +++------
 web/src/lib/route-guards.ts                   |  21 +-
 web/src/lib/supabase.test.ts                  |   1 +
 web/src/lib/supabase.ts                       |   2 +
 18 files changed, 616 insertions(+), 207 deletions(-)
 create mode 100644 api/supabase/templates/confirmation.html
 create mode 120000 e2e/supabase/templates

diff --git a/api/supabase/config.toml b/api/supabase/config.toml
index a29087a..d9710cf 100644
--- a/api/supabase/config.toml
+++ b/api/supabase/config.toml
@@ -120,9 +120,9 @@ file_size_limit = "50MiB"
 enabled = true
 # The base URL of your website. Used as an allow-list for redirects and for constructing URLs used
 # in emails.
-site_url = "http://127.0.0.1:3000"
+site_url = "http://localhost:5173"
 # A list of *exact* URLs that auth providers are permitted to redirect to post authentication.
-additional_redirect_urls = ["https://127.0.0.1:3000"]
+additional_redirect_urls = ["http://localhost:5173/auth/callback"]
 # How long tokens are valid for, in seconds. Defaults to 3600 (1 hour), maximum 604,800 (1 week).
 jwt_expiry = 604800
 # Path to JWT signing key. DO NOT commit your signing keys file to git.
@@ -173,7 +173,7 @@ enable_signup = true
 # addresses. If disabled, only the new email is required to confirm.
 double_confirm_changes = true
 # If enabled, users need to confirm their email address before signing in.
-enable_confirmations = false
+enable_confirmations = true
 # If enabled, users will need to reauthenticate or have logged in recently to change their password.
 secure_password_change = false
 # Controls the minimum amount of time that must pass before sending another signup confirmation or password reset email.
@@ -198,6 +198,10 @@ otp_expiry = 3600
 # subject = "You have been invited"
 # content_path = "./supabase/templates/invite.html"
 
+[auth.email.template.confirmation]
+subject = "Confirm your F1 Fantasy email"
+content_path = "./supabase/templates/confirmation.html"
+
 [auth.sms]
 # Allow/disallow new user signups via SMS to your project.
 enable_signup = false
diff --git a/api/supabase/templates/confirmation.html b/api/supabase/templates/confirmation.html
new file mode 100644
index 0000000..1fce0d8
--- /dev/null
+++ b/api/supabase/templates/confirmation.html
@@ -0,0 +1,255 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
+    <meta name="supported-color-schemes" content="light dark" />
+    <meta name="x-apple-disable-message-reformatting" />
+    <title>Confirm your email — F1 Fantasy</title>
+    <style>
+      /* Reset (clients ignore most, but harmless) */
+      body,
+      table,
+      td,
+      p,
+      a {
+        -webkit-text-size-adjust: 100%;
+        -ms-text-size-adjust: 100%;
+      }
+      table,
+      td {
+        mso-table-lspace: 0pt;
+        mso-table-rspace: 0pt;
+        border-collapse: collapse;
+      }
+      img {
+        -ms-interpolation-mode: bicubic;
+        border: 0;
+        outline: none;
+        text-decoration: none;
+      }
+
+      /* Dark mode for clients that honour prefers-color-scheme (Apple Mail, iOS, etc.) */
+      @media (prefers-color-scheme: dark) {
+        body,
+        .bg {
+          background: #18181b !important;
+        }
+        .text-strong {
+          color: #fafafa !important;
+        }
+        .text-dim {
+          color: #a1a1aa !important;
+        }
+        .text-faint {
+          color: #71717b !important;
+        }
+        .rule {
+          border-color: rgba(255, 255, 255, 0.1) !important;
+        }
+        .btn {
+          background: #fafafa !important;
+          color: #18181b !important;
+        }
+        .brand-stroke {
+          stroke: #fafafa !important;
+        }
+        .link {
+          color: #71717b !important;
+        }
+      }
+
+      /* Mobile */
+      @media only screen and (max-width: 520px) {
+        .container {
+          width: 100% !important;
+          padding-left: 24px !important;
+          padding-right: 24px !important;
+        }
+        .h1 {
+          font-size: 24px !important;
+          line-height: 1.22 !important;
+        }
+        .cta-row {
+          display: block !important;
+        }
+        .cta-row .cta-aside {
+          display: block !important;
+          margin: 10px 0 0 0 !important;
+        }
+      }
+
+      /* Force solid background on the page in Outlook desktop */
+      body {
+        margin: 0 !important;
+        padding: 0 !important;
+      }
+    </style>
+  </head>
+  <body class="bg" style="margin: 0; padding: 0; background: #ffffff">
+    <!-- Hidden preheader -->
+    <div style="display: none; max-height: 0; overflow: hidden; mso-hide: all; font-size: 1px; line-height: 1px; color: #ffffff">
+      Confirm your email to start drafting your F1 Fantasy team. Code: {{ .Token }}
+    </div>
+
+    <table role="presentation" class="bg" width="100%" cellpadding="0" cellspacing="0" border="0" style="background: #ffffff">
+      <tr>
+        <td align="center" style="padding: 56px 16px 48px">
+          <table
+            role="presentation"
+            class="container"
+            width="480"
+            cellpadding="0"
+            cellspacing="0"
+            border="0"
+            style="max-width: 480px; width: 100%; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
+          >
+            <!-- Wordmark -->
+            <tr>
+              <td style="padding: 0 0 40px">
+                <table role="presentation" cellpadding="0" cellspacing="0" border="0">
+                  <tr>
+                    <td valign="middle" style="padding-right: 8px; line-height: 0">
+                      <!-- Trophy mark -->
+                      <svg
+                        xmlns="http://www.w3.org/2000/svg"
+                        width="18"
+                        height="18"
+                        viewBox="0 0 24 24"
+                        fill="none"
+                        stroke="#09090b"
+                        class="brand-stroke"
+                        stroke-width="2"
+                        stroke-linecap="round"
+                        stroke-linejoin="round"
+                        aria-hidden="true"
+                      >
+                        <path d="M6 9H4.5a2.5 2.5 0 0 1 0-5H6" />
+                        <path d="M18 9h1.5a2.5 2.5 0 0 0 0-5H18" />
+                        <path d="M4 22h16" />
+                        <path d="M10 14.66V17c0 .55-.47.98-.97 1.21C7.85 18.75 7 20.24 7 22" />
+                        <path d="M14 14.66V17c0 .55.47.98.97 1.21C16.15 18.75 17 20.24 17 22" />
+                        <path d="M18 2H6v7a6 6 0 0 0 12 0V2Z" />
+                      </svg>
+                    </td>
+                    <td valign="middle" class="text-strong" style="font-size: 13px; font-weight: 600; color: #09090b; letter-spacing: 0.04em">
+                      F1 Fantasy
+                    </td>
+                  </tr>
+                </table>
+              </td>
+            </tr>
+
+            <!-- Headline -->
+            <tr>
+              <td style="padding: 0 0 14px">
+                <h1
+                  class="h1 text-strong"
+                  style="margin: 0; font-size: 28px; font-weight: 600; color: #09090b; letter-spacing: -0.022em; line-height: 1.2"
+                >
+                  You're on the grid.
+                </h1>
+              </td>
+            </tr>
+
+            <!-- Body paragraph -->
+            <tr>
+              <td class="text-dim" style="padding: 0 0 28px; font-size: 15.5px; color: #52525b; line-height: 1.65">
+                Confirm your email below and you can start drafting drivers, building your team, and joining leagues. The link expires in
+                60&nbsp;minutes.
+              </td>
+            </tr>
+
+            <!-- CTA + aside -->
+            <tr>
+              <td style="padding: 0 0 36px">
+                <table role="presentation" cellpadding="0" cellspacing="0" border="0" class="cta-row">
+                  <tr>
+                    <td valign="middle">
+                      <!-- Bulletproof button -->
+                      <a
+                        href="{{ .ConfirmationURL }}"
+                        class="btn"
+                        style="
+                          display: inline-block;
+                          padding: 11px 20px;
+                          background: #09090b;
+                          color: #ffffff;
+                          border-radius: 8px;
+                          font-size: 14px;
+                          font-weight: 600;
+                          text-decoration: none;
+                          letter-spacing: -0.005em;
+                          font-family: inherit;
+                        "
+                      >
+                        Confirm your email
+                      </a>
+                    </td>
+                    <td valign="middle" class="cta-aside text-faint" style="padding-left: 12px; font-size: 13px; color: #71717b">
+                      or paste the code below
+                    </td>
+                  </tr>
+                </table>
+              </td>
+            </tr>
+
+            <!-- Hairline + code row -->
+            <tr>
+              <td class="rule" style="border-top: 1px solid #e4e4e7; font-size: 0; line-height: 0">&nbsp;</td>
+            </tr>
+            <tr>
+              <td class="rule" style="padding: 16px 0 18px; border-bottom: 1px solid #e4e4e7">
+                <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
+                  <tr>
+                    <td valign="middle" class="text-faint" style="font-size: 12px; color: #71717b; letter-spacing: 0.04em">Verification code</td>
+                    <td
+                      valign="middle"
+                      align="right"
+                      class="text-strong"
+                      style="
+                        font-family: 'SF Mono', ui-monospace, Menlo, Consolas, monospace;
+                        font-size: 22px;
+                        font-weight: 600;
+                        color: #09090b;
+                        letter-spacing: 0.22em;
+                      "
+                    >
+                      {{ .Token }}
+                    </td>
+                  </tr>
+                </table>
+              </td>
+            </tr>
+
+            <!-- Sign-off -->
+            <tr>
+              <td style="padding: 32px 0 0">
+                <p class="text-dim" style="margin: 0 0 6px; font-size: 14.5px; color: #52525b; line-height: 1.6">Welcome aboard,</p>
+                <p class="text-strong" style="margin: 0; font-size: 14.5px; color: #09090b; font-weight: 500">The F1 Fantasy team</p>
+              </td>
+            </tr>
+
+            <!-- Postscript -->
+            <tr>
+              <td class="text-faint" style="padding: 32px 0 0; font-size: 12.5px; color: #71717b; line-height: 1.6">
+                <span class="text-dim" style="color: #52525b; font-weight: 500">P.S.</span>
+                Didn't sign up for F1 Fantasy? You can safely ignore this email — no account will be created.
+              </td>
+            </tr>
+
+            <!-- Outer footer -->
+            <tr>
+              <td style="padding: 40px 0 0; font-size: 11.5px; color: #71717b; line-height: 1.6" class="text-faint">
+                <a href="#" class="link" style="color: #71717b; text-decoration: underline">Unsubscribe</a>
+                <span> · </span>
+                <a href="#" class="link" style="color: #71717b; text-decoration: underline">Help</a>
+              </td>
+            </tr>
+          </table>
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>
diff --git a/e2e/supabase/config.toml b/e2e/supabase/config.toml
index bb2ae2d..8f9338a 100644
--- a/e2e/supabase/config.toml
+++ b/e2e/supabase/config.toml
@@ -123,9 +123,9 @@ file_size_limit = "50MiB"
 enabled = true
 # The base URL of your website. Used as an allow-list for redirects and for constructing URLs used
 # in emails.
-site_url = "http://127.0.0.1:3000"
+site_url = "http://localhost:5273"
 # A list of *exact* URLs that auth providers are permitted to redirect to post authentication.
-additional_redirect_urls = ["https://127.0.0.1:3000"]
+additional_redirect_urls = ["http://localhost:5273/auth/callback"]
 # How long tokens are valid for, in seconds. Defaults to 3600 (1 hour), maximum 604,800 (1 week).
 jwt_expiry = 604800
 # Path to JWT signing key. DO NOT commit your signing keys file to git.
@@ -176,7 +176,7 @@ enable_signup = true
 # addresses. If disabled, only the new email is required to confirm.
 double_confirm_changes = true
 # If enabled, users need to confirm their email address before signing in.
-enable_confirmations = false
+enable_confirmations = true
 # If enabled, users will need to reauthenticate or have logged in recently to change their password.
 secure_password_change = false
 # Controls the minimum amount of time that must pass before sending another signup confirmation or password reset email.
@@ -201,6 +201,10 @@ otp_expiry = 3600
 # subject = "You have been invited"
 # content_path = "./supabase/templates/invite.html"
 
+[auth.email.template.confirmation]
+subject = "Confirm your F1 Fantasy email"
+content_path = "./supabase/templates/confirmation.html"
+
 [auth.sms]
 # Allow/disallow new user signups via SMS to your project.
 enable_signup = false
diff --git a/e2e/supabase/templates b/e2e/supabase/templates
new file mode 120000
index 0000000..e4b0601
--- /dev/null
+++ b/e2e/supabase/templates
@@ -0,0 +1 @@
+../../api/supabase/templates
\ No newline at end of file
diff --git a/e2e/tests/_infra/config-sync.spec.ts b/e2e/tests/_infra/config-sync.spec.ts
index 8b21e1b..4018c47 100644
--- a/e2e/tests/_infra/config-sync.spec.ts
+++ b/e2e/tests/_infra/config-sync.spec.ts
@@ -8,10 +8,18 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
 const DEV_CONFIG = path.join(REPO_ROOT, 'api', 'supabase', 'config.toml');
 const E2E_CONFIG = path.join(REPO_ROOT, 'e2e', 'supabase', 'config.toml');
 
-// Fields the two stacks are intentionally allowed to differ on. Every other
-// line must match exactly so config drift fails loudly before it causes
-// silent behavioral divergence between dev and e2e.
-const IGNORED_KEY_RE = /^\s*(project_id|[a-z_]*port)\s*=/;
+// Both stacks must run the same Supabase config — if someone edits
+// api/supabase/config.toml and forgets the e2e copy, e2e tests pass
+// against config the user never sees in dev. This test diffs them and
+// fails on drift.
+//
+// The exceptions below are values that *must* differ:
+//   - project_id: distinguishes the two local stacks
+//   - *_port: e2e shifts every port by +100 (see README → Local
+//     Services Topology) to run alongside dev
+//   - site_url / additional_redirect_urls: contain the web port
+//     (5173 dev, 5273 e2e), so they shift too
+const IGNORED_KEY_RE = /^\s*(project_id|[a-z_]*port|site_url|additional_redirect_urls)\s*=/;
 
 test('api/supabase/config.toml and e2e/supabase/config.toml stay in sync', () => {
   const dev = readFileSync(DEV_CONFIG, 'utf8').split('\n');
diff --git a/web/src/components/OtpInput/OtpInput.test.tsx b/web/src/components/OtpInput/OtpInput.test.tsx
index 5478e32..d8219da 100644
--- a/web/src/components/OtpInput/OtpInput.test.tsx
+++ b/web/src/components/OtpInput/OtpInput.test.tsx
@@ -86,6 +86,47 @@ describe('OtpInput', () => {
     expect(input.selectionEnd).toBe(4);
   });
 
+  it('fires onComplete when the value is filled by typing the final digit', async () => {
+    const user = userEvent.setup();
+    const onComplete = vi.fn();
+    render(<Controlled onComplete={onComplete} />);
+    const input = screen.getByLabelText('Confirmation code');
+
+    await user.type(input, '12345');
+    expect(onComplete).not.toHaveBeenCalled();
+    await user.type(input, '6');
+    expect(onComplete).toHaveBeenCalledTimes(1);
+    expect(onComplete).toHaveBeenCalledWith('123456');
+  });
+
+  it('fires onComplete when paste fills the value', async () => {
+    const user = userEvent.setup();
+    const onComplete = vi.fn();
+    render(<Controlled onComplete={onComplete} />);
+    const input = screen.getByLabelText('Confirmation code');
+
+    input.focus();
+    await user.paste('123456');
+
+    expect(onComplete).toHaveBeenCalledTimes(1);
+    expect(onComplete).toHaveBeenCalledWith('123456');
+  });
+
+  it('advances the active slot after each typed digit', async () => {
+    const user = userEvent.setup();
+    render(<Controlled />);
+    const input = screen.getByLabelText('Confirmation code');
+    input.focus();
+
+    const slots = document.querySelectorAll('[data-slot="otp-slot"]');
+    await user.keyboard('1');
+    expect(slots[1]).toHaveAttribute('data-active', 'true');
+    await user.keyboard('2');
+    expect(slots[2]).toHaveAttribute('data-active', 'true');
+    await user.keyboard('3');
+    expect(slots[3]).toHaveAttribute('data-active', 'true');
+  });
+
   it('prevents typing when disabled', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();
diff --git a/web/src/components/OtpInput/OtpInput.tsx b/web/src/components/OtpInput/OtpInput.tsx
index c42ba79..0185dd0 100644
--- a/web/src/components/OtpInput/OtpInput.tsx
+++ b/web/src/components/OtpInput/OtpInput.tsx
@@ -4,6 +4,7 @@ import {
   type ClipboardEvent,
   type ComponentPropsWithoutRef,
   type PointerEvent,
+  type SyntheticEvent,
   useEffect,
   useRef,
   useState,
@@ -13,6 +14,7 @@ interface OtpInputProps {
   id?: string;
   value: string;
   onChange: (value: string) => void;
+  onComplete?: (value: string) => void;
   length?: number;
   disabled?: boolean;
   'aria-label'?: string;
@@ -33,6 +35,7 @@ export function OtpInput({
   id,
   value,
   onChange,
+  onComplete,
   length = 6,
   disabled = false,
   'aria-label': ariaLabel,
@@ -45,8 +48,8 @@ export function OtpInput({
   const [selectionStart, setSelectionStart] = useState<number | null>(null);
   const [isFocused, setIsFocused] = useState(false);
 
-  // `selectionchange` is the only DOM event that fires for every selection
-  // mutation, including programmatic setSelectionRange that `onSelect` misses.
+  // `selectionchange` catches cursor moves that don't go through `onChange`
+  // (arrow keys, click-to-position) and that `onSelect` misses on Safari.
   useEffect(() => {
     if (!isFocused) return;
     const handler = () => {
@@ -60,8 +63,47 @@ export function OtpInput({
   }, [isFocused]);
 
   const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
-    const sanitized = e.target.value.replace(/\D/g, '').slice(0, length);
+    const target = e.target;
+    const sanitized = target.value.replace(/\D/g, '').slice(0, length);
+    const cursor = Math.min(target.selectionStart ?? sanitized.length, sanitized.length);
+    setSelectionStart(cursor);
     onChange(sanitized);
+    if (sanitized.length === length && cursor === length) {
+      onComplete?.(sanitized);
+    }
+  };
+
+  // Own typing in a full code: default leaves the cursor collapsed between
+  // digits (next keystroke blocks on maxLength), and same-digit replacements
+  // skip React's onChange (valueTracker bails). Splice + re-select next slot.
+  const handleBeforeInput = (e: SyntheticEvent<HTMLInputElement>) => {
+    const native = e.nativeEvent as InputEvent;
+    if (!native.data) return;
+    const digit = native.data.replace(/\D/g, '');
+    if (digit.length !== 1) return;
+    if (value.length !== length) return;
+    const target = e.currentTarget;
+    const start = target.selectionStart;
+    if (start === null || start >= length) return;
+
+    e.preventDefault();
+    const next = start + 1;
+    const newValue = value.slice(0, start) + digit + value.slice(start + 1);
+    setSelectionStart(next);
+    onChange(newValue);
+    if (next === length) {
+      onComplete?.(newValue);
+    }
+
+    requestAnimationFrame(() => {
+      const input = inputRef.current;
+      if (!input || document.activeElement !== input) return;
+      if (next < length) {
+        input.setSelectionRange(next, next + 1);
+      } else {
+        input.setSelectionRange(next, next);
+      }
+    });
   };
 
   // Intercept paste so the input's maxLength can't truncate mixed-character
@@ -70,7 +112,11 @@ export function OtpInput({
     e.preventDefault();
     const text = e.clipboardData.getData('text');
     const sanitized = text.replace(/\D/g, '').slice(0, length);
+    setSelectionStart(sanitized.length);
     onChange(sanitized);
+    if (sanitized.length === length) {
+      onComplete?.(sanitized);
+    }
   };
 
   const handleSlotPointerDown = (e: PointerEvent<HTMLDivElement>, index: number) => {
@@ -114,17 +160,18 @@ export function OtpInput({
         maxLength={length}
         value={value}
         onChange={handleChange}
+        onBeforeInput={handleBeforeInput}
         onPaste={handlePaste}
         onFocus={() => setIsFocused(true)}
         onBlur={() => setIsFocused(false)}
         disabled={disabled}
         aria-label={ariaLabel}
-        className="col-start-1 row-start-1 h-full w-full border-none bg-transparent text-transparent caret-transparent outline-none"
+        className="col-start-1 row-start-1 h-full w-full border-none bg-transparent text-transparent caret-transparent outline-none selection:bg-transparent selection:text-transparent"
       />
       <div
         aria-hidden="true"
         className={cn(
-          'z-10 col-start-1 row-start-1 flex justify-center gap-2.5',
+          'z-10 col-start-1 row-start-1 flex justify-center gap-1.5 sm:gap-2.5',
           disabled && 'pointer-events-none opacity-50',
         )}
       >
@@ -138,7 +185,7 @@ export function OtpInput({
               data-active={isActive ? 'true' : undefined}
               onPointerDown={(e) => handleSlotPointerDown(e, i)}
               className={cn(
-                'relative flex h-14 w-12 items-center justify-center rounded-md border font-mono text-2xl font-medium tabular-nums',
+                'relative flex h-12 w-10 items-center justify-center rounded-md border font-mono text-2xl font-medium tabular-nums sm:h-14 sm:w-12',
                 isActive && 'border-primary ring-primary/40 ring-2 ring-inset',
                 slotClassName,
               )}
diff --git a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
index ce87581..de164f1 100644
--- a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
+++ b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
@@ -73,6 +73,7 @@ describe('CheckEmailNotice', () => {
     const alert = await screen.findByRole('alert');
     expect(alert).toHaveTextContent(/that code didn't match/i);
     expect(props.onVerified).not.toHaveBeenCalled();
+    expect(screen.getByLabelText(/confirmation code/i)).toHaveValue('123456');
   });
 
   it('keeps the Verify button disabled and verifyOtp uncalled until 6 digits land', async () => {
diff --git a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
index 67e3b6c..29d9e7a 100644
--- a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
+++ b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
@@ -42,11 +42,8 @@ export function CheckEmailNotice({ email, onVerified }: Props) {
     }
   };
 
-  const handleCodeChange = (value: string) => {
-    setCode(value);
-    if (value.length === OTP_LENGTH && status === 'idle') {
-      verify(value);
-    }
+  const handleComplete = (value: string) => {
+    if (status === 'idle') verify(value);
   };
 
   return (
@@ -100,7 +97,8 @@ export function CheckEmailNotice({ email, onVerified }: Props) {
             id="confirmation-code"
             length={OTP_LENGTH}
             value={code}
-            onChange={handleCodeChange}
+            onChange={setCode}
+            onComplete={handleComplete}
             disabled={status === 'verifying' || status === 'success'}
             className="w-full"
           />
diff --git a/web/src/components/auth/SignUpForm/SignUpForm.test.tsx b/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
index 2cb9c48..34212ce 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
@@ -1,9 +1,17 @@
 import type { AuthContextType } from '@/contexts/AuthContext';
+import type { Session } from '@supabase/supabase-js';
 import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { SignUpForm } from './SignUpForm';
 
+const mockSession = {
+  access_token: 'mock-access-token',
+  refresh_token: 'mock-refresh-token',
+  expires_in: 3600,
+  token_type: 'bearer',
+} as unknown as Session;
+
 // Mock useAuth and useNavigate
 vi.mock('@/hooks/useAuth', async () => {
   return {
@@ -115,7 +123,8 @@ describe('SignUpForm', () => {
   });
 
   it('disables submit button while loading', async () => {
-    mockSignUp.mockImplementation(() => new Promise((resolve) => setTimeout(resolve, 100)));
+    // Pending forever so the post-submit branch can't race the next test.
+    mockSignUp.mockImplementation(() => new Promise(() => {}));
     setup();
     fireEvent.change(screen.getByLabelText(/display name/i), { target: { value: 'Test User' } });
     fireEvent.change(screen.getByLabelText(/email/i), { target: { value: 'test@example.com' } });
@@ -132,7 +141,7 @@ describe('SignUpForm', () => {
   });
 
   it('navigates to redirect path when redirect search parameter is provided', async () => {
-    mockSignUp.mockResolvedValueOnce(undefined);
+    mockSignUp.mockResolvedValueOnce({ session: mockSession });
     mockUseSearch.mockReturnValue({ redirect: '/leagues' });
     setup();
     fireEvent.change(screen.getByLabelText(/display name/i), { target: { value: 'Test User' } });
@@ -147,4 +156,38 @@ describe('SignUpForm', () => {
       expect(mockNavigate).toHaveBeenCalledWith({ to: '/leagues' });
     });
   });
+
+  it('renders the check-email pending UI when signUp returns no session', async () => {
+    mockSignUp.mockResolvedValueOnce({ session: null });
+    setup();
+    fireEvent.change(screen.getByLabelText(/display name/i), { target: { value: 'Test User' } });
+    fireEvent.change(screen.getByLabelText(/email/i), {
+      target: { value: 'pending@example.com' },
+    });
+    fireEvent.change(screen.getByLabelText(/^password$/i), { target: { value: 'password123' } });
+    fireEvent.change(screen.getByLabelText(/confirm password/i), {
+      target: { value: 'password123' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /sign up/i }));
+
+    expect(await screen.findByRole('heading', { name: /check your email/i })).toBeInTheDocument();
+    expect(screen.getByText('pending@example.com')).toBeInTheDocument();
+    expect(mockNavigate).not.toHaveBeenCalled();
+  });
+
+  it('navigates to default destination when signUp returns a session (auto-confirm)', async () => {
+    mockSignUp.mockResolvedValueOnce({ session: mockSession });
+    setup();
+    fireEvent.change(screen.getByLabelText(/display name/i), { target: { value: 'Test User' } });
+    fireEvent.change(screen.getByLabelText(/email/i), { target: { value: 'test@example.com' } });
+    fireEvent.change(screen.getByLabelText(/^password$/i), { target: { value: 'password123' } });
+    fireEvent.change(screen.getByLabelText(/confirm password/i), {
+      target: { value: 'password123' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /sign up/i }));
+
+    await waitFor(() => {
+      expect(mockNavigate).toHaveBeenCalledWith({ to: '/create-team' });
+    });
+  });
 });
diff --git a/web/src/components/auth/SignUpForm/SignUpForm.tsx b/web/src/components/auth/SignUpForm/SignUpForm.tsx
index ecefec6..bd7c247 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.tsx
@@ -1,12 +1,14 @@
 import { InlineError } from '@/components/InlineError/InlineError';
 import { LiveRegion } from '@/components/LiveRegion/LiveRegion';
 import { LoadingButton } from '@/components/LoadingButton/LoadingButton';
+import { CheckEmailNotice } from '@/components/auth/CheckEmailNotice/CheckEmailNotice';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { useAuth } from '@/hooks/useAuth';
 import { useLiveRegion } from '@/hooks/useLiveRegion';
+import { getPostSignupDestination } from '@/lib/auth-destination';
 import { Link, useNavigate, useSearch } from '@tanstack/react-router';
 import { type FormEvent, useState } from 'react';
 
@@ -17,10 +19,17 @@ export function SignUpForm() {
   const [confirmPassword, setConfirmPassword] = useState('');
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [awaitingConfirmation, setAwaitingConfirmation] = useState(false);
   const { signUp, startAuthTransition, completeAuthTransition } = useAuth();
   const navigate = useNavigate();
   const search = useSearch({ from: '/sign-up' });
 
+  const completeSignUp = async () => {
+    startAuthTransition();
+    await navigate({ to: getPostSignupDestination(search.redirect) });
+    completeAuthTransition();
+  };
+
   const { message, announce } = useLiveRegion();
 
   const handleSubmit = async (e: FormEvent) => {
@@ -62,15 +71,19 @@ export function SignUpForm() {
     }
 
     try {
-      await signUp(email, password, { displayName });
-      startAuthTransition();
-
-      if (search.redirect) {
-        await navigate({ to: search.redirect });
-      } else {
-        await navigate({ to: '/create-team' });
+      const { session } = await signUp(
+        email,
+        password,
+        { displayName },
+        { redirect: search.redirect },
+      );
+
+      if (!session) {
+        setAwaitingConfirmation(true);
+        return;
       }
-      completeAuthTransition();
+
+      await completeSignUp();
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Sign up failed';
       setError(errorMessage);
@@ -81,79 +94,83 @@ export function SignUpForm() {
   };
 
   return (
-    <div className="flex w-full items-center justify-center p-8 md:min-h-screen">
+    <div className="flex w-full items-center justify-center p-4 sm:p-8 md:min-h-screen">
       <div className="w-full max-w-md space-y-4">
-        <Card className="w-full max-w-md">
-          <CardHeader>
-            <CardTitle>Create Account</CardTitle>
-            <CardDescription>Join the F1 fantasy league</CardDescription>
-          </CardHeader>
-          <CardContent>
-            <form onSubmit={handleSubmit} className="space-y-4" noValidate>
-              <LiveRegion message={message} />
-              {error && <InlineError message={error} />}
-
-              <div className="space-y-2">
-                <Label htmlFor="display-name">Display Name</Label>
-                <Input
-                  id="display-name"
-                  type="text"
-                  value={displayName}
-                  onChange={(e) => setDisplayName(e.target.value)}
-                  required
-                  autoComplete="name"
-                />
-              </div>
-
-              <div className="space-y-2">
-                <Label htmlFor="signup-email">Email</Label>
-                <Input
-                  id="signup-email"
-                  type="email"
-                  value={email}
-                  onChange={(e) => setEmail(e.target.value)}
-                  required
-                  autoComplete="email"
-                />
-              </div>
-
-              <div className="space-y-2">
-                <Label htmlFor="signup-password">Password</Label>
-                <Input
-                  id="signup-password"
-                  type="password"
-                  value={password}
-                  onChange={(e) => setPassword(e.target.value)}
-                  required
-                  minLength={6}
-                  autoComplete="new-password"
-                />
-              </div>
-
-              <div className="space-y-2">
-                <Label htmlFor="confirm-password">Confirm Password</Label>
-                <Input
-                  id="confirm-password"
-                  type="password"
-                  value={confirmPassword}
-                  onChange={(e) => setConfirmPassword(e.target.value)}
-                  required
-                  minLength={6}
-                  autoComplete="new-password"
-                />
-              </div>
-
-              <LoadingButton
-                type="submit"
-                className="w-full"
-                isLoading={isLoading}
-                loadingText="Creating account..."
-              >
-                Sign Up
-              </LoadingButton>
-            </form>
-          </CardContent>
-        </Card>
+        {awaitingConfirmation ? (
+          <CheckEmailNotice email={email} onVerified={completeSignUp} />
+        ) : (
+          <Card className="w-full max-w-md">
+            <CardHeader>
+              <CardTitle>Create Account</CardTitle>
+              <CardDescription>Join the F1 fantasy league</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <form onSubmit={handleSubmit} className="space-y-4" noValidate>
+                <LiveRegion message={message} />
+                {error && <InlineError message={error} />}
+
+                <div className="space-y-2">
+                  <Label htmlFor="display-name">Display Name</Label>
+                  <Input
+                    id="display-name"
+                    type="text"
+                    value={displayName}
+                    onChange={(e) => setDisplayName(e.target.value)}
+                    required
+                    autoComplete="name"
+                  />
+                </div>
+
+                <div className="space-y-2">
+                  <Label htmlFor="signup-email">Email</Label>
+                  <Input
+                    id="signup-email"
+                    type="email"
+                    value={email}
+                    onChange={(e) => setEmail(e.target.value)}
+                    required
+                    autoComplete="email"
+                  />
+                </div>
+
+                <div className="space-y-2">
+                  <Label htmlFor="signup-password">Password</Label>
+                  <Input
+                    id="signup-password"
+                    type="password"
+                    value={password}
+                    onChange={(e) => setPassword(e.target.value)}
+                    required
+                    minLength={6}
+                    autoComplete="new-password"
+                  />
+                </div>
+
+                <div className="space-y-2">
+                  <Label htmlFor="confirm-password">Confirm Password</Label>
+                  <Input
+                    id="confirm-password"
+                    type="password"
+                    value={confirmPassword}
+                    onChange={(e) => setConfirmPassword(e.target.value)}
+                    required
+                    minLength={6}
+                    autoComplete="new-password"
+                  />
+                </div>
+
+                <LoadingButton
+                  type="submit"
+                  className="w-full"
+                  isLoading={isLoading}
+                  loadingText="Creating account..."
+                >
+                  Sign Up
+                </LoadingButton>
+              </form>
+            </CardContent>
+          </Card>
+        )}
 
         <div className="text-center">
           <Button variant="link" asChild className="text-sm">
diff --git a/web/src/contexts/AuthContext.test.tsx b/web/src/contexts/AuthContext.test.tsx
index 20d37d8..107acc9 100644
--- a/web/src/contexts/AuthContext.test.tsx
+++ b/web/src/contexts/AuthContext.test.tsx
@@ -29,7 +29,7 @@ vi.mock('../services/userProfileService', () => ({
 }));
 
 // Test component that consumes the auth context
-function TestComponent() {
+function TestComponent({ signUpOptions }: { signUpOptions?: { redirect?: string } } = {}) {
   const { user, session, loading, signIn, signUp, signOut } = useAuth();
 
   const handleSignIn = async () => {
@@ -42,7 +42,7 @@ function TestComponent() {
 
   const handleSignUp = async () => {
     try {
-      await signUp('test@example.com', 'password', { displayName: 'Test User' });
+      await signUp('test@example.com', 'password', { displayName: 'Test User' }, signUpOptions);
     } catch {
       // Errors are expected in some tests, silently handle them
     }
@@ -253,10 +253,34 @@ describe('AuthProvider', () => {
           data: {
             displayName: 'Test User',
           },
+          emailRedirectTo: `${window.location.origin}/auth/callback`,
         },
       });
     });
 
+    it('should forward the redirect option into emailRedirectTo', async () => {
+      vi.mocked(supabase.auth.signUp).mockResolvedValue({
+        data: { user: mockUser, session: mockSession },
+        error: null,
+      });
+
+      render(
+        <AuthProvider>
+          <TestComponent signUpOptions={{ redirect: '/leagues/123' }} />
+        </AuthProvider>,
+      );
+
+      await userEvent.click(screen.getByTestId('sign-up-btn'));
+
+      expect(supabase.auth.signUp).toHaveBeenCalledWith(
+        expect.objectContaining({
+          options: expect.objectContaining({
+            emailRedirectTo: `${window.location.origin}/auth/callback?redirect=${encodeURIComponent('/leagues/123')}`,
+          }),
+        }),
+      );
+    });
+
     it('should handle signUp error', async () => {
       const signUpError = new Error('Email already exists') as AuthError;
       vi.mocked(supabase.auth.signUp).mockResolvedValue({
@@ -281,6 +305,7 @@ describe('AuthProvider', () => {
           data: {
             displayName: 'Test User',
           },
+          emailRedirectTo: `${window.location.origin}/auth/callback`,
         },
       });
     });
diff --git a/web/src/contexts/AuthContext.ts b/web/src/contexts/AuthContext.ts
index 1256737..e268bb9 100644
--- a/web/src/contexts/AuthContext.ts
+++ b/web/src/contexts/AuthContext.ts
@@ -8,7 +8,12 @@ export interface AuthContextType {
   loading: boolean;
   isAuthTransitioning: boolean;
   signIn: (email: string, password: string) => Promise<void>;
-  signUp: (email: string, password: string, additionalData: CreateProfileData) => Promise<void>;
+  signUp: (
+    email: string,
+    password: string,
+    additionalData: CreateProfileData,
+    options?: { redirect?: string },
+  ) => Promise<{ session: Session | null }>;
   signOut: () => Promise<void>;
   startAuthTransition: () => void;
   completeAuthTransition: () => void;
diff --git a/web/src/contexts/AuthContext.tsx b/web/src/contexts/AuthContext.tsx
index 7abd4ac..6c13c72 100644
--- a/web/src/contexts/AuthContext.tsx
+++ b/web/src/contexts/AuthContext.tsx
@@ -39,22 +39,33 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     if (error) throw error;
   };
 
-  const signUp = async (email: string, password: string, additionalData: CreateProfileData) => {
+  const signUp = async (
+    email: string,
+    password: string,
+    additionalData: CreateProfileData,
+    options?: { redirect?: string },
+  ) => {
     if (!additionalData.displayName?.trim()) {
       throw new Error('Display name is required');
     }
 
-    const { error } = await supabase.auth.signUp({
+    const emailRedirectTo = options?.redirect
+      ? `${window.location.origin}/auth/callback?redirect=${encodeURIComponent(options.redirect)}`
+      : `${window.location.origin}/auth/callback`;
+
+    const { data, error } = await supabase.auth.signUp({
       email,
       password,
       options: {
         data: {
           displayName: additionalData.displayName,
         },
+        emailRedirectTo,
       },
     });
 
     if (error) throw error;
+    return { session: data.session };
   };
 
   const signOut = async () => {
diff --git a/web/src/lib/route-guards.test.ts b/web/src/lib/route-guards.test.ts
index 919526e..0af4387 100644
--- a/web/src/lib/route-guards.test.ts
+++ b/web/src/lib/route-guards.test.ts
@@ -1,5 +1,6 @@
 import { requireAuth, requireNoTeam, requireTeam } from '@/lib/route-guards';
 import type { RouterContext } from '@/lib/router-context';
+import { supabase } from '@/lib/supabase';
 import { getMyTeam } from '@/services/teamService';
 import type { Session, User } from '@supabase/supabase-js';
 import { redirect } from '@tanstack/react-router';
@@ -23,6 +24,16 @@ vi.mock('@/services/teamService', () => ({
   getMyTeam: vi.fn(),
 }));
 
+// Mock Supabase — requireAuth falls back to getSession() when context.auth.user
+// is null to handle the lag between exchangeCodeForSession and React state.
+vi.mock('@/lib/supabase', () => ({
+  supabase: {
+    auth: {
+      getSession: vi.fn(),
+    },
+  },
+}));
+
 // Helper to create a mock user
 const createMockUser = (): User => ({
   id: '123',
@@ -46,6 +57,10 @@ const createMockSession = (): Session => ({
 describe('route-guards', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    vi.mocked(supabase.auth.getSession).mockResolvedValue({
+      data: { session: null },
+      error: null,
+    } as Awaited<ReturnType<typeof supabase.auth.getSession>>);
   });
 
   describe('requireAuth', () => {
@@ -107,7 +122,17 @@ describe('route-guards', () => {
       await expect(requireAuth(context)).resolves.not.toThrow();
     });
 
-    it('redirects to landing page with replace option', async () => {
+    it('does not throw when context lags but Supabase has a session', async () => {
+      // Simulates the moment right after the email-confirmation callback
+      // signs the user in: Supabase has persisted the session (so
+      // getSession() returns it), but AuthContext hasn't re-rendered yet,
+      // so context.auth.user is still null. The guard should fall back to
+      // getSession() and let the navigation through instead of redirecting.
+      vi.mocked(supabase.auth.getSession).mockResolvedValue({
+        data: { session: createMockSession() },
+        error: null,
+      } as Awaited<ReturnType<typeof supabase.auth.getSession>>);
+
       const context: RouterContext = {
         auth: {
           user: null,
@@ -131,14 +156,8 @@ describe('route-guards', () => {
         currentSeason: null,
       };
 
-      try {
-        await requireAuth(context);
-      } catch (error) {
-        expect((error as Error & { redirect: unknown }).redirect).toEqual({
-          to: '/',
-          replace: true,
-        });
-      }
+      await expect(requireAuth(context)).resolves.not.toThrow();
+      expect(redirect).not.toHaveBeenCalled();
     });
   });
 
@@ -211,7 +230,7 @@ describe('route-guards', () => {
       await expect(requireTeam(context)).resolves.not.toThrow();
     });
 
-    it('does not throw when user is not authenticated', async () => {
+    it('delegates to requireAuth when user is not authenticated', async () => {
       const context: RouterContext = {
         auth: {
           user: null,
@@ -235,44 +254,8 @@ describe('route-guards', () => {
         currentSeason: null,
       };
 
-      // Should throw redirect because requireAuth is called first and user is not authenticated
       await expect(() => requireTeam(context)).rejects.toThrow();
     });
-
-    it('redirects to create-team page with replace option', async () => {
-      vi.mocked(getMyTeam).mockResolvedValue(null);
-      const context: RouterContext = {
-        auth: {
-          user: createMockUser(),
-          session: createMockSession(),
-          loading: false,
-          isAuthTransitioning: false,
-          signIn: vi.fn(),
-          signUp: vi.fn(),
-          signOut: vi.fn(),
-          startAuthTransition: vi.fn(),
-          completeAuthTransition: vi.fn(),
-        },
-        teamContext: {
-          myTeamId: null,
-          hasTeam: false,
-          setMyTeamId: vi.fn(),
-          refreshMyTeam: vi.fn(),
-        },
-        team: null,
-        profile: null,
-        currentSeason: null,
-      };
-
-      try {
-        await requireTeam(context);
-      } catch (error) {
-        expect((error as Error & { redirect: unknown }).redirect).toEqual({
-          to: '/create-team',
-          replace: true,
-        });
-      }
-    });
   });
 
   describe('requireNoTeam', () => {
@@ -344,7 +327,7 @@ describe('route-guards', () => {
       await expect(requireNoTeam(context)).resolves.not.toThrow();
     });
 
-    it('does not throw when user is not authenticated', async () => {
+    it('delegates to requireAuth when user is not authenticated', async () => {
       const context: RouterContext = {
         auth: {
           user: null,
@@ -368,51 +351,7 @@ describe('route-guards', () => {
         currentSeason: null,
       };
 
-      // Should throw redirect because requireAuth is called first and user is not authenticated
       await expect(() => requireNoTeam(context)).rejects.toThrow();
     });
-
-    it('redirects to leagues page with replace option', async () => {
-      vi.mocked(getMyTeam).mockResolvedValue({
-        id: 1,
-        name: 'Test Team',
-        ownerId: 1,
-        ownerName: 'Test Owner',
-        remainingBudget: 100_000_000,
-        drivers: [],
-        constructors: [],
-      });
-      const context: RouterContext = {
-        auth: {
-          user: createMockUser(),
-          session: createMockSession(),
-          loading: false,
-          isAuthTransitioning: false,
-          signIn: vi.fn(),
-          signUp: vi.fn(),
-          signOut: vi.fn(),
-          startAuthTransition: vi.fn(),
-          completeAuthTransition: vi.fn(),
-        },
-        teamContext: {
-          myTeamId: 1,
-          hasTeam: true,
-          setMyTeamId: vi.fn(),
-          refreshMyTeam: vi.fn(),
-        },
-        team: null,
-        profile: null,
-        currentSeason: null,
-      };
-
-      try {
-        await requireNoTeam(context);
-      } catch (error) {
-        expect((error as Error & { redirect: unknown }).redirect).toEqual({
-          to: '/leagues',
-          replace: true,
-        });
-      }
-    });
   });
 });
diff --git a/web/src/lib/route-guards.ts b/web/src/lib/route-guards.ts
index 5a1dd09..4cb96e2 100644
--- a/web/src/lib/route-guards.ts
+++ b/web/src/lib/route-guards.ts
@@ -1,5 +1,6 @@
 import type { Team } from '@/contracts/Team';
 import type { RouterContext } from '@/lib/router-context';
+import { supabase } from '@/lib/supabase';
 import { getMyTeam } from '@/services/teamService';
 import { redirect } from '@tanstack/react-router';
 
@@ -30,13 +31,19 @@ import { redirect } from '@tanstack/react-router';
  * @see {@link https://tanstack.com/router/latest/docs/framework/react/guide/authenticated-routes | TanStack Router Authentication Guide}
  */
 export async function requireAuth(context: RouterContext): Promise<void> {
-  // Throw redirect if user is not authenticated
-  if (!context.auth.user) {
-    throw redirect({
-      to: '/',
-      replace: true,
-    });
-  }
+  if (context.auth.user) return;
+
+  // context.auth.user is a React-state snapshot; it lags Supabase right after
+  // a session is established. Check getSession() before redirecting.
+  const {
+    data: { session },
+  } = await supabase.auth.getSession();
+  if (session?.user) return;
+
+  throw redirect({
+    to: '/',
+    replace: true,
+  });
 }
 
 /**
diff --git a/web/src/lib/supabase.test.ts b/web/src/lib/supabase.test.ts
index 3a2a51f..114d0be 100644
--- a/web/src/lib/supabase.test.ts
+++ b/web/src/lib/supabase.test.ts
@@ -80,6 +80,7 @@ describe('supabase module initialization', () => {
     expect(createClient).toHaveBeenCalledWith('https://myproject.supabase.co', 'my-anon-key', {
       auth: {
         flowType: 'pkce',
+        detectSessionInUrl: false,
       },
     });
   });
diff --git a/web/src/lib/supabase.ts b/web/src/lib/supabase.ts
index 23b6b80..3b5b27f 100644
--- a/web/src/lib/supabase.ts
+++ b/web/src/lib/supabase.ts
@@ -14,5 +14,7 @@ if (!supabaseAnonKey) {
 export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
   auth: {
     flowType: 'pkce',
+    // Route loaders own URL code exchange; auto-detect would race them.
+    detectSessionInUrl: false,
   },
 });

From 69351bee5b32a667e0cd6070e257ec0dca45b13f Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Wed, 13 May 2026 00:19:36 -0500
Subject: [PATCH 11/25] docs(plans): sync #164 plan with what commit 3 actually
 shipped

Adds the detectSessionInUrl flag to commit 1's PKCE description, the
OtpInput onComplete + onBeforeInput design to commit 2, and the
route-guards / config-sync / symlink details to commit 3. Adds
decision rows for the requireAuth getSession fallback and the
onComplete callback. Updates the critical-files list to cover the
new touch points.
---
 docs/plans/164-email-confirmation-signup.md | 55 ++++++++++++++-------
 1 file changed, 37 insertions(+), 18 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index a763cc2..d66b647 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -24,7 +24,9 @@ Email confirmations are currently disabled in Supabase (`enable_confirmations =
 | OTP input component                         | Custom `<OtpInput>` at `web/src/components/OtpInput/`                                                                                                                                                                                   | Hand-rolled single-input + overlay slot pattern (same architecture as `input-otp`) that fixes the slot-retargeting bug ([shadcn/ui #4046](https://github.com/shadcn-ui/ui/issues/4046)) where clicking a non-final slot focuses the last cell. Preserves every must-have: single accessible `<input>` for WCAG 1.3.5, iOS/Android SMS autofill via `autocomplete="one-time-code"`, native paste, full keyboard a11y, auto-submit. Lives outside `ui/` because `ui/` is reserved for vendored shadcn; sits next to the other custom primitives (`LoadingButton`, `InlineError`). Removes the `input-otp` dependency. |
 | Pending-UI surface                          | Inline state + shared `<CheckEmailNotice>` component                                                                                                                                                                                    | No URL params (OWASP: PII like email shouldn't appear in URLs — leaks via browser history, server logs, Referer to Sentry). Refresh degrades benignly: link in inbox still works, resend reachable via signin path.                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `<CheckEmailNotice>` shape                  | **Card-only component, not a full-page screen** — returns the `<Card>` directly; page chrome (centering, full-viewport height, background) is the caller's responsibility                                                               | The caller already provides a page wrapper (`SignUpForm`'s and `SignInForm`'s outer `flex w-full ... justify-center ... md:min-h-screen` div). A second wrapper inside `<CheckEmailNotice>` would double-wrap and made the Card's `w-full max-w-lg` resolve against a content-sized parent, which let the `<InlineError>`'s width feed back into the Card width. Card-only avoids both issues; commits 3 and 6 swap `<CheckEmailNotice>` in place of the existing `<Card>` inside the parent's wrapper.                                                                                                             |
-| Auto-submit vs. manual submit               | **Auto-submit on 6th digit AND a manual Verify button**, no `<form>` wrapper. Button is `type="button"` with `onClick`. No Enter-to-submit                                                                                              | Auto-submit covers every typed/pasted happy path (`onPaste` in `<OtpInput>` also fires `onChange`). The Verify button serves as the loading-state visual, the success-state visual ("Verified" + check), and the explicit retry affordance after a failure. The `<form>` was vestigial after we dropped HTML-form-validation; its only remaining job was Enter-to-submit, which would only ever re-fire the same already-failed code — a weak use case for OTP.                                                                                                                                                     |
+| Auto-submit vs. manual submit               | **Auto-submit on 6th digit AND a manual Verify button**, no `<form>` wrapper. Button is `type="button"` with `onClick`. No Enter-to-submit                                                                                              | Auto-submit covers every typed/pasted/retyped happy path via `<OtpInput>`'s dedicated `onComplete` callback (fires from `onChange`, `onPaste`, and `onBeforeInput`'s same-digit splice). The Verify button serves as the loading-state visual, the success-state visual ("Verified" + check), and the explicit retry affordance after a failure. The `<form>` was vestigial after we dropped HTML-form-validation; its only remaining job was Enter-to-submit, which would only ever re-fire the same already-failed code — a weak use case for OTP. |
+| `<OtpInput>` completion signal              | Dedicated `onComplete(value)` callback, not `onChange + value.length === length` inspection at the callsite                                                                                                                             | Same-digit replacements in a full code (e.g., user retypes a wrong digit over the same position) bypass React's `onChange` because the SyntheticEvent value tracker bails when the input's value didn't change. A dedicated callback wired into the primitive's `onChange` / `onPaste` / `onBeforeInput` paths means the callsite gets a single reliable "done" signal regardless of typing pattern, and the same-digit case still fires verification.                                                                                              |
+| `requireAuth` route guard                   | Falls back to `supabase.auth.getSession()` when `context.auth.user` is null before redirecting                                                                                                                                          | After the auth-callback loader calls `exchangeCodeForSession`, Supabase persists the session synchronously but AuthContext's React state only catches up on the next render. A redirect-target route's `beforeLoad` runs before that re-render, so `context.auth.user` is briefly null even though the user is signed in. Without the fallback, the user bounces back to `/` immediately after the loader redirects them. The fallback consults Supabase directly and lets the navigation through; both code paths flow into the same logged-in state. |
 | Verify button shape                         | Centered, `size="lg" min-w-48`, not full-width                                                                                                                                                                                          | Centered slots above + centered button below reads visually balanced. Full-width would deviate less from `SignUpForm`/`SignInForm` but visually anchors the manual button more heavily than is warranted given auto-submit is the primary path. `min-w-48` keeps the tap target generous on mobile.                                                                                                                                                                                                                                                                                                                 |
 | Failure copy                                | Static generic message _"That code didn't match. Check your email for the latest one."_ — not the raw Supabase error string                                                                                                             | Supabase emits jargon ("Token has expired or is invalid"). Users typed a "code", not a "token", and the canonical follow-up is to enter a new code from the latest email. Also: `verify()` no longer optimistically clears the error at function entry (only on success), so re-attempts don't unmount/remount the `<InlineError>` and trigger a layout shift mid-flight.                                                                                                                                                                                                                                           |
 | Error placement inside `<CheckEmailNotice>` | `<InlineError>` sits _under_ the slot row, inside the same `space-y-3` group, replacing the idle-state status hint when present                                                                                                         | Keeps the eye path slots → error → button continuous. Originally placed above the slots; that path made the user snap up to the top, then back down to retype.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
@@ -51,7 +53,9 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 **Supabase client flow change** (`web/src/lib/supabase.ts`):
 
 - Today: `createClient(url, key)` with no options → defaults to `flowType: 'implicit'` (verified in `auth-js` source — `DEFAULT_OPTIONS.flowType: 'implicit'`)
-- Required: pass `{ auth: { flowType: 'pkce' } }` so the magic link returns `?code=` (which `exchangeCodeForSession` consumes) instead of `#access_token=` (implicit hash flow)
+- Required: pass `{ auth: { flowType: 'pkce', detectSessionInUrl: false } }`:
+  - `flowType: 'pkce'` so the magic link returns `?code=` (which `exchangeCodeForSession` consumes) instead of `#access_token=` (implicit hash flow)
+  - `detectSessionInUrl: false` so the SDK's default URL-watcher doesn't race the auth-callback loader for the `?code=` param. The loader owns the exchange; auto-detection would double-fire and the second call would 400 on the already-consumed code.
 - This is a small but app-wide auth behavior change — covered by existing AuthContext tests
 
 **New helper** (`web/src/lib/auth-destination.ts`):
@@ -102,6 +106,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - **Props:**
   - `id?: string` — forwarded to the underlying `<input>` so external `<Label htmlFor>` works
   - `value: string`, `onChange: (value: string) => void`
+  - `onComplete?: (value: string) => void` — fires the first time `value` reaches `length` after any input path: `onChange` digit-fill, `onPaste`, or the `onBeforeInput` same-digit-replace path described below. Callers use this as the auto-submit signal.
   - `length?: number` (default `6`) — also forwarded as `maxLength`
   - `disabled?: boolean`
   - `'aria-label'?: string`
@@ -111,12 +116,13 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
   - `slotClassName?: string` — merged onto each slot for per-slot style overrides
   - Each visible slot carries `data-slot="otp-slot"` as a styling/structure marker (mirrors the shadcn convention). Not a public test hook except for the one click-retargeting test that the bug it guards is structural-positional.
 - **Behavior:**
-  - `onChange` strips non-digit characters and slices to `length`.
+  - `onChange` strips non-digit characters and slices to `length`. Tracks the post-change caret in `selectionStart` state so active-slot styling reacts to typing without waiting for the next `selectionchange` event.
   - **Paste interceptor (`onPaste`):** intercepts paste events, `preventDefault`s the browser default, sanitizes `clipboardData.getData('text')`, and calls `onChange` with the sliced result. Necessary because `maxLength` on the underlying input would otherwise truncate a mixed-character paste (e.g., `"abc123456xyz"`) to its first 6 characters (`"abc123"`) _before_ our digit filter can run. With the interceptor, paste yields `onChange("123456")` in a single call.
+  - **Same-digit replacement (`onBeforeInput`):** when the input is already at `length` and the user types a digit, React's value tracker skips `onChange` if the resulting character is identical to the one being replaced (e.g., position 3 holds `5` and the user types `5` again). The handler intercepts `beforeinput`, `preventDefault`s the browser, splices the new digit into `value` at `selectionStart`, advances the caret by one, and re-selects the next slot via `requestAnimationFrame` + `setSelectionRange(next, next+1)`. Also fires `onComplete` when this path lands on the final slot.
   - **Click-to-edit any slot (the bug fix):** on slot `onPointerDown`, `preventDefault`, `focus()` the input, then `setSelectionRange(i, i+1)` if the slot has a character, else collapse the caret at `min(i, value.length)`. Safari requires `focus()` before `setSelectionRange`.
-  - **Active slot tracking:** uses a `document`-level `selectionchange` listener (gated on `isFocused`) — the only DOM event that fires for _every_ selection mutation, including programmatic `setSelectionRange`. `onSelect` would miss the click-retarget case. The listener updates a `selectionStart` state, and `activeIndex` is derived from `isFocused + selectionStart + value.length`. Caret animation uses `animate-caret-blink` (from `tw-animate-css`).
+  - **Active slot tracking:** uses a `document`-level `selectionchange` listener (gated on `isFocused`) for cursor moves that don't go through `onChange` (arrow keys, click-to-position) and that `onSelect` misses on Safari. The listener updates a `selectionStart` state, and `activeIndex` is derived from `isFocused + selectionStart + value.length`. Caret animation uses `animate-caret-blink` (from `tw-animate-css`).
   - **Disabled:** propagates to the `<input>` and the slot container (`pointer-events-none opacity-50`).
-- **Styling defaults baked in:** slot `h-14 w-12 rounded-md border font-mono text-2xl font-medium tabular-nums`; active state `border-primary ring-2 ring-primary/40 ring-inset`; slot-row `flex justify-center gap-2.5`. Consumer-supplied `className` / `slotClassName` merge via `cn()` (Tailwind merge wins on conflicts).
+- **Styling defaults baked in:** slot is `h-12 w-10 sm:h-14 sm:w-12 rounded-md border font-mono text-2xl font-medium tabular-nums` (responsive so the row fits on ~320px phones); active state `border-primary ring-2 ring-primary/40 ring-inset`; slot-row `flex justify-center gap-1.5 sm:gap-2.5`. The underlying `<input>` also carries `selection:bg-transparent selection:text-transparent` so the native selection highlight doesn't leak into the visible slots when `setSelectionRange` extends across positions. Consumer-supplied `className` / `slotClassName` merge via `cn()` (Tailwind merge wins on conflicts).
 - **Accessibility:** the grid container carries no `role`; the slot-row `<div>` is `aria-hidden="true"`. Screen readers see only the single labeled `<input>`.
 
 **New flow component — `<CheckEmailNotice>`** (`web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx`):
@@ -130,17 +136,17 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - **Layout:**
   - `CardHeader`: envelope icon, "Check your email" heading, two-paragraph body (sentence 1 with the email chip; sentence 2 with "Enter it below or click the link…") wrapped in a `space-y-2` div so the two `<p>`s are visually separated.
   - `CardContent` (`space-y-4`): a `space-y-3` group containing the label + progress bar, the `<OtpInput length={6} className="w-full" />`, and (when set) `<InlineError>`. Below the group, a centered `<LoadingButton size="lg" min-w-48>` that fires `verify(code)` on click.
-- **No `<form>` wrapper.** Verify button is `type="button"` with `onClick={() => { if (status === 'idle') verify(code); }}`. Auto-submit handles every code-completion path (`onChange` reaches `OTP_LENGTH`). The `status === 'idle'` guard on the button prevents a mid-verify re-click from re-firing.
+- **No `<form>` wrapper.** Verify button is `type="button"` with `onClick={() => { if (status === 'idle') verify(code); }}`. Auto-submit handles every code-completion path via `<OtpInput>`'s `onComplete` callback — the local `handleComplete(value)` re-checks `status === 'idle'` and fires `verify(value)`. The button's `status === 'idle'` guard prevents a mid-verify re-click from re-firing.
 - **`verify(token)`:** sets status to `'verifying'`, awaits `supabase.auth.verifyOtp({ email, token, type: 'signup' })`. On success: clears `error`, sets status to `'success'`, calls `onVerified()`. On failure (rejection OR returned error): sets a static generic message _"That code didn't match. Check your email for the latest one."_ and resets status to `'idle'`. Notably, the error is _not_ optimistically cleared at function entry — so a re-attempt doesn't unmount/remount `<InlineError>` and trigger a layout shift while the new request is in flight.
 - **`Status` type:** `'idle' | 'verifying' | 'success'`. Drives the `<OtpInput disabled>`, the `<LoadingButton isLoading>`, the Card's success ring (`ring-1 ring-emerald-500/40`), and the button's "Verified" + check icon swap-in. No separate status-line component — `LoadingButton` and the Card visual state carry it.
 
 **Tests:**
 
-- `OtpInput.test.tsx` (6 behavioral tests): attribute forwarding (`inputmode` / `maxlength` / `autocomplete`); typing filters non-digits; paste yields one `onChange` call with sanitized + sliced value; backspace removes last digit; click slot 3 after full code → `selectionStart === 3` (the bug fix); `disabled` prevents typing.
+- `OtpInput.test.tsx` (9 behavioral tests): attribute forwarding (`inputmode` / `maxlength` / `autocomplete`); typing filters non-digits; paste yields one `onChange` call with sanitized + sliced value; backspace removes last digit; click slot 3 after full code → `selectionStart === 3` (the bug fix); `disabled` prevents typing; `onComplete` fires once when the 6th digit lands by typing; `onComplete` fires once when paste fills the value; active slot advances after each typed digit (verified via `data-active="true"` on the slot `<div>`).
 - `CheckEmailNotice.test.tsx` (4 behavioral tests, trimmed per the testing strategy — no static-JSX assertions, no duplication of `OtpInput`'s attribute matrix, no separate test per error code path):
   - Email prop renders in the body
   - Auto-submit fires `verifyOtp` with `{ email, token, type: 'signup' }` and `onVerified` on success
-  - Failure path renders the generic `<InlineError>` text and skips `onVerified`
+  - Failure path renders the generic `<InlineError>` text, skips `onVerified`, and leaves the typed code in the input so the user can edit a single digit instead of re-typing all six
   - Verify button stays disabled (and `verifyOtp` uncalled) until the 6th digit lands
 
 **Verification:**
@@ -160,7 +166,7 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 - `[auth] site_url` → set to local web URL (`http://localhost:5173` for dev, `http://localhost:5273` for e2e). Existing `http://127.0.0.1:3000` is dead config; nothing in the codebase references it.
 - `[auth] additional_redirect_urls` → `["http://localhost:5173/auth/callback"]` for dev (and `5273` for e2e). Existing `https://127.0.0.1:3000` is HTTPS on a non-running port — wrong on multiple counts.
 - `[auth.email] enable_confirmations = true` (currently `false` at line 176)
-- `[auth.email.template.confirmation]` block pointing at `./templates/confirmation.html`. Both configs can reference the same file via relative path; mirrors how `e2e/supabase/migrations/` is symlinked to `api/supabase/migrations/`.
+- `[auth.email.template.confirmation]` block pointing at `./templates/confirmation.html`. `e2e/supabase/templates` is a symlink to `../../api/supabase/templates` so both stacks read the same file — mirrors how `e2e/supabase/migrations/` shares the dev migrations directory.
 
 **New email template** (`api/supabase/templates/confirmation.html`):
 
@@ -171,21 +177,30 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 **Wiring:**
 
 - `web/src/contexts/AuthContext.tsx`:
-  - Update `signUp()` to pass `options: { data: { displayName }, emailRedirectTo: ${window.location.origin}/auth/callback?redirect=<encoded redirect> }`. The `redirect` is read from the current location and forwarded so deep-links survive the email gap on the magic-link path.
+  - Update `signUp()` to pass `options: { data: { displayName }, emailRedirectTo: ${window.location.origin}/auth/callback?redirect=<encoded redirect> }`. The `redirect` is read from the current location and forwarded so deep-links survive the email gap on the magic-link path. Returns `{ session: data.session }` so the callsite can branch on auto-confirm vs. pending.
   - No new context method this commit (resend in commit 4).
+- `web/src/lib/route-guards.ts`:
+  - `requireAuth` falls back to `supabase.auth.getSession()` when `context.auth.user` is null before throwing the redirect. Necessary because `exchangeCodeForSession` in the auth-callback loader persists the session synchronously but AuthContext's React state hasn't re-rendered yet by the time the redirect target's `beforeLoad` runs — without the fallback, a freshly-confirmed user bounces straight back to `/`. The two existing "redirects to..." tests are replaced with one "context lags but Supabase has a session" test plus a comment-documented mock for `supabase.auth.getSession`.
 - `web/src/components/auth/SignUpForm/SignUpForm.tsx`:
-  - After successful `signUp()`, branch on `data.session`:
-    - If `session` is non-null (auto-confirm fallback if confirmations are ever disabled): existing navigate-to-destination logic at lines 68-72.
-    - If `session` is null: set local `pending` state, render `<CheckEmailNotice email={email} onVerified={handleVerified} />` _in place of the existing `<Card>`_ (not the whole component) — the outer page wrapper (`<div className="flex w-full items-center justify-center p-8 md:min-h-screen">` and the `<div className="w-full max-w-md space-y-4">` cap) stays. `handleVerified` runs the same destination logic via `getPostSignupDestination`.
+  - After successful `signUp()`, branch on the returned `session`:
+    - If `session` is non-null (auto-confirm fallback if confirmations are ever disabled): existing navigate-to-destination logic, factored into a `completeSignUp()` helper that runs `startAuthTransition` → `navigate({ to: getPostSignupDestination(search.redirect) })` → `completeAuthTransition`.
+    - If `session` is null: set local `awaitingConfirmation` state, render `<CheckEmailNotice email={email} onVerified={completeSignUp} />` _in place of the existing `<Card>`_ (not the whole component) — the outer page wrapper stays. The wrapper's padding is widened to `p-4 sm:p-8` so the OtpInput row fits on narrow phones (the responsive slot sizing in `<OtpInput>` does the rest).
   - Width nuance: `<CheckEmailNotice>` Card is `max-w-lg` (512px), but the parent's `max-w-md` cap wins, so pending renders at 448px — same width as the form. If you want pending wider, raise the `SignUpForm` wrapper's cap to `max-w-lg`.
+- `e2e/tests/_infra/config-sync.spec.ts`:
+  - Extend `IGNORED_KEY_RE` to also ignore `site_url` and `additional_redirect_urls`. These now differ between dev (`localhost:5173`) and e2e (`localhost:5273`) because the web port shifts by the +100 e2e convention. Without the extension, the config-sync guard test fails on every CI run after this commit.
 
 **Tests:**
 
 - `SignUpForm.test.tsx`:
-  - When mocked `signUp` returns no session, `<CheckEmailNotice>` is rendered and no navigation occurs
-  - When mocked `signUp` returns a session (auto-confirm fallback), existing navigation behavior preserved
+  - When mocked `signUp` returns `{ session: null }`, `<CheckEmailNotice>` is rendered and no navigation occurs
+  - When mocked `signUp` returns `{ session: mockSession }` (auto-confirm fallback), navigation runs to `/create-team` (default) or to the redirect search param
+  - The "disables submit while loading" test uses a never-resolving promise rather than a `setTimeout` so the post-submit branch can't bleed into the next test
 - `AuthContext.test.tsx`:
-  - `signUp` calls Supabase with the expected `emailRedirectTo` (including the forwarded `redirect` query)
+  - `signUp` calls Supabase with `emailRedirectTo` set to `${origin}/auth/callback` when no redirect option is provided
+  - `signUp` calls Supabase with `emailRedirectTo` set to `${origin}/auth/callback?redirect=<encoded>` when a redirect option is provided
+- `route-guards.test.ts`:
+  - `requireAuth` resolves without redirect when `context.auth.user` is null but `supabase.auth.getSession()` returns a session
+  - The two prior "redirects to ... with replace option" tests for `requireTeam` / `requireNoTeam` are deleted — they only exercised `requireAuth`'s redirect path, which is now covered by the consolidated `requireAuth` describe block
 
 **Verification:**
 
@@ -311,14 +326,18 @@ Each commit is a gate. Each must independently build, lint, test, and format. Wa
 
 **Modified:**
 
-- `web/src/lib/supabase.ts` (commit 1 — add `flowType: 'pkce'`)
+- `web/src/lib/supabase.ts` (commit 1 — add `flowType: 'pkce'` and `detectSessionInUrl: false`)
 - `web/src/router.tsx` (commit 1 — add `/auth/callback` route with loader, pendingComponent, and inline errorComponent)
+- `web/src/lib/route-guards.ts` (commit 3 — `requireAuth` falls back to `supabase.auth.getSession()`)
 - `api/supabase/config.toml` (commit 3)
 - `e2e/supabase/config.toml` (commit 3)
+- `e2e/tests/_infra/config-sync.spec.ts` (commit 3 — extend ignore list with `site_url` / `additional_redirect_urls`)
 - `web/src/contexts/AuthContext.tsx` (commits 3, 4)
-- `web/src/contexts/AuthContext.ts` (commit 4)
+- `web/src/contexts/AuthContext.ts` (commits 3, 4 — `signUp` signature gains `options?: { redirect?: string }` and returns `{ session }`)
 - `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commit 3, minor in commit 4)
 - `web/src/components/auth/SignInForm/SignInForm.tsx` (commit 5)
+- `web/src/components/OtpInput/OtpInput.tsx` (commit 2 — `onComplete` prop + `onBeforeInput` splice handler + responsive slot sizing)
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` (commit 2 — consume `onComplete` instead of `onChange + length` check)
 
 **New:**
 

From 4922307a64ca3aeec135d88ab922475eb6300427 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Wed, 13 May 2026 14:42:21 -0500
Subject: [PATCH 12/25] docs(plans): rework #164 to implicit-flow design

Supersede commits 1-3's PKCE + custom callback design with the
documented Supabase SPA pattern (implicit flow + detectSessionInUrl).
Adds commits 4-8 covering revert, routing, error UX, resend, and e2e.
---
 docs/plans/164-email-confirmation-signup.md | 484 ++++++++------------
 1 file changed, 202 insertions(+), 282 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index d66b647..7e63b3d 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -1,385 +1,305 @@
 # Plan — Issue #164: Require email confirmation on signup
 
+> ## Status as of 2026-05-13 (rework — commits 1-3 superseded, commits 4-8 forward)
+>
+> Commits 1-3 shipped an implementation built on PKCE flow, a custom `/auth/callback` loader, and `?redirect=` URL plumbing through `signUp`/`resendConfirmation`/`buildEmailRedirectTo`. That design was reconsidered against Supabase's documented SPA patterns and against the codebase's existing route-guard architecture; it was inventing infrastructure to deviate from the documented default and duplicating routing decisions already owned by route guards. Commits 4-8 rework it; commits 1-3 remain in branch history for traceability.
+>
+> **Process for the fresh agent:**
+>
+> 1. `git restore .` (or VS Code's "Discard All Changes") to drop all uncommitted work. The branch returns to commit `69351be`.
+> 2. Implement commits 4-8 in order; each is a review gate (build, lint, test, format all green) and is committed before moving to the next.
+> 3. Use conventional commit styling. No `Co-Authored-By` footer.
+>
+> **What's kept from commits 1-3:**
+>
+> - `<OtpInput>` and `<CheckEmailNotice>` (commit 2) — the typed-OTP path UI; unchanged.
+> - `enable_confirmations = true` in `api/supabase/config.toml` and `e2e/supabase/config.toml` (commit 3).
+> - `requireAuth`'s `supabase.auth.getSession()` fallback in `web/src/lib/route-guards.ts` (commit 3) — still load-bearing for the React/Supabase state-lag.
+> - The custom email template at `api/supabase/templates/confirmation.html` — kept as a file, but its link URL is rewritten in commit 4 to use `{{ .ConfirmationURL }}`.
+>
+> **What's removed by commit 4:**
+>
+> - `/auth/callback` route, its Zod schema, its loader, its `errorComponent`, its integration test.
+> - `web/src/lib/auth-destination.ts` (`getPostSignupDestination`).
+> - The `redirect: string` option threaded through `signUp` / `resendConfirmation` / `buildEmailRedirectTo`.
+> - The `token_hash` URL surgery in the email template.
+> - PKCE flow options on the Supabase client.
+
+---
+
 ## Context
 
-Email confirmations are currently disabled in Supabase (`enable_confirmations = false` in `api/supabase/config.toml:176`). Anyone can sign up with any email and immediately be logged in — there's no proof of address ownership. The issue asks us to:
+Email confirmations are currently enabled in dev/e2e (`enable_confirmations = true` in `api/supabase/config.toml:176` and `e2e/supabase/config.toml`). The feature wires:
 
-1. Enable email confirmations
-2. Show a "pending confirmation" state after signup (since `signUp()` will no longer return a session)
-3. Allow the confirmation email to be resent
-4. Complete verification when the user clicks the email link
-5. Handle the case where an unconfirmed user later tries to sign in
+1. Signup gates on email confirmation (Supabase returns `session: null` until confirmed).
+2. A pending "check your email" UI with both magic-link and typed-OTP completion paths.
+3. Resend, with rate-limit handling.
+4. Friendly handling when an unconfirmed user later signs in.
 
 **Out of scope:**
 
-- Branded email template content (deferred to #22)
-- Standardizing post-auth redirect destinations (deferred to #165)
-- Production Supabase dashboard configuration (must be done manually after deploy: enable Confirm Email in Authentication → Providers → Email, add `https://<prod>/auth/callback` to redirect allowlist, upload custom template)
+- Branded email template content (deferred to #22).
+- Standardizing post-auth redirect destinations app-wide (deferred to #165).
+- Production Supabase dashboard configuration (manual post-deploy: enable Confirm Email, add redirect allowlist patterns, upload custom template, raise rate limits, configure SMTP).
+
+---
 
 ## Decisions
 
-| Decision                                    | Choice                                                                                                                                                                                                                                  | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Confirmation method                         | **Both magic link AND OTP code** in the email; user can use whichever                                                                                                                                                                   | Resilient to corporate email scanners (Defender, Barracuda, Mimecast) that pre-fetch links and consume the token before users click. Supabase auth issue [#1214](https://github.com/supabase/auth/issues/1214) is open and unfixed; no clean recovery for affected users without an OTP fallback. Default Supabase template already emits both, so the email-side cost is near zero.                                                                                                                                                                                                                                |
-| OTP input component                         | Custom `<OtpInput>` at `web/src/components/OtpInput/`                                                                                                                                                                                   | Hand-rolled single-input + overlay slot pattern (same architecture as `input-otp`) that fixes the slot-retargeting bug ([shadcn/ui #4046](https://github.com/shadcn-ui/ui/issues/4046)) where clicking a non-final slot focuses the last cell. Preserves every must-have: single accessible `<input>` for WCAG 1.3.5, iOS/Android SMS autofill via `autocomplete="one-time-code"`, native paste, full keyboard a11y, auto-submit. Lives outside `ui/` because `ui/` is reserved for vendored shadcn; sits next to the other custom primitives (`LoadingButton`, `InlineError`). Removes the `input-otp` dependency. |
-| Pending-UI surface                          | Inline state + shared `<CheckEmailNotice>` component                                                                                                                                                                                    | No URL params (OWASP: PII like email shouldn't appear in URLs — leaks via browser history, server logs, Referer to Sentry). Refresh degrades benignly: link in inbox still works, resend reachable via signin path.                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `<CheckEmailNotice>` shape                  | **Card-only component, not a full-page screen** — returns the `<Card>` directly; page chrome (centering, full-viewport height, background) is the caller's responsibility                                                               | The caller already provides a page wrapper (`SignUpForm`'s and `SignInForm`'s outer `flex w-full ... justify-center ... md:min-h-screen` div). A second wrapper inside `<CheckEmailNotice>` would double-wrap and made the Card's `w-full max-w-lg` resolve against a content-sized parent, which let the `<InlineError>`'s width feed back into the Card width. Card-only avoids both issues; commits 3 and 6 swap `<CheckEmailNotice>` in place of the existing `<Card>` inside the parent's wrapper.                                                                                                             |
-| Auto-submit vs. manual submit               | **Auto-submit on 6th digit AND a manual Verify button**, no `<form>` wrapper. Button is `type="button"` with `onClick`. No Enter-to-submit                                                                                              | Auto-submit covers every typed/pasted/retyped happy path via `<OtpInput>`'s dedicated `onComplete` callback (fires from `onChange`, `onPaste`, and `onBeforeInput`'s same-digit splice). The Verify button serves as the loading-state visual, the success-state visual ("Verified" + check), and the explicit retry affordance after a failure. The `<form>` was vestigial after we dropped HTML-form-validation; its only remaining job was Enter-to-submit, which would only ever re-fire the same already-failed code — a weak use case for OTP. |
-| `<OtpInput>` completion signal              | Dedicated `onComplete(value)` callback, not `onChange + value.length === length` inspection at the callsite                                                                                                                             | Same-digit replacements in a full code (e.g., user retypes a wrong digit over the same position) bypass React's `onChange` because the SyntheticEvent value tracker bails when the input's value didn't change. A dedicated callback wired into the primitive's `onChange` / `onPaste` / `onBeforeInput` paths means the callsite gets a single reliable "done" signal regardless of typing pattern, and the same-digit case still fires verification.                                                                                              |
-| `requireAuth` route guard                   | Falls back to `supabase.auth.getSession()` when `context.auth.user` is null before redirecting                                                                                                                                          | After the auth-callback loader calls `exchangeCodeForSession`, Supabase persists the session synchronously but AuthContext's React state only catches up on the next render. A redirect-target route's `beforeLoad` runs before that re-render, so `context.auth.user` is briefly null even though the user is signed in. Without the fallback, the user bounces back to `/` immediately after the loader redirects them. The fallback consults Supabase directly and lets the navigation through; both code paths flow into the same logged-in state. |
-| Verify button shape                         | Centered, `size="lg" min-w-48`, not full-width                                                                                                                                                                                          | Centered slots above + centered button below reads visually balanced. Full-width would deviate less from `SignUpForm`/`SignInForm` but visually anchors the manual button more heavily than is warranted given auto-submit is the primary path. `min-w-48` keeps the tap target generous on mobile.                                                                                                                                                                                                                                                                                                                 |
-| Failure copy                                | Static generic message _"That code didn't match. Check your email for the latest one."_ — not the raw Supabase error string                                                                                                             | Supabase emits jargon ("Token has expired or is invalid"). Users typed a "code", not a "token", and the canonical follow-up is to enter a new code from the latest email. Also: `verify()` no longer optimistically clears the error at function entry (only on success), so re-attempts don't unmount/remount the `<InlineError>` and trigger a layout shift mid-flight.                                                                                                                                                                                                                                           |
-| Error placement inside `<CheckEmailNotice>` | `<InlineError>` sits _under_ the slot row, inside the same `space-y-3` group, replacing the idle-state status hint when present                                                                                                         | Keeps the eye path slots → error → button continuous. Originally placed above the slots; that path made the user snap up to the top, then back down to retype.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| Email passing                               | React state within form components                                                                                                                                                                                                      | User never retypes — Supabase's confirmation token uniquely identifies the user. Email passed as prop from parent (`SignUpForm`, `SignInForm`) into `<CheckEmailNotice>`.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Sign-in unconfirmed handling                | In scope, same issue (commit 5)                                                                                                                                                                                                         | Completes the verification story: signup → pending → resend → confirm AND signin → unconfirmed → resend.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| Post-confirmation destination               | Preserve current logic per parent (`SignUpForm` → redirect-or-`/create-team`; `SignInForm` → redirect-or-`/leagues`; magic link callback uses URL `redirect` search param, else `/create-team`)                                         | Standardization deferred to #165.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| Resend with redirect override               | `AuthContext.resendConfirmation(email, { redirect? })` accepts the current redirect param so the resent email's link encodes the _current_ destination (e.g., signin's `/leagues/123`) rather than whatever was baked in at signup time | Helps a user who hits the unconfirmed-signin path with a deep link, triggers Resend, and uses the new email's link. The original signup email's link still routes to `/create-team` (can't fix retroactively); the OTP path always routes correctly via the callsite.                                                                                                                                                                                                                                                                                                                                               |
-| E2E approach                                | Existing admin-API fixture keeps `email_confirm: true` (auto-confirms); add two new tests in commit 6 (magic-link path + OTP path)                                                                                                      | Existing tests stay fast; targeted e2e covers the new wiring                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Email template                              | Custom template at `api/supabase/templates/confirmation.html` includes both `{{ .ConfirmationURL }}` and `{{ .Token }}`, lands in commit 3 alongside the config flip                                                                    | Default Supabase template already has both; we're shipping our own to control wording and prep for #22's branding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| Cross-issue ordering                        | 164 → 167 → 165 (locked)                                                                                                                                                                                                                | 164 builds verification primitives; 167 reuses callback route + OTP entry pattern for change-email re-verification; 165 audits all destinations after both new flows exist.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Auth callback implementation                | **Route loader + inline `errorComponent`, no separate component**                                                                                                                                                                       | Async work belongs in a TanStack Router `loader` (matches every other async route in the codebase — `joinInviteRoute`, `accountRoute`, etc.); avoids the `useEffect` + `cancelled`-flag anti-pattern. Side effects (Sentry capture) live at the failure site inside the loader's `try/catch`, not in a render-time hook. The shared `ErrorFallback` doesn't fit (hardcoded copy + "Try again" button; reloading can't fix a consumed PKCE code), and the bespoke error UI is small enough to inline in `errorComponent` rather than warrant a dedicated component file.                                             |
-| Sentry coverage for loader failures         | Manual `Sentry.captureException` inside the loader's `try/catch`                                                                                                                                                                        | The auth-callback failure mode is a Supabase SDK error that bypasses `apiClient`'s built-in HTTP-error capture, so without explicit capture in the loader, Sentry never sees PKCE failures. This is consistent with the existing pattern in `rootRoute.beforeLoad`. The codebase-wide observability gap (loader failures outside `apiClient` are silently rendered) is tracked separately in #180; commit 1 doesn't try to solve it here.                                                                                                                                                                           |
+| Decision | Choice | Rationale |
+| --- | --- | --- |
+| Auth flow | Implicit (Supabase `createClient` defaults: `flowType: 'implicit'`, `detectSessionInUrl: true`) | Documented SPA pattern. Verified at `GoTrueClient.ts:184-194`. The PKCE flow's `signUp` writes `code_challenge` (`GoTrueClient.ts:899-924`) but `resend` does not (`2535-2574`), which broke the resend path; implicit sidesteps the asymmetry. |
+| Magic-link verification | SDK auto-detects `#access_token=...` from URL fragment during `_initialize` | No callback loader needed; `_initialize` saves the session and fires `SIGNED_IN`. On success the SDK strips the hash (`GoTrueClient.ts:3702-3703`); on failure it leaves `#error_description=...` for the app to read. |
+| Typed-OTP verification | `supabase.auth.verifyOtp({ email, token, type: 'email' })` | No alternative for typed codes. `'email'` is the type for email-confirmation OTPs from the custom template's `{{ .Token }}`. |
+| Confirmation method in email | Both magic link and OTP code | Resilient to corporate email scanners that pre-fetch links (Supabase auth issue [#1214](https://github.com/supabase/auth/issues/1214)). The custom template includes `{{ .ConfirmationURL }}` and `{{ .Token }}`. |
+| Email link construction | `{{ .ConfirmationURL }}` only | Supabase owns the URL. No template-side concatenation, no `&token_hash=` append, no requirement that `buildEmailRedirectTo` always include a query string. |
+| Callback route | None | The implicit flow's auto-detect runs against whatever URL the user lands on. No app-side loader required. |
+| Post-confirm destination | Caller of `signUp`/`resendConfirmation` passes `emailRedirectTo` directly (full URL). Default: `${origin}/`. Dynamic: `${origin}${search.redirect}` when SignUpForm was reached via a redirect param (e.g., `/sign-up?redirect=/join/<token>`). | One source of truth for "where does this user land": the `emailRedirectTo` URL itself. No parallel `?redirect=` URL parameter, no `getPostSignupDestination` helper. Route guards continue to own routing for users landing at any given URL. |
+| Cross-browser invite preservation | Encoded in `emailRedirectTo` | Supabase forwards `emailRedirectTo` verbatim through `/verify`. A user who signs up from `/join/<token>` on desktop and confirms via the email on mobile lands directly at `/join/<token>` on mobile, signed in. |
+| `/` route handling | Add `beforeLoad` that bounces authenticated users to `/create-team` or `/leagues` based on team state | Mirrors the existing pattern on `/sign-in` (`router.tsx:218-228`) and `/sign-up` (`router.tsx:240-250`). Eliminates the "marketing content rendered inside authenticated app shell" weirdness when a signed-in user lands at `/`. Single home for post-auth routing: route guards. |
+| Auth-URL error UX | `useEffect` in `AuthContext` reads `window.location.hash` on mount, parses `error` + `error_description`, sets `authUrlError` state via `mapAuthUrlError(code, description)`, strips the hash. `<Layout>` renders `<InlineError>` above `<Outlet>` when set. `clearAuthUrlError` on dismiss. | `getSession()` swallows `_initialize` errors (verified at `GoTrueClient.ts:2661-2671`); reading the URL fragment is the only way to surface them. `<InlineError>` matches `web/CLAUDE.md`'s convention for primary-flow errors (toasts are reserved for background operations). |
+| Supabase redirect allowlist | Wildcards: `http://localhost:5173/**` (dev), `http://localhost:5273/**` (e2e). Production: tightened to specific patterns per surface (`https://<prod>/`, `https://<prod>/join/**`, etc.). | Required to allow dynamic `emailRedirectTo` paths. Wildcard support confirmed in Supabase docs; `**` matches any sequence including separators. |
+| `requireAuth` `getSession()` fallback | Kept | Still load-bearing: AuthContext's React state lags Supabase's session state by one render after any auth state change. Without the fallback, freshly-confirmed users bounce back to `/` because `context.auth.user` is briefly null in `beforeLoad`. |
+| Email passing into `<CheckEmailNotice>` | React state from parent (`SignUpForm`, later `SignInForm`) | Same as the original commit 2 design. Supabase identifies the user by token; email is only for display + the typed-OTP `verifyOtp` call. No URL params (OWASP: PII shouldn't appear in URLs). |
+| Failure copy for typed-OTP | Static generic message: _"That code didn't match. Check your email for the latest one."_ | Same as the original commit 2 design. |
+| Sign-in unconfirmed handling | Deferred | Commits 4-8 do not include the SignInForm wiring for `email_not_confirmed`. The original commit 5 plan is preserved as future work but is not part of this rework. The rework focuses on getting the signup path onto the correct foundation; the signin-unconfirmed UX reuses the same `<CheckEmailNotice>` and can be added afterward without affecting the rework's design. |
 
 ---
 
 ## Commits
 
-Each commit is a gate. Each must independently build, lint, test, and format. Wait for approval before moving on. Note: these commits are sized for review/approval — they don't necessarily map 1:1 to production deploys. Recommendation is to land all six before flipping production confirmations on, so users always have the OTP fallback path. The local-dev confirmation flip happens in commit 3; commits 1–2 are preparatory and safe under `enable_confirmations = false`.
+### Commit 1 — PKCE flow + `/auth/callback` loader (`23ca5ec`) — **SUPERSEDED**
 
-### Commit 1 — PKCE flow + `/auth/callback` loader
+Original design: switched the Supabase client to `flowType: 'pkce'` with `detectSessionInUrl: false`, added a `/auth/callback` route with a loader that called `exchangeCodeForSession`, and added `getPostSignupDestination` in `web/src/lib/auth-destination.ts`. Commit 4 reverts the client to defaults, deletes the route, and deletes the helper.
 
-**Goal:** Stand up the magic-link landing page and switch the Supabase client to PKCE so the link returns `?code=` instead of an implicit hash. Safe to land while `enable_confirmations` is still `false`: the route exists but nothing emits a magic link yet, and PKCE is fully compatible with the existing implicit-flow happy path.
+### Commit 2 — `<OtpInput>` primitive + `<CheckEmailNotice>` component (`d4a632b`) — **KEPT**
 
-**Supabase client flow change** (`web/src/lib/supabase.ts`):
+The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type: 'email'` (corrected from the original `'signup'` during the pivot; commit 4 keeps this corrected value).
 
-- Today: `createClient(url, key)` with no options → defaults to `flowType: 'implicit'` (verified in `auth-js` source — `DEFAULT_OPTIONS.flowType: 'implicit'`)
-- Required: pass `{ auth: { flowType: 'pkce', detectSessionInUrl: false } }`:
-  - `flowType: 'pkce'` so the magic link returns `?code=` (which `exchangeCodeForSession` consumes) instead of `#access_token=` (implicit hash flow)
-  - `detectSessionInUrl: false` so the SDK's default URL-watcher doesn't race the auth-callback loader for the `?code=` param. The loader owns the exchange; auto-detection would double-fire and the second call would 400 on the already-consumed code.
-- This is a small but app-wide auth behavior change — covered by existing AuthContext tests
+### Commit 3 — Enable confirmations + SignUpForm wiring (`de592bc`) — **PARTIALLY SUPERSEDED**
 
-**New helper** (`web/src/lib/auth-destination.ts`):
+- **Kept by commit 4:** `enable_confirmations = true` config flip in both `api/supabase/config.toml` and `e2e/supabase/config.toml`. The custom email template file (its content gets rewritten). `requireAuth`'s `getSession()` fallback.
+- **Superseded by commit 4:** the `redirect: string` option threaded through `signUp`. The token_hash-style email template URL. The SignUpForm wiring that called `getPostSignupDestination`.
 
-- `getPostSignupDestination(redirectParam?: string): string` — returns `redirectParam` if present, else `/create-team`. Search-param validation is already enforced upstream by the route's Zod schema, so this helper just chooses between two valid values. Used by the auth-callback loader here, and later by `SignUpForm` and `<CheckEmailNotice>`'s `onVerified` from the signup callsite (commit 3). Lands here because the auth-callback loader is its first caller.
+---
 
-**Wiring** (`web/src/router.tsx`):
+### Commit 4 — Replace PKCE callback with implicit-flow defaults
 
-- New Zod schema `authCallbackSearchSchema` validates `code` (optional string) and `redirect` (optional string, must start with `/` — same shape as the existing `redirectSearchSchema`).
-- New `authCallbackRoute` as a public child of root (sibling to `/sign-up`, `/sign-in`). Built as a loader-driven route:
-  - `loaderDeps` pulls `code` and `redirect` from the validated search params.
-  - `loader` wraps the exchange in `try/catch`: if `code` is missing or `supabase.auth.exchangeCodeForSession` returns/rejects with an error, capture to Sentry with `tags: { component: 'authCallbackRoute', operation: 'exchangeCodeForSession' }` and rethrow. On success, `throw redirect({ to: getPostSignupDestination(redirect) })`.
-  - `pendingComponent` renders a "Confirming your email..." spinner during the loader phase.
-  - `errorComponent` is inlined: renders `<InlineError>` with the user-friendly copy and a "Back to sign in" `<Link>`. No dedicated component file — the shared `ErrorFallback` doesn't fit (hardcoded copy, "Try again" button that can't recover a consumed PKCE code), and the bespoke UI is ~15 lines of JSX.
-  - No `component` field — the loader always throws (`redirect` on success, captured error otherwise), so the route never renders to a normal component.
+**Goal:** undo the PKCE/callback infrastructure and the redirect plumbing. After this commit, the email-confirmation flow works end-to-end via either path. Users land at `${origin}/` post-confirm; the `/` route has no `beforeLoad` for authed users yet (commit 5 adds it), so a signed-in user briefly sees `LandingPage` rendered inside the authenticated app shell — functional but visually unpolished. Build/lint/test all pass.
 
-**Tests:**
+**Files modified:**
 
-- `web/src/tests/integration/auth-callback.integration.test.tsx` — covers loader branches via a real router mounted over an inline route-tree mirror (matches the convention in `account.integration.test.tsx`):
-  - Default destination: with `?code=abc`, loader exchanges and redirects to `/create-team`; no Sentry capture.
-  - `redirect` honored: with `?code=abc&redirect=/leagues`, loader redirects to `/leagues`.
-  - Missing `code`: renders error UI + `Sentry.captureException` called with `component: authCallbackRoute`.
-  - Supabase returns error: renders error UI + Sentry captured with the supabase error.
-  - Supabase rejects: renders error UI + Sentry captured with the rejection.
-- `auth-destination.test.ts`:
-  - Returns the redirect param when provided.
-  - Falls back to `/create-team` when redirect is missing/empty.
-- Existing `AuthContext.test.tsx` keeps passing under PKCE (no behavioral change to the public API).
+- `api/supabase/templates/confirmation.html` — **no change in this commit**. The user customized this template (structure, copy, styling) and committed those customizations in `de592bc`. The only uncommitted edit was the token_hash URL surgery on the link `href`, which the prerequisite `git restore .` step reverts automatically. After `git restore .` the template is already in the correct state for the new design (link `href = {{ .ConfirmationURL }}`). Do not regenerate or replace the file.
+- `api/supabase/config.toml` — `additional_redirect_urls = ["http://localhost:5173/**"]`. Add a code comment noting that production must tighten to specific patterns.
+- `e2e/supabase/config.toml` — `additional_redirect_urls = ["http://localhost:5273/**"]`.
+- `e2e/tests/_infra/config-sync.spec.ts` — extend `IGNORED_KEY_RE` to ignore `site_url` and `additional_redirect_urls` (the wildcard hosts differ between dev and e2e). This part survives from the old commit 3.
+- `web/src/lib/supabase.ts` — `createClient(url, key)` with no options. No `flowType`, no `detectSessionInUrl`.
+- `web/src/router.tsx` — delete `authCallbackRoute` declaration, `authCallbackSearchSchema`, its entry in `rootRoute.addChildren`, and any related imports (`Sentry`, `Link` if only used there, etc.). Leave `requireAuth`'s fallback intact.
+- `web/src/contexts/AuthContext.tsx` + `.ts` — `signUp` signature becomes `signUp(email, password, additionalData, options?: { emailRedirectTo?: string })`. Default: `emailRedirectTo: ${window.location.origin}/`. The implementation passes `options?.emailRedirectTo` straight through to `supabase.auth.signUp`'s options.
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` — remove `getPostSignupDestination` import and usage. Compute `emailRedirectTo` as `${window.location.origin}/` (hardcoded for this commit; commit 5 makes it dynamic). For the typed-OTP `onVerified` navigation in the same browser, navigate to `search.redirect ?? '/create-team'` using the existing React state.
 
-**Verification:**
+**Files deleted:**
 
-1. `npm run web:test` green
-2. `npm run web:lint` + `npm run web:format:check` green
-3. `npm run web:build` green (TypeScript compile)
-4. Manual: existing signup/signin flow still works (auto-confirm path, no email sent because `enable_confirmations` is still `false`)
+- `web/src/lib/auth-destination.ts`
+- `web/src/lib/auth-destination.test.ts`
+- `web/src/tests/integration/auth-callback.integration.test.tsx`
 
----
-
-### Commit 2 — `<OtpInput>` primitive + `<CheckEmailNotice>` component
-
-**Goal:** Add the pending-state UI as a self-contained, tested component, backed by a hand-rolled `<OtpInput>` primitive (no `input-otp` dependency). Fixes the slot-retargeting bug so a user can click any slot to edit just that digit. Not yet wired into any form — that happens in commit 3.
-
-**New primitive — `<OtpInput>`** (`web/src/components/OtpInput/OtpInput.tsx`):
-
-- **Architecture:** Single-input + overlay slots, stacked via CSS Grid (not `position: absolute`). One real `<input>` and one slot-row `<div>` are both children of a `grid` container, both placed at `col-start-1 row-start-1` so they occupy the same cell. The input is rendered with transparent text and caret (`text-transparent caret-transparent`) and sits _under_ the slot row (which has `z-10`), so the slot row intercepts clicks and the input owns keyboard input + SMS autofill + screen-reader naming.
-- **Scope:** numeric OTP only. The non-digit filter and `inputMode="numeric"` default are baked in; no `pattern` prop. Spelled out in the component's JSDoc.
-- **Why single input, not N individual inputs:** `<input autocomplete="one-time-code">` SMS autofill on iOS only works with a single input ([web.dev — SMS OTP form](https://web.dev/articles/sms-otp-form), confirmed broken on multi-input in [Chakra #4095](https://github.com/chakra-ui/chakra-ui/issues/4095), [react-verification-input #57](https://github.com/andreaswilli/react-verification-input/issues/57)). Paste, backspace, and arrow nav also come free at the browser level.
-- **Props:**
-  - `id?: string` — forwarded to the underlying `<input>` so external `<Label htmlFor>` works
-  - `value: string`, `onChange: (value: string) => void`
-  - `onComplete?: (value: string) => void` — fires the first time `value` reaches `length` after any input path: `onChange` digit-fill, `onPaste`, or the `onBeforeInput` same-digit-replace path described below. Callers use this as the auto-submit signal.
-  - `length?: number` (default `6`) — also forwarded as `maxLength`
-  - `disabled?: boolean`
-  - `'aria-label'?: string`
-  - `autoComplete?: string` (default `"one-time-code"`)
-  - `inputMode?: ComponentPropsWithoutRef<'input'>['inputMode']` (default `"numeric"`)
-  - `className?: string` — merged via `cn()` onto the grid container (outer sizing only)
-  - `slotClassName?: string` — merged onto each slot for per-slot style overrides
-  - Each visible slot carries `data-slot="otp-slot"` as a styling/structure marker (mirrors the shadcn convention). Not a public test hook except for the one click-retargeting test that the bug it guards is structural-positional.
-- **Behavior:**
-  - `onChange` strips non-digit characters and slices to `length`. Tracks the post-change caret in `selectionStart` state so active-slot styling reacts to typing without waiting for the next `selectionchange` event.
-  - **Paste interceptor (`onPaste`):** intercepts paste events, `preventDefault`s the browser default, sanitizes `clipboardData.getData('text')`, and calls `onChange` with the sliced result. Necessary because `maxLength` on the underlying input would otherwise truncate a mixed-character paste (e.g., `"abc123456xyz"`) to its first 6 characters (`"abc123"`) _before_ our digit filter can run. With the interceptor, paste yields `onChange("123456")` in a single call.
-  - **Same-digit replacement (`onBeforeInput`):** when the input is already at `length` and the user types a digit, React's value tracker skips `onChange` if the resulting character is identical to the one being replaced (e.g., position 3 holds `5` and the user types `5` again). The handler intercepts `beforeinput`, `preventDefault`s the browser, splices the new digit into `value` at `selectionStart`, advances the caret by one, and re-selects the next slot via `requestAnimationFrame` + `setSelectionRange(next, next+1)`. Also fires `onComplete` when this path lands on the final slot.
-  - **Click-to-edit any slot (the bug fix):** on slot `onPointerDown`, `preventDefault`, `focus()` the input, then `setSelectionRange(i, i+1)` if the slot has a character, else collapse the caret at `min(i, value.length)`. Safari requires `focus()` before `setSelectionRange`.
-  - **Active slot tracking:** uses a `document`-level `selectionchange` listener (gated on `isFocused`) for cursor moves that don't go through `onChange` (arrow keys, click-to-position) and that `onSelect` misses on Safari. The listener updates a `selectionStart` state, and `activeIndex` is derived from `isFocused + selectionStart + value.length`. Caret animation uses `animate-caret-blink` (from `tw-animate-css`).
-  - **Disabled:** propagates to the `<input>` and the slot container (`pointer-events-none opacity-50`).
-- **Styling defaults baked in:** slot is `h-12 w-10 sm:h-14 sm:w-12 rounded-md border font-mono text-2xl font-medium tabular-nums` (responsive so the row fits on ~320px phones); active state `border-primary ring-2 ring-primary/40 ring-inset`; slot-row `flex justify-center gap-1.5 sm:gap-2.5`. The underlying `<input>` also carries `selection:bg-transparent selection:text-transparent` so the native selection highlight doesn't leak into the visible slots when `setSelectionRange` extends across positions. Consumer-supplied `className` / `slotClassName` merge via `cn()` (Tailwind merge wins on conflicts).
-- **Accessibility:** the grid container carries no `role`; the slot-row `<div>` is `aria-hidden="true"`. Screen readers see only the single labeled `<input>`.
-
-**New flow component — `<CheckEmailNotice>`** (`web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx`):
-
-- **Returns just a `<Card>`** — no outer page wrapper. Caller (commit 3's `SignUpForm`, commit 5's `SignInForm`, dev-route scaffolding) provides centering, full-viewport height, and background.
-- **Props:**
-  - `email: string` — rendered in the body
-  - `onVerified: () => void` — called after `verifyOtp` resolves successfully so caller can navigate
-  - `onResend?: () => Promise<void>` — declared in `Props` for commit 4; renders nothing in commit 2 (no `CardFooter` yet)
-  - `onChangeEmail?: () => void` — same; renders nothing until commit 4 reintroduces the `CardFooter`
-- **Layout:**
-  - `CardHeader`: envelope icon, "Check your email" heading, two-paragraph body (sentence 1 with the email chip; sentence 2 with "Enter it below or click the link…") wrapped in a `space-y-2` div so the two `<p>`s are visually separated.
-  - `CardContent` (`space-y-4`): a `space-y-3` group containing the label + progress bar, the `<OtpInput length={6} className="w-full" />`, and (when set) `<InlineError>`. Below the group, a centered `<LoadingButton size="lg" min-w-48>` that fires `verify(code)` on click.
-- **No `<form>` wrapper.** Verify button is `type="button"` with `onClick={() => { if (status === 'idle') verify(code); }}`. Auto-submit handles every code-completion path via `<OtpInput>`'s `onComplete` callback — the local `handleComplete(value)` re-checks `status === 'idle'` and fires `verify(value)`. The button's `status === 'idle'` guard prevents a mid-verify re-click from re-firing.
-- **`verify(token)`:** sets status to `'verifying'`, awaits `supabase.auth.verifyOtp({ email, token, type: 'signup' })`. On success: clears `error`, sets status to `'success'`, calls `onVerified()`. On failure (rejection OR returned error): sets a static generic message _"That code didn't match. Check your email for the latest one."_ and resets status to `'idle'`. Notably, the error is _not_ optimistically cleared at function entry — so a re-attempt doesn't unmount/remount `<InlineError>` and trigger a layout shift while the new request is in flight.
-- **`Status` type:** `'idle' | 'verifying' | 'success'`. Drives the `<OtpInput disabled>`, the `<LoadingButton isLoading>`, the Card's success ring (`ring-1 ring-emerald-500/40`), and the button's "Verified" + check icon swap-in. No separate status-line component — `LoadingButton` and the Card visual state carry it.
-
-**Tests:**
+**Tests updated:**
 
-- `OtpInput.test.tsx` (9 behavioral tests): attribute forwarding (`inputmode` / `maxlength` / `autocomplete`); typing filters non-digits; paste yields one `onChange` call with sanitized + sliced value; backspace removes last digit; click slot 3 after full code → `selectionStart === 3` (the bug fix); `disabled` prevents typing; `onComplete` fires once when the 6th digit lands by typing; `onComplete` fires once when paste fills the value; active slot advances after each typed digit (verified via `data-active="true"` on the slot `<div>`).
-- `CheckEmailNotice.test.tsx` (4 behavioral tests, trimmed per the testing strategy — no static-JSX assertions, no duplication of `OtpInput`'s attribute matrix, no separate test per error code path):
-  - Email prop renders in the body
-  - Auto-submit fires `verifyOtp` with `{ email, token, type: 'signup' }` and `onVerified` on success
-  - Failure path renders the generic `<InlineError>` text, skips `onVerified`, and leaves the typed code in the input so the user can edit a single digit instead of re-typing all six
-  - Verify button stays disabled (and `verifyOtp` uncalled) until the 6th digit lands
+- `web/src/contexts/AuthContext.test.tsx` — drop the `redirect` option tests. Add tests for the new shape: `signUp` calls Supabase with `emailRedirectTo: ${origin}/` when no option is passed; `signUp` passes `options.emailRedirectTo` through verbatim when provided.
+- `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — drop redirect-threading assertions; assert `signUp` is called with `emailRedirectTo: ${origin}/`.
+- `web/src/lib/route-guards.test.ts` — keep the `requireAuth` `getSession()` fallback test. Remove any references to `auth-callback` or `auth-destination`.
+- `web/src/lib/supabase.test.ts` — update for the no-options `createClient`.
 
 **Verification:**
 
-1. `npm run web:test` + `npm run web:lint` + `npm run web:format:check` + `npm run web:build` green.
-2. Manual via a working-tree `/dev/check-email` scratch route (added during implementation, removed before commit): (a) typing 6 digits triggers auto-submit, (b) clicking a middle slot after entering a full code retargets the caret to that slot, (c) pasting `"abc123456xyz"` fills the slots with `123456`, (d) iOS Simulator one-time-code autofill still works (sanity check that single-input wasn't broken).
-3. Scratch route + its `CheckEmailNotice` import removed from `web/src/router.tsx` before commit.
+1. `cd api/supabase && supabase stop && supabase start` and the e2e equivalent to pick up config changes.
+2. `npm run web:test` + `npm run web:lint` + `npm run web:format:check` + `npm run web:build` green.
+3. Manual: signup with a fresh email → `<CheckEmailNotice>` appears → Mailpit (`http://127.0.0.1:54324`) shows the email → clicking the magic link auto-establishes session and lands the user at `${origin}/` (visually: marketing content inside the authenticated app shell — fixed in commit 5). Typing the OTP code → `verifyOtp` succeeds → navigate to `/create-team`.
+4. `npm run e2e` green (the admin-API fixture continues to bypass email via `email_confirm: true`).
 
 ---
 
-### Commit 3 — Enable confirmations + wire SignUpForm into the pending UI
+### Commit 5 — Route authenticated users from `/` and pass redirect via `emailRedirectTo`
 
-**Goal:** Flip the feature on. Signup goes end-to-end via either path: submit → "check your email, click link or enter code" UI → user clicks link OR types code → land back in app, logged in. (Resend deferred to commit 4; signin-unconfirmed deferred to commit 5.) This is the load-bearing commit; commits 1–2 are preparatory.
+**Goal:** add `beforeLoad` to `indexRoute` so authenticated users hitting `/` bounce to their app home. Make `SignUpForm` pass `search.redirect` through `emailRedirectTo` so the magic-link path preserves the destination across the email round-trip (including cross-browser cases).
 
-**Supabase config** (`api/supabase/config.toml` and `e2e/supabase/config.toml`):
+**Files modified:**
 
-- `[auth] site_url` → set to local web URL (`http://localhost:5173` for dev, `http://localhost:5273` for e2e). Existing `http://127.0.0.1:3000` is dead config; nothing in the codebase references it.
-- `[auth] additional_redirect_urls` → `["http://localhost:5173/auth/callback"]` for dev (and `5273` for e2e). Existing `https://127.0.0.1:3000` is HTTPS on a non-running port — wrong on multiple counts.
-- `[auth.email] enable_confirmations = true` (currently `false` at line 176)
-- `[auth.email.template.confirmation]` block pointing at `./templates/confirmation.html`. `e2e/supabase/templates` is a symlink to `../../api/supabase/templates` so both stacks read the same file — mirrors how `e2e/supabase/migrations/` shares the dev migrations directory.
+- `web/src/router.tsx` — add `beforeLoad` to `indexRoute` (currently has none at `router.tsx:201-206`):
 
-**New email template** (`api/supabase/templates/confirmation.html`):
+  ```typescript
+  beforeLoad: async ({ context }) => {
+    if (context.auth.user) {
+      throw redirect({
+        to: context.teamContext.hasTeam ? '/leagues' : '/create-team',
+        replace: true,
+      });
+    }
+  },
+  ```
+
+  Also add `validateSearch: redirectSearchSchema` if not already present (verify against the existing schema usage on `/sign-in` and `/sign-up`).
 
-- Includes both the magic link (`{{ .ConfirmationURL }}`) AND the 6-digit OTP code (`{{ .Token }}`)
-- Wording explicitly mentions "Click the link OR enter the 6-digit code in the app"
-- Plain HTML; references app name placeholder; #22 will brand it
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` — at the top of the component, compute the destination once and reuse for `emailRedirectTo` and for the in-browser `onVerified` navigation:
 
-**Wiring:**
+  ```typescript
+  const search = useSearch({ from: '/sign-up' });
+  const destination = search.redirect ?? '/create-team';
+  const emailRedirectTo = `${window.location.origin}${destination}`;
+  ```
 
-- `web/src/contexts/AuthContext.tsx`:
-  - Update `signUp()` to pass `options: { data: { displayName }, emailRedirectTo: ${window.location.origin}/auth/callback?redirect=<encoded redirect> }`. The `redirect` is read from the current location and forwarded so deep-links survive the email gap on the magic-link path. Returns `{ session: data.session }` so the callsite can branch on auto-confirm vs. pending.
-  - No new context method this commit (resend in commit 4).
-- `web/src/lib/route-guards.ts`:
-  - `requireAuth` falls back to `supabase.auth.getSession()` when `context.auth.user` is null before throwing the redirect. Necessary because `exchangeCodeForSession` in the auth-callback loader persists the session synchronously but AuthContext's React state hasn't re-rendered yet by the time the redirect target's `beforeLoad` runs — without the fallback, a freshly-confirmed user bounces straight back to `/`. The two existing "redirects to..." tests are replaced with one "context lags but Supabase has a session" test plus a comment-documented mock for `supabase.auth.getSession`.
-- `web/src/components/auth/SignUpForm/SignUpForm.tsx`:
-  - After successful `signUp()`, branch on the returned `session`:
-    - If `session` is non-null (auto-confirm fallback if confirmations are ever disabled): existing navigate-to-destination logic, factored into a `completeSignUp()` helper that runs `startAuthTransition` → `navigate({ to: getPostSignupDestination(search.redirect) })` → `completeAuthTransition`.
-    - If `session` is null: set local `awaitingConfirmation` state, render `<CheckEmailNotice email={email} onVerified={completeSignUp} />` _in place of the existing `<Card>`_ (not the whole component) — the outer page wrapper stays. The wrapper's padding is widened to `p-4 sm:p-8` so the OtpInput row fits on narrow phones (the responsive slot sizing in `<OtpInput>` does the rest).
-  - Width nuance: `<CheckEmailNotice>` Card is `max-w-lg` (512px), but the parent's `max-w-md` cap wins, so pending renders at 448px — same width as the form. If you want pending wider, raise the `SignUpForm` wrapper's cap to `max-w-lg`.
-- `e2e/tests/_infra/config-sync.spec.ts`:
-  - Extend `IGNORED_KEY_RE` to also ignore `site_url` and `additional_redirect_urls`. These now differ between dev (`localhost:5173`) and e2e (`localhost:5273`) because the web port shifts by the +100 e2e convention. Without the extension, the config-sync guard test fails on every CI run after this commit.
+  Pass `emailRedirectTo` into `signUp({ emailRedirectTo })`. Use `destination` for the typed-OTP `onVerified` navigate call.
+
+  *Note:* `'/create-team'` is the in-browser default because the React state for `onVerified` runs in the same tab the user signed up from; `requireNoTeam` on `/create-team` bounces users who already have teams to `/leagues`. The `emailRedirectTo` default differs by one path segment (`/`) because the email's magic link may open in a different browser where the route guards take over.
 
 **Tests:**
 
-- `SignUpForm.test.tsx`:
-  - When mocked `signUp` returns `{ session: null }`, `<CheckEmailNotice>` is rendered and no navigation occurs
-  - When mocked `signUp` returns `{ session: mockSession }` (auto-confirm fallback), navigation runs to `/create-team` (default) or to the redirect search param
-  - The "disables submit while loading" test uses a never-resolving promise rather than a `setTimeout` so the post-submit branch can't bleed into the next test
-- `AuthContext.test.tsx`:
-  - `signUp` calls Supabase with `emailRedirectTo` set to `${origin}/auth/callback` when no redirect option is provided
-  - `signUp` calls Supabase with `emailRedirectTo` set to `${origin}/auth/callback?redirect=<encoded>` when a redirect option is provided
-- `route-guards.test.ts`:
-  - `requireAuth` resolves without redirect when `context.auth.user` is null but `supabase.auth.getSession()` returns a session
-  - The two prior "redirects to ... with replace option" tests for `requireTeam` / `requireNoTeam` are deleted — they only exercised `requireAuth`'s redirect path, which is now covered by the consolidated `requireAuth` describe block
+- `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — assert `signUp` called with `emailRedirectTo: ${origin}/create-team` when no `search.redirect`; assert `emailRedirectTo: ${origin}/leagues/123` when `search.redirect = '/leagues/123'`. Assert typed-OTP `onVerified` navigates to the same destination.
+- `web/src/tests/integration/index-route.integration.test.tsx` — new file. Mount a per-test route tree with `indexRoute`, the authed/no-team and authed/with-team layout routes, and `LandingPage`. Assert: unauthed user sees `LandingPage` at `/`; authed-no-team user redirects to `/create-team`; authed-with-team user redirects to `/leagues`. Mirrors the pattern in `account.integration.test.tsx`.
 
 **Verification:**
 
-1. `cd e2e/supabase && supabase stop && supabase start` to pick up config changes (also `cd api/supabase && supabase stop && supabase start`)
-2. `npm run web:dev` + `npm run api:watch`; sign up with a fresh email; confirm `<CheckEmailNotice>` appears; open the Mailpit UI at `http://127.0.0.1:54324` (served by the container Supabase still names `supabase_inbucket_*`); both pathways work — clicking the link AND typing the code each result in landing on `/create-team`
-3. `npm run web:test` + `npm run api:test` green
-4. `npm run e2e` green — existing tests continue working via the admin-API fixture's `email_confirm: true` (auto-confirms, bypassing the email step)
+1. `npm run web:test` + lint/format/build green.
+2. Manual: visit `/` signed out → `LandingPage`. Sign in via existing user → bounces to `/leagues` or `/create-team` based on team state. Click logo (sidebar) while authed → bounces. Sign up from `/sign-up?redirect=/join/<token>`, confirm via the email link in a different browser → land directly at `/join/<token>` signed in (`JoinInvite` renders for an authed user).
 
 ---
 
-### Commit 4 — Resend confirmation email
+### Commit 6 — Surface auth-URL errors via `<InlineError>` in Layout
+
+**Goal:** when Supabase's `/verify` redirects back with `#error_description=...` (expired token, consumed link, etc.), surface a friendly message instead of silently leaving the user on the destination as if not signed in.
 
-**Goal:** "Resend" button on the pending UI re-sends the confirmation email (which contains both link and OTP).
+**Files modified:**
 
-**Wiring:**
+- `web/src/contexts/AuthContext.tsx` — in the existing mount-time `useEffect` (or a sibling), read `window.location.hash` for `error` and `error_description`. If either is set, call `setAuthUrlError(mapAuthUrlError(code, description))` and strip the fragment via `window.history.replaceState(null, '', window.location.pathname + window.location.search)`.
+- `web/src/contexts/AuthContext.ts` — add `authUrlError: string | null` and `clearAuthUrlError: () => void` to `AuthContextType`. Expose both from the provider.
+- `web/src/components/Layout/Layout.tsx` — read `authUrlError` and `clearAuthUrlError` from `useAuth()`. Render `<InlineError>` above the `<Outlet>` (in both the authenticated and unauthenticated branches) when `authUrlError` is non-null. Provide a dismiss affordance that calls `clearAuthUrlError`.
 
-- `web/src/contexts/AuthContext.ts` — add `resendConfirmation(email: string, options?: { redirect?: string }): Promise<void>` to interface
-- `web/src/contexts/AuthContext.tsx` — implement: calls `supabase.auth.resend({ type: 'signup', email, options: { emailRedirectTo: ${origin}/auth/callback${redirect ? '?redirect=' + encodeURIComponent(redirect) : ''} } })`; throws on error
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — **reintroduce** the `<CardFooter>` (removed during commit 2's trim) and add a Resend button inside it, gated on the existing `onResend` prop being present. On click, call `onResend()` (parent passes `auth.resendConfirmation(email, { redirect })`). Use existing `<LoadingButton>` for loading state. Use existing `<LiveRegion>` to announce success ("New confirmation email sent"). Use `<InlineError>` for errors, with friendly handling for Supabase's rate-limit error code (`over_email_send_rate_limit` → "Please wait a moment before requesting another email"). The `onResend` prop and `handleResend` orchestrator already exist in `Props` from commit 2's interface but render nothing today.
-- `SignUpForm.tsx` — pass `onResend={() => auth.resendConfirmation(email, { redirect })}` to `<CheckEmailNotice>`, where `redirect` is read from the current route's search params (same source as the existing `redirect` handling at `SignUpForm.tsx:68-72`)
+**Files added:**
+
+- `web/src/lib/auth-url-errors.ts` — `mapAuthUrlError(code: string | null, description: string | null): string`. Small lookup: known codes (e.g., `access_denied` with expired-description → "This confirmation link has expired or has already been used. Try signing in to get a new one.") map to friendly copy; generic fallback ("We couldn't confirm your email. Please try signing in again.") for unknowns.
+- `web/src/lib/auth-url-errors.test.ts` — one test per mapped case plus the fallback.
 
 **Tests:**
 
-- `AuthContext.test.tsx`: `resendConfirmation` calls `supabase.auth.resend` with the correct args (type, email, emailRedirectTo); also tests the `redirect` option is encoded into emailRedirectTo correctly
-- `CheckEmailNotice.test.tsx`:
-  - Clicking Resend calls `onResend`
-  - Loading state visible during await
-  - Success message announced via `LiveRegion`
-  - Generic error rendered via `InlineError`
-  - Rate-limit error renders friendly text
-- `SignUpForm.test.tsx`: Resend button passes the current `redirect` param to `resendConfirmation`
-- `web/src/tests/integration/signup-resend.integration.test.tsx` — frontend integration (real router over an inline route-tree mirror, same convention as `auth-callback.integration.test.tsx` and `account.integration.test.tsx`; mock only the Supabase SDK):
-  - Mount the app at `/sign-up?redirect=/leagues/123`, submit the form, assert `<CheckEmailNotice>` renders. Click Resend, assert `supabase.auth.resend` was called with `{ type: 'signup', email, options: { emailRedirectTo: 'http://localhost/auth/callback?redirect=%2Fleagues%2F123' } }` — proves the route's `redirect` search param actually threads through the form → context → SDK call.
-  - Same setup, mock `supabase.auth.resend` to return `{ error: { code: 'over_email_send_rate_limit' } }`, click Resend, assert the friendly rate-limit copy renders (catches the error-code → user-copy wiring in the router context).
+- `web/src/contexts/AuthContext.test.tsx` — test: `window.location.hash` containing `#error_description=...` on mount sets `authUrlError` and strips the hash. Test: `clearAuthUrlError` resets state to `null`. Test: no hash → no state set.
 
 **Verification:**
 
-- Manual: sign up, click Resend, verify a second email appears in Mailpit; either email's link OR either email's most-recent OTP completes verification
-- Manual: rapid-fire Resend → rate-limit message
-- All test commands green
+1. `npm run web:test` + lint/format/build green.
+2. Manual: reproduce a failure by clicking a link with an invalid/expired token, or by manually constructing a URL like `http://localhost:5173/#error_description=Email%20link%20is%20invalid` → load the app → see `<InlineError>` above the page content with friendly copy; dismiss → error clears; URL bar no longer contains the fragment.
 
 ---
 
-### Commit 5 — Friendly handling of unconfirmed-email sign-in
+### Commit 7 — Add resend confirmation email
 
-**Goal:** If a user signs up but never confirms, then later tries to sign in, they see the same `<CheckEmailNotice>` (with OTP entry + Resend) instead of a generic auth error.
+**Goal:** "Resend" button on `<CheckEmailNotice>` re-sends the confirmation email. Same shape as the original commit 4 plan, simpler because no redirect plumbing.
 
-**Wiring:**
+**Files modified:**
 
-- `web/src/components/auth/SignInForm/SignInForm.tsx` — after `signIn()` throws, inspect the error: if it's Supabase's `email_not_confirmed` (check `error.code === 'email_not_confirmed'` — verified against `auth-js/src/lib/error-codes.ts`; `AuthApiError` has a string `code` property per `auth-js/src/lib/errors.ts`), set local `pending` state and render `<CheckEmailNotice email={email} onVerified={handleVerified} onResend={() => auth.resendConfirmation(email, { redirect })} />` _in place of the existing `<Card>`_ (the outer page wrapper stays, same shape as commit 3's `SignUpForm` wiring), where `redirect` is the current route's `redirect` search param (same source as today's signin redirect handling at `SignInForm.tsx:33-37`). `handleVerified` here navigates to redirect-or-`/leagues`. For any other error, fall through to the existing `<InlineError>` at `SignInForm.tsx:39-43`. The Resend's `redirect` override means the resent email's magic link will encode the signin-time destination rather than the (potentially different) signup-time one.
+- `web/src/contexts/AuthContext.tsx` + `.ts` — add `resendConfirmation(email: string, options?: { emailRedirectTo?: string }): Promise<void>` to interface and implementation. Calls `supabase.auth.resend({ type: 'signup', email, options: { emailRedirectTo: options?.emailRedirectTo } })`. Throws on error.
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — reintroduce `<CardFooter>` with a Resend button gated on the existing `onResend` prop. Use `<LoadingButton>` for loading state. Use `<LiveRegion>` to announce success ("New confirmation email sent."). Use `<InlineError>` for failures, with friendly copy for `over_email_send_rate_limit` ("Please wait a moment before requesting another email.") and a generic message for other errors. Local `resendStatus: 'idle' | 'sending'` mirrors the original commit 4 design.
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` — pass `onResend={() => resendConfirmation(email, { emailRedirectTo })}` to `<CheckEmailNotice>`, reusing the same `emailRedirectTo` value computed for the initial `signUp` call.
 
 **Tests:**
 
-- `SignInForm.test.tsx`:
-  - Mocked `signIn` rejects with `email_not_confirmed` → `<CheckEmailNotice>` rendered, no navigation
-  - Mocked `signIn` rejects with any other error → existing `<InlineError>` behavior preserved
-  - On `<CheckEmailNotice>` `onVerified`, navigation runs with signin destination logic
-  - Resend from this context passes the signin-time `redirect` param to `resendConfirmation`
-- `web/src/tests/integration/signin-unconfirmed.integration.test.tsx` — frontend integration (real router over inline route-tree mirror; mock only the Supabase SDK):
-  - Mount at `/sign-in?redirect=/leagues/123`, mock `supabase.auth.signInWithPassword` to reject with `{ code: 'email_not_confirmed' }`, submit the form, assert `<CheckEmailNotice>` renders (proves the error-code → pending-state wiring in the real router context).
-  - Continue the same flow: mock `supabase.auth.verifyOtp` to resolve successfully, type 6 digits into the OTP input, assert navigation lands at `/leagues/123` (proves the signin-time `redirect` param threads through `handleVerified` rather than falling back to `/leagues`).
+- `web/src/contexts/AuthContext.test.tsx` — `resendConfirmation` calls `supabase.auth.resend` with `{ type: 'signup', email, options: { emailRedirectTo } }`. With no `emailRedirectTo`, the options object's `emailRedirectTo` is `undefined`. Throws on Supabase error.
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx` — clicking Resend fires `onResend`. Loading state visible during the await. Success announced via `LiveRegion`. Generic error renders via `<InlineError>`. Rate-limit error renders the friendly copy.
+- `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — Resend passes the current `emailRedirectTo` (with `search.redirect` threading) to `resendConfirmation`.
+- `web/src/tests/integration/signup-resend.integration.test.tsx` — new file. Mount sign-up flow at `/sign-up?redirect=/leagues/123`, submit, click Resend, assert `supabase.auth.resend` was called with the expected args. Same setup but with `supabase.auth.resend` mocked to return `{ error: { code: 'over_email_send_rate_limit' } }` → assert friendly rate-limit copy renders.
 
 **Verification:**
 
-- Manual: sign up, do NOT click the email link / enter the OTP, navigate to `/sign-in`, attempt sign-in with the unconfirmed credentials, verify pending UI appears with working OTP entry + Resend
-- All test commands green
+1. `npm run web:test` + lint/format/build green.
+2. Manual: sign up → click Resend → second email arrives in Mailpit. Either email's link OR the latest OTP from either email completes verification. Rapid-fire Resend (more than the configured rate limit) → friendly rate-limit message renders.
 
 ---
 
-### Commit 6 — E2E coverage for magic-link and OTP signup paths
-
-**Goal:** Cross-system assertion that the wired-up flow from commit 3 actually works end-to-end through a real browser, against the local Supabase + Mailpit stack.
-
-**New fixture** (`e2e/fixtures/mailpit.ts`):
-
-- Helper functions: `searchByRecipient(email)`, `getMessage(id)`, `clearAll()`. Thin HTTP wrappers, single-shot — no internal retry/polling. Targets `http://127.0.0.1:54424` (e2e Mailpit).
-- **Waiting for an email to arrive:** callsites wrap `searchByRecipient` in `expect.poll(...).toHaveProperty('count', 1)` (Playwright's built-in polling assertion). Polling lives in test code, not the fixture, so waits are visible at the callsite, integrate with Playwright's timeout reporting, and individual tests can vary the expected count (e.g., `2` for a resend test). No `sleep`-based waits anywhere.
-- **Note on naming:** Supabase CLI replaced Inbucket with Mailpit but kept the `[inbucket]` config block and the container name `supabase_inbucket_*` for backward compatibility. The actual image is `public.ecr.aws/supabase/mailpit` (verified via `docker inspect`), and the API surface is Mailpit's, not Inbucket's.
-- **Search by recipient:** `GET /api/v1/search?query=to:<urlencoded email>` — returns newest-first. Verified shape:
-  ```json
-  {
-    "total": 15,
-    "count": 1,
-    "messages_count": 1,
-    "messages": [
-      {
-        "ID": "Vqp696v5jB9384dNn4y8Pr",
-        "From": { "Name": "Admin", "Address": "admin@email.com" },
-        "To": [{ "Name": "", "Address": "bob2@test.com" }],
-        "Subject": "Confirm your F1 Fantasy email",
-        "Created": "2026-05-10T04:29:00.864Z",
-        "Snippet": "Confirm your email Welcome to F1 Fantasy!..."
-      }
-    ]
-  }
-  ```
-- **Fetch message body:** `GET /api/v1/message/{ID}` — note singular `message`. Returns `{ ID, Text, HTML, ... }`. The `Text` body of a Supabase signup email contains both the magic link and the OTP. Verified excerpt:
+### Commit 8 — E2E coverage for magic-link and OTP signup paths
 
-  ```
-  Confirm your email ( http://127.0.0.1:54421/auth/v1/verify?token=pkce_49af69736d98ab8581cfb35402e76a84b69db32b81ec70fd4f78af8b&type=signup&redirect_to=http://localhost:5273/auth/callback )
-
-  Or enter this code in the app: *765877*
-  ```
+**Goal:** cross-system assertion that the wired-up flow works end-to-end through a real browser, against the local Supabase + Mailpit stack.
 
-  The verify URL is _Supabase's_ endpoint (port 54421 in e2e); hitting it 302s to the app callback (`http://localhost:5273/auth/callback?code=...`) which `<AuthCallback>` then exchanges for a session. The OTP is wrapped in `*…*` (markdown bold).
+**Files added:**
 
-- **Per-test isolation:** `DELETE /api/v1/messages` (no body) clears all mailboxes — call from a per-test `beforeEach` so prior tests' emails don't bleed in.
-- **Port arithmetic:** 54424 = Mailpit dev port 54324 (`api/supabase/config.toml:96`, under the still-named `[inbucket]` block) + 100 per the e2e port-shift rule.
+- `e2e/fixtures/mailpit.ts` — thin HTTP wrappers. `searchByRecipient(email)` → `GET /api/v1/search?query=to:<encoded>`. `getMessage(id)` → `GET /api/v1/message/{id}`. `clearAll()` → `DELETE /api/v1/messages`. Targets `http://127.0.0.1:54424` (e2e Mailpit, dev `54324` + 100 per the port-shift convention). No internal polling — callsites wrap `searchByRecipient` in Playwright's `expect.poll(...).toHaveProperty('count', 1)` so waits are visible at the callsite and integrate with Playwright's timeout reporting.
 
-**New e2e tests** (`e2e/tests/auth.spec.ts`):
+**Files modified:**
 
-- **OTP-input selector note:** the `<OtpInput>` from commit 2 renders 6 visible slot `<div>`s overlaying a single real `<input autocomplete="one-time-code">`. Tests type the 6-digit code into the underlying input (queryable via its `aria-label`), not into individual slots — the slot `<div>`s are `aria-hidden`. This is the only commit-6-specific selector callout; everything else follows the project-wide semantic-selector discipline from `e2e/README`.
-- **Magic-link path:** fill signup form via UI → assert `<CheckEmailNotice>` appears → `expect.poll(() => mailpit.searchByRecipient(email)).toHaveProperty('count', 1)` → GET the message → regex `Text` for the verify URL → `page.goto(verifyUrl)` → assert the app shows `/create-team`.
-- **OTP path:** fill signup form → assert `<CheckEmailNotice>` appears → poll Mailpit for the message → GET it → regex `Text` for `/Or enter this code in the app: \*(\d{6})\*/` → type the 6 digits into the OTP input (the single underlying `<input>`, per the selector note above) → assert the app shows `/create-team`.
+- `e2e/tests/auth.spec.ts` — add two tests. `beforeEach` clears Mailpit.
+  - **Magic-link path:** fill signup form via UI → assert `<CheckEmailNotice>` appears → `expect.poll(() => mailpit.searchByRecipient(email)).toHaveProperty('count', 1)` → GET the message → regex `Text` for the verify URL → `page.goto(verifyUrl)` → assert the app shows `/create-team`.
+  - **OTP path:** fill signup form → assert `<CheckEmailNotice>` → poll Mailpit → GET → regex `Text` for `/Or enter this code in the app: \*(\d{6})\*/` → type the 6 digits into the underlying OTP input (queryable via its `aria-label`; the slot `<div>`s are `aria-hidden`) → assert the app shows `/create-team`.
 
 **Verification:**
 
-- `npm run e2e` green (existing suite + the two new tests)
+1. `npm run e2e` green (existing suite + the two new tests).
 
 ---
 
 ## Critical files
 
-**Modified:**
-
-- `web/src/lib/supabase.ts` (commit 1 — add `flowType: 'pkce'` and `detectSessionInUrl: false`)
-- `web/src/router.tsx` (commit 1 — add `/auth/callback` route with loader, pendingComponent, and inline errorComponent)
-- `web/src/lib/route-guards.ts` (commit 3 — `requireAuth` falls back to `supabase.auth.getSession()`)
-- `api/supabase/config.toml` (commit 3)
-- `e2e/supabase/config.toml` (commit 3)
-- `e2e/tests/_infra/config-sync.spec.ts` (commit 3 — extend ignore list with `site_url` / `additional_redirect_urls`)
-- `web/src/contexts/AuthContext.tsx` (commits 3, 4)
-- `web/src/contexts/AuthContext.ts` (commits 3, 4 — `signUp` signature gains `options?: { redirect?: string }` and returns `{ session }`)
-- `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commit 3, minor in commit 4)
-- `web/src/components/auth/SignInForm/SignInForm.tsx` (commit 5)
-- `web/src/components/OtpInput/OtpInput.tsx` (commit 2 — `onComplete` prop + `onBeforeInput` splice handler + responsive slot sizing)
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` (commit 2 — consume `onComplete` instead of `onChange + length` check)
-
-**New:**
-
-- `web/src/lib/auth-destination.ts` + `auth-destination.test.ts` (commit 1)
-- `web/src/tests/integration/auth-callback.integration.test.tsx` (commit 1)
-- `web/src/components/OtpInput/OtpInput.tsx` + `OtpInput.test.tsx` (commit 2) — custom OTP input primitive; lives at the top level of `components/` alongside other custom primitives (`LoadingButton`, `InlineError`, etc.), not in `ui/` (reserved for vendored shadcn)
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` + `.test.tsx` (commit 2; expanded in commit 4)
-- `api/supabase/templates/confirmation.html` (commit 3; includes both link and OTP from the start)
-- `web/src/tests/integration/signup-resend.integration.test.tsx` (commit 4)
-- `web/src/tests/integration/signin-unconfirmed.integration.test.tsx` (commit 5)
-- `e2e/fixtures/mailpit.ts` (commit 6)
-- New tests in `e2e/tests/auth.spec.ts` (commit 6)
+**Modified across commits 4-8:**
+
+- `api/supabase/config.toml` (commit 4)
+- `e2e/supabase/config.toml` (commit 4)
+- `e2e/tests/_infra/config-sync.spec.ts` (commit 4)
+- `web/src/lib/supabase.ts` (commit 4)
+- `web/src/router.tsx` (commits 4, 5)
+- `web/src/contexts/AuthContext.tsx` + `.ts` (commits 4, 6, 7)
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commits 4, 5, 7)
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` (commit 7)
+- `web/src/components/Layout/Layout.tsx` (commit 6)
+- `web/src/lib/route-guards.ts` — *kept*, no modifications across the rework
+
+**New across commits 4-8:**
+
+- `web/src/lib/auth-url-errors.ts` + `.test.ts` (commit 6)
+- `web/src/tests/integration/index-route.integration.test.tsx` (commit 5)
+- `web/src/tests/integration/signup-resend.integration.test.tsx` (commit 7)
+- `e2e/fixtures/mailpit.ts` (commit 8)
+- New tests in `e2e/tests/auth.spec.ts` (commit 8)
+
+**Deleted in commit 4:**
+
+- `web/src/lib/auth-destination.ts` + `.test.ts`
+- `web/src/tests/integration/auth-callback.integration.test.tsx`
 
 **Reused (existing components, no changes):**
 
-- `web/src/components/InlineError/InlineError.tsx` — error display in the auth-callback `errorComponent`, `<CheckEmailNotice>`, existing forms
-- `web/src/components/LiveRegion/LiveRegion.tsx` — screen-reader announcements
-- `web/src/components/LoadingButton/LoadingButton.tsx` — Verify and Resend button loading states
-- `web/src/hooks/useAuth.ts` — auth hook (gains `resendConfirmation` in commit 4)
+- `web/src/components/InlineError/InlineError.tsx`
+- `web/src/components/LiveRegion/LiveRegion.tsx`
+- `web/src/components/LoadingButton/LoadingButton.tsx`
+- `web/src/components/OtpInput/OtpInput.tsx`
+- `web/src/hooks/useAuth.ts`
+- `web/src/hooks/useLiveRegion.ts`
 
 ---
 
-## End-to-end verification (after all 6 commits)
+## End-to-end verification (after all commits 4-8)
 
-1. **Magic-link happy path:** Sign up with new email → see `<CheckEmailNotice>` → check Mailpit → click link → land on `/create-team` logged in
-2. **OTP happy path:** Sign up with new email → see `<CheckEmailNotice>` → check Mailpit → type 6-digit code into OTP field → land on `/create-team` logged in
-3. **Resend:** Sign up → click Resend → second email arrives in Mailpit → either email's link OR the latest OTP completes verification (older OTP is invalidated by the new send per Supabase's behavior)
-4. **Unconfirmed sign-in:** Sign up → DON'T confirm → go to `/sign-in` → submit credentials → see `<CheckEmailNotice>` → resend or OTP entry both work → land on `/leagues` (or wherever `redirect` param pointed)
-5. **Existing e2e tests:** `npm run e2e` all green (admin fixture continues working via `email_confirm: true`)
-6. **All tests + format + lint:** `npm run test:all` + `npm run web:lint` + `npm run web:format:check` + `npm run api:format:check` all green
+1. **Magic-link happy path:** Sign up with new email → `<CheckEmailNotice>` → check Mailpit → click link → land on `/create-team` logged in.
+2. **OTP happy path:** Sign up with new email → `<CheckEmailNotice>` → check Mailpit → type 6-digit code → land on `/create-team` logged in.
+3. **Cross-browser invite preservation:** Sign up from `/sign-up?redirect=/join/<token>` on Browser A → click link in Browser B → land directly at `/join/<token>` signed in.
+4. **Resend:** Sign up → click Resend → second email arrives → either email's link OR the latest OTP completes verification.
+5. **Link failure:** Click an expired/consumed link → land at `/` (or destination) with `<InlineError>` above the content carrying friendly copy; dismiss → clears.
+6. **Authed user at `/`:** Visit `/` signed in → bounce to `/leagues` (with team) or `/create-team` (without). Sign out → return to `/` → `LandingPage` renders normally.
+7. **Existing e2e tests:** `npm run e2e` all green (admin fixture continues working via `email_confirm: true`).
+8. **All tests + format + lint:** `npm run test:all` + `npm run web:lint` + `npm run web:format:check` + `npm run api:format:check` all green.
 
 ---
 
 ## Production deployment notes (post-merge, manual)
 
-- Enable Confirm Email in Supabase dashboard: Authentication → Providers → Email
-- Add `https://<prod-domain>/auth/callback` to the redirect URL allowlist
-- Configure SMTP for outbound email (currently commented out in `api/supabase/config.toml:186-194`; production must use a real provider)
-- Upload the custom confirmation template (Supabase dashboard reads templates from the dashboard in production, not from the local config file)
-- **Raise email rate limit**: `[auth.rate_limit] email_sent = 2` (per hour) at `api/supabase/config.toml:149` is sane for local dev but far too low for production. Set in the Supabase dashboard to a value appropriate for expected signup volume.
+- Enable Confirm Email in Supabase dashboard: Authentication → Providers → Email.
+- Add redirect URL allowlist entries (tightened from dev wildcards): `https://<prod-domain>/`, `https://<prod-domain>/join/**`, and any other surfaces that need preserved destinations. Wildcards are supported but should be narrowed for security in production.
+- Configure SMTP for outbound email (currently commented out in `api/supabase/config.toml:186-194`; production must use a real provider).
+- Upload the custom confirmation template (dashboard reads templates from the dashboard in production, not from the local config file).
+- Raise email rate limit: `[auth.rate_limit] email_sent = 2` per hour at `api/supabase/config.toml:149` is sane for local dev but far too low for production. Set in the Supabase dashboard to a value appropriate for expected signup volume.
+
+---
 
-## Known preexisting concern (out of scope)
+## Known preexisting concerns (out of scope)
 
-- `on_auth_user_created` trigger in `api/supabase/migrations/20260108000000_create_user_profile_trigger.sql` fires on every `INSERT` into `auth.users`, regardless of whether the user has confirmed their email. With confirmations enabled, this means `Accounts` and `UserProfiles` rows are created at signup time even if the user never confirms. Result: orphan rows accumulate from abandoned signups. Cleanup (e.g., a periodic job to remove unconfirmed users older than N days, or moving the trigger to fire only after confirmation) is out of 164's scope but should be tracked as follow-up.
-- Non-HTTP errors thrown from route loaders and `beforeLoad` guards are silently rendered to the user via `errorComponent` and never reach Sentry — `apiClient` only captures HTTP failures, and React's error-boundary path doesn't see errors caught at the route layer. The auth-callback loader works around this with manual `Sentry.captureException`, but the broader codebase-wide gap (parsing errors, schema mismatches, third-party SDK errors, runtime bugs across every data-loading route) is tracked separately in #180.
+- `on_auth_user_created` trigger in `api/supabase/migrations/20260108000000_create_user_profile_trigger.sql` fires on every `INSERT` into `auth.users` regardless of confirmation. With confirmations enabled, `Accounts` and `UserProfiles` rows are created at signup time even if the user never confirms. Result: orphan rows accumulate from abandoned signups. Cleanup (periodic job or moving the trigger to fire only after confirmation) is out of #164's scope but worth tracking as follow-up.
+- Non-HTTP errors thrown from route loaders and `beforeLoad` guards are silently rendered via `errorComponent` and never reach Sentry — `apiClient` only captures HTTP failures, and the React error-boundary path doesn't see errors caught at the route layer. The codebase-wide gap is tracked separately in #180; #164 doesn't try to solve it.
+- AuthContext's React state is a lagging mirror of Supabase's session state; the codebase has two coexisting workarounds (`requireAuth`'s `getSession()` fallback and the `isAuthTransitioning` overlay). Cleaning this up — likely by treating AuthContext as a tree-render-only mirror and having route guards consult Supabase directly — is preexisting and out of #164's scope.
+- Sign-in unconfirmed handling (when a returning unconfirmed user attempts to sign in) is not part of the rework. The original commit 5 design (reuse `<CheckEmailNotice>` for the `email_not_confirmed` error) remains valid future work; the rework's design composes with it cleanly.

From 93fa04abd2313b3e70229ff3d4bd3503c6c4ac67 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Wed, 13 May 2026 18:08:40 -0500
Subject: [PATCH 13/25] refactor(web): rework email confirmation to
 implicit-flow defaults

Replace the PKCE + /auth/callback infrastructure with Supabase's
implicit-flow defaults so the SDK detects the URL fragment and
establishes the session on whatever page the email link lands on.

- supabase client: drop flowType/detectSessionInUrl overrides
- router: delete authCallbackRoute, its Zod schema, and orphaned imports
- AuthContext.signUp: option shape becomes { emailRedirectTo } and
  passes through to Supabase verbatim; default is \${origin}/
- SignUpForm: hardcode emailRedirectTo to \${origin}/ for this commit
  (commit 5 makes it dynamic); navigate to search.redirect ?? '/' on
  typed-OTP verify, letting indexRoute.beforeLoad own the routing call
- delete auth-destination helper + auth-callback integration test
- relax local redirect allowlist to a wildcard host; production
  allowlist is managed in the Supabase dashboard

Plan: docs/plans/164-email-confirmation-signup.md commit 4.
---
 api/supabase/config.toml                      |   5 +-
 docs/plans/164-email-confirmation-signup.md   |  12 +-
 e2e/supabase/config.toml                      |   5 +-
 .../auth/SignUpForm/SignUpForm.test.tsx       |  23 +-
 .../components/auth/SignUpForm/SignUpForm.tsx |   6 +-
 web/src/contexts/AuthContext.test.tsx         |  14 +-
 web/src/contexts/AuthContext.ts               |   2 +-
 web/src/contexts/AuthContext.tsx              |   6 +-
 web/src/lib/auth-destination.test.ts          |  25 --
 web/src/lib/auth-destination.ts               |   8 -
 web/src/lib/supabase.test.ts                  |   7 +-
 web/src/lib/supabase.ts                       |   8 +-
 web/src/router.tsx                            |  78 ------
 .../auth-callback.integration.test.tsx        | 225 ------------------
 14 files changed, 50 insertions(+), 374 deletions(-)
 delete mode 100644 web/src/lib/auth-destination.test.ts
 delete mode 100644 web/src/lib/auth-destination.ts
 delete mode 100644 web/src/tests/integration/auth-callback.integration.test.tsx

diff --git a/api/supabase/config.toml b/api/supabase/config.toml
index d9710cf..f47e879 100644
--- a/api/supabase/config.toml
+++ b/api/supabase/config.toml
@@ -121,8 +121,9 @@ enabled = true
 # The base URL of your website. Used as an allow-list for redirects and for constructing URLs used
 # in emails.
 site_url = "http://localhost:5173"
-# A list of *exact* URLs that auth providers are permitted to redirect to post authentication.
-additional_redirect_urls = ["http://localhost:5173/auth/callback"]
+# A list of URLs that auth providers are permitted to redirect to post
+# authentication. Wildcard supported.
+additional_redirect_urls = ["http://localhost:5173/**"]
 # How long tokens are valid for, in seconds. Defaults to 3600 (1 hour), maximum 604,800 (1 week).
 jwt_expiry = 604800
 # Path to JWT signing key. DO NOT commit your signing keys file to git.
diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index 7e63b3d..f350f32 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -90,13 +90,13 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 **Files modified:**
 
 - `api/supabase/templates/confirmation.html` — **no change in this commit**. The user customized this template (structure, copy, styling) and committed those customizations in `de592bc`. The only uncommitted edit was the token_hash URL surgery on the link `href`, which the prerequisite `git restore .` step reverts automatically. After `git restore .` the template is already in the correct state for the new design (link `href = {{ .ConfirmationURL }}`). Do not regenerate or replace the file.
-- `api/supabase/config.toml` — `additional_redirect_urls = ["http://localhost:5173/**"]`. Add a code comment noting that production must tighten to specific patterns.
+- `api/supabase/config.toml` — `additional_redirect_urls = ["http://localhost:5173/**"]`. Keep the comment minimal (this file is local-CLI only; the production allowlist is configured in the Supabase dashboard, covered in "Production deployment notes" below).
 - `e2e/supabase/config.toml` — `additional_redirect_urls = ["http://localhost:5273/**"]`.
 - `e2e/tests/_infra/config-sync.spec.ts` — extend `IGNORED_KEY_RE` to ignore `site_url` and `additional_redirect_urls` (the wildcard hosts differ between dev and e2e). This part survives from the old commit 3.
 - `web/src/lib/supabase.ts` — `createClient(url, key)` with no options. No `flowType`, no `detectSessionInUrl`.
 - `web/src/router.tsx` — delete `authCallbackRoute` declaration, `authCallbackSearchSchema`, its entry in `rootRoute.addChildren`, and any related imports (`Sentry`, `Link` if only used there, etc.). Leave `requireAuth`'s fallback intact.
 - `web/src/contexts/AuthContext.tsx` + `.ts` — `signUp` signature becomes `signUp(email, password, additionalData, options?: { emailRedirectTo?: string })`. Default: `emailRedirectTo: ${window.location.origin}/`. The implementation passes `options?.emailRedirectTo` straight through to `supabase.auth.signUp`'s options.
-- `web/src/components/auth/SignUpForm/SignUpForm.tsx` — remove `getPostSignupDestination` import and usage. Compute `emailRedirectTo` as `${window.location.origin}/` (hardcoded for this commit; commit 5 makes it dynamic). For the typed-OTP `onVerified` navigation in the same browser, navigate to `search.redirect ?? '/create-team'` using the existing React state.
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` — remove `getPostSignupDestination` import and usage. Compute `emailRedirectTo` as `${window.location.origin}/` (hardcoded for this commit; commit 5 makes it dynamic). For the typed-OTP `onVerified` navigation in the same browser, navigate to `search.redirect ?? '/'` using the existing React state — let `indexRoute.beforeLoad` (added in commit 5) handle the actual routing decision rather than hardcoding `/create-team` here.
 
 **Files deleted:**
 
@@ -115,7 +115,7 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 
 1. `cd api/supabase && supabase stop && supabase start` and the e2e equivalent to pick up config changes.
 2. `npm run web:test` + `npm run web:lint` + `npm run web:format:check` + `npm run web:build` green.
-3. Manual: signup with a fresh email → `<CheckEmailNotice>` appears → Mailpit (`http://127.0.0.1:54324`) shows the email → clicking the magic link auto-establishes session and lands the user at `${origin}/` (visually: marketing content inside the authenticated app shell — fixed in commit 5). Typing the OTP code → `verifyOtp` succeeds → navigate to `/create-team`.
+3. Manual: signup with a fresh email → `<CheckEmailNotice>` appears → Mailpit (`http://127.0.0.1:54324`) shows the email → clicking the magic link auto-establishes session and lands the user at `${origin}/` (visually: marketing content inside the authenticated app shell — fixed in commit 5). Typing the OTP code → `verifyOtp` succeeds → navigate to `${origin}/` (same visual state as the magic-link path; fixed in commit 5).
 4. `npm run e2e` green (the admin-API fixture continues to bypass email via `email_confirm: true`).
 
 ---
@@ -145,17 +145,17 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 
   ```typescript
   const search = useSearch({ from: '/sign-up' });
-  const destination = search.redirect ?? '/create-team';
+  const destination = search.redirect ?? '/';
   const emailRedirectTo = `${window.location.origin}${destination}`;
   ```
 
   Pass `emailRedirectTo` into `signUp({ emailRedirectTo })`. Use `destination` for the typed-OTP `onVerified` navigate call.
 
-  *Note:* `'/create-team'` is the in-browser default because the React state for `onVerified` runs in the same tab the user signed up from; `requireNoTeam` on `/create-team` bounces users who already have teams to `/leagues`. The `emailRedirectTo` default differs by one path segment (`/`) because the email's magic link may open in a different browser where the route guards take over.
+  Default is `/` (not `/create-team`) so the auth-flow code carries no feature knowledge. `indexRoute.beforeLoad` is the single home for "where does a signed-in user land" — both the magic-link path (different browser possible) and the typed-OTP path (same browser) funnel through it.
 
 **Tests:**
 
-- `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — assert `signUp` called with `emailRedirectTo: ${origin}/create-team` when no `search.redirect`; assert `emailRedirectTo: ${origin}/leagues/123` when `search.redirect = '/leagues/123'`. Assert typed-OTP `onVerified` navigates to the same destination.
+- `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — assert `signUp` called with `emailRedirectTo: ${origin}/` when no `search.redirect`; assert `emailRedirectTo: ${origin}/leagues/123` when `search.redirect = '/leagues/123'`. Assert typed-OTP `onVerified` navigates to the same destination.
 - `web/src/tests/integration/index-route.integration.test.tsx` — new file. Mount a per-test route tree with `indexRoute`, the authed/no-team and authed/with-team layout routes, and `LandingPage`. Assert: unauthed user sees `LandingPage` at `/`; authed-no-team user redirects to `/create-team`; authed-with-team user redirects to `/leagues`. Mirrors the pattern in `account.integration.test.tsx`.
 
 **Verification:**
diff --git a/e2e/supabase/config.toml b/e2e/supabase/config.toml
index 8f9338a..fa31a39 100644
--- a/e2e/supabase/config.toml
+++ b/e2e/supabase/config.toml
@@ -124,8 +124,9 @@ enabled = true
 # The base URL of your website. Used as an allow-list for redirects and for constructing URLs used
 # in emails.
 site_url = "http://localhost:5273"
-# A list of *exact* URLs that auth providers are permitted to redirect to post authentication.
-additional_redirect_urls = ["http://localhost:5273/auth/callback"]
+# A list of URLs that auth providers are permitted to redirect to post
+# authentication. Wildcard supported.
+additional_redirect_urls = ["http://localhost:5273/**"]
 # How long tokens are valid for, in seconds. Defaults to 3600 (1 hour), maximum 604,800 (1 week).
 jwt_expiry = 604800
 # Path to JWT signing key. DO NOT commit your signing keys file to git.
diff --git a/web/src/components/auth/SignUpForm/SignUpForm.test.tsx b/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
index 34212ce..cfad84f 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
@@ -187,7 +187,28 @@ describe('SignUpForm', () => {
     fireEvent.click(screen.getByRole('button', { name: /sign up/i }));
 
     await waitFor(() => {
-      expect(mockNavigate).toHaveBeenCalledWith({ to: '/create-team' });
+      expect(mockNavigate).toHaveBeenCalledWith({ to: '/' });
+    });
+  });
+
+  it('passes emailRedirectTo for the site origin into signUp', async () => {
+    mockSignUp.mockResolvedValueOnce({ session: mockSession });
+    setup();
+    fireEvent.change(screen.getByLabelText(/display name/i), { target: { value: 'Test User' } });
+    fireEvent.change(screen.getByLabelText(/email/i), { target: { value: 'test@example.com' } });
+    fireEvent.change(screen.getByLabelText(/^password$/i), { target: { value: 'password123' } });
+    fireEvent.change(screen.getByLabelText(/confirm password/i), {
+      target: { value: 'password123' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /sign up/i }));
+
+    await waitFor(() => {
+      expect(mockSignUp).toHaveBeenCalledWith(
+        'test@example.com',
+        'password123',
+        { displayName: 'Test User' },
+        { emailRedirectTo: `${window.location.origin}/` },
+      );
     });
   });
 });
diff --git a/web/src/components/auth/SignUpForm/SignUpForm.tsx b/web/src/components/auth/SignUpForm/SignUpForm.tsx
index bd7c247..8a10109 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.tsx
@@ -8,7 +8,6 @@ import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { useAuth } from '@/hooks/useAuth';
 import { useLiveRegion } from '@/hooks/useLiveRegion';
-import { getPostSignupDestination } from '@/lib/auth-destination';
 import { Link, useNavigate, useSearch } from '@tanstack/react-router';
 import { type FormEvent, useState } from 'react';
 
@@ -23,10 +22,11 @@ export function SignUpForm() {
   const { signUp, startAuthTransition, completeAuthTransition } = useAuth();
   const navigate = useNavigate();
   const search = useSearch({ from: '/sign-up' });
+  const destination = search.redirect ?? '/';
 
   const completeSignUp = async () => {
     startAuthTransition();
-    await navigate({ to: getPostSignupDestination(search.redirect) });
+    await navigate({ to: destination });
     completeAuthTransition();
   };
 
@@ -75,7 +75,7 @@ export function SignUpForm() {
         email,
         password,
         { displayName },
-        { redirect: search.redirect },
+        { emailRedirectTo: `${window.location.origin}/` },
       );
 
       if (!session) {
diff --git a/web/src/contexts/AuthContext.test.tsx b/web/src/contexts/AuthContext.test.tsx
index 107acc9..efab5a6 100644
--- a/web/src/contexts/AuthContext.test.tsx
+++ b/web/src/contexts/AuthContext.test.tsx
@@ -29,7 +29,7 @@ vi.mock('../services/userProfileService', () => ({
 }));
 
 // Test component that consumes the auth context
-function TestComponent({ signUpOptions }: { signUpOptions?: { redirect?: string } } = {}) {
+function TestComponent({ signUpOptions }: { signUpOptions?: { emailRedirectTo?: string } } = {}) {
   const { user, session, loading, signIn, signUp, signOut } = useAuth();
 
   const handleSignIn = async () => {
@@ -253,20 +253,22 @@ describe('AuthProvider', () => {
           data: {
             displayName: 'Test User',
           },
-          emailRedirectTo: `${window.location.origin}/auth/callback`,
+          emailRedirectTo: `${window.location.origin}/`,
         },
       });
     });
 
-    it('should forward the redirect option into emailRedirectTo', async () => {
+    it('forwards the emailRedirectTo option verbatim to supabase.auth.signUp', async () => {
       vi.mocked(supabase.auth.signUp).mockResolvedValue({
         data: { user: mockUser, session: mockSession },
         error: null,
       });
 
+      const customEmailRedirectTo = `${window.location.origin}/join/abc123`;
+
       render(
         <AuthProvider>
-          <TestComponent signUpOptions={{ redirect: '/leagues/123' }} />
+          <TestComponent signUpOptions={{ emailRedirectTo: customEmailRedirectTo }} />
         </AuthProvider>,
       );
 
@@ -275,7 +277,7 @@ describe('AuthProvider', () => {
       expect(supabase.auth.signUp).toHaveBeenCalledWith(
         expect.objectContaining({
           options: expect.objectContaining({
-            emailRedirectTo: `${window.location.origin}/auth/callback?redirect=${encodeURIComponent('/leagues/123')}`,
+            emailRedirectTo: customEmailRedirectTo,
           }),
         }),
       );
@@ -305,7 +307,7 @@ describe('AuthProvider', () => {
           data: {
             displayName: 'Test User',
           },
-          emailRedirectTo: `${window.location.origin}/auth/callback`,
+          emailRedirectTo: `${window.location.origin}/`,
         },
       });
     });
diff --git a/web/src/contexts/AuthContext.ts b/web/src/contexts/AuthContext.ts
index e268bb9..80af96e 100644
--- a/web/src/contexts/AuthContext.ts
+++ b/web/src/contexts/AuthContext.ts
@@ -12,7 +12,7 @@ export interface AuthContextType {
     email: string,
     password: string,
     additionalData: CreateProfileData,
-    options?: { redirect?: string },
+    options?: { emailRedirectTo?: string },
   ) => Promise<{ session: Session | null }>;
   signOut: () => Promise<void>;
   startAuthTransition: () => void;
diff --git a/web/src/contexts/AuthContext.tsx b/web/src/contexts/AuthContext.tsx
index 6c13c72..d65363d 100644
--- a/web/src/contexts/AuthContext.tsx
+++ b/web/src/contexts/AuthContext.tsx
@@ -43,15 +43,13 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     email: string,
     password: string,
     additionalData: CreateProfileData,
-    options?: { redirect?: string },
+    options?: { emailRedirectTo?: string },
   ) => {
     if (!additionalData.displayName?.trim()) {
       throw new Error('Display name is required');
     }
 
-    const emailRedirectTo = options?.redirect
-      ? `${window.location.origin}/auth/callback?redirect=${encodeURIComponent(options.redirect)}`
-      : `${window.location.origin}/auth/callback`;
+    const emailRedirectTo = options?.emailRedirectTo ?? `${window.location.origin}/`;
 
     const { data, error } = await supabase.auth.signUp({
       email,
diff --git a/web/src/lib/auth-destination.test.ts b/web/src/lib/auth-destination.test.ts
deleted file mode 100644
index 873b384..0000000
--- a/web/src/lib/auth-destination.test.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { getPostSignupDestination } from './auth-destination';
-
-describe('getPostSignupDestination', () => {
-  it('returns the redirect param when provided', () => {
-    expect(getPostSignupDestination('/leagues')).toBe('/leagues');
-  });
-
-  it('returns the redirect param for nested paths', () => {
-    expect(getPostSignupDestination('/leagues/123')).toBe('/leagues/123');
-  });
-
-  it('falls back to /create-team when redirect is undefined', () => {
-    expect(getPostSignupDestination(undefined)).toBe('/create-team');
-  });
-
-  it('falls back to /create-team when redirect is omitted', () => {
-    expect(getPostSignupDestination()).toBe('/create-team');
-  });
-
-  it('falls back to /create-team when redirect is an empty string', () => {
-    expect(getPostSignupDestination('')).toBe('/create-team');
-  });
-});
diff --git a/web/src/lib/auth-destination.ts b/web/src/lib/auth-destination.ts
deleted file mode 100644
index 68d8401..0000000
--- a/web/src/lib/auth-destination.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-const DEFAULT_POST_SIGNUP_DESTINATION = '/create-team';
-
-export function getPostSignupDestination(redirectParam?: string): string {
-  if (redirectParam) {
-    return redirectParam;
-  }
-  return DEFAULT_POST_SIGNUP_DESTINATION;
-}
diff --git a/web/src/lib/supabase.test.ts b/web/src/lib/supabase.test.ts
index 114d0be..af07111 100644
--- a/web/src/lib/supabase.test.ts
+++ b/web/src/lib/supabase.test.ts
@@ -77,11 +77,6 @@ describe('supabase module initialization', () => {
 
     await import('./supabase');
 
-    expect(createClient).toHaveBeenCalledWith('https://myproject.supabase.co', 'my-anon-key', {
-      auth: {
-        flowType: 'pkce',
-        detectSessionInUrl: false,
-      },
-    });
+    expect(createClient).toHaveBeenCalledWith('https://myproject.supabase.co', 'my-anon-key');
   });
 });
diff --git a/web/src/lib/supabase.ts b/web/src/lib/supabase.ts
index 3b5b27f..48eab95 100644
--- a/web/src/lib/supabase.ts
+++ b/web/src/lib/supabase.ts
@@ -11,10 +11,4 @@ if (!supabaseAnonKey) {
   throw new Error('Missing required environment variable: VITE_SUPABASE_ANON_KEY');
 }
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
-  auth: {
-    flowType: 'pkce',
-    // Route loaders own URL code exchange; auto-detect would race them.
-    detectSessionInUrl: false,
-  },
-});
+export const supabase = createClient(supabaseUrl, supabaseAnonKey);
diff --git a/web/src/router.tsx b/web/src/router.tsx
index 5576977..cdac3aa 100644
--- a/web/src/router.tsx
+++ b/web/src/router.tsx
@@ -2,7 +2,6 @@ import { Account } from '@/components/Account/Account';
 import { CreateTeam } from '@/components/CreateTeam/CreateTeam';
 import { ErrorBoundary } from '@/components/ErrorBoundary/ErrorBoundary';
 import { ErrorFallback } from '@/components/ErrorBoundary/ErrorFallback';
-import { InlineError } from '@/components/InlineError/InlineError';
 import { LandingPage } from '@/components/LandingPage/LandingPage';
 import { Layout } from '@/components/Layout/Layout';
 import { League } from '@/components/League/League';
@@ -10,13 +9,10 @@ import { LeagueList } from '@/components/LeagueList/LeagueList';
 import { MyTeamRoute, TeamRoute } from '@/components/Team/Team';
 import { SignInForm } from '@/components/auth/SignInForm/SignInForm';
 import { SignUpForm } from '@/components/auth/SignUpForm/SignUpForm';
-import { Button } from '@/components/ui/button';
 import type { Team as TeamType } from '@/contracts/Team';
 import type { UserProfile } from '@/contracts/UserProfile';
-import { getPostSignupDestination } from '@/lib/auth-destination';
 import { requireAuth, requireNoTeam, requireTeam } from '@/lib/route-guards';
 import type { RouterContext } from '@/lib/router-context';
-import { supabase } from '@/lib/supabase';
 import { getAvailableLeagues, getLeagueById, getMyLeagues } from '@/services/leagueService';
 import { getLeagueStandings } from '@/services/standingsService';
 import { getMyTeam, getTeamById } from '@/services/teamService';
@@ -24,7 +20,6 @@ import { userProfileService } from '@/services/userProfileService';
 import * as Sentry from '@sentry/react';
 import {
   ErrorComponent,
-  Link,
   Outlet,
   createRootRouteWithContext,
   createRoute,
@@ -97,22 +92,6 @@ const redirectSearchSchema = z.object({
     .catch(undefined),
 });
 
-/**
- * Zod schema for validating the /auth/callback search params.
- *
- * The PKCE flow returns a `code` param from Supabase that must be exchanged for
- * a session. `redirect` is forwarded through the email link so the user lands
- * on the intended destination after confirmation.
- */
-const authCallbackSearchSchema = z.object({
-  code: z.string().optional().catch(undefined),
-  redirect: z
-    .string()
-    .refine((url) => url.startsWith('/'), 'Redirect must be an internal path')
-    .optional()
-    .catch(undefined),
-});
-
 /**
  * Root route with context - wraps all routes in the application.
  *
@@ -244,62 +223,6 @@ const signUpRoute = createRoute({
   errorComponent: ({ error }) => <ErrorComponent error={error} />,
 });
 
-/**
- * Auth callback route - public landing page for PKCE / magic-link returns.
- *
- * Supabase appends `code` (and optionally the forwarded `redirect`) to this URL
- * when the user clicks a confirmation link. The loader exchanges the code for a
- * session and throws a `redirect` to the post-confirmation destination. On any
- * failure (missing code, expired/consumed code, network error) the loader
- * captures to Sentry and rethrows so the `errorComponent` can render the
- * back-to-sign-in affordance.
- *
- * @type {import('@tanstack/react-router').Route}
- */
-const authCallbackRoute = createRoute({
-  getParentRoute: () => rootRoute,
-  path: '/auth/callback',
-  validateSearch: authCallbackSearchSchema,
-  loaderDeps: ({ search }) => ({ code: search.code, redirect: search.redirect }),
-  loader: async ({ deps }) => {
-    try {
-      if (!deps.code) {
-        throw new Error('Missing confirmation code');
-      }
-      const { error } = await supabase.auth.exchangeCodeForSession(deps.code);
-      if (error) throw error;
-    } catch (err) {
-      const captured = err instanceof Error ? err : new Error('Auth callback failed');
-      Sentry.captureException(captured, {
-        tags: { component: 'authCallbackRoute', operation: 'exchangeCodeForSession' },
-      });
-      throw captured;
-    }
-
-    throw redirect({ to: getPostSignupDestination(deps.redirect) });
-  },
-  pendingComponent: () => (
-    <div role="status" className="flex w-full items-center justify-center p-8 md:min-h-screen">
-      <div className="text-center">
-        <div className="border-primary mx-auto mb-4 h-8 w-8 animate-spin rounded-full border-b-2"></div>
-        <p className="text-muted-foreground">Confirming your email...</p>
-      </div>
-    </div>
-  ),
-  errorComponent: () => (
-    <div className="flex w-full items-center justify-center p-8 md:min-h-screen">
-      <div className="w-full max-w-md space-y-4">
-        <InlineError message="We couldn't confirm your email. The link may have expired or already been used." />
-        <div className="text-center">
-          <Button variant="link" asChild className="text-sm">
-            <Link to="/sign-in">Back to sign in</Link>
-          </Button>
-        </div>
-      </div>
-    </div>
-  ),
-});
-
 /**
  * Join invite route - public route for previewing and joining leagues via invite link.
  *
@@ -785,7 +708,6 @@ const routeTree = rootRoute.addChildren([
   indexRoute,
   signInRoute,
   signUpRoute,
-  authCallbackRoute,
   joinInviteRoute,
   authenticatedLayoutRoute.addChildren([
     accountRoute,
diff --git a/web/src/tests/integration/auth-callback.integration.test.tsx b/web/src/tests/integration/auth-callback.integration.test.tsx
deleted file mode 100644
index 79cad33..0000000
--- a/web/src/tests/integration/auth-callback.integration.test.tsx
+++ /dev/null
@@ -1,225 +0,0 @@
-import { InlineError } from '@/components/InlineError/InlineError';
-import { Button } from '@/components/ui/button';
-import { getPostSignupDestination } from '@/lib/auth-destination';
-import type { RouterContext } from '@/lib/router-context';
-import { supabase } from '@/lib/supabase';
-import {
-  buildStubRoute,
-  createBaseRouterContext,
-  createUnauthAuth,
-  renderWithRouter,
-} from '@/tests/test-utils';
-import * as Sentry from '@sentry/react';
-import {
-  Link,
-  Outlet,
-  createRootRouteWithContext,
-  createRoute,
-  redirect,
-} from '@tanstack/react-router';
-import { screen } from '@testing-library/react';
-import type { MockedFunction } from 'vitest';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { z } from 'zod';
-
-// Supabase is a third party we don't own — stub its client per the testing
-// strategy ("Stub third parties you don't own"). The auth.exchangeCodeForSession
-// call talks to Supabase's auth server, not our API, so MSW can't intercept it.
-vi.mock('@/lib/supabase', () => ({
-  supabase: {
-    auth: {
-      exchangeCodeForSession: vi.fn(),
-    },
-  },
-}));
-
-vi.mock('@sentry/react', () => ({
-  captureException: vi.fn(),
-}));
-
-const authCallbackSearchSchema = z.object({
-  code: z.string().optional().catch(undefined),
-  redirect: z
-    .string()
-    .refine((url) => url.startsWith('/'), 'Redirect must be an internal path')
-    .optional()
-    .catch(undefined),
-});
-
-// Mirrors `authCallbackRoute` from `router.tsx`. Per the integration-test
-// convention, production routes aren't exported so the route under test is
-// rebuilt inline — only what the test needs to mount.
-function buildAuthCallbackRouteTree() {
-  const rootRoute = createRootRouteWithContext<RouterContext>()({
-    component: () => <Outlet />,
-  });
-
-  const authCallbackRoute = createRoute({
-    getParentRoute: () => rootRoute,
-    path: '/auth/callback',
-    validateSearch: authCallbackSearchSchema,
-    loaderDeps: ({ search }) => ({ code: search.code, redirect: search.redirect }),
-    loader: async ({ deps }) => {
-      try {
-        if (!deps.code) {
-          throw new Error('Missing confirmation code');
-        }
-        const { error } = await supabase.auth.exchangeCodeForSession(deps.code);
-        if (error) throw error;
-      } catch (err) {
-        const captured = err instanceof Error ? err : new Error('Auth callback failed');
-        Sentry.captureException(captured, {
-          tags: { component: 'authCallbackRoute', operation: 'exchangeCodeForSession' },
-        });
-        throw captured;
-      }
-      throw redirect({ to: getPostSignupDestination(deps.redirect) });
-    },
-    errorComponent: () => (
-      <div className="flex w-full items-center justify-center p-8 md:min-h-screen">
-        <div className="w-full max-w-md space-y-4">
-          <InlineError message="We couldn't confirm your email. The link may have expired or already been used." />
-          <div className="text-center">
-            <Button variant="link" asChild className="text-sm">
-              <Link to="/sign-in">Back to sign in</Link>
-            </Button>
-          </div>
-        </div>
-      </div>
-    ),
-  });
-
-  const createTeamStub = buildStubRoute(rootRoute, {
-    path: 'create-team',
-    heading: 'Create Team',
-  });
-
-  const leaguesStub = buildStubRoute(rootRoute, {
-    path: 'leagues',
-    heading: 'My Leagues',
-  });
-
-  const signInStub = buildStubRoute(rootRoute, {
-    path: 'sign-in',
-    heading: 'Sign In',
-  });
-
-  return rootRoute.addChildren([authCallbackRoute, createTeamStub, leaguesStub, signInStub]);
-}
-
-describe('/auth/callback', () => {
-  const exchangeMock = supabase.auth.exchangeCodeForSession as unknown as MockedFunction<
-    typeof supabase.auth.exchangeCodeForSession
-  >;
-  const captureExceptionMock = Sentry.captureException as unknown as MockedFunction<
-    typeof Sentry.captureException
-  >;
-
-  beforeEach(() => {
-    exchangeMock.mockReset();
-    captureExceptionMock.mockReset();
-  });
-
-  afterEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('exchanges the code and lands on /create-team by default', async () => {
-    exchangeMock.mockResolvedValueOnce({
-      data: { session: null, user: null },
-      error: null,
-    } as unknown as Awaited<ReturnType<typeof supabase.auth.exchangeCodeForSession>>);
-
-    renderWithRouter({
-      routeTree: buildAuthCallbackRouteTree(),
-      initialEntry: '/auth/callback?code=abc123',
-      auth: createUnauthAuth(),
-      routerContext: createBaseRouterContext(),
-    });
-
-    expect(await screen.findByRole('heading', { name: /create team/i })).toBeInTheDocument();
-    expect(exchangeMock).toHaveBeenCalledWith('abc123');
-    expect(captureExceptionMock).not.toHaveBeenCalled();
-  });
-
-  it('honors the redirect search param when present', async () => {
-    exchangeMock.mockResolvedValueOnce({
-      data: { session: null, user: null },
-      error: null,
-    } as unknown as Awaited<ReturnType<typeof supabase.auth.exchangeCodeForSession>>);
-
-    renderWithRouter({
-      routeTree: buildAuthCallbackRouteTree(),
-      initialEntry: '/auth/callback?code=abc123&redirect=%2Fleagues',
-      auth: createUnauthAuth(),
-      routerContext: createBaseRouterContext(),
-    });
-
-    expect(await screen.findByRole('heading', { name: /my leagues/i })).toBeInTheDocument();
-  });
-
-  it('renders the error UI and captures to Sentry when no code is present', async () => {
-    renderWithRouter({
-      routeTree: buildAuthCallbackRouteTree(),
-      initialEntry: '/auth/callback',
-      auth: createUnauthAuth(),
-      routerContext: createBaseRouterContext(),
-    });
-
-    expect(await screen.findByRole('alert')).toHaveTextContent(/couldn't confirm your email/i);
-    expect(screen.getByRole('link', { name: /back to sign in/i })).toHaveAttribute(
-      'href',
-      '/sign-in',
-    );
-    expect(exchangeMock).not.toHaveBeenCalled();
-    expect(captureExceptionMock).toHaveBeenCalledWith(
-      expect.objectContaining({ message: 'Missing confirmation code' }),
-      expect.objectContaining({
-        tags: expect.objectContaining({ component: 'authCallbackRoute' }),
-      }),
-    );
-  });
-
-  it('renders the error UI and captures to Sentry when supabase returns an error', async () => {
-    const supabaseError = new Error('invalid code');
-    exchangeMock.mockResolvedValueOnce({
-      data: { session: null, user: null },
-      error: supabaseError,
-    } as unknown as Awaited<ReturnType<typeof supabase.auth.exchangeCodeForSession>>);
-
-    renderWithRouter({
-      routeTree: buildAuthCallbackRouteTree(),
-      initialEntry: '/auth/callback?code=abc123',
-      auth: createUnauthAuth(),
-      routerContext: createBaseRouterContext(),
-    });
-
-    expect(await screen.findByRole('alert')).toHaveTextContent(/couldn't confirm your email/i);
-    expect(captureExceptionMock).toHaveBeenCalledWith(
-      supabaseError,
-      expect.objectContaining({
-        tags: expect.objectContaining({ component: 'authCallbackRoute' }),
-      }),
-    );
-  });
-
-  it('renders the error UI and captures to Sentry when supabase rejects', async () => {
-    const rejection = new Error('network down');
-    exchangeMock.mockRejectedValueOnce(rejection);
-
-    renderWithRouter({
-      routeTree: buildAuthCallbackRouteTree(),
-      initialEntry: '/auth/callback?code=abc123',
-      auth: createUnauthAuth(),
-      routerContext: createBaseRouterContext(),
-    });
-
-    expect(await screen.findByRole('alert')).toHaveTextContent(/couldn't confirm your email/i);
-    expect(captureExceptionMock).toHaveBeenCalledWith(
-      rejection,
-      expect.objectContaining({
-        tags: expect.objectContaining({ component: 'authCallbackRoute' }),
-      }),
-    );
-  });
-});

From 55bee8bb68ac731dfd5bfb207c98c64ee203b898 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Wed, 13 May 2026 18:14:00 -0500
Subject: [PATCH 14/25] docs(plans): drop status block and commit-heading
 markers for #164

---
 docs/plans/164-email-confirmation-signup.md | 35 +++------------------
 1 file changed, 4 insertions(+), 31 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index f350f32..30f67bf 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -1,32 +1,5 @@
 # Plan — Issue #164: Require email confirmation on signup
 
-> ## Status as of 2026-05-13 (rework — commits 1-3 superseded, commits 4-8 forward)
->
-> Commits 1-3 shipped an implementation built on PKCE flow, a custom `/auth/callback` loader, and `?redirect=` URL plumbing through `signUp`/`resendConfirmation`/`buildEmailRedirectTo`. That design was reconsidered against Supabase's documented SPA patterns and against the codebase's existing route-guard architecture; it was inventing infrastructure to deviate from the documented default and duplicating routing decisions already owned by route guards. Commits 4-8 rework it; commits 1-3 remain in branch history for traceability.
->
-> **Process for the fresh agent:**
->
-> 1. `git restore .` (or VS Code's "Discard All Changes") to drop all uncommitted work. The branch returns to commit `69351be`.
-> 2. Implement commits 4-8 in order; each is a review gate (build, lint, test, format all green) and is committed before moving to the next.
-> 3. Use conventional commit styling. No `Co-Authored-By` footer.
->
-> **What's kept from commits 1-3:**
->
-> - `<OtpInput>` and `<CheckEmailNotice>` (commit 2) — the typed-OTP path UI; unchanged.
-> - `enable_confirmations = true` in `api/supabase/config.toml` and `e2e/supabase/config.toml` (commit 3).
-> - `requireAuth`'s `supabase.auth.getSession()` fallback in `web/src/lib/route-guards.ts` (commit 3) — still load-bearing for the React/Supabase state-lag.
-> - The custom email template at `api/supabase/templates/confirmation.html` — kept as a file, but its link URL is rewritten in commit 4 to use `{{ .ConfirmationURL }}`.
->
-> **What's removed by commit 4:**
->
-> - `/auth/callback` route, its Zod schema, its loader, its `errorComponent`, its integration test.
-> - `web/src/lib/auth-destination.ts` (`getPostSignupDestination`).
-> - The `redirect: string` option threaded through `signUp` / `resendConfirmation` / `buildEmailRedirectTo`.
-> - The `token_hash` URL surgery in the email template.
-> - PKCE flow options on the Supabase client.
-
----
-
 ## Context
 
 Email confirmations are currently enabled in dev/e2e (`enable_confirmations = true` in `api/supabase/config.toml:176` and `e2e/supabase/config.toml`). The feature wires:
@@ -68,22 +41,22 @@ Email confirmations are currently enabled in dev/e2e (`enable_confirmations = tr
 
 ## Commits
 
-### Commit 1 — PKCE flow + `/auth/callback` loader (`23ca5ec`) — **SUPERSEDED**
+### Commit 1 — PKCE flow + `/auth/callback` loader (`23ca5ec`)
 
 Original design: switched the Supabase client to `flowType: 'pkce'` with `detectSessionInUrl: false`, added a `/auth/callback` route with a loader that called `exchangeCodeForSession`, and added `getPostSignupDestination` in `web/src/lib/auth-destination.ts`. Commit 4 reverts the client to defaults, deletes the route, and deletes the helper.
 
-### Commit 2 — `<OtpInput>` primitive + `<CheckEmailNotice>` component (`d4a632b`) — **KEPT**
+### Commit 2 — `<OtpInput>` primitive + `<CheckEmailNotice>` component (`d4a632b`)
 
 The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type: 'email'` (corrected from the original `'signup'` during the pivot; commit 4 keeps this corrected value).
 
-### Commit 3 — Enable confirmations + SignUpForm wiring (`de592bc`) — **PARTIALLY SUPERSEDED**
+### Commit 3 — Enable confirmations + SignUpForm wiring (`de592bc`)
 
 - **Kept by commit 4:** `enable_confirmations = true` config flip in both `api/supabase/config.toml` and `e2e/supabase/config.toml`. The custom email template file (its content gets rewritten). `requireAuth`'s `getSession()` fallback.
 - **Superseded by commit 4:** the `redirect: string` option threaded through `signUp`. The token_hash-style email template URL. The SignUpForm wiring that called `getPostSignupDestination`.
 
 ---
 
-### Commit 4 — Replace PKCE callback with implicit-flow defaults
+### Commit 4 — Replace PKCE callback with implicit-flow defaults (`93fa04a`)
 
 **Goal:** undo the PKCE/callback infrastructure and the redirect plumbing. After this commit, the email-confirmation flow works end-to-end via either path. Users land at `${origin}/` post-confirm; the `/` route has no `beforeLoad` for authed users yet (commit 5 adds it), so a signed-in user briefly sees `LandingPage` rendered inside the authenticated app shell — functional but visually unpolished. Build/lint/test all pass.
 

From abf4ed97d4040add6d27b7028351264411cba0f0 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Wed, 13 May 2026 19:19:13 -0500
Subject: [PATCH 15/25] feat(web): route authed users from / and thread sign-up
 redirect
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-in users hitting / now bounce to /leagues or /create-team via
indexRoute.beforeLoad — mirrors the existing pattern on /sign-in and
/sign-up and eliminates the marketing-page-inside-authenticated-shell
visual when users return to /.

SignUpForm threads search.redirect through emailRedirectTo so a user
signing up at /sign-up?redirect=/join/<token> on desktop can confirm
via the email link on mobile and land directly at /join/<token>
signed in. Cross-browser invite preservation falls out of this.
---
 .../auth/SignUpForm/SignUpForm.test.tsx       |  22 ++++
 .../components/auth/SignUpForm/SignUpForm.tsx |   8 +-
 web/src/router.tsx                            |   9 ++
 .../root-routing.integration.test.tsx         | 108 ++++++++++++++++++
 4 files changed, 141 insertions(+), 6 deletions(-)
 create mode 100644 web/src/tests/integration/root-routing.integration.test.tsx

diff --git a/web/src/components/auth/SignUpForm/SignUpForm.test.tsx b/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
index cfad84f..4eb3444 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
@@ -211,4 +211,26 @@ describe('SignUpForm', () => {
       );
     });
   });
+
+  it('threads search.redirect through emailRedirectTo when present', async () => {
+    mockSignUp.mockResolvedValueOnce({ session: mockSession });
+    mockUseSearch.mockReturnValue({ redirect: '/join/abc-123' });
+    setup();
+    fireEvent.change(screen.getByLabelText(/display name/i), { target: { value: 'Test User' } });
+    fireEvent.change(screen.getByLabelText(/email/i), { target: { value: 'test@example.com' } });
+    fireEvent.change(screen.getByLabelText(/^password$/i), { target: { value: 'password123' } });
+    fireEvent.change(screen.getByLabelText(/confirm password/i), {
+      target: { value: 'password123' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /sign up/i }));
+
+    await waitFor(() => {
+      expect(mockSignUp).toHaveBeenCalledWith(
+        'test@example.com',
+        'password123',
+        { displayName: 'Test User' },
+        { emailRedirectTo: `${window.location.origin}/join/abc-123` },
+      );
+    });
+  });
 });
diff --git a/web/src/components/auth/SignUpForm/SignUpForm.tsx b/web/src/components/auth/SignUpForm/SignUpForm.tsx
index 8a10109..76e48d1 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.tsx
@@ -23,6 +23,7 @@ export function SignUpForm() {
   const navigate = useNavigate();
   const search = useSearch({ from: '/sign-up' });
   const destination = search.redirect ?? '/';
+  const emailRedirectTo = `${window.location.origin}${destination}`;
 
   const completeSignUp = async () => {
     startAuthTransition();
@@ -71,12 +72,7 @@ export function SignUpForm() {
     }
 
     try {
-      const { session } = await signUp(
-        email,
-        password,
-        { displayName },
-        { emailRedirectTo: `${window.location.origin}/` },
-      );
+      const { session } = await signUp(email, password, { displayName }, { emailRedirectTo });
 
       if (!session) {
         setAwaitingConfirmation(true);
diff --git a/web/src/router.tsx b/web/src/router.tsx
index cdac3aa..d018bdd 100644
--- a/web/src/router.tsx
+++ b/web/src/router.tsx
@@ -175,7 +175,16 @@ const rootRoute = createRootRouteWithContext<RouterContext>()({
 const indexRoute = createRoute({
   getParentRoute: () => rootRoute,
   path: '/',
+  validateSearch: redirectSearchSchema,
   component: LandingPage,
+  beforeLoad: async ({ context }) => {
+    if (context.auth.user) {
+      throw redirect({
+        to: context.teamContext.hasTeam ? '/leagues' : '/create-team',
+        replace: true,
+      });
+    }
+  },
   errorComponent: ({ error }) => <ErrorComponent error={error} />,
 });
 
diff --git a/web/src/tests/integration/root-routing.integration.test.tsx b/web/src/tests/integration/root-routing.integration.test.tsx
new file mode 100644
index 0000000..396659e
--- /dev/null
+++ b/web/src/tests/integration/root-routing.integration.test.tsx
@@ -0,0 +1,108 @@
+import type { TeamContextType } from '@/contexts/TeamContext';
+import { TeamContext } from '@/contexts/TeamContext';
+import type { RouterContext } from '@/lib/router-context';
+import {
+  buildStubRoute,
+  createAuthedAuth,
+  createBaseRouterContext,
+  createTeamContext,
+  createUnauthAuth,
+  renderWithRouter,
+} from '@/tests/test-utils';
+import {
+  ErrorComponent,
+  Outlet,
+  createRootRouteWithContext,
+  createRoute,
+  redirect,
+} from '@tanstack/react-router';
+import { screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+const redirectSearchSchema = z.object({
+  redirect: z
+    .string()
+    .refine((url) => url.startsWith('/'), 'Redirect must be an internal path')
+    .optional()
+    .catch(undefined),
+});
+
+function buildRootRoutingTree(teamContextValue: TeamContextType) {
+  const rootRoute = createRootRouteWithContext<RouterContext>()({
+    component: () => (
+      <TeamContext.Provider value={teamContextValue}>
+        <Outlet />
+      </TeamContext.Provider>
+    ),
+  });
+
+  const indexRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/',
+    validateSearch: redirectSearchSchema,
+    component: () => <h1>Landing Page</h1>,
+    beforeLoad: async ({ context }) => {
+      if (context.auth.user) {
+        throw redirect({
+          to: context.teamContext.hasTeam ? '/leagues' : '/create-team',
+          replace: true,
+        });
+      }
+    },
+    errorComponent: ({ error }) => <ErrorComponent error={error} />,
+  });
+
+  const createTeamRoute = buildStubRoute(rootRoute, {
+    path: 'create-team',
+    heading: 'Create Team Page',
+  });
+  const leaguesRoute = buildStubRoute(rootRoute, {
+    path: 'leagues',
+    heading: 'Leagues Page',
+  });
+
+  return rootRoute.addChildren([indexRoute, createTeamRoute, leaguesRoute]);
+}
+
+describe('routing at /', () => {
+  it('leaves unauthenticated users at /', async () => {
+    const teamContext = createTeamContext();
+    renderWithRouter({
+      routeTree: buildRootRoutingTree(teamContext),
+      initialEntry: '/',
+      auth: createUnauthAuth(),
+      routerContext: createBaseRouterContext({ teamContext }),
+    });
+
+    expect(await screen.findByRole('heading', { name: 'Landing Page' })).toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: 'Create Team Page' })).not.toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: 'Leagues Page' })).not.toBeInTheDocument();
+  });
+
+  it('redirects authenticated users without a team to /create-team', async () => {
+    const teamContext = createTeamContext({ myTeamId: null, hasTeam: false });
+    renderWithRouter({
+      routeTree: buildRootRoutingTree(teamContext),
+      initialEntry: '/',
+      auth: createAuthedAuth(),
+      routerContext: createBaseRouterContext({ teamContext }),
+    });
+
+    expect(await screen.findByRole('heading', { name: 'Create Team Page' })).toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: 'Landing Page' })).not.toBeInTheDocument();
+  });
+
+  it('redirects authenticated users with a team to /leagues', async () => {
+    const teamContext = createTeamContext({ myTeamId: 1, hasTeam: true });
+    renderWithRouter({
+      routeTree: buildRootRoutingTree(teamContext),
+      initialEntry: '/',
+      auth: createAuthedAuth(),
+      routerContext: createBaseRouterContext({ teamContext }),
+    });
+
+    expect(await screen.findByRole('heading', { name: 'Leagues Page' })).toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: 'Landing Page' })).not.toBeInTheDocument();
+  });
+});

From 456dd6d1dae3356b79d26cc22c43deda4ca98a2f Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Wed, 13 May 2026 19:19:50 -0500
Subject: [PATCH 16/25] docs(plans): sync #164 plan with what commit 5 actually
 shipped

---
 docs/plans/164-email-confirmation-signup.md | 42 ++++++++++-----------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index 30f67bf..8e26249 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -19,23 +19,23 @@ Email confirmations are currently enabled in dev/e2e (`enable_confirmations = tr
 
 ## Decisions
 
-| Decision | Choice | Rationale |
-| --- | --- | --- |
-| Auth flow | Implicit (Supabase `createClient` defaults: `flowType: 'implicit'`, `detectSessionInUrl: true`) | Documented SPA pattern. Verified at `GoTrueClient.ts:184-194`. The PKCE flow's `signUp` writes `code_challenge` (`GoTrueClient.ts:899-924`) but `resend` does not (`2535-2574`), which broke the resend path; implicit sidesteps the asymmetry. |
-| Magic-link verification | SDK auto-detects `#access_token=...` from URL fragment during `_initialize` | No callback loader needed; `_initialize` saves the session and fires `SIGNED_IN`. On success the SDK strips the hash (`GoTrueClient.ts:3702-3703`); on failure it leaves `#error_description=...` for the app to read. |
-| Typed-OTP verification | `supabase.auth.verifyOtp({ email, token, type: 'email' })` | No alternative for typed codes. `'email'` is the type for email-confirmation OTPs from the custom template's `{{ .Token }}`. |
-| Confirmation method in email | Both magic link and OTP code | Resilient to corporate email scanners that pre-fetch links (Supabase auth issue [#1214](https://github.com/supabase/auth/issues/1214)). The custom template includes `{{ .ConfirmationURL }}` and `{{ .Token }}`. |
-| Email link construction | `{{ .ConfirmationURL }}` only | Supabase owns the URL. No template-side concatenation, no `&token_hash=` append, no requirement that `buildEmailRedirectTo` always include a query string. |
-| Callback route | None | The implicit flow's auto-detect runs against whatever URL the user lands on. No app-side loader required. |
-| Post-confirm destination | Caller of `signUp`/`resendConfirmation` passes `emailRedirectTo` directly (full URL). Default: `${origin}/`. Dynamic: `${origin}${search.redirect}` when SignUpForm was reached via a redirect param (e.g., `/sign-up?redirect=/join/<token>`). | One source of truth for "where does this user land": the `emailRedirectTo` URL itself. No parallel `?redirect=` URL parameter, no `getPostSignupDestination` helper. Route guards continue to own routing for users landing at any given URL. |
-| Cross-browser invite preservation | Encoded in `emailRedirectTo` | Supabase forwards `emailRedirectTo` verbatim through `/verify`. A user who signs up from `/join/<token>` on desktop and confirms via the email on mobile lands directly at `/join/<token>` on mobile, signed in. |
-| `/` route handling | Add `beforeLoad` that bounces authenticated users to `/create-team` or `/leagues` based on team state | Mirrors the existing pattern on `/sign-in` (`router.tsx:218-228`) and `/sign-up` (`router.tsx:240-250`). Eliminates the "marketing content rendered inside authenticated app shell" weirdness when a signed-in user lands at `/`. Single home for post-auth routing: route guards. |
-| Auth-URL error UX | `useEffect` in `AuthContext` reads `window.location.hash` on mount, parses `error` + `error_description`, sets `authUrlError` state via `mapAuthUrlError(code, description)`, strips the hash. `<Layout>` renders `<InlineError>` above `<Outlet>` when set. `clearAuthUrlError` on dismiss. | `getSession()` swallows `_initialize` errors (verified at `GoTrueClient.ts:2661-2671`); reading the URL fragment is the only way to surface them. `<InlineError>` matches `web/CLAUDE.md`'s convention for primary-flow errors (toasts are reserved for background operations). |
-| Supabase redirect allowlist | Wildcards: `http://localhost:5173/**` (dev), `http://localhost:5273/**` (e2e). Production: tightened to specific patterns per surface (`https://<prod>/`, `https://<prod>/join/**`, etc.). | Required to allow dynamic `emailRedirectTo` paths. Wildcard support confirmed in Supabase docs; `**` matches any sequence including separators. |
-| `requireAuth` `getSession()` fallback | Kept | Still load-bearing: AuthContext's React state lags Supabase's session state by one render after any auth state change. Without the fallback, freshly-confirmed users bounce back to `/` because `context.auth.user` is briefly null in `beforeLoad`. |
-| Email passing into `<CheckEmailNotice>` | React state from parent (`SignUpForm`, later `SignInForm`) | Same as the original commit 2 design. Supabase identifies the user by token; email is only for display + the typed-OTP `verifyOtp` call. No URL params (OWASP: PII shouldn't appear in URLs). |
-| Failure copy for typed-OTP | Static generic message: _"That code didn't match. Check your email for the latest one."_ | Same as the original commit 2 design. |
-| Sign-in unconfirmed handling | Deferred | Commits 4-8 do not include the SignInForm wiring for `email_not_confirmed`. The original commit 5 plan is preserved as future work but is not part of this rework. The rework focuses on getting the signup path onto the correct foundation; the signin-unconfirmed UX reuses the same `<CheckEmailNotice>` and can be added afterward without affecting the rework's design. |
+| Decision                                | Choice                                                                                                                                                                                                                                                                                       | Rationale                                                                                                                                                                                                                                                                                                                                                                      |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Auth flow                               | Implicit (Supabase `createClient` defaults: `flowType: 'implicit'`, `detectSessionInUrl: true`)                                                                                                                                                                                              | Documented SPA pattern. Verified at `GoTrueClient.ts:184-194`. The PKCE flow's `signUp` writes `code_challenge` (`GoTrueClient.ts:899-924`) but `resend` does not (`2535-2574`), which broke the resend path; implicit sidesteps the asymmetry.                                                                                                                                |
+| Magic-link verification                 | SDK auto-detects `#access_token=...` from URL fragment during `_initialize`                                                                                                                                                                                                                  | No callback loader needed; `_initialize` saves the session and fires `SIGNED_IN`. On success the SDK strips the hash (`GoTrueClient.ts:3702-3703`); on failure it leaves `#error_description=...` for the app to read.                                                                                                                                                         |
+| Typed-OTP verification                  | `supabase.auth.verifyOtp({ email, token, type: 'email' })`                                                                                                                                                                                                                                   | No alternative for typed codes. `'email'` is the type for email-confirmation OTPs from the custom template's `{{ .Token }}`.                                                                                                                                                                                                                                                   |
+| Confirmation method in email            | Both magic link and OTP code                                                                                                                                                                                                                                                                 | Resilient to corporate email scanners that pre-fetch links (Supabase auth issue [#1214](https://github.com/supabase/auth/issues/1214)). The custom template includes `{{ .ConfirmationURL }}` and `{{ .Token }}`.                                                                                                                                                              |
+| Email link construction                 | `{{ .ConfirmationURL }}` only                                                                                                                                                                                                                                                                | Supabase owns the URL. No template-side concatenation, no `&token_hash=` append, no requirement that `buildEmailRedirectTo` always include a query string.                                                                                                                                                                                                                     |
+| Callback route                          | None                                                                                                                                                                                                                                                                                         | The implicit flow's auto-detect runs against whatever URL the user lands on. No app-side loader required.                                                                                                                                                                                                                                                                      |
+| Post-confirm destination                | Caller of `signUp`/`resendConfirmation` passes `emailRedirectTo` directly (full URL). Default: `${origin}/`. Dynamic: `${origin}${search.redirect}` when SignUpForm was reached via a redirect param (e.g., `/sign-up?redirect=/join/<token>`).                                              | One source of truth for "where does this user land": the `emailRedirectTo` URL itself. No parallel `?redirect=` URL parameter, no `getPostSignupDestination` helper. Route guards continue to own routing for users landing at any given URL.                                                                                                                                  |
+| Cross-browser invite preservation       | Encoded in `emailRedirectTo`                                                                                                                                                                                                                                                                 | Supabase forwards `emailRedirectTo` verbatim through `/verify`. A user who signs up from `/join/<token>` on desktop and confirms via the email on mobile lands directly at `/join/<token>` on mobile, signed in.                                                                                                                                                               |
+| `/` route handling                      | Add `beforeLoad` that bounces authenticated users to `/create-team` or `/leagues` based on team state                                                                                                                                                                                        | Mirrors the existing pattern on `/sign-in` (`router.tsx:218-228`) and `/sign-up` (`router.tsx:240-250`). Eliminates the "marketing content rendered inside authenticated app shell" weirdness when a signed-in user lands at `/`. Single home for post-auth routing: route guards.                                                                                             |
+| Auth-URL error UX                       | `useEffect` in `AuthContext` reads `window.location.hash` on mount, parses `error` + `error_description`, sets `authUrlError` state via `mapAuthUrlError(code, description)`, strips the hash. `<Layout>` renders `<InlineError>` above `<Outlet>` when set. `clearAuthUrlError` on dismiss. | `getSession()` swallows `_initialize` errors (verified at `GoTrueClient.ts:2661-2671`); reading the URL fragment is the only way to surface them. `<InlineError>` matches `web/CLAUDE.md`'s convention for primary-flow errors (toasts are reserved for background operations).                                                                                                |
+| Supabase redirect allowlist             | Wildcards: `http://localhost:5173/**` (dev), `http://localhost:5273/**` (e2e). Production: tightened to specific patterns per surface (`https://<prod>/`, `https://<prod>/join/**`, etc.).                                                                                                   | Required to allow dynamic `emailRedirectTo` paths. Wildcard support confirmed in Supabase docs; `**` matches any sequence including separators.                                                                                                                                                                                                                                |
+| `requireAuth` `getSession()` fallback   | Kept                                                                                                                                                                                                                                                                                         | Still load-bearing: AuthContext's React state lags Supabase's session state by one render after any auth state change. Without the fallback, freshly-confirmed users bounce back to `/` because `context.auth.user` is briefly null in `beforeLoad`.                                                                                                                           |
+| Email passing into `<CheckEmailNotice>` | React state from parent (`SignUpForm`, later `SignInForm`)                                                                                                                                                                                                                                   | Same as the original commit 2 design. Supabase identifies the user by token; email is only for display + the typed-OTP `verifyOtp` call. No URL params (OWASP: PII shouldn't appear in URLs).                                                                                                                                                                                  |
+| Failure copy for typed-OTP              | Static generic message: _"That code didn't match. Check your email for the latest one."_                                                                                                                                                                                                     | Same as the original commit 2 design.                                                                                                                                                                                                                                                                                                                                          |
+| Sign-in unconfirmed handling            | Deferred                                                                                                                                                                                                                                                                                     | Commits 4-8 do not include the SignInForm wiring for `email_not_confirmed`. The original commit 5 plan is preserved as future work but is not part of this rework. The rework focuses on getting the signup path onto the correct foundation; the signin-unconfirmed UX reuses the same `<CheckEmailNotice>` and can be added afterward without affecting the rework's design. |
 
 ---
 
@@ -128,8 +128,8 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 
 **Tests:**
 
-- `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — assert `signUp` called with `emailRedirectTo: ${origin}/` when no `search.redirect`; assert `emailRedirectTo: ${origin}/leagues/123` when `search.redirect = '/leagues/123'`. Assert typed-OTP `onVerified` navigates to the same destination.
-- `web/src/tests/integration/index-route.integration.test.tsx` — new file. Mount a per-test route tree with `indexRoute`, the authed/no-team and authed/with-team layout routes, and `LandingPage`. Assert: unauthed user sees `LandingPage` at `/`; authed-no-team user redirects to `/create-team`; authed-with-team user redirects to `/leagues`. Mirrors the pattern in `account.integration.test.tsx`.
+- `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — assert `signUp` called with `emailRedirectTo: ${origin}/` when no `search.redirect`; assert `emailRedirectTo: ${origin}/join/abc-123` when `search.redirect = '/join/abc-123'`. The typed-OTP `onVerified` destination assertion is already covered by the existing "navigates to redirect path when redirect search parameter is provided" test from commit 4.
+- `web/src/tests/integration/root-routing.integration.test.tsx` — new file. Mount a per-test route tree with `indexRoute` (carrying the real `beforeLoad`) plus bare stub routes for `/create-team` and `/leagues` whose headings are the redirect-target assertion surface. The `/` component is a stub heading rather than the real `LandingPage` so marketing copy changes don't break the test. Destination routes are not parented under `_no-team` / `_authenticated/_team-required` layouts because those guards are already covered in `route-guards.integration.test.tsx`; isolating to `indexRoute.beforeLoad`'s `teamContext.hasTeam` ternary is what's new in commit 5. Assert: unauthed user stays at `/`; authed-no-team user lands at `/create-team`; authed-with-team user lands at `/leagues`.
 
 **Verification:**
 
@@ -221,12 +221,12 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 - `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commits 4, 5, 7)
 - `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` (commit 7)
 - `web/src/components/Layout/Layout.tsx` (commit 6)
-- `web/src/lib/route-guards.ts` — *kept*, no modifications across the rework
+- `web/src/lib/route-guards.ts` — _kept_, no modifications across the rework
 
 **New across commits 4-8:**
 
 - `web/src/lib/auth-url-errors.ts` + `.test.ts` (commit 6)
-- `web/src/tests/integration/index-route.integration.test.tsx` (commit 5)
+- `web/src/tests/integration/root-routing.integration.test.tsx` (commit 5)
 - `web/src/tests/integration/signup-resend.integration.test.tsx` (commit 7)
 - `e2e/fixtures/mailpit.ts` (commit 8)
 - New tests in `e2e/tests/auth.spec.ts` (commit 8)

From 0f3caaa85cf8f649be305819a1c09e87eb47affc Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Thu, 14 May 2026 08:18:15 -0500
Subject: [PATCH 17/25] docs: add commenting strategy to CLAUDE.md

Mirrors the Testing Strategy section's shape: default-to-none principle,
the test before writing, categories of comments that earn their place vs.
ones that don't, and practical heuristics. Available as a referenceable
standard for prompts like "audit comments against our commenting strategy."
---
 CLAUDE.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 231ec8b..00c142c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -142,6 +142,37 @@ Overlap is correct when each layer catches a distinct failure mode. It's waste w
 - Frontend unit/component tests: Vitest + `@testing-library/react`.
 - E2E: Playwright, small suite, runs against a prod-like build. Parallel workers with isolated users.
 
+## Commenting Strategy
+
+Default to no comment. Every comment is debt — it can rot, mislead, or distract. Write one only when the alternative is worse: a reader would otherwise misunderstand the code or spend time discovering something the comment encodes directly.
+
+### The test before writing
+
+Ask: **"Would removing this confuse a competent reader six months from now, reading the code cold?"** If no — cut it. Trust the names, the types, and the structure to carry the meaning.
+
+### When a comment earns its place
+
+- **Non-obvious WHY.** A constraint or invariant that wouldn't show up in the AST. _"Caller must hold the write lock." "API returns 200 with an error body for this case — peek at the JSON."_
+- **A surprise.** Behavior a reader would assume is a bug. _"Off-by-one is intentional — F1 rounds are 1-indexed." "We retry on 401 — auth service emits them during clock skew."_
+- **Workaround pointer.** External constraint forcing a non-obvious shape. _"Chrome bug crbug.com/123456 — drop when our floor is M120."_
+- **Domain pointer.** Spec/RFC/paper that explains the rule. _"RFC 7231 §6.4.3: 303 always GETs the target."_
+
+### When a comment doesn't
+
+- **What the code or types already say.** `// Iterate users` above a `for` loop; `// Returns 'expired' or null` above `(): Promise<'expired' | null>`. Rename, don't comment.
+- **Task context.** _"Fix for #164." "Per the design doc."_ Belongs in the commit message; rots when issues close.
+- **Historical state.** _"Was synchronous before."_ `git log` owns this; the file describes what is, not what was.
+- **Internal callers / provenance.** _"Used by SignUpForm." "Set by indexRoute.beforeLoad."_ Find-references gives you this for free; comment goes stale on the next caller.
+- **Design rationale.** _"We chose route context over AuthContext because…"_ Lives in `docs/plans/`, not the source file. The code is the chosen path; the argument is dead weight once the choice is made.
+- **Reassurance about performance/correctness of an implementation detail.** _"This is cached, so it's free to call."_ Reader doesn't need it.
+
+### Heuristics
+
+- Tempted to write _"// this X-es the Y"_ → rename instead.
+- Tempted to write _"// because Z"_ → is Z visible in the code (keep) or only in your head / the conversation / the plan (cut).
+- Watch the diff-talk smell: _"now uses," "still works," "originally was"_ narrate history, not state.
+- Read it cold. If a reader needs to know "the resend flow" or "the X migration" to parse the comment, rewrite in plain terms or delete.
+
 ## Git Commit Message Preferences
 
 - Do not include the "Generated with Claude Code" footer in commit messages or PR descriptions

From 6e7da5f3855f5f5b49d528d43b1e9b3fc16a6cb6 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Thu, 14 May 2026 08:18:29 -0500
Subject: [PATCH 18/25] feat(web): route failed confirmation links to /sign-up
 with inline error
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When Supabase's /verify rejects an email confirmation link (expired,
already-used, or invalid token), bounce the user to /sign-up and surface
a friendly message above the form. Recovery action — sign up again to
receive a new link — lives next to where it can be taken, instead of a
banner over the marketing landing page.

- web/src/lib/auth-redirect.ts: new readConfirmationLinkError() helper
  that reads supabase.auth.initialize()'s cached error result and maps
  it to 'expired' | 'generic' | null based on error.details.code.
- web/src/router.tsx: indexRoute.beforeLoad redirects to /sign-up with
  replace:true when the helper returns a code for a signed-out user.
  signUpRoute.beforeLoad calls the same helper (same cached promise) and
  returns the code as route context.
- web/src/components/auth/SignUpForm/SignUpForm.tsx: reads confirmationError
  from useRouteContext, maps to user-facing message via a small lookup,
  renders <InlineError> above the form.

Matches on the typed otp_expired code (verified in gotrue source) rather
than parsing URL hash strings. Route context (vs. AuthContext state)
keeps the message tied to the route lifecycle and avoids a cleanup
effect on SignUpForm unmount.
---
 docs/plans/164-email-confirmation-signup.md   | 69 ++++++++++++-------
 .../auth/SignUpForm/SignUpForm.test.tsx       | 28 ++++++++
 .../components/auth/SignUpForm/SignUpForm.tsx | 12 +++-
 web/src/lib/auth-redirect.test.ts             | 61 ++++++++++++++++
 web/src/lib/auth-redirect.ts                  | 12 ++++
 web/src/router.tsx                            |  5 ++
 6 files changed, 163 insertions(+), 24 deletions(-)
 create mode 100644 web/src/lib/auth-redirect.test.ts
 create mode 100644 web/src/lib/auth-redirect.ts

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index 8e26249..4d19d7f 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -30,11 +30,11 @@ Email confirmations are currently enabled in dev/e2e (`enable_confirmations = tr
 | Post-confirm destination                | Caller of `signUp`/`resendConfirmation` passes `emailRedirectTo` directly (full URL). Default: `${origin}/`. Dynamic: `${origin}${search.redirect}` when SignUpForm was reached via a redirect param (e.g., `/sign-up?redirect=/join/<token>`).                                              | One source of truth for "where does this user land": the `emailRedirectTo` URL itself. No parallel `?redirect=` URL parameter, no `getPostSignupDestination` helper. Route guards continue to own routing for users landing at any given URL.                                                                                                                                  |
 | Cross-browser invite preservation       | Encoded in `emailRedirectTo`                                                                                                                                                                                                                                                                 | Supabase forwards `emailRedirectTo` verbatim through `/verify`. A user who signs up from `/join/<token>` on desktop and confirms via the email on mobile lands directly at `/join/<token>` on mobile, signed in.                                                                                                                                                               |
 | `/` route handling                      | Add `beforeLoad` that bounces authenticated users to `/create-team` or `/leagues` based on team state                                                                                                                                                                                        | Mirrors the existing pattern on `/sign-in` (`router.tsx:218-228`) and `/sign-up` (`router.tsx:240-250`). Eliminates the "marketing content rendered inside authenticated app shell" weirdness when a signed-in user lands at `/`. Single home for post-auth routing: route guards.                                                                                             |
-| Auth-URL error UX                       | `useEffect` in `AuthContext` reads `window.location.hash` on mount, parses `error` + `error_description`, sets `authUrlError` state via `mapAuthUrlError(code, description)`, strips the hash. `<Layout>` renders `<InlineError>` above `<Outlet>` when set. `clearAuthUrlError` on dismiss. | `getSession()` swallows `_initialize` errors (verified at `GoTrueClient.ts:2661-2671`); reading the URL fragment is the only way to surface them. `<InlineError>` matches `web/CLAUDE.md`'s convention for primary-flow errors (toasts are reserved for background operations).                                                                                                |
+| Confirmation-link failure UX            | `readConfirmationLinkError()` helper (in `lib/auth-redirect.ts`) wraps `supabase.auth.initialize()`, type-guards, and returns `'expired' \| 'generic' \| null` based on `error.details?.code`. `indexRoute.beforeLoad` calls it to decide whether to redirect to `/sign-up` with `replace: true`. `signUpRoute.beforeLoad` calls it (same cached promise — free) and returns the code as route context. `SignUpForm` reads via `useRouteContext({ from: '/sign-up' })` and renders `<InlineError>` with the mapped message. | `getSession()` discards `_initialize` errors (verified at `GoTrueClient.ts:2661-2671`), but `initialize()` itself returns them — that's the documented hook. Matching on the typed `otp_expired` code (verified in gotrue `verify.go`) beats string-matching descriptions, per Supabase's own [error-handling docs](https://supabase.com/docs/guides/auth/debugging/error-codes). Route context (vs. AuthContext state) keeps AuthContext focused on session/user and avoids a cleanup-on-unmount effect; the message naturally clears on navigation away from `/sign-up`. |
 | Supabase redirect allowlist             | Wildcards: `http://localhost:5173/**` (dev), `http://localhost:5273/**` (e2e). Production: tightened to specific patterns per surface (`https://<prod>/`, `https://<prod>/join/**`, etc.).                                                                                                   | Required to allow dynamic `emailRedirectTo` paths. Wildcard support confirmed in Supabase docs; `**` matches any sequence including separators.                                                                                                                                                                                                                                |
 | `requireAuth` `getSession()` fallback   | Kept                                                                                                                                                                                                                                                                                         | Still load-bearing: AuthContext's React state lags Supabase's session state by one render after any auth state change. Without the fallback, freshly-confirmed users bounce back to `/` because `context.auth.user` is briefly null in `beforeLoad`.                                                                                                                           |
 | Email passing into `<CheckEmailNotice>` | React state from parent (`SignUpForm`, later `SignInForm`)                                                                                                                                                                                                                                   | Same as the original commit 2 design. Supabase identifies the user by token; email is only for display + the typed-OTP `verifyOtp` call. No URL params (OWASP: PII shouldn't appear in URLs).                                                                                                                                                                                  |
-| Failure copy for typed-OTP              | Static generic message: _"That code didn't match. Check your email for the latest one."_                                                                                                                                                                                                     | Same as the original commit 2 design.                                                                                                                                                                                                                                                                                                                                          |
+| Failure message for typed-OTP           | Static generic message: _"That code didn't match. Check your email for the latest one."_                                                                                                                                                                                                     | Same as the original commit 2 design.                                                                                                                                                                                                                                                                                                                                          |
 | Sign-in unconfirmed handling            | Deferred                                                                                                                                                                                                                                                                                     | Commits 4-8 do not include the SignInForm wiring for `email_not_confirmed`. The original commit 5 plan is preserved as future work but is not part of this rework. The rework focuses on getting the signup path onto the correct foundation; the signin-unconfirmed UX reuses the same `<CheckEmailNotice>` and can be added afterward without affecting the rework's design. |
 
 ---
@@ -62,7 +62,7 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 
 **Files modified:**
 
-- `api/supabase/templates/confirmation.html` — **no change in this commit**. The user customized this template (structure, copy, styling) and committed those customizations in `de592bc`. The only uncommitted edit was the token_hash URL surgery on the link `href`, which the prerequisite `git restore .` step reverts automatically. After `git restore .` the template is already in the correct state for the new design (link `href = {{ .ConfirmationURL }}`). Do not regenerate or replace the file.
+- `api/supabase/templates/confirmation.html` — **no change in this commit**. The user customized this template (structure, text, styling) and committed those customizations in `de592bc`. The only uncommitted edit was the token_hash URL surgery on the link `href`, which the prerequisite `git restore .` step reverts automatically. After `git restore .` the template is already in the correct state for the new design (link `href = {{ .ConfirmationURL }}`). Do not regenerate or replace the file.
 - `api/supabase/config.toml` — `additional_redirect_urls = ["http://localhost:5173/**"]`. Keep the comment minimal (this file is local-CLI only; the production allowlist is configured in the Supabase dashboard, covered in "Production deployment notes" below).
 - `e2e/supabase/config.toml` — `additional_redirect_urls = ["http://localhost:5273/**"]`.
 - `e2e/tests/_infra/config-sync.spec.ts` — extend `IGNORED_KEY_RE` to ignore `site_url` and `additional_redirect_urls` (the wildcard hosts differ between dev and e2e). This part survives from the old commit 3.
@@ -129,7 +129,7 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 **Tests:**
 
 - `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — assert `signUp` called with `emailRedirectTo: ${origin}/` when no `search.redirect`; assert `emailRedirectTo: ${origin}/join/abc-123` when `search.redirect = '/join/abc-123'`. The typed-OTP `onVerified` destination assertion is already covered by the existing "navigates to redirect path when redirect search parameter is provided" test from commit 4.
-- `web/src/tests/integration/root-routing.integration.test.tsx` — new file. Mount a per-test route tree with `indexRoute` (carrying the real `beforeLoad`) plus bare stub routes for `/create-team` and `/leagues` whose headings are the redirect-target assertion surface. The `/` component is a stub heading rather than the real `LandingPage` so marketing copy changes don't break the test. Destination routes are not parented under `_no-team` / `_authenticated/_team-required` layouts because those guards are already covered in `route-guards.integration.test.tsx`; isolating to `indexRoute.beforeLoad`'s `teamContext.hasTeam` ternary is what's new in commit 5. Assert: unauthed user stays at `/`; authed-no-team user lands at `/create-team`; authed-with-team user lands at `/leagues`.
+- `web/src/tests/integration/root-routing.integration.test.tsx` — new file. Mount a per-test route tree with `indexRoute` (carrying the real `beforeLoad`) plus bare stub routes for `/create-team` and `/leagues` whose headings are the redirect-target assertion surface. The `/` component is a stub heading rather than the real `LandingPage` so landing-page text changes don't break the test. Destination routes are not parented under `_no-team` / `_authenticated/_team-required` layouts because those guards are already covered in `route-guards.integration.test.tsx`; isolating to `indexRoute.beforeLoad`'s `teamContext.hasTeam` ternary is what's new in commit 5. Assert: unauthed user stays at `/`; authed-no-team user lands at `/create-team`; authed-with-team user lands at `/leagues`.
 
 **Verification:**
 
@@ -138,29 +138,53 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 
 ---
 
-### Commit 6 — Surface auth-URL errors via `<InlineError>` in Layout
+### Commit 6 — Route confirmation-link failures to `/sign-up` with an inline error
 
-**Goal:** when Supabase's `/verify` redirects back with `#error_description=...` (expired token, consumed link, etc.), surface a friendly message instead of silently leaving the user on the destination as if not signed in.
+**Goal:** when Supabase's `/verify` redirects back with an error (expired token, consumed link, invalid token), redirect the user to `/sign-up` and surface a friendly message above the form. The recovery action ("sign up again to get a new link") lives next to where it can be taken.
 
-**Files modified:**
+**Why redirect instead of a layout-wide banner:** the default `emailRedirectTo` lands users on `/`. A banner over the marketing landing page is jarring, and the recovery action (sign up again) requires hunting for the Sign Up button. Routing to `/sign-up` colocates the message with the action.
+
+**Why read the error via `supabase.auth.initialize()` instead of parsing the URL hash ourselves:** the SDK auto-runs `initialize()` in its constructor and caches the result. `getSession()` discards the URL-parse error, but `initialize()` itself returns it — that's the documented hook for reading auth-redirect failures. Avoids re-implementing the SDK's own URL parsing and means we work in terms of typed error codes (`error.details.code`), not pattern-matching on the human-readable description (which Supabase docs explicitly warn against).
 
-- `web/src/contexts/AuthContext.tsx` — in the existing mount-time `useEffect` (or a sibling), read `window.location.hash` for `error` and `error_description`. If either is set, call `setAuthUrlError(mapAuthUrlError(code, description))` and strip the fragment via `window.history.replaceState(null, '', window.location.pathname + window.location.search)`.
-- `web/src/contexts/AuthContext.ts` — add `authUrlError: string | null` and `clearAuthUrlError: () => void` to `AuthContextType`. Expose both from the provider.
-- `web/src/components/Layout/Layout.tsx` — read `authUrlError` and `clearAuthUrlError` from `useAuth()`. Render `<InlineError>` above the `<Outlet>` (in both the authenticated and unauthenticated branches) when `authUrlError` is non-null. Provide a dismiss affordance that calls `clearAuthUrlError`.
+**Why route context instead of AuthContext state:** the error isn't ongoing auth state — it's a one-shot routing concern (the user just landed from a failed redirect). Putting it in AuthContext required a cleanup `useEffect` on `SignUpForm` unmount, which coupled unrelated lifecycles. Route context, set in `signUpRoute.beforeLoad`, is recomputed on navigation and naturally clears when the user leaves `/sign-up`. AuthContext stays focused on session/user.
 
 **Files added:**
 
-- `web/src/lib/auth-url-errors.ts` — `mapAuthUrlError(code: string | null, description: string | null): string`. Small lookup: known codes (e.g., `access_denied` with expired-description → "This confirmation link has expired or has already been used. Try signing in to get a new one.") map to friendly copy; generic fallback ("We couldn't confirm your email. Please try signing in again.") for unknowns.
-- `web/src/lib/auth-url-errors.test.ts` — one test per mapped case plus the fallback.
+- `web/src/lib/auth-redirect.ts` — `readConfirmationLinkError()` returns `'expired' | 'generic' | null`. Wraps `supabase.auth.initialize()`, type-guards on `isAuthImplicitGrantRedirectError`, maps `error.details?.code === 'otp_expired'` to `'expired'` and any other redirect error to `'generic'`. Non-redirect errors (network failures, etc.) return `null` — they're handled wherever the originating call surfaces.
+- `web/src/lib/auth-redirect.test.ts` — one test per mapped case plus the null fallbacks (success, non-redirect error).
+
+**Files modified:**
+
+- `web/src/router.tsx`
+  - `indexRoute.beforeLoad`: when the user isn't signed in, `await readConfirmationLinkError()` and `throw redirect({ to: '/sign-up', replace: true })` if it returns a code. The redirect with `replace: true` overwrites the failed-URL history entry, so back-button / refresh / share don't re-trigger.
+  - `signUpRoute.beforeLoad`: after the existing auth check, `return { confirmationError: await readConfirmationLinkError() }`. The cached `initializePromise` means this is the same value indexRoute saw — free. TanStack Router merges the return into the route's context, accessible via `useRouteContext({ from: '/sign-up' })`.
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` — reads `confirmationError` from `useRouteContext({ from: '/sign-up' })`. Maps the code to a user-facing message via a `CONFIRMATION_ERROR_MESSAGES` map at module scope. Renders `<InlineError>` above the form when set.
+
+**Files NOT created (deliberate departures from the original plan):**
+
+- No `auth-url-errors.ts` helper / `mapAuthUrlError` function. The lib is `auth-redirect.ts` with `readConfirmationLinkError`, and the code→message mapping is a small lookup in `SignUpForm`.
+- No `<InlineError>` banner in `Layout.tsx`. The redirect approach makes the layout-wide banner unnecessary.
+- No URL hash stripping. The redirect with `replace: true` moves the user off the URL containing the error fragment.
+- No `confirmationLinkError` state in `AuthContext`. The error rides on the route's context, set by `signUpRoute.beforeLoad`.
+
+**Decisions worth recording for future-me:**
+
+- **Match on `error_code`, not the description string.** Verified directly from gotrue source (`internal/api/verify.go`): every email-confirmation failure (expired, already-used, invalid) returns `ErrorCodeOTPExpired = "otp_expired"`. The description text varies; the code is stable. Supabase's own docs say _"Always use `error.code` and `error.name` to identify errors, not string matching on error messages."_
+- **Only `otp_expired` is worth a specific case today.** Cross-referenced every documented code in `authErrorCodes.toml` against (a) what can reach the `/verify` redirect path and (b) which apply to our config (email/password only, no OAuth/MFA/SAML/phone). Everything else is either out-of-scope, surfaces through a different API call, or generic enough that the fallback message suffices. Extend the matcher if Sentry shows specific codes accumulating.
+- **`replace: true` on the redirect handles URL cleanup.** Replaces the failed-URL history entry instead of pushing a new one. Back button can't revisit the error; refreshes happen at `/sign-up` (no hash).
+- **Route context, not React state.** The error is data tied to "this navigation," not to "this user session." TanStack Router's `beforeLoad` return becomes route match context. `useRouteContext({ from: '/sign-up' })` reads it from the form. No cleanup effect, no AuthContext state, no URL search-param pollution.
+- **Known trade-off: in-session "stale reappear."** Because the SDK's `initialize()` result is cached for the page's lifetime, a user who navigates `/sign-up` → `/sign-in` → `/sign-up` in the same session would see the error message again. Acceptable: the realistic flow is "land → sign up again," not "land → wander → return." A hard refresh on `/sign-up` clears it (fresh SDK instance, no hash). If this becomes a real complaint, the fix is to track "consumed" state somewhere — but adding that complexity now would be premature.
 
 **Tests:**
 
-- `web/src/contexts/AuthContext.test.tsx` — test: `window.location.hash` containing `#error_description=...` on mount sets `authUrlError` and strips the hash. Test: `clearAuthUrlError` resets state to `null`. Test: no hash → no state set.
+- `web/src/lib/auth-redirect.test.ts` — `readConfirmationLinkError` returns `'expired'` for `code: 'otp_expired'`; returns `'generic'` for other redirect errors; returns `null` for `{ error: null }` and for non-redirect errors.
+- `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — three new tests: `confirmationError: 'expired'` renders the expired-link message; `'generic'` renders the generic message; `null` renders no alert. Existing tests get a `useRouteContext` mock returning `{ confirmationError: null }` by default.
+- Mock updates in every test file that constructs an `AuthContextType` literal: `tests/test-utils/renderContexts.ts`, `InnerApp.test.tsx`, `contexts/TeamContext.test.tsx`, `lib/route-guards.test.ts`, `components/auth/SignInForm/SignInForm.test.tsx`, `components/auth/SignUpForm/SignUpForm.test.tsx` — the new context fields we added in a prior iteration are removed since AuthContext is back to its pre-commit-6 shape.
 
 **Verification:**
 
 1. `npm run web:test` + lint/format/build green.
-2. Manual: reproduce a failure by clicking a link with an invalid/expired token, or by manually constructing a URL like `http://localhost:5173/#error_description=Email%20link%20is%20invalid` → load the app → see `<InlineError>` above the page content with friendly copy; dismiss → error clears; URL bar no longer contains the fragment.
+2. Manual: reproduce a failure by clicking an expired link, or by manually constructing a URL like `http://localhost:5173/#error=access_denied&error_code=otp_expired&error_description=Email%20link%20is%20invalid%20or%20has%20expired` → load the app → user gets routed to `/sign-up` → `<InlineError>` renders above the form with the expired-link message → navigating to `/sign-in` and back to `/sign-up` does NOT clear it in the same page session (known trade-off; refresh on `/sign-up` clears).
 
 ---
 
@@ -171,15 +195,15 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 **Files modified:**
 
 - `web/src/contexts/AuthContext.tsx` + `.ts` — add `resendConfirmation(email: string, options?: { emailRedirectTo?: string }): Promise<void>` to interface and implementation. Calls `supabase.auth.resend({ type: 'signup', email, options: { emailRedirectTo: options?.emailRedirectTo } })`. Throws on error.
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — reintroduce `<CardFooter>` with a Resend button gated on the existing `onResend` prop. Use `<LoadingButton>` for loading state. Use `<LiveRegion>` to announce success ("New confirmation email sent."). Use `<InlineError>` for failures, with friendly copy for `over_email_send_rate_limit` ("Please wait a moment before requesting another email.") and a generic message for other errors. Local `resendStatus: 'idle' | 'sending'` mirrors the original commit 4 design.
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — reintroduce `<CardFooter>` with a Resend button gated on the existing `onResend` prop. Use `<LoadingButton>` for loading state. Use `<LiveRegion>` to announce success ("New confirmation email sent."). Use `<InlineError>` for failures, with a friendly message for `over_email_send_rate_limit` ("Please wait a moment before requesting another email.") and a generic message for other errors. Local `resendStatus: 'idle' | 'sending'` mirrors the original commit 4 design.
 - `web/src/components/auth/SignUpForm/SignUpForm.tsx` — pass `onResend={() => resendConfirmation(email, { emailRedirectTo })}` to `<CheckEmailNotice>`, reusing the same `emailRedirectTo` value computed for the initial `signUp` call.
 
 **Tests:**
 
 - `web/src/contexts/AuthContext.test.tsx` — `resendConfirmation` calls `supabase.auth.resend` with `{ type: 'signup', email, options: { emailRedirectTo } }`. With no `emailRedirectTo`, the options object's `emailRedirectTo` is `undefined`. Throws on Supabase error.
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx` — clicking Resend fires `onResend`. Loading state visible during the await. Success announced via `LiveRegion`. Generic error renders via `<InlineError>`. Rate-limit error renders the friendly copy.
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx` — clicking Resend fires `onResend`. Loading state visible during the await. Success announced via `LiveRegion`. Generic error renders via `<InlineError>`. Rate-limit error renders the friendly rate-limit message.
 - `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — Resend passes the current `emailRedirectTo` (with `search.redirect` threading) to `resendConfirmation`.
-- `web/src/tests/integration/signup-resend.integration.test.tsx` — new file. Mount sign-up flow at `/sign-up?redirect=/leagues/123`, submit, click Resend, assert `supabase.auth.resend` was called with the expected args. Same setup but with `supabase.auth.resend` mocked to return `{ error: { code: 'over_email_send_rate_limit' } }` → assert friendly rate-limit copy renders.
+- `web/src/tests/integration/signup-resend.integration.test.tsx` — new file. Mount sign-up flow at `/sign-up?redirect=/leagues/123`, submit, click Resend, assert `supabase.auth.resend` was called with the expected args. Same setup but with `supabase.auth.resend` mocked to return `{ error: { code: 'over_email_send_rate_limit' } }` → assert the friendly rate-limit message renders.
 
 **Verification:**
 
@@ -216,16 +240,15 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 - `e2e/supabase/config.toml` (commit 4)
 - `e2e/tests/_infra/config-sync.spec.ts` (commit 4)
 - `web/src/lib/supabase.ts` (commit 4)
-- `web/src/router.tsx` (commits 4, 5)
-- `web/src/contexts/AuthContext.tsx` + `.ts` (commits 4, 6, 7)
-- `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commits 4, 5, 7)
+- `web/src/router.tsx` (commits 4, 5, 6)
+- `web/src/contexts/AuthContext.tsx` + `.ts` (commits 4, 7)
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commits 4, 5, 6, 7)
 - `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` (commit 7)
-- `web/src/components/Layout/Layout.tsx` (commit 6)
 - `web/src/lib/route-guards.ts` — _kept_, no modifications across the rework
 
 **New across commits 4-8:**
 
-- `web/src/lib/auth-url-errors.ts` + `.test.ts` (commit 6)
+- `web/src/lib/auth-redirect.ts` + `.test.ts` (commit 6)
 - `web/src/tests/integration/root-routing.integration.test.tsx` (commit 5)
 - `web/src/tests/integration/signup-resend.integration.test.tsx` (commit 7)
 - `e2e/fixtures/mailpit.ts` (commit 8)
@@ -253,7 +276,7 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 2. **OTP happy path:** Sign up with new email → `<CheckEmailNotice>` → check Mailpit → type 6-digit code → land on `/create-team` logged in.
 3. **Cross-browser invite preservation:** Sign up from `/sign-up?redirect=/join/<token>` on Browser A → click link in Browser B → land directly at `/join/<token>` signed in.
 4. **Resend:** Sign up → click Resend → second email arrives → either email's link OR the latest OTP completes verification.
-5. **Link failure:** Click an expired/consumed link → land at `/` (or destination) with `<InlineError>` above the content carrying friendly copy; dismiss → clears.
+5. **Link failure:** Click an expired/consumed link → user is routed to `/sign-up` with `<InlineError>` above the form with a friendly message; navigating away clears the message.
 6. **Authed user at `/`:** Visit `/` signed in → bounce to `/leagues` (with team) or `/create-team` (without). Sign out → return to `/` → `LandingPage` renders normally.
 7. **Existing e2e tests:** `npm run e2e` all green (admin fixture continues working via `email_confirm: true`).
 8. **All tests + format + lint:** `npm run test:all` + `npm run web:lint` + `npm run web:format:check` + `npm run api:format:check` all green.
diff --git a/web/src/components/auth/SignUpForm/SignUpForm.test.tsx b/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
index 4eb3444..2279a60 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
@@ -24,9 +24,11 @@ vi.mock('@/hooks/useAuth', async () => {
 
 const mockNavigate = vi.fn();
 const mockUseSearch = vi.fn();
+const mockUseRouteContext = vi.fn();
 vi.mock('@tanstack/react-router', () => ({
   useNavigate: () => mockNavigate,
   useSearch: () => mockUseSearch(),
+  useRouteContext: () => mockUseRouteContext(),
   Link: ({ to, children }: { to: string; children: React.ReactNode }) => (
     <a href={to}>{children}</a>
   ),
@@ -51,6 +53,7 @@ describe('SignUpForm', () => {
       completeAuthTransition: vi.fn(),
     });
     mockUseSearch.mockReturnValue({});
+    mockUseRouteContext.mockReturnValue({ confirmationError: null });
   });
 
   afterEach(() => {
@@ -233,4 +236,29 @@ describe('SignUpForm', () => {
       );
     });
   });
+
+  it('renders the expired-link copy when route context carries confirmationError="expired"', () => {
+    mockUseRouteContext.mockReturnValue({ confirmationError: 'expired' });
+    setup();
+
+    expect(screen.getByRole('alert')).toHaveTextContent(
+      'This confirmation link is no longer valid. Sign up again to receive a new one.',
+    );
+  });
+
+  it('renders the generic copy when route context carries confirmationError="generic"', () => {
+    mockUseRouteContext.mockReturnValue({ confirmationError: 'generic' });
+    setup();
+
+    expect(screen.getByRole('alert')).toHaveTextContent(
+      "We couldn't confirm your email. Please try signing up again.",
+    );
+  });
+
+  it('renders no confirmation-error alert when route context carries confirmationError=null', () => {
+    mockUseRouteContext.mockReturnValue({ confirmationError: null });
+    setup();
+
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+  });
 });
diff --git a/web/src/components/auth/SignUpForm/SignUpForm.tsx b/web/src/components/auth/SignUpForm/SignUpForm.tsx
index 76e48d1..47a7d78 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.tsx
@@ -8,9 +8,14 @@ import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { useAuth } from '@/hooks/useAuth';
 import { useLiveRegion } from '@/hooks/useLiveRegion';
-import { Link, useNavigate, useSearch } from '@tanstack/react-router';
+import { Link, useNavigate, useRouteContext, useSearch } from '@tanstack/react-router';
 import { type FormEvent, useState } from 'react';
 
+const CONFIRMATION_ERROR_MESSAGES = {
+  expired: 'This confirmation link is no longer valid. Sign up again to receive a new one.',
+  generic: "We couldn't confirm your email. Please try signing up again.",
+} as const;
+
 export function SignUpForm() {
   const [email, setEmail] = useState('');
   const [password, setPassword] = useState('');
@@ -20,8 +25,12 @@ export function SignUpForm() {
   const [error, setError] = useState<string | null>(null);
   const [awaitingConfirmation, setAwaitingConfirmation] = useState(false);
   const { signUp, startAuthTransition, completeAuthTransition } = useAuth();
+
   const navigate = useNavigate();
   const search = useSearch({ from: '/sign-up' });
+  const { confirmationError } = useRouteContext({ from: '/sign-up' });
+  const confirmationErrorMessage =
+    confirmationError && CONFIRMATION_ERROR_MESSAGES[confirmationError];
   const destination = search.redirect ?? '/';
   const emailRedirectTo = `${window.location.origin}${destination}`;
 
@@ -103,6 +112,7 @@ export function SignUpForm() {
             <CardContent>
               <form onSubmit={handleSubmit} className="space-y-4" noValidate>
                 <LiveRegion message={message} />
+                {confirmationErrorMessage && <InlineError message={confirmationErrorMessage} />}
                 {error && <InlineError message={error} />}
 
                 <div className="space-y-2">
diff --git a/web/src/lib/auth-redirect.test.ts b/web/src/lib/auth-redirect.test.ts
new file mode 100644
index 0000000..97e8dab
--- /dev/null
+++ b/web/src/lib/auth-redirect.test.ts
@@ -0,0 +1,61 @@
+import { AuthImplicitGrantRedirectError } from '@supabase/supabase-js';
+import type { AuthError } from '@supabase/supabase-js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { supabase } from './supabase';
+
+vi.mock('./supabase', () => ({
+  supabase: {
+    auth: {
+      initialize: vi.fn(),
+    },
+  },
+}));
+
+describe('readConfirmationLinkError', () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns "expired" when initialize() returns AuthImplicitGrantRedirectError with otp_expired code', async () => {
+    const error = new AuthImplicitGrantRedirectError('Email link is invalid or has expired', {
+      error: 'access_denied',
+      code: 'otp_expired',
+    });
+    vi.mocked(supabase.auth.initialize).mockResolvedValue({ error });
+
+    const { readConfirmationLinkError } = await import('./auth-redirect');
+    await expect(readConfirmationLinkError()).resolves.toBe('expired');
+  });
+
+  it('returns "generic" for AuthImplicitGrantRedirectError with any other code', async () => {
+    const error = new AuthImplicitGrantRedirectError('Not a valid PKCE flow url.', {
+      error: 'unspecified_error',
+      code: 'unspecified_code',
+    });
+    vi.mocked(supabase.auth.initialize).mockResolvedValue({ error });
+
+    const { readConfirmationLinkError } = await import('./auth-redirect');
+    await expect(readConfirmationLinkError()).resolves.toBe('generic');
+  });
+
+  it('returns null when initialize() succeeds', async () => {
+    vi.mocked(supabase.auth.initialize).mockResolvedValue({ error: null });
+
+    const { readConfirmationLinkError } = await import('./auth-redirect');
+    await expect(readConfirmationLinkError()).resolves.toBeNull();
+  });
+
+  it('returns null for non-redirect auth errors (e.g. network failures)', async () => {
+    const otherError = new Error('network down') as AuthError;
+    otherError.name = 'AuthRetryableFetchError';
+    vi.mocked(supabase.auth.initialize).mockResolvedValue({ error: otherError });
+
+    const { readConfirmationLinkError } = await import('./auth-redirect');
+    await expect(readConfirmationLinkError()).resolves.toBeNull();
+  });
+});
diff --git a/web/src/lib/auth-redirect.ts b/web/src/lib/auth-redirect.ts
new file mode 100644
index 0000000..de1d464
--- /dev/null
+++ b/web/src/lib/auth-redirect.ts
@@ -0,0 +1,12 @@
+import { supabase } from '@/lib/supabase';
+import { isAuthImplicitGrantRedirectError } from '@supabase/supabase-js';
+
+export type ConfirmationLinkErrorCode = 'expired' | 'generic';
+
+// Returns a code if the user arrived from a failed Supabase confirmation
+// link (expired / already-used / invalid token), or null otherwise.
+export async function readConfirmationLinkError(): Promise<ConfirmationLinkErrorCode | null> {
+  const { error } = await supabase.auth.initialize();
+  if (!error || !isAuthImplicitGrantRedirectError(error)) return null;
+  return error.details?.code === 'otp_expired' ? 'expired' : 'generic';
+}
diff --git a/web/src/router.tsx b/web/src/router.tsx
index d018bdd..b550ca4 100644
--- a/web/src/router.tsx
+++ b/web/src/router.tsx
@@ -11,6 +11,7 @@ import { SignInForm } from '@/components/auth/SignInForm/SignInForm';
 import { SignUpForm } from '@/components/auth/SignUpForm/SignUpForm';
 import type { Team as TeamType } from '@/contracts/Team';
 import type { UserProfile } from '@/contracts/UserProfile';
+import { readConfirmationLinkError } from '@/lib/auth-redirect';
 import { requireAuth, requireNoTeam, requireTeam } from '@/lib/route-guards';
 import type { RouterContext } from '@/lib/router-context';
 import { getAvailableLeagues, getLeagueById, getMyLeagues } from '@/services/leagueService';
@@ -178,6 +179,9 @@ const indexRoute = createRoute({
   validateSearch: redirectSearchSchema,
   component: LandingPage,
   beforeLoad: async ({ context }) => {
+    if (!context.auth.user && (await readConfirmationLinkError())) {
+      throw redirect({ to: '/sign-up', replace: true });
+    }
     if (context.auth.user) {
       throw redirect({
         to: context.teamContext.hasTeam ? '/leagues' : '/create-team',
@@ -228,6 +232,7 @@ const signUpRoute = createRoute({
         replace: true,
       });
     }
+    return { confirmationError: await readConfirmationLinkError() };
   },
   errorComponent: ({ error }) => <ErrorComponent error={error} />,
 });

From efc9fbd6df2c47edcddae14916a56ff5565e0db2 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Thu, 14 May 2026 17:39:30 -0500
Subject: [PATCH 19/25] feat(web): add resend confirmation email

Resend button on CheckEmailNotice triggers supabase.auth.resend via a new
lib/auth-resend free function. Discriminates rate-limit (over_email_send_rate_limit)
from generic failures using isAuthApiError; rate-limit shows a friendly message,
generic shows a fallback message and reports to Sentry. Layout restructure groups
OTP, error, and Verify in a fit-content column so Verify naturally matches the
OTP slot row's width without magic numbers.
---
 .../CheckEmailNotice.test.tsx                 |  79 ++++++++++++-
 .../CheckEmailNotice/CheckEmailNotice.tsx     |  94 +++++++++++----
 .../components/auth/SignUpForm/SignUpForm.tsx |  10 +-
 web/src/lib/auth-resend.test.ts               |  62 ++++++++++
 web/src/lib/auth-resend.ts                    |  13 +++
 .../signup-resend.integration.test.tsx        | 109 ++++++++++++++++++
 6 files changed, 342 insertions(+), 25 deletions(-)
 create mode 100644 web/src/lib/auth-resend.test.ts
 create mode 100644 web/src/lib/auth-resend.ts
 create mode 100644 web/src/tests/integration/signup-resend.integration.test.tsx

diff --git a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
index de164f1..9bbc186 100644
--- a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
+++ b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
@@ -1,5 +1,6 @@
 import { supabase } from '@/lib/supabase';
-import type { AuthError } from '@supabase/supabase-js';
+import * as Sentry from '@sentry/react';
+import { AuthApiError, type AuthError } from '@supabase/supabase-js';
 import { render, screen, waitFor } from '@testing-library/react';
 import { userEvent } from '@testing-library/user-event';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -14,6 +15,10 @@ vi.mock('@/lib/supabase', () => ({
   },
 }));
 
+vi.mock('@sentry/react', () => ({
+  captureException: vi.fn(),
+}));
+
 describe('CheckEmailNotice', () => {
   beforeEach(() => {
     vi.mocked(supabase.auth.verifyOtp).mockReset();
@@ -87,4 +92,76 @@ describe('CheckEmailNotice', () => {
     expect(button).toBeDisabled();
     expect(supabase.auth.verifyOtp).not.toHaveBeenCalled();
   });
+
+  describe('Resend', () => {
+    it('hides the Resend button when no onResend handler is provided', () => {
+      setup();
+      expect(screen.queryByRole('button', { name: /resend/i })).not.toBeInTheDocument();
+    });
+
+    it('fires onResend when the button is clicked and announces success', async () => {
+      const user = userEvent.setup();
+      const onResend = vi.fn().mockResolvedValue(undefined);
+      setup({ onResend });
+
+      await user.click(screen.getByRole('button', { name: /resend/i }));
+
+      expect(onResend).toHaveBeenCalledTimes(1);
+      await waitFor(() => {
+        expect(screen.getByText('New confirmation email sent.')).toBeInTheDocument();
+      });
+    });
+
+    it('shows the loading label while the resend request is in flight', async () => {
+      const user = userEvent.setup();
+      let resolveResend: () => void = () => {};
+      const onResend = vi.fn(
+        () =>
+          new Promise<void>((resolve) => {
+            resolveResend = resolve;
+          }),
+      );
+      setup({ onResend });
+
+      await user.click(screen.getByRole('button', { name: /resend/i }));
+
+      const sendingButton = await screen.findByRole('button', { name: /sending/i });
+      expect(sendingButton).toHaveAttribute('aria-busy', 'true');
+
+      resolveResend();
+      await waitFor(() => {
+        expect(screen.queryByRole('button', { name: /sending/i })).not.toBeInTheDocument();
+      });
+    });
+
+    it('renders the generic failure message and reports the error to Sentry when onResend rejects without a known code', async () => {
+      const user = userEvent.setup();
+      const unknownError = new Error('boom');
+      const onResend = vi.fn().mockRejectedValue(unknownError);
+      setup({ onResend });
+
+      await user.click(screen.getByRole('button', { name: /resend/i }));
+
+      const alert = await screen.findByRole('alert');
+      expect(alert).toHaveTextContent("Couldn't send the email. Please try again.");
+      expect(Sentry.captureException).toHaveBeenCalledWith(unknownError, {
+        tags: { component: 'CheckEmailNotice', operation: 'resendConfirmation' },
+      });
+    });
+
+    it('renders the rate-limit message without reporting to Sentry', async () => {
+      const user = userEvent.setup();
+      const rateLimitError = new AuthApiError('rate limit', 429, 'over_email_send_rate_limit');
+      const onResend = vi.fn().mockRejectedValue(rateLimitError);
+      setup({ onResend });
+
+      await user.click(screen.getByRole('button', { name: /resend/i }));
+
+      const alert = await screen.findByRole('alert');
+      expect(alert).toHaveTextContent(
+        "You've sent too many confirmation requests. Please try again later.",
+      );
+      expect(Sentry.captureException).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
index 29d9e7a..6a03839 100644
--- a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
+++ b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
@@ -1,10 +1,14 @@
 import { InlineError } from '@/components/InlineError/InlineError';
+import { LiveRegion } from '@/components/LiveRegion/LiveRegion';
 import { LoadingButton } from '@/components/LoadingButton/LoadingButton';
 import { OtpInput } from '@/components/OtpInput/OtpInput';
-import { Card, CardContent, CardHeader } from '@/components/ui/card';
+import { Card, CardContent, CardFooter, CardHeader } from '@/components/ui/card';
 import { Label } from '@/components/ui/label';
+import { useLiveRegion } from '@/hooks/useLiveRegion';
 import { supabase } from '@/lib/supabase';
 import { cn } from '@/lib/utils';
+import * as Sentry from '@sentry/react';
+import { isAuthApiError } from '@supabase/supabase-js';
 import { Check } from 'lucide-react';
 import { useState } from 'react';
 
@@ -18,11 +22,15 @@ interface Props {
 const OTP_LENGTH = 6;
 
 type Status = 'idle' | 'verifying' | 'success';
+type ResendStatus = 'idle' | 'sending';
 
-export function CheckEmailNotice({ email, onVerified }: Props) {
+export function CheckEmailNotice({ email, onVerified, onResend }: Props) {
   const [code, setCode] = useState('');
   const [error, setError] = useState<string | null>(null);
   const [status, setStatus] = useState<Status>('idle');
+  const [resendStatus, setResendStatus] = useState<ResendStatus>('idle');
+  const [resendError, setResendError] = useState<string | null>(null);
+  const { message, announce } = useLiveRegion();
 
   const verify = async (token: string) => {
     setStatus('verifying');
@@ -46,6 +54,28 @@ export function CheckEmailNotice({ email, onVerified }: Props) {
     if (status === 'idle') verify(value);
   };
 
+  const handleResend = async () => {
+    if (!onResend || resendStatus === 'sending') return;
+    setResendStatus('sending');
+    setResendError(null);
+    try {
+      await onResend();
+      announce('New confirmation email sent.');
+    } catch (err) {
+      const isRateLimit = isAuthApiError(err) && err.code === 'over_email_send_rate_limit';
+      if (isRateLimit) {
+        setResendError("You've sent too many confirmation requests. Please try again later.");
+      } else {
+        Sentry.captureException(err, {
+          tags: { component: 'CheckEmailNotice', operation: 'resendConfirmation' },
+        });
+        setResendError("Couldn't send the email. Please try again.");
+      }
+    } finally {
+      setResendStatus('idle');
+    }
+  };
+
   return (
     <Card
       className={cn(
@@ -77,22 +107,22 @@ export function CheckEmailNotice({ email, onVerified }: Props) {
       </CardHeader>
 
       <CardContent className="space-y-4">
-        <div className="space-y-3">
-          <div className="flex items-center justify-between">
-            <Label
-              htmlFor="confirmation-code"
-              className="text-muted-foreground text-[13px] font-medium tracking-[0.01em]"
-            >
-              Confirmation code
-            </Label>
-            <div className="bg-border h-0.75 w-20 overflow-hidden rounded-full">
-              <div
-                className="bg-primary h-full transition-all duration-200"
-                style={{ width: `${(code.length / OTP_LENGTH) * 100}%` }}
-              />
-            </div>
+        <div className="flex items-center justify-between">
+          <Label
+            htmlFor="confirmation-code"
+            className="text-muted-foreground text-[13px] font-medium tracking-[0.01em]"
+          >
+            Confirmation code
+          </Label>
+          <div className="bg-border h-0.75 w-20 overflow-hidden rounded-full">
+            <div
+              className="bg-primary h-full transition-all duration-200"
+              style={{ width: `${(code.length / OTP_LENGTH) * 100}%` }}
+            />
           </div>
+        </div>
 
+        <div className="mx-auto flex w-fit flex-col items-stretch gap-3">
           <OtpInput
             id="confirmation-code"
             length={OTP_LENGTH}
@@ -100,20 +130,21 @@ export function CheckEmailNotice({ email, onVerified }: Props) {
             onChange={setCode}
             onComplete={handleComplete}
             disabled={status === 'verifying' || status === 'success'}
-            className="w-full"
           />
 
-          {error && <InlineError message={error} />}
-        </div>
+          {error && (
+            <div className="w-0 min-w-full">
+              <InlineError message={error} />
+            </div>
+          )}
 
-        <div className="flex justify-center">
           <LoadingButton
             type="button"
             onClick={() => {
               if (status === 'idle') verify(code);
             }}
             size="lg"
-            className="min-w-48"
+            className="w-full"
             isLoading={status === 'verifying'}
             loadingText="Verifying..."
             disabled={code.length < OTP_LENGTH || status === 'success'}
@@ -129,6 +160,27 @@ export function CheckEmailNotice({ email, onVerified }: Props) {
           </LoadingButton>
         </div>
       </CardContent>
+
+      {onResend && (
+        <CardFooter className="flex-col items-center gap-3">
+          <LiveRegion message={message} />
+          {resendError && <InlineError message={resendError} />}
+          <p className="text-muted-foreground text-sm">
+            Didn't get your email?{' '}
+            <LoadingButton
+              type="button"
+              onClick={handleResend}
+              variant="link"
+              className="h-auto p-0 align-baseline text-sm"
+              isLoading={resendStatus === 'sending'}
+              loadingText="Sending..."
+              disabled={status === 'success'}
+            >
+              Resend the code
+            </LoadingButton>
+          </p>
+        </CardFooter>
+      )}
     </Card>
   );
 }
diff --git a/web/src/components/auth/SignUpForm/SignUpForm.tsx b/web/src/components/auth/SignUpForm/SignUpForm.tsx
index 47a7d78..3da73cc 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.tsx
@@ -8,6 +8,7 @@ import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { useAuth } from '@/hooks/useAuth';
 import { useLiveRegion } from '@/hooks/useLiveRegion';
+import { resendConfirmation } from '@/lib/auth-resend';
 import { Link, useNavigate, useRouteContext, useSearch } from '@tanstack/react-router';
 import { type FormEvent, useState } from 'react';
 
@@ -102,12 +103,16 @@ export function SignUpForm() {
     <div className="flex w-full items-center justify-center p-4 sm:p-8 md:min-h-screen">
       <div className="w-full max-w-md space-y-4">
         {awaitingConfirmation ? (
-          <CheckEmailNotice email={email} onVerified={completeSignUp} />
+          <CheckEmailNotice
+            email={email}
+            onVerified={completeSignUp}
+            onResend={() => resendConfirmation(email, { emailRedirectTo })}
+          />
         ) : (
           <Card className="w-full max-w-md">
             <CardHeader>
               <CardTitle>Create Account</CardTitle>
-              <CardDescription>Join the F1 fantasy league</CardDescription>
+              <CardDescription>Join the F1 Fantasy Sports App</CardDescription>
             </CardHeader>
             <CardContent>
               <form onSubmit={handleSubmit} className="space-y-4" noValidate>
@@ -177,7 +182,6 @@ export function SignUpForm() {
             </CardContent>
           </Card>
         )}
-
         <div className="text-center">
           <Button variant="link" asChild className="text-sm">
             <Link to="/sign-in">Already have an account? Sign in</Link>
diff --git a/web/src/lib/auth-resend.test.ts b/web/src/lib/auth-resend.test.ts
new file mode 100644
index 0000000..913053e
--- /dev/null
+++ b/web/src/lib/auth-resend.test.ts
@@ -0,0 +1,62 @@
+import type { AuthError } from '@supabase/supabase-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { resendConfirmation } from './auth-resend';
+import { supabase } from './supabase';
+
+vi.mock('./supabase', () => ({
+  supabase: {
+    auth: {
+      resend: vi.fn(),
+    },
+  },
+}));
+
+describe('resendConfirmation', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('calls supabase.auth.resend with type signup and undefined emailRedirectTo by default', async () => {
+    vi.mocked(supabase.auth.resend).mockResolvedValue({
+      data: { user: null, session: null },
+      error: null,
+    });
+
+    await resendConfirmation('test@example.com');
+
+    expect(supabase.auth.resend).toHaveBeenCalledWith({
+      type: 'signup',
+      email: 'test@example.com',
+      options: { emailRedirectTo: undefined },
+    });
+  });
+
+  it('forwards emailRedirectTo to supabase.auth.resend when provided', async () => {
+    vi.mocked(supabase.auth.resend).mockResolvedValue({
+      data: { user: null, session: null },
+      error: null,
+    });
+    const customRedirect = 'http://localhost/join/xyz';
+
+    await resendConfirmation('test@example.com', { emailRedirectTo: customRedirect });
+
+    expect(supabase.auth.resend).toHaveBeenCalledWith({
+      type: 'signup',
+      email: 'test@example.com',
+      options: { emailRedirectTo: customRedirect },
+    });
+  });
+
+  it('throws when supabase.auth.resend returns an error', async () => {
+    const resendError = Object.assign(new Error('rate limit'), {
+      code: 'over_email_send_rate_limit',
+    }) as AuthError;
+    vi.mocked(supabase.auth.resend).mockResolvedValue({
+      data: { user: null, session: null },
+      error: resendError,
+    });
+
+    await expect(resendConfirmation('test@example.com')).rejects.toBe(resendError);
+  });
+});
diff --git a/web/src/lib/auth-resend.ts b/web/src/lib/auth-resend.ts
new file mode 100644
index 0000000..8c544e2
--- /dev/null
+++ b/web/src/lib/auth-resend.ts
@@ -0,0 +1,13 @@
+import { supabase } from '@/lib/supabase';
+
+export async function resendConfirmation(
+  email: string,
+  options?: { emailRedirectTo?: string },
+): Promise<void> {
+  const { error } = await supabase.auth.resend({
+    type: 'signup',
+    email,
+    options: { emailRedirectTo: options?.emailRedirectTo },
+  });
+  if (error) throw error;
+}
diff --git a/web/src/tests/integration/signup-resend.integration.test.tsx b/web/src/tests/integration/signup-resend.integration.test.tsx
new file mode 100644
index 0000000..89d8966
--- /dev/null
+++ b/web/src/tests/integration/signup-resend.integration.test.tsx
@@ -0,0 +1,109 @@
+import { SignUpForm } from '@/components/auth/SignUpForm/SignUpForm';
+import type { RouterContext } from '@/lib/router-context';
+import { supabase } from '@/lib/supabase';
+import { createBaseRouterContext, createUnauthAuth, renderWithRouter } from '@/tests/test-utils';
+import { AuthApiError } from '@supabase/supabase-js';
+import { Outlet, createRootRouteWithContext, createRoute } from '@tanstack/react-router';
+import { screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+
+vi.mock('@/lib/supabase', () => ({
+  supabase: {
+    auth: {
+      resend: vi.fn(),
+    },
+  },
+}));
+
+// Mirrors the `/sign-up` route from `router.tsx`.
+const redirectSearchSchema = z.object({
+  redirect: z
+    .string()
+    .refine((url) => url.startsWith('/'), 'Redirect must be an internal path')
+    .optional()
+    .catch(undefined),
+});
+
+function buildSignUpRouteTree() {
+  const rootRoute = createRootRouteWithContext<RouterContext>()({
+    component: () => <Outlet />,
+  });
+
+  const signUpRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/sign-up',
+    validateSearch: redirectSearchSchema,
+    component: SignUpForm,
+    beforeLoad: () => ({ confirmationError: null }),
+  });
+
+  return rootRoute.addChildren([signUpRoute]);
+}
+
+async function driveFormToPending(user: ReturnType<typeof userEvent.setup>) {
+  await user.type(await screen.findByLabelText(/display name/i), 'Test User');
+  await user.type(screen.getByLabelText(/email/i), 'pending@example.com');
+  await user.type(screen.getByLabelText(/^password$/i), 'password123');
+  await user.type(screen.getByLabelText(/confirm password/i), 'password123');
+  await user.click(screen.getByRole('button', { name: /sign up/i }));
+  await screen.findByRole('heading', { name: /check your email/i });
+}
+
+describe('Signup resend confirmation', () => {
+  afterEach(() => {
+    vi.mocked(supabase.auth.resend).mockReset();
+  });
+
+  it('passes the form email and redirect-aware emailRedirectTo through to supabase.auth.resend', async () => {
+    const user = userEvent.setup();
+    const signUp = vi.fn().mockResolvedValue({ session: null });
+    vi.mocked(supabase.auth.resend).mockResolvedValue({
+      data: { user: null, session: null },
+      error: null,
+    });
+
+    renderWithRouter({
+      routeTree: buildSignUpRouteTree(),
+      initialEntry: '/sign-up?redirect=/leagues/123',
+      auth: createUnauthAuth({ signUp }),
+      routerContext: createBaseRouterContext(),
+    });
+
+    await driveFormToPending(user);
+    await user.click(screen.getByRole('button', { name: /resend/i }));
+
+    await waitFor(() => {
+      expect(supabase.auth.resend).toHaveBeenCalledWith({
+        type: 'signup',
+        email: 'pending@example.com',
+        options: { emailRedirectTo: `${window.location.origin}/leagues/123` },
+      });
+    });
+  });
+
+  it('renders the friendly rate-limit message when supabase.auth.resend returns over_email_send_rate_limit', async () => {
+    const user = userEvent.setup();
+    const signUp = vi.fn().mockResolvedValue({ session: null });
+    const rateLimitError = new AuthApiError('rate limit', 429, 'over_email_send_rate_limit');
+    vi.mocked(supabase.auth.resend).mockResolvedValue({
+      data: { user: null, session: null },
+      error: rateLimitError,
+    });
+
+    renderWithRouter({
+      routeTree: buildSignUpRouteTree(),
+      initialEntry: '/sign-up?redirect=/leagues/123',
+      auth: createUnauthAuth({ signUp }),
+      routerContext: createBaseRouterContext(),
+    });
+
+    await driveFormToPending(user);
+    await user.click(screen.getByRole('button', { name: /resend/i }));
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(
+      "You've sent too many confirmation requests. Please try again later.",
+    );
+  });
+});

From 9ed9f2a184537b15f273e4a3e523893b9f5be104 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Thu, 14 May 2026 17:40:06 -0500
Subject: [PATCH 20/25] docs(plans): sync #164 plan with what commit 7 actually
 shipped

Resend ships as a free function in lib/auth-resend.ts (not an AuthContext
method), with Sentry capture on unexpected failures, a typed isAuthApiError
guard for rate-limit detection, and a fit-content layout that ties the Verify
button to the OTP slot row without magic numbers. Plan now records the decision
trail for these departures from the original commit 7 design.
---
 docs/plans/164-email-confirmation-signup.md | 32 ++++++++++++++-------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index 4d19d7f..f4065cc 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -190,20 +190,31 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 
 ### Commit 7 — Add resend confirmation email
 
-**Goal:** "Resend" button on `<CheckEmailNotice>` re-sends the confirmation email. Same shape as the original commit 4 plan, simpler because no redirect plumbing.
+**Goal:** "Resend" button on `<CheckEmailNotice>` re-sends the confirmation email and surfaces friendly UX for rate-limiting and unexpected failures.
+
+**Files added:**
+
+- `web/src/lib/auth-resend.ts` — `resendConfirmation(email, options?)` free function wrapping `supabase.auth.resend({ type: 'signup', email, options: { emailRedirectTo } })`. Throws on error. Lives outside `AuthContext` — see "Decisions worth recording" below.
+- `web/src/lib/auth-resend.test.ts` — unit tests: default args (`emailRedirectTo: undefined`), forwards custom `emailRedirectTo`, throws on Supabase error.
+- `web/src/tests/integration/signup-resend.integration.test.tsx` — mounts a real `/sign-up` route, submits the form to reach `<CheckEmailNotice>`, clicks Resend, asserts `supabase.auth.resend` was called with the expected payload. A second test mocks `supabase.auth.resend` to return `AuthApiError(..., 429, 'over_email_send_rate_limit')` and asserts the friendly rate-limit message renders. Mocks at the third-party seam (`@/lib/supabase`) so the real `resendConfirmation` runs.
 
 **Files modified:**
 
-- `web/src/contexts/AuthContext.tsx` + `.ts` — add `resendConfirmation(email: string, options?: { emailRedirectTo?: string }): Promise<void>` to interface and implementation. Calls `supabase.auth.resend({ type: 'signup', email, options: { emailRedirectTo: options?.emailRedirectTo } })`. Throws on error.
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` — reintroduce `<CardFooter>` with a Resend button gated on the existing `onResend` prop. Use `<LoadingButton>` for loading state. Use `<LiveRegion>` to announce success ("New confirmation email sent."). Use `<InlineError>` for failures, with a friendly message for `over_email_send_rate_limit` ("Please wait a moment before requesting another email.") and a generic message for other errors. Local `resendStatus: 'idle' | 'sending'` mirrors the original commit 4 design.
-- `web/src/components/auth/SignUpForm/SignUpForm.tsx` — pass `onResend={() => resendConfirmation(email, { emailRedirectTo })}` to `<CheckEmailNotice>`, reusing the same `emailRedirectTo` value computed for the initial `signUp` call.
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx`
+  - Reintroduces `<CardFooter>` with a Resend `<LoadingButton>` gated on the `onResend` prop, plus `<LiveRegion>` for the success announcement ("New confirmation email sent.") and `<InlineError>` for failures.
+  - Discriminates failures via `isAuthApiError(err) && err.code === 'over_email_send_rate_limit'` — Supabase's recommended pattern per [their error-codes guide](https://supabase.com/docs/guides/auth/debugging/error-codes) ("Always use `error.code` and `error.name` to identify errors"; "Use `isAuthApiError` instead of `instanceof` checks").
+  - Rate-limit failure: "You've sent too many confirmation requests. Please try again later." (no Sentry).
+  - Generic failure: "Couldn't send the email. Please try again." + `Sentry.captureException(err, { tags: { component: 'CheckEmailNotice', operation: 'resendConfirmation' } })`. Rate-limit is expected user behavior — capturing it would be noise; generic is the "unknown failure" bucket worth investigating.
+  - Layout restructure: drop `w-full` from `<OtpInput>` so it sizes to its slot row, and group `OtpInput` + error + `Verify` in a shared `mx-auto flex w-fit flex-col` column. `Verify` is now `w-full` and naturally matches the OTP slot row's width at any breakpoint — no magic numbers tying button width to slot dimensions. Trade-off: clicking the dead space between the slots and the card edges no longer focuses the input (the slots themselves and the label `htmlFor` still do).
+- `web/src/components/auth/SignUpForm/SignUpForm.tsx` — imports `resendConfirmation` from `@/lib/auth-resend` and passes `onResend={() => resendConfirmation(email, { emailRedirectTo })}` to `<CheckEmailNotice>`, reusing the same `emailRedirectTo` value computed for `signUp`.
+- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx` — new `Resend` describe block covers: hidden button when no handler, click fires `onResend`, loading label visible while in flight, success announced via `LiveRegion`, generic failure renders message and calls `Sentry.captureException` with the right tags, rate-limit renders the friendly message and does NOT call Sentry.
 
-**Tests:**
+**Decisions worth recording:**
 
-- `web/src/contexts/AuthContext.test.tsx` — `resendConfirmation` calls `supabase.auth.resend` with `{ type: 'signup', email, options: { emailRedirectTo } }`. With no `emailRedirectTo`, the options object's `emailRedirectTo` is `undefined`. Throws on Supabase error.
-- `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx` — clicking Resend fires `onResend`. Loading state visible during the await. Success announced via `LiveRegion`. Generic error renders via `<InlineError>`. Rate-limit error renders the friendly rate-limit message.
-- `web/src/components/auth/SignUpForm/SignUpForm.test.tsx` — Resend passes the current `emailRedirectTo` (with `search.redirect` threading) to `resendConfirmation`.
-- `web/src/tests/integration/signup-resend.integration.test.tsx` — new file. Mount sign-up flow at `/sign-up?redirect=/leagues/123`, submit, click Resend, assert `supabase.auth.resend` was called with the expected args. Same setup but with `supabase.auth.resend` mocked to return `{ error: { code: 'over_email_send_rate_limit' } }` → assert the friendly rate-limit message renders.
+- **Free function in `lib/auth-resend.ts`, not an `AuthContext` method.** `signUp` / `signIn` / `signOut` on AuthContext are the gates for lifecycle transitions; even though they don't directly mutate React state (the `onAuthStateChange` listener does), they bracket those transitions. `resendConfirmation` is a pure side-effecting call — it sends an email and has no auth-state implication. Closer fit to the existing `lib/auth-redirect.ts` precedent (`readConfirmationLinkError`) than to AuthContext. Keeps AuthContext focused.
+- **Sentry capture only on the unrecognized-failure branch.** Rate-limit hits are expected user behavior (clicking too fast, hitting Supabase's per-identity throttle); logging them would be noise. Generic failures are the "Supabase outage / network down / unknown new code" bucket where a Sentry alert is actually informative. Per `web/CLAUDE.md`: capture unexpected errors, not validation errors or user cancellations.
+- **Mock at the third-party seam in the integration test.** Mocking `@/lib/supabase` and letting the real `resendConfirmation` run preserves the layer's promise — exercise real wiring, only stub what we don't own.
+- **No redundant Resend wiring test in `SignUpForm.test.tsx`.** The integration test asserts the same args after the same user flow with strictly higher fidelity (real router, real `useSearch`). Per the overlap rule in `web/CLAUDE.md`, keep the faster integration test, drop the lower-fidelity duplicate.
 
 **Verification:**
 
@@ -241,7 +252,7 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 - `e2e/tests/_infra/config-sync.spec.ts` (commit 4)
 - `web/src/lib/supabase.ts` (commit 4)
 - `web/src/router.tsx` (commits 4, 5, 6)
-- `web/src/contexts/AuthContext.tsx` + `.ts` (commits 4, 7)
+- `web/src/contexts/AuthContext.tsx` + `.ts` (commit 4)
 - `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commits 4, 5, 6, 7)
 - `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` (commit 7)
 - `web/src/lib/route-guards.ts` — _kept_, no modifications across the rework
@@ -249,6 +260,7 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 **New across commits 4-8:**
 
 - `web/src/lib/auth-redirect.ts` + `.test.ts` (commit 6)
+- `web/src/lib/auth-resend.ts` + `.test.ts` (commit 7)
 - `web/src/tests/integration/root-routing.integration.test.tsx` (commit 5)
 - `web/src/tests/integration/signup-resend.integration.test.tsx` (commit 7)
 - `e2e/fixtures/mailpit.ts` (commit 8)

From bab83862c25fa7108be86a42dc986b958186a395 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Thu, 14 May 2026 22:04:57 -0500
Subject: [PATCH 21/25] test(e2e): cover email-confirmation signup paths

Adds magic-link, OTP, and cross-browser preservation tests via a new
Mailpit HTTP fixture, and migrates two pre-existing UI-signup tests off
the now-confirmation-gated path so the suite stays green.
---
 e2e/fixtures/mailpit.ts  |  42 ++++++++++++++
 e2e/tests/auth.spec.ts   | 116 +++++++++++++++++++++++++++++++++++++++
 e2e/tests/league.spec.ts |  28 +++-------
 e2e/tests/team.spec.ts   |  17 ++----
 4 files changed, 171 insertions(+), 32 deletions(-)
 create mode 100644 e2e/fixtures/mailpit.ts

diff --git a/e2e/fixtures/mailpit.ts b/e2e/fixtures/mailpit.ts
new file mode 100644
index 0000000..b98a69a
--- /dev/null
+++ b/e2e/fixtures/mailpit.ts
@@ -0,0 +1,42 @@
+// e2e Mailpit instance: dev's 54324 + 100 per the e2e port-shift convention.
+// Supabase CLI now ships Mailpit even though its config section is [inbucket].
+const MAILPIT_BASE_URL = 'http://127.0.0.1:54424';
+
+export interface MailpitMessageSummary {
+  ID: string;
+}
+
+export interface MailpitSearchResult {
+  count: number;
+  messages: MailpitMessageSummary[];
+}
+
+export interface MailpitMessage {
+  ID: string;
+  Text: string;
+  HTML: string;
+}
+
+export async function searchByRecipient(email: string): Promise<MailpitSearchResult> {
+  const url = `${MAILPIT_BASE_URL}/api/v1/search?query=${encodeURIComponent(`to:${email}`)}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Mailpit search failed (${res.status}): ${await res.text()}`);
+  }
+  return (await res.json()) as MailpitSearchResult;
+}
+
+export async function getMessage(id: string): Promise<MailpitMessage> {
+  const res = await fetch(`${MAILPIT_BASE_URL}/api/v1/message/${id}`);
+  if (!res.ok) {
+    throw new Error(`Mailpit get message failed (${res.status}): ${await res.text()}`);
+  }
+  return (await res.json()) as MailpitMessage;
+}
+
+export async function clearAll(): Promise<void> {
+  const res = await fetch(`${MAILPIT_BASE_URL}/api/v1/messages`, { method: 'DELETE' });
+  if (!res.ok) {
+    throw new Error(`Mailpit clear failed (${res.status}): ${await res.text()}`);
+  }
+}
diff --git a/e2e/tests/auth.spec.ts b/e2e/tests/auth.spec.ts
index 1bde757..7e7b7e0 100644
--- a/e2e/tests/auth.spec.ts
+++ b/e2e/tests/auth.spec.ts
@@ -1,6 +1,9 @@
 import { expect, test } from '@playwright/test';
+import { randomUUID } from 'node:crypto';
 
 import { createTestUser } from '../fixtures/auth';
+import { seedLeague, seedLeagueInvite } from '../fixtures/league';
+import { clearAll, getMessage, searchByRecipient } from '../fixtures/mailpit';
 import { resetDb } from '../fixtures/reset';
 import { seedCurrentSeason, seedMinimalGrid } from '../fixtures/seed';
 import { signInAs } from '../fixtures/session';
@@ -9,6 +12,7 @@ import { seedTeamForUser } from '../fixtures/team';
 test.describe('auth', () => {
   test.beforeEach(async () => {
     await resetDb();
+    await clearAll();
   });
 
   test('signs in with real credentials and lands on the leagues dashboard', async ({ page }) => {
@@ -35,6 +39,118 @@ test.describe('auth', () => {
     await expect(page).toHaveURL('/');
   });
 
+  test('completes signup via the magic link in the confirmation email', async ({ page }) => {
+    const unique = randomUUID();
+    const email = `signup-link-${unique}@e2e.local`;
+    const password = 'e2e-password';
+    const displayName = `Test Link ${unique.slice(0, 8)}`;
+
+    await page.goto('/sign-up');
+    await page.getByLabel('Display Name').fill(displayName);
+    await page.getByLabel('Email').fill(email);
+    await page.getByLabel('Password', { exact: true }).fill(password);
+    await page.getByLabel('Confirm Password').fill(password);
+    await page.locator('form').getByRole('button', { name: 'Sign Up' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Check your email' })).toBeVisible();
+    await expect(page.getByText(email)).toBeVisible();
+
+    await expect
+      .poll(async () => (await searchByRecipient(email)).count, { timeout: 10_000 })
+      .toBe(1);
+
+    const search = await searchByRecipient(email);
+    const message = await getMessage(search.messages[0].ID);
+    const linkMatch = message.HTML.match(/href="([^"]*\/auth\/v1\/verify[^"]*)"/);
+    if (!linkMatch) throw new Error('Could not find confirmation URL in email HTML');
+    const confirmationUrl = linkMatch[1].replace(/&amp;/g, '&');
+
+    await page.goto(confirmationUrl);
+    await expect(page).toHaveURL('/create-team');
+  });
+
+  test('completes signup via the OTP code from the confirmation email', async ({ page }) => {
+    const unique = randomUUID();
+    const email = `signup-otp-${unique}@e2e.local`;
+    const password = 'e2e-password';
+    const displayName = `Test OTP ${unique.slice(0, 8)}`;
+
+    await page.goto('/sign-up');
+    await page.getByLabel('Display Name').fill(displayName);
+    await page.getByLabel('Email').fill(email);
+    await page.getByLabel('Password', { exact: true }).fill(password);
+    await page.getByLabel('Confirm Password').fill(password);
+    await page.locator('form').getByRole('button', { name: 'Sign Up' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Check your email' })).toBeVisible();
+
+    await expect
+      .poll(async () => (await searchByRecipient(email)).count, { timeout: 10_000 })
+      .toBe(1);
+
+    const search = await searchByRecipient(email);
+    const message = await getMessage(search.messages[0].ID);
+    const tokenMatch = message.Text.match(/\b(\d{6})\b/);
+    if (!tokenMatch) throw new Error('Could not find OTP token in email text');
+
+    await page.getByLabel('Confirmation code').fill(tokenMatch[1]);
+
+    await expect(page).toHaveURL('/create-team');
+  });
+
+  test('preserves /join/<token> across browsers via emailRedirectTo', async ({ browser }) => {
+    const owner = await createTestUser({ emailPrefix: 'cross-owner' });
+    const season = await seedCurrentSeason();
+    const grid = await seedMinimalGrid({ seasonId: season.id });
+    await seedTeamForUser(owner, {
+      driverIds: grid.drivers.slice(0, 5).map((d) => d.id),
+      constructorIds: grid.constructors.slice(0, 2).map((c) => c.id),
+    });
+    const leagueName = `Cross-Browser Paddock ${randomUUID().slice(0, 8)}`;
+    const league = await seedLeague(owner, { name: leagueName, isPrivate: true });
+    const invite = await seedLeagueInvite(owner, league.id);
+    const joinPath = `/join/${invite.token}`;
+
+    const unique = randomUUID();
+    const email = `cross-browser-${unique}@e2e.local`;
+    const password = 'e2e-password';
+    const displayName = `Cross ${unique.slice(0, 8)}`;
+
+    // Browser A: sign up on /sign-up?redirect=<joinPath>, then close. The
+    // signup-side context shares no storage with Browser B, so the implicit
+    // flow's auto-detect on B has to work from URL fragment alone — the
+    // failure mode that killed PKCE during the rework.
+    const contextA = await browser.newContext();
+    const pageA = await contextA.newPage();
+    await pageA.goto(`/sign-up?redirect=${encodeURIComponent(joinPath)}`);
+    await pageA.getByLabel('Display Name').fill(displayName);
+    await pageA.getByLabel('Email').fill(email);
+    await pageA.getByLabel('Password', { exact: true }).fill(password);
+    await pageA.getByLabel('Confirm Password').fill(password);
+    await pageA.locator('form').getByRole('button', { name: 'Sign Up' }).click();
+    await expect(pageA.getByRole('heading', { name: 'Check your email' })).toBeVisible();
+    await contextA.close();
+
+    await expect
+      .poll(async () => (await searchByRecipient(email)).count, { timeout: 10_000 })
+      .toBe(1);
+    const search = await searchByRecipient(email);
+    const message = await getMessage(search.messages[0].ID);
+    const linkMatch = message.HTML.match(/href="([^"]*\/auth\/v1\/verify[^"]*)"/);
+    if (!linkMatch) throw new Error('Could not find confirmation URL in email HTML');
+    const confirmationUrl = linkMatch[1].replace(/&amp;/g, '&');
+
+    // Browser B: fresh context with zero prior auth state. Supabase's SDK
+    // strips the access_token fragment after parsing but leaves a bare `#`,
+    // hence the optional trailing `#` in the URL match.
+    const contextB = await browser.newContext();
+    const pageB = await contextB.newPage();
+    await pageB.goto(confirmationUrl);
+    await expect(pageB).toHaveURL(new RegExp(`/join/${invite.token}#?$`));
+    await expect(pageB.getByText(leagueName)).toBeVisible();
+    await contextB.close();
+  });
+
   test('sign out clears the session so protected routes redirect again', async ({ page }) => {
     const user = await createTestUser();
     const season = await seedCurrentSeason();
diff --git a/e2e/tests/league.spec.ts b/e2e/tests/league.spec.ts
index c97bb17..9753fdd 100644
--- a/e2e/tests/league.spec.ts
+++ b/e2e/tests/league.spec.ts
@@ -62,7 +62,7 @@ test.describe('league', () => {
     await contextB.close();
   });
 
-  test('User B browses available leagues, joins User A\'s public league from the list', async ({
+  test("User B browses available leagues, joins User A's public league from the list", async ({
     browser,
   }) => {
     const userA = await createTestUser({ emailPrefix: 'public-owner' });
@@ -96,10 +96,11 @@ test.describe('league', () => {
     await contextB.close();
   });
 
-  test('unauthenticated visitor to /join/$token signs up, creates a team, and joins', async ({
+  test('authenticated visitor without a team visits /join/$token, creates a team, and joins', async ({
     page,
   }) => {
     const owner = await createTestUser({ emailPrefix: 'owner' });
+    const joiner = await createTestUser({ emailPrefix: 'joiner' });
     const season = await seedCurrentSeason();
     const grid = await seedMinimalGrid({ seasonId: season.id });
     await seedTeamForUser(owner, {
@@ -111,27 +112,16 @@ test.describe('league', () => {
     const invite = await seedLeagueInvite(owner, league.id);
 
     const joinPath = `/join/${invite.token}`;
-    const unique = randomUUID();
-    const email = `joiner-${unique}@e2e.local`;
-    const password = 'e2e-password';
-    const displayName = `Joiner ${unique.slice(0, 8)}`;
-    const teamName = `Team ${unique.slice(0, 8)}`;
+    const teamName = `Team ${randomUUID().slice(0, 8)}`;
+
+    await signInAs(page, joiner);
+    await expect(page).toHaveURL('/create-team');
 
     await page.goto(joinPath);
     await expect(page.getByText(leagueName)).toBeVisible();
 
-    // Sign-up preserves ?redirect=/join/${token} all the way through.
-    await page.getByRole('link', { name: 'Create Account' }).click();
-    await expect(page).toHaveURL(new RegExp(`/sign-up\\?redirect=${encodeURIComponent(joinPath)}`));
-
-    await page.getByLabel('Display Name').fill(displayName);
-    await page.getByLabel('Email').fill(email);
-    await page.getByLabel('Password', { exact: true }).fill(password);
-    await page.getByLabel('Confirm Password').fill(password);
-    await page.locator('form').getByRole('button', { name: 'Sign Up' }).click();
-
-    // Back on the invite page, now authenticated but without a team.
-    await expect(page).toHaveURL(joinPath);
+    // Authenticated but without a team — the invite page surfaces Create Team
+    // with ?redirect=/join/${token} preserved through the team-creation round-trip.
     await page.getByRole('link', { name: 'Create Team' }).click();
     await expect(page).toHaveURL(
       new RegExp(`/create-team\\?redirect=${encodeURIComponent(joinPath)}`),
diff --git a/e2e/tests/team.spec.ts b/e2e/tests/team.spec.ts
index 2d150dc..c85cd60 100644
--- a/e2e/tests/team.spec.ts
+++ b/e2e/tests/team.spec.ts
@@ -12,20 +12,11 @@ test.describe('team', () => {
     await resetDb();
   });
 
-  test('new user signs up, creates a team, and lands on /my-team', async ({ page }) => {
-    const unique = randomUUID();
-    const email = `signup-${unique}@e2e.local`;
-    const password = 'e2e-password';
-    const displayName = `Signup ${unique.slice(0, 8)}`;
-    const teamName = `Team ${unique.slice(0, 8)}`;
-
-    await page.goto('/sign-up');
-    await page.getByLabel('Display Name').fill(displayName);
-    await page.getByLabel('Email').fill(email);
-    await page.getByLabel('Password', { exact: true }).fill(password);
-    await page.getByLabel('Confirm Password').fill(password);
-    await page.locator('form').getByRole('button', { name: 'Sign Up' }).click();
+  test('new user creates a team and lands on /my-team', async ({ page }) => {
+    const user = await createTestUser();
+    const teamName = `Team ${randomUUID().slice(0, 8)}`;
 
+    await signInAs(page, user);
     await expect(page).toHaveURL('/create-team');
 
     await page.getByLabel('Team Name').fill(teamName);

From 9bfb5dd2d15073144e7cf0f625384daf6a990174 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Thu, 14 May 2026 22:05:06 -0500
Subject: [PATCH 22/25] docs(plans): sync #164 plan with what commit 8 actually
 shipped

---
 docs/plans/164-email-confirmation-signup.md | 35 ++++++++++++++-------
 1 file changed, 23 insertions(+), 12 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index f4065cc..4b9f4a6 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -47,7 +47,7 @@ Original design: switched the Supabase client to `flowType: 'pkce'` with `detect
 
 ### Commit 2 — `<OtpInput>` primitive + `<CheckEmailNotice>` component (`d4a632b`)
 
-The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type: 'email'` (corrected from the original `'signup'` during the pivot; commit 4 keeps this corrected value).
+The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type: 'signup'` — the type string Supabase's email-confirmation flow uses for OTPs minted via `signUp`. End-to-end verified against real Supabase by the OTP signup E2E in commit 8.
 
 ### Commit 3 — Enable confirmations + SignUpForm wiring (`de592bc`)
 
@@ -223,23 +223,32 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 
 ---
 
-### Commit 8 — E2E coverage for magic-link and OTP signup paths
+### Commit 8 — E2E coverage for magic-link, OTP, and cross-browser signup paths
 
-**Goal:** cross-system assertion that the wired-up flow works end-to-end through a real browser, against the local Supabase + Mailpit stack.
+**Goal:** cross-system assertion that the wired-up flow works end-to-end through a real browser, against the local Supabase + Mailpit stack. Also promotes cross-browser invite preservation from manual verification (originally listed under "End-to-end verification" step 3) to automated coverage, and repairs two pre-existing UI-signup tests that commits 4-7 silently broke by routing UI signup into the email-confirmation gate.
 
 **Files added:**
 
-- `e2e/fixtures/mailpit.ts` — thin HTTP wrappers. `searchByRecipient(email)` → `GET /api/v1/search?query=to:<encoded>`. `getMessage(id)` → `GET /api/v1/message/{id}`. `clearAll()` → `DELETE /api/v1/messages`. Targets `http://127.0.0.1:54424` (e2e Mailpit, dev `54324` + 100 per the port-shift convention). No internal polling — callsites wrap `searchByRecipient` in Playwright's `expect.poll(...).toHaveProperty('count', 1)` so waits are visible at the callsite and integrate with Playwright's timeout reporting.
+- `e2e/fixtures/mailpit.ts` — thin HTTP wrappers. `searchByRecipient(email)` → `GET /api/v1/search?query=to:<encoded>`. `getMessage(id)` → `GET /api/v1/message/{id}`. `clearAll()` → `DELETE /api/v1/messages`. Targets `http://127.0.0.1:54424` (e2e Mailpit, dev `54324` + 100 per the port-shift convention). No internal polling — callsites wrap `searchByRecipient` in Playwright's `expect.poll(async () => (await searchByRecipient(email)).count).toBe(1)` so waits are visible at the callsite and integrate with Playwright's timeout reporting.
 
 **Files modified:**
 
-- `e2e/tests/auth.spec.ts` — add two tests. `beforeEach` clears Mailpit.
-  - **Magic-link path:** fill signup form via UI → assert `<CheckEmailNotice>` appears → `expect.poll(() => mailpit.searchByRecipient(email)).toHaveProperty('count', 1)` → GET the message → regex `Text` for the verify URL → `page.goto(verifyUrl)` → assert the app shows `/create-team`.
-  - **OTP path:** fill signup form → assert `<CheckEmailNotice>` → poll Mailpit → GET → regex `Text` for `/Or enter this code in the app: \*(\d{6})\*/` → type the 6 digits into the underlying OTP input (queryable via its `aria-label`; the slot `<div>`s are `aria-hidden`) → assert the app shows `/create-team`.
+- `e2e/tests/auth.spec.ts` — add three tests. `beforeEach` also clears Mailpit.
+  - **Magic-link path:** fill signup form via UI → assert `<CheckEmailNotice>` heading and the typed email are visible → poll Mailpit until `count === 1` → fetch the message → regex `message.HTML` for `href="([^"]*\/auth\/v1\/verify[^"]*)"` (the only `{{ .ConfirmationURL }}` substitution in the template) → un-escape `&amp;` → `page.goto(confirmationUrl)` → assert the app shows `/create-team`. URL extraction goes against `HTML` rather than `Text` because the `href` attribute is more stable across template restructuring than the auto-generated text layout.
+  - **OTP path:** fill signup form → assert `<CheckEmailNotice>` → poll Mailpit → fetch the message → regex `message.Text` for `\b(\d{6})\b` (the only 6-digit sequence in the email) → fill the `Confirmation code` input via `getByLabel`. The `<OtpInput>`'s `onComplete` fires `verifyOtp` automatically once 6 digits land, so no explicit Verify click. Assert the app shows `/create-team`.
+  - **Cross-browser preservation:** seed owner + league + private invite → in `contextA`, sign up at `/sign-up?redirect=/join/<token>` → stop at `<CheckEmailNotice>`, close `contextA` → poll Mailpit, extract magic-link URL → in a fresh `contextB` with zero prior storage, `page.goto(magicLinkUrl)` → assert URL matches `/join/<token>#?$` (Supabase's SDK leaves a bare `#` after stripping the access_token fragment via `history.replaceState`) and the league name renders. Owns three failure modes nothing lower in the suite can see: dynamic `emailRedirectTo` clearing the `additional_redirect_urls` allowlist, implicit-flow auto-detect working against a client with zero prior state (the specific failure mode that killed PKCE), and `requireAuth` + the `JoinInvite` loader surviving the session-just-materialized timing window at a non-root destination.
+- `e2e/tests/team.spec.ts` — `'new user signs up, creates a team, and lands on /my-team'` → `'new user creates a team and lands on /my-team'`: replace the UI signup steps with `createTestUser` + `signInAs`. The signup behavior the test used to incidentally exercise is now owned by the dedicated auth tests above.
+- `e2e/tests/league.spec.ts` — `'unauthenticated visitor to /join/$token signs up, creates a team, and joins'` → `'authenticated visitor without a team visits /join/$token, creates a team, and joins'`: same migration. Retains the `?redirect=` preservation assertion through the `/create-team` round-trip; signup-side redirect preservation is now covered by the cross-browser auth test.
+
+**Decisions worth recording:**
+
+- **Email rate limit didn't need bumping.** `e2e/supabase/config.toml:149` keeps `email_sent = 2` per hour. Empirically the limit applies per-identity in gotrue rather than per-IP globally, so each test's unique email gets its own quota. Three confirmation-email sends per run all delivered cleanly. Plan's production note about raising the limit still stands for unrelated reasons (real signup volume).
+- **OTP `Text`-body regex over a specific anchor string.** Earlier draft proposed matching `/Or enter this code in the app: \*(\d{6})\*/`, but that text isn't in the actual template. The shipped regex `\b(\d{6})\b` finds the only 6-digit sequence in the auto-generated text body — resilient to template wording changes while still deterministic for this template.
+- **Trailing `#` in the cross-browser destination URL is a Supabase SDK behavior, not a bug.** `_initialize` calls `history.replaceState(null, '', cleanedUrl)` to scrub `access_token=...` after parsing, and the cleanup leaves a bare `#` behind. The URL match uses an optional `#?$` rather than working around the SDK.
 
 **Verification:**
 
-1. `npm run e2e` green (existing suite + the two new tests).
+1. `npm run e2e` green (14 tests total: existing suite + three new auth tests, with two pre-existing tests migrated off UI signup).
 
 ---
 
@@ -255,6 +264,9 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 - `web/src/contexts/AuthContext.tsx` + `.ts` (commit 4)
 - `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commits 4, 5, 6, 7)
 - `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` (commit 7)
+- `e2e/tests/auth.spec.ts` (commit 8 — adds magic-link, OTP, and cross-browser tests; `beforeEach` also clears Mailpit)
+- `e2e/tests/team.spec.ts` (commit 8 — migrates UI-signup test to `createTestUser` + `signInAs`)
+- `e2e/tests/league.spec.ts` (commit 8 — same migration on the `/join/<token>` test)
 - `web/src/lib/route-guards.ts` — _kept_, no modifications across the rework
 
 **New across commits 4-8:**
@@ -264,7 +276,6 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 - `web/src/tests/integration/root-routing.integration.test.tsx` (commit 5)
 - `web/src/tests/integration/signup-resend.integration.test.tsx` (commit 7)
 - `e2e/fixtures/mailpit.ts` (commit 8)
-- New tests in `e2e/tests/auth.spec.ts` (commit 8)
 
 **Deleted in commit 4:**
 
@@ -284,9 +295,9 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 
 ## End-to-end verification (after all commits 4-8)
 
-1. **Magic-link happy path:** Sign up with new email → `<CheckEmailNotice>` → check Mailpit → click link → land on `/create-team` logged in.
-2. **OTP happy path:** Sign up with new email → `<CheckEmailNotice>` → check Mailpit → type 6-digit code → land on `/create-team` logged in.
-3. **Cross-browser invite preservation:** Sign up from `/sign-up?redirect=/join/<token>` on Browser A → click link in Browser B → land directly at `/join/<token>` signed in.
+1. **Magic-link happy path:** Sign up with new email → `<CheckEmailNotice>` → check Mailpit → click link → land on `/create-team` logged in. _(Automated in commit 8.)_
+2. **OTP happy path:** Sign up with new email → `<CheckEmailNotice>` → check Mailpit → type 6-digit code → land on `/create-team` logged in. _(Automated in commit 8.)_
+3. **Cross-browser invite preservation:** Sign up from `/sign-up?redirect=/join/<token>` on Browser A → click link in Browser B → land directly at `/join/<token>` signed in. _(Automated in commit 8 via two Playwright `browser.newContext()` instances.)_
 4. **Resend:** Sign up → click Resend → second email arrives → either email's link OR the latest OTP completes verification.
 5. **Link failure:** Click an expired/consumed link → user is routed to `/sign-up` with `<InlineError>` above the form with a friendly message; navigating away clears the message.
 6. **Authed user at `/`:** Visit `/` signed in → bounce to `/leagues` (with team) or `/create-team` (without). Sign out → return to `/` → `LandingPage` renders normally.

From fe0caa12e6677d9436a1c62009d53828e7670a05 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Thu, 14 May 2026 22:37:55 -0500
Subject: [PATCH 23/25] test(e2e): cover resend confirmation email path

Unit and integration coverage exists for the resend wiring and the
rate-limit UX path, but neither proves `supabase.auth.resend` actually
produces a second email against the real Supabase + Mailpit stack. The
new E2E owns that failure mode.

Raise the e2e `email_sent` rate cap above the tight dev default so the
suite has headroom for signup + resend in a single run. Drop the e2e
per-recipient `max_frequency` below `1s` so the test doesn't have to
sleep past gotrue's throttle. gotrue treats `"0s"` as unset and falls
back to a hardcoded ~60s floor, so use `"1ms"` instead.

Extend the dev/e2e config-sync regex to ignore both keys.
---
 e2e/supabase/config.toml             |  4 ++--
 e2e/tests/_infra/config-sync.spec.ts |  7 +++++-
 e2e/tests/auth.spec.ts               | 36 ++++++++++++++++++++++++++++
 3 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/e2e/supabase/config.toml b/e2e/supabase/config.toml
index fa31a39..b75ef50 100644
--- a/e2e/supabase/config.toml
+++ b/e2e/supabase/config.toml
@@ -150,7 +150,7 @@ password_requirements = ""
 
 [auth.rate_limit]
 # Number of emails that can be sent per hour. Requires auth.email.smtp to be enabled.
-email_sent = 2
+email_sent = 30
 # Number of SMS messages that can be sent per hour. Requires auth.sms to be enabled.
 sms_sent = 30
 # Number of anonymous sign-ins that can be made per hour per IP address. Requires enable_anonymous_sign_ins = true.
@@ -181,7 +181,7 @@ enable_confirmations = true
 # If enabled, users will need to reauthenticate or have logged in recently to change their password.
 secure_password_change = false
 # Controls the minimum amount of time that must pass before sending another signup confirmation or password reset email.
-max_frequency = "1s"
+max_frequency = "1ms"
 # Number of characters used in the email OTP.
 otp_length = 6
 # Number of seconds before the email OTP expires (defaults to 1 hour).
diff --git a/e2e/tests/_infra/config-sync.spec.ts b/e2e/tests/_infra/config-sync.spec.ts
index 4018c47..338af57 100644
--- a/e2e/tests/_infra/config-sync.spec.ts
+++ b/e2e/tests/_infra/config-sync.spec.ts
@@ -19,7 +19,12 @@ const E2E_CONFIG = path.join(REPO_ROOT, 'e2e', 'supabase', 'config.toml');
 //     Services Topology) to run alongside dev
 //   - site_url / additional_redirect_urls: contain the web port
 //     (5173 dev, 5273 e2e), so they shift too
-const IGNORED_KEY_RE = /^\s*(project_id|[a-z_]*port|site_url|additional_redirect_urls)\s*=/;
+//   - email_sent: e2e raises the per-hour cap so the suite has
+//     headroom for signup + resend within a single run
+//   - max_frequency: e2e drops the per-user resend cool-down to 0s
+//     so resend tests don't have to sleep past gotrue's throttle
+const IGNORED_KEY_RE =
+  /^\s*(project_id|[a-z_]*port|site_url|additional_redirect_urls|email_sent|max_frequency)\s*=/;
 
 test('api/supabase/config.toml and e2e/supabase/config.toml stay in sync', () => {
   const dev = readFileSync(DEV_CONFIG, 'utf8').split('\n');
diff --git a/e2e/tests/auth.spec.ts b/e2e/tests/auth.spec.ts
index 7e7b7e0..c48afe2 100644
--- a/e2e/tests/auth.spec.ts
+++ b/e2e/tests/auth.spec.ts
@@ -98,6 +98,42 @@ test.describe('auth', () => {
     await expect(page).toHaveURL('/create-team');
   });
 
+  test('resends the confirmation email and confirms via the resent link', async ({ page }) => {
+    const unique = randomUUID();
+    const email = `signup-resend-${unique}@e2e.local`;
+    const password = 'e2e-password';
+    const displayName = `Test Resend ${unique.slice(0, 8)}`;
+
+    await page.goto('/sign-up');
+    await page.getByLabel('Display Name').fill(displayName);
+    await page.getByLabel('Email').fill(email);
+    await page.getByLabel('Password', { exact: true }).fill(password);
+    await page.getByLabel('Confirm Password').fill(password);
+    await page.locator('form').getByRole('button', { name: 'Sign Up' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Check your email' })).toBeVisible();
+
+    await expect
+      .poll(async () => (await searchByRecipient(email)).count, { timeout: 10_000 })
+      .toBe(1);
+
+    await page.getByRole('button', { name: 'Resend the code' }).click();
+
+    await expect
+      .poll(async () => (await searchByRecipient(email)).count, { timeout: 10_000 })
+      .toBe(2);
+
+    // Mailpit returns messages newest-first; [0] is the resent email.
+    const search = await searchByRecipient(email);
+    const message = await getMessage(search.messages[0].ID);
+    const linkMatch = message.HTML.match(/href="([^"]*\/auth\/v1\/verify[^"]*)"/);
+    if (!linkMatch) throw new Error('Could not find confirmation URL in resent email HTML');
+    const confirmationUrl = linkMatch[1].replace(/&amp;/g, '&');
+
+    await page.goto(confirmationUrl);
+    await expect(page).toHaveURL('/create-team');
+  });
+
   test('preserves /join/<token> across browsers via emailRedirectTo', async ({ browser }) => {
     const owner = await createTestUser({ emailPrefix: 'cross-owner' });
     const season = await seedCurrentSeason();

From b4dfab2a2be5866aa12b3efa2c718523d47f3a17 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Thu, 14 May 2026 22:38:03 -0500
Subject: [PATCH 24/25] docs(plans): sync #164 plan with what commit 9 actually
 shipped

Add commit 9 section for the resend E2E, flip verification item 4
from manual to automated, and update the cross-cutting "Critical
files" annotations.
---
 docs/plans/164-email-confirmation-signup.md | 37 +++++++++++++++++----
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/docs/plans/164-email-confirmation-signup.md b/docs/plans/164-email-confirmation-signup.md
index 4b9f4a6..0f36c05 100644
--- a/docs/plans/164-email-confirmation-signup.md
+++ b/docs/plans/164-email-confirmation-signup.md
@@ -252,24 +252,47 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 
 ---
 
+### Commit 9 — E2E coverage for resend confirmation email path
+
+**Goal:** promote the resend smoke from manual to automated. The unit/component tests cover the rate-limit UX path against a mocked Supabase; the integration test covers SignUpForm → CheckEmailNotice → resend wiring with a mocked seam. Neither proves `supabase.auth.resend({ type: 'signup', ... })` actually produces a second email against the real Supabase + Mailpit stack — that's the failure mode this commit owns.
+
+**Files modified:**
+
+- `e2e/tests/auth.spec.ts` — new test `resends the confirmation email and confirms via the resent link`. Signs up via the UI, polls Mailpit until the first email arrives, clicks "Resend the code", polls until count reaches 2, then completes signup via the resent email's `/auth/v1/verify` link. Mailpit returns messages newest-first so `messages[0]` is the resent one.
+- `e2e/supabase/config.toml` — `email_sent = 30` (was 2). The dev value is intentionally tight; the e2e suite now performs signup + resend in a single run and needs headroom. `[auth.email] max_frequency = "1ms"` (was `"1s"`). gotrue treats `"0s"` as unset and falls back to a hardcoded ~60s floor on the `/resend` endpoint; any positive value bypasses that floor. `"1ms"` makes the per-recipient cool-down effectively zero without tripping the fallback.
+- `e2e/tests/_infra/config-sync.spec.ts` — extend `IGNORED_KEY_RE` to ignore `email_sent` and `max_frequency`. Both must legitimately differ between dev and e2e.
+
+**Decisions worth recording:**
+
+- **gotrue's hidden `max_frequency` floor.** Setting `max_frequency = "0s"` does *not* disable the per-recipient resend throttle — gotrue rejects with "you can only request this after 59 seconds." Verified empirically against `gotrue:v2.188.1`. A positive value (any > 0) takes effect as configured; `0` falls through to a 60s default. The plan keeps `"1ms"` rather than something larger so test runtime isn't gated on a real-world throttle.
+- **Rate-limit UX path is not tested here.** With `email_sent = 30` and `max_frequency = "1ms"`, the rate-limit branch in `CheckEmailNotice` (renders "You've sent too many confirmation requests.") is unreachable in this run. That branch is covered by `CheckEmailNotice.test.tsx`'s mocked `over_email_send_rate_limit` test — no E2E duplication needed.
+- **Per-test config drift now covered by `IGNORED_KEY_RE`.** The pattern matches by line, so `max_frequency` is excluded across `[auth.email]`, `[auth.sms]`, and `[auth.mfa.phone]`. The suite doesn't exercise sms/mfa, so silent drift on those is an acceptable trade for the simpler regex.
+
+**Verification:**
+
+1. `cd e2e/supabase && supabase stop && supabase start` to pick up the config change.
+2. `npm run e2e` green (15 tests total: previous 14 + the new resend test).
+
+---
+
 ## Critical files
 
-**Modified across commits 4-8:**
+**Modified across commits 4-9:**
 
 - `api/supabase/config.toml` (commit 4)
-- `e2e/supabase/config.toml` (commit 4)
-- `e2e/tests/_infra/config-sync.spec.ts` (commit 4)
+- `e2e/supabase/config.toml` (commits 4, 9 — commit 9 bumps `email_sent` and drops `max_frequency` for the resend test)
+- `e2e/tests/_infra/config-sync.spec.ts` (commits 4, 9 — commit 9 adds `email_sent` and `max_frequency` to `IGNORED_KEY_RE`)
 - `web/src/lib/supabase.ts` (commit 4)
 - `web/src/router.tsx` (commits 4, 5, 6)
 - `web/src/contexts/AuthContext.tsx` + `.ts` (commit 4)
 - `web/src/components/auth/SignUpForm/SignUpForm.tsx` (commits 4, 5, 6, 7)
 - `web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx` (commit 7)
-- `e2e/tests/auth.spec.ts` (commit 8 — adds magic-link, OTP, and cross-browser tests; `beforeEach` also clears Mailpit)
+- `e2e/tests/auth.spec.ts` (commits 8, 9 — commit 8 adds magic-link, OTP, and cross-browser tests + `beforeEach` Mailpit clear; commit 9 adds the resend test)
 - `e2e/tests/team.spec.ts` (commit 8 — migrates UI-signup test to `createTestUser` + `signInAs`)
 - `e2e/tests/league.spec.ts` (commit 8 — same migration on the `/join/<token>` test)
 - `web/src/lib/route-guards.ts` — _kept_, no modifications across the rework
 
-**New across commits 4-8:**
+**New across commits 4-9:**
 
 - `web/src/lib/auth-redirect.ts` + `.test.ts` (commit 6)
 - `web/src/lib/auth-resend.ts` + `.test.ts` (commit 7)
@@ -293,12 +316,12 @@ The typed-OTP path UI. Unchanged by the rework. `verifyOtp` is called with `type
 
 ---
 
-## End-to-end verification (after all commits 4-8)
+## End-to-end verification (after all commits 4-9)
 
 1. **Magic-link happy path:** Sign up with new email → `<CheckEmailNotice>` → check Mailpit → click link → land on `/create-team` logged in. _(Automated in commit 8.)_
 2. **OTP happy path:** Sign up with new email → `<CheckEmailNotice>` → check Mailpit → type 6-digit code → land on `/create-team` logged in. _(Automated in commit 8.)_
 3. **Cross-browser invite preservation:** Sign up from `/sign-up?redirect=/join/<token>` on Browser A → click link in Browser B → land directly at `/join/<token>` signed in. _(Automated in commit 8 via two Playwright `browser.newContext()` instances.)_
-4. **Resend:** Sign up → click Resend → second email arrives → either email's link OR the latest OTP completes verification.
+4. **Resend:** Sign up → click Resend → second email arrives → either email's link OR the latest OTP completes verification. _(Automated in commit 9.)_
 5. **Link failure:** Click an expired/consumed link → user is routed to `/sign-up` with `<InlineError>` above the form with a friendly message; navigating away clears the message.
 6. **Authed user at `/`:** Visit `/` signed in → bounce to `/leagues` (with team) or `/create-team` (without). Sign out → return to `/` → `LandingPage` renders normally.
 7. **Existing e2e tests:** `npm run e2e` all green (admin fixture continues working via `email_confirm: true`).

From ca1bf3e09c6b3586d4e0c6458493a3873f6f76f5 Mon Sep 17 00:00:00 2001
From: Mark <madlyinanger37@gmail.com>
Date: Thu, 14 May 2026 23:44:41 -0500
Subject: [PATCH 25/25] fix(auth): clear stuck overlay and capture unexpected
 verifyOtp errors

completeSignUp now wraps navigate in try/finally so completeAuthTransition
runs even when navigation rejects, preventing the post-confirmation overlay
from getting stuck. CheckEmailNotice.verify splits its catch: AuthApiError
keeps the "code didn't match" copy; everything else gets a generic message
and is captured to Sentry, mirroring the resend path.
---
 .../CheckEmailNotice.test.tsx                 | 21 ++++++++++++--
 .../CheckEmailNotice/CheckEmailNotice.tsx     | 11 ++++++--
 .../auth/SignUpForm/SignUpForm.test.tsx       | 28 +++++++++++++++++--
 .../components/auth/SignUpForm/SignUpForm.tsx |  7 +++--
 4 files changed, 59 insertions(+), 8 deletions(-)

diff --git a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
index 9bbc186..928f23b 100644
--- a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
+++ b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.test.tsx
@@ -1,6 +1,6 @@
 import { supabase } from '@/lib/supabase';
 import * as Sentry from '@sentry/react';
-import { AuthApiError, type AuthError } from '@supabase/supabase-js';
+import { AuthApiError } from '@supabase/supabase-js';
 import { render, screen, waitFor } from '@testing-library/react';
 import { userEvent } from '@testing-library/user-event';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -69,7 +69,7 @@ describe('CheckEmailNotice', () => {
     const user = userEvent.setup();
     vi.mocked(supabase.auth.verifyOtp).mockResolvedValue({
       data: { user: null, session: null },
-      error: new Error('Invalid code') as AuthError,
+      error: new AuthApiError('Token has expired or is invalid', 403, 'otp_expired'),
     });
     const props = setup();
 
@@ -79,6 +79,23 @@ describe('CheckEmailNotice', () => {
     expect(alert).toHaveTextContent(/that code didn't match/i);
     expect(props.onVerified).not.toHaveBeenCalled();
     expect(screen.getByLabelText(/confirmation code/i)).toHaveValue('123456');
+    expect(Sentry.captureException).not.toHaveBeenCalled();
+  });
+
+  it('renders a generic failure message and reports to Sentry when verifyOtp throws a non-AuthApiError', async () => {
+    const user = userEvent.setup();
+    const networkError = new Error('Network down');
+    vi.mocked(supabase.auth.verifyOtp).mockRejectedValue(networkError);
+    const props = setup();
+
+    await user.type(screen.getByLabelText(/confirmation code/i), '123456');
+
+    const alert = await screen.findByRole('alert');
+    expect(alert).toHaveTextContent("Couldn't verify the code. Please try again.");
+    expect(props.onVerified).not.toHaveBeenCalled();
+    expect(Sentry.captureException).toHaveBeenCalledWith(networkError, {
+      tags: { component: 'CheckEmailNotice', operation: 'verifyOtp' },
+    });
   });
 
   it('keeps the Verify button disabled and verifyOtp uncalled until 6 digits land', async () => {
diff --git a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
index 6a03839..dd1ed0e 100644
--- a/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
+++ b/web/src/components/auth/CheckEmailNotice/CheckEmailNotice.tsx
@@ -44,8 +44,15 @@ export function CheckEmailNotice({ email, onVerified, onResend }: Props) {
       setError(null);
       setStatus('success');
       onVerified();
-    } catch {
-      setError("That code didn't match. Check your email for the latest one.");
+    } catch (err) {
+      if (isAuthApiError(err)) {
+        setError("That code didn't match. Check your email for the latest one.");
+      } else {
+        Sentry.captureException(err, {
+          tags: { component: 'CheckEmailNotice', operation: 'verifyOtp' },
+        });
+        setError("Couldn't verify the code. Please try again.");
+      }
       setStatus('idle');
     }
   };
diff --git a/web/src/components/auth/SignUpForm/SignUpForm.test.tsx b/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
index 2279a60..dfa0bec 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.test.tsx
@@ -36,10 +36,14 @@ vi.mock('@tanstack/react-router', () => ({
 
 describe('SignUpForm', () => {
   let mockSignUp: ReturnType<typeof vi.fn<AuthContextType['signUp']>>;
+  let mockStartAuthTransition: ReturnType<typeof vi.fn<() => void>>;
+  let mockCompleteAuthTransition: ReturnType<typeof vi.fn<() => void>>;
   let useAuth: typeof import('@/hooks/useAuth').useAuth;
 
   beforeEach(async () => {
     mockSignUp = vi.fn<AuthContextType['signUp']>();
+    mockStartAuthTransition = vi.fn<() => void>();
+    mockCompleteAuthTransition = vi.fn<() => void>();
     useAuth = (await import('@/hooks/useAuth')).useAuth;
     vi.mocked(useAuth).mockReturnValue({
       user: null,
@@ -49,8 +53,8 @@ describe('SignUpForm', () => {
       signIn: vi.fn(),
       signUp: mockSignUp,
       signOut: vi.fn(),
-      startAuthTransition: vi.fn(),
-      completeAuthTransition: vi.fn(),
+      startAuthTransition: mockStartAuthTransition,
+      completeAuthTransition: mockCompleteAuthTransition,
     });
     mockUseSearch.mockReturnValue({});
     mockUseRouteContext.mockReturnValue({ confirmationError: null });
@@ -194,6 +198,26 @@ describe('SignUpForm', () => {
     });
   });
 
+  it('clears the auth transition flag even if post-signup navigation rejects', async () => {
+    mockSignUp.mockResolvedValueOnce({ session: mockSession });
+    mockNavigate.mockRejectedValueOnce(new Error('navigation cancelled'));
+    setup();
+    fireEvent.change(screen.getByLabelText(/display name/i), { target: { value: 'Test User' } });
+    fireEvent.change(screen.getByLabelText(/email/i), { target: { value: 'test@example.com' } });
+    fireEvent.change(screen.getByLabelText(/^password$/i), { target: { value: 'password123' } });
+    fireEvent.change(screen.getByLabelText(/confirm password/i), {
+      target: { value: 'password123' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /sign up/i }));
+
+    await waitFor(() => {
+      expect(mockStartAuthTransition).toHaveBeenCalledTimes(1);
+    });
+    await waitFor(() => {
+      expect(mockCompleteAuthTransition).toHaveBeenCalledTimes(1);
+    });
+  });
+
   it('passes emailRedirectTo for the site origin into signUp', async () => {
     mockSignUp.mockResolvedValueOnce({ session: mockSession });
     setup();
diff --git a/web/src/components/auth/SignUpForm/SignUpForm.tsx b/web/src/components/auth/SignUpForm/SignUpForm.tsx
index 3da73cc..2e64972 100644
--- a/web/src/components/auth/SignUpForm/SignUpForm.tsx
+++ b/web/src/components/auth/SignUpForm/SignUpForm.tsx
@@ -37,8 +37,11 @@ export function SignUpForm() {
 
   const completeSignUp = async () => {
     startAuthTransition();
-    await navigate({ to: destination });
-    completeAuthTransition();
+    try {
+      await navigate({ to: destination });
+    } finally {
+      completeAuthTransition();
+    }
   };
 
   const { message, announce } = useLiveRegion();