Expand game engine, replay, tests, and documentation

src/engine/events.ts

@@ -41,6 +41,18 @@ export type GameEvent =
    * the advanced RNG so that folding events reproduces the draw exactly.
    */
   | { type: 'trainScheduled'; player: PlayerIndex; trainNumber: number; roll: number; slot: number; rngState: number }
+  /**
+   * Train lifecycle. These were originally squeezed into `phaseBegan` with a free-text label,
+   * which made the replay say "New Train" and nothing else. A train being made up, departing,
+   * arriving or finishing its run are four distinct facts and deserve four event types.
+   */
+  | { type: 'extraQueued'; player: PlayerIndex; trainNumber: number }
+  | { type: 'secondSectionOrdered'; player: PlayerIndex; trainNumber: number }
+  | { type: 'trainMadeUp'; trainNumber: number; isExtra: boolean; at: string; direction: string }
+  | { type: 'trainHeld'; trainNumber: number; reason: string }
+  | { type: 'trainHighballed'; trainNumber: number; from: string; to: string }
+  | { type: 'trainArrived'; trainNumber: number; consist: RollingStock[]; office: string }
+  | { type: 'trainCompleted'; trainNumber: number; consist: RollingStock[] }
   | { type: 'carPlacedOnTrain'; player: PlayerIndex; trayId: TrayId; stock: RollingStock }
   | { type: 'carPassed'; player: PlayerIndex; trayId: TrayId }
   | { type: 'clearanceRequested'; trainId: TrayId; occupiedBy: TrayId }