# Trovex Pulse Polished React TypeScript social pulse homepage for Trovex Lite with auth, feed actions, tribes, creator support, and mobile bottom navigation. ## Masterplan - Ship a high-fidelity “Pulse” homepage for Trovex Lite: vibes, post creation shortcuts, rich feed cards, flame trends, suggested tribes, supporter panels, and rising creators. - Serve mobile-first social users, creators, and tribe members who browse trends, react to posts, support creators, and discover communities. - Provide an authenticated identity hub using the injected GenMB auth SDK; do not add a custom auth backend. - Keep non-Pulse product areas (`Tribes`, `Forge`, `Signal`) as lightweight placeholders while preserving complete navigation. - Use static demo data and local UI state so the app feels interactive before relational database/feed integration is implemented. ## Tech Stack & Architecture - **Runtime/build:** Vite + React 18 + TypeScript with strict TS (`tsconfig.json`). - **Routing:** `HashRouter` in `src/App.tsx` for static-hosting-safe routes: - `/` → `PulsePage` - `/tribes`, `/forge`, `/signal` → `SimplePage` - `/identity` → `IdentityPage` - `*` → `NotFound` - **Styling:** Tailwind CSS v4 via `@import "tailwindcss"` in `src/styles/main.css`; design tokens are CSS variables exposed through `@theme inline`. - **Icons:** `lucide-react`. - **Class utilities:** `cn()` in `src/lib/utils.ts` combines `clsx` and `tailwind-merge`. - **Auth:** GenMB auth SDK is injected directly in `index.html`, typed in `src/types/genmb.d.ts`, and consumed through `useAuth()` from `src/mainProviders.tsx`. - **State management:** React context only: - `AuthContext`: `user`, `loading`, `refresh`. - `ThemeContext`: `light | dark`, persisted as `trovex-theme` in `localStorage`; toggles `.dark` on ``. - `ToastContext`: transient toast queue rendered globally by `Providers`. - **Data:** Static demo models in `src/data.ts`; no relational DB calls are currently present despite the capability being enabled. - **App shell:** `src/main.tsx` mounts `` and imports global CSS. `src/components/Layout.tsx` wraps every route with header, desktop nav, mobile bottom nav, search modal, and notifications modal. - **Metadata:** Pages update `document.title` and the existing meta description in `useEffect`. Important gotchas: - `src/components/ui/Button.tsx` only accepts native `button` props. `src/pages/SimplePage.tsx` currently passes `as="button"`, which is invalid for this component and may fail strict TypeScript builds. Remove `as`. - Auth methods use `window.genmb?.auth`. Optional chaining prevents some crashes, but in environments without the injected SDK, calls may no-op or return `undefined`; keep auth UI defensive. - `readJSON()` in `src/lib/utils.ts` does not catch `JSON.parse` errors. Wrap reads in `try/catch` for any old or user-edited localStorage values. - Search submission in `Layout` navigates to `/?q=...`; `PulsePage` must read and apply the query if filtering behavior is desired. - `Modal` manually traps focus and locks body scroll. If adding nested overlays, verify Escape handling and focus restoration. - Toast IDs use `crypto.randomUUID()`, so very old browsers need a polyfill if targeted. ## File Structure ```txt index.html Root HTML, metadata, and injected GenMB auth SDK. package.json Vite/React/Tailwind/lucide/clsx dependencies and scripts. vite.config.ts Vite app configuration. tsconfig.json Strict TypeScript settings; includes src only. src/main.tsx React entry; imports main.css and wraps App in Providers. src/App.tsx HashRouter route map under shared Layout. src/mainProviders.tsx Auth, theme, and toast contexts plus global toast renderer. src/styles/main.css Tailwind v4 import, Trovex design tokens, safe-area utilities. src/types/genmb.d.ts Window/genmb auth SDK and user typings. src/data.ts Static Pulse posts, trends, tribes, rising stars, supporters. src/lib/utils.ts cn(), persistJSON(), readJSON() helpers. src/components/Layout.tsx Sticky header, desktop nav, mobile bottom nav, search/notification modals. src/components/ui/Button.tsx Button-only shared control with variants and loading state. src/components/ui/Card.tsx Shared card shell with interactive/selected states. src/components/ui/EmptyState.tsx Reusable icon/title/description/action empty state. src/components/ui/Input.tsx Labeled input with validation/error rendering. src/components/ui/Modal.tsx Accessible-ish modal with focus trap, Escape close, scroll lock. src/components/ui/Skeleton.tsx Muted pulse loading placeholder. src/pages/PulsePage.tsx Main Pulse homepage: vibes, create card, feed, trends, support, tribes, stars. src/pages/IdentityPage.tsx GenMB auth hub: Google, magic link, password, signup OTP, reset, sign out. src/pages/SimplePage.tsx Placeholder pages for Tribes, Forge, Signal. src/pages/NotFound.tsx 404 empty state with return-to-Pulse action. ``` ## Key Features ### Pulse homepage Implemented in `src/pages/PulsePage.tsx` using static content from `src/data.ts`. Requirements: - Show the Trovex Pulse experience as the primary route (`/`). - Include: - Vibes row: friends’ vibes, tribe vibes, add vibe. - Create post card actions: photo, video, music, live. - Pulse feed post cards from `samplePosts`. - Flame Chain/trending hashtags from `trends`. - Supporting panel with “Support Creator” and top supporters from `supporters`. - Suggested tribes from `tribes`. - Rising Stars from `risingStars`. - Feed cards should represent creator info, verification badge, tribe tag, content type, text/media, and Trovex actions: - Heat - Microphone / voice reaction - Boost - Sync - Interactions are local/demo only unless wired to a backend later. Use toast feedback for actions that do not persist. Current data model in `src/data.ts`: ```ts type Post = { id: string; username: string; verified: boolean; tribe: string; avatar: string; alt: string; contentType: 'photo' | 'video' | 'text' | 'music'; text: string; image?: string; imageSubject?: string; heat: number; boosts: number; syncs: number; created: string; }; ``` Other static data: - `trends: string[]` - `tribes: { id; name; members; icon }[]` - `risingStars: { id; name; focus; avatar }[]` - `supporters: string[]` ### Layout and navigation Implemented in `src/components/Layout.tsx`. Requirements: - Sticky top header: - Trovex logo links to `/`. - Desktop primary nav for Pulse, Tribes, Forge, Signal, Identity. - Search button opens modal. - Notifications button opens modal with unread dot. - Theme toggle shown on `sm+`. - Profile/avatar button navigates to `/identity`. - Mobile bottom navigation: - Fixed bottom nav with five destinations: Pulse, Tribes, Forge, Signal, Identity. - Uses safe-area padding via `.bottom-safe`. - Header and bottom nav must appear on all routes. ### Search Implemented in `Layout`. Requirements: - Modal title: “Search Trovex”. - Input label: “Search posts, vibes, or tribes”. - Reject queries shorter than 2 characters. - On submit, close modal and navigate to `/?q={encodedQuery}`. - Actual filtering belongs in `PulsePage` if needed. ### Notifications Implemented in `Layout`. Requirements: - Start with `unread = 3`. - Display demo notification copy in a modal. - “Mark all read” persists timestamp to `localStorage` key `trovex-notifications-read`, sets unread to `0`, and shows a toast. - The stored timestamp is not currently read back on page load. ### Identity/auth hub Implemented in `src/pages/IdentityPage.tsx`. Requirements: - If `useAuth().loading`, show session-checking card. - If authenticated, show user picture/name/email and sign out. - If unauthenticated, support: - Google sign-in: `window.genmb.auth.signIn()` - Magic link: `sendMagicLink(email)` - Password login: `signInWithPassword(email, password)` - Signup request: `signUp(email, password, name)` - Signup OTP verification: `verifySignUp(email, code)` - Password reset request: `requestPasswordReset(email)` - Password reset confirmation: `confirmPasswordReset(email, code, newPassword)` - Use the shared toast system for success/error feedback. - Validate email with the current lightweight regex: `/\S+@\S+\.\S+/`. Auth API surface from injected SDK: ```ts window.genmb.auth.ready(): Promise window.genmb.auth.signIn(): Promise window.genmb.auth.sendMagicLink(email): Promise window.genmb.auth.signUp(email, password, name?): Promise window.genmb.auth.verifySignUp(email, code): Promise window.genmb.auth.signInWithPassword(email, password): Promise window.genmb.auth.requestPasswordReset(email): Promise window.genmb.auth.confirmPasswordReset(email, code, newPassword): Promise window.genmb.auth.signOut(): Promise window.genmb.auth.getUser(): User | null window.genmb.auth.isAuthenticated(): boolean window.genmb.auth.onAuthStateChange(cb): () => void ``` User shape: ```ts { id: string; email: string; name: string; picture?: string } ``` ### Placeholder product areas Implemented in `src/pages/SimplePage.tsx`. Requirements: - Used for `/tribes`, `/forge`, `/signal`. - Shows a section-specific icon, “is warming up” copy, a return-to-Pulse action, and Identity link. - Keep these lightweight until real section integrations are added. ### 404 Implemented in `src/pages/NotFound.tsx`. Requirements: - Show “This signal faded”. - Return user to `/` through `useNavigate()`. ## Design Guidelines - **Overall style:** polished social dashboard, warm creator-economy feel, rounded cards, subtle shadows, lightweight motion. - **Primary color:** flame orange via `--primary`: - Light: `hsl(14 89% 54%)` - Dark: `hsl(18 94% 62%)` - **Accent:** soft purple for active/nav accents: - Light: `hsl(267 84% 95%)` - Dark: `hsl(265 40% 22%)` - **Backgrounds:** light mode white/warm muted surfaces; dark mode deep navy surfaces. - **Typography:** `Inter, ui-sans-serif, system-ui, sans-serif` via `--font-sans`. - **Components:** - Cards use `rounded-lg border border-border bg-card p-6 shadow-sm`. - Buttons use `rounded-md`, `min-h-10`, focus rings, active scale, and hover lift for primary/secondary/destructive. - Inputs always have visible labels; errors render as destructive text. - **Responsive behavior:** - Desktop nav appears at `md+`. - Mobile bottom nav appears below `md`. - `.page-pad` reserves bottom space for mobile nav and safe-area inset. - Header uses `.top-safe`; mobile nav uses `.bottom-safe`. - **Accessibility patterns:** - Use `aria-label` for icon-only buttons. - Preserve focus rings. - `Modal` sets `role="dialog"`, `aria-modal`, Escape close, backdrop close, and focus restoration. ## App Flow ### First load 1. `src/main.tsx` renders providers and router. 2. `Providers`: - Applies saved theme from `localStorage` key `trovex-theme`. - Calls `window.genmb.auth.ready()` if available. - Subscribes to `onAuthStateChange`. 3. `Layout` renders app chrome. 4. `/` displays `PulsePage` with static social demo data. ### Browsing Pulse - User lands on `/`. - User can browse vibes, create-post shortcuts, feed cards, flame chain, support panel, tribes, and rising stars. - Local/demo actions should provide immediate UI feedback and/or toast, not imply real persistence unless added. ### Searching 1. User clicks search icon. 2. Modal opens and focuses input. 3. Query shorter than 2 chars shows validation error. 4. Valid query navigates to `/?q=...`. 5. Pulse remains the destination for interpreting/filtering the query. ### Notifications 1. User clicks bell. 2. Modal shows demo notifications. 3. “Mark all read” sets unread state to zero and stores a timestamp locally. 4. If persistence across reloads is desired, add a `readJSON('trovex-notifications-read')` read in `Layout`. ### Authentication 1. User opens `/identity` via header avatar or nav. 2. `IdentityPage` shows session loading, signed-in profile, or auth forms. 3. Auth success calls `refresh()` and displays a toast. 4. Auth errors display `error.code` where available. ### Navigation edge cases - Unknown hash routes render `NotFound`. - HashRouter means links should use React Router paths like `/identity`; the URL becomes `#/identity`. - Direct browser path routing is not required because the app is hash-based. ## Conventions - **Files/components:** - Shared UI primitives live in `src/components/ui`. - Route pages live in `src/pages`. - App-wide providers/hooks live in `src/mainProviders.tsx`. - Static demo content and data types live in `src/data.ts`. - **Naming:** - Components use PascalCase filenames and default exports. - Hooks exported from providers are named `useAuth`, `useTheme`, `useToast`. - Local UI state should use descriptive names (`searchOpen`, `noticeOpen`, `pending`, etc.). - **Styling:** - Prefer Tailwind utility classes using theme token names (`bg-card`, `text-muted-foreground`, `border-border`) instead of hard-coded colors. - Use `cn()` when composing conditional classes. - Reuse `Button`, `Card`, `Input`, `Modal`, `EmptyState`, and `Skeleton` before adding new primitives. - **Adding a new route/page:** 1. Create `src/pages/NewPage.tsx`. 2. Add route in `src/App.tsx` inside the `Layout` route. 3. Add nav item to `nav` in `src/components/Layout.tsx` if it belongs in primary/mobile navigation. 4. Set page-specific `document.title` and meta description in `useEffect`. - **Adding a Pulse data-backed feature later:** - Start by extending types in `src/data.ts` or replacing static arrays with a service module. - Keep presentational feed/card logic separate from persistence calls. - Surface async states with `Skeleton` and errors with `EmptyState` or toasts. - **Backend/API status:** - There is no custom backend code in this repo. - Relational DB capability is enabled but unused. - The only active external integration is GenMB auth through `window.genmb.auth` injected in `index.html`. ## 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.