Redefine formation leader as first-selected unit, add persistent follow, speed cap, and drag-to-face

Reworks the formation system per feedback on PR #9:

- Leader is now whichever unit the player selected first (the one others
get added to), not a stat-based pick. pickLeader() and layout() in
engine/formation.js simply use array order instead of scanning for
highest maxHp.

- Selecting and moving just the leader now drags along everyone
previously grouped with it, with no need to reselect the group. A new
persistent "follow-leader" order (engine/commands.js, engine/movement.js,
engine/sim.js, engine/combat.js) mirrors the existing escort-order
pattern: followers re-seek the leader's live position every tick via
object references (unit.squadLeader / leader.squadFollowers), set up
by dispatchFormation() and torn down by any direct order that bypasses
it (stop, hold, scout, build).

- A formation's travel speed is capped to its slowest member so a fast
leader can't stretch the group out of shape. dispatchFormation()
computes the cap once at issue time and stores it on the leader's
order as order.speedCap; a new orderedSpeed() helper in movement.js
applies it at every move/attack-move/hold-formation stepToward call
site.

- Right-click-and-drag now sets an explicit facing: input.js tracks a
real mousedown/mousemove/mouseup gesture (replacing the old
contextmenu-only handling) and turns a long-enough drag into a
heading passed through to issueMove/issueAttackMove/issueHoldFormation.
applyFacing() stamps unit.facing accordingly. This applies to
formations and to single/multi-unit selections alike (e.g. facing a
choke point while waiting for the enemy). renderShared.js's
updateFacing() prefers the stamped facing while a unit is
near-stationary, but still faces the direction of travel while moving.

Two issues turned up during implementation and were fixed proactively:

- The new leader/follower squad mechanic only applies to player-owned
units (dispatchFormation gates on leader.owner === "player"); AI-issued
multi-unit orders bypass it entirely so every AI unit still gets its
own real order, exactly as before. Full-suite regression caught this
as a real collision with existing AI tactical tests.

- squadLeader/squadFollowers and any live follow-leader order carry
circular object references that can't survive JSON.stringify.
persist.js now strips them (and nulls follow-leader orders) during
save, matching the existing pattern for other transient fields, with
a regression test confirming save/load doesn't throw while a squad
is active.

Rewrote test/formation.test.js (leader-order semantics, persistent
follow, speed cap, facing, AI-owner gating, save/load safety) and
test/input.test.js (drag-vs-click distinction, facing on drag). Full
suite: 814/814 passing. Typecheck clean. Manually verified in a live
browser via Playwright: group drag-move sets facing and speed cap
correctly, and a solo move of just the leader correctly drags the whole
previously-formed squad along.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dmxcvm178TEt2wVXrX5Cj1

engine/combat.js

@@ -15,7 +15,7 @@
 
 "use strict";
 
-import { stepToward, keepEscortStation, keepFormationStation } from "./movement.js";
+import { stepToward, keepEscortStation, keepFormationStation, keepFollowingLeader, orderedSpeed } from "./movement.js";
 import { UNITS, BUILDINGS, upgradeMult } from "./entities.js";
 import { getEntity, removeEntity } from "./state.js";
 import { queryNeighbors } from "./grid.js";
@@ -28,7 +28,7 @@ export function updateCombat(state, unit, dt) {
   unit.attackTimer = Math.max(0, unit.attackTimer - dt);
 
   if (unit.order && unit.order.type === "move") {
-    const arrived = stepToward(state, unit, unit.order.x, unit.order.y, def.speed, dt);
+    const arrived = stepToward(state, unit, unit.order.x, unit.order.y, orderedSpeed(def.speed, unit.order), dt);
     if (arrived) unit.order = null;
     return;
   }
@@ -77,7 +77,7 @@ export function updateCombat(state, unit, dt) {
   }
 
   if (unit.order && unit.order.type === "attack-move") {
-    const arrived = stepToward(state, unit, unit.order.x, unit.order.y, def.speed, dt);
+    const arrived = stepToward(state, unit, unit.order.x, unit.order.y, orderedSpeed(def.speed, unit.order), dt);
     if (arrived) unit.order = null;
     return;
   }
@@ -88,10 +88,14 @@ export function updateCombat(state, unit, dt) {
   if (unit.order && unit.order.type === "escort") {
     keepEscortStation(state, unit, def.speed, dt);
   } else if (unit.order && unit.order.type === "hold-formation") {
-    // Same idea, but the "target" is the group's own fixed anchor rather than a moving ship —
-    // a defensive formation holding its ground, still fully combat-reactive above (this only
-    // runs once no threat was acquired/engaged this tick).
+    // Same idea, but the "target" is this unit's OWN fixed anchor rather than a moving ship —
+    // a formation leader holding its ground, still fully combat-reactive above (this only runs
+    // once no threat was acquired/engaged this tick).
     keepFormationStation(state, unit, def.speed, dt);
+  } else if (unit.order && unit.order.type === "follow-leader") {
+    // A formation follower: keeps its slot relative to the leader's live position, same
+    // combat-reactive treatment as escort/hold-formation above.
+    keepFollowingLeader(state, unit, def.speed, dt);
   }
 }
 

engine/commands.js

@@ -17,7 +17,14 @@ import { formationSlots } from "./formation.js";
 // fully idle unit acts immediately, so the first waypoint of a chain doesn't
 // sit inert. A plain command always wipes any queued waypoints, so it cancels a
 // chain cleanly. sim.js pulls the next queued order in as soon as `order` clears.
+//
+// A DIRECT order (anything except the follow-leader order dispatchFormation itself hands out)
+// releases the unit from whatever squad it was following — direct control always wins. The
+// squad's leader is untouched by this (a leader never carries squadLeader itself), so giving
+// the LEADER a fresh order here never disbands the squad; only a follower ordered on its own
+// leaves it.
 function dispatch(unit, order, queue) {
+  if (order.type !== "follow-leader") setSquadLeader(unit, null);
   if (!unit.orderQueue) unit.orderQueue = [];
   unit.hold = false;   // any positive order (move/attack/gather/waypoint) cancels a Hold stance
   if (queue && (unit.order || unit.orderQueue.length)) {
@@ -28,12 +35,116 @@ function dispatch(unit, order, queue) {
   }
 }
 
-// `formation` ({shape, leaderPos}, engine/formation.js) is optional — omitted, it's the
-// original flat grid spread (byte-identical to the old behaviour), unchanged for any caller
-// that doesn't pass one (the AI, and every pre-existing test).
-export function issueMove(units, x, y, queue = false, formation) {
+// Attach/detach `unit` to/from `leader`'s squad (or clear it with leader=null). Keeps the
+// relationship bidirectional and consistent: leaving a DIFFERENT leader's squad always trims
+// that leader's own squadFollowers list too, so a leader never keeps dragging along a unit that
+// no longer considers it the leader. Transient, session-only state (never persisted — see
+// persist.js's serPlanet, which strips both fields and drops a live follow-leader order
+// entirely rather than trying to serialize the object reference it carries).
+function setSquadLeader(unit, leader) {
+  const old = unit.squadLeader;
+  if (old && old !== leader && old.squadFollowers) {
+    const i = old.squadFollowers.indexOf(unit);
+    if (i >= 0) old.squadFollowers.splice(i, 1);
+  }
+  unit.squadLeader = leader || undefined;
+}
+
+// The shared machinery behind issueMove/issueAttackMove/issueHoldFormation: lay the group out
+// in `formation`'s shape, give the LEADER (units[0] — see engine/formation.js) its own real
+// order via `makeLeaderOrder(point)`, and give every OTHER unit a persistent "follow-leader"
+// order that keeps it at a fixed offset from the leader's LIVE position from now on
+// (engine/movement.js keepFollowingLeader) — not just for this one command. That's what makes
+// "select the leader alone and move it" drag the rest of the formation along for free: a later
+// solo command to the leader (the n===1 branch below) re-uses its EXISTING squadFollowers
+// (pruned of anything that's died) purely to recompute the group's speed cap; it never touches
+// the followers' own orders, because they're already perpetually chasing the leader regardless
+// of what NEW order the leader receives.
+//
+// The whole squad's travel speed is capped to its SLOWEST member (order.speedCap, read by
+// engine/movement.js's orderedSpeed) so a fast leader can't outrun its own formation — without
+// this, followers would perpetually lag behind a leader moving at its own full speed, stretching
+// the shape out instead of holding it.
+function dispatchFormation(units, x, y, formation, queue, makeLeaderOrder) {
+  const leader = units[0];
+
+  // The leader/follow squad is a PLAYER selection-UX feature — there's no analogous "the unit
+  // you built a selection around" concept for the scripted AI (or a test double with no owner
+  // set at all), and the existing tactical AI (kiting, retreats, feint response, wave sizing…)
+  // reads every one of ITS units' own real move/attack-move order directly. So anything that
+  // isn't a confirmed player unit skips the whole leader/follower mechanic and just gets the
+  // plain per-unit spread this replaces — one real order per unit, exactly as before this
+  // feature existed. (Every player-issued command always passes real player.owner==="player"
+  // units — see input.js's selectedUnits().)
+  if (leader.owner !== "player") {
+    const spots = formationSlots(units, x, y, formation);
+    units.forEach((u, i) => dispatch(u, makeLeaderOrder(spots[i]), queue));
+    return;
+  }
+
+  if (units.length === 1) {
+    const order = makeLeaderOrder({ x, y });
+    if (leader.squadFollowers && leader.squadFollowers.length) {
+      leader.squadFollowers = leader.squadFollowers.filter(f => f.hp > 0);
+      const groupSpeed = [leader, ...leader.squadFollowers].reduce((m, u) => Math.min(m, UNITS[u.type]?.speed ?? Infinity), Infinity);
+      if (Number.isFinite(groupSpeed)) order.speedCap = groupSpeed;
+    }
+    dispatch(leader, order, queue);
+    return;
+  }
+
   const spots = formationSlots(units, x, y, formation);
-  units.forEach((u, i) => dispatch(u, { type: "move", x: spots[i].x, y: spots[i].y }, queue));
+  const leaderSpot = spots[0];
+  const newFollowers = units.slice(1);
+
+  // Redefining the squad for exactly this unit set: anyone who WAS following this leader but
+  // isn't part of it this time is released — and actually stopped, not just unlinked, so a
+  // dropped unit doesn't silently keep chasing a leader that no longer lists it.
+  if (leader.squadFollowers) {
+    for (const old of leader.squadFollowers) {
+      if (!newFollowers.includes(old)) { setSquadLeader(old, null); old.order = null; }
+    }
+  }
+  leader.squadFollowers = newFollowers;
+
+  const groupSpeed = units.reduce((m, u) => Math.min(m, UNITS[u.type]?.speed ?? Infinity), Infinity);
+  const leaderOrder = makeLeaderOrder(leaderSpot);
+  if (Number.isFinite(groupSpeed)) leaderOrder.speedCap = groupSpeed;
+  dispatch(leader, leaderOrder, queue);
+
+  for (let i = 1; i < units.length; i++) {
+    setSquadLeader(units[i], leader);
+    dispatch(units[i], {
+      type: "follow-leader", leader,
+      offsetX: spots[i].x - leaderSpot.x, offsetY: spots[i].y - leaderSpot.y,
+    }, queue);
+  }
+}
+
+// A click-and-drag command's drag vector (formation.headingX/headingY) is also the direction
+// the player wants the group to FACE — not just how the shape is oriented while travelling.
+// Stamped onto every commanded unit as `facing` (read by renderShared.js's updateFacing once a
+// unit stops moving, overriding the angle it would otherwise just freeze at) — the "give a
+// formation, or a single/multiple selection, a direction to face" ask (e.g. holding a line
+// facing the enemy). A PLAIN command (a click, no drag — no explicit heading) clears any
+// earlier facing instead, so it never lingers stale once the player stops aiming their orders.
+function applyFacing(units, formation) {
+  const hx = formation?.headingX || 0, hy = formation?.headingY || 0;
+  if (hx || hy) {
+    const angle = Math.atan2(hy, hx);
+    for (const u of units) u.facing = angle;
+  } else {
+    for (const u of units) delete u.facing;
+  }
+}
+
+// `formation` ({shape, leaderPos, headingX, headingY}, engine/formation.js) is optional —
+// omitted, it's the original flat grid spread (byte-identical to the old behaviour), unchanged
+// for any caller that doesn't pass one (the AI, and every pre-existing test).
+export function issueMove(units, x, y, queue = false, formation) {
+  if (!units.length) return;
+  dispatchFormation(units, x, y, formation, queue, pt => ({ type: "move", x: pt.x, y: pt.y }));
+  applyFacing(units, formation);
 }
 
 export function issueGather(units, nodeId, queue = false) {
@@ -64,8 +175,9 @@ export function issueAttack(units, targetId, queue = false) {
 }
 
 export function issueAttackMove(units, x, y, queue = false, formation) {
-  const spots = formationSlots(units, x, y, formation);
-  units.forEach((u, i) => dispatch(u, { type: "attack-move", x: spots[i].x, y: spots[i].y }, queue));
+  if (!units.length) return;
+  dispatchFormation(units, x, y, formation, queue, pt => ({ type: "attack-move", x: pt.x, y: pt.y }));
+  applyFacing(units, formation);
 }
 
 // Escort a friendly ship: each unit takes a stable slot on a protective ring around the
@@ -79,25 +191,22 @@ export function issueEscort(units, targetId, queue = false) {
 }
 
 // Protection of a FORMATION, not one external ship: the group forms up in the chosen shape
-// right where it's standing (its own current centroid — see formationSlots) and holds there,
-// each unit re-seeking its own slot every tick (engine/movement.js keepFormationStation) so a
-// unit nudged out of place (avoidance jostling, a broken engagement) settles back rather than
-// drifting. Persists like escort — never cleared on arrival — until a new order replaces it.
-// Combat units also take the Hold stance (issueHold's existing "stand fast, don't chase" rule),
-// so the whole formation keeps its shape instead of scattering to run down a distant target;
-// non-combat units (workers, a Mender) still take a slot — sheltering behind/inside the line —
-// they just have no stance flag to set. Each unit's slot is baked into its OWN order as a fixed
-// offset from the anchor at issue time, so holding station never needs to re-scan the group.
+// right where it's standing (its own current centroid) and holds there — the LEADER holds its
+// own fixed anchor (engine/movement.js keepFormationStation), everyone else follows it there and
+// keeps station relative to it (keepFollowingLeader) exactly like a hold-formation-flavoured
+// move, so a later solo command to just the leader picks the whole formation back up too (see
+// dispatchFormation). Combat units also take the Hold stance (issueHold's existing "stand fast,
+// don't chase" rule) — LEADER AND FOLLOWERS alike — so the whole formation keeps its shape
+// instead of scattering to run down a distant target; non-combat units (workers, a Mender) still
+// take a slot — sheltering behind/inside the line — they just have no stance flag to set.
 export function issueHoldFormation(units, shape = "grid", leaderPos = "front") {
   if (!units.length) return;
   let sx = 0, sy = 0;
   for (const u of units) { sx += u.x; sy += u.y; }
   const anchorX = sx / units.length, anchorY = sy / units.length;
-  const slots = formationSlots(units, anchorX, anchorY, { shape, leaderPos, originX: anchorX, originY: anchorY });
-  units.forEach((u, i) => {
-    dispatch(u, { type: "hold-formation", anchorX, anchorY, offsetX: slots[i].x - anchorX, offsetY: slots[i].y - anchorY }, false);
-    if (UNITS[u.type] && UNITS[u.type].role === "combat") u.hold = true;
-  });
+  dispatchFormation(units, anchorX, anchorY, { shape, leaderPos, originX: anchorX, originY: anchorY }, false,
+    pt => ({ type: "hold-formation", anchorX: pt.x, anchorY: pt.y, offsetX: 0, offsetY: 0 }));
+  for (const u of units) if (UNITS[u.type] && UNITS[u.type].role === "combat") u.hold = true;
 }
 
 // Pays the cost up front, drops a constructing building on the spot, and
@@ -121,6 +230,7 @@ export function issueBuild(state, workerId, buildingType, x, y) {
   payCost(player.resources, def.cost);
   const building = makeBuilding(buildingType, worker.owner, x, y, { constructing: true });
   state.buildings.set(building.id, building);
+  setSquadLeader(worker, null);   // a direct order releases the worker from any squad it was following
   worker.order = { type: "build", buildingId: building.id };
   return building.id;
 }
@@ -136,8 +246,9 @@ export function issueAssistBuild(units, buildingId, queue = false) {
 // where it stands. A combat unit still defends itself (it re-auto-acquires an
 // enemy that wanders into range next tick), but it won't chase or resume a
 // path — the standard RTS "stop" that pulls a unit out of a move or a chain.
+// A direct order like this always releases the unit from a squad it was following.
 export function issueStop(units) {
-  units.forEach(u => { u.order = null; u.orderQueue = []; u.hold = false; });
+  units.forEach(u => { setSquadLeader(u, null); u.order = null; u.orderQueue = []; u.hold = false; });
 }
 
 // Hold position: a combat unit stands its ground and fires on anything that
@@ -146,7 +257,7 @@ export function issueStop(units) {
 // holding a line or a choke. Any move/attack order, or Stop, clears it.
 export function issueHold(units) {
   units.forEach(u => {
-    if (UNITS[u.type] && UNITS[u.type].role === "combat") { u.order = null; u.orderQueue = []; u.hold = true; }
+    if (UNITS[u.type] && UNITS[u.type].role === "combat") { setSquadLeader(u, null); u.order = null; u.orderQueue = []; u.hold = true; }
   });
 }
 
@@ -157,7 +268,7 @@ export function issueHold(units) {
 // a plain command — the mode is persistent, not something to stack behind.
 export function issueScout(units) {
   units.forEach(u => {
-    if (UNITS[u.type] && UNITS[u.type].role === "scout") { u.order = { type: "scout" }; u.orderQueue = []; }
+    if (UNITS[u.type] && UNITS[u.type].role === "scout") { setSquadLeader(u, null); u.order = { type: "scout" }; u.orderQueue = []; }
   });
 }
 

engine/formation.js

@@ -18,20 +18,28 @@
                 explicitly asked for), or takes a point ON the ring at the
                 front/back with everyone else filling the rest evenly
 
-   The "leader" is deterministic, not selection-order-dependent: the unit
-   with the most maxHp (a bigger hull naturally leads), ties broken by id —
-   see pickLeader.
+   The "leader" is whichever unit is FIRST in the `units` array — i.e.
+   whichever unit the player selected first and added the rest to (the
+   normal box-select-additive selection order preserves this: an existing
+   selection is kept first, newly-added picks are appended after — see
+   input.js's applyBoxSelection). Deliberately NOT a stat-based pick (e.g.
+   highest maxHp): the player chooses their leader by building the
+   selection around it, the same unit engine/commands.js then keeps giving
+   its own real order to while everyone else follows it (issueHoldFormation
+   / follow-leader — see commands.js and movement.js).
 
    NESTED formations: a selection that's ALREADY spread into distinct spatial
    clusters (e.g. two armies on opposite sides of the map, box-selected
    together) is laid out as a formation OF formations — clusterUnits splits
-   it, the SAME shape arranges the clusters' centres relative to each other
-   (a wedge of wedges, a line of lines, …), spaced by each cluster's own
-   footprint so sub-formations can't overlap, and each cluster is then laid
-   out again internally around its assigned centre. A single blob of units —
-   the ordinary case, everyone selected in one place — collapses to exactly
-   ONE cluster, so nesting only ever engages when the selection already
-   calls for it.
+   it (preserving each unit's relative position in the original array, so
+   the cluster CONTAINING the overall leader is always clusters[0] and thus
+   still gets the outer leader slot), the SAME shape arranges the clusters'
+   centres relative to each other (a wedge of wedges, a line of lines, …),
+   spaced by each cluster's own footprint so sub-formations can't overlap,
+   and each cluster is then laid out again internally around its assigned
+   centre. A single blob of units — the ordinary case, everyone selected in
+   one place — collapses to exactly ONE cluster, so nesting only ever
+   engages when the selection already calls for it.
 
    Spacing is derived from the group's own hull sizes (spacingFor), not a
    flat constant, EXCEPT the plain single-group "grid" path, which keeps the
@@ -69,17 +77,11 @@ function centroid(units) {
   return { x: sx / units.length, y: sy / units.length };
 }
 
-// The deterministic "flagship": the unit with the most maxHp (ties broken by id, never by
-// selection/array order — the same pick must come out of the same group regardless of how the
-// player happened to box-select it).
+// The leader is simply whichever unit is first in the given array — see the file header. A
+// one-line function so callers (engine/commands.js) don't have to know/duplicate the rule.
 /** @param {Unit[]} units @returns {Unit} */
 export function pickLeader(units) {
-  let best = units[0];
-  for (const u of units) {
-    const bhp = best.maxHp ?? 0, uhp = u.maxHp ?? 0;
-    if (uhp > bhp || (uhp === bhp && u.id < best.id)) best = u;
-  }
-  return best;
+  return units[0];
 }
 
 // Radius-aware baseline spacing for a group: room for the two largest hulls present to clear
@@ -96,6 +98,11 @@ function spacingFor(units) {
 // other (transitively) land in the same cluster — a plain union-find pass over CURRENT
 // positions. A single blob of units (the common case) collapses to one cluster. O(n^2) on the
 // selection size, which is issue-time work on a small array, not a per-tick cost.
+//
+// Preserves each unit's relative order from the input array within its cluster, AND across
+// clusters (the cluster containing units[0] is always clusters[0]) — both `layout` calls below
+// rely on member[0] being the leader, so this ordering guarantee is what keeps the overall
+// leader's own cluster the "leader cluster" of the outer formation too.
 /** @param {Unit[]} units @returns {Unit[][]} */
 export function clusterUnits(units) {
   const n = units.length;
@@ -186,12 +193,13 @@ function shapeOffsets(n, shape, leaderPos, spacing) {
   return centerOffsets(raw);
 }
 
-// Lay out `members` (units OR cluster-arrays — anything `weightOf`/`idOf`/`spacingOf` can read)
-// into `shape`, oriented by (headingX,headingY), centred on (cx,cy). Returns points in the SAME
-// order as `members`. `shape==="grid"` ignores heading entirely (world-axis-aligned, exactly the
-// legacy behaviour); every other shape orients its forward axis along the heading (or a stable
-// default when the group isn't actually travelling — e.g. re-forming in place).
-function layout(members, cx, cy, headingX, headingY, shape, leaderPos, spacingOf, weightOf, idOf) {
+// Lay out `members` (units OR cluster-arrays) into `shape`, oriented by (headingX,headingY),
+// centred on (cx,cy). Returns points in the SAME order as `members` — member[0] (the leader,
+// see the file header) always takes the shape's own leader slot (raw[0]). `shape==="grid"`
+// ignores heading entirely (world-axis-aligned, exactly the legacy behaviour); every other
+// shape orients its forward axis along the heading (or a stable default when the group isn't
+// actually travelling — e.g. re-forming in place).
+function layout(members, cx, cy, headingX, headingY, shape, leaderPos, spacingOf) {
   const n = members.length;
   if (n === 1) return [{ x: cx, y: cy }];
   const spacing = spacingOf(members);
@@ -208,33 +216,28 @@ function layout(members, cx, cy, headingX, headingY, shape, leaderPos, spacingOf
   const hlen = Math.hypot(hx, hy);
   if (hlen < 1e-6) { hx = 1; hy = 0; } else { hx /= hlen; hy /= hlen; }
 
-  // Leader-first slot order: which member sits in raw[0] (the shape's leader treatment) — most
-  // weight wins, ties by id — same rule as pickLeader, generalised to non-Unit members (clusters).
-  const order = members.map((_, i) => i).sort((ia, ib) => {
-    const wa = weightOf(members[ia]), wb = weightOf(members[ib]);
-    if (wa !== wb) return wb - wa;
-    const a = idOf(members[ia]), b = idOf(members[ib]);
-    return a < b ? -1 : (a > b ? 1 : 0);
-  });
-
   const raw = shapeOffsets(n, shape, leaderPos, spacing);
-  const out = new Array(n);
-  order.forEach((memberIdx, slot) => {
-    const { forward, right } = raw[slot];
-    out[memberIdx] = { x: cx + forward * hx + right * hy, y: cy + forward * hy - right * hx };
+  return members.map((_, i) => {
+    const { forward, right } = raw[i];
+    return { x: cx + forward * hx + right * hy, y: cy + forward * hy - right * hx };
   });
-  return out;
 }
 
 /**
  * Where each unit in `units` should stand for a move to (destX,destY) — or, for a stationary
  * hold, where the group's own current centroid already is (pass it as both the destination AND
- * `originX`/`originY`, or simply omit `originX`/`originY` and let it default there). Returns
- * one {x,y} per unit, in the SAME order as `units`.
+ * `originX`/`originY`, or simply omit `originX`/`originY` and let it default there). `units[0]`
+ * is always the leader (see the file header) and always lands on the shape's own leader slot.
+ * Returns one {x,y} per unit, in the SAME order as `units`.
+ *
+ * The heading (which way the shape faces) is normally derived from `origin -> dest`, but a
+ * player can instead set it explicitly — e.g. a click-and-drag command, where the drag vector
+ * IS the desired facing regardless of how far the destination actually is — via `headingX`/
+ * `headingY`; either non-zero overrides the origin-derived heading entirely.
  * @param {Unit[]} units
  * @param {number} destX
  * @param {number} destY
- * @param {{shape?:string, leaderPos?:string, originX?:number, originY?:number}} [opts]
+ * @param {{shape?:string, leaderPos?:string, originX?:number, originY?:number, headingX?:number, headingY?:number}} [opts]
  * @returns {{x:number, y:number}[]}
  */
 export function formationSlots(units, destX, destY, opts = {}) {
@@ -243,19 +246,22 @@ export function formationSlots(units, destX, destY, opts = {}) {
   const { shape = "grid", leaderPos = "front" } = opts || {};
   if (n === 1) return [{ x: destX, y: destY }];
 
-  let { originX, originY } = opts || {};
-  if (!Number.isFinite(originX) || !Number.isFinite(originY)) {
-    const c = centroid(units);
-    originX = c.x; originY = c.y;
+  let headingX = opts?.headingX, headingY = opts?.headingY;
+  if (!((headingX || 0) || (headingY || 0))) {
+    let { originX, originY } = opts || {};
+    if (!Number.isFinite(originX) || !Number.isFinite(originY)) {
+      const c = centroid(units);
+      originX = c.x; originY = c.y;
+    }
+    headingX = destX - originX; headingY = destY - originY;
   }
-  const headingX = destX - originX, headingY = destY - originY;
 
   const clusters = clusterUnits(units);
   if (clusters.length <= 1) {
     // The one path that must stay byte-identical to the old flat grid spread: no shape chosen,
     // one blob of units — the legacy formationSpots' exact spacing constant, untouched.
     const spacingOf = shape === "grid" ? () => GRID_SPACING : spacingFor;
-    return layout(units, destX, destY, headingX, headingY, shape, leaderPos, spacingOf, u => u.maxHp ?? 0, u => u.id);
+    return layout(units, destX, destY, headingX, headingY, shape, leaderPos, spacingOf);
   }
 
   // Nested: a formation OF formations. Each cluster is one outer slot, arranged by the SAME
@@ -263,17 +269,13 @@ export function formationSlots(units, destX, destY, opts = {}) {
   // footprint so sub-formations can't overlap ("sufficient spacing… in formation of formations").
   const footprints = clusters.map(c => Math.max(1, Math.ceil(Math.sqrt(c.length))) * spacingFor(c));
   const outerSpacing = Math.max(...footprints) * NEST_GAP_MULT;
-  const clusterWeight = c => c.reduce((s, u) => s + (u.maxHp ?? 0), 0);
-  const centers = layout(
-    clusters, destX, destY, headingX, headingY, shape, leaderPos,
-    () => outerSpacing, clusterWeight, c => c[0].id,
-  );
+  const centers = layout(clusters, destX, destY, headingX, headingY, shape, leaderPos, () => outerSpacing);
 
   const placed = new Map();
   clusters.forEach((cluster, i) => {
     const { x: ccx, y: ccy } = centers[i];
     const cc = centroid(cluster);
-    const inner = layout(cluster, ccx, ccy, ccx - cc.x, ccy - cc.y, shape, leaderPos, spacingFor, u => u.maxHp ?? 0, u => u.id);
+    const inner = layout(cluster, ccx, ccy, ccx - cc.x, ccy - cc.y, shape, leaderPos, spacingFor);
     cluster.forEach((u, k) => placed.set(u, inner[k]));
   });
   return units.map(u => placed.get(u));

engine/movement.js

@@ -70,16 +70,48 @@ export function keepEscortStation(state, unit, speed, dt) {
   return true;
 }
 
-// Advance a unit holding a formation station (order {type:"hold-formation", anchorX, anchorY,
-// offsetX, offsetY} — engine/commands.js issueHoldFormation) one tick toward its assigned slot,
-// a fixed offset from the anchor baked in at issue time. Unlike escort's ring (which re-seeks a
-// MOVING external target every tick), the anchor here never moves — that's the point: this is a
-// group defending its own position, not following anyone. So there's nothing that can "vanish"
-// and drop the order the way an escort's target can; it persists until a new order replaces it.
+// Advance a formation LEADER holding station (order {type:"hold-formation", anchorX, anchorY,
+// offsetX, offsetY} — engine/commands.js issueHoldFormation) one tick toward its own fixed
+// anchor point. Unlike escort's ring (which re-seeks a MOVING external target every tick), the
+// anchor here never moves — that's the point: this is a unit (or a formation's leader — see
+// keepFollowingLeader below for everyone else in the group) defending its own position, not
+// following anyone. Nothing can "vanish" and drop the order the way an escort's target can; it
+// persists until a new order replaces it.
 /** @param {State} state @param {Unit} unit @param {number} speed @param {number} dt */
 export function keepFormationStation(state, unit, speed, dt) {
   const o = unit.order;
-  stepToward(state, unit, o.anchorX + o.offsetX, o.anchorY + o.offsetY, speed, dt);
+  stepToward(state, unit, o.anchorX + o.offsetX, o.anchorY + o.offsetY, orderedSpeed(speed, o), dt);
+}
+
+// Advance a formation FOLLOWER (order {type:"follow-leader", leader, offsetX, offsetY} —
+// engine/commands.js dispatchFormation) one tick toward a fixed offset from its leader's LIVE
+// position — re-seeked every tick, exactly like escort's ring around its guarded ship, except
+// the "target" is another player unit that itself is under direct orders (move/attack-move/
+// hold-formation) rather than just standing still. This is what makes "select the leader alone
+// and move it" drag the rest of the formation along for free: the leader gets a fresh order,
+// the followers were never re-ordered at all — they're still chasing `leader.pos + offset`
+// every tick, whatever that position now is. Drops the order (returns to independent control)
+// the moment the leader dies, the same as an escort losing its guarded ship.
+/** @param {State} state @param {Unit} unit @param {number} speed @param {number} dt @returns {boolean} */
+export function keepFollowingLeader(state, unit, speed, dt) {
+  const o = unit.order;
+  const leader = o.leader;
+  if (!leader || leader.hp <= 0) { unit.order = null; return false; }
+  stepToward(state, unit, leader.x + o.offsetX, leader.y + o.offsetY, speed, dt);
+  return true;
+}
+
+// A formation's overall pace is capped to its SLOWEST member (order.speedCap, stamped by
+// engine/commands.js's dispatchFormation) so a fast leader can't outrun the group it's
+// supposedly leading — without this, followers (who each move at their OWN top speed toward the
+// leader's live position) would perpetually lag behind while the leader is in motion, stretching
+// the shape out instead of holding it. Followers never need this themselves: every follower's own
+// speed is, by construction, at least the group minimum, so they can always keep pace with a
+// leader that's capped to it. Identity (returns `speed` unchanged) for any order without a cap —
+// every order type except move/attack-move/hold-formation, and those two before this feature.
+/** @param {number} speed @param {Order} order @returns {number} */
+export function orderedSpeed(speed, order) {
+  return Number.isFinite(order?.speedCap) ? Math.min(speed, order.speedCap) : speed;
 }
 
 // Moves `unit` at most `speed * dt` toward (tx, ty). Returns true once it

engine/persist.js

@@ -159,6 +159,11 @@ function cleanEntity(e, def, map) {
   // value can't win the "most recently used pad" tie-break it's only ever compared with. Only
   // present once a jump has actually landed there, so this only fires when the field exists.
   if (e.type === "spaceport" && e.lastLanding !== undefined) e.lastLanding = Math.max(0, num(e.lastLanding, 0));
+  // A unit's player-set `facing` (engine/commands.js applyFacing) is untrusted too — a bogus
+  // non-numeric value would flow straight into Math.cos/sin (renderShared.js) as NaN, silently
+  // mis-drawing (never crashing) the sprite. Coerce it to a finite number, or drop the field
+  // entirely so the unit just falls back to its normal movement-inferred facing.
+  if (e.facing !== undefined) { const f = num(e.facing, NaN); if (Number.isFinite(f)) e.facing = f; else delete e.facing; }
   // A producer's output buffer (building.store) and a factory's input buffer (building.input) are
   // untrusted save data — a hand-edited file could smuggle in a bogus commodity, a negative/NaN qty,
   // or an over-capacity buffer. Keep only real commodities with a positive qty and clamp each buffer's
@@ -282,7 +287,16 @@ function serPlanet(state) {
     // `_gi` is the grid broad-phase index — a transient stamped fresh onto every unit each tick
     // by buildUnitGrid, meaningless once saved. Strip it so it doesn't bloat the payload with a
     // per-unit integer that the next tick overwrites anyway. Shallow copy, only at save time.
-    units: [...state.units.values()].map(({ _gi, repairTargetId, ...u }) => u),   // both transient (grid index; live repair pick)
+    // `squadLeader`/`squadFollowers` (engine/commands.js) are live UNIT OBJECT REFERENCES, not
+    // ids — session-only, transient bookkeeping like the rest of this denylist, but they ALSO
+    // can't survive JSON.stringify at all: a follower points at its leader, the leader's own
+    // squadFollowers list points right back, and JSON.stringify throws on a circular structure
+    // rather than silently truncating it — a live squad would crash every save. Strip both
+    // fields, and null out a live `follow-leader` order too (it embeds the same leader
+    // reference) — a reload simply drops squad membership, the same "recomputed/reset, never
+    // persisted" treatment repairTargetId already gets.
+    units: [...state.units.values()].map(({ _gi, repairTargetId, squadLeader, squadFollowers, ...u }) =>
+      u.order && u.order.type === "follow-leader" ? { ...u, order: null } : u),
     // `haulers`/`servers` (logistics tallies, engine/haul.js), `powered`/`fuel` (Generator fuel
     // state, engine/industry.js), `menderClaims` (auto-repair Mender tally, engine/sim.js) and
     // `lastYield`/`lastTier` (a Plasma Rig's last-strike HUD readout, engine/rig.js — regenerated on

engine/sim.js

@@ -6,7 +6,7 @@
 
 "use strict";
 
-import { stepToward, keepEscortStation, keepFormationStation } from "./movement.js";
+import { stepToward, keepEscortStation, keepFormationStation, keepFollowingLeader, orderedSpeed } from "./movement.js";
 import { buildUnitGrid } from "./grid.js";
 import { updateGather } from "./gather.js";
 import { updateHaul, assignHaul, updateService, assignService, countLogistics } from "./haul.js";
@@ -160,7 +160,7 @@ function updateUnit(state, unit, dt) {
   if (!unit.order) return;
   switch (unit.order.type) {
     case "move": {
-      const arrived = stepToward(state, unit, unit.order.x, unit.order.y, def.speed, dt);
+      const arrived = stepToward(state, unit, unit.order.x, unit.order.y, orderedSpeed(def.speed, unit.order), dt);
       if (arrived) unit.order = null;
       break;
     }
@@ -178,9 +178,13 @@ function updateUnit(state, unit, dt) {
       keepEscortStation(state, unit, def.speed, dt);
       break;
     case "hold-formation":
-      // A non-combat unit (worker, freighter) sheltering in a formation just keeps its slot.
+      // A non-combat formation LEADER (worker, freighter) holds its own fixed anchor.
       keepFormationStation(state, unit, def.speed, dt);
       break;
+    case "follow-leader":
+      // A non-combat formation FOLLOWER just keeps its slot relative to the leader.
+      keepFollowingLeader(state, unit, def.speed, dt);
+      break;
     case "scout":
       updateScoutMode(state, unit, dt);
       break;
@@ -235,23 +239,28 @@ function updateSupport(state, unit, def, dt) {
     keepEscortStation(state, unit, def.speed, dt);
     return;
   }
-  // Holding a defensive formation: same idea, station-keeping at a fixed slot instead of a
-  // moving target — the drone mends whatever's near it (the repair pass) right where it stands.
+  // Holding a defensive formation: same idea, station-keeping at its own fixed anchor instead
+  // of a moving target — the drone mends whatever's near it (the repair pass) right where it stands.
   if (o.type === "hold-formation") {
     keepFormationStation(state, unit, def.speed, dt);
     return;
   }
-  let tx, ty, follow = false;
+  // Following a formation leader: keeps its slot relative to the leader's LIVE position.
+  if (o.type === "follow-leader") {
+    keepFollowingLeader(state, unit, def.speed, dt);
+    return;
+  }
+  let tx, ty, follow = false, speed = def.speed;
   if (o.type === "attack") {
     const t = getEntity(state, o.targetId);
     if (!t || t.hp <= 0) { unit.order = null; return; }
     tx = t.x; ty = t.y; follow = true;   // keep chasing a moving foe rather than stopping on arrival
   } else if (o.type === "move" || o.type === "attack-move") {
-    tx = o.x; ty = o.y;
+    tx = o.x; ty = o.y; speed = orderedSpeed(def.speed, o);
   } else {
     unit.order = null; return;   // gather / scout / build are meaningless for a drone
   }
-  const arrived = stepToward(state, unit, tx, ty, def.speed, dt);
+  const arrived = stepToward(state, unit, tx, ty, speed, dt);
   if (arrived && !follow) unit.order = null;
 }
 

engine/types.js

@@ -35,7 +35,7 @@
 
 /**
  * A unit order. `type` is always present; the rest depend on the order kind
- * (move/gather/attack/attack-move/build/escort/scout/hold-formation).
+ * (move/gather/attack/attack-move/build/escort/scout/hold-formation/follow-leader).
  * @typedef {Object} Order
  * @property {string} type
  * @property {number} [x]
@@ -48,10 +48,12 @@
  * @property {number} [slots]
  * @property {string} [phase]
  * @property {boolean} [manual]   a player-assigned service order sticks to its building (engine/haul.js)
- * @property {number} [anchorX]   hold-formation: the formation's fixed anchor point (engine/commands.js issueHoldFormation)
+ * @property {number} [anchorX]   hold-formation: this unit's own fixed anchor point (engine/commands.js issueHoldFormation)
  * @property {number} [anchorY]
- * @property {number} [offsetX]   hold-formation: this unit's fixed offset from the anchor (engine/formation.js)
+ * @property {number} [offsetX]   hold-formation/follow-leader: this unit's fixed offset from the anchor/leader (engine/formation.js)
  * @property {number} [offsetY]
+ * @property {Unit} [leader]      follow-leader: the formation leader this unit is chasing (engine/movement.js keepFollowingLeader) — a live object reference, NEVER persisted (engine/persist.js drops a follow-leader order entirely on save)
+ * @property {number} [speedCap]  move/attack-move/hold-formation: a formation leader's travel speed, capped to its slowest member (engine/movement.js orderedSpeed)
  */
 
 /**
@@ -94,6 +96,9 @@
  * @property {string|null} [targetId] aim target (combat.js / render.js)
  * @property {Object.<string, number>} [freight]  a freighter's player-managed cargo hold, commodity → qty (engine/galaxy.js)
  * @property {boolean} [armed]  a Helium Bomb set to detonate on attack/enemy presence/command (engine/bomb.js)
+ * @property {Unit} [squadLeader]     transient, NEVER persisted: the leader this unit is following, if any (engine/commands.js setSquadLeader) — a live object reference
+ * @property {Unit[]} [squadFollowers]  transient, NEVER persisted: the units following THIS unit as their leader (engine/commands.js dispatchFormation)
+ * @property {number} [facing]  a player-set facing angle (radians), from a click-and-drag move/attack-move (engine/commands.js applyFacing) — overrides the movement-inferred angle a STATIONARY unit would otherwise freeze at (renderShared.js updateFacing); a plain (non-drag) move/attack-move clears it, so it never lingers stale after a later un-aimed order
  */
 
 /**

hudSelection.js

@@ -1122,6 +1122,11 @@ function rebuildSelectionPanel(sel) {
     head.textContent = "Formation";
     panelEl.appendChild(head);
 
+    const leaderHint = document.createElement("p");
+    leaderHint.className = "hint";
+    leaderHint.textContent = "The first unit you selected leads — the rest follow it, even on a later solo move.";
+    panelEl.appendChild(leaderHint);
+
     const shapeRow = document.createElement("div");
     shapeRow.className = "formation-row";
     for (const shape of FORMATION_SHAPES) {
@@ -1206,7 +1211,7 @@ function rebuildSelectionPanel(sel) {
     const hint = document.createElement("p");
     hint.className = "hint";
     hint.textContent = touch ? "Tap the map to move. Tap a foe to attack. Attack-Move advances and engages."
-                             : "A + click to attack-move. Right-click moves (ignores enemies). Ctrl+right-click queues a waypoint.";
+                             : "A + click to attack-move. Right-click moves (ignores enemies). Right-drag also sets a facing. Ctrl+right-click queues a waypoint.";
     panelEl.appendChild(hint);
   } else if (sel.length === 1 && (cc || barracks)) {
     const hint = document.createElement("p");
@@ -1241,6 +1246,7 @@ function controlsLegend() {
   ] : [
     ["Left-drag", "select · Ctrl+drag adds"],
     ["Right-click", "move / attack / gather"],
+    ["Right-drag", "…and face that direction"],
     ["A + click", "attack-move"],
     ["Ctrl+right", "queue a waypoint"],
     ["Shift+1–9", "set group · 1–9 recall"],

input.js

@@ -38,6 +38,7 @@ export function attachInput(canvas, state, onChange) {
   const heldKeys = new Set();
 
   let dragBox = null;
+  let rightDragStart = null;   // world-space {x,y} where a right-button drag began, or null between drags
   let buildMode = null;
   let attackMoveArmed = false;   // set by the A key; the next left-click issues an attack-move
   let lastWorldPos = { x: state.map.width / 2, y: state.map.height / 2 };
@@ -86,17 +87,25 @@ export function attachInput(canvas, state, onChange) {
 
   // The player's current formation choice (session.js), read fresh on every order — so
   // switching shapes in the HUD mid-game takes effect on the very next command issued.
-  function currentFormation() {
-    return { shape: game.formation.shape, leaderPos: game.formation.leaderPos };
+  // `heading` ({x,y}, a world-space vector — NOT normalized, engine/formation.js does that) is
+  // set only by a right-click-DRAG (see rightDragStart below): the drag direction becomes both
+  // the formation's facing while it travels and the persisted `unit.facing` it holds once
+  // stopped (engine/commands.js applyFacing). A plain click carries no heading, so the shape
+  // orients itself off the group's own travel direction as before, and any earlier facing is
+  // cleared.
+  function currentFormation(heading) {
+    const f = { shape: game.formation.shape, leaderPos: game.formation.leaderPos };
+    if (heading) { f.headingX = heading.x; f.headingY = heading.y; }
+    return f;
   }
 
   // Attack-move to (x,y): combat units advance-and-engage anything met on the
   // way; non-combat units (workers, the Ranger) can't attack-move, so they just
   // move. Same split the Ctrl-queue and minimap-command paths use.
-  function aggressiveMove(units, x, y, queue = false) {
+  function aggressiveMove(units, x, y, queue = false, heading) {
     const combatants = units.filter(u => UNITS[u.type].role === "combat");
     const others = units.filter(u => UNITS[u.type].role !== "combat");
-    const formation = currentFormation();
+    const formation = currentFormation(heading);
     if (combatants.length) issueAttackMove(combatants, x, y, queue, formation);
     if (others.length) issueMove(others, x, y, queue, formation);
   }
@@ -173,7 +182,12 @@ export function attachInput(canvas, state, onChange) {
   // a single selected production building sets its rally; otherwise the current
   // unit selection assists-builds, attacks, gathers, or moves as the target
   // warrants. `queue` chains it as a waypoint instead of replacing the order.
-  function commandAt(p, queue) {
+  // `heading` (world-space {x,y}, only ever set by a right-click-drag — see
+  // rightDragStart) only matters to the final plain-move fallback: gathering,
+  // attacking, escorting, and assisting/servicing a building all target a SPECIFIC
+  // entity/node, where "which way to face while getting there" isn't a choice —
+  // only an undirected move onto open ground is.
+  function commandAt(p, queue, heading) {
     if (state.selection.length === 1) {
       const building = state.buildings.get(state.selection[0]);
       if (building && building.owner === "player" && BUILDINGS[building.type].produces) {
@@ -220,13 +234,19 @@ export function attachInput(canvas, state, onChange) {
       if (workers.length) { issueGather(workers, node.id, queue); sound.playOrder(); onChange(); }
       return;
     }
-    if (queue) aggressiveMove(selected, p.x, p.y, true);
-    else issueMove(selected, p.x, p.y, false, currentFormation());
+    if (queue) aggressiveMove(selected, p.x, p.y, true, heading);
+    else issueMove(selected, p.x, p.y, false, currentFormation(heading));
     sound.playOrder();
     onChange();
   }
 
   canvas.addEventListener("mousedown", e => {
+    if (e.button === 2) {
+      // The actual command (or a build/attack-move cancel) fires on mouseup below, once we
+      // know whether this stayed a click or became a drag — just mark where it started.
+      rightDragStart = toWorld(e.clientX, e.clientY);
+      return;
+    }
     if (e.button !== 0) return;
     const p = toWorld(e.clientX, e.clientY);
     if (buildMode) { placeBuildingAt(p); return; }
@@ -258,6 +278,23 @@ export function attachInput(canvas, state, onChange) {
   canvas.addEventListener("mouseleave", () => { edgePan = [0, 0]; }, { signal });
 
   window.addEventListener("mouseup", e => {
+    if (e.button === 2) {
+      const start = rightDragStart;
+      rightDragStart = null;
+      if (!start) return;   // the button went down somewhere this listener never saw (e.g. off-canvas)
+      if (buildMode) { buildMode = null; onChange(); return; }
+      if (attackMoveArmed) { setArmed(false); return; }   // right-click cancels a pending attack-move
+      const end = toWorld(e.clientX, e.clientY);
+      const dx = end.x - start.x, dy = end.y - start.y;
+      // A plain click carries no heading (the shape/facing fall back to the group's own travel
+      // direction, exactly as before); a real drag's direction becomes the explicit heading —
+      // see currentFormation/applyFacing. Holding Ctrl queues the order as a waypoint instead of
+      // replacing what the units are doing, so a sequence of Ctrl+right-drags lays down a
+      // multi-leg, individually-aimed path.
+      const heading = Math.hypot(dx, dy) >= CLICK_THRESHOLD ? { x: dx, y: dy } : null;
+      commandAt(start, e.ctrlKey, heading);
+      return;
+    }
     if (e.button !== 0 || !dragBox) return;
     const box = dragBox;
     dragBox = null;
@@ -278,19 +315,13 @@ export function attachInput(canvas, state, onChange) {
     selectSameTypeAt(toWorld(e.clientX, e.clientY));
   }, { signal });
 
-  canvas.addEventListener("contextmenu", e => {
-    e.preventDefault();
-    if (buildMode) { buildMode = null; onChange(); return; }
-    if (attackMoveArmed) { setArmed(false); return; }   // right-click cancels a pending attack-move
-
-    // Holding Ctrl queues the order as a waypoint instead of replacing what the
-    // units are doing, so a sequence of Ctrl+right-clicks lays down a path
-    // (move/attack/gather steps) the units run through in order. A plain
-    // right-click issues immediately and clears any queued waypoints. NOT Shift:
-    // Firefox force-shows the native context menu on Shift+right-click and
-    // bypasses preventDefault, so a Shift-queued order could never be captured.
-    commandAt(toWorld(e.clientX, e.clientY), e.ctrlKey);
-  }, { signal });
+  // The actual right-click handling (build/attack-move cancel, or commandAt with whatever
+  // heading the drag implies) lives on mouseup above, which fires before this — contextmenu's
+  // only remaining job is suppressing the browser's native menu. NOT Shift+right-click: Firefox
+  // force-shows the native context menu on it and bypasses preventDefault, so a Shift-modified
+  // right-drag could never be captured — Ctrl is the queue modifier here instead, for exactly
+  // that reason.
+  canvas.addEventListener("contextmenu", e => { e.preventDefault(); }, { signal });
 
   canvas.addEventListener("wheel", e => {
     e.preventDefault();

overlays.js

@@ -120,6 +120,7 @@ export function flashHint(msg) {
 const HELP_ROWS = [
   ["Left-drag", "Select units · Ctrl+drag adds to selection"],
   ["Right-click", "Move · attack an enemy · gather a node"],
+  ["Right-click and drag", "…the drag direction also becomes the group's (or a lone unit's) facing"],
   ["A, then click", "Attack-move — advance and engage on the way"],
   ["Ctrl+right-click", "Queue a waypoint (chain a path)"],
   ["1–9 / Shift+1–9", "Recall / bind a control group"],

renderShared.js

@@ -81,14 +81,22 @@ export function resetFacing() {
 
 // Infer and store a unit's facing angle from its frame-to-frame movement; returns the angle so
 // an oriented hull can draw pointing the way it's actually moving. A near-stationary unit keeps
-// its previous angle (no jitter). Buildings call it too (a turret barrel) — the "b*"/"u*" id
-// spaces can't collide in the shared map.
+// its previous angle EXCEPT when the player has set an explicit one (unit.facing — a real,
+// engine-side field set by a click-and-drag move/attack-move, engine/commands.js applyFacing):
+// then it snaps to/holds THAT instead, so a formation told to face the enemy actually does once
+// it stops, rather than freezing at whatever direction its last step of pathing happened to
+// leave it pointing. While actually moving, travel direction still wins — a unit sliding
+// sideways while nominally "facing" a fixed angle would read as broken, not deliberate. Buildings
+// call it too (a turret barrel, which never sets unit.facing) — the "b*"/"u*" id spaces can't
+// collide in the shared map.
 export function updateFacing(unit) {
   const prev = facing.get(unit.id);
-  let angle = prev ? prev.angle : -Math.PI / 2;
+  const explicit = Number.isFinite(unit.facing);
+  let angle = prev ? prev.angle : (explicit ? unit.facing : -Math.PI / 2);
   if (prev) {
     const dx = unit.x - prev.x, dy = unit.y - prev.y;
     if (Math.hypot(dx, dy) > 0.5) angle = Math.atan2(dy, dx);
+    else if (explicit) angle = unit.facing;
   }
   facing.set(unit.id, { x: unit.x, y: unit.y, angle });
   return angle;

test/formation.test.js

@@ -1,7 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { formationSlots, clusterUnits, pickLeader, FORMATION_SHAPES } from "../engine/formation.js";
-import { issueHoldFormation } from "../engine/commands.js";
+import { issueHoldFormation, issueMove, issueAttackMove, issueStop } from "../engine/commands.js";
 import { UNITS } from "../engine/entities.js";
 import { createGameState, makeUnit } from "../engine/state.js";
 import { tick } from "../engine/sim.js";
@@ -9,9 +9,14 @@ import { updateCombat } from "../engine/combat.js";
 import { serializeGame, deserializeGame } from "../engine/persist.js";
 
 // A bare positioned "unit" — enough for formation.js (which only reads id/type/x/y/maxHp),
-// without going through makeUnit/a real game state.
+// without going through makeUnit/a real game state. No `owner` on purpose for the pure-geometry
+// tests below (formation.js itself doesn't care); tests that exercise the PLAYER leader/follow
+// squad mechanic (engine/commands.js) need a real owner:"player" — see fakePlayerUnit.
 function fakeUnit(id, type, x, y, maxHp) {
-  return { id, type, x, y, maxHp: maxHp ?? UNITS[type].hp };
+  return { id, type, x, y, maxHp: maxHp ?? UNITS[type].hp, order: null };
+}
+function fakePlayerUnit(id, type, x, y) {
+  return { ...fakeUnit(id, type, x, y), owner: "player" };
 }
 
 // A minimal state (as the movement/combat tests use): just a unit Map + players, so we can drive
@@ -25,20 +30,13 @@ function miniState(...units) {
   };
 }
 
-// ---- pickLeader -------------------------------------------------------------
-
-test("pickLeader picks the unit with the most maxHp", () => {
-  const a = fakeUnit("u2", "skiff", 0, 0);         // maxHp 72
-  const b = fakeUnit("u1", "dreadnought", 0, 0);   // maxHp 340
-  const c = fakeUnit("u3", "worker", 0, 0);        // maxHp 40
-  assert.equal(pickLeader([a, b, c]).id, "u1");
-});
+// ---- pickLeader: the unit FIRST in the array, not a stat-based pick ----------
 
-test("pickLeader breaks a maxHp tie by the lower id, never by array order", () => {
-  const first = fakeUnit("u5", "skiff", 0, 0);
-  const second = fakeUnit("u4", "skiff", 0, 0);   // same maxHp, lower id, listed SECOND
-  assert.equal(pickLeader([first, second]).id, "u4");
-  assert.equal(pickLeader([second, first]).id, "u4");
+test("pickLeader is simply the first unit in the array — the one the rest were added to", () => {
+  const a = fakeUnit("u2", "dreadnought", 0, 0);   // highest maxHp, but NOT first
+  const b = fakeUnit("u1", "skiff", 0, 0);          // listed first
+  assert.equal(pickLeader([b, a]).id, "u1");
+  assert.equal(pickLeader([a, b]).id, "u2", "array order alone decides it — not maxHp");
 });
 
 // ---- clusterUnits: the nesting trigger ---------------------------------------
@@ -56,6 +54,13 @@ test("clusterUnits splits a selection spread across the map into separate armies
   assert.deepEqual(clusters.map(c => c.length).sort(), [3, 3]);
 });
 
+test("clusterUnits keeps the cluster containing units[0] first, so it stays the outer leader cluster", () => {
+  const leaderSide = [0, 1].map(i => fakeUnit(`L${i}`, "skiff", i * 10, 0));
+  const otherSide = [0, 1].map(i => fakeUnit(`O${i}`, "skiff", 3000 + i * 10, 0));
+  const clusters = clusterUnits([...leaderSide, ...otherSide]);
+  assert.equal(clusters[0][0].id, "L0", "units[0]'s cluster is clusters[0]");
+});
+
 // ---- formationSlots: the default (grid, single cluster) path stays legacy-exact ----
 
 test("formationSlots grid (no shape chosen) matches the exact legacy spacing formula", () => {
@@ -89,65 +94,74 @@ test("line/wedge/circle center their group's centroid exactly on the destination
   }
 });
 
+// ---- explicit heading override ------------------------------------------------
+
+test("an explicit headingX/headingY overrides the origin-derived heading", () => {
+  const units = [0, 1, 2, 3].map(i => fakeUnit(`u${i}`, "skiff", 0, 0));
+  // origin==dest (no travel at all) defaults to a stable heading (see the "line formation"
+  // tests below, which rely on exactly this default) — an explicit override must still change
+  // the resulting layout rather than being silently ignored.
+  const withoutOverride = formationSlots(units, 500, 500, { shape: "line", originX: 500, originY: 500 });
+  const withOverride = formationSlots(units, 500, 500, { shape: "line", originX: 500, originY: 500, headingX: 0, headingY: -1 });
+  assert.notDeepEqual(withOverride, withoutOverride, "an explicit heading produces a different layout than the origin-derived default");
+});
+
 // ---- line ---------------------------------------------------------------------
+// The leader is always units[0] — these tests put the intended leader FIRST in the array.
 
 test("line formation: leaderPos front pushes the leader ahead of the rest of the line", () => {
-  const leader = fakeUnit("L", "dreadnought", 0, 0);
+  const leader = fakeUnit("L", "skiff", 0, 0);
   const followers = [1, 2, 3, 4].map(i => fakeUnit(`f${i}`, "skiff", 0, 0));
-  const units = [...followers, leader];
+  const units = [leader, ...followers];
   const spots = formationSlots(units, 1000, 0, { shape: "line", leaderPos: "front", originX: 0, originY: 0 });
-  const leaderX = spots[units.indexOf(leader)].x;
-  const avgFollowerX = followers.reduce((s, f) => s + spots[units.indexOf(f)].x, 0) / followers.length;
+  const leaderX = spots[0].x;
+  const avgFollowerX = spots.slice(1).reduce((s, p) => s + p.x, 0) / followers.length;
   assert.ok(leaderX > avgFollowerX, "the leader sits ahead of the line toward the heading");
 });
 
 test("line formation: leaderPos back tucks the leader behind the line", () => {
-  const leader = fakeUnit("L", "dreadnought", 0, 0);
+  const leader = fakeUnit("L", "skiff", 0, 0);
   const followers = [1, 2, 3, 4].map(i => fakeUnit(`f${i}`, "skiff", 0, 0));
-  const units = [...followers, leader];
+  const units = [leader, ...followers];
   const spots = formationSlots(units, 1000, 0, { shape: "line", leaderPos: "back", originX: 0, originY: 0 });
-  const leaderX = spots[units.indexOf(leader)].x;
-  const avgFollowerX = followers.reduce((s, f) => s + spots[units.indexOf(f)].x, 0) / followers.length;
+  const leaderX = spots[0].x;
+  const avgFollowerX = spots.slice(1).reduce((s, p) => s + p.x, 0) / followers.length;
   assert.ok(leaderX < avgFollowerX, "the leader trails behind the line");
 });
 
 // ---- wedge ----------------------------------------------------------------------
 
 test("wedge formation: leaderPos front puts the leader at the tip, most forward of everyone", () => {
-  const leader = fakeUnit("L", "dreadnought", 0, 0);
+  const leader = fakeUnit("L", "skiff", 0, 0);
   const others = [1, 2, 3, 4].map(i => fakeUnit(`f${i}`, "skiff", 0, 0));
   const units = [leader, ...others];
   const spots = formationSlots(units, 1000, 0, { shape: "wedge", leaderPos: "front", originX: 0, originY: 0 });
-  const leaderX = spots[units.indexOf(leader)].x;
-  for (const o of others) assert.ok(leaderX >= spots[units.indexOf(o)].x - 1e-6, `${o.id} trails the tip`);
+  const leaderX = spots[0].x;
+  for (const p of spots.slice(1)) assert.ok(leaderX >= p.x - 1e-6, "every flank trails the tip");
 });
 
 test("wedge formation: leaderPos back shields the leader at the rear vertex, flanks leading", () => {
-  const leader = fakeUnit("L", "dreadnought", 0, 0);
+  const leader = fakeUnit("L", "skiff", 0, 0);
   const others = [1, 2, 3, 4].map(i => fakeUnit(`f${i}`, "skiff", 0, 0));
   const units = [leader, ...others];
   const spots = formationSlots(units, 1000, 0, { shape: "wedge", leaderPos: "back", originX: 0, originY: 0 });
-  const leaderX = spots[units.indexOf(leader)].x;
-  for (const o of others) assert.ok(leaderX <= spots[units.indexOf(o)].x + 1e-6, `${o.id} leads ahead of the shielded leader`);
+  const leaderX = spots[0].x;
+  for (const p of spots.slice(1)) assert.ok(leaderX <= p.x + 1e-6, "every flank leads ahead of the shielded leader");
 });
 
 // ---- circle -----------------------------------------------------------------
 
 test("circle formation: leaderPos center seats the leader at the anchor, escorted by a ring", () => {
-  const leader = fakeUnit("L", "dreadnought", 0, 0);
+  const leader = fakeUnit("L", "skiff", 0, 0);
   const others = [1, 2, 3, 4, 5].map(i => fakeUnit(`f${i}`, "skiff", 0, 0));
   const units = [leader, ...others];
   const spots = formationSlots(units, 900, 700, { shape: "circle", leaderPos: "center", originX: 0, originY: 0 });
-  const leaderSpot = spots[units.indexOf(leader)];
-  assert.ok(Math.hypot(leaderSpot.x - 900, leaderSpot.y - 700) < 0.5, "leader sits at the anchor");
-  for (const o of others) {
-    const p = spots[units.indexOf(o)];
-    assert.ok(Math.hypot(p.x - 900, p.y - 700) > 10, `${o.id} stands out on the protective ring`);
-  }
+  assert.ok(Math.hypot(spots[0].x - 900, spots[0].y - 700) < 0.5, "leader sits at the anchor");
+  for (const p of spots.slice(1)) assert.ok(Math.hypot(p.x - 900, p.y - 700) > 10, "an escort stands out on the protective ring");
 });
 
 test("circle formation: leaderPos front/back puts every unit, leader included, on the ring", () => {
-  const leader = fakeUnit("L", "dreadnought", 0, 0);
+  const leader = fakeUnit("L", "skiff", 0, 0);
   const others = [1, 2, 3].map(i => fakeUnit(`f${i}`, "skiff", 0, 0));
   const units = [leader, ...others];
   const spots = formationSlots(units, 900, 700, { shape: "circle", leaderPos: "front", originX: 0, originY: 0 });
@@ -204,24 +218,52 @@ test("formationSlots lays out a nested formation of formations — tight within
   assert.ok(Math.abs(avgX - 1500) < 5 && Math.abs(avgY - 0) < 5, "the nested layout as a whole is still centered on the destination");
 });
 
-// ---- issueHoldFormation (engine/commands.js) ---------------------------------
+// ---- AI-owned (and owner-less) units never form a squad ----------------------
+// The leader/follow mechanic is a PLAYER selection-UX feature: the scripted AI (and any test
+// double with no owner set) always gets the plain, pre-existing per-unit spread — every unit its
+// own real order, no leader, no follow-leader, no speed cap.
 
-test("issueHoldFormation anchors the group on its own current centroid, not the map origin", () => {
-  const units = [
-    { id: "u1", type: "skiff", x: 100, y: 100, maxHp: 72, order: null },
-    { id: "u2", type: "skiff", x: 120, y: 100, maxHp: 72, order: null },
-  ];
-  issueHoldFormation(units, "grid", "front");
+test("issueMove on AI-owned units gives every unit its own real move order — no squad", () => {
+  const units = [fakeUnit("a1", "skiff", 0, 0), fakeUnit("a2", "skiff", 0, 0)].map(u => ({ ...u, owner: "ai" }));
+  issueMove(units, 900, 700);
   for (const u of units) {
-    assert.equal(u.order.type, "hold-formation");
-    assert.equal(u.order.anchorX, 110);
-    assert.equal(u.order.anchorY, 100);
-    assert.equal(u.hold, true, "a combat unit also takes the Hold stance");
+    assert.equal(u.order.type, "move");
+    assert.ok(Number.isFinite(u.order.x) && Number.isFinite(u.order.y));
   }
+  assert.equal(units[1].order.type, "move", "the second unit is NOT a follow-leader");
+  assert.equal(units.some(u => u.squadLeader), false);
+});
+
+test("issueMove on owner-less units (a bare test double) also skips the squad mechanic", () => {
+  const units = [fakeUnit("u1", "skiff", 0, 0), fakeUnit("u2", "skiff", 0, 0)];   // no owner field at all
+  issueMove(units, 900, 700);
+  units.forEach(u => assert.equal(u.order.type, "move"));
+});
+
+// ---- issueHoldFormation / the leader-follow squad (engine/commands.js) -------
+
+test("issueHoldFormation makes units[0] the leader (anchored near the group's own centroid) and everyone else a follower", () => {
+  const units = [fakePlayerUnit("u1", "skiff", 100, 100), fakePlayerUnit("u2", "skiff", 120, 100)];
+  issueHoldFormation(units, "grid", "front");
+  const [leader, follower] = units;
+  assert.equal(leader.order.type, "hold-formation");
+  // The grid shape gives the leader its own slot in the grid (not necessarily the exact
+  // centroid — see the "matches the exact legacy spacing formula" test), but it's always
+  // WITHIN the group's own footprint, close to where the two units actually are.
+  assert.ok(Math.hypot(leader.order.anchorX - 110, leader.order.anchorY - 100) < 20);
+  assert.equal(follower.order.type, "follow-leader");
+  assert.equal(follower.order.leader, leader);
+  assert.equal(follower.squadLeader, leader);
+  assert.deepEqual(leader.squadFollowers, [follower]);
+  assert.equal(leader.hold, true, "a combat leader also takes the Hold stance");
+  assert.equal(follower.hold, true, "…and so does a combat follower");
+  // Leader and follower end up at distinct points (the formation's own spacing), not stacked.
+  const followerTarget = { x: leader.order.anchorX + follower.order.offsetX, y: leader.order.anchorY + follower.order.offsetY };
+  assert.ok(Math.hypot(followerTarget.x - leader.order.anchorX, followerTarget.y - leader.order.anchorY) > 5);
 });
 
 test("issueHoldFormation gives a non-combat unit a slot but no Hold stance to set", () => {
-  const worker = { id: "u1", type: "worker", x: 0, y: 0, maxHp: 40, order: null };
+  const worker = fakePlayerUnit("u1", "worker", 0, 0);
   issueHoldFormation([worker]);
   assert.equal(worker.order.type, "hold-formation");
   assert.ok(!worker.hold);
@@ -231,18 +273,99 @@ test("issueHoldFormation on an empty selection is a safe no-op", () => {
   assert.doesNotThrow(() => issueHoldFormation([]));
 });
 
-// ---- sim/combat integration: keepFormationStation ----------------------------
+// ---- persistent leader-follow: select the leader alone, move it, others trail --
+
+test("a solo move on the leader alone drags its existing followers along, capped to the group's slowest speed", () => {
+  const leader = fakePlayerUnit("L", "bulkfreighter", 100, 100);   // slow (speed 32)
+  const follower = fakePlayerUnit("F", "ranger", 120, 100);        // fast (speed 115)
+  issueMove([leader, follower], 1000, 100);
+  assert.equal(leader.order.speedCap, UNITS.bulkfreighter.speed, "capped to the slowest member");
+  assert.equal(follower.order.type, "follow-leader");
+  assert.equal(follower.order.leader, leader);
+
+  // Now command the LEADER alone — the follower's order is untouched (still follow-leader,
+  // still pointing at the same live leader object), so it keeps trailing automatically.
+  issueMove([leader], 50, 100);
+  assert.equal(leader.order.type, "move");
+  assert.equal(leader.order.speedCap, UNITS.bulkfreighter.speed, "the solo command still re-derives the group's speed cap");
+  assert.equal(follower.order.type, "follow-leader", "never re-issued — it was already chasing the leader");
+  assert.equal(follower.order.leader, leader);
+});
+
+test("a follower given a DIRECT order leaves the squad — the leader's own list drops it", () => {
+  const leader = fakePlayerUnit("L", "skiff", 0, 0);
+  const follower = fakePlayerUnit("F", "skiff", 0, 0);
+  issueHoldFormation([leader, follower]);
+  assert.equal(follower.squadLeader, leader);
+
+  issueMove([follower], 500, 500);   // a direct command to the follower alone
+
+  assert.equal(follower.order.type, "move", "direct control wins");
+  assert.equal(follower.squadLeader, undefined, "no longer tracked as this leader's follower");
+  assert.deepEqual(leader.squadFollowers, [], "the leader's own list was trimmed to match");
+});
+
+test("issueStop on a follower releases it from the squad too", () => {
+  const leader = fakePlayerUnit("L", "skiff", 0, 0);
+  const follower = fakePlayerUnit("F", "skiff", 0, 0);
+  issueHoldFormation([leader, follower]);
+  issueStop([follower]);
+  assert.equal(follower.order, null);
+  assert.equal(follower.squadLeader, undefined);
+  assert.deepEqual(leader.squadFollowers, []);
+});
+
+test("redefining a leader's squad with a smaller group stops (not just unlinks) the dropped-out unit", () => {
+  const leader = fakePlayerUnit("L", "skiff", 0, 0);
+  const a = fakePlayerUnit("A", "skiff", 0, 0);
+  const b = fakePlayerUnit("B", "skiff", 0, 0);
+  issueHoldFormation([leader, a, b]);
+  assert.deepEqual(leader.squadFollowers, [a, b]);
+
+  issueMove([leader, a], 500, 0);   // a fresh command that only re-selects the leader + A
+
+  assert.deepEqual(leader.squadFollowers, [a], "B fell out of the squad");
+  assert.equal(b.squadLeader, undefined);
+  assert.equal(b.order, null, "B is actually stopped, not left silently chasing a leader that dropped it");
+  assert.equal(a.order.type, "follow-leader", "A is still following");
+});
+
+// ---- click-and-drag facing (engine/commands.js applyFacing) ------------------
+
+test("issueMove with an explicit heading stamps every commanded unit's facing; a plain move clears it", () => {
+  const units = [fakePlayerUnit("u1", "skiff", 0, 0), fakePlayerUnit("u2", "skiff", 0, 0)];
+  issueMove(units, 100, 0, false, { headingX: 0, headingY: 1 });   // facing straight down (+y)
+  for (const u of units) assert.ok(Math.abs(u.facing - Math.PI / 2) < 1e-6);
+
+  issueMove(units, 100, 0);   // a later plain move, no heading
+  for (const u of units) assert.ok(!Number.isFinite(u.facing), "no explicit heading clears the earlier facing");
+});
+
+test("issueAttackMove also stamps and clears facing the same way", () => {
+  const units = [fakePlayerUnit("u1", "skiff", 0, 0)];
+  issueAttackMove(units, 100, 0, false, { headingX: -1, headingY: 0 });   // facing left
+  assert.ok(Math.abs(units[0].facing - Math.PI) < 1e-6);
+  issueAttackMove(units, 100, 0);
+  assert.ok(!Number.isFinite(units[0].facing));
+});
+
+// ---- sim/combat integration: keepFormationStation / keepFollowingLeader -----
 
-test("a combat unit holding formation converges on its own anchor+offset slot and never clears the order on arrival", () => {
-  const units = [makeUnit("skiff", "player", 100, 100), makeUnit("skiff", "player", 300, 300)];
+test("a leader holding formation converges on its own anchor; a follower converges on leader+offset — arrival never clears either", () => {
+  const leader = makeUnit("skiff", "player", 100, 100);
+  const follower = makeUnit("skiff", "player", 300, 300);
+  const units = [leader, follower];
   const s = miniState(...units);
   issueHoldFormation(units, "line", "front");
   for (let i = 0; i < 400; i++) for (const u of units) updateCombat(s, u, 0.1);
-  for (const u of units) {
-    const tx = u.order.anchorX + u.order.offsetX, ty = u.order.anchorY + u.order.offsetY;
-    assert.ok(Math.hypot(u.x - tx, u.y - ty) < 5, `${u.id} reached its formation slot`);
-    assert.equal(u.order.type, "hold-formation", "arrival never clears a hold-formation order");
-  }
+
+  const leaderTarget = { x: leader.order.anchorX + leader.order.offsetX, y: leader.order.anchorY + leader.order.offsetY };
+  assert.ok(Math.hypot(leader.x - leaderTarget.x, leader.y - leaderTarget.y) < 5, "leader reached its own anchor");
+  assert.equal(leader.order.type, "hold-formation");
+
+  const followerTarget = { x: leader.x + follower.order.offsetX, y: leader.y + follower.order.offsetY };
+  assert.ok(Math.hypot(follower.x - followerTarget.x, follower.y - followerTarget.y) < 5, "follower reached leader+offset");
+  assert.equal(follower.order.type, "follow-leader");
 });
 
 test("a unit holding formation still fires on a threat that wanders into weapon range", () => {
@@ -268,31 +391,78 @@ test("the Hold stance keeps a formation unit from chasing a target out of weapon
   assert.ok(Math.hypot(guard.x - startX, guard.y - startY) < 2, "held ground instead of closing on an out-of-range target");
 });
 
-test("a worker (non-combat) holding formation reaches its slot via the full sim tick path", () => {
+test("a combat follower still auto-engages a threat, then resumes following", () => {
+  const leader = makeUnit("skiff", "player", 500, 500);
+  const follower = makeUnit("skiff", "player", 540, 500);
+  const units = [leader, follower];
+  const s = miniState(...units);
+  issueHoldFormation(units);
+  for (let i = 0; i < 100; i++) for (const u of units) updateCombat(s, u, 0.1);   // settle into formation
+
+  const enemy = makeUnit("skiff", "ai", follower.x + 20, follower.y);   // right on the follower
+  enemy.hp = enemy.maxHp = 100000;
+  s.units.set(enemy.id, enemy);
+  for (let i = 0; i < 80; i++) updateCombat(s, follower, 0.1);
+  assert.ok(enemy.hp < enemy.maxHp, "the follower broke to engage a threat at its post");
+  assert.equal(follower.order.type, "follow-leader", "still tracking its leader throughout");
+});
+
+test("a follower drops its order (free to be re-ordered) the moment its leader dies", () => {
+  const leader = makeUnit("skiff", "player", 500, 500);
+  const follower = makeUnit("skiff", "player", 540, 500);
+  const s = miniState(leader, follower);
+  issueHoldFormation([leader, follower]);
+  leader.hp = 0;   // the leader has died (removeEntity already dropped it from state.units in real play)
+  updateCombat(s, follower, 0.1);
+  assert.equal(follower.order, null, "no live leader to follow → free for a new order");
+});
+
+test("a worker (non-combat) leader+follower pair reaches its formation via the full sim tick path", () => {
   const s = createGameState({ planetId: "ferros", seed: 2 });
   const w1 = makeUnit("worker", "player", 500, 500);
   const w2 = makeUnit("worker", "player", 700, 500);
+  const units = [w1, w2];
   s.units.set(w1.id, w1); s.units.set(w2.id, w2);
-  issueHoldFormation([w1, w2], "line", "front");
+  issueHoldFormation(units, "line", "front");
   for (let i = 0; i < 200; i++) tick(s, 0.1);
-  for (const u of [w1, w2]) {
-    const tx = u.order.anchorX + u.order.offsetX, ty = u.order.anchorY + u.order.offsetY;
-    assert.ok(Math.hypot(u.x - tx, u.y - ty) < 10, `${u.id} reached its slot`);
-    assert.equal(u.order.type, "hold-formation");
-  }
+
+  const leaderTarget = { x: w1.order.anchorX + w1.order.offsetX, y: w1.order.anchorY + w1.order.offsetY };
+  assert.ok(Math.hypot(w1.x - leaderTarget.x, w1.y - leaderTarget.y) < 10, "leader reached its anchor");
+  const followerTarget = { x: w1.x + w2.order.offsetX, y: w1.y + w2.order.offsetY };
+  assert.ok(Math.hypot(w2.x - followerTarget.x, w2.y - followerTarget.y) < 10, "follower reached leader+offset");
 });
 
-test("a support unit (Mender) holding formation keeps station via updateSupport", () => {
+test("a support unit (Mender) leader+follower pair keeps station via updateSupport", () => {
   const s = createGameState({ planetId: "ferros", seed: 3 });
   const m1 = makeUnit("mender", "player", 500, 500);
   const m2 = makeUnit("mender", "player", 700, 500);
   s.units.set(m1.id, m1); s.units.set(m2.id, m2);
   issueHoldFormation([m1, m2], "circle", "front");
   for (let i = 0; i < 200; i++) tick(s, 0.1);
-  for (const u of [m1, m2]) {
-    const tx = u.order.anchorX + u.order.offsetX, ty = u.order.anchorY + u.order.offsetY;
-    assert.ok(Math.hypot(u.x - tx, u.y - ty) < 10, `${u.id} reached its slot`);
-  }
+  const leaderTarget = { x: m1.order.anchorX + m1.order.offsetX, y: m1.order.anchorY + m1.order.offsetY };
+  assert.ok(Math.hypot(m1.x - leaderTarget.x, m1.y - leaderTarget.y) < 10);
+  const followerTarget = { x: m1.x + m2.order.offsetX, y: m1.y + m2.order.offsetY };
+  assert.ok(Math.hypot(m2.x - followerTarget.x, m2.y - followerTarget.y) < 10);
+});
+
+test("a formation's travel speed never outruns its slowest member, via the real tick loop", () => {
+  const s = createGameState({ planetId: "ferros", seed: 5 });
+  const leader = makeUnit("bulkfreighter", "player", 500, 500);   // speed 32 — the slowest
+  // Placed ALONGSIDE the leader (perpendicular to the +x travel direction), not directly ahead
+  // of it on the path — so movement.js's lateral-avoidance sensing (same-owner neighbours AHEAD
+  // in the seek direction) never engages and curves either unit's path, keeping this a clean
+  // measurement of the speed cap alone.
+  const follower = makeUnit("ranger", "player", 500, 530);        // speed 115 — much faster
+  s.units.set(leader.id, leader); s.units.set(follower.id, follower);
+  issueMove([leader, follower], 1500, 500);
+  for (let i = 0; i < 50; i++) tick(s, 0.1);   // 5 sim seconds
+  const traveled = leader.x - 500;
+  assert.ok(traveled < UNITS.ranger.speed * 5 * 0.5,
+    `the leader (${traveled.toFixed(0)} travelled) moves far slower than the follower's own top speed would allow`);
+  // The formation's grid layout for 2 units puts the follower's slot 20 units off the leader's
+  // own — see the "matches the exact legacy spacing formula" test above (spacing 20, cols 2).
+  const gap = Math.hypot(follower.x - (leader.x + 20), follower.y - leader.y);
+  assert.ok(gap < 10, `the fast follower stays tight on the slow leader (gap ${gap.toFixed(1)}), not racing ahead and idling`);
 });
 
 // ---- persistence --------------------------------------------------------------
@@ -318,3 +488,22 @@ test("a hold-formation order survives save/load, and a tampered anchor/offset ca
   tick(restored, 0.1);
   assert.ok(Number.isFinite(ru1.x) && Number.isFinite(ru1.y), "position stays finite even with a garbage anchor/offset");
 });
+
+test("a follow-leader order (and squadLeader/squadFollowers) never survives save/load — no circular reference crash", () => {
+  const s = createGameState({ planetId: "ferros", seed: 6 });
+  const leader = makeUnit("skiff", "player", 500, 500);
+  const follower = makeUnit("skiff", "player", 540, 500);
+  s.units.set(leader.id, leader); s.units.set(follower.id, follower);
+  issueHoldFormation([leader, follower]);
+
+  let payload;
+  assert.doesNotThrow(() => { payload = JSON.parse(JSON.stringify(serializeGame(s))); },
+    "serializing a live squad (a circular leader<->follower reference) must not throw");
+
+  const restored = deserializeGame(payload);
+  const rLeader = [...restored.units.values()].find(u => u.id === leader.id);
+  const rFollower = [...restored.units.values()].find(u => u.id === follower.id);
+  assert.equal(rFollower.order, null, "the follow-leader order is dropped, not reconstructed");
+  assert.equal(rLeader.squadFollowers, undefined);
+  assert.equal(rFollower.squadLeader, undefined);
+});

test/input.test.js

@@ -87,6 +87,16 @@ function clientFor(controller, wx, wy) {
   return { clientX: VW / 2 + (wx - cam.x) * cam.zoom, clientY: VH / 2 + (wy - cam.y) * cam.zoom };
 }
 
+// A real right-click (as of the click-and-drag heading gesture) is a button-2 mousedown on the
+// canvas followed by a button-2 mouseup on window — commandAt now fires from mouseup, not a bare
+// `contextmenu` event (contextmenu's only remaining job is suppressing the browser's native
+// menu). Mouse down and up at the SAME point is a plain click: no drag, so no explicit heading —
+// byte-identical to the old single-event behaviour these tests were written against.
+function rightClick(canvas, window, clientX, clientY, ctrlKey = false) {
+  canvas.dispatchEvent(ev("mousedown", { button: 2, clientX, clientY }));
+  window.dispatchEvent(ev("mouseup", { button: 2, clientX, clientY, ctrlKey }));
+}
+
 // ============================================================================
 // Bug 1 — alt-tab camera drift: a backgrounded tab doesn't reliably get a keyup, so a
 // pan key held at the moment of alt-tab must not stay "held" forever. A window blur is
@@ -148,7 +158,7 @@ test("commandAt still notifies on a rally order (regression: the branch that alr
   state.selection = [cc.id];
 
   const { clientX, clientY } = clientFor(controller, 2500, 2600);
-  canvas.dispatchEvent(ev("contextmenu", { clientX, clientY, ctrlKey: false }));
+  rightClick(canvas, window, clientX, clientY);
 
   assert.deepEqual(cc.rally, { x: 2500, y: 2600, nodeId: null });
   assert.equal(calls(), 1, "onChange fires exactly once for the order");
@@ -164,7 +174,7 @@ test("commandAt notifies on an attack order (the headline branch the review flag
   reveal(state.fog, enemy.x, enemy.y);   // entityAt only returns a non-player unit if it's visible
 
   const { clientX, clientY } = clientFor(controller, enemy.x, enemy.y);
-  canvas.dispatchEvent(ev("contextmenu", { clientX, clientY, ctrlKey: false }));
+  rightClick(canvas, window, clientX, clientY);
 
   assert.deepEqual(attacker.order, { type: "attack", targetId: enemy.id });
   assert.equal(calls(), 1, "the HUD's Attack-Move button (and everything else onChange refreshes) must hear about this immediately, not on a stray HUD tick");
@@ -179,7 +189,7 @@ test("commandAt notifies on a gather order", () => {
   state.map.nodes.push(node);
 
   const { clientX, clientY } = clientFor(controller, node.x, node.y);
-  canvas.dispatchEvent(ev("contextmenu", { clientX, clientY, ctrlKey: false }));
+  rightClick(canvas, window, clientX, clientY);
 
   assert.deepEqual(worker.order, { type: "gather", nodeId: "node-1" });
   assert.equal(calls(), 1);
@@ -192,12 +202,50 @@ test("commandAt notifies on the plain move fallback (nothing at the click point)
   state.selection = [worker.id];
 
   const { clientX, clientY } = clientFor(controller, 2800, 1400);   // empty ground, no unit/building/node
-  canvas.dispatchEvent(ev("contextmenu", { clientX, clientY, ctrlKey: false }));
+  rightClick(canvas, window, clientX, clientY);
 
   assert.deepEqual(worker.order, { type: "move", x: 2800, y: 1400 });
   assert.equal(calls(), 1, "the fallback move branch must notify too, not just the rally special case");
 });
 
+// ============================================================================
+// Click-and-drag heading: a right-DRAG (mousedown then mouseup at a different point) sets the
+// destination at the DRAG'S START and stamps the drag direction as an explicit facing (a plain
+// click carries none — the two commandAt tests above already cover that byte-identical case).
+// ============================================================================
+
+test("a right-drag moves to where the drag STARTED, not where it ended", () => {
+  const { state, canvas, controller } = setup();
+  const worker = makeUnit("worker", "player", 500, 500);
+  state.units.set(worker.id, worker);
+  state.selection = [worker.id];
+
+  const start = clientFor(controller, 2800, 1400);
+  const end = clientFor(controller, 3200, 1400);   // dragged further along +x
+  canvas.dispatchEvent(ev("mousedown", { button: 2, clientX: start.clientX, clientY: start.clientY }));
+  window.dispatchEvent(ev("mouseup", { button: 2, clientX: end.clientX, clientY: end.clientY }));
+
+  assert.deepEqual(worker.order, { type: "move", x: 2800, y: 1400 }, "destination is the drag's START point");
+});
+
+test("a right-drag stamps the drag direction as the unit's facing; a plain click clears it", () => {
+  const { state, canvas, controller } = setup();
+  const worker = makeUnit("worker", "player", 500, 500);
+  state.units.set(worker.id, worker);
+  state.selection = [worker.id];
+
+  const start = clientFor(controller, 2800, 1400);
+  const end = clientFor(controller, 2800, 1800);   // dragged straight down (+y) from the start point
+  canvas.dispatchEvent(ev("mousedown", { button: 2, clientX: start.clientX, clientY: start.clientY }));
+  window.dispatchEvent(ev("mouseup", { button: 2, clientX: end.clientX, clientY: end.clientY }));
+
+  assert.ok(Number.isFinite(worker.facing), "the drag set an explicit facing");
+  assert.ok(Math.abs(worker.facing - Math.PI / 2) < 1e-6, "facing straight down (+y) is angle PI/2");
+
+  rightClick(canvas, window, start.clientX, start.clientY);   // a later PLAIN click, no drag
+  assert.ok(!Number.isFinite(worker.facing), "a plain command with no heading clears the earlier facing");
+});
+
 // ============================================================================
 // Bug 3 — dblclick ignored buildMode/attackMoveArmed and ran its normal
 // reselect-fleet-of-this-type logic regardless, silently overriding the click that had