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/lib/map-pick.svelte.ts

@@ -0,0 +1,133 @@
+// `MapPickService` is the Svelte-side adapter the inspector uses to
+// drive a map-driven destination pick. The service owns the
+// promise-shaped contract (`pick()` returns the picked planet
+// number or `null` on cancel) and a reactive `active` flag for any
+// surface that wants to disable other UI while a session is open.
+//
+// The actual renderer plumbing — dim outside `reachableIds`, anchor
+// ring, cursor line, hover outline, click + Escape resolution —
+// lives in `ui/frontend/src/map/render.ts.setPickMode`. The map
+// active view (`lib/active-view/map.svelte`) is the only producer:
+// it constructs the service, sets it on the layout context with
+// `MAP_PICK_CONTEXT_KEY`, and binds a resolver that translates the
+// service-level request into a `PickModeOptions` payload for the
+// current renderer handle.
+
+export const MAP_PICK_CONTEXT_KEY = Symbol("map-pick");
+
+/** High-level pick request the inspector composes. The renderer
+ * resolver (registered by the map view) is responsible for turning
+ * `sourcePlanetNumber` into the underlying `PickModeOptions`. */
+export interface MapPickRequest {
+	readonly sourcePlanetNumber: number;
+	readonly reachableIds: ReadonlySet<number>;
+}
+
+/** A renderer-side resolver registered by the map view. Returns an
+ * imperative cancel hook the service uses for `cancel()`, or `null`
+ * when the renderer cannot open a session right now (e.g. the
+ * source planet is missing from the world). When `null` is
+ * returned, the service resolves the pending promise with `null`
+ * straight away. */
+export type MapPickResolver = (input: {
+	sourcePlanetNumber: number;
+	reachableIds: ReadonlySet<number>;
+	onResolve: (id: number | null) => void;
+}) => { cancel(): void } | null;
+
+/**
+ * MapPickService coordinates pick-mode sessions between the Svelte
+ * inspector and the renderer. Lives for the lifetime of the
+ * in-game shell layout; renderer handles come and go through
+ * `bindResolver` as the map remounts.
+ */
+export class MapPickService {
+	/** Reactive flag — true while a pick session is open. The
+	 * inspector reads this to render its "pick prompt" status line
+	 * and to keep the slot button disabled until resolution. */
+	active = $state(false);
+
+	private resolver: MapPickResolver | null = null;
+	private currentHandle: { cancel(): void } | null = null;
+	private currentResolve: ((id: number | null) => void) | null = null;
+
+	/**
+	 * bindResolver attaches a renderer-side handler that opens
+	 * pick-mode sessions. Pass `null` to detach (the map view does
+	 * this on dispose); a detach with a session in progress
+	 * resolves the pending promise with `null` so callers do not
+	 * deadlock waiting for a renderer that no longer exists.
+	 */
+	bindResolver(resolver: MapPickResolver | null): void {
+		if (resolver === null && this.currentResolve !== null) {
+			const r = this.currentResolve;
+			this.currentResolve = null;
+			this.currentHandle = null;
+			this.active = false;
+			r(null);
+		}
+		this.resolver = resolver;
+	}
+
+	/**
+	 * pick opens a pick session. Resolves to the picked planet
+	 * number on a successful pick, or `null` when the player
+	 * cancels via Escape, the inspector calls `cancel()`, or the
+	 * renderer detaches mid-session.
+	 *
+	 * Calling `pick` while a session is already active cancels the
+	 * old one first (its promise resolves to `null`). The
+	 * inspector should normally guard against this via the
+	 * reactive `active` flag, but the service stays defensive.
+	 */
+	pick(request: MapPickRequest): Promise<number | null> {
+		return new Promise((resolve) => {
+			if (this.resolver === null) {
+				resolve(null);
+				return;
+			}
+			if (this.currentHandle !== null) {
+				const previousHandle = this.currentHandle;
+				this.currentHandle = null;
+				previousHandle.cancel();
+			}
+			this.currentResolve = resolve;
+			this.active = true;
+			const handle = this.resolver({
+				sourcePlanetNumber: request.sourcePlanetNumber,
+				reachableIds: request.reachableIds,
+				onResolve: (id) => {
+					// Guard against late notifications from a stale
+					// session (e.g. resolver swapped while a pick was
+					// in flight).
+					if (this.currentResolve !== resolve) return;
+					this.currentResolve = null;
+					this.currentHandle = null;
+					this.active = false;
+					resolve(id);
+				},
+			});
+			if (handle === null) {
+				if (this.currentResolve === resolve) {
+					this.currentResolve = null;
+					this.active = false;
+					resolve(null);
+				}
+				return;
+			}
+			this.currentHandle = handle;
+		});
+	}
+
+	/**
+	 * cancel terminates the active session, if any. Safe to call
+	 * when no session is open — it is a no-op then. The pending
+	 * promise resolves with `null`.
+	 */
+	cancel(): void {
+		if (this.currentHandle === null) return;
+		const handle = this.currentHandle;
+		this.currentHandle = null;
+		handle.cancel();
+	}
+}