Sonic Topography (The Huntrix Globe)

A root-cause-first implementation of the Sonic Topography PRD: a neon, audio-reactive globe that visualizes regional music genres as a living frequency mesh.

What is implemented

• Canonical data contract in data/regions.json with schema validation at the source boundary.
• Pure domain core (src/core/*) covering validation, geo math, proximity evaluation, crossfade math, mesh construction, and camera focus computation.
• Canonical genre color mapping module (src/data/genreColorMap.ts) that enforces the PRD palette consistently across the dataset.
• TDD coverage for the core domain layer using Node's built-in test runner.
• Runtime architecture (React + Vite + React Three Fiber + Zustand + Web Audio API) with shader-based neon lines, atmosphere fresnel, proximity-driven intensity, and scroll-to-cycle genre logic.

Getting started

This environment cannot access the npm registry, so npm install will fail here. The steps below work in a normal development environment.

npm install
npm run dev

Then open the printed local URL (typically http://localhost:5173).

Testing (TDD)

The core domain layer is validated with a compile-then-test workflow:

npm run test

This runs tsc -p tsconfig.test.json followed by node --test on the compiled artifacts.

Data contract and extension points

Regions dataset

• Path: data/regions.json
• Each entry must include:
  • id: string
  • name: string
  • coordinates: [latitude, longitude]
  • genres: { name, color, audioUrl, bpm }[]

Validation is enforced by validateRegions in src/core/schema.ts and applied at import time in src/data/regions.ts.

Where to extend

• Add new regions or genres in data/regions.json.
• Update canonical genre colors or aliases in src/data/genreColorMap.ts.
• Adjust proximity thresholds in src/core/proximity.ts.
• Tune mesh density and globe sizing in src/config/globe.ts.
• Tweak shader behavior in src/shaders/*.