# GODSIGH — Wave 4 Spec: Solar System mode ("Travel to…")

**Author:** Claude Fable 5, 2026-07-14, on John's request. Built by Fable in the same session.
**Prereq:** Waves 1–3.2 live at partly.party/godsigh. This is additive — a new *mode*, not a layer.

## 0. Mission
A "Travel to…" experience: leave Earth and fly out to a Sun-centred solar system rendered from free/public data — the 8 planets (+ Sun, Moon) as spheres textured with real imagery, at their true current positions, with orbits, and smooth camera flights between them. Everything computed or harvested from free/CC/public-domain sources (the "harvest it all" ethos, applied to the sky).

## 1. Ground truth — verified 2026-07-14 (CORS-probed)
- **Planet textures:** solarsystemscope.com `/textures/download/2k_*.jpg` (CC BY 4.0) — 200. No ACAO ⇒ **self-host** (WebGL taints cross-origin textures). Download the 2k set into `textures/`.
- **Real surface tiles (Phase 2):** NASA Moon Trek WMTS (`trek.nasa.gov/tiles/Moon/…`) and USGS/OpenPlanetaryMap Mars tiles — both 200 with `ACAO: *`. Usable as Cesium imagery providers.
- **Positions:** computed (Schlyter low-precision series, already proven in `js/layers/celestial.js`).

## 2. Architecture decision (locked)
Cesium's globe is Earth-at-origin, so a Sun-centred scene can't move the globe. Therefore **Solar System mode HIDES the Earth globe** (`scene.globe.show = false`, hide all Earth OSINT layers) and renders a **heliocentric orrery** with entities; exiting restores the Earth OSINT view. The detailed Earth globe stays the "home" view; the orrery is a distinct mode.

- **Bodies:** Sun + Mercury·Venus·Earth·Mars·Jupiter·Saturn·Uranus·Neptune (+ Moon near Earth) as `ellipsoid` entities with `ImageMaterialProperty` (self-hosted textures). Saturn gets a ring (`2k_saturn_ring_alpha.png` on a flat disc / ring geometry). Real axial tilt applied via entity orientation.
- **Positions:** heliocentric xyz from Schlyter (extend the celestial ELEM table with Uranus & Neptune; Earth = −sunRect). Compressed distance scale (tune in-browser) + exaggerated body sizes so it reads (true scale is unviewable — Sun↔Neptune is 30 AU vs Sun radius 0.005 AU). Directions/relative order stay true.
- **Orbits:** faint polyline ellipses per planet (sample the orbit over one period).
- **Travel-to:** a mode panel with a destination per body; clicking `camera.flyTo` the body with a sensible offset. "Return to Earth" exits the mode.
- **Skybox/Sun light:** keep Cesium starfield; a point of light at the Sun optional.

## 3. Phases
- **P1 (core, must-ship):** mode toggle + orrery (all 8 planets + Sun + Moon textured, true positions, orbits) + travel-to camera flights + return-to-Earth. Self-hosted 2k textures. Attribution in-app + README.
- **P2 (stretch):** "Land" on **Mars** and the **Moon** with real NASA/USGS tile imagery. Cleanest path that avoids fragile globe-ellipsoid swapping: when travelling to Mars/Moon, load an 8k real-imagery texture (still real, harvested) OR, if a runtime globe swap proves stable, a true tile-imagery explorable body. Attempt the swap; fall back to hi-res texture if fragile.
- **P3 (later, noted):** OSINT-on-other-worlds — Mars rover positions (NASA public APIs), Apollo landing sites, active orbiters.

## 4. Files
- `textures/` — self-hosted CC planet maps (2k set) + `TEXTURES_CREDIT.md` (CC BY 4.0 attribution to solarsystemscope.com).
- `js/solarsystem.js` — the mode: build bodies, orbits, travel-to menu, enter/exit.
- HUD: a "◉ Solar System" toggle (top of the HUD, near the Data/Photo buttons) that enters/exits the mode; a destination panel while inside.
- `main.js` — wire the mode (hide/restore globe + Earth layers + timeline; the mode owns its own render/positions).

## 5. Verify (browser, per phase)
Zero console errors; textures load (self-hosted, same-origin); planets at plausible positions (inner planets near Sun, gas giants far, correct order); travel-to flies smoothly and arrives framed; return-to-Earth restores every layer + the globe exactly. Screenshot the orrery and an arrival. Subpath-safe (`textures/…`, relative). Commit per phase; deploy = rsync `js/` + `textures/` (no nginx change — all static/CORS-open).

## 6. Attribution (license compliance)
Planet textures © solarsystemscope.com, CC BY 4.0 — credit in-app footer + README + `textures/TEXTURES_CREDIT.md`. Mars/Moon tiles: NASA/USGS/OpenPlanetaryMap (public domain / open) — credit when P2 lands.

## 7. Out of scope (Wave 4)
Comets, asteroids, moons beyond Earth's, true-scale mode, VR. Roadmap.