ui/phase-19: ship-group decoder + map binding + selection store

Wires Phase 19's data and rendering layers without yet adding the
inspector UI:

  - game-state.ts grows ReportLocalShipGroup / ReportOtherShipGroup
    / ReportIncomingShipGroup / ReportUnidentifiedShipGroup /
    ReportLocalFleet types and walks the matching FlatBuffers
    vectors (LocalGroup, OtherGroup, IncomingGroup,
    UnidentifiedGroup, LocalFleet) inside decodeReport. The Tech
    map is folded into the fixed-shape ShipGroupTech struct;
    cargo strings normalise to the closed CargoLoadType | "NONE"
    union; UUIDs come back as canonical 36-char strings.
  - synthetic-report.ts mirrors the new fields so the DEV-only
    lobby loader can feed JSON produced by legacy-report-to-json
    straight into the live UI surface.
  - selection.svelte.ts widens its discriminated union with a
    `kind: "shipGroup"` branch carrying a ShipGroupRef
    (local UUID / other / incoming / unidentified by index).
  - world.ts adds Style.strokeDashPx and render.ts.drawLine
    honours it via manual segmentation (PixiJS v8 has no native
    dash API). Ignored on points and circles.
  - state-binding.ts now returns { world, hitLookup }: the
    hit-lookup map keys every primitive id back to a concrete
    HitTarget so the click handler can dispatch to selectPlanet
    or selectShipGroup. Ship-group primitives live in a separate
    ship-groups.ts that emits one point per local / other /
    unidentified group, plus a dashed origin→destination line +
    clickable point per incoming group. Position is interpolated
    along the trajectory for in-hyperspace groups.
  - map.svelte threads the hitLookup into handleMapClick.

Vitest:
  - tests/helpers/empty-ship-groups.ts exposes EMPTY_SHIP_GROUPS
    so existing fixtures can spread the new five empty arrays
    without enumerating every field.
  - state-binding-groups.test.ts covers each group variant's
    primitive geometry and lookup correctness.
  - All previously-existing fixture builders pick up the spread
    so GameReport stays a complete object.

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

ui/frontend/src/map/render.ts

@@ -702,10 +702,29 @@ function drawCircle(g: Graphics, p: CirclePrim, theme: Theme): void {
 }
 
 function drawLine(g: Graphics, p: LinePrim, theme: Theme): void {
-	g.moveTo(p.x1, p.y1);
-	g.lineTo(p.x2, p.y2);
 	const color = p.style.strokeColor ?? theme.lineStroke;
 	const alpha = p.style.strokeAlpha ?? 1;
 	const width = p.style.strokeWidthPx ?? 1;
+	const dash = p.style.strokeDashPx;
+	if (dash === undefined || dash <= 0) {
+		g.moveTo(p.x1, p.y1);
+		g.lineTo(p.x2, p.y2);
+		g.stroke({ color, alpha, width });
+		return;
+	}
+	// PixiJS v8 has no native dashed-line API; segment the path into
+	// equal-length dashes (dash and gap both `dash` units).
+	const dx = p.x2 - p.x1;
+	const dy = p.y2 - p.y1;
+	const length = Math.hypot(dx, dy);
+	if (length === 0) return;
+	const ux = dx / length;
+	const uy = dy / length;
+	const step = dash * 2;
+	for (let t = 0; t < length; t += step) {
+		const segEnd = Math.min(t + dash, length);
+		g.moveTo(p.x1 + ux * t, p.y1 + uy * t);
+		g.lineTo(p.x1 + ux * segEnd, p.y1 + uy * segEnd);
+	}
 	g.stroke({ color, alpha, width });
 }

ui/frontend/src/map/ship-groups.ts

@@ -0,0 +1,246 @@
+// Phase 19 ship-group → World primitive translation. Sits next to
+// `state-binding.ts` so the latter can stay focused on planets while
+// the more involved group geometry (in-hyperspace interpolation,
+// incoming-trajectory lines) lives here.
+//
+// Position rules:
+//   - On-planet local / other groups (origin === null) — drawn next
+//     to the destination planet, slightly offset so the group has its
+//     own hit-target distinct from the planet pixel. Multiple groups
+//     stationed at the same planet share the offset (Phase 19
+//     limitation; a future phase fans them out or lists them in the
+//     planet inspector).
+//   - In-hyperspace local / other groups (origin / range set) —
+//     interpolated along the origin → destination line at `range`
+//     world units from the destination.
+//   - Incoming groups — origin and destination are always present;
+//     emit a dashed red trajectory line between the two and a
+//     clickable point at the interpolated position (range = the
+//     `distance` field).
+//   - Unidentified groups — drawn at the absolute (x, y) the radar
+//     reports.
+//
+// PrimitiveIDs are partitioned via large per-variant offsets so they
+// never collide with planet ids (which run in `[0, planetCount)`).
+
+import type {
+	GameReport,
+	ReportIncomingShipGroup,
+	ReportLocalShipGroup,
+	ReportOtherShipGroup,
+	ReportPlanet,
+	ReportUnidentifiedShipGroup,
+} from "../api/game-state";
+import type { ShipGroupRef } from "../lib/selection.svelte";
+import type { LinePrim, PointPrim, PrimitiveID, Style } from "./world";
+
+/**
+ * SHIP_GROUP_ID_OFFSETS partitions the primitive-id namespace so a
+ * hit on a ship-group primitive is unambiguous: the offset alone
+ * disambiguates the variant and `id - offset` recovers the index
+ * (or, for `local`, lookup happens via the parallel hitLookup map
+ * since UUID strings cannot fit in a numeric primitive id).
+ */
+export const SHIP_GROUP_ID_OFFSETS = {
+	local: 100_000_000,
+	other: 200_000_000,
+	incoming: 300_000_000,
+	incomingLine: 350_000_000,
+	unidentified: 400_000_000,
+} as const;
+
+/** ON_PLANET_OFFSET is the (dx, dy) world-unit shift applied to a
+ * group point that sits on a planet, so the group has a distinct
+ * click target from the planet itself. The offset is small enough
+ * that the visual association with the planet stays clear. */
+const ON_PLANET_OFFSET = { dx: 6, dy: -6 };
+
+const STYLE_LOCAL_GROUP: Style = {
+	fillColor: 0xfff176,
+	fillAlpha: 0.95,
+	pointRadiusPx: 3,
+};
+
+const STYLE_OTHER_GROUP: Style = {
+	fillColor: 0xff6f40,
+	fillAlpha: 0.9,
+	pointRadiusPx: 3,
+};
+
+const STYLE_INCOMING_GROUP: Style = {
+	fillColor: 0xff5252,
+	fillAlpha: 1,
+	pointRadiusPx: 4,
+};
+
+const STYLE_INCOMING_LINE: Style = {
+	strokeColor: 0xff5252,
+	strokeAlpha: 0.85,
+	strokeWidthPx: 1,
+	strokeDashPx: 4,
+};
+
+const STYLE_UNIDENTIFIED_GROUP: Style = {
+	fillColor: 0x9aa3a8,
+	fillAlpha: 0.65,
+	pointRadiusPx: 3,
+};
+
+// Priority order inside `hit-test`: ship groups outrank planets so a
+// hyperspace group landing on top of an unidentified planet is
+// selectable. On-planet groups stay below the planet so clicks on a
+// planet still resolve to the planet itself (the offset gives the
+// group its own un-overlapped hit area).
+const PRIORITY_LOCAL = 5;
+const PRIORITY_OTHER = 5;
+const PRIORITY_INCOMING_POINT = 6;
+const PRIORITY_INCOMING_LINE = 0;
+const PRIORITY_UNIDENTIFIED = 4;
+
+export interface ShipGroupPrimitives {
+	primitives: (PointPrim | LinePrim)[];
+	lookup: Map<PrimitiveID, ShipGroupRef>;
+}
+
+export function shipGroupsToPrimitives(report: GameReport): ShipGroupPrimitives {
+	const primitives: (PointPrim | LinePrim)[] = [];
+	const lookup = new Map<PrimitiveID, ShipGroupRef>();
+	const planetIndex = new Map<number, ReportPlanet>();
+	for (const planet of report.planets) {
+		planetIndex.set(planet.number, planet);
+	}
+
+	for (let i = 0; i < report.localShipGroups.length; i++) {
+		const group = report.localShipGroups[i]!;
+		const pos = computeGroupPosition(group, planetIndex);
+		if (pos === null) continue;
+		const id = SHIP_GROUP_ID_OFFSETS.local + i;
+		primitives.push(makePoint(id, pos.x, pos.y, PRIORITY_LOCAL, STYLE_LOCAL_GROUP));
+		lookup.set(id, { variant: "local", id: group.id });
+	}
+
+	for (let i = 0; i < report.otherShipGroups.length; i++) {
+		const group = report.otherShipGroups[i]!;
+		const pos = computeGroupPosition(group, planetIndex);
+		if (pos === null) continue;
+		const id = SHIP_GROUP_ID_OFFSETS.other + i;
+		primitives.push(makePoint(id, pos.x, pos.y, PRIORITY_OTHER, STYLE_OTHER_GROUP));
+		lookup.set(id, { variant: "other", index: i });
+	}
+
+	for (let i = 0; i < report.incomingShipGroups.length; i++) {
+		const group = report.incomingShipGroups[i]!;
+		const origin = planetIndex.get(group.origin);
+		const destination = planetIndex.get(group.destination);
+		if (origin === undefined || destination === undefined) continue;
+		const lineId = SHIP_GROUP_ID_OFFSETS.incomingLine + i;
+		primitives.push({
+			kind: "line",
+			id: lineId,
+			priority: PRIORITY_INCOMING_LINE,
+			style: STYLE_INCOMING_LINE,
+			hitSlopPx: 0,
+			x1: origin.x,
+			y1: origin.y,
+			x2: destination.x,
+			y2: destination.y,
+		});
+		const pos = interpolateAlongLine(
+			destination.x,
+			destination.y,
+			origin.x,
+			origin.y,
+			group.distance,
+		);
+		const pointId = SHIP_GROUP_ID_OFFSETS.incoming + i;
+		primitives.push(
+			makePoint(
+				pointId,
+				pos.x,
+				pos.y,
+				PRIORITY_INCOMING_POINT,
+				STYLE_INCOMING_GROUP,
+				/*hitSlopPx*/ 4,
+			),
+		);
+		lookup.set(pointId, { variant: "incoming", index: i });
+	}
+
+	for (let i = 0; i < report.unidentifiedShipGroups.length; i++) {
+		const group: ReportUnidentifiedShipGroup =
+			report.unidentifiedShipGroups[i]!;
+		const id = SHIP_GROUP_ID_OFFSETS.unidentified + i;
+		primitives.push(
+			makePoint(
+				id,
+				group.x,
+				group.y,
+				PRIORITY_UNIDENTIFIED,
+				STYLE_UNIDENTIFIED_GROUP,
+			),
+		);
+		lookup.set(id, { variant: "unidentified", index: i });
+	}
+
+	return { primitives, lookup };
+}
+
+function computeGroupPosition(
+	group: ReportLocalShipGroup | ReportOtherShipGroup,
+	planetIndex: Map<number, ReportPlanet>,
+): { x: number; y: number } | null {
+	const destination = planetIndex.get(group.destination);
+	if (destination === undefined) return null;
+	if (group.origin === null || group.range === null) {
+		// Stationed on the destination planet; offset slightly so the
+		// group is distinct from the planet's own hit target.
+		return {
+			x: destination.x + ON_PLANET_OFFSET.dx,
+			y: destination.y + ON_PLANET_OFFSET.dy,
+		};
+	}
+	const origin = planetIndex.get(group.origin);
+	if (origin === undefined) return null;
+	return interpolateAlongLine(
+		destination.x,
+		destination.y,
+		origin.x,
+		origin.y,
+		group.range,
+	);
+}
+
+/**
+ * interpolateAlongLine returns the point that sits `range` world
+ * units away from `(dx, dy)` toward `(ox, oy)`. The total path length
+ * is the Euclidean distance between the two anchors; the position is
+ * `dest + (range / total) × (origin - dest)`. When the anchors are
+ * coincident or `range` is zero the result is the destination, which
+ * is fine for the ship-group rendering — a degenerate group still
+ * gets a click target on the destination planet.
+ */
+function interpolateAlongLine(
+	dx: number,
+	dy: number,
+	ox: number,
+	oy: number,
+	range: number,
+): { x: number; y: number } {
+	const ddx = ox - dx;
+	const ddy = oy - dy;
+	const total = Math.hypot(ddx, ddy);
+	if (total === 0 || range <= 0) return { x: dx, y: dy };
+	const t = Math.min(1, range / total);
+	return { x: dx + t * ddx, y: dy + t * ddy };
+}
+
+function makePoint(
+	id: PrimitiveID,
+	x: number,
+	y: number,
+	priority: number,
+	style: Style,
+	hitSlopPx = 0,
+): PointPrim {
+	return { kind: "point", id, priority, style, hitSlopPx, x, y };
+}

ui/frontend/src/map/state-binding.ts

@@ -1,9 +1,11 @@
 // State binding between the typed game report and the renderer's
-// World. Phase 11 only emits primitives for planets; later phases
-// extend the binding with ship-class reach circles (Phase 17 / 18),
-// hyperspace and incoming groups (Phase 11+ via separate primitives),
-// cargo routes (Phase 16), reach / visibility zones (Phase 17), and
-// battle / bombing markers (Phase 27).
+// World. Phase 11 emitted primitives only for planets; Phase 19
+// extends the binding with ship-group primitives (own / foreign / in-
+// hyperspace / incoming / unidentified) plus a `hitLookup` map so the
+// click handler can dispatch a renderer-side hit back to the right
+// selection variant. Later phases extend with ship-class reach
+// circles (Phase 17 / 18 in `ui/core/calc/`), reach / visibility
+// zones, and battle / bombing markers (Phase 27).
 //
 // The four planet kinds in the report each map to a distinct style so
 // the user can tell own / other-race / uninhabited / unidentified
@@ -12,7 +14,9 @@
 // colours and adds theme switching.
 
 import type { GameReport, ReportPlanet } from "../api/game-state";
-import { World, type Primitive, type Style } from "./world";
+import type { ShipGroupRef } from "../lib/selection.svelte";
+import { shipGroupsToPrimitives } from "./ship-groups";
+import { World, type Primitive, type PrimitiveID, type Style } from "./world";
 
 const STYLE_LOCAL: Style = {
 	fillColor: 0x6dd2ff,
@@ -39,11 +43,11 @@ const STYLE_UNIDENTIFIED: Style = {
 };
 
 // PlanetIDs occupy the [0, 4_000_000_000) range — well below
-// JavaScript's `Number.MAX_SAFE_INTEGER` — so the engine `number` (uint64)
-// fits in a primitive id (number) without truncation. The binding
-// uses the engine number directly as the primitive id so later phases
-// can resolve a planet by its hit-test result without an extra
-// lookup table.
+// JavaScript's `Number.MAX_SAFE_INTEGER` — so the engine `number`
+// (uint64) fits in a primitive id (number) without truncation. The
+// binding uses the engine number directly as the primitive id so the
+// click handler can recover a planet by hit-test result without an
+// extra lookup.
 function styleFor(kind: ReportPlanet["kind"]): Style {
 	switch (kind) {
 		case "local":
@@ -70,17 +74,38 @@ function priorityFor(kind: ReportPlanet["kind"]): number {
 	}
 }
 
+/**
+ * HitTarget describes which game entity a renderer-side hit-test
+ * resolves to. The click handler in `lib/active-view/map.svelte`
+ * looks the hit primitive's id up in the binding's hitLookup map
+ * and dispatches `selection.selectPlanet` or
+ * `selection.selectShipGroup` accordingly.
+ */
+export type HitTarget =
+	| { kind: "planet"; number: number }
+	| { kind: "shipGroup"; ref: ShipGroupRef };
+
+export interface ReportToWorldResult {
+	world: World;
+	hitLookup: Map<PrimitiveID, HitTarget>;
+}
+
 /**
  * reportToWorld translates a GameReport into a renderer-ready World
- * containing one Point primitive per planet (all four planet kinds).
- * The world rectangle matches `report.mapWidth` × `report.mapHeight`.
+ * containing one Point primitive per planet (all four planet kinds)
+ * plus the Phase 19 ship-group surface — own / foreign groups
+ * (on-planet or in-hyperspace), incoming groups (dashed trajectory
+ * line + clickable point), and unidentified-group blips. The world
+ * rectangle matches `report.mapWidth` × `report.mapHeight`.
  *
  * If the report carries zero planets (turn-zero edge cases or seeded
  * tests), the World is still well-formed: the renderer mounts on an
  * empty primitive list without errors.
  */
-export function reportToWorld(report: GameReport): World {
+export function reportToWorld(report: GameReport): ReportToWorldResult {
 	const primitives: Primitive[] = [];
+	const hitLookup = new Map<PrimitiveID, HitTarget>();
+
 	for (const planet of report.planets) {
 		primitives.push({
 			kind: "point",
@@ -91,8 +116,18 @@ export function reportToWorld(report: GameReport): World {
 			x: planet.x,
 			y: planet.y,
 		});
+		hitLookup.set(planet.number, { kind: "planet", number: planet.number });
 	}
+
+	const groups = shipGroupsToPrimitives(report);
+	for (const prim of groups.primitives) {
+		primitives.push(prim);
+	}
+	for (const [primId, ref] of groups.lookup) {
+		hitLookup.set(primId, { kind: "shipGroup", ref });
+	}
+
 	const width = report.mapWidth > 0 ? report.mapWidth : 1;
 	const height = report.mapHeight > 0 ? report.mapHeight : 1;
-	return new World(width, height, primitives);
+	return { world: new World(width, height, primitives), hitLookup };
 }

ui/frontend/src/map/world.ts

@@ -24,6 +24,13 @@ export interface Style {
 	strokeAlpha?: number; // 0..1
 	strokeWidthPx?: number; // pixels at any zoom
 	pointRadiusPx?: number; // pixels at any zoom (for kind === 'point')
+	// strokeDashPx — when set on a `LinePrim`, the line is rendered as
+	// a dashed pattern whose dash and gap are both this length. When
+	// unset (or zero), the stroke is solid. Interpreted in the same
+	// world-unit space as `strokeWidthPx`, so the dash spacing scales
+	// with the camera. Phase 19 uses this for the IncomingGroup
+	// trajectory line; ignored on point and circle primitives.
+	strokeDashPx?: number;
 }
 
 // PrimitiveBase carries the fields shared by every primitive kind.