galaxy-game/ui/docs/navigation.md

In-game shell — navigation model

This doc covers the chrome that wraps every in-game view: the single-URL app-shell that selects screens and views from in-memory state, the responsive layout shell, the sidebar with three tools and its state-preservation rule, and the mobile bottom-tabs. The user-facing spec — view list, breakpoint diagrams, history-mode plans — lives in ../PLAN.md, section Information Architecture and Navigation. This doc is the source of truth for how those rules are implemented.

App-shell: one URL, screens and views as state

The game UI is a single SvelteKit route served at /game/. There are no per-screen or per-view routes — the address bar stays /game/ for the whole session. The only other routes are the dev/test-only /__debug/* surfaces. What the URL used to encode now lives in two rune singletons in src/lib/app-nav.svelte.ts:

• appScreen — the top-level screen (login / lobby / lobby-create / game) plus the active gameId. It replaces the old goto-based redirects and the [id] route param.
• activeView — the in-game view (map / table / report / battle / mail / designer-science) plus the sub-parameters the old route segments carried (tableEntity, battleId, turn, scienceId). It replaces the URL params the route wrappers read.

A single-route dispatcher (src/routes/+page.svelte) chooses what to render: it gates on session.status (anonymous → login, authenticated → the appScreen.screen), and for the authenticated tree mounts the matching screen component from src/lib/screens/ (login-screen.svelte, lobby-screen.svelte, lobby-create-screen.svelte) or, for screen === "game", the in-game shell src/lib/game/game-shell.svelte. The game shell in turn renders the active view from activeView (see below). Navigation is appScreen.go(screen, { gameId }) and activeView.select(view, params) — never goto.

Active-view dispatch

The client renders one active view at a time. The game shell (game-shell.svelte) holds an {#if} ladder keyed on activeView.view that mounts the matching content component from src/lib/active-view/<name>.svelte:

activeView.view	sub-params	Active view component
map	—	lib/active-view/map.svelte
table	tableEntity	lib/active-view/table.svelte
report	—	lib/active-view/report.svelte (see report-view.md)
battle	battleId, turn	lib/active-view/battle.svelte
mail	—	lib/active-view/mail.svelte
designer-science	scienceId	lib/active-view/designer-science.svelte

Entering a game defaults the view to map (activeView.reset()). The optional scienceId sub-param on the science designer is absent for the empty new-science form and set to the science name for an existing one. Ship-class design is folded into the sidebar ship-class calculator (lib/sidebar/calculator-tab.svelte, see calculator-ux.md), reached from the ship-classes table and the view/bottom menus.

The tableEntity slug is kebab-case (planets, ship-classes, ship-groups, fleets, sciences, races). table.svelte is the table dispatcher: it switches by slug to the per-entity component (ship-classes → table-ship-classes.svelte; other entities dispatch to their respective components).

Screen history: Back/Forward without a URL

Browser Back/Forward move between screens, not views, and they do so without ever changing the URL. The shell layers screen history on top of appScreen via SvelteKit shallow routing: appScreen.go(...) calls pushState("", { screen, gameId }) for the overlay screens (game, lobby-create) and replaceState(...) for lobby / login, so browser Back from a game returns to the lobby beneath it. On the first authenticated render the dispatcher stamps the restored overlay on top of the load entry, then mirrors page.state back into the store on every popstate through appScreen.syncFromHistory(...). The store is the source of truth; history only mirrors it.

In-game view switches do not create history entries — activeView.select(...) only mutates state and persists the snapshot. Back from any in-game view therefore leaves the game entirely rather than stepping through the views the player visited.

A "return to lobby" control lives in the in-game header (lib/header/header.svelte, data-testid="return-to-lobby", label game.shell.menu.return_to_lobby); it calls appScreen.go("lobby").

Refresh and restore

appScreen / activeView persist a snapshot (screen, game id, view + sub-params) to sessionStorage (galaxy-app-nav) on every mutation and read it back once at construction, so a refresh restores the last screen and view. Re-entering a game from the lobby is not a restore: the lobby resets activeView to the map before appScreen.go("game"), so only an in-place refresh replays the saved view — browser Back and the in-game return-to-lobby control both exit to the lobby. On a full load the dispatcher records the restored game id (appScreen.restoredGameId); the game shell's boot path then validates it against the player's game list. GameStateStore.init looks the game up through listMyGames / findGame, and if the game is gone (cancelled, removed, or access revoked) it sets the distinct gameState.notFound flag. The shell reacts by dropping to the lobby (appScreen.go("lobby")) with an game.events.unavailable toast rather than stranding the user on an in-game error. A transient network error keeps notFound false and surfaces the in-game error state instead. See game-state.md for the notFound semantics.

Standalone-target compatibility

The single-URL app-shell is the natural fit for the planned standalone wrappers (Wails desktop, Capacitor / gomobile mobile — see ../ROADMAP.md). Those targets load a single bundled index.html with no server, no per-route URLs, and no browser history to rely on; an in-memory screen/view model and shallow-routing history that never touches the address bar work there unchanged.

Sidebar tools and state preservation

The desktop sidebar hosts three tools:

Tool	Component
Calculator	lib/sidebar/calculator-tab.svelte
Inspector	lib/sidebar/inspector-tab.svelte
Order	lib/sidebar/order-tab.svelte

The selected-tab state is a $state rune in lib/game/game-shell.svelte, bound into lib/sidebar/sidebar.svelte via $bindable(). The shell owns the rune so external events — such as a planet click — can drive the active tab from outside the sidebar without plumbing callbacks. The shell instance lives for the lifetime of the game screen, and an in-game view switch is a pure activeView state change that never remounts the shell, so the rune survives every active-view switch automatically — it is in-memory state, with no URL coupling. The history-mode reset described below lives inside the sidebar — it mutates the bindable in place; the shell sees the change through the binding.

The tool state is pure in-memory rune state. There is no ?sidebar= URL param (the app-shell has no per-screen URL to carry one) and no default-tab URL seed; the shell opens on its inspector default and external events flip the tab.

The Order entry is hidden when the shell's historyMode flag is true. game-shell.svelte forwards a derived value to Sidebar, which forwards hideOrder to its TabBar; the same flag goes to BottomTabs so the mobile Order button is also suppressed. An $effect on the sidebar resets activeTab away from order if the flag flips on mid-session.

The historyMode flag is derived from the live history signal owned by GameStateStore. The derivation lives directly in game-shell.svelte (const historyMode = $derived(gameState.historyMode)) — no separate lib/history-mode.ts module exists, because the shell is the single consumer and the project's compactness rule rejects a one-line indirection. The order draft survives the toggle because OrderDraftStore lives one level above the sidebar in the shell hierarchy; the same historyMode derivation is also fed into OrderDraftStore.bindClient so inspector-driven mutations (add / remove / move) become no-ops while the user is viewing a past turn. See order-composer.md for the draft-store side of the flow and game-state.md for the rune split between currentTurn and viewedTurn.

Header turn navigator and history banner

The header shows a ← Turn N → triplet (lib/header/turn-navigator.svelte). The arrows step viewedTurn by ±1 (disabled at boundaries 0 and currentTurn); clicking the middle button opens an absolute popover (desktop) or a fixed full-width drawer (mobile, ≤ 767.98 px) listing every turn from currentTurn down to 0. Selecting the current-turn row routes through gameState.returnToCurrent(); any other row calls gameState.viewTurn(N). Selecting the row already on screen (viewedTurn) is a pure no-op — it only closes the popover — so re-picking the live turn (most visibly turn 0, where it is the only row) never re-fetches the report to redraw the same snapshot. The popover reuses view-menu.svelte's outside-click / Escape pattern.

lib/header/history-banner.svelte renders directly under the header whenever gameState.historyMode === true. It shows "Viewing turn {N} · read-only" with a "Return to current turn" button that delegates back to gameState.returnToCurrent(). Both the navigator and the banner read gameState through context, so the game shell is the only place where the wiring lives.

Layout breakpoints

Three discrete CSS modes matched to the IA section diagrams:

• ≥ 1024 px (desktop) — the sidebar sits beside the active view and is always rendered. The header view-menu trigger uses the dropdown icon (▾). Bottom-tabs and the tablet sidebar-toggle are CSS-hidden.
• 768–1024 px (tablet) — the sidebar collapses behind a click toggle in the header right corner. Tapping the toggle slides the sidebar in as a fixed overlay above the active view; a close button on the sidebar dismisses it. The full swipe-from-right gesture is deferred to the finalization plan (../PLAN-finalize.md).
• < 768 px (mobile) — the sidebar is hidden entirely and the bottom-tabs row appears at the bottom of the viewport. The view-menu trigger swaps to a hamburger icon (☰) that opens the drop-down as a full-width drawer below the header.

On mobile the bottom tab row does not include Inspector. The inspector content is reached by tapping a map object instead, which raises a bottom-sheet — see Planet selection.

Mobile bottom-tabs and tool overlay

The bottom-tabs row is [Map, Calc, Order, More]. Map selects the map view (activeView.select("map")) and clears any tool overlay. Calc and Order select the map view too — but they also flip the shell's mobileTool state to calc / order, which the shell uses to swap the active-view slot for the Calculator / Order tool component.

The tool overlay only applies while the active view is the map. The shell's derived effectiveTool is gated by activeView.view === "map": selecting any other view through the More drawer or the header view-menu collapses effectiveTool back to map, so the user always sees the active view rather than a stale overlay. The next time the user taps a Calc or Order bottom-tab, the selection switches back to the map view and re-applies the overlay.

The More button opens a drawer that mirrors the header view-menu content. A narrower "More" list (Mail, Battle log, Tables, History, Settings, Logout) is deferred to the finalization plan (../PLAN-finalize.md); the current drawer keeps a single source of truth for destinations.

Transient map overlays

Some views can push a transient overlay onto the map view with a back affordance. (The calculator reach circles are a simpler, always-on map extra rather than a back-stacked overlay; the transient back-stack mechanism is planned — see ../ROADMAP.md.) A transient overlay clears when the user selects any other view via the header or the bottom-tabs.

The back-stack mechanism is not yet implemented; it is planned alongside its first user (multi-turn projection, range circles in the ship-class designer) in ../ROADMAP.md.

Planet selection

The map view is the entry point for the inspector by translating a renderer click into a planet selection. The flow:

1. The renderer (src/map/render.ts) exposes onClick(cb) next to the existing hitAt(cursor). It is built on pixi-viewport's clicked event, which already differentiates a click from a pan-drag, so a click handler will not race the pan plugin.
2. lib/active-view/map.svelte wires that callback after a successful mountRenderer. On a click it asks the renderer for the hit primitive, looks the planet up by number in the live GameStateStore.report, and calls SelectionStore.selectPlanet(number).
3. SelectionStore (lib/selection.svelte.ts) is a runes store instantiated by the game shell and exposed via Svelte context under SELECTION_CONTEXT_KEY. It carries a discriminated union — { kind: "planet"; id: number } for planets and widened for ship groups. Selection is in-memory only: it survives the shell's lifetime (in-memory activeView switches inside the game screen) but does not persist across reloads — that contrast with the order draft is intentional.
4. The shell watches the selection rune and, on the null → planet transition, flips its bound activeTab to inspector and sidebarOpen to true. Desktop already has the sidebar pinned; tablet needs the drawer to surface; mobile is unaffected by the tab rune because the sidebar is CSS-hidden there.
5. lib/sidebar/inspector-tab.svelte and lib/inspectors/planet-sheet.svelte both read the selection store, resolve it against the live report, and either render lib/inspectors/planet.svelte or fall back to the empty state. A selection that points at a planet missing from the current report (visibility lost between turns) collapses to the empty state instead of holding stale rows.

The mobile bottom-sheet is mounted alongside <BottomTabs /> in the game shell. Its visibility is conditional on effectiveTool === "map" so it does not stack on top of the calc / order overlays. The dismissal surface is a close button (✕) that calls SelectionStore.clear(). Tap-outside and swipe-down dismissal are deferred to the finalization plan (../PLAN-finalize.md). A click that lands on empty space is a no-op — selection is mutated only by an explicit planet click or by the close button.

The planet inspector itself is a presentational component: it takes a ReportPlanet snapshot as a prop and renders the documented field set per planet kind. The wrapper in api/game-state.ts exposes every field the FBS schema carries (industryStockpile for capital, materialsStockpile for material, industry, population, colonists, production, freeIndustry, plus owner for other). Fields the FBS table does not project for a given kind read as null and the inspector simply omits the row.

The selected-planet visual on the map (a ring or halo) is deferred to the finalization plan (../PLAN-finalize.md) together with the sheet's swipe-to-dismiss gesture.

Auth gate

The auth gate is state-based, applied by the dispatcher (src/routes/+page.svelte): an anonymous session renders the login screen, an authenticated one renders the appScreen.screen (lobby / game / …). There is no goto("/login") redirect. When a session is revoked while the user is in the game shell, the revocation watcher flips session.status back to anonymous, and the dispatcher swaps the whole tree to the login screen on the next render — the URL stays /game/ throughout. See auth-flow.md for the session state machine.