jev-chess 1.0.0

package/src/chessEngine.ts

@@ -0,0 +1,191 @@
+import { Chess, type PieceSymbol, type Square } from "chess.js";
+import type { AnnotatedMove, BoardContext, GamePhase, MaterialBalance } from "./types.js";
+
+const PIECE_NAMES: Record<PieceSymbol, string> = {
+  p: "pawn",
+  n: "knight",
+  b: "bishop",
+  r: "rook",
+  q: "queen",
+  k: "king",
+};
+
+const PIECE_VALUES: Record<PieceSymbol, number> = {
+  p: 1,
+  n: 3,
+  b: 3,
+  r: 5,
+  q: 9,
+  k: 0,
+};
+
+export class ChessEngine {
+  public chess: Chess;
+
+  constructor(fen?: string) {
+    this.chess = new Chess(fen);
+  }
+
+  public reset(): void {
+    this.chess.reset();
+  }
+
+  public load(fen: string): boolean {
+    try {
+      this.chess.load(fen);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  public fen(): string {
+    return this.chess.fen();
+  }
+
+  public turn(): "white" | "black" {
+    return this.chess.turn() === "w" ? "white" : "black";
+  }
+
+  public isCheck(): boolean {
+    return this.chess.inCheck();
+  }
+
+  public isGameOver(): boolean {
+    return this.chess.isGameOver();
+  }
+
+  public history(): string[] {
+    return this.chess.history();
+  }
+
+  /**
+   * Generates all legal moves in the current position, richly annotated with semantic facts.
+   * This is 100% deterministic code.
+   */
+  public getAnnotatedMoves(): AnnotatedMove[] {
+    const rawMoves = this.chess.moves({ verbose: true });
+    return rawMoves.map((m) => {
+      const pieceName = PIECE_NAMES[m.piece] ?? m.piece;
+      const isCastling = m.san === "O-O" || m.san === "O-O-O";
+      const isCapture = Boolean(m.captured);
+      const capturedName = m.captured ? PIECE_NAMES[m.captured] : undefined;
+
+      let description = `${pieceName} moves from ${m.from} to ${m.to}`;
+      if (isCastling) {
+        description = m.san === "O-O" ? "Kingside castle" : "Queenside castle";
+      } else if (isCapture) {
+        description = `${pieceName} on ${m.from} captures ${capturedName} on ${m.to}`;
+      }
+      if (m.san.includes("+")) {
+        description += " with check";
+      } else if (m.san.includes("#")) {
+        description += " with checkmate!";
+      }
+
+      return {
+        san: m.san,
+        from: m.from,
+        to: m.to,
+        piece: pieceName,
+        color: m.color === "w" ? "white" : "black",
+        isCapture,
+        capturedPiece: capturedName,
+        isCheck: m.san.includes("+") || m.san.includes("#"),
+        isCastling,
+        description,
+      };
+    });
+  }
+
+  /**
+   * Calculates material balance between white and black.
+   */
+  public getMaterialBalance(): MaterialBalance {
+    const board = this.chess.board();
+    let whiteScore = 0;
+    let blackScore = 0;
+
+    for (const row of board) {
+      for (const square of row) {
+        if (!square) continue;
+        const val = PIECE_VALUES[square.type];
+        if (square.color === "w") whiteScore += val;
+        else blackScore += val;
+      }
+    }
+
+    const diff = whiteScore - blackScore;
+    let description = "Material is exactly equal";
+    if (diff > 0) {
+      description = `White is up +${diff} point${diff > 1 ? "s" : ""}`;
+    } else if (diff < 0) {
+      description = `Black is up +${Math.abs(diff)} point${Math.abs(diff) > 1 ? "s" : ""}`;
+    }
+
+    return { whiteScore, blackScore, diff, description };
+  }
+
+  /**
+   * Deterministically infers game phase based on remaining major/minor pieces and move number.
+   */
+  public getGamePhase(): GamePhase {
+    const board = this.chess.board();
+    let totalPieces = 0;
+    let queenCount = 0;
+
+    for (const row of board) {
+      for (const square of row) {
+        if (!square) continue;
+        if (square.type !== "p" && square.type !== "k") {
+          totalPieces++;
+          if (square.type === "q") queenCount++;
+        }
+      }
+    }
+
+    const moveCount = this.chess.history().length;
+    if (moveCount < 16 && totalPieces >= 12) {
+      return "opening";
+    }
+    if (totalPieces <= 6 || queenCount === 0) {
+      return "endgame";
+    }
+    return "middlegame";
+  }
+
+  /**
+   * Creates the complete structured context representing the board.
+   * This matches TypeSafe's principle: provide clear, structured JSON state.
+   */
+  public getBoardContext(): BoardContext {
+    const history = this.chess.history();
+    const recentHistory = history.slice(-6);
+
+    return {
+      fen: this.chess.fen(),
+      turn: this.turn(),
+      moveNumber: Math.floor(history.length / 2) + 1,
+      inCheck: this.isCheck(),
+      materialBalance: this.getMaterialBalance(),
+      gamePhase: this.getGamePhase(),
+      recentHistory,
+      candidateMoves: this.getAnnotatedMoves(),
+    };
+  }
+
+  /**
+   * Deterministically applies a move in SAN (Standard Algebraic Notation).
+   */
+  public makeMove(sanOrUci: string): AnnotatedMove | null {
+    const candidate = this.getAnnotatedMoves().find(
+      (m) => m.san === sanOrUci || `${m.from}${m.to}` === sanOrUci
+    );
+    if (!candidate) {
+      return null;
+    }
+
+    this.chess.move(candidate.san);
+    return candidate;
+  }
+}

package/src/classicMatches.ts

@@ -0,0 +1,291 @@
+import { ChessEngine } from "./chessEngine.js";
+import { choice, getTypeSafeClient, noul, score } from "./typeSafeClient.js";
+
+export interface ClassicMatch {
+  id: string;
+  title: string;
+  white: string;
+  black: string;
+  year: number;
+  event: string;
+  result: "1-0" | "0-1" | "1/2-1/2";
+  eco: string;
+  opening: string;
+  description: string;
+  moves: string[]; // SAN moves
+  keyMoveIndex: number; // Index of the iconic turning point move
+}
+
+export interface MatchClassification {
+  matchId: string;
+  title: string;
+  archetype: string;
+  aestheticBrilliance: {
+    score: number;
+    level: string;
+    confidence: number;
+  };
+  overallSharpness: {
+    score: number;
+    level: string;
+  };
+  hasDecisiveSacrifice: boolean;
+  turningPoint: {
+    moveNumber: number;
+    san: string;
+    annotation: string;
+  };
+  strategicBreakdown: {
+    tacticalStrikesPct: number;
+    pawnBreaksPct: number;
+    prophylaxisPct: number;
+    pieceActivationPct: number;
+  };
+  verdict: string;
+}
+
+export const CLASSIC_MATCHES: ClassicMatch[] = [
+  {
+    id: "immortal-game",
+    title: "The Immortal Game",
+    white: "Adolf Anderssen",
+    black: "Lionel Kieseritzky",
+    year: 1851,
+    event: "London (Casual match during 1st International Tournament)",
+    result: "1-0",
+    eco: "C33",
+    opening: "King's Gambit Accepted",
+    description:
+      "Anderssen gave up both rooks and a bishop, followed by his queen, delivering checkmate with his three remaining minor pieces.",
+    keyMoveIndex: 38, // 20. Ke2! or 22. Qf6+!
+    moves: [
+      "e4", "e5", "f4", "exf4", "Bc4", "Qh4+", "Kf1", "b5", "Bxb5", "Nf6",
+      "Nf3", "Qh6", "d3", "Nh5", "Nh4", "Qg5", "Nf5", "c6", "g4", "Nf6",
+      "Rg1", "cxb5", "h4", "Qg6", "h5", "Qg5", "Qf3", "Ng8", "Bxf4", "Qf6",
+      "Nc3", "Bc5", "Nd5", "Qxb2", "Bd6", "Bxg1", "e5", "Qxa1+", "Ke2", "Na6",
+      "Nxg7+", "Kd8", "Qf6+", "Nxf6", "Be7#"
+    ],
+  },
+  {
+    id: "opera-game",
+    title: "The Opera Game",
+    white: "Paul Morphy",
+    black: "Duke of Brunswick & Count Isouard",
+    year: 1858,
+    event: "Paris Opera House (Norma intermission)",
+    result: "1-0",
+    eco: "C41",
+    opening: "Philidor Defense",
+    description:
+      "Morphy's quintessential demonstration of rapid development, open lines, and deflection queen sacrifice ending in checkmate with rook and bishop.",
+    keyMoveIndex: 30, // 16. Qb8+!
+    moves: [
+      "e4", "e5", "Nf3", "d6", "d4", "Bg4", "dxe5", "Bxf3", "Qxf3", "dxe5",
+      "Bc4", "Nf6", "Qb3", "Qe7", "Nc3", "c6", "Bg5", "b5", "Nxb5", "cxb5",
+      "Bxb5+", "Nbd7", "O-O-O", "Rd8", "Rxd7", "Rxd7", "Rd1", "Qe6", "Bxd7+", "Nxd7",
+      "Qb8+", "Nxb8", "Rd8#"
+    ],
+  },
+  {
+    id: "game-of-the-century",
+    title: "Game of the Century",
+    white: "Donald Byrne",
+    black: "Bobby Fischer (age 13)",
+    year: 1956,
+    event: "Rosenwald Memorial Tournament, New York",
+    result: "0-1",
+    eco: "D92",
+    opening: "Grünfeld Defence, 5.Bf4",
+    description:
+      "A 13-year-old Bobby Fischer sacrifices his queen on move 17 (Be6!!) to unleash an unstoppable windmill attack with bishop and knight.",
+    keyMoveIndex: 33, // 17... Be6!!
+    moves: [
+      "Nf3", "Nf6", "c4", "g6", "Nc3", "Bg7", "d4", "O-O", "Bf4", "d5",
+      "Qb3", "dxc4", "Qxc4", "c6", "e4", "Nbd7", "Rd1", "Nb6", "Qc5", "Bg4",
+      "Bg5", "Na4", "Qa3", "Nxc3", "bxc3", "Nxe4", "Bxe7", "Qb6", "Bc4", "Nxc3",
+      "Bc5", "Rfe8+", "Kf1", "Be6", "Bxb6", "Bxc4+", "Kg1", "Ne2+", "Kf1", "Nxd4+",
+      "Kg1", "Ne2+", "Kf1", "Nc3+", "Kg1", "axb6", "Qb4", "Ra4", "Qxb6", "Nxd1",
+      "h3", "Rxa2", "Kh2", "Nxf2", "Re1", "Rxe1", "Qd8+", "Bf8", "Nxe1", "Bd5",
+      "Nf3", "Ne4", "Qb8", "b5", "h4", "h5", "Ne5", "Kg7", "Kg1", "Bc5+",
+      "Kf1", "Ng3+", "Ke1", "Bb4+", "Kd1", "Bb3+", "Kc1", "Ne2+", "Kb1", "Nc3+",
+      "Kc1", "Rc2#"
+    ],
+  },
+  {
+    id: "kasparov-immortal",
+    title: "Kasparov's Immortal",
+    white: "Garry Kasparov",
+    black: "Veselin Topalov",
+    year: 1999,
+    event: "Hoogovens Group A, Wijk aan Zee",
+    result: "1-0",
+    eco: "B07",
+    opening: "Pirc Defense",
+    description:
+      "Kasparov sacrifices his rook on d4 (24. Rxd4!!) initiating a spectacular 15-move king hunt that drove the black king across the entire board.",
+    keyMoveIndex: 46, // 24. Rxd4!!
+    moves: [
+      "e4", "d6", "d4", "Nf6", "Nc3", "g6", "Be3", "Bg7", "Qd2", "c6",
+      "f3", "b5", "Nge2", "Nbd7", "Bh6", "Bxh6", "Qxh6", "Bb7", "a3", "e5",
+      "O-O-O", "Qe7", "Kb1", "a6", "Nc1", "O-O-O", "Nb3", "exd4", "Rxd4", "c5",
+      "Rd1", "Nb6", "g3", "Kb8", "Na5", "Ba8", "Bh3", "d5", "Qf4+", "Ka7",
+      "Rhe1", "d4", "Nd5", "Nbxd5", "exd5", "Qd6", "Rxd4", "cxd4", "Re7+", "Kb6",
+      "Qxd4+", "Kxa5", "b4+", "Ka4", "Qc3", "Qxd5", "Ra7", "Bb7", "Rxb7", "Qc4",
+      "Qxf6", "Kxa3", "Qxa6+", "Kxb4", "c3+", "Kxc3", "Qa1+", "Kd2", "Qb2+", "Kd1",
+      "Bf1", "Rd2", "Rd7+", "Rxd7", "Bxc4", "bxc4", "Qxh8", "Rd3", "Qa8", "c3",
+      "Qa4+", "Ke1", "f4", "f5", "Kc1", "Rd2", "Qa7"
+    ],
+  },
+  {
+    id: "tal-larsen-1965",
+    title: "Tal's Wild Central Sacrifice",
+    white: "Mikhail Tal",
+    black: "Bent Larsen",
+    year: 1965,
+    event: "Candidates Semifinal, Bled, Match Game 10",
+    result: "1-0",
+    eco: "B57",
+    opening: "Sicilian Defense, Richter-Rauzer",
+    description:
+      "Tal's famous intuitive piece sacrifice 16. Nxd5!! blowing open the center against Larsen's uncastled king to clinch the match.",
+    keyMoveIndex: 30, // 16. Nxd5!!
+    moves: [
+      "e4", "c5", "Nf3", "Nc6", "d4", "cxd4", "Nxd4", "e6", "Nc3", "d6",
+      "Be3", "Nf6", "f4", "Be7", "Qf3", "O-O", "O-O-O", "Qc7", "Ndb5", "Qb8",
+      "g4", "a6", "Nd4", "Nxd4", "Bxd4", "b5", "g5", "Nd7", "Bd3", "b4",
+      "Nd5", "exd5", "exd5", "f5", "Rde1", "Rf7", "h4", "Bb7", "Bxf5", "Rxf5",
+      "Rxe7", "Ne5", "Qe4", "Qf8", "fxe5", "Rf4", "Qe3", "Rf3", "Qe2", "Qxe7",
+      "Qxf3", "dxe5", "Re1", "Rd8", "Rxe5", "Qd6", "Qf4", "Rf8", "Qe4", "Bc8",
+      "b3", "a5", "h5", "Bd7", "h6"
+    ],
+  },
+];
+
+const MATCH_ARCHETYPES = {
+  romantic_swashbuckler: "Cascading material sacrifices culminating in a forced mating net",
+  dynamic_initiative: "Relentless piece tempo and coordinated piece pressure dominating passive defenders",
+  positional_squeeze: "Prophylactic clamp, suffocating opponent counterplay before technical breakthrough",
+  tactical_firestorm: "Sharp double-edged complications with king chases and critical calculate-or-die tactics",
+};
+
+const BRILLIANCE_RUBRIC = [
+  "Standard technical victory with routine exchanges",
+  "Well-played competitive game with solid tactical execution",
+  "Brilliant game featuring deep calculation and attractive piece play",
+  "Immortal artistic masterpiece that redefined chess literature",
+] as const;
+
+const MATCH_SHARPNESS_RUBRIC = [
+  "Solid and quiet; long positional maneuvering behind closed pawns",
+  "Balanced fighting contest with strategic tension",
+  "Very sharp; frequent piece contact, king exposure, and tactical threats",
+  "Wild tactical hurricane; mutual piece sacrifices and all-out monarch assault",
+] as const;
+
+export class ClassicMatchStudio {
+  private get client() {
+    return getTypeSafeClient();
+  }
+
+  /**
+   * Classifies a classic chess match using TypeSafe System One.
+   */
+  public async classifyMatch(match: ClassicMatch): Promise<MatchClassification> {
+    const turningMove = match.moves[match.keyMoveIndex] ?? match.moves[match.moves.length - 1] ?? "e4";
+    const moveNum = Math.floor((match.keyMoveIndex) / 2) + 1;
+
+    const state = {
+      match_meta: {
+        id: match.id,
+        title: match.title,
+        white: match.white,
+        black: match.black,
+        year: match.year,
+        eco: match.eco,
+        opening: match.opening,
+        result: match.result,
+        total_moves: match.moves.length,
+      },
+      turning_point: {
+        move_number: moveNum,
+        san: turningMove,
+        description: match.description,
+      },
+      moves_sample: match.moves.slice(0, 30),
+    };
+
+    const response = await this.client.systemOne({
+      state,
+      questions: {
+        archetype: choice(
+          "Which historical chess archetype best classifies `match_meta.title`?",
+          MATCH_ARCHETYPES
+        ),
+        brilliance: score(
+          "Rate the aesthetic and instructive brilliance of this classic match:",
+          BRILLIANCE_RUBRIC
+        ),
+        sharpness: score(
+          "Rate the overall tactical sharpness and volatility of this game:",
+          MATCH_SHARPNESS_RUBRIC
+        ),
+        decisive_sacrifice: noul(
+          "Does this match feature a sound, decisive piece or queen sacrifice for the initiative?"
+        ),
+      },
+    });
+
+    const archetype = response.answers.archetype.choice;
+    const brillianceScore = response.answers.brilliance.score;
+    const sharpnessScore = response.answers.sharpness.score;
+    const hasSac = response.answers.decisive_sacrifice.noul >= 0.6;
+
+    // Deterministically count tactical themes from move properties
+    let checksAndCaptures = 0;
+    let pawnMoves = 0;
+    for (const m of match.moves) {
+      if (m.includes("+") || m.includes("x") || m.includes("#")) checksAndCaptures++;
+      else if (m.toLowerCase()[0] >= "a" && m.toLowerCase()[0] <= "h" && !m.includes("O")) pawnMoves++;
+    }
+    const total = Math.max(1, match.moves.length);
+    const tacticalPct = Math.round((checksAndCaptures / total) * 100);
+    const pawnPct = Math.round((pawnMoves / total) * 100);
+    const piecePct = Math.max(10, 100 - tacticalPct - pawnPct);
+    const prophylPct = Math.round(piecePct * 0.35);
+
+    let verdict = `${match.title} (${match.year}) is a classic ${archetype.replace(/_/g, " ")}. `;
+    if (brillianceScore >= 2.3) {
+      verdict += "Widely celebrated as one of the finest artistic achievements in the history of the game.";
+    } else {
+      verdict += "A deeply instructive showcase of classical principles and aggressive tactical conversion.";
+    }
+
+    return {
+      matchId: match.id,
+      title: match.title,
+      archetype: archetype.replace(/_/g, " ").toUpperCase(),
+      aestheticBrilliance: {
+        score: brillianceScore,
+        level: BRILLIANCE_RUBRIC[Math.min(BRILLIANCE_RUBRIC.length - 1, Math.round(brillianceScore))] ?? "Masterpiece",
+        confidence: response.answers.brilliance.confidence,
+      },
+      overallSharpness: {
+        score: sharpnessScore,
+        level: MATCH_SHARPNESS_RUBRIC[Math.min(MATCH_SHARPNESS_RUBRIC.length - 1, Math.round(sharpnessScore))] ?? "Sharp",
+      },
+      hasDecisiveSacrifice: hasSac,
+      turningPoint: {
+        moveNumber: moveNum,
+        san: turningMove,
+        annotation: match.description,
+      },
+      strategicBreakdown: {
+        tacticalStrikesPct: tacticalPct,
+        pawnBreaksPct: pawnPct,
+        prophylaxisPct: prophylPct,
+        pieceActivationPct: piecePct,
+      },
+      verdict,
+    };
+  }
+}

package/src/demo.ts

@@ -0,0 +1,160 @@
+import { ChessEngine } from "./chessEngine.js";
+import { MoveResolver } from "./moveResolver.js";
+import { MoveEvaluator } from "./moveEvaluator.js";
+import { PersonaEngine, CHESS_PERSONAS } from "./personaEngine.js";
+import { GameReviewer } from "./gameReviewer.js";
+import { getTypeSafeClient } from "./typeSafeClient.js";
+
+async function runDemo() {
+  const client = getTypeSafeClient();
+  console.log("================================================================================");
+  console.log("   ♟️  JEV-CHESS: DESIGNING CHESS MOVES & GAMES WITH TYPESAFE AI  ♟️");
+  console.log("================================================================================");
+  console.log(`Backend Mode: ${client.isLive ? "🟢 LIVE (TypeSafe API - jev-latest)" : "🟡 SIMULATED (Calibrated offline fallback)"}`);
+  console.log("Principle: Code enforces board physics & rules; TypeSafe System One provides fast semantic judgment.\n");
+
+  const engine = new ChessEngine();
+
+  // ---------------------------------------------------------------------------
+  // SECTION 1: MOVE DESIGN - NATURAL LANGUAGE INTENT RESOLUTION
+  // ---------------------------------------------------------------------------
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log("1. MOVE RESOLUTION: 'Select Instead of Generate' Pattern (TypeSafe Choice)");
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+
+  // Play standard 1. e4 e5
+  engine.makeMove("e4");
+  engine.makeMove("e5");
+  console.log(`Current Board FEN: ${engine.fen()}`);
+  console.log(`Turn: ${engine.turn()} | Move: 2\n`);
+
+  const resolver = new MoveResolver();
+
+  const queries = [
+    "Develop my knight towards the center and attack their pawn",
+    "Push the queen's pawn two squares forward to contest the center",
+    "Teleport my rook directly to the other side", // Intent with no legal match
+  ];
+
+  for (const q of queries) {
+    console.log(`> Human command: "${q}"`);
+    const result = await resolver.resolveIntent(engine, q);
+    if (result.matchedMove) {
+      console.log(`  ✅ Matched Legal Move: ${result.matchedMove.san} (${result.matchedMove.description})`);
+      console.log(`     Confidence: ${(result.confidence * 100).toFixed(1)}%`);
+    } else {
+      console.log(`  ⚠️ Ambiguous or Illegal Command!`);
+      console.log(`     Confidence: ${(result.confidence * 100).toFixed(1)}% (Clarification Required)`);
+      if (result.alternativeCandidates.length > 0) {
+        console.log(`     Did you mean: ${result.alternativeCandidates.join(", ")}?`);
+      }
+    }
+    console.log();
+  }
+
+  // Play White 2. Nf3, Black 2. Nc6, White 3. Bc4, Black 3. Bc5
+  engine.makeMove("Nf3");
+  engine.makeMove("Nc6");
+  engine.makeMove("Bc4");
+  engine.makeMove("Bc5");
+
+  // ---------------------------------------------------------------------------
+  // SECTION 2: MOVE DESIGN - MULTI-DIMENSIONAL QUALITATIVE EVALUATION
+  // ---------------------------------------------------------------------------
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log("2. MOVE EVALUATION: Parallel Atomic Judgments (Score, Choice, Noul)");
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+
+  const evaluator = new MoveEvaluator();
+  const testMoves = ["c3", "O-O", "Bxf7+"];
+
+  for (const san of testMoves) {
+    // Check if legal in current or alternate position
+    const candidates = engine.getAnnotatedMoves();
+    let moveObj = candidates.find((m) => m.san === san);
+    if (!moveObj) {
+      // Create synthetic candidate for demonstration if not currently legal
+      moveObj = {
+        san,
+        from: "c2",
+        to: "c3",
+        piece: "pawn",
+        color: "white",
+        isCapture: san.includes("x"),
+        isCheck: san.includes("+"),
+        isCastling: san === "O-O",
+        description: san === "O-O" ? "Kingside castle" : `Move ${san}`,
+      };
+    }
+
+    const evalResult = await evaluator.evaluateMove(engine, moveObj);
+    console.log(`Move: ${evalResult.san}`);
+    console.log(`  Badge:                  ${evalResult.commentaryBadge}`);
+    console.log(`  Tactical Sharpness:     ${evalResult.tacticalSharpness.score.toFixed(1)} / 3.0 (${evalResult.tacticalSharpness.level})`);
+    console.log(`  Strategic Theme:        ${evalResult.strategicTheme.theme} (Confidence: ${(evalResult.strategicTheme.confidence * 100).toFixed(0)}%)`);
+    console.log(`  King Attack Threat:     ${(evalResult.kingAttackRisk.probability * 100).toFixed(0)}%`);
+    console.log(`  Psychological Pressure: ${(evalResult.psychologicalPressure.probability * 100).toFixed(0)}%`);
+    console.log();
+  }
+
+  // ---------------------------------------------------------------------------
+  // SECTION 3: GAME DESIGN - PERSONA AI OPPONENTS VIA COMPOSITE SCORING
+  // ---------------------------------------------------------------------------
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log("3. GAME DESIGN: Persona AI Opponents via Composite Scoring");
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log("Demonstrating how atomic scores are re-weighted in code to produce distinct personalities without rerunning inference:\n");
+
+  const personaEngine = new PersonaEngine();
+  const personas: Array<keyof typeof CHESS_PERSONAS> = ["tal", "petrosian", "capablanca", "coffeehouse"];
+
+  for (const pId of personas) {
+    const decision = await personaEngine.selectMove(engine, pId, 4);
+    const p = decision.persona;
+    console.log(`👤 ${p.name} - "${p.title}"`);
+    console.log(`   Weights: Aggression=${p.weights.aggression}, Prophylaxis=${p.weights.prophylaxis}, Complexity=${p.weights.complexity}, Greed=${p.weights.materialGreed}`);
+    console.log(`   Decision: Plays ${decision.selectedMove.san} (${decision.selectedMove.description})`);
+    console.log(`   Top 3 Ranked Moves:`);
+    for (let i = 0; i < Math.min(3, decision.rankedCandidates.length); i++) {
+      const c = decision.rankedCandidates[i]!;
+      console.log(`     #${i + 1} ${c.move.san.padEnd(5)} | Composite Score: ${c.compositeScore.toFixed(3)} (Agg:${c.dimensionScores.aggression.toFixed(1)}, Pro:${c.dimensionScores.prophylaxis.toFixed(1)}, Comp:${c.dimensionScores.complexity.toFixed(1)}, Greed:${c.dimensionScores.materialGreed.toFixed(2)})`);
+    }
+    console.log();
+  }
+
+  // ---------------------------------------------------------------------------
+  // SECTION 4: GAME REVIEW - POST-GAME BLUNDER TAXONOMY & DIAGNOSTICS
+  // ---------------------------------------------------------------------------
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log("4. GAME REVIEW: Structured Mistake Diagnostics (The Cascade Pattern)");
+  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+
+  const reviewer = new GameReviewer();
+  const sampleBlunder = {
+    san: "Qxh7??",
+    from: "d3",
+    to: "h7",
+    piece: "queen",
+    color: "white" as const,
+    isCapture: true,
+    isCheck: false,
+    isCastling: false,
+    description: "Queen captures h7 pawn without checking king safety",
+  };
+
+  const diagnosis = await reviewer.diagnoseMove(engine, sampleBlunder, 14);
+  console.log(`Reviewed Move: Move ${diagnosis.moveNumber} White played ${diagnosis.playedMove}`);
+  console.log(`  Mistake Taxonomy:    ${diagnosis.mistakeArchetype.toUpperCase()}`);
+  console.log(`  Defensive Difficulty: ${diagnosis.defensiveDifficulty.toFixed(1)} / 3.0`);
+  console.log(`  Game Tension Level:   ${diagnosis.tacticalTension.toFixed(1)} / 3.0`);
+  console.log(`  Coach Feedback:       "${diagnosis.coachAdvice}"\n`);
+
+  console.log("================================================================================");
+  console.log("   ✅ TypeSafe Chess Moves and Games Architecture demonstrated successfully!    ");
+  console.log("================================================================================");
+}
+
+runDemo().catch((err) => {
+  console.error("Demo failed:", err);
+  process.exit(1);
+});