Initial commit

2026-07-31 07:19:57 -04:00
commit e7bc07df85
39 changed files with 12438 additions and 0 deletions
@@ -0,0 +1,510 @@
+/**
+ * Component 16 — Game replay viewer.
+ *
+ * Records one game and writes a **self-contained HTML file** that plays it back step by step.
+ *
+ *   node src/sim/replay.ts [--seed 1234] [--length standard] [--out replay.html]
+ *
+ * The browser never runs the engine. Frames are precomputed here in Node and embedded as JSON, so
+ * the page is a dumb renderer with no bundling and no build step.
+ *
+ * The recorder drives `advance()` and `applyIntent()` itself rather than reusing `playGame`'s pump
+ * loop, because `pump` batches a whole automatic phase into one call — which would collapse an
+ * entire Mainline Phase into a single frame. Driving `advance` gives one frame per step.
+ *
+ * Priority is CLARITY over polish: plain boxes, words not symbols, and an explicit panel for what
+ * is currently blocked.
+ */
+
+import { writeFileSync } from 'node:fs';
+
+import { advance } from '../engine/advance.ts';
+import { applyIntent, areaOf, facilityCarType, laborersLeft, portersLeft } from '../engine/apply.ts';
+import type { GameLength } from '../engine/content.ts';
+import { lengthProfile, officeProfile } from '../engine/content.ts';
+import type { GameEvent } from '../engine/events.ts';
+import { legalActions } from '../engine/legal.ts';
+import { createGame } from '../engine/setup.ts';
+import type { GameConfig, GameState } from '../engine/state.ts';
+import { developerBot } from './bot.ts';
+import type { Impediment } from './narrate.ts';
+import { carLabel, clockTime, impediments, isVisible, narrate, phaseLabel } from './narrate.ts';
+
+// ---------------------------------------------------------------------------
+// Frame shape — only what the viewer draws
+// ---------------------------------------------------------------------------
+
+export type CellView = {
+  row: number;
+  col: number;
+  kind: string;
+  label: string;
+  running: boolean;
+  tray: string | null;
+  cars: string[];
+  facility: FacilityView | null;
+};
+
+export type FacilityView = {
+  name: string;
+  commodity: string;
+  flow: string;
+  green: string[];
+  greenCap: number;
+  maw: (string | null)[];
+  red: string[];
+  redCap: number;
+  track: string[];
+  trackCap: number;
+  laborers: string;
+  porters: string;
+};
+
+export type DivisionView = { kind: string; label: string; trains: string[][] };
+
+export type Frame = {
+  day: number;
+  stage: number;
+  clock: string;
+  phase: string;
+  actor: number | null;
+  superintendent: number;
+  revenue: number;
+  lines: { text: string; tone: string }[];
+  where: { row: number; col: number } | null;
+  division: DivisionView[];
+  cells: CellView[];
+  facilities: FacilityView[];
+  hand: number;
+  deck: number;
+  blocked: Impediment[];
+  trains: { label: string; where: string }[];
+};
+
+// ---------------------------------------------------------------------------
+// Snapshotting
+// ---------------------------------------------------------------------------
+
+const FACILITY_NAMES: Record<string, string> = {
+  mineTipple: 'Mine Tipple',
+  produceShed: 'Produce Shed',
+  grocersWarehouse: "Grocer's Warehouse",
+  oilRefinery: 'Oil Refinery',
+  powerPlant: 'Power Plant',
+};
+
+function facilityView(card: { geometry: { kind: string; facility?: string }; facility: NonNullable<CellView['facility']> extends never ? never : unknown }): FacilityView | null {
+  const f = (card as { facility: import('../engine/state.ts').Facility | null }).facility;
+  if (!f || f.kind !== 'freight') return null;
+  const key = card.geometry.kind === 'facility' ? (card.geometry.facility ?? '') : '';
+  return {
+    name: FACILITY_NAMES[key] ?? key,
+    commodity: facilityCarType(f) ?? '?',
+    flow: f.allows.outbound && f.allows.inbound ? 'both' : f.allows.outbound ? 'ships out' : 'receives',
+    green: f.outboundBox.map(carLabel),
+    greenCap: f.capacity.outbound,
+    maw: f.menAtWork.map((l) => (l ? `${l.type} ${l.dir === 'out' ? '→' : '←'}` : null)),
+    red: f.inboundBox.map(carLabel),
+    redCap: f.capacity.inbound,
+    track: f.industryTrack.cars.map(carLabel),
+    trackCap: f.industryTrack.length,
+    laborers: `${laborersLeft(f)}/${f.laborers}`,
+    porters: `${portersLeft(f)}/${f.porters}`,
+  };
+}
+
+function snapshot(
+  s: GameState,
+  lines: { text: string; tone: string }[],
+  where: { row: number; col: number } | null,
+): Frame {
+  const area = areaOf(s, 0);
+  const trayAt = new Map<string, string>();
+  for (const [id, tray] of s.trays) {
+    if (tray.position.at === 'grid') {
+      const label = tray.trainNumber === null ? 'crew' : `T${tray.trainIsExtra ? 'X' : ''}${tray.trainNumber}`;
+      trayAt.set(`${tray.position.coord.row},${tray.position.coord.col}`, label);
+    }
+  }
+
+  const cells: CellView[] = [];
+  const facilities: FacilityView[] = [];
+  for (const [key, card] of area.grid) {
+    const [row, col] = key.split(',').map(Number);
+    const g = card.geometry;
+    const kind = g.kind;
+    let label: string;
+    if (g.kind === 'office') label = officeProfile(area.tier).name;
+    else if (g.kind === 'limits') label = 'Limits';
+    else if (g.kind === 'facility') label = FACILITY_NAMES[g.facility] ?? g.facility;
+    else label = g.geometry === 'runAround' ? 'run-around' : g.geometry;
+
+    const fv = facilityView(card as never);
+    if (fv) facilities.push(fv);
+
+    cells.push({
+      row: row!,
+      col: col!,
+      kind,
+      label,
+      running: row === area.runningRow,
+      tray: trayAt.get(key) ?? null,
+      cars: (card.facility?.industryTrack.length ? card.facility.industryTrack.cars : card.standing).map(carLabel),
+      facility: fv,
+    });
+  }
+
+  const division: DivisionView[] = s.division.nodes.map((n) => {
+    if (n.kind === 'divisionPoint') {
+      return {
+        kind: 'dp',
+        label: n.side === 'west' ? 'West DP' : 'East DP',
+        trains: [n.holding.map((id) => trainChip(s, id))],
+      };
+    }
+    if (n.kind === 'mainline') {
+      return {
+        kind: 'ml',
+        label: 'Mainline',
+        trains: n.regions.map((r) => (r.occupant ? [trainChip(s, r.occupant)] : [])),
+      };
+    }
+    return {
+      kind: 'office',
+      label: officeProfile(areaOf(s, n.owner).tier).name,
+      trains: [areaOf(s, n.owner).adOccupancy.map((id) => trainChip(s, id))],
+    };
+  });
+
+  return {
+    day: s.clock.day,
+    stage: s.clock.stage,
+    clock: clockTime(s.clock.stage),
+    phase: phaseLabel(s.clock.phase),
+    actor: s.clock.currentActor,
+    superintendent: s.clock.superintendent,
+    revenue: s.players[0]?.revenue ?? 0,
+    lines,
+    where,
+    division,
+    cells,
+    facilities,
+    hand: (s.decks.hands.get(0) ?? []).length,
+    deck: s.decks.homeOffice.length,
+    blocked: impediments(s, 0),
+    trains: [...s.trays.values()].map((t) => ({
+      label: t.trainNumber === null ? 'local crew' : `Train ${t.trainIsExtra ? 'X' : ''}${t.trainNumber}`,
+      where:
+        t.position.at === 'divisionPoint'
+          ? `${t.position.side} Division Point`
+          : t.position.at === 'mainline'
+            ? `Mainline ${t.position.index}, region ${t.position.region + 1}`
+            : `Office Area (${t.position.coord.row},${t.position.coord.col})`,
+    })),
+  };
+}
+
+function trainChip(s: GameState, id: string): string {
+  const t = s.trays.get(id);
+  if (!t) return id;
+  return t.trainNumber === null ? 'crew' : `T${t.trainIsExtra ? 'X' : ''}${t.trainNumber}`;
+}
+
+// ---------------------------------------------------------------------------
+// Recording
+// ---------------------------------------------------------------------------
+
+export type Recording = { seed: number; length: GameLength; frames: Frame[]; outcome: string };
+
+export function record(seed: number, length: GameLength, maxSteps = 100_000): Recording {
+  const config: GameConfig = {
+    mode: 'solitaire',
+    victory: 'highestAfterDays',
+    length,
+    optionalRules: {
+      reducedVisibility: false,
+      sisterTrains: false,
+      employeeRotation: false,
+      emergencyToolbox: false,
+    },
+  };
+  const s = createGame({ id: `replay-${seed}`, seed, config, playerNames: ['player'] });
+  const frames: Frame[] = [];
+
+  const push = (events: GameEvent[]): void => {
+    const visible = events.filter(isVisible);
+    if (visible.length === 0) return;
+    const narrated = visible.map(narrate);
+    const where = narrated.find((n) => n.where)?.where ?? null;
+    frames.push(snapshot(s, narrated.map((n) => ({ text: n.text, tone: n.tone })), where ?? null));
+  };
+
+  frames.push(snapshot(s, [{ text: 'Game begins — the Division has just been spiked down.', tone: 'clock' }], null));
+
+  for (let step = 0; step < maxSteps; step++) {
+    const r = advance(s);
+    push(r.events);
+    if (s.status === 'finished') break;
+    if (!r.needsInput) continue;
+
+    const actor = s.clock.pendingDecision !== null ? s.clock.superintendent : s.clock.currentActor;
+    if (actor === null) break;
+    const options = legalActions(s, actor);
+    if (options.length === 0) break;
+    const applied = applyIntent(s, actor, developerBot.choose(s, actor, options));
+    if (!applied.ok) break;
+    push(applied.events);
+  }
+
+  const o = s.outcome;
+  return {
+    seed,
+    length,
+    frames,
+    outcome: o ? `${o.result} — ${o.reason} · final Revenue ${s.players[0]?.revenue ?? 0}` : 'unfinished',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// HTML
+// ---------------------------------------------------------------------------
+
+export function renderHtml(rec: Recording): string {
+  const target = lengthProfile(rec.length);
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Station Master — replay seed ${rec.seed}</title>
+<style>
+:root{--bg:#14161a;--fg:#e8e6e3;--dim:#8b9199;--line:#2c3138;--panel:#1b1f25;
+--good:#5fd08a;--bad:#ff7a70;--clock:#7fb8ff;--warn:#ffc46b;--green:#2f6b47;--red:#6b3230;--maw:#2a4a6b}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--fg);font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace}
+header{padding:10px 14px;border-bottom:1px solid var(--line);position:sticky;top:0;background:var(--bg);z-index:5}
+h1{font-size:14px;margin:0 0 6px;font-weight:600}
+.bar{display:flex;gap:18px;flex-wrap:wrap;align-items:baseline}
+.big{font-size:19px;font-weight:700}
+.dim{color:var(--dim)}
+.wrap{display:grid;grid-template-columns:minmax(0,3fr) minmax(0,2fr);gap:14px;padding:14px}
+@media(max-width:900px){.wrap{grid-template-columns:1fr}}
+section{background:var(--panel);border:1px solid var(--line);border-radius:6px;padding:10px 12px;margin-bottom:14px}
+h2{font-size:11px;letter-spacing:.09em;text-transform:uppercase;color:var(--dim);margin:0 0 8px;font-weight:600}
+.div-strip{display:flex;gap:6px;overflow-x:auto;padding-bottom:4px}
+.node{border:1px solid var(--line);border-radius:5px;padding:6px 8px;min-width:96px;background:#20252c}
+.node.office{border-color:var(--clock)}
+.regions{display:flex;gap:4px;margin-top:5px}
+.region{flex:1;min-height:22px;border:1px dashed var(--line);border-radius:3px;display:flex;align-items:center;justify-content:center;font-size:11px}
+.chip{background:var(--clock);color:#0d1117;border-radius:3px;padding:1px 5px;font-weight:700;font-size:11px}
+.grid{display:grid;gap:5px;overflow-x:auto}
+.cell{border:1px solid var(--line);border-radius:5px;padding:6px;min-height:64px;background:#20252c}
+.cell.run{border-color:#4a545f;background:#252b33}
+.cell.hl{outline:2px solid var(--warn);outline-offset:1px}
+.cell .nm{font-weight:700;font-size:11px}
+.cell .cars{color:var(--dim);font-size:10.5px;margin-top:3px}
+.cell .tray{display:inline-block;margin-top:4px}
+.fac{border:1px solid var(--line);border-radius:5px;padding:8px;margin-bottom:8px;background:#20252c}
+.boxes{display:flex;gap:6px;flex-wrap:wrap;margin-top:6px;align-items:center}
+.box{border-radius:3px;padding:3px 7px;font-size:11px;border:1px solid var(--line)}
+.box.g{background:var(--green)}.box.r{background:var(--red)}.box.m{background:var(--maw)}
+.box.empty{background:transparent;color:var(--dim)}
+.log{max-height:230px;overflow:auto}
+.line{padding:2px 0;border-bottom:1px solid #23272e}
+.t-good{color:var(--good)}.t-bad{color:var(--bad)}.t-clock{color:var(--clock);font-weight:700}
+.t-quiet{color:var(--dim)}.t-plain{color:var(--fg)}
+.blocked li{margin-bottom:4px}
+.sev-stuck{color:var(--bad)}.sev-risk{color:var(--warn)}.sev-waiting{color:var(--dim)}
+footer{position:sticky;bottom:0;background:var(--bg);border-top:1px solid var(--line);padding:9px 14px;
+display:flex;gap:8px;align-items:center;flex-wrap:wrap;z-index:5}
+button{background:#2a3038;color:var(--fg);border:1px solid var(--line);border-radius:5px;padding:5px 11px;
+font:inherit;cursor:pointer}
+button:hover{background:#343b45}
+input[type=range]{flex:1;min-width:180px}
+.legend{font-size:11px;color:var(--dim);padding:0 14px 14px}
+</style></head><body>
+
+<header>
+  <h1>Station Master — replay · seed ${rec.seed} · ${rec.length} (target ${target.target} over ${target.days} Days) · ${esc(rec.outcome)}</h1>
+  <div class="bar">
+    <span class="big" id="when">—</span>
+    <span>phase <b id="phase">—</b></span>
+    <span class="dim">actor <span id="actor">—</span> · fedora <span id="super">—</span></span>
+    <span>revenue <b class="big" id="rev">0</b></span>
+    <span class="dim">hand <span id="hand">0</span> · deck <span id="deck">0</span></span>
+    <span class="dim">frame <span id="fno">0</span>/<span id="ftot">0</span></span>
+  </div>
+</header>
+
+<div class="wrap">
+  <div>
+    <section><h2>Division — west to east</h2><div class="div-strip" id="division"></div></section>
+    <section><h2>Office Area</h2><div class="grid" id="grid"></div></section>
+    <section><h2>Facilities</h2><div id="facs"></div></section>
+  </div>
+  <div>
+    <section><h2>What just happened</h2><div id="now"></div></section>
+    <section><h2>Blocked — why nothing is moving</h2><ul class="blocked" id="blocked"></ul></section>
+    <section><h2>Trains in play</h2><div id="trains" class="dim"></div></section>
+    <section><h2>History</h2><div class="log" id="log"></div></section>
+  </div>
+</div>
+
+<div class="legend">
+  Running Track is the lighter row. <span class="chip">T4</span> is a train. Green box = outbound loads waiting ·
+  MEN / AT / WORK = the three-step loading track (→ outbound, ← inbound) · red box = delivered loads.
+  Laborers and Porters show remaining/total for this Stage.
+</div>
+
+<footer>
+  <button id="first">⏮ start</button>
+  <button id="back">◀ step</button>
+  <button id="play">▶ play</button>
+  <button id="fwd">step ▶</button>
+  <button id="stage">next Stage ⏭</button>
+  <button id="money">next revenue 💰</button>
+  <button id="crash">next collision ⚠</button>
+  <input type="range" id="scrub" min="0" value="0">
+  <select id="speed">
+    <option value="600">slow</option>
+    <option value="250" selected>normal</option>
+    <option value="90">fast</option>
+    <option value="20">very fast</option>
+  </select>
+</footer>
+
+<script>
+const FRAMES = ${JSON.stringify(rec.frames)};
+let i = 0, timer = null;
+const $ = (id) => document.getElementById(id);
+const esc = (s) => String(s).replace(/[&<>]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
+
+function boxes(items, cap, cls) {
+  let h = '';
+  for (let k = 0; k < Math.max(cap, items.length); k++) {
+    const v = items[k];
+    h += '<span class="box ' + (v ? cls : 'empty') + '">' + (v ? esc(v) : '·') + '</span>';
+  }
+  return h || '<span class="dim">—</span>';
+}
+
+function render() {
+  const f = FRAMES[i];
+  $('when').textContent = 'Day ' + f.day + ' · Stage ' + f.stage + ' · ' + f.clock;
+  $('phase').textContent = f.phase;
+  $('actor').textContent = f.actor === null ? 'automatic' : 'P' + f.actor;
+  $('super').textContent = 'P' + f.superintendent;
+  $('rev').textContent = f.revenue;
+  $('rev').className = 'big ' + (f.revenue < 0 ? 't-bad' : f.revenue > 0 ? 't-good' : '');
+  $('hand').textContent = f.hand;
+  $('deck').textContent = f.deck;
+  $('fno').textContent = i;
+  $('scrub').value = i;
+
+  $('division').innerHTML = f.division.map((n) =>
+    '<div class="node ' + (n.kind === 'office' ? 'office' : '') + '"><div class="nm">' + esc(n.label) + '</div>' +
+    '<div class="regions">' + n.trains.map((r) =>
+      '<div class="region">' + r.map((t) => '<span class="chip">' + esc(t) + '</span>').join('') + '</div>').join('') +
+    '</div></div>').join('');
+
+  const rows = f.cells.map((c) => c.row), cols = f.cells.map((c) => c.col);
+  const r0 = Math.min(...rows), r1 = Math.max(...rows), c0 = Math.min(...cols), c1 = Math.max(...cols);
+  const g = $('grid');
+  g.style.gridTemplateColumns = 'repeat(' + (c1 - c0 + 1) + ', minmax(110px, 1fr))';
+  let cellsHtml = '';
+  for (let r = r1; r >= r0; r--) {
+    for (let c = c0; c <= c1; c++) {
+      const cell = f.cells.find((x) => x.row === r && x.col === c);
+      if (!cell) { cellsHtml += '<div></div>'; continue; }
+      const hl = f.where && f.where.row === r && f.where.col === c;
+      cellsHtml += '<div class="cell ' + (cell.running ? 'run ' : '') + (hl ? 'hl' : '') + '">' +
+        '<div class="nm">' + esc(cell.label) + '</div>' +
+        '<div class="dim" style="font-size:10px">(' + r + ',' + c + ')</div>' +
+        (cell.tray ? '<span class="chip tray">' + esc(cell.tray) + '</span>' : '') +
+        (cell.cars.length ? '<div class="cars">' + cell.cars.map(esc).join('<br>') + '</div>' : '') +
+        '</div>';
+    }
+  }
+  g.innerHTML = cellsHtml;
+
+  $('facs').innerHTML = f.facilities.length === 0
+    ? '<span class="dim">no freight facilities built yet</span>'
+    : f.facilities.map((x) =>
+      '<div class="fac"><b>' + esc(x.name) + '</b> <span class="dim">' + esc(x.commodity) + ' · ' + esc(x.flow) +
+      ' · laborers ' + esc(x.laborers) + ' · porters ' + esc(x.porters) + '</span>' +
+      '<div class="boxes"><span class="dim">green</span>' + boxes(x.green, x.greenCap, 'g') + '</div>' +
+      '<div class="boxes"><span class="dim">MEN|AT|WORK</span>' +
+        x.maw.map((m) => '<span class="box ' + (m ? 'm' : 'empty') + '">' + (m ? esc(m) : '·') + '</span>').join('') + '</div>' +
+      '<div class="boxes"><span class="dim">red</span>' + boxes(x.red, x.redCap, 'r') + '</div>' +
+      '<div class="boxes"><span class="dim">siding</span>' + boxes(x.track, x.trackCap, 'g') + '</div>' +
+      '</div>').join('');
+
+  $('now').innerHTML = f.lines.map((l) => '<div class="line t-' + l.tone + '">' + esc(l.text) + '</div>').join('');
+  $('blocked').innerHTML = f.blocked.length === 0
+    ? '<li class="dim">nothing blocked</li>'
+    : f.blocked.map((b) => '<li class="sev-' + b.severity + '"><b>' + esc(b.where) + '</b> — ' + esc(b.why) + '</li>').join('');
+  $('trains').innerHTML = f.trains.length === 0
+    ? 'no trains running'
+    : f.trains.map((t) => esc(t.label) + ' — ' + esc(t.where)).join('<br>');
+
+  let hist = '';
+  for (let k = Math.max(0, i - 24); k <= i; k++) {
+    for (const l of FRAMES[k].lines) hist += '<div class="line t-' + l.tone + '">' + esc(l.text) + '</div>';
+  }
+  $('log').innerHTML = hist;
+  $('log').scrollTop = $('log').scrollHeight;
+}
+
+function go(n) { i = Math.max(0, Math.min(FRAMES.length - 1, n)); render(); }
+function findNext(pred) { for (let k = i + 1; k < FRAMES.length; k++) if (pred(FRAMES[k], FRAMES[k - 1])) return go(k); go(FRAMES.length - 1); }
+
+$('ftot').textContent = FRAMES.length - 1;
+$('scrub').max = FRAMES.length - 1;
+$('scrub').oninput = (e) => go(+e.target.value);
+$('first').onclick = () => go(0);
+$('back').onclick = () => go(i - 1);
+$('fwd').onclick = () => go(i + 1);
+$('stage').onclick = () => findNext((f, p) => f.stage !== p.stage || f.day !== p.day);
+$('money').onclick = () => findNext((f, p) => f.revenue !== p.revenue);
+$('crash').onclick = () => findNext((f) => f.lines.some((l) => /COLLISION|collision/.test(l.text)));
+$('play').onclick = () => {
+  if (timer) { clearInterval(timer); timer = null; $('play').textContent = '▶ play'; return; }
+  $('play').textContent = '⏸ pause';
+  timer = setInterval(() => {
+    if (i >= FRAMES.length - 1) { clearInterval(timer); timer = null; $('play').textContent = '▶ play'; return; }
+    go(i + 1);
+  }, +$('speed').value);
+};
+$('speed').onchange = () => { if (timer) { $('play').click(); $('play').click(); } };
+document.onkeydown = (e) => {
+  if (e.key === 'ArrowRight') go(i + 1);
+  if (e.key === 'ArrowLeft') go(i - 1);
+  if (e.key === ' ') { e.preventDefault(); $('play').click(); }
+};
+render();
+</script></body></html>`;
+}
+
+function esc(s: string): string {
+  return s.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c] ?? c);
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const isMain = process.argv[1]?.endsWith('replay.ts') ?? false;
+
+if (isMain) {
+  const arg = (name: string, dflt: string): string => {
+    const i = process.argv.indexOf(`--${name}`);
+    return i >= 0 ? (process.argv[i + 1] ?? dflt) : dflt;
+  };
+  const seed = Number(arg('seed', '1234'));
+  const length = arg('length', 'standard') as GameLength;
+  const out = arg('out', 'replay.html');
+
+  const rec = record(seed, length);
+  writeFileSync(out, renderHtml(rec));
+  const kb = (Buffer.byteLength(renderHtml(rec)) / 1024).toFixed(0);
+  console.log(`wrote ${out} — ${rec.frames.length} frames, ${kb} KB`);
+  console.log(`seed ${seed} · ${length} · ${rec.outcome}`);
+}