---
phase: 01-foundation
plan: 02
subsystem: auth
tags: [next-auth, next.js, tailwind, server-actions, server-components, client-components]

# Dependency graph
requires:
  - phase: 01-foundation/01-01
    provides: "src/lib/auth.ts with signIn/signOut/auth exports; middleware.ts protecting /agent/*"
provides:
  - src/app/agent/login/page.tsx — branded login page with email/password form, error banner, signed-out confirmation
  - src/app/agent/login/PasswordField.tsx — client component for password show/hide toggle
  - src/app/agent/layout.tsx — agent portal layout with defense-in-depth auth() check and header
  - src/app/agent/dashboard/page.tsx — protected dashboard stub showing agent email
  - src/components/ui/LogoutButton.tsx — form-action logout triggering signOut({ redirectTo: "/agent/login?signed_out=1" })
  - public/red.jpg — agent brand photo served as static asset
affects:
  - 01-03
  - all subsequent phases using /agent/* routes or LogoutButton

# Tech tracking
tech-stack:
  added: []
  patterns:
    - Server action inside page file: loginAction with try/catch — re-throw non-AuthError (allows NEXT_REDIRECT to bubble)
    - Client sub-component in same route folder: PasswordField.tsx co-located with login page
    - Defense-in-depth auth: middleware (primary) + layout auth() + page auth() (belt-and-suspenders)
    - Form action pattern for logout: avoids NEXT_REDIRECT catch issues by using <form action={serverAction}>
    - CSS-in-JS style props for brand colors: inline style={{ backgroundColor }} avoids Tailwind JIT misses

key-files:
  created:
    - teressa-copeland-homes/src/app/agent/login/page.tsx
    - teressa-copeland-homes/src/app/agent/login/PasswordField.tsx
    - teressa-copeland-homes/src/app/agent/layout.tsx
    - teressa-copeland-homes/src/app/agent/dashboard/page.tsx
    - teressa-copeland-homes/src/components/ui/LogoutButton.tsx
    - teressa-copeland-homes/public/red.jpg
  modified:
    - teressa-copeland-homes/src/app/page.tsx

key-decisions:
  - "PasswordField extracted to separate 'use client' file co-located in login/ folder — keeps page.tsx as pure server component"
  - "loginAction re-throws non-AuthError (including NEXT_REDIRECT) — critical pattern for Auth.js v5 server actions"
  - "Brand colors applied via inline style props for reliability — Tailwind JIT may not generate one-off hex values"
  - "Agent photo confirmed copied from /Users/ccopeland/Downloads/red.jpg to public/red.jpg"

patterns-established:
  - "Auth server action pattern: catch AuthError only, re-throw everything else (NEXT_REDIRECT must bubble)"
  - "Client sub-component co-location: 'use client' files live in same folder as parent server component"
  - "Defense-in-depth layering: middleware → layout → page all independently verify session"

requirements-completed: [AUTH-01, AUTH-02, AUTH-03, AUTH-04]

# Metrics
duration: 2min
completed: 2026-03-19
---

# Phase 1 Plan 02: Login Pages and Auth UI Summary

**Branded split-screen login page with signIn/signOut server actions, password toggle, and agent dashboard stub — completing all four AUTH requirements visible to the user**

## Performance

- **Duration:** ~2 min
- **Started:** 2026-03-19T19:37:45Z
- **Completed:** 2026-03-19T19:39:35Z
- **Tasks:** 2
- **Files modified:** 6 created, 1 modified

## Accomplishments

- Built full-screen split-layout login page with Teressa's photo left-panel and branded login card right-panel
- Implemented loginAction server action with AuthError-only catch and NEXT_REDIRECT re-throw
- Created PasswordField client sub-component with eye/eye-off SVG icon toggle
- Built agent portal layout with auth() defense-in-depth check and header showing agent email
- Created dashboard stub with auth() belt-and-suspenders check and welcome message
- LogoutButton form-action component calls signOut({ redirectTo: "/agent/login?signed_out=1" })
- Updated homepage to Teressa Copeland Homes placeholder (marketing content deferred to Phase 2)

## Task Commits

Each task was committed atomically:

1. **Task 1: Build the branded login page with password toggle and error handling** - `f221597` (feat)
2. **Task 2: Build the agent portal layout, dashboard stub, and logout mechanism** - `32dc2d3` (feat)

## Files Created/Modified

- `teressa-copeland-homes/src/app/agent/login/page.tsx` - Server component: branded split-screen login, loginAction, error/signed-out banners
- `teressa-copeland-homes/src/app/agent/login/PasswordField.tsx` - Client component: password input with show/hide toggle and eye SVG icons
- `teressa-copeland-homes/src/app/agent/layout.tsx` - Agent layout: auth() defense-in-depth, header with email + sign-out
- `teressa-copeland-homes/src/app/agent/dashboard/page.tsx` - Protected dashboard stub: auth() check + welcome message with email
- `teressa-copeland-homes/src/components/ui/LogoutButton.tsx` - Form-action logout to /agent/login?signed_out=1
- `teressa-copeland-homes/public/red.jpg` - Agent brand photo (copied from /Users/ccopeland/Downloads/red.jpg — confirmed present)
- `teressa-copeland-homes/src/app/page.tsx` - Public homepage updated to Teressa Copeland Homes placeholder

## Decisions Made

- **PasswordField as co-located client sub-component** — extracted to `login/PasswordField.tsx` so `page.tsx` stays a pure server component while the show/hide toggle has access to `useState`
- **loginAction NEXT_REDIRECT re-throw** — `if (error instanceof AuthError)` catches only auth failures; all other errors (including the NEXT_REDIRECT thrown by Next.js router on successful redirect) bubble up naturally
- **Brand colors via inline style props** — hex values `#C9A84C`, `#1B2B4B`, `#FAF9F7` applied via `style={{}}` rather than Tailwind arbitrary values to guarantee they render without JIT generation issues
- **Agent photo confirmed copied** — `/Users/ccopeland/Downloads/red.jpg` existed at execution time and was copied to `public/red.jpg`
- **No forgot-password link** — explicitly omitted per user decision in CONTEXT.md (deferred feature)

## Brand Colors Applied

| Role | Color | Hex |
|------|-------|-----|
| Accent (buttons, focus rings) | Warm gold | `#C9A84C` |
| Primary text / headings | Deep navy | `#1B2B4B` |
| Page background | Warm off-white | `#FAF9F7` |
| Error background | Soft red | `#FEF2F2` |
| Error text | Dark red | `#991B1B` |
| Success background | Soft green | `#F0FDF4` |
| Success text | Dark green | `#166534` |

## Manual Auth Flow Verification Status

Build-time verification passed (npm run build + npx tsc --noEmit). Full runtime flow requires DATABASE_URL + seeded user (pending Neon setup per Plan 01 user setup notes). Expected behavior:

1. Visit /agent/dashboard → redirected to /agent/login (middleware enforces, AUTH-03)
2. Submit wrong credentials → "Invalid email or password." banner (loginAction catches AuthError, AUTH-01)
3. Submit correct credentials → redirects to /agent/dashboard with email visible (AUTH-01)
4. Refresh /agent/dashboard → stays logged in via 7-day JWT cookie (AUTH-02, handled in auth.ts)
5. Click "Sign out" → redirects to /agent/login with "You've been signed out." (AUTH-04)
6. Visit /agent/dashboard while logged out → redirects to /agent/login (AUTH-03)

## Deviations from Plan

None — plan executed exactly as written. All patterns, file paths, color values, and component structures match plan specification.

## Issues Encountered

None beyond confirming the agent photo was present at the specified download path.

## User Setup Required

None beyond what was documented in Plan 01 (Neon database + Vercel env vars). Runtime auth flow requires those to be configured before end-to-end testing is possible.

## Next Phase Readiness

- All four AUTH requirements satisfied at code level (AUTH-01 through AUTH-04)
- Plan 03 and all subsequent /agent/* features can import from AgentLayout — header and session context provided
- LogoutButton is ready to use anywhere inside the /agent/* route tree
- Blockers: Neon + Vercel provisioning still required for runtime testing (carries over from Plan 01)

## Self-Check: PASSED

All key files verified present:
- FOUND: teressa-copeland-homes/src/app/agent/login/page.tsx
- FOUND: teressa-copeland-homes/src/app/agent/login/PasswordField.tsx
- FOUND: teressa-copeland-homes/src/app/agent/layout.tsx
- FOUND: teressa-copeland-homes/src/app/agent/dashboard/page.tsx
- FOUND: teressa-copeland-homes/src/components/ui/LogoutButton.tsx
- FOUND: teressa-copeland-homes/public/red.jpg

All task commits verified in git log:
- FOUND: f221597 (Task 1)
- FOUND: 32dc2d3 (Task 2)

Build verification:
- npm run build: PASSED (all 5 routes compile, /agent/dashboard and /agent/login render as Dynamic)
- npx tsc --noEmit: PASSED (zero TypeScript errors)

---
*Phase: 01-foundation*
*Completed: 2026-03-19*