# Aura AI Visual Assistant A premium, cinematic AI companion web app with swipeable characters, persona-driven chat, an AI video “lab,” and a gem + subscription economy (EN/AR with RTL). ## Masterplan - **Vision and core purpose** - Aura AI is a “Cinematic AI Companion”: a visually immersive assistant focused on emotion + aesthetics first, utility second. - Deliver a native-app feel in a no-build, CDN-based web runtime (GenMB). - **Target users and their needs** - **Personal companion seekers:** want distinct personalities and “presence” (intro video + tone). - **Prompt-to-video explorers/creators:** want fast iterations and a simple creation loop. - **Mobile-first premium users:** expect smooth transitions, glassmorphism UI, safe-area handling, and RTL support. - **Primary value proposition** - Distinct character archetypes (Aria/Luxury, Leo/Romantic, Nova/Futuristic) with persona-prompted AI chat. - AI-assisted “video generation” flow gated by gems (13 gems per generation). - Hybrid monetization: subscription grants gems + premium flag; non-premium sees timed upsell overlay. - **Key differentiators** - **No-build architecture:** React + HTM via CDN; no bundler, no Node runtime. - **Immersive UI:** rotating cinematic backgrounds + glass panels + neon accents. - **Bilingual UX:** instant EN/AR switching with `dir` and RTL layout adjustments. - **Economy loop:** gems deducted on generate; subscription adds gems and removes ads. ## Tech Stack & Architecture - **Frontend** - **React 19.2.0** via `https://esm.sh/react@19.2.0` - **ReactDOM 19.2.0 client** via `https://esm.sh/react-dom@19.2.0/client?deps=react@19.2.0` - **HTM 3.1.1** for JSX-like templates without compilation (`src/jsx.js`) - **Tailwind CSS Play CDN** via `https://cdn.tailwindcss.com` (utility classes used directly in components) - **Lucide React** icons via `https://esm.sh/lucide-react?deps=react@19.2.0` - **Styling** - `styles/main.css` defines theme tokens (HSL CSS variables), glassmorphism, safe-area vars, and key animations. - Tailwind is used “as-is” (Play CDN). There is **no Tailwind config file**; custom theming is primarily via CSS variables and arbitrary Tailwind values like `bg-[hsl(var(--primary))]`. - **App structure** - **SPA with hash routing**: `window.location.hash` routing in `src/App.js`. No React Router. - Pages are simple modules under `src/pages/*` rendered by `App.renderPage()`. - **Entry point & module linkage** - `index.html` loads Tailwind CDN + `styles/main.css`, then runs `src/main.js`. - `src/main.js` mounts React root, wraps with ``, then renders ``. - **State management** - Central global store via **React Context + `useReducer`** in `src/mainProviders.js` using `reducer/initialState` from `src/store.js`. - **Persistence:** entire store saved to `localStorage` under key `aura_state` on every state change. On boot, persisted state is merged into `initialState` to handle schema evolution. - Gotcha: this is “last write wins” persistence; avoid storing large blobs (e.g., base64 video) in state. - **Key design patterns** - **HTM templating:** components return `html\`...\`` from `src/jsx.js`. - **Dictionary-based i18n:** `translations[language]` with key lookups; pages must not hardcode UI strings. - **Optimistic UI + error surfaces:** most flows use component-local `error` state plus inline alert rows; some still use `alert()`/`confirm()`. - **Simulated video generation:** current implementation does not call a real video API; it calls AI for analysis then selects a sample MP4. ## File Structure ```text index.html # Required entry point. Loads Tailwind Play CDN, styles/main.css, then src/main.js as ES module. styles/ main.css # Theme tokens (HSL CSS vars), glass-panel styling, safe-area variables, page transition animations, # swipe container rules, mobile keyboard sizing helpers, and small UX fixes (e.g., iOS input zoom prevention). src/ main.js # ReactDOM mount. Renders using HTM html`` syntax. jsx.js # Binds HTM to React.createElement. All components should import { html } from here. mainProviders.js # StoreContext provider using useReducer. Loads/saves full state to localStorage key `aura_state`. # Merges parsed saved state with initialState to tolerate older saved schemas. store.js # initialState (user, characters, generatedVideos) and reducer actions: # UPDATE_USER, DEDUCT_GEMS, ADD_GEMS, ADD_VIDEO, UPDATE_VIDEO, DELETE_VIDEO, SET_PREMIUM, SET_LANGUAGE. translations.js # EN/AR dictionaries. Includes persona copy, validation messages, and monetization strings. App.js # Root shell: # - Hash router # - Rotating background images (10s interval) # - Applies RTL/LTR classes and sets `dir` attribute # - Renders Navigation and AdOverlay globally components/ Navigation.js # Fixed bottom nav. Highlights active route; treats #/character/* as Home. GemBadge.js # Displays current gems from global state. AdOverlay.js # Timed premium upsell overlay for non-premium users (every 4 minutes). pages/ Home.js # Swipeable horizontal character cards (scroll-snap), quick actions to Video + Subscribe. # Includes image load/error retry logic with fallback image. CharacterDetail.js # Character hero (image + optional looping intro video), persona detail, and AI chat. # Calls /api/ai/completion with a stitched prompt context. # (File includes additional chat UI below the truncation in this snapshot.) VideoGenerator.js # Video preview gallery + “creator” flow. # Prompt refine uses /api/ai/completion. # Generate: checks gems >= 13, calls AI for a one-line scene analysis, simulates progress, # then stores a generatedVideos entry pointing to a random SAMPLE_VIDEOS URL. # Includes download/refresh/delete actions and handles video load errors. Profile.js # Profile edit (name -> initials avatar), language toggle, advanced settings: # autoOptimize/debugMode toggles and a “clear cache” alert stub. # (Some sections truncated in snapshot.) Subscription.js # Weekly/Monthly plans. “Subscribe” currently: # - Adds gems # - Sets premium flag # - alerts success # - navigates to profile ``` ## Key Features ### P0 (must work flawlessly) 1. **Swipeable character discovery** - Home shows character cards from `state.characters`. - Horizontal scroll-snap container (`.character-swipe-container`) emulates “swipe navigation.” - Each card links to `#/character/{id}`. 2. **Character intro + persona detail** - CharacterDetail displays: - hero background image with retry+fallback behavior - optional looping `introVideo` - personality + “What I offer” sections pulled from `translations` via keys stored in character config. - “Start Interaction” seeds chat with `t[char.introKey]`. 3. **Persona-driven AI chat (text)** - Calls `/api/ai/completion` with a prompt that includes: - system persona definition (name, personality, theme, language) - last ~6 messages of context - Requirements: - Must handle empty input validation (`t.messageRequired`) - Must show rate-limit errors (HTTP 429 -> `t.rateLimitError`) - Must remain in character and respond in the current UI language. 4. **AI Video Lab (prompt → simulated generation)** - Validate prompt: required + minimum length (>= 10 chars). - Optional “Refine with AI”: - Calls `/api/ai/completion` to expand prompt to cinematic <50 words in selected language. - Generate: - Costs **13 gems**; block if `state.user.gems < 13`. - Simulated progress UI steps + AI “scene analysis” call. - On success: - dispatch `DEDUCT_GEMS` 13 - dispatch `ADD_VIDEO` with `{id, prompt, timestamp, videoUrl}` (videoUrl is a random sample MP4) - On failure: - do **not** deduct gems - display localized error message 5. **Gem economy** - Gems displayed globally via `GemBadge`. - Deductions/additions happen only through reducer actions (`DEDUCT_GEMS`, `ADD_GEMS`). - Starting balance: `150` in `initialState.user.gems`. ### P1 (premium & retention) 6. **Subscription page** - Two plans: - Weekly: $15, +100 gems - Monthly: $30, +225 gems, tagged “Best Value” - Current implementation is **non-payment** (simulated via dispatch + alert). - Premium flag: `state.user.isPremium = true`. 7. **Ad overlay upsell** - For non-premium users only. - Shows every **4 minutes** via `setInterval(240000)` in `AdOverlay`. - CTA navigates to `#/subscribe`. - Gotcha: there is no persistence of “last ad shown” beyond component lifecycle; `state.lastAdTime` exists but is currently unused. 8. **Profile + advanced controls** - Edit name (validation: required, length >= 2); avatar becomes initials. - Language toggle EN/AR (`SET_LANGUAGE`). - Advanced toggles: - `autoOptimize` (UI-only) - `debugMode` (UI-only) - “Clear system cache” currently just `alert(t.cleared)` and does not clear `localStorage`. ### Data models (current client-side) - **User** - `name: string` - `avatar: string` (initials) - `gems: number` - `isPremium: boolean` - `language: 'en' | 'ar'` - `performance: string` (UI-only) - `aiSpeed: string` (UI-only) - `autoOptimize: boolean` (UI-only) - `debugMode: boolean` (UI-only) - **Character** - `id: 'aria'|'leo'|'nova'|...` - `name: string` - `themeKey/personalityKey/introKey: string` (keys into `translations`) - `color/accent: string` (Tailwind class fragments used by UI) - `image: string` (remote URL) - `introVideo?: string` (remote MP4 URL) - **GeneratedVideo** - `id: number` (currently `Date.now()`) - `prompt: string` (saved scene description) - `timestamp: string` (localized date string) - `videoUrl: string` (remote MP4) - `color: string` (Tailwind gradient fragment) ### External integrations (current) - **AI proxy**: `POST /api/ai/completion` - Used in: - Character chat (`CharacterDetail.js`) - Prompt refinement and scene analysis (`VideoGenerator.js`) - Expected response: `{ success: boolean, data: { text: string } }` - Error handling: - `429` treated as rate limit in chat flow - general non-OK treated as generic failures elsewhere *Not yet integrated (concept requirements, future work):* Auth (`/api/auth/google/*`), database (`/api/data/{appId}/*`), storage uploads, contact form submission. ## Design Guidelines - **Visual style** - Futuristic premium dark UI with glassmorphism panels and neon accents. - Cinematic feel via rotating background images + soft blur overlay. - **Color palette (from `styles/main.css`)** - Background: `hsl(240 10% 3.9%)` - Foreground: `hsl(0 0% 98%)` - Primary accent (neon cyan): `hsl(199 100% 50%)` - Secondary accent (purple): `hsl(270 100% 60%)` - Muted foreground: `hsl(240 5% 64.9%)` - **Typography** - Uses `Inter` in CSS; note: Inter is referenced but not imported in `index.html`. If you add a webfont import, do it via `` in `index.html` (no build step). - Headings often use `font-black` with tight tracking for “premium” emphasis. - **Spacing & component patterns** - Rounded corners are large (`rounded-[2rem]`, `rounded-[2.5rem]`, etc.). - Glass panels: `.glass-panel` class + Tailwind borders/shadows. - Safe areas: bottom nav container uses `var(--safe-area-bottom)`. - **Responsive behavior** - Mobile-first; special handling for very small screens in `@media (max-width: 420px)`. - Uses `100dvh` when supported to avoid mobile browser chrome height issues. - **Accessibility requirements (implement/maintain)** - All tappable controls must be reachable and have visible focus states (currently many rely on Tailwind defaults; add `focus:outline-none` cautiously). - Provide `alt` text for images (Home does; CharacterDetail hero image currently has none—add when editing). - Avoid color-only state cues; active nav already uses both color and indicator bar. - Ensure RTL icon direction flips are preserved (several icons rotate in RTL). ## App Flow ### Primary user journeys 1. **Discover → choose companion** - `#/` Home renders character cards. - User swipes horizontally (scroll-snap) and taps “Interact”. 2. **Companion detail → start interaction** - `#/character/:id` shows hero image/video, personality, offers. - “Start Interaction” seeds first AI message and reveals chat UI. 3. **Create a video** - From Home quick action or nav: `#/video`. - User selects previews (UI) then enters creator flow (controlled by `showCreator` in `VideoGenerator.js`). - User refines prompt (optional) then generates (costs 13 gems). - Generated video saved to “Your Creations.” 4. **Monetization / upgrade** - Timed `AdOverlay` appears for non-premium every 4 minutes. - CTA goes to `#/subscribe`. - Subscription adds gems, sets premium, navigates to profile. 5. **Profile management** - `#/profile` edit name/avatar initials, toggle language, open advanced settings. ### Navigation structure & state transitions - Hash routes: - `#/` → `Home` - `#/character/:id` → `CharacterDetail` - `#/video` → `VideoGenerator` - `#/subscribe` → `Subscription` - `#/profile` → `Profile` - App shell always renders: - background rotation layer - bottom `Navigation` - global `AdOverlay` ### Edge cases / error / loading states - **Remote media failures** - Home character images: retry once, then fallback image. - CharacterDetail hero image: retry logic + fallback. - VideoGenerator: tracks `videoLoadErrors` per id; offers refresh. - **AI failures** - Chat: - empty message => inline error - 429 => localized rate limit error - invalid JSON shape => `t.invalidAIResponse` - Video refine/generate: - non-OK => localized refine error / generic failure message - **Gems insufficient** - Generation blocked with `alert(t.notEnoughGems)`; no state change. - **Persistence pitfalls** - Corrupt localStorage state: provider catches parse errors and resets to `initialState`. - State schema changes: provider merges saved state with `initialState` (user sub-merge included). ## Conventions & Patterns - **Coding style** - ES modules only, explicit CDN imports for libraries. - Prefer small, page-local state (`useState`) for transient UI and global state for economy/user prefs. - **Naming** - Components: `PascalCase.js` - Pages: `PascalCase.js` under `src/pages/` - Reducer actions: `SCREAMING_SNAKE_CASE` - **HTM / templating rules** - Always import and return templates using: - `import { html } from '../jsx.js'` (or `./jsx.js`) - `return html\`

...

\`;` - Components are invoked as: `<${Component} prop=${value} />` (HTM pattern). - **Translations** - Do not hardcode user-facing strings (including alerts) unless there is no key yet—add keys to **both** `en` and `ar` in `src/translations.js`. - Access via: ```js const t = translations[state?.user?.language] || translations.en; ``` - **Routing** - Use hash links: `` - Programmatic: `window.location.hash = '#/profile'` - Active route is tracked in `App` state; update via `hashchange` listener. - **State updates** - Use `dispatch({ type, payload })` only; do not mutate `state`. - Add new state fields in `initialState` and handle merging in `Providers` if nested. - **Styling** - Prefer Tailwind utility classes. - Use `.glass-panel` for the signature surface. - Use theme tokens via `hsl(var(--...))` and Tailwind arbitrary values (`bg-[hsl(var(--primary))]`). - **How to add a new page** 1. Create `src/pages/NewPage.js` exporting a default component using HTM. 2. Add a route case in `src/App.js` `renderPage()` switch. 3. (Optional) Add nav item in `src/components/Navigation.js`. 4. Add translations keys if new UI strings are introduced. - **How to add a new character** 1. Add a character object in `src/store.js` `initialState.characters`. 2. Add `themeX`, `persX`, `introX` keys to both languages in `src/translations.js`. 3. Ensure `image` and optional `introVideo` URLs support CORS for playback/display. - **How to add a new economy action** 1. Add reducer action in `src/store.js`. 2. Dispatch from UI and ensure persistence is acceptable (avoid large payloads). 3. Update any UI badges/labels (GemBadge, Subscription copy) via translations. ## Platform (GenMB) This app is built and hosted on GenMB. When modifying this code, respect these constraints: **Runtime environment:** - Runs in a browser sandbox (iframe preview) or deployed to GenMB's Cloud Run infrastructure - No Node.js server at runtime — all code runs client-side unless a backend/ directory exists - Static assets served via GenMB's deploy service with CDN caching **Frontend constraints:** - Dependencies loaded via CDN (esm.sh, cdn.tailwindcss.com, unpkg) — no npm install at runtime - Use ES module imports with full CDN URLs (e.g., `import React from 'https://esm.sh/react@19'`) - index.html is the entry point — must include all CDN script tags - Tailwind CSS via CDN (`cdn.tailwindcss.com`) with inline config, not PostCSS **Built-in services (use relative API paths, never hardcode domains):** - `/api/ai/completion` — AI text/image generation proxy - `/api/data/{appId}/*` — PostgreSQL database (relational data via DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS-backed) - `/api/auth/google/*` — Google OAuth for end-users - `/api/contact/submit` — Contact form handler - SDKs auto-injected: `window.genmb.db`, `window.genmb.storage`, `window.genmb.auth` **File structure rules:** - `index.html` — required entry point - `src/` — application source code (JS/JSX modules) - `styles/` — CSS files - `backend/` — optional FastAPI backend (deployed separately) - `CLAUDE.md` — this file (auto-generated, do not manually edit) - No `node_modules/`, no build step in production (CDN-based) **What you CANNOT do:** - Install npm packages at runtime (use CDN imports instead) - Access the filesystem or run shell commands - Make server-side API calls from frontend code (use the proxy endpoints above) - Modify deploy infrastructure or DNS