v0.4.4 — New Game dialog for the opening hand and the three revenue rates, Yard renamed Interchange, and two movement bugs behind a mirrored consist

src/engine/advance.ts

@@ -27,6 +27,7 @@ import {
   STAGES_PER_DAY,
   STAGES_PER_SHIFT,
   collectiveRevenueFloor,
+  houseRules,
   lengthProfile,
   officeProfile,
   REGIONS_PER_MAINLINE_CARD,
@@ -422,6 +423,26 @@ function enterMainline(
   );
   node.transits.push({ tray: id, stagesRemaining: stages, stagesTotal: stages, direction: tray.direction });
   tray.position = { at: 'mainline', index };
+
+  /**
+   * OUT OF THE DISTRICT, AND THE SPUR PORT GOES WITH IT.
+   *
+   * `facing` is a port on the card the train is standing on, and switching round a district leaves
+   * it holding a real compass port — 'n' or 's' off a curve. Nothing cleared it when the train
+   * departed, so it carried that port out onto a Division that runs east and west, and then into
+   * the next Office, whose card has no north or south edge at all.
+   *
+   * That is not cosmetic. `movesFor` explores from `facing` and from its opposite, and a card with
+   * neither port yields no destinations either way — so a train that had been shunted onto a spur
+   * arrived at the next Office **unable to make a single Move**. It also drew a ▲ on the Division
+   * map, where there is no north to point at.
+   *
+   * A train out here is running one way along an east-west railroad with its engine at one end, so
+   * this is what `facing` means on the Division; there is nothing else it could be. `railFacing`
+   * follows for the same reason — this IS the east-west sense, freshly known.
+   */
+  tray.facing = tray.direction === 'west' ? 'w' : 'e';
+  tray.railFacing = tray.facing;
 }
 
 /**
@@ -931,17 +952,21 @@ function collide(
  *
  * A crew with no train number is a local switching move, not a run, so it earns nothing.
  *
- * PROVISIONAL — the previous version was worth about +5 Revenue a game against a mean of 2.7, and
- * this one pays far less often. Flagged in `TODO.md`.
+ * NOW A DIAL, AND OFF BY DEFAULT. At 1 it was worth ~5.4 Revenue against a bot mean of 7.0 — the
+ * railroad was making most of its money from the one thing no one has to work, and the freight and
+ * passenger economies it exists to reward could not be read through it. `trainPerTransit` sets the
+ * rate per player, and 0 (the default) means no event at all rather than a run of "+0" entries.
  */
 function awardCompletedRun(s: GameState, tray: CrewTray, events: GameEvent[]): void {
   if (tray.trainNumber === null) return;
+  const rate = houseRules(s.config).revenue.trainPerTransit;
+  if (rate <= 0) return;
   for (const p of s.players) {
-    p.revenue += 1;
+    p.revenue += rate;
     events.push({
       type: 'revenueChanged',
       player: p.index,
-      delta: 1,
+      delta: rate,
       total: p.revenue,
       reason: 'a train completed its run',
     });

src/engine/apply.ts

@@ -25,6 +25,7 @@ import {
   industryProfile,
   mainlineModifierRule,
   mainlineProfile,
+  houseRules,
   modifierProfile,
   nextOfficeTier,
   officeProfile,
@@ -56,6 +57,7 @@ import {
   canDropCarsAt,
   canPlaceAt,
   carriesThroughTrack,
+  exitsFrom,
   exploreMoves,
   facilityVariants,
   opposite,
@@ -122,6 +124,20 @@ function occupancyFor(s: GameState, player: PlayerIndex, self: TrayId): Occupanc
   };
 }
 
+/**
+ * The port a train that came in through `entry` would carry on out by — read off the CARD.
+ *
+ * On a straight that is `opposite(entry)`, which is what this used to assume everywhere. On a curve
+ * it is the other end of the arc, and the two are never the same: a curve joins ADJACENT edges.
+ *
+ * A card reached by a Move has exactly one exit from the port it was entered by — the only card with
+ * three is a turnout, and a train may not finish a Move on one (§A.1). The fallback is for a caller
+ * holding a card the walk never validated, and matches the old behaviour rather than throwing.
+ */
+function farPort(card: TrackCard | undefined, entry: Port): Port {
+  return (card ? exitsFrom(card, entry)[0] : undefined) ?? opposite(entry);
+}
+
 /** A tray's facing, expressed as the port it would leave by going forward. */
 function facingPort(s: GameState, trayId: TrayId): Port {
   const tray = s.trays.get(trayId);
@@ -1183,19 +1199,29 @@ function execute(s: GameState, player: PlayerIndex, i: Intent): GameEvent[] {
           to: i.to,
           movesRemaining: turnOf(s, player).movesRemaining - 1,
           /**
-           * A TRAIN THAT BACKS UP HAS NOT TURNED AROUND.
+           * A TRAIN THAT BACKS UP HAS NOT TURNED AROUND — AND A CURVE IS NOT A STRAIGHT.
            *
-           * `facing` is which way the ENGINE points, and this set it to the direction of travel on
-           * every move — so one reverse move silently spun the train about. Everything then read
-           * "forward" again, and a run-around became pointless: you could change ends for free by
-           * backing up twice.
+           * `facing` is which way the ENGINE points, and this once set it to the direction of travel
+           * on every move — so one reverse move silently spun the train about, and a run-around
+           * became pointless: you could change ends for free by backing up twice.
            *
-           * Running forward the engine leads, so it points the way the train went: `opposite(entry)`.
-           * Backing up it trails, still pointing the way it came, which is the port it arrived
-           * through. Both hold around a curve, where the compass heading changes but the engine's
-           * relationship to its train does not.
+           * Backing up, the engine TRAILS, still pointing the way it came — out through the port the
+           * train arrived by. That holds whatever the track does underneath, so it is `dest.entry`
+           * and nothing else.
+           *
+           * Running forward, the engine LEADS, so it points out through the card's far end. That was
+           * written `opposite(entry)`, which is the far end of a straight and of nothing else: a
+           * curve is an arc between two ADJACENT edges, so entering a north-west curve through its
+           * west port leaves the engine facing NORTH, not east. The wrong port was not merely
+           * cosmetic — `movesFor` explores from `facing`, and a port the card does not have yields
+           * no destinations at all, so a crew that rounded a curve could only back out the way it
+           * came. Reported as a consist drawn mirrored, which is the other half of the same bug: the
+           * east-west sense the board draws is carried from `facing` (`railFacingOf`).
+           *
+           * `farPort` asks the CARD. A destination is never a turnout — a train may not finish a
+           * Move on one (§A.1) — so there is exactly one way out of it.
            */
-          facing: i.reverse ? dest.entry : opposite(dest.entry),
+          facing: i.reverse ? dest.entry : farPort(areaOf(s, player).grid.get(coordKey(i.to)), dest.entry),
         },
       ];
       if (dest.couples.length > 0) {
@@ -1419,16 +1445,21 @@ function execute(s: GameState, player: PlayerIndex, i: Intent): GameEvent[] {
         },
       ];
 
+    /**
+     * A COACH PAYS AT BOTH ENDS OF ITS JOURNEY — once boarded, once detrained — and each end pays
+     * `passengerPerCoach` (`content.ts`). Half a passenger movement is half the work, and the rate
+     * is named per COACH because a Porter handles exactly one coach per action.
+     */
     case 'porter.board':
       return [
         { type: 'passengersBoarded', player, at: i.at },
-        { type: 'revenueChanged', player, delta: 1, total: revenueAfter(s, player, 1), reason: 'boarding' },
+        ...earns(s, player, houseRules(s.config).revenue.passengerPerCoach, 'boarding'),
       ];
 
     case 'porter.detrain':
       return [
         { type: 'passengersDetrained', player, at: i.at },
-        { type: 'revenueChanged', player, delta: 1, total: revenueAfter(s, player, 1), reason: 'detraining' },
+        ...earns(s, player, houseRules(s.config).revenue.passengerPerCoach, 'detraining'),
       ];
 
     case 'laborer.startLoad': {
@@ -1442,18 +1473,20 @@ function execute(s: GameState, player: PlayerIndex, i: Intent): GameEvent[] {
       const load = workTrack(f)[i.box]!;
       const next = load.dir === 'out' ? i.box + 1 : i.box - 1;
 
+      // Like a coach, a load pays at both ends — made up outbound and broken inbound — and each end
+      // pays `freightPerLoad` (`content.ts`).
       if (next >= workTrack(f).length) {
         // Outbound complete: the load goes onto the spotted car (§9.3).
         return [
           { type: 'loadCompleted', player, at: i.at, carType: load.type },
-          { type: 'revenueChanged', player, delta: 1, total: revenueAfter(s, player, 1), reason: 'freightLoad' },
+          ...earns(s, player, houseRules(s.config).revenue.freightPerLoad, 'freightLoad'),
         ];
       }
       if (next < 0) {
         // Inbound complete: the load reaches the red Unloading box (§9.3).
         return [
           { type: 'unloadCompleted', player, at: i.at, carType: load.type },
-          { type: 'revenueChanged', player, delta: 1, total: revenueAfter(s, player, 1), reason: 'freightUnload' },
+          ...earns(s, player, houseRules(s.config).revenue.freightPerLoad, 'freightUnload'),
         ];
       }
       return [{ type: 'loadAdvanced', player, at: i.at, fromBox: i.box, toBox: next }];
@@ -1481,6 +1514,18 @@ function revenueAfter(s: GameState, player: PlayerIndex, delta: number): number
   return (s.players[player]?.revenue ?? 0) + delta;
 }
 
+/**
+ * A revenue award at this game's rate, or NO EVENT AT ALL when the rate is zero.
+ *
+ * Zero is a real setting — it is how you switch one economy off to read the others — and a stream of
+ * "+0 Revenue" entries in the history panel would be the loudest possible way to say nothing
+ * happened. The work still happens; it just does not pay.
+ */
+function earns(s: GameState, player: PlayerIndex, rate: number, reason: string): GameEvent[] {
+  if (rate <= 0) return [];
+  return [{ type: 'revenueChanged', player, delta: rate, total: revenueAfter(s, player, rate), reason }];
+}
+
 /** §7 — from the rolled slot, walk down the Timetable column, wrapping at the bottom. */
 function findTimetableSlot(s: GameState, from: number): number | null {
   for (let i = 0; i < s.timetable.length; i++) {
@@ -1509,7 +1554,12 @@ export function reduce(s: GameState, e: GameEvent): void {
       // A tray moving stays in the district it was already in — the seat does not change.
       const seat = tray.position.at === 'grid' ? tray.position.seat : 0;
       tray.position = { at: 'grid', seat, coord: e.to };
-      if (e.facing) tray.facing = e.facing;
+      if (e.facing) {
+        tray.facing = e.facing;
+        // The east-west sense only exists on east-west track, so it is CARRIED across north-south
+        // track rather than recomputed there — see `railFacing` in state.ts.
+        if (e.facing === 'e' || e.facing === 'w') tray.railFacing = e.facing;
+      }
       // Only the player sitting in this district can be switching this tray, so the Moves come off
       // their turn. The event carries no player of its own.
       turnOf(s, playerAtSeat(s, seat)).movesRemaining = e.movesRemaining;

src/engine/content.ts

@@ -417,7 +417,7 @@ export function consistSize(c: ConsistSpec): number {
 
 export type MainlineKind =
   | 'plains' | 'curves' | 'hilly' | 'heavyGrade' | 'doubleTrack'
-  | 'uncontrolledSiding' | 'tunnel' | 'trestle' | 'yard';
+  | 'uncontrolledSiding' | 'tunnel' | 'trestle' | 'interchange';
 
 /**
  * Speed as printed. `60` and `30` appear on the cards; Hilly prints P60/F30, and Heavy Grade
@@ -437,7 +437,7 @@ export type MainlineProfile = {
   speed: MainlineSpeed;
   /** Double Track and Uncontrolled Siding: "Trains may pass". */
   trainsMayPass: boolean;
-  /** Yard: "Sort cars in new order". */
+  /** Interchange: "Sort cars in new order". */
   sortsCars: boolean;
   /** Named entry points printed on the card; some are unlocked by modifier cards. */
   entryPoints: readonly string[];
@@ -452,7 +452,14 @@ export const MAINLINE_PROFILES: readonly MainlineProfile[] = [
   { kind: 'uncontrolledSiding', name: 'Uncontrolled Siding', speed: { kind: 'uniform', value: 60 }, trainsMayPass: true, sortsCars: false, entryPoints: ['noPass', 'passingTrains'] },
   { kind: 'tunnel', name: 'Tunnel', speed: { kind: 'uniform', value: 30 }, trainsMayPass: false, sortsCars: false, entryPoints: ['start'] },
   { kind: 'trestle', name: 'Trestle', speed: { kind: 'uniform', value: 60 }, trainsMayPass: false, sortsCars: false, entryPoints: ['start'] },
-  { kind: 'yard', name: 'Yard', speed: { kind: 'uniform', value: 60 }, trainsMayPass: false, sortsCars: true, entryPoints: ['start', 'sortCars'] },
+  /**
+   * RENAMED FROM "Yard" after play. The card is unchanged — same 60, same "sort cars in new
+   * order", same entry points, same art — but "Yard" collided with the Division Yard, the
+   * Classification Yard, the Salvage Yard, the Yard Office and the Small Yard, none of which are
+   * this. Its own key is renamed with it, so the two never drift apart. Those OTHER yards are
+   * deliberately left alone: they are different things that merely shared a word.
+   */
+  { kind: 'interchange', name: 'Interchange', speed: { kind: 'uniform', value: 60 }, trainsMayPass: false, sortsCars: true, entryPoints: ['start', 'sortCars'] },
 ];
 
 /**
@@ -756,13 +763,117 @@ export const STAGES_PER_SHIFT = 3;
 export const HAND_LIMIT = 3;
 
 /**
- * The opening deal: 3 track cards and 3 others, from two separately shuffled piles (`setup.ts`).
+ * The split opening deal: 3 track cards and 3 others, from two separately shuffled piles
+ * (`setup.ts`). One of the three `StartingHand` options below, not the only one any more.
  *
  * Six against a limit of three on purpose — the first turn is spent choosing which district you can
- * afford to build. PROVISIONAL, and flagged in `TODO.md` for review after play.
+ * afford to build.
  */
 export const OPENING_TRACK = 3;
 export const OPENING_OTHER = 3;
+
+// ---------------------------------------------------------------------------
+// House rules — the settings the New Game dialog offers
+// ---------------------------------------------------------------------------
+
+/**
+ * WHAT EACH PLAYER OPENS HOLDING.
+ *
+ * Three answers, all of which have been the rule at some point, and none of which is obviously
+ * right — so the game stops guessing and asks whoever deals.
+ *
+ * - `threeRandom` — the prototype rule. Three cards off one deck, at the hand limit, no guarantees.
+ * - `sixRandom` — six off one deck, so the first turn is a discard and the opening is a choice,
+ *   without the track being handed to you.
+ * - `threeTrackThreeOther` — three of each from separately shuffled piles. Introduced because a
+ *   run-around needs five specific pieces and the bot held a turnout and a matching-hand curve
+ *   together on 0.2% of turns; measured five ways, that was a SUPPLY problem, not a bot weakness.
+ */
+export type StartingHand = 'threeRandom' | 'sixRandom' | 'threeTrackThreeOther';
+
+/** How many cards come off which pile, per `StartingHand`. `any` is dealt from the single deck. */
+export const OPENING_DEALS: Readonly<Record<StartingHand, { any: number; track: number; other: number }>> = {
+  threeRandom: { any: 3, track: 0, other: 0 },
+  sixRandom: { any: 6, track: 0, other: 0 },
+  threeTrackThreeOther: { any: 0, track: OPENING_TRACK, other: OPENING_OTHER },
+};
+
+/**
+ * WHAT THE THREE WORKING ECONOMIES PAY.
+ *
+ * Balance is the open problem in this game — the developer bot averages 7.0 Revenue against a target
+ * of 20, of which most came from traffic nobody had to work — and the way to settle it is to play it
+ * at several settings rather than to keep re-deriving it. So the three rates are dials, set when the
+ * game is dealt and fixed for its duration.
+ *
+ * `passengerPerCoach` and `freightPerLoad` each pay on BOTH halves of their cycle: a coach pays when
+ * it is boarded and again when it is detrained, a load pays when it is made up outbound and again
+ * when it is broken inbound. That is what the rates have always done; these scale it.
+ *
+ * `trainPerTransit` pays every player, once, when a train runs off the end of the Division — it is
+ * the shared achievement, and every Office it crossed had to clear it. It defaults to 0 because at 1
+ * it was worth ~5.4 of a 7.0 mean: the railroad was earning most of its money from traffic no one
+ * had to work, which drowned out the freight and passenger economies this game is actually about.
+ */
+export type RevenueRules = {
+  passengerPerCoach: number;
+  freightPerLoad: number;
+  trainPerTransit: number;
+};
+
+export type HouseRules = { startingHand: StartingHand; revenue: RevenueRules };
+
+/** What a caller may name — any subset, down to none — resolved by `houseRules()`. */
+export type HouseRuleOverrides = { startingHand?: StartingHand; revenue?: Partial<RevenueRules> };
+
+/** The dialog's range. Zero is a real setting: it switches an economy off so the others can be read. */
+export const REVENUE_MIN = 0;
+export const REVENUE_MAX = 5;
+
+export const DEFAULT_HOUSE_RULES: HouseRules = {
+  startingHand: 'threeRandom',
+  revenue: { passengerPerCoach: 1, freightPerLoad: 1, trainPerTransit: 0 },
+};
+
+/**
+ * THE RULES A SAVE THAT PREDATES THIS SETTING WAS PLAYED UNDER.
+ *
+ * A save is a seed and a list of intents, so it only replays under the ruleset that produced it —
+ * `TODO.md` records two published replays going dead unnoticed when the rules moved, one of them 42
+ * intents into 360. Every save written from now on carries its rules; the ones already written do
+ * not, and this is what they meant. Do not "tidy" it into the defaults above: that silently kills
+ * the three replays in `public/replays/`.
+ */
+export const LEGACY_HOUSE_RULES: HouseRules = {
+  startingHand: 'threeTrackThreeOther',
+  revenue: { passengerPerCoach: 1, freightPerLoad: 1, trainPerTransit: 1 },
+};
+
+/** A whole, valid rule set from a config that may carry none, some, or out-of-range values. */
+export function houseRules(config: { houseRules?: HouseRuleOverrides }): HouseRules {
+  const given = config.houseRules ?? {};
+  const rev = given.revenue ?? {};
+  const clamp = (n: number | undefined, fallback: number): number =>
+    typeof n === 'number' && Number.isFinite(n)
+      ? Math.max(REVENUE_MIN, Math.min(REVENUE_MAX, Math.round(n)))
+      : fallback;
+  const d = DEFAULT_HOUSE_RULES;
+  return {
+    startingHand: given.startingHand ?? d.startingHand,
+    revenue: {
+      passengerPerCoach: clamp(rev.passengerPerCoach, d.revenue.passengerPerCoach),
+      freightPerLoad: clamp(rev.freightPerLoad, d.revenue.freightPerLoad),
+      trainPerTransit: clamp(rev.trainPerTransit, d.revenue.trainPerTransit),
+    },
+  };
+}
+
+/** What the dialog calls each option, in the order it offers them. */
+export const STARTING_HAND_LABELS: readonly { value: StartingHand; label: string }[] = [
+  { value: 'threeRandom', label: 'Three random cards' },
+  { value: 'sixRandom', label: 'Six random cards' },
+  { value: 'threeTrackThreeOther', label: 'Three random track and three random non-track cards' },
+];
 export const MAX_CONSIST = 4;
 export const MOVES_PER_LOCAL_OPS = 6;
 export const MOVES_PER_LOCAL_OPS_NIGHT = 5;

src/engine/setup.ts

@@ -16,9 +16,9 @@ import {
   MOVES_PER_LOCAL_OPS,
   MODIFIER_PROFILES,
   OFFICE_PROFILES,
-  OPENING_OTHER,
-  OPENING_TRACK,
+  OPENING_DEALS,
   MAINLINE_PROFILES,
+  houseRules,
   mainlineProfile,
   TRACK_CARDS,
   ROLLING_STOCK_SUPPLY,
@@ -287,53 +287,59 @@ export function createGame(opts: SetupOptions): GameState {
     .sort((a, b) => divisionRolls[a]! - divisionRolls[b]! || b - a);
 
   /**
-   * §4.6-4.7 — THE OPENING DEAL, dealt from two piles rather than one.
+   * §4.6-4.7 — THE OPENING DEAL, in whichever of the three shapes this game was dealt with.
    *
-   * Track is shuffled SEPARATELY from everything else and each player is dealt **3 track cards and 3
-   * other cards**; the track left over is then shuffled back in and the game runs off one deck as
-   * before. The player opens holding six against a limit of three, so the first turn is spent
+   * `threeRandom` and `sixRandom` deal off ONE shuffled deck; `threeTrackThreeOther` shuffles track
+   * separately and deals three of each, then shuffles the remainder back together so the game runs
+   * off one deck from the first draw onward either way. `content.ts` says what each option is for.
+   *
+   * A player dealt six holds six against a limit of three, on purpose: the first turn is spent
    * choosing what to keep — draw as usual, then play or discard down to three (§6.2, enforced on
-   * `draw.end`, which needs no special case for this).
+   * `draw.end`, which needs no special case for this). A player dealt three is already at the limit.
    *
-   * WHY. A run-around needs five specific pieces in a usable order, and the bot held a turnout and a
-   * matching-hand curve together on **0.2% of turns** — about once every eight games. Measured five
-   * ways, that is a SUPPLY problem and not a bot weakness: 91 run-arounds per 100 games when track
-   * was a private 26-piece supply the player chose from, 29 per 100 once it was drawn, 4 per 60 with
-   * track in the deck. Dealing the opening district as track restores something close to the
-   * prototype's private supply without reintroducing an unbounded one, and makes the opening a
-   * decision rather than a wait.
-   *
-   * PROVISIONAL — flagged for review once it has been played. See `TODO.md`.
+   * §4.7 — "starting from the Superintendent, deal each player…", which proceeds round the table and
+   * is therefore SEAT order, not player order. That is the same in all three shapes.
    */
+  const rules = houseRules(config);
+  const deal = OPENING_DEALS[rules.startingHand];
   const deck = buildDeck(config.mode);
   const cards = new Map<CardId, Card>();
   for (const c of deck) cards.set(c.id, c);
 
   const isTrack = (id: CardId): boolean => cards.get(id)?.kind.kind === 'track';
   const ids = deck.map((c) => c.id);
-  // Shuffled in a fixed order — track first — so the RNG stream is deterministic for a given seed.
-  const trackPile = rng.shuffle(ids.filter(isTrack));
-  const otherPile = rng.shuffle(ids.filter((id) => !isTrack(id)));
-
-  const hands = new Map<PlayerIndex, CardId[]>();
-  let trackCursor = 0;
-  let otherCursor = 0;
-  // §4.7 — "starting from the Superintendent, deal each player…", which proceeds round the table
-  // and is therefore seat order, not player order.
   const superSeat = seating.indexOf(superintendent);
-  for (let i = 0; i < playerCount; i++) {
-    const p = seating[(superSeat + i) % playerCount]!;
-    hands.set(p, [
-      ...trackPile.slice(trackCursor, trackCursor + OPENING_TRACK),
-      ...otherPile.slice(otherCursor, otherCursor + OPENING_OTHER),
-    ]);
-    trackCursor += OPENING_TRACK;
-    otherCursor += OPENING_OTHER;
-  }
+  const hands = new Map<PlayerIndex, CardId[]>();
+  const dealtTo = (i: number): PlayerIndex => seating[(superSeat + i) % playerCount]!;
 
-  // The remainder goes back into ONE deck for the rest of the game — the split is an opening-deal
-  // device only, so track competes for the draw exactly as before from the first draw onward.
-  const shuffled = rng.shuffle([...trackPile.slice(trackCursor), ...otherPile.slice(otherCursor)]);
+  let shuffled: CardId[];
+  if (deal.any > 0) {
+    // One deck, one shuffle, the top cards off it — the prototype's own deal.
+    const single = rng.shuffle(ids);
+    let cut = 0;
+    for (let i = 0; i < playerCount; i++) {
+      hands.set(dealtTo(i), single.slice(cut, cut + deal.any));
+      cut += deal.any;
+    }
+    shuffled = single.slice(cut);
+  } else {
+    // Shuffled in a fixed order — track first — so the RNG stream is deterministic for a given seed.
+    const trackPile = rng.shuffle(ids.filter(isTrack));
+    const otherPile = rng.shuffle(ids.filter((id) => !isTrack(id)));
+    let trackCursor = 0;
+    let otherCursor = 0;
+    for (let i = 0; i < playerCount; i++) {
+      hands.set(dealtTo(i), [
+        ...trackPile.slice(trackCursor, trackCursor + deal.track),
+        ...otherPile.slice(otherCursor, otherCursor + deal.other),
+      ]);
+      trackCursor += deal.track;
+      otherCursor += deal.other;
+    }
+    // The remainder goes back into ONE deck for the rest of the game — the split is an opening-deal
+    // device only, so track competes for the draw exactly as before from the first draw onward.
+    shuffled = rng.shuffle([...trackPile.slice(trackCursor), ...otherPile.slice(otherCursor)]);
+  }
 
   // §4.6-4.7 — three cards turned face up beside the deck. Each is the bottom of a Department pile
   // that grows as players discard onto it. Taken after the recombination, so a Department slot can

src/engine/state.ts

@@ -13,6 +13,7 @@ import type {
   MainlineKind,
   FreightKind,
   GameLength,
+  HouseRuleOverrides,
   ModifierKind,
   OfficeTier,
   TrackGeometry,
@@ -282,6 +283,28 @@ export type CrewTray = {
    * without one falls back to `direction`.
    */
   facing?: 'n' | 's' | 'e' | 'w';
+  /**
+   * WHICH WAY THE ENGINE POINTS IN RAILROAD TERMS — east or west, and never anything else.
+   *
+   * `facing` is a PORT, because movement needs one: a crew on a north-south spur must be able to
+   * leave by 'n' or 's'. But a Division runs east and west, and a player reads a train the way a
+   * railroader does — "the engine is on the west end" — so a ▲ on a crew that had turned onto a
+   * spur read as a train that had somehow stood itself on end. Worse, nothing resets `facing` when
+   * a train leaves the district, so a crew that shunted onto a north-south spur and then departed
+   * carried its 'n' out onto the Division map and drew ▲ there too.
+   *
+   * So this is the DISPLAY facing, and it is a separate field because it cannot be derived: on
+   * north-south track the east-west sense is not in the current port, it is in the last one. It
+   * holds its value across north-south track and updates whenever `facing` becomes 'e' or 'w' —
+   * which is exactly the railroad's own convention, where compass north on a branch is still
+   * timetable east. A train that runs forward through 180° of curves genuinely does come out
+   * pointing the other way, and this follows it; backing up does not change it, because a train
+   * that backs up has not turned around.
+   *
+   * NOT `direction`: that is the timetable direction of the RUN and does not move when a run-around
+   * puts the engine on the other end, which is the one thing the arrow exists to show.
+   */
+  railFacing?: 'e' | 'w';
   position: NodeRef;
   movesUsed: number;
   /**
@@ -468,6 +491,14 @@ export type GameConfig = {
     employeeRotation: boolean;
     emergencyToolbox: boolean;
   };
+  /**
+   * The opening deal and the three revenue rates, chosen when the game is dealt (`content.ts`).
+   *
+   * Optional and PARTIAL on purpose. Every caller that does not care about them — and most of the
+   * engine tests do not — gets `DEFAULT_HOUSE_RULES` through `houseRules()`, which is the one place
+   * a default is written down. A caller that cares names only the dials it is setting.
+   */
+  houseRules?: HouseRuleOverrides;
 };
 
 export type OutcomeReason =
@@ -524,6 +555,21 @@ export function freshTurns(players: number, moves: number): Map<PlayerIndex, Tur
   return turns;
 }
 
+/**
+ * WHICH WAY TO DRAW THE ENGINE — east or west, for every train, everywhere.
+ *
+ * The single place the display facing is decided, so the Division map, the Office cards and the
+ * tooltips can never disagree about which end of a train the engine is on. Three sources, in the
+ * order they can be trusted: the carried east-west sense; the current port, when it happens to be
+ * an east-west one (a tray placed straight onto the board has no history yet); and failing both,
+ * the direction of the run.
+ */
+export function railFacingOf(tray: Pick<CrewTray, 'railFacing' | 'facing' | 'direction'>): 'e' | 'w' {
+  if (tray.railFacing) return tray.railFacing;
+  if (tray.facing === 'e' || tray.facing === 'w') return tray.facing;
+  return tray.direction === 'west' ? 'w' : 'e';
+}
+
 export function turnOf(s: GameState, player: PlayerIndex): TurnState {
   const t = s.turns.get(player);
   if (!t) throw new Error(`no turn state for player ${player}`);

src/sim/board-svg.ts

@@ -77,7 +77,8 @@ export function divisionSvg(nodes: DivisionView[]): string {
       /** Nose first, no engine — drawn as blocks, loaded solid and empty hollow. */
       cars?: string[];
       engineAt?: number;
-      facing?: string;
+      /** East or west, always — a Division runs east and west and so does its rolling stock. */
+      facing?: 'e' | 'w';
       region?: number;
       direction?: string;
       stagesLeft?: number;
@@ -291,7 +292,7 @@ export function divisionSvg(nodes: DivisionView[]): string {
      */
     c.trains.forEach((t, k) => {
       const cars = t.cars ?? [];
-      const arrow = t.facing === 'w' ? '\u25c0' : t.facing === 'e' ? '\u25b6' : t.facing === 'n' ? '\u25b2' : '\u25bc';
+      const arrow = t.facing === 'w' ? '\u25c0' : '\u25b6';
       const loaded = cars.filter((x) => /^loaded/.test(x) || /caboose/.test(x)).length;
       const label = cars.length === 0 ? `${t.label} ${arrow}` : `${t.label} ${arrow}${cars.length}`;
 
@@ -704,7 +705,7 @@ export function officeSvg(
         kind: /^loaded/.test(c) || /caboose/.test(c) ? 'ld' : 'mt',
         what: c,
       }));
-      const arrow = t.facing === 'w' ? '\u25c0' : t.facing === 'e' ? '\u25b6' : t.facing === 'n' ? '\u25b2' : '\u25bc';
+      const arrow = t.facing === 'w' ? '\u25c0' : '\u25b6';
       items.splice(t.engineAt, 0, { label: arrow, kind: 'eng', what: 'the engine' });
       /**
        * WEST ON THE LEFT, AND THE NOSE POINTING THE WAY THE ENGINE FACES.
@@ -715,15 +716,19 @@ export function officeSvg(
        * drawn engine-first at the WEST end, which reads as an engine shoving four cars ahead of it.
        *
        * The board is a map, so the drawing has to obey the map: reverse the seating order for an
-       * east-facing train and its nose lands at the east end, where it is. A crew on a north-south
-       * spur has no left or right to be right about, so it keeps nose-left and its \u25b2/\u25bc says the rest.
+       * east-facing train and its nose lands at the east end, where it is.
+       *
+       * A crew on a north-south spur is drawn east-west like every other train, because `facing` is
+       * now always east or west (`railFacingOf`). It used to keep its compass port and draw \u25b2 or \u25bc
+       * with the consist pinned nose-left, which meant the one thing the picture is for \u2014 which end
+       * the engine is on \u2014 flipped its convention the moment a crew turned a corner. Playtested and
+       * reported as more confusing than a strip drawn the same way every time.
        */
       const laid = t.facing === 'e' ? [...items].reverse() : items;
       const cw = 17;
       const tw = Math.min(W - 8, laid.length * cw + 30);
       const tx = W / 2 - tw / 2;
-      const facingWord =
-        t.facing === 'e' ? 'east' : t.facing === 'w' ? 'west' : t.facing === 'n' ? 'north' : 'south';
+      const facingWord = t.facing === 'e' ? 'east' : 'west';
       const consistWords = t.cars.length === 0 ? 'no cars' : t.cars.join(', ');
       out += `<g class="bs-crew" data-tip="${esc(
         `${t.label} — engine pointing ${facingWord}, carrying ${consistWords}` + (t.what ? `\n\n${t.what}` : ''),

src/sim/save-replay.ts

@@ -21,7 +21,7 @@
  *   node src/sim/save-replay.ts 400 --top 3 trainCapSlack=0
  */
 
-import { writeFileSync } from 'node:fs';
+import { readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -131,13 +131,33 @@ if (isMain) {
     `  best ${revenues.slice(0, 5).join(', ')} · median ${revenues[Math.floor(revenues.length / 2)]}`,
   );
 
-  let written = 0;
-  for (const p of best) {
+  const verified = best.filter((p) => {
     const check = verifyReplays(p);
-    if (!check.ok) {
-      console.warn(`  REFUSED seed ${p.seed} — ${check.why}`);
-      continue;
+    if (!check.ok) console.warn(`  REFUSED seed ${p.seed} — ${check.why}`);
+    return check.ok;
+  });
+
+  /**
+   * THE PUBLISHED SET IS REPLACED, NOT ADDED TO.
+   *
+   * Every file here is named for its seed, so re-recording used to leave the previous set sitting
+   * beside the new one — and the previous set is precisely the one whose rules have just moved. The
+   * point of re-recording is that those files are dead; keeping them means the site serves dead
+   * replays and `harness.test.ts` fails on them forever, which is how the last two went unnoticed.
+   *
+   * Only ever run after at least one replacement verifies, so a run that produces nothing publishable
+   * leaves what is already published alone.
+   */
+  if (verified.length > 0) {
+    for (const old of readdirSync(dest).filter((f) => f.endsWith('.json') && f !== 'manifest.json')) {
+      if (verified.some((p) => `seed-${p.seed}.json` === old)) continue;
+      unlinkSync(join(dest, old));
+      console.log(`  retired ${old} — recorded under rules that have since moved`);
     }
+  }
+
+  let written = 0;
+  for (const p of verified) {
     const file = join(dest, `seed-${p.seed}.json`);
     writeFileSync(
       file,
@@ -148,13 +168,16 @@ if (isMain) {
           // there is room — a title carrying seven tweak names is a title nobody reads.
           title: `${p.revenue} Revenue · seed ${p.seed}`,
           note: `${p.note} · played by ${policy.name}`,
+          // The house rules it was DEALT under, without which the seed does not name this game and
+          // the file replays as something else — see `Save.rules` in `web/game.ts`.
+          ...(p.save.rules ? { rules: p.save.rules } : {}),
           history: p.save.history,
         },
         null,
         1,
       ),
     );
-    console.log(`  wrote ${file}  (${p.note}, ${check.why})`);
+    console.log(`  wrote ${file}  (${p.note})`);
     written += 1;
   }
   console.log(`${written} replay(s) saved — run \`npm run build:web\` to publish them`);

src/sim/view.ts

@@ -38,11 +38,12 @@ import {
   lengthProfile,
   officeProfile,
   trainProfile,
+  houseRules,
 } from '../engine/content.ts';
 import type { Intent } from '../engine/intents.ts';
 import type { Facility, GameState, PlayerIndex, TrackCard, TurnoutOrientation } from '../engine/state.ts';
-import { playerAtSeat, seatOf, turnOf } from '../engine/state.ts';
-import type { Hand, TrackGeometry } from '../engine/content.ts';
+import { playerAtSeat, railFacingOf, seatOf, turnOf } from '../engine/state.ts';
+import type { Hand, HouseRules, TrackGeometry } from '../engine/content.ts';
 import type { Port } from '../engine/track.ts';
 import { connectionsFor, slopeOfPair, variantsFor } from '../engine/track.ts';
 import type { Impediment } from './narrate.ts';
@@ -76,13 +77,14 @@ export type CellView = {
    * not plan a move at all: "drop 1 car" tells you nothing when you cannot see what is on the back.
    *
    * `cars` runs nose first, matching the tray; `engineAt` is where the locomotive sits in it, and
-   * `facing` is the port it points at on this card.
+   * `facing` is which way the engine points — EAST OR WEST, never north or south, whatever the
+   * track under it runs. See `railFacingOf` in state.ts for why, and why the type says so.
    */
   train: {
     label: string;
     cars: string[];
     engineAt: number;
-    facing: string;
+    facing: 'e' | 'w';
     /**
      * WHAT THIS PARTICULAR TRAIN'S CARD SAYS.
      *
@@ -188,13 +190,14 @@ export type TrainChip = {
    * THE SAME TRAIN THE OFFICE CARD DRAWS, so the Division map can draw it the same way.
    *
    * `cars` is nose first and carries no engine; `engineAt` is where the engine sits among them and
-   * `facing` is the port it points at. The Division chip used to be a name and a number — and the
-   * number was Stages left to cross, which reads as redundant beside the position already drawn on
-   * the card. A train is worth drawing: what it is carrying, loaded or empty, and which end leads.
+   * `facing` is which way the engine points, east or west. The Division chip used to be a name and a
+   * number — and the number was Stages left to cross, which reads as redundant beside the position
+   * already drawn on the card. A train is worth drawing: what it is carrying, loaded or empty, and
+   * which end leads.
    */
   cars: string[];
   engineAt: number;
-  facing: string;
+  facing: 'e' | 'w';
   /**
    * Which region of a Mainline card the train is standing in, and which way it is going. Absent
    * everywhere else: a Division Point is a single queue, and inside a district a train moves by
@@ -287,6 +290,14 @@ export type Frame = {
    */
   /** Which of §6's three exclusive options the VIEWER has taken this Stage, if any. */
   option: 'switch' | 'draw' | 'freightAgent' | null;
+  /**
+   * The settings this game was dealt under — the opening hand, and what the three economies pay.
+   *
+   * On the Frame rather than read off the config, for the same reason as everything else here: a
+   * remote client holds no `GameState`, and "what does a load pay in this game?" is a question it
+   * must be able to answer. Resolved, never partial, so nobody downstream re-applies defaults.
+   */
+  houseRules: HouseRules;
   status: GameState['status'];
   outcome: GameState['outcome'];
   /**
@@ -513,7 +524,7 @@ function trainOnCard(s: GameState, key: string): CellView['train'] {
       label: t.trainNumber === null ? 'crew' : `T${t.trainIsExtra ? 'X' : ''}${t.trainNumber}`,
       cars: t.consist.map(carLabel),
       engineAt: Math.max(0, Math.min(t.consist.length, t.engineAt)),
-      facing: t.facing ?? (t.direction === 'west' ? 'w' : 'e'),
+      facing: railFacingOf(t),
       what: t.trainNumber === null ? 'A local crew — no timetable, no card, no special rules.' : trainRules(t),
     };
     void id;
@@ -1044,6 +1055,7 @@ export function snapshot(
     decision,
     wasted,
     option: turnOf(s, viewer).option,
+    houseRules: houseRules(s.config),
     status: s.status,
     outcome: s.outcome,
     players: s.players.map((p) => ({
@@ -1579,7 +1591,7 @@ function trainChip(s: GameState, id: string): TrainChip {
     consist: seated,
     cars,
     engineAt: at,
-    facing: t.facing ?? (t.direction === 'west' ? 'w' : 'e'),
+    facing: railFacingOf(t),
   };
 }
 

src/web/game.ts

@@ -42,8 +42,15 @@ import {
   trainName,
   variantLabel,
 } from '../sim/view.ts';
-import { HAND_LIMIT, mainlineProfile, trainProfile } from '../engine/content.ts';
-import type { Hand, TrackGeometry } from '../engine/content.ts';
+import {
+  DEFAULT_HOUSE_RULES,
+  HAND_LIMIT,
+  LEGACY_HOUSE_RULES,
+  houseRules,
+  mainlineProfile,
+  trainProfile,
+} from '../engine/content.ts';
+import type { Hand, HouseRuleOverrides, TrackGeometry } from '../engine/content.ts';
 import type { Port } from '../engine/track.ts';
 import { connectionsFor, joins, neighbour, variantsFor } from '../engine/track.ts';
 import { areaOf, trainNeedingCars } from '../engine/apply.ts';
@@ -59,8 +66,16 @@ export const SOLO_CONFIG: GameConfig = {
     employeeRotation: false,
     emergencyToolbox: false,
   },
+  // Spelt out rather than left to fall through, so a save written by the page always names the rules
+  // it was played under — see `Save.rules`.
+  houseRules: DEFAULT_HOUSE_RULES,
 };
 
+/** 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 }) };
+}
+
 /** A group of legal actions of one kind, ready to put on screen. */
 export type ActionGroup = {
   kind: string;
@@ -708,10 +723,31 @@ function record(game: Game, events: GameEvent[], actor: PlayerIndex | null = nul
 // Saving — seed plus intents, replayed
 // ---------------------------------------------------------------------------
 
-export type Save = { seed: number; history: Intent[] };
+/**
+ * A save is a seed, the house rules it was dealt under, and the intents submitted.
+ *
+ * `rules` is optional because saves written before the New Game dialog existed do not have it, and
+ * those replay under `LEGACY_HOUSE_RULES` — see `configFor`. Everything written from now on carries
+ * its rules, so a save can never again be silently re-dealt by a change of default.
+ */
+export type Save = { seed: number; history: Intent[]; rules?: HouseRuleOverrides };
 
 export function toSave(game: Game): Save {
-  return { seed: game.seed, history: game.history };
+  const rules = game.state.config.houseRules;
+  return rules ? { seed: game.seed, history: game.history, rules } : { seed: game.seed, history: game.history };
+}
+
+/**
+ * THE CONFIG A SAVE MUST BE REPLAYED UNDER, which is not necessarily today's default.
+ *
+ * A save is a seed and a list of intents: replay it under different rules and it is a different
+ * game, and the symptom is not an error but a replay that quietly stops early. `TODO.md` records
+ * that happening twice unnoticed, once 42 intents into 360. So a save that names its rules gets
+ * exactly those, and a save that names none is from before the dialog and gets the rules that were
+ * in force then — never the current defaults.
+ */
+function configFor(save: Save, config: GameConfig): GameConfig {
+  return { ...config, houseRules: save.rules ?? LEGACY_HOUSE_RULES };
 }
 
 /**
@@ -736,7 +772,9 @@ export function toSave(game: Game): Save {
  */
 export function undo(game: Game, config: GameConfig = SOLO_CONFIG): Game | null {
   if (game.history.length === 0) return null;
-  return fromSave({ seed: game.seed, history: game.history.slice(0, -1) }, config);
+  // `toSave` first, so the rules this game was dealt under come with it. Rebuilding the save by hand
+  // here dropped them, and undo re-dealt the game under the defaults instead of its own settings.
+  return fromSave({ ...toSave(game), history: game.history.slice(0, -1) }, config);
 }
 
 /**
@@ -747,7 +785,7 @@ export function undo(game: Game, config: GameConfig = SOLO_CONFIG): Game | null
  * stops the replay rather than being forced — better a short game than a corrupt one.
  */
 export function fromSave(save: Save, config: GameConfig = SOLO_CONFIG): Game {
-  const game = newGame(save.seed, config);
+  const game = newGame(save.seed, configFor(save, config));
   for (const intent of save.history) {
     const actor = currentActor(game);
     if (actor === null) break;

src/web/main.ts

@@ -12,7 +12,8 @@ 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 } from '../engine/content.ts';
+import { MOVES_PER_LOCAL_OPS, STARTING_HAND_LABELS, 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';
 
@@ -112,14 +113,73 @@ function renderTurnChart(f: Frame): void {
   $('turnchart').innerHTML = turnChartHtml(f, actorName);
 }
 
+/**
+ * The settings this game was dealt under, beside the seed, because the seed alone does not name it.
+ *
+ * Abbreviated to fit a header that must not wrap — `3 cards · 1/1/0` — with the whole of it in the
+ * tooltip. Written down at all because a playtest note is worthless without it: "scored 4" means one
+ * thing at 1 Revenue per transit and another at 5.
+ */
+function renderHouseRules(rules: HouseRules): void {
+  const { passengerPerCoach: pax, freightPerLoad: frt, trainPerTransit: trn } = rules.revenue;
+  const short = { threeRandom: '3 cards', sixRandom: '6 cards', threeTrackThreeOther: '3+3 cards' };
+  const el = $('houserules');
+  el.textContent = `· ${short[rules.startingHand]} · ${pax}/${frt}/${trn}`;
+  const handWords = STARTING_HAND_LABELS.find((o) => o.value === rules.startingHand)?.label ?? '';
+  el.title =
+    `Opening hand: ${handWords.toLowerCase()}.\n` +
+    `Passenger revenue per coach: ${pax} (paid on boarding and again on detraining).\n` +
+    `Freight revenue per load: ${frt} (paid on loading and again on unloading).\n` +
+    `Train revenue per transit: ${trn} (paid to every player when a train leaves the Division).`;
+}
+
+/**
+ * THE HOUSE RULES 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()`.
+ *
+ * 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;
+
+function rulesFromUrl(params: URLSearchParams): HouseRuleOverrides {
+  const rules: HouseRuleOverrides = {};
+  const hand = params.get('hand');
+  if (STARTING_HAND_LABELS.some((o) => o.value === hand)) rules.startingHand = hand as StartingHand;
+
+  const revenue: Partial<RevenueRules> = {};
+  for (const [param, key] of Object.entries(RULE_PARAMS)) {
+    const raw = params.get(param);
+    // `houseRules()` clamps and rounds, so anything hand-edited into the URL lands in range rather
+    // than dealing a game at 900 Revenue a coach.
+    if (raw !== null && raw.trim() !== '' && Number.isFinite(Number(raw))) revenue[key] = Number(raw);
+  }
+  if (Object.keys(revenue).length > 0) rules.revenue = revenue;
+  return rules;
+}
+
+function rulesToUrl(rules: HouseRules, 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]));
+  return `?${params}`;
+}
+
 function start(): void {
   const params = new URLSearchParams(location.search);
   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);
+  session = createLocalSession(seed, rulesFromUrl(params));
 
+  // 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);
 
@@ -185,6 +245,7 @@ function render(): void {
   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());
+  renderHouseRules(f.houseRules);
 
   // -- division
   $('division').innerHTML = divisionSvg(f.division);
@@ -828,35 +889,76 @@ if (saveBtn) saveBtn.onclick = downloadSave;
  * steps back one action at a time, but nothing brings back a game that has been dealt over, and the
  * replay download is right beside it.
  *
- * `location.search = ''` rather than a direct re-render, so a `?seed=` in the URL goes too — leaving
- * it would deal the same game again and look like the button had done nothing.
+ * Navigating rather than re-rendering, so a stale `?seed=` in the URL goes too — leaving it would
+ * deal the same game again and look like the button had done nothing.
  */
 const newBtn = document.getElementById('newgame');
-if (newBtn) {
+const dlg = document.getElementById('newgamedlg') as HTMLDialogElement | null;
+if (newBtn && dlg) {
+  const field = <T extends HTMLElement>(id: string): T => document.getElementById(id) as T;
+
+  /**
+   * ASK FOR ALL THREE, 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.
+   */
   newBtn.onclick = () => {
     const f = session.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;
-    /**
-     * ASK FOR THE SEED, rather than documenting a URL parameter in the title bar.
-     *
-     * The same deal can be replayed, shared or compared by seed, which is worth offering — it was
-     * offered as the note "add ?seed=1234 for a set deal", which spent width on the one line that
-     * must not wrap to explain a thing the button could simply ask. Blank means random.
-     */
-    const asked = prompt('Seed for the new game — leave blank for a random one:', '');
-    if (asked === null) return; // cancelled
-    clearSave();
-    const wanted = asked.trim();
-    if (wanted === '') {
-      // No `?seed=`, so `start()` rolls one. Reload rather than re-render, to clear any seed in the URL.
-      if (location.search === '') location.reload();
-      else location.search = '';
-      return;
+
+    const current = session.view().houseRules;
+    field<HTMLInputElement>('ng-seed').value = '';
+    for (const input of dlg.querySelectorAll<HTMLInputElement>('input[name="ng-hand"]')) {
+      input.checked = input.value === current.startingHand;
     }
-    location.search = `?seed=${encodeURIComponent(wanted)}`;
+    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);
+    dlg.showModal();
   };
+
+  /**
+   * One handler for every way the dialog can close — the Deal button, the Cancel button, and Esc,
+   * which `<dialog>` answers with an empty `returnValue` and no submit event at all.
+   *
+   * 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.
+   */
+  dlg.addEventListener('close', () => {
+    if (dlg.returnValue !== 'deal') return;
+
+    const asked = field<HTMLInputElement>('ng-seed').value.trim();
+    // A seed the browser cannot parse is not a reason to refuse to deal — blank and unparseable
+    // both mean "surprise me", which is what leaving the box alone plainly asks for.
+    const seed = asked === '' || !Number.isFinite(Number(asked)) ? '' : String(Math.trunc(Number(asked)));
+    const picked = dlg.querySelector<HTMLInputElement>('input[name="ng-hand"]:checked')?.value;
+    const rules = houseRules({
+      houseRules: {
+        ...(STARTING_HAND_LABELS.some((o) => o.value === picked) ? { startingHand: picked as StartingHand } : {}),
+        revenue: {
+          passengerPerCoach: Number(field<HTMLInputElement>('ng-passenger').value),
+          freightPerLoad: Number(field<HTMLInputElement>('ng-freight').value),
+          trainPerTransit: Number(field<HTMLInputElement>('ng-transit').value),
+        },
+      },
+    });
+
+    clearSave();
+    const next = rulesToUrl(rules, 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.
+    if (next === location.search) location.reload();
+    else location.search = next;
+  });
 }
 
 const soundBtn = document.getElementById('sound');

src/web/play.html

@@ -40,6 +40,32 @@ header button:disabled:hover{border-color:#2c333d}
 .pace.good{background:rgba(40,140,60,.32)}
 .pace.behind{background:rgba(190,120,40,.28)}
 .yard.bare{outline:1px dashed #e0a060;outline-offset:3px;border-radius:4px;padding:3px}
+/* NEW GAME DIALOG. Native <dialog>, so Esc closes it and focus is trapped without any of that
+   being written here. Everything below is only colour and spacing: the browser's own white-on-white
+   default is unreadable against this page. */
+dialog{background:var(--panel);color:var(--fg);border:1px solid var(--line);border-radius:9px;
+  padding:16px 18px;max-width:520px;width:calc(100% - 32px);font:inherit;max-height:86vh;overflow:auto}
+dialog::backdrop{background:rgba(0,0,0,.62)}
+dialog h3{margin-top:15px}
+/* The rationale under each heading, not beside each control — the reasons are sentences, and a
+   sentence squeezed into a label column wraps into noise. */
+.ng-note{color:var(--dim);font-size:11.5px;margin:0 0 8px;line-height:1.45}
+dialog input[type=text],dialog input[type=number]{background:#0f1318;color:var(--fg);
+  border:1px solid var(--line);border-radius:5px;padding:4px 7px;font:inherit;font-size:13px}
+dialog input[type=text]{width:100%}
+dialog input[type=number]{width:64px;text-align:right}
+dialog input:focus{outline:none;border-color:#4d6fa8}
+/* Whole rows, so the click target is the sentence and not the 13px circle beside it. */
+.ng-radio{display:flex;gap:9px;align-items:flex-start;padding:6px 7px;border-radius:5px;cursor:pointer}
+.ng-radio:hover{background:#20262e}
+.ng-radio input{margin-top:3px;flex:0 0 auto}
+.ng-radio .dim{font-size:11.5px}
+.ng-num{display:flex;justify-content:space-between;align-items:center;gap:12px;padding:4px 7px}
+.ng-buttons{display:flex;justify-content:flex-end;gap:8px;margin:16px 0 0;padding:0}
+.ng-buttons button{background:#2a3038;color:inherit;border:1px solid var(--line);border-radius:5px;
+  padding:5px 14px;cursor:pointer;font:inherit;font-size:13px}
+.ng-buttons button:hover{border-color:#4d6fa8}
+#ng-deal{background:#31527f;border-color:#4d6fa8}
 main{display:grid;grid-template-columns:minmax(0,1fr) 400px;gap:14px;padding:14px;align-items:start}
 @media(max-width:1100px){main{grid-template-columns:1fr}}
 section{background:var(--panel);border:1px solid var(--line);border-radius:7px;
@@ -176,10 +202,15 @@ ul.blocked li{padding:2px 0}
        engine's guess at what your score ought to be were noise on the one line that must not wrap. -->
   <span id="objective" class="pace">—</span>
   <span class="dim">seed <span id="seed">—</span></span>
+  <!-- WHICH RULES THIS GAME IS BEING PLAYED UNDER. The settings are chosen when the game is dealt
+       and then never mentioned again, which makes a playtest note ("scored 4") unreadable a week
+       later: at 0 revenue per transit that is a different game from the same seed at 5. Short enough
+       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>
   <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 will be asked for a seed — leave it blank for a random one. 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>
+  <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>
   <a class="home" href="./replays.html" style="font-size:12px">replays</a>
   <span class="dim build" title="what is actually deployed">__BUILD__</span>
 </header>
@@ -248,6 +279,53 @@ ul.blocked li{padding:2px 0}
   </div>
 </main>
 
+<!-- ===================================================================
+     NEW GAME — the seed, the opening hand, and what the three economies pay.
+
+     It was a `prompt()` asking for a seed. Two of the three things that decide what kind of game
+     you are about to play had no way in at all: the opening hand had been changed twice with no
+     way back to the earlier rule, and the revenue rates were constants in the source. Balance is
+     the open question in this game (`TODO.md`), and the way to settle it is to deal several games
+     at different settings — which needs a dialog, not a rebuild.
+
+     Every control has a default that is the recommended answer, so DEAL with nothing touched is a
+     complete, sensible game. The settings ride in the URL alongside the seed, because a seed alone
+     no longer names a game: `?seed=430` with a different opening hand is a different railroad.
+     ==================================================================== -->
+<dialog id="newgamedlg" aria-labelledby="ng-title">
+  <form method="dialog" id="newgameform">
+    <h2 class="big" id="ng-title">New game</h2>
+
+    <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">
+
+    <h3>Starting hand</h3>
+    <p class="ng-note">What each player is dealt before the first turn. The hand limit is three either way — deal six and the first turn is spent choosing which of them to keep.</p>
+    <label class="ng-radio"><input type="radio" name="ng-hand" value="threeRandom" checked>
+      <span><b>Three random cards</b><br><span class="dim">The original rule. At the hand limit already, and no guarantee of track.</span></span></label>
+    <label class="ng-radio"><input type="radio" name="ng-hand" value="sixRandom">
+      <span><b>Six random cards</b><br><span class="dim">Twice the choice, still no guaranteed track — the first turn is a discard.</span></span></label>
+    <label class="ng-radio"><input type="radio" name="ng-hand" value="threeTrackThreeOther">
+      <span><b>Three random track and three random non-track cards</b><br><span class="dim">Dealt from two piles, so the district you can build is dealt rather than waited for.</span></span></label>
+
+    <h3>Revenue</h3>
+    <p class="ng-note">What each piece of work pays, 0 to 5. A coach pays when it is boarded and again when it is detrained; a load pays when it is made up and again when it is broken. Zero switches an economy off so the others can be read.</p>
+    <label class="ng-num"><span>Passenger revenue per coach</span>
+      <input id="ng-passenger" type="number" min="0" max="5" step="1" value="1"></label>
+    <label class="ng-num"><span>Freight revenue per load</span>
+      <input id="ng-freight" type="number" min="0" max="5" step="1" value="1"></label>
+    <label class="ng-num"><span>Train revenue per transit</span>
+      <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>
+
+    <menu class="ng-buttons">
+      <button value="cancel" id="ng-cancel" type="submit" formnovalidate>Cancel</button>
+      <button value="deal" id="ng-deal" type="submit">Deal</button>
+    </menu>
+  </form>
+</dialog>
+
 <script type="module" src="./web/main.js"></script>
 </body>
 </html>

src/web/session.ts

@@ -17,10 +17,12 @@
 
 import type { Intent } from '../engine/intents.ts';
 import type { Frame } from '../sim/view.ts';
-import type { GameConfig, PlayerIndex } from '../engine/state.ts';
+import type { PlayerIndex } from '../engine/state.ts';
+import type { HouseRuleOverrides } from '../engine/content.ts';
 import type { Game, Menu, Save } from './game.ts';
 import {
   actionMenu,
+  configWith,
   currentActor,
   fromSave,
   handPlayable,
@@ -112,9 +114,15 @@ 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.
  */
-export function createLocalSession(seed: number, config?: GameConfig): LocalSession {
-  let game: Game = config ? newGame(seed, config) : newGame(seed);
+export function createLocalSession(seed: number, rules?: HouseRuleOverrides): LocalSession {
+  let game: Game = rules ? newGame(seed, configWith(rules)) : newGame(seed);
   const listeners = new Set<() => void>();
   const changed = (): void => {
     for (const fn of [...listeners]) fn();