Add PlanetPulse MVP: Interactive spinning globe with data viz

[jakenuts]

Summary

• Introduces PlanetPulse MVP: an interactive spinning globe visualizing earthquake data using Three.js
• Features starfield background, procedural globe texture, and sprite-based data markers
• Supports dynamic metrics (Magnitude, Depth), time-range filtering, tooltips, details panel, and statistics
• Keyboard accessibility and responsive UI punch-list included in MVP scope

Changes

Core Architecture

• Added full MVP architecture in a single, cohesive setup with modules:
  • CONFIG: global settings for data, globe, starfield, metrics, colors, and marker sizing
  • Utils: debounce, color interpolation, lat/lon to vector conversion, marker texture creation
  • DataService: fetches USGS earthquake data (past 30 days, mag >= 2.5) with 10s timeout and fallback to SAMPLE_DATA
  • GlobeRenderer: Three.js scene setup, globe, starfield, lighting, markers, interactions, and animation loop
  • UIController: UI bindings for metrics, time filter, overlays, tooltips, and details
  • App: entry point orchestrating the flow
• Implemented a robust data flow: App → DataService → GlobeRenderer → UIController

Data & Rendering

• Data pipeline fetches and limits to CONFIG.api.maxPoints (500) and sorts by magnitude
• Fallback sample data provided (SAMPLE_DATA) if API fails, ensuring a functional MVP
• Markers rendered as sprites on the globe with color and size mapped to the selected metric
• Color scale interpolates across low/mid/high ranges; markers scale with metric-normalized value
• Implemented pulse animation for major earthquakes (magnitude 6+), while preserving hover/selection scales
• Procedural globe texture created on the fly (no external image dependencies) and rendered with basic lighting
• Starfield generated as a distant particle system for depth

Interaction & UI

• Orbit controls enable rotation, with debounced resize handling for performance
• Play/Pause rotation and Reset view controls on globe overlay
• Time range slider (1–30 days) to filter visible events; updates markers and stats
• Metric switcher with two options: Magnitude and Depth
• Legend shows current metric range and description; gradient reflects color scale
• Tooltip on hover with location and metric value
• Details panel displays location, magnitude, depth, coordinates, and time upon selection
• Stats panel shows: Visible Events, Avg, Max for the current metric
• Data source attribution to USGS in footer area
• Keyboard accessibility: Escape to clear selection, Space to toggle rotation, R to reset view

Styling & UX

• New styles.css to support globe UI, panels, legend, tooltip, and responsive layout
• Clear visual cues for interactive elements, focus states, and hover feedback

Testing Plan

• Run the app and verify the globe renders with the starfield and procedural texture
• Confirm data loads from USGS; if unavailable, ensure fallback SAMPLE_DATA is used
• Switch metrics (Magnitude vs Depth) and observe color/size changes on markers
• Use time range slider to filter data; verify markers update and stats reflect visible data
• Hover over markers to see tooltip; click to reveal details in the details panel
• Verify stats panel updates: total, avg, max for selected metric
• Use play/pause to control rotation and reset view to re-center globe
• Test keyboard shortcuts: Escape, Space, R
• Validate responsive layout on tablet/phone breakpoints

Notes & Considerations

• MVP intentionally caps data to ~500 points for performance
• Uses USGS as primary data source with a client-side fallback for reliability
• Potential enhancements (future PR): more metrics, richer marker styling, accessibility polish, and additional data sources

🌿 Generated by Terry

---

ℹ️ Tag @terragon-labs to ask questions and address PR feedback

📎 Task: https://www.terragonlabs.com/task/2cb74c21-a45f-42b4-bac2-b9c8a2b562ce