galaxy-game/ui/docs/cargo-routes-ux.md

Cargo routes UX

This document covers the cargo-route surface added in Phase 16: the four-slot inspector subsection, the map-driven destination pick, and the optimistic overlay that keeps the inspector and the map in lock- step with the local order draft. The user-visible spec lives in ../PLAN.md Phase 16; the engine semantics are quoted from game/rules.txt section "Грузовые маршруты" (lines 808–843); this file is the source of truth for how the UI surfaces those rules.

Engine semantics in one paragraph

A cargo route on a planet you own pairs a load-type slot (COL/CAP/MAT/EMP) with a destination planet. Once set, the engine loads transport ships at the source on every turn cutoff and sends them to the destination, draining the load-type stockpile ("colonists" → population pool, "capital" → industry crates, "mat" → raw materials, "empty" → ships returning unloaded). When several slots are configured the engine processes them in COL > CAP > MAT > EMP priority order (game/internal/controller/route.go.SendRoutedGroups, line 101). Routes are constrained by reach: the destination must be no further than 40 × driveTech world units along the torus-shortest path (util.ShortDistance ≤ Race.FlightDistance()), and a route whose destination becomes unreachable at the next turn is auto-removed (RemoveUnreachableRoutes).

Four-slot inspector subsection

The cargo-routes subsection renders below the production controls on every owned planet inspector. Slots appear in CARGO_LOAD_TYPE_VALUES order (COL, CAP, MAT, EMP) so visual order matches the engine's load priority — players who scan top-down see the highest-priority cargo first.

Slot states:

• Empty — (no route) text plus a single Add button.
• Filled — → {destination name} plus Edit and Remove.

Add and Edit open a renderer-driven destination pick (see next section). Remove emits a removeCargoRoute command. The collapse rule on the order draft store ensures only one entry per (source, loadType) slot survives in the draft at any time, so a sequence of Add → Edit → Remove collapses to the latest verb only (matching the production-controls pattern from Phase 15).

Disabled state: every button is disabled when the OrderDraftStore or MapPickService context is missing (the component is mounted outside the in-game shell, in tests, etc.).

Map-driven destination pick

The picker is renderer-side: the inspector calls MapPickService.pick({sourcePlanetNumber, reachableIds}) and awaits a planet number (or null on cancel). Reach is computed inline against localPlayerDrive — see the calc-bridge waiver in calc-bridge.md.

While a session is active:

• All planets whose ids are not in reachableIds and are not the source render at alpha = 0.3. The visual fade signals "not a valid destination" without removing the planet from the map.
• The source planet keeps full alpha and gains an outline ring so the player sees where the route originates.
• A line is drawn from the source to the cursor. On touch devices the line follows the finger during drag.
• Hover over a reachable planet adds an outline highlight at pointRadiusPx + 4 world units so the player can confirm which planet they are about to pick.

Resolution paths:

• Click on a reachable planet → setCargoRoute enters the draft; the inspector slot fills; the arrow appears immediately on the map (overlay route applied on the next render).
• Click on empty space or a non-reachable planet → no-op (a forgiving rule for accidental taps mid-pan).
• Press Escape, click the inspector's Cancel pick button, or unmount the active map view (e.g. switch tools, navigate away) → session cancels; the slot stays as it was.

The inspector renders an inline status line pick a destination on the map (Esc to cancel) while the session is active so the player knows the click target and the cancel hotkey. The line vanishes as soon as the picker resolves.

Optimistic map overlay

applyOrderOverlay projects every locally-valid, in-flight, or applied setCargoRoute / removeCargoRoute onto report.routes, re-runs reportToWorld (which appends LinePrim arrows from buildCargoRouteLines), and remounts the renderer when the routes- content fingerprint changes. The map active view captures camera centre + zoom before each remount and restores them when the game id is unchanged, so adding a route mid-pan does not jolt the view.

Arrows are drawn as a shaft plus two short arrowhead wings. Per-type styling (placeholder Phase 16 colours; final values land in Phase 35 polish):

Load type	Stroke colour	Notes
COL	#4FC3F7	brightest blue, highest priority
CAP	#FFB74D	warm orange
MAT	#81C784	green
EMP	#90A4AE	dim grey, thinner stroke

Arrow priority (COL=8, CAP=7, MAT=6, EMP=5) sits above all planet priorities (1..4), so two arrows that overlap exactly resolve to the higher-priority load type during hit-test. Planet primitives still win over arrows because the line ids carry a high-bit prefix (0x80000000) and the renderer keeps points at the kind tie-break position 0.

Reach computation

Implementation: inline TypeScript using torusShortestDelta for each axis and Math.hypot for the distance, compared against 40 × localPlayerDrive. The local player's drive comes from the report's Player block, looked up by name === report.race (api/game-state.ts.findLocalPlayerDrive).

Why inline rather than via a Go calc bridge? See the Phase 15 / 16 deferral note in calc-bridge.md. The formula is trivial (tech × 40) and the WASM glue would be premature infrastructure; when the calc bridge phase lands the shared pkg/calc.Reach will replace this implementation.

Tests

Layer	File	What it covers
Order draft collapse	tests/order-draft.test.ts	(source, loadType) collapse rules across set and remove.
Encode / decode round-trip	tests/submit.test.ts, tests/order-load.test.ts	setCargoRoute and removeCargoRoute ↔ FBS payloads; UNKNOWN load-type drops with a warn.
Overlay	tests/order-overlay.test.ts	applyOrderOverlay upserts / drops route entries for valid / submitting / applied statuses.
Inspector subsection	tests/inspector-planet-cargo-routes.test.ts	Slot rendering, pick invocation, emit, cancel, edit, remove, per-type independence.
Map arrows	tests/map-cargo-routes.test.ts	buildCargoRouteLines shape on torus + no-wrap fixtures, per-type style, priority ordering.
End-to-end	tests/e2e/cargo-routes.spec.ts	Mocked gateway: open inspector, dim outside reach, pick destination, arrow appears, reload.

File index

• ui/frontend/src/lib/inspectors/planet/cargo-routes.svelte — inspector subsection.
• ui/frontend/src/sync/order-types.ts — CargoLoadType, SetCargoRouteCommand, RemoveCargoRouteCommand.
• ui/frontend/src/sync/order-draft.svelte.ts — collapse rule.
• ui/frontend/src/sync/submit.ts — encoder.
• ui/frontend/src/sync/order-load.ts — decoder.
• ui/frontend/src/api/game-state.ts — routes and localPlayerDrive decoding plus overlay extension.
• ui/frontend/src/map/cargo-routes.ts — arrow geometry.
• ui/frontend/src/map/state-binding.ts — appends route lines.
• ui/frontend/src/lib/active-view/map.svelte — fingerprint guard
  • camera preservation.
• ui/frontend/src/map/pick-mode.ts and ui/frontend/src/map/render.ts — pick-mode foundation.
• ui/frontend/src/lib/map-pick.svelte.ts — Svelte adapter.
• ui/docs/renderer.md — pick-mode and debug-surface contract.