chesspal 0.0.1 → 0.2.0

package/dist/core/pgn.d.ts

@@ -0,0 +1,10 @@
+import { type GameRecord } from "./record.ts";
+/**
+ * A game as PGN: the seven standard tags first, then its others (SetUp before a FEN), the moves with their judgments, in lines under 80 characters.
+ * The judgments $1 to $6 are written as !, ?, !!, ??, !? and ?!, which players read and every tool takes.
+ */
+export declare function writePgn(record: GameRecord): string;
+/** The games of a PGN text, with their tags, moves, NAGs (! and ? too) and comments; variations are skipped. Every move is checked: an error names its line. */
+export declare function readPgn(text: string): GameRecord[];
+/** The day of a date, in its own time zone, as PGN's Date tag writes it: 2026.11.02. */
+export declare function pgnDate(date: Date): string;

package/dist/core/pgn.js

@@ -0,0 +1,213 @@
+// PGN in and out, our own: chess.js drops NAGs and variations. Every move read is checked by a Game.
+import { Game } from "./game.js";
+import { cleanComment, recordedMove } from "./record.js";
+/**
+ * A game as PGN: the seven standard tags first, then its others (SetUp before a FEN), the moves with their judgments, in lines under 80 characters.
+ * The judgments $1 to $6 are written as !, ?, !!, ??, !? and ?!, which players read and every tool takes.
+ */
+export function writePgn(record) {
+    const roster = sevenTags.map(([name, unknown]) => tagLine(name, record.tags[name] ?? unknown));
+    // SetUp goes first, before the FEN it announces.
+    const { SetUp: setUp = record.tags.FEN === undefined ? undefined : "1", ...tags } = record.tags;
+    const others = Object.entries(setUp === undefined ? tags : { SetUp: setUp, ...tags }).filter(([name]) => !sevenTagNames.has(name)).map(([name, value]) => tagLine(name, value));
+    return `${[...roster, ...others].join("\n")}\n\n${wrapped(movetext(record))}\n`;
+}
+/** The games of a PGN text, with their tags, moves, NAGs (! and ? too) and comments; variations are skipped. Every move is checked: an error names its line. */
+export function readPgn(text) {
+    return new PgnReader(text).read();
+}
+/** The day of a date, in its own time zone, as PGN's Date tag writes it: 2026.11.02. */
+export function pgnDate(date) {
+    const two = (value) => String(value).padStart(2, "0");
+    return `${date.getFullYear()}.${two(date.getMonth() + 1)}.${two(date.getDate())}`;
+}
+// The seven tags of every PGN, in their order, with the value for an unknown one.
+const sevenTags = [["Event", "?"], ["Site", "?"], ["Date", "????.??.??"], ["Round", "?"], ["White", "?"], ["Black", "?"], ["Result", "*"]];
+const sevenTagNames = new Set(sevenTags.map(([name]) => name));
+// The judgments written after a move, NAGs $1 to $6.
+const glyphs = ["!", "?", "!!", "??", "!?", "?!"];
+const nagOfGlyph = new Map(glyphs.map((glyph, index) => [glyph, index + 1]));
+// The standard wants lines under 80 characters.
+const lineLength = 79;
+// A token: spaces, a % escape line, a ; comment, a tag, a { comment }, a NAG, a parenthesis, a move number, a result, a move.
+const tokenPattern = /\s+|(?<![^\n])%[^\n]*|;[^\n]*|\[\s*(\w+)\s*"((?:[^"\\]|\\.)*)"\s*\]|\{([^}]*)\}|\$(\d+)|([()])|\d+\s*\.+|\.+|(1-0|0-1|1\/2-1\/2|\*)|([^\s{}()[\]";$]+)/y;
+class PgnReader {
+    text;
+    records = [];
+    tags = [];
+    comments = [];
+    moves = [];
+    game;
+    result;
+    depth = 0;
+    at = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    read() {
+        for (let index = 0; index < this.text.length; index = tokenPattern.lastIndex) {
+            tokenPattern.lastIndex = index;
+            const match = tokenPattern.exec(this.text);
+            if (match === null) {
+                const character = this.text[index];
+                throw this.error(index, character === "{" ? "this comment is never closed with }." : `"${character}" is not PGN: remove it.`);
+            }
+            this.at = index;
+            this.take(match);
+        }
+        if (this.depth > 0) {
+            throw this.error(this.text.length, "a variation is never closed with ).");
+        }
+        this.finish();
+        return this.records;
+    }
+    take([, tagName, tagValue = "", comment, nag, parenthesis, result, move]) {
+        if (parenthesis !== undefined) {
+            this.depth += parenthesis === "(" ? 1 : -1;
+            if (this.depth < 0) {
+                throw this.error(this.at, "this ) closes no variation: remove it.");
+            }
+            return;
+        }
+        // Inside a variation, everything is skipped.
+        if (this.depth > 0) {
+            return;
+        }
+        if (tagName !== undefined) {
+            this.tag(tagName, tagValue.replace(/\\(.)/g, "$1"));
+        }
+        else if (comment !== undefined) {
+            this.started();
+            (this.moves.at(-1)?.comments ?? this.comments).push(comment);
+        }
+        else if (nag !== undefined) {
+            this.nag(Number(nag));
+        }
+        else if (result !== undefined) {
+            this.started();
+            this.result = result;
+            this.finish();
+        }
+        else if (move !== undefined) {
+            this.move(move);
+        }
+    }
+    tag(name, value) {
+        // A tag after the moves starts the next game, when the last one had no result.
+        if (this.game !== undefined) {
+            this.finish();
+        }
+        this.tags.push([name, value]);
+    }
+    move(token) {
+        // "e.p." after an en passant capture says nothing more.
+        if (/^e\.?p\.?$/i.test(token)) {
+            return;
+        }
+        const [, san = "", glyph = ""] = /^(.*?)([!?]*)$/.exec(token) ?? [];
+        const game = this.started();
+        if (san !== "") {
+            const played = game.playRecorded(san);
+            if (!played.played) {
+                throw this.error(this.at, played.message, game.position.moveNumber);
+            }
+            this.moves.push({ san: played.move.san, nags: [], comments: [] });
+        }
+        if (glyph !== "") {
+            const nag = nagOfGlyph.get(glyph);
+            if (nag === undefined) {
+                throw this.error(this.at, `"${glyph}" is not a judgment: write !, ?, !!, ??, !? or ?!.`);
+            }
+            this.nag(nag);
+        }
+    }
+    nag(nag) {
+        if (nag > 255) {
+            throw this.error(this.at, `$${nag} is not a NAG: NAGs go from $0 to $255.`);
+        }
+        this.started();
+        // A NAG before the first move judges nothing: skipped.
+        this.moves.at(-1)?.nags.push(nag);
+    }
+    /** The game the moves are played on, made from the tags at the first move. */
+    started() {
+        if (this.game === undefined) {
+            try {
+                this.game = new Game({ tags: Object.fromEntries(this.tags), moves: [] });
+            }
+            catch (error) {
+                throw this.error(this.at, error.message);
+            }
+        }
+        return this.game;
+    }
+    finish() {
+        if (this.tags.length > 0 || this.moves.length > 0 || this.result !== undefined) {
+            this.started();
+            const tags = Object.fromEntries(this.tags);
+            if (tags.Result === undefined && this.result !== undefined) {
+                tags.Result = this.result;
+            }
+            const moves = Object.freeze(this.moves.map((move) => recordedMove(move.san, move.nags, move.comments.join(" "))));
+            const comment = cleanComment(this.comments.join(" ")) || undefined;
+            this.records.push(Object.freeze(comment === undefined ? { tags: Object.freeze(tags), moves } : { tags: Object.freeze(tags), comment, moves }));
+        }
+        this.tags = [];
+        this.comments = [];
+        this.moves = [];
+        this.game = undefined;
+        this.result = undefined;
+    }
+    error(index, message, moveNumber) {
+        const line = this.text.slice(0, index).split("\n").length;
+        return new Error(`Line ${line}${moveNumber === undefined ? "" : `, move ${moveNumber}`}: ${message}`);
+    }
+}
+function movetext(record) {
+    const [, turn, , , , number] = (record.tags.FEN ?? "").split(" ");
+    const tokens = commentTokens(record.comment);
+    let moveNumber = Number(number) || 1;
+    let white = turn !== "b";
+    // Black's move carries its number at the start and after a comment or a NAG of its own.
+    let annotated = true;
+    for (const move of record.moves) {
+        if (white) {
+            tokens.push(`${moveNumber}.`);
+        }
+        else if (annotated) {
+            tokens.push(`${moveNumber}...`);
+        }
+        const glyph = move.nags?.find((nag) => nag >= 1 && nag <= glyphs.length);
+        const nags = (move.nags ?? []).filter((nag) => nag !== glyph).map((nag) => `$${nag}`);
+        const comment = commentTokens(move.comment);
+        tokens.push(glyph === undefined ? move.san : `${move.san}${glyphs[glyph - 1]}`, ...nags, ...comment);
+        annotated = nags.length > 0 || comment.length > 0;
+        moveNumber += white ? 0 : 1;
+        white = !white;
+    }
+    tokens.push(record.tags.Result ?? "*");
+    return tokens;
+}
+/** A comment as PGN tokens, cleaned for a record written by hand; none for no comment. */
+function commentTokens(comment) {
+    const text = cleanComment(comment ?? "");
+    return text === "" ? [] : `{${text}}`.split(" ");
+}
+function tagLine(name, value) {
+    return `[${name} "${value.replace(/\s*[\r\n]+\s*/g, " ").replace(/[\\"]/g, "\\$&")}"]`;
+}
+function wrapped(tokens) {
+    const lines = [];
+    let line = "";
+    for (const token of tokens) {
+        if (line !== "" && line.length + 1 + token.length > lineLength) {
+            lines.push(line);
+            line = token;
+        }
+        else {
+            line = line === "" ? token : `${line} ${token}`;
+        }
+    }
+    lines.push(line);
+    return lines.join("\n");
+}

package/dist/core/profile.d.ts

@@ -0,0 +1,117 @@
+import { Chess, type Square } from "chess.js";
+import { type PieceLetter } from "./facts.ts";
+import type { Move, Side } from "./game.ts";
+import { type Material } from "./material.ts";
+/** The pawns of a side, by kind; a pawn may be of several. */
+export interface PawnFacts {
+    /** No pawn of its side on the files beside it. */
+    readonly isolated: readonly Square[];
+    /** Another pawn of its side on its file. */
+    readonly doubled: readonly Square[];
+    /** Pawns of its side beside it, all of them further on, and the square in front of it attacked by an enemy pawn. */
+    readonly backward: readonly Square[];
+    /** No enemy pawn in front of it, on its file or the files beside it. */
+    readonly passed: readonly Square[];
+    /** Groups of neighbouring files with pawns of its side, by their files: "a-b", "d", "f-h". */
+    readonly islands: readonly string[];
+}
+/** A bishop with how many pawns of its side stand on squares of its colour. */
+export interface BishopFacts {
+    readonly square: Square;
+    readonly pawnsOnColour: number;
+    readonly pawns: number;
+}
+/** A square on the side's ranks 4 to 6, defended by its pawn, that no enemy pawn can ever attack and no pawn stands on; with the piece of the side on it. */
+export interface Outpost {
+    readonly square: Square;
+    readonly piece?: PieceLetter;
+}
+/** Around a side's king: its pawns in front of it, the files beside it without a pawn of its side, and how many enemy attacks fall on the squares next to it. */
+export interface KingFacts {
+    readonly square: Square;
+    readonly shield: readonly Square[];
+    readonly openFiles: readonly string[];
+    readonly attacksNear: number;
+}
+/** The profile of one side. */
+export interface SideProfile {
+    readonly pawns: PawnFacts;
+    /** Files with enemy pawns and none of its own. */
+    readonly halfOpenFiles: readonly string[];
+    /** Its rooks and queens on open or half-open files. */
+    readonly heavyOnFiles: readonly Square[];
+    /** Its rooks and queens on the enemy's second rank: the seventh for White, the second for Black. */
+    readonly onSeventh: readonly Square[];
+    readonly bishopPair: boolean;
+    readonly bishops: readonly BishopFacts[];
+    readonly outposts: readonly Outpost[];
+    /** Squares of the other half that one of its pieces attacks. */
+    readonly space: number;
+    /** Its legal moves by piece, as if it were to move; left out for the side not to move when the other is in check. */
+    readonly mobility?: Readonly<Partial<Record<PieceLetter, number>>>;
+    /** Its knights and bishops still on their first squares. */
+    readonly undeveloped: readonly Square[];
+    /** How it castled, or "no"; left out when the game began from a FEN and it has not castled since, which says nothing of before. */
+    readonly castled?: "O-O" | "O-O-O" | "no";
+    readonly castlingRights: readonly ("O-O" | "O-O-O")[];
+    readonly king?: KingFacts;
+}
+/** Who stands on a central square and how many pieces of each side attack it. */
+export interface CentreSquare {
+    readonly square: Square;
+    readonly piece?: {
+        readonly letter: PieceLetter;
+        readonly side: Side;
+    };
+    readonly white: number;
+    readonly black: number;
+}
+/**
+ * The game's phase, by a rule, never a judgment of the position: endgame when the pieces but pawns and kings add up to 26 or less (62 at the start, N and B
+ * 3, R 5, Q 9); opening while they add up to 56 or more, by move 15, and a knight or bishop is still on its first square; middlegame otherwise.
+ */
+export type Phase = "opening" | "middlegame" | "endgame";
+/** A passed pawn of a pawn ending with whether the enemy king is inside its square, the side to move counted. */
+export interface PawnSquare {
+    readonly pawn: Square;
+    readonly caught: boolean;
+}
+/** The profile of a position (D-19): data for the AI and the page, never a judgment. */
+export interface Profile {
+    readonly material: Material;
+    readonly white: SideProfile;
+    readonly black: SideProfile;
+    /** Files without pawns. */
+    readonly openFiles: readonly string[];
+    /** One bishop each, on squares of different colours. */
+    readonly oppositeBishops: boolean;
+    readonly centre: readonly CentreSquare[];
+    /** For each square, how many pieces of each side attack it, as the facts count them (a piece pinned to its king only along the pin): [White, Black]. */
+    readonly control: Readonly<Partial<Record<Square, readonly [number, number]>>>;
+    /** How many squares only White attacks, only Black, and both. */
+    readonly controlled: {
+        readonly white: number;
+        readonly black: number;
+        readonly contested: number;
+    };
+    readonly phase: Phase;
+    /** How many times the position has stood with this side to move, now included; the half-moves left before the fifty-move draw; material too little to mate. */
+    readonly draw: {
+        readonly repetitions: number;
+        readonly fiftyMovesLeft: number;
+        readonly insufficient: boolean;
+    };
+    /** Only kings and pawns: the rule of the square for each passed pawn, and the side that has the opposition, when the kings stand in it. */
+    readonly pawnEnding?: {
+        readonly squares: readonly PawnSquare[];
+        readonly opposition?: Side;
+    };
+}
+/** What the profile needs of the game's past: how many times the position has stood, now included, how each side castled, and whether it began from a FEN. */
+export interface Past {
+    readonly repetitions: number;
+    readonly castled: Readonly<Partial<Record<Side, "O-O" | "O-O-O">>>;
+    readonly fromFen: boolean;
+}
+/** The profile of a chess.js board and its game's past: computed once for each position and past, and frozen. */
+export declare function profileOf(chess: Chess, past: Past, legal: readonly Move[]): Profile;

package/dist/core/profile.js

@@ -0,0 +1,232 @@
+// The positional profile (D-19): pawns, files, bishops, outposts, space and centre, mobility, development, king safety, control, phase, draws and
+// the geometry of pawn endings, each a separate fact; never weighed, never summed.
+import { Chess } from "chess.js";
+import { attacksOf, fileOf, rankOf } from "./facts.js";
+import { materialOf } from "./material.js";
+/** The profile of a chess.js board and its game's past: computed once for each position and past, and frozen. */
+export function profileOf(chess, past, legal) {
+    // The FEN, not the hash: the fifty-move count and the move number are facts of the profile too.
+    const key = `${chess.fen()} ${past.repetitions} ${past.castled.white ?? ""} ${past.castled.black ?? ""} ${past.fromFen}`;
+    let profile = profileByPosition.get(key);
+    if (profile === undefined) {
+        profile = deepFrozen(computed(chess, past.repetitions, { w: castledOf(past, "white"), b: castledOf(past, "black") }, legal));
+        if (profileByPosition.size >= positionsKept) {
+            profileByPosition.delete(profileByPosition.keys().next().value);
+        }
+        profileByPosition.set(key, profile);
+    }
+    return profile;
+}
+const profileByPosition = new Map();
+const positionsKept = 256;
+const files = "abcdefgh";
+const allSquares = [..."abcdefgh"].flatMap((file) => [1, 2, 3, 4, 5, 6, 7, 8].map((rank) => `${file}${rank}`));
+const centreSquares = ["d4", "e4", "d5", "e5"];
+const pieceValues = { p: 0, n: 3, b: 3, r: 5, q: 9, k: 0 };
+const firstSquares = {
+    w: [["b1", "n"], ["g1", "n"], ["c1", "b"], ["f1", "b"]],
+    b: [["b8", "n"], ["g8", "n"], ["c8", "b"], ["f8", "b"]],
+};
+function computed(chess, repetitions, castled, legal) {
+    const placed = chess.board().flat().filter((cell) => cell !== null).map(({ square, type, color }) => ({ square, type, color }));
+    const attackers = attacksOf(chess);
+    const control = Object.fromEntries(allSquares.map((square) => [square, [attackers(square, "w").length, attackers(square, "b").length]]));
+    const pawnsOn = (color, file) => placed.filter((piece) => piece.type === "p" && piece.color === color && fileOf(piece.square) === file);
+    const openFiles = [...files].filter((_, file) => pawnsOn("w", file).length === 0 && pawnsOn("b", file).length === 0);
+    const bishops = placed.filter((piece) => piece.type === "b");
+    const onlyKingsAndPawns = placed.every((piece) => piece.type === "k" || piece.type === "p");
+    const mobility = mobilityOf(chess, legal);
+    const side = (color) => sideProfile(chess, color, placed, control, castled[color], mobility[color]);
+    const counts = allSquares.map((square) => control[square]);
+    const endingFacts = onlyKingsAndPawns ? pawnEnding(chess, placed) : undefined;
+    return {
+        material: materialOf(chess.fen()),
+        white: side("w"),
+        black: side("b"),
+        openFiles,
+        oppositeBishops: bishops.length === 2 && bishops[0].color !== bishops[1].color && squareColour(bishops[0].square) !== squareColour(bishops[1].square),
+        centre: centreSquares.map((square) => centreSquare(chess, square, control[square])),
+        control,
+        controlled: {
+            white: counts.filter(([white, black]) => white > 0 && black === 0).length,
+            black: counts.filter(([white, black]) => black > 0 && white === 0).length,
+            contested: counts.filter(([white, black]) => white > 0 && black > 0).length,
+        },
+        phase: phaseOf(chess, placed),
+        draw: { repetitions, fiftyMovesLeft: Math.max(0, 100 - Number(chess.fen().split(" ")[4])), insufficient: chess.isInsufficientMaterial() },
+        ...(endingFacts === undefined ? {} : { pawnEnding: endingFacts }),
+    };
+}
+function sideProfile(chess, color, placed, control, castled, mobility) {
+    const enemy = color === "w" ? "b" : "w";
+    const mine = placed.filter((piece) => piece.color === color);
+    const pawns = mine.filter((piece) => piece.type === "p");
+    const enemyPawns = placed.filter((piece) => piece.type === "p" && piece.color === enemy);
+    const hasPawn = (list, file) => list.some((pawn) => fileOf(pawn.square) === file);
+    const halfOpenFiles = [...files].filter((_, file) => !hasPawn(pawns, file) && hasPawn(enemyPawns, file));
+    const bishops = mine.filter((piece) => piece.type === "b");
+    const otherHalf = allSquares.filter((square) => (color === "w" ? rankOf(square) >= 5 : rankOf(square) <= 4));
+    const index = color === "w" ? 0 : 1;
+    const rights = chess.getCastlingRights(color);
+    const king = mine.find((piece) => piece.type === "k");
+    return {
+        pawns: pawnFacts(color, pawns, enemyPawns),
+        halfOpenFiles,
+        heavyOnFiles: mine.filter((piece) => (piece.type === "r" || piece.type === "q") && !hasPawn(pawns, fileOf(piece.square))).map((piece) => piece.square).sort(),
+        onSeventh: mine.filter((piece) => (piece.type === "r" || piece.type === "q") && rankOf(piece.square) === (color === "w" ? 7 : 2)).map((piece) => piece.square).sort(),
+        bishopPair: bishops.length >= 2 && new Set(bishops.map((bishop) => squareColour(bishop.square))).size === 2,
+        bishops: bishops.map((bishop) => ({
+            square: bishop.square,
+            pawnsOnColour: pawns.filter((pawn) => squareColour(pawn.square) === squareColour(bishop.square)).length,
+            pawns: pawns.length,
+        })),
+        outposts: outpostsOf(chess, color, pawns, enemyPawns),
+        space: otherHalf.filter((square) => control[square][index] > 0).length,
+        ...(mobility === undefined ? {} : { mobility }),
+        undeveloped: firstSquares[color].filter(([square, type]) => chess.get(square)?.type === type && chess.get(square)?.color === color).map(([square]) => square),
+        ...(castled === undefined ? {} : { castled }),
+        castlingRights: [...(rights.k ? ["O-O"] : []), ...(rights.q ? ["O-O-O"] : [])],
+        ...(king === undefined ? {} : { king: kingFacts(king.square, color, pawns, control) }),
+    };
+}
+function pawnFacts(color, pawns, enemyPawns) {
+    const forward = color === "w" ? 1 : -1;
+    const ahead = (from, other) => (rankOf(other) - rankOf(from)) * forward > 0;
+    const besides = (pawn) => pawns.filter((other) => Math.abs(fileOf(other.square) - fileOf(pawn.square)) === 1);
+    const stopAttacked = (pawn) => enemyPawns.some((enemy) => Math.abs(fileOf(enemy.square) - fileOf(pawn.square)) === 1 && rankOf(enemy.square) === rankOf(pawn.square) + 2 * forward);
+    const usedFiles = [...new Set(pawns.map((pawn) => fileOf(pawn.square)))].sort();
+    const sorted = (list) => list.map((pawn) => pawn.square).sort();
+    return {
+        isolated: sorted(pawns.filter((pawn) => besides(pawn).length === 0)),
+        doubled: sorted(pawns.filter((pawn) => pawns.some((other) => other !== pawn && fileOf(other.square) === fileOf(pawn.square)))),
+        backward: sorted(pawns.filter((pawn) => besides(pawn).length > 0 && besides(pawn).every((other) => ahead(pawn.square, other.square)) && stopAttacked(pawn))),
+        passed: sorted(pawns.filter((pawn) => !enemyPawns.some((enemy) => Math.abs(fileOf(enemy.square) - fileOf(pawn.square)) <= 1 && ahead(pawn.square, enemy.square)))),
+        islands: islandsOf(usedFiles),
+    };
+}
+/** The pawn islands, from the files with pawns in order: neighbouring files make one, named by its first and last file. */
+function islandsOf(usedFiles) {
+    const islands = [];
+    for (const file of usedFiles) {
+        const last = islands.at(-1);
+        if (last !== undefined && last.at(-1) === file - 1) {
+            last.push(file);
+        }
+        else {
+            islands.push([file]);
+        }
+    }
+    return islands.map((island) => (island.length === 1 ? files[island[0]] : `${files[island[0]]}-${files[island.at(-1)]}`));
+}
+/** The outposts of a side: on ranks 4 to 6 as it sees the board, defended by its pawn, out of reach of every enemy pawn, not under one of its pawns. */
+function outpostsOf(chess, color, pawns, enemyPawns) {
+    const forward = color === "w" ? 1 : -1;
+    const ranks = color === "w" ? [4, 5, 6] : [5, 4, 3];
+    return allSquares.filter((square) => {
+        const file = fileOf(square);
+        const rank = rankOf(square);
+        const defended = pawns.some((pawn) => Math.abs(fileOf(pawn.square) - file) === 1 && rankOf(pawn.square) === rank - forward);
+        const reachable = enemyPawns.some((enemy) => Math.abs(fileOf(enemy.square) - file) === 1 && (rankOf(enemy.square) - rank) * forward > 0);
+        const own = chess.get(square);
+        return ranks.includes(rank) && defended && !reachable && own?.type !== "p";
+    }).map((square) => {
+        const piece = chess.get(square);
+        return piece?.color === color ? { square, piece: piece.type.toUpperCase() } : { square };
+    });
+}
+function kingFacts(square, color, pawns, control) {
+    const forward = color === "w" ? 1 : -1;
+    const file = fileOf(square);
+    const near = [file - 1, file, file + 1].filter((other) => other >= 0 && other < 8);
+    const enemy = color === "w" ? 1 : 0;
+    const around = allSquares.filter((other) => other !== square && Math.abs(fileOf(other) - file) <= 1 && Math.abs(rankOf(other) - rankOf(square)) <= 1);
+    return {
+        square,
+        shield: pawns.filter((pawn) => near.includes(fileOf(pawn.square)) && [1, 2].includes((rankOf(pawn.square) - rankOf(square)) * forward)).map((pawn) => pawn.square).sort(),
+        openFiles: near.filter((other) => !pawns.some((pawn) => fileOf(pawn.square) === other && (rankOf(pawn.square) - rankOf(square)) * forward > 0))
+            .map((other) => files[other]),
+        attacksNear: around.reduce((sum, other) => sum + control[other][enemy], 0),
+    };
+}
+/** The legal moves of each side by piece: the side to move's, and the other's on the same board with the turn passed, unless the side to move is in check. */
+function mobilityOf(chess, legal) {
+    const byPiece = (letters) => {
+        const counts = {};
+        for (const letter of letters) {
+            counts[letter] = (counts[letter] ?? 0) + 1;
+        }
+        return counts;
+    };
+    const turn = chess.turn();
+    // A promotion is one move, whatever the pawn becomes.
+    const mine = byPiece(legal.filter((move) => move.promotion === undefined || move.promotion === "q").map((move) => chess.get(move.from).type.toUpperCase()));
+    if (chess.inCheck()) {
+        return { [turn]: mine };
+    }
+    const fields = chess.fen().split(" ");
+    fields[1] = turn === "w" ? "b" : "w";
+    fields[3] = "-";
+    // A SAN names its piece first, castling is the king's, and a pawn's move starts with its file.
+    const letterOf = (san) => (san.startsWith("O-O") ? "K" : /^[KQRBN]/.test(san) ? san[0] : "P");
+    return { [turn]: mine, [fields[1]]: byPiece(new Chess(fields.join(" ")).moves().filter((san) => !/=[RBN]/.test(san)).map(letterOf)) };
+}
+function centreSquare(chess, square, [white, black]) {
+    const piece = chess.get(square);
+    return piece === undefined ? { square, white, black } : { square, piece: { letter: piece.type.toUpperCase(), side: piece.color === "w" ? "white" : "black" }, white, black };
+}
+function phaseOf(chess, placed) {
+    const material = placed.reduce((sum, piece) => sum + pieceValues[piece.type], 0);
+    if (material <= 26) {
+        return "endgame";
+    }
+    const undeveloped = ["w", "b"].some((color) => firstSquares[color].some(([square, type]) => chess.get(square)?.type === type && chess.get(square)?.color === color));
+    return material >= 56 && chess.moveNumber() <= 15 && undeveloped ? "opening" : "middlegame";
+}
+/** The rule of the square for each passed pawn, and the opposition of the kings: on one file, rank or diagonal, an odd number of squares between them. */
+function pawnEnding(chess, placed) {
+    const kings = placed.filter((piece) => piece.type === "k");
+    const kingOf = (color) => kings.find((king) => king.color === color)?.square;
+    const squares = [];
+    for (const color of ["w", "b"]) {
+        const pawns = placed.filter((piece) => piece.type === "p" && piece.color === color);
+        const enemyPawns = placed.filter((piece) => piece.type === "p" && piece.color !== color);
+        const defender = kingOf(color === "w" ? "b" : "w");
+        for (const pawn of pawnFacts(color, pawns, enemyPawns).passed) {
+            const promotion = `${pawn[0]}${color === "w" ? 8 : 1}`;
+            // From its first square a pawn steps two: it is as far as from the next one.
+            const steps = Math.min(5, Math.abs((color === "w" ? 8 : 1) - rankOf(pawn)));
+            // The king takes the new queen on its square: one move more when it is the defender's turn.
+            const reach = steps + (chess.turn() === color ? 0 : 1);
+            if (defender !== undefined) {
+                squares.push({ pawn, caught: distance(defender, promotion) <= reach });
+            }
+        }
+    }
+    const white = kingOf("w");
+    const black = kingOf("b");
+    const opposition = white === undefined || black === undefined ? undefined : oppositionOf(white, black, chess.turn());
+    return opposition === undefined ? { squares } : { squares, opposition };
+}
+/** The side that has the opposition: the one not to move, when the kings stand on one line with an odd number of squares between them. */
+function oppositionOf(white, black, turn) {
+    const files = Math.abs(fileOf(white) - fileOf(black));
+    const ranks = Math.abs(rankOf(white) - rankOf(black));
+    const between = files === 0 ? ranks - 1 : ranks === 0 ? files - 1 : files === ranks ? files - 1 : -1;
+    return between > 0 && between % 2 === 1 ? (turn === "w" ? "black" : "white") : undefined;
+}
+function castledOf(past, side) {
+    return past.castled[side] ?? (past.fromFen ? undefined : "no");
+}
+function squareColour(square) {
+    return (fileOf(square) + rankOf(square)) % 2;
+}
+function distance(from, to) {
+    return Math.max(Math.abs(fileOf(from) - fileOf(to)), Math.abs(rankOf(from) - rankOf(to)));
+}
+function deepFrozen(value) {
+    if (typeof value === "object" && value !== null) {
+        Object.values(value).forEach(deepFrozen);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/core/record.d.ts

@@ -0,0 +1,21 @@
+/** A judgment on a move: NAGs ($1 good move, $2 mistake, $3 brilliant…) and a comment. */
+export interface Annotation {
+    readonly nags?: readonly number[];
+    readonly comment?: string;
+}
+/** A move of a recorded game: its SAN and its judgment. */
+export interface RecordedMove extends Annotation {
+    readonly san: string;
+}
+/** A game as plain data: its PGN tags (a FEN tag when it starts from another position), the comment before its first move, its moves. */
+export interface GameRecord {
+    readonly tags: Readonly<Record<string, string>>;
+    readonly comment?: string;
+    readonly moves: readonly RecordedMove[];
+}
+/** The game with its tags and moves alone, without comments, plans or judgments: for Lichess or chess.com to load. */
+export declare function movesOnly(record: GameRecord): GameRecord;
+/** A recorded move, frozen, with only the annotations it has. */
+export declare function recordedMove(san: string, nags?: readonly number[], comment?: string): RecordedMove;
+/** A comment as PGN can hold it: on one line, without a closing brace. */
+export declare function cleanComment(text: string): string;

package/dist/core/record.js

@@ -0,0 +1,25 @@
+// A game as plain data: the form it takes on disk (D-27) and in a PGN.
+/** The game with its tags and moves alone, without comments, plans or judgments: for Lichess or chess.com to load. */
+export function movesOnly(record) {
+    return { tags: record.tags, moves: record.moves.map((move) => ({ san: move.san })) };
+}
+/** A recorded move, frozen, with only the annotations it has. */
+export function recordedMove(san, nags = [], comment = "") {
+    const wrong = nags.find((nag) => !Number.isInteger(nag) || nag < 0 || nag > 255);
+    if (wrong !== undefined) {
+        throw new RangeError(`${wrong} is not a NAG: NAGs are whole numbers from 0 to 255.`);
+    }
+    const text = cleanComment(comment);
+    const move = { san };
+    if (nags.length > 0) {
+        move.nags = Object.freeze([...nags]);
+    }
+    if (text !== "") {
+        move.comment = text;
+    }
+    return Object.freeze(move);
+}
+/** A comment as PGN can hold it: on one line, without a closing brace. */
+export function cleanComment(text) {
+    return text.replaceAll("}", "").replace(/\s+/g, " ").trim();
+}