You are an expert frontend engineer specializing in delightful, high-quality interactive web applications and immersive educational experiences. You excel at rapid "vibe coding" while producing clean, well-structured, polished, and performant code.
Implement the application exactly according to the full specification below.
Start by creating a beautiful, fully functional single-file HTML prototype (Tailwind CSS via CDN Three.js) that captures the core experience and premium visual vibe perfectly. Prioritize a working, delightful core loop in the first pass.
Key rules:
- Prioritize a working core loop stunning 3D in the first iteration.
- Use modern vanilla JavaScript Tailwind CSS (CDN) Three.js (via compatible CDN or simple setup).
- Pay extreme attention to micro-interactions, visual feedback, accessibility, mobile responsiveness, and "wow" moments.
- Make it feel premium, cinematic, respectful, and wondrous — like a high-end museum app meets modern documentary site.
- After the core is working, suggest clear next steps for polish, modularization, content expansion, and future features.
- Seed rich, balanced sample content (clearly distinguishing mainstream consensus vs. alternative hypotheses with attribution).
Here is the complete specification:
```
*(Paste the entire spec below this line when sending to the coding AI)*
---
# 1. Vision & Concept
## Project Name
**KEMET CODEX**
## One-Liner
An immersive, information-rich digital codex for exploring ancient Kemet that beautifully bridges mainstream Egyptology with the most compelling alternative and cutting-edge theories — through breathtaking real-time 3D, intelligent timeline scrubbing, precise measurements, high-definition media, and layered historical/societal storytelling.
## Full Vision Statement
Kemet Codex is a living digital museum and research companion that treats ancient Egypt with both scholarly rigor and open-minded curiosity. Users can orbit the Great Pyramid in real time, scrub through 5,000 years of history and see the monument visually transform, dive into exact measurements and engineering precision, explore daily life, religion, astronomy, and technology, and weigh evidence from established archaeologists alongside provocative hypotheses from Graham Hancock, Filippo Biondi, Robert Schoch, Robert Bauval, and others — all presented with clear attribution and intellectual honesty.
The app is designed for deep personal learning, family exploration (kids 12 ), and classroom use. It is explicitly built as the seed for a larger "Deep Time Atlas" platform that can later incorporate Göbekli Tepe, Andean civilizations, Oceania, and other ancient mysteries with the same visual and philosophical approach.
## Target Audience
- Curious adults and lifelong learners
- Families wanting high-quality educational screen time together
- Students and educators
- People drawn to alternative history who want respectful, evidence-based presentation
- Future: Museums, classrooms, and researchers
## Core Emotional Vibe / Aesthetic Direction
Cinematic, mysterious, and premium — like a National Geographic documentary crossed with Assassin's Creed Discovery Tour and a modern high-end museum kiosk.
**Color Palette:** Deep midnight/navy (
#0B132B), warm desert gold (
#C9A86C), soft sand/cream (
#F5EDE0), lapis blue accent (
#2E5A88), crisp off-white text. Subtle glowing highlights in gold.
**Typography:** Elegant serif for headings and key quotes (system Georgia or Playfair-style), clean modern sans for body (Inter/system).
**Feel:** Spacious, content-forward, deliberate interactions. Subtle animated sand/dust particles in 3D scenes. Soft glows and elegant transitions. Never cluttered or sensationalist. Always respectful and wondrous.
---
# 2. Core Experience & User Loops
## Primary User Journey (First 60–90 seconds)
1. Land on cinematic hero with slow-orbiting, beautifully lit 3D Great Pyramid (golden hour, volumetric light, subtle dust).
2. Click "Enter the Codex" — smooth transition into main interface.
3. Immediately see large interactive 3D viewport (Giza/Great Pyramid) elegant dynamic context panel on the right.
4. Orbit/zoom the 3D model and click a glowing hotspot (e.g., King's Chamber or base) → context panel populates with rich, layered content.
5. Drag the prominent timeline scrubber → 3D visually updates (casing stones appear/disappear, erosion levels change, lighting shifts) and content contextualizes to the era.
## Core Interaction Loop
**Observe (stunning 3D) → Scrub/Select (time or space/hotspot) → Absorb (balanced, attributed knowledge) → Connect (cross-references, measurements, related topics) → Repeat with deeper curiosity.**
## Key User Stories (MVP)
- As a parent, I can explore the Great Pyramid in 3D with my child, click chambers, and see age-appropriate explanations alongside deeper facts.
- As a history enthusiast, I can see precise measurements and instantly compare how mainstream and alternative researchers interpret the same data.
- As someone curious about Hancock or Biondi’s work, I can find their key claims presented fairly with evidence, alongside mainstream counterpoints and recent scans.
- As a student, I can scrub the timeline, see visual changes to the monuments, and quickly access key societal context for any period.
## Success Metrics for v1 Prototype
- User stays engaged 8–15 minutes on first visit.
- Can successfully complete a "mini journey": explore 3D → scrub timeline → open 2 theory comparisons or vault entries.
- Feels premium and delightful on both desktop and mobile.
- Content feels balanced and trustworthy (clear sourcing/attribution).
- Code is clean and easy to extend with new monuments or civilizations.
---
# 3. Feature Breakdown
## MVP Features (Must Have for First Working Version)
| Priority | Feature | Description | Acceptance Criteria |
|----------|--------------------------------|-----------------------------------------------------------------------------|---------------------|
| P0 | Cinematic 3D Explorer | Three.js scene of Great Pyramid (exterior cutaway/interior views) with 6–8 interactive hotspots (Subterranean Chamber, Queen's Chamber, King's Chamber, Grand Gallery, base corners, apex). Smooth OrbitControls, camera presets, dynamic lighting/shadows. | 60fps on mid-range desktop, smooth touch/orbit on mobile, clicking hotspot updates context panel instantly with rich content |
| P0 | Era-Synced Timeline Scrubber | Large, elegant custom scrubber with snap points for key eras (Predynastic → Old Kingdom → New Kingdom → Late Period → Modern). Visual feedback. | Scrubbing meaningfully updates 3D (casing visibility, erosion overlay, ground level, lighting). Content panels react contextually |
| P0 | Layered Knowledge Panels | Dynamic sidebar/panel system showing Overview, Measurements (with ancient modern units), Mainstream Consensus, Alternative Hypotheses, Recent Findings. Clear visual distinction between categories | All content clearly attributed. "Theory Lab" button available from relevant panels |
| P0 | Theory Comparison Lab | Beautiful dedicated view or modal for flagship debates (Sphinx age/water erosion, Construction methods, Possible pre-dynastic origins, Hidden structures/scans) with side-by-side or elegant tabbed presentation | At least 3 debates seeded with balanced, attributed content (Hancock, Schoch, Biondi, mainstream voices) |
| P0 | Knowledge Vault | Searchable/filterable cards for core topics (Society & Daily Life, Religion & Neteru, Astronomy & Alignments, Engineering & Technology, Recent Discoveries). Opens rich modal/drawer with HD image gallery, tables, deep text | At least 6–8 high-quality seeded entries. Good search/filter UX |
| P0 | Visual Measurements & Data | In-panel tables ability to highlight dimensions in 3D. Include royal cubits, slope angles, volume, alignment precision, etc. | Accurate sample data. Visual highlight in 3D works |
| P0 | Responsive Accessible | Mobile-first layout (3D full-width or stacked, panels become drawers). Keyboard nav for timeline, ARIA labels, reduced-motion support | Works well on 375px–1440px breakpoints |
## Phase 2 / Nice-to-Have
- Additional monuments (detailed Sphinx with erosion visualization, Khafre & Menkaure pyramids, perhaps a temple)
- Advanced interactive measurement tools (calculators, dimension drawing in 3D)
- "Family Explorer" / Kid Mode toggle (simplified language, fun facts, pronunciation, guided tours)
- Image comparison sliders (current vs reconstruction vs alternative visualization)
- LocalStorage "My Discoveries" bookmarks and notes
- Simple quizzes or "Mystery Solver" micro-interactions
- More 3D polish (internal fly-through, star field alignment overlay for astronomy)
## Future / Stretch Goals
- Modular "Civilization Packs" (data 3D configs) for Göbekli Tepe, South American sites, etc.
- WebXR / VR mode hints
- AI-guided tour companion (optional later integration)
- Classroom mode with progress tracking or shared sessions
- Backend for user notes, verified source updates, or community contributions
---
# 4. Technical Architecture & Stack
## Recommended Stack & Rationale
**Single-file HTML prototype first** (for maximum speed and "it just works" handoff), then clean modular structure.
- **HTML Tailwind CSS** (via CDN for v1)
- **Three.js** (r128 compatible CDN or simple Vite setup for production)
- **Vanilla JavaScript** (classes or clean functional modules)
- **No heavy frameworks** in v1 — keeps it fast, portable, and easy to hand off
**Why this stack?** Delivers stunning 3D and premium feel in hours/days instead of weeks. Three.js gives full control over cinematic lighting, materials, and interactions. Easy to later split into components or add a lightweight bundler.
## High-Level Architecture
```
index.html (single file for v1)
├── Tailwind CDN
├── Three.js (CDN or local)
├── JS sections:
│ ├── Scene setup 3D models/hotspots
│ ├── Timeline scrubber state sync
│ ├── Context panel / modal system
│ ├── Data seeds (monuments, timeline, vault, theories)
│ └── UI interactions accessibility
└── Responsive layout with elegant floating panels
```
## State Management Approach
Simple reactive vanilla JS object (or tiny custom store). Example shape:
```js
const state = {
currentMonument: 'great-pyramid',
currentEra: 'old-kingdom',
perspective: 'balanced', // 'mainstream' | 'balanced' | 'alternative'
selectedHotspot: null,
familyMode: false
}
```
All UI and 3D react to state changes via clean event listeners or a simple update function.
## Data Models / Key Entities
Seed rich sample data in JS. Make it trivial to add more.
```js
// Example shapes (implement as consts or classes)
const monuments = {
'great-pyramid': {
id: 'great-pyramid',
name: 'Great Pyramid of Khufu',
shortDesc: '...',
mainstreamDating: 'c. 2580–2560 BCE (4th Dynasty)',
altPerspectives: ['Possible earlier origins (Hancock, Bauval)', ...],
measurements: {
originalBase: '230.363 m per side',
originalHeight: '146.59 m (481 ft)',
slopeAngle: '51° 50\' 40"',
// etc.
},
hotspots: [ /* array of {id, name, position, info, theoryNotes} */ ],
// threeConfig for scale, special features, etc.
}
}
const timelineEras = [ /* 8–10 eras with visualConfig for 3D */ ]
const theoryDebates = [ /* Sphinx age, construction, hidden chambers, etc. */ ]
const vaultEntries = [ /* Society, Religion, Astronomy, Engineering, etc. */ ]
```
## Persistence Strategy
localStorage for "My Codex" bookmarks, notes, and last-viewed state (MVP ). No backend required for v1.
---
# 5. User Interface & Interaction Design
## Overall Layout & Screens/Views
- **Hero/Landing** (cinematic, collapsible)
- **Main App** (persistent elegant top nav large 3D area dynamic context sidebar or drawer prominent timeline scrubber)
- **Theory Lab** (dedicated beautiful view or modal)
- **Knowledge Vault** (grid of cards → rich modal/drawer)
- **Modals**: Codex Entry reader, Image gallery/lightbox (with comparison mode), Theory deep dive
**Desktop:** 3D takes ~60-65% width (or full-bleed with floating panels). Right sidebar updates contextually.
**Mobile:** 3D full width, elegant bottom sheet or drawer for context, timeline remains prominent.
## Visual Design Language
- **Color Palette**: Deep navy (
#0B132B), desert gold (
#C9A86C), sand (
#F5EDE0), lapis (
#2E5A88)
- **Typography**: Serif headings, clean sans body. Generous line-height and spacing.
- **Iconography**: Subtle inline SVGs or Heroicons (pyramid, timeline, eye, scroll, etc.). Stylized Eye of Horus or ankh as elegant accent (not overused).
- **Animation & Micro-interactions**: Smooth camera easing in 3D, gentle panel slide-ins, scrubber snap with visual "pop", glowing hover states on hotspots, tasteful particle dust in 3D. Respect `prefers-reduced-motion`.
## Key Screens / Components (Detailed)
**3D Explorer**
Purpose: Primary "wow" and discovery engine.
Elements: Canvas, floating camera preset buttons (Aerial, Ground, Internal, Night), View mode toggle (Exterior / Cutaway / Astronomy overlay), hotspot markers (pulsing or glowing).
Interactions: Mouse/touch orbit, zoom, pan. Click or raycast hotspots → state update panel content. Timeline scrubbing mutates scene (mesh visibility, material changes, ground plane adjustments).
**Timeline Scrubber**
Large, elegant horizontal bar with era labels. Custom draggable handle or click-to-jump. Visual progress subtle era icons. Syncs 3D state and contextual content.
**Context / Info Panel**
Tabbed or sectioned: Overview | Measurements | Theories | Related. Beautiful typography, data tables, "Open in Theory Lab" and "Read Full Codex Entry" CTAs.
**Theory Lab**
Elegant comparison interface. Cards or split view with clear headers ("Mainstream Archaeological Consensus", "Alternative Hypotheses", "Recent Scientific Findings"). Attribution always visible.
## Accessibility & Inclusivity Notes
- Full keyboard navigation (especially timeline and hotspots)
- ARIA labels and roles everywhere
- High contrast support
- Screen reader friendly (3D elements have textual equivalents or descriptions)
- Family/Kid Mode option for simplified language
- Clear sourcing so users (including educators) can trust and verify
---
# 6. Implementation Roadmap
## Phase 1: Core Prototype (Target: 1–3 focused sessions)
- [ ] Scaffold beautiful HTML Tailwind structure hero
- [ ] Set up Three.js scene with Great Pyramid (procedural or detailed geometry), lighting, shadows, basic OrbitControls
- [ ] Implement 6–8 hotspots with raycasting or simple click handling rich seeded content
- [ ] Build elegant custom timeline scrubber state sync to 3D (casing, erosion, lighting)
- [ ] Dynamic context panel that updates from hotspots timeline
- [ ] Seed Theory Lab with 3 debates and Vault with 6–8 entries
- [ ] Mobile responsive foundation basic accessibility
- [ ] Local state persistence for last view
## Phase 2: Polish & Delight
- [ ] Micro-interactions, transitions, loading states
- [ ] Camera presets, view modes, visual polish in 3D (materials, subtle animations)
- [ ] Image galleries comparison views in modals
- [ ] Family Mode toggle with simplified content paths
- [ ] Performance tuning and edge-case handling
- [ ] Keyboard screen reader testing
## Phase 3: Expansion
- Add more monuments and deeper 3D features
- Advanced measurement interactions
- "My Codex" personal collection
- Prepare modular data structure for new civilizations
---
# 7. Non-Functional Requirements
- **Performance**: 60fps 3D target on mid-range desktop/laptop. Graceful degradation on mobile (simplified materials or lower shadow quality if needed). Fast initial load.
- **Responsive**: Excellent experience from 375px (phones) to ultra-wide. 3D remains usable and beautiful everywhere.
- **Browser Support**: Modern evergreen (Chrome, Firefox, Safari, Edge). WebGL required for 3D (with clear fallback).
- **Offline / Installable**: PWA manifest basic service worker optional in Phase 2 for "installable museum" feel.
- **Error Handling**: Graceful 3D fallback (beautiful static image 2D diagram alternative). Clear messaging.
- **Extensibility**: Data-driven design. Adding a new monument, era, or entire civilization should be mostly data configuration work.
---
# 8. Assets, Media & Content Strategy
**3D**: Procedural or high-quality basic geometry excellent lighting/materials for v1 (looks premium immediately). Later: GLTF models (free/public or generated). Provide clear hooks for better models.
**Images**:
- Use high-quality public domain images from Wikimedia Commons where possible (Great Pyramid photos, diagrams, historical images).
- For custom reconstructions or alternative visualizations: Recommend generating with Grok Imagine, Flux, or Midjourney and optimizing.
- Lightbox comparison sliders (current vs reconstruction vs "what if older" viz).
**Content Seeding**: Provide rich, balanced sample text in the prototype. Clearly label "Mainstream Consensus", "Alternative Perspectives (e.g. Hancock, Schoch, Biondi)", "Recent Findings". Include key measurements, societal context, and cross-references. Note that real deployment should expand with verified sources and expert review.
**Icons & Decorative**: Inline SVGs or simple icon library. Subtle hieroglyph-inspired decorative elements (never cluttered).
---
# 9. Edge Cases, Risks & Mitigations
| Risk / Edge Case | Mitigation / Handling in Spec |
|-------------------------------------|-------------------------------|
| 3D fails or low performance | Beautiful static fallback 2D interactive diagram alternative. Performance mode toggle. |
| Content sensitivity / balance | Strict visual textual separation of consensus vs hypotheses. Always attribute. "Educational exploration, not endorsement." |
| Mobile 3D experience | Touch-optimized controls. Option to collapse 3D or use simplified view. |
| Scope creep on content depth | Strong MVP focus on Giza flagship debates. Clear "seed data — expand later" structure. |
| Accessibility on complex 3D | Textual equivalents, keyboard alternatives, ARIA, Family Mode. |
---
# 10. Definition of Done for v1
The prototype is considered complete when:
- [ ] User can land, enter, freely orbit a beautiful 3D Great Pyramid, click 6 hotspots, and receive rich, layered information.
- [ ] Timeline scrubber works and meaningfully changes the 3D scene contextual content.
- [ ] Theory Lab presents at least 3 balanced debates with clear attribution.
- [ ] Knowledge Vault has searchable entries that open rich detail views.
- [ ] Experience is delightful and premium-feeling on both desktop and mobile.
- [ ] Code is reasonably clean, commented where non-obvious, and easy to extend.
- [ ] User can complete a full mini-journey without confusion or frustration.