galaxy-game/ui/frontend/src/map/pending-send-routes.ts

// Map overlay for pending Send commands. The order draft can carry
// `sendShipGroup` entries that have not yet reached the engine —
// the client wants to show them on the map straight away so the
// player can tell at a glance which orbits are about to launch
// where. Each pending Send becomes a green dashed line from the
// source group's current orbit planet to the chosen destination,
// drawn alongside the cargo-route arrows on the same overlay
// layer.
//
// The lines are *route hints*: they do not contribute to hit-test
// (the picker is the only way to issue Send), and they share the
// dashed style with in-space tracks so the player reads "this is
// motion" without confusing them with cargo arrows.

import type { GameReport, ReportPlanet } from "../api/game-state";
import type { OrderCommand } from "../sync/order-types";
import { torusShortestDelta } from "./math";
import { DARK_THEME, type LinePrim, type PrimitiveID, type Style, type Theme } from "./world";

// Sit between cargo-route arrows (5..8) and ship-group points (5..)
// in priority. The line never participates in hit-test (hitSlopPx=0)
// so the relative ordering only affects depth-stacking.
const PRIORITY_PENDING_SEND_LINE = 1;

/**
 * High-bit prefix on every pending-send line id so it cannot
 * collide with planet numbers, ship-group ids, or cargo-route line
 * ids. Cargo routes use `0x80000000`; pending-send routes use
 * `0xa0000000`. The renderer's hit-test treats ids opaquely.
 */
export const PENDING_SEND_LINE_ID_PREFIX = 0xa0000000;

/**
 * buildPendingSendLines emits one `LinePrim` per `sendShipGroup`
 * command in the supplied draft snapshot. Lines are drawn from the
 * source group's current orbit planet to the chosen destination.
 * Skipped silently when the source group is no longer in the
 * report (history-mode snapshot, group already left orbit), when
 * either planet is missing, or when the command's status is
 * `invalid` / `rejected` (the engine refused it; do not visualise
 * a route the engine will not take).
 *
 * The function is pure — it walks the supplied arrays and returns
 * a new primitive list. Callers combine the result with cargo-
 * route lines and feed both into `handle.setExtraPrimitives`.
 *
 * `theme` supplies the dashed-line colour and defaults to `DARK_THEME`.
 */
export function buildPendingSendLines(
	report: GameReport,
	commands: readonly OrderCommand[],
	statuses: Readonly<Record<string, string>>,
	opts?: { skipPlanets?: ReadonlySet<number> },
	theme: Theme = DARK_THEME,
): LinePrim[] {
	if (commands.length === 0) return [];
	const skip = opts?.skipPlanets;
	const style: Style = {
		strokeColor: theme.pendingSend,
		strokeAlpha: 0.85,
		strokeWidthPx: 1,
		strokeDashPx: 4,
	};
	const planetById = new Map<number, ReportPlanet>();
	for (const planet of report.planets) {
		planetById.set(planet.number, planet);
	}
	const groupById = new Map<string, (typeof report.localShipGroups)[number]>();
	for (const g of report.localShipGroups) {
		groupById.set(g.id, g);
	}
	const lines: LinePrim[] = [];
	let serial = 0;
	for (const cmd of commands) {
		if (cmd.kind !== "sendShipGroup") continue;
		const status = statuses[cmd.id];
		if (status === "rejected" || status === "invalid") continue;
		const group = groupById.get(cmd.groupId);
		if (group === undefined) continue;
		// The group must currently be on its orbit planet (origin
		// null, range null) for the Send to make geometric sense in
		// the report. Once the engine launches it the report flips
		// origin / range to live coordinates and the in-space track
		// renders instead.
		if (group.origin !== null || group.range !== null) continue;
		if (skip !== undefined && skip.has(group.destination)) continue;
		if (skip !== undefined && skip.has(cmd.destinationPlanetNumber)) continue;
		const source = planetById.get(group.destination);
		const destination = planetById.get(cmd.destinationPlanetNumber);
		if (source === undefined || destination === undefined) continue;
		const dx = torusShortestDelta(source.x, destination.x, report.mapWidth);
		const dy = torusShortestDelta(source.y, destination.y, report.mapHeight);
		if (dx === 0 && dy === 0) continue;
		lines.push({
			kind: "line",
			id: pendingSendLineId(serial),
			priority: PRIORITY_PENDING_SEND_LINE,
			style,
			hitSlopPx: 0,
			x1: source.x,
			y1: source.y,
			x2: source.x + dx,
			y2: source.y + dy,
		});
		serial++;
	}
	return lines;
}

/**
 * pendingSendLineId returns the primitive id of the n-th pending-
 * send line within the prefix-reserved range. Bit-OR rather than
 * addition keeps the prefix unambiguous when `serial` overflows
 * into the prefix bits — the renderer treats ids opaquely, but
 * the encoding stays self-describing for debug dumps.
 */
function pendingSendLineId(serial: number): PrimitiveID {
	return (PENDING_SEND_LINE_ID_PREFIX | (serial & 0x0fffffff)) >>> 0;
}