# Login Form Builder A responsive, multi-method “Workspace” authentication portal backed by the injected GenMB Auth SDK. ## Masterplan - Provide a complete, user-friendly sign-in experience for Workspace users: email/password, Google OAuth, email magic links, account registration, and password recovery. - Serve users who need to create an account, authenticate securely, or manage their current session without a custom application backend. - Keep authentication state centralized so protected account content is inaccessible until the GenMB session is restored. - Offer accessible validation, clear in-context errors, loading states, and toast feedback across every auth action. ## Tech Stack & Architecture - **React + TypeScript** application bootstrapped by Vite. - **React Router (`HashRouter`)** provides client-side routes: - `#/login` - `#/account` - **Tailwind CSS v4** is integrated via `@tailwindcss/vite` and imported in `src/styles/main.css`. - **Lucide React** supplies all interface icons. - **`clsx` + `tailwind-merge`** power the `cn()` class utility in `src/lib/utils.ts`. - **Auth integration:** `index.html` injects and initializes `window.genmb.auth`. This is the only authentication/data integration in the current project. - There is **no local database code, server API, ORM, or custom backend** in this repository. - Do not replace or remove the injected SDK script in `index.html`; it owns session checks, OAuth popup/redirect behavior, magic-link token handling, and credential requests. ### Application architecture - `src/main.tsx` mounts `` and imports global Tailwind/theme styles. - `src/app.tsx` initializes the auth session before rendering routes: - Loading → `AuthLoading` - Session initialization failure → `SessionError` - Ready → router plus `ToastProvider` - `src/hooks/use-auth-session.ts` is the single source of truth for the current `GenMBUser`, loading state, and auth initialization error. - It calls `window.genmb.auth.ready()` once on mount. - It subscribes through `onAuthStateChange` so login/logout updates propagate without manually mutating global state. - `LoginPage` and `AccountPage` receive `user` as props and redirect based on it. This is a UI-level route guard, not a server authorization layer. - Authentication form state is intentionally local to `src/components/login-page.tsx`; no Redux, Zustand, or persistent form store is used. - Toast state is local to `ToastProvider` and rendered above the router. ## File Structure ```text index.html Vite shell; includes the injected GenMB authentication SDK and base metadata. package.json Project scripts and frontend dependencies. vite.config.ts Enables React and Tailwind Vite plugins. src/ ├── main.tsx React entry point; loads App and global CSS. ├── app.tsx Auth bootstrap, toast boundary, hash routes, and default redirects. ├── styles/ │ └── main.css Tailwind import, semantic color tokens, light/dark theme values, global base styles. ├── components/ │ ├── login-page.tsx All sign-in, sign-up, OTP verification, magic-link, and password-reset form flows. │ ├── account-page.tsx Authenticated Workspace profile/session screen and sign-out action. │ ├── auth-loading.tsx Skeleton shown while GenMB restores/checks the session. │ ├── session-error.tsx Retry screen when initial auth session loading fails. │ └── ui/ │ ├── button.tsx Reusable button variants, sizes, focus treatment, and loading state. │ ├── input.tsx Reusable accessible input with invalid/error styling. │ └── toast-provider.tsx Context-based transient success, error, and info notifications. ├── hooks/ │ ├── use-auth-session.ts Initializes/subscribes to window.genmb.auth and exposes user/loading/error/retry. │ └── use-page-metadata.ts Updates document title and description per rendered page. ├── lib/ │ └── utils.ts cn(), email validation, and safe authentication error-message extraction. └── types/ └── genmb.d.ts Type declarations for window.genmb.auth and GenMBUser. ``` ## Key Features ### Authentication methods `src/components/login-page.tsx` supports six local views: 1. **Password sign-in** - Requires a syntactically valid email and a non-empty password. - Calls `window.genmb.auth.signInWithPassword(email, password)`. - Successful authentication navigates to `#/account`. 2. **Google sign-in** - Calls `window.genmb.auth.signIn()`. - The injected SDK handles popup sign-in and falls back to a full-page redirect if popups are blocked. - Do not assume a user is returned immediately during redirect fallback. 3. **Magic-link sign-in** - Requires a valid email. - Calls `window.genmb.auth.sendMagicLink(email)`. - The SDK automatically processes `?magic_token=...` during `auth.ready()` and removes the token from the URL afterward. 4. **Account registration** - Collects optional display name, valid email, and password of at least **8 characters**. - Calls `window.genmb.auth.signUp(email, password, name?)`. - Advances to six-digit OTP verification after the email code is sent. 5. **Sign-up verification** - Requires a six-digit numeric code. - Calls `window.genmb.auth.verifySignUp(email, code)`. - A successful verification creates/authenticates the account and routes to the account page. 6. **Forgot-password and reset-password** - Requests a password-reset OTP with `window.genmb.auth.requestPasswordReset(email)`. - Confirms the reset through `window.genmb.auth.confirmPasswordReset(email, code, newPassword)`. - Reset forms must preserve the existing six-digit OTP validation and password confirmation checks. ### Session management - `useAuthSession()` runs before routes render, preventing redirect flicker while session state is unknown. - `AccountPage` redirects unauthenticated visitors to `#/login`. - `LoginPage` redirects authenticated visitors to `#/account`. - Signing out calls `window.genmb.auth.signOut()`, displays a toast, and navigates to login. - The account page displays: - User name - User email - Profile picture when provided - Initials fallback when no picture exists or image loading fails ### GenMB Auth API surface Types are defined in `src/types/genmb.d.ts`. ```ts window.genmb.auth.ready(): Promise window.genmb.auth.getUser(): GenMBUser | null window.genmb.auth.isAuthenticated(): boolean window.genmb.auth.onAuthStateChange(callback): () => void window.genmb.auth.signIn(): Promise window.genmb.auth.signInWithPassword(email, password): Promise window.genmb.auth.sendMagicLink(email): Promise<{ success: boolean; data?: unknown }> window.genmb.auth.signUp(email, password, name?): Promise<{ success: boolean; data?: unknown }> window.genmb.auth.verifySignUp(email, code): Promise window.genmb.auth.requestPasswordReset(email): Promise window.genmb.auth.confirmPasswordReset(email, code, newPassword): Promise<{ success: boolean; data?: unknown }> window.genmb.auth.signOut(): Promise ``` `GenMBUser` contains `id`, `email`, `name`, and `picture`. Treat `name` and `picture` defensively in UI even though the current type marks them as strings. ## Design Guidelines - **Style:** restrained, professional security/workspace interface using bordered white/dark cards, soft shadows, rounded controls, and security-oriented iconography. - **Theme:** semantic CSS tokens are defined in `src/styles/main.css`, including `primary`, `muted`, `destructive`, and custom `success`. - Primary is blue-indigo. - Success is green. - Destructive/error is red-orange. - **Dark mode:** follows `prefers-color-scheme`; do not add a manual theme toggle unless explicitly requested. - **Typography:** `Inter, ui-sans-serif, system-ui, sans-serif`; no external font loading is configured. - **Sizing:** body supports a minimum viewport width of `320px`; login/error cards use `max-w-md`, while account content uses `max-w-3xl`/`max-w-5xl`. - **Accessibility:** preserve semantic headings, labels, error-associated input states, `aria-busy`, live toast announcements, visible focus rings, and keyboard-operable native controls. - **Responsive behavior:** forms/cards are full-width with page padding on mobile; account profile switches from stacked to horizontal layout at the `sm` breakpoint. ## App Flow ### Initial load 1. `App` calls `useAuthSession()`. 2. `AuthLoading` is displayed while `window.genmb.auth.ready()` checks/restores the session and potentially consumes a magic-link token. 3. If initialization fails, show `SessionError`; **Try again** reruns initialization. 4. If ready: - authenticated user → `#/account` - unauthenticated user → `#/login` ### Login and account navigation - Login page offers password sign-in as the primary view, with links/actions to Google, magic link, registration, and password recovery flows. - Each view change clears prior validation errors and notices, then focuses the email input. - Successful auth actions navigate with `replace: true` to avoid returning to stale auth forms through browser history. - On the account page, sign-out ends the SDK session and returns to `#/login`. - Unknown hash routes redirect according to authentication state. ### Important edge cases - Google popup blocking is handled by the GenMB SDK redirect fallback; avoid treating a `null` immediate result as a definite failed login. - Session readiness must finish before rendering protected/redirecting route content. - Handle rejected SDK calls with `getAuthErrorMessage()` and provide both field feedback where relevant and a toast. - Profile images may fail cross-origin or be unavailable; retain the initials fallback. - Hash routing is deliberate for static hosting. Do not change to `BrowserRouter` without configuring server-side route fallbacks. ## Conventions - Use lowercase kebab-case filenames: `login-page.tsx`, `use-auth-session.ts`. - Use PascalCase for components and TypeScript types; prefix hook names with `use`. - Keep page-level behavior in `src/components/*-page.tsx`; place reusable primitives under `src/components/ui/`. - Use Tailwind utility classes directly in JSX. Reuse semantic tokens (`bg-primary`, `text-muted-foreground`, `border-input`) rather than hardcoded colors. - Use `cn()` from `src/lib/utils.ts` when conditionally composing class names. - Reuse `Button` and `Input` rather than duplicating base control styles. Use `Button`’s `loading` and `loadingLabel` for async actions. - Keep authentication calls behind `window.genmb.auth` and update `src/types/genmb.d.ts` if the SDK contract changes. - For a new authenticated page: 1. Create `src/components/-page.tsx`. 2. Accept `user: GenMBUser | null` if it needs identity data and redirect unauthenticated users as `AccountPage` does. 3. Set metadata using `usePageMetadata()`. 4. Add a route in `src/app.tsx`. 5. Add navigation from the account area if users need to discover it. - Do not introduce a local database/auth implementation unless the architecture is intentionally expanded; current persistence and identity management belong to GenMB Auth. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.