Player Client¶

Status: 🚧 Partial — Core surfaces (first-login, galaxy 3D, trading-interface, subscriptions) are real. Re-verified 2026-08-21 vs tip 46bce720: Tip delta from prior 1a40ce1a includes Admin Soft-ORDER honesty + GS #710 medal collection GET — #710/#789-class deltas ≠ PC Soft-HOLD unlock. Soft-ORDER #789/#788 remain tip-PRESENT; PC Soft-HOLDs unchanged. contexts/ has 7 tsx files (Auth, Autopilot, FirstLogin, Game, Settings, WebSocket, WindshieldFlight); services/ has 11 ts files. components/pages/ has 5 tsx — no GalaxyMap.tsx or Dashboard.tsx on tip (App.tsx /game/map is RedirectToGame; 3D map is galaxy/Galaxy3DRenderer.tsx inside GameDashboard / cockpit NAV). Combat on tip is CombatInterface + NpcCombatBanner only. Soft-HOLD tip-pending (not tip-complete): Fibril #1210/#1209 i18n · #1445 Gatewright toll_stats · #1364 beacon popup · #1180 combat history browse · #1097 landing-rights whitelist/denylist · #1179 PlayerNamePlate medals — see § Soft-HOLD tip residuals below. Tip-PRESENT this stamp: #1178 bounty board (#838/#839); #1207 Leaderboards medal column (#865).

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.

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: Fibril #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: Fibril #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.

Soft-HOLD tip residuals (tip 46bce720 — do not read as tip-complete; PC Soft-HOLDs unchanged by Soft-ORDER #789 / #788 or GS #710): - Fibril #1210 — API-down / offline fallback seeds zh-CN (i18n runtime code is zh) and sets completionPercentage: 0 for every non-en row (LanguageSwitcher.tsx:58–59). Not the Admin launch-complete 100% path. - Fibril #1209 — scripts/validate-translations.js KNOWN_NAMESPACES is still {common, game, auth} while i18n.ts declares 7 namespaces (common, game, auth, ai, marketing, errors, validation). - Fibril #1445 / PR #618 — Gatewright owner toll_stats consumer still ABSENT on tip (GS listMine half tip-PRESENT; see ../FEATURES/galaxy/warp-gates.md). - Fibril #1364 / PR #719 — windshield beacon sector popup remains preview-only (no Read/Salvage CTAs; see ../FEATURES/gameplay/message-beacons.md). - Fibril #1180 / PR #689 — combat history browse UI tip-pending (GS GET /api/v1/combat/history tip-PRESENT via #756; PC ABSENT — see ../FEATURES/gameplay/combat.md). - Fibril #1097 / PR #698 — landing-rights whitelist/denylist UUID editor tip-pending (see ../FEATURES/planets/colonization.md). - Fibril #1179 / PR #597 — PlayerNamePlate medal identity tip-pending (see ../FEATURES/gameplay/medals.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.