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/src/sync/order-draft.svelte.ts

@@ -174,12 +174,20 @@ export class OrderDraftStore {
 	 * Mutations made before `init` resolves are ignored — the layout
 	 * always awaits `init` before exposing the store.
 	 *
-	 * `setProductionType` carries a collapse-by-`planetNumber` rule:
-	 * a new entry supersedes any prior `setProductionType` for the
-	 * same planet, so the draft holds at most one production choice
-	 * per planet at any time. Other variants append unconditionally —
-	 * `planetRename` keeps its append-only behaviour because each
-	 * rename is a distinct user-visible action.
+	 * Collapse rules:
+	 *
+	 *   - `setProductionType` collapses by `planetNumber`: a new
+	 *     entry supersedes any prior `setProductionType` for the
+	 *     same planet, so the draft holds at most one production
+	 *     choice per planet.
+	 *   - `setCargoRoute` and `removeCargoRoute` share a collapse
+	 *     key on `(sourcePlanetNumber, loadType)` — the engine
+	 *     stores a single (planet, type) → destination mapping, so
+	 *     a newer entry for the same slot supersedes any prior
+	 *     `set` or `remove` for that slot. Different load-types or
+	 *     different sources coexist.
+	 *   - `planetRename` and `placeholder` append unconditionally;
+	 *     each rename is a distinct user-visible action.
 	 */
 	async add(command: OrderCommand): Promise<void> {
 		if (this.status !== "ready") return;
@@ -198,6 +206,24 @@ export class OrderDraftStore {
 				nextCommands.push(existing);
 			}
 			nextCommands.push(command);
+		} else if (
+			command.kind === "setCargoRoute" ||
+			command.kind === "removeCargoRoute"
+		) {
+			nextCommands = [];
+			for (const existing of this.commands) {
+				if (
+					(existing.kind === "setCargoRoute" ||
+						existing.kind === "removeCargoRoute") &&
+					existing.sourcePlanetNumber === command.sourcePlanetNumber &&
+					existing.loadType === command.loadType
+				) {
+					removed.push(existing.id);
+					continue;
+				}
+				nextCommands.push(existing);
+			}
+			nextCommands.push(command);
 		} else {
 			nextCommands = [...this.commands, command];
 		}
@@ -444,6 +470,23 @@ function validateCommand(cmd: OrderCommand): CommandStatus {
 				return validateEntityName(cmd.subject).ok ? "valid" : "invalid";
 			}
 			return "valid";
+		case "setCargoRoute":
+			// The picker pre-checks reach (and so refuses to emit a
+			// route to an unreachable destination) and the engine
+			// re-validates ownership / reach server-side. Locally we
+			// only refuse a self-route — the FBS validator
+			// (`pkg/model/order/order.go`) accepts every other
+			// (origin, destination, load_type) triple.
+			if (cmd.sourcePlanetNumber === cmd.destinationPlanetNumber) {
+				return "invalid";
+			}
+			return "valid";
+		case "removeCargoRoute":
+			// `removeCargoRoute` carries no destination; the only
+			// engine-side check is ownership of the source planet,
+			// which the inspector enforces by only mounting the
+			// component on `kind === "local"`.
+			return "valid";
 		case "placeholder":
 			// Phase 12 placeholder entries are content-free and never
 			// transition out of `draft` — they are not submittable.

ui/frontend/src/sync/order-load.ts

@@ -14,11 +14,18 @@ import {
 	CommandPayload,
 	CommandPlanetProduce,
 	CommandPlanetRename,
+	CommandPlanetRouteRemove,
+	CommandPlanetRouteSet,
 	PlanetProduction,
+	PlanetRouteLoadType,
 	UserGamesOrderGet,
 	UserGamesOrderGetResponse,
 } from "../proto/galaxy/fbs/order";
-import type { OrderCommand, ProductionType } from "./order-types";
+import type {
+	CargoLoadType,
+	OrderCommand,
+	ProductionType,
+} from "./order-types";
 
 const MESSAGE_TYPE = "user.games.order.get";
 
@@ -155,6 +162,41 @@ function decodeCommand(item: CommandItemView): OrderCommand | null {
 				subject: inner.subject() ?? "",
 			};
 		}
+		case CommandPayload.CommandPlanetRouteSet: {
+			const inner = new CommandPlanetRouteSet();
+			item.payload(inner);
+			const loadType = cargoLoadTypeFromFBS(inner.loadType());
+			if (loadType === null) {
+				console.warn(
+					`fetchOrder: skipping CommandPlanetRouteSet with unknown load_type enum (${inner.loadType()})`,
+				);
+				return null;
+			}
+			return {
+				kind: "setCargoRoute",
+				id,
+				sourcePlanetNumber: Number(inner.origin()),
+				destinationPlanetNumber: Number(inner.destination()),
+				loadType,
+			};
+		}
+		case CommandPayload.CommandPlanetRouteRemove: {
+			const inner = new CommandPlanetRouteRemove();
+			item.payload(inner);
+			const loadType = cargoLoadTypeFromFBS(inner.loadType());
+			if (loadType === null) {
+				console.warn(
+					`fetchOrder: skipping CommandPlanetRouteRemove with unknown load_type enum (${inner.loadType()})`,
+				);
+				return null;
+			}
+			return {
+				kind: "removeCargoRoute",
+				id,
+				sourcePlanetNumber: Number(inner.origin()),
+				loadType,
+			};
+		}
 		default:
 			console.warn(
 				`fetchOrder: skipping unknown command kind (payloadType=${payloadType})`,
@@ -196,6 +238,31 @@ export function productionTypeFromFBS(
 	}
 }
 
+/**
+ * cargoLoadTypeFromFBS reverses `cargoLoadTypeToFBS` from
+ * `submit.ts`. `PlanetRouteLoadType.UNKNOWN` and any out-of-band
+ * value yield `null` so the caller drops the entry rather than
+ * fabricating a synthetic load type.
+ */
+export function cargoLoadTypeFromFBS(
+	value: PlanetRouteLoadType,
+): CargoLoadType | null {
+	switch (value) {
+		case PlanetRouteLoadType.COL:
+			return "COL";
+		case PlanetRouteLoadType.CAP:
+			return "CAP";
+		case PlanetRouteLoadType.MAT:
+			return "MAT";
+		case PlanetRouteLoadType.EMP:
+			return "EMP";
+		case PlanetRouteLoadType.UNKNOWN:
+			return null;
+		default:
+			return null;
+	}
+}
+
 function decodeError(
 	payload: Uint8Array,
 	resultCode: string,

ui/frontend/src/sync/order-types.ts

@@ -84,6 +84,49 @@ export interface SetProductionTypeCommand {
 	readonly subject: string;
 }
 
+/**
+ * CargoLoadType mirrors the engine `PlanetRouteLoadType` enum
+ * (`pkg/schema/fbs/order.fbs`). The values are wire-stable: the
+ * submit encoder maps them to the FBS enum and the read-back
+ * decoder maps them back. The four members enumerate the four
+ * mutually-exclusive cargo-route slots a planet can drive at any
+ * one time.
+ *
+ *   `COL` — colonists (highest priority on load),
+ *   `CAP` — capital / industry crates,
+ *   `MAT` — raw materials,
+ *   `EMP` — empty ships returning to a producer.
+ */
+export type CargoLoadType = "COL" | "CAP" | "MAT" | "EMP";
+
+/**
+ * SetCargoRouteCommand binds a (source, loadType) slot to a
+ * destination planet. Phase 16 carries a collapse-by-(source,
+ * loadType) rule: at most one entry per slot lives in the draft at
+ * any time. A `removeCargoRoute` for the same slot supersedes a
+ * pending set (the engine accepts either order, but keeping the
+ * draft minimal avoids confusing the order tab).
+ */
+export interface SetCargoRouteCommand {
+	readonly kind: "setCargoRoute";
+	readonly id: string;
+	readonly sourcePlanetNumber: number;
+	readonly destinationPlanetNumber: number;
+	readonly loadType: CargoLoadType;
+}
+
+/**
+ * RemoveCargoRouteCommand drops the (source, loadType) slot. Same
+ * collapse rule as `SetCargoRouteCommand` — a later `set` for the
+ * same slot supersedes the remove, and vice versa.
+ */
+export interface RemoveCargoRouteCommand {
+	readonly kind: "removeCargoRoute";
+	readonly id: string;
+	readonly sourcePlanetNumber: number;
+	readonly loadType: CargoLoadType;
+}
+
 /**
  * OrderCommand is the discriminated union of every command shape the
  * local order draft can hold. The `kind` field is the discriminator;
@@ -93,7 +136,9 @@ export interface SetProductionTypeCommand {
 export type OrderCommand =
 	| PlaceholderCommand
 	| PlanetRenameCommand
-	| SetProductionTypeCommand;
+	| SetProductionTypeCommand
+	| SetCargoRouteCommand
+	| RemoveCargoRouteCommand;
 
 /**
  * PRODUCTION_TYPE_VALUES is the canonical tuple of `ProductionType`
@@ -120,6 +165,31 @@ export function isProductionType(value: string): value is ProductionType {
 	return (PRODUCTION_TYPE_VALUES as readonly string[]).includes(value);
 }
 
+/**
+ * CARGO_LOAD_TYPE_VALUES is the canonical tuple of `CargoLoadType`
+ * literals in turn-cutoff priority order
+ * (`game/internal/controller/route.go.SendRoutedGroups`):
+ * colonists first, then capital, then materials, then empty ships.
+ * The inspector renders slots in this order so visual order
+ * matches engine behaviour. Used by validators and by the FBS
+ * converters in `submit.ts` and `order-load.ts`.
+ */
+export const CARGO_LOAD_TYPE_VALUES = [
+	"COL",
+	"CAP",
+	"MAT",
+	"EMP",
+] as const satisfies readonly CargoLoadType[];
+
+/**
+ * isCargoLoadType narrows an arbitrary string to the
+ * `CargoLoadType` union. The decoder uses this when the engine
+ * report's `RouteEntry.value` carries the load-type string.
+ */
+export function isCargoLoadType(value: string): value is CargoLoadType {
+	return (CARGO_LOAD_TYPE_VALUES as readonly string[]).includes(value);
+}
+
 /**
  * CommandStatus is the lifecycle of a single command from the moment
  * it lands in the draft to the moment the server resolves it. The

ui/frontend/src/sync/submit.ts

@@ -29,11 +29,18 @@ import {
 	CommandPayload,
 	CommandPlanetProduce,
 	CommandPlanetRename,
+	CommandPlanetRouteRemove,
+	CommandPlanetRouteSet,
 	PlanetProduction,
+	PlanetRouteLoadType,
 	UserGamesOrder,
 	UserGamesOrderResponse,
 } from "../proto/galaxy/fbs/order";
-import type { OrderCommand, ProductionType } from "./order-types";
+import type {
+	CargoLoadType,
+	OrderCommand,
+	ProductionType,
+} from "./order-types";
 
 const MESSAGE_TYPE = "user.games.order";
 
@@ -163,6 +170,29 @@ function encodeCommandPayload(
 				payloadOffset: offset,
 			};
 		}
+		case "setCargoRoute": {
+			const offset = CommandPlanetRouteSet.createCommandPlanetRouteSet(
+				builder,
+				BigInt(cmd.sourcePlanetNumber),
+				BigInt(cmd.destinationPlanetNumber),
+				cargoLoadTypeToFBS(cmd.loadType),
+			);
+			return {
+				payloadType: CommandPayload.CommandPlanetRouteSet,
+				payloadOffset: offset,
+			};
+		}
+		case "removeCargoRoute": {
+			const offset = CommandPlanetRouteRemove.createCommandPlanetRouteRemove(
+				builder,
+				BigInt(cmd.sourcePlanetNumber),
+				cargoLoadTypeToFBS(cmd.loadType),
+			);
+			return {
+				payloadType: CommandPayload.CommandPlanetRouteRemove,
+				payloadOffset: offset,
+			};
+		}
 		case "placeholder":
 			throw new SubmitError(
 				"invalid_request",
@@ -200,6 +230,24 @@ export function productionTypeToFBS(value: ProductionType): PlanetProduction {
 	}
 }
 
+/**
+ * cargoLoadTypeToFBS converts the wire-stable `CargoLoadType` literal
+ * to the FlatBuffers enum value. Mirrors the engine
+ * `PlanetRouteLoadType` enum (`pkg/schema/fbs/order.fbs`).
+ */
+export function cargoLoadTypeToFBS(value: CargoLoadType): PlanetRouteLoadType {
+	switch (value) {
+		case "COL":
+			return PlanetRouteLoadType.COL;
+		case "CAP":
+			return PlanetRouteLoadType.CAP;
+		case "MAT":
+			return PlanetRouteLoadType.MAT;
+		case "EMP":
+			return PlanetRouteLoadType.EMP;
+	}
+}
+
 function decodeOrderResponse(
 	payload: Uint8Array,
 	commands: OrderCommand[],