engine/galaxy.js

/* ============================================================
   The Odyssey galaxy — the open-world meta-layer over the per-planet sim. A
   galaxy holds one engine game state per planet (each a normal createGameState);
   one is "active" (rendered + controlled by the player) and ticks at full rate,
   while the worlds you've left keep evolving in the background on a coarser
   schedule (stepGalaxy). The player has a single, relocatable Command Center:
   their capital seat travels with them via a Spaceport (jumpCapital), and a world
   they leave stays a colony that keeps producing and sends home passive income.

   This module owns everything meta: the world roster, universal credits, the
   active planet, the per-frame advance (stepGalaxy), background-colony upkeep +
   notifications (sweepColonies), a status snapshot for the starmap (galaxyStatus),
   and the jump. The per-planet engine is untouched — a planet is just a normal
   createGameState flagged `endless` (no victory, no clock — see engine/victory.js).

   Determinism: the start world and every planet's map are derived from the galaxy
   seed, and the background schedule is keyed to the integer `galaxy.tick`, so the
   same seed replays the same galaxy — the same guarantee as the skirmish sim.
   ============================================================ */

"use strict";

import { createGameState, makeUnit, peekEntityId, restoreEntityId } from "./state.js";
import { mulberry32 } from "./rng.js";
import { updateFog } from "./fog.js";
import { tick } from "./sim.js";
import { createMarket } from "./market.js";
import { createDiplomacy, aiDevelopment, PEACE_THRESHOLD, ALLIED_THRESHOLD,
         FACTION_ECHO_PENALTY, FACTION_ECHO_DURATION } from "./diplomacy.js";
import { UNITS, BUILDINGS, freightUsed, freightRoom } from "./entities.js";
import { hasColonyShip } from "./colony.js";
import { PLANET_ARCHETYPE, ODYSSEY_EXTRA_ARCHETYPE, archetypeFor } from "./aiArchetypes.js";
import { DIFFICULTY_OPTIONS } from "./aiDifficulty.js";
import { STRATEGIES } from "./aiStrategy.js";
import { runColonyPolicies } from "./colonyPolicy.js";
import { PLANETS, COM } from "../data.js";

// The worlds an Odyssey can settle: the skirmish nine PLUS the Odyssey-only extras
// (a research capital, an agri world) — appended AFTER the nine so the skirmish
// worlds keep their roster index, which keeps the background-tick schedule (keyed
// on worlds.indexOf) and every same-seed replay stable.
export const ODYSSEY_WORLDS = [...Object.keys(PLANET_ARCHETYPE), ...Object.keys(ODYSSEY_EXTRA_ARCHETYPE)];

// A stable per-planet seed derived from the galaxy seed + the world id, so every
// world generates its own deterministic map and two galaxies with the same seed
// are byte-identical.
function planetSeed(seed, planetId) {
  let h = seed >>> 0;
  for (let i = 0; i < planetId.length; i++) h = (Math.imul(h ^ planetId.charCodeAt(i), 0x01000193)) >>> 0;
  return h >>> 0;
}

// LIVING GALAXY, BOUNDED. The galaxy is alive before you ever visit it — but not ALL of it at
// once: only this many of the OTHER worlds actually exist and simulate from turn one. The whole
// roster stays on the starmap and stays jumpable; an undrawn world is simply DORMANT until the
// player arrives, at which point jumpCapital instantiates it exactly as it always did for a
// never-visited destination. Bounding the live set keeps the per-frame background scheduler's
// work (and a save's size) proportional to a handful of worlds instead of the whole roster,
// while the galaxy still develops, spreads factions and races its Gate behind your back.
export const BACKGROUND_WORLDS = 3;

// WHICH worlds those are: a seeded, pseudo-random draw from the roster minus the start seat, so
// two runs from the same seed bring up the same neighbours (the determinism guarantee in this
// file's header) while two different seeds explore different pockets of the galaxy — the live set
// is part of what a seed means, not a fixed prefix of ODYSSEY_WORLDS.
//
// Drawn from its OWN distinctly-keyed stream (planetSeed with a ":backgroundWorlds" suffix, the
// same idiom neighbourAiProfile uses below) rather than createGalaxy's `pick`, so adding or
// changing this draw can never shift the start-world roll or any other seeded stream.
//
// Returned in fixed ROSTER order, not draw order: the background scheduler (stepGalaxy) keys on
// each world's roster index and every galaxy-wide scan walks `galaxy.worlds`, so keeping the
// creation order roster-ordered leaves those paths reading exactly as they did when every world
// was instantiated.
export function backgroundWorldIds(seed, startId, count = BACKGROUND_WORLDS) {
  const pool = ODYSSEY_WORLDS.filter(id => id !== startId);
  const n = Math.max(0, Math.min(count | 0, pool.length));
  const pick = mulberry32(planetSeed(seed >>> 0, ":backgroundWorlds"));
  // Partial Fisher-Yates: draw n distinct worlds without the retry loop a naive
  // "roll until it's new" pick would need (and without its unbounded worst case).
  for (let i = 0; i < n; i++) {
    const j = i + Math.floor(pick() * (pool.length - i));
    const tmp = pool[i]; pool[i] = pool[j]; pool[j] = tmp;
  }
  const drawn = new Set(pool.slice(0, n));
  return ODYSSEY_WORLDS.filter(id => drawn.has(id));
}

// VARIED NEIGHBOURS: every world but the player's start seat carries its OWN difficulty and AI
// Strategy (personality) — a distribution across the galaxy, some easier, some harder — instead
// of mirroring the player's own splash-screen pick everywhere. Pure function of the galaxy seed +
// planetId (a distinctly-keyed planetSeed, so this draws an independent stream from map
// generation's own rng), so the same galaxy seed always assigns the same profile to the same
// world: exploring is how you learn a neighbour's temperament, not a settings screen.
// aiApm/aiMicro are read off the SAME resolved difficulty entry, never left mismatched with a
// different world's dials (addPlanet threads all four through together).
export function neighbourAiProfile(seed, planetId) {
  const pick = mulberry32(planetSeed(seed, planetId + ":neighbourProfile"));
  const diffOpt = DIFFICULTY_OPTIONS[Math.floor(pick() * DIFFICULTY_OPTIONS.length)];
  const strategyKeys = Object.keys(STRATEGIES);
  const aiStrategy = strategyKeys[Math.floor(pick() * strategyKeys.length)];
  return { difficulty: diffOpt.mult, aiApm: diffOpt.aiApm, aiMicro: diffOpt.aiMicro, aiStrategy };
}

// Create an Odyssey galaxy. Phase 1: a single active planet (the player's
// randomly-chosen — or explicitly PICKED — starting world) plus the meta-fields
// (credits, activeId, the world roster) the later phases grow into.
export function createGalaxy({ seed = 1, difficulty = "medium", sizeMult = 1,
  resourceMult = 1, playerFaction = "frontier", aiApm, aiMicro, aiStrategy, startId: startIdOpt, popCap = null } = {}) {
  seed = seed >>> 0;
  const pick = mulberry32(seed);
  // Always draw, even when the caller supplies an explicit startId: consuming this draw keeps
  // every OTHER seed-derived RNG stream byte-identical whether the player picked a world or left
  // it to chance (CONTRIBUTING.md's determinism guarantee) — skipping the draw on the "explicit
  // pick" path would silently shift whatever a later change might draw from this same `pick`.
  const drawnId = ODYSSEY_WORLDS[Math.floor(pick() * ODYSSEY_WORLDS.length)];
  const startId = (startIdOpt != null && ODYSSEY_WORLDS.includes(startIdOpt)) ? startIdOpt : drawnId;

  const galaxy = {
    seed,
    credits: 500,               // universal credits — galaxy-wide, transportable; fund jumps + trade
    activeId: startId,          // the world the player is currently on
    worlds: ODYSSEY_WORLDS.slice(),
    planets: new Map(),         // planetId -> engine game state
    // `startId` records which world was actually landed on (the player's pick, or the seed's own
    // draw) — informational, not read back to reconstruct anything (activeId already IS that
    // world, and persists on its own); rides along for free since `settings` is saved whole.
    settings: { difficulty, sizeMult, resourceMult, playerFaction, aiApm, aiMicro, aiStrategy, startId, popCap },
    tick: 0,                    // integer galaxy-tick counter (drives the background-world schedule)
    time: 0,                    // galaxy-wide sim clock (seconds) — monotonic across jumps; keys the relief cooldown
    entitySeq: 0,               // fresh-id counter for entities relocated across worlds by a jump
    colonyNotes: new Map(),     // per-planet UI notification bookkeeping (galaxy-side, not sim state)
    pacified: new Set(),        // worlds where you've razed the neighbour's Command Center (a conquest milestone)
    pacifyNotes: [],            // freshly-pacified world ids awaiting a UI toast + firework (transient, drained by boot.js)
    reached: new Set(),         // progress milestones already celebrated (see checkGalaxyProgress) — persisted so a reload doesn't re-fire them
    milestones: [],             // freshly-reached milestones awaiting a UI firework (transient, drained by boot.js)
    wonBy: null,                // legacy: no Odyssey win any more (play-forever) — kept null for save/skirmish compat
    discovered: new Set([startId]),   // LIVING GALAXY: worlds the player has actually reached (starmap "explored" + free return-jump). Every world SIMULATES from the start, but the player only SEES a world once they've been there.
    claims: new Map(),          // faction spread: worldId → controlling faction (checkExpansion), shown on the starmap
    expansionNotes: [],         // freshly-claimed/expanded worlds awaiting a UI toast (transient, drained by boot.js)
    lanes: [],                  // Freight Lanes (runLanes below): standing shipping routes between held worlds
    laneSeq: 0,                 // fresh lane-id counter (createLane)
  };
  addPlanet(galaxy, startId);
  // LIVING GALAXY: a seeded handful of the other worlds (backgroundWorldIds, above) already exist and
  // simulate in the background from turn one — each with its own AI faction founding a base and
  // developing (engine/ai.js aiIndustry), its economy growing and its diplomacy drifting — so the
  // galaxy is alive before you ever visit, and (checkExpansion) factions spread across it over time.
  // Added `unsettled` (no player presence until you jump in). The rest of the roster stays DORMANT
  // and is built in on arrival (jumpCapital), so every world remains a destination. The BG scheduler
  // (stepGalaxy) spreads the live ones' ticks round-robin. Deterministic: the draw and each world's
  // map both come from the galaxy seed, so two same-seed galaxies are byte-identical.
  for (const id of backgroundWorldIds(seed, startId)) addPlanet(galaxy, id, { unsettled: true });
  return galaxy;
}

// Units staged within this radius of a Spaceport ride along with the capital on
// a jump — you assemble your expedition at the pad, then launch.
export const JUMP_LOAD_RADIUS = 150;

// Credits a jump costs (fuel). Funded by trading at the market, so exploration
// draws on your economy rather than being free.
export const JUMP_COST = 400;

// A held background colony sends home this many credits per second per surviving
// income-earning player building — passive income, so the worlds you leave keep working
// for you (and a razed colony, down to no buildings, quietly stops paying).
export const COLONY_INCOME_PER_BUILDING = 0.3;
// …but only up to this many buildings per world. Without a cap, spamming the cheapest
// building (a 75-ore Habitat, a turret) on a pacified world — where the razed neighbour
// can never strike back — was an unbounded credit annuity that made the counter a
// meaningless up-only number. The cap bounds a colony's yield to a real economy's worth.
export const COLONY_INCOME_CAP = 6;

// DOMINATION WITH TEETH, optional occupation dividend (docs/improvement-proposals.md 663): a
// pacified world pays a small flat credits/sec just for being held down — no player building
// required, since the point is that razing the neighbour's capital and keeping it razed is worth
// something on its own, distinct from (and additive with) whatever a colony you've also founded
// there separately earns above. Same universal-credits currency as COLONY_INCOME_PER_BUILDING and
// a small fraction of what a single well-built colony can pay at its cap (COLONY_INCOME_PER_BUILDING
// * COLONY_INCOME_CAP = 1.8/s), so conquest is a genuine but modest reward, not a better economy
// than actually building one.
export const PACIFIED_INCOME = 0.1;   // credits/sec per pacified world (~6/min)

const playerBuildingCount = state => {
  let n = 0;
  for (const b of state.buildings.values()) if (b.owner === "player") n++;
  return n;
};

// Buildings that count toward passive income: everything except the pure-defensive
// turret (a turret wall isn't an economy), capped per world (see COLONY_INCOME_CAP).
const incomeBuildingCount = state => {
  let n = 0;
  for (const b of state.buildings.values()) if (b.owner === "player" && b.type !== "turret") n++;
  return Math.min(COLONY_INCOME_CAP, n);
};

// Build (or rebuild) a planet's engine state into the galaxy. Reuses the exact
// skirmish scaffold — economy, both players' bases, fog — but flagged `endless`
// so it never resolves by conquest or clock (see engine/victory.js).
//
// `unsettled` strips the auto-seeded player presence: a jump DESTINATION you
// haven't settled yet has only its neighbour — your capital + forces arrive via
// the jump, not from map generation.
//
// AI dials: the player's OWN splash-screen difficulty/strategy pick (galaxy.settings) applies
// only to the start seat (planetId === galaxy.activeId, true for every world at the point
// createGalaxy calls this). Every other world resolves its own varied profile instead
// (neighbourAiProfile, above) — a distribution across the galaxy, not one setting everywhere.
export function addPlanet(galaxy, planetId, { unsettled = false } = {}) {
  const state = buildPlanetState(galaxy, planetId, unsettled);
  galaxy.planets.set(planetId, state);
  bumpEntityCounterPastGalaxy(galaxy);         // keep future live-built ids galaxy-unique (see below)
  return state;
}

// A DORMANT world's state, built to LOOK at without waking it. The landing picker
// (landingPicker.js) has to draw the destination's map before the player commits to the jump, and
// only a seeded handful of worlds are alive from turn one (BACKGROUND_WORLDS) — so merely opening
// that modal, or backing out of it, must not add a world to the live set. Built from the same
// (galaxy seed, planetId) inputs addPlanet uses and never ticked, so the state the jump really
// creates on arrival is identical to the one previewed. A world that's already up IS its own
// preview and is returned as-is.
export function previewPlanet(galaxy, planetId) {
  const live = galaxy.planets.get(planetId);
  if (live) return live;
  const state = buildPlanetState(galaxy, planetId, true);
  // Even a throwaway world moves the GLOBAL entity-id counter (createGameState re-seeds it from 1
  // per world — see bumpEntityCounterPastGalaxy below), so the same bump the registering path does
  // is mandatory here too: without it the next thing built anywhere could reuse a live id.
  bumpEntityCounterPastGalaxy(galaxy);
  return state;
}

// The shared core of both: a planet's engine state, built but not registered.
function buildPlanetState(galaxy, planetId, unsettled) {
  const s = galaxy.settings;
  const seed = planetSeed(galaxy.seed, planetId);
  // A DORMANT world (one the background draw didn't bring up) can be CLAIMED by a spreading faction
  // before it ever exists — checkExpansion's sweep walks the whole roster, and the starmap flies the
  // claim on it. So a world built in later takes the claimed colours over its own archetype's, exactly
  // as checkExpansion flips an already-instantiated world's AI faction on the spot: the flag the
  // player has been looking at is the one they meet on landing.
  const claimed = galaxy.claims && galaxy.claims.get(planetId);
  const aiFaction = claimed || archetypeFor(planetId).faction || "neutral";
  const profile = planetId === galaxy.activeId
    ? { difficulty: s.difficulty, aiApm: s.aiApm, aiMicro: s.aiMicro, aiStrategy: s.aiStrategy }
    : neighbourAiProfile(galaxy.seed, planetId);
  const state = createGameState({
    planetId, seed, rng: mulberry32(seed),
    aiApm: profile.aiApm, aiMicro: profile.aiMicro, aiStrategy: profile.aiStrategy, difficulty: profile.difficulty,
    sizeMult: s.sizeMult, resourceMult: s.resourceMult, popCap: s.popCap,
    playerFaction: s.playerFaction, aiFaction, endless: true,
  });
  if (unsettled) {
    for (const [id, u] of [...state.units]) if (u.owner === "player") state.units.delete(id);
    for (const [id, b] of [...state.buildings]) if (b.owner === "player") state.buildings.delete(id);
    state.background = true;   // not the active seat until you land here
    updateFog(state, state.fog, "player");
  }
  state.market = createMarket(state);         // every world has its own price book
  state.diplomacy = createDiplomacy();        // and its own neighbour's stance toward you
  state.inGalaxy = true;                       // part of a galaxy → the per-world defeat check is off (engine/victory.js);
                                               // the galaxy never loses (checkGalaxyRescue), it only ends by surrender
  return state;
}

// createGameState (engine/state.js) resets the GLOBAL entity-id counter to 1 for each world's
// deterministic seeding — which, once a galaxy holds more than one world, would leave the counter
// BELOW ids already live on other worlds. The next thing the player then built or produced could
// reuse an id and silently overwrite an existing entity (e.g. return to a built-up world after
// visiting a new one and lay down a Spaceport → it clobbers a building that shared the id). So
// after each world is (re)built in, bump the counter past every b/u id anywhere in the galaxy, so
// live mints stay unique galaxy-wide. Deterministic — reads only entity ids (no clock/RNG); the
// seeded ids themselves are untouched, so per-world determinism is preserved.
function idNum(id) {
  const n = parseInt(String(id).replace(/^\D+/, ""), 10);   // "b12" | "u7" | "g3" → 12 | 7 | 3
  return Number.isFinite(n) ? n : 0;
}
function bumpEntityCounterPastGalaxy(galaxy) {
  let max = peekEntityId() - 1;                              // whatever this world's own seeding reached
  for (const state of galaxy.planets.values()) {
    for (const id of state.units.keys()) max = Math.max(max, idNum(id));
    for (const id of state.buildings.keys()) max = Math.max(max, idNum(id));
  }
  restoreEntityId(max + 1);
}

// Run the background colonies each tick: bank their passive income, watch for
// trouble, and return notifications for the UI. Also the single place their sim
// events are drained — a colony isn't rendered or heard, so nothing else consumes
// them (left alone they would grow without bound). Reports a colony coming under
// attack (a player asset destroyed there) and a colony being lost (its last
// player building razed), each at most once per state transition. The "already
// notified" flags live on the galaxy (colonyNotes), not on the deterministic
// engine state — they're transient UI bookkeeping, re-derived harmlessly on load.
export function sweepColonies(galaxy, dt = 0) {
  const out = [];
  for (const [id, state] of galaxy.planets) {
    if (!state.background) continue;
    const buildings = playerBuildingCount(state);
    galaxy.credits += incomeBuildingCount(state) * COLONY_INCOME_PER_BUILDING * dt;   // capped, turret-excluded passive income
    if (galaxy.pacified && galaxy.pacified.has(id)) galaxy.credits += PACIFIED_INCOME * dt;   // occupation dividend, additive
    const rec = galaxy.colonyNotes.get(id) || { hadColony: false, colonyLost: false };
    // A standing colony resets the lost latch, so retaking and rebuilding a world re-arms
    // its alerts — without this, a world lost once was muted forever (a second razing never
    // re-announced, and the rebuilt colony's under-attack pings stayed suppressed).
    if (buildings > 0) { rec.hadColony = true; rec.colonyLost = false; }
    if (rec.hadColony && buildings === 0 && !rec.colonyLost) {
      rec.colonyLost = true;
      out.push({ type: "lost", planetId: id });
    } else if (rec.hadColony && !rec.colonyLost) {
      // Only worlds the player actually colonised raise hostile/attacked alerts — the living galaxy
      // now background-simulates every world (its AI can drift to war on its own), but a neighbour
      // turning on a world you've never set foot on isn't your problem and mustn't ping you.
      // A background world's diplomacy keeps drifting (diplomacy.js CREEP_RATE), so a
      // neighbour eventually declares war — but its neighbourHostile event has no other
      // consumer here and used to be silently drained, so the FIRST warning was the colony
      // already dying. Surface the declaration (once — diplomacy latches warAnnounced), else
      // the ongoing raid (fresh player losses this tick).
      if (state.events.some(e => e.type === "neighbourHostile")) out.push({ type: "hostile", planetId: id });
      else if (state.events.some(e => e.type === "entityKilled" && e.owner === "player")) out.push({ type: "attacked", planetId: id });
    }
    galaxy.colonyNotes.set(id, rec);
    state.events.length = 0;   // drain: a background colony's events have no other consumer
  }
  return out;
}

// The game state the player is currently on — what boot.js renders and drives.
export function activeState(galaxy) {
  return galaxy.planets.get(galaxy.activeId);
}

// Background worlds tick once every BG_STEP galaxy-ticks, each time by BG_STEP× the
// step, so a colony advances the same amount of sim time as the active world over
// any span — just in coarser, cheaper increments.
export const BG_STEP = 4;

// id -> roster-index lookup for `galaxy.worlds`, cached by the ARRAY's own identity rather than
// on the galaxy object: `worlds` is built in two places (createGalaxy above, and
// deserializeGalaxy in engine/persist.js), and both set it exactly once and never mutate it in
// place afterwards (append-only roster growth on load rebuilds the array — see persist.js —
// it doesn't push/splice the live `galaxy.worlds` reference), so a WeakMap keyed on that
// reference is a safe, self-invalidating O(1) replacement for the old per-frame
// `galaxy.worlds.indexOf(id)` scan (stepGalaxy runs this once per background world every
// frame, and per its header comment the whole scheduler is meant to stay well under 1ms/frame).
const worldIndexCache = new WeakMap();
function worldIndexMap(worlds) {
  let idx = worldIndexCache.get(worlds);
  if (!idx) { idx = new Map(worlds.map((id, i) => [id, i])); worldIndexCache.set(worlds, idx); }
  return idx;
}

// Advance the whole galaxy by one frame. The active world ticks every frame at
// full cadence (it's rendered and controlled). Every background colony ticks on a
// coarser fixed step, spread round-robin across BG_STEP frames by its fixed roster
// index, so per-frame background work is ~ceil(N/BG_STEP) worlds instead of N.
// Deterministic by construction: the schedule is pure integer arithmetic on the
// galaxy tick and the world's roster position (no wall-clock, no Map-order
// dependence), and each background tick uses the exact constant dtBg so total sim
// time is conserved regardless of cadence.
export function stepGalaxy(galaxy, dt) {
  const t = (galaxy.tick = (galaxy.tick | 0) + 1);
  galaxy.time = (galaxy.time || 0) + dt;             // galaxy-wide clock (deterministic: dt is the fixed step)
  tick(activeState(galaxy), dt);                     // active world: full rate
  const dtBg = dt * BG_STEP;
  const worldIndex = worldIndexMap(galaxy.worlds);
  for (const [id, state] of galaxy.planets) {
    if (id === galaxy.activeId || !state.background) continue;
    if (t % BG_STEP === worldIndex.get(id) % BG_STEP) tick(state, dtBg);
  }
  // Freight Lanes: a standing shipping drip, on its own integer-tick schedule (LANE_PERIOD) —
  // independent of the ~1/sec scan below (lanes move real cargo, so they're worth their own,
  // coarser cadence rather than piggybacking on a scan meant for cheap galaxy-wide bookkeeping).
  if (t % LANE_PERIOD === 0) runLanes(galaxy);
  // These galaxy-wide scans (conquest progress, milestones, no-foothold relief) all change on a
  // minutes timescale, so running them every frame (20 Hz) is wasted work that grows with the
  // colony count. Throttle to ~1/sec on the same deterministic integer schedule the BG round-
  // robin uses — a milestone/pacification/rescue firing up to a second later is imperceptible,
  // and RELIEF_COOLDOWN (20 s) dwarfs it. Runs on tick 1 too, so a freshly-stepped galaxy is
  // checked immediately. Pure integer arithmetic on galaxy.tick — no wall-clock, deterministic.
  if (t === 1 || t % PROGRESS_CHECK_EVERY === 0) {
    checkDomination(galaxy);      // conquest progress: pacified worlds (per-world toast) + a milestone at the target
    checkExpansion(galaxy);       // faction spread: developed AI worlds claim + colonise across the starmap
    updateFactionWarmth(galaxy);  // faction memory (allied direction): refresh each world's Allied-faction-mate count
    checkGalaxyProgress(galaxy);  // milestones: colonies founded, the Antimatter Gate coming online — fireworks, not wins
    checkRivalGate(galaxy);       // the rival Gate: track the galaxy's own charging threat, ascend it on completion
    checkGalaxyRescue(galaxy);    // NEVER auto-defeat: a total wipeout sends a relief colony ship so life goes on
    runColonyPolicies(galaxy);    // colony standing orders (engine/colonyPolicy.js): auto-sell + sustain workers, background worlds only
  }
}
const PROGRESS_CHECK_EVERY = 20;   // galaxy-wide scans run ~once per second (20 Hz sim), not every frame

// The Odyssey NEVER ends in defeat — as long as you haven't surrendered, life goes on
// (surrenderGalaxy is the only terminal state). So there's no galaxy-wide loss; instead, if you
// ever hold NO foothold anywhere (every Command Center razed and no colony ship left), a RELIEF
// colony ship is dispatched to your active world's landing zone so you can re-found and fight on.
// A short cooldown bounds the churn if relief keeps getting farmed, and its arrival is flagged for
// a UI toast. Once you hold the ship you have a foothold again, so it won't re-send. The per-world
// checkEndlessLoss is suppressed for galaxy states (state.inGalaxy, engine/victory.js), so this is
// the sole authority. The cooldown is keyed on the GALAXY-WIDE clock (galaxy.time), not any one
// world's local time — a jump swaps the active world, and each world's clock advances on its own,
// so comparing lastReliefTime (set on world A) to world B's time could read as "cooldown elapsed"
// (B younger than A ⇒ negative delta) or "never elapses", either of which breaks the anti-farm
// bound and could dead-end the no-defeat guarantee. galaxy.time is monotonic across the whole run.
// Pure + deterministic (galaxy.time accumulates the fixed dt in stepGalaxy).
export const RELIEF_COOLDOWN = 20;   // sim seconds between relief drops (anti-farm)
export function checkGalaxyRescue(galaxy) {
  const active = activeState(galaxy);
  if (active.over) return;                                         // a surrender already ended it
  for (const state of galaxy.planets.values()) {
    for (const b of state.buildings.values())
      if (b.owner === "player" && b.type === "command") return;   // a base somewhere → still going
    if (hasColonyShip(state, "player")) return;                   // …or a colony ship to re-found from
  }
  const now = galaxy.time || 0;
  if (now - (galaxy.lastReliefTime ?? -Infinity) < RELIEF_COOLDOWN) return;   // still on cooldown
  galaxy.lastReliefTime = now;
  const lz = active.map.bases.player;
  const ship = makeUnit("colonyship", "player", lz.x, lz.y);
  ship.id = "g" + (galaxy.entitySeq = (galaxy.entitySeq || 0) + 1);   // galaxy id scheme (as in jumpCapital)
  active.units.set(ship.id, ship);
  galaxy.reliefNote = true;                                        // drained by boot.js for a toast
}

// The one terminal state: the player voluntarily gives up. Ends the run on the active seat (the
// boot.js over-poll then shows the game-over screen with the surrender copy). A wipeout alone
// never triggers this — only an explicit surrender does.
export function surrenderGalaxy(galaxy) {
  const active = activeState(galaxy);
  if (active.over) return;
  active.over = true; active.winner = "ai";
  galaxy.surrendered = true;
}

// Record a one-time progress milestone — a firework, drained UI-side by boot.js. Idempotent
// per id, and `reached` persists (engine/persist.js) so a reload never replays a milestone
// you've already celebrated.
// The complete milestone vocabulary — the ONLY ids reachMilestone ever mints. Exported so the load
// path can filter a saved `reached` set against it (engine/persist.js): an unfiltered set let a
// hand-edited save inject junk, and — more importantly — filtering against the WORLD roster instead
// would silently drop every real milestone and replay its fireworks on the next load.
export const MILESTONE_IDS = ["capital", "gate", "domination", "domination:all", "rival-gate"];
/** True for any id reachMilestone can produce, including the per-world `world:N` family. */
export function isMilestoneId(id) {
  return typeof id === "string" && (MILESTONE_IDS.includes(id) || /^world:\d+$/.test(id));
}

function reachMilestone(galaxy, id) {
  if (galaxy.reached.has(id)) return;
  galaxy.reached.add(id);
  galaxy.milestones.push(id);
}

// Progress milestones for the play-forever sandbox — the fireworks that mark how far you've
// come, in place of a victory that would end the run. Swept galaxy-wide each tick, each fired
// once (reachMilestone): founding your first base and each further WORLD you settle
// ("world:N"), fortifying your first Capital ("capital"), and bringing an Antimatter Gate
// online anywhere ("gate" — the former economic victory, now a triumph you keep playing past).
// Conquest milestones live in checkDomination. Pure — reads only entity state; the firework
// itself is fired UI-side (boot.js), keeping the engine DOM-free.
export function checkGalaxyProgress(galaxy) {
  let settledWorlds = 0, hasCapital = false, gateOnline = false;
  for (const state of galaxy.planets.values()) {
    let heldHere = false;
    for (const b of state.buildings.values()) {
      if (b.owner !== "player") continue;
      if (b.type === "command" && !b.constructing) { heldHere = true; if (b.capital) hasCapital = true; }
      if (BUILDINGS[b.type]?.wonder && (b.charge || 0) >= 1) gateOnline = true;
    }
    if (heldHere) settledWorlds++;
  }
  for (let n = 1; n <= settledWorlds; n++) reachMilestone(galaxy, "world:" + n);
  if (hasCapital) reachMilestone(galaxy, "capital");
  if (gateOnline) reachMilestone(galaxy, "gate");
}

// Worlds to pacify (raze the neighbour's Command Center on) for the grand CONQUEST
// milestone — the military, multi-world firework. No longer a win: the galaxy keeps
// running past it (play-forever).
export const DOMINATION_TARGET = 4;

// The AI's foothold on a world — a Command Center OR an undeployed colony ship. The
// colony-ship clause is what stops checkDomination false-pacifying every world at
// tick 0 (both sides now START with a CC-less colony ship), and keeps "pacified"
// meaning "you actually drove them off" — a neighbour reduced to a lone ship can still
// re-found, so it isn't conquered yet. hasColonyShip is false in a skirmish.
const hasAiCommand = state => {
  for (const b of state.buildings.values()) if (b.owner === "ai" && b.type === "command" && !b.constructing) return true;
  return hasColonyShip(state, "ai");
};

// The faction a world answers to for cross-world faction-memory purposes (the grievance echo
// below, and updateFactionWarmth's Allied lift): its DYNAMIC controlling faction (checkExpansion's
// claims, once spread) when it has one, else its own neighbour's faction (state.players.ai.faction)
// — the same claim-first, AI-faction-fallback resolution checkExpansion's own self-claim step
// effectively establishes. Null for a state with no AI player at all.
function worldFaction(galaxy, id, state) {
  const claimed = galaxy.claims && galaxy.claims.get(id);
  if (claimed) return claimed;
  return (state && state.players.ai && state.players.ai.faction) || null;
}

// Conquest progress. A world is "pacified" the moment its neighbour has no standing
// Command Center — you razed it (only two sides fight, and every world is seeded with an
// AI capital). Pacification is STICKY (recorded on the galaxy, so a neighbour rebuilding
// can't un-pacify it); each freshly-pacified world is queued for a UI toast + firework
// (pacifyNotes), and reaching DOMINATION_TARGET fires the grand "domination" milestone —
// a firework, NOT a win, so the sandbox plays on. Deterministic — reads only entity state.
//
// DOMINATION WITH TEETH (docs/improvement-proposals.md 657-665): also stamp the diplomacy-side
// floor flag (state.diplomacy.pacified) on the razed world itself — checkDomination already holds
// that state in this loop. engine/diplomacy.js's updateDiplomacy reads the flag to floor the
// world's drift target at Neutral permanently, so a conquered neighbour rebuilds and defends
// itself but never re-initiates.
//
// FACTION MEMORY (docs/improvement-proposals.md 519-527), tuned as ONE system with the floor
// above: once every fresh pacification THIS TICK is recorded (so two faction-mates pacified in
// the same tick correctly exclude each other below, regardless of which one Map iteration visits
// first — see the second loop), echo a bounded, ONE-TIME stance penalty onto each pacified world's
// remaining UNPACIFIED faction-mates (matched by claim or AI faction — worldFaction, above), plus a
// starmap toast queued the same way checkExpansion already queues its own (expansionNotes). An
// already-pacified faction-mate is excluded — its own floor (this same function, an earlier tick)
// already holds it at Neutral-or-better, so a further hit would only fight that floor for no
// visible effect; a domination spree instead snowballs resistance across whichever of the
// faction's worlds AREN'T yet conquered.
export function checkDomination(galaxy) {
  const active = activeState(galaxy);
  if (active.over) return;
  const freshlyPacified = [];
  for (const [id, state] of galaxy.planets) {
    if (galaxy.pacified.has(id) || hasAiCommand(state)) continue;
    galaxy.pacified.add(id);
    galaxy.pacifyNotes.push(id);
    state.diplomacy.pacified = true;
    freshlyPacified.push({ id, state });
  }
  for (const { id, state } of freshlyPacified) {
    const faction = worldFaction(galaxy, id, state);
    if (!faction || faction === "neutral") continue;
    for (const [mateId, mateState] of galaxy.planets) {
      if (mateId === id || galaxy.pacified.has(mateId)) continue;
      if (worldFaction(galaxy, mateId, mateState) !== faction) continue;
      const dip = mateState.diplomacy;
      if (!dip) continue;
      dip.stance = Math.max(-1, Math.min(1, dip.stance - FACTION_ECHO_PENALTY));
      dip.factionEchoUntil = mateState.time + FACTION_ECHO_DURATION;
    }
    galaxy.expansionNotes.push({ type: "factionEcho", planetId: id, faction });
  }
  if (galaxy.pacified.size >= DOMINATION_TARGET) reachMilestone(galaxy, "domination");
  // The maximal achievement in a play-forever sandbox — pacifying EVERY world — gets its
  // own grander milestone, so the conquest-minded player who pushes hours past the 4-world
  // target isn't met with silence (and a per-conquest toast reading "Conquered 11/4").
  if (galaxy.pacified.size >= galaxy.worlds.length) reachMilestone(galaxy, "domination:all");
}

// FACTION SPREAD across the galaxy. The living galaxy fills up with developing AI factions
// (engine/ai.js aiIndustry); this is how their influence spreads between planets over a long game:
//  • SELF-CLAIM — a world whose AI has developed past CLAIM_DEV flies its own faction's flag.
//  • EXPAND — the single most-developed claimed world (past EXPAND_DEV) colonises the NEAREST still-
//    unclaimed world, claiming it and flipping that world's AI to its colours — so a thriving faction
//    absorbs the fringe and its territory grows across the starmap.
// One cross-planet claim per scan keeps the spread gradual; it's paced by how fast worlds develop
// (minutes), and converges once every world is claimed. Deterministic: development is an entity count,
// distance is fixed planet-x, order is the fixed roster, ties break by world id — no clock, no RNG.
// Reads/writes only galaxy.claims (persisted) + the AI's faction (persisted), so it's save/load-safe.
export const CLAIM_DEV = 3;    // industrial development at which a world's AI faction claims its homeworld
export const EXPAND_DEV = 6;   // ...and at which a thriving world reaches out to colonise a neighbour

export function checkExpansion(galaxy) {
  const claims = galaxy.claims || (galaxy.claims = new Map());
  const notes = galaxy.expansionNotes || (galaxy.expansionNotes = []);
  // SELF-CLAIM: every developed homeworld with a standing base flies its faction's flag (roster order).
  for (const id of galaxy.worlds) {
    if (claims.has(id)) continue;
    const s = galaxy.planets.get(id);
    if (!s || !hasAiCommand(s) || aiDevelopment(s) < CLAIM_DEV) continue;
    const faction = s.players.ai ? s.players.ai.faction : "neutral";
    claims.set(id, faction);
    notes.push({ type: "claim", planetId: id, faction });
  }
  // EXPAND: the single most-developed claimed world past EXPAND_DEV (tie by id) colonises the nearest
  // still-unclaimed world (tie by id). One per scan → gradual spread.
  let exp = null, expDev = EXPAND_DEV - 1e-9;
  for (const id of galaxy.worlds) {
    if (!claims.has(id)) continue;
    const s = galaxy.planets.get(id);
    if (!s) continue;
    const dev = aiDevelopment(s);
    if (dev > expDev || (dev === expDev && exp !== null && id < exp)) { expDev = dev; exp = id; }
  }
  if (exp === null) return;
  let best = null, bestD = Infinity;
  for (const other of galaxy.worlds) {
    if (claims.has(other)) continue;
    // Never colonise the world the player is on, or one they hold a base on. Expansion flips the
    // target world's AI faction (below), and faction feeds LIVE combat/economy multipliers
    // (factions.js → sideMod, read on every hit and haul) — so flipping a world the player is
    // actively fighting on would silently change the enemy's damage/sight/speed/gather mid-battle,
    // with only a starmap toast to show for it. Spread only reaches the unclaimed, unheld fringe.
    if (other === galaxy.activeId || playerFoothold(galaxy.planets.get(other))) continue;
    const d = Math.abs(planetX(other) - planetX(exp));
    if (d < bestD || (d === bestD && best !== null && other < best)) { bestD = d; best = other; }
  }
  if (best === null) return;
  const faction = claims.get(exp);
  claims.set(best, faction);
  const bs = galaxy.planets.get(best);
  if (bs && bs.players.ai) bs.players.ai.faction = faction;   // the colonised world flies the expander's colours
  notes.push({ type: "expand", from: exp, planetId: best, faction });
}

// FACTION MEMORY, allied direction (docs/improvement-proposals.md 519-527) — the mirror of
// checkDomination's grievance echo above: holding an Allied stance on one world lifts the drift
// TARGET of its faction-mates a little (engine/diplomacy.js updateDiplomacy), so befriending a
// bloc pays across its whole territory. Unlike the grievance echo this isn't a one-time event —
// it's a continuously-held CONDITION — so it's recomputed here on the same throttled ~1/sec scan
// stepGalaxy already runs checkDomination/checkExpansion on, rather than latched by an event: a
// world that drifts back down out of Allied stops granting the lift again within about a second.
//
// Stores a RAW COUNT per world (dip.factionWarmth: how many of ITS OTHER faction-mates are
// currently Allied), mirroring aiDevelopment's own raw-count shape — updateDiplomacy applies the
// per-unit weight and cap at the point of use, exactly like aiDevelopment's own
// DEV_SOFT_PER/DEV_SOFT_CAP. Pure (reads only persisted galaxy/diplomacy state) and deterministic
// (fixed roster order, no RNG, no wall clock).
export function updateFactionWarmth(galaxy) {
  const alliedByFaction = new Map();   // faction -> how many of its worlds are currently Allied
  for (const id of galaxy.worlds) {
    const state = galaxy.planets.get(id);
    const dip = state && state.diplomacy;
    if (!dip || dip.stance < ALLIED_THRESHOLD) continue;
    const faction = worldFaction(galaxy, id, state);
    if (!faction || faction === "neutral") continue;
    alliedByFaction.set(faction, (alliedByFaction.get(faction) || 0) + 1);
  }
  for (const id of galaxy.worlds) {
    const state = galaxy.planets.get(id);
    const dip = state && state.diplomacy;
    if (!dip) continue;
    const faction = worldFaction(galaxy, id, state);
    let count = (faction && alliedByFaction.get(faction)) || 0;
    if (dip.stance >= ALLIED_THRESHOLD) count--;   // a world's own Allied stance doesn't lift itself
    dip.factionWarmth = Math.max(0, count);
  }
}

/* ---------- THE RIVAL GATE (docs/improvement-proposals.md "the galaxy's strongest faction races
   its own wonder" + "a fully-teched neighbour races its own Antimatter Gate", merged per the
   Phase 7 plan — two independently-written proposals describing the same feature, reconciled
   into one mechanism here).

   The TRIGGER (whether a world raises and charges its own Gate at all) lives entirely in
   engine/aiIndustry.js's rivalGateEligible/RIVAL_GATE_BUFFER — every qualifying world builds its
   own Gate independently, self-contained, on its own think cycle, exactly like every other
   aiIndustry.js building decision. This module's job is narrower: pick which ONE currently-
   charging world is surfaced to the player as THE Rival Gate (checkExpansion's own most-
   developed, tie-by-id idiom, just above — deterministic, no clock/RNG), track its live charge
   for the starmap, and apply the 'ascension' consequence to EVERY world whose Gate completes —
   not only the tracked one, so two simultaneously-eligible worlds (a rare but real possibility on
   a Hard-heavy galaxy) can't let a second Gate complete unnoticed just because this scan happened
   to be watching a different one.

   THE ASCENSION CONSEQUENCE deliberately COMBINES both twins' proposals rather than picking one:
   the claimed-neighbours burst (Defense twin) AND the hardEdge upgrade + a permanent stance
   ceiling (AI twin) are not mutually exclusive, and the trigger is already double-gated (the
   Strategic tier banked AND Hard/wantsDeepIndustry) — a genuinely rare, hard-earned event, so
   escalating hard on it reads as "the galaxy changed under you" (the Defense twin's own framing)
   rather than as pile-on. Never a defeat: state.over is never touched by any of this. */

// The AI twin's proposal literally says "a permanent stance floor" for the ascension; taken
// literally that would HELP the player (the same shape as diplomacy.js's own APPEASE_FLOOR truce
// line), which contradicts its own framing as a "penalty toward the player" — so this reads it as
// a permanent CEILING instead: the ascended world's stance can never rise back past Wary, no
// matter how the scarcity/development pull on it evolves. Reapplied every scan (below), not a
// one-time snap — updateDiplomacy's own drift would otherwise claw it back up, and the AI twin's
// own "Where" note explicitly keeps this out of engine/diplomacy.js ("needs no change").
//
// EXCEPT once the player has personally pacified that same world (Domination with teeth,
// checkDomination/dip.pacified below): conquest is the more direct, more recent player action, so
// it wins over a stale ascension from before the capital fell. Without this guard the ceiling and
// the pacified floor fight forever — the ceiling reasserts every scan and always wins the raw
// stance value between updateDiplomacy's slower drift ticks, so razing an ascended neighbour's
// Command Center would have no visible effect on its stance, which reads as broken in play.
export const RIVAL_ASCENSION_STANCE_CEILING = PEACE_THRESHOLD;

// The currently-charging AI-owned wonder building on `state`, or null — the same predicate
// aiIndustry.js's own `hasGate` check uses, just read from the outside.
function aiWonderOn(state) {
  for (const b of state.buildings.values())
    if (b.owner === "ai" && BUILDINGS[b.type]?.wonder) return b;
  return null;
}

// Apply the ascension consequence to `worldId` exactly once. Combines both twins' proposals (see
// the header comment above): hardEdge + a permanent stance ceiling, AND an all-at-once claims
// burst — every still-unclaimed world the player hasn't founded/settled on and isn't currently
// standing on (the exact same safety exclusion checkExpansion's own EXPAND step already applies,
// for the exact same reason: flipping a world's faction out from under live combat/economy
// multipliers). Deliberately ALL AT ONCE rather than checkExpansion's own one-per-scan trickle —
// an ascension is a single dramatic event, not a gradual spread.
function applyRivalAscension(galaxy, worldId, state) {
  if (state.players.ai) state.players.ai.upgrades.hardEdge = true;
  (galaxy.rivalAscended || (galaxy.rivalAscended = new Set())).add(worldId);
  if (state.diplomacy && !state.diplomacy.pacified)
    state.diplomacy.stance = Math.min(state.diplomacy.stance, RIVAL_ASCENSION_STANCE_CEILING);

  const claims = galaxy.claims || (galaxy.claims = new Map());
  const notes = galaxy.expansionNotes || (galaxy.expansionNotes = []);
  const faction = state.players.ai ? state.players.ai.faction : "neutral";
  claims.set(worldId, faction);
  for (const other of galaxy.worlds) {
    if (other === worldId || claims.has(other)) continue;
    if (other === galaxy.activeId || playerFoothold(galaxy.planets.get(other))) continue;
    claims.set(other, faction);
    const os = galaxy.planets.get(other);
    if (os && os.players.ai) os.players.ai.faction = faction;
    notes.push({ type: "expand", from: worldId, planetId: other, faction });
  }
}

// The rival-gate scan, run at PROGRESS_CHECK_EVERY cadence from stepGalaxy — the same throttled
// schedule checkDomination/checkExpansion/checkGalaxyProgress already share. Three jobs, in order:
//  1. Ascension sweep — any AI-owned wonder anywhere at full charge ascends exactly once
//     (galaxy.rivalAscended is the idempotency latch), regardless of whether it was the tracked
//     world. Fires the singular "rival-gate" milestone the first time this happens anywhere.
//  2. Reapply the stance ceiling for every already-ascended world — "permanent" in the same sense
//     DOMINATION_TARGET's pacify flag is permanent: reasserted every scan, not a single mutation.
//  3. Selection — if nothing is currently tracked, pick the single most-developed world with a
//     live (charging, not yet ascended) Gate to surface as THE Rival Gate (galaxyStatus below).
// Iterates `galaxy.worlds` (the fixed roster order), never the Map, so neither insertion order nor
// Map iteration can affect the outcome — only aiDevelopment values and the id tie-break can.
export function checkRivalGate(galaxy) {
  const ascended = galaxy.rivalAscended || (galaxy.rivalAscended = new Set());
  const notes = galaxy.rivalGateNotes || (galaxy.rivalGateNotes = []);

  // 1) ASCENSION SWEEP.
  for (const worldId of galaxy.worlds) {
    if (ascended.has(worldId)) continue;
    const state = galaxy.planets.get(worldId);
    if (!state) continue;
    const b = aiWonderOn(state);
    if (!b || (b.charge || 0) < 1) continue;
    applyRivalAscension(galaxy, worldId, state);
    notes.push({ type: "ascended", planetId: worldId });
    reachMilestone(galaxy, "rival-gate");
    if (galaxy.rivalGate && galaxy.rivalGate.worldId === worldId) galaxy.rivalGate = null;
  }

  // 2) REAPPLY the permanent stance ceiling on every ascended world — see the header comment on
  // why this lives here rather than in engine/diplomacy.js's own drift. Skips a world the player
  // has since personally pacified (see the header comment on RIVAL_ASCENSION_STANCE_CEILING) —
  // conquest overrides a stale ascension, not the other way around.
  for (const worldId of ascended) {
    const state = galaxy.planets.get(worldId);
    if (state && state.diplomacy && !state.diplomacy.pacified)
      state.diplomacy.stance = Math.min(state.diplomacy.stance, RIVAL_ASCENSION_STANCE_CEILING);
  }

  // 3) SELECTION — only when nothing is currently tracked. Clear a stale tracked reference first
  // (its building razed out from under it without ascending).
  if (galaxy.rivalGate) {
    const state = galaxy.planets.get(galaxy.rivalGate.worldId);
    const b = state && state.buildings.get(galaxy.rivalGate.buildingId);
    if (!b || b.owner !== "ai" || !BUILDINGS[b.type]?.wonder || (b.charge || 0) >= 1) {
      galaxy.rivalGate = null;
    }
  }
  if (!galaxy.rivalGate) {
    let best = null, bestDev = -Infinity, bestBuilding = null;
    for (const worldId of galaxy.worlds) {
      if (ascended.has(worldId)) continue;
      const state = galaxy.planets.get(worldId);
      if (!state) continue;
      const b = aiWonderOn(state);
      if (!b || (b.charge || 0) >= 1) continue;
      const dev = aiDevelopment(state);
      if (dev > bestDev || (dev === bestDev && best !== null && worldId < best)) { bestDev = dev; best = worldId; bestBuilding = b; }
    }
    if (best !== null) {
      galaxy.rivalGate = { worldId: best, buildingId: bestBuilding.id };
      notes.push({ type: "spotted", planetId: best });
    }
  }
}

// The tracked Rival Gate's live status for the starmap — { worldId, charge } or null. Reads the
// CURRENT charge straight off the building (not a stale snapshot), so a caller polling this every
// frame always sees the live number.
function rivalGateStatus(galaxy) {
  if (!galaxy.rivalGate) return null;
  const state = galaxy.planets.get(galaxy.rivalGate.worldId);
  const b = state && state.buildings.get(galaxy.rivalGate.buildingId);
  if (!b) return null;
  return { worldId: galaxy.rivalGate.worldId, charge: b.charge || 0 };
}

// A pure snapshot of the galaxy for the starmap: per-world status (your active
// seat / a colony you hold / unexplored) and, for worlds you've been to, the
// neighbour's stance. Plus the visited count and credits.
export function galaxyStatus(galaxy) {
  // Every world simulates, but the player only SEES one they've REACHED (`discovered`). An
  // undiscovered world reads "unexplored" and hides its neighbour's stance, exactly as before the
  // living galaxy — the difference is now invisible until you visit. Old saves default to the
  // instantiated set (which for them was precisely the visited worlds).
  const discovered = galaxy.discovered || new Set(galaxy.planets.keys());
  return {
    credits: galaxy.credits,
    activeId: galaxy.activeId,
    visited: discovered.size,
    total: galaxy.worlds.length,
    pacified: galaxy.pacified ? galaxy.pacified.size : 0,   // Domination progress: worlds conquered
    dominationTarget: DOMINATION_TARGET,
    rivalGate: rivalGateStatus(galaxy),   // the tracked Rival Gate's { worldId, charge }, or null — starmap alert
    worlds: galaxy.worlds.map(id => {
      const seen = discovered.has(id);
      const s = seen ? galaxy.planets.get(id) : null;
      let status = "unexplored", income = 0;
      const pacified = !!(galaxy.pacified && galaxy.pacified.has(id));
      // LABEL AND INCOME ARE DECIDED INDEPENDENTLY. "pacified" outranks colony/contested as a
      // label, but it is NOT a reason to report no income: sweepColonies pays a conquered world
      // BOTH halves (its buildings' passive income AND the occupation dividend, additively), so
      // a `pacified` arm that short-circuited before the income line made the player's best-paying
      // world read 0 on the starmap. What's reported here mirrors what sweepColonies actually
      // banks, dividend included and background-only — the seat earns nothing there
      // (`if (!state.background) continue;`) and so must report nothing here.
      if (id === galaxy.activeId) status = "seat";
      else if (s) {
        const buildings = playerBuildingCount(s);
        // A world you've been to is a "colony" only while you still hold a
        // building there; once razed it's "contested" — visited but no longer
        // yours (so the map doesn't keep calling a lost world your colony).
        status = pacified ? "pacified" : (buildings > 0 ? "colony" : "contested");
        income = s.background                                                     // credits/min (capped, turret-excluded)
          ? Math.round((incomeBuildingCount(s) * COLONY_INCOME_PER_BUILDING + (pacified ? PACIFIED_INCOME : 0)) * 60)
          : 0;
      }
      else if (pacified) status = "pacified";   // conquered but not in `discovered` (so `s` is null) — still label it
      // Industry/Tech ratings (data.js) drive factory speed + research speed and
      // finished-good prices — surfaced so "where to settle/jump" is an informed call.
      const p = PLANETS.find(pl => pl.id === id);
      // `faction` is the world's fixed cultural origin (data.js PLANETS); `controlledBy` is the DYNAMIC
      // faction that has claimed it via expansion (checkExpansion) — the spreading galactic politics
      // shown on the starmap. Visible galaxy-wide (it's sphere-of-influence news, not tactical intel).
      return { id, status, income, pacified, stance: seen && s && s.diplomacy ? s.diplomacy.stance : null,
        industry: p ? p.industry : 5, tech: p ? p.tech : 5, faction: p ? p.faction : null,
        controlledBy: (galaxy.claims && galaxy.claims.get(id)) || null };
    }),
  };
}

// The fortified Capital: an upgraded Command Center with double HP. Like every deployed
// base it is permanent — it never travels (interplanetary jumps carry a colony ship, not
// a base; jumpVessel/jumpCapital) — so the Capital is your hardened anchor world. One
// per owner; the flag also drives its gold ring on the map (render.js).
export const CAPITAL_UPGRADE_COST = { ore: 400 };
export const CAPITAL_HP_MULT = 2;

// Improve a Command Center into your Capital: pay the cost, mark it, and scale its HP
// (and current HP, preserving any battle damage as a fraction) by CAPITAL_HP_MULT.
// Odyssey-only, one Capital per owner, not on a still-constructing CC. Deterministic —
// pure state mutation, no clock/RNG. Returns whether the upgrade happened.
export function upgradeToCapital(state, building) {
  if (!building || building.type !== "command" || building.constructing || building.capital) return false;
  const owner = building.owner;
  for (const b of state.buildings.values())
    if (b.owner === owner && b.capital) return false;             // only one Capital
  const res = state.players[owner].resources;
  for (const com in CAPITAL_UPGRADE_COST) if ((res[com] || 0) < CAPITAL_UPGRADE_COST[com]) return false;
  for (const com in CAPITAL_UPGRADE_COST) res[com] -= CAPITAL_UPGRADE_COST[com];
  building.capital = true;
  building.maxHp = Math.round(building.maxHp * CAPITAL_HP_MULT);
  building.hp = Math.round(building.hp * CAPITAL_HP_MULT);        // keeps the damage fraction
  return true;
}

// The Spaceport comes in THREE tiers. Its jump capacity — how much fleet it can launch
// at once, measured in ship POPULATION (supply cost), not head-count — scales with the
// tier, so a very large army has to cross in several jumps through a small pad, or you
// upgrade to a bigger one. Capacity is indexed by tier (1..3); index 0 is unused.
export const SPACEPORT_MAX_TIER = 3;
export const SPACEPORT_CAPACITY = [0, 12, 24, 40];              // supply carried per jump, by tier
export const SPACEPORT_UPGRADE_COST = { 2: { ore: 250 }, 3: { ore: 500 } };   // ore to reach a tier (escalating)

// A Spaceport's tier (defaults to 1 for a fresh pad or a pre-tier save) and the per-jump
// capacity it grants.
export const spaceportTier = b => Math.min(SPACEPORT_MAX_TIER, Math.max(1, b.tier || 1));
export const jumpCapacity = b => SPACEPORT_CAPACITY[spaceportTier(b)];

// Upgrade a Spaceport one tier (max 3): pay the ore, bump the tier, raising its per-jump
// capacity. Odyssey-only, deterministic (pure state mutation — no clock/RNG), like the
// Capital fortification. Returns whether it happened (refused when already max, still
// under construction, or unaffordable).
export function upgradeSpaceport(state, building) {
  if (!building || building.type !== "spaceport" || building.constructing) return false;
  const tier = spaceportTier(building);
  if (tier >= SPACEPORT_MAX_TIER) return false;
  const cost = SPACEPORT_UPGRADE_COST[tier + 1];
  const res = state.players[building.owner].resources;
  for (const com in cost) if ((res[com] || 0) < cost[com]) return false;
  for (const com in cost) res[com] -= cost[com];
  building.tier = tier + 1;
  return true;
}

const unitSupply = u => UNITS[u.type]?.supplyCost || 0;

// What counts as a launch-ready pad: the player's own, finished Spaceport. Defined once so
// jumpVessel/canJump/jumpCapital can't drift on the predicate (owner + type + built).
const isPlayerSpaceport = b => b.owner === "player" && b.type === "spaceport" && !b.constructing;
// EVERY launch-ready pad the player holds on this world, not just one — a world can carry
// more than one completed Spaceport (a second pad built for extra jump throughput, or while
// upgrading the first). Sorted by id for a stable, deterministic iteration order (matches the
// codebase's usual entity tie-break), so which pad "goes first" below can never depend on Map
// insertion order.
export const playerSpaceports = state => [...state.buildings.values()].filter(isPlayerSpaceport).sort((a, b) => (a.id < b.id ? -1 : 1));

// The colony ship that would carry an interplanetary jump: a player colony ship staged within
// JUMP_LOAD_RADIUS of ANY completed Spaceport (not just one — see playerSpaceports). A jump
// relocates the SHIP (and the rest of the staged expedition) — NOT a deployed base. Deployed
// Command Centers are permanent: the world you leave keeps them and becomes a background
// colony. Deploy the ship at the destination to found your new base there. Null when no ship
// is on any pad.
export function jumpVessel(state) {
  const spaceports = playerSpaceports(state);
  if (!spaceports.length) return null;
  for (const u of state.units.values())
    if (u.owner === "player" && u.type === "colonyship"
        && spaceports.some(sp => Math.hypot(u.x - sp.x, u.y - sp.y) <= JUMP_LOAD_RADIUS)) return u;
  return null;
}

// Can the player launch a jump from this world? — just a completed Spaceport. No colony
// ship is required: a jump can carry one (to settle a new world), or an army (to reinforce
// a colony), or nothing (to hop back and control a world you already hold). jumpVessel
// stays as an informational helper (is a ship loaded?) for the HUD, not a gate.
export function canJump(state) {
  return playerSpaceports(state).length > 0;
}

// A world where the player still has a foothold — a Command Center or an undeployed colony ship
// (the same notion as the galaxy defeat/relief check). It's a world a stranded force can fall
// back to and actually operate from: build, re-arm, or fetch a colony ship.
const playerFoothold = state => !!state && ([...state.buildings.values()]
  .some(b => b.owner === "player" && b.type === "command") || hasColonyShip(state, "player"));

// Can the player jump to `destId` right now? A Spaceport on the CURRENT world lets you jump
// anywhere (expand to a new world or hop to a held one). WITHOUT a Spaceport here you can still
// FALL BACK to any world where you have a foothold — so a force stranded on a portless world
// (e.g. you hopped an army over and forgot the colony ship) is never trapped: it can always
// retreat to a base it holds and bring the ship back. Only opening a NEW frontier needs a
// Spaceport here.
export function canJumpTo(galaxy, destId) {
  if (destId === galaxy.activeId) return false;
  return canJump(activeState(galaxy)) || playerFoothold(galaxy.planets.get(destId));
}

const planetX = id => PLANETS.find(p => p.id === id)?.x ?? 0;

// The Spaceport's tier doesn't just lift more fleet per jump (SPACEPORT_CAPACITY) — a bigger
// pad also burns new-world fuel more efficiently. Indexed by tier (1..3) like SPACEPORT_CAPACITY;
// index 0 (no completed pad at all) is the same x1.0 as a fresh Tier-1 pad, so building the FIRST
// Spaceport is a pure capability unlock and never itself a hidden fuel bump.
export const FUEL_DISCOUNT_BY_TIER = [1, 1, 0.85, 0.7];

// The fuel a jump to `destId` costs: FREE to a world you already hold (any world you've
// visited — a colony you're returning to, reinforcing, or re-settling), so bouncing between
// your own worlds to defend or ferry a colony ship stays friction-free. Reaching a NEW world
// costs fuel that SCALES WITH DISTANCE across the frontier (data.js planet x, 0..~18): a near
// hop is close to the base fee, settling a distant world is a real, growing credit sink and a
// strategic choice — so exploration spend isn't the old flat, quickly-capped ~4,000 lifetime.
// The origin's best COMPLETED Spaceport tier (playerSpaceports(from), not the jump's actual
// destination pad — this is about YOUR launch infrastructure) cuts that distance-scaled fuel by
// FUEL_DISCOUNT_BY_TIER, so upgrading the pad is a real economic choice, not just a capacity knob.
export function jumpCost(galaxy, destId) {
  // Free to a world you've already REACHED (a colony you're returning to, reinforcing, or
  // re-settling). Since the living galaxy instantiates every world up front, "reached" is the
  // player-facing `discovered` set, NOT merely "the state object exists" — else every jump would be
  // free. Old saves (no discovered set) fall back to planets.has, which for them meant the same thing.
  const known = galaxy.discovered ? galaxy.discovered.has(destId) : galaxy.planets.has(destId);
  if (known || playerFoothold(galaxy.planets.get(destId))) return 0;   // reached before, or a base you still hold → free
  const dist = Math.abs(planetX(destId) - planetX(galaxy.activeId));
  const tier = playerSpaceports(activeState(galaxy)).reduce((max, sp) => Math.max(max, spaceportTier(sp)), 0);
  const discount = FUEL_DISCOUNT_BY_TIER[tier] ?? 1;
  return Math.round(JUMP_COST * discount * (0.8 + dist / 18));   // ~340 next-door … ~720 across the map, before the pad discount
}

// The player units staged near a Spaceport — the expedition that rides along on a
// jump. One definition, so the HUD's preview count and the jump's actual move can
// never disagree about what leaves.
export function stagedRiders(state, spaceport) {
  const out = [];
  for (const u of state.units.values())
    // A ship assigned to a Freight Lane (u.laneId, see runLanes below) is physically parked here
    // as a STANDING investment, not a free ride — excluded so it never gets swept off-world on the
    // next jump out from under its lane.
    if (u.owner === "player" && !u.laneId && Math.hypot(u.x - spaceport.x, u.y - spaceport.y) <= JUMP_LOAD_RADIUS) out.push(u);
  return out;
}

// What actually LAUNCHES on one jump, capped by the pad's tier capacity. From the units
// staged near the Spaceport, fill the hold closest-to-the-pad first by ship population
// (supply) until the next unit wouldn't fit — a skip-not-break fill, so a heavy unit that
// doesn't fit is passed over for lighter ones behind it rather than blocking them (workers
// are supply 1, so a fleet always makes progress and nothing softlocks). The overflow
// waits at the pad for the next jump. Pure + deterministic: closest-first, ties broken by
// entity id. One definition, so the HUD preview and the jump's actual move always agree.
export function jumpManifest(state, spaceport) {
  const capacity = jumpCapacity(spaceport);
  const staged = stagedRiders(state, spaceport)
    .map(u => ({ u, d: Math.hypot(u.x - spaceport.x, u.y - spaceport.y) }))
    .sort((a, b) => a.d - b.d || (a.u.id < b.u.id ? -1 : 1));
  const riders = [];
  let used = 0;
  for (const { u } of staged) {
    const s = unitSupply(u);
    if (used + s <= capacity) { riders.push(u); used += s; }
  }
  const stagedSupply = staged.reduce((t, { u }) => t + unitSupply(u), 0);
  return { riders, capacity, used, stagedSupply, staged: staged.length, leftBehind: staged.length - riders.length };
}

// EVERY player Spaceport's staged riders, combined into one launch. With a single completed
// pad this is byte-identical to jumpManifest(state, thatPad) — every candidate unit's nearest
// pad is trivially the one pad, so the same closest-first fill runs unchanged. With more than
// one pad, each staged unit boards through its NEAREST pad (ties broken by pad id, matching
// the unit tie-break below), and each pad fills its own capacity independently — a unit that
// doesn't fit at its nearest pad is left behind rather than spilling over to another pad's
// spare capacity (a simple, deterministic policy, not a globally-optimal pack across pads).
// jumpCapital is the only caller: this is what actually determines who jumps, so it has to
// count every completed pad, not just one — a second Spaceport's staged units used to be
// silently ignored on every jump, because only the first Spaceport found (Map iteration
// order) was ever consulted.
export function jumpManifestAll(state) {
  const spaceports = playerSpaceports(state);
  if (!spaceports.length) return { riders: [], capacity: 0, used: 0, stagedSupply: 0, staged: 0, leftBehind: 0 };

  // Every player unit within range of at least one pad, tagged with its NEAREST pad so it can
  // never be double-counted across two overlapping catchment radii.
  const byNearestPad = new Map(spaceports.map(sp => [sp.id, []]));
  for (const u of state.units.values()) {
    // A Freight Lane's assigned ship is busy standing infrastructure, not a jump rider — see
    // stagedRiders' identical exclusion above; jumpManifestAll can't just call stagedRiders (it
    // needs the nearest-pad tagging below), so the check is repeated here.
    if (u.owner !== "player" || u.laneId) continue;
    let nearest = null, nearestD = Infinity;
    for (const sp of spaceports) {
      const d = Math.hypot(u.x - sp.x, u.y - sp.y);
      if (d > JUMP_LOAD_RADIUS) continue;
      if (d < nearestD || (d === nearestD && sp.id < nearest.id)) { nearest = sp; nearestD = d; }
    }
    if (nearest) byNearestPad.get(nearest.id).push({ u, d: nearestD });
  }

  const riders = [];
  let capacity = 0, used = 0, stagedSupply = 0, staged = 0;
  for (const sp of spaceports) {
    const cap = jumpCapacity(sp);
    capacity += cap;
    const candidates = byNearestPad.get(sp.id).sort((a, b) => a.d - b.d || (a.u.id < b.u.id ? -1 : 1));
    let padUsed = 0;
    for (const { u } of candidates) {
      const s = unitSupply(u);
      if (padUsed + s <= cap) { riders.push(u); padUsed += s; }
    }
    used += padUsed;
    staged += candidates.length;
    stagedSupply += candidates.reduce((t, { u }) => t + unitSupply(u), 0);
  }
  return { riders, capacity, used, stagedSupply, staged, leftBehind: staged - riders.length };
}

// A jump carries a CARGO HOLD of manufactured goods to the destination, so a run of production on
// one world can be sold on another — the make-here/sell-there loop (produced goods price
// differently per world, engine/market.js). The hold's SIZE is the combined cargoHold of the cargo
// ships (engine/entities.js: hauler/heavyhauler/bulkfreighter) staged for the jump — no cargo ship
// means no freight. Loaded most-valuable-first (data.js COM.base: machinery 250 > electronics 95 >
// alloys 80 > spice 34 > metals 22). spice is here so Verdani's agri surplus can be exported and
// sold dear on an industrial world (it's cheap where it's mined, precious where it isn't); cheaper
// raws aren't worth a cargo slot and strategic goods stay put.
// Exported so runLanes' commodity-filter fallback (below) and any future caller can share the
// exact same default ordering cargoManifest already uses — one most-valuable-first list, not two
// that could drift.
export const CARGO_GOODS = ["machinery", "electronics", "alloys", "spice", "metals"];

// The freight capacity a set of riders provides — the summed cargoHold of the cargo ships among
// them (anything without a cargoHold carries nothing). Pure.
export function freightCapacity(riders) {
  let cap = 0;
  for (const u of riders) cap += UNITS[u.type]?.cargoHold || 0;
  return cap;
}

// What `capacity` units of hold would haul from `from`, as { good: qty } — most-valuable-first, for
// the HUD preview and the jump itself (so the shown manifest and the moved goods can never
// disagree). capacity 0 (no cargo ship staged) → an empty hold. `goods` lets a caller restrict the
// pick to a subset (runLanes' commodity filter, below) while walking CARGO_GOODS' own
// most-valuable-first order; omitted, it's the exact same list every existing caller already got.
export function cargoManifest(from, capacity = 0, goods = CARGO_GOODS) {
  let room = Math.max(0, capacity | 0);
  const src = from.players.player.resources;
  const manifest = {};
  for (const com of goods) {
    if (room <= 0) break;
    const move = Math.min(Math.floor(src[com] || 0), room);
    if (move > 0) { manifest[com] = move; room -= move; }
  }
  return manifest;
}

/* ---------- Freight Lanes: standing shipping between held worlds ---------- */

// How often (in galaxy ticks) an active lane moves cargo — an integer schedule keyed on
// galaxy.tick, exactly like BG_STEP/PROGRESS_CHECK_EVERY above, so it's deterministic and
// independent of frame dt. A lane is a slow drip (real sim minutes, at the 20Hz cadence the rest
// of this scheduler assumes), not an instant transfer — it's standing infrastructure, not a
// one-off haul.
export const LANE_PERIOD = 200;   // ~10 sim-seconds at 20Hz

// Create a standing lane from `from` to `to`, filtered to `commodities` (empty/omitted = every
// CARGO_GOODS commodity, most-valuable-first — see runLanes). Refused for a same-world "lane" or
// an unrecognised world on either end. Returns the new lane (also pushed onto galaxy.lanes), or
// null on refusal.
export function createLane(galaxy, from, to, commodities = []) {
  if (from === to || !galaxy.planets.has(from) || !galaxy.planets.has(to)) return null;
  const lanes = galaxy.lanes || (galaxy.lanes = []);
  const lane = { id: "lane" + (galaxy.laneSeq = (galaxy.laneSeq || 0) + 1), from, to, commodities: [...commodities], shipIds: [] };
  lanes.push(lane);
  return lane;
}

// Disband a lane and free every ship it held busy (clears their laneId flag). Returns whether a
// lane with that id existed.
export function deleteLane(galaxy, laneId) {
  const lanes = galaxy.lanes;
  if (!lanes) return false;
  const idx = lanes.findIndex(l => l.id === laneId);
  if (idx < 0) return false;
  const lane = lanes[idx];
  const from = galaxy.planets.get(lane.from);
  if (from) for (const id of lane.shipIds) { const u = from.units.get(id); if (u) delete u.laneId; }
  lanes.splice(idx, 1);
  return true;
}

// Assign a player freighter parked on the lane's SOURCE world to it — it must be a real cargo
// ship (UNITS[type].cargoHold) and currently standing within JUMP_LOAD_RADIUS of one of that
// world's own completed Spaceports (reusing the exact same catchment jumpVessel/stagedRiders use
// — this is deliberately the same "at the pad" test, not a new one). A ship already on another
// lane is moved over rather than double-booked. Returns whether the assignment happened.
export function assignShipToLane(galaxy, laneId, unitId) {
  const lane = (galaxy.lanes || []).find(l => l.id === laneId);
  if (!lane) return false;
  const from = galaxy.planets.get(lane.from);
  const u = from && from.units.get(unitId);
  if (!u || u.owner !== "player" || !UNITS[u.type]?.cargoHold) return false;
  const pads = playerSpaceports(from);
  if (!pads.length || !pads.some(p => Math.hypot(u.x - p.x, u.y - p.y) <= JUMP_LOAD_RADIUS)) return false;
  if (u.laneId && u.laneId !== laneId) unassignShipFromLane(galaxy, u.laneId, unitId);
  if (!lane.shipIds.includes(unitId)) lane.shipIds.push(unitId);
  u.laneId = laneId;
  return true;
}

// Pull a ship off a lane, freeing it for jumps/other orders again. Returns whether it was found.
export function unassignShipFromLane(galaxy, laneId, unitId) {
  const lane = (galaxy.lanes || []).find(l => l.id === laneId);
  if (!lane) return false;
  const idx = lane.shipIds.indexOf(unitId);
  if (idx < 0) return false;
  lane.shipIds.splice(idx, 1);
  const from = galaxy.planets.get(lane.from);
  const u = from && from.units.get(unitId);
  if (u && u.laneId === laneId) delete u.laneId;
  return true;
}

// Run every standing lane one delivery cycle: revalidate its assigned ships (still alive, still a
// player freighter, still parked near one of the source world's own Spaceports — exactly
// assignShipToLane's own test, run again every cycle so a ship that wandered off, died, or was
// reassigned quietly drops out rather than silently keep "shipping" from wherever it ended up),
// then move min(the survivors' combined cargoHold, the filtered stock on hand) straight from the
// source world's treasury to the destination's — a lane never touches a ship's own .freight hold,
// it's a capacity NUMBER standing in for "how much this route can carry today", not a physical
// load/unload cycle. Called from stepGalaxy on the LANE_PERIOD schedule. Deterministic: galaxy.lanes
// and each lane's shipIds are plain arrays in insertion order, and cargoManifest's own commodity
// walk is a fixed list — nothing here reads a clock, RNG, or Map/Set iteration order.
export function runLanes(galaxy) {
  const lanes = galaxy.lanes;
  if (!lanes || !lanes.length) return;
  for (const lane of lanes) {
    const from = galaxy.planets.get(lane.from);
    const to = galaxy.planets.get(lane.to);
    if (!from || !to) continue;
    const pads = playerSpaceports(from);
    const kept = [];
    for (const id of lane.shipIds) {
      const u = from.units.get(id);
      const valid = u && u.owner === "player" && UNITS[u.type]?.cargoHold
        && pads.some(p => Math.hypot(u.x - p.x, u.y - p.y) <= JUMP_LOAD_RADIUS);
      if (valid) { u.laneId = lane.id; kept.push(id); }
      else if (u) delete u.laneId;
    }
    lane.shipIds = kept;
    if (!kept.length) continue;
    const capacity = kept.reduce((sum, id) => sum + (UNITS[from.units.get(id).type]?.cargoHold || 0), 0);
    if (capacity <= 0) continue;
    const goods = lane.commodities && lane.commodities.length ? lane.commodities : CARGO_GOODS;
    const manifest = cargoManifest(from, capacity, goods);
    const src = from.players.player.resources, dst = to.players.player.resources;
    for (const com in manifest) {
      src[com] -= manifest[com];
      dst[com] = (dst[com] || 0) + manifest[com];
    }
  }
}

// freightUsed/freightRoom (how full a freighter's hold is, and its remaining room) now live in
// entities.js — engine/haul.js needs them for the worker↔freighter physical loading path and can't
// import this module (galaxy.js -> sim.js -> haul.js would cycle back here). Re-exported (imported
// above) so every existing caller of these two from "./galaxy.js" is unaffected.
export { freightUsed, freightRoom };

// Load up to `qty` of commodity `com` from the CURRENT world's player stockpile into a freighter's
// hold, clamped to the hold's room and what's actually in stock. Returns the amount loaded (0 if
// it's not a player freighter, the commodity is unknown, or nothing could move). The goods leave
// the stockpile immediately — they're aboard the ship now, to ride the next jump.
export function loadFreighter(state, unitId, com, qty) {
  const u = state.units.get(unitId);
  if (!u || u.owner !== "player" || !u.freight || !COM[com] || !(UNITS[u.type]?.cargoHold)) return 0;
  const res = state.players.player.resources;
  const move = Math.min(Math.floor(qty) || 0, freightRoom(u), Math.floor(res[com] || 0));
  if (move <= 0) return 0;
  res[com] -= move;
  u.freight[com] = (u.freight[com] || 0) + move;
  return move;
}

// Unload up to `qty` of `com` from a freighter's hold back onto the CURRENT world's player
// stockpile. Returns the amount unloaded. Works wherever the ship is — the origin (to undo a
// load) or a world it jumped to (to bank the haul and sell it at that market).
export function unloadFreighter(state, unitId, com, qty) {
  const u = state.units.get(unitId);
  if (!u || u.owner !== "player" || !u.freight) return 0;
  const move = Math.min(Math.floor(qty) || 0, u.freight[com] || 0);
  if (move <= 0) return 0;
  u.freight[com] -= move;
  if (u.freight[com] <= 0) delete u.freight[com];
  const res = state.players.player.resources;
  res[com] = (res[com] || 0) + move;
  return move;
}

// A jump delivers every staged freighter's HOLD to the destination colony's stockpile — exactly
// what the player hand-loaded (loadFreighter/unloadFreighter), nothing more. A freighter left
// empty carries nothing across; it does NOT auto-fill from the origin stockpile any more (the
// previous "empty hold → most-valuable-first" default made a round trip actively work against a
// player who wanted to haul on the way back only: land empty at a destination, jump home before
// reloading, and the empty ship would eagerly scoop up local goods and carry them right back,
// silently undoing a delivery the player had just made — see the reported case in git history).
// Manual control now means exactly that: load what you want shipped, or it stays put. Returns the
// combined delivered manifest (for the arrival toast). `riders` are the units that lifted off;
// non-freighters (no hold) are skipped.
function loadCargo(from, dest, riders) {
  const dst = dest.players.player.resources;
  const delivered = {};
  for (const u of riders) {
    if (!u.freight || !(UNITS[u.type]?.cargoHold)) continue;
    for (const com in u.freight) {                               // deliver the hold to the destination colony
      dst[com] = (dst[com] || 0) + u.freight[com];
      delivered[com] = (delivered[com] || 0) + u.freight[com];
    }
    u.freight = {};
  }
  return delivered;
}

// A minimap pick is necessarily coarse — that's the whole point of it (a blind landing on a
// world with no beacon should feel like one, not a precise coordinate entry). So a pick resolves
// to the NEAREST ALLOWED LANDING SITE: a fixed grid of them across the world's middle, plus the
// margin ring itself at each edge. The margin comfortably exceeds the widest rider-spawn ring
// jumpCapital uses below (46 + 2*18 = 82), so a picked corner can never spawn a unit off the map.
//
// NEAREST-SITE, NOT ROUND-THEN-CLAMP. This used to round onto the grid and then clamp into the
// margin, which made it NOT IDEMPOTENT: the clamp bound (100) is not a multiple of the grid (160),
// so the whole edge band collapsed onto an off-lattice 100 that re-snapped to 160. Feeding the
// function its own output moved the point again — 161 of the 1601 x-values on a 1600-wide map.
// That is a live trap for callers, because the obvious way to build a picker is "snap to show the
// player where they'll land, then send THAT point": the confirmed point got snapped a second time
// and the colony touched down 60 units from the ring the player was looking at, with nothing on
// screen to say so. (landingPicker.js dodges it by forwarding the RAW point and snapping once —
// which is no longer something a caller has to know.)
//
// Choosing the nearest site instead fixes that WITHOUT changing where anyone can land: the set of
// reachable outputs is exactly what round-then-clamp already produced — {margin, ...grid...,
// span-margin} — so no landing area is lost or gained, and no balance changes. All that changes is
// which clicks map to which site, and only inside the edge bands, where a click now resolves to
// the site actually closest to it (x=90 lands at 100, where it used to skip out to 160). Every
// output is a fixed point, so snap(snap(p)) === snap(p) everywhere.
export const LANDING_PICK_GRID = 160;
const LANDING_PICK_MARGIN = 100;

// Every landing site along one axis of length `span`, ascending: the near margin, the grid points
// strictly inside it, and the far margin. Exported through landingSites below so a picker can OFFER
// these rather than guess at them — "the grid" alone is not the answer (a click at 90 belongs to
// the margin site at 100, not to the grid point at 160), which is exactly the kind of 60-unit-wrong
// lattice a caller would otherwise build for itself.
function axisLandingSites(span) {
  const lo = LANDING_PICK_MARGIN, hi = span - LANDING_PICK_MARGIN;
  // A world narrower than its own two margins has no valid band at all. Nothing generates one
  // (engine/map.js maps are far wider), but this is reachable from any caller's map object, and a
  // single fixed site keeps the "every output is a fixed point" promise true even there.
  if (hi <= lo) return [Math.round(span / 2)];
  const sites = [lo];
  for (let v = Math.ceil(lo / LANDING_PICK_GRID) * LANDING_PICK_GRID; v < hi; v += LANDING_PICK_GRID)
    if (v > lo) sites.push(v);
  sites.push(hi);
  return sites;
}

// The allowed landing sites for `map`, as the two axes' independent site lists (any xs × ys pair is
// a valid landing point). Purely derived — no clock, no RNG, no state.
export function landingSites(map) {
  return { xs: axisLandingSites(num(map.width)), ys: axisLandingSites(num(map.height)) };
}

export function snapLandingPoint(map, x, y) {
  // Nearest site wins; a tie goes to the FARTHER-OUT one, matching the way the old Math.round
  // broke its own half-way ties upward (a click exactly between two sites is arbitrary either way).
  const snap = (v, sites) => {
    let best = sites[0];
    for (const s of sites) if (Math.abs(v - s) <= Math.abs(v - best)) best = s;
    return best;
  };
  const { xs, ys } = landingSites(map);
  return { x: snap(num(x), xs), y: snap(num(y), ys) };
}
function num(v) { const n = Number(v); return Number.isFinite(n) ? n : 0; }

// Where a jump's riders actually touch down on `dest`. In priority order:
//   1. The player's own Spaceport most recently used to LAND here (`lastLanding`, a galaxy.time
//      stamp — see below) — a return trip comes in at your own infrastructure, not the world's
//      fixed generation-time anchor, which could by now be nowhere near where you actually
//      built. Ties (never-landed-at pads) fall to the lowest id, same as every other tie-break
//      in this file.
//   2. No Spaceport stands on `dest` at all (never settled, or one stood here and was since
//      razed): there's no beacon to home in on, so the player chose an approximate spot
//      themselves (the landingPicker.js "blind minimap" screen) — `landingPoint`, already
//      fuzzed by snapLandingPoint above before it ever reaches here.
//   3. Neither — an old save, or a caller that skipped the picker: the planet's fixed
//      generation-time anchor, exactly today's (pre-this-feature) behaviour.
function landingZone(dest, landingPoint) {
  const pads = playerSpaceports(dest);
  if (pads.length) {
    let best = pads[0];
    for (const p of pads) if ((p.lastLanding || 0) > (best.lastLanding || 0)) best = p;
    return { x: best.x, y: best.y, pad: best };
  }
  if (landingPoint && Number.isFinite(landingPoint.x) && Number.isFinite(landingPoint.y)) {
    const p = snapLandingPoint(dest.map, landingPoint.x, landingPoint.y);
    return { x: p.x, y: p.y, pad: null };
  }
  return { x: dest.map.bases.player.x, y: dest.map.bases.player.y, pad: null };
}

// Launch an interplanetary jump to `destId`: player units move to the destination's landing
// zone along with the cargo hold. NO deployed base moves — the origin keeps ALL its buildings
// and becomes a background colony. Costs fuel only for a NEW world (jumpCost); returning to a
// held world is free.
//
// Two modes:
//   • With a Spaceport HERE — the normal launch: the capacity-capped expedition staged near the
//     pad (a colony ship to settle, an army to reinforce, or nothing) rides along.
//   • WITHOUT a Spaceport, falling back to a world you ALREADY HOLD — a pure CONTROL SWITCH that
//     moves NO units: with no launch pad there's no way to load a fleet, so the force you left on
//     this world STAYS PUT. This is the catch-22 escape (hop back to a base to fetch a colony
//     ship) WITHOUT dragging a garrison home — you bring the ship to the stranded force, not the
//     force back. To actually ferry units off a world, build a Spaceport there. See canJumpTo.
//
// `opts.landingPoint` (world coords) is consulted ONLY when `dest` has no player Spaceport of
// its own — see landingZone above. Ignored (harmlessly) whenever a pad is standing, and never
// required: every other case falls back cleanly on its own.
//
// Returns a summary, or null if the jump can't run (no way to reach the destination, same world,
// or too poor to fuel a new-world jump).
export function jumpCapital(galaxy, destId, opts = {}) {
  const from = activeState(galaxy);
  if (destId === galaxy.activeId) return null;
  const hasSpaceport = playerSpaceports(from).length > 0;
  const canFallBack = playerFoothold(galaxy.planets.get(destId));   // a world you hold a base on
  if (!hasSpaceport && !canFallBack) return null;                   // no port here and nowhere to fall back → can't jump
  const cost = jumpCost(galaxy, destId);
  if (galaxy.credits < cost) return null;

  // A Spaceport (or several — every completed pad's staged units ride, not just one) → the
  // combined capacity-capped expedition. No Spaceport (a fallback) → nothing rides: a control
  // switch that leaves every unit on this world where it is.
  let riders = [], leftBehind = 0;
  if (hasSpaceport) ({ riders, leftBehind } = jumpManifestAll(from));
  galaxy.credits -= cost;   // fuel — free to a world you already hold

  const dest = galaxy.planets.get(destId) || addPlanet(galaxy, destId, { unsettled: true });
  const { x: lzx, y: lzy, pad } = landingZone(dest, opts.landingPoint);
  const nextId = () => "g" + (galaxy.entitySeq = (galaxy.entitySeq || 0) + 1);   // fresh ids: no cross-state collision

  riders.forEach((u, i) => {
    from.units.delete(u.id);
    const a = (i / Math.max(1, riders.length)) * Math.PI * 2, ring = 46 + (i % 3) * 18;
    u.id = nextId(); u.x = lzx + Math.cos(a) * ring; u.y = lzy + Math.sin(a) * ring;
    u.order = null; u.orderQueue = [];
    dest.units.set(u.id, u);
  });
  // Remember this pad for the NEXT return trip (landingZone above prefers whichever pad has
  // the highest `lastLanding`). Only worth stamping when riders actually landed — an empty
  // control-switch hop (see the file header comment) doesn't touch anything here.
  if (pad && riders.length) pad.lastLanding = galaxy.time || 0;

  const cargo = loadCargo(from, dest, riders);   // deliver each staged freighter's hold — hand-loaded only

  from.selection = []; dest.selection = [];
  from.background = true;    // the world you left keeps evolving on its own
  dest.background = false;   // the destination is now your active seat
  galaxy.activeId = destId;
  (galaxy.discovered || (galaxy.discovered = new Set())).add(destId);   // now REACHED — a free return-jump, and it shows on the starmap
  updateFog(dest, dest.fog, "player");
  updateFog(dest, dest.fogAI, "ai");
  updateFog(from, from.fog, "player");
  return { destId, riders: riders.length, leftBehind, cargo };   // leftBehind: staged units the pad couldn't fit this trip
}