v0.7.0 — four game types, a lobby you can read and leave, and a multiplayer game that makes a sound

The multiplayer set-up, the lobby, the start of a game, and four signals a remote client had never
been sent. Reasoning, the preset table and what was verified how: CHANGELOG.md.

- Co-op, Competitive, Cutthroat, Solitaire and Custom, on both screens, from one shared block —
  they had drifted, and each was missing a question the other asked.
- A player reads the whole rule set before taking a seat, may leave a lobby or a running game, and
  keeps a seat across a reload. The host may clear a chair. The browser remembers every game it is
  in, not just the last one.
- The start of a game is drawn: a handoff beat, an announcement, the code and type in the header.
- Sound, the timetable flash, announcements and the just-drawn badge now reach a remote client;
  justDrawn goes to the seat that drew it and nobody else.
- Played on StartOS, which found the rest: an Extra belongs to the player who played it, the board
  never named the Superintendent, bot seats were reported as absent players, and rule section
  numbers are out of every string a player reads.

Also carries the previous session's Heavy Grade documentation work — asked again, answer unchanged.

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

docs/StationMaster-Mainline-Deck-v0.4.5.md

@@ -38,7 +38,7 @@ The PDF art labels this card “Yard”; this reference uses the implementation
 | Plains | 60 mph; one Stage for Fast, two for Slow. The implementation has one Plains *type* rather than the PDF’s two physical copies. |
 | Curves | 30 mph; two Stages for Fast, three for Slow. |
 | Hilly | Passenger train: 60 mph. Freight-only train: 30 mph. Add one Stage if Slow. |
-| Heavy Grade | Starts at 30 mph; two Stages for Fast, three for Slow. The card requires the player to select its uphill direction; v0.4.5 instead selects that direction from the game seed during setup. Grade modifiers can reduce the time, to a minimum of one Stage. |
+| Heavy Grade | Starts at 30 mph; two Stages for Fast, three for Slow. The card prints “Player sets orientation”; **the game deliberately overrides that and rolls the uphill direction from the seed** — settled in v0.5.0 and re-confirmed 2026-08-23, see the note below. Grade modifiers can reduce the time, to a minimum of one Stage. |
 | Double Track | 60 mph. Printed capability: trains may pass. The traffic-resolution rule is in Rules §4.5. |
 | Uncontrolled Siding | 60 mph. Printed capability: trains may pass. The traffic-resolution rule is in Rules §4.5. |
 | Tunnel | 30 mph. |
@@ -70,6 +70,16 @@ For the grade cards, “uphill” should be the direction selected by the player
 
 ## What is not implemented
 
-- There is no finite draw pile, player choice, or physical placement interaction for Mainline cards; setup selects their types automatically from the seeded random stream.
+- There is no player choice or physical placement interaction for Mainline cards; setup deals them automatically from the seeded random stream. There **is** a finite draw pile as of v0.6.2 — the deck above, dealt without replacement, so no Division can hold two of a card printed once.
 - Interchange is catalogued as a “sort cars” card, but v0.4.5 has no operation that reorders a train on the Interchange. The Small Yard in an Office Area is the implemented sorting mechanism.
-- Heavy Grade orientation is seeded automatically rather than chosen by a player. The implementation needs a player-selection step to match the card.
+- Interchange now has one player-facing use: an Extra Train may be **started** there, made up in its yard and highballing onto the Mainline when the Subdivision is clear (§7, v0.6.2). Car sorting remains unimplemented.
+
+## Heavy Grade orientation is settled, not missing
+
+Heavy Grade orientation is rolled from the seed rather than chosen by a player. **This is a decision, not a gap, and it is not awaiting a player-selection step.**
+
+The card prints “(Up)” and “Player sets orientation”, which assumes the card has an owner. This one does not: `buildDivision` lays the Division as `DP · Mainline · Office · Mainline · … · DP`, so a Heavy Grade always sits **between two districts**, or beyond an end Division Point next to one — never inside a single player’s own district.
+
+Orientation is not cosmetic: Brakeman and Airbrakes each take a Stage off a train running **downhill**, Helpers takes one off a train running **uphill**, and odd-numbered trains run west while even run east. Turning the card around therefore decides which of those modifier cards are worth anything and which direction of traffic is favoured — permanently, for the whole game. Handing that to one of the two neighbours advantages them over the other, and no player has a fair claim to it.
+
+**Re-opened and closed again on 2026-08-23**, when the option of giving the choice to the Superintendent was considered and rejected. Jesse’s call: v0.5.0’s ruling stands. Rolling from the seed is deterministic, roughly even (51/49 east/west over 400 games), identical for solitaire and multiplayer, and keeps setup non-interactive — the game has no setup phase, so the question would have to interrupt play before the first Local Operations, in the minority of games that deal the card at all (20% at one player, rising to 50% at four).

docs/architecture/lobby-and-sessions.md

@@ -44,8 +44,10 @@ Real accounts can be layered on later without touching the rules engine, which i
 ## 2. Creating and joining
 
 ```
-Lobby.Create { secret, config }            →  { gameId, gameCode, token }
-Lobby.Join   { secret, gameCode, displayName }  →  { token, player }
+Lobby.Create  { secret, config, displayName, players, seed }  →  { gameId, gameCode, token, player }
+Lobby.Preview { secret, gameCode }                            →  { gameCode, hostName, config, players, seated }
+Lobby.Join    { secret, gameCode, displayName }               →  { gameId, gameCode, token, player }
+Lobby.Leave   { token, seat? }                                →  { ok, closed? }
 ```
 
 **These four messages are the one family with no types behind them**, because the engine has no
@@ -60,7 +62,28 @@ per-origin, alongside the token.
 
 A **game code** — short, human-speakable, e.g. `RAIL-4471` — is the discovery mechanism *inside* the
 door. No matchmaking, no browsing, no public game list. Players are already talking to each other; the
-code just needs to survive being read aloud.
+code just needs to survive being read aloud. The seating screen also offers it as an invite **link**
+(`…/play.html?lobby&code=RAIL-4471`), which is what a chat message wants — the link carries the code
+and never the join secret, because the secret is the door key and travels out of band by design.
+
+**A player reads the rules before taking a chair.** `Lobby.Preview` answers the same join secret with
+the whole config, the host's name and who is seated, and takes no seat — added 2026-08-23, when the
+alternative was sitting down blind and (until the same pass) having no way back out. **It never
+carries the seed**: the seed decides every shuffle and every roll in the game, so it belongs to the
+host alone.
+
+**Two players may not share a display name.** The name labels the district on the Division map, it is
+what the turn chart means by "waiting on Jesse", and `record()` puts it in front of every line that
+player causes — so two of them make all three ambiguous, and the names lock at `Lobby.Start`. A
+clashing join is refused (`NAME_TAKEN`, compared trimmed and case-insensitively) rather than silently
+suffixed: a player should play under the name they chose, or be asked for another.
+
+**Anybody may leave, and the host may clear a chair.** `Lobby.Leave` frees the seat, drops the token
+from `joinOrder`, and passes host rights on exactly as a dropped connection does. Naming somebody
+else's `seat` is host-only. When the last human leaves, the lobby is deleted outright — code, file and
+index row — rather than left as a table of bots waiting for a host who no longer exists. Before this
+existed a mis-join or a player who wandered off wedged the whole table, since Start needs every chair
+filled and a bot may not be dropped onto an occupied seat.
 
 **One game at a time per person is expected usage and is deliberately not enforced** (`multiplayer.md`
 §10). Enforcing it needs cross-game state whose only job is deciding when to release someone, and
@@ -88,15 +111,27 @@ The cap is about what has been played, not about what the game can do.
 
 ## 3. Configuration, and when it locks
 
-Set before start, immutable after:
+Set before start, immutable after — the whole of `GameConfig` (`state.ts`), which the host fills in
+by choosing a **game type** and then editing whatever they like:
 
 ```
-mode          : solitaire | competitive | coop
-victory       : firstToTarget | highestAfterDays
-length        : short | standard | campaign
-optionalRules : { reducedVisibility, sisterTrains, employeeRotation, emergencyToolbox }
+mode              : solitaire | competitive | coop
+days              : how long the game runs
+minCombinedRevenue, maxCollisionsPerDay, maxCollisionsTotal   (0 = that condition is off)
+pvpCardsAllowed   : a property of the type, not a control — the cards are unbuilt (setup.ts)
+optionalRules     : { reducedVisibility, employeeRotation, emergencyToolbox }
+houseRules        : { startingHand, extraStart, revenue }
 ```
 
+**The four game types** (`src/web/presets.ts`, Jesse's design 2026-08-23) are Co-op, Competitive,
+Cutthroat and Solitaire, plus **Custom** — which is not a fifth type but the state of having edited
+one, and is scored as whichever type it was edited away from. The type is *derived* by comparing a
+config against the four, never stored, so a saved game carries no label that can disagree with its own
+numbers. Seed, player count and Day count sit ABOVE the type on both screens as **parameters**: the
+types are formulas in the table size and the length (the Revenue floor is 3 per player per Day in
+Co-op, 2 in Competitive, nothing in Cutthroat), so changing one re-derives rather than making the game
+Custom.
+
 These must lock at `Lobby.Start`. Changing `length` mid-game would move the finish line; changing
 `mode` would switch which failure floors apply (§3.4, §3.5). Neither has a coherent meaning
 mid-game, so the server should refuse rather than try.
@@ -141,6 +176,12 @@ to hide it. Show the chain forming.
 **Solitaire is unchanged and must stay so:** one player is one seat, seating is trivially `[0]`, and
 every published replay depends on that.
 
+**What a seat is told as the game begins** (2026-08-23). The board used to simply appear, mid-Local
+Operations, with a log already several bot turns deep and nothing marking where the game began. The
+page now holds a deliberate beat on a handoff curtain, announces the game and its type, marks the top
+of the log, and shows the code and the type in the header for the rest of the game — none of which is
+new *data*, only the first time any of it was drawn.
+
 **Employee Rotation** (Appendix B), if enabled, moves every player one seat left at the end of each
 Day, carrying their Revenue and the Fedora with them. **The model supports this as of v0.4.0**:
 offices and districts are keyed by seat, hands and Revenue and the Fedora by player, and `seating[]`
@@ -163,6 +204,16 @@ if it was their turn. Broadcast a disconnect notice so everyone else can see why
 server-layer news about a *connection*, not about the game, so it belongs with the transport rather
 than in `GameEvent`, which must stay replayable from a seed.
 
+**On connect, a client is told about every other seat at once** (2026-08-23). A change notice alone
+answered "who just left", never "who is here" — so a player arriving at a table where two people had
+not opened the game yet was told nothing about them at all, which is precisely the question at the
+moment a game starts. Each entry carries `seen`, separating **was here and dropped** from **has never
+opened the game**: the first will probably be back, the second needs somebody to send them the link.
+`seen` is remembered only for as long as the process runs, so after a restart every absent seat reads
+as "not here yet" — the more cautious of the two. **Bot seats are never reported**: a bot holds no
+connection and never will, and listing one puts "waiting on Bot 1" on every screen for the whole game
+(found by playing a three-seat game, not by reading the code).
+
 **On reconnect:** the client presents its token and the server replies with a **full current view**.
 Not an event tail — a returning client needs the position, not the history of how it got there, and
 the server can always produce the position because it holds the game

docs/architecture/protocol.md

@@ -103,6 +103,17 @@ Two consequences worth knowing before adding an event:
 - **Events are not what goes over the wire.** The server applies the intent and pushes the resulting
   `Frame` (`multiplayer.md` D2/D3). Events are narration and cues, not the protocol — and a reconnect
   gets a fresh `Frame` rather than the tail it missed.
+- **What events EARN does go over the wire, as four transient signals** (2026-08-23): the sound cues,
+  the timetable slot a D12 just filled, a one-line announcement, and the id of the card that just came
+  into this seat's hand. They ride beside the `Frame` rather than on it because they mark a *moment*
+  and are consumed — putting them on the Frame would re-fire them on every redraw. Before this a
+  remote client got none of them, so multiplayer had no sound at all, no flash and no announcements
+  while solitaire had all three. The first three are shared and identical in every seat's push; the
+  fourth is **not** — `game.justDrawn` is one field for the whole game and does not say whose card it
+  is, so the server remembers who drew and sends it to that seat alone
+  (`test/server/session.test.ts`, "the four transient signals"). A reconnect gets none of the shared
+  three: a fresh connection is drawing a state, and replaying the sounds of everything it missed is a
+  burst of noise about the past.
 
 ---
 

docs/rules/implications.md

@@ -89,6 +89,28 @@ district — so whichever direction climbs advantages one neighbour over the oth
 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.
 
+**Re-opened and closed again, 2026-08-23.** The question came back as "did we ever fix Heavy Grade
+to allow user placement of direction?", and the option of handing the choice to the **Superintendent**
+— the neutral office, which rotates with the Fedora every three Stages — was considered and rejected.
+Jesse's call: v0.5.0's ruling stands. What the re-examination surfaced, worth recording so this is not
+asked a third time:
+
+- **The advantage is permanent; the office is not.** Orientation decides which modifier cards pay for
+  the whole game (Brakeman and Airbrakes on the descent, Helpers on the climb) and therefore which
+  direction of traffic is favoured — and odd trains run west while even run east. A rotating office
+  making a one-way, once-and-for-all call does not dissolve the fairness problem, it just moves it.
+- **There is no setup phase to ask in.** `createGame` is pure and synchronous and the game opens at
+  Day 1, Stage 1, Local Operations. The question would have to interrupt play before the first turn,
+  and `clock.pendingDecision` is typed for clearance alone (`SuperintendentClearance | null`, read in
+  19 places), so a second decision kind would be most of the work.
+- **Most games never meet the card.** Since v0.6.2 deals the Mainline deck without replacement there
+  is at most one Heavy Grade in ten cards, drawn `players + 1` times: **20%** of solitaire games,
+  rising to 50% at four players. A pre-game interrupt for a rule four games in five never see.
+
+The docs were the actual defect. `README.md` still listed it among three open rules questions (all
+three closed in v0.5.0) and `StationMaster-Mainline-Deck-v0.4.5.md` still said "the implementation
+needs a player-selection step to match the card". Both now say settled, and why.
+
 **Still not implemented**: the Action (10) and Space-use (12) cards, which are genuinely
 multiplayer-only. Playing them is rejected with `NOT_IMPLEMENTED`.
 
@@ -542,7 +564,7 @@ We modelled a Mainline card as **2 regions, uniform**. The design has **ten dist
 | Plains | 60 | |
 | Curves | 30 | |
 | Hilly | **P60 / F30** | different speeds for passenger and freight |
-| Heavy Grade (Up) | **G** | player sets orientation; Brakeman/Airbrakes/Helpers unlock better start positions |
+| Heavy Grade (Up) | **G** | player sets orientation †; Brakeman/Airbrakes/Helpers unlock better start positions |
 | Double Track | 60 | **trains may pass** |
 | Uncontrolled Siding | 60 | trains may pass; separate "no pass" and "passing" starts |
 | Tunnel | 30 | |
@@ -550,6 +572,10 @@ We modelled a Mainline card as **2 regions, uniform**. The design has **ten dist
 | Interchange | 60 | **sort cars into any new order**; has a Yard Limit. Printed "Yard" on the prototype card and renamed after play — it shared a word with the Division Yard, the Classification Yard, the Salvage Yard, the Yard Office and the Small Yard, and is none of them |
 | East / West Division Point | — | the ends |
 
+† **"Player sets orientation" is deliberately NOT implemented** — the table records what the card
+prints, which is what this section is for. The game rolls the uphill direction from the seed instead;
+settled v0.5.0, re-confirmed 2026-08-23, reasoning in §10 Q11 above.
+
 Each card shows **Start positions** — where a train enters depending on direction, train type, and
 which modifier cards are in play. The Heavy Grade card has five distinct starts (plain, brakemen,
 airbrakes, plain, helpers), so playing Brakeman literally moves your entry point further along.