chesspal 0.0.1 → 0.2.0

package/dist/core/game.js

@@ -0,0 +1,352 @@
+// A live game on chess.js: the rules, the record, and the legal moves computed once per position.
+import { Chess, validateFen } from "chess.js";
+import { factsOf } from "./facts.js";
+import { whyIllegal } from "./illegal.js";
+import { profileOf } from "./profile.js";
+import { cleanComment, recordedMove } from "./record.js";
+/**
+ * A live game: it plays moves written in SAN or as squares, and keeps the record. Checkmate, stalemate and the draws by insufficient material,
+ * threefold repetition and fifty moves end it (D-37); a game recorded elsewhere replays past the draws it played on from.
+ */
+export class Game {
+    chess;
+    tags;
+    comment;
+    moves = [];
+    last;
+    // The key of every position the game has stood in, the first included, and how each side castled: for the profile's repetitions and castling.
+    keys;
+    castled = {};
+    keptPosition;
+    keptOutcome;
+    keptRecord;
+    /** The game of a record, replayed move by move; without one, a new game from the standard position. */
+    constructor(record = { tags: {}, moves: [] }) {
+        this.chess = startingBoard(record.tags.FEN);
+        // The first key without an en passant square no pawn can use, which the FEN may give: the position then repeats as the rules count it.
+        this.keys = [new Chess(this.chess.fen()).hash()];
+        this.tags = { ...record.tags };
+        this.comment = cleanComment(record.comment ?? "") || undefined;
+        for (const { san, nags, comment } of record.moves) {
+            const move = this.apply(normalized(san));
+            // A refused move changes nothing: the label still names its place.
+            if ("refusal" in move) {
+                throw new Error(`The record's move ${moveLabel(this.chess, san)} cannot be played: ${move.message} Fix it, or the moves before it.`);
+            }
+            this.moves.push(recordedMove(move.san, nags, comment));
+        }
+    }
+    /** Where the game stands now. */
+    get position() {
+        this.keptPosition ??= Object.freeze({
+            fen: this.chess.fen(),
+            key: this.chess.hash(),
+            turn: sideToMove(this.chess),
+            moveNumber: this.chess.moveNumber(),
+            check: this.chess.inCheck(),
+        });
+        return this.keptPosition;
+    }
+    /** Whether the board ends the game, and how. */
+    get outcome() {
+        this.keptOutcome ??= outcomeOf(this.chess);
+        return this.keptOutcome;
+    }
+    /** The game as plain data, frozen; when the board ends the game, its Result tag is the board's, unless the record gave one. */
+    get record() {
+        this.keptRecord ??= this.snapshot();
+        return this.keptRecord;
+    }
+    /** The last move played, with its squares; none before the first. */
+    get lastMove() {
+        return this.last;
+    }
+    /** What the position shows (D-26): attackers and defenders, pieces at risk, pins, checks, the moves of each piece; computed once for each position. */
+    get facts() {
+        return factsOf(this.chess, legalMovesOf(this.chess));
+    }
+    /** The positional profile (D-19): pawns, files, outposts, space, mobility, development, king safety, control, phase, draws; computed once for each position. */
+    get profile() {
+        const key = this.chess.hash();
+        return profileOf(this.chess, { repetitions: this.keys.filter((seen) => seen === key).length, castled: this.castled, fromFen: this.tags.FEN !== undefined }, legalMovesOf(this.chess));
+    }
+    /** The legal moves, or those of the piece on a square. */
+    legalMoves(square) {
+        const moves = legalMovesOf(this.chess);
+        return square === undefined ? moves : moves.filter((move) => move.from === square);
+    }
+    /** Why the piece of the side to move on a square cannot go to another (D-18); undefined when it can, or when no rule says why. */
+    whyNot(from, to) {
+        return this.legalMoves(from).some((move) => move.to === to) ? undefined : whyIllegal(this.chess, from, to);
+    }
+    /** Plays a move written in SAN (Nf3, exd5, O-O, e8=Q), with the pieces' figurines too (♘f3), or as squares (g1f3, e7e8q); a refused move changes nothing. */
+    play(text) {
+        const { outcome } = this;
+        if (outcome.over) {
+            return { played: false, ...gameOver(outcome), legal: [] };
+        }
+        return this.playRecorded(text);
+    }
+    /** Plays a move of a game recorded elsewhere, as play does, but also past a draw that game played on from: insufficient material, repetition or fifty moves. */
+    playRecorded(text) {
+        const input = normalized(text);
+        const move = this.apply(input);
+        if ("refusal" in move) {
+            return { played: false, ...move, legal: legalMovesOf(this.chess).map((legal) => legal.san) };
+        }
+        this.moves.push(recordedMove(move.san));
+        const note = checkNote(input, move.san);
+        return note === undefined ? { played: true, move } : { played: true, move, note };
+    }
+    /** Sets the judgment of a move by its ply, 1 for the first move recorded: the NAGs and the comment given replace its own, an empty one removes them. */
+    annotate(ply, annotation) {
+        const move = this.moves[ply - 1];
+        if (!Number.isInteger(ply) || move === undefined) {
+            const plies = this.moves.length === 0 ? "the game has no moves yet" : `give a ply from 1 to ${this.moves.length}`;
+            throw new RangeError(`There is no move ${ply} in this game: ${plies}.`);
+        }
+        this.moves[ply - 1] = recordedMove(move.san, annotation.nags ?? move.nags, annotation.comment ?? move.comment);
+        this.keptRecord = undefined;
+    }
+    apply(input) {
+        // chess.js plays "--" as a null move, which skips a turn.
+        if (input.startsWith("--")) {
+            return unreadable(input);
+        }
+        const mover = sideToMove(this.chess);
+        // Proper SAN is the fast way; anything else is matched by hand, because chess.js guesses where we must ask.
+        const exact = attempt(() => this.chess.move(input, { strict: true }));
+        const move = exact === undefined ? this.resolve(input) : toMove(exact);
+        if ("refusal" in move) {
+            return move;
+        }
+        if (exact === undefined) {
+            this.chess.move({ from: move.from, to: move.to, promotion: move.promotion });
+        }
+        this.last = move;
+        this.keys.push(this.chess.hash());
+        if (move.san.startsWith("O-O")) {
+            this.castled[mover] = move.san.startsWith("O-O-O") ? "O-O-O" : "O-O";
+        }
+        this.keptPosition = undefined;
+        this.keptOutcome = undefined;
+        this.keptRecord = undefined;
+        return move;
+    }
+    /** A move written loosely (as squares, with a letter too many or too few) matched against the legal moves. */
+    resolve(input) {
+        const legal = legalMovesOf(this.chess);
+        // No legal move: checkmate or stalemate.
+        if (legal.length === 0 && this.outcome.over) {
+            return gameOver(this.outcome);
+        }
+        const bare = input.replace(/[+#]?[!?]*$/, "");
+        if (/^O-O(?:-O)?$/.test(bare)) {
+            return this.illegal(input);
+        }
+        const parts = loosePattern.exec(bare);
+        if (parts === null) {
+            return foreignLetter(input, bare) ?? unreadable(input);
+        }
+        const [, piece, file, rank, separator, target = "", promotion] = parts;
+        const capture = separator === "x" || separator === ":";
+        // "bc4" is a bishop without its capital, or a pawn's capture without its x, as "bb4" or "cc6" is a piece or a pawn: never guessed (Anatolij, round of D-87).
+        if (piece === undefined && file !== undefined && rank === undefined && !capture) {
+            return smallLetter(input, file, target);
+        }
+        // Without a letter, a move is a pawn's, unless it gives its whole starting square.
+        const kind = piece?.toLowerCase() ?? (file !== undefined && rank !== undefined ? undefined : "p");
+        const candidates = legal.filter((move) => move.to === target
+            && (file === undefined || move.from[0] === file)
+            && (rank === undefined || move.from[1] === rank)
+            && (kind === undefined || this.chess.get(move.from)?.type === kind)
+            && (!capture || move.san.includes("x"))
+            && (promotion === undefined || move.promotion === promotion.toLowerCase()));
+        if (promotion === undefined && candidates.some((move) => move.promotion !== undefined)) {
+            return { refusal: "unreadable", message: `${input} takes a pawn to the last rank: say the piece it becomes, as e8=Q or e7e8q.` };
+        }
+        if (candidates.length > 1) {
+            return { refusal: "ambiguous", message: `${input} could be ${candidates.map((move) => move.san).sort().join(" or ")}: say which.` };
+        }
+        if (candidates.length === 0 && capture && this.chess.get(target) === undefined && !legal.some((move) => move.to === target && move.san.includes("x"))) {
+            return { refusal: "illegal", message: `${input} takes, but there is nothing to take on ${target}.` };
+        }
+        // An Italian, French or Spanish R is the king: said when the king could go there and no rook can.
+        if (candidates.length === 0 && piece === "R" && legal.some((move) => move.to === target && this.chess.get(move.from)?.type === "k")) {
+            return { refusal: "illegal", message: `${input} is not legal here: R is the rook in SAN, and the king is K: K${target}.` };
+        }
+        return candidates[0] ?? this.illegal(input);
+    }
+    illegal(input) {
+        return { refusal: "illegal", message: `${input} is not legal here, with ${this.chess.turn() === "w" ? "White" : "Black"} to move.` };
+    }
+    snapshot() {
+        const { outcome } = this;
+        // A game recorded elsewhere keeps its Result: it may have played on from a draw and ended otherwise.
+        const open = (this.tags.Result ?? "*") === "*";
+        const tags = Object.freeze(outcome.over && open ? { ...this.tags, Result: outcome.result } : { ...this.tags });
+        const moves = Object.freeze([...this.moves]);
+        return Object.freeze(this.comment === undefined ? { tags, moves } : { tags, comment: this.comment, moves });
+    }
+}
+// A piece, all or part of its square, a separator, the square it goes to, the promotion: e4, Nbd2, g1f3, e7-e8q, exd6 e.p.
+const loosePattern = /^([KQRBNP])?([a-h])?([1-8])?([-x:])?([a-h][1-8])=?([QRBNqrbn])?(?:\s*e\.?p\.?)?$/;
+// What word processors, phones and books write for SAN's letters and signs; the pawn's figurine says nothing.
+const asciiOf = {
+    "–": "-",
+    "—": "-",
+    "−": "-",
+    "×": "x",
+    "♔": "K",
+    "♚": "K",
+    "♕": "Q",
+    "♛": "Q",
+    "♖": "R",
+    "♜": "R",
+    "♗": "B",
+    "♝": "B",
+    "♘": "N",
+    "♞": "N",
+    "♙": "",
+    "♟": "",
+};
+/** A text with SAN's letters and signs for the figurines and signs others write: ♘f3 as Nf3, × as x; a pawn's figurine says nothing. */
+export function withSanLetters(text) {
+    return text.replace(/[︎️]/g, "").replace(/[–—−×♔-♟]/g, (sign) => asciiOf[sign] ?? sign);
+}
+// The pieces' letters of other languages that name one piece only: the Italian, French, Spanish and German ones; R is the rook in SAN.
+const foreignPieces = {
+    C: ["knight", "N"],
+    S: ["knight", "N"],
+    A: ["bishop", "B"],
+    F: ["bishop", "B"],
+    L: ["bishop", "B"],
+    T: ["rook", "R"],
+    D: ["queen", "Q"],
+};
+// The legal moves of the positions seen last, by their key: about 4 KB each.
+const legalByPosition = new Map();
+const positionsKept = 1_000;
+const goingOn = Object.freeze({ over: false });
+const draws = [
+    ["stalemate", (chess) => chess.isStalemate()],
+    ["insufficient material", (chess) => chess.isInsufficientMaterial()],
+    ["threefold repetition", (chess) => chess.isThreefoldRepetition()],
+    ["fifty moves", (chess) => chess.isDrawByFiftyMoves()],
+];
+function legalMovesOf(chess) {
+    const key = chess.hash();
+    let moves = legalByPosition.get(key);
+    if (moves === undefined) {
+        moves = Object.freeze(chess.moves({ verbose: true }).map(toMove));
+        if (legalByPosition.size >= positionsKept) {
+            legalByPosition.delete(legalByPosition.keys().next().value);
+        }
+        legalByPosition.set(key, moves);
+    }
+    return moves;
+}
+function outcomeOf(chess) {
+    if (chess.isCheckmate()) {
+        return Object.freeze({ over: true, result: chess.turn() === "w" ? "0-1" : "1-0", ending: "checkmate" });
+    }
+    const draw = draws.find(([, applies]) => applies(chess));
+    return draw === undefined ? goingOn : Object.freeze({ over: true, result: "1/2-1/2", ending: draw[0] });
+}
+function toMove({ san, from, to, promotion }) {
+    return Object.freeze(promotion === undefined ? { san, from, to } : { san, from, to, promotion: promotion });
+}
+/**
+ * The move in SAN: trimmed, without a move number before it, its signs and figurines in ASCII, a piece's small letter in capital (not b, a file too), ++ as
+ * #, castling in capital O.
+ */
+function normalized(text) {
+    return text.trim()
+        .replace(/^\d+\s*(?:\.[\s.]*|…\s*)/, "")
+        .replace(/[︎️]/g, "")
+        // A space after the piece's letter, "N f3", as an AI may show the player how to write (Priya).
+        .replace(/^([A-Z♔-♟])\s+(?=[a-h1-8x:])/, "$1")
+        .replace(/[–—−×♔-♟]/g, (sign) => asciiOf[sign] ?? sign)
+        // A small t too, so that "tf1" is told the rook's R as "Tf1" is.
+        .replace(/^[nrqkt](?=[a-h1-8x:])/, (piece) => piece.toUpperCase())
+        .replace(/\+\+(?=[!?]*$)/, "#")
+        .replace(/^[0Oo]-[0Oo](?:-[0Oo])?(?=[+#]?[!?]*$)/, (castling) => castling.replace(/[0o]/g, "O"));
+}
+/** What the board says when a move was written with a check or a mate it does not give: a sign that the writer sees another position; neutral, since the AI reads it of the player's moves too. */
+function checkNote(input, san) {
+    const written = /([+#])[!?]*$/.exec(input)?.[1];
+    const given = /[+#]$/.exec(san)?.[0];
+    if (written === undefined || written === given) {
+        return undefined;
+    }
+    const bare = san.replace(/[+#]$/, "");
+    const truth = given === undefined ? "gives no check" : given === "+" ? "is check, not mate" : "is checkmate";
+    return `Written as ${input}, but ${bare} ${truth}.`;
+}
+/** The board of a FEN tag, refused when no game can reach it; without one, the standard position. */
+function startingBoard(fen) {
+    if (fen === undefined) {
+        return new Chess();
+    }
+    const { ok, error } = validateFen(fen);
+    const chess = ok ? new Chess(fen) : undefined;
+    if (chess === undefined || kingInCheckOffTurn(chess)) {
+        throw new Error(`The FEN tag is not a valid position (${error ?? "the side not to move is in check"}): fix it, or remove it to start from the standard position.`);
+    }
+    return chess;
+}
+function kingInCheckOffTurn(chess) {
+    const [king] = chess.findPiece({ type: "k", color: chess.turn() === "w" ? "b" : "w" });
+    return king !== undefined && chess.isAttacked(king, chess.turn());
+}
+function gameOver({ ending, result }) {
+    return { refusal: "over", message: `The game is over by ${ending} (${result}): no move can follow.` };
+}
+/** A move written with a piece's letter of another language: Cf3 for an Italian or French knight, Dd1 for a queen; none for another mistake. */
+function foreignLetter(input, bare) {
+    const [, move = "", becomes = ""] = /^(.*[18])=?([A-Z])$/.exec(bare) ?? [];
+    if (becomes !== "" && !"QRBN".includes(becomes)) {
+        const piece = foreignPieces[becomes];
+        const instead = piece === undefined ? "" : ` For a ${piece[0]}, ${move}=${piece[1]}.`;
+        return { refusal: "unreadable", message: `"${input}" is not a move: a pawn becomes Q, R, B or N, never ${becomes}.${instead}` };
+    }
+    const letter = /^([A-Z])[a-h1-8]?[-x:]?[a-h][1-8]/.exec(bare)?.[1];
+    if (letter === undefined || "KQRBNP".includes(letter)) {
+        return undefined;
+    }
+    const piece = foreignPieces[letter];
+    const instead = piece === undefined ? "" : ` For a ${piece[0]}, ${piece[1]}${bare.slice(1)}.`;
+    // T is the Italian, French and Spanish rook, whose R is their king.
+    const king = letter === "T" ? " In SAN R is the rook, and K the king." : "";
+    return { refusal: "unreadable", message: `"${input}" is not a move: SAN writes the pieces K, Q, R, B and N, and a pawn with none, never ${letter}.${instead}${king}` };
+}
+/** A move that opens with a small letter and a square of another file, or "bb4": a pawn's capture without its x, a piece without its capital. */
+function smallLetter(input, file, target) {
+    const files = Math.abs(file.charCodeAt(0) - target.charCodeAt(0));
+    const piece = file === "b" ? ["bishop", "B"] : foreignPieces[file.toUpperCase()];
+    const hints = [
+        files === 0 ? `The pawn's move is ${target}.` : "",
+        files === 1 ? `A pawn takes with an x: ${file}x${target}.` : "",
+        piece === undefined ? "" : `For a ${piece[0]}, ${piece[1]}${target}.`,
+    ].filter((hint) => hint !== "");
+    const said = hints.length > 0 ? hints : ["A piece is a capital letter: K, Q, R, B or N."];
+    return { refusal: "unreadable", message: `"${input}" is not a move: ${file} is a file. ${said.join(" ")}` };
+}
+/** A move that reads as none, with SAN's examples. */
+function unreadable(input) {
+    return { refusal: "unreadable", message: `"${input}" is not a move: write it in SAN (Nf3, exd5, O-O, e8=Q) or as squares (g1f3, e7e8q).` };
+}
+function sideToMove(chess) {
+    return chess.turn() === "w" ? "white" : "black";
+}
+function moveLabel(chess, san) {
+    return `${chess.moveNumber()}${chess.turn() === "w" ? "." : "..."} ${san}`;
+}
+function attempt(run) {
+    try {
+        return run();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/illegal.d.ts

@@ -0,0 +1,19 @@
+import { Chess, type Square } from "chess.js";
+/**
+ * Why a piece cannot go to a square: a piece of its side stands there; it does not move that way; a piece stands in its way; a pawn takes only
+ * diagonally, goes two squares only from its first, diagonally only to take, and en passant only right after the double step; the king is in check and
+ * the move does not answer it; the move uncovers the king; the king would stand in check; castling with the king or that rook moved, the rook gone, a
+ * piece between them, the king in check, or a square it crosses or reaches attacked.
+ */
+export type IllegalReason = "own" | "shape" | "blocked" | "pawn-straight" | "pawn-double" | "pawn-diagonal" | "en-passant-late" | "check" | "pinned" | "attacked" | "castle-lost" | "castle-rook-gone" | "castle-blocked" | "castle-check" | "castle-through";
+/**
+ * Why a move is not legal, with the square of the piece that makes it so, when one does (the blocker, the piece giving check, the pinner, the attacker, the
+ * pawn too late to take), and the square it concerns, when it is not the one the piece went to: the rook's corner, the square castling crosses.
+ */
+export interface Illegal {
+    readonly reason: IllegalReason;
+    readonly by?: Square;
+    readonly at?: Square;
+}
+/** Why the piece of the side to move on one square cannot go to another, which its legal moves do not reach; undefined when no rule says why. */
+export declare function whyIllegal(chess: Chess, from: Square, to: Square): Illegal | undefined;

package/dist/core/illegal.js

@@ -0,0 +1,141 @@
+// Why the board refuses a move, without judging anything (D-18): the page tells the player who tried it.
+import { Chess } from "chess.js";
+import { fileOf, rankOf, squaresBetween } from "./facts.js";
+/** Why the piece of the side to move on one square cannot go to another, which its legal moves do not reach; undefined when no rule says why. */
+export function whyIllegal(chess, from, to) {
+    const piece = chess.get(from);
+    if (piece === undefined || piece.color !== chess.turn()) {
+        throw new RangeError(`There is no piece of the side to move on ${from}: ask why only of a piece that may move.`);
+    }
+    // A king going two squares from its first castles, as does one taken onto its own rook, though a piece of its own stands where it goes.
+    const castling = piece.type === "k" ? castlingTo(chess, from, to, piece.color) : undefined;
+    if (castling !== undefined) {
+        return whyNotCastling(chess, from, castling, piece.color);
+    }
+    // The way a piece moves comes first: a rook taken diagonally onto a piece of its own breaks that rule before the other.
+    if (piece.type !== "p" && !reaches(piece.type, from, to)) {
+        return { reason: "shape" };
+    }
+    if (chess.get(to)?.color === piece.color) {
+        return { reason: "own" };
+    }
+    const pawn = piece.type === "p" ? pawnRule(chess, from, to, piece.color) : undefined;
+    if (pawn !== undefined) {
+        return pawn;
+    }
+    const blocker = squaresBetween(from, to).find((square) => chess.get(square) !== undefined);
+    return blocker !== undefined && piece.type !== "n" ? { reason: "blocked", by: blocker } : kingExposed(chess, from, to, piece.color);
+}
+/** Whether a piece's move from one square reaches another on an empty board: pawns aside. */
+function reaches(type, from, to) {
+    const files = Math.abs(fileOf(to) - fileOf(from));
+    const ranks = Math.abs(rankOf(to) - rankOf(from));
+    const straight = files === 0 || ranks === 0;
+    const diagonal = files === ranks;
+    switch (type) {
+        case "n":
+            return files * ranks === 2;
+        case "k":
+            return Math.max(files, ranks) === 1;
+        case "b":
+            return diagonal;
+        case "r":
+            return straight;
+        default:
+            return straight || diagonal;
+    }
+}
+/** What a pawn's own rules refuse, with the piece in its way on a double step, or the pawn it took en passant too late; undefined when they allow the move. */
+function pawnRule(chess, from, to, color) {
+    const forward = color === "w" ? 1 : -1;
+    const files = Math.abs(fileOf(to) - fileOf(from));
+    const ranks = (rankOf(to) - rankOf(from)) * forward;
+    const taken = chess.get(to) !== undefined;
+    if (files === 1 && ranks === 1) {
+        // chess.js leaves the en passant square out of its FEN when no capture there is legal, unless forced.
+        const enPassant = chess.fen({ forceEnpassantSquare: true }).split(" ")[3];
+        return taken || to === enPassant ? undefined : lateEnPassant(chess, from, to, color) ?? { reason: "pawn-diagonal" };
+    }
+    if (files !== 0 || ranks < 1 || ranks > 2) {
+        return { reason: "shape" };
+    }
+    if (ranks === 2 && rankOf(from) !== (color === "w" ? 2 : 7)) {
+        return { reason: "pawn-double" };
+    }
+    const between = squaresBetween(from, to).find((square) => chess.get(square) !== undefined);
+    if (between !== undefined) {
+        return { reason: "blocked", by: between };
+    }
+    return taken ? { reason: "pawn-straight" } : undefined;
+}
+/** A pawn on its fifth rank taking diagonally to an empty square beside an enemy pawn: en passant, but not right after that pawn's double step. */
+function lateEnPassant(chess, from, to, color) {
+    const beside = `${to[0]}${from[1]}`;
+    const pawn = chess.get(beside);
+    const fifth = rankOf(from) === (color === "w" ? 5 : 4);
+    return fifth && pawn?.type === "p" && pawn.color !== color ? { reason: "en-passant-late", by: beside } : undefined;
+}
+/** Why the move would leave its king in check, played on a copy: the king steps into it, a check it does not answer, or a line it uncovers. */
+function kingExposed(chess, from, to, color) {
+    const enemy = color === "w" ? "b" : "w";
+    const piece = chess.get(from);
+    const after = new Chess(chess.fen());
+    const enPassant = piece.type === "p" && fileOf(from) !== fileOf(to) && after.get(to) === undefined;
+    after.remove(from);
+    after.remove(to);
+    after.put(piece, to);
+    if (enPassant) {
+        after.remove(`${to[0]}${from[1]}`);
+    }
+    const king = piece.type === "k" ? to : after.findPiece({ type: "k", color })[0];
+    const attackers = after.attackers(king, enemy);
+    if (attackers.length === 0) {
+        return undefined;
+    }
+    if (piece.type === "k") {
+        return { reason: "attacked", by: attackers[0] };
+    }
+    const checkers = chess.inCheck() ? chess.attackers(king, enemy) : [];
+    const unanswered = attackers.find((square) => checkers.includes(square));
+    return unanswered !== undefined ? { reason: "check", by: unanswered } : { reason: "pinned", by: attackers[0] };
+}
+/** The square a king's move castles to: two squares along its first rank from its own, or its own rook's corner; none for another move. */
+function castlingTo(chess, from, to, color) {
+    const home = color === "w" ? "e1" : "e8";
+    if (from !== home || to[1] !== home[1]) {
+        return undefined;
+    }
+    const corner = to[0] === "h" ? "g" : to[0] === "a" ? "c" : undefined;
+    const rook = chess.get(to);
+    if (corner !== undefined && rook?.type === "r" && rook.color === color) {
+        return `${corner}${home[1]}`;
+    }
+    return Math.abs(fileOf(to) - fileOf(from)) === 2 ? to : undefined;
+}
+/** Why the king cannot castle: its right lost, the rook gone, a check, a piece between it and the rook, a square it crosses or reaches attacked. */
+function whyNotCastling(chess, from, to, color) {
+    const kingside = fileOf(to) > fileOf(from);
+    const corner = `${kingside ? "h" : "a"}${from[1]}`;
+    const enemy = color === "w" ? "b" : "w";
+    const rook = chess.get(corner);
+    if (rook?.type !== "r" || rook.color !== color) {
+        return { reason: "castle-rook-gone", at: corner };
+    }
+    if (!chess.getCastlingRights(color)[kingside ? "k" : "q"]) {
+        return { reason: "castle-lost" };
+    }
+    if (chess.inCheck()) {
+        return { reason: "castle-check", by: chess.attackers(from, enemy)[0] };
+    }
+    const between = squaresBetween(from, corner).find((square) => chess.get(square) !== undefined);
+    if (between !== undefined) {
+        return { reason: "castle-blocked", by: between };
+    }
+    for (const square of [...squaresBetween(from, to), to]) {
+        const [attacker] = chess.attackers(square, enemy);
+        if (attacker !== undefined) {
+            return { reason: "castle-through", by: attacker, at: square };
+        }
+    }
+    return undefined;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,20 @@
+export { boardText, figurinesOf } from "./board-text.ts";
+export { canMate, clockAfterMove, clockOfComment, clockStarted, clockTag, clockText, startClock, timeControlOf, timeControlOfTag, timeControlTag, timeControlText, timeLeft } from "./clock.ts";
+export type { Clock, TimeControl } from "./clock.ts";
+export type { Facts, PieceFacts, PieceLetter, Pin } from "./facts.ts";
+export { Game, withSanLetters } from "./game.ts";
+export type { Ending, Move, Outcome, Played, Position, Promotion, Refusal, Side, Square } from "./game.ts";
+export type { Illegal, IllegalReason } from "./illegal.ts";
+export { type Lead, leadOf, leadText, readLead, withLead } from "./lead.ts";
+export { aiLevels, layersOf, levelForPlayer, levelOf, levelTag, sees, suggestedLevel } from "./levels.ts";
+export type { AiLevel, Layer } from "./levels.ts";
+export { materialOf } from "./material.ts";
+export type { Material } from "./material.ts";
+export { endWithMood, type Mood, moodAt, type MoodNow, moodOf, moods, moodTag, withoutMoods } from "./moods.ts";
+export { bookMoves, indexBook, indexOpenings, inOpenings, openingOf, outOfBookMove } from "./openings.ts";
+export type { Opening, OpeningBook, OpeningIndex } from "./openings.ts";
+export { pgnDate, readPgn, writePgn } from "./pgn.ts";
+export type { BishopFacts, CentreSquare, KingFacts, Outpost, PawnFacts, PawnSquare, Phase, Profile, SideProfile } from "./profile.ts";
+export { movesOnly } from "./record.ts";
+export type { Annotation, GameRecord, RecordedMove } from "./record.ts";
+export { type AiModel, aiModelIn, annotatorOf, arrowOf, type Badge, badges, closingOf, type DrawColour, drawingsIn, drawingsText, type DrawnArrow, type DrawnSquare, gameReviewOf, isReviewed, type MoveReview, reviewed, reviewOf, squareOf, unreviewed, withAiModel, withAnnotator, withGameReview, } from "./review.ts";

package/dist/core/index.js

@@ -0,0 +1,12 @@
+// The chess core: the game and its rules, the facts of a position, its record, PGN, the openings. It runs in the browser too (D-17, D-18).
+export { boardText, figurinesOf } from "./board-text.js";
+export { canMate, clockAfterMove, clockOfComment, clockStarted, clockTag, clockText, startClock, timeControlOf, timeControlOfTag, timeControlTag, timeControlText, timeLeft } from "./clock.js";
+export { Game, withSanLetters } from "./game.js";
+export { leadOf, leadText, readLead, withLead } from "./lead.js";
+export { aiLevels, layersOf, levelForPlayer, levelOf, levelTag, sees, suggestedLevel } from "./levels.js";
+export { materialOf } from "./material.js";
+export { endWithMood, moodAt, moodOf, moods, moodTag, withoutMoods } from "./moods.js";
+export { bookMoves, indexBook, indexOpenings, inOpenings, openingOf, outOfBookMove } from "./openings.js";
+export { pgnDate, readPgn, writePgn } from "./pgn.js";
+export { movesOnly } from "./record.js";
+export { aiModelIn, annotatorOf, arrowOf, badges, closingOf, drawingsIn, drawingsText, gameReviewOf, isReviewed, reviewed, reviewOf, squareOf, unreviewed, withAiModel, withAnnotator, withGameReview, } from "./review.js";

package/dist/core/lead.d.ts

@@ -0,0 +1,15 @@
+import { type RecordedMove } from "./record.ts";
+/** Who is ahead after a move: pawns from White's side (+1.5 White, -3 Black), or a mate in so many moves (#3 White's, #-3 Black's). */
+export type Lead = {
+    readonly pawns: number;
+} | {
+    readonly mate: number;
+};
+/** A lead as the AI writes it: +1.5, -3, 0, #3, #-2; none when it is not one. */
+export declare function readLead(text: string): Lead | undefined;
+/** A lead as the PGN and the page write it: +1.5, -3, 0, #3, #-2. */
+export declare function leadText(lead: Lead): string;
+/** The lead a move's comment carries, when the AI estimated one. */
+export declare function leadOf(comment: string | undefined): Lead | undefined;
+/** The move with the AI's lead in place of the one it had, beside what its comment held. */
+export declare function withLead(move: RecordedMove, lead: Lead): RecordedMove;

package/dist/core/lead.js

@@ -0,0 +1,40 @@
+// Who is ahead in a position, as the AI estimates it (D-90): in pawns from White's side, as chess.com shows it, or a mate it sees. It rides in a move's
+// comment as [%lead +1.5] or [%lead #-3], Chesspal's own command and not [%eval], which elsewhere would pass for an engine's. Chesspal keeps it and draws
+// it, never computes it (D-6, D-19).
+import { recordedMove } from "./record.js";
+/** A lead as the AI writes it: +1.5, -3, 0, #3, #-2; none when it is not one. */
+export function readLead(text) {
+    const plain = text.trim().replaceAll("−", "-").replace(/^M/i, "#").replace(/^([+-])[#M]/i, "#$1");
+    const mate = /^#([+-]?)(\d+)$/.exec(plain);
+    if (mate !== null) {
+        const moves = Number(mate[2]);
+        return moves < 1 || moves > leadLimit ? undefined : { mate: mate[1] === "-" ? -moves : moves };
+    }
+    if (!/^[+-]?\d+(\.\d+)?$/.test(plain)) {
+        return undefined;
+    }
+    // To a tenth, a half away from zero on both sides; never a negative zero: -0.04 is an even game.
+    const figure = Number(plain);
+    const pawns = Math.sign(figure) * Math.round(Math.abs(figure) * 10) / 10;
+    return Math.abs(pawns) > leadLimit ? undefined : { pawns: pawns === 0 ? 0 : pawns };
+}
+/** A lead as the PGN and the page write it: +1.5, -3, 0, #3, #-2. */
+export function leadText(lead) {
+    if ("mate" in lead) {
+        return `#${lead.mate}`;
+    }
+    return lead.pawns > 0 ? `+${lead.pawns}` : `${lead.pawns}`;
+}
+/** The lead a move's comment carries, when the AI estimated one. */
+export function leadOf(comment) {
+    const found = leadPattern.exec(comment ?? "")?.[1];
+    return found === undefined ? undefined : readLead(found);
+}
+/** The move with the AI's lead in place of the one it had, beside what its comment held. */
+export function withLead(move, lead) {
+    const comment = [(move.comment ?? "").replace(/\s*\[%lead [^\]]*\]/g, "").trim(), `[%lead ${leadText(lead)}]`].filter((part) => part !== "").join(" ");
+    return recordedMove(move.san, move.nags, comment);
+}
+const leadPattern = /\[%lead ([^\]]*)\]/;
+// The largest lead Chesspal keeps, in pawns or moves to mate: beyond it the AI's figure says nothing more.
+const leadLimit = 99;

package/dist/core/levels.d.ts

@@ -0,0 +1,20 @@
+import type { GameRecord } from "./record.ts";
+/** The AI's levels, the weakest first. */
+export declare const aiLevels: readonly ["beginner", "club", "strong", "master"];
+export type AiLevel = (typeof aiLevels)[number];
+/** The layers of facts: the board as the player sees it (D-59), the tactical view (D-26), the positional profile, the opening book's moves (D-15). */
+declare const layers: readonly ["board", "tactics", "strategy", "theory"];
+export type Layer = (typeof layers)[number];
+/** The PGN tag that keeps a game's level, so the archive keeps it too. */
+export declare const levelTag = "AILevel";
+/** The level to suggest by how the player says they play (D-23), a step below their strength: strong only when they choose it. */
+export declare const levelForPlayer: Readonly<Record<string, AiLevel>>;
+/** The level of a new game the player does not choose: the game before's, else the one that suits how the player says they play, else the former one. */
+export declare function suggestedLevel(before: GameRecord | undefined, playerLevel: string | undefined): AiLevel;
+/** The layers a level sees, the board first. */
+export declare function layersOf(level: AiLevel): readonly Layer[];
+/** Whether a level sees a layer. */
+export declare function sees(level: AiLevel, layer: Layer): boolean;
+/** The level a game is played at, by its tag; a game without one was played before levels came. */
+export declare function levelOf(record: GameRecord): AiLevel;
+export {};