docs/analysis/03-client-coupling.md

03 — Client coupling: what must change to become a networked client

Status: analysis, input to ADRs and TASKS.md. Not a specification. Source audited: /home/user/alma92350/spaceexploration-rts @ working tree (read-only clone). Assumed decision (upstream): server-authoritative headless Node sim; the browser renders a state it is given and sends commands instead of mutating locally.

All file.js:line citations are against the SOURCE tree. Line numbers are exact at the time of writing; they are cited so a reader can confirm each claim, not as a patch plan.

---

0. Headline findings

Five facts shape everything below. They are the reason this port is a re-seaming job and not a rewrite.

1. The client barely mutates the sim. Outside engine/, sim mutation happens at exactly 56 call sites across 6 files — and all but 10 of them go through named engine functions (issue*, queueProduction, sell/buy, …) that already take an explicit (state, entityId, args) shape. Those 46 sites are already command envelopes; they just aren't serialized. The other 10 are state.selection = …, which isn't sim state at all (engine/persist.js:777 resets it to [] on load).
2. No client file writes resources or credits directly. Verified by grep — zero hits. Every economic mutation is an engine call. The trust boundary is therefore already drawn in the right place; it is simply not enforced.
3. The engine is already owner-generic in its bones. state.owners is the canonical side list, state.players and state.fogs are keyed by owner id, and state.fog/state.fogAI are documented aliases into state.fogs (engine/state.js:167-189, 227-234), pinned by test/ownerScaffold.test.js. Victory already iterates state.owners (engine/victory.js:11, 30, 165). "Seat 3 of 5" is a change to ownerDefs (engine/state.js:174-181), not a sweep.
4. The renderers are already owner-generic for colour and already fog-gate every entity. Team colour is read as state.players[owner].color at all four draw sites (renderUnits.js:66, renderBuildings.js:75, minimap.js:95, minimap.js:100); the fog rule is factored into one named predicate, renderShared.js:253 hiddenByFog. Nothing hardcodes #4fd1ff/#f87171 for entities — those literals live in engine/state.js:179-180 as data.
5. The sim is cheap. Measured on this machine: a full skirmish with both seats AI-driven costs 0.096–0.142 ms/tick (27,000 ticks, 15 sim-minutes, small and 2× maps). At 20 Hz that is ~0.2–0.3 % of one core per match. A single Node process can host dozens of concurrent matches without breaking a sweat. Headless authority is not a performance risk.

The real work is concentrated in three places: boot.js (the lifecycle), input.js + inputCommands.js + hudSelection.js (the ~46 synchronous engine calls), and the ~110 hardcoded "player"/"ai" owner literals scattered across the HUD and renderers.

---

1. The local-authority inventory

1.1 engine/commands.js issue* — direct order issuance

engine/commands.js exports 22 issue* functions (lines 231–531). Four client files import them. Every one of these becomes submitCommand(envelope).

Site	Call	Notes
main.js:21	import issueMove, issueAttackMove	minimap right-click
main.js:149	issueAttackMove(combatants, world.x, world.y)	minimap command
main.js:150	issueMove(others, world.x, world.y)	minimap command
input.js:12	import issueBuild, issueStop, issueScout, issueHold, issueHoldFormation, issuePatrol
input.js:346	issueStop(selectedUnits())	S key
input.js:351	issueScout(selectedUnits())	scout toggle
input.js:355	issueHold(selectedUnits())	H key
input.js:372	issuePatrol([u], points)	per-unit patrol loop
input.js:379	issueHoldFormation(selectedUnits(), game.formation.shape, game.formation.leaderPos)	reads client-only game.formation (session.js:75)
input.js:521	issueBuild(state, worker.id, buildingType, p.x, p.y)	returns a value the client uses — see §1.6
inputCommands.js:27	import 11 issue*	the right-click router
inputCommands.js:94	issueAttackMove(combatants, x, y, queue, formation)
inputCommands.js:95	issueMove(others, x, y, queue, formation)
inputCommands.js:199	issueSetRally(building, p.x, p.y, node?.id)	passes a live building object, not an id
inputCommands.js:212	issueAssistBuild(workers, target.id, target.type, queue)
inputCommands.js:226	issueServiceBuilding(workers, target.id, queue)
inputCommands.js:235	issueRepair(workers, target.id, queue)
inputCommands.js:245	issueSetHomeBase(eligible, target.id)
inputCommands.js:249	issueAttack(attackers, target.id, queue)
inputCommands.js:259	issueFerryFreighter(workers, target.id, queue)
inputCommands.js:266	issueRepair(workers, target.id, queue)
inputCommands.js:273	issueEscort(escorts, target.id, queue)
inputCommands.js:278	issueGather(workers, node.id, queue)
inputCommands.js:282	issueMove(selected, p.x, p.y, false, currentFormation(heading))
hudSelection.js:21	import issueSetAILogistics, issueSetCollectPoint, issueSetLogiPriority, issueRecycle, issueCancelRecycle
hudSelection.js:518	issueSetAILogistics([f], !on, state)
hudSelection.js:542	issueSetCollectPoint([f], !on)
hudSelection.js:600	issueSetLogiPriority(state, b.id, LOGI_PRIORITY_NEXT[cur])
hudSelection.js:1821	issueCancelRecycle(recyclingNow)	passes live entity objects
hudSelection.js:1835	issueRecycle(recyclable)	passes live entity objects
tools/ailab.js:78,82,168-320	issueAttackMove, issueBuild	headless bench, not shipped client

Shape problem to fix once: most issue* take arrays of live unit objects, and three take live building/entity objects (inputCommands.js:199, hudSelection.js:1821, :1835). A wire envelope must carry ids. Recommended: add one dispatcher, applyCommand(state, seat, {verb, ids, args}), in engine/commands.js that resolves ids → entities, filters to entities owned by seat (this is the anti-cheat gate, and it does not exist anywhere today), then calls the existing issue* unchanged. Every existing test/commands.test.js assertion (503 LOC) keeps passing against the raw issue*.

1.2 Non-issue* engine mutators called from the client

These are just as authoritative and are easy to miss because they don't share a prefix.

Site	Call	Subsystem
hudSelection.js:1098, 1104, 1198, 1629	queueProduction(state, b.id, t[, true])	production
hudSelection.js:197	cancelProduction(state, building.id, i)	production
hudSelection.js:1149	researchUpgrade(state, refinery.id, u.id)	tech
hudSelection.js:1179	researchTech(state, datacenter.id, t.id)	tech (Odyssey)
hudSelection.js:235	cancelResearch(state, building.id, i)	tech
hudSelection.js:381, 395, 405	sell(game.galaxy, state, com, qty)	market (Odyssey)
hudSelection.js:414	buy(game.galaxy, state, com, TRADE_LOT)	market (Odyssey)
hudSelection.js:449, 485	loadFreighter(state, f.id, com, qty)	freight (Odyssey)
hudSelection.js:459, 494	unloadFreighter(state, f.id, com, qty)	freight (Odyssey)
hudSelection.js:630	offerTribute(game.galaxy, state)	diplomacy (Odyssey)
hudSelection.js:661	fulfillRequest(game.galaxy, state)	diplomacy (Odyssey)
hudSelection.js:705	offerGift(state, com, TRADE_LOT)	diplomacy (Odyssey)
hudSelection.js:766, 777, 781, 793	unassignShipFromLane / assignShipToLane / deleteLane / createLane	lanes (Odyssey)
hudSelection.js:831, 837, 850, 870, 876	setColonyPolicy(g, planetId, …)	colony policy (Odyssey)
hudSelection.js:900	upgradeToCapital(state, cc)	Odyssey
hudSelection.js:905	packCommandCenter(state, cc.id)	Odyssey
hudSelection.js:1386	upgradeSpaceport(state, spaceport)	Odyssey
hudSelection.js:1455	lightFuse(state, bomb)	bombs — skirmish, must be a command
hudSelection.js:1750	deployColonyShip(state, colonyShip.id)	Odyssey
hud.js:37	repairConvoy(game.state)	scenario
hud.js:38	departNow(game.state)	scenario
starmap.js:229, 239, 244	setColonyPolicy(g, w.id, …)	Odyssey

For v1 skirmish MP, the mandatory set is small: queueProduction, cancelProduction, researchUpgrade, cancelResearch, lightFuse, plus the issue* family. Everything marked Odyssey is out of scope (§7) and stays reachable only on the offline path (§8).

1.3 Direct state.* writes

Only two kinds exist in the whole non-engine tree.

Site	Write	Verdict
input.js:318, 337, 382, 395, 411, 543	state.selection = …	Not sim state. Move to the client session.
inputCommands.js:147, 152, 154, 157, 177	state.selection = …	same
boot.js:766	state.events.length = 0	The client drains the sim's event queue. On the server path, events arrive per-snapshot and are consumed the same way.

state.selection also has 2 engine references (engine/state.js:346 prunes dead ids; engine/galaxy.js:1422 clears both sides on a jump), 32 client references and 124 test references. It is single-seat by construction and must move out of the shared sim state — it is the single largest mechanical edit in the port. engine/persist.js:777 already proves it is disposable (it saves as []).

1.4 state.players.player.resources and friends — direct owner-keyed reads

There are no writes. Reads (all of which become "read my seat"):

Site	Read
hud.js:99	{ ...state.players.player.resources } (flow history sample)
hud.js:174	state.players.player.resources (topbar readout)
hudSelection.js:272, 363, 432, 522, 680	state.players.player.resources
hudSelection.js:651	state.players.player.resources[req.com]
hudSelection.js:508, 1122, 1157	state.players.player.upgrades
hudSelection.js:1941	state.players.player.color (button sprite tint)
hudSelection.js:1955	canAfford(state.players.player.resources, cost)
hudPanelSignature.js:146, 264, 344	state.players.player.resources
hudPanelSignature.js:180	state.players.player.upgrades
hudPanelSignature.js:227, 228	state.players.player.resources[…]
overlays.js:34	st.players.player.faction and st.players.ai.faction
observer.js:276	state.players.ai (spectator stats)
techChart.js:36	const OWNER = "player" — the whole module's owner, used at :138, :153, :196

Fix: one accessor. me(state) → state.players[session.seat]. 20 sites, purely mechanical. overlays.js:34 and observer.js:276 are the two that read someone else's player record and therefore need a public-facts channel under filtering (§4).

1.5 createGameState / tick() / createLoop — the sim ownership itself

All in boot.js. This is the file that becomes the transport.

Site	Call
boot.js:14	import createGameState
boot.js:16	import createLoop
boot.js:17	import tick
boot.js:22	import createSelfPlayState, tickSelfPlay, SELFPLAY_HZ
boot.js:119	createGameState({ planetId, seed, rng: mulberry32(seed), … }) — skirmish
boot.js:169	createGameState({ … }) — competition fixture
boot.js:207	createSelfPlayState({ … }) — watched AI-vs-AI
boot.js:236, 244, 252	setupEscort / setupRaider / setupBounty — scenarios
boot.js:262	createGalaxy({ … }) — Odyssey
boot.js:287	jumpCapital(game.galaxy, destId, …)
boot.js:344	surrenderGalaxy(game.galaxy)
boot.js:485	loop = createLoop({ hz, speed, update, render })
boot.js:503	stepGalaxy(game.galaxy, dt)
boot.js:504	sweepColonies(game.galaxy, dt)
boot.js:530	tickSelfPlay(game.state, dt)
boot.js:531	tick(game.state, dt) — the single skirmish tick

Note engine/loop.js:34 createLoop is a render loop with an embedded fixed-step accumulator. On the server, the accumulator half is reusable verbatim; the requestAnimationFrame half (engine/loop.js:69, 77, 81, each marked browser-exempt) needs a setInterval/timer driver. Recommendation: extract the accumulator into a stepper and give it two drivers, rather than forking the file — the fixed-step semantics documented at engine/loop.js:18-26 are what make replay determinism hold, and they must not diverge.

1.6 Return values the client consumes — the "optimistic" hazards

Three call sites use the return value of a mutation, which a fire-and-forget command envelope cannot provide:

• input.js:521 — issueBuild(...) returns the new building id or null; the client uses the falsy result to keep build mode armed and play a rejection sound. Under server authority this becomes a rejection message or an optimistic ghost that clears on the next snapshot.
• hudSelection.js:449, 459, 485, 494 — loadFreighter/unloadFreighter return the quantity actually moved and drive the UI feedback (sound.playProductionBlocked() on 0). Odyssey-only.
• boot.js:287 — jumpCapital returns a result object or null. Odyssey-only.

Only the first matters for v1.

---

2. session.js / boot.js — the lifecycle, and how it re-shapes

2.1 session.js today (120 LOC)

A single exported mutable object, game, that every UI module reads at call time (never destructured at module scope) so a restart is picked up automatically. Its 17 fields are exactly three kinds of thing:

Kind	Fields	MP fate
The sim handles	state (session.js:16), galaxy (:22)	Become received state; galaxy out of v1
The input controller	input (:17)	Stays; becomes command-emitting rather than state-mutating
Per-viewer UI state	supplyBlockedUntil (:34), lastAttackAt (:40), lastGateCharge (:52), colonyAlerts (:64), groups (:69), formation (:75), collapsedSections (:84), observerMode (:89), spectateId (:92), spectatePreview (:99), observerCamera (:103), spectateSpeed (:119)	Stays exactly as-is. None of it is sim state; all of it is per-client.
Match-provenance flags	competition (:30), spectateMatch (:114)	Replaced by match (server-issued match descriptor)

This object is the right shape already. The port adds fields, it does not restructure: seat (my owner id), seats (public roster: id, name, colour, faction, isAI/isAgent), transport, connection (connecting/live/desynced/dropped), serverTick, selection (moved off state), and role ("player" | "spectator").

2.2 boot.js today — the lifecycle in one line each

main.js:165  renderMapSelect()                      splash / map-select screen (setup.js:306)
             └ user picks world + dials → setup     (setup.js:104, the shared config object)
boot.js:109  startGame(planetId)                    resolveSeed → difficultyDials → createGameState
boot.js:443  bootState(newState, {intro})           THE single boot path — 5 other entry points funnel here
   :444-446    stop old loop, destroy old input, exitObserverMode
   :447-451    hide mapSelect / gameOver / underAttack overlays
   :453-457    clear galaxy / competition / spectateMatch / groups / colonyAlerts
   :458        game.state = newState
   :463-465    seed chip, faction chip, objectives strip
   :466        game.input = attachInput(canvas, state, () => renderHUD())
   :471-475    open camera on state.map.bases.player, clamp
   :476-482    resetEffects / resetFacing / resetPanelSignature / resetWorldUiBookkeeping / clearPause
   :485        loop = createLoop({ hz: PLAY_HZ(20) | SELFPLAY_HZ, speed, update, render })
   :499-532      update(dt): pause gate → snapshotPositions → (stepGalaxy | tickSelfPlay | tick)
   :533-579      render(alpha): tickCamera → drawFrame → drawMinimap → processFrameEvents
                                → throttled renderHUD/renderObserverPanel (150 ms)
                                → **over-poll**: if (state.over && !announced) → showGameOver
   :581        loop.start(); :582 renderHUD()
boot.js:400  restartToMapSelect()                   loop.stop, input.destroy, null state/galaxy,
                                                    clearPause, renderMapSelect, unhide mapSelect

Five other entry points reuse bootState verbatim: startCompetitionMatch (:159), startSpectatedMatch (:204), startScenario/startRaider/startBounty (:234/:242/:250), startOdyssey→bootGalaxy (:259/:273), and saveload.js's load path.

Three structural properties matter for the port:

• End of match is a poll, not an event (boot.js:551: if (game.state.over && !announced)). There is no callback, no state machine. The client discovers the match ended by looking.
• bootState is idempotent teardown-then-setup. Every "leaving" concern is already centralised — the comment block at boot.js:390-399 documents exactly why nulling the session matters (stale hotkeys, the autosave timer writing after "Exit without Saving").
• The loop reads game.state live (boot.js:501, 503, 530, 531, 545), never a captured binding. Swapping the state under it is already a supported operation (that is how the Odyssey jump works, boot.js:365 focusActivePlanet).

2.3 The multiplayer re-shape

The lifecycle gains one screen and loses ownership of two transitions. Concretely:

SPLASH  →  LOBBY  →  (host: configure | join: wait)  →  server: MATCH_START
        →  bootState(receivedSnapshot, {seat})  →  loop(render-only) + command submit
        →  server: MATCH_END  →  post-match screen  →  LOBBY

setup.js splits in two. setup.js:104's setup object is match configuration — world, seed, difficulty, sizeMult, resourceMult, matchTimeLimit, popCap, faction. In MP that object is the host's lobby form, sent to the server once, and echoed back to every client as part of the match descriptor. The battlefield cards (setup.js:306 renderMapSelect) stay verbatim for the host; joiners see the same cards read-only. setup.js keeps its exported option tables (MAP_CHOICES:29, MATCH_LENGTH_OPTIONS:59, POP_CAP_OPTIONS:77, STRATEGY_OPTIONS:98, DIFFICULTY_OPTIONS re-export at :18) unchanged — they are pure data and the server needs the same lists to validate a lobby form.

startGame inverts. boot.js:109-125 currently constructs the state. It becomes:

startGame(planetId)  →  transport.requestMatch(setup)   // returns nothing; server decides
server MATCH_START   →  onMatchStart({ config, seat, seats, snapshot })
                     →  bootState(hydrate(config, snapshot), { intro: true, seat })

hydrate is cheap because the save format already does it: engine/persist.js:496 serPlanet persists only (seed, planetId, sizeMult, resourceMult, swapAsym) plus dynamic entities, and rehydratePlanet regenerates the whole map deterministically. The client can regenerate terrain and node geometry itself from the config; only node.amount and the entity tables need to arrive (engine/persist.js:549-551 already ships exactly {id, amount} per node).

bootState keeps its body almost exactly. Changes:

• :485 createLoop keeps render and drops the sim from update. The update callback becomes applySnapshot/interpolate. snapshotPositions(game.state) at :501 must still run immediately before each applied snapshot (it is the interpolation baseline, renderShared.js:45); this is the one ordering constraint that must not be lost.
• :471 state.map.bases.player → state.map.bases[seat].
• :466 attachInput(canvas, state, onChange) gains a seat and a submit collaborator.
• :551 the over-poll is replaced by an explicit MATCH_END message from the server carrying winner, winReason, and per-seat scores (§4 explains why scores must be server-computed). Keep the poll as the loopback path's implementation of the same callback (§8).

restartToMapSelect (boot.js:400) becomes leaveMatch. Its existing teardown is exactly right and should be preserved verbatim (it is the file's most carefully-reasoned function). It gains: close/park the transport, clear seat/seats, and — the new hazard — handle the server ending the match while the client is mid-teardown.

New states with no analogue today: LOBBY (roster, ready-up, seat/faction/colour pick), CONNECTING, RECONNECTING, DESYNCED, and OPPONENT_DROPPED. pauseReasons (boot.js:94-106) is a refcounted set and is the right primitive for "the server paused us" — but note that pauseLoop currently gates only the local update (boot.js:500). In MP, pause must come from the server; a client-side pause becomes a render-freeze only, and togglePause (boot.js:103) must be disabled or converted to a vote. landingPicker, starmap, and techchart all currently call pauseLoop to freeze the world behind a modal (boot.js:332, starmap.js tail, techChart.js tail) — all three must stop pausing in MP; they become non-blocking overlays.

---

3. Hardcoded "you are the player" assumptions

~110 literal "player"/"ai" occurrences outside engine/. They fall into five classes.

3.1 "Is this entity mine?" — the largest class, and the easiest

Every one of these is owner === "player" / owner !== "player" and becomes owner === session.seat.

File	Lines
input.js	317 (click-select own), 383 (select-all-army), 391 (idle worker), 407 (idle producer), 423 (CC cycle)
inputCommands.js	58, 62 (fog gate on hit-test), 99 (alivePlayerUnitIds), 131, 136, 170, 178, 197, 210, 223, 232, 242, 247, 257, 264, 271 — the entire right-click router
hud.js	47 (gate chip), 137, 194, 336 (idle workers), 352 (idle production), 429 (freighter count)
hudPanelSignature.js	149, 234, 290, 312
renderBuildings.js	84 (enemy pip), 120, 147, 165, 181, 233
renderEffects.js	413, 563 (rally point), 600 (waypoints), 637 (escort links)
renderUnits.js	91 (enemy pip)
renderShared.js	254 — hiddenByFog, the one fog predicate; fix here fixes four draw passes at once
minimap.js	94, 99
boot.js	370 (focusActivePlanet finds own CC), 675 (event fog gate), 684, 704, 712 (under-attack trigger), 737 (own supply block)
starmap.js	56, 58
landingPicker.js	60, 61, 151, 160
techChart.js	36 — const OWNER = "player", then used at 138, 153, 196
overlays.js	68-81 (the eight opening-objective predicates, each countUnits(state,"player",…) / hasCompletedBuilding(state,"player",…))

Recommendation: introduce isMine(e) in session.js and a SEAT accessor, then sweep. This is ~70 one-line edits with excellent test coverage already in place (test/input.test.js 57 tests, test/renderShared.test.js 34 tests, test/hud.test.js 33).

3.2 "The enemy is "ai"" — the class that genuinely breaks at N seats

These assume exactly one opponent, not merely that it is named "ai":

Site	Assumption
boot.js:684, 704, 712	if (ev.owner === "ai") triggerUnderAttack(...) — the comment at boot.js:669-671 states it outright: "an attackHit whose attacker is the AI necessarily means the target is the player's (only two sides exist)". At 5 seats this fires the under-attack alarm for every fight on the map. Must become ev.targetOwner === seat, which means engine/combat.js must start emitting the target owner on attackHit. This is the one place a sim change is forced by multiplayer.
hud.js:314	playerScore(state, "ai") — the topbar score bar shows "you vs them"
overlays.js:407	playerScore(opts.state, "ai") — the game-over breakdown
overlays.js:34	FACTIONS[st.players.ai.faction] — the faction chip is a two-sided "you vs them"
overlays.js:376, 392	winner === "player" ? victory : defeat
overlays.js:393-394	"Victory — the enemy's last Command Center is destroyed" / "Defeat — your last Command Center was destroyed." — singular "the enemy"
observer.js:290, 291	supplyUsed(state,"ai") / supplyCap(state,"ai")
observerPanel.js:89	owner => (owner === "player" ? watch.aName : watch.bName) — hard two-entrant
observer.js:116	state.map.bases.player || state.map.bases.ai
hudPanelSignature.js:225-228	diplomacy signature reads state.diplomacy as a single relationship

The score bar, the faction chip and the game-over copy are all "two columns" UI. At N seats they need to become a small roster table. That is a real (if modest) UI design job, not a rename.

3.3 Colours

Not a problem. #4fd1ff / #f87171 appear as entity colours only in engine/state.js:179-180, as ownerDefs[].color. Every renderer reads state.players[owner].color (renderUnits.js:66, renderBuildings.js:75, minimap.js:95, 100), and hudSelection.js:1941 / techChart.js:196 / landingPicker.js:149 do the same for icons. The remaining literals in renderEffects.js:111-113, 315, 326, 447, 511, 542, 584, 616, 680, minimap.js:114, renderUnits.js:126, renderShared.js:195, renderBuildings.js:109, 154, 197 are semantic colours (valid/invalid placement, health tiers, power tiers, tracer types) that happen to reuse the same hexes. Leave them.

Action: extend ownerDefs to N entries with a colour ramp; add colours to style.css (3 hits) for the HUD chrome. Nothing else.

3.4 state.fog vs state.fogAI

Already an alias pair over state.fogs (engine/state.js:232-234, pinned by test/ownerScaffold.test.js). Client reads:

Site	Read
render.js:202	drawFogBase — the charted-space wash
minimap.js:36, 83	minimap fog underlay + entity gate
renderShared.js:254	hiddenByFog
renderNodes.js:26	isNodeDiscovered(state.fog, n)
renderEffects.js:466	node picking overlay
inputCommands.js:58, 62, 69	hit-test + node-pick gating
boot.js:675	event audibility

All nine become state.fogs[seat]. The remaining hazard is inside the engine: engine/sim.js:70-71 hardcodes updateFog(state, state.fog, "player") and updateFog(state, state.fogAI, "ai") even though state.fogs exists. That must become for (const id of state.owners) updateFog(state, state.fogs[id], id) — which is exactly what engine/state.js:270 already does at construction time.

3.5 state.map.bases.player

boot.js:371, boot.js:471, input.js:430, observer.js:116, and inside the engine engine/galaxy.js:421, 1365, engine/map.js:177, 179, 207. engine/aiMilitary.js:554, 574, 589, 694 already indexes generically (state.map.bases[owner]). Map generation must produce N start positions — this is a map-generation change (engine/map.js) and is the single largest engine task implied by N-seat multiplayer. It is out of the client's scope but gates it.

---

4. Rendering under authoritative fog

4.1 How hard is per-client filtering?

Much easier than it looks, because the client already renders as if it were filtered.

engine/fog.js is 144 LOC, pure, and already per-owner: createFog(map) (:34), isVisibleAt(fog,x,y) (:49), isExploredAt (:55), isNodeDiscovered (:66), updateFog(state, fog, owner) (:124). state.fogs[owner] exists. There is no remembered snapshot of enemy positions (engine/fog.js:14-15 says so explicitly) — an out-of-vision enemy simply stops rendering. That is precisely the semantics a filtered projection provides.

So projectFor(state, seat) is a ~60-line pure function:

units      → own ∪ { u : isVisibleAt(fogs[seat], u.x, u.y) }, enemy entries stripped
             of order/orderQueue/homeCC/target internals (intel leak)
buildings  → same rule
nodes      → { id, amount } for every charted node; hidden nodes only where
             isNodeDiscovered(fogs[seat], n)          (engine/fog.js:66)
players    → { [seat]: full record } + public facts for the rest
             (id, name, colour, faction, score, supply, isAI)
fogs       → { [seat]: fogs[seat] }, with `fog` aliased for the legacy readers
owners     → unchanged (public)
selection  → this seat's own (once it moves off state)
events     → the rule already at boot.js:675: own events, plus any event
             at a currently-visible point
map        → NOT sent; client regenerates from (planetId, seed, sizeMult,
             resourceMult, swapAsym) — engine/map.js generateMap is deterministic

The renderer needs no changes to consume this, because every per-entity fog gate (renderShared.js:254, minimap.js:94, 99, renderNodes.js:26, inputCommands.js:58, 62) simply becomes tautologically true rather than wrong.

4.2 What filtering would strip that the client currently needs

Six real dependencies. Five are trivially fixable; one is a genuine visual regression.

1. playerScore(state, "ai") — hud.js:314 (score bar), overlays.js:407 (game-over breakdown). Reads all of the enemy's bank/army/structures. → Server computes per-seat scores and ships them as public facts. engine/victory.js:158-165 already iterates ownersOf(state).
2. Enemy faction — overlays.js:34 reads st.players.ai.faction for the "you vs them" chip. → Public lobby fact; ship in the match descriptor.
3. Enemy supply — observer.js:290-291. Spectator-only; the spectator seat receives an unfiltered projection.
4. Enemy CC existence for victory — client never checks this; engine/victory.js does, on the server. No client change.
5. Hidden-node discovery — isNodeDiscovered gates right-click targetability (inputCommands.js:69), not just drawing. If the client recomputes fog locally (see below), a snapshot-rate mismatch could make client and server disagree about whether a cache is targetable. → Ship an authoritative discoveredNodeIds set per seat. It is tiny (caches are a handful per map, engine/map.js:266-267).
6. Interpolation continuity — the real regression. renderShared.js:39 prevPos keys interpolation baselines by unit id; renderShared.js:69 pruneFacing deletes the baseline the moment a unit is absent from state.units. Today an enemy unit that ducks behind fog stays in the Map (only its draw is gated), so it keeps a continuous baseline. Under filtering it leaves the map, loses its baseline and its facing entry, and on re-entry snaps rather than slides. → Give pruneFacing a grace window (drop after N frames absent, not immediately). ~5 lines in a file with 34 existing tests.

Everything else the renderer touches is either the client's own entities, immutable map data it can regenerate, or already fog-gated.

4.3 Measured payload (this machine, engine/persist.js format)

Full serializeGameString snapshot, 15 sim-minutes, both seats AI-driven:

Map	units / bldgs	full	fog (both)	units	buildings	nodes
Small (1600×1000)	16 / 16	18.9 KB	3.9 KB	4.5 KB	3.7 KB	4.4 KB
Standard 2× (3200×2000)	27 / 16	30.1 KB	15.6 KB	6.7 KB	3.7 KB	2.4 KB
Gigantic 4× (6400×4000)	—	69.6 KB	62.5 KB	3.5 KB	1.1 KB	1.3 KB

Fog dominates on large maps and entities are tiny. That single fact drives the recommendation.

4.4 Recommendation

Ship fog-filtered-per-client, and ship no fog grid at all.

Three parts:

1. Filter entities server-side with projectFor(state, seat). This is the anti-cheat boundary and it must exist before any public or agent-played match. It is ~60 LOC of pure engine code, directly unit-testable against the existing test/fog.test.js fixtures.
2. Do not transmit the fog grid. The client already has everything needed to recompute it: its own units and buildings, and a deterministically regenerated map. updateFog(state, myFog, seat) (engine/fog.js:124) is pure, allocation-free, and is exactly what engine/sim.js:70 already calls each tick. explored accumulates client-side across snapshots (it is monotonic). This deletes 3.9–62.5 KB from every snapshot and makes payload scale with army size rather than map size. The only thing that must remain server-authoritative is hidden-node discovery (see §4.2 item 5), which is a tiny id set.
3. Keep full-state broadcast as a named, flagged mode — spectator and replay — not as the default. observer.js (§7) is already exactly this client, and saveShape.js:28 resumableMode already encodes "a spectated match is not the player's game".

Trade-off, stated plainly. Full-state broadcast is ~2 days of work and lets every existing client module run untouched; it is also trivially cheatable by anyone who opens devtools, and it is especially wrong for this project because MCP agents receive state programmatically — an agent handed the full state is not playing the same game as a human. Filtering costs perhaps a week (the projection function, per-seat score/faction public facts, the pruneFacing grace window, and the discovered-node channel) and is the only version that survives contact with public play.

Migration path. These are additive and independently shippable:

• M0 — projectFor(state, seat) written and tested, but the server still broadcasts full state. Test: projectFor(s,"player") renders pixel-identically to s under the existing render tests. This proves the renderer tolerates a filtered state before anything depends on it.
• M1 — server switches to projectFor; fog grid still shipped. Add per-seat public scores (hud.js:314, overlays.js:407) and the faction roster (overlays.js:34).
• M2 — stop shipping fog; client calls updateFog locally on each snapshot. Add the discoveredNodeIds channel. Add the pruneFacing grace window.
• M3 — delta-encode entities against the previous acknowledged snapshot. At 16–27 entities, this is optional until army sizes grow.

---

5. What is reusable VERBATIM

The tree is 90,762 LOC total (.js/.css/.html/.json/.md); 81,257 LOC of .js/.css/.html, of which 43,101 is tests. Shipped application code is ~35,400 LOC (engine 15,659 + top-level client 17,903 + css/html 1,815).

5.1 Zero change — pure, import-free or engine-data-only leaves

Module	LOC	Why it is untouched
sound.js	181	No imports at all. Pure WebAudio. Nothing about it is single-player.
effects.js	183	No imports at all. Tracers, death flashes, pings, fireworks — pure render-side particle bookkeeping.
camera.js	105	No imports at all. createCamera/zoomAt/panCamera/pinchZoomPan/screenToWorld/clampCamera.
data.js	242	Static tables (planets, commodities, recipes). Pure data.
dom.js	68	Element handles + MINIMAP_W/H + isTouchMode(). Already Node-import-safe by design (dom.js:11-18).
style.css	1,732	3 hits on the team hexes; add N-seat colour variables. Otherwise verbatim.
saveShape.js	31	Two pure predicates. Gains one term (§6).
renderShared.js	255	One line (:254). Geometry/colour helpers, interpolation, health bars — all generic.
renderNodes.js	171	One line (:26).
renderUnits.js	699	Two lines (:91 enemy pip, :126 a semantic red). Colour already comes from players[owner].color (:66).
minimap.js	138	Two lines (:94, :99).
render.js	277	drawFrame orchestration + spriteIcon cache + drawFogBase. Only state.fog → state.fogs[seat] at :202.
renderBuildings.js	807	Six owner !== "player" lines. Everything else — hull art, power tiers, storage bars, jump staging — is generic.
renderEffects.js	683	Five owner !== "player" lines.
techChart.js	366	One line: const OWNER = "player" (:36). Plus: stop calling pauseLoop in MP.
landingPicker.js	211	Four owner lines. Odyssey-only anyway (§7).
elo.js	147	Pure rating math, zero engine/DOM. Lift to the server verbatim when MP ranking lands.
pairing.js	518	Pure Swiss/round-robin scheduling; its own header (pairing.js:15) notes the single import is hashStr. Lift to the server verbatim.
version.js	60	Version/save-impact reporting.
Subtotal	~6,874

5.2 Near-zero change — a rename sweep, no restructuring

Module	LOC	Change
overlays.js	585	Owner literals at :34, :68-81, :376, :392-394, :406-407; game-over copy becomes N-seat. Toasts/hints/help/objectives verbatim.
hud.js	452	9 owner literals; score bar becomes a roster; two scenario buttons (:37, :38) become commands.
hudPanelSignature.js	380	4 owner literals + the players.player reads. It is a pure signature/diff function — the mechanism is untouched.
session.js	120	Additive fields only.
observer.js + observerPanel.js	550	Repurposed as the spectator client (§7). enterObserverMode (observer.js:128) gains a third permitted condition.
main.js	168	:145-151 (minimap right-click) becomes a command submit. Everything else is canvas/DPR/toggles.
starmap.js	318	Odyssey-only; unchanged on the offline path.
update.js	108	Version chip / auto-update. Verbatim.
Subtotal	~2,681

5.3 Real work

Module	LOC	Nature
boot.js	788	Lifecycle inversion (§2). The single heaviest file.
input.js	588	6 state.selection writes, 6 issue* calls, 5 owner literals; becomes command-emitting. Gesture/camera/touch code untouched.
inputCommands.js	288	5 selection writes, 13 issue* calls, 16 owner literals. Its own header (inputCommands.js:15-17) notes commandAt is already the "what does this click mean" decision, callable directly — this file is the natural home of client-side command construction.
hudSelection.js	1,998	~30 mutator calls + players.player reads. But ~900–1,000 LOC of it is Odyssey panels (renderMarket:346, renderFreight:430, renderDiplomacy:612, renderLanes:717, renderColonyPolicy:809, renderCapital:890, renderSpaceport:1328, renderDatacenter:1156) that are out of v1 scope and need no change at all.
setup.js	462	Splits into lobby form + option tables (§2.3).
saveload.js	371	§6.
Subtotal	~4,495

5.4 Quantified

Of the ~17,900 LOC of shipped client JS:

• ~6,900 LOC (≈39 %) verbatim or one-line-per-file (§5.1)
• ~2,700 LOC (≈15 %) a mechanical owner-literal sweep (§5.2)
• ~4,500 LOC (≈25 %) genuine rework (§5.3), of which roughly a fifth is Odyssey panels that are simply not touched in v1
• ~3,800 LOC (≈21 %) out of v1 scope entirely — the competition cluster (§7)

Plus 1,732 LOC of CSS effectively verbatim and 15,659 LOC of engine that keeps running unchanged — on the server instead of in the tab. The 5 renderer files alone (render + renderBuildings + renderEffects + renderNodes + renderUnits + renderShared = 2,892 LOC) survive with 17 changed lines between them. That is the single strongest argument for server-authoritative-with-thin-client over any rewrite.

---

6. saveload.js / autosave / localStorage in multiplayer

6.1 What exists

• Two channels (saveload.js:1-18): file (topbar Save/Load, an explicit .json) and localStorage autosave every 12 s (saveload.js:39) plus on tab-hide/unload, feeding the map-select "Continue" buttons.
• Two generations per key (saveload.js:33-38, 84-98) so one corrupt write cannot lose a run.
• Keys: stellarfrontier.save.v1 (:31), stellarfrontier.odyssey.v1 (:32).
• The decision of what is resumable is a 3-line pure function, saveShape.js:28 resumableMode({state, galaxy, spectateMatch}) — already unit-tested (test/save-shape.test.js) and already refuses to checkpoint a scenario, a finished match, or a spectated match whose player seat isn't really the player's.
• Other localStorage users: overlays.js:104-108 (objectives-strip dismissed, per mode), update.js:23-24 (version-banner dismissed), competitionLedger.js:1238-1286 (the Elo ledger, two generations, sanitized on read).

6.2 Recommendation

Drop client saves for multiplayer entirely. Persist matches server-side using the existing format. Record replays as command logs, not snapshots.

1. Client autosave off in MP — a one-term change. saveShape.js:28 already reads { state, galaxy, spectateMatch }. Add netMatch: if (!state || state.over || state.scenario || spectateMatch || netMatch) return null; That single edit disables autosave, "Save & Exit", and the "Continue" buttons for a networked match, in a pure function with existing tests. Resuming a shared match from one participant's private browser copy is incoherent, and the localStorage payload is attacker-editable — the file's own header (competitionLedger.js:11) already says so.
2. Server-side match persistence reuses engine/persist.js unchanged. serializeGameString (:808) / deserializeGame (:811) already produce and consume the exact snapshot the server needs, and deserializeGame already treats its input as hostile (sanitizeSave, engine/persist.js:48-49, plus test/save-hardening.test.js at 836 LOC). The server checkpoints on the same 12 s cadence; a crash resumes the match. Zero new format.
3. Replays are command logs, not snapshot streams. The sim is deterministic from (config, seed) and the loop is fixed-step (engine/loop.js:18-26 explains why the timestep is the simulation and not a tuning knob). There is already determinism coverage (test/determinism.test.js, test/determinism-roster.test.js) and a replay concept (boot.js:215-219's recorded, which lets the game-over screen state honestly whether the determinism claim held). A (config, [{tick, seat, envelope}]) log is orders of magnitude smaller than snapshots, doubles as the anti-cheat audit trail, and is the natural artefact for an MCP agent to review its own play. Recording the command log should be built in from day one — it is nearly free once commands are envelopes, and retrofitting it is not.
4. Keep client localStorage for per-viewer preferences only — overlays.js:104-108, update.js:23-24, volume/mute. These are correct as-is.
5. File Save/Load stays, single-player only. Hide saveBtn/loadBtn (dom.js:42-43) in a networked match, exactly as starmapBtn is already conditionally hidden.
6. competitionLedger.js's localStorage Elo ledger is single-player only and stays that way. Any MP ladder must be server-side or it is forged by editing a string.

---

7. Odyssey / galaxy / competition / observer — in or out for v1

Subsystem	LOC (client + engine)	v1 verdict
Skirmish (the base game)	—	IN — this is v1
Odyssey / galaxy	engine/galaxy.js 1,431 + colony 93 + colonyPolicy 160 + diplomacy 501 + market 309 + wonder 93 + starmap.js 318 + landingPicker.js 211 + ~950 of hudSelection.js = ≈4,066	OUT
Competition / Elo / ladder	competition.js 3,773 + competitionLedger.js 1,290 + competitionWorker.js 355 + pairing.js 518 + elo.js 147 + playerFingerprint.js 167 + tools/duelCore.js 119 + tools/genome.js 680 = 7,049	OUT as shipped; mine it
Observer / spectator	observer.js 304 + observerPanel.js 246 = 550	IN — repurposed
Scenarios (Escort / Raider / Bounty)	engine/scenarios.js 720	OUT (offline path only)

Odyssey — OUT

Three independent reasons, any one sufficient:

• It is not a match; it is a save file. The Odyssey is an open-world sandbox that ticks every world in the galaxy each tick (boot.js:503 stepGalaxy), with a single per-player credit pool, background colonies raising notifications (boot.js:504 sweepColonies → boot.js:605 notifyColony), and interplanetary relocation that swaps which state is rendered (boot.js:365 focusActivePlanet). "Two players share a galaxy" is an unanswered game-design question, not a porting question.
• It pauses the world for modals. boot.js:332 (landing picker), starmap.js (M key), and techChart.js (T key) all call pauseLoop. In MP nothing may pause the shared world for one participant. Every Odyssey overlay would need reworking.
• It carries most of the client's remaining complexity. Roughly half of hudSelection.js (the 1,998-LOC file) is Odyssey panels. Excluding Odyssey removes ~950 LOC of panel work from v1 at zero cost, because those panels never render when game.galaxy is null.

Keep the code in-tree and reachable on the offline path (§8). Do not delete it. Its tests (test/odyssey.test.js 809 LOC, test/starmap.test.js 482, test/landing.test.js 439, test/lanes.test.js, test/colonyPolicy.test.js, test/livingGalaxy.test.js, test/domination.test.js, test/rivalgate.test.js) keep passing and keep protecting the shared engine code that skirmish also uses.

Competition / Elo — OUT as shipped, but read it first

competition.js (3,773 LOC) is a single-player ladder screen: it schedules AI-vs-AI duels, runs them in a Web Worker (competitionWorker.js), and writes ratings into a localStorage ledger. None of that is multiplayer. But three things in this cluster are the prior art for the port and should be read before writing the server:

• competitionWorker.js (355) + tools/duelCore.js (119) + tools/selfplay.js (169) — this is already a headless, off-main-thread, deterministic match runner. It is the server sim in miniature. engine/state.js:250-254 documents state.playerAi, the second controller slot that makes owner "player" AI-driven — the exact hook an MCP agent occupies.
• pairing.js (518) and elo.js (147) are pure, engine-free, and directly liftable to the server when MP ranking lands. pairing.js:15 states it holds no engine state at all.
• playerFingerprint.js (167) — fingerprintPlayer(state, owner = "player") (:53) and mirrorOfPlayer(state, {owner}) (:162) are already owner-parameterised. Useful for agent-vs-human matchmaking later.

Also note the guard at test/engine-purity.test.js:20-41: it already extends the determinism scan to browser-reachable tools/ files precisely because "bench" code started deciding persisted ratings. The same guard should be extended to the server's sim entry point on day one.

Observer — IN, repurposed as the spectator client

This is the highest-leverage "already written" asset in the tree. observer.js's header states its contract exactly: it "reveals fog on whichever world you're looking at", gives a free camera, "deliberately does not touch game.state, game.galaxy.activeId, or the real input camera", and makes input.js refuse to issue a single order — every mouse/wheel/key path already early-returns into observer.js while game.observerMode is on. That is a spectator client, already built and already tested (test/observer.test.js, 23 tests).

The change is one condition. observer.js:128 enterObserverMode() currently permits exactly two cases (an Odyssey, or a watched AI-vs-AI match) and refuses an ordinary skirmish because that would be a fog cheat. Add a third: the server assigned this connection the spectator role. The server then hands that connection an unfiltered projection, which is legitimate precisely because a spectator has no seat to cheat with.

Justification for including it in v1: multiplayer needs spectating on day one, and AI-agent matches make it a requirement, not a nicety — an MCP agent playing a match is only interesting if a human can watch it. observerPanel.js:89's two-entrant naming (owner === "player" ? watch.aName : watch.bName) is the only piece needing real work.

---

8. Offline / single-player preservation

Yes — and it should be the primary design constraint, not an afterthought.

Two reasons. First, the game is the single-player game; shipping a port that can only run against a server throws away a working product. Second and more practically: of ~2,466 tests, roughly 1,735 are engine/tools tests that drive tick() and createGameState directly, and roughly 731 are client tests that drive the current client against a locally-constructed state (test/input.test.js 57, test/hudSelection.test.js 50, test/boot.test.js 29, test/hud.test.js 33, test/renderShared.test.js 34, test/overlays.test.js 26, test/saveload.test.js 24, test/observer.test.js 23 …). If the client can no longer run its own sim, every one of those 731 tests needs a mock. That is the single biggest risk in the port.

8.1 Recommendation — a loopback transport

Define one interface and give it two implementations:

Transport {
  submit(envelope)            // a command from this client's seat
  onSnapshot(fn)              // state deliveries
  onMatchStart(fn) / onMatchEnd(fn)
  seat, seats, role
}

• LoopbackTransport — constructs the state in-process with createGameState, runs createLoop/tick exactly as boot.js:485-531 does today, and submit applies the command synchronously, in the caller's stack frame, by calling the same issue* the client calls today. Behaviourally byte-identical to the current game.
• SocketTransport — serializes envelopes, applies snapshots.

8.2 Why this keeps the tests meaningful

The seam is placed at exactly two points, and both preserve today's observable semantics:

1. Command submission. Because LoopbackTransport.submit mutates before returning, every existing client test that asserts "after this click, the unit has this order" still passes unchanged. This is the whole trick: keep the loopback synchronous.
2. State delivery. boot.js's update callback (:499-532) becomes transport-driven. snapshotPositions(game.state) (:501) must run before either a local tick or an applied snapshot — one ordering rule, easy to pin with a test.

Add one new engine function, applyCommand(state, seat, envelope), that resolves ids → entities, filters to seat-owned entities, and calls the unchanged issue*. Then:

• test/commands.test.js (503 LOC) keeps testing issue* directly — untouched.
• One new test file pins envelope → issue* and the ownership filter (which is new safety the game has never had: today nothing stops a client from ordering enemy units, because there is no adversary).
• test/input.test.js, test/hudSelection.test.js, test/boot.test.js keep working against the loopback.

The one unavoidable test churn is state.selection (§1.3): 124 test references. Moving it to the client session is mechanical but wide. Budget for it explicitly; do it as its own change, before the transport work, so the diff is reviewable.

8.3 What single-player retains

With a loopback transport, the full offline game keeps working: skirmish, all three scenarios (boot.js:234, 242, 250), the whole Odyssey (boot.js:259), the competition ladder and its Web Worker duels, file save/load, and localStorage Continue. saveShape.js:28's netMatch term (§6.2) is exactly what keeps the two worlds from contaminating each other. The Hugging Face Space can therefore serve one bundle that plays offline and connects — and the offline path is also the fastest development loop for anyone working on the renderers or the HUD.

---

9. Summary table

Verdicts: verbatim (0–2 changed lines) · light (a rename sweep, no restructuring) · heavy (real rework) · server-side (moves out of the browser) · out-v1 (untouched, offline-only)

Module	LOC	Verdict	Why
engine/ (all 49 files)	15,659	server-side	Runs headless. Needs: applyCommand dispatcher, projectFor(state, seat), N-entry ownerDefs (state.js:174), owner-generic updateFog loop (sim.js:70), N start bases (map.js), attackHit target owner (combat.js)
style.css	1,732	verbatim	3 team-colour hits; add N-seat variables
index.html	83	light	Add a lobby container; hide save/load in MP
sound.js	181	verbatim	Zero imports
effects.js	183	verbatim	Zero imports
camera.js	105	verbatim	Zero imports
data.js	242	verbatim	Static tables
dom.js	68	verbatim	Already Node-safe (dom.js:11-18)
version.js	60	verbatim
update.js	108	verbatim	Self-wired version chip
saveShape.js	31	verbatim	+1 term: netMatch (:28)
renderShared.js	255	verbatim	:254 only; + pruneFacing grace window (§4.2)
renderNodes.js	171	verbatim	:26 only
minimap.js	138	verbatim	:94, :99
render.js	277	verbatim	:202 (state.fog → fogs[seat])
renderUnits.js	699	verbatim	:91; colour already generic at :66
renderBuildings.js	807	verbatim	6 owner lines; colour generic at :75
renderEffects.js	683	verbatim	5 owner lines
techChart.js	366	verbatim	:36 OWNER; stop pausing in MP
elo.js	147	server-side	Pure; lift verbatim when ranking lands
pairing.js	518	server-side	Pure; lift verbatim when ranking lands
playerFingerprint.js	167	out-v1	Already owner-parameterised (:53, :162); useful later
session.js	120	light	Additive: seat, seats, role, transport, selection
main.js	168	light	:145-151 minimap command → submit
hud.js	452	light	9 owner literals; score bar → roster; :37, :38 → commands
hudPanelSignature.js	380	light	4 owner literals + players.player reads
overlays.js	585	light	:34, :68-81, :376, :392-394, :406-407; N-seat game-over copy
observer.js	304	light	:128 gains a third permitted case → the spectator client
observerPanel.js	246	light	:89 two-entrant naming → N-seat
inputCommands.js	288	heavy	13 issue* + 5 selection writes + 16 owner literals; becomes the command constructor
input.js	588	heavy	6 issue* + 6 selection writes + 5 owner literals; gesture/camera/touch untouched
setup.js	462	heavy	Splits: lobby form + (verbatim) option tables
saveload.js	371	heavy	MP: off. SP: unchanged. Server reuses engine/persist.js
boot.js	788	heavy	Lifecycle inversion; the single biggest file of real work
hudSelection.js	1,998	heavy (1,050) / out-v1 (950)	~30 mutator calls in the skirmish half; the Odyssey panels are untouched
starmap.js	318	out-v1	Odyssey
landingPicker.js	211	out-v1	Odyssey
competition.js	3,773	out-v1	Single-player ladder screen
competitionLedger.js	1,290	out-v1	localStorage Elo ledger — forgeable, SP-only
competitionWorker.js	355	out-v1	Read as prior art for the headless server sim
tools/ (selfplay, duelCore, genome, ailab, serve, smoke)	3,593	out-v1	selfplay.js/duelCore.js are the closest existing thing to the server runner
test/	43,101	preserve	~1,735 engine tests unaffected; ~731 client tests preserved by the synchronous loopback (§8)

Totals: verbatim/near-verbatim ≈ 6,900 LOC (39 % of shipped client JS) · light sweep ≈ 2,700 (15 %) · heavy ≈ 4,500 (25 %) · out-v1 ≈ 3,800 (21 %) · plus 15,659 LOC of engine relocated intact and 1,732 LOC of CSS untouched.

---

10. Ordered recommendations

1. Move state.selection off the sim state first. 10 write sites, 32 client reads, 2 engine reads, 124 test references. It is the widest mechanical change and it is independent of everything else — do it as its own reviewable diff, before the transport.
2. Add applyCommand(state, seat, envelope) to engine/commands.js, with the seat-ownership filter that does not exist today. Keep every issue* unchanged so test/commands.test.js is untouched.
3. Introduce Transport with LoopbackTransport first. Land the whole port against loopback before a socket exists. The client tests are the regression suite.
4. Sweep the owner literals behind session.seat / isMine(e) (§3.1). ~70 one-liners with heavy existing coverage.
5. Make the engine N-seat: ownerDefs (engine/state.js:174), the updateFog loop (engine/sim.js:70), N start bases (engine/map.js), and attackHit's target owner (engine/combat.js). test/ownerScaffold.test.js is the spec that already exists.
6. Write projectFor(state, seat) and prove it renders identically to the full state before anything depends on it (M0 in §4.4).
7. Record the command log from day one. It is nearly free once commands are envelopes, it is the replay format, the anti-cheat audit trail, and the MCP agent's trace.
8. Extend test/engine-purity.test.js's reachability walk to the server entry point the moment it exists. The guard's own comment (:20-41) explains what happened last time a "bench" file started deciding real outcomes.
9. Defer Odyssey and the competition ladder; keep both alive on the loopback path. They cost nothing to keep and protect ~1,000 tests over shared engine code.
10. Ship the spectator seat in v1 by widening observer.js:128. It is already written, already tested, and AI-agent matches make it a requirement rather than a nicety.