routes

PURPOSE

Declares the React Router route table for the metagame shell. Maps URL paths to screen components, defines redirects for retired routes, and exposes a /beta standalone PWA entry that auto-bootstraps a run.

OWNS

• The Routes component (exported), which renders a react-router-dom Routes element containing every metagame and dev-tool route.
• The BetaGameScreen local wrapper that seeds a default runDef (ship dart_common, planet index 0) via assembleRunDef when none exists, then renders GameScreen.
• The catch-all route that redirects unknown paths to /.
• Legacy-route redirects (/games/starship-survivors/ships/:hull, /games/starship-survivors/mods, /collection) that funnel to the unified /games/starship-survivors/ships?tab=select screen, and /games/starship-survivors/loot-bag which redirects to /.

READS FROM

• react-router-dom — Routes, Route, Navigate primitives.
• Screen components from ../screens/ and @starship-survivors/screens/: HubScreen, ShopScreen, ProfileScreen, AdminScreen, LevelSelectScreen, MissionBoardScreen, GameScreen, DevHomepage, ShipPlaygroundScreen, WeaponWorkbenchScreen, ShipsScreen, RevealScreen, ShipPullScreen, RunStatsScreen, BossTestScreen, PerfBenchmarkScreen, PerfDashboardScreen, PrologueScreen, NebulaViewerScreen, BackgroundsViewerScreen.
• useSessionStore from @starship-survivors/stores/sessionStore — read inside BetaGameScreen to inspect/set runDef.
• assembleRunDef from @starship-survivors/services/assembleRunService — invoked inside BetaGameScreen to seed a default run.

PUSHES TO

• Mutates sessionStore.runDef via setRunDef inside BetaGameScreen when first hitting /beta without a run in progress.

DOES NOT

• Does not declare a Router provider — assumes a parent component wraps it in a BrowserRouter (or equivalent).
• Does not perform auth, route guards, or permission checks. /admin is mounted unconditionally; gating lives inside AdminScreen.
• Does not lazy-load any screen — all screen modules are imported eagerly at module load.
• Does not handle deep-link query parameters; the ?tab= parameter on the ships route is parsed inside ShipsScreen.
• Does not log or telemeter route changes.

Signals

• Route table changes propagate to all metagame navigation. Adding a new screen requires importing it here and adding a <Route>.
• The BetaGameScreen wrapper signals that /beta is a self-bootstrapping standalone entry point — used as the PWA target so users can land directly in a run without traversing hub flow.
• Redirects from /games/starship-survivors/ships/:hull, /games/starship-survivors/mods, and /collection to /games/starship-survivors/ships?tab=select signal that ship detail, mods, and collection have been unified into the ShipsScreen tabbed layout.
• The redirect from /games/starship-survivors/loot-bag to / signals the loot bag screen has been retired.

Entry points

• Routes() — the only export; mounted from the metagame app shell.
• BetaGameScreen() — file-local, referenced only by the /beta route element.

Route table:

Path	Screen	Notes
/	HubScreen	Root metagame hub.
/shop	ShopScreen
/profile	ProfileScreen
/admin	AdminScreen	No router-level gating.
/games/starship-survivors/ships	ShipsScreen	Unified ship/artifact/mod screen, tab via ?tab=select|artifacts.
/games/starship-survivors/ships/:hull	redirect	→ /games/starship-survivors/ships?tab=select.
/games/starship-survivors/mods	redirect	→ /games/starship-survivors/ships?tab=select.
/collection	redirect	→ /games/starship-survivors/ships?tab=select.
/games/starship-survivors/levels	LevelSelectScreen
/games/starship-survivors/board	MissionBoardScreen
/games/starship-survivors/play	GameScreen	Main play entry.
/beta	BetaGameScreen	PWA entry; auto-seeds run.
/games/starship-survivors/reveal	RevealScreen
/games/starship-survivors/ship-pull	ShipPullScreen
/games/starship-survivors/loot-bag	redirect	→ /.
/games/starship-survivors/stats	RunStatsScreen
/prologue	PrologueScreen	Onboarding.
/dev	DevHomepage	Dev tools index.
/games/starship-survivors/boss-test	BossTestScreen	Dev.
/dev/analytics	PerfDashboardScreen	Dev.
/perf-benchmark	PerfBenchmarkScreen	Dev.
/nebula-viewer	NebulaViewerScreen	Dev.
/backgrounds-viewer	BackgroundsViewerScreen	Dev.
/ship-playground	ShipPlaygroundScreen	Dev.
/weapon-workbench	WeaponWorkbenchScreen	Dev.
*	redirect	→ / (catch-all).

Pattern notes

• Mixed path prefixes: most game routes live under /games/starship-survivors/... while dev tools and a few legacy paths (/dev, /shop, /profile, /admin, /prologue, /perf-benchmark, /nebula-viewer, /backgrounds-viewer, /ship-playground, /weapon-workbench, /beta) sit at the root. New game routes should use the /games/starship-survivors/ prefix; dev/test routes can sit at the root.
• Aliased import RRRoutes avoids a name collision with the exported Routes component.
• react-router-dom Navigate with replace prevents the retired URLs from polluting browser history.
• BetaGameScreen mutates the session store synchronously inside the component body before returning JSX. This works because Zustand’s setRunDef is a synchronous setter and GameScreen re-reads runDef from the store, but it does mean the first render reads runDef === null before the seeded run is committed. No effect or guard prevents repeated seeding if runDef is cleared mid-session.
• Mixing imports above and below the BetaGameScreen function definition is intentional but irregular — the screen imports that follow BetaGameScreen (lines 29-37) are only consumed by routes declared later in the file.
• All screen imports are eager. Bundle splitting for dev tools and rarely-used screens (BossTestScreen, PerfBenchmarkScreen, viewers) is not applied here.