# Sprint 35: Atlas — Client Tasks

**Goal:** Launch Phase 3 — open the Atlas implant panel so a player can navigate from the Reach map down to any planetary body and see a heightmap with generated city markers, overlays, and a city data panel linking to the economics monitor.

**Branch:** `sprint-35/client`
**Agents:** Stig (UI), Tyre (architecture)

## New Tickets

| # | Title | Blocked by |
|---|-------|------------|
| #834 | Atlas implant panel — system picker, orbital diagram, body navigation | — |
| #835 | Atlas heightmap viewer — pan/zoom, marker overlay, city data panel | #834 |
| #836 | Atlas overlay system — 9 MVP overlays with visibility tiers | #835 |

## Key Decisions

- `decisions/architecture.md` — D-191 (Atlas Phase 3 scope — full UI spec: zoom hierarchy, navigation levels, city data panel, overlay system, MVP completion criteria), D-169 (implant UI component library — compose from `client/ui/implant/`), D-170 (HUD visibility groups — Atlas registers as `implant/map/atlas`, FULLSCREEN mode z=20)
- `decisions/economics.md` — D-181 (signal visibility ladder — maps to which overlays are always-on vs. toggleable vs. locked in #836)

## Notes

### #834 — Atlas implant panel: system picker + orbital diagram + body navigation

New implant app. Register with `HudGroups` as `implant/map/atlas` in FULLSCREEN mode (z=20). The atlas is an extension of `implant/map`, not a separate app — the existing `star_map.gd` registers at `implant/map/starchart`. The atlas adds the next zoom levels downward.

**Three navigation levels:**
1. **System picker** — reuse the system list from `client/ui/implant/economics_panel.gd`. Searchable scroll list. Selecting a system advances to level 2. `client/ui/star_map.gd` already has a system selection signal; check if it can be reused or if the atlas needs its own.
2. **Orbital diagram** — star at center, bodies arranged by `orbit_index` from `systems.db`. Click a body → level 3. Click a station → mini data panel (name, operator, currency_zone — no drill-down; stations have no heightmap). Back navigation returns to system picker.
3. **Body entry point** — tile/button that opens the heightmap viewer (`#835`). Can be a simple "VIEW ATLAS" button in this ticket; the actual viewer is built in #835.

Use implant component library throughout: `ImplantPanel`, `ImplantHeader`, `ImplantSeparator`, `ImplantDataRow`, `ImplantTextBlock`. Theme from `client/ui/implant/default_implant.tres`.

This ticket delivers navigation skeleton only — the heightmap viewer content comes from #835. Build with stub data (empty orbital diagram with system name and body count) so the panel can be tested independently. Data for the orbital diagram lives in `res://data/star_map_data.json` (the same source used by the star map). Check whether `orbit_index` and body type are already in the JSON; extend the generation script (`tooling/generate-star-map-data.py`) if not.

Add keyboard shortcut and implant nav entry (consistent with how `economics_panel.gd` registers its shortcut).

### #835 — Atlas heightmap viewer: pan/zoom, marker overlay, city data panel

Body atlas level. Loaded when a body is selected in #834.

**Heightmap display:** Load the heightmap PNG as `Texture2D` in a `SubViewportContainer` with pan/zoom. The heightmap path comes from `terrain_reference` in `bodies` data (the `star_map_data.json` should include this after #839 runs on server; if the JSON was generated before #839, re-run `make atlas-generate` to pick up the column). Pan/zoom: mouse drag + scroll wheel, pinch gesture on touchscreen. Clamp to image bounds.

**MarkerOverlay:** A `Node2D` drawn via `_draw()` on top of the viewport. Renders from `markers.json` per body (path: same directory as the heightmap PNG):
- Cities: filled circles, radius scaled by `population_tier`
- Roads: polylines (solid, thin)
- Railroads: polylines (dashed)
- POIs: diamond shapes
- Named features (rivers, oceans, mountains): labels at centroid

`markers.json` will be initially empty for most bodies until server's #832 and #833 complete. The overlay must handle empty arrays gracefully — display the bare heightmap if `cities` is empty.

**City data panel sidebar:** Clicking a city opens a right-side panel (ImplantPanel components) showing:
- City name, population tier, primary function
- Currency zone, Commission presence flag
- Shadow economy zone (broad band from `shadow_economy_intensity`)
- Gate distance (hop count to nearest gate terminal)
- **Economics panel link** — button that calls `HudGroups.open_app("implant/economics")` and triggers an `EconStateQuery` pre-filtered to this body's system node. This is the cross-panel integration point from D-191 criterion 5.

Blocked by #834 (needs the navigation frame). Can start before #832/#833 complete — build against the empty `markers.json` state; the overlay will auto-populate once the server pipeline runs.

### #836 — Atlas overlay system: 9 MVP overlays with visibility tiers

Overlay toggle bar at top-right of the regional view (inside the heightmap viewer scene from #835).

**Always-on (5):** terrain, infrastructure (roads + rail), named features, gate/spaceport markers, political zones (currency zone color bands)

**Toggleable (4):** population density heatmap, production zones, shadow economy zones (broad bands from `shadow_economy_intensity`), corporate presence Tier 1 (dots where Tier 1 corps operate)

**Deferred (visible but locked):** overlays requiring D-181 semi-private or private signals (signals 5–6: `stockpile_weeks`, `production_vs_baseline`). Show these as greyed toggle buttons with a tooltip explaining the unlock requirement ("Requires corporate contact" / "Requires insider access").

The deferred overlays are present in the UI per D-191 — they communicate to the player that deeper information exists and is gated. Do not omit them.

Implementation: each overlay is a separate `Node2D` child of the `MarkerOverlay` container, toggled visible/invisible. The toggle bar is an `HBoxContainer` of `ImplantTabRow`-style buttons. State persists per session (not saved to disk).

Maps to D-181 signal visibility ladder — always-on overlays use public signals (1–2), toggleable overlays use observable signals (3–4), locked overlays use semi-private/private signals (5–6).

Blocked by #835 (needs the heightmap viewer and marker overlay infrastructure).

## Dependency Chain

```
#834 (atlas panel — system picker + orbital diagram + body nav) — start here, standalone
  → #835 (heightmap viewer — pan/zoom, marker overlay, city data panel)
     → #836 (overlay system — 9 MVP overlays)
```

`#834` can begin immediately (no server dependency for skeleton). `#835` builds on #834's navigation frame. `#836` builds on #835's MarkerOverlay infrastructure.

The heightmap viewer (#835) can be built against empty `markers.json` and will auto-populate when the server atlas pipeline (#832, #833) completes — no hard sequencing dependency between server and client work, only a data-availability dependency at test time.

## PR Workflow

```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz \
  --title "feat(ui): Atlas implant panel — Phase 3 planetary viewer" \
  --description "Sprint 35 client work: atlas navigation panel, heightmap viewer, 9-overlay system" \
  --base main --head sprint-35/client
```