---
sessionId: session-260928-131223-1ueu
---

# Requirements

### Overview & Goals
The goal of this initiative is to elevate the UI and user experience of `ZeroSpace.Web` and introduce an interactive **Galaxy Map** page. The Galaxy Map will visually display all planetary nodes positioned by their coordinates `(X, Y)`, render connection lines between interconnected systems, and provide instant hover information popups detailing yields, occupation buffs, masteries, and faction classifications.

### Scope
#### In Scope
- **Galaxy Page (`/galaxy`)**: Interactive star map rendering all 78 star systems from `StarSystems.All` with their actual `(X, Y)` spatial coordinates.
- **Connection Lines**: Drawing connection paths between systems based on `StarSystemData.ConnectedSystems`.
- **Hover Information Popup**: Dynamic floating tooltip/card showing system name, kind, occupation buffs, system masteries, yield bonuses, and connections.
- **Click Navigation**: Direct navigation from galaxy nodes to `/StarSystem/{Id}` details page.
- **UI & Aesthetic Overhaul**:
  - Updating `NavMenu.razor` with a dedicated Galaxy Map entry and modern styling.
  - Revamping `Home.razor` from default template placeholder to an engaging sci-fi overview dashboard.
  - Enhancing theme colors, badge indicators, cards, and typography in `app.css`.

#### Out of Scope
- Backend database schema modifications (uses existing static/generated `ZeroSpace.Model` records).
- Real-time multiplayer synchronization or editing capabilities (map editing remains in `ZeroSpace.MapEditor`).

### User Stories
- **As a player / wiki reader**, I want to view a visual galaxy map with all planetary nodes and connections so that I can understand system layout and routes across the galaxy.
- **As a player**, I want to hover over any planetary node to immediately see its occupation buff, yields, and system mastery without having to navigate to separate pages.
- **As a user**, I want to click on a star system node on the map to navigate directly to its detailed page.
- **As a user**, I want a sleek, cohesive dark sci-fi web interface with clear navigation and a functional dashboard.

### Functional Requirements
1. **Galaxy Map Rendering**:
   - The map shall render an SVG canvas encompassing coordinate bounds (0 to 1000) preserving aspect ratio.
   - Lines must connect every system with its entries in `ConnectedSystems` without duplicate edge rendering.
   - Planetary nodes shall be rendered as circular nodes styled and colored according to `StarSystemKind`:
     - *Homeworld*: Vibrant Emerald / Green (`#43a047` / `#10b981`)
     - *Core*: Vibrant Amber / Orange (`#fb8c00` / `#f59e0b`)
     - *Side*: Vibrant Sky Blue / Cyan (`#4a90d9` / `#38bdf8`)
2. **Hover Information Popup**:
   - Hovering over a planet node triggers a floating information popup.
   - Popup content includes:
     - Planet Name & Kind badge
     - Occupation buff (e.g. `+50 Starting Hexite`)
     - System mastery name (if present)
     - Higher yield indicators (Influence, Credits, Energy, Items)
     - Count and list of connected star systems
   - Tooltip disappears smoothly when the cursor leaves the node.
3. **Map Interaction**:
   - Hovering a node highlights the node (glow ring) and highlights incoming/outgoing connection lines.
   - Clicking a node navigates to `/StarSystem/{Id}`.
4. **App Navigation & Home Page**:
   - `NavMenu.razor` includes a link to `/galaxy` labeled "Galaxy Map" with an appropriate icon.
   - `Home.razor` provides quick-launch cards to Galaxy Map, Star Systems, Masteries, and Units with summary counts.

### Non-Functional Requirements
- **Performance**: Instant SVG rendering with zero lag for 78 nodes and ~200 connections; pure CSS/Blazor event handling with no external heavy mapping dependencies.
- **Responsiveness**: Map scales smoothly inside its container across desktop and mobile screens.
- **Accessibility**: Clear contrast ratios, readable tooltips, and keyboard/touch support for node selection.

# Technical Design

### Current Implementation
- `ZeroSpace.Model.StarSystems.All`: Contains all 78 star systems with records containing `Id`, `Name`, `Kind`, `X`, `Y`, `ConnectedSystems`, `OccupationBuff`, `SystemMastery`, and yield flags.
- `ZeroSpace.Web`: Blazor WebAssembly application using Bootstrap 5 and Telerik Blazor components.
- Existing pages include `StarSystemIndex.razor`, `StarSystemDetail.razor`, `SystemMasteryIndex.razor`, and `Units.razor`.
- `Home.razor` is currently a default "Hello World" template placeholder.

### Key Decisions
1. **SVG Vector Graphics for Galaxy Map**:
   - *Chosen Approach*: Native Blazor SVG rendering (`<svg viewBox="0 0 1000 1000">`).
   - *Rationale*: SVG offers vector sharpness at all display resolutions, reactive Blazor event binding (`@onmouseenter`, `@onmouseleave`, `@onclick`), lightweight footprint, and zero external JS dependency overhead.
2. **Dynamic Overlay Tooltip**:
   - *Chosen Approach*: HTML/CSS floating glassmorphism card positioned relative to the hovered node/cursor with smooth fade transition.
   - *Rationale*: Allows rich formatting (badges, icons, multi-column yields) and styling that matches the dark sci-fi aesthetic better than native SVG `<title>` or basic browser tooltips.
3. **Connection Line Optimization**:
   - *Chosen Approach*: Precompute unique undirected edge pairs `(From, To)` on initialization.
   - *Rationale*: Prevents duplicate overlapping lines between reciprocal connections `A -> B` and `B -> A`, improving render performance and visual clarity.

### Proposed Architecture & Flow

```mermaid
graph TD
    Nav[NavMenu.razor] -->|Navigate /galaxy| GalaxyPage[Galaxy.razor]
    Home[Home.razor] -->|Quick Link| GalaxyPage
    
    subgraph Galaxy.razor
        Model[StarSystems.All] --> EdgeBuilder[Connection Deduplicator]
        EdgeBuilder --> SVGCanvas[SVG Canvas ViewBox 0 0 1000 1000]
        Model --> NodeRenderer[Node Elements & Coordinates]
        
        SVGCanvas --> Lines[SVG Lines: Connection Paths]
        SVGCanvas --> Nodes[SVG Circles & Glows: Planets]
        
        Nodes -->|@onmouseenter| HoverState[Hovered System State]
        Nodes -->|@onclick| NavAction[NavigationManager.NavigateTo /StarSystem/Id]
        
        HoverState --> Popup[Floating Planet Info Card]
    end
```

### Components & File Structure
- **New Files**:
  - `ZeroSpace.Web/Pages/Galaxy.razor`: Main Galaxy map page containing the SVG viewport, control header, node filtering/legend, and popup overlay.
  - `ZeroSpace.Web/Pages/Galaxy.razor.css`: Scoped styles for map container, SVG glow effects, connection styling, and animated hover card.
- **Modified Files**:
  - `ZeroSpace.Web/Layout/NavMenu.razor`: Add "Galaxy Map" item with navigation icon.
  - `ZeroSpace.Web/Pages/Home.razor`: Overhaul into a sci-fi hub with hero banner and feature cards.
  - `ZeroSpace.Web/wwwroot/css/app.css`: Dark sci-fi styling improvements, badge colors, and glassmorphism utilities.

### Data Models / Contracts
```csharp
public sealed record ConnectionEdge(
    StarSystemData From,
    StarSystemData To);

public sealed class GalaxyMapState
{
    public IReadOnlyList<StarSystemData> Systems { get; set; } = StarSystems.All;
    public IReadOnlyList<ConnectionEdge> Connections { get; set; } = [];
    public StarSystemData? HoveredSystem { get; set; }
    public double TooltipX { get; set; }
    public double TooltipY { get; set; }
    public string? SelectedKindFilter { get; set; }
}
```

### Risks & Mitigations
- **Tooltip overflow near screen edges**: Clamp calculated tooltip coordinates within container boundaries to prevent viewport clipping.
- **Coordinate overlap on small screens**: Ensure viewBox preserves 1:1 aspect ratio (`preserveAspectRatio="xMidYMid meet"`) and allow zooming/scaling via standard CSS/viewport responsiveness.

# Testing

### Validation Approach
Verification will be performed through build checks, component markup analysis, and interactive scenario validation in the Blazor runtime.

### Key Scenarios
1. **Galaxy Map Rendering**:
   - Verify that all 78 star systems are rendered at their designated `(X, Y)` positions.
   - Verify that connection lines accurately connect linked systems without orphaned or broken lines.
   - Verify node color coding matches `StarSystemKind` (Homeworld, Core, Side).
2. **Hover Information Popup**:
   - Hovering over a planet node displays the popup immediately.
   - Verify all fields render accurately (Occupation buff, System mastery, Yields, Connected systems list).
   - Moving the mouse away dismisses the popup cleanly.
3. **Navigation & Interactivity**:
   - Clicking a node navigates to the corresponding `/StarSystem/{Id}` route.
   - Navigating via the "Galaxy Map" link in `NavMenu.razor` loads the page properly.
4. **UI & Responsiveness**:
   - Verify `Home.razor` renders updated dashboard cards and quick links.
   - Verify dark-theme sci-fi visual style across desktop and smaller browser viewports.

### Regressions & Edge Cases
- Star systems without occupation buffs or masteries display clean fallback dashes (`—`) without layout breaks.
- Rapid mouse movements over adjacent nodes update the hover popup smoothly without flickering.

# Delivery Steps

### ✓ Step 1: Implement Galaxy Map SVG rendering and connection lines
A functional SVG-based Galaxy Map page (`Galaxy.razor`) renders all star system nodes and connection lines based on their world coordinates.

- Create `ZeroSpace.Web/Pages/Galaxy.razor` with route `@page "/galaxy"` and navigation title.
- Parse `StarSystems.All` to extract unique undirected connection pairs and planetary node coordinate models.
- Render connection lines (`<line>`) in SVG with dark-steel futuristic line styling (`#3a4d6b`, opacity, glow).
- Render planetary nodes (`<circle>` / `<g>`) positioned at `(system.X, system.Y)` using color coding based on `StarSystemKind` (Homeworld = green, Core = orange/amber, Side = blue/cyan).
- Add SVG viewBox scaling (e.g. `0 0 1000 1000`) and responsive container layout to ensure crisp vector rendering on all screen sizes.
- Implement click handlers on nodes to navigate directly to `/StarSystem/{Id}`.

### ✓ Step 2: Implement dynamic planetary hover popup and interactive highlights
Interactive hover tooltip overlays display rich star system details when the user hovers over any planet node on the galaxy map.

- Design a floating glassmorphism hover card component / markup positioned dynamically relative to the active node or cursor.
- Display star system metadata: system name, `Kind` badge, `OccupationBuff`, `SystemMastery` link, and `Yield` bonuses (Influence, Credits, Energy, Items).
- Add highlight visual effects when hovering over a node (pulsing glow radius, highlight connected lines).
- Handle edge cases such as tooltip boundary clamping near viewport edges and debounced mouse enter/leave events.

### ✓ Step 3: Refine global UI, navigation menu, and dashboard landing page
ZeroSpace.Web navigation, Home landing dashboard, and global UI styles are updated to match a polished sci-fi space aesthetic.

- Update `ZeroSpace.Web/Layout/NavMenu.razor` with a dedicated "Galaxy Map" navigation link with custom star/galaxy icon.
- Transform `ZeroSpace.Web/Pages/Home.razor` into an overview hub showcasing quick links and summary stats for Galaxy Map, Star Systems, System Masteries, and Units.
- Enhance `ZeroSpace.Web/wwwroot/css/app.css` and component stylesheets with refined dark-theme colors, glassmorphism cards, glowing badges, and smooth hover transitions.
- Verify solution builds cleanly and all navigation flows between the Galaxy map, system details, and other pages work seamlessly.