galaxy-game/ui/docs/report-view.md

Report view

The in-game "turn report" view is a single scrollable layout with twenty sections, one per array on the FBS Report table. The route file is the standard two-line wrapper; the orchestrator and the per-section components live under ui/frontend/src/lib/active-view/report/.

Component layout

lib/active-view/report.svelte is the orchestrator. It owns the section list, instantiates IntersectionObserver to track which section is active, and renders the table of contents alongside the section column.

report.svelte
├── report/report-toc.svelte           // anchor list + mobile <select>
├── report/section-galaxy-summary.svelte
├── report/section-votes.svelte
├── report/section-player-status.svelte
├── report/section-my-sciences.svelte
├── report/section-foreign-sciences.svelte
├── report/section-my-ship-classes.svelte
├── report/section-foreign-ship-classes.svelte
├── report/section-battles.svelte
├── report/section-bombings.svelte
├── report/section-approaching-groups.svelte
├── report/section-my-planets.svelte
├── report/section-ships-in-production.svelte
├── report/section-cargo-routes.svelte
├── report/section-foreign-planets.svelte
├── report/section-uninhabited-planets.svelte
├── report/section-unknown-planets.svelte
├── report/section-my-fleets.svelte
├── report/section-my-ship-groups.svelte
├── report/section-foreign-ship-groups.svelte
└── report/section-unidentified-groups.svelte

Each section component is self-contained:

• reads RenderedReportSource from context;
• renders the loading copy when rendered.report === null;
• renders the empty-state copy when its array is empty;
• otherwise emits a <section id="report-<slug>" data-testid="report-section-<slug>"> containing the relevant grid / list / kv-list.

No shared <Section> wrapper exists. The visual scaffolding (dark grid CSS, header style, status paragraph) is inlined per component. The CLAUDE.md "wait for the third real caller before extracting an abstraction" rule applies; with one shape per section, the per-section inline CSS is the smallest correct solution.

Shared formatters live in report/format.ts (formatPercent, formatCount, formatFloat, formatVotes, planetLabel).

Section order, data sources, empty copy

#	Slug	Data	Empty copy (en)
1	galaxy-summary	header turn / size / planet count / race	never empty
2	votes	myVotes, myVoteFor, races[].votesReceived	"no votes cast yet"
3	player-status	players[] (full roster, self + extinct)	never empty
4	my-sciences	localScience[]	"no sciences defined yet"
5	foreign-sciences	otherScience[], one sub-table per race	"no foreign sciences observed yet"
6	my-ship-classes	localShipClass[]	"no ship classes designed yet"
7	foreign-ship-classes	otherShipClass[], one sub-table per race	"no foreign ship classes observed yet"
8	battles	battleIds[] (inactive monospace spans)	"no battles last turn"
9	bombings	bombings[], wiped rows visually distinct	"no bombings last turn"
10	approaching-groups	incomingShipGroups[]	"no approaching groups"
11	my-planets	planets.filter(kind==="local")	"no planets owned yet"
12	ships-in-production	shipProductions[]	"no ships in production"
13	cargo-routes	routes[] (flattened to one row per entry)	"no cargo routes set"
14	foreign-planets	planets.filter(kind==="other")	"no foreign planets observed"
15	uninhabited-planets	planets.filter(kind==="uninhabited")	"no uninhabited planets observed"
16	unknown-planets	planets.filter(kind==="unidentified")	"no unknown planets"
17	my-fleets	localFleets[]	"no fleets created yet"
18	my-ship-groups	localShipGroups[]	"no ship groups yet"
19	foreign-ship-groups	otherShipGroups[]	"no foreign ship groups observed"
20	unidentified-groups	unidentifiedShipGroups[]	"no unidentified groups"

The orchestrator iterates this list once for the TOC and once for the body — both surfaces stay in sync by construction.

Table of contents and active highlight

report/report-toc.svelte renders two surfaces driven by the same entry list:

• Desktop / tablet sidebar — sticky <aside> with vertical anchor list. The anchor for the currently-visible section gets aria-current="location" and an .active CSS class.
• Mobile (< 768 px) — the desktop sidebar is hidden via CSS and a sticky <select> takes its place at the top of the body. Picking an option scrolls the matching section into view. The mobile contract intentionally avoids stacking another overlay on top of the existing layout-owned bottom-tabs.

Both surfaces also expose a "Back to map" affordance (report-back-to-map) at the top.

The active slug is computed by an IntersectionObserver rooted on the viewport (root: null) with rootMargin: "-30% 0px -60% 0px". The skew biases the active band toward the upper third of the visible area so that scrolling down advances the highlight naturally. The observer is created on mount and torn down on unmount.

The in-game shell layout (routes/games/[id]/+layout.svelte) expands <main class="active-view-host"> to fit content rather than constraining it, so the document body is the actual scroll container — not the host. The IntersectionObserver root is null to match.

Scroll save / restore

routes/games/[id]/report/+page.svelte exports a SvelteKit Snapshot<{ scrollY: number }>:

• capture() reads window.scrollY when SvelteKit's beforeNavigate cycle runs.
• restore(value) schedules a short requestAnimationFrame poll that waits for document.documentElement.scrollHeight to grow tall enough to honour the saved offset, then calls window.scrollTo(0, value). The poll caps at ~60 frames (≈ 1 second) so a never-tall-enough body never pins a frame loop.

The capture / restore pair is keyed by route, so:

• Forward navigation from /report to /map lands /map at scrollY 0 (no snapshot for /map to restore from).
• History-back from /map to /report restores the previously captured scrollY — the user returns to the same section.

The Snapshot API does not capture the active sidebar slug; the IntersectionObserver re-derives it from the restored scroll position on the next animation frame, which keeps the TOC highlight consistent without a second source of truth.

i18n namespace

All strings live under game.report.*:

• game.report.loading — section loading placeholder.
• game.report.back_to_map, game.report.toc.title, game.report.toc.mobile_label — shell-level strings.
• game.report.section.<slug>.title — section heading.
• game.report.section.<slug>.empty — empty-state copy (where applicable).
• game.report.section.<slug>.column.<column> — column headings.
• A small number of section-specific keys (bombings.wiped, player_status.local_marker, player_status.extinct_marker, foreign_sciences.race_header, foreign_ship_classes.race_header, battles.id_label, votes.target_none).

The namespace is intentionally separate from game.table.* even where the data shape overlaps (e.g. sciences, ship classes); the two surfaces evolve independently and a shared key set would couple them silently.

Test seams

• Vitest — four representative specs cover the four section shapes: kv-list (report-section-galaxy-summary.test.ts), grid with conditional row state (report-section-bombings.test.ts), per-race sub-table (report-section-foreign-sciences.test.ts), TOC (report-toc.test.ts). Each spec mounts the component against a synthetic RenderedReportSource, so the orchestrator / IntersectionObserver are out of scope.
• Playwright — tests/e2e/report-sections.spec.ts exercises the full integration: every TOC anchor lands its section in view, the snapshot mechanism preserves window.scrollY on history navigation, the back-to-map button reaches /map, the mobile <select> scrolls to the chosen section on a narrow viewport.

Test IDs follow the pattern report-section-<slug> for section roots, report-toc-<slug> for TOC anchors, and per-section row identifiers (e.g. report-bombing-row, my-planets-row).