Skip to content

Cockpit Shell & Menu Structure

Code-verified against services/player-client/src/ (anchors are file:line), browser-verified at 1440×900, as of 2026-07-11. This page is the canonical map of the player client's screen regions, navigation systems, and complete menu tree. For end-to-end task flows see ui-flows.md; for the tech stack see player-client.md.

The player client is a persistent starship cockpit, not a hub-and-spoke website. The player is always "in the chair": a windshield scene occupies the top of the screen, instrument monitors occupy the bottom deck, and a left sidebar carries the ship-systems nav rail plus two multi-function displays (MFDs). Routed pages render as a single full-height instrument monitor in place of the deck.

1. Screen regions

1.1 Geometry

Shell geometry is governed by three CSS variables — --band-h (windshield band height, 20%), --sidebar-w (clamp ≈317px at 1440w), --deck-h (48%) — plus four modifier classes (game-layout.css:84-172). At 1440×900 in flight mode:

┌──────────────────────────────────────────────────────────────────┐
│  WINDSHIELD BAND — full width, 20% height                        │
│  [PlayerVitalsHud overlay: name/rank · ₡ credits · turns ·       │
│   drones · mines · LINK · (bounty) · LOGOUT]                     │
├───────────────┬──────────────────────────────────────────────────┤
│ SIDEBAR 17.6% │  SCENE (right column of the inverted-L)          │
│ ┌───────────┐ │  canvas + HUD chips (LOCATION / HAZARD /         │
│ │ROUTE RAIL │ │  RADIATION / FORMATIONS)                         │
│ │ 9 keys    │ ├──────────────────────────────────────────────────┤
│ ├───────────┤ │  INSTRUMENT DECK — 37.4%                         │
│ │ MFD-A     │ │ ┌────────────┬──────────────┬────────────┐       │
│ ├───────────┤ │ │ PLANETARY  │     NAV      │   COMMS    │       │
│ │ MFD-B     │ │ │   (30%)    │    (40%)     │   (30%)    │       │
│ └───────────┘ │ └────────────┴──────────────┴────────────┘       │
└───────────────┴──────────────────────────────────────────────────┘

State variants:

State Windshield Deck Notes
Flight (/game) 45.0% (inverted-L) 37.4% — three monitors The only state where the scene is interactive
Docked 4.6% (auto-minimized, 60px band) 72.8% — single station monitor ⤢ Expand Viewport restores the band
Landed 4.6%, sidebar auto-collapses up to 93.3% — single planetary monitor .landed-expanded flips to 64.9% scene / 35% deck
Any other /game/* route absent 73.3% — one CockpitInstrument monitor hosts the routed page Sidebar + HUD persist (cockpit-instrument.css:28-77); exception: /game/player renders its own chrome instead of the monitor frame (PlayerInfo.tsx:73-105)

The document never scrolls on /game routes (GameLayout.tsx:141-152); scrolling happens only inside sanctioned containers (.mfd-page-body, .screen-hud-content, monitor interiors). One responsive breakpoint exists (768px); there is no mobile layout.

1.2 Always-visible vs conditional

Region Visibility
StatusBar (persistent bar: identity chip · location chip · vitals cluster · settings popup · logout) Always, every authed route; BOUNTY chip only when a bounty is active (StatusBar.tsx)
Sidebar (rail + both MFDs) Always mounted; collapsible (manual toggle, or auto-collapse on landing)
Windshield scene + deck /game only
Standalone monitor Every /game/* route except /game
Toast/overlay layer (medal, priority hail, welcome-back, NPC-combat banner, first-session objectives) Event-conditional; fixed z-ladder 1200–10000 (GameLayout.tsx:245-256)

2. Navigation systems

The client runs six distinct navigation grammars simultaneously. This is the load-bearing fact of the current organization and the primary target of reorganization review.

  1. RouteRail — 9 router-link keys in the sidebar, labeled with 3-letter mnemonics (full names on hover/ARIA only; RouteRail.tsx:5-19):
Key Full name Route Content
CMD COMMAND /game The cockpit (windshield + deck)
NAV NAV CHART /game/map Galaxy map (3D/2D, plot/engage autopilot)
PLY PLAYER INFO /game/player Tabs: IDENTITY · REPUTATION · HANGAR · COLONIES
SET SETTINGS /game/settings UI Scale slider + Back button (2 controls)
COL COLONIES /game/planets Owned-planet roster ("COLONIAL REGISTRY")
WPN WEAPONS /game/combat Target select + engage ("WEAPONS CONSOLE")
CRW CREW /game/team Team management ("CREW MANIFEST")
GOV GOVERNANCE /game/governance Elections · Policies · Treaties
SVC SERVICE RECORD /game/ranking Rank / promotion / standings (read-only)

  1. MFD-A / MFD-B — two persistent multi-function displays under the rail, each a softkey tablist with a hard 5-softkey cap and no paging, driven by the shared softkey-rail primitive that also drives monitor, station, and colony tablists (common/SoftkeyRail.tsx). MFD-A: STAT · CRGO · QTM (Warp Jumper only). MFD-B: POS · COMM. Threat and salvage read out on the TACTICAL and SOLAR SYSTEM deck monitors; ARIA converses on the teleprinter, which also exposes a JOURNAL tab → MemoryJournalPanel ✅ (LEG-397 / #701 8df00523). Page selection persists in localStorage sw2102.mfd.v1; docking/landing hydrates MFD-A to CARGO (situations.ts:19-25); a page may not appear on both MFDs at once; faulted pages render a PAGE FAULT boundary with RETRY.

  2. Deck monitors (flight, /game only) — PLANETARY (planet/station rows → Claim/Land/Dock, HARVEST), NAV (course plot + engage/abort + adjacent-sector click-to-move — the primary movement act), COMMS (CONTACTS/HAILS mailbox + HAIL composer).

  3. Docked sub-navigation — regular station: 3-tab console (🛒 TRADE · 🏛️ PORT OFFICE · 📋 CONTRACTS) + UNDOCK & LAUNCH. SpaceDock: a 10-venue card hub (Trading Hub · Shipyard · Construction (TradeDock) · Port Office · Contract Board · Genesis Store · Armory · Ship Services · Astral Mining · Gambling Hall) plus a reputation-gated Black Market door (SpaceDockInterface.tsx:1354-1863).

  4. Landed sub-navigation — planet vitals strip (rename · embark/disembark colonists · terraform header) plus, on owned non-hub planets, a 7-tab colony console: ⬡ Citadel · ▦ Grid · 🌍 Terraform · ⟳ Research · 🏭 Production · 🛡️ Defense · 🔐 Safe (CockpitColonyManagement.tsx:123-280).

  5. Windshield interactions (flight only) — canvas entity popups (stations → ⚓ DOCK), orbital closeup (🛬 LAND, ✎ rename), HUD chips with per-chip minimize (persisted cockpit.hud.<id>.min), LOCATION chip owner controls (◆ GOVERNANCE · region select · INVITE CONTROL · TRADEDOCK CONSTRUCTION), FORMATIONS 🔬 INVESTIGATE.

Plus a seventh, linguistic channel: the ARIA terminal accepts a nav-command grammar ("set course to N" / "engage" / "abort") parsed client-side before any network round-trip (ADR-0072; AriaTerminalPage.tsx:264-323).

3. Complete menu tree

Node format: [Label] (kind) — what it opens/does. DEAD = present in code but unreachable or no-op. ALSO-VIA = the same function is reachable elsewhere.

/game (CMD — cockpit)
├─ WINDSHIELD (flight scene only)
│  ├─ [entity] canvas-click → info popup → [⚓ DOCK] (stations)
│  ├─ [planet] canvas-click → orbital closeup → [🛬 LAND] · [✎ NAME THIS WORLD]
│  ├─ LOCATION chip → [◆ GOVERNANCE] · [◆ region select] · [◆ INVITE CONTROL]
│  │                  · [◆ TRADEDOCK CONSTRUCTION] (owner-gated)
│  └─ FORMATIONS chip → [🔬 INVESTIGATE] (one-shot per formation)
├─ DECK — flight (three monitors)
│  ├─ PLANETARY: [planet row → Claim/Land] · [station row → Dock] · [⛏️ HARVEST]
│  ├─ NAV: [sector# + PLOT] · [🧭 ENGAGE] · [🛑 ABORT] · [adjacent node → MOVE]
│  │       · [WARP GRAPH | QUANTUM DRIVE] (Warp Jumper) → Gatewright panel
│  └─ COMMS: [CONTACTS | HAILS] · [HAIL] (per contact)
├─ DECK — docked at regular station
│  └─ [🛒 TRADE | 🏛️ PORT OFFICE | 📋 CONTRACTS] · [🚀 UNDOCK & LAUNCH]
│     ├─ TRADE → market grid · Buy/Sell desks · Trade Route Optimizer
│     ├─ PORT OFFICE → [Registry | War Room] · Acquisition Desk
│     └─ CONTRACTS → [Board | My Contracts | Post Contract] · [Accept] per row
├─ DECK — docked at SpaceDock
│  └─ 10 venue cards + Black Market door (rep-gated) · [← Back to Hub] in each
├─ DECK — landed (owned, non-hub planet)
│  ├─ vitals strip: [✎ rename] · [⬇ DISEMBARK] · [⬆ EMBARK] → transfer modal
│  └─ colony console: [⬡ Citadel]* · [▦ Grid] · [🌍 Terraform] · [⟳ Research]
│     · [🏭 Production] (preset buttons + coupled sliders + 🔐 Store + 🎯 Specialization)
│     · [🛡️ Defense] (upgrade/build with inline two-step confirms)
│     · [🔐 Safe] (Deposit|Withdraw tabs · quick-fill % · auto-deposit · per-commodity)
│     (* Citadel tab hosts Buildings / Defenses / Siege modals)
│
SIDEBAR (all routes)
├─ RouteRail: CMD NAV PLY SET COL WPN CRW GOV SVC (§2 table)
├─ MFD-A: [STAT] vitals · [CRGO] cargo + [TERRAFORM READY — DEPLOY]
│         · [THRT] hazard/law + [Clear Fine] + [LAY MINEFIELD qty+Deploy]
│         · [QTM] (Warp Jumper) · [SALV] wrecks → [qty + Salvage]
├─ MFD-B: [NAV] position/exits (display-only) · [ARIA] chat + command grammar · Teleprinter [JOURNAL] → memory journal ✅
│         · [COMM] unread/contacts/crew (passive — no composer)
└─ DEAD MFD pages: [TURN] turn-economy · [REP] reputation (registered, no softkey)
│
ROUTED PAGES (single monitor)
├─ /game/map (NAV): [3D|2D] · [Scan latent warps] · [+/−/Reset] · sector node →
│     [Travel to Sector] · [Lay in course] · [Engage Autopilot] · FRONTIER chips
├─ /game/player (PLY): [IDENTITY | REPUTATION | HANGAR | COLONIES]
├─ /game/settings (SET): [UI Scale] · [← Back to game]
├─ /game/planets (COL): colony roster
├─ /game/combat (WPN): target select → engage → round replay
├─ /game/team (CRW): create-team form | [Overview|Members|Treasury|Chat|Settings]
├─ /game/governance (GOV): [Elections|Policies|Treaties] · [+ PROPOSE POLICY]
├─ /game/ranking (SVC): rank/promotion/commendations/standings (zero controls)
├─ /game/ships — ORPHAN (no link anywhere; typed URL only) — ship switcher
└─ /game/trading — ORPHAN (no link anywhere) — standalone trade ledger

3.1 Counts (live controls; venue/modal interiors excluded)

Metric Value
Total interactive options across all states ≈205
Top-level entries (rail 9 + softkeys 8 + LOGOUT) 18
Max nesting depth 6 clicks
Routed pages 11 (9 rail-linked, 2 orphaned)
Sub-navigation systems invisible to the router 6
Registered-but-dead MFD pages 2

3.2 Clicks-to-reach (from flight, defaults)

Action Clicks Action Clicks
Move (adjacent) 1 Colony manage 2
Check cargo 1 (0 docked) Team chat 2
Settings 1 Combat engage 3
Chat ARIA 0–1 Trade desk 2–3
Dock 2 Repair ≥3

4. Known organizational debt

These are statements of the shipped structure, recorded so reorganization work has a checklist.

Duplicate paths — the same function reachable N ways with no declared primary:

Function Ways Surfaces
Trading 4 docked TRADE tab · SpaceDock venue · orphan route · embedded component
Movement / course plotting 5 NAV-monitor node click · PLOT/ENGAGE · cockpit NAV / Galaxy3DRenderer (not GalaxyMap.tsx — absent on tip 46bce720; App.tsx /game/map is RedirectToGame) · ARIA grammar · per-colony Set course rows (PlanetManager.tsx:530-539, also inside PLY→COLONIES)
Autopilot engage/abort 3 NAV monitor · cockpit NAV / Galaxy3DRenderer · ARIA
Planet roster 3 COL route · PLY→COLONIES tab · landed console (deep)
Dock / Land 2 each PLANETARY monitor rows · windshield popups
Governance 2 GOV rail key · LOCATION chip button
Hangar 2 PLY→HANGAR tab · orphan /game/ships

Misgroupings:

  • SETTINGS (2 controls) and SERVICE RECORD (0 controls) each hold one of only 9 top-level keys, peers to WEAPONS and GOVERNANCE.
  • HANGAR and TRADE LEDGER are full instrument pages with no rail presence — buried as a sub-tab and a docked tab respectively.
  • Messaging is stranded: the COMM MFD page is deliberately passive, and the only hail composer lives on the flight deck — there is no way to compose a message while docked, landed, or on any routed page.
  • Combat state has three homes: WPN route (engage), THRT MFD (mines/law/fines), NPC-combat banner (toasts).
  • Colony management is split across three differently-shaped surfaces (deep console · roster route · roster tab).

Naming collisions:

  • "NAV" names three things — the NAV CHART rail key, the NAV/POSITION MFD page (~150px apart in the same column), and the deck NAV monitor. The control that actually moves the ship is the unlabeled monitor.
  • "CREW" names two concepts — CRW rail key opens team management ("CREW MANIFEST"); the COMM MFD page ("COMMS / CREW") shows sector contacts.
  • Trading carries three names (TRADE LEDGER · 🛒 TRADE · Trading Hub 🏪) for one component.
  • The per-system accent palette reuses the same cyan for CMD, NAV CHART, GOVERNANCE, and SETTINGS — color does not uniquely identify a system.
  • Two chrome dialects coexist: the rail/MFD layer is strict text-glyph (no emoji); the deck/console layer is emoji-heavy.

Structural constraints for any reorg:

  • Every route remounts its own GameLayout, so sidebar/windshield UI state resets per navigation — a persistent layout route is a prerequisite for stateful nav chrome (GameLayout.tsx:134,230).
  • MFD-A is at its 5-softkey cap; the next MFD page must land on MFD-B or force a redesign.
  • Shell geometry is centralized in three CSS variables — regions can be re-plumbed in one file (game-layout.css:84-172).
  • Defense/Safe tab bodies live inside the 3,598-line GameDashboard closure rather than components — any reorg drags dashboard state with it.

5. Dead surfaces (disposition pending)

Surface State
/game/ships, /game/trading Routed, zero inbound links — orphans
MFD pages TURN ECONOMY, REPUTATION Registered + tested; no softkey; selection rejected
pages/Dashboard.tsx (legacy Command Center) Imported nowhere
pages/SubscriptionResult.tsx No route — PayPal return flow dead-ends client-side
Docked/landed min-bar system (EXPAND/MINIMIZE SURFACE/BAY) Hidden or no-op
TacticalCard Imported, never rendered
responsive.css / mobile-game.css layout classes Zero TSX usages

Closed 2026-08-16 (LEG-64 / LEG-72): Windshield planet-popup LAND branch removed — planet Inspect routes to orbital closeup (enterOrbit); LAND remains on the orbital-closeup HUD only. Live-flight windshield LAND stays on the WindshieldTableau proximity flow. Intentional path: planet → orbital closeup → LAND.

6. Reserved menu slots (canon-mandated, partial / unbuilt)

Surfaces canon requires that the menu tree must eventually seat — reserve homes for these during any reorganization:

  • ✅ ARIA memory journal — Teleprinter JOURNAL tab → MemoryJournalPanel.tsx (LEG-397 / PR #701 8df00523); not the same as a full companion avatar surface — see aria-companion.md.
  • 🚧 ARIA companion panel (avatar / tier / relationship) — still reserved/partial alongside the shipped journal tab.
  • ARIA recommendation panels (aria.md), unified message inbox + priority ladder (messaging.md), fleet coordination (fleet-tactics.md), bounty board (bounties.md), beacon deploy/list (message-beacons.md), mining license/depletion affordances (mining docs), reputation readout in the top bar (DECISIONS #9), and subscription management (monetization.md).