Feature Map

00 · Overview

Top-level routing happens in src/App.tsx and is driven by state.screen (one of 'title' | 'map' | 'docked' | 'denied' | 'transit' | 'gameover', defined in src/state/types.ts). Persistent chrome stacks on every non-title screen; overlays and modals stack on top.

Quick reference

01 · Window Taxonomy

Every visible UI surface, grouped by its window class. One row per pane — tabs inside a tabbed window are listed individually, not folded into the parent.

1a · Screens

1b · Panes (tabs)

StationPanel  — left column of DockPanel

File: src/components/StationPanel.tsx. A .station-hero header (station art + faction emblem + standing bar) sits above a two-level tab nav: four primary groups (Trade / Services / People / Info) and, when a group has more than one tab, a secondary .station-subtabs row. Each tab's visibility depends on station.shipyard, station.outfitting, etc.

ShipPanel  — right column of DockPanel

File: src/components/ShipPanel.tsx. A fixed-width sidebar (flex: 0 0 clamp(380px, 36%, 480px)) with no tabs — an always-on summary that stacks the readouts, crew roster, and cargo list.

StoryPanel  — Star Map .starmap-nav-dock tabs (L key)

File: src/components/StoryPanel.tsx. Not a standalone window — it renders in the lower section of the Star Map's navigation sidebar (.starmap-nav-dock, §1c) as the Missions / Factions / Codex tabs alongside the Roster. [L] jumps to the Missions tab. Accepts a controlled tab prop + showTabs={false} so the sidebar's tab strip drives it.

1c · Sub-surfaces (Star Map zones)

StarMap.tsx is a two-column shell (.starmap-layout), mirroring the docked layout: a map canvas (.starmap-root, left, flexible) + a persistent navigation sidebar (.starmap-nav, right, clamp(340px,32%,420px)). The old floating Intel / roster / bottom-strip windows were folded into the sidebar.

1d · Overlays

1e · Modals

1f · Persistent Chrome

Rendered on top of every non-title screen. Not windows — never call them "panels".

1g · Proposed — new homes for orphaned systems

These game systems exist in the engine / data but have no canonical window today — they're either scattered inline across unrelated panels or invisible after the moment they fire. Each row below is a proposed new pane; none of these are implemented yet. Documenting them as the agreed home prevents the next ad-hoc inline render from deepening the scatter.

02 · Shared Components

Canonical implementations of UI patterns that appear in multiple panes. Located at src/components/shared/. Do not duplicate these inline — import from shared/. If you find a pattern rendered in 2+ panes with cosmetic drift, promote it here.

03 · Engine Modules

Pure modules under src/engine/. No React imports. Each pane consumes zero or more of these to compute display values.

04 · Static Data

All under src/data/. Loaded at build time. Every entity follows the same convention: one JSON file per entity, aggregated into an array by a thin .ts wrapper using import.meta.glob. No data is inline in TypeScript.

4a · Data editor (/editor/ — dev-only)

A password-gated editor for tweaking the static-data JSON (and balance.json) against the running game, for balancing. Dev-only: it lives under npm run dev and is deliberately excluded from vite build (not in rollupOptions.input), so it 404s on a deployed site.

Schemas cover all 10 entity types plus balance.json; every existing data file validates clean. Saving writes the real source JSON on disk (canonical 2-space); Vite HMR then reloads any open /game/ tab. See .env.local.example to enable.

4b · Telemetry server + admin console (deployed)

A standalone Node service (server/, Fastify + node:sqlite) on the OVH box. Not part of the game build or static rsync — it runs as its own systemd service; nginx serves the static game and reverse-proxies /api/* + /editor to it.

Saves are a mirror: localStorage stays the source of truth for playing; the server copy exists for the console. No cross-device restore.

4c · Public guide (generated)

The player-safe documentation portal at /guide/ is generated from docs/public/*.md and docs/catalog.json. scripts/generate-docs.mjs emits a landing page, clean chapter routes, and a static search index during predev and prebuild.

Generated guide HTML and public/guide/search-index.json are ignored build output. Maintainer runbooks never enter dist/.

05 · Keyboard Map

Handled in App.tsx (handleKey) unless noted. ? / / always toggles ControlsOverlay.

The canonical list rendered to the player lives in src/components/ControlsOverlay.tsx. Keep this table and that array in sync.

06 · Screen Transitions

                ┌──────────┐
                │  title   │
                └────┬─────┘
                     │ start / load
                     ▼
                ┌──────────┐                ┌─────────────┐
   undock ◀────┤   map    ├─── jump ─────▶ │   transit   │
                │          │                │             │
                │   ▲      │ complete       │  (StarMap   │
                │   └──────┼────────────────┤   in        │
                │          │                │   transit   │
                │  dock    │                │   mode)     │
                └────┬─────┘                └─────────────┘
                     │
                     ▼
                ┌──────────┐
                │  docked  │
                └────┬─────┘
                     │
              hostile / locked
                     ▼
                ┌──────────┐
                │  denied  │
                └──────────┘

       hull == 0 / catastrophic event from any state ▶  gameover

07 · When to Update This File

You must update this file (and its markdown twin feature-map.md) when you:

• Add a new top-level screen (new value of state.screen).
• Add a new tab to StationPanel, ShipPanel, or StoryPanel.
• Add a new persistent chrome element rendered above every screen.
• Add a new overlay or modal.
• Add a new sub-surface to StarMap.
• Add a new engine module under src/engine/.
• Add a new key binding handled by App.tsx or a screen-level component.
• Implement one of the §1g proposed homes — move its row from §1g into §1b in the same change.

You do not need to update this file for:

• Internal refactors that don't change the surface area.
• Visual-only tweaks (those go in style-guide.md).
• Data-only additions (new stations, ships, goods, missions) — those flow through existing tables.