Player Client¶

Status: 🚧 Partial — Core surfaces (first-login, galaxy 3D, trading-interface, subscriptions) are real. Re-verified 2026-09-01 vs tip df11cf380: contexts/ has 7 tsx files; services/ has 14 ts files. components/pages/ has 5 tsx — no GalaxyMap.tsx or Dashboard.tsx on tip. Combat history browse ✅ tip-PRESENT via CombatHistoryPanel in ServiceRecordTab.tsx. PlayerNamePlate medal chrome ✅ tip-PRESENT on df11cf380 (incl. CombatHistory foe pins #1185). Persisted ARIA trading recommendations browse ✅ tip-PRESENT via TradingRecommendationsPanel in TradingInterface.tsx (#1184 / LEG-3217). Tip delta from prior 2d64087f4 stamp: MERGED #1320/#1321/#1322/#1324/#1325/#1313/#1316/#1317/#1318 + OPEN PC #1327(EmpireProductionDashboard + CockpitColonyManagement transport-error densify) + GS OPEN #1312/#1328 (feat tip df11cf380) — tip-PRESENT ≠ Soft-HOLD unlock. Soft-HOLD tip residuals: none beyond density Soft-HOLD (orthogonal). ✅ #1210/#1209 i18n CLOSED; ✅ #1364 beacon Read/Salvage CLOSED; ✅ #1097 LandingRights UUID editor CLOSED — all tip-PRESENT on df11cf380. Tip-PRESENT this stamp: #1178 bounty board (#838/#839); #1207 Leaderboards medal column (#865); #1180 combat history browse (CombatHistoryPanel); #1179 PlayerNamePlate medals; #1445 Gatewright owner toll_stats (#618 / LEG-100); #1184 trading recommendations browse (TradingRecommendationsPanel).

The player-facing web app at services/player-client/.

1. Tech stack¶

From services/player-client/package.json on tip 9dc7ed12:

Layer	Choice
Framework	React 19.2 + TypeScript 7.0
Build	Vite 8.2
Routing	react-router-dom 7.18
HTTP	axios 1.19
3D	three 0.185, @react-three/fiber 9.7, @react-three/drei 10.7
Animation	react-spring 10.0 (no framer-motion on tip)
Icons	lucide-react 1.28
Sanitization	isomorphic-dompurify 3.21 (XSS prevention for AI chat)
Utility	lodash.debounce, lodash.throttle
i18n	i18next 26.3 + react-i18next 17.0 + browser-languagedetector + http-backend
Tests	Vitest 4.1 (`npm test`); Playwright 1.62 (E2E)

State management: React Context (AuthContext, AutopilotContext, FirstLoginContext, GameContext, SettingsContext, WebSocketContext, WindshieldFlightContext).

Default ports: player-client on 3000, gameserver on 8080.

2. Project layout¶

services/player-client/src/
├── App.tsx, main.tsx, i18n.ts
├── components/
│   ├── ai/              AIAssistant, AIAssistantButton, EnhancedAIAssistant (ARIA chat)
│   ├── analytics/       AchievementTracker, GoalManager, Leaderboards, PlayerAnalytics, ProgressVisualizer
│   ├── auth/
│   ├── combat/          CombatInterface, NpcCombatBanner (only — no CombatLog / CombatAnalytics / DroneManager / FleetBattlePanel / FormationControl / SiegeInterface / TacticalPlanner on tip)
│   ├── common/          shared UI (LanguageSwitcher, etc.)
│   ├── first-login/     FirstLoginContainer, DialogueExchange, ShipSelection,
│   │                    OutcomeDisplay, NicknameConfirm
│   ├── galaxy/          Galaxy3DRenderer, SectorNode3D, PlayerMarker3D,
│   │                    ConnectionPath3D, StarField, CourseConfirmPopup
│   ├── layouts/
│   ├── market-intelligence/  MarketAnalyzer, PricePredictor, RouteOptimizer, CompetitionMonitor
│   ├── pages/           5 tsx pages (see Section 3) — no GalaxyMap.tsx / Dashboard.tsx
│   ├── paypal/          PayPalSubscription
│   ├── planetary/       15 tsx (PlanetManager, BuildingManager, ColonistAllocator,
│   │                    ColonySpecialization, DefenseConfiguration, GenesisDeployment,
│   │                    SiegeStatusMonitor, CitadelManager, CitadelStructure, GridManager,
│   │                    LandingRightsControl, PioneerOfficeVenue, PopulationCenterInterface,
│   │                    SpecializationDrawer, TerraformingPanel) — no ProductionDashboard.tsx on tip
│   ├── ranking/         RankDisplay, RankProgress, Leaderboard, MedalShowcase
│   ├── ships/           InsuranceManager, MaintenanceManager, ModuleGridInterface,
│   │                    ShipRegistryPanel, ShipSelector
│   ├── spacedock/       SpaceDockInterface
│   ├── tactical/        SectorViewport, NavigationMap, PlanetCard, PlanetPortPair,
│   │                    StationCard, TacticalCard
│   ├── teams/           TeamManager, TeamChat, ResourceSharing, MissionPlanner
│   └── trading/         TradingInterface, MarketIntelligenceDashboard, SmartTradingAutomation
├── contexts/            Auth, Autopilot, FirstLogin, Game, Settings, WebSocket, WindshieldFlight (7 tsx)
├── services/            api.ts, apiClient.ts, websocket.ts, aiTradingService.ts,
│                        deckNavBus.ts, intrasystemFlight.ts, marketStream.ts, resourceCatalog.ts,
│                        routeOptimizerService.ts, teleprinterBus.ts, warpCinematicBus.ts (11 ts)
├── styles/, themes/, types/, utils/
└── utils/security/      XSS / sanitization helpers (separate from common utils)

A shared API layer lives in services/api.ts plus services/apiClient.ts. Real-time traffic flows through services/websocket.ts (the multiplayer protocol client).

3. Pages¶

components/pages/ has 5 tsx pages on tip 9dc7ed12 — not 7, and not GalaxyMap.tsx:

Page	Purpose
`LoginPage.tsx`	Auth
`GameDashboard.tsx`	Player landing / cockpit (galaxy 3D, NAV, gameplay decks)
`SubscriptionResult.tsx`	PayPal subscription confirmation
`DebugPage.tsx`, `TestAuthPage.tsx`	Dev / QA tools

There is no Dashboard.tsx and no GalaxyMap.tsx anywhere under services/player-client on this tip. App.tsx routes /game/map (and several sibling paths) to RedirectToGame; the Three.js map is galaxy/Galaxy3DRenderer.tsx inside the GameDashboard cockpit, not a standalone page.

Most actual gameplay UI happens inside GameDashboard via the feature modules above rather than dedicated pages.

4. Key features¶

first-login/FirstLoginContainer.tsx orchestrates the AI guard interrogation. DialogueExchange.tsx renders the conversation, ShipSelection.tsx is the ship picker, OutcomeDisplay.tsx shows the resolution, NicknameConfirm.tsx confirms the callsign. There is no TrustMeter.tsx on tip 9dc7ed12. CSS is heavy (first-login.css). Backed by /api/v1/first-login/* and the multi-provider AI dialogue service (OpenAI primary, Anthropic secondary, deterministic fallback).

Trading + ARIA market intelligence¶

trading/TradingInterface.tsx is the core buy/sell UI. trading/MarketIntelligenceDashboard.tsx (~22 KB) and trading/SmartTradingAutomation.tsx (~29 KB) plus the market-intelligence/ quartet (MarketAnalyzer, PricePredictor, RouteOptimizer, CompetitionMonitor) surface ARIA's per-player observations and predictions. Service: services/aiTradingService.ts.

Tip-PRESENT this stamp: LEG-3217 / #1184 MERGED → feat tip 3ed0147cd — TradingRecommendationsPanel.tsx mounted from TradingInterface.tsx:898,1316; first player consumer of GET /api/v1/ai/recommendations via aiTradingService.getRecommendations(). TradeCascadePanel.tsx (LEG-725 / POST /api/v1/ai/trade-cascade) ships on the same trading desk surface. See ../FEATURES/gameplay/aria-companion.md and ../SYSTEMS/enhanced-ai-intelligence.md.

Combat¶

Two components in combat/ on tip 9dc7ed12: CombatInterface.tsx and NpcCombatBanner.tsx. The older eight-file set (CombatLog, CombatAnalytics, DroneManager, FleetBattlePanel, FormationControl, SiegeInterface, TacticalPlanner) is absent — do not invent those UIs back onto the tip. Product combat-HUD / drone gaps belong to existing player-client WOs, not this inventory page. There is no combat/README.md on tip.

Planetary management¶

15 tsx components in planetary/ on tip 9dc7ed12 (PlanetManager, BuildingManager, ColonistAllocator, ColonySpecialization, DefenseConfiguration, GenesisDeployment, SiegeStatusMonitor, CitadelManager, CitadelStructure, GridManager, LandingRightsControl, PioneerOfficeVenue, PopulationCenterInterface, SpecializationDrawer, TerraformingPanel). ProductionDashboard.tsx is not on tip.

Galaxy / 3D¶

galaxy/Galaxy3DRenderer.tsx plus SectorNode3D, PlayerMarker3D, ConnectionPath3D, StarField, and CourseConfirmPopup provide the Three.js view (cockpit NAV — not a pages/GalaxyMap.tsx). tactical/SectorViewport.tsx is the in-sector 2D view.

Teams / alliances¶

Four tsx components in teams/ on tip 9dc7ed12: TeamManager, TeamChat, ResourceSharing, MissionPlanner. TeamAnalytics / AllianceManager / DiplomacyInterface are not on tip.

Ships & space dock¶

ships/ has 5 tsx components on tip 9dc7ed12 (InsuranceManager, MaintenanceManager, ModuleGridInterface, ShipRegistryPanel, ShipSelector). CargoManager / FleetCoordination / ShipDetails / UpgradeInterface are not on tip. spacedock/SpaceDockInterface.tsx is the standalone dock view.

ARIA chat¶

See ./aria.md — ai/EnhancedAIAssistant.tsx is the main chat component with DOMPurify sanitization, client-side rate limiting, Web Speech API, and WebSocket integration.

Subscriptions¶

paypal/PayPalSubscription.tsx plus pages/SubscriptionResult.tsx handle the PayPal monetization flow used by multi-regional ($25/mo regional ownership, $5/mo galactic citizenship — see ./multi-regional.md).

Player progression UI¶

ranking/ (RankDisplay, RankProgress, Leaderboard, MedalShowcase) renders the military-rank progression. See FEATURES/gameplay/ranking.md.
analytics/AchievementTracker.tsx, GoalManager.tsx, and the rest of the analytics/ directory cover lifetime achievements and personal goals.

Real-time multiplayer¶

services/websocket.ts is the multiplayer-protocol client (presence, sector chat, combat events). See ./realtime.md.

i18n¶

common/LanguageSwitcher.tsx; full i18next setup. Six languages targeted (English / Spanish / French / Portuguese / Chinese launch-complete; German Partial — see ./i18n.md).

Tip-PRESENT this stamp: #1178 / #838 MERGED → b0fa048a8 + place/cancel #839 — player-client BountyBoard.tsx + BountyPlaceCancel.tsx mounted from ServiceRecordTab.tsx; bountyAPI.getAvailable / place / cancel bound on feat tip (ancestor 935e557d3 / #946). #838/#839 is PC product ≠ density Soft-HOLD unlock. See ../FEATURES/gameplay/bounties.md.

Tip-PRESENT this stamp: #1207 / #865 MERGED → 4108cf582 / LEG-2594 — player-client Leaderboard.tsx Medals column (medal_count + pinned_medal_id; PlayerNamePlate leaderboard-medal-plate). Live origin/feat 935e557d3 ancestor. #865 is PC product ≠ density Soft-HOLD unlock. See ../FEATURES/gameplay/medals.md.

Tip-PRESENT this stamp: #1445 / PR #618 MERGED → 07c629d6 / LEG-100 — GatewrightPanel.tsx calls warpGatesAPI.listMine() and renders owner toll_stats. Re-verified 2026-08-31 vs origin/feat a9e82ca55. See ../FEATURES/galaxy/warp-gates.md § Toll system.

Tip-PRESENT this stamp: #1180 / CombatHistoryPanel.tsx — Service Record dossier + standalone combat history browse on tip 391dd835c (ServiceRecordTab.tsx:41, CombatInterface.tsx:555; GS GET /api/v1/combat/history via #756; Vitest CombatHistoryPanel.typeErrorHonesty.test.tsx). See ../FEATURES/gameplay/combat.md.

Tip-PRESENT this stamp: #1179 / PlayerNamePlate.tsx — pinned-medal identity chrome tip-PRESENT on 3ed0147cd (CommsCrew, Leaderboard, TeamManager, sector view). See ../FEATURES/gameplay/medals.md.

Tip-PRESENT this stamp: #1184 / LEG-3217 — TradingRecommendationsPanel.tsx persisted recommendations browse tip-PRESENT on feat 3ed0147cd (TradingInterface.tsx:898,1316; aiTradingService.getRecommendations() → GET /api/v1/ai/recommendations). See ../FEATURES/gameplay/aria-companion.md.

Tip-PRESENT this stamp: #1185 / PR #1185 / LEG-3234 — CombatHistoryPanel.tsx foe PlayerNamePlate (pinnedMedalId/medalCount from item.opponent) on tip 89b712001. See ../FEATURES/gameplay/medals.md.

Tip-PRESENT this stamp (Soft-HOLD #1364 CLOSED): windshield sector-view beacon popup ships visitor Read/Salvage CTAs (windshieldTableauPopupContent.tsx case 'beacon' + beaconAPI.read/salvage; Vitest windshieldTableauPopupContent.test.tsx) on tip 89b712001. See ../FEATURES/gameplay/message-beacons.md.

Tip-PRESENT this stamp (Soft-HOLD #1097 CLOSED): LandingRightsControl.tsx whitelist/denylist UUID list editor (data-testid=landing-rights-list-editor, parseUuidList) on tip 89b712001. See ../FEATURES/planets/colonization.md.

Soft-HOLD tip residuals (tip 89b712001 — do not read as tip-complete): - ✅ #1210 CLOSED tip-PRESENT — API-down / offline fallback uses runtime zh + STATIC_COMPLETION_PERCENT (en/es/fr/zh/pt=100, de=26) via buildStaticLanguages() (LanguageSwitcher.tsx:27-46). Not a zh-CN/0% seed. - ✅ #1209 CLOSED tip-PRESENT — scripts/validate-translations.js KNOWN_NAMESPACES lists all 7 namespaces matching i18n.ts (common,game,auth,ai,marketing,errors,validation). - ✅ #1364 CLOSED tip-PRESENT — windshield beacon sector popup Read/Salvage CTAs on tip 89b712001 (windshieldTableauPopupContent.tsx; see ../FEATURES/gameplay/message-beacons.md). - ✅ #1097 CLOSED tip-PRESENT — landing-rights whitelist/denylist UUID list editor on tip 89b712001 (LandingRightsControl.tsx; see ../FEATURES/planets/colonization.md).

Do not remint these Soft-HOLDs. Density Soft-HOLD is orthogonal.

5. Build / test¶

# from services/player-client/
npm run dev         # vite dev (port 3000)
npm run build       # tsc + vite build
npm run lint        # eslint
npm test            # vitest run
npm run test:e2e    # playwright via scripts/run-tests.js
npm run test:e2e:ui # playwright UI mode

E2E specs on tip 9dc7ed12 live in e2e_tests/player/ui/ (4 files): player-ui.spec.ts, deck-page-switch.spec.ts, deck-reflow-bands.spec.ts, uiscale-band-clear-matrix.spec.ts. e2e_tests/foundation-sprint/ contains only test-helpers.ts — the previously named security-validation.spec.ts / websocket-realtime.spec.ts are not on tip.