/**
 * Component 1 — Card catalogue / static content.
 *
 * TRANSCRIBED FROM THE RECOVERED DESIGN FILES (2026-07-30):
 *   docs/Deck cards2.xlsx   — the complete card list and counts
 *   docs/Trains3.pdf        — all 22 train cards
 *   docs/Mainline Cards.pdf — the ten Mainline card types
 *   docs/tracks.png         — card art
 *
 * This replaced an invented 52-card placeholder. See docs/rules/implications.md for what changed
 * and which decisions it supersedes.
 *
 * This is DATA, not logic. Keep tuning confined here so it never requires touching the engine.
 *
 * BEHAVIOUR NOT YET IMPLEMENTED, pending answers from the designer (implications.md §10): the
 * meaning of Mainline speeds and Fast/Slow, the "Expedite" keyword, lockout semantics, and how
 * space-use cards are played. The DATA for all of these is transcribed below and marked.
 */

// ---------------------------------------------------------------------------
// Primitives
// ---------------------------------------------------------------------------

export type CarType = 'coach' | 'boxcar' | 'reefer' | 'hopper' | 'tank' | 'caboose';
export type Direction = 'east' | 'west';

/** §9 — an industry loads only, unloads only, or does both. */
export type FlowDirection = 'outbound' | 'inbound' | 'both';

export type OfficeTier = 'whistlePost' | 'depot' | 'station' | 'terminal';

/** The six industries in the design. Note: no "oilRefinery" — it is `refinery`. */
export type FreightKind =
  | 'freightHouse'
  | 'mineTipple'
  | 'refinery'
  | 'powerPlant'
  | 'packingSheds'
  | 'grocersWarehouse';

export type TrackGeometry = 'straight' | 'curved' | 'sharpCurved' | 'turnout';
export type Hand = 'left' | 'right' | 'none';

// ---------------------------------------------------------------------------
// Track — a PER-PLAYER supply, not deck cards
// ---------------------------------------------------------------------------

export type TrackProfile = {
  geometry: TrackGeometry;
  hand: Hand;
  name: string;
  perPlayer: number;
  /** Column J of the sheet, "Train can stop here". Turnouts are blank. */
  isOperationalRail: boolean;
  /** Sharp curves: "Any move across this track is doubled (two moves)". */
  moveCost: number;
};

/**
 * 26 pieces per player, 104 for four players. Track is NOT in the Home Office deck — this is the
 * single biggest structural change from the placeholder, and it means the draw is entirely about
 * industry, trains and enhancements.
 *
 * Handedness is PRINTED, not chosen on placement. That supersedes Gap 11.
 */
export const TRACK_SUPPLY: readonly TrackProfile[] = [
  { geometry: 'straight', hand: 'none', name: 'Straight track', perPlayer: 8, isOperationalRail: true, moveCost: 1 },
  { geometry: 'curved', hand: 'left', name: 'Curved track (left)', perPlayer: 4, isOperationalRail: true, moveCost: 1 },
  { geometry: 'curved', hand: 'right', name: 'Curved track (right)', perPlayer: 4, isOperationalRail: true, moveCost: 1 },
  { geometry: 'sharpCurved', hand: 'left', name: 'Sharp Curved Track (left)', perPlayer: 1, isOperationalRail: true, moveCost: 2 },
  { geometry: 'sharpCurved', hand: 'right', name: 'Sharp Curved Track (right)', perPlayer: 1, isOperationalRail: true, moveCost: 2 },
  { geometry: 'turnout', hand: 'left', name: 'Turnout (left)', perPlayer: 4, isOperationalRail: false, moveCost: 1 },
  { geometry: 'turnout', hand: 'right', name: 'Turnout (right)', perPlayer: 4, isOperationalRail: false, moveCost: 1 },
];

export const TRACK_PER_PLAYER = TRACK_SUPPLY.reduce((n, t) => n + t.perPlayer, 0); // 26

/** Start cards, placed at setup and never shuffled: 4 Whistle Posts, 8 Limits. */
export const WHISTLE_POST_SUPPLY = 4;
export const LIMITS_SUPPLY = 8;

/** Legacy alias kept so existing call sites resolve; prefer TRACK_SUPPLY. */
export const TRACK_PROFILES = TRACK_SUPPLY;

// ---------------------------------------------------------------------------
// Offices — Depot 4, Station 2, Terminal 1
// ---------------------------------------------------------------------------

export type OfficeProfile = {
  tier: OfficeTier;
  name: string;
  isControlPoint: boolean;
  isPassengerFacility: boolean;
  adTracks: number;
  porters: number;
  /** Green slots. The design gives slots EQUAL to porters, not one more. */
  passengerOut: number;
  /** Red slots. */
  passengerIn: number;
  copiesInDeck: number;
};

/**
 * A/D tracks and Porter counts are exactly as designed. The slot counts are corrected downward:
 * an earlier guess gave one more slot than porters at every tier. Capacity is instead grown by the
 * passenger modifier cards (Waiting Area, Restaurant, Hotel).
 */
/**
 * Office cards. `copiesInDeck` was **doubled** (Depot 4→8, Station 2→4, Terminal 1→2) — Q12.
 *
 * Players always start at a Whistle Post, which has ONE A/D track, so a second arrival is an
 * automatic collision (§8.3, Gap 2a). Measured at the original density, 25 of 100 games never drew
 * a Depot and never escaped: they averaged **−6.0** revenue against **−0.4** for games that
 * upgraded at least once, and 25 of 26 collisions happened at Whistle Post. Escaping needed one of
 * 4 Depot cards in 111, roughly a 59% chance across a game's draws.
 *
 * Upgrades are strictly sequential (Gap 3b, no skipping), so Station and Terminal are rarer than
 * their raw counts imply — Terminal needs all three cards in order. Station and Terminal were
 * doubled with Depot to keep that ladder in proportion rather than making Depot a special case.
 *
 * PROVISIONAL — re-evaluate. This was chosen to remove a 25% chance of an unwinnable opening deal,
 * not from the recovered design, and it is a blunt instrument: it lifts the whole office ladder and
 * dilutes every other category slightly (deck 133 → 140). Revisit once the victory target is
 * settled and freight is carrying its intended share; the right answer may instead be fewer
 * Terminals, a cheaper first upgrade, or more A/D capacity at Whistle Post.
 */
export const OFFICE_PROFILES: readonly OfficeProfile[] = [
  { tier: 'whistlePost', name: 'Whistle Post', isControlPoint: false, isPassengerFacility: false, adTracks: 1, porters: 0, passengerOut: 0, passengerIn: 0, copiesInDeck: 0 },
  { tier: 'depot', name: 'Depot', isControlPoint: true, isPassengerFacility: true, adTracks: 2, porters: 1, passengerOut: 1, passengerIn: 1, copiesInDeck: 8 },
  { tier: 'station', name: 'Station', isControlPoint: true, isPassengerFacility: true, adTracks: 3, porters: 2, passengerOut: 2, passengerIn: 2, copiesInDeck: 4 },
  { tier: 'terminal', name: 'Terminal', isControlPoint: true, isPassengerFacility: true, adTracks: 4, porters: 3, passengerOut: 3, passengerIn: 3, copiesInDeck: 2 },
];

export const OFFICE_ORDER: readonly OfficeTier[] = ['whistlePost', 'depot', 'station', 'terminal'];

export function officeProfile(tier: OfficeTier): OfficeProfile {
  const found = OFFICE_PROFILES.find((p) => p.tier === tier);
  if (!found) throw new Error(`unknown office tier: ${tier}`);
  return found;
}

export function nextOfficeTier(tier: OfficeTier): OfficeTier | null {
  const i = OFFICE_ORDER.indexOf(tier);
  return i >= 0 && i + 1 < OFFICE_ORDER.length ? OFFICE_ORDER[i + 1]! : null;
}

// ---------------------------------------------------------------------------
// Industries — one car out, one loader. Capacity grows via modifiers.
// ---------------------------------------------------------------------------

export type IndustryProfile = {
  kind: FreightKind;
  name: string;
  carTypes: readonly CarType[];
  flow: FlowDirection;
  /** Base green-box capacity. Every industry starts at ONE. */
  baseOut: number;
  /** Base red-box capacity. */
  baseIn: number;
  /** "Loaders" in the design; the rules PDF calls them Laborers. One to start. */
  baseLoaders: number;
  /** Column E — industries that may not coexist with this one. Semantics pending (§10 Q4). */
  lockouts: readonly FreightKind[];
  copies: number;
};

/**
 * Industry density (Gap 12). The recovered sheet lists 9 industries in a 115-card deck; the
 * prototype ran 10 in 52. At 9-in-115 a game saw 1.6 Freight Facilities, freight was 10% of gross
 * revenue, and `carsCoupled` fired 4 times per 100 games — the freight loop, which is the point of
 * the game, effectively never ran.
 *
 * Each industry's `copies` is TRIPLED, giving 27 in 133. That restores roughly the prototype's
 * ratio while preserving the sheet's proportions exactly: the outbound/inbound balance and the
 * lockout structure are unchanged, because every kind scales by the same factor.
 */
export const INDUSTRY_PROFILES: readonly IndustryProfile[] = [
  { kind: 'freightHouse', name: 'Freight House', carTypes: ['boxcar'], flow: 'both', baseOut: 1, baseIn: 1, baseLoaders: 1, lockouts: ['grocersWarehouse'], copies: 6 },
  { kind: 'mineTipple', name: 'Mine Tipple', carTypes: ['hopper'], flow: 'outbound', baseOut: 1, baseIn: 0, baseLoaders: 1, lockouts: ['powerPlant'], copies: 6 },
  { kind: 'refinery', name: 'Refinery', carTypes: ['tank'], flow: 'outbound', baseOut: 1, baseIn: 0, baseLoaders: 1, lockouts: ['powerPlant'], copies: 3 },
  { kind: 'powerPlant', name: 'Power Plant', carTypes: ['hopper', 'tank'], flow: 'inbound', baseOut: 0, baseIn: 1, baseLoaders: 1, lockouts: ['mineTipple', 'refinery'], copies: 6 },
  { kind: 'packingSheds', name: 'Packing Sheds', carTypes: ['reefer'], flow: 'outbound', baseOut: 1, baseIn: 0, baseLoaders: 1, lockouts: ['grocersWarehouse'], copies: 3 },
  { kind: 'grocersWarehouse', name: "Grocer's Warehouse", carTypes: ['boxcar', 'reefer'], flow: 'inbound', baseOut: 0, baseIn: 1, baseLoaders: 1, lockouts: ['packingSheds', 'freightHouse'], copies: 3 },
];

/** Legacy alias; the engine still reads FREIGHT_PROFILES in places. */
export const FREIGHT_PROFILES = INDUSTRY_PROFILES;

/** §9.3 — the collective term for an industry that both loads and unloads. */
export function isFreightHouse(p: IndustryProfile): boolean {
  return p.flow === 'both';
}

export function industryProfile(kind: FreightKind): IndustryProfile {
  const f = INDUSTRY_PROFILES.find((p) => p.kind === kind);
  if (!f) throw new Error(`unknown industry: ${kind}`);
  return f;
}

// ---------------------------------------------------------------------------
// Modifiers — 17 industry + 6 passenger, each tied to specific hosts
// ---------------------------------------------------------------------------

export type ModifierKind =
  | 'waitingArea' | 'restaurant' | 'hotel'
  | 'truckDock' | 'railroadExpressAgency' | 'forklifts'
  | 'prepPlant' | 'coalPiles' | 'conveyorBelts'
  | 'pipelines' | 'oilDepot' | 'viscosityBreakers'
  | 'transmissionLines' | 'rotaryDumps' | 'steamTurbines'
  | 'iceHouse' | 'localSmallGroceries';

export type ModifierProfile = {
  kind: ModifierKind;
  name: string;
  /** Which hosts it may sit beside. 'office' means any Passenger Facility. */
  hosts: readonly (FreightKind | 'office')[];
  addOut: number;
  addIn: number;
  addLoaders: number;
  addPorters: number;
  copies: number;
};

export const MODIFIER_PROFILES: readonly ModifierProfile[] = [
  // Passenger — "Add 1 Psgn out, 1 porter"
  { kind: 'waitingArea', name: 'Waiting area', hosts: ['office'], addOut: 1, addIn: 0, addLoaders: 0, addPorters: 1, copies: 3 },
  { kind: 'restaurant', name: 'Restaurant', hosts: ['office'], addOut: 1, addIn: 0, addLoaders: 0, addPorters: 1, copies: 2 },
  { kind: 'hotel', name: 'Hotel', hosts: ['office'], addOut: 1, addIn: 0, addLoaders: 0, addPorters: 1, copies: 1 },
  // Freight House / Packing Sheds / Grocer's
  { kind: 'truckDock', name: 'Truck dock', hosts: ['freightHouse', 'packingSheds', 'grocersWarehouse'], addOut: 1, addIn: 0, addLoaders: 1, addPorters: 0, copies: 2 },
  { kind: 'railroadExpressAgency', name: 'Railroad Express Agency', hosts: ['freightHouse'], addOut: 1, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
  { kind: 'forklifts', name: 'Forklifts', hosts: ['freightHouse', 'packingSheds'], addOut: 1, addIn: 0, addLoaders: 1, addPorters: 0, copies: 2 },
  // Mine Tipple
  { kind: 'prepPlant', name: 'Prep Plant', hosts: ['mineTipple'], addOut: 1, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
  { kind: 'coalPiles', name: 'Coal Piles', hosts: ['mineTipple'], addOut: 1, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
  { kind: 'conveyorBelts', name: 'Conveyor Belts', hosts: ['mineTipple'], addOut: 1, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
  // Refinery
  { kind: 'pipelines', name: 'Pipelines', hosts: ['refinery'], addOut: 1, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
  { kind: 'oilDepot', name: 'Oil Depot', hosts: ['refinery'], addOut: 1, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
  { kind: 'viscosityBreakers', name: 'Viscosity breakers', hosts: ['refinery'], addOut: 1, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
  // Power Plant — inbound, so these add loaders rather than outbound capacity
  { kind: 'transmissionLines', name: 'Transmission lines', hosts: ['powerPlant'], addOut: 0, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
  { kind: 'rotaryDumps', name: 'Rotary Dumps', hosts: ['powerPlant'], addOut: 0, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
  { kind: 'steamTurbines', name: 'Steam Turbines', hosts: ['powerPlant'], addOut: 0, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
  // Produce
  { kind: 'iceHouse', name: 'Ice House', hosts: ['packingSheds', 'grocersWarehouse'], addOut: 1, addIn: 0, addLoaders: 1, addPorters: 0, copies: 2 },
  { kind: 'localSmallGroceries', name: 'Local small groceries', hosts: ['grocersWarehouse'], addOut: 0, addIn: 0, addLoaders: 1, addPorters: 0, copies: 1 },
];

export function modifierProfile(kind: ModifierKind): ModifierProfile {
  const m = MODIFIER_PROFILES.find((p) => p.kind === kind);
  if (!m) throw new Error(`unknown modifier: ${kind}`);
  return m;
}

// ---------------------------------------------------------------------------
// Trains — 22 cards, named, with speed class and individual rules
// ---------------------------------------------------------------------------

export type TrainSpeed = 'fast' | 'slow';

/**
 * Consists are specified by CATEGORY, not by car type: "Freight (2)" means any two freight cars.
 * `freightTypes` narrows it where a card does (X14 is reefers only).
 */
export type ConsistSpec = {
  freight: number;
  coach: number;
  caboose: number;
  freightTypes?: readonly CarType[];
  /** X13 Appleseed: empties only. */
  emptiesOnly?: boolean;
};

/** Operating rules printed on the card. Behaviour pending §10 Q1 for `expedite`. */
export type TrainRules = {
  noSwitching?: boolean;
  terminalsOnly?: boolean;
  expedite?: boolean;
  /** Train 7/8: "Coach must remain on station track if switching." */
  coachStaysOnStationTrack?: boolean;
  /** Train 3/4: may drop or pick up one freight car at every location. */
  oneFreightPerLocation?: boolean;
  noPassengerWork?: boolean;
  /** X13: may drop empties but not pick anything up. X22: may only pick up empties. */
  dropOnly?: boolean;
  pickUpEmptiesOnly?: boolean;
  /** X17 Campaign, X18 Circus: a scheduled stop that does something. */
  stopEarnsPoint?: boolean;
  stopThenExpedite?: boolean;
  /** The Second Section card copies the next scheduled train. */
  copiesNextScheduled?: boolean;
  note?: string;
};

export type TrainProfile = {
  number: number;
  isExtra: boolean;
  name: string;
  speed: TrainSpeed;
  direction: Direction | 'playerChoice';
  consist: ConsistSpec;
  rules: TrainRules;
};

/** Odd numbers run westbound, even eastbound (§2.3). Pairs share a class. */
function pair(odd: number, name: string, speed: TrainSpeed, consist: ConsistSpec, rules: TrainRules): TrainProfile[] {
  return [
    { number: odd, isExtra: false, name, speed, direction: 'west', consist, rules },
    { number: odd + 1, isExtra: false, name, speed, direction: 'east', consist, rules },
  ];
}

export const TIMETABLED_TRAINS: readonly TrainProfile[] = [
  ...pair(1, 'Crack Limited', 'fast', { freight: 0, coach: 3, caboose: 0 },
    { terminalsOnly: true, noSwitching: true, expedite: true, note: 'Stop at Terminals only.' }),
  ...pair(3, 'Express', 'fast', { freight: 2, coach: 0, caboose: 0 },
    { oneFreightPerLocation: true, expedite: true, note: 'May drop or pick up one freight car at every location.' }),
  ...pair(5, 'The Sparrow', 'fast', { freight: 0, coach: 2, caboose: 0 },
    { noSwitching: true, expedite: true }),
  ...pair(7, 'Local', 'slow', { freight: 1, coach: 1, caboose: 0 },
    { coachStaysOnStationTrack: true, note: 'Maximum one freight, one coach.' }),
  ...pair(9, 'Heavy Freight', 'slow', { freight: 3, coach: 0, caboose: 1 }, {}),
  ...pair(11, 'Drag Freight', 'slow', { freight: 2, coach: 0, caboose: 1 }, {}),
];

/**
 * Extras are X13–X22 — ALL junior to every timetabled train, so Gap 5's tie between an Extra and a
 * Timetabled train of the same number can no longer occur.
 */
export const EXTRA_TRAINS: readonly TrainProfile[] = [
  { number: 13, isExtra: true, name: 'Appleseed Extra', speed: 'slow', direction: 'playerChoice', consist: { freight: 3, coach: 0, caboose: 1, emptiesOnly: true }, rules: { dropOnly: true, note: 'May drop MTs but not pick up anything.' } },
  { number: 14, isExtra: true, name: 'Fruit Growers Express', speed: 'fast', direction: 'playerChoice', consist: { freight: 2, coach: 0, caboose: 1, freightTypes: ['reefer'] }, rules: { expedite: true, note: 'Reefers only. May pick up one extra loaded reefer.' } },
  { number: 15, isExtra: true, name: 'Yard Xfer', speed: 'slow', direction: 'playerChoice', consist: { freight: 2, coach: 0, caboose: 1 }, rules: {} },
  { number: 16, isExtra: true, name: 'Light Engine Move', speed: 'fast', direction: 'playerChoice', consist: { freight: 0, coach: 0, caboose: 0 }, rules: { noSwitching: true, note: 'No cars at all.' } },
  { number: 17, isExtra: true, name: 'Campaign Train', speed: 'fast', direction: 'playerChoice', consist: { freight: 0, coach: 1, caboose: 0 }, rules: { noSwitching: true, stopThenExpedite: true, note: 'One turn at station (speeches) then expedite.' } },
  { number: 18, isExtra: true, name: 'Circus Train', speed: 'slow', direction: 'playerChoice', consist: { freight: 2, coach: 1, caboose: 1 }, rules: { noSwitching: true, stopEarnsPoint: true, note: 'One turn stopped on any track (circus set-up) earns 1 point.' } },
  { number: 19, isExtra: true, name: 'Military Train', speed: 'slow', direction: 'playerChoice', consist: { freight: 1, coach: 2, caboose: 0 }, rules: { noSwitching: true, noPassengerWork: true, expedite: true } },
  { number: 20, isExtra: true, name: "Director's private car", speed: 'slow', direction: 'playerChoice', consist: { freight: 2, coach: 1, caboose: 0 }, rules: { noPassengerWork: true } },
  { number: 21, isExtra: true, name: 'Freight Extra', speed: 'slow', direction: 'playerChoice', consist: { freight: 3, coach: 0, caboose: 1 }, rules: {} },
  { number: 22, isExtra: true, name: 'Pee-Dee', speed: 'slow', direction: 'playerChoice', consist: { freight: 0, coach: 0, caboose: 1 }, rules: { pickUpEmptiesOnly: true, note: 'Per-diem train. May only pick up MTs.' } },
];

export const ALL_TRAINS: readonly TrainProfile[] = [...TIMETABLED_TRAINS, ...EXTRA_TRAINS];

export function trainProfile(number: number, isExtra: boolean): TrainProfile | null {
  return ALL_TRAINS.find((t) => t.number === number && t.isExtra === isExtra) ?? null;
}

/** Total cars a consist calls for. The Crew Tray limit still applies (§A.4). */
export function consistSize(c: ConsistSpec): number {
  return c.freight + c.coach + c.caboose;
}

// ---------------------------------------------------------------------------
// Mainline cards — ten types, with speeds and named entry points
// ---------------------------------------------------------------------------

export type MainlineKind =
  | 'plains' | 'curves' | 'hilly' | 'heavyGrade' | 'doubleTrack'
  | 'uncontrolledSiding' | 'tunnel' | 'trestle' | 'yard';

/**
 * Speed as printed. `60` and `30` appear on the cards; Hilly prints P60/F30, and Heavy Grade
 * prints "G" with the player setting orientation.
 *
 * WHAT THESE NUMBERS MEAN IS NOT YET SETTLED — see implications.md §10 Q2. Transcribed as data so
 * the answer can be applied without re-reading the cards.
 */
export type MainlineSpeed =
  | { kind: 'uniform'; value: number }
  | { kind: 'byTrainType'; passenger: number; freight: number }
  | { kind: 'grade' };

export type MainlineProfile = {
  kind: MainlineKind;
  name: string;
  speed: MainlineSpeed;
  /** Double Track and Uncontrolled Siding: "Trains may pass". */
  trainsMayPass: boolean;
  /** Yard: "Sort cars in new order". */
  sortsCars: boolean;
  /** Named entry points printed on the card; some are unlocked by modifier cards. */
  entryPoints: readonly string[];
};

export const MAINLINE_PROFILES: readonly MainlineProfile[] = [
  { kind: 'plains', name: 'Plains', speed: { kind: 'uniform', value: 60 }, trainsMayPass: false, sortsCars: false, entryPoints: ['start'] },
  { kind: 'curves', name: 'Curves', speed: { kind: 'uniform', value: 30 }, trainsMayPass: false, sortsCars: false, entryPoints: ['start'] },
  { kind: 'hilly', name: 'Hilly', speed: { kind: 'byTrainType', passenger: 60, freight: 30 }, trainsMayPass: false, sortsCars: false, entryPoints: ['passenger', 'freight'] },
  { kind: 'heavyGrade', name: 'Heavy Grade', speed: { kind: 'grade' }, trainsMayPass: false, sortsCars: false, entryPoints: ['start', 'brakemen', 'airbrakes', 'helpers'] },
  { kind: 'doubleTrack', name: 'Double Track', speed: { kind: 'uniform', value: 60 }, trainsMayPass: true, sortsCars: false, entryPoints: ['start'] },
  { 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'] },
];

/**
 * How many Stages a train needs to cross a Mainline card.
 *
 * Q1 — the printed 60/30 are miles per hour expressed as crossing time: a 60 card takes one Stage,
 * a 30 card takes two. The cells drawn on the cards are decoration.
 * Q2 — a Slow train adds one Stage to every card.
 *
 * Hilly prints P60/F30, so it reads the consist rather than the speed class: a train carrying any
 * coach is "passenger" for this purpose.
 */
export function crossingStages(
  kind: MainlineKind,
  trainSpeed: TrainSpeed,
  carriesPassengers: boolean,
  modifiers: readonly string[] = [],
  direction: Direction = 'east',
  gradeUp: Direction = 'east',
): number {
  const profile = MAINLINE_PROFILES.find((m) => m.kind === kind);
  if (!profile) throw new Error(`unknown mainline card: ${kind}`);

  let mph: number;
  switch (profile.speed.kind) {
    case 'uniform':
      mph = profile.speed.value;
      break;
    case 'byTrainType':
      mph = carriesPassengers ? profile.speed.passenger : profile.speed.freight;
      break;
    case 'grade':
      // Heavy Grade has no printed number; the modifier cards are what improve it, so it is a 30
      // until one is placed.
      mph = 30;
      break;
  }

  const base = mph >= 60 ? 1 : 2;
  const stages = base + (trainSpeed === 'slow' ? 1 : 0);
  return Math.max(1, stages - gradeReduction(profile, modifiers, direction, gradeUp));
}

/**
 * Q11, answered: the Heavy Grade card prints "(Up)" and "Player sets orientation", so which way it
 * climbs is a property of the placed card, not a constant. `gradeUp` is the direction a train is
 * travelling when it goes UPHILL; a train heading the other way is descending.
 *
 * Each applicable card takes a Stage off, never below one: a train cannot cross in no time.
 * Airbrakes only counts when Brakeman is already there, which the placement rule enforces.
 */
function gradeReduction(
  profile: MainlineProfile,
  modifiers: readonly string[],
  direction: Direction,
  gradeUp: Direction,
): number {
  if (profile.speed.kind !== 'grade') return 0;
  const downhill = direction !== gradeUp;
  let n = 0;
  if (downhill) {
    if (modifiers.includes('brakeman')) n++;
    if (modifiers.includes('airbrakes')) n++;
  } else if (modifiers.includes('helpers')) {
    n++;
  }
  return n;
}

export function mainlineProfile(kind: MainlineKind): MainlineProfile {
  const p = MAINLINE_PROFILES.find((m) => m.kind === kind);
  if (!p) throw new Error(`unknown mainline card: ${kind}`);
  return p;
}

/** Which Mainline modifiers may sit on `kind`, and what each additionally requires. */
export const MAINLINE_MODIFIER_RULES: readonly {
  key: string;
  /** Only placeable on a card whose speed is a grade. */
  gradeOnly: boolean;
  /** Another modifier that must already be on the same card. */
  requiresOnCard?: string;
}[] = [
  { key: 'brakeman', gradeOnly: true },
  { key: 'airbrakes', gradeOnly: true, requiresOnCard: 'brakeman' },
  { key: 'helpers', gradeOnly: true },
  { key: 'realignment', gradeOnly: false },
];

export function mainlineModifierRule(key: string) {
  return MAINLINE_MODIFIER_RULES.find((r) => r.key === key) ?? null;
}

/** `Realignment` converts one Mainline card into another. */
export const REALIGNMENTS: readonly { from: MainlineKind; to: MainlineKind }[] = [
  { from: 'plains', to: 'doubleTrack' },
  { from: 'curves', to: 'plains' },
  { from: 'uncontrolledSiding', to: 'doubleTrack' },
  { from: 'trestle', to: 'uncontrolledSiding' },
];

// ---------------------------------------------------------------------------
// The four new card categories
// ---------------------------------------------------------------------------

export type SimpleCard = { key: string; name: string; copies: number; placement: string; effect: string };

/** "Burns tablespace" — occupies a grid cell and does nothing useful. Semantics pending §10 Q6. */
export const SPACE_USE_CARDS: readonly SimpleCard[] = [
  { key: 'beanHouse', name: 'Bean house', copies: 1, placement: 'adjacent to any straight, curve, turnout, Limit', effect: 'Burns tablespace.' },
  { key: 'flopHouse', name: 'Flop house', copies: 1, placement: 'adjacent to any straight, curve, turnout', effect: 'Burns tablespace.' },
  { key: 'watertower', name: 'Watertower', copies: 1, placement: 'adjacent to any straight, turnout on Running Track', effect: 'Burns tablespace.' },
  { key: 'hoboJungle', name: 'Hobo Jungle', copies: 1, placement: 'adjacent to any straight, turnout, Limit on Running Track', effect: 'Burns tablespace. Vandalism can loot a boxcar passing it.' },
  { key: 'sectionHouse', name: 'Section House', copies: 1, placement: 'adjacent to any straight, curve, turnout', effect: 'Burns tablespace.' },
  { key: 'cityBlocks', name: 'City blocks', copies: 4, placement: 'adjacent to any straight, curve, turnout, Limit', effect: 'Burns tablespace.' },
  { key: 'engineShops', name: 'Engine Shops', copies: 1, placement: 'adjacent to any straight, curve, turnout', effect: 'Burns tablespace.' },
  { key: 'tenderloin', name: 'Tenderloin District', copies: 1, placement: 'adjacent to any straight, curve, turnout, Limit', effect: 'Burns tablespace.' },
  { key: 'engineerCemetery', name: 'Engineer cemetery', copies: 1, placement: 'adjacent to any straight, curve, turnout, Limit', effect: 'Burns tablespace.' },
];

export type EnhancementKey =
  | 'interlocking' | 'facingPointLocks' | 'yardOffice' | 'smallYard'
  | 'waterColumn' | 'overpass' | 'telegraph' | 'telephone' | 'radio' | 'absSignals';

/** Where an Enhancement may be laid. */
export type EnhancementPlacement =
  | 'runningTrackStraight'
  | 'secondaryTrackStraight'
  | 'mainlineCard'
  | 'onCard';

export type EnhancementRule = {
  key: EnhancementKey;
  placement: EnhancementPlacement;
  /** Must sit on a card already carrying this enhancement (Telephone on Telegraph, etc.). */
  requiresOnSameCard?: EnhancementKey;
  /** Must exist somewhere in the district (Facing Point Locks needs Interlocking). */
  requiresInDistrict?: EnhancementKey;
  /** Bonus added to an opposing train's number when resolving a meet, once a Day. */
  dispatchBonus?: number;
};

export const ENHANCEMENT_RULES: readonly EnhancementRule[] = [
  { key: 'interlocking', placement: 'runningTrackStraight' },
  { key: 'facingPointLocks', placement: 'onCard', requiresInDistrict: 'interlocking' },
  { key: 'yardOffice', placement: 'secondaryTrackStraight' },
  { key: 'smallYard', placement: 'secondaryTrackStraight' },
  { key: 'waterColumn', placement: 'runningTrackStraight' },
  { key: 'overpass', placement: 'onCard' },
  { key: 'telegraph', placement: 'runningTrackStraight', dispatchBonus: 4 },
  { key: 'telephone', placement: 'onCard', requiresOnSameCard: 'telegraph', dispatchBonus: 8 },
  { key: 'radio', placement: 'onCard', requiresOnSameCard: 'telephone', dispatchBonus: 12 },
  { key: 'absSignals', placement: 'mainlineCard' },
];

export function enhancementRule(key: string): EnhancementRule | null {
  return ENHANCEMENT_RULES.find((r) => r.key === key) ?? null;
}

export const ENHANCEMENT_CARDS: readonly SimpleCard[] = [
  { key: 'interlocking', name: 'Interlocking', copies: 2, placement: 'any Running Track Straight', effect: 'May stop an inbound train on the Limit Track.' },
  { key: 'facingPointLocks', name: 'Facing Point Locks', copies: 2, placement: 'adjacent to Interlocking', effect: 'Must have Interlocking. Prevents Derail being played on you.' },
  { key: 'yardOffice', name: 'Yard office', copies: 1, placement: 'any Secondary Track Straight', effect: 'An inbound train with no coaches that can reach the yard office in one move may arrive there instead of the Train Order Office.' },
  { key: 'smallYard', name: 'Small yard', copies: 1, placement: 'any Secondary Track Straight', effect: 'A train that spends one move in the yard may sort itself into ANY order, including cars ahead of the engine.' },
  { key: 'waterColumn', name: 'Water column', copies: 2, placement: 'any Running Track Straight', effect: 'Lets you remove any Watertower in your district.' },
  { key: 'overpass', name: 'Overpass', copies: 1, placement: 'any Railroad Crossing', effect: 'Removes the restrictions of a played Railroad Crossing.' },
  { key: 'telegraph', name: 'Telegraph', copies: 3, placement: 'any Running Track Straight', effect: 'Once a day, when dispatching facing trains, add +4 to the other train’s number.' },
  { key: 'telephone', name: 'Telephone', copies: 2, placement: 'on Telegraph', effect: 'Once a day, add +8 to the other train’s number.' },
  { key: 'radio', name: 'Radio', copies: 2, placement: 'on Telephone', effect: 'Once a day, add +12 to the other train’s number.' },
  { key: 'absSignals', name: 'ABS Signals', copies: 2, placement: 'any Mainline card', effect: 'Trains on this card will not rear-end each other; they stop short of a collision.' },
];

export const MAINLINE_MODIFIER_CARDS: readonly SimpleCard[] = [
  { key: 'brakeman', name: 'Brakeman', copies: 1, placement: 'a GRADE Mainline card', effect: 'Faster passage downhill.' },
  { key: 'airbrakes', name: 'Airbrakes', copies: 1, placement: 'a GRADE Mainline card', effect: 'Faster passage downhill. Brakeman must be in effect.' },
  { key: 'helpers', name: 'Helpers', copies: 1, placement: 'a GRADE Mainline card', effect: 'Faster passage uphill.' },
  { key: 'realignment', name: 'Realignment', copies: 2, placement: 'a Mainline card', effect: 'Convert one Mainline type to another. Not while a train is on it.' },
  { key: 'facingPointLocksMainline', name: 'Facing Point Locks', copies: 2, placement: 'adjacent to Interlocking', effect: 'Prevents Derail being played on you.' },
];

/**
 * Q9 — the Second Section card. Played on a train that is DUE OUT; a second identical train runs
 * immediately behind it, needing its own Crew Tray. It deliberately creates the following-train
 * situation §8.1 makes the Superintendent rule on. Supersedes the "Sister trains" optional rule.
 */
export const SECOND_SECTION = { key: 'secondSection', name: 'Second Section', copies: 1 };

export const MANEUVER_CARDS: readonly SimpleCard[] = [
  { key: 'redFlags', name: 'Red Flags', copies: 5, placement: 'any time', effect: 'A stopped train is prevented from being hit; the approaching train is prevented from moving.' },
  { key: 'flyingSwitch', name: 'Flying Switch', copies: 1, placement: 'any time', effect: 'Break a cut of cars away from behind the engine and roll them into an industry.' },
  { key: 'poling', name: 'Poling', copies: 1, placement: 'any time', effect: 'TBD in the source.' },
];

/** Played AT other players. We have no player-interaction mechanic yet. */
export const ACTION_CARDS: readonly SimpleCard[] = [
  { key: 'derail', name: 'Derail', copies: 2, placement: 'a moving train in the Local Phase', effect: 'That train must stop for the remainder of the turn.' },
  { key: 'brokenCoupler', name: 'Broken coupler', copies: 1, placement: 'a moving train in the Mainline Phase', effect: 'That train must stop and not move.' },
  { key: 'railroadCrossing', name: 'Railroad crossing', copies: 1, placement: 'any Secondary Track Straight', effect: 'May not be used as a stop point for switching. May not become an Industry.' },
  { key: 'perDiemInventory', name: 'Per Diem inventory', copies: 1, placement: 'another player', effect: 'Lose one point per 2 empty cars on Secondary Tracks.' },
  { key: 'demurrageCharge', name: 'Demurrage charge', copies: 1, placement: 'another player', effect: 'Lose one point per 2 loaded freight cars on Secondary Tracks.' },
  { key: 'customerComplaints', name: 'Customer complaints', copies: 1, placement: 'another player', effect: 'Lose one point per 2 coaches in loading boxes.' },
  { key: 'vandalism', name: 'Vandalism', copies: 1, placement: 'another player', effect: 'A train passing a Hobo Jungle has a boxcar looted (converted to empty).' },
  { key: 'hotbox', name: 'Hotbox', copies: 1, placement: 'another player', effect: 'A train just arrived must set one car (chooser’s pick) onto Secondary Track until it departs.' },
  { key: 'outlawed', name: 'Outlawed', copies: 1, placement: 'another player', effect: 'A train just arrived may not depart for one turn — the crew’s hours have expired.' },
];

// ---------------------------------------------------------------------------
// Rolling stock, scale, and victory
// ---------------------------------------------------------------------------

export type StockSupply = { type: CarType; loaded: number; empty: number };

/**
 * NOT in the recovered files — still the provisional figure.
 *
 * Scaled up alongside the Gap 12 industry increase. Worst-case demand (every copy of every
 * industry in play at full capacity) is boxcar 15, hopper 12, tank 9, reefer 6; the supply must
 * cover that, since a Division Yard that runs dry starves the freight loop the increase exists to
 * feed. Lockouts and district size mean the worst case cannot actually occur, so this carries
 * deliberate headroom.
 */
export const ROLLING_STOCK_SUPPLY: readonly StockSupply[] = [
  { type: 'coach', loaded: 8, empty: 8 },
  { type: 'boxcar', loaded: 10, empty: 10 },
  { type: 'hopper', loaded: 8, empty: 8 },
  { type: 'reefer', loaded: 5, empty: 5 },
  { type: 'tank', loaded: 6, empty: 6 },
  { type: 'caboose', loaded: 6, empty: 0 },
];

export const TOTAL_ROLLING_STOCK = ROLLING_STOCK_SUPPLY.reduce((n, s) => n + s.loaded + s.empty, 0);

export function mainlineCardCount(players: number): number {
  return players + 1;
}

/** Provisional; not in the recovered files. */
export function crewTrayCount(players: number): number {
  return players + 3;
}

export const REGIONS_PER_MAINLINE_CARD = 2; // provisional, pending §10 Q2
export const STAGES_PER_DAY = 12;
export const STAGES_PER_SHIFT = 3;
export const HAND_LIMIT = 3;
export const MAX_CONSIST = 4;
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;

export function collectiveRevenueFloor(players: number, days: number): number {
  return 3 * players * days;
}

export type GameLength = 'short' | 'standard' | 'campaign';
export type LengthProfile = { length: GameLength; target: number; 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 },
];

export function lengthProfile(length: GameLength): LengthProfile {
  const found = LENGTH_PROFILES.find((p) => p.length === length);
  if (!found) throw new Error(`unknown game length: ${length}`);
  return found;
}

// ---------------------------------------------------------------------------
// Deck composition — 140 cards
// ---------------------------------------------------------------------------

/**
 * Cards that can only be played AT another player (Q6). In a solitaire game they have no legal
 * target, so they are removed from the deck rather than sitting in hand as 19% dead draws.
 */
export const OPPONENT_ONLY_CATEGORIES: readonly string[] = ['spaceUse', 'action'];

export function isOpponentOnly(category: string): boolean {
  return OPPONENT_ONLY_CATEGORIES.includes(category);
}

export function deckComposition(): { category: string; count: number }[] {
  const sum = (xs: readonly { copies: number }[]): number => xs.reduce((n, x) => n + x.copies, 0);
  return [
    { category: 'office', count: OFFICE_PROFILES.reduce((n, o) => n + o.copiesInDeck, 0) },
    { category: 'industry', count: sum(INDUSTRY_PROFILES) },
    { category: 'modifier', count: sum(MODIFIER_PROFILES) },
    { category: 'train', count: ALL_TRAINS.length },
    { category: 'spaceUse', count: sum(SPACE_USE_CARDS) },
    { category: 'enhancement', count: sum(ENHANCEMENT_CARDS) },
    { category: 'mainlineModifier', count: sum(MAINLINE_MODIFIER_CARDS) },
    { category: 'maneuver', count: sum(MANEUVER_CARDS) },
    { category: 'action', count: sum(ACTION_CARDS) },
  ];
}

export const DECK_SIZE = deckComposition().reduce((n, c) => n + c.count, 0); // 140

/** The solitaire deck drops the 22 opponent-directed cards, leaving 118. */
export const SOLITAIRE_DECK_SIZE = deckComposition()
  .filter((c) => !isOpponentOnly(c.category))
  .reduce((n, c) => n + c.count, 0);
