Jesse.Markowitz/station-master
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

v0.5.0 — multiplayer Phases 2 and 3: a server that runs a game and survives being restarted

Browse Source 
Phases 0-1 shipped in v0.4.0 (seat/identity split, per-player turn state, the Session boundary).
This lands Phase 2 (server core, one game, no lobby) and Phase 3 (persistence and resumption) per
docs/architecture/multiplayer.md §12. Phases 4-6 (lobby/reconnection, the 22 opponent-directed
cards, StartOS packaging) are still ahead.

Phase 2: src/server/session.ts hosts a game in pure logic (no sockets) on top of game.ts's existing
Game/submit/currentActor/actionMenu; it verifies seat === currentActor(game) itself before calling
submit, since submit() trusts its caller and a server can't. src/server/http.ts and index.ts add
POST /api/game, GET /api/stream (SSE, per-seat), POST /api/intent, and static serving of dist/.
src/sim/frame-delta.ts is a purpose-built per-seat board delta for one live push at a time. Found
and fixed along the way: actionMenu(game, seat) only used seat for the hand field, so a server
computing every connected seat's Menu would have handed the acting player's legal moves to a
waiting seat. Verified with a live end-to-end smoke test (2-player game, two SSE streams, a
rejected intent from the wrong seat, an idempotent resend) plus test/server/session.test.ts and
test/redaction.test.ts. Not verified: an actual browser (none available in this environment).

Phase 3: src/server/persistence.ts writes game.json and turn-timings.json, atomic-rewrite-then-
rename. game.ts gained fromMultiplayerSave, fixing a narration-attribution bug found while testing
it (fromSave's replay loop drops the actor argument, invisible in solitaire, unreadable the moment
there's more than one seat — fromSave itself still has this gap, deliberately untouched). Verified
live: server killed and restarted mid-game, both seats reconnected exactly where they left off.

Two rules bugs found while building this: the New Train phase never implemented its car-placement
round (every car of every train was placed by the Superintendent alone, in every mode, all along —
now reads the round position off tray.consist.length); and victory conditions are now one shared,
configurable GameConfig set across solitaire/competitive/coop instead of a fixed length lookup and
a dead firstToTarget condition.

Also folds in the three fixes already released on the patch line as v0.4.9b/c/d: a switching
train's crew badge failing to draw once it left the Office square, an unload that always took the
westmost car regardless of which was picked, and a legal decision that could render with zero
buttons.

docs/testing/0.5.0-test-plan.md and three reported-bug save files (docs/station-master-seed*.json)
included for reproducibility. tools/jitsi-harness/ deliberately left untracked — unrelated
side-project work, not part of this release. 635 tests, 0 failures.
This commit is contained in:
Jesse
2026-08-20 23:50:38 -04:00
parent f9c4d9fa92
commit c3c5cbfeec
52 changed files with 5282 additions and 420 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -15,6 +15,7 @@ Thumbs.db
# "tsc: not found" and 20 tests failed for a reason that had nothing to do with the code.
node_modules
dist/
dist-test/
build/
target/
__pycache__/
CHANGELOG.md
+98
View File
@@ -19,6 +19,104 @@ page as `v0.1.0 · <sha> · <date>`, so what is deployed can always be identifie
---
## 0.5.0 — 2026-08-21
Multiplayer Phases 2 and 3 (`docs/architecture/multiplayer.md` §12): a real server exists now, one
game at a time, and it survives being restarted mid-game. Phases 0 and 1 shipped in v0.4.0; Phases
4–6 (lobby/reconnection, the 22 opponent-directed cards, StartOS packaging) are still ahead. Also
folds in the three playtest fixes already released as v0.4.9b/c/d on the patch line, plus two rules
bugs and a victory-condition redesign found along the way.
### Phase 2 — server core, one game, no lobby
- `src/server/session.ts` — the game session host: pure logic, no sockets, built entirely on
`game.ts`'s existing `Game`/`submit`/`currentActor`/`actionMenu` rather than re-deriving intent
application or narration. **Found while building it:** `submit()` derives the acting player from
`currentActor(game)` and never checks who is actually calling it — harmless for `LocalSession`
(only one possible caller) but not safe for a server, so the session host now verifies `seat ===
currentActor(game)` itself before calling `submit`, rejecting with `NOT_YOUR_TURN` otherwise.
Idempotent resend (a repeated `seq`) and the illegal-intent path (checked via `check()` directly,
so a rejection never pollutes the shared narration log with text meant only for the submitter) are
both handled here.
- `src/server/http.ts` / `src/server/index.ts` — plain `node:http`, no framework: `POST /api/game`,
`GET /api/stream` (SSE, per-seat, 20s heartbeat, `id:` line per push), `POST /api/intent`, and
static serving of `dist/` so the server is same-origin with itself.
- `src/sim/frame-delta.ts` — the live per-seat board delta (`deltaFrame`/`applyDelta`), a smaller
replacement purpose-built for a single live push rather than reusing `replay.ts`'s `compress()`,
which interns strings across a whole recorded array with nothing here to intern against; only its
one-step-back "null if unchanged" idea carried over.
- **Found and fixed:** `actionMenu(game, seat)` only used `seat` for the `hand` field — everything
else came from `currentActor(game)` regardless of who asked, so a server computing every connected
seat's Menu would have handed the acting player's legal moves to a waiting seat, paired with the
wrong seat's cards. Fixed with a guard in `game.ts`; tested in `multiplayer.test.ts`.
- The redaction test (§7, `test/redaction.test.ts`) passed on the first run against the existing
`snapshot()`, confirming it was already correct rather than just apparently so.
- `src/web/session.ts` gained `createRemoteSession`; `main.ts`'s `start()` switches on `?seat=`
presence (one bundle, unchanged). Every `LocalSession`-only call site in `main.ts` now goes through
an `isLocal()` type guard instead of assuming.
- Verified two ways: `test/server/session.test.ts` exercises the session host directly, and a live
end-to-end smoke test (server started, a 2-player game created, two SSE streams opened, an intent
rejected from the non-acting seat, accepted from the acting seat and broadcast to both, a resent
`seq` producing no second push, the board correctly nulled on the second push). **Not verified: an
actual browser** — no browser binary in this environment, so `RemoteSession`'s DOM-facing code
compiled and typechecks but was never clicked through visually.
### Phase 3 — persistence and resumption
- `src/server/persistence.ts` — `game.json` (`{engineVersion, seed, config, playerNames, history,
status, createdAt}`) and `turn-timings.json`, both atomic-rewrite-then-rename.
- `game.ts` gained `fromMultiplayerSave`, `fromSave`'s multi-player sibling. **Found while testing
it:** `fromSave`'s replay loop calls `record(game, result.events)` without the `actor` argument
`submit()` always passes, so every replayed line loses its "Player X" attribution — invisible for
solitaire, immediately visible for multiplayer, where anonymous "Chose to…" lines are unreadable
the moment there is more than one seat. Fixed in the new function; `fromSave` itself still has the
gap, deliberately untouched here since it's used far more widely (undo, save/restore, the replay
viewer) and deserves its own pass.
- `session.ts` gained `exportSave()`, `resumeSession()`, and turn-timing tracking — a span (player,
phase, day, stage, start/end wall-clock) that closes and reopens whenever the acting player, phase,
Day or Stage changes, recorded entirely in the session host and never inside `history` (a replay
must reproduce a game from decisions alone).
- `index.ts` loads `game.json` on boot before starting the listener: version match → resumed and
replayed straight through; mismatch → refused explicitly and loudly, file left untouched, server
starts with no active game rather than replaying under the wrong rules.
- Verified live: server started against a fresh data directory, a 2-player game created, intents
submitted from both seats, **the server process killed and restarted**, both `?seat=` streams
reconnected and picked up exactly where they left off — same Day/Stage/phase, correct whose-turn,
correct narration attribution. Separately confirmed the version-mismatch path with a hand-edited
`engineVersion`.
- **Found and fixed an infrastructure bug along the way:** adding `test/server/` broke `npm test`'s
glob. `"test": "node --test test/**/*.test.ts"` relied on the shell passing the literal,
unexpanded pattern through whenever it matched no files at the shell level — the moment a
subdirectory existed, the shell expanded it to just that one file, and `npm test` silently ran only
the new suite. Fixed by listing both depths explicitly.
### Two rules bugs found while building this
- **New Train phase car-placement is one player's job even in competitive mode — it should be a
round.** §7 is explicit: starting with the Superintendent and working left, each player places one
car, and the round repeats until the consist is full. `newTrainPhase` never implemented the round —
`enterPhase` resets `actorOffset` to 0 on entry and nothing ever incremented it the way Local Ops
does — so the actor was always the Superintendent alone, for every car of every train, in every
mode. Fixed by reading the round position off `tray.consist.length`, which already counts
placements toward that tray and resets per train with no new state needed.
- **Victory conditions unified across solitaire, competitive and coop.** One shared, configurable
`GameConfig` set (`days`, `minCombinedRevenue`, `maxCollisionsPerDay`, `maxCollisionsTotal`,
`pvpCardsAllowed`) replaces the old fixed `LENGTH_PROFILES.target`, a dead `firstToTarget` victory
condition, and a flat collision-floor constant. Collision caps stay flat rather than scaling with
player count — Jesse's call: more players means more independent chances to collide, not a bigger
shared budget, so multiplayer is deliberately riskier than solitaire at the same default. One New
Game dialog now covers all three modes, with fields greyed out wherever a mode forces a value.
### The three v0.4.9b/c/d playtest fixes, folded in
Already shipped on the patch line — see 0.4.9d below for the full writeup of each. Summarized: a
switching train's crew badge failed to draw once it left the Office square (display only, game state
was never affected); unloading a freight car always took the westmost one regardless of which car
was picked; and a legal decision (`newTrain.startExtra`) could render with zero buttons, which was
indistinguishable from a hang. 635 tests, 0 failures.
---
## 0.4.9d — 2026-08-21
Three bugs from the same playtest session, patched directly onto 0.4.9a rather than the in-progress
TODO.md
+281 -99
View File
@@ -14,8 +14,14 @@ to Rules Questions.
## Next
Nothing scheduled at the moment — v0.4.9's plan (coordinate labels, the no-switching fix, the
expedite rewrite, the `evaluateClearance` bug, the splash artwork) is built; see Done below.
Queued from the 2026-08-20 multiplayer planning session (reasoning in Multiplayer below), in order:
1. ~~**Fix the New Train phase car-placement round**~~ — done, see Multiplayer below.
2. ~~**Unify victory conditions across solitaire, competitive and coop**~~ — done, see Multiplayer
below.
3. ~~**Phase 2 of `docs/architecture/multiplayer.md` — server core**~~ — done, see Multiplayer below.
Nothing else queued at the moment.
---
@@ -58,6 +64,22 @@ The replay viewer, the save format, and how a game gets shared.
personal StartOS box at all.** If it is, (1) is the piece (2) would need anyway, so it is the
right thing to build first either way.
- [ ] **`fromSave`'s replayed narration loses "Player X" attribution — found 2026-08-20 building
multiplayer Phase 3, not fixed there.** `fromSave`'s loop (`game.ts`) calls `record(game,
result.events)` without the `actor` argument `submit()` always passes it (`game.ts`'s own
`record(game, events, actor)` — `actor` is what turns "Chose to draw a card" into "Player X
chose to draw a card"). So a restored save, an undone game (`undo` rebuilds via `fromSave`
internally), or a replayed one all lose attribution on every line — invisible in solitaire
because nothing ever compares a `fromSave`-built log against a live-played one (the one test
that compares logs, `test/web.test.ts`'s "leaves nothing in the log describing a move that was
taken back", compares `undo`'s `fromSave`-built log against ANOTHER `fromSave`-built log, so
the missing attribution cancels out both sides), but it would read as broken the moment more
than one seat's history is on screen at once — exactly what the replay viewer and any
multiplayer post-game replay (D20) need to get right. Fixed in `fromMultiplayerSave`
(multiplayer's version of this function, added for Phase 3) by passing `actor` through; not
touched in `fromSave` itself since it's used far more widely (undo, save/restore, the replay
viewer) and deserves its own careful look rather than a fix bundled into an unrelated change.
- [ ] **Review the standalone replay against the site's replay viewer.** `node src/sim/replay.ts
--seed 1234 --out replay.html` writes a self-contained HTML file; the site instead reads JSON
saves from `public/replays/`. Nothing links to the standalone one and its output is gitignored,
@@ -228,7 +250,10 @@ number until the rules stop moving.
those multipliers exist to relieve. The 8 sharp curves have already been taken out on that
argument; offices and industries are the two left. Until then, read no balance conclusion from the revenue
numbers; they are a functionality signal only.
- [ ] **RE-MEASURE THE BOT AT THE NEW DEFAULTS.** Both provisional rules below are now **settings on
- [ ] **Superseded 2026-08-20 by the victory-condition redesign (Multiplayer) — kept for the
measurements.** `minCombinedRevenue` replaces the fixed target these numbers were read
against; re-measure once that lands rather than off this. **RE-MEASURE THE BOT AT THE NEW
DEFAULTS.** Both provisional rules below are now **settings on
the New Game dialog** rather than fixed choices, and the defaults are not what the numbers in
this file were measured under: the opening hand defaults to **three random cards** (the
prototype rule) rather than 3+3, and **train revenue per transit defaults to 0** rather than 1.
@@ -237,7 +262,10 @@ number until the rules stop moving.
has actually been trying to read all along. Every mean, floor and threshold quoted below and in
the tests predates it. The three revenue rates run 0–5, so the useful next step is a sweep
rather than a single re-run.
- [ ] **REVIEW THE TWO NEW RULES ONCE THEY HAVE BEEN PLAYED — both went in provisional, and both are
- [ ] **Not superseded by the 2026-08-20 victory-condition redesign (Multiplayer) — these two stay
`houseRules` dials, separate from the new `GameConfig` victory dials.** Noted only so the two
redesigns aren't conflated. **REVIEW THE TWO NEW RULES ONCE THEY HAVE BEEN
PLAYED — both went in provisional, and both are
now selectable rather than fixed.** Jesse's call, both implemented and measured, both flagged
in `rules-v0.2.md`. What follows is what was measured when each was the only option.
@@ -293,8 +321,15 @@ number until the rules stop moving.
- [ ] **Train density.** Left alone by decision, but noted: 22 train cards in 140 are drawn less often
than 22 in 115 were, and trains scheduled fell 2.9 → 2.1 as a side effect of the other density
changes.
- [ ] **The victory target (20 over 5 Days) is out of reach by a factor of about four, and the
Office ladder is why.** Measured over 800 games with the tuned bot, which no longer throws
- [ ] **Superseded 2026-08-20 by the victory-condition redesign (Multiplayer) — kept for the
measurements and the reasoning.** `LENGTH_PROFILES.target` (20 over 5 Days, `standard`) is
retiring in favour of `minCombinedRevenue`, defaulting to `3 × players × days` (15 for
1-player/5-day, not 20) — a different number, deliberately not tuned to match this table.
Whether the Office-ladder bottleneck below still applies at the new default is worth
re-measuring once the redesign lands, but the fixed "20" this data argues against no longer
exists as a target. **The victory target (20 over 5 Days) is out of reach by a factor of
about four, and the Office ladder is why.** Measured over 800 games with the tuned bot, which
no longer throws
revenue away on collisions (0.0 a game, down from 0.4):
| trains scheduled | games | revenue | | Office reached | games | trains | revenue |
@@ -368,11 +403,88 @@ Deferred while planning the server; decisions and reasoning are in `docs/archite
pointed at the open internet for long. Note that one-game-at-a-time per person is expected
usage and deliberately NOT enforced — enforcing it needs cross-game state whose only job is
deciding when to release someone, and getting that wrong locks a player out.
- [ ] **WHY DOES A 4-PLAYER COMPETITIVE GAME END AFTER ~16 STAGES OF A POSSIBLE 60?** Measured while
sizing multiplayer: 8 games, all reaching Day 5, but only ~16 distinct (day, stage) pairs each
and ~355 intents. Most likely the collision or revenue floor (§3.4) firing early, which would
make a competitive game about an hour rather than four. Worth knowing whether that is the
design working or a balance bug — it decides what a lobby should tell players about length.
- [x] **~~WHY DOES A 4-PLAYER COMPETITIVE GAME END AFTER ~16 STAGES OF A POSSIBLE 60?~~ Answered
2026-08-20: the collision floor, not the revenue floor.** Traced `checkVictory`
(`advance.ts:1086-1133`): in competitive mode the revenue floor can only fire at the exact
Day-5 boundary (Stage 60), so it structurally cannot explain a 16-Stage ending. Only the
collision floor can (`advance.ts:1076-1080`, 3 collisions in one Day, checked at every Stage
boundary). `collisionsToday` is one counter every seat feeds, so a 4-player table burns a
fixed shared budget roughly 4x faster than one player would. Also: `multiplayer.md` §3's
8-game sample predates `DEFAULT_HOUSE_RULES` (v0.4.2) and most likely ran under what is now
`LEGACY_HOUSE_RULES` — that sizing data is stale on top of the collision-floor explanation.
Jesse's call, 2026-08-20: keep the collision caps flat rather than player-scaled (below), so
16-Stage games under default settings are an accepted, deliberate outcome, not something to
re-tune away — re-measure `multiplayer.md` §3's sizing table once the redesign lands, but
expect similar early endings by design.
- [x] **~~Victory conditions unified across solitaire, competitive and coop~~ — designed and
implemented 2026-08-20.** One shared, fully-configurable set of `GameConfig` dials replaces
`LENGTH_PROFILES.target`, `VictoryCondition: 'firstToTarget'` (confirmed dead — grepped, never
selected anywhere in the codebase today) and the flat `COLLISION_FLOOR_PER_DAY` constant:
| dial | meaning | default |
| --- | --- | --- |
| `days` | how many Days the game runs | 5, all modes |
| `minCombinedRevenue` | everyone loses if the table's total Revenue is below this when Days run out | `3 × players × days` — reuses `collectiveRevenueFloor()` (`content.ts:1020`), now also applied to solitaire (1 player) rather than competitive-only |
| `maxCollisionsPerDay` | everyone loses immediately, mid-game, once collisions in one Day reach this | 3, **flat — not scaled by players.** Jesse's call: more players means more independent chances to collide, not a bigger shared budget, so multiplayer is deliberately riskier than solitaire at the same default |
| `maxCollisionsTotal` | same, summed across the whole game | 5, flat, same reasoning |
| `pvpCardsAllowed` | whether the 22 opponent-directed cards (still unbuilt, see below) are in the deck | forced off in solitaire and coop — no valid target for them in either — on by default in competitive |
`0` means "off" for every dial. Win/lose shape is otherwise unchanged from what solitaire
already does: most Revenue when Days run out wins, unless `minCombinedRevenue` was missed, in
which case everyone loses — just made configurable per game instead of a fixed `length`
lookup. Coop keeps its existing "score is the table's total" model, now against a
configurable floor instead of `profile.target * players.length`.
**New Game dialog:** one shared dialog for all three modes, per Jesse — a mode radio button
at the top, the same field set underneath for all three, greyed out wherever a mode forces a
value (the PvP checkbox in solitaire/coop). Solitaire gains the four new dials alongside the
starting-hand and revenue-rate fields it already has; picking a mode only changes the
defaults, never the field set. **Deal stays disabled for Competitive/Co-op** with a "needs a
server" note, since Phase 2 didn't yet expose a way to actually start one from the browser
(see below) — only Solitaire's Deal path is wired to a real game today.
- [x] **~~New Train phase car-placement is one player's job even in competitive mode~~ — fixed
2026-08-20.** §7 (`rules-v0.2.md:346-363`) is explicit: "starting with the Superintendent and
working left, each player may place ONE car... the round repeats... until the consist is
full," with a worked 2-player example. `newTrainPhase` (`advance.ts:187-282`) never
implemented the round: `enterPhase` resets `actorOffset = 0` on entering the phase
(`advance.ts:172`) and `newTrainPhase` never incremented it the way `playerPhase` does for
Local Ops (`advance.ts:140`), so the actor was always the Superintendent alone, for every car
of every train made up that Stage. Fixed by reading the round position off
`tray.consist.length` instead — it already counts placements toward that tray and resets per
train with no new state needed. Test in `multiplayer.test.ts`, "the New Train phase
car-placement round rotates."
**Found in the process, not fixed, logged separately:** `newTrain.passCar`'s `check()`
(`apply.ts:959-967`) tests whether the *entire* Division Yard is empty rather than whether a
car suitable for *this* tray exists, and `reduce()` has no case for `carPassed` at all
(`apply.ts:2246-2247`, falls to `default: break` — applying a pass currently mutates nothing).
Unreachable in practice today: `trainNeedingCars` only ever flags a tray that already has a
suitable car waiting, so a legal `passCar` for the flagged tray can't occur. Only matters if a
future change lets the New Train phase address more than one tray at a time. Not fixed here —
nothing to verify against an intent that can't legally fire.
- [ ] **The redaction test (multiplayer.md §7) is more done than the plan suggests, but the
exhaustive check is still missing.** `test/multiplayer.test.ts`'s "the view shows one seat at
a time" section (added earlier) already proves `snapshot(s, ..., viewer)` gives each seat its
own hand, board, Revenue and impediments — traced `snapshot()` itself
(`src/sim/view.ts:1180-1219`): `hand` reads only `s.decks.hands.get(viewer)`, `deck` is a
count, other seats' hands appear only as `.length`, and `Frame`'s type has no `seed`,
`rngState` or card-id-dictionary field for anything to leak through by accident. What exists
is all spot-checks, though — "this seat's Frame has the right hand length." What's still
missing is the exhaustive one §7 actually calls for: serialize a seat's `Frame` and assert it
contains none of another seat's actual card ids and no deck order, so a future careless edit
is caught rather than assumed safe. Doesn't need a server — buildable now against `snapshot()`
and the existing `game()`/`playGame` harness already in `multiplayer.test.ts`. Held for now,
2026-08-20.
- [ ] **D19's switching-instrumentation still needs writing, once real people are playing.** "13%
for the bot" (`multiplayer.md` D19) was a one-off measurement, not code — nothing in `bot.ts`
or the sim tools logs it today. It needs live human wait-state data, so it can't usefully land
before Phase 2 and realistically not before Phase 4 (real people at a lobby, not bots). A few
lines when the time comes: log whether a legal local-only action existed for a waiting player,
and whether they took it the moment their turn arrived.
- [ ] **THE 22 OPPONENT-DIRECTED CARDS — 10 Action, 12 Space-use — ARE OUT OF EVERY DECK UNTIL THEY
ARE BUILT.** Jesse's call. They were already cut from solitaire (Q6, no legal target with one
player); they are now cut from the competitive deck too, because `checkPlay` answers both
@@ -382,72 +494,90 @@ Deferred while planning the server; decisions and reasoning are in `docs/archite
**three Enhancements are waiting on them**: Facing Point Locks, Water Column and Overpass are
wired and read, and fire only against these cards. Until then those three are dormant by
design rather than broken.
- [ ] **Multiplayer proper — Phases 0 and 1 done (v0.4.0), Phases 2–6 to go.** The full plan is
`docs/architecture/multiplayer.md` §12. The engine now has seat/player separation and
per-player turn state, the page renders from `Frame` + `Menu` alone and talks to a `Session`
rather than to the engine — so a `RemoteSession` can be dropped in without the page changing.
Still no server, no turn submission and no per-player push: that is Phase 2, and it is
deliberately held until the two provisional rules have been playtested, because a rule change
after the wire format is live is much more expensive than one before it.
- [x] **Multiplayer proper — Phases 0, 1 and 2 done (v0.4.0, 2026-08-20), Phases 3–6 to go.** The
full plan is `docs/architecture/multiplayer.md` §12. Phase 2 (server core) landed in one pass:
---
- `src/sim/frame-delta.ts` — the live per-seat board delta (`deltaFrame`/`applyDelta`), a
smaller, purpose-written replacement for reusing `replay.ts`'s `compress()` — that function
interns strings across a whole recorded array, which a live single-frame push has nothing to
intern against; only its one-step-back "null if unchanged" idea carried over.
- **Found and fixed a real bug tracing this**: `actionMenu(game, seat)` only used `seat` for the
`hand` field — everything else came from `currentActor(game)` regardless of who asked, so a
server computing every connected seat's Menu would have handed the acting player's legal
moves to a waiting seat, paired with the wrong seat's cards. Fixed in `game.ts` with a guard;
tested in `multiplayer.test.ts`.
- The redaction test (§7) is built — `test/redaction.test.ts` — and passed on the first run
against the existing `snapshot()`, confirming it was already correct, not just apparently so.
- `src/server/session.ts` — the game session host (pure logic, no sockets, reuses `game.ts`'s
`Game`/`submit`/`currentActor`/`actionMenu` wholesale rather than re-deriving intent
application/narration). **Found while building it**: `submit()` derives the acting player from
`currentActor(game)` itself and does not check who is calling it — safe for `LocalSession`
(one possible caller) but not for a server, so the session host verifies `seat ===
currentActor(game)` itself before ever calling `submit`, rejecting with `NOT_YOUR_TURN`
otherwise. Idempotent resend (a repeat `seq`) and the illegal-intent path (checked via
`check()` directly, so a rejection never pollutes the shared narration log with "not allowed"
text meant only for the submitter) are both handled here too.
- `src/server/http.ts` / `src/server/index.ts` — plain `node:http`, no framework (confirmed
nothing to reuse and nothing else warranted — zero runtime dependencies anywhere else in the
project). `POST /api/game`, `GET /api/stream` (SSE, per-seat, with a 20s heartbeat and an
`id:` line per push), `POST /api/intent`, and static serving of `dist/` so the server can be
same-origin with itself (D16). No `gameId`/multi-game concept yet — one game per process,
matching "Phase 2 has no lobby."
- `src/web/session.ts` gained `createRemoteSession`; `main.ts`'s `start()` switches on `?seat=`
presence (D4 — one bundle, unchanged). Every `LocalSession`-only call site in `main.ts`
(`seed()`, `save()`, `undo()`, the New Game dialog) now goes through an `isLocal()` type guard
rather than assuming, since `session` can now be either.
- **Found and fixed a real infrastructure bug**: adding `test/server/` broke `npm test`'s glob.
`"test": "node --test test/**/*.test.ts"` relied on bash's non-globstar behaviour of passing
the *literal, unexpanded* pattern through to Node (which then globs it correctly itself) —
that only happens when the pattern matches *no* files at the shell level. The moment a
subdirectory existed, bash expanded it to just that one file, and `npm test` silently ran only
the new suite. Fixed by listing both depths explicitly:
`"test": "node --test test/*.test.ts test/**/*.test.ts"`.
- Verified two ways: `test/server/session.test.ts` exercises the session host directly (no
sockets); a live end-to-end curl smoke test (server started, a 2-player game created, two SSE
streams opened, an intent rejected from the non-acting seat, accepted from the acting seat and
broadcast to both, a resent `seq` producing no second push, and the board correctly nulled on
the second push) — see the session transcript. **Not verified**: an actual browser — no
browser binary exists in this environment, so `RemoteSession`'s DOM-facing code
(`EventSource`/`fetch` wiring) compiled and typechecks but was not clicked through visually.
## Rules Questions
**Phase 3 (persistence/resumption) done, same session, 2026-08-21.** Per §12 steps 14-16 and
`lobby-and-sessions.md` §5-6 (unusually concrete — the exact storage shape was specified, not
designed here):
Blocked on a decision, not on work.
- [ ] **WHERE THE LOCAL'S COACH STANDS WHILE ITS ENGINE WORKS (§A.4) — now hit in play, still open.**
Trains 7/8 print "coach must remain on station track if switching", read as "the coach is never
set out". A cut comes off an OUTER end, so a coach on one outer end with the engine on the
other locks the train completely: it cannot set its freight car out, and cannot uncouple to run
around either, because that leaves the coach standing. Measured over 60 games — **1,181
positions where a set-out should have been possible, every one refused; no other train blocked
once.** Two of the six possible arrangements lock, and `ENGINE boxcar coach` — the one that
locks — is both prototypical and what make-up naturally produces.
**Worked around, not solved.** The make-up panel now tells the player to add the coach first
(v0.4.6), which produces `ENGINE coach boxcar` and works. The rules question is untouched: if
the coach may be set out **at the Office**, which is what the card's wording plainly says and
what a real mixed train does, then the prototypical make-up works and the advice becomes
unnecessary. That needs one exception to §A.4's blanket refusal to leave Rolling Stock at the
Office, for the coach and only on the Local. **Decision needed:** should the Office square — or
a station track beside it — accept a parked coach?
- [ ] **3/4 EXPRESS PRINTS A RULE IT CAN NEVER USE — Jesse's call.** The card says *"may drop or pick
up one freight car at every location"* and also prints **Expedite**. Expedite means the train
departs the Stage it arrives (Q3): it arrives in the Mainline phase, stands through Cargo, and
highballs in Supervisor Shift — so it is never on the board during a Local Operations phase,
which is the only phase in which freight is coupled or set out. Measured over 40 bot games:
**31 Office visits, 31 of them with no Local Operations turn.** X14 Fruit Growers Express is in
the same position, though its "may pick up one extra loaded reefer" is only a note today.
The four options put to Jesse, unchanged: drop Expedite from 3/4 only (the other Expedite
trains all print "no switching" and lose nothing); leave Q3 alone and strike the freight line
from the card; drop Expedite everywhere (it partly exists to relieve Crew Tray scarcity, so
this needs re-measuring); or move the Express's freight budget into the Cargo phase, where an
expedited train does still get a turn. **Nothing is broken** — this is a contradiction between
two lines on one card, and the timing rule itself is behaving exactly as recorded.
**Should be resolved as a side effect of the Expedite fix in Next**, once built: correcting
Q3 so an expedited train gets an ordinary Local Operations turn removes the contradiction
without picking any of the four options above. Leaving this open until that lands and is
confirmed in play.
- [ ] **THE INDUSTRY TABLE STILL DISAGREES WITH THE CARD REFERENCE — two items left, Jesse's call.**
v0.4.7 corrected the DIRECTIONS: the Grocer's Warehouse and the Oil Refinery are `flow: 'both'`,
as `card-reference.md` always said, which is what let an Ice House finally give a Grocer's its
outbound slot. Two discrepancies remain and both are deliberate for now.
**(a) Base capacities.** The reference prints Grocer's 2/2 with 2 Laborers and the Refinery 2/2
with 3; the engine gives every industry 1 per direction it allows, Mine Tipple included. Raising
one alone would be a balance change rather than a correction.
**(b) The Freight House card.** The reference is explicit — "'Freight House' is not a card. It is
the collective term for a freight facility that loads *and* unloads" — and the engine deals 6
copies of one. Removing them is a deck-composition change worth measuring, not a quiet delete.
- [ ] **Poling.** The only card in the deck with no defined behaviour — the sheet records its effect
as "TBD in the source". A test asserts it stays TBD so nobody invents one.
- [ ] **Heavy Grade orientation is rolled, not chosen.** The card prints "Player sets orientation",
but it is dealt during setup and setup has no decision point at all — `createGame` is a pure
function of the seed, which is also what makes a save portable. Rolled from the seed for now.
Revisit when setup gains an interactive phase; the orientation matters, because it decides
which direction climbs and therefore what Brakeman and Helpers are worth.
- `src/server/persistence.ts` — `game.json` (`{engineVersion, seed, config, playerNames,
history, status, createdAt}`) and `turn-timings.json`, both atomic-rewrite-then-rename, no
`gameId`/index yet (one game per process, same deferral as Phase 2's `gameId`).
- `game.ts` gained `fromMultiplayerSave` — `fromSave`'s multi-player sibling, built on
`newMultiplayerGame`. **Found while testing it**: `fromSave`'s replay loop calls
`record(game, result.events)` without the `actor` argument `submit()` itself always passes,
so every replayed line loses its "Player X" attribution — invisible for solitaire (nothing
ever compares a `fromSave` replay against a live-played log; `undo`'s rebuilt game is itself
`fromSave`-built, so the one test that compares logs only ever compares two unattributed
replays against each other) but immediately visible for multiplayer, where anonymous "Chose
to..." lines are unreadable the moment there is more than one seat. Fixed in the new function;
**`fromSave` itself still has the gap** — not touched here, since it is used far more widely
(undo, save/restore, the replay viewer) and deserves its own careful pass rather than a
touch-in-passing. Worth its own TODO item if picked up.
- `session.ts` gained `exportSave()`, `resumeSession()`, and turn-timing tracking — a `TurnTiming`
span (player, phase, day, stage, start/end wall-clock) closes and reopens whenever the acting
player, phase, Day or Stage changes; recorded entirely in the session host, never touching the
engine (which must stay clock-free and deterministic) and never stored inside `history` (a
replay must reproduce a game from decisions alone). No reporting/aggregation/UI on this data
yet — §5 calls that "optional... if unobtrusive," and the Phase 3 deliverable is the data
being recorded, not a view of it.
- `index.ts` loads `game.json` on boot before starting the HTTP listener: version match →
`resumeSession`, replayed straight through; mismatch → refused explicitly and loudly (the
file is left untouched, so rolling the running version back recovers it), server starts with
no active game rather than replaying under the wrong rules.
- Verified live, matching this phase's own "done when": server started against a fresh data
directory, a 2-player game created, intents submitted from both seats, **the server process
killed and restarted**, both `?seat=` streams reconnected and picked up exactly where they
left off — same Day/Stage/phase, correct whose-turn-it-is, correct narration attribution.
Separately confirmed the version-mismatch path: hand-edited `engineVersion` to a bogus value,
restarted, server logged the refusal and started with no active game (confirmed via `POST
/api/game` succeeding rather than 409ing).
---
@@ -455,12 +585,6 @@ Blocked on a decision, not on work.
Doesn't fit the above.
- [ ] **Engines are not a SUPPLY yet, only a position.** `engineAt` now records where the engine
sits in the tray and the consist shows it, but an engine is still conjured with the tray
rather than drawn from the Division Yard and returned to it. The rules put engines in the
Division Yard alongside the cars, with a predefined number of them, so running out of engines
should be a second way trains get held — today only the Crew Tray count does that. Needs a
number to start from, then playtesting.
- [ ] **Real audio, as committed assets.** Everything the game plays is synthesised from oscillators
(`src/web/sound.ts`), which was the honest choice for a site that fetches nothing — but it is a
placeholder, not the finished sound. Sound therefore defaults to OFF.
@@ -473,9 +597,18 @@ Doesn't fit the above.
`trainHighballed` (Office departures only), and `trainsDestroyed`. Good enough to keep as the
real thing rather than a placeholder — no WAV clips needed for these three.
- **Find and add the rest as assets**: steam whistle, grade-crossing bell, couplers clashing.
Needs licences that permit redistribution (CC0 or similar), files small enough to commit, and
a check that the "fetches nothing external" test still passes — assets must be served from the
site's own folder, never hot-linked.
**Every file added needs three things recorded alongside it: the sound file itself, its
source (where it was obtained from), and its license.** The preferred license is **CC0
("Creative Commons Zero")** — a public-domain dedication: the creator waives all copyright
and related rights, so the file may be used, modified, and redistributed for any purpose,
including commercial, with **no attribution required and no restriction**. That is the
cleanest fit for a file committed straight into the repo, since it needs no attribution to
track going forward. Only fall back to an equally-permissive alternative (e.g. a license that
explicitly permits redistribution with no ongoing obligation) if CC0 isn't available for a
given sound, and record that license's actual terms plainly rather than assuming they match
CC0. Files also need to be small enough to commit, and a check that the "fetches nothing
external" test still passes — assets must be served from the site's own folder, never
hot-linked.
- Keep the synthesised versions as the fallback for anything not sourced, so a missing file is
a quieter game rather than a broken one.
- [ ] **Regions as the primary model (the other half of §8.2).** The Division map now DRAWS regions,
@@ -491,22 +624,18 @@ Doesn't fit the above.
Doing it properly changes movement, so it invalidates every balance figure — revenue 8.7, the
freight numbers, all of it — and needs a full paired re-measure over 400 seeds. Needs the
source Start-position art for the ten card types before it can begin.
- [ ] **Player settings, saved.** The district's auto-focus is the first of these: it is DISPLAY
state, so in a multiplayer game two players may reasonably want it set differently and it must
never become part of game state. It currently resets on reload. Worth a settings object in
localStorage — auto-focus mode to start with, and whatever else earns a preference — kept
strictly separate from the save, which is the seed plus the intents and has to stay portable.
- [ ] **The test suite fails at random under `npm test`, and it is the runner rather than the code.**
`node --test test/**/*.test.ts` runs the files in parallel and three suites write and read the
same `dist/` — the static build, the published-replay check and "the three places a game is
drawn stay in step". Back-to-back full runs measured **9 failures then 0**; run one file at a
time and every suite passes. That is worse than a slow suite: it trains us to shrug at a red
run, which is exactly how a real regression gets waved through. Give the build test its own
output directory, or mark the trio to run serially.
- [ ] **Curves are drawn as two straight segments meeting**, not true arcs. Fine at this size, angular
close up.
- [ ] **Wide boards scroll.** A 40-card district and a 13-section Division both need horizontal
scrolling. Legible, not compact.
- [ ] **`card-reference.md`'s industry table may still be stale beyond Grocer's Warehouse, the Oil
Refinery and Freight House (corrected v0.5.0) — Mine Tipple, Produce Shed and Power Plant were
NOT re-verified.** The v0.5.0 pass corrected three rows (and the "Freight House is not a card"
claim across `card-reference.md`, `glossary.md`, `rules-v0.2.md` and `open-questions.md`) on
Jesse's explicit call. Checking `content.ts` while making that change turned up that
`mineTipple` and `powerPlant` are ALSO base 1 out/in + 1 Laborer in the engine — the same
uniform model as the three that were corrected — while `card-reference.md` still prints Mine
Tipple 3/3/4 and Power Plant 3/3/4, and the "Throughput — why these Laborer counts" section
right below the table is built entirely on those higher numbers. Flagged inline in
`card-reference.md` rather than silently rewritten — this needs the same kind of decision Jesse
made for the other three, not an assumption that the same correction applies, since raising or
lowering Laborer counts is also a balance question, not only a docs one.
---
@@ -768,3 +897,56 @@ Doesn't fit the above.
(3.0 MB) resized to a 145 KB JPEG (`public/images/`, copied into the build by `build-web.ts`)
and placed beside the title, tagline, blurb and both buttons in a side-by-side hero, stacking
to image-above-text on mobile.
- [x] **A coach may now be set out at the Office — v0.5.0, Jesse's call.** §A.4's blanket "no Rolling
Stock may be left at the Office" now carries one exception: any train (not just 7/8) may drop
one or more coaches there; freight and cabooses stay banned. Unlocks the `ENGINE boxcar coach`
arrangement that used to lock completely — measured at 1,181 refused set-outs over 60 games,
every one of them this case. `canDropCarsAt` (`track.ts`) takes a `coachesOnly` flag instead of
refusing the Office outright; trains 7/8's `coachStaysOnStationTrack` rule now forbids the coach
everywhere EXCEPT the Office, rather than everywhere. The Office's "cars fouling the Running
Track" collision (`advance.ts`) is exempted for coach-only standing cars, so a legally parked
coach is not a hazard to the next arrival.
- [x] **3/4 EXPRESS PRINTS A RULE IT CAN NEVER USE — closed, v0.5.0.** Confirmed already resolved as
a side effect of the v0.4.9 Expedite fix (see that entry above); removed from Rules Questions.
- [x] **THE INDUSTRY TABLE VS. THE CARD REFERENCE — v0.5.0, Jesse's call: the engine was right, the
docs were stale.** `card-reference.md` printed Grocer's Warehouse and Oil Refinery at 2/2 with
2–3 Laborers, and claimed "'Freight House' is not a card"; the engine already had both
industries at 1 out/1 in/1 Laborer and already dealt Freight House as a real sixth industry, 6
copies. Corrected the docs (`card-reference.md`, `glossary.md`, `rules-v0.2.md`,
`open-questions.md`) to match the engine; no engine change. Turned up that Mine Tipple, Produce
Shed and Power Plant may be similarly stale — flagged as a new item above rather than assumed.
- [x] **Poling — closed, v0.5.0.** Confirmed already at 0 copies, the same treatment as Sharp Curves,
pinned by `mainline-cards.test.ts`. No code change; removed from Rules Questions.
- [x] **Heavy Grade orientation stays rolled, permanently — v0.5.0, Jesse's call.** The card prints
"Player sets orientation", but a Heavy Grade sits on the shared Division chain between two
players (or beyond an end Division Point, next to one) — never inside one player's own district
— so there is no single player with a fair claim to the choice. Settled as random from the
seed, identically for solitaire and multiplayer, overriding the card's print. No code change
(the roll in `setup.ts` was already doing this); the comments and `implications.md` §10 Q11
previously framed it as a placeholder awaiting an interactive setup phase — corrected.
- [x] **Engines are not a separate supply from Crew Trays — confirmed, v0.5.0.** `rules-v0.2.md`:339
(Gap 4b) ties Crew Trays and engine pieces together as one combined resource, `player count +
3` — not two independently-tracked supplies. The engine already enforces exactly that via
`crewTrayCount`/`freeTrays`; `NO_FREE_TRAY` already fires exactly when engine supply would run
out too. No code change; corrected the comments that called this provisional or unsourced.
- [x] **Player settings, saved — v0.5.0.** A `localStorage` settings object (`SETTINGS_KEY`, separate
from the game save) now persists district auto-focus mode, sound on/off, and board zoom level
across reloads — all three previously reset every time. Falls back to today's defaults on a
missing, corrupt, or disabled `localStorage`, the same guard the save already had.
- [x] **The test suite's flakiness under `npm test` — fixed, v0.5.0.** Two changes: (1) a `pretest`
npm script now builds the shared `dist/` once, before `node --test` runs, so every test reading
`dist/` no longer depends on another test in the file having built it first; (2) the one test
that actually exercises the build COMMAND now builds into its own `dist-test/` directory
(`BUILD_DIST_DIR` env var, `scripts/build-web.ts`) instead of rebuilding the shared `dist/` out
from under the tests reading it. `dist/` is now single-writer.
- [x] **Curves and turnout diverging legs now draw as smooth curves, not two straight segments
meeting at a corner — v0.5.0.** `curvedRail` in `board-svg.ts` replaces the old hard-cornered
"run to the frog, then a straight 45° leg" with a sampled cubic-Bezier easement: tangent to
horizontal at the east/west edge (so an abutting straight card's rail still reads as one
unbroken line) and tangent to exactly 45° at the north/south edge (so two stacked curves still
read as one continuous diagonal). Both plain curve cards and a turnout's diverging leg go
through this same code path, so both are fixed by the one change.
- [x] **Wide boards can now be zoomed — v0.5.0.** Discrete zoom presets (75/100/125/150%) for both
the district grid and the Division map, applied by resizing the rendered SVG's own pixel
dimensions (not a CSS `transform`), so the existing `overflow-x:auto` scrollbars keep doing the
panning with no new gesture code. Persisted in the new settings object above.
docs/rules/card-reference.md
+16 -5
View File
@@ -42,17 +42,28 @@ Operational Rail wheel icon, an industry track of the stated length, Laborer ico
| --- | --- | --- | ---: | ---: | ---: | ---: | ---: |
| Mine Tipple | Hopper | Outbound only | 3 | 3 | — | 4 | 2 |
| Produce Shed | Reefer | Outbound only | 2 | 2 | — | 3 | 2 |
| Grocer's Warehouse | Boxcar | Both | 2 | 2 | 2 | 3 | 2 |
| Oil Refinery | Tank car | Both | 3 | 2 | 2 | 4 | 2 |
| Grocer's Warehouse | Boxcar | Both | 1 | 1 | 1 | 3 | 3 |
| Oil Refinery | Tank car | Both | 1 | 1 | 1 | 4 | 3 |
| Power Plant | Hopper | Inbound only | 3 | — | 3 | 4 | 2 |
| Freight House | Boxcar | Both | 1 | 1 | 1 | — | 6 |
Directions follow the commodity: coal originates at a Mine Tipple and is consumed at a Power Plant;
produce ships out; a warehouse and a refinery do both. This gives §9 all three of its cases —
outbound-only, inbound-only, and both.
**"Freight House"** (§9.3, Appendix A) is not a card. It is the collective term for a freight facility
that loads *and* unloads — the Grocer's Warehouse and the Oil Refinery. §9.3's "Passenger Facilities
and Freight Houses permit cars to move each direction" therefore names exactly those two.
**"Freight House" IS a card** (corrected v0.5.0) — a sixth industry, dealt 6 copies, one Laborer and
one slot each direction. An earlier pass here read §9.3/Appendix A's "Passenger Facilities and
Freight Houses permit cars to move each direction" as meaning "Freight House" was only ever a
*collective term* for the Grocer's Warehouse and the Oil Refinery, never a card of its own — that
reading was wrong; the engine deals it as a real sixth industry (`content.ts`'s `freightHouse`
profile) and this table follows the engine.
<!-- TODO v0.5.0: Mine Tipple, Produce Shed and Power Plant above (3/3/4, 2/2/3, 3/3/4) were NOT
re-verified against the engine in this pass — only Grocer's Warehouse, Oil Refinery and Freight
House were. `mineTipple` and `powerPlant` in `content.ts` are also base 1/1/1, same as the three
corrected here, so these three rows and the "Throughput" reasoning below (built on the OLD
2–3-Laborer numbers) may be stale too. Flagged in TODO.md rather than silently rewritten — this
needs the same kind of decision Jesse made for Grocer's/Refinery/Freight House, not an assumption
that the same correction applies. -->
### Throughput — why these Laborer counts
docs/rules/glossary.md
+2 -2
View File
@@ -24,8 +24,8 @@ Every defined term, alphabetized for lookup. The core comes from the Definitions
| **Extra Platform** | Modifier card: +1 green and +1 red slot at a Passenger Facility. | §12.5 |
| **Extra Train** | A one-and-done train; its card returns to the Salvage Yard on completion. Head-on card image, so the drawing player picks its direction. Numbered with an "X" prefix; the following number gives its seniority, and it yields to the Timetabled train of that number. | §2.3, §8 |
| **Facility** | A business which loads/unloads cargo and freight. | §2.5 |
| **Freight Facility** | Mine Tipples, Produce Sheds, Grocer's Warehouses, Oil Refineries, Power Plants. Some allow only outbound, some only inbound, some both. Per-card values in §12.5. | §9, §12.5 |
| **Freight House** | Not a card — the collective term for a freight facility permitting both directions, namely the Grocer's Warehouse and the Oil Refinery. | §9.3, §12.5 |
| **Freight Facility** | Mine Tipples, Produce Sheds, Grocer's Warehouses, Oil Refineries, Power Plants, Freight Houses. Some allow only outbound, some only inbound, some both. Per-card values in §12.5. | §9, §12.5 |
| **Freight House** | A sixth Freight Facility card (corrected v0.5.0 — an earlier pass here read it as a collective term for the Grocer's Warehouse and the Oil Refinery rather than a card of its own; it is dealt like any other industry). Permits both directions, the same as a Grocer's Warehouse or Oil Refinery. | §9.3, §12.5 |
| **Highball** | When a train holding at an Office automatically departs. | §2.4 |
| **Home Office** | The primary face-down deck cards are drawn from. 52 cards. | §2.6, §12.1 |
| **Hopper** | Coal rolling stock (brown = loaded, white = empty). | §2.2 |
docs/rules/implications.md
+6 -4
View File
@@ -82,10 +82,12 @@ direction. `DivisionNode.gradeUp` records the direction a train travels when **c
going the other way is descending. Brakeman and Airbrakes apply to the descent, Helpers to the
climb, so turning the card around swaps which trains each card helps.
One gap remains, and it is a **setup** gap rather than a rules one: `createGame` is synchronous and
returns a ready state, so there is no point at which a player can be asked. Orientation is currently
**rolled** — deterministic from the seed, and roughly even (51/49 east/west across 400 games) — and
should become a real player choice when setup gains an interactive phase.
**Settled (v0.5.0): orientation is never a player choice, and this overrides the card's own printed
"Player sets orientation."** A Heavy Grade sits on the shared west-to-east Division chain, between
two players (§4.2) or beyond an end Division Point next to one — never inside a single player's own
district — so whichever direction climbs advantages one neighbour over the other, and no one player
has a fair claim to the decision. Orientation is **rolled** from the seed instead — deterministic,
and roughly even (51/49 east/west across 400 games) — identically for solitaire and multiplayer.
**Still not implemented**: the Action (10) and Space-use (12) cards, which are genuinely
multiplayer-only. Playing them is rejected with `NOT_IMPLEMENTED`.
docs/rules/open-questions.md
+6 -4
View File
@@ -718,10 +718,12 @@ leave no way at all to speed up a slow facility. Section Gang is the sole worker
keeps that power scarce. Capacity modifiers are stronger than they sound, since banking room rather
than worker count is what limits output.
**Sub-decision — what a "Freight House" is.** §9.3 and Appendix A refer to Freight Houses, but §9's
facility list never defines one. It is **not a card**: it is the collective term for a freight
facility that both loads and unloads — under 10a, the Grocer's Warehouse and the Oil Refinery. This
reconciles every reference without adding a card type or disturbing Gap 4a's deck composition.
**Sub-decision — what a "Freight House" is. SUPERSEDED (v0.5.0).** §9.3 and Appendix A refer to
Freight Houses, but §9's facility list never defines one. This originally concluded it was **not a
card** — the collective term for a freight facility that both loads and unloads, under 10a the
Grocer's Warehouse and the Oil Refinery. That reading was wrong: it **is** a card, a sixth Freight
Facility dealt 6 copies (`content.ts`'s `freightHouse` profile), which the engine has implemented
all along. Left here for the reasoning; do not read this entry as current.
### 10e — Revenue/Day revalidated, and the Gap 6 targets revised
docs/rules/rules-v0.2.md
+7 -5
View File
@@ -452,9 +452,10 @@ Loading and unloading of Rolling Stock (passengers and freight) takes place in t
(§11). A Whistle Post is not a Passenger Facility, so a player who has not upgraded has no
passenger business at all.
- **Freight Facilities:** Mine Tipples, Produce Sheds, Grocer's Warehouses, Oil Refineries, Power
Plants. Per-card values in §12.5.
- **Freight House:** **[Gap 10d]** not a facility type of its own, but the collective term for a
freight facility permitting both directions — the Grocer's Warehouse and the Oil Refinery.
Plants, Freight Houses. Per-card values in §12.5.
- **Freight House:** a Freight Facility card in its own right (corrected v0.5.0 — **[Gap 10d]**
previously read this as a collective term for the Grocer's Warehouse and the Oil Refinery rather
than a card of its own). Permits both directions, the same as those two.
- **Modifier Facilities:** Cards that, placed adjacent (on any of the nine nearby spots), increase a
passenger or freight facility's capacities. If two Facilities are adjacent to the Modifier, its
effects may only be used on one Facility per **Stage** **[Gap 7]**.
@@ -753,8 +754,9 @@ Modifier effects, and track geometries — is catalogued in
| Extra Platform | +1 green and +1 red slot (passenger) |
| Section Gang | +1 Laborer or +1 Porter |
**"Freight House"** (§9.3, Appendix A) is not a card — it is the collective term for a freight
facility that both loads and unloads, namely the Grocer's Warehouse and the Oil Refinery.
**"Freight House"** (§9.3, Appendix A) is a Freight Facility card (corrected v0.5.0 — previously
read as not a card, only a collective term for a facility that both loads and unloads). It permits
both directions, the same as the Grocer's Warehouse and the Oil Refinery.
---
docs/station-master-seed116956197-day2.json
+301
View File
@@ -0,0 +1,301 @@
{
"seed": 116956197,
"history": [
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 0
},
{
"type": "card.play",
"cardId": "c27"
},
{
"type": "card.play",
"cardId": "c30"
},
{
"type": "card.play",
"cardId": "c4"
},
{
"type": "card.play",
"cardId": "c2"
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 2
},
{
"type": "card.play",
"cardId": "c197",
"placement": {
"row": 0,
"col": -1
},
"variant": 1
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 2
},
{
"type": "card.play",
"cardId": "c163",
"placement": {
"row": 1,
"col": -1
},
"variant": 0
},
{
"type": "card.play",
"cardId": "c41",
"placement": {
"row": 1,
"col": 0
},
"variant": 0
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 0
},
{
"type": "card.play",
"cardId": "c127",
"placement": {
"row": 0,
"col": 1
},
"variant": 0
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.play",
"cardId": "c183",
"placement": {
"row": 0,
"col": 2
},
"variant": 1
},
{
"type": "card.play",
"cardId": "c150",
"placement": {
"row": 1,
"col": 2
},
"variant": 0
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 1
},
{
"type": "card.play",
"cardId": "c136",
"placement": {
"row": 1,
"col": 1
},
"variant": 0
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 0
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.discard",
"cardId": "c77",
"toSlot": 1
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.discard",
"cardId": "c171",
"toSlot": 0
},
{
"type": "draw.end"
},
{
"type": "newTrain.placeCar",
"trayId": "tray3",
"carType": "boxcar",
"loaded": false
},
{
"type": "newTrain.placeCar",
"trayId": "tray3",
"carType": "boxcar",
"loaded": true
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.discard",
"cardId": "c153",
"toSlot": 1
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.play",
"cardId": "c9"
},
{
"type": "draw.end"
},
{
"type": "newTrain.placeCar",
"trayId": "tray2",
"carType": "coach",
"loaded": true
},
{
"type": "newTrain.placeCar",
"trayId": "tray2",
"carType": "coach",
"loaded": true
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "switch"
}
],
"rules": {
"startingHand": "sixRandom",
"revenue": {
"passengerPerCoach": 1,
"freightPerLoad": 1,
"trainPerTransit": 0
}
}
}
docs/station-master-seed116956197-day2b.json
+714
View File
@@ -0,0 +1,714 @@
{
"seed": 116956197,
"history": [
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 0
},
{
"type": "card.play",
"cardId": "c27"
},
{
"type": "card.play",
"cardId": "c30"
},
{
"type": "card.play",
"cardId": "c4"
},
{
"type": "card.play",
"cardId": "c2"
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 2
},
{
"type": "card.play",
"cardId": "c197",
"placement": {
"row": 0,
"col": -1
},
"variant": 1
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 2
},
{
"type": "card.play",
"cardId": "c163",
"placement": {
"row": 1,
"col": -1
},
"variant": 0
},
{
"type": "card.play",
"cardId": "c41",
"placement": {
"row": 1,
"col": 0
},
"variant": 0
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 0
},
{
"type": "card.play",
"cardId": "c127",
"placement": {
"row": 0,
"col": 1
},
"variant": 0
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.play",
"cardId": "c183",
"placement": {
"row": 0,
"col": 2
},
"variant": 1
},
{
"type": "card.play",
"cardId": "c150",
"placement": {
"row": 1,
"col": 2
},
"variant": 0
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 1
},
{
"type": "card.play",
"cardId": "c136",
"placement": {
"row": 1,
"col": 1
},
"variant": 0
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromDepartment",
"slot": 0
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.discard",
"cardId": "c77",
"toSlot": 1
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.discard",
"cardId": "c171",
"toSlot": 0
},
{
"type": "draw.end"
},
{
"type": "newTrain.placeCar",
"trayId": "tray3",
"carType": "boxcar",
"loaded": false
},
{
"type": "newTrain.placeCar",
"trayId": "tray3",
"carType": "boxcar",
"loaded": true
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.discard",
"cardId": "c153",
"toSlot": 1
},
{
"type": "draw.end"
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.play",
"cardId": "c9"
},
{
"type": "draw.end"
},
{
"type": "newTrain.placeCar",
"trayId": "tray2",
"carType": "coach",
"loaded": true
},
{
"type": "newTrain.placeCar",
"trayId": "tray2",
"carType": "coach",
"loaded": true
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "switch"
},
{
"type": "switch.move",
"trayId": "tray3",
"to": {
"row": 0,
"col": -2
},
"reverse": false
},
{
"type": "switch.move",
"trayId": "tray3",
"to": {
"row": 1,
"col": 0
},
"reverse": true
},
{
"type": "switch.dropCars",
"trayId": "tray3",
"count": 1
},
{
"type": "switch.move",
"trayId": "tray3",
"to": {
"row": 0,
"col": -2
},
"reverse": false
},
{
"type": "switch.move",
"trayId": "tray3",
"to": {
"row": 0,
"col": 0
},
"reverse": true
},
{
"type": "switch.end"
},
{
"type": "laborer.beginUnload",
"at": {
"row": 1,
"col": 0
},
"carIndex": 0
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.discard",
"cardId": "c162",
"toSlot": 2
},
{
"type": "draw.end"
},
{
"type": "porter.detrain",
"at": {
"row": 0,
"col": 0
}
},
{
"type": "porter.detrain",
"at": {
"row": 0,
"col": 0
}
},
{
"type": "laborer.advanceLoad",
"at": {
"row": 1,
"col": 0
},
"box": 2
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "freightAgent"
},
{
"type": "freightAgent.clearInbound",
"at": {
"row": 0,
"col": 0
},
"index": 0
},
{
"type": "laborer.advanceLoad",
"at": {
"row": 1,
"col": 0
},
"box": 1
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "freightAgent"
},
{
"type": "freightAgent.clearInbound",
"at": {
"row": 0,
"col": 0
},
"index": 0
},
{
"type": "laborer.advanceLoad",
"at": {
"row": 1,
"col": 0
},
"box": 0
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "freightAgent"
},
{
"type": "freightAgent.stockOutbound",
"at": {
"row": 1,
"col": 0
},
"carType": "boxcar"
},
{
"type": "laborer.startLoad",
"at": {
"row": 1,
"col": 0
}
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "freightAgent"
},
{
"type": "freightAgent.stockOutbound",
"at": {
"row": 0,
"col": 0
},
"carType": "coach"
},
{
"type": "newTrain.placeCar",
"trayId": "tray2",
"carType": "boxcar",
"loaded": true
},
{
"type": "newTrain.placeCar",
"trayId": "tray2",
"carType": "boxcar",
"loaded": true
},
{
"type": "newTrain.placeCar",
"trayId": "tray2",
"carType": "boxcar",
"loaded": true
},
{
"type": "newTrain.placeCar",
"trayId": "tray2",
"carType": "caboose",
"loaded": true
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "freightAgent"
},
{
"type": "freightAgent.clearInbound",
"at": {
"row": 1,
"col": 0
},
"index": 0
},
{
"type": "laborer.advanceLoad",
"at": {
"row": 1,
"col": 0
},
"box": 0
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "freightAgent"
},
{
"type": "freightAgent.stockOutbound",
"at": {
"row": 0,
"col": 0
},
"carType": "coach"
},
{
"type": "laborer.advanceLoad",
"at": {
"row": 1,
"col": 0
},
"box": 1
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "draw"
},
{
"type": "draw.fromHomeOffice"
},
{
"type": "card.discard",
"cardId": "c50",
"toSlot": 0
},
{
"type": "draw.end"
},
{
"type": "laborer.advanceLoad",
"at": {
"row": 1,
"col": 0
},
"box": 2
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "switch"
},
{
"type": "switch.move",
"trayId": "tray2",
"to": {
"row": 0,
"col": -2
},
"reverse": true
},
{
"type": "switch.dropCars",
"trayId": "tray2",
"count": 1
},
{
"type": "switch.move",
"trayId": "tray2",
"to": {
"row": 0,
"col": 3
},
"reverse": false,
"via": {
"row": 0,
"col": 0
}
},
{
"type": "switch.move",
"trayId": "tray2",
"to": {
"row": 1,
"col": 0
},
"reverse": true
},
{
"type": "switch.move",
"trayId": "tray2",
"to": {
"row": 0,
"col": 3
},
"reverse": false
},
{
"type": "switch.move",
"trayId": "tray2",
"to": {
"row": 0,
"col": 1
},
"reverse": true
},
{
"type": "switch.dropCars",
"trayId": "tray2",
"count": 1
},
{
"type": "switch.move",
"trayId": "tray2",
"to": {
"row": 0,
"col": 3
},
"reverse": false
},
{
"type": "newTrain.placeCar",
"trayId": "tray3",
"carType": "tank",
"loaded": false
},
{
"type": "newTrain.placeCar",
"trayId": "tray3",
"carType": "tank",
"loaded": false
},
{
"type": "loadUnload.end"
},
{
"type": "localOps.choose",
"option": "switch"
},
{
"type": "switch.move",
"trayId": "tray2",
"to": {
"row": 1,
"col": 0
},
"reverse": true
},
{
"type": "switch.dropCars",
"trayId": "tray2",
"count": 3
},
{
"type": "switch.move",
"trayId": "tray2",
"to": {
"row": 0,
"col": 3
},
"reverse": false
},
{
"type": "switch.move",
"trayId": "tray2",
"to": {
"row": 0,
"col": -2
},
"reverse": true,
"via": {
"row": 0,
"col": 1
}
},
{
"type": "switch.move",
"trayId": "tray2",
"to": {
"row": 0,
"col": 0
},
"reverse": false
},
{
"type": "switch.end"
}
],
"rules": {
"startingHand": "sixRandom",
"revenue": {
"passengerPerCoach": 1,
"freightPerLoad": 1,
"trainPerTransit": 0
}
}
}
docs/station-master-seed116956197-day3b.json
+1004
View File
File diff suppressed because it is too large Load Diff
docs/testing/0.5.0-test-plan.md
+195
View File
@@ -0,0 +1,195 @@
# Station Master 0.5.0 — Test Plan
Written 2026-08-21, against an uncommitted working tree. Covers only the changes made in this
session's work — victory-condition unification, the New Train phase fix, and the multiplayer server
(Phases 2-3). Nothing here is committed yet; see the Coordination Note below before running any of it
against a tree that has since moved.
## Coordination note — shared working tree
Another thread is bug-fixing the 0.4.9 series **in this same uncommitted working tree**, concurrently.
`git status` shows changes I did not make in: `apply.ts`, `events.ts`, `track.ts`, `board-svg.ts`,
`docs/rules/*.md`, `package-lock.json`, `scripts/build-web.ts`, `.gitignore`, plus new
`docs/station-master-seed*.json` files still appearing as of this writing. **This plan does not cover
any of that** — it is scoped to the files below, which are the ones I actually touched.
Practical implications:
- Before running this plan, confirm the files under "Files this plan covers" still read the way this
document describes them — the other thread's commits could in principle touch the same functions
(`apply.ts`'s `check()` is used directly by `src/server/session.ts`, for instance).
- Run the full regression gate (`npm run typecheck && npm test`) fresh, not from a memory of an earlier
green run — both threads are editing live.
- The two bodies of work are unrelated in intent (0.4.9 patch fixes vs. 0.5.0 multiplayer groundwork)
but share a tree, so a clean split into separate commits before either is finalized is worth doing
deliberately rather than by accident.
### Files this plan covers
```
Engine: src/engine/advance.ts, src/engine/content.ts, src/engine/setup.ts, src/engine/state.ts
Web: src/web/game.ts, src/web/main.ts, src/web/play.html, src/web/session.ts
Sim: src/sim/view.ts, src/sim/frame-delta.ts (new), src/sim/compare.ts, src/sim/harness.ts,
src/sim/replay.ts
Server: src/server/ (new — index.ts, http.ts, session.ts, persistence.ts)
Tests: test/advance.test.ts, test/multiplayer.test.ts, test/web.test.ts, test/setup.test.ts,
test/redaction.test.ts (new), test/frame-delta.test.ts (new), test/server/ (new)
Docs: TODO.md, package.json (test script only)
```
---
## 0. Automated regression gate — run first, every time
```
npm run typecheck
npm test
```
Expected: typecheck clean, **all tests passing** (632 at the time this plan was written — the exact
number will drift as the other thread's work lands; what matters is zero failures). If either command
is red, stop and diagnose before doing anything below — a red gate means the manual steps are testing
against a broken build.
**If you only have time for one thing before the break ends, run this.** Everything else in this
document is either already covered by it, or is the manual/live verification that can't be — flagged
per-section below.
---
## 1. Regression baseline — solitaire must play exactly as before
The engine and dialog changes touch shared code paths solitaire also uses. None of this should have
changed solitaire's actual behavior.
| # | Test | Steps | Expected |
|---|---|---|---|
| 1.1 | Fresh deal | `npm run serve:web`, open `/play.html`, no URL params | A new random-seed solitaire game deals normally, board and hand render |
| 1.2 | Full game to completion | Play (or let a bot/harness play) a solitaire game to Day 5 | Game ends with a win/loss exactly as it would have before — `minCombinedRevenue` defaults to `collectiveRevenueFloor(1,5)=15`, not the old fixed `20`; a game scoring 15-19 that used to lose now wins (**intentional** — see §3, not a bug) |
| 1.3 | Save / restore | Play a few turns, reload the page (auto-restores from `localStorage`) | Game resumes exactly where it left off, house rules and victory dials intact |
| 1.4 | Save file download | Click "Save replay" mid-game | Downloads a small JSON; re-opening it in the replay viewer plays back identically |
| 1.5 | Undo | Play a few turns, click Undo repeatedly to the start | Each step back is clean; log never shows a move that "un-happened" |
| 1.6 | Existing published replays | Open each file under `public/replays/` in the replay viewer | All three still play back — `LEGACY_HOUSE_RULES` fallback for saves with no `houseRules` field is unaffected by this session's changes |
Automated coverage: `test/advance.test.ts`, `test/web.test.ts`, `test/session.test.ts` already assert
most of this at the unit level. §1 is about confirming nothing *visibly* changed for a solitaire
player, which only a live playthrough shows.
---
## 2. New Train phase car-placement rotation (engine fix)
**What changed:** the Superintendent used to place every car of every train alone, even in
competitive mode, against §7's written rule. Now the round rotates Superintendent-then-left, one car
per player, per `tray.consist.length`.
Automated: `test/multiplayer.test.ts`, "the New Train phase car-placement round rotates (§7, Gap 9)" —
asserts the exact actor sequence for 2p (wraps: 0,1,0) and 3p (no wrap: 0,1,2) against a real train
profile.
| # | Test | Steps | Expected |
|---|---|---|---|
| 2.1 | Manual multi-seat check | Drive a 3-4 player competitive game via the bot harness (`node src/sim/harness.ts`) or by hand through `src/server/`, and watch a Timetabled train get made up | Car-placement decisions visibly move between seats rather than one player filling the whole consist |
| 2.2 | Solitaire unaffected | Play any solitaire game where a train is made up | No visible change — one player, nothing to rotate, `tray.consist.length % 1 === 0` always |
Not covered, flagged in `TODO.md` (do not re-test, it's expected to be unreachable): `newTrain.passCar`
still has a dormant `check()`/`reduce()` gap, harmless because `trainNeedingCars` never offers a tray
with nothing suitable in the yard.
---
## 3. Victory conditions unified (`GameConfig` dials)
**What changed:** `days`, `minCombinedRevenue`, `maxCollisionsPerDay`, `maxCollisionsTotal`,
`pvpCardsAllowed` replace the old `length`-preset/`target`/flat collision constant, across all three
modes. Automated coverage: `test/advance.test.ts`'s "victory conditions (§3, Gap 10e) — unified
2026-08-20" describe block (8 tests) covers every case below at the engine level already. This section
is for confirming the *dialog* actually produces the numbers the engine then honors.
| # | Test | Steps | Expected |
|---|---|---|---|
| 3.1 | `minCombinedRevenue` — loss | New Game, set it to a number higher than achievable, play to Day N | Loss, reason `revenueFloor`, regardless of individual score |
| 3.2 | `minCombinedRevenue` — win | Set it to 0, play to Day N with any score | Win — `0` genuinely disables the floor |
| 3.3 | `maxCollisionsPerDay` — **new solitaire behavior** | Set to 1, deliberately cause 1 collision (e.g. leave every A/D track occupied on an arrival) | Game ends **immediately**, mid-Stage, loss, reason `collisionFloor` — solitaire could never lose this way before this change |
| 3.4 | `maxCollisionsTotal` | Set `maxCollisionsPerDay=0` (off), `maxCollisionsTotal=2`, cause 2 collisions across different Days | Game ends on the 2nd collision, whichever Day it falls on |
| 3.5 | Both collision caps at 0 | Set both to 0, cause several collisions | Game does **not** end early — same as pre-change solitaire (collisions still cost Revenue, just don't end the game) |
| 3.6 | Mode radio defaults | Open New Game, click Competitive | `minCombinedRevenue` suggests `3 × 4 × days` (nominal 4-player assumption — no lobby yet to ask real seat count), `pvpCardsAllowed` checks and enables, Deal disables with a "needs a server" note |
| 3.7 | Mode radio — Co-op | Click Co-op | `pvpCardsAllowed` unchecks and **greys out** (forced off, not just defaulted off — no valid target when everyone's on one side), Deal disables |
| 3.8 | Mode radio — back to Solitaire | Click Solitaire again | Deal re-enables, `pvpCardsAllowed` unchecks and greys, all four dials show the numbers the *currently playing* game actually has (not the preset) |
| 3.9 | URL round-trip | Deal a game with non-default `days`/`minrev`/`colday`/`coltotal`, copy the URL, open it in a new tab | Identical settings — all four now travel via `?days=&minrev=&colday=&coltotal=` alongside the existing `?hand=&passenger=&freight=&transit=` |
**Not yet clicked through in a real browser** (no browser binary in the sandbox this was built in —
verified only via a simulated-DOM test harness, `test/web.test.ts`'s "the New Game dialog" describe
block, which drives the actual compiled bundle). §3.6-3.9 specifically should get a real click-through
before calling this done.
---
## 4. Multiplayer server — Phase 2 (session core)
New in this release: `src/server/` (session host, HTTP/SSE, static serving), `src/web/session.ts`'s
`createRemoteSession`, `src/sim/frame-delta.ts`. Automated: `test/server/session.test.ts` (12 cases,
pure logic, no sockets), `test/redaction.test.ts` (4 cases — the exhaustive "no seat sees another
seat's secrets" check), `test/frame-delta.test.ts` (5 cases).
| # | Test | Steps | Expected |
|---|---|---|---|
| 4.1 | Boot | `JOIN_SECRET=x PORT=8081 node src/server/index.ts` | Starts, logs the bind address and `dist/` path |
| 4.2 | Join secret gate | `curl -X POST localhost:8081/api/game` (no `?secret=`) | `403 bad or missing secret` |
| 4.3 | Create game | `POST /api/game?secret=x` with `{config, playerNames}` | `200 {ok:true, playerCount:N}`; a second call while a game exists → `409` |
| 4.4 | Per-seat SSE | Open `/api/stream?seat=0` and `?seat=1` for a 2-player game | Only the current actor's push has a non-null `menu`; the other seat's is `null` |
| 4.5 | Turn enforcement | `POST /api/intent` as the **non-acting** seat | `{ok:false, code:"NOT_YOUR_TURN"}`, no broadcast, no state change |
| 4.6 | Accept + broadcast | `POST /api/intent` as the acting seat, a legal intent | `{ok:true}`; **both** SSE streams receive a push with fresh narration |
| 4.7 | Idempotent resend | Submit the same `{seq, intent}` twice | Second call: `{ok:true}`, **no** new SSE push (already applied, silently ignored) |
| 4.8 | Illegal intent | Submit something `check()` would reject | `{ok:false, code:"<real RejectionCode>"}`; the rejection text does **not** appear in the *other* seat's narration (private feedback, §session.ts's design note) |
| 4.9 | Board delta | Submit an intent that doesn't move anything on the board (e.g. `localOps.choose`) | The next push's `frame.division`/`frame.cells` are `null` (unchanged-since-last-push-to-this-seat) |
| 4.10 | Heartbeat | Hold an SSE connection open >20s idle | A `: ping` comment line appears (EventSource ignores it; keeps a proxy from reaping the socket) |
| 4.11 | **Real browser — not yet done** | Two actual browser tabs, `?seat=0` and `?seat=1`, playing a shared game by clicking | Confirm the whole loop works through the actual UI, not just curl: turn indicator, disabled controls for the non-acting seat, board updates on both sides, a rejected action shows *something* sensible on screen rather than silently doing nothing |
§4.1-4.10 were run live against a real server process during this session (not just unit-tested) — see
the session transcript for the actual curl commands and captured output. §4.11 genuinely was not done;
no browser was available in the environment this was built in.
---
## 5. Multiplayer server — Phase 3 (persistence and resumption)
New: `src/server/persistence.ts`, `game.ts`'s `fromMultiplayerSave`, `session.ts`'s `exportSave`/
`resumeSession`/turn-timing tracking. Automated: `test/server/persistence.test.ts` (6 cases),
`test/server/session.test.ts`'s "turn timings" and "persistence hooks" describe blocks.
| # | Test | Steps | Expected |
|---|---|---|---|
| 5.1 | Immediate persistence | `POST /api/game`, then check `DATA_DIR/game.json` | Exists immediately, empty `history`, correct `engineVersion` (= `package.json`'s `version`) |
| 5.2 | History grows | Submit a few intents | `game.json`'s `history` array grows by one entry per accepted intent, in order |
| 5.3 | Turn timings recorded | Submit enough intents to cross a full turn (player/phase/day/stage change) | `DATA_DIR/turn-timings.json` gains an entry: `{player, phase, day, stage, startedAt, endedAt}`, `endedAt >= startedAt` |
| 5.4 | **Restart and resume** (the actual "done when" for Phase 3) | Kill the server process mid-game, restart it against the same `DATA_DIR` | Log line: `"Resumed a saved game... N intents replayed"`; reconnecting both `?seat=` streams shows the exact same Day/Stage/phase/whose-turn as before the kill, correct narration attribution ("Player X chose to...", not anonymous) |
| 5.5 | Version-mismatch refusal | Hand-edit `game.json`'s `engineVersion` to a bogus value, restart | Log line refusing to load, naming both versions; server starts with **no** active game (confirm via `POST /api/game` succeeding, not `409`ing); the file is **not** deleted or modified |
| 5.6 | Atomic writes, no stray temp files | After several intents, check `DATA_DIR` | Only `game.json`/`turn-timings.json` present — no leftover `.tmp` files from an interrupted write |
§5.1-5.6 were all run live during this session (kill-and-restart included) — see the transcript. This
is the most thoroughly live-verified section of the whole plan.
---
## 6. Things this session found but did *not* fix — verify they're still correctly deferred
These are logged in `TODO.md`, not bugs to chase here — listed so a tester doesn't rediscover them and
assume something regressed.
| Item | Where | Current state to confirm |
|---|---|---|
| `fromSave`'s replay loses "Player X" narration attribution | `src/web/game.ts` | Still present in `fromSave` (untouched, out of scope); **fixed** in the new `fromMultiplayerSave` — §5.4's narration check is what confirms the fix landed where it needed to |
| `newTrain.passCar`'s `check()`/`reduce()` gap | `src/engine/apply.ts` | Still dormant/unreachable — confirm no new caller has started exercising it (would only matter if the *other* thread's 0.4.9 work touches this area) |
| No real browser click-through | This session | §3.6-3.9, §4.11 — the two gaps a human still needs to close |
---
## Summary checklist
- [ ] §0 automated gate green
- [ ] §1 solitaire regression (six checks)
- [ ] §2 New Train rotation, manual multi-seat check
- [ ] §3 victory conditions, especially §3.6-3.9 (dialog, not yet browser-verified)
- [ ] §4 server core, especially §4.11 (real browser, not yet done)
- [ ] §5 persistence — already live-verified this session; worth a second independent run
- [ ] §6 confirm the three known-and-deferred items are still exactly as described
package-lock.json
Generated
+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "station-master",
"version": "0.4.8",
"version": "0.5.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "station-master",
"version": "0.4.8",
"version": "0.5.0",
"devDependencies": {
"@types/node": "^26.1.2",
"typescript": "^7.0.2"
package.json
+3 -2
View File
@@ -1,6 +1,6 @@
{
"name": "station-master",
"version": "0.4.9d",
"version": "0.5.0",
"private": true,
"type": "module",
"description": "Station Master — a railroad operations game",
@@ -9,7 +9,8 @@
},
"scripts": {
"typecheck": "tsc --noEmit",
"test": "node --test test/**/*.test.ts",
"pretest": "node scripts/build-web.ts",
"test": "node --test test/*.test.ts test/**/*.test.ts",
"build:web": "node scripts/build-web.ts",
"serve:web": "node scripts/build-web.ts && npx --yes http-server dist -p 8080 -c-1",
"deploy:web": "node scripts/deploy-web.ts"
scripts/build-web.ts
+7 -1
View File
@@ -15,7 +15,13 @@ import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
const root = join(dirname(fileURLToPath(import.meta.url)), '..');
const dist = join(root, 'dist');
/**
* Overridable so a test can point the build at an isolated directory instead of the shared
* `dist/` the rest of the suite reads — see `test/web.test.ts`'s "builds, and needs nothing but a
* static host". Must be a sibling of `dist/`, not nested inside it: this script's own `rmSync`
* below wipes the whole directory it is given, so nesting one inside the other would still race.
*/
const dist = join(root, process.env['BUILD_DIST_DIR'] ?? 'dist');
rmSync(dist, { recursive: true, force: true });
mkdirSync(dist, { recursive: true });
src/engine/advance.ts
+52 -40
View File
@@ -27,9 +27,7 @@ import {
MOVES_PER_LOCAL_OPS_NIGHT,
STAGES_PER_DAY,
STAGES_PER_SHIFT,
collectiveRevenueFloor,
houseRules,
lengthProfile,
officeProfile,
REGIONS_PER_MAINLINE_CARD,
mainlineProfile,
@@ -273,10 +271,23 @@ function newTrainPhase(s: GameState, events: GameEvent[]): AdvanceResult {
return { events, needsInput: true };
}
// Gap 9 — the car-placement round REPEATS until the consist is full or no suitable car remains.
/**
* Gap 9 — the car-placement round REPEATS until the consist is full or no suitable car remains,
* cycling Superintendent-then-left one car at a time (§7).
*
* `tray.consist.length` IS the round position: a freshly made-up tray always starts with
* `consist: []`, and each `newTrain.placeCar` appends exactly one car to it (`apply.ts`'s
* `carPlacedOnTrain` reducer), so it counts placements toward THIS tray without any new state —
* and resets to 0 naturally for the next train made up, which a phase-wide `actorOffset` cannot
* do. Reproduces the rulebook's worked example exactly: 2 players, 4-coach Limited → seats
* 0, 1, 0, 1.
*/
const filling = trainNeedingCars(s);
if (filling) {
s.clock.currentActor = actorAt(s, s.clock.actorOffset % s.players.length);
const tray = s.trays.get(filling)!;
const nextActor = actorAt(s, tray.consist.length % s.players.length);
if (s.clock.currentActor !== nextActor) events.push({ type: 'actorChanged', player: nextActor });
s.clock.currentActor = nextActor;
return { events, needsInput: true };
}
@@ -893,8 +904,13 @@ function arriveAtOffice(
// §8.3 — cars standing on the Running Track between the Limits and the Office. A train at speed
// is not expecting them (§A.4), so this is a collision too, not a coupling.
//
// A coach is the one exception (v0.5.0, §A.4's Office carve-out): it may be legally, deliberately
// parked at the Office while its engine switches, so it must not become a hazard to the next
// arrival. Anything else standing there is still illegal to have dropped in the first place —
// `canDropCarsAt` already refuses it — so this filter only ever excludes a coach in practice.
const officeCard = area.grid.get(coordKey(area.officeCoord));
if (officeCard && officeCard.standing.length > 0) {
if (officeCard && officeCard.standing.some((c) => c.type !== 'coach')) {
collide(s, playerAtSeat(s, seat), [id], events, 'cars fouling the Running Track', 'the Running Track');
return 'moved';
}
@@ -956,6 +972,7 @@ function collide(
}
s.collisionsToday += 1;
s.collisionsTotal += 1;
const player = s.players[faultPlayer];
if (player) {
player.revenue -= COLLISION_PENALTY;
@@ -1067,47 +1084,52 @@ function shiftChange(s: GameState, events: GameEvent[]): AdvanceResult {
events.push({ type: 'stageBegan', day: s.clock.day, stage: s.clock.stage });
}
// §3.4 — Competitive only: three collisions in one Day and everyone loses.
if (s.config.mode === 'competitive' && s.collisionsToday >= 3) {
// §3.4 — every mode but competitive-and-coop-only: a Day's collisions against `maxCollisionsPerDay`
// and the game's running total against `maxCollisionsTotal`. `0` disables either check. Flat, not
// scaled by player count — Jesse's call, 2026-08-20: more players is more independent chances to
// collide, not a bigger shared budget.
if (s.config.mode === 'competitive' || s.config.mode === 'coop') {
const perDayBreach =
s.config.maxCollisionsPerDay > 0 && s.collisionsToday >= s.config.maxCollisionsPerDay;
const totalBreach =
s.config.maxCollisionsTotal > 0 && s.collisionsTotal >= s.config.maxCollisionsTotal;
if (perDayBreach || totalBreach) {
s.status = 'finished';
s.outcome = { result: 'loss', winner: null, reason: 'collisionFloor' };
return { events, needsInput: false };
}
}
return { events: [...events, ...enterPhase(s, 'localOps')], needsInput: false };
}
/** §3.3 — evaluated at the end of a Day. */
/**
* §3.3 — evaluated at the end of a Day.
*
* Unified 2026-08-20 across all three modes: play `config.days`, then whoever has the most Revenue
* wins — unless the table's combined Revenue missed `config.minCombinedRevenue`, in which case
* everyone loses. Solitaire is "everyone" with one player, so this is the same win/lose shape it
* always had, just against a configured floor instead of a `length`-preset `target`. Coop keeps its
* "the table's score is everyone's Revenue summed" model — winner stays null, the achievement is
* shared — now against the same configurable floor.
*/
function checkVictory(s: GameState, _events: GameEvent[]): boolean {
const profile = lengthProfile(s.config.length);
const daysElapsed = s.clock.day - 1;
if (s.config.victory === 'firstToTarget') {
const target =
s.config.mode === 'coop' ? profile.target * s.players.length : profile.target;
const score = s.config.mode === 'coop' ? totalRevenue(s) : Math.max(...s.players.map((p) => p.revenue));
if (score >= target) {
const winner =
s.config.mode === 'coop'
? null
: s.players.findIndex((p) => p.revenue === score);
s.status = 'finished';
s.outcome = { result: 'win', winner: winner === -1 ? null : winner, reason: 'targetReached' };
return true;
}
return false;
}
if (daysElapsed < profile.days) return false;
if (daysElapsed < s.config.days) return false;
s.status = 'finished';
if (s.config.mode === 'competitive') {
// §3.5 — all players' Revenue combined must clear the floor, or everyone loses.
if (totalRevenue(s) < collectiveRevenueFloor(s.players.length, profile.days)) {
const combined = totalRevenue(s);
if (s.config.minCombinedRevenue > 0 && combined < s.config.minCombinedRevenue) {
s.outcome = { result: 'loss', winner: null, reason: 'revenueFloor' };
return true;
}
if (s.config.mode === 'coop') {
s.outcome = { result: 'win', winner: null, reason: 'daysElapsed' };
return true;
}
const best = Math.max(...s.players.map((p) => p.revenue));
s.outcome = {
result: 'win',
@@ -1115,16 +1137,6 @@ function checkVictory(s: GameState, _events: GameEvent[]): boolean {
reason: 'daysElapsed',
};
return true;
}
// Solitaire and Co-op: the target doubles as a MINIMUM. Below it you lose regardless of score.
const target = s.config.mode === 'coop' ? profile.target * s.players.length : profile.target;
const score = s.config.mode === 'coop' ? totalRevenue(s) : (s.players[0]?.revenue ?? 0);
s.outcome =
score >= target
? { result: 'win', winner: null, reason: 'daysElapsed' }
: { result: 'loss', winner: null, reason: 'revenueFloor' };
return true;
}
// ---------------------------------------------------------------------------
src/engine/apply.ts
+10 -11
View File
@@ -697,25 +697,24 @@ export function check(s: GameState, player: PlayerIndex, i: Intent): RejectionCo
? tray.consist.slice(0, i.count)
: tray.consist.slice(tray.consist.length - i.count);
const dropRules = rulesOf(tray);
const dropArea = areaOf(s, player);
const atOffice = here.row === dropArea.officeCoord.row && here.col === dropArea.officeCoord.col;
/**
* Trains 7/8 Local — "coach must remain on station track if switching", i.e. the coach is
* never set out during switching at all.
*
* The intended reading was "set out only at the Office", but §A.4 makes that unimplementable:
* `canDropCarsAt` refuses the Office square outright — "the Office track is Operational Rail,
* but Rolling Stock may not be left there" — so "only at the Office" and "nowhere" are the same
* rule. What is left is the effect that matters: the Local may shunt its freight car around the
* district, and may not abandon its coach at an industry or on a siding while it does.
* Flagged in `TODO.md` in case the station track is meant to become a real place to leave one.
* Trains 7/8 Local — "coach must remain on station track if switching" — the coach may never
* be set out anywhere ELSE while switching. §A.4 now carries an exception for the Office
* square (v0.5.0, Jesse's call): any train may cut a coach loose there, which is exactly what
* "station track" meant on the card all along. So the coach is refused everywhere except the
* Office, rather than everywhere.
*/
if (dropRules.coachStaysOnStationTrack && cut.some((c) => c.type === 'coach')) {
if (dropRules.coachStaysOnStationTrack && cut.some((c) => c.type === 'coach') && !atOffice) {
return 'COACH_MUST_STAY';
}
const droppedFreight = cut.filter(isFreight).length;
if (droppedFreight > 0 && !freightBudgetLeft(s, player, tray, here, droppedFreight)) {
return 'FREIGHT_WORKED_HERE';
}
return canDropCarsAt(areaOf(s, player), here, i.count) ? null : 'CANNOT_DROP_HERE';
const coachesOnly = cut.every((c) => c.type === 'coach');
return canDropCarsAt(dropArea, here, i.count, coachesOnly) ? null : 'CANNOT_DROP_HERE';
}
case 'switch.sortConsist': {
src/engine/content.ts
+26 -7
View File
@@ -876,7 +876,13 @@ export function mainlineCardCount(players: number): number {
return players + 1;
}
/** Provisional; not in the recovered files. */
/**
* Sourced, not provisional: `rules-v0.2.md`:339, "There are only a limited number of Crew Trays
* and engine pieces [Gap 4b: player count + 3]." The rules tie Crew Trays and engine pieces
* together as ONE combined resource, not two independently-tracked supplies — an engine is never
* conjured separately from the tray it rides in, and the game has no state for "an engine with no
* tray" or "a tray with no engine". `state.ts`'s `freeTrays` pool already IS the engine supply.
*/
export function crewTrayCount(players: number): number {
return players + 3;
}
@@ -1003,7 +1009,11 @@ export const MOVES_PER_LOCAL_OPS = 6;
export const MOVES_PER_LOCAL_OPS_NIGHT = 5;
export const LABORER_ACTIONS_PER_LOAD = 4;
export const COLLISION_PENALTY = 5;
export const COLLISION_FLOOR_PER_DAY = 3;
/** Suggested defaults for `GameConfig`'s collision floors — see `state.ts`'s `GameConfig` doc. */
export const DEFAULT_MAX_COLLISIONS_PER_DAY = 3;
export const DEFAULT_MAX_COLLISIONS_TOTAL = 5;
/** Suggested default for `GameConfig.days`, all modes. */
export const DEFAULT_DAYS = 5;
/**
* Q3 — an expedited train left parked off the Office when a Mainline Phase begins is a Station
* Master fault: the train was not kept ready to highball the moment the Subdivision allowed it.
@@ -1011,18 +1021,27 @@ export const COLLISION_FLOOR_PER_DAY = 3;
*/
export const EXPEDITE_FAULT_PENALTY = 1;
/**
* The suggested default for `GameConfig.minCombinedRevenue` — a caller computes this before
* submitting a config; the engine itself never calls it (`state.ts`'s `GameConfig` doc explains why).
*/
export function collectiveRevenueFloor(players: number, days: number): number {
return 3 * players * days;
}
/**
* `GameLength` IS NOT PART OF `GameConfig` ANY MORE (2026-08-20) — `days` is a free variable there
* now, replacing the old `target`-bearing preset. This survives only as a convenience for sim/CLI
* tooling (`harness.ts`, `compare.ts`, `replay.ts`) that still wants a `short`/`standard`/`campaign`
* argument instead of a raw day count; `lengthProfile()` just resolves that argument to `days`.
*/
export type GameLength = 'short' | 'standard' | 'campaign';
export type LengthProfile = { length: GameLength; target: number; days: number };
export type LengthProfile = { length: GameLength; days: number };
/** Provisional and now unvalidated — the balance run they came from used a placeholder ruleset. */
export const LENGTH_PROFILES: readonly LengthProfile[] = [
{ length: 'short', target: 10, days: 3 },
{ length: 'standard', target: 20, days: 5 },
{ length: 'campaign', target: 45, days: 10 },
{ length: 'short', days: 3 },
{ length: 'standard', days: 5 },
{ length: 'campaign', days: 10 },
];
export function lengthProfile(length: GameLength): LengthProfile {
src/engine/setup.ts
+16 -13
View File
@@ -53,13 +53,16 @@ export type SetupOptions = {
};
/** Builds the 52-card Home Office deck (§12.1). Unshuffled; caller shuffles with the seeded RNG. */
export function buildDeck(mode: GameConfig['mode'] = 'competitive'): Card[] {
export function buildDeck(mode: GameConfig['mode'] = 'competitive', pvpCardsAllowed = false): Card[] {
/**
* THE 22 OPPONENT-DIRECTED CARDS ARE OUT OF EVERY DECK FOR NOW, not just the solitaire one.
* THE 22 OPPONENT-DIRECTED CARDS ARE OUT OF EVERY DECK REGARDLESS OF `pvpCardsAllowed`, for now.
*
* Q6 took them out of solitaire because they have no legal target in a one-player game. They are
* out of the competitive deck too because `checkPlay` answers both categories `NOT_IMPLEMENTED`:
* leaving them in would make ~9% of draws reject outright, which is worse than not dealing them.
* `pvpCardsAllowed` (`GameConfig`, wired 2026-08-20) is the player-facing toggle, but ANDing it
* with `cardsImplemented` keeps it inert until Phase 5 actually builds the cards — flipping
* `pvpCardsAllowed` on today must not turn a working game into one where ~9% of draws reject.
*
* AND SO ARE THE SEVEN CARDS THAT ANSWER THEM — see below. They used to be dealt and sit dormant,
* which is the same dead draw by another name. Recorded in TODO.md as multiplayer work.
@@ -68,7 +71,8 @@ export function buildDeck(mode: GameConfig['mode'] = 'competitive'): Card[] {
* for these two categories today.
*/
void mode;
const opponentCardsInDeck = false;
const cardsImplemented = false;
const opponentCardsInDeck = pvpCardsAllowed && cardsImplemented;
const cards: Card[] = [];
let n = 0;
const push = (kind: Card['kind']): void => {
@@ -226,17 +230,15 @@ function buildDivision(players: number, rng: Rng): DivisionNode[] {
const mainline = (): DivisionNode => {
const card = kinds[rng.nextInt(kinds.length)]!;
const node: DivisionNode = { kind: 'mainline', card, transits: [] };
// The Heavy Grade card says "Player sets orientation", but setup has no decision point yet —
// createGame is synchronous and returns a ready state. Rolled for now so the orientation is at
// least deterministic and varies between games; it should become a real player choice when
// setup gains an interactive phase. See implications.md §10 Q11.
if (mainlineProfile(card).speed.kind === 'grade') {
/**
* TEMPORARY, and flagged in TODO. The card prints "(Up)" and "Player sets orientation", so
* which way a Heavy Grade climbs is the player's decision — but it is dealt during setup, and
* setup has no decision point at all. Rolled from the seed until it gains one, because the
* orientation MATTERS: it decides which direction climbs, and therefore what a Brakeman or
* Helpers card is worth.
* SETTLED, not provisional (v0.5.0, Jesse's call) — this overrides the card's own printed
* "Player sets orientation". A Heavy Grade sits on the shared west-to-east chain BETWEEN two
* players (§4.2), or beyond an end Division Point next to one — never inside one player's own
* district — so whichever direction climbs advantages one neighbour over the other, and there
* is no single player who owns that call fairly. Orientation is rolled from the seed instead,
* identically for solitaire and multiplayer, and this is not expected to change when setup
* eventually gains an interactive phase for other decisions. See implications.md §10 Q11.
*/
node.gradeUp = rng.nextInt(2) === 0 ? 'east' : 'west';
}
@@ -317,7 +319,7 @@ export function createGame(opts: SetupOptions): GameState {
*/
const rules = houseRules(config);
const deal = OPENING_DEALS[rules.startingHand];
const deck = buildDeck(config.mode);
const deck = buildDeck(config.mode, config.pvpCardsAllowed);
const cards = new Map<CardId, Card>();
for (const c of deck) cards.set(c.id, c);
@@ -409,6 +411,7 @@ export function createGame(opts: SetupOptions): GameState {
turns: freshTurns(playerCount, MOVES_PER_LOCAL_OPS),
movedThisPhase: new Set(),
collisionsToday: 0,
collisionsTotal: 0,
status: 'active',
outcome: null,
};
src/engine/state.ts
+43 -10
View File
@@ -12,7 +12,6 @@ import type {
Hand,
MainlineKind,
FreightKind,
GameLength,
HouseRuleOverrides,
ModifierKind,
OfficeTier,
@@ -326,6 +325,12 @@ export type CrewTray = {
*
* The engine is NOT one of the `consist` entries: §8.2 counts the consist as Rolling Stock, and
* the four-car limit (§A.4) is a limit on cars, not on the locomotive hauling them.
*
* This only records POSITION, not a supply — and that is not a gap. `rules-v0.2.md`:339 (Gap 4b)
* ties Crew Trays and engine pieces together as one combined resource, `player count + 3`
* (`crewTrayCount` in `content.ts`), so engine scarcity IS tray scarcity: `freeTrays` running out
* already blocks a new train exactly when the engine supply would. There is no state for "a tray
* with no engine" because the rules never separate the two.
*/
engineAt: number;
/**
@@ -540,12 +545,42 @@ export type Player = {
};
export type GameMode = 'solitaire' | 'competitive' | 'coop';
export type VictoryCondition = 'firstToTarget' | 'highestAfterDays';
/**
* VICTORY CONDITIONS — designed 2026-08-20, unified across all three modes.
*
* Replaces the old `length`-preset lookup (`LENGTH_PROFILES.target`) and the dead
* `VictoryCondition: 'firstToTarget'` (grepped: never selected anywhere in the codebase). Winner is
* whoever has the most Revenue when `days` run out — solitaire's own player counts as "everyone" —
* unless `minCombinedRevenue` was missed, in which case everyone loses. Coop keeps summing every
* player's Revenue into one table score, now against a configurable floor instead of
* `profile.target * players.length`.
*
* `0` means "off" for every numeric field below. `minCombinedRevenue`'s natural default is
* `collectiveRevenueFloor(players, days)` (`content.ts`), computed by whoever authors the config —
* the engine only ever reads a concrete number here, never resolves one lazily, because player count
* is not always known at config-authoring time (a lobby, a CLI flag, a dialog).
*
* `maxCollisionsPerDay`/`maxCollisionsTotal` are deliberately FLAT, not scaled by player count: more
* players means more independent chances to collide, not a bigger shared budget, so a multiplayer
* table is genuinely riskier than solitaire at the same default (Jesse's call).
*/
export type GameConfig = {
mode: GameMode;
victory: VictoryCondition;
length: GameLength;
/** How many Days the game runs. */
days: number;
/** Everyone loses if the table's total Revenue is below this when `days` run out. 0 = off. */
minCombinedRevenue: number;
/** Everyone loses immediately, mid-game, once collisions in one Day reach this. 0 = off. */
maxCollisionsPerDay: number;
/** Same, summed across the whole game, never reset. 0 = off. */
maxCollisionsTotal: number;
/**
* Whether the 22 opponent-directed cards are in the deck (`setup.ts`'s `buildDeck`). Forced off in
* `solitaire` and `coop` — neither has a valid target for them — on by default in `competitive`.
* Has no effect until those cards are built (Phase 5); see `TODO.md`.
*/
pvpCardsAllowed: boolean;
optionalRules: {
reducedVisibility: boolean;
sisterTrains: boolean;
@@ -562,11 +597,7 @@ export type GameConfig = {
houseRules?: HouseRuleOverrides;
};
export type OutcomeReason =
| 'targetReached'
| 'daysElapsed'
| 'collisionFloor'
| 'revenueFloor';
export type OutcomeReason = 'daysElapsed' | 'collisionFloor' | 'revenueFloor';
export type Outcome = {
result: 'win' | 'loss';
@@ -742,8 +773,10 @@ export type GameState = {
turns: Map<PlayerIndex, TurnState>;
/** Transient: trains already moved in the current Mainline Phase. Cleared when it ends. */
movedThisPhase: Set<TrayId>;
/** §3.4 — resets at the start of each Day. */
/** §3.4 — resets at the start of each Day; checked against `config.maxCollisionsPerDay`. */
collisionsToday: number;
/** §3.4 — never reset; checked against `config.maxCollisionsTotal`. */
collisionsTotal: number;
status: 'setup' | 'active' | 'finished';
outcome: Outcome | null;
};
src/engine/track.ts
+10 -3
View File
@@ -667,12 +667,19 @@ export function canPlaceAt(area: OfficeArea, coord: GridCoord, card: TrackCard):
}
/**
* §A.4 — the Office track is Operational Rail, but Rolling Stock may not be left there.
* §A.4 — the Office track is Operational Rail, but Rolling Stock may not be left there — WITH ONE
* EXCEPTION (Jesse's call, v0.5.0): any train may set out one or more coaches at the Office. It is
* the one car type a passenger platform is meant to hold, and it is what makes the ENGINE-boxcar-
* coach Local arrangement workable — the coach drops here while the engine and freight car switch
* freely. Freight and cabooses stay banned at the Office for every train, no exception.
*
* An industry track also has a finite length (§9.3), so it can be full.
*/
export function canDropCarsAt(area: OfficeArea, coord: GridCoord, count = 1): boolean {
if (sameCoord(coord, area.officeCoord)) return false;
export function canDropCarsAt(area: OfficeArea, coord: GridCoord, count = 1, coachesOnly = false): boolean {
const card = cardAt(area, coord);
if (sameCoord(coord, area.officeCoord)) {
return coachesOnly && !!card && isOperationalRail(card) && spaceOn(card) >= count;
}
if (!card || !isOperationalRail(card)) return false;
return spaceOn(card) >= count;
}
src/server/http.ts
+197
View File
@@ -0,0 +1,197 @@
/**
* The HTTP/SSE wiring — Phase 2 of `docs/architecture/multiplayer.md` (§8-9, §12 steps 8 and 12).
*
* Plain `node:http`, no framework: the project has zero runtime dependencies
* (`package.json`), and `scripts/build-web.ts` already shells out to `tsc` directly rather than
* reaching for a bundler — this matches that everywhere-else choice rather than introducing the
* first framework dependency for one route table.
*
* All the game logic lives in `session.ts`; this file is deliberately thin — routing, the join-secret
* gate, SSE mechanics, and static file serving for the built client (`dist/`, D16: the server serves
* the client, which is what makes same-origin work with no CORS).
*/
import { createServer } from 'node:http';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { createReadStream } from 'node:fs';
import { stat } from 'node:fs/promises';
import { extname, join, normalize } from 'node:path';
import type { Intent } from '../engine/intents.ts';
import type { GameConfig, PlayerIndex } from '../engine/state.ts';
import { appendTiming, writeGame } from './persistence.ts';
import { createSession } from './session.ts';
import type { GameSession, Push } from './session.ts';
export type ServerOptions = {
port: number;
bindAddress: string;
/** D14 — a server-wide secret, passed out of band. Gates every `/api/*` route. */
joinSecret: string;
/** The built client (`npm run build:web`'s `dist/`), served at `/` (D16). */
distDir: string;
/** Where `game.json`/`turn-timings.json` live (Phase 3). */
dataDir: string;
/** `package.json`'s version — stamped onto every write, checked on every load (§12 step 15). */
engineVersion: string;
/** Already reconstructed by `index.ts`'s load-on-start, or `null` for a fresh server. */
initialSession: GameSession | null;
};
const MIME: Record<string, string> = {
'.html': 'text/html; charset=utf-8',
'.js': 'text/javascript; charset=utf-8',
'.css': 'text/css; charset=utf-8',
'.json': 'application/json; charset=utf-8',
'.png': 'image/png',
'.svg': 'image/svg+xml',
};
const HEARTBEAT_MS = 20_000;
async function readJson(req: IncomingMessage): Promise<unknown> {
const chunks: Buffer[] = [];
for await (const chunk of req) chunks.push(chunk as Buffer);
const text = Buffer.concat(chunks).toString('utf8');
return text.trim() === '' ? {} : JSON.parse(text);
}
function sendJson(res: ServerResponse, status: number, body: unknown): void {
const text = JSON.stringify(body);
res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(text) });
res.end(text);
}
async function serveStatic(distDir: string, urlPath: string, res: ServerResponse): Promise<void> {
const rel = urlPath === '/' ? '/index.html' : urlPath;
// `normalize` collapses `..`, and the join is then checked to still be inside `distDir` — a request
// for `/../../etc/passwd` must not escape the one directory this is allowed to read from.
const full = join(distDir, normalize(rel));
if (!full.startsWith(distDir)) {
sendJson(res, 400, { error: 'bad path' });
return;
}
try {
const info = await stat(full);
if (!info.isFile()) throw new Error('not a file');
res.writeHead(200, { 'Content-Type': MIME[extname(full)] ?? 'application/octet-stream', 'Content-Length': info.size });
createReadStream(full).pipe(res);
} catch {
res.writeHead(404, { 'Content-Type': 'text/plain' });
res.end('not found');
}
}
export function startServer(opts: ServerOptions): void {
let session: GameSession | null = opts.initialSession;
// One open SSE response per seat — a second connection from the same seat replaces the first
// rather than fanning out to both (Phase 2 has no concept of "the same seat from two tabs").
const connections = new Map<PlayerIndex, ServerResponse>();
const eventIds = new Map<PlayerIndex, number>();
function checkSecret(url: URL, res: ServerResponse): boolean {
if (url.searchParams.get('secret') === opts.joinSecret) return true;
sendJson(res, 403, { error: 'bad or missing secret' });
return false;
}
function writeSse(seat: PlayerIndex, push: Push): void {
const res = connections.get(seat);
if (!res) return; // that seat is not currently connected — Phase 4's reconnect story, not this one
const id = (eventIds.get(seat) ?? 0) + 1;
eventIds.set(seat, id);
res.write(`id: ${id}\ndata: ${JSON.stringify(push)}\n\n`);
}
function broadcast(pushes: Map<PlayerIndex, Push>): void {
for (const [seat, push] of pushes) writeSse(seat, push);
}
const server = createServer((req, res) => {
void (async () => {
const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
if (url.pathname === '/api/game' && req.method === 'POST') {
if (!checkSecret(url, res)) return;
if (session) {
sendJson(res, 409, { error: 'a game already exists on this server' });
return;
}
const body = (await readJson(req)) as { config?: GameConfig; playerNames?: string[]; seed?: number };
if (!body.config || !Array.isArray(body.playerNames) || body.playerNames.length < 1) {
sendJson(res, 400, { error: 'expected { config, playerNames }' });
return;
}
session = createSession(body.seed ?? Math.floor(Math.random() * 1e9), body.config, body.playerNames);
// Persisted immediately, empty history and all — a crash one second after creation should
// still resume as "the game exists, day 1, nobody has moved" rather than vanish entirely.
await writeGame(opts.dataDir, session.exportSave(), opts.engineVersion);
sendJson(res, 200, { ok: true, playerCount: session.playerCount });
return;
}
if (url.pathname === '/api/stream' && req.method === 'GET') {
if (!checkSecret(url, res)) return;
if (!session) {
sendJson(res, 404, { error: 'no game yet' });
return;
}
const seat = Number(url.searchParams.get('seat')) as PlayerIndex;
if (!Number.isInteger(seat) || seat < 0 || seat >= session.playerCount) {
sendJson(res, 400, { error: 'bad or missing ?seat=' });
return;
}
res.writeHead(200, {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
Connection: 'keep-alive',
});
connections.set(seat, res);
writeSse(seat, session.connect(seat));
// Idle for minutes at a time is the expected shape of this game (multiplayer.md §9) — a
// silent SSE connection is exactly what a proxy in the path may reap. A comment line is not a
// real event (EventSource ignores lines starting with `:`), so it costs the client nothing.
const heartbeat = setInterval(() => res.write(': ping\n\n'), HEARTBEAT_MS);
req.on('close', () => {
clearInterval(heartbeat);
if (connections.get(seat) === res) connections.delete(seat);
});
return;
}
if (url.pathname === '/api/intent' && req.method === 'POST') {
if (!checkSecret(url, res)) return;
if (!session) {
sendJson(res, 404, { error: 'no game yet' });
return;
}
const seat = Number(url.searchParams.get('seat')) as PlayerIndex;
if (!Number.isInteger(seat) || seat < 0 || seat >= session.playerCount) {
sendJson(res, 400, { error: 'bad or missing ?seat=' });
return;
}
const body = (await readJson(req)) as { seq?: number; intent?: Intent };
if (typeof body.seq !== 'number' || !body.intent) {
sendJson(res, 400, { error: 'expected { seq, intent }' });
return;
}
const result = session.intent(seat, body.seq, body.intent);
if (result.accepted) {
// Persisted BEFORE the response goes out — "accepted" should mean "durably on disk" at
// this scale, not just "applied in memory" (§12 step 14).
await writeGame(opts.dataDir, session.exportSave(), opts.engineVersion);
if (result.timing) await appendTiming(opts.dataDir, result.timing);
}
sendJson(res, 200, result.accepted ? { ok: true } : { ok: false, code: result.code });
if (result.accepted) broadcast(result.pushes);
return;
}
await serveStatic(opts.distDir, url.pathname, res);
})().catch((err: unknown) => {
sendJson(res, 500, { error: err instanceof Error ? err.message : 'internal error' });
});
});
server.listen(opts.port, opts.bindAddress);
}
src/server/index.ts
+51
View File
@@ -0,0 +1,51 @@
/**
* Process bootstrap — Phase 2 §12 step 8, extended for Phase 3 (§12 steps 14-15) load-on-start.
*
* Run with: node src/server/index.ts
*
* Env-configured, no config file — matches how the rest of this project's dev-side tooling reads
* `process.env` directly (`scripts/build-web.ts`'s `BUILD_DIST_DIR`).
*/
import { readFileSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { startServer } from './http.ts';
import { loadGame } from './persistence.ts';
import { resumeSession } from './session.ts';
import type { GameSession } from './session.ts';
const port = Number(process.env['PORT'] ?? 8081);
const bindAddress = process.env['BIND_ADDRESS'] ?? '0.0.0.0';
const joinSecret = process.env['JOIN_SECRET'];
const distDir = resolve(process.env['DIST_DIR'] ?? 'dist');
const dataDir = resolve(process.env['DATA_DIR'] ?? 'data');
if (!joinSecret) {
console.error('JOIN_SECRET must be set — a server-wide secret, passed out of band (D14).');
process.exit(1);
}
// `package.json`'s version IS `engineVersion` (§12 step 15) — the same reading `scripts/build-web.ts`'s
// `buildStamp()` already does, just from `src/server/` rather than the repo root script directory.
const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
const engineVersion = (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { version: string }).version;
let initialSession: GameSession | null = null;
const loaded = await loadGame(dataDir, engineVersion);
if (loaded.found && loaded.ok) {
initialSession = resumeSession(loaded.saved);
console.log(`Resumed a saved game from ${dataDir} (${loaded.saved.history.length} intents replayed).`);
} else if (loaded.found && !loaded.ok) {
// Refused explicitly (§12 step 15) — never silently replayed under rules it wasn't recorded
// under. The file is left untouched: rolling the running version back would let it load again.
console.error(
`Refusing to load ${dataDir}/game.json: it was saved under engine version ` +
`${loaded.storedVersion}, this server is running ${engineVersion}. Starting with no active ` +
`game. The saved file has not been touched.`,
);
}
startServer({ port, bindAddress, joinSecret, distDir, dataDir, engineVersion, initialSession });
console.log(`Station Master multiplayer server on ${bindAddress}:${port}, serving ${distDir}`);
src/server/persistence.ts
+69
View File
@@ -0,0 +1,69 @@
/**
* Persistence — Phase 3 of `docs/architecture/multiplayer.md` (§12 steps 14-15;
* `lobby-and-sessions.md` §6 specifies the exact shape and reasoning).
*
* One game per process (Phase 2's scope, unchanged) — two files in `DATA_DIR`, no index and no
* `gameId`, both deferred to Phase 4's multi-game generalization same as the server core deferred
* them. Every write is a full-file atomic rewrite (write to `.tmp`, `rename` over the real path)
* rather than true on-disk appending: §6 says the storage mechanism is genuinely open as long as the
* LOGICAL history is never rewritten or reordered, which a full rewrite of an always-growing array
* satisfies — and at the measured scale (~350 intents, a few hundred bytes per game) there is nothing
* to optimize yet.
*/
import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import type { SavedGame, TurnTiming } from './session.ts';
const GAME_FILE = 'game.json';
const TIMINGS_FILE = 'turn-timings.json';
type PersistedGame = SavedGame & { engineVersion: string };
async function atomicWrite(path: string, text: string): Promise<void> {
const tmp = `${path}.tmp`;
await writeFile(tmp, text);
await rename(tmp, path);
}
export async function writeGame(dataDir: string, saved: SavedGame, engineVersion: string): Promise<void> {
await mkdir(dataDir, { recursive: true });
const payload: PersistedGame = { engineVersion, ...saved };
await atomicWrite(join(dataDir, GAME_FILE), JSON.stringify(payload, null, 1));
}
export type LoadResult =
| { found: false }
| { found: true; ok: true; saved: SavedGame }
/** §12 step 15 — refused explicitly, never silently replayed under the wrong rules. */
| { found: true; ok: false; storedVersion: string; currentVersion: string };
export async function loadGame(dataDir: string, currentVersion: string): Promise<LoadResult> {
let text: string;
try {
text = await readFile(join(dataDir, GAME_FILE), 'utf8');
} catch {
return { found: false };
}
const payload = JSON.parse(text) as PersistedGame;
if (payload.engineVersion !== currentVersion) {
return { found: true, ok: false, storedVersion: payload.engineVersion, currentVersion };
}
const { engineVersion: _engineVersion, ...saved } = payload;
return { found: true, ok: true, saved };
}
/** Appended once per closed turn span (`GameSession.intent`'s `timing` result) — read-modify-write at
* this scale rather than real appending, same reasoning as `writeGame`. */
export async function appendTiming(dataDir: string, timing: TurnTiming): Promise<void> {
await mkdir(dataDir, { recursive: true });
const path = join(dataDir, TIMINGS_FILE);
let existing: TurnTiming[];
try {
existing = JSON.parse(await readFile(path, 'utf8')) as TurnTiming[];
} catch {
existing = [];
}
existing.push(timing);
await atomicWrite(path, JSON.stringify(existing, null, 1));
}
src/server/session.ts
+200
View File
@@ -0,0 +1,200 @@
/**
* The game session host — Phases 2 and 3 of `docs/architecture/multiplayer.md` (§8, §12 steps 9,
* 14-16).
*
* Pure logic, no sockets, no filesystem — `src/server/http.ts` is the thin wiring that calls into
* this, and `src/server/persistence.ts` is what actually reads/writes disk. One `GameSession` per
* in-memory game (Phase 2 is one game per process; Phase 4 generalizes to many).
*
* REUSES `src/web/game.ts`'s `Game`/`submit`/`drain`/`currentActor`/`actionMenu` wholesale — all pure
* logic already, with no DOM dependency, exactly as `LocalSession` uses them client-side. Building a
* second copy of "apply an intent, narrate it, compute the Menu" here would drift from what solitaire
* already does and is tested against.
*
* ONE THING `game.ts`'s `submit` DOES NOT DO: verify who is calling it. `submit(game, intent)` reads
* `currentActor(game)` itself and applies the intent AS that player, regardless of who asked — safe
* for `LocalSession` (there is only ever one possible caller: the one browser). A server has more than
* one seat submitting, so THIS file is where "is `seat` actually allowed to act right now?" has to be
* checked, before `submit` is ever called — see `intent()` below.
*/
import { check } from '../engine/apply.ts';
import type { Intent } from '../engine/intents.ts';
import type { GameConfig, PlayerIndex } from '../engine/state.ts';
import { actionMenu, currentActor, fromMultiplayerSave, newMultiplayerGame, submit } from '../web/game.ts';
import type { Game, Menu } from '../web/game.ts';
import { deltaFrame } from '../sim/frame-delta.ts';
import type { FrameDelta } from '../sim/frame-delta.ts';
import { snapshot } from '../sim/view.ts';
import type { Frame } from '../sim/view.ts';
export type Push = {
frame: FrameDelta;
/** Non-null only for the seat that may currently act — never guess otherwise (`game.ts`'s `actionMenu` guards this too, but the host must still only compute/send it for the actor). */
menu: Menu | null;
/** Narration since the LAST push to this specific seat, not the whole game's log. */
lines: { text: string; tone: string }[];
};
/**
* `lobby-and-sessions.md` §5 — "wall-clock at the start of a turn, wall-clock at the intent that
* ends it, per player per phase." Computed entirely here, never touching the engine (which has no
* clock and must stay deterministic) and never stored inside `history` (a replay must reproduce a
* game from decisions alone).
*/
export type TurnTiming = {
player: PlayerIndex;
phase: string;
day: number;
stage: number;
startedAt: number;
endedAt: number;
};
/** Everything `persistence.ts` needs to write `game.json` and rebuild a session from it later. */
export type SavedGame = {
seed: number;
config: GameConfig;
playerNames: string[];
history: Intent[];
status: 'active' | 'finished';
createdAt: number;
};
export type IntentResult =
| { accepted: true; pushes: Map<PlayerIndex, Push>; timing: TurnTiming | null }
| { accepted: false; code: string };
export type GameSession = {
readonly playerCount: number;
/** A new SSE connection (or a reconnect) for `seat` — always a full Frame, never a delta. */
connect(seat: PlayerIndex): Push;
intent(seat: PlayerIndex, seq: number, i: Intent): IntentResult;
/** Everything needed to persist this game and, later, rebuild it via `resumeSession`. */
exportSave(): SavedGame;
};
type OpenSpan = { player: PlayerIndex; phase: string; day: number; stage: number; startedAt: number };
function buildSession(game: Game, playerNames: string[], createdAt: number): GameSession {
const lastSeq = new Map<PlayerIndex, number>();
const lastFrame = new Map<PlayerIndex, Frame>();
const sentLines = new Map<PlayerIndex, number>();
const openSpanFor = (now: number): OpenSpan | null => {
const actor = currentActor(game);
if (actor === null) return null;
return { player: actor, phase: game.state.clock.phase, day: game.state.clock.day, stage: game.state.clock.stage, startedAt: now };
};
let open: OpenSpan | null = openSpanFor(Date.now());
function frameFor(seat: PlayerIndex): Frame {
return snapshot(game.state, game.log, null, null, null, false, seat);
}
function linesSince(seat: PlayerIndex): { text: string; tone: string }[] {
const already = sentLines.get(seat) ?? 0;
sentLines.set(seat, game.log.length);
return game.log.slice(already);
}
function menuFor(seat: PlayerIndex): Menu | null {
return seat === currentActor(game) ? actionMenu(game, seat) : null;
}
function pushFor(seat: PlayerIndex): Push {
const frame = frameFor(seat);
const delta = deltaFrame(lastFrame.get(seat) ?? null, frame);
lastFrame.set(seat, frame);
return { frame: delta, menu: menuFor(seat), lines: linesSince(seat) };
}
function pushesForAll(): Map<PlayerIndex, Push> {
const out = new Map<PlayerIndex, Push>();
for (let seat = 0; seat < playerNames.length; seat++) out.set(seat as PlayerIndex, pushFor(seat as PlayerIndex));
return out;
}
/**
* Closes the open span if the acting player, phase, Day or Stage moved since it opened, and opens
* the next one (or none, in the automatic Mainline Phase). Returns the just-closed span, if any,
* for the caller to persist — a "turn" here is exactly the contiguous stretch where none of those
* four things changed, which can span several intents (draw, then play, then end) as one span.
*/
function settleTiming(): TurnTiming | null {
const now = Date.now();
const next = openSpanFor(now);
const same =
open !== null &&
next !== null &&
open.player === next.player &&
open.phase === next.phase &&
open.day === next.day &&
open.stage === next.stage;
if (same) return null;
const closed: TurnTiming | null = open === null ? null : { ...open, endedAt: now };
open = next;
return closed;
}
return {
playerCount: playerNames.length,
connect(seat) {
// A (re)connect always starts from a clean slate — no cache to trust across a lost connection
// (or a server restart, Phase 3) — so the honest thing is a full Frame, not a delta.
lastFrame.delete(seat);
return pushFor(seat);
},
intent(seat, seq, i) {
// Idempotent resend (protocol.md §5): a repeat of an ALREADY-APPLIED seq is a no-op success,
// with no pushes to re-broadcast. A repeat after a REJECTION is not remembered here — it was
// never applied, so it is worth trying again (see the `lastSeq.set` below: only on success).
if (lastSeq.get(seat) === seq) return { accepted: true, pushes: new Map(), timing: null };
if (seat !== currentActor(game)) return { accepted: false, code: 'NOT_YOUR_TURN' };
// Checked directly, rather than via `submit`'s boolean, for two reasons: `submit` writes a
// "that is not allowed" line into the SHARED `game.log` on rejection, which would otherwise
// broadcast one seat's illegal attempt to the whole table on their next push (rejection
// feedback is private, to the submitter only); and calling `check` first means an intent
// already known to be illegal never touches the engine at all.
const code = check(game.state, seat, i);
if (code) return { accepted: false, code };
const applied = submit(game, i);
/* c8 ignore next -- `check` above already proved this intent is legal; `submit` cannot then refuse it. */
if (!applied) return { accepted: false, code: 'REJECTED' };
lastSeq.set(seat, seq);
const timing = settleTiming();
return { accepted: true, pushes: pushesForAll(), timing };
},
exportSave() {
return {
seed: game.seed,
config: game.state.config,
playerNames: [...playerNames],
history: [...game.history],
status: game.state.status === 'finished' ? 'finished' : 'active',
createdAt,
};
},
};
}
export function createSession(seed: number, config: GameConfig, playerNames: string[]): GameSession {
return buildSession(newMultiplayerGame(seed, config, playerNames), playerNames, Date.now());
}
/**
* Phase 3 — rebuild a session from a persisted `SavedGame` (`persistence.ts`). The engine-version
* check happens before this is ever called; by the time `saved.history` reaches here it is already
* known to have been recorded under the currently-running rules.
*/
export function resumeSession(saved: SavedGame): GameSession {
const game = fromMultiplayerSave(saved.seed, saved.config, saved.playerNames, saved.history);
return buildSession(game, saved.playerNames, saved.createdAt);
}
src/sim/board-svg.ts
+70 -7
View File
@@ -474,6 +474,65 @@ export function officeSvg(
return out;
};
/**
* A 45° LEG, drawn as a smooth curve rather than two straight segments meeting at a hard corner.
*
* It is an EASEMENT, not an arbitrary curve: tangent to horizontal at `p0` (the east or west edge),
* so an abutting straight card's through-rail still reads as one unbroken line, and tangent to
* exactly 45° at `p3` (the north or south edge), so two stacked curves still read as one continuous
* diagonal and the edge-crossing angle the matching rule depends on is unchanged. `p1`/`p2` are
* cubic-Bezier control points chosen to hit those two tangents — see the call site.
*
* Sampled as a short polyline rather than left as one SVG path command, because the two parallel
* rails and the tie marks all need points evenly spaced ALONG THE CURVE with the local tangent at
* each one — `rail()`'s straight-line version does the same sampling, just on a line.
*/
const curvedRail = (
p0: { x: number; y: number },
p1: { x: number; y: number },
p2: { x: number; y: number },
p3: { x: number; y: number },
): string => {
const at = (t: number): { x: number; y: number } => {
const u = 1 - t;
return {
x: u * u * u * p0.x + 3 * u * u * t * p1.x + 3 * u * t * t * p2.x + t * t * t * p3.x,
y: u * u * u * p0.y + 3 * u * u * t * p1.y + 3 * u * t * t * p2.y + t * t * t * p3.y,
};
};
const tangentAt = (t: number): { x: number; y: number } => {
const u = 1 - t;
return {
x: 3 * u * u * (p1.x - p0.x) + 6 * u * t * (p2.x - p1.x) + 3 * t * t * (p3.x - p2.x),
y: 3 * u * u * (p1.y - p0.y) + 6 * u * t * (p2.y - p1.y) + 3 * t * t * (p3.y - p2.y),
};
};
const N = 24;
const left: string[] = [];
const right: string[] = [];
let ties = '';
for (let i = 0; i <= N; i++) {
const t = i / N;
const pt = at(t);
const tan = tangentAt(t);
const tlen = Math.hypot(tan.x, tan.y) || 1;
const nx = (-tan.y / tlen) * 2.5;
const ny = (tan.x / tlen) * 2.5;
left.push(`${pt.x + nx} ${pt.y + ny}`);
right.push(`${pt.x - nx} ${pt.y - ny}`);
// Every third sample — the same rough 9px spacing `rail()` uses for a straight run of similar
// length, not tied to `N` itself.
if (i % 3 === 0) {
ties += `<line class="bs-tie" x1="${pt.x + nx * 1.8}" y1="${pt.y + ny * 1.8}" x2="${pt.x - nx * 1.8}" y2="${pt.y - ny * 1.8}"/>`;
}
}
return (
`<path class="bs-rail" fill="none" d="M${left.join(' L')}"/>` +
`<path class="bs-rail" fill="none" d="M${right.join(' L')}"/>` +
ties
);
};
// Where each port meets the card edge. East and west sit at the rail height — the card's middle —
// so a straight run stays straight across the whole row; north and south are centred on the edge.
const port = (p: string): { x: number; y: number } => {
@@ -534,19 +593,23 @@ export function officeSvg(
out += rail(port(from).x, port(from).y, port(to).x, port(to).y);
} else {
/**
* A 45° LEG, drawn as the card prints it: along the centre line from the east or west edge
* to the FROG, then out at exactly 45° through the middle of the north or south edge.
* A 45° LEG — drawn as a smooth curve (v0.5.0) that still passes through the same FROG the
* old two-segment version bent at, so the underlying geometry (and the `frog` position used
* elsewhere for the actual joining/matching rules) is unchanged; only the picture is.
*
* The frog is `H/2` from the centre because a 45° run climbing half the card's height
* travels half its height sideways. This used to be a fixed elbow at (W/2, RAIL+(H-RAIL)/2)
* — below the rail on the assumption everything diverged downward — which drew a leg
* reaching north as a hook that dropped past the rail and came back up, and drew nothing at
* any angle the matching rule cares about.
* travels half its height sideways. The control points sit halfway from each endpoint to the
* frog, which is what gives the curve a horizontal tangent at the e/w edge (matching an
* abutting straight card's through-rail) and an exact 45° tangent at the n/s edge (matching
* the card above or below) — see `curvedRail`.
*/
const side = vertical === from ? to : from;
const frog = { x: W / 2 + (side === 'e' ? H / 2 : -H / 2), y: RAIL };
const start = port(side);
const edge = port(vertical);
out += rail(port(side).x, port(side).y, frog.x, frog.y) + rail(frog.x, frog.y, edge.x, edge.y);
const c1 = { x: start.x + 0.5 * (frog.x - start.x), y: start.y };
const c2 = { x: edge.x + 0.5 * (frog.x - edge.x), y: edge.y + 0.5 * (frog.y - edge.y) };
out += curvedRail(start, c1, c2, edge);
}
}
src/sim/compare.ts
+17 -4
View File
@@ -31,6 +31,12 @@
import { pump } from '../engine/advance.ts';
import { createGame } from '../engine/setup.ts';
import {
DEFAULT_MAX_COLLISIONS_PER_DAY,
DEFAULT_MAX_COLLISIONS_TOTAL,
collectiveRevenueFloor,
lengthProfile,
} from '../engine/content.ts';
import type { GameLength } from '../engine/content.ts';
import type { GameConfig, GameMode } from '../engine/state.ts';
import type { BotPolicy, BotTweaks } from './bot.ts';
@@ -56,17 +62,24 @@ export type PairedResult = {
variantStats: GameStats[];
};
const SOLO = (length: GameLength, mode: GameMode): GameConfig => ({
// Always one bot (`runOne` below), so the revenue floor is `collectiveRevenueFloor(1, days)`.
const SOLO = (length: GameLength, mode: GameMode): GameConfig => {
const days = lengthProfile(length).days;
return {
mode,
victory: 'highestAfterDays',
length,
days,
minCombinedRevenue: collectiveRevenueFloor(1, days),
maxCollisionsPerDay: DEFAULT_MAX_COLLISIONS_PER_DAY,
maxCollisionsTotal: DEFAULT_MAX_COLLISIONS_TOTAL,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
employeeRotation: false,
emergencyToolbox: false,
},
});
};
};
/**
* One game, one seed, one policy.
src/sim/frame-delta.ts
+53
View File
@@ -0,0 +1,53 @@
/**
* Live per-seat Frame delta — Phase 2 of `docs/architecture/multiplayer.md`.
*
* `src/sim/replay.ts`'s `compress()` looked like the thing to reuse here (D2/D3's "2.9 KB per push
* with the board omitted when unchanged" cites it) but it solves a different problem: it interns
* card/description strings across a WHOLE recorded array of frames, which only pays off when
* bundling many frames into one replay file. A live server pushes one frame at a time and has
* nothing to intern against. The part that genuinely carries over is much smaller — a one-step-back
* "null if unchanged since the last thing sent to THIS seat" check on the three fields that make up
* almost all of a Frame's size: `cells`, `facilities`, `division` (`replay.ts`'s own `keys` array).
*
* Node-free by design, unlike `replay.ts` (which imports `node:fs`) — both the server and a browser
* `RemoteSession` import this file directly.
*/
import type { CellView, DivisionView, FacilityView, Frame } from './view.ts';
/** A `Frame` with the three board-shaped fields replaced by `null` where unchanged since `previous`. */
export type FrameDelta = Omit<Frame, 'cells' | 'facilities' | 'division'> & {
cells: CellView[] | null;
facilities: FacilityView[] | null;
division: DivisionView[] | null;
};
const BOARD_KEYS = ['cells', 'facilities', 'division'] as const;
/**
* `previous` is the last Frame actually sent to THIS seat, or `null` for a first connect / a
* reconnect after a gap — Phase 2 has no persistence to replay a gap against (Phase 3), so a
* reconnect always gets a full Frame here rather than a delta.
*/
export function deltaFrame(previous: Frame | null, next: Frame): FrameDelta {
const out = { ...next } as unknown as FrameDelta;
for (const key of BOARD_KEYS) {
const unchanged = previous !== null && JSON.stringify(previous[key]) === JSON.stringify(next[key]);
(out as Record<string, unknown>)[key] = unchanged ? null : next[key];
}
return out;
}
/** The receiving side: merges a delta back onto the last full Frame this seat actually has. */
export function applyDelta(previous: Frame | null, delta: FrameDelta): Frame {
const out = { ...delta } as unknown as Frame;
for (const key of BOARD_KEYS) {
if (delta[key] === null) {
if (previous === null) {
throw new Error(`deltaFrame said "${key}" is unchanged, but there is no previous Frame to merge onto`);
}
(out as Record<string, unknown>)[key] = previous[key];
}
}
return out;
}
src/sim/harness.ts
+15 -6
View File
@@ -12,7 +12,12 @@
*/
import { pump } from '../engine/advance.ts';
import { collectiveRevenueFloor, lengthProfile } from '../engine/content.ts';
import {
DEFAULT_MAX_COLLISIONS_PER_DAY,
DEFAULT_MAX_COLLISIONS_TOTAL,
collectiveRevenueFloor,
lengthProfile,
} from '../engine/content.ts';
import { createGame } from '../engine/setup.ts';
import type { GameLength } from '../engine/content.ts';
import type { GameConfig, GameMode } from '../engine/state.ts';
@@ -60,11 +65,15 @@ function statsOf(xs: number[]): Stats {
};
}
function configFor(mode: GameMode, length: GameLength): GameConfig {
function configFor(mode: GameMode, length: GameLength, players: number): GameConfig {
const days = lengthProfile(length).days;
return {
mode,
victory: 'highestAfterDays',
length,
days,
minCombinedRevenue: collectiveRevenueFloor(players, days),
maxCollisionsPerDay: DEFAULT_MAX_COLLISIONS_PER_DAY,
maxCollisionsTotal: DEFAULT_MAX_COLLISIONS_TOTAL,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
@@ -83,7 +92,7 @@ export function simulate(opts: SimOptions): SimReport {
const s = createGame({
id: `sim-${i}`,
seed,
config: configFor(opts.mode, opts.length),
config: configFor(opts.mode, opts.length, opts.players.length),
playerNames: opts.players,
});
// The probe watches the game as it is played: the funnel gates are conditions at a moment, not
@@ -154,7 +163,7 @@ export function formatReport(r: SimReport, length: GameLength, players: number):
// The provisional numbers this exists to test.
out.push('\n against the provisional targets:');
out.push(` target ${profile.target} over ${profile.days} Days`);
out.push(` ${profile.days} Days`);
out.push(
` predicted ~5-6 revenue/player/Day steady state; observed mean ` +
`${r.revenuePerPlayerPerDay.mean.toFixed(1)}`,
src/sim/replay.ts
+16 -5
View File
@@ -21,7 +21,14 @@ import { writeFileSync } from 'node:fs';
import { advance } from '../engine/advance.ts';
import { applyIntent, areaOf, facilityCarType, laborersLeft, portersLeft } from '../engine/apply.ts';
import type { GameLength } from '../engine/content.ts';
import { MAINLINE_PROFILES, lengthProfile, officeProfile } from '../engine/content.ts';
import {
DEFAULT_MAX_COLLISIONS_PER_DAY,
DEFAULT_MAX_COLLISIONS_TOTAL,
MAINLINE_PROFILES,
collectiveRevenueFloor,
lengthProfile,
officeProfile,
} from '../engine/content.ts';
import type { GameEvent } from '../engine/events.ts';
import type { Intent } from '../engine/intents.ts';
import { legalActions } from '../engine/legal.ts';
@@ -51,10 +58,14 @@ import { playCue } from '../web/sound.ts';
export type Recording = { seed: number; length: GameLength; frames: Frame[]; outcome: string };
export function record(seed: number, length: GameLength, maxSteps = 100_000): Recording {
const days = lengthProfile(length).days;
const config: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length,
days,
minCombinedRevenue: collectiveRevenueFloor(1, days),
maxCollisionsPerDay: DEFAULT_MAX_COLLISIONS_PER_DAY,
maxCollisionsTotal: DEFAULT_MAX_COLLISIONS_TOTAL,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
@@ -263,7 +274,7 @@ export function rehydrateCells(
}
export function renderHtml(rec: Recording): string {
const target = lengthProfile(rec.length);
const profile = lengthProfile(rec.length);
return `<!doctype html>
<html lang="en"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
@@ -360,7 +371,7 @@ kbd{background:#2a3038;border:1px solid var(--line);border-radius:3px;padding:0
</style></head><body>
<header>
<h1>Station Master — replay · seed ${rec.seed} · ${rec.length} (target ${target.target} over ${target.days} Days) · ${esc(rec.outcome)}</h1>
<h1>Station Master — replay · seed ${rec.seed} · ${rec.length} (${profile.days} Days) · ${esc(rec.outcome)}</h1>
<div class="bar">
<span class="dim">fedora <span id="super">—</span></span>
<span>revenue <b class="big" id="rev">0</b></span>
src/sim/view.ts
+50 -8
View File
@@ -24,6 +24,7 @@ import {
import {
ACTION_CARDS,
ENHANCEMENT_CARDS,
HAND_LIMIT,
MAINLINE_MODIFIER_CARDS,
MAINLINE_PROFILES,
MANEUVER_CARDS,
@@ -37,7 +38,6 @@ import {
industryProfile,
mainlineProfile,
modifierProfile,
lengthProfile,
officeProfile,
trainProfile,
houseRules,
@@ -348,6 +348,18 @@ export type Frame = {
* must be able to answer. Resolved, never partial, so nobody downstream re-applies defaults.
*/
houseRules: HouseRules;
/**
* The victory-condition dials this game was configured with (`GameConfig`, `state.ts`), plus the
* running collision counts — same reasoning as `houseRules`: a remote client holds no `GameState`
* and needs to show live progress ("2 of 3 collisions today") without guessing a default. `0` on
* any `max*`/`minCombinedRevenue` field means that check is off.
*/
days: number;
minCombinedRevenue: number;
maxCollisionsPerDay: number;
maxCollisionsTotal: number;
collisionsToday: number;
collisionsTotal: number;
status: GameState['status'];
outcome: GameState['outcome'];
/**
@@ -360,6 +372,13 @@ export type Frame = {
players: { index: number; seat: number; name: string; revenue: number; hand: number }[];
/** How many cards the VIEWER holds. Other players' counts are in `players`. */
handCount: number;
/**
* True when the VIEWER's hand is over §6.2's limit and their turn cannot end until it is played
* down. Duplicates `game.ts`'s `overHandLimit(game, seat)` at the engine-data level rather than
* importing the web layer here — a `RemoteSession` (Phase 2) has no `GameState` to compute this
* from, only a `Frame`, so it has to already be resolved on the wire.
*/
overHandLimit: boolean;
lines: { text: string; tone: string }[];
where: { row: number; col: number } | null;
/** Origin of a Move, so the crew's journey is visible rather than a chip teleporting. */
@@ -1207,6 +1226,12 @@ export function snapshot(
wasted,
option: turnOf(s, viewer).option,
houseRules: houseRules(s.config),
days: s.config.days,
minCombinedRevenue: s.config.minCombinedRevenue,
maxCollisionsPerDay: s.config.maxCollisionsPerDay,
maxCollisionsTotal: s.config.maxCollisionsTotal,
collisionsToday: s.collisionsToday,
collisionsTotal: s.collisionsTotal,
status: s.status,
outcome: s.outcome,
players: s.players.map((p) => ({
@@ -1217,6 +1242,8 @@ export function snapshot(
hand: (s.decks.hands.get(p.index) ?? []).length,
})),
handCount: (s.decks.hands.get(viewer) ?? []).length,
overHandLimit:
(s.decks.hands.get(viewer) ?? []).length > (s.decks.redFlags.get(viewer) ? HAND_LIMIT + 1 : HAND_LIMIT),
objective: objectiveOf(s, viewer),
runningRow: area.runningRow,
limits: { west: area.limitsWest.col, east: area.limitsEast.col },
@@ -1633,21 +1660,36 @@ const SIMPLE_CARDS = [
...ACTION_CARDS,
];
/** The goal, and whether the VIEWER's score is keeping up with the clock. */
/**
* The goal, and whether the VIEWER's score is keeping up with the clock.
*
* `target` is `config.minCombinedRevenue` now (2026-08-20) — the floor below which everyone loses,
* not a per-player win threshold; `days` and `daysLeft` come off `config.days`. Paced against the
* VIEWER's own Revenue, same as before: exact for solitaire (the viewer IS the whole table), an
* approximation for competitive/coop until Phase 2 gives the objective panel a combined-progress
* view of its own. `0` means no floor is configured — nothing to pace against.
*/
function objectiveOf(s: GameState, viewer: PlayerIndex): Frame['objective'] {
const profile = lengthProfile(s.config.length);
const { days, minCombinedRevenue: target } = s.config;
const revenue = s.players[viewer]?.revenue ?? 0;
const daysLeft = Math.max(0, profile.days - s.clock.day + 1);
const elapsed = profile.days - daysLeft + 1;
const daysLeft = Math.max(0, days - s.clock.day + 1);
const elapsed = days - daysLeft + 1;
if (target <= 0) {
const note =
daysLeft === 0
? 'the last Day is over'
: `${revenue} · ${daysLeft} Day${daysLeft === 1 ? '' : 's'} left · no minimum this game`;
return { target: 0, days, daysLeft, onPace: true, note };
}
// Straight-line pace: by the end of Day N you want N/days of the target.
const expected = (profile.target * elapsed) / profile.days;
const expected = (target * elapsed) / days;
const onPace = revenue >= expected;
const note =
daysLeft === 0
? 'the last Day is over'
: `${revenue} of ${profile.target} · ${daysLeft} Day${daysLeft === 1 ? '' : 's'} left · ` +
: `${revenue} of ${target} · ${daysLeft} Day${daysLeft === 1 ? '' : 's'} left · ` +
(onPace ? 'on pace' : `behind pace (about ${Math.ceil(expected)} by now)`);
return { target: profile.target, days: profile.days, daysLeft, onPace, note };
return { target, days, daysLeft, onPace, note };
}
/**
src/web/game.ts
+102 -5
View File
@@ -44,9 +44,13 @@ import {
variantLabel,
} from '../sim/view.ts';
import {
DEFAULT_DAYS,
DEFAULT_HOUSE_RULES,
DEFAULT_MAX_COLLISIONS_PER_DAY,
DEFAULT_MAX_COLLISIONS_TOTAL,
HAND_LIMIT,
LEGACY_HOUSE_RULES,
collectiveRevenueFloor,
houseRules,
mainlineProfile,
trainProfile,
@@ -57,10 +61,19 @@ import { connectionsFor, joins, neighbour, variantsFor } from '../engine/track.t
import { areaOf, destinationsFor, selectDestination, trainNeedingCars } from '../engine/apply.ts';
import type { Frame } from '../sim/view.ts';
/**
* The canonical "what does a fresh solitaire game look like" config — also what the New Game
* dialog's solitaire defaults are drawn from (`main.ts`). One player, so `minCombinedRevenue` uses
* `collectiveRevenueFloor(1, DEFAULT_DAYS)` — the same formula multiplayer configs use, just at
* player count 1.
*/
export const SOLO_CONFIG: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'standard',
days: DEFAULT_DAYS,
minCombinedRevenue: collectiveRevenueFloor(1, DEFAULT_DAYS),
maxCollisionsPerDay: DEFAULT_MAX_COLLISIONS_PER_DAY,
maxCollisionsTotal: DEFAULT_MAX_COLLISIONS_TOTAL,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
@@ -72,9 +85,29 @@ export const SOLO_CONFIG: GameConfig = {
houseRules: DEFAULT_HOUSE_RULES,
};
/**
* Everything the New Game dialog can set for a solitaire game — the opening deal and the three
* revenue rates (`houseRules`, unchanged), plus the four victory-condition dials added 2026-08-20.
* Solitaire's `pvpCardsAllowed` is not here: it is forced off (`SOLO_CONFIG`), never a player choice.
*/
export type NewGameOptions = {
houseRules?: HouseRuleOverrides;
days?: number;
minCombinedRevenue?: number;
maxCollisionsPerDay?: number;
maxCollisionsTotal?: number;
};
/** The same config with the New Game dialog's answers in it. */
export function configWith(rules: HouseRuleOverrides): GameConfig {
return { ...SOLO_CONFIG, houseRules: houseRules({ houseRules: rules }) };
export function configWith(opts: NewGameOptions): GameConfig {
return {
...SOLO_CONFIG,
days: opts.days ?? SOLO_CONFIG.days,
minCombinedRevenue: opts.minCombinedRevenue ?? SOLO_CONFIG.minCombinedRevenue,
maxCollisionsPerDay: opts.maxCollisionsPerDay ?? SOLO_CONFIG.maxCollisionsPerDay,
maxCollisionsTotal: opts.maxCollisionsTotal ?? SOLO_CONFIG.maxCollisionsTotal,
houseRules: houseRules(opts.houseRules ? { houseRules: opts.houseRules } : {}),
};
}
/** A group of legal actions of one kind, ready to put on screen. */
@@ -237,6 +270,23 @@ export function newGame(seed: number, config: GameConfig = SOLO_CONFIG): Game {
return game;
}
/**
* `newGame`'s multi-player sibling — the server session host (Phase 2) needs a `Game` wrapper for
* more than one seat, and `newGame` hardcodes `[SOLO_PLAYER]`. Kept as a separate function rather
* than a shared parametrized helper: `newGame` is exercised by every solitaire test and save, and
* reordering its log-then-drain sequence to share code with this risks nothing for a marginal DRY
* gain. `submit`/`drain`/`actionMenu`/`currentActor` all work on either unchanged, since none of them
* know or care how many players a `Game` has.
*/
export function newMultiplayerGame(seed: number, config: GameConfig, playerNames: string[]): Game {
const state = createGame({ id: `mp-${seed}`, seed, config, playerNames });
const game: Game = { state, seed, history: [], log: [], mustPlayCard: false, cues: [], scheduled: null, justDrawn: null, announced: null };
game.log.push({ text: 'Game Begins', tone: 'start' });
game.log.push({ text: `${config.mode} · ${playerNames.length} players · seed ${seed}`, tone: 'quiet' });
drain(game);
return game;
}
/**
* Run the engine forward until it needs a decision.
*
@@ -530,7 +580,16 @@ export type Menu = {
/** The action list as the page shows it: direct actions, plus subject-then-location for the rest. */
export function actionMenu(game: Game, seat: PlayerIndex = 0): Menu {
const { options, groups } = actionGroups(game);
/**
* SEAT-SAFETY. `actionGroups`/`legalActions` answer for `currentActor(game)`, not for `seat` — there
* is exactly one acting player at a time, so a Menu built for anyone else must show no actions at
* all, only their own hand (found the hard way: calling this for a non-acting seat used to hand
* back the ACTOR's legal moves paired with the WRONG seat's cards). Emptying `options`/`groups` here
* degrades every downstream computation (`direct`, `placeable`, `makeUp`) to empty for free — the
* hand section below still reads `seat`'s own cards correctly either way.
*/
const isActor = seat === currentActor(game);
const { options, groups } = isActor ? actionGroups(game) : { options: [] as Intent[], groups: [] as ActionGroup[] };
const direct: ActionGroup[] = [];
const placeableByTitle = new Map<string, Map<string, Placeable>>();
@@ -1079,3 +1138,41 @@ export function fromSave(save: Save, config: GameConfig = SOLO_CONFIG): Game {
}
return game;
}
/**
* `fromSave`'s multi-player sibling — Phase 3 (`docs/architecture/multiplayer.md`): "a mid-game
* server restart is a replay rather than a recovery" (`lobby-and-sessions.md` §6). Built on
* `newMultiplayerGame` instead of `newGame` since a saved multiplayer game did not deal to
* `[SOLO_PLAYER]`. The engine-version check belongs to the caller (`src/server/persistence.ts`) —
* this function only ever reconstructs from history that is already known to have been recorded
* under the currently-running rules.
*
* UNLIKE `fromSave`'s loop, this passes `actor` to `record()` (matching `submit`'s own call,
* `game.ts` above) — found while testing Phase 3's resume path: without it, every replayed line loses
* its "Player X" attribution and reads as anonymous "Chose to..." narration, which `record`'s own
* comment calls "unreadable the moment there is more than one seat" — exactly the multiplayer case a
* resumed game hits every time. `fromSave` has the same gap (it predates multiplayer and nothing ever
* compares its output against a LIVE-played log, so it has gone unnoticed — `undo`'s rebuilt game is
* itself `fromSave`-built, so `test/web.test.ts`'s replay-fidelity test only ever compares one
* unattributed replay against another). Flagged in `TODO.md` rather than fixed there in this pass —
* out of scope for Phase 3 and used far more widely, so worth its own careful look rather than a
* touch-in-passing.
*/
export function fromMultiplayerSave(
seed: number,
config: GameConfig,
playerNames: string[],
history: Intent[],
): Game {
const game = newMultiplayerGame(seed, config, playerNames);
for (const intent of history) {
const actor = currentActor(game);
if (actor === null) break;
const result = applyIntent(game.state, actor, intent);
if (!result.ok) break;
game.history.push(intent);
record(game, result.events, actor);
drain(game);
}
return game;
}
src/web/main.ts
+263 -37
View File
@@ -12,21 +12,89 @@ import type { Menu, Save } from './game.ts';
import { PANEL_CSS, blockedHtml, facilitiesHtml, pilesHtml, timetableHtml, yardHtml } from './panels.ts';
import { TOOLTIP_CSS, installTooltips } from './tooltip.ts';
import { playCue } from './sound.ts';
import { MOVES_PER_LOCAL_OPS, STARTING_HAND_LABELS, houseRules } from '../engine/content.ts';
import {
DEFAULT_MAX_COLLISIONS_PER_DAY,
DEFAULT_MAX_COLLISIONS_TOTAL,
MOVES_PER_LOCAL_OPS,
STARTING_HAND_LABELS,
collectiveRevenueFloor,
houseRules,
} from '../engine/content.ts';
import type { HouseRuleOverrides, HouseRules, RevenueRules, StartingHand } from '../engine/content.ts';
import type { LocalSession } from './session.ts';
import { createLocalSession } from './session.ts';
import type { NewGameOptions } from './game.ts';
import type { LocalSession, Session } from './session.ts';
import { createLocalSession, createRemoteSession } from './session.ts';
import type { PlayerIndex } from '../engine/state.ts';
const SAVE_KEY = 'station-master.save.v1';
const SETTINGS_KEY = 'station-master.settings.v1';
/** Preset board zoom levels — a fraction applied to the rendered SVG's own pixel dimensions. */
const ZOOM_LEVELS = [0.75, 1, 1.25, 1.5] as const;
/**
* The game, behind the Session boundary.
*
* Typed as `LocalSession` because this page is the solitaire client and uses undo, local saves and
* new-game — all of which are local-only. The parts that draw and submit go through the plain
* `Session` surface, which is what a remote client will provide unchanged.
* Small persisted preferences, kept in a `localStorage` key of their own — separate from
* `SAVE_KEY`. A save is the seed plus the intents and has to stay portable; none of this belongs
* in it, and in a multiplayer game two players may reasonably want these set differently. Grows as
* more of the page's display state earns a preference; `districtMode`/`soundOn`/`zoom` are the
* first three.
*/
let session: LocalSession;
type Settings = {
districtMode: 'auto' | 'open' | 'closed';
soundOn: boolean;
zoom: number;
};
const DEFAULT_SETTINGS: Settings = { districtMode: 'auto', soundOn: false, zoom: 1 };
function loadSettings(): Settings {
try {
const raw = localStorage.getItem(SETTINGS_KEY);
const parsed = raw ? (JSON.parse(raw) as Partial<Settings>) : {};
// A missing key, a corrupt value, or a level dropped from `ZOOM_LEVELS` since it was saved all
// fall back to the default for that one field, rather than rejecting the whole object.
return {
districtMode:
parsed.districtMode === 'open' || parsed.districtMode === 'closed' ? parsed.districtMode : 'auto',
soundOn: typeof parsed.soundOn === 'boolean' ? parsed.soundOn : DEFAULT_SETTINGS.soundOn,
zoom:
typeof parsed.zoom === 'number' && (ZOOM_LEVELS as readonly number[]).includes(parsed.zoom)
? parsed.zoom
: DEFAULT_SETTINGS.zoom,
};
} catch {
// A full or disabled localStorage must not take the game down with it — same guard as the save.
return { ...DEFAULT_SETTINGS };
}
}
let settings = loadSettings();
function saveSettings(patch: Partial<Settings>): void {
settings = { ...settings, ...patch };
try {
localStorage.setItem(SETTINGS_KEY, JSON.stringify(settings));
} catch {
/* nothing to do */
}
}
/**
* The game, behind the Session boundary — `LocalSession` (solitaire, `?seat=` absent from the URL)
* or `RemoteSession` (`?seat=` present, Phase 2). Typed as the common `Session` surface; every
* LocalSession-only touch (undo, local saves, dealing a new game) goes through `isLocal` below rather
* than assuming, since `session` may now be either.
*/
let session: Session;
/**
* The three `Capabilities` (`undo`/`saveLocal`/`newGame`) travel together — all `true` for a
* `LocalSession`, all `false` for a `RemoteSession` (`session.ts`) — so any one of them is a safe
* discriminant. `newGame` is used here since it reads clearly at every call site: "only if this
* session can deal locally."
*/
function isLocal(s: Session): s is LocalSession {
return s.capabilities.newGame;
}
/** Which card or track piece is picked, waiting for a location. */
let selected: string | null = null;
/**
@@ -49,18 +117,20 @@ let pendingAt: string | null = null;
*
* 'auto' follows the phase; 'open' and 'closed' are the player overriding it and stay put until
* they change it again. Display only — in a multiplayer game two players may reasonably want it
* set differently, so this must never become part of game state.
* set differently, so this must never become part of game state. Persisted in `settings`, not the
* save, for exactly that reason.
*/
let districtMode: 'auto' | 'open' | 'closed' = 'auto';
let districtMode: 'auto' | 'open' | 'closed' = settings.districtMode;
/**
* Sound, OFF until asked for.
* Sound, OFF by default until a player asks for it once — then remembered via `settings`.
*
* Everything it plays is synthesised rather than recorded, so it is a placeholder for real audio
* rather than the finished thing — and a playtester who did not ask for noise should not get any.
* One click in the title bar turns it on, and that click is also the gesture browsers require
* before any audio may start.
* rather than the finished thing. One click in the title bar turns it on, and that click is also
* the gesture browsers require before any audio may start.
*/
let soundOn = false;
let soundOn = settings.soundOn;
/** Preset board zoom (see `ZOOM_LEVELS`), persisted in `settings`. */
let zoom = settings.zoom;
/**
* The phase the page last drew, so a change of phase can be announced.
*
@@ -99,6 +169,23 @@ const $ = (id: string): HTMLElement => {
const esc = (s: string): string =>
s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] ?? c);
/**
* Size a freshly-rendered board SVG off its own `viewBox`, at the current `zoom`.
*
* `#grid` and `#division` already scroll horizontally when their content is wider than the column
* (`overflow-x:auto` in `play.html`) — that mechanism is untouched. This only changes how big the
* SVG itself renders, in real pixels rather than a CSS `transform` (which would leave the container's
* scrollable area the wrong size), so zooming in genuinely grows the scrollable area and zooming out
* genuinely shrinks it.
*/
function applyZoom(container: HTMLElement): void {
const svg = container.querySelector('svg');
const box = svg?.viewBox.baseVal;
if (!svg || !box || box.width === 0) return;
svg.style.width = `${box.width * zoom}px`;
svg.style.height = `${box.height * zoom}px`;
}
/**
* A DRAWING OF THE PIECE A PLACEMENT WOULD LAY.
*
@@ -153,19 +240,27 @@ function renderHouseRules(rules: HouseRules): void {
}
/**
* THE HOUSE RULES TRAVEL IN THE URL, BESIDE THE SEED.
* THE HOUSE RULES AND VICTORY DIALS TRAVEL IN THE URL, BESIDE THE SEED.
*
* A seed on its own no longer names a game: `?seed=430` dealt three random cards is a different
* railroad from `?seed=430` dealt three track and three other, and at 0 Revenue per transit it is a
* different economy again. The link has to carry all of it or "same link, same deal" stops being
* true — and the New Game dialog navigates by URL, so this is also how its answers reach `start()`.
* different economy again — and now a game with `minrev=15` is a different game from one with
* `minrev=0`. The link has to carry all of it or "same link, same deal" stops being true — and the
* New Game dialog navigates by URL, so this is also how its answers reach `start()`.
*
* Absent parameters mean the DEFAULTS, not the legacy rules: a bare `?seed=430` is a new game at
* today's settings. It is a save with no rules in it that is old (`game.ts`, `configFor`).
*/
const RULE_PARAMS = { passenger: 'passengerPerCoach', freight: 'freightPerLoad', transit: 'trainPerTransit' } as const;
/** The four victory-condition dials added 2026-08-20 (`GameConfig`), same URL-round-trip convention. */
const VICTORY_PARAMS = {
days: 'days',
minrev: 'minCombinedRevenue',
colday: 'maxCollisionsPerDay',
coltotal: 'maxCollisionsTotal',
} as const;
function rulesFromUrl(params: URLSearchParams): HouseRuleOverrides {
function gameOptionsFromUrl(params: URLSearchParams): NewGameOptions {
const rules: HouseRuleOverrides = {};
const hand = params.get('hand');
if (STARTING_HAND_LABELS.some((o) => o.value === hand)) rules.startingHand = hand as StartingHand;
@@ -178,29 +273,62 @@ function rulesFromUrl(params: URLSearchParams): HouseRuleOverrides {
if (raw !== null && raw.trim() !== '' && Number.isFinite(Number(raw))) revenue[key] = Number(raw);
}
if (Object.keys(revenue).length > 0) rules.revenue = revenue;
return rules;
const options: NewGameOptions = { houseRules: rules };
for (const [param, key] of Object.entries(VICTORY_PARAMS)) {
const raw = params.get(param);
// Negative or fractional values from a hand-edited URL are clamped the same way `configWith`'s
// defaults are — a stray `minrev=-5` should mean "off-ish", not a config the engine never sees.
if (raw !== null && raw.trim() !== '' && Number.isFinite(Number(raw))) {
options[key] = Math.max(0, Math.round(Number(raw)));
}
}
return options;
}
function rulesToUrl(rules: HouseRules, seed: string): string {
function rulesToUrl(rules: HouseRules, options: NewGameOptions, seed: string): string {
const params = new URLSearchParams();
if (seed !== '') params.set('seed', seed);
params.set('hand', rules.startingHand);
for (const [param, key] of Object.entries(RULE_PARAMS)) params.set(param, String(rules.revenue[key]));
for (const [param, key] of Object.entries(VICTORY_PARAMS)) {
const value = options[key];
if (value !== undefined) params.set(param, String(value));
}
return `?${params}`;
}
/**
* `?seat=` PRESENT means multiplayer (D4 — one bundle, runtime switch). The seed, house rules and
* URL-carried save/restore logic below are all solitaire concepts: a remote game's rules come from
* whatever the server was configured with, not from this browser's URL or `localStorage`.
*/
function start(): void {
const params = new URLSearchParams(location.search);
const requested = params.get('seed');
const seatParam = params.get('seat');
if (seatParam !== null) {
const seat = Number(seatParam) as PlayerIndex;
session = createRemoteSession(seat, params.get('secret') ?? '');
applyCapabilities();
// A LocalSession has data the instant it is constructed; a RemoteSession does not — its first
// real Frame only exists once the SSE connection's first push arrives, so the first render waits
// for `subscribe`'s callback rather than firing immediately (`session.ts`'s own doc comment on
// `createRemoteSession` explains why `view()` would otherwise throw).
session.subscribe(render);
return;
}
const requested = params.get('seed');
// A seed in the URL makes a game shareable and reproducible: same link, same deal.
const seed = requested !== null ? Number(requested) || 1 : Math.floor(Math.random() * 1e9);
session = createLocalSession(seed, rulesFromUrl(params));
const local = createLocalSession(seed, gameOptionsFromUrl(params));
session = local;
// A saved game carries its OWN rules and re-deals itself under them, whatever the URL says — see
// `configFor`. That is why the restore happens after the session is built rather than feeding it.
const saved = load();
if (saved && requested === null) session.restore(saved);
if (saved && requested === null) local.restore(saved);
applyCapabilities();
// Every render goes through the session, so the page redraws whenever the game says it changed —
@@ -263,11 +391,14 @@ function render(): void {
const obj = $('objective');
obj.textContent = `${f.revenue} of ${f.objective.target} · ${f.objective.daysLeft} Day${f.objective.daysLeft === 1 ? '' : 's'} left`;
obj.className = 'pace';
$('seed').textContent = String(session.seed());
// The seed is never sent to a remote client at all (it would leak every future shuffle and roll,
// `multiplayer.md` §7) — `RemoteSession` has no `.seed()` because there is nothing to return.
$('seed').textContent = isLocal(session) ? String(session.seed()) : `Seat ${session.seat()}`;
renderHouseRules(f.houseRules);
// -- division
$('division').innerHTML = divisionSvg(f.division);
applyZoom($('division'));
// -- board. Both renderers are shared with the replay so the two can never draw different
// pictures of the same position.
@@ -302,6 +433,7 @@ function render(): void {
return [{ row: cell.row, col: cell.col, label }];
});
grid.innerHTML = officeSvg(f.cells, f.runningRow, ghostCoords, legalCaps, f.limits, selectedCrew);
applyZoom(grid);
// Wire the roster chips: clicking one sets `selectedCrew`, the same value the "Which train are
// you switching?" picker writes, so the board and the action panel drive one value either way.
@@ -593,14 +725,18 @@ function render(): void {
*/
function renderUndo(): void {
const btn = document.getElementById('undo') as HTMLButtonElement | null;
if (!btn || !session.capabilities.undo) return;
const n = session.steps();
if (!btn || !isLocal(session)) return;
// Captured as a `const` rather than read as `session` again inside the closure below: `session` is
// a mutable module-level `let`, so TypeScript cannot carry the `isLocal` narrowing across a closure
// boundary — a local const it can never see reassigned keeps the narrowed `LocalSession` type.
const local = session;
const n = local.steps();
btn.disabled = n === 0;
btn.textContent = n === 0 ? 'Undo' : `Undo (${n})`;
btn.onclick = () => {
// The session drops the rebuilt game's cues and draws — replaying the history re-records them,
// and none of it is news to a player who just stepped back.
if (!session.undo()) return;
if (!local.undo()) return;
selected = null;
mode = null;
pendingAt = null;
@@ -657,6 +793,7 @@ function renderDistrict(f: Frame): void {
btn.onclick = () => {
// auto -> pin it to the opposite of what auto is doing -> back to auto.
districtMode = districtMode === 'auto' ? (open ? 'closed' : 'open') : 'auto';
saveSettings({ districtMode });
render();
};
}
@@ -980,6 +1117,10 @@ function renderActions(
* where a rendered page would have been megabytes.
*/
function downloadSave(): void {
// The button this fires from is hidden by `applyCapabilities()` for any session that cannot save
// (`#savefile`), but nothing stops this function being called directly, so the guard is repeated
// here rather than only trusted to the DOM.
if (!isLocal(session)) return;
const data = JSON.stringify(session.save(), null, 1);
const blob = new Blob([data], { type: 'application/json' });
const url = URL.createObjectURL(blob);
@@ -991,7 +1132,7 @@ function downloadSave(): void {
}
function save(): void {
if (!session.capabilities.saveLocal) return;
if (!isLocal(session)) return;
try {
localStorage.setItem(SAVE_KEY, JSON.stringify(session.save()));
} catch {
@@ -1043,32 +1184,79 @@ const newBtn = document.getElementById('newgame');
const dlg = document.getElementById('newgamedlg') as HTMLDialogElement | null;
if (newBtn && dlg) {
const field = <T extends HTMLElement>(id: string): T => document.getElementById(id) as T;
type Mode = 'solitaire' | 'competitive' | 'coop';
/**
* ASK FOR ALL THREE, rather than documenting URL parameters in the title bar.
* PICKING A TYPE JUST SETS THE FIELDS BELOW TO THAT TYPE'S DEFAULTS (Jesse's design, 2026-08-20) —
* every number stays editable afterward, so "Competitive" isn't a fixed ruleset, it's a starting
* point. `players = 4` for Competitive/Co-op is a nominal stand-in: there's no lobby yet to ask who
* is actually seated (Phase 4), so this is a suggestion a real seat count will replace.
*
* Only Solitaire can be dealt today — Deal disables itself for the other two, with a note, rather
* than pretending a click would do something (`RemoteSession` is Phase 2).
*/
function applyModePreset(mode: Mode): void {
const days = 5;
const players = mode === 'solitaire' ? 1 : 4;
field<HTMLInputElement>('ng-days').value = String(days);
field<HTMLInputElement>('ng-minrev').value = String(collectiveRevenueFloor(players, days));
field<HTMLInputElement>('ng-colday').value = String(DEFAULT_MAX_COLLISIONS_PER_DAY);
field<HTMLInputElement>('ng-coltotal').value = String(DEFAULT_MAX_COLLISIONS_TOTAL);
// No valid target for these cards in Solitaire or Co-op — forced off, not merely defaulted off.
const pvp = field<HTMLInputElement>('ng-pvp');
pvp.checked = mode === 'competitive';
pvp.disabled = mode !== 'competitive';
field<HTMLButtonElement>('ng-deal').disabled = mode !== 'solitaire';
field<HTMLElement>('ng-multiplayer-note').style.visibility = mode === 'solitaire' ? 'hidden' : 'visible';
}
for (const input of dlg.querySelectorAll<HTMLInputElement>('input[name="ng-mode"]')) {
input.onchange = () => applyModePreset(input.value as Mode);
}
/**
* ASK FOR ALL OF IT, rather than documenting URL parameters in the title bar.
*
* It asked for the seed alone, through `prompt()`. The opening hand and the three revenue rates
* were constants in the source, so trying a variation meant an edit and a rebuild — and balance is
* the open question this game has (`TODO.md`). A dialog is what lets a playtest be a playtest.
*
* The dialog OPENS ON THE RULES IN PLAY rather than on the defaults: dealing a second game to
* compare against the first is the common case, and re-entering four settings each time is how a
* comparison silently stops comparing.
* compare against the first is the common case, and re-entering settings each time is how a
* comparison silently stops comparing. Mode always reopens on Solitaire — it's the only one a
* previous session could actually have been, since Deal is disabled for the other two.
*/
newBtn.onclick = () => {
const f = session.view();
// The button itself is hidden for a session that cannot deal (`applyCapabilities`), but the
// dialog's whole answer-reading/URL-navigating flow below assumes a LocalSession throughout, so
// the guard is repeated — and `local` is captured as a `const` so the narrowing survives the
// closures below it (see `renderUndo`'s identical note on why `session` itself cannot be).
if (!isLocal(session)) return;
const local = session;
const f = local.view();
const day = f.day;
const started = f.status === 'active' && (day > 1 || f.stage > 1);
if (started && !confirm(`Forget this game (seed ${session.seed()}, Day ${day}) and deal a new one?`)) return;
if (started && !confirm(`Forget this game (seed ${local.seed()}, Day ${day}) and deal a new one?`)) return;
const current = session.view().houseRules;
const current = f.houseRules;
field<HTMLInputElement>('ng-seed').value = '';
for (const input of dlg.querySelectorAll<HTMLInputElement>('input[name="ng-mode"]')) {
input.checked = input.value === 'solitaire';
}
applyModePreset('solitaire');
for (const input of dlg.querySelectorAll<HTMLInputElement>('input[name="ng-hand"]')) {
input.checked = input.value === current.startingHand;
}
field<HTMLInputElement>('ng-passenger').value = String(current.revenue.passengerPerCoach);
field<HTMLInputElement>('ng-freight').value = String(current.revenue.freightPerLoad);
field<HTMLInputElement>('ng-transit').value = String(current.revenue.trainPerTransit);
// Overwrite the preset with the actual rules in play — solitaire is the only real session today.
field<HTMLInputElement>('ng-days').value = String(f.days);
field<HTMLInputElement>('ng-minrev').value = String(f.minCombinedRevenue);
field<HTMLInputElement>('ng-colday').value = String(f.maxCollisionsPerDay);
field<HTMLInputElement>('ng-coltotal').value = String(f.maxCollisionsTotal);
dlg.showModal();
};
@@ -1078,6 +1266,8 @@ if (newBtn && dlg) {
*
* The answers go into the URL and the page navigates, which is the same path `?seed=` already
* took: `start()` reads them back, so there is exactly one place that turns a URL into a game.
* Deal is disabled whenever the mode radio isn't Solitaire, so this never actually runs for the
* other two — nothing here needs to branch on mode.
*/
dlg.addEventListener('close', () => {
if (dlg.returnValue !== 'deal') return;
@@ -1097,9 +1287,15 @@ if (newBtn && dlg) {
},
},
});
const victory: NewGameOptions = {
days: Math.max(1, Math.round(Number(field<HTMLInputElement>('ng-days').value)) || 5),
minCombinedRevenue: Math.max(0, Math.round(Number(field<HTMLInputElement>('ng-minrev').value)) || 0),
maxCollisionsPerDay: Math.max(0, Math.round(Number(field<HTMLInputElement>('ng-colday').value)) || 0),
maxCollisionsTotal: Math.max(0, Math.round(Number(field<HTMLInputElement>('ng-coltotal').value)) || 0),
};
clearSave();
const next = rulesToUrl(rules, seed);
const next = rulesToUrl(rules, victory, seed);
// Assigning the search string the page ALREADY has does nothing at all, which reads as a button
// that did not work — and it is the common case: deal a random seed, decide it was a bad deal,
// deal another at the same settings. Reload instead, and `start()` rolls a fresh seed.
@@ -1108,6 +1304,35 @@ if (newBtn && dlg) {
});
}
const zoomOutBtn = document.getElementById('zoomout') as HTMLButtonElement | null;
const zoomInBtn = document.getElementById('zoomin') as HTMLButtonElement | null;
const zoomLabel = document.getElementById('zoomlabel');
if (zoomOutBtn && zoomInBtn && zoomLabel) {
const paintZoom = (): void => {
zoomLabel.textContent = `${Math.round(zoom * 100)}%`;
zoomOutBtn.disabled = zoom <= ZOOM_LEVELS[0]!;
zoomInBtn.disabled = zoom >= ZOOM_LEVELS[ZOOM_LEVELS.length - 1]!;
};
const setZoom = (level: number): void => {
zoom = level;
saveSettings({ zoom });
paintZoom();
// Re-apply to whichever boards are already on the page — no full re-render needed, this is
// display-only sizing, same as `render()`'s own calls after each innerHTML assignment.
applyZoom($('division'));
applyZoom($('grid'));
};
zoomOutBtn.onclick = () => {
const i = ZOOM_LEVELS.indexOf(zoom as (typeof ZOOM_LEVELS)[number]);
if (i > 0) setZoom(ZOOM_LEVELS[i - 1]!);
};
zoomInBtn.onclick = () => {
const i = ZOOM_LEVELS.indexOf(zoom as (typeof ZOOM_LEVELS)[number]);
if (i >= 0 && i < ZOOM_LEVELS.length - 1) setZoom(ZOOM_LEVELS[i + 1]!);
};
paintZoom();
}
const soundBtn = document.getElementById('sound');
if (soundBtn) {
const paint = (): void => {
@@ -1115,6 +1340,7 @@ if (soundBtn) {
};
soundBtn.onclick = () => {
soundOn = !soundOn;
saveSettings({ soundOn });
paint();
// Confirm the change audibly — the one press where a sound is unambiguously wanted, and it
// doubles as the user gesture the browser needs before any audio may start.
src/web/play.html
+33
View File
@@ -33,6 +33,9 @@ header button:hover{border-color:#4d6fa8}
stops inviting the press. */
header button:disabled{opacity:.45;cursor:not-allowed;border-color:#2c333d}
header button:disabled:hover{border-color:#2c333d}
.zoom{display:inline-flex;align-items:center;gap:4px}
.zoom button{padding:3px 9px;line-height:1}
.zoom #zoomlabel{font-size:11px;color:var(--dim);min-width:32px;text-align:center;display:inline-block}
.build{margin-left:auto;font-size:10px;opacity:.55;white-space:nowrap}
.home{color:inherit;text-decoration:none;border-bottom:1px dotted #5f6b7a}
.home:hover{color:#5aa9e6}
@@ -221,6 +224,12 @@ ul.blocked li{padding:2px 0}
to keep the header on one line; the tooltip spells it out. -->
<span class="dim" id="houserules" title="">—</span>
<button id="sound" title="Whistle at the end of each Stage, the crossing bell at the end of each Day, and the conductor when a train is built. Currently synthesised, not recorded.">🔇 muted</button>
<!-- BOARD ZOOM. Applies to the Division map and the Office Area grid alike — both already scroll
horizontally (`#division`, `#grid`) when they run wide, so this only ever needs to resize the
rendered SVG's own pixel dimensions; the existing scrollbar keeps doing the panning. -->
<span class="zoom" title="Zoom the Division map and your Office Area. Both already scroll — this only changes their size.">
<button id="zoomout" aria-label="Zoom out">−</button><span id="zoomlabel">100%</span><button id="zoomin" aria-label="Zoom in">+</button>
</span>
<button id="undo" title="Take the last action back. The save is the seed plus the moves made, so this replays the game without the last one — as far back as you like.">Undo</button>
<button id="savefile" title="Download this game as a save file you can replay or share">Save replay</button>
<button id="newgame" title="Deal a fresh game. You choose the seed, the opening hand and what the three economies pay. Undo steps back one action at a time; this throws the whole game away, so download the replay first if you want to keep it.">New game</button>
@@ -309,6 +318,15 @@ ul.blocked li{padding:2px 0}
<form method="dialog" id="newgameform">
<h2 class="big" id="ng-title">New game</h2>
<h3>Game type</h3>
<p class="ng-note">Picking a type just sets the fields below to that type's defaults — every number stays yours to change afterward. Solitaire is the only type that can be dealt today; Competitive and Co-op need a server (coming soon).</p>
<label class="ng-radio"><input type="radio" name="ng-mode" value="solitaire" checked>
<span><b>Solitaire</b><br><span class="dim">One railroad, one player. Everything below is real today.</span></span></label>
<label class="ng-radio"><input type="radio" name="ng-mode" value="competitive">
<span><b>Competitive</b><br><span class="dim">Highest Revenue wins, unless the table misses the combined minimum — then everyone loses.</span></span></label>
<label class="ng-radio"><input type="radio" name="ng-mode" value="coop">
<span><b>Co-op</b><br><span class="dim">Everyone's Revenue counts as one table score, against the same kind of combined minimum.</span></span></label>
<h3>Seed</h3>
<p class="ng-note">The same seed and the same settings always deal the same railroad, so a game can be shared, compared or replayed. Leave it blank for a random one.</p>
<input id="ng-seed" type="text" inputmode="numeric" autocomplete="off" placeholder="blank for a random seed">
@@ -332,7 +350,22 @@ ul.blocked li{padding:2px 0}
<input id="ng-transit" type="number" min="0" max="5" step="1" value="0"></label>
<p class="ng-note">A transit pays every player, once, when a train runs off the end of the Division — the one thing nobody has to work for. It defaults to 0 for that reason.</p>
<h3>Victory conditions</h3>
<p class="ng-note">How long the game runs, and the ways it can end. 0 turns any of these off. The combined-Revenue suggestion updates for Competitive/Co-op — it assumes a 4-player table until there's a lobby to ask who's actually seated.</p>
<label class="ng-num"><span>Days</span>
<input id="ng-days" type="number" min="1" max="20" step="1" value="5"></label>
<label class="ng-num"><span>Minimum combined Revenue to avoid a loss</span>
<input id="ng-minrev" type="number" min="0" step="1" value="15"></label>
<label class="ng-num"><span>Collisions in one Day that end the game</span>
<input id="ng-colday" type="number" min="0" step="1" value="3"></label>
<label class="ng-num"><span>Collisions across the whole game that end it</span>
<input id="ng-coltotal" type="number" min="0" step="1" value="5"></label>
<label class="ng-num"><span>Allow the opponent-directed cards</span>
<input id="ng-pvp" type="checkbox"></label>
<p class="ng-note" id="ng-pvp-note">Not yet built (<code>TODO.md</code>) — this has no effect either way until then.</p>
<menu class="ng-buttons">
<span class="ng-note" id="ng-multiplayer-note" style="margin:0 auto 0 0">Multiplayer needs a server — coming soon.</span>
<button value="cancel" id="ng-cancel" type="submit" formnovalidate>Cancel</button>
<button value="deal" id="ng-deal" type="submit">Deal</button>
</menu>
src/web/session.ts
+83 -9
View File
@@ -18,8 +18,9 @@
import type { Intent } from '../engine/intents.ts';
import type { Frame } from '../sim/view.ts';
import type { PlayerIndex } from '../engine/state.ts';
import type { HouseRuleOverrides } from '../engine/content.ts';
import type { Game, Menu, Save } from './game.ts';
import { applyDelta } from '../sim/frame-delta.ts';
import type { FrameDelta } from '../sim/frame-delta.ts';
import type { Game, Menu, NewGameOptions, Save } from './game.ts';
import {
actionMenu,
configWith,
@@ -115,14 +116,14 @@ export type LocalSession = Session & {
* `Game` is mutated in place by `submit`, so the wrapper keeps a mutable reference rather than
* copying — `undo` and `restore` replace the whole game, which is why `game` is a getter.
*
* It takes `rules` rather than a whole `GameConfig` because DEALING is the only thing on the far
* side of this that the page is allowed to decide. A config carries the mode, the victory condition
* and the optional rules — table settings a lobby owns — and handing main.ts a `GameConfig` to build
* meant importing the engine's own defaults into the page, which is the boundary `session.test.ts`
* guards. The seed and the house rules are the two things a player picks when they press New game.
* It takes `NewGameOptions` rather than a whole `GameConfig` because DEALING is the only thing on the
* far side of this that the page is allowed to decide. A config carries the mode and the optional
* rules — table settings a lobby owns — and handing main.ts a `GameConfig` to build meant importing
* the engine's own defaults into the page, which is the boundary `session.test.ts` guards. The seed,
* the house rules and the victory-condition dials are what a player picks when they press New game.
*/
export function createLocalSession(seed: number, rules?: HouseRuleOverrides): LocalSession {
let game: Game = rules ? newGame(seed, configWith(rules)) : newGame(seed);
export function createLocalSession(seed: number, options?: NewGameOptions): LocalSession {
let game: Game = options ? newGame(seed, configWith(options)) : newGame(seed);
const listeners = new Set<() => void>();
const changed = (): void => {
for (const fn of [...listeners]) fn();
@@ -187,3 +188,76 @@ export function createLocalSession(seed: number, rules?: HouseRuleOverrides): Lo
},
};
}
/** The push envelope `src/server/session.ts` sends over SSE — mirrored here rather than imported,
* so this file never depends on anything under `src/server/` even at the type level. */
type Push = { frame: FrameDelta; menu: Menu | null; lines: { text: string; tone: string }[] };
/**
* A session backed by a server (Phase 2). Holds no authoritative state — no deck order, no other
* seat's hand — only the last `Frame`/`Menu` a push actually told it. `capabilities` are all `false`:
* undo would have to un-see what other players already saw, a local save is meaningless when the
* server is the store, and dealing a new game is the lobby's job (Phase 4).
*
* Construction is synchronous (the `Session` interface has no async surface), but the first real
* `Frame` only exists once the SSE connection's first push arrives — `main.ts` accounts for this by
* not rendering until `subscribe`'s callback fires at least once for a session whose `capabilities`
* are all `false` (a `LocalSession` always has data the instant it is constructed; this does not).
*/
export function createRemoteSession(seat: PlayerIndex, secret: string): Session {
let frame: Frame | null = null;
let menu: Menu | null = null;
let lines: { text: string; tone: string }[] = [];
let nextSeq = 1;
const listeners = new Set<() => void>();
const changed = (): void => {
for (const fn of [...listeners]) fn();
};
const qs = `seat=${seat}&secret=${encodeURIComponent(secret)}`;
const source = new EventSource(`/api/stream?${qs}`);
source.onmessage = (ev: MessageEvent<string>) => {
const push = JSON.parse(ev.data) as Push;
frame = applyDelta(frame, push.frame);
menu = push.menu;
lines = [...lines, ...push.lines];
changed();
};
const need = (): Frame => {
if (frame === null) throw new Error('RemoteSession.view() called before the first Frame arrived');
return frame;
};
return {
view: need,
menu: () => menu ?? { options: [], direct: [], placeable: [], hand: [], makeUp: null },
seat: () => seat,
actor: () => need().actor,
overHandLimit: () => need().overHandLimit,
handPlayable: () => (menu?.hand ?? []).map((h) => h.playNow !== null),
async submit(intent: Intent): Promise<boolean> {
const seq = nextSeq++;
const res = await fetch(`/api/intent?${qs}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ seq, intent }),
});
const result = (await res.json()) as { ok: boolean; code?: string };
// The visible update arrives via the SSE push (broadcast to every seat, including this one),
// not from this response — this only reports whether the rules accepted it.
return result.ok;
},
subscribe(fn: () => void) {
listeners.add(fn);
return () => listeners.delete(fn);
},
capabilities: { undo: false, saveLocal: false, newGame: false },
lines: () => lines,
takeCues: () => [],
takeScheduled: () => null,
takeAnnouncement: () => null,
justDrawn: () => null,
};
}
test/advance.test.ts
+168 -20
View File
@@ -9,17 +9,20 @@ import assert from 'node:assert/strict';
import { advance, pump } from '../src/engine/advance.ts';
import { applyIntent, areaOf, check } from '../src/engine/apply.ts';
import { EXPEDITE_FAULT_PENALTY, HAND_LIMIT, STAGES_PER_DAY, lengthProfile, TOTAL_ROLLING_STOCK } from '../src/engine/content.ts';
import { EXPEDITE_FAULT_PENALTY, HAND_LIMIT, STAGES_PER_DAY, TOTAL_ROLLING_STOCK } from '../src/engine/content.ts';
import { legalActions } from '../src/engine/legal.ts';
import { createGame } from '../src/engine/setup.ts';
import { developerBot } from '../src/sim/bot.ts';
import type { CrewTray, GameConfig, GameState } from '../src/engine/state.ts';
import { railFacingOf } from '../src/engine/state.ts';
import { coordKey, railFacingOf } from '../src/engine/state.ts';
const baseConfig = (over: Partial<GameConfig> = {}): GameConfig => ({
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'short',
days: 3,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
@@ -327,6 +330,75 @@ describe('collisions are automatic (Gap 2)', () => {
assert.ok(!s.trays.has(id), 'the train is removed');
});
it('does not collide when a coach is legally parked at the Office (v0.5.0 §A.4 exception)', () => {
// A coach may now be set out at the Office (§A.4's carve-out). It must not become a hazard to
// the next train in — that would punish exactly the thing the rule was written to allow.
const s = game();
const area = s.officeAreas.get(0)!;
area.adOccupancy = []; // an A/D track is free — only the fouling check is under test
const officeCard = area.grid.get(coordKey(area.officeCoord))!;
officeCard.standing = [{ type: 'coach', loaded: false }];
const id = 'inbound';
s.trays.set(id, {
id,
trainNumber: 2,
trainIsExtra: false,
engineAt: 0,
consist: [{ type: 'coach', loaded: true }],
direction: 'east',
position: { at: 'mainline', index: 1 },
movesUsed: 0,
});
const ml = s.division.nodes[1];
if (ml?.kind === 'mainline') {
ml.card = 'plains';
ml.transits.push({ tray: id, stagesRemaining: 1, stagesTotal: 1, direction: 'east' });
}
s.clock.phase = 'mainline';
s.movedThisPhase = new Set();
advance(s);
assert.equal(s.collisionsToday, 0, 'a legally parked coach is not a hazard to the next arrival');
assert.ok(s.trays.has(id), 'the train is not written off');
});
it('still collides when a non-coach car is left fouling the Office track', () => {
// Reachable only by poking state directly — `canDropCarsAt` already refuses every non-coach
// drop at the Office, so this backstops the collision check itself, not a state a legal game
// can reach.
const s = game();
const area = s.officeAreas.get(0)!;
area.adOccupancy = [];
const officeCard = area.grid.get(coordKey(area.officeCoord))!;
officeCard.standing = [{ type: 'boxcar', loaded: false }];
const id = 'inbound';
s.trays.set(id, {
id,
trainNumber: 2,
trainIsExtra: false,
engineAt: 0,
consist: [{ type: 'coach', loaded: true }],
direction: 'east',
position: { at: 'mainline', index: 1 },
movesUsed: 0,
});
const ml = s.division.nodes[1];
if (ml?.kind === 'mainline') {
ml.card = 'plains';
ml.transits.push({ tray: id, stagesRemaining: 1, stagesTotal: 1, direction: 'east' });
}
s.clock.phase = 'mainline';
s.movedThisPhase = new Set();
advance(s);
assert.equal(s.collisionsToday, 1);
assert.ok(!s.trays.has(id), 'the train is removed');
});
it('returns cabooses to the Division Yard and other stock to Classification (Gap 2c)', () => {
const s = game();
s.officeAreas.get(0)!.adOccupancy = ['blocker'];
@@ -464,11 +536,11 @@ describe('the Superintendent clearance interrupt (§8.1)', () => {
// ---------------------------------------------------------------------------
describe('victory conditions (§3, Gap 10e)', () => {
it('loses a timed Solitaire game that misses the target', () => {
// The target doubles as a MINIMUM in Solitaire: below it you lose regardless of score.
const s = game(1);
s.clock.day = lengthProfile('short').days + 1;
describe('victory conditions (§3, Gap 10e) — unified 2026-08-20', () => {
it('loses a timed Solitaire game that misses minCombinedRevenue', () => {
// minCombinedRevenue doubles as a MINIMUM in Solitaire: below it you lose regardless of score.
const s = game(1, { minCombinedRevenue: 10 });
s.clock.day = s.config.days + 1;
s.clock.stage = STAGES_PER_DAY;
s.clock.phase = 'shiftChange';
s.players[0]!.revenue = 0;
@@ -478,25 +550,101 @@ describe('victory conditions (§3, Gap 10e)', () => {
assert.equal(s.outcome!.reason, 'revenueFloor');
});
it('wins a timed Solitaire game that clears the target', () => {
const s = game(1);
s.clock.day = lengthProfile('short').days + 1;
it('wins a timed Solitaire game that clears minCombinedRevenue', () => {
const s = game(1, { minCombinedRevenue: 10 });
s.clock.day = s.config.days + 1;
s.clock.stage = STAGES_PER_DAY;
s.clock.phase = 'shiftChange';
s.players[0]!.revenue = lengthProfile('short').target;
s.players[0]!.revenue = 10;
advance(s);
assert.equal(s.status, 'finished');
assert.equal(s.outcome!.result, 'win');
});
it('ends a first-to-target game the moment the target is reached', () => {
const s = game(1, { victory: 'firstToTarget' });
s.players[0]!.revenue = lengthProfile('short').target;
it('minCombinedRevenue = 0 disables the floor — any score wins once days run out', () => {
const s = game(1, { minCombinedRevenue: 0 });
s.clock.day = s.config.days + 1;
s.clock.stage = STAGES_PER_DAY;
s.clock.phase = 'shiftChange';
s.players[0]!.revenue = 0;
advance(s);
assert.equal(s.status, 'finished');
assert.equal(s.outcome!.result, 'win');
});
it('everyone loses in Competitive when the TABLE misses minCombinedRevenue, whoever scored best', () => {
const s = createGame({
id: 'g', seed: 2, config: baseConfig({ mode: 'competitive', minCombinedRevenue: 20 }),
playerNames: ['A', 'B'],
});
s.clock.day = s.config.days + 1;
s.clock.stage = STAGES_PER_DAY;
s.clock.phase = 'shiftChange';
s.players[0]!.revenue = 5; // best individual score...
s.players[1]!.revenue = 3; // ...but combined (8) still misses the floor (20).
advance(s);
assert.equal(s.status, 'finished');
assert.equal(s.outcome!.result, 'loss');
assert.equal(s.outcome!.reason, 'revenueFloor');
});
it('Co-op wins as one table score (summed Revenue), winner stays null', () => {
const s = createGame({
id: 'g', seed: 3, config: baseConfig({ mode: 'coop', minCombinedRevenue: 10 }),
playerNames: ['A', 'B'],
});
s.clock.day = s.config.days + 1;
s.clock.stage = STAGES_PER_DAY;
s.clock.phase = 'shiftChange';
s.players[0]!.revenue = 4;
s.players[1]!.revenue = 6; // combined 10 clears the floor, neither alone would.
advance(s);
assert.equal(s.status, 'finished');
assert.equal(s.outcome!.result, 'win');
assert.equal(s.outcome!.winner, null, 'Co-op names an individual winner instead of a shared one');
});
it('ends immediately, mid-Stage, when collisions reach maxCollisionsPerDay', () => {
// Competitive/coop only, and immediate — not gated on the day boundary the way the revenue
// floor is. Stage 1, well short of STAGES_PER_DAY, proves it fires mid-day.
const s = game(1, { mode: 'competitive', maxCollisionsPerDay: 2 });
s.collisionsToday = 2;
s.clock.stage = 1;
s.clock.phase = 'shiftChange';
advance(s);
assert.equal(s.status, 'finished');
assert.equal(s.outcome!.reason, 'targetReached');
assert.equal(s.outcome!.result, 'loss');
assert.equal(s.outcome!.reason, 'collisionFloor');
});
it('ends immediately when the running total reaches maxCollisionsTotal, even under the per-day cap', () => {
const s = game(1, { mode: 'coop', maxCollisionsPerDay: 0, maxCollisionsTotal: 3 });
s.collisionsTotal = 3;
s.clock.stage = 1;
s.clock.phase = 'shiftChange';
advance(s);
assert.equal(s.status, 'finished');
assert.equal(s.outcome!.reason, 'collisionFloor');
});
it('maxCollisionsPerDay = 0 and maxCollisionsTotal = 0 disable the collision floor entirely', () => {
const s = game(1, { mode: 'competitive', maxCollisionsPerDay: 0, maxCollisionsTotal: 0 });
s.collisionsToday = 99;
s.collisionsTotal = 99;
s.clock.stage = 1;
s.clock.phase = 'shiftChange';
advance(s);
assert.notEqual(s.status, 'finished');
});
it('solitaire never checks the collision floor, whatever the counts', () => {
const s = game(1, { mode: 'solitaire', maxCollisionsPerDay: 1, maxCollisionsTotal: 1 });
s.collisionsToday = 99;
s.collisionsTotal = 99;
s.clock.stage = 1;
s.clock.phase = 'shiftChange';
advance(s);
assert.notEqual(s.status, 'finished');
});
});
@@ -708,7 +856,7 @@ describe('the history says WHY a train moved, and says it truthfully', () => {
* which deadlocks the moment Local Operations wants an option chosen before it can be ended.
*/
const phasesWith = (trainNumber: number): { localOps: number; loadUnload: number; leftIn: string } => {
const s = game(7, { length: 'standard' });
const s = game(7, { days: 5 });
for (const n of s.division.nodes) if (n.kind === 'mainline') n.card = 'plains';
/**
* A DIVISION WITH NOTHING ELSE ON IT. §8.1 can still hold any train, Expedited or not, on a
@@ -799,7 +947,7 @@ describe('the history says WHY a train moved, and says it truthfully', () => {
// What Expedite actually restricts now: not WHEN the train leaves, but WHERE it may be left
// standing in the meantime. Parked on Secondary Track — cleared there to make way for other
// switching, say — it must not still be there when the next Mainline Phase begins.
const s = game(7, { length: 'standard' });
const s = game(7, { days: 5 });
const area = areaOf(s, 0);
const id = 'expedited';
const secondary = { row: area.officeCoord.row, col: area.officeCoord.col + 1 };
@@ -827,7 +975,7 @@ describe('the history says WHY a train moved, and says it truthfully', () => {
it('does not fault an Expedited train legitimately held at the station itself', () => {
// A train sitting on the Office square is not "left" anywhere — including one §8.1 is holding
// for a same-direction meet, which is an ordinary hold, not a Station Master failure.
const s = game(7, { length: 'standard' });
const s = game(7, { days: 5 });
const area = areaOf(s, 0);
const id = 'expedited';
s.trays.set(id, {
test/apply.test.ts
+5 -2
View File
@@ -17,8 +17,11 @@ import { cardDescription, snapshot } from '../src/sim/view.ts';
const config: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'standard',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
test/cut-ordering.test.ts
+5 -2
View File
@@ -18,8 +18,11 @@ import { carsOn, coordKey, turnOf } from '../src/engine/state.ts';
const config: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'standard',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
test/enhancements.test.ts
+5 -2
View File
@@ -18,8 +18,11 @@ import { coordKey, subdivisions, turnOf } from '../src/engine/state.ts';
const config: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'standard',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
};
const game = (seed = 5): GameState => createGame({ id: 'g', seed, config, playerNames: ['p'] });
test/frame-delta.test.ts
+87
View File
@@ -0,0 +1,87 @@
import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { areaOf } from '../src/engine/apply.ts';
import { createGame } from '../src/engine/setup.ts';
import { coordKey } from '../src/engine/state.ts';
import type { GameConfig, GameState } from '../src/engine/state.ts';
import { applyDelta, deltaFrame } from '../src/sim/frame-delta.ts';
import { snapshot } from '../src/sim/view.ts';
const config: GameConfig = {
mode: 'solitaire',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
employeeRotation: false,
emergencyToolbox: false,
},
};
const game = (seed = 1): GameState => createGame({ id: 'g', seed, config, playerNames: ['a'] });
describe('deltaFrame — the live one-step-back board diff', () => {
it('nulls cells/facilities/division when the board has not changed, keeps everything else', () => {
const s = game();
const first = snapshot(s, [], null);
s.players[0]!.revenue = 42; // a non-board change
const second = snapshot(s, [], null);
const delta = deltaFrame(first, second);
assert.equal(delta.cells, null, 'unchanged cells were not nulled');
assert.equal(delta.facilities, null, 'unchanged facilities were not nulled');
assert.equal(delta.division, null, 'unchanged division was not nulled');
assert.equal(delta.revenue, 42, 'a real change was dropped along with the unchanged board');
});
it('sends the real board when it changed', () => {
const s = game();
const first = snapshot(s, [], null);
const area = areaOf(s, 0);
area.grid.set(coordKey({ row: area.runningRow - 1, col: 0 }), {
geometry: { kind: 'track', geometry: 'straight' },
baseOperationalRail: true, standing: [], standingWest: 0, facility: null, modifiers: [], enhancements: [],
});
const second = snapshot(s, [], null);
const delta = deltaFrame(first, second);
assert.notEqual(delta.cells, null, 'a real board change was nulled');
assert.deepEqual(delta.cells, second.cells);
});
it('never nulls anything on a first connect (no previous Frame)', () => {
const s = game();
const frame = snapshot(s, [], null);
const delta = deltaFrame(null, frame);
assert.deepEqual(delta.cells, frame.cells);
assert.deepEqual(delta.facilities, frame.facilities);
assert.deepEqual(delta.division, frame.division);
});
it('applyDelta round-trips: merge(delta(A, B)) against A reconstructs B exactly', () => {
const s = game();
const a = snapshot(s, [], null);
s.players[0]!.revenue = 7;
const area = areaOf(s, 0);
area.grid.set(coordKey({ row: area.runningRow - 1, col: 1 }), {
geometry: { kind: 'track', geometry: 'straight' },
baseOperationalRail: true, standing: [], standingWest: 0, facility: null, modifiers: [], enhancements: [],
});
const b = snapshot(s, [], null);
const merged = applyDelta(a, deltaFrame(a, b));
assert.deepEqual(merged, b);
});
it('throws rather than silently reconstructing garbage when previous is missing but the delta says "unchanged"', () => {
const s = game();
const frame = snapshot(s, [], null);
const delta = deltaFrame(frame, frame); // everything nulled, since nothing changed
assert.throws(() => applyDelta(null, delta));
});
});
test/harness.test.ts
+5 -2
View File
@@ -29,8 +29,11 @@ const root = join(dirname(fileURLToPath(import.meta.url)), '..');
const config: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'standard',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
test/mainline-cards.test.ts
+7 -4
View File
@@ -32,8 +32,11 @@ import { snapshot } from '../src/sim/view.ts';
const config: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'standard',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
};
const game = (seed = 5): GameState => createGame({ id: 'g', seed, config, playerNames: ['p'] });
@@ -733,7 +736,7 @@ describe('regions on a Mainline card (§2.1, §8.2)', () => {
id: 'reg',
seed: 4,
config: {
mode: 'solitaire', victory: 'highestAfterDays', length: 'standard',
mode: 'solitaire', days: 5, minCombinedRevenue: 0, maxCollisionsPerDay: 0, maxCollisionsTotal: 0, pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
},
playerNames: ['Solitaire'],
@@ -796,7 +799,7 @@ describe('Q13 — a train that catches the one ahead runs into it', () => {
const s = createGame({
id: 'rear', seed: 3,
config: {
mode: 'solitaire', victory: 'highestAfterDays', length: 'standard',
mode: 'solitaire', days: 5, minCombinedRevenue: 0, maxCollisionsPerDay: 0, maxCollisionsTotal: 0, pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
},
playerNames: ['bot'],
test/multiplayer.test.ts
+116 -4
View File
@@ -11,21 +11,31 @@ import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { advance, pump } from '../src/engine/advance.ts';
import { areaAtSeat, areaOf } from '../src/engine/apply.ts';
import { applyIntent, areaAtSeat, areaOf } from '../src/engine/apply.ts';
import { STAGES_PER_SHIFT, crewTrayCount } from '../src/engine/content.ts';
import { createGame } from '../src/engine/setup.ts';
import type { GameConfig, GameState, PlayerIndex } from '../src/engine/state.ts';
import { coordKey, playerAtSeat, seatOf, subdivisions } from '../src/engine/state.ts';
import { coordKey, playerAtSeat, playerLeftOf, seatOf, subdivisions } from '../src/engine/state.ts';
import { developerBot, playGame } from '../src/sim/bot.ts';
import { snapshot } from '../src/sim/view.ts';
import { impediments } from '../src/sim/narrate.ts';
import { readFileSync, readdirSync } from 'node:fs';
import { join } from 'node:path';
import { actionMenu } from '../src/web/game.ts';
import type { Game } from '../src/web/game.ts';
/** The thin wrapper `actionMenu` expects, built directly around an already-created multi-player state
* — `newGame` (game.ts) hardcodes one player, so it cannot construct this for a multi-seat game. */
const wrap = (s: GameState): Game =>
({ state: s, seed: s.seed, history: [], log: [], mustPlayCard: false, cues: [], scheduled: null, justDrawn: null, announced: null });
const competitive: GameConfig = {
mode: 'competitive',
victory: 'highestAfterDays',
length: 'standard',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
};
@@ -474,6 +484,9 @@ describe('the view shows one seat at a time', () => {
* which is a list of squares that do not exist on the board they are looking at.
*/
const s = game(3);
// A real floor to pace against — the shared `competitive` fixture leaves it off (0) since most
// tests in this file don't care, but pacing against "off" is trivially "always on pace" (view.ts).
s.config.minCombinedRevenue = 10;
s.players[0]!.revenue = 1;
s.players[1]!.revenue = 9;
s.players[2]!.revenue = 17;
@@ -600,3 +613,102 @@ describe('scoring lands on the right seat', () => {
assert.notEqual(areaAtSeat(s, 1), areaAtSeat(s, 2), 'two seats share one Office Area object');
});
});
describe('the New Train phase car-placement round rotates (§7, Gap 9)', () => {
/**
* REGRESSION. `newTrainPhase` used to hand the whole car-filling loop to a fixed actor —
* `actorOffset` is reset to 0 entering the phase and was never incremented, so `actorAt(s, 0)`
* always resolved to the Superintendent, who placed every car of every train alone. The written
* rule (`rules-v0.2.md` §7, Gap 9) is explicit: "starting with the Superintendent and working
* left, each player may place ONE car... the round repeats... until the consist is full," with a
* worked example showing seats alternating. The fix reads the round position off
* `tray.consist.length` instead, which is already exactly that counter and resets per train.
*/
it('cycles Superintendent-then-left, one car per player, wrapping as the round repeats', () => {
// Train 1, "Crack Limited" — 3 coaches, no freight or caboose (content.ts) — small enough to
// exercise both a player count that wraps (2p: seats 0,1,0) and one that doesn't (3p: 0,1,2).
for (const players of [2, 3]) {
const s = game(players);
s.clock.phase = 'newTrain';
s.trays.set('t1', {
id: 't1',
trainNumber: 1,
trainIsExtra: false,
engineAt: 0,
consist: [],
direction: 'west',
position: { at: 'divisionPoint', side: 'east' },
movesUsed: 0,
});
s.yards.divisionYard.push(
{ type: 'coach', loaded: false },
{ type: 'coach', loaded: false },
{ type: 'coach', loaded: false },
);
const expected = [0, 1, 2].map((offset) => playerLeftOf(s, s.clock.superintendent, offset));
const seenActors: PlayerIndex[] = [];
for (let guard = 0; guard < 10; guard++) {
const r = advance(s);
if (!r.needsInput) break;
const actor = s.clock.currentActor!;
seenActors.push(actor);
const result = applyIntent(s, actor, {
type: 'newTrain.placeCar',
trayId: 't1',
carType: 'coach',
loaded: false,
});
assert.ok(result.ok, `${players}p: placeCar rejected — ${result.ok ? '' : result.code}`);
}
const wanted = [0, 1, 2].map((i) => expected[i % players]!);
assert.deepEqual(
seenActors,
wanted,
`${players}p: actor sequence was [${seenActors}], wanted [${wanted}] (Superintendent-then-left)`,
);
}
});
});
describe('actionMenu is seat-safe (Phase 2 prep)', () => {
/**
* REGRESSION. `actionMenu(game, seat)` used `seat` only for the `hand` field — `options`/`direct`/
* `placeable`/`makeUp` all came from `currentActor(game)` regardless of which seat was asked. A
* server computing every connected seat's Menu would have handed the acting player's legal moves to
* a waiting seat, paired with the WRONG seat's hand. Found tracing Phase 2's per-seat Menu step.
*/
it('gives the acting seat its real options, and every other seat none at all', () => {
const s = game(3);
const g = wrap(s);
const actorSeat = s.clock.currentActor!;
const waiting = [0, 1, 2].filter((seat) => seat !== actorSeat);
const actorMenu = actionMenu(g, actorSeat as PlayerIndex);
assert.ok(actorMenu.options.length > 0, "the acting seat's Menu had no options at all");
for (const seat of waiting) {
const menu = actionMenu(g, seat as PlayerIndex);
assert.deepEqual(menu.options, [], `seat ${seat} (not acting) was given real options`);
assert.deepEqual(menu.direct, [], `seat ${seat} (not acting) was given direct actions`);
assert.deepEqual(menu.placeable, [], `seat ${seat} (not acting) was given placeable actions`);
assert.equal(menu.makeUp, null, `seat ${seat} (not acting) was given a make-up panel`);
}
});
it('still shows a waiting seat its own hand, just nothing to do with it', () => {
const s = game(3);
const g = wrap(s);
const actorSeat = s.clock.currentActor!;
const waitingSeat = [0, 1, 2].find((seat) => seat !== actorSeat)! as PlayerIndex;
const menu = actionMenu(g, waitingSeat);
const expectedHand = s.decks.hands.get(waitingSeat) ?? [];
assert.equal(menu.hand.length, expectedHand.length, "the waiting seat's own hand did not come through");
for (const card of menu.hand) {
assert.equal(card.playNow, null, 'a waiting seat was offered a way to play a card');
assert.equal(card.spots, 0, 'a waiting seat was offered somewhere to place a card');
}
});
});
test/redaction.test.ts
+118
View File
@@ -0,0 +1,118 @@
/**
* §7's redaction test — "the single most important test in the plan."
*
* Everything else about `Frame` degrades gracefully; a redaction bug hands one player's hand to
* another and cannot be walked back once it has been seen. `test/multiplayer.test.ts`'s "the view
* shows one seat at a time" section already proves `snapshot(s, ..., viewer)` gives each seat its
* own hand, board and Revenue — spot-checks that today's code does the right thing. This is the
* different, exhaustive check: serialize a seat's whole `Frame` and assert none of some OTHER seat's
* actual secret data appears anywhere in it, so a future careless edit is caught rather than assumed
* safe. No server needed — `snapshot()` and a multi-player `GameState` are all this exercises.
*/
import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { pump } from '../src/engine/advance.ts';
import { createGame } from '../src/engine/setup.ts';
import type { GameConfig, GameState, PlayerIndex } from '../src/engine/state.ts';
import { developerBot, playGame } from '../src/sim/bot.ts';
import { snapshot } from '../src/sim/view.ts';
const config: GameConfig = {
mode: 'competitive',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
employeeRotation: false,
emergencyToolbox: false,
},
};
/** Plays a real multi-player game partway — enough for every seat to hold a real, distinct hand. */
function midGame(players: number, seed: number): GameState {
const s = createGame({
id: `redact-${players}`,
seed,
config,
playerNames: Array.from({ length: players }, (_, i) => `p${i}`),
});
const r = playGame(s, developerBot, pump, 400);
// A partial or finished game both exercise real hands — either is fine for this check.
void r;
return s;
}
describe('redaction — a seat\'s Frame never carries another seat\'s secrets', () => {
it('never contains another seat\'s actual hand-card ids', () => {
for (const players of [3, 4]) {
const s = midGame(players, 1000 + players);
for (let viewer = 0 as PlayerIndex; viewer < players; viewer++) {
const serialized = JSON.stringify(snapshot(s, [], null, null, null, false, viewer));
for (let other = 0 as PlayerIndex; other < players; other++) {
if (other === viewer) continue;
for (const cardId of s.decks.hands.get(other) ?? []) {
assert.ok(
!serialized.includes(`"${cardId}"`),
`${players}p seed ${1000 + players}: seat ${viewer}'s Frame contains seat ${other}'s ` +
`hand card id "${cardId}"`,
);
}
}
}
}
});
it('never contains the Home Office deck\'s order or contents, only its count', () => {
for (const players of [3, 4]) {
const s = midGame(players, 2000 + players);
// The deck's own card ids are the thing that must never leak — distinct from any hand's ids,
// since a card once dealt is removed from `homeOffice` (state.ts).
const deckIds = new Set(s.decks.homeOffice);
for (let viewer = 0 as PlayerIndex; viewer < players; viewer++) {
const frame = snapshot(s, [], null, null, null, false, viewer);
assert.equal(frame.deck, s.decks.homeOffice.length, 'deck field is not a plain count');
const serialized = JSON.stringify(frame);
for (const cardId of deckIds) {
assert.ok(
!serialized.includes(`"${cardId}"`),
`${players}p seed ${2000 + players}: seat ${viewer}'s Frame contains a Home Office deck id "${cardId}"`,
);
}
}
}
});
it('never carries the seed or rngState — Frame has no field for either', () => {
// A structural guarantee, not a runtime one: confirmed here so a future field addition to Frame
// that reintroduces one of these is at least forced past a reader of this test, if not the type
// system directly (see Frame in src/sim/view.ts, which carries neither today).
const s = midGame(3, 3003);
const frame = snapshot(s, [], null, null, null, false, 0);
assert.ok(!('seed' in frame), 'Frame gained a seed field');
assert.ok(!('rngState' in frame), 'Frame gained an rngState field');
const serialized = JSON.stringify(frame);
assert.ok(!serialized.includes(String(s.seed)), 'the seed value leaked into the Frame some other way');
});
it('only the viewer\'s own hand and handCount are non-public — everything else matches across seats', () => {
// The redaction surface is four fields (§7), not sixty event types. Cross-check that seats agree
// on everything else a Frame carries about shared state.
const s = midGame(3, 4004);
const frames = [0, 1, 2].map((p) => snapshot(s, [], null, null, null, false, p as PlayerIndex));
for (const f of frames) {
assert.deepEqual(f.timetable, frames[0]!.timetable, 'the public timetable differs by seat');
assert.deepEqual(f.deck, frames[0]!.deck, 'the deck count differs by seat');
assert.deepEqual(
f.players.map((p) => ({ index: p.index, revenue: p.revenue, hand: p.hand })),
frames[0]!.players.map((p) => ({ index: p.index, revenue: p.revenue, hand: p.hand })),
'public standing (names, Revenue, hand COUNTS) differs by seat',
);
}
});
});
test/replay.test.ts
+8 -2
View File
@@ -9,6 +9,7 @@ import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { pump } from '../src/engine/advance.ts';
import { DEFAULT_MAX_COLLISIONS_PER_DAY, DEFAULT_MAX_COLLISIONS_TOTAL, collectiveRevenueFloor } from '../src/engine/content.ts';
import type { GameEvent } from '../src/engine/events.ts';
import { createGame } from '../src/engine/setup.ts';
import type { GameConfig } from '../src/engine/state.ts';
@@ -17,10 +18,15 @@ import { impediments, isVisible, narrate, phaseLabel } from '../src/sim/narrate.
import { compress, rehydrateCells, record, renderHtml } from '../src/sim/replay.ts';
import { summarize } from '../src/sim/stats.ts';
// Mirrors `record()`'s own default exactly (`replay.ts`) — "does not drift from the engine" below
// plays the same seed through both paths and compares outcomes, so they must share one floor.
const config: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'standard',
days: 5,
minCombinedRevenue: collectiveRevenueFloor(1, 5),
maxCollisionsPerDay: DEFAULT_MAX_COLLISIONS_PER_DAY,
maxCollisionsTotal: DEFAULT_MAX_COLLISIONS_TOTAL,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
test/server/persistence.test.ts
+101
View File
@@ -0,0 +1,101 @@
import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { mkdtemp, readFile, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { GameConfig } from '../../src/engine/state.ts';
import type { SavedGame } from '../../src/server/session.ts';
import { appendTiming, loadGame, writeGame } from '../../src/server/persistence.ts';
const config: GameConfig = {
mode: 'competitive',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
employeeRotation: false,
emergencyToolbox: false,
},
};
const saved: SavedGame = {
seed: 42,
config,
playerNames: ['Alice', 'Bob'],
history: [{ type: 'localOps.choose', option: 'draw' }],
status: 'active',
createdAt: 1000,
};
async function withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
const dir = await mkdtemp(join(tmpdir(), 'station-master-persist-'));
try {
return await fn(dir);
} finally {
await rm(dir, { recursive: true, force: true });
}
}
describe('game persistence (Phase 3)', () => {
it('writes and reads back exactly what was written', () =>
withTempDir(async (dir) => {
await writeGame(dir, saved, '1.2.3');
const result = await loadGame(dir, '1.2.3');
assert.equal(result.found, true);
if (!result.found) return;
assert.equal(result.ok, true);
if (!result.ok) return;
assert.deepEqual(result.saved, saved);
}));
it('refuses a version mismatch explicitly, naming both versions', () =>
withTempDir(async (dir) => {
await writeGame(dir, saved, '1.2.3');
const result = await loadGame(dir, '9.9.9');
assert.equal(result.found, true);
if (!result.found) return;
assert.equal(result.ok, false);
if (result.ok) return;
assert.equal(result.storedVersion, '1.2.3');
assert.equal(result.currentVersion, '9.9.9');
}));
it('reports not-found rather than throwing when nothing has been saved yet', () =>
withTempDir(async (dir) => {
const result = await loadGame(dir, '1.2.3');
assert.deepEqual(result, { found: false });
}));
it('a later writeGame fully replaces the earlier one, not merges with it', () =>
withTempDir(async (dir) => {
await writeGame(dir, saved, '1.2.3');
const grown: SavedGame = { ...saved, history: [...saved.history, { type: 'draw.end' }] };
await writeGame(dir, grown, '1.2.3');
const result = await loadGame(dir, '1.2.3');
assert.equal(result.found, true);
if (!result.found) return;
assert.equal(result.ok, true);
if (!result.ok) return;
assert.equal(result.saved.history.length, 2);
}));
it('never leaves a stray .tmp file behind after a write', () =>
withTempDir(async (dir) => {
await writeGame(dir, saved, '1.2.3');
await assert.rejects(() => readFile(join(dir, 'game.json.tmp')));
}));
it('appendTiming accumulates across calls rather than overwriting', () =>
withTempDir(async (dir) => {
await appendTiming(dir, { player: 0, phase: 'localOps', day: 1, stage: 1, startedAt: 1, endedAt: 2 });
await appendTiming(dir, { player: 1, phase: 'localOps', day: 1, stage: 1, startedAt: 2, endedAt: 3 });
const text = await readFile(join(dir, 'turn-timings.json'), 'utf8');
const timings = JSON.parse(text) as unknown[];
assert.equal(timings.length, 2);
}));
});
test/server/session.test.ts
+200
View File
@@ -0,0 +1,200 @@
/**
* The game session host (`src/server/session.ts`) — pure logic, no sockets, exercised directly.
*/
import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import type { GameConfig, PlayerIndex } from '../../src/engine/state.ts';
import type { Push } from '../../src/server/session.ts';
import { createSession, resumeSession } from '../../src/server/session.ts';
const config: GameConfig = {
mode: 'competitive',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
employeeRotation: false,
emergencyToolbox: false,
},
};
describe('the game session host', () => {
it('gives a fresh connect a full Frame — nothing nulled', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
const push = session.connect(0 as PlayerIndex);
assert.notEqual(push.frame.cells, null, 'a first connect nulled the board');
assert.notEqual(push.frame.division, null, 'a first connect nulled the division');
});
it('only the current actor gets a real Menu; every other seat gets null', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
const a = session.connect(0 as PlayerIndex);
const b = session.connect(1 as PlayerIndex);
const actorPushes = [a, b].filter((p) => p.menu !== null);
assert.equal(actorPushes.length, 1, 'more than one seat (or zero) was given a real Menu');
});
it('rejects an intent from a seat that is not the current actor, with NOT_YOUR_TURN', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
// Whichever seat is NOT the current actor should be refused, regardless of the intent's content.
const bPush = session.connect(1 as PlayerIndex);
const notActor = (bPush.menu === null ? 1 : 0) as PlayerIndex;
const result = session.intent(notActor, 1, { type: 'localOps.choose', option: 'draw' });
assert.equal(result.accepted, false);
if (!result.accepted) assert.equal(result.code, 'NOT_YOUR_TURN');
});
it('accepts a legal intent from the current actor and pushes every seat', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
const aPush = session.connect(0 as PlayerIndex);
const actor = (aPush.menu !== null ? 0 : 1) as PlayerIndex;
const result = session.intent(actor, 1, { type: 'localOps.choose', option: 'draw' });
assert.equal(result.accepted, true);
if (result.accepted) assert.equal(result.pushes.size, 2, 'not every connected seat was pushed to');
});
it('rejects an illegal intent with its real RejectionCode, and does not remember the seq', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
const aPush = session.connect(0 as PlayerIndex);
const actor = (aPush.menu !== null ? 0 : 1) as PlayerIndex;
// Discarding before ever drawing is illegal on an opening hand at the limit — a safe "this is
// definitely rejected" fixture that does not depend on exactly which cards were dealt.
const bad = session.intent(actor, 1, { type: 'card.discard', cardId: 'not-a-real-card', toSlot: 0 });
assert.equal(bad.accepted, false);
if (!bad.accepted) assert.ok(bad.code.length > 0, 'a rejection carried no code at all');
// The same seq, now with a legal intent, must still go through — a rejection is not "applied".
const retry = session.intent(actor, 1, { type: 'localOps.choose', option: 'draw' });
assert.equal(retry.accepted, true, 'a seq burned by an earlier rejection could not be reused');
});
it('treats a repeated seq as an already-applied no-op, not a second application', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
const aPush = session.connect(0 as PlayerIndex);
const actor = (aPush.menu !== null ? 0 : 1) as PlayerIndex;
const first = session.intent(actor, 1, { type: 'localOps.choose', option: 'draw' });
assert.equal(first.accepted, true);
const second = session.intent(actor, 1, { type: 'localOps.choose', option: 'draw' });
assert.equal(second.accepted, true, 'a resend of an already-applied seq was rejected instead of ignored');
if (second.accepted) assert.equal(second.pushes.size, 0, 'a resend produced pushes as if newly applied');
});
it('deltas the board on a second push when it has not changed since the first', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
const aPush = session.connect(0 as PlayerIndex);
session.connect(1 as PlayerIndex); // both seats need a baseline Frame before a delta means anything
const actor = (aPush.menu !== null ? 0 : 1) as PlayerIndex;
const result = session.intent(actor, 1, { type: 'localOps.choose', option: 'draw' });
assert.equal(result.accepted, true);
if (!result.accepted) return;
// Choosing "draw" doesn't move a single card on the board — the division/cells should be nulled
// on this push for a seat that already had them from `connect`.
const push = result.pushes.get(actor)!;
assert.equal(push.frame.division, null, 'the board was resent even though nothing on it changed');
});
it('only sends narration NEW since the last push to that specific seat', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
const aPush = session.connect(0 as PlayerIndex);
const actor = (aPush.menu !== null ? 0 : 1) as PlayerIndex;
// A first connect is this seat's first contact, so it gets everything narrated so far (the
// "Game Begins" intro and whatever `drain()` said entering the first Stage) — not an empty log.
assert.ok(aPush.lines.length > 0, 'a first connect got no narration at all, not even the game-begins intro');
const first = session.intent(actor, 1, { type: 'localOps.choose', option: 'draw' });
assert.equal(first.accepted, true);
if (!first.accepted) return;
const firstLines = first.pushes.get(actor)!.lines;
assert.ok(firstLines.length > 0, 'the acting seat got no narration for its own action');
const second = session.intent(actor, 2, { type: 'draw.end' });
assert.equal(second.accepted, true);
if (!second.accepted) return;
const secondLines = second.pushes.get(actor)!.lines;
assert.ok(secondLines.length > 0, 'a second real action produced no narration at all');
for (const line of firstLines) {
assert.ok(!secondLines.includes(line), 'the second push repeated narration already sent in the first');
}
});
});
describe('turn timings (lobby-and-sessions.md §5)', () => {
it('records a wall-clock span once the acting player, phase, Day or Stage changes', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
let pushes = new Map<PlayerIndex, Push>([
[0 as PlayerIndex, session.connect(0 as PlayerIndex)],
[1 as PlayerIndex, session.connect(1 as PlayerIndex)],
]);
const seq = new Map<PlayerIndex, number>([[0 as PlayerIndex, 1], [1 as PlayerIndex, 1]]);
const timings = [];
for (let step = 0; step < 60 && timings.length === 0; step++) {
const acting = [0, 1].find((seat) => pushes.get(seat as PlayerIndex)!.menu !== null) as PlayerIndex | undefined;
const menu = acting === undefined ? null : pushes.get(acting)!.menu;
if (acting === undefined || !menu || menu.options.length === 0) break;
const n = seq.get(acting)!;
seq.set(acting, n + 1);
const result = session.intent(acting, n, menu.options[0]!);
assert.equal(result.accepted, true, `step ${step}: ${JSON.stringify(menu.options[0])} rejected`);
if (!result.accepted) break;
if (result.timing) timings.push(result.timing);
pushes = result.pushes;
}
assert.ok(timings.length > 0, 'no turn timing ever closed across 60 real steps of actual play');
const [timing] = timings;
assert.ok(timing!.endedAt >= timing!.startedAt, 'a span ended before it started');
assert.ok([0, 1].includes(timing!.player), 'a timing named a player outside the table');
});
});
describe('persistence hooks — exportSave / resumeSession (Phase 3)', () => {
it('exportSave carries enough to reconstruct the exact same game', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
const push = session.connect(0 as PlayerIndex);
const actor = (push.menu !== null ? 0 : 1) as PlayerIndex;
const applied = session.intent(actor, 1, { type: 'localOps.choose', option: 'draw' });
assert.equal(applied.accepted, true);
const saved = session.exportSave();
assert.equal(saved.seed, 42);
assert.deepEqual(saved.playerNames, ['Alice', 'Bob']);
assert.equal(saved.history.length, 1);
assert.equal(saved.status, 'active');
assert.ok(saved.createdAt > 0, 'createdAt was not set');
const resumed = resumeSession(saved);
const before = session.connect(actor);
const after = resumed.connect(actor);
assert.deepEqual(after.frame, before.frame, 'resumeSession did not reconstruct the same board/state');
});
it('a resumed session keeps enforcing whose turn it is', () => {
const session = createSession(7, config, ['Alice', 'Bob']);
const push = session.connect(0 as PlayerIndex);
const actor = (push.menu !== null ? 0 : 1) as PlayerIndex;
session.intent(actor, 1, { type: 'localOps.choose', option: 'draw' });
const resumed = resumeSession(session.exportSave());
const notActor = (actor === 0 ? 1 : 0) as PlayerIndex;
const rejected = resumed.intent(notActor, 1, { type: 'draw.end' });
assert.equal(rejected.accepted, false);
if (!rejected.accepted) assert.equal(rejected.code, 'NOT_YOUR_TURN');
});
it('marks status finished only once the game actually is', () => {
const session = createSession(42, config, ['Alice', 'Bob']);
assert.equal(session.exportSave().status, 'active');
});
});
test/setup.test.ts
+13 -6
View File
@@ -34,8 +34,11 @@ import { subdivisions } from '../src/engine/state.ts';
const solitaireConfig: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'standard',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
@@ -299,12 +302,16 @@ describe('card catalogue (component 1)', () => {
}
});
it('uses the Gap 10e revised victory targets', () => {
it('keeps the three day-count presets sim/CLI tooling still relies on', () => {
// Gap 10e's fixed targets retired 2026-08-20 — `minCombinedRevenue` is a free `GameConfig`
// variable now, not a `length`-keyed lookup. `LENGTH_PROFILES` survives only as a convenience
// preset for tools that still want a short/standard/campaign argument (`harness.ts`, `compare.ts`,
// `replay.ts`).
assert.deepEqual(
LENGTH_PROFILES.map((p) => [p.target, p.days]),
[[10, 3], [20, 5], [45, 10]],
LENGTH_PROFILES.map((p) => [p.length, p.days]),
[['short', 3], ['standard', 5], ['campaign', 10]],
);
assert.equal(lengthProfile('standard').target, 20);
assert.equal(lengthProfile('standard').days, 5);
});
it('scales fixed supplies with player count', () => {
test/sim.test.ts
+22 -19
View File
@@ -22,8 +22,11 @@ import { anomalies, strategyBuckets } from '../src/sim/stats.ts';
const config: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'short',
days: 3,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: {
reducedVisibility: false,
sisterTrains: false,
@@ -155,7 +158,7 @@ describe('the revenue chain works end to end (regression)', () => {
// more cars in total (22 vs 19 over forty games). Widened so it fails for the reason it names.
let spotted = 0;
for (const seed of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]) {
const s = createGame({ id: 'g', seed, config: { ...config, length: 'standard' }, playerNames: ['bot'] });
const s = createGame({ id: 'g', seed, config: { ...config, days: 5 }, playerNames: ['bot'] });
playGame(s, developerBot, pump);
for (const card of s.officeAreas.get(0)!.grid.values()) {
if (card.facility?.kind === 'freight') spotted += card.facility.industryTrack.cars.length;
@@ -172,7 +175,7 @@ describe('the revenue chain works end to end (regression)', () => {
// the old 52-card placeholder it was 10 in 52.
let placed = 0;
for (const seed of [11, 23, 47, 91, 137, 211]) {
const s = createGame({ id: 'g', seed, config: { ...config, length: 'campaign' }, playerNames: ['bot'] });
const s = createGame({ id: 'g', seed, config: { ...config, days: 10 }, playerNames: ['bot'] });
playGame(s, developerBot, pump);
for (const card of s.officeAreas.get(0)!.grid.values()) {
if (card.geometry.kind !== 'facility') continue;
@@ -206,7 +209,7 @@ describe('the revenue chain works end to end (regression)', () => {
// "downward only" is gone, and with it the rule that rejected every square above row 0.
const rows = new Set<number>();
for (const seed of [3, 9, 27, 81]) {
const s = createGame({ id: 'g', seed, config: { ...config, length: 'campaign' }, playerNames: ['bot'] });
const s = createGame({ id: 'g', seed, config: { ...config, days: 10 }, playerNames: ['bot'] });
playGame(s, developerBot, pump);
for (const key of s.officeAreas.get(0)!.grid.keys()) rows.add(Number(key.split(',')[0]));
}
@@ -272,7 +275,7 @@ describe('the deck is closed — no card is created or destroyed', () => {
// Every card is in exactly one place: the Home Office deck, a Department pile, the Salvage Yard,
// a hand, or on the board — grid cells, enhancements laid on them, and Mainline modifiers.
for (const seed of [3, 17, 91]) {
const s = createGame({ id: `cc-${seed}`, seed, config: { ...config, length: 'standard' }, playerNames: ['bot'] });
const s = createGame({ id: `cc-${seed}`, seed, config: { ...config, days: 5 }, playerNames: ['bot'] });
const total = s.cards.size;
playGame(s, developerBot, pump);
@@ -294,7 +297,7 @@ describe('the deck is closed — no card is created or destroyed', () => {
// The sharper form of the same guard. A discard moves a card from a hand to a Department pile
// and a draw moves one back, so the count across deck + Departments + Salvage Yard + hands can
// only fall by cards actually placed on the board — never by one being overwritten.
const s = createGame({ id: 'cc', seed: 5, config: { ...config, length: 'standard' }, playerNames: ['bot'] });
const s = createGame({ id: 'cc', seed: 5, config: { ...config, days: 5 }, playerNames: ['bot'] });
const before = s.cards.size;
playGame(s, developerBot, pump);
const loose =
@@ -541,7 +544,7 @@ describe('the bot builds sidings that are actually sidings (regression)', () =>
const s = createGame({
id: `sd-${i}`,
seed: 1000 + i * 7919,
config: { ...config, length: 'standard' },
config: { ...config, days: 5 },
playerNames: ['bot'],
});
playGame(s, developerBot, pump);
@@ -639,7 +642,7 @@ describe('the bot builds sidings that are actually sidings (regression)', () =>
const s = createGame({
id: `cs-${i}`,
seed: 1000 + i * 7919,
config: { ...config, length: 'standard' },
config: { ...config, days: 5 },
playerNames: ['bot'],
});
const r = playGame(s, developerBot, pump);
@@ -723,7 +726,7 @@ describe('the bot does not throw away its own freight (regression)', () => {
const s = createGame({
id: `uj-${i}`,
seed: 1000 + i * 7919,
config: { ...config, length: 'standard' },
config: { ...config, days: 5 },
playerNames: ['bot'],
});
const r = playGame(s, developerBot, pump);
@@ -752,7 +755,7 @@ describe('the bot does not throw away its own freight (regression)', () => {
// The other half of the regression above. Gutting the fallback entirely would satisfy "never
// unjams a green box" while leaving a real jam to block the industry forever — a load stranded
// on WORK keeps the track locked, which now stops trains passing as well as stopping (§9.3).
const s = createGame({ id: 'jam', seed: 5, config: { ...config, length: 'standard' }, playerNames: ['bot'] });
const s = createGame({ id: 'jam', seed: 5, config: { ...config, days: 5 }, playerNames: ['bot'] });
const area = s.officeAreas.get(0)!;
area.grid.set('-1,0', {
geometry: { kind: 'facility', facility: 'mineTipple' },
@@ -797,7 +800,7 @@ describe('Enhancements can reach the board at all (regression)', () => {
const s = createGame({
id: `st-${i}`,
seed: 1000 + i * 7919,
config: { ...config, length: 'standard' },
config: { ...config, days: 5 },
playerNames: ['bot'],
});
playGame(s, developerBot, pump);
@@ -834,7 +837,7 @@ describe('Enhancements can reach the board at all (regression)', () => {
const s = createGame({
id: `il-${i}`,
seed: 1000 + i * 7919,
config: { ...config, length: 'standard' },
config: { ...config, days: 5 },
playerNames: ['bot'],
});
playGame(s, developerBot, pump);
@@ -872,7 +875,7 @@ describe('rolling stock returns to service (regression)', () => {
const s = createGame({
id: 'refill',
seed: 4,
config: { ...config, length: 'standard' },
config: { ...config, days: 5 },
playerNames: ['bot'],
});
@@ -911,7 +914,7 @@ describe('measurement discipline', () => {
// the observer hook cannot drift from the log, so probes have one trustworthy way in and no
// reason to hand-roll the drive loop again.
const seen: string[] = [];
const s = createGame({ id: 'obs', seed: 4242, config: { ...config, length: 'standard' }, playerNames: ['b'] });
const s = createGame({ id: 'obs', seed: 4242, config: { ...config, days: 5 }, playerNames: ['b'] });
const out = playGame(s, developerBot, pump, 50_000, (e) => seen.push(e.type));
assert.ok(out.events.length > 0, 'a finished game must produce events');
@@ -923,7 +926,7 @@ describe('measurement discipline', () => {
// Asserted across several seeds because a single game may never draw a Depot card.
let upgrades = 0;
for (let seed = 0; seed < 25; seed++) {
const s = createGame({ id: `u${seed}`, seed, config: { ...config, length: 'standard' }, playerNames: ['b'] });
const s = createGame({ id: `u${seed}`, seed, config: { ...config, days: 5 }, playerNames: ['b'] });
const out = playGame(s, developerBot, pump);
upgrades += out.events.filter((e) => e.type === 'officeUpgraded').length;
}
@@ -943,7 +946,7 @@ describe('the bot does not lay track that cannot work (regression)', () => {
const s = createGame({
id: `lay-${seed}`,
seed,
config: { ...config, length: 'standard' },
config: { ...config, days: 5 },
playerNames: ['Solitaire'],
});
const laid: Lay[] = [];
@@ -996,7 +999,7 @@ describe('the bot does not lay track that cannot work (regression)', () => {
for (const seed of SEEDS) {
const s = createGame({
id: `dp-${seed}`, seed,
config: { ...config, length: 'standard' },
config: { ...config, days: 5 },
playerNames: ['Solitaire'],
});
const spy = {
@@ -1085,7 +1088,7 @@ describe('the freight figures count both halves (regression)', () => {
const seed = 1000 + i * 7919;
const s = createGame({
id: `fu-${seed}`, seed,
config: { ...config, length: 'standard' },
config: { ...config, days: 5 },
playerNames: ['bot'],
});
const r = playGame(s, developerBot, pump);
test/track.test.ts
+11 -1
View File
@@ -128,7 +128,7 @@ function gameWith(area: OfficeArea): GameState {
const s = createGame({
id: 'g', seed: 5,
config: {
mode: 'solitaire', victory: 'highestAfterDays', length: 'standard',
mode: 'solitaire', days: 5, minCombinedRevenue: 0, maxCollisionsPerDay: 0, maxCollisionsTotal: 0, pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
},
playerNames: ['p'],
@@ -563,6 +563,16 @@ describe('placement and drop-off', () => {
assert.ok(canDropCarsAt(area, at(0, 1)), 'ordinary Operational Rail');
});
it('allows a coach, and only a coach, to be dropped at the Office (v0.5.0 §A.4 exception)', () => {
const area = areaFrom(
{ [coordKey(at(0, 0))]: officeCard(), [coordKey(at(0, 1))]: straight() },
at(0, 0),
);
assert.ok(!canDropCarsAt(area, at(0, 0), 1, false), 'not asking for the coach exception');
assert.ok(canDropCarsAt(area, at(0, 0), 1, true), 'one coach');
assert.ok(canDropCarsAt(area, at(0, 0), 2, true), 'more than one coach');
});
it('forbids dropping cars on a locked industry track', () => {
const area = areaFrom(
{
test/train-rules.test.ts
+43 -5
View File
@@ -19,8 +19,11 @@ import { trainRules } from '../src/sim/view.ts';
const config: GameConfig = {
mode: 'solitaire',
victory: 'highestAfterDays',
length: 'standard',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
};
const game = (seed = 5): GameState => createGame({ id: 'g', seed, config, playerNames: ['p'] });
@@ -46,9 +49,9 @@ function switching(
): string {
const area = areaOf(s, 0);
const office = area.officeCoord;
// The crew stands one square west of the Office and works westward. It may NOT stand on the Office
// itself: §A.4 forbids leaving Rolling Stock on the Office track, so every drop there is refused
// whatever the train's own card says.
// The crew stands one square west of the Office and works westward, away from the Office square's
// own special-cased drop rule (§A.4 forbids everything but a coach there, v0.5.0) — tests that want
// that exception exercise it directly instead.
const here = { row: office.row, col: office.col - 1 };
area.grid.set(coordKey(here), straight());
area.grid.set(coordKey({ row: office.row, col: office.col - 2 }), straight(westCars));
@@ -202,6 +205,41 @@ describe('§7 — the Local keeps its coach (trains 7/8)', () => {
switching(s, 9, false, [boxcar(), coach()]);
assert.equal(check(s, 0, { type: 'switch.dropCars', trayId: 't', count: 1 }), null);
});
it('may set the coach out at the Office — the one place §A.4 now allows it (v0.5.0)', () => {
const s = game();
const area = areaOf(s, 0);
const office = area.officeCoord;
s.trays.set('t', {
id: 't',
trainNumber: 7,
trainIsExtra: false,
engineAt: 0,
consist: [boxcar(), coach()],
direction: 'west',
facing: 'w',
position: { at: 'grid', seat: 0, coord: office },
movesUsed: 0,
});
s.clock.phase = 'localOps';
s.clock.currentActor = 0;
turnOf(s, 0).option = 'switch';
turnOf(s, 0).movesRemaining = 6;
assert.equal(
check(s, 0, { type: 'switch.dropCars', trayId: 't', count: 1 }),
null,
'the coach may be cut loose at the Office',
);
assert.ok(applyIntent(s, 0, { type: 'switch.dropCars', trayId: 't', count: 1 }).ok);
const officeCard = area.grid.get(coordKey(office))!;
assert.deepEqual(
officeCard.standing.map((c) => c.type),
['coach'],
'the coach is parked on the Office card',
);
assert.equal(s.trays.get('t')!.consist.length, 1, 'the coach left the tray');
});
});
describe('§7 — trains Porters may not work', () => {
test/web.test.ts
+333 -46
View File
@@ -42,7 +42,21 @@ import {
} from '../src/web/game.ts';
const root = join(import.meta.dirname, '..');
/**
* `dist/` is built once by the `pretest` npm script (`scripts/build-web.ts`), before `node --test`
* ever starts — every test below that reads `dist` assumes it is already complete, not that some
* other test in this file built it. `npm run test` directly (skipping `npm test`'s `pretest` hook)
* will not have run it.
*/
const dist = join(root, 'dist');
/**
* A directory the actual "run the build command" test below builds into, kept separate from the
* shared `dist/` above. Two suites racing to write and read the SAME `dist/` — the build command
* doing a full `rmSync` + rebuild while other tests in this file read it mid-run — used to fail 9
* times in one measured run and 0 the next. `dist/` is now single-writer (`pretest`, once, before
* anything reads it); this directory is the ONLY thing the build-command test itself may touch.
*/
const distTest = join(root, 'dist-test');
/** Play a whole game by always taking the first offered action. */
function playThrough(seed: number, maxTurns = 20_000) {
@@ -764,15 +778,30 @@ describe('the board draws the printed card (docs/tracks.png)', () => {
.map((m) => ({ x1: Number(m[1]), y1: Number(m[2]), x2: Number(m[3]), y2: Number(m[4]) }));
};
/** Undirected segment angles in degrees, deduplicated. 0 is horizontal. */
const angles = (links: string[]): number[] => [
...new Set(
draw(links).map((r) => {
const a = (Math.atan2(r.y2 - r.y1, r.x2 - r.x1) * 180) / Math.PI;
return Math.round((((a % 180) + 180) % 180) * 10) / 10;
/**
* A 45° leg is a curved `<path>` now (v0.5.0), not straight `<line>`s — see `curvedRail` in
* `board-svg.ts`. Each returned array is the sampled polyline for one of the leg's two rails, in
* order from the through edge to the diagonal edge.
*/
const drawCurve = (links: string[]): { x: number; y: number }[][] => {
const cell = {
row: 0, col: 0, kind: 'trk', label: 'x', running: true, enhancements: [], enhancementsWhat: [],
trains: [], adTracks: null, cars: [], standingWest: 0, facility: null, links, what: '',
};
const svg = officeSvg([cell] as never, 0);
return [...svg.matchAll(/<path class="bs-rail" fill="none" d="M([^"]+)"\/>/g)].map((m) =>
m[1]!.split(' L').map((pair) => {
const [x, y] = pair.trim().split(' ').map(Number);
return { x: x!, y: y! };
}),
),
].sort((a, b) => a - b);
);
};
/** Undirected angle in degrees between two points, 0–180. */
const angleOf = (a: { x: number; y: number }, b: { x: number; y: number }): number => {
const deg = (Math.atan2(b.y - a.y, b.x - a.x) * 180) / Math.PI;
return ((deg % 180) + 180) % 180;
};
it('runs the through track dead centre, edge to edge', () => {
// The measurement from the printed sheet: on every one of its nine rows the east-west rail sits
@@ -788,36 +817,46 @@ describe('the board draws the printed card (docs/tracks.png)', () => {
}
});
it('leaves at exactly 45°, through the middle of the north or south edge', () => {
it('leaves the through edge level and the diagonal edge at 45°, curved rather than kinked', () => {
// The TRUE tangent is exactly 0° at the through edge and exactly 45°/135° at the diagonal edge —
// that is what the curve's control points are chosen to hit (see `curvedRail`'s call site). What
// is rendered is a sampled polyline, so the first and last drawn segment only APPROXIMATE that
// limit; a few degrees off at the sample count in use, well inside the tolerance below.
for (const links of [['ne'], ['nw'], ['se'], ['sw'], ['ew', 'ws'], ['ew', 'en']]) {
const found = angles(links);
assert.ok(found.includes(0), `${links} has no level run along the centre line`);
assert.ok(
found.includes(45) || found.includes(135),
`${links} draws its leg at ${found.join('/')}° — the card prints 45°`,
);
assert.equal(found.length, 2, `${links} draws ${found.join('/')}° — a leg is a run and one 45° angle`);
const [rail] = drawCurve(links);
assert.ok(rail && rail.length > 2, `${links} drew no curved leg`);
const start = angleOf(rail[0]!, rail[1]!);
const end = angleOf(rail[rail.length - 2]!, rail[rail.length - 1]!);
assert.ok(start <= 6 || start >= 174, `${links} leaves the through edge at ${start}°, not level`);
const offDiagonal = Math.min(Math.abs(end - 45), Math.abs(end - 135));
assert.ok(offDiagonal <= 6, `${links} meets the diagonal edge at ${end}°, not 45°/135°`);
}
});
it('draws the two diagonals as two different diagonals', () => {
// The matching rule made visible. `ne` and `sw` lie on one line and `nw` and `se` on the other,
// so a stacked pair on the same diagonal reads as one unbroken rail and a mismatched pair reads
// as the V it is. Drawn alike, the picture would claim a join the engine refuses.
assert.deepEqual(angles(['ne']), angles(['sw']), 'ne and sw must lie on the same diagonal');
assert.deepEqual(angles(['nw']), angles(['se']), 'nw and se must lie on the same diagonal');
assert.notDeepEqual(angles(['ne']), angles(['nw']), 'the two diagonals must be distinguishable');
// so a stacked pair on the same diagonal reads as one continuous curve and a mismatched pair
// reads as the V it is. Drawn alike, the picture would claim a join the engine refuses.
const family = (links: string[]): 'rising' | 'falling' => {
const [rail] = drawCurve(links);
const end = angleOf(rail![rail!.length - 2]!, rail![rail!.length - 1]!);
return Math.abs(end - 45) < Math.abs(end - 135) ? 'rising' : 'falling';
};
assert.equal(family(['ne']), family(['sw']), 'ne and sw must lie on the same diagonal');
assert.equal(family(['nw']), family(['se']), 'nw and se must lie on the same diagonal');
assert.notEqual(family(['ne']), family(['nw']), 'the two diagonals must be distinguishable');
});
it('meets the card edge at its midpoint, so abutting cards line up', () => {
// A leg that met the edge anywhere else would join to nothing, however right its angle.
// A leg that met the edge anywhere else would join to nothing, however right its angle. Exact,
// not approximate: the curve's LAST sampled point is always the true edge point (`edge` in
// `curvedRail`'s call site, not a discretised approximation of it), so averaging the two rails'
// endpoints cancels their perpendicular offset exactly, the same way it did when the leg was two
// straight segments.
const W = 166;
const H = 96;
// Only the sloping segments, and only the end of each that lands on the south edge.
const atEdge = draw(['sw'])
.filter((r) => r.y1 !== r.y2)
.map((r) => (Math.abs(r.y1 - H) < Math.abs(r.y2 - H) ? r.x1 : r.x2));
assert.equal(atEdge.length, 2, 'the leg is two rails');
const rails = drawCurve(['sw']);
assert.equal(rails.length, 2, 'the leg is two rails');
const atEdge = rails.map((r) => r[r.length - 1]!.x);
const mid = (atEdge[0]! + atEdge[1]!) / 2;
assert.ok(Math.abs(mid - W / 2) < 0.5, `the leg crosses the south edge at x=${mid}, not the middle (${W / 2})`);
});
@@ -1171,10 +1210,12 @@ describe('the page explains itself', () => {
});
it('states the objective and whether you are keeping up', () => {
// SOLO_CONFIG's minCombinedRevenue is collectiveRevenueFloor(1, 5) = 15 (game.ts) — the old
// fixed target of 20 retired 2026-08-20 with the victory-condition redesign.
const f = view(newGame(430));
assert.equal(f.objective.target, 20);
assert.equal(f.objective.target, 15);
assert.equal(f.objective.days, 5);
assert.match(f.objective.note, /of 20/);
assert.match(f.objective.note, /of 15/);
assert.match(f.objective.note, /Days? left/);
});
@@ -1325,11 +1366,17 @@ describe('replays are saves', () => {
describe('the static build', () => {
it('builds, and needs nothing but a static host', () => {
execFileSync('node', ['scripts/build-web.ts'], { cwd: root, stdio: 'pipe' });
// Its OWN directory (`dist-test/`), not the shared `dist/` every other test in this file reads
// — see the comment on `distTest` above.
execFileSync('node', ['scripts/build-web.ts'], {
cwd: root,
stdio: 'pipe',
env: { ...process.env, BUILD_DIST_DIR: 'dist-test' },
});
assert.ok(existsSync(join(dist, 'index.html')), 'no index.html');
assert.ok(existsSync(join(dist, 'web/main.js')), 'no entry script');
assert.ok(existsSync(join(dist, 'engine/apply.js')), 'the engine did not emit');
assert.ok(existsSync(join(distTest, 'index.html')), 'no index.html');
assert.ok(existsSync(join(distTest, 'web/main.js')), 'no entry script');
assert.ok(existsSync(join(distTest, 'engine/apply.js')), 'the engine did not emit');
});
it('emits no import that a browser cannot resolve', () => {
@@ -1579,6 +1626,173 @@ describe('the static build', () => {
);
});
it('remembers auto-focus, sound and zoom across a reload, separately from the save', async () => {
// A lighter DOM stub than the highlight test above — this never touches board highlighting or
// action buttons, only the settings-bearing elements and `localStorage` itself.
const els = new Map<string, Record<string, unknown>>();
const injected: Record<string, unknown>[] = [];
const make = (): Record<string, unknown> => {
let html = '';
const listeners = new Map<string, ((e?: unknown) => void)[]>();
const ownClasses = new Set<string>();
const node: Record<string, unknown> = {
textContent: '', style: {}, dataset: {}, onclick: null, disabled: false,
title: '', returnValue: '', open: false,
addEventListener: (type: string, fn: (e?: unknown) => void) =>
void listeners.set(type, [...(listeners.get(type) ?? []), fn]),
showModal() {
(node as { open: boolean }).open = true;
},
close(value?: string) {
(node as { open: boolean; returnValue: string }).open = false;
if (value !== undefined) (node as { returnValue: string }).returnValue = value;
for (const fn of listeners.get('close') ?? []) fn();
},
classList: {
add: (c: string) => void ownClasses.add(c),
remove: (c: string) => void ownClasses.delete(c),
contains: (c: string) => ownClasses.has(c),
toggle: (c: string) => (ownClasses.has(c) ? ownClasses.delete(c) : ownClasses.add(c)),
},
// No real `<svg>` child: `applyZoom` looks for one, finds none on this stub, and no-ops —
// the same way it does on a board card the stub never renders. Sizing the actual SVG needs a
// real DOM (jsdom or a browser), which this test suite does not carry; what IS checked here —
// the persisted setting, the button labels, the click wiring — is everything observable
// without one. `querySelectorAll` empty rather than absent: several unrelated render steps
// (crew markers, hand buttons, department piles) iterate whatever their element returns.
querySelector: () => null,
querySelectorAll: () => [],
};
Object.defineProperty(node, 'innerHTML', {
get: () => html,
set: (v: string) => void (html = v),
});
return node;
};
const served = new Set(
[...readFileSync(join(dist, 'play.html'), 'utf8').matchAll(/id="([a-zA-Z][\w-]*)"/g)].map(
(m) => m[1]!,
),
);
const g = globalThis as Record<string, unknown>;
g['document'] = {
getElementById: (id: string) => {
if (!served.has(id)) return null;
if (!els.has(id)) els.set(id, make());
return els.get(id);
},
createElement: () => make(),
addEventListener: () => {},
body: { appendChild: () => {} },
head: { appendChild: (node: Record<string, unknown>) => void injected.push(node) },
};
g['location'] = { search: '?seed=555' };
const store = new Map<string, string>();
// Seeded BEFORE import: settings load once, at module top level, from whatever is already there.
store.set(
'station-master.settings.v1',
JSON.stringify({ districtMode: 'open', soundOn: true, zoom: 1.25 }),
);
g['localStorage'] = {
getItem: (k: string) => store.get(k) ?? null,
setItem: (k: string, v: string) => void store.set(k, v),
removeItem: (k: string) => void store.delete(k),
};
g['URLSearchParams'] = class {
search: string;
constructor(search: string) {
this.search = search;
}
get(k: string): string | null {
return new RegExp(`${k}=([^&]*)`).exec(this.search)?.[1] ?? null;
}
};
await import(`file://${join(dist, 'web/main.js')}?t=${Date.now()}`);
// The seeded settings took effect on load, before any click.
assert.match(String(els.get('sound')!['textContent']), /sound/, 'sound started ON, as seeded');
assert.equal(els.get('zoomlabel')!['textContent'], '125%', 'zoom started at the seeded level');
// Zooming in from 125% goes to 150% and persists; the button disables at the top of the range.
(els.get('zoomin')!['onclick'] as () => void)();
assert.equal(els.get('zoomlabel')!['textContent'], '150%');
assert.equal(els.get('zoomin')!['disabled'], true, 'already at the highest preset');
assert.equal(
(JSON.parse(store.get('station-master.settings.v1')!) as { zoom: number }).zoom,
1.5,
'the new zoom level was written back to localStorage',
);
// Muting persists too, independently of zoom.
(els.get('sound')!['onclick'] as () => void)();
assert.match(String(els.get('sound')!['textContent']), /muted/);
assert.equal(
(JSON.parse(store.get('station-master.settings.v1')!) as { soundOn: boolean }).soundOn,
false,
);
});
it('falls back to the defaults when settings are missing or corrupt, rather than throwing', async () => {
const els = new Map<string, Record<string, unknown>>();
const make = (): Record<string, unknown> => {
const node: Record<string, unknown> = {
textContent: '', style: {}, dataset: {}, onclick: null, disabled: false,
title: '', returnValue: '', open: false,
addEventListener: () => {},
showModal() {},
close() {},
classList: { add: () => {}, remove: () => {}, contains: () => false, toggle: () => {} },
querySelector: () => null,
querySelectorAll: () => [],
};
let html = '';
Object.defineProperty(node, 'innerHTML', { get: () => html, set: (v: string) => void (html = v) });
return node;
};
const served = new Set(
[...readFileSync(join(dist, 'play.html'), 'utf8').matchAll(/id="([a-zA-Z][\w-]*)"/g)].map(
(m) => m[1]!,
),
);
const g = globalThis as Record<string, unknown>;
g['document'] = {
getElementById: (id: string) => {
if (!served.has(id)) return null;
if (!els.has(id)) els.set(id, make());
return els.get(id);
},
createElement: () => make(),
addEventListener: () => {},
body: { appendChild: () => {} },
head: { appendChild: () => {} },
};
g['location'] = { search: '?seed=556' };
g['localStorage'] = {
// Neither a JSON parse error nor a thrown access should reach the page — a full or disabled
// localStorage must not take the game down with it, the same guard the save already has.
getItem: () => {
throw new Error('storage disabled');
},
setItem: () => {},
removeItem: () => {},
};
g['URLSearchParams'] = class {
search: string;
constructor(search: string) {
this.search = search;
}
get(k: string): string | null {
return new RegExp(`${k}=([^&]*)`).exec(this.search)?.[1] ?? null;
}
};
await import(`file://${join(dist, 'web/main.js')}?t=${Date.now()}`);
assert.match(String(els.get('sound')!['textContent']), /muted/, 'sound defaults OFF');
assert.equal(els.get('zoomlabel')!['textContent'], '100%', 'zoom defaults to 100%');
});
it('busts the cache on every module, so a deploy cannot half-load', () => {
// The first real deploy served a fresh index.html against a CACHED main.js: the HTML had
// dropped an element the old script still asked for, so the page threw `missing element:
@@ -2318,8 +2532,11 @@ describe('the Division map shows the whole route', () => {
seed: 7,
config: {
mode: players === 1 ? 'solitaire' : 'competitive',
victory: 'highestAfterDays',
length: 'standard',
days: 5,
minCombinedRevenue: 0,
maxCollisionsPerDay: 0,
maxCollisionsTotal: 0,
pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
},
playerNames: ['A', 'B', 'C', 'D'].slice(0, players),
@@ -2334,7 +2551,7 @@ describe('the Division map shows the whole route', () => {
id: 'div-run',
seed: 7,
config: {
mode: 'solitaire', victory: 'highestAfterDays', length: 'standard',
mode: 'solitaire', days: 5, minCombinedRevenue: 0, maxCollisionsPerDay: 0, maxCollisionsTotal: 0, pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
},
playerNames: ['Solitaire'],
@@ -2387,7 +2604,7 @@ describe('the Division map shows the whole route', () => {
const s = createEngineGame({
id: 'div-chips', seed: 7,
config: {
mode: 'solitaire', victory: 'highestAfterDays', length: 'standard',
mode: 'solitaire', days: 5, minCombinedRevenue: 0, maxCollisionsPerDay: 0, maxCollisionsTotal: 0, pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
},
playerNames: ['Solitaire'],
@@ -2716,7 +2933,7 @@ describe('the tray is an engine plus its Rolling Stock', () => {
const s = createEngineGame({
id: 'eng', seed: 1038389,
config: {
mode: 'solitaire', victory: 'highestAfterDays', length: 'standard',
mode: 'solitaire', days: 5, minCombinedRevenue: 0, maxCollisionsPerDay: 0, maxCollisionsTotal: 0, pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
},
playerNames: ['Solitaire'],
@@ -2766,7 +2983,7 @@ describe('the tray is an engine plus its Rolling Stock', () => {
const s = createEngineGame({
id: 'yards', seed: 1038389,
config: {
mode: 'solitaire', victory: 'highestAfterDays', length: 'standard',
mode: 'solitaire', days: 5, minCombinedRevenue: 0, maxCollisionsPerDay: 0, maxCollisionsTotal: 0, pvpCardsAllowed: false,
optionalRules: { reducedVisibility: false, sisterTrains: false, employeeRotation: false, emergencyToolbox: false },
},
playerNames: ['Solitaire'],
@@ -2818,12 +3035,21 @@ describe('the New Game dialog', () => {
value,
checked: false,
}));
// The mode radios are real DOM inputs, so `onchange` has to actually fire when a test flips
// `checked` — `applyModePreset` is wired to it, not polled.
const modeRadios = ['solitaire', 'competitive', 'coop'].map((value) => ({
value,
checked: value === 'solitaire',
onchange: null as (() => void) | null,
}));
let html = '';
const node: Record<string, unknown> = {
id, value: '', textContent: '', title: '', returnValue: '', open: false,
style: {}, dataset: {}, onclick: null, scrollTop: 0, scrollHeight: 0,
checked: false, disabled: false,
classList: { add: () => {}, remove: () => {}, contains: () => false, toggle: () => {} },
radios,
modeRadios,
addEventListener: (type: string, fn: () => void) =>
void listeners.set(type, [...(listeners.get(type) ?? []), fn]),
showModal: () => void ((node as { open: boolean }).open = true),
@@ -2833,9 +3059,14 @@ describe('the New Game dialog', () => {
},
// Only the radio-group selectors the dialog actually uses; anything else is not this
// element's business and answering it with a guess would hide a typo in the real selector.
querySelectorAll: (sel: string) => (sel === 'input[name="ng-hand"]' ? radios : []),
querySelectorAll: (sel: string) =>
sel === 'input[name="ng-hand"]' ? radios : sel === 'input[name="ng-mode"]' ? modeRadios : [],
querySelector: (sel: string) =>
sel === 'input[name="ng-hand"]:checked' ? (radios.find((r) => r.checked) ?? null) : null,
sel === 'input[name="ng-hand"]:checked'
? (radios.find((r) => r.checked) ?? null)
: sel === 'input[name="ng-mode"]:checked'
? (modeRadios.find((r) => r.checked) ?? null)
: null,
};
Object.defineProperty(node, 'innerHTML', { get: () => html, set: (v: string) => void (html = v) });
return node;
@@ -2888,6 +3119,53 @@ describe('the New Game dialog', () => {
assert.deepEqual(checked.map((r) => r.value), ['sixRandom'], 'the opening hand in play was not preselected');
});
it('always reopens on Solitaire, Deal enabled, PvP forced off — the only mode a prior game could be', async () => {
const { els } = await load('?seed=430');
(els.get('newgame')!['onclick'] as () => void)();
const dlg = els.get('newgamedlg')!;
const modeRadios = dlg['modeRadios'] as { value: string; checked: boolean }[];
assert.deepEqual(
modeRadios.filter((r) => r.checked).map((r) => r.value),
['solitaire'],
'the dialog did not reopen on Solitaire',
);
assert.equal(els.get('ng-deal')!['disabled'], false, 'Deal was disabled for the one dealable mode');
assert.equal(els.get('ng-pvp')!['checked'], false, 'PvP defaulted on for Solitaire');
assert.equal(els.get('ng-pvp')!['disabled'], true, "Solitaire's PvP checkbox was left editable");
});
it('picking Competitive suggests a 4-player floor, turns PvP on, and disables Deal', async () => {
const { els } = await load('?seed=430');
(els.get('newgame')!['onclick'] as () => void)();
const dlg = els.get('newgamedlg')!;
const modeRadios = dlg['modeRadios'] as { value: string; checked: boolean; onchange: (() => void) | null }[];
const competitive = modeRadios.find((r) => r.value === 'competitive')!;
for (const r of modeRadios) r.checked = r === competitive;
competitive.onchange!();
assert.equal(els.get('ng-minrev')!['value'], '60', 'the suggested floor is not 3 * 4 players * 5 days');
assert.equal(els.get('ng-pvp')!['checked'], true, 'Competitive did not default PvP on');
assert.equal(els.get('ng-pvp')!['disabled'], false, "Competitive's PvP checkbox was left disabled");
assert.equal(els.get('ng-deal')!['disabled'], true, 'Deal was enabled for a mode with nowhere to go yet');
});
it('picking Co-op forces PvP off — no valid target for those cards when everyone is on one side', async () => {
const { els } = await load('?seed=430');
(els.get('newgame')!['onclick'] as () => void)();
const dlg = els.get('newgamedlg')!;
const modeRadios = dlg['modeRadios'] as { value: string; checked: boolean; onchange: (() => void) | null }[];
const coop = modeRadios.find((r) => r.value === 'coop')!;
for (const r of modeRadios) r.checked = r === coop;
coop.onchange!();
assert.equal(els.get('ng-pvp')!['checked'], false, 'Co-op defaulted PvP on');
assert.equal(els.get('ng-pvp')!['disabled'], true, "Co-op's PvP checkbox was left editable");
assert.equal(els.get('ng-deal')!['disabled'], true, 'Deal was enabled for a mode with nowhere to go yet');
});
it('puts the seed and all three settings into the URL when it deals', async () => {
const { els, nav } = await load('?seed=430');
(els.get('newgame')!['onclick'] as () => void)();
@@ -2901,7 +3179,10 @@ describe('the New Game dialog', () => {
dlg['returnValue'] = 'deal';
(dlg['close'] as () => void)();
assert.equal(nav.search, '?seed=99&hand=threeTrackThreeOther&passenger=5&freight=0&transit=2');
assert.equal(
nav.search,
'?seed=99&hand=threeTrackThreeOther&passenger=5&freight=0&transit=2&days=5&minrev=15&colday=3&coltotal=5',
);
});
it('deals nothing on cancel, and nothing on Esc', async () => {
@@ -2920,8 +3201,10 @@ describe('the New Game dialog', () => {
it('reloads when the answers are the URL the page already has, so a re-deal is not a no-op', async () => {
// Dealing a random seed, disliking it and dealing again at the same settings produces the same
// search string — and assigning `location.search` the value it already holds does nothing.
const url = '?hand=threeRandom&passenger=1&freight=1&transit=0';
// search string — and assigning `location.search` the value it already holds does nothing. Spells
// out the victory dials explicitly (rather than leaving them to default) so the URL Deal produces
// is byte-identical to the one the page loaded with.
const url = '?hand=threeRandom&passenger=1&freight=1&transit=0&days=5&minrev=15&colday=3&coltotal=5';
const { els, nav } = await load(url);
(els.get('newgame')!['onclick'] as () => void)();
const dlg = els.get('newgamedlg')!;
@@ -2950,7 +3233,11 @@ describe('the New Game dialog', () => {
dlg['returnValue'] = 'deal';
(dlg['close'] as () => void)();
assert.equal(nav.search, '?hand=threeRandom&passenger=1&freight=1&transit=0', 'a bad seed was carried into the URL');
assert.equal(
nav.search,
'?hand=threeRandom&passenger=1&freight=1&transit=0&days=5&minrev=15&colday=3&coltotal=5',
'a bad seed was carried into the URL',
);
});
});