ui/phase-16: cargo routes inspector + map pick foundation

Add per-planet cargo routes (COL/CAP/MAT/EMP) to the inspector with
a renderer-driven destination picker (faded out-of-reach planets,
cursor-line anchor, hover-highlight) and per-route arrows on the
map. The pick-mode primitives are exposed via `MapPickService` so
ship-group dispatch in Phase 19/20 can reuse the same surface.

Pass A — generic map foundation:
- hit-test now sizes the click zone to `pointRadiusPx + slopPx` so
  the visible disc is always part of the target.
- `RendererHandle` gains `onPointerMove`, `onHoverChange`,
  `setPickMode`, `getPickState`, `getPrimitiveAlpha`,
  `setExtraPrimitives`, `getPrimitives`. The click dispatcher is
  centralised: pick-mode swallows clicks atomically so the standard
  selection consumers do not race against teardown.
- `MapPickService` (`lib/map-pick.svelte.ts`) wraps the renderer
  contract in a promise-shaped `pick(...)`. The in-game shell
  layout owns the service so sidebar and bottom-sheet inspectors
  see the same instance.
- Debug-surface registry exposes `getMapPrimitives`,
  `getMapPickState`, `getMapCamera` to e2e specs without spawning a
  separate debug page after navigation.

Pass B — cargo-route feature:
- `CargoLoadType`, `setCargoRoute`, `removeCargoRoute` typed
  variants with `(source, loadType)` collapse rule on the order
  draft; round-trip through the FBS encoder/decoder.
- `GameReport` decodes `routes` and the local player's drive tech
  for the inline reach formula (40 × drive). `applyOrderOverlay`
  upserts/drops route entries for valid/submitting/applied
  commands.
- `lib/inspectors/planet/cargo-routes.svelte` renders the
  four-slot section. `Add` / `Edit` call `MapPickService.pick`,
  `Remove` emits `removeCargoRoute`.
- `map/cargo-routes.ts` builds shaft + arrowhead primitives per
  cargo type; the map view pushes them through
  `setExtraPrimitives` so the renderer never re-inits Pixi on
  route mutations (Pixi 8 doesn't support that on a reused
  canvas).

Docs:
- `docs/cargo-routes-ux.md` covers engine semantics + UI map.
- `docs/renderer.md` documents pick mode and the debug surface.
- `docs/calc-bridge.md` records the Phase 16 reach waiver.
- `PLAN.md` rewrites Phase 16 to reflect the foundation + feature
  split and the decisions baked in (map-driven picker, inline
  reach, optimistic overlay via `setExtraPrimitives`).

Tests:
- `tests/map-pick-mode.test.ts` — pure overlay-spec helper.
- `tests/map-cargo-routes.test.ts` — `buildCargoRouteLines`.
- `tests/inspector-planet-cargo-routes.test.ts` — slot rendering,
  picker invocation, collapse, cancel, remove.
- Extensions to `order-draft`, `submit`, `order-load`,
  `order-overlay`, `state-binding`, `inspector-planet`,
  `inspector-overlay`, `game-shell-sidebar`, `game-shell-header`.
- `tests/e2e/cargo-routes.spec.ts` — Playwright happy path: add
  COL, add CAP, remove COL, asserting both the inspector and the
  arrow count via `__galaxyDebug.getMapPrimitives()`.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

ui/frontend/tests/e2e/fixtures/order-fbs.ts

@@ -14,7 +14,10 @@ import {
 	CommandPayload,
 	CommandPlanetProduce,
 	CommandPlanetRename,
+	CommandPlanetRouteRemove,
+	CommandPlanetRouteSet,
 	PlanetProduction,
+	PlanetRouteLoadType,
 	UserGamesOrder,
 	UserGamesOrderGetResponse,
 	UserGamesOrderResponse,
@@ -48,9 +51,25 @@ export interface SetProductionTypeResultFixture
 	subject: string;
 }
 
+export interface SetCargoRouteResultFixture extends CommandResultFixtureBase {
+	kind: "setCargoRoute";
+	sourcePlanetNumber: number;
+	destinationPlanetNumber: number;
+	loadType: "COL" | "CAP" | "MAT" | "EMP";
+}
+
+export interface RemoveCargoRouteResultFixture
+	extends CommandResultFixtureBase {
+	kind: "removeCargoRoute";
+	sourcePlanetNumber: number;
+	loadType: "COL" | "CAP" | "MAT" | "EMP";
+}
+
 export type CommandResultFixture =
 	| PlanetRenameResultFixture
-	| SetProductionTypeResultFixture;
+	| SetProductionTypeResultFixture
+	| SetCargoRouteResultFixture
+	| RemoveCargoRouteResultFixture;
 
 export function buildOrderResponsePayload(
 	gameId: string,
@@ -135,6 +154,25 @@ function encodeItem(builder: Builder, c: CommandResultFixture): number {
 			payloadType = CommandPayload.CommandPlanetProduce;
 			break;
 		}
+		case "setCargoRoute": {
+			inner = CommandPlanetRouteSet.createCommandPlanetRouteSet(
+				builder,
+				BigInt(c.sourcePlanetNumber),
+				BigInt(c.destinationPlanetNumber),
+				cargoLoadTypeToFBS(c.loadType),
+			);
+			payloadType = CommandPayload.CommandPlanetRouteSet;
+			break;
+		}
+		case "removeCargoRoute": {
+			inner = CommandPlanetRouteRemove.createCommandPlanetRouteRemove(
+				builder,
+				BigInt(c.sourcePlanetNumber),
+				cargoLoadTypeToFBS(c.loadType),
+			);
+			payloadType = CommandPayload.CommandPlanetRouteRemove;
+			break;
+		}
 	}
 	CommandItem.startCommandItem(builder);
 	CommandItem.addCmdId(builder, cmdIdOffset);
@@ -169,3 +207,18 @@ function productionTypeToFBS(
 			return PlanetProduction.SHIP;
 	}
 }
+
+function cargoLoadTypeToFBS(
+	value: SetCargoRouteResultFixture["loadType"],
+): PlanetRouteLoadType {
+	switch (value) {
+		case "COL":
+			return PlanetRouteLoadType.COL;
+		case "CAP":
+			return PlanetRouteLoadType.CAP;
+		case "MAT":
+			return PlanetRouteLoadType.MAT;
+		case "EMP":
+			return PlanetRouteLoadType.EMP;
+	}
+}

ui/frontend/tests/e2e/fixtures/report-fbs.ts

@@ -19,7 +19,10 @@ import { Builder } from "flatbuffers";
 import {
 	LocalPlanet,
 	OtherPlanet,
+	Player,
 	Report,
+	Route,
+	RouteEntry,
 	ShipClass,
 	UnidentifiedPlanet,
 	UninhabitedPlanet,
@@ -52,6 +55,21 @@ export interface ShipClassFixture {
 	name: string;
 }
 
+export interface PlayerFixture {
+	name: string;
+	drive?: number;
+}
+
+export interface RouteEntryFixture {
+	loadType: "COL" | "CAP" | "MAT" | "EMP";
+	destinationPlanetNumber: number;
+}
+
+export interface RouteFixture {
+	sourcePlanetNumber: number;
+	entries: RouteEntryFixture[];
+}
+
 export interface ReportFixture {
 	turn: number;
 	mapWidth?: number;
@@ -61,6 +79,9 @@ export interface ReportFixture {
 	uninhabitedPlanets?: PlanetFixture[];
 	unidentifiedPlanets?: { number: number; x: number; y: number }[];
 	localShipClass?: ShipClassFixture[];
+	race?: string;
+	players?: PlayerFixture[];
+	routes?: RouteFixture[];
 }
 
 export function buildReportPayload(fixture: ReportFixture): Uint8Array {
@@ -147,6 +168,29 @@ export function buildReportPayload(fixture: ReportFixture): Uint8Array {
 		return ShipClass.endShipClass(builder);
 	});
 
+	const playerOffsets = (fixture.players ?? []).map((p) => {
+		const name = builder.createString(p.name);
+		Player.startPlayer(builder);
+		Player.addName(builder, name);
+		Player.addDrive(builder, p.drive ?? 1);
+		return Player.endPlayer(builder);
+	});
+
+	const routeOffsets = (fixture.routes ?? []).map((route) => {
+		const entryOffsets = route.entries.map((entry) => {
+			const valueOffset = builder.createString(entry.loadType);
+			RouteEntry.startRouteEntry(builder);
+			RouteEntry.addKey(builder, BigInt(entry.destinationPlanetNumber));
+			RouteEntry.addValue(builder, valueOffset);
+			return RouteEntry.endRouteEntry(builder);
+		});
+		const entriesVec = Route.createRouteVector(builder, entryOffsets);
+		Route.startRoute(builder);
+		Route.addPlanet(builder, BigInt(route.sourcePlanetNumber));
+		Route.addRoute(builder, entriesVec);
+		return Route.endRoute(builder);
+	});
+
 	const localVec =
 		localOffsets.length === 0
 			? null
@@ -167,6 +211,16 @@ export function buildReportPayload(fixture: ReportFixture): Uint8Array {
 		localShipClassOffsets.length === 0
 			? null
 			: Report.createLocalShipClassVector(builder, localShipClassOffsets);
+	const playerVec =
+		playerOffsets.length === 0
+			? null
+			: Report.createPlayerVector(builder, playerOffsets);
+	const routeVec =
+		routeOffsets.length === 0
+			? null
+			: Report.createRouteVector(builder, routeOffsets);
+	const raceOffset =
+		fixture.race === undefined ? null : builder.createString(fixture.race);
 
 	const totalPlanets =
 		(fixture.localPlanets ?? []).length +
@@ -179,12 +233,15 @@ export function buildReportPayload(fixture: ReportFixture): Uint8Array {
 	Report.addWidth(builder, fixture.mapWidth ?? 4000);
 	Report.addHeight(builder, fixture.mapHeight ?? 4000);
 	Report.addPlanetCount(builder, totalPlanets);
+	if (raceOffset !== null) Report.addRace(builder, raceOffset);
+	if (playerVec !== null) Report.addPlayer(builder, playerVec);
 	if (localVec !== null) Report.addLocalPlanet(builder, localVec);
 	if (otherVec !== null) Report.addOtherPlanet(builder, otherVec);
 	if (uninhabitedVec !== null) Report.addUninhabitedPlanet(builder, uninhabitedVec);
 	if (unidentifiedVec !== null) Report.addUnidentifiedPlanet(builder, unidentifiedVec);
 	if (localShipClassVec !== null)
 		Report.addLocalShipClass(builder, localShipClassVec);
+	if (routeVec !== null) Report.addRoute(builder, routeVec);
 	const reportOff = Report.endReport(builder);
 	builder.finish(reportOff);
 	return builder.asUint8Array();