ASTRUM-OS — Voice Celestial AI Agent

You are a Principal Frontend Architect and Lead Creative Technologist.

Task: Build Phase 1 of ASTRUM-OS — an ultra-futuristic, voice-controlled holographic celestial AI web application.

================================
1. TECH STACK & SETUP
================================
- Framework: Next.js 15 (App Router, React 19, TypeScript)
- Styling: Tailwind CSS v4 + Custom Glassmorphic FUI CSS variables
- Icons: Lucide React
- Fonts: JetBrains Mono / Space Grotesk for technical telemetry HUD text

================================
2. COLOR PALETTE & DESIGN SYSTEM
================================
Define CSS variables and Tailwind utility classes for:
- Deep Void Black: #020208
- Holographic Cyan: #00F0FF
- Astral Gold: #E5C158
- Nebula Purple: #8B5CF6

================================
3. UI COMPONENTS TO CREATED
================================
1. `app/layout.tsx`: Dark background (#020208), scanline overlay, ambient glow particles, and custom typography setup.
2. `components/ui/GlassCard.tsx`: Reusable holographic glass panel featuring sub-pixel cyan borders, backdrop blur (`backdrop-blur-xl`), animated corner brackets (`+` or `L` bracket accents), and subtle inner glow.
3. `components/ui/TelemetryBadge.tsx`: Small monospaced FUI readout badge displaying system status, coordinates, and live metrics.
4. `app/page.tsx`: Full-screen spatial layout container structured for the upcoming 3D canvas, top telemetry bar, center voice orb, and bottom expandable drawers.

Deliverable: Clean, compilation-ready Next.js 15 layout with working glassmorphic CSS tokens and responsive dark FUI structure.

Continue from Phase 1. Build Phase 2: The Three.js 3D Celestial Canvas.

================================
1. TECH STACK
================================
- `@react-three/fiber`
- `@react-three/drei`
- `three` & `@types/three`

================================
2. COMPONENT: components/canvas/CelestialScene.tsx
================================
Create a full-screen interactive 3D scene containing:

1. 12 Concentric Zodiac Rings (Armillary Sphere):
   - Glowing 3D torus/ring geometries rendered with emissive materials (#00F0FF & #8B5CF6).
   - Each ring slowly rotates along independent axes (X, Y, Z).
   - Rings subtly tilt and react to mouse movement and scroll position.

2. Floating Nebula Particle Field:
   - 2,000+ starlight particles using custom vertex shader displacement or instanced points.
   - Particles drift gently through space with subtle color shifts between cyan, purple, and gold.

3. Central Stellar Core:
   - Floating 3D mesh at scene origin representing the AI's core consciousness.
   - Accepts an `audioIntensity` prop (0.0 to 1.0).
   - Core scales, pulses, and alters noise displacement when audio activity is detected.

4. Performance & Fallback:
   - Responsive canvas scaling, DPR optimization, and WebGL context loss handling.

Deliverable: Working 3D Canvas component integrated seamlessly into `app/page.tsx` behind the glass HUD layout.

Continue from Phase 2. Build Phase 3: The Voice Interface Engine.

================================
1. HOOK: hooks/useVoiceAgent.ts
================================
Implement a comprehensive voice control hook managing Speech-to-Text, Audio Analysis, and Text-to-Speech:

1. Speech-to-Text (STT):
   - Use browser Web Speech API (`SpeechRecognition` / `webkitSpeechRecognition`).
   - Capture real-time user speech input and return live transcript string.
   - Handle permissions, speech start/end events, and error states gracefully.

2. Web Audio Analyser:
   - Request microphone audio stream via `navigator.mediaDevices.getUserMedia`.
   - Create AudioContext and `AnalyserNode` to compute frequency data array (`getByteFrequencyData`).
   - Output normalized audio intensity value (0-1) to feed the 3D Stellar Core in `CelestialScene.tsx`.

3. Text-to-Speech (TTS):
   - Use Web Speech Synthesis API (`window.speechSynthesis`).
   - Configure voice parameters: lower pitch (0.85), steady rate (0.95), and select crisp English synthetic voice (resembling J.A.R.V.I.S. / ethereal AI).
   - Expose `speak(text: string)` function with callback triggers when speech starts and finishes.

Deliverable: Fully typed React hook managing STT transcription, real-time microphone frequency data, and spoken AI audio playback.

Continue from Phase 3. Build Phase 4: Astrological Knowledge & AI Brain.

================================
1. API ROUTE: app/api/oracle/route.ts
================================
Create a Next.js App Router POST endpoint connecting user voice/text queries to the AI LLM (Claude / Gemini API).

================================
2. SYSTEM PROMPT: ASTRUM, The Celestial Intelligence
================================
Synthesize Western and Vedic astrological principles:
- Birth Chart Dynamics: Sun (Core Ego), Moon (Emotional Memory), Rising/Ascendant (Outer Horizon).
- 12 Astrological Houses & Planetary Transits (Saturn Returns, Mercury Retrogrades, Jupiter Expansions).
- Karmic Nodes: North Node (Future Horizon / Destiny) vs. South Node (Past Life Patterns).
- Tone: Tactical, authoritative, ethereal, and JARVIS-like sci-fi precision.

================================
3. STRUCTURED JSON OUTPUT SCHEME
================================
The API route must return JSON matching this TypeScript interface:
```ts
export interface OracleResponse {
  voiceSummary: string; // 2-3 sentence JARVIS-style spoken brief
  chartMetrics: {
    dominantTransit: string;
    intuitionScore: number; // 0-100
    powerScore: number;     // 0-100
    transformationScore: number; // 0-100
  };
  pastAnalysis: {
    karmicPattern: string;
    lessonLearned: string;
  };
  presentTransits: Array<{
    planet: string;
    house: string;
    impact: string;
  }>;
  futureTimeline: Array<{
    dateWindow: string;
    eventForecast: string;
  }>;
}
```

Deliverable: Production-ready API route with system prompt, schema validation, and fallback mock generator for offline/testing mode.

Continue from Phase 4. Build Phase 5: UI HUD Layout & Motion Polish.

================================
1. COMPONENT: components/ui/HUD.tsx
================================
Assemble the complete FUI HUD overlay:

1. Top Telemetry Navigation:
   - Header title: "ASTRUM-OS v2.6 // CELESTIAL NEURAL FEED".
   - Real-time UTC digital clock.
   - Live astronomical coordinates display (e.g., "RA 05h 35m / DEC +09°").

2. Center Viewport Voice Button:
   - Glowing holographic Orb Button ("HOLD TO COMMUNE / CLICK TO LISTEN").
   - Multi-state visual changes:
     * Idle: Soft cyan pulse (#00F0FF).
     * Listening: Rapid expansion + Live transcript HUD overlay.
     * Processing: Cyan/Purple warp effect + telemetry number count-up.
     * Speaking: Pulsing gold/cyan core synchronized with SpeechSynthesis.

3. Audio Waveform Visualizer Bar:
   - Canvas element rendering real-time audio frequencies from `useVoiceAgent`.

4. Bottom Expandable Glass Drawer:
   - 3 Expandable Cards: "Past Reflection", "Present Transits", and "Future Horizon".
   - Unmasks automatically when Oracle API returns data with Framer Motion staggered kinetic text entry.
   - Animate energy score meters (0-100) for Intuition, Power, and Transformation.

Deliverable: Fully integrated, Awwwards-quality futuristic voice HUD application ready to launch locally via `npm run dev`.

Build a complete, production-ready Next.js 15 (React 19, TypeScript, Tailwind CSS v4) web application named "ASTRUM-OS" — an ultra-futuristic, voice-controlled astrological agent.

### 1. CORE CONCEPT & AESTHETIC
- Aesthetic: Sci-Fi Holographic Celestial Interface (Iron Man JARVIS meets cosmic astrology).
- Color Palette: Deep Void Black (#020208), Holographic Cyan (#00F0FF), Astral Gold (#E5C158), and Nebula Purple (#8B5CF6).
- UI Structure: Dark glassmorphic floating HUD panels, telemetry coordinates, animated scanlines, radial orbital rings, and glowing corner brackets.

### 2. THREE.JS 3D CELESTIAL CANVAS (components/canvas/CelestialScene.tsx)
- Render a 3D Armillary Sphere / Zodiac Galaxy using @react-three/fiber and @react-three/drei.
- 12 Concentric glowing rings representing the Zodiac houses that subtly rotate on mouse move and scroll.
- Floating particle field (starlight/nebula dust) with vertex shader displacement.
- Central glowing Stellar Core that scales and pulses dynamically when the voice listener or text-to-speech is active.

### 3. VOICE INTERFACE ENGINE (hooks/useVoiceAgent.ts)
- Use Web Speech API (SpeechRecognition / webkitSpeechRecognition) to capture user audio input.
- Real-time Speech-to-Text HUD showing live transcript as the user speaks.
- Web Audio API AnalyserNode listening to the microphone stream to output an audio-frequency array for the 3D visualizer core.
- Text-to-Speech (TTS) response playback using Web Speech Synthesis API (configured with low pitch, steady rate, and ethereal reverb/spatial depth effect) or an API endpoint.

### 4. ASTROLOGICAL KNOWLEDGE & AI BRAIN (app/api/oracle/route.ts)
- Create a Next.js API route that interfaces with the AI LLM (Claude / Gemini API).
- Implement a comprehensive Astrology System Prompt acting as "ASTRUM, The Celestial Intelligence".
- System Knowledge: Western & Vedic astrology synthesis, Birth Chart calculations (Sun, Moon, Rising/Ascendant), 12 Houses, Planetary Transits (Saturn Returns, Mercury Retrogrades, Jupiter Expansions), Karmic North/South Nodes, and Temporal Timeline Projections (Past Life Patterns vs. Future Horizons).
- Response Format: Return structured JSON with:
  1. `voiceSummary`: 2-3 sentence J.A.R.V.I.S.-style spoken brief (e.g., "Transit detected: Saturn entering your 8th house. Past burdens are dissolving; prepare for financial recalibration in Q3.").
  2. `chartMetrics`: Current dominant planetary alignment, energy scores (0-100 for Intuition, Power, Transformation).
  3. `pastAnalysis`: Deep reading of past karmic loops and lessons learned.
  4. `futureTimeline`: Key upcoming dates and astrological window forecast.

### 5. UI HUD LAYOUT (components/ui/HUD.tsx)
- Top Navigation: "ASTRUM-OS v2.6 // CELESTIAL NEURAL FEED", Live UTC Clock, Astro Coordinates (e.g., "RA 05h 35m / DEC +09°").
- Center Viewport: Interactive 3D Canvas + Voice Activation Orb Button ("HOLD TO COMMUNE / CLICK TO LISTEN").
- Bottom Glass Drawer: Floating expandable HUD cards for "Past Reflection", "Present Transits", and "Future Horizon".
- Audio Waveform Bar: Real-time canvas waveform visualizer tracking voice input.

### 6. INTERACTIONS & ANIMATIONS
- Transition states handled via Framer Motion & GSAP.
- When user finishes speaking:
  1. Orb shifts color to Cyan/Purple warp effect.
  2. Telemetry numbers count up rapidly.
  3. Oracle voice response triggers automatically while corresponding HUD cards unmask with staggered kinetic text animations.

Setup the project structure cleanly with all component files, API routes, type definitions, and CSS glassmorphism styles ready to run locally via `npm run dev`.