chesspal 0.3.6 → 0.4.0

package/dist/commands/game/player-move.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
-import { loadGame } from "../../games/index.js";
+import { withSanPieces } from "../../core/index.js";
+import { endOf, gameStamp, loadGame, rerunIfChanged } from "../../games/index.js";
+import { hasDoorbell } from "../../host-files/index.js";
 import { gameFolder } from "../../profiles/index.js";
 import { closingLines, coachOnEnd, coachOnEndLine, coachRuns, lastMoveText, moveLines, newWords, playMove, positionIn, refuseUnseenPosition, shownMove, withAnalyst } from "../answers/index.js";
 import { defineCommand } from "../registry/index.js";
@@ -17,30 +19,78 @@ export const playerMove = defineCommand({
     alwaysLoad: true,
     showsGame: true,
     positionals: ["move"],
-    run: ({ move, offer_draw: offerDraw = false }, context) => {
-        const folder = gameFolder(context.home());
-        // A chat that has seen no game yet, new or resumed, plays the player's own move: its answer shows the game the AI decides on (D-71).
-        if (context.positionSeen !== null) {
-            refuseUnseenPosition(context, folder);
-        }
-        const started = context.positionSeen === null ? positionIn(folder).started : context.positionSeen?.started;
-        const played = playMove(folder, context.now(), "player", move, (message) => `${message} Ask the player again. Nothing changed.`, { allowance: chatAllowance, offerDraw, coached: coachRuns(context) });
-        // A game over by this move has no more moves to play there: the next game's window gives the address (Federico, round of D-85).
-        const invite = played.game.end === undefined ? pageInvite(context, started) : undefined;
-        const ended = played.game.end === undefined ? undefined : loadGame(folder);
-        const coach = ended !== undefined && coachOnEnd(context, folder, ended);
-        return { ...played, game: withAnalyst(played.game, context), words: newWords(context), ...(invite === undefined ? {} : { invite }), ...(coach ? { coach } : {}) };
-    },
-    format: (result) => [
+    run: (input, context) => playersMove(input, context, chatAllowance),
+    format: (result, context) => [
         `Player: ${result.game.lastMove === undefined ? shownMove(result.move) : lastMoveText(result.game.lastMove)}.`,
         ...moveLines(result),
         ...(result.invite === undefined ? [] : [inviteLine(result.invite)]),
-        ...(result.coach === true ? [coachOnEndLine] : []),
-        ...closingLines(result.game, result.words),
+        ...(result.coach === true ? [coachOnEndLine(result.game)] : []),
+        ...closingLines(result.game, result.words, false, hasDoorbell(context?.host?.())),
     ].join("\n"),
 });
+/**
+ * Plays the move the player sent alone in the chat, before the AI reads it (D-36): at the moment they sent it, so with no allowance, and answered as
+ * player_move answers, with the player's words on the board page the AI has not answered. Refused as player_move refuses it: the AI reads the prompt then.
+ */
+export function playMoveSentAlone(move, context) {
+    const folder = gameFolder(context.home());
+    const before = new Set(context.given);
+    const played = rerunIfChanged(() => playersMove({ move }, context, 0));
+    const stamp = gameStamp(folder);
+    return {
+        answer: `Chesspal has already played the move the player wrote alone in the chat: don't call player_move for it.\n${playerMove.format(played, context)}`,
+        position: positionIn(folder),
+        ...(stamp === undefined ? {} : { stamp }),
+        given: [...context.given].filter((key) => !before.has(key)),
+    };
+}
 /**
  * The time a move in the chat leaves off the player's clock (D-36): the AI writing after its move and reading the player's, about 10 s as Priya measured.
- * Claude Code's hooks will time it exactly; the board page's moves need none.
+ * The board page's moves need none, nor those Chesspal plays as the player sends them.
  */
 const chatAllowance = 10_000;
+function playersMove({ move, offer_draw: offerDraw = false }, context, allowance) {
+    const folder = gameFolder(context.home());
+    // A chat that has seen no game yet, new or resumed, plays the player's own move: its answer shows the game the AI decides on (D-71).
+    if (context.positionSeen !== null) {
+        refuseUnseenPosition(context, folder);
+    }
+    refuseKingAsRook(move, folder);
+    // A piece's letter of another language is read as SAN's (D-113): Cf3 is the knight's move, Tf1 the rook's.
+    const read = withSanPieces(move);
+    const readAs = read === move ? "" : `${move.trim()} is read as ${read.trim()}. `;
+    const started = context.positionSeen === null ? positionIn(folder).started : context.positionSeen?.started;
+    const played = playMove(folder, context.now(), "player", read, (message) => `${readAs}${message} Ask the player again. Nothing changed.`, { allowance, offerDraw, coached: coachRuns(context) });
+    // A game over by this move has no more moves to play there: the next game's window gives the address (Federico, round of D-85).
+    const invite = played.game.end === undefined ? pageInvite(context, started) : undefined;
+    const ended = played.game.end === undefined ? undefined : loadGame(folder);
+    const coach = ended !== undefined && coachOnEnd(context, folder, ended);
+    return { ...played, game: withAnalyst(played.game, context), words: newWords(context), ...(invite === undefined ? {} : { invite }), ...(coach ? { coach } : {}) };
+}
+/**
+ * Refuses a move written R and a square when the player's king could go there: R is the king in Italian, French and Spanish, and only the player's words
+ * tell which. A rook's move that names its file or rank, or given as squares, is never the king's.
+ */
+function refuseKingAsRook(move, folder) {
+    const written = move.trim().replace(/^\d+\s*(?:\.[\s.]*|…\s*)/, "").replace(/\s+/g, "");
+    const target = /^[Rr][x:]?([a-h][1-8])[+#]*[!?]*$/.exec(written)?.[1];
+    const current = target === undefined ? undefined : loadGame(folder);
+    // Another side to move, or a game over, is refused by the move itself.
+    if (current === undefined || current.game.position.turn === current.ai || endOf(current.game) !== undefined) {
+        return;
+    }
+    const there = current.game.legalMoves().filter((legal) => legal.to === target);
+    const rooks = there.filter((legal) => legal.san.startsWith("R")).map(squaresOf);
+    const king = there.find((legal) => legal.san.startsWith("K"));
+    if (rooks.length > 0 && king !== undefined) {
+        throw new Error(`${written} may be the rook's move, ${rooks.join(" or ")}, or the king's, ${squaresOf(king)}: R is the king in Italian, French and Spanish. `
+            + "Unless the player's words name the piece, ask them which; then give it as squares. Nothing changed.");
+    }
+    if (rooks.length === 0 && king !== undefined) {
+        throw new Error(`${written} is not legal: R is the rook in SAN, and no rook can go to ${target}. The king can, ${king.san}, and R is the king in Italian, French and Spanish: `
+            + `ask the player whether they meant the king, and give ${king.san} only once they say so. Nothing changed.`);
+    }
+}
+function squaresOf(move) {
+    return `${move.from}${move.to}`;
+}

package/dist/commands/game/ponder.js

@@ -26,7 +26,10 @@ export const ponder = defineCommand({
     }),
     byAgents: ponderAgents,
     hosts: agentHosts,
-    run: async ({ position, reply, move, why, say, done = false }, context) => {
+    run: async (input, context) => {
+        const { reply, move, why, say, done = false } = input;
+        // A quick model writes ponder {} as ponder {position: 0}, and was told to stop: alone, it asks for the position too (Priya).
+        const position = input.position === 0 && Object.keys(input).length === 1 ? undefined : input.position;
         const folder = gameFolder(context.home());
         const current = toPonder(folder, context.now(), position);
         if (current === undefined) {

package/dist/commands/game/status.d.ts

@@ -27,7 +27,7 @@ interface Status {
     };
     /** A game going on from before this chat, told once a chat: the player says whether to go on with it. */
     fromBefore?: true;
-    /** The coach to start, once, for the player's move that ended the game (D-88). */
+    /** The coach to start, once a move ended the game, for the player's last move (D-88). */
     coach?: true;
     /** The files an older init wrote in the player's folder, which this version would write otherwise. */
     outdated?: string[];

package/dist/commands/game/status.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { Game, gameReviewOf, leadOf, reviewOf } from "../../core/index.js";
 import { archivedName, cleanSince, endOf, gameInAnalysis, lastChatStart } from "../../games/index.js";
-import { isCodex, outdatedHostFiles } from "../../host-files/index.js";
+import { hasDoorbell, isCodex, outdatedHostFiles } from "../../host-files/index.js";
 import { gameFolder } from "../../profiles/index.js";
 import { version } from "../../version.js";
 import { analystLine, analystRuns, closingLines, coachOnEnd, coachOnEndLine, coachRuns, gameAt, goneOver, namedGame, newGameStep, positionLines, reviewedLine, shownMoves, sidesLine, speechLine, speechOf, summaryOf, unansweredWords, withAnalyst, withThought, wordLines, } from "../answers/index.js";
@@ -56,7 +56,7 @@ export const status = defineCommand({
                 if (first && endOf(current.game) === undefined && current.game.record.moves.length > 0 && (chatStart === undefined || cleanSince(chatStart, current.started))) {
                     status.fromBefore = true;
                 }
-                // The player's move on the board page that ended the game: the coach judges it too (D-88).
+                // A move that ended the game: the coach judges the player's last move, told until it starts (D-88).
                 if (coachOnEnd(context, folder, current)) {
                     status.coach = true;
                 }
@@ -80,7 +80,7 @@ export const status = defineCommand({
         }
         return status;
     },
-    format: ({ version, folder, page, pageClosed, player, speech, game, problem, words = [], analysis, fromBefore, coach, outdated, unread }) => [
+    format: ({ version, folder, page, pageClosed, player, speech, game, problem, words = [], analysis, fromBefore, coach, outdated, unread }, context) => [
         `Chesspal ${version}. Folder: ${folder}`,
         ...(unread === true ? [unreadLine] : []),
         ...(outdated === undefined ? [] : [outdatedLine(outdated)]),
@@ -88,7 +88,7 @@ export const status = defineCommand({
         ...(player === undefined ? [] : [player]),
         ...(speech === undefined ? [] : [speechLine(speech)]),
         ...(fromBefore === true ? [fromBeforeLine] : []),
-        ...(problem !== undefined ? [problem] : gameLines(game, words, analysis?.brought === true, pageClosed === true, coach === true)),
+        ...(problem !== undefined ? [problem] : gameLines(game, words, analysis?.brought === true, pageClosed === true, coach === true, hasDoorbell(context?.host?.()))),
         ...(analysis === undefined ? [] : [analysisLine(analysis)]),
     ].join("\n"),
 });
@@ -166,8 +166,8 @@ function reviewProgress(context, game) {
  * The game's lines; a game the player brought to analyse takes the place of the next step. The coach to start goes just before the next step, where
  * the AI acts on it (Priya).
  */
-function gameLines(game, words, brought, pageClosed, coach) {
-    const closing = [...(coach ? [coachOnEndLine] : []), ...(brought ? wordLines(words) : closingLines(game, words, pageClosed))];
+function gameLines(game, words, brought, pageClosed, coach, doorbell) {
+    const closing = [...(coach && game !== undefined ? [coachOnEndLine(game)] : []), ...(brought ? wordLines(words) : closingLines(game, words, pageClosed, doorbell))];
     if (game === undefined) {
         return ["No game.", ...closing];
     }

package/dist/commands/index.d.ts

@@ -1,8 +1,8 @@
 import type { AnyCommand } from "./registry/index.ts";
 export { analyseGame, deleteReview, siteGames, SiteGamesRefused } from "./analysis/index.ts";
-export { analystOf, bookOpening, bookPlies, gameAt, gameToStudy, namedGame, playMove, PositionChanged, positionIn, samePosition, say, shownPosition } from "./answers/index.ts";
-export { aiMove, answerDraw, ChatNotClear, DrawRefused, endGame, newGame, offerDraw, startNewGame } from "./game/index.ts";
+export { analystOf, analystQuietAt, bookOpening, bookPlies, gameAt, gameToStudy, namedGame, playMove, PositionChanged, positionIn, samePosition, say, shownPosition } from "./answers/index.ts";
+export { aiMove, answerDraw, ChatNotClear, DrawRefused, endGame, type MoveSentAlone, newGame, offerDraw, playMoveSentAlone, startNewGame } from "./game/index.ts";
 export { chooseDrawnAvatar, deleteGame, editProfile, GameGoingOn, newProfile, ratingsAge, refreshRatings, useProfile } from "./profiles/index.ts";
-export { type AnyCommand, baseType, type Caller, type Command, commandLineFieldProblem, type Context, defaultContext, inputProblems, isBoolean, isList, type SeenPosition, speaksItalian, takesNumbers } from "./registry/index.ts";
+export { type AnyCommand, baseType, type Caller, type Command, commandLineFieldProblem, type Context, defaultContext, homeForOneCall, inputProblems, isBoolean, isList, type SeenPosition, speaksItalian, takesNumbers, } from "./registry/index.ts";
 /** Every command of Chesspal, in the order the command line lists them and the MCP server offers them. */
 export declare const commands: AnyCommand[];

package/dist/commands/index.js

@@ -6,10 +6,10 @@ import { init, instructions } from "./setup/index.js";
 import { aiSay, playerSay } from "./talk/index.js";
 // What the server and the command line use besides the list: the context, the reading of an input, and the operations the page shares with the tools.
 export { analyseGame, deleteReview, siteGames, SiteGamesRefused } from "./analysis/index.js";
-export { analystOf, bookOpening, bookPlies, gameAt, gameToStudy, namedGame, playMove, PositionChanged, positionIn, samePosition, say, shownPosition } from "./answers/index.js";
-export { aiMove, answerDraw, ChatNotClear, DrawRefused, endGame, newGame, offerDraw, startNewGame } from "./game/index.js";
+export { analystOf, analystQuietAt, bookOpening, bookPlies, gameAt, gameToStudy, namedGame, playMove, PositionChanged, positionIn, samePosition, say, shownPosition } from "./answers/index.js";
+export { aiMove, answerDraw, ChatNotClear, DrawRefused, endGame, newGame, offerDraw, playMoveSentAlone, startNewGame } from "./game/index.js";
 export { chooseDrawnAvatar, deleteGame, editProfile, GameGoingOn, newProfile, ratingsAge, refreshRatings, useProfile } from "./profiles/index.js";
-export { baseType, commandLineFieldProblem, defaultContext, inputProblems, isBoolean, isList, speaksItalian, takesNumbers } from "./registry/index.js";
+export { baseType, commandLineFieldProblem, defaultContext, homeForOneCall, inputProblems, isBoolean, isList, speaksItalian, takesNumbers, } from "./registry/index.js";
 /** Every command of Chesspal, in the order the command line lists them and the MCP server offers them. */
 export const commands = [
     init,

package/dist/commands/profiles/past-games.d.ts

@@ -11,6 +11,6 @@ export declare const pastGames: import("../registry/registry.ts").Command<z.ZodO
 }>;
 /**
  * The latest games of the archive, one line each as the AI reads them, those holding every word searched: none when there is no archive. A game closed
- * before any move is no game played.
+ * before any move is no game played. A game is read from its tags alone when the archive wrote the opening's and the plies', or else whole.
  */
 export declare function pastGameLines(folder: string, count: number, search?: string): string[];

package/dist/commands/profiles/past-games.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { writePgn } from "../../core/index.js";
-import { archivedGame, archivedGames, archivedWhen } from "../../games/index.js";
+import { archivedGame, archivedGames, archivedTags, archivedWhen, hasListTags } from "../../games/index.js";
 import { gameFolder } from "../../profiles/index.js";
 import { openingName } from "../answers/index.js";
 import { defineCommand } from "../registry/index.js";
@@ -30,7 +30,7 @@ export const pastGames = defineCommand({
 });
 /**
  * The latest games of the archive, one line each as the AI reads them, those holding every word searched: none when there is no archive. A game closed
- * before any move is no game played.
+ * before any move is no game played. A game is read from its tags alone when the archive wrote the opening's and the plies', or else whole.
  */
 export function pastGameLines(folder, count, search = "") {
     const words = search.toLowerCase().split(/\s+/).filter((word) => word !== "");
@@ -40,8 +40,7 @@ export function pastGameLines(folder, count, search = "") {
             break;
         }
         try {
-            const record = archivedGame(folder, name);
-            const line = record.moves.length > 0 ? pastGameLine(name, record) : undefined;
+            const line = pastGameLine(folder, name);
             // The ending names the player's colour too, as "(Black resigns)": a colour searched is the AI's alone.
             const searched = line?.replace(/ \((?:White|Black) [^)]*\)/, "").toLowerCase();
             if (line !== undefined && words.every((word) => searched.includes(word))) {
@@ -55,14 +54,26 @@ export function pastGameLines(folder, count, search = "") {
     return lines;
 }
 const listed = 20;
+/** A game's line, from its tags when they say all of it, or else from the whole game: none for a game closed before any move. */
+function pastGameLine(folder, name) {
+    const tags = archivedTags(folder, name);
+    const { ECO: eco, Opening: opening, PlyCount: plies } = tags;
+    if (hasListTags(tags)) {
+        return lineOf(name, tags, Number(plies), eco === undefined || opening === undefined ? undefined : `${eco} ${opening}`);
+    }
+    const record = archivedGame(folder, name);
+    return lineOf(name, record.tags, record.moves.length, openingName(record));
+}
 /** 2026-11-03 12:04, you (AI) played Black and won 0-1 (White resigns), B50 Sicilian Defense, 15 moves. games/2026-11-03-120423.pgn */
-function pastGameLine(name, record) {
-    const ai = record.tags.Black === "AI" ? "black" : "white";
-    const result = record.tags.Result ?? "*";
+function lineOf(name, tags, plies, opening) {
+    if (plies === 0) {
+        return undefined;
+    }
+    const ai = tags.Black === "AI" ? "black" : "white";
+    const result = tags.Result ?? "*";
     const outcome = result === "*" ? ", unfinished" : ` and ${resultFor(result, ai)} ${result}`;
-    const termination = record.tags.Termination === undefined || result === "*" ? "" : ` (${record.tags.Termination})`;
-    const opening = openingName(record);
-    const moves = Math.ceil(record.moves.length / 2);
+    const termination = tags.Termination === undefined || result === "*" ? "" : ` (${tags.Termination})`;
+    const moves = Math.ceil(plies / 2);
     return `${archivedWhen(name)}, you (AI) played ${ai === "white" ? "White" : "Black"}${outcome}${termination}${opening === undefined ? "" : `, ${opening}`}, ${moves} moves. ${name}`;
 }
 function resultFor(result, ai) {

package/dist/commands/registry/context.d.ts

@@ -74,6 +74,8 @@ export interface SeenPosition {
 }
 /** The context of a process started in the player's folder: the data folder is found at the first command that needs it, once. */
 export declare function defaultContext(): Context;
+/** The data folder for one tool call: looked for, its profile made when missing, at its first use in the call alone; the next call looks again. */
+export declare function homeForOneCall(context: Context): () => string;
 /** Whether the player's language is Italian: the command line speaks Italian to them then, English otherwise (D-32). */
 export declare function speaksItalian(language: string | undefined): boolean;
 /** A data folder with a profile in it, the first made when there is none, named after the system's account (D-71). */

package/dist/commands/registry/context.js

@@ -18,6 +18,11 @@ export function defaultContext() {
         fetch: globalThis.fetch,
     };
 }
+/** The data folder for one tool call: looked for, its profile made when missing, at its first use in the call alone; the next call looks again. */
+export function homeForOneCall(context) {
+    let found;
+    return () => (found ??= context.home());
+}
 /** Whether the player's language is Italian: the command line speaks Italian to them then, English otherwise (D-32). */
 export function speaksItalian(language) {
     return language?.slice(0, 2).toLowerCase() === "it";

package/dist/commands/registry/index.d.ts

@@ -1,2 +1,2 @@
-export { type Caller, type Context, defaultContext, type SeenPosition, speaksItalian } from "./context.ts";
+export { type Caller, type Context, defaultContext, homeForOneCall, type SeenPosition, speaksItalian } from "./context.ts";
 export { type AnyCommand, baseType, type Command, commandLineFieldProblem, defineCommand, inputProblems, isBoolean, isList, sentence, takesNumbers } from "./registry.ts";

package/dist/commands/registry/index.js

@@ -1,3 +1,3 @@
 // What a command is and what it runs with: the definition and the reading of its input, and the context of folders, time and randomness.
-export { defaultContext, speaksItalian } from "./context.js";
+export { defaultContext, homeForOneCall, speaksItalian } from "./context.js";
 export { baseType, commandLineFieldProblem, defineCommand, inputProblems, isBoolean, isList, sentence, takesNumbers } from "./registry.js";

package/dist/commands/talk/ai-say.d.ts

@@ -4,7 +4,7 @@ interface Said {
     /** The game, none when the AI spoke before the first (D-77). */
     game?: GameSummary;
     words: Written[];
-    /** The coach yet to start on the player's move that ended the game (D-88). */
+    /** The coach yet to start once a move ended the game (D-88). */
     coach?: true;
 }
 /** The AI's words on the board page without a move, read only there, on the player's time: an answer, or a word it has to say (D-54, D-72). */

package/dist/commands/talk/ai-say.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { moods } from "../../core/index.js";
 import { archivedName, talkLimits } from "../../games/index.js";
+import { hasDoorbell } from "../../host-files/index.js";
 import { gameFolder } from "../../profiles/index.js";
 import { analystLine, coachOnEnd, coachOnEndLine, give, newGameStep, nextStep, refuseOtherGame, reviewedLine, say, summaryOf, waitingWords, withAnalyst, wordLines } from "../answers/index.js";
 import { defineCommand } from "../registry/index.js";
@@ -28,15 +29,15 @@ export const aiSay = defineCommand({
         // The chat woken by the player's ending move on the page may have gone to its words without the coach (Priya).
         return { game: withAnalyst(summaryOf(current, context.now(), archivedName(folder, current)), context, current), words, ...(coachOnEnd(context, folder, current) ? { coach: true } : {}) };
     },
-    format: ({ game, words, coach }) => [
+    format: ({ game, words, coach }, context) => [
         "Said on the board page, where the player reads it: don't write it again in the chat.",
         ...wordLines(words),
-        ...(coach === true ? [coachOnEndLine] : []),
-        afterWords(game, words),
+        ...(coach === true && game !== undefined ? [coachOnEndLine(game)] : []),
+        afterWords(game, words, hasDoorbell(context?.host?.())),
     ].join("\n"),
 });
 /** The next step once the AI has spoken: the end of a game over has been told already, and the player's draw offer answered in words. */
-function afterWords(game, words) {
+function afterWords(game, words, doorbell) {
     if (words.length === 0 && game?.end !== undefined) {
         // The offer to go over the game, made in the AI's words, waits for the player's yes (D-89).
         if (game.end.analyst === "done") {
@@ -49,5 +50,5 @@ function afterWords(game, words) {
     if (words.length === 0 && game?.drawOffer === "player" && game.turn !== game.ai) {
         return "Next: accept the draw with end_game draw_agreed, or wait for the player's move.";
     }
-    return nextStep(game, words);
+    return nextStep(game, words, false, doorbell);
 }

package/dist/core/game.d.ts

@@ -58,6 +58,7 @@ export declare class Game {
     private readonly moves;
     private last;
     private readonly keys;
+    private readonly positions;
     private readonly castled;
     private keptPosition;
     private keptOutcome;
@@ -70,6 +71,8 @@ export declare class Game {
     get outcome(): Outcome;
     /** 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(): GameRecord;
+    /** The key of every position the game has stood in, its start first, as the openings' book keys them (D-68): no replay to look the book up. */
+    get positionKeys(): readonly string[];
     /** The last move played, with its squares; none before the first. */
     get lastMove(): Move | undefined;
     /** What the position shows (D-26): attackers and defenders, pieces at risk, pins, checks, the moves of each piece; computed once for each position. */
@@ -98,3 +101,13 @@ export declare class Game {
 }
 /** 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 declare function withSanLetters(text: string): string;
+/** The moves a text writes with a piece's letter of another language, each with its SAN: Cxe5 as Nxe5. */
+export declare function foreignMovesIn(text: string): {
+    written: string;
+    san: string;
+}[];
+/**
+ * A player's move written with a piece's letter of another language that names one piece only, in SAN's (D-113): Cf3 as Nf3, Tf1 as Rf1, e8=D as e8=Q;
+ * a small t too, which is no file. Any other text as it is: B stays the bishop, K the king, R the rook, a small letter a file.
+ */
+export declare function withSanPieces(move: string): string;

package/dist/core/game.js

@@ -2,6 +2,7 @@
 import { Chess, validateFen } from "chess.js";
 import { factsOf } from "./facts.js";
 import { whyIllegal } from "./illegal.js";
+import { positionKey } from "./openings.js";
 import { possibilitiesOf, threatsOf } from "./possibilities.js";
 import { profileOf } from "./profile.js";
 import { cleanComment, recordedMove } from "./record.js";
@@ -17,6 +18,8 @@ export class Game {
     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;
+    // The same positions keyed as the openings' book keys them, its FEN without the move counters.
+    positions;
     castled = {};
     keptPosition;
     keptOutcome;
@@ -26,6 +29,7 @@ export class Game {
         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.positions = [positionKey(this.chess.fen())];
         this.tags = { ...record.tags };
         this.comment = cleanComment(record.comment ?? "") || undefined;
         for (const { san, nags, comment } of record.moves) {
@@ -58,6 +62,10 @@ export class Game {
         this.keptRecord ??= this.snapshot();
         return this.keptRecord;
     }
+    /** The key of every position the game has stood in, its start first, as the openings' book keys them (D-68): no replay to look the book up. */
+    get positionKeys() {
+        return this.positions;
+    }
     /** The last move played, with its squares; none before the first. */
     get lastMove() {
         return this.last;
@@ -129,11 +137,10 @@ export class Game {
         if ("refusal" in move) {
             return move;
         }
-        if (exact === undefined) {
-            this.chess.move({ from: move.from, to: move.to, promotion: move.promotion });
-        }
+        const after = exact === undefined ? this.chess.move({ from: move.from, to: move.to, promotion: move.promotion }).after : exact.after;
         this.last = move;
         this.keys.push(this.chess.hash());
+        this.positions.push(positionKey(after));
         if (move.san.startsWith("O-O")) {
             this.castled[mover] = move.san.startsWith("O-O-O") ? "O-O-O" : "O-O";
         }
@@ -223,6 +230,20 @@ const asciiOf = {
 export function withSanLetters(text) {
     return text.replace(/[︎️]/g, "").replace(/[–—−×♔-♟]/g, (sign) => asciiOf[sign] ?? sign);
 }
+/** The moves a text writes with a piece's letter of another language, each with its SAN: Cxe5 as Nxe5. */
+export function foreignMovesIn(text) {
+    return [...text.matchAll(foreignMove)]
+        .map(([written]) => ({ written, san: `${foreignPieces[written[0]][1]}${written.slice(1)}` }));
+}
+/**
+ * A player's move written with a piece's letter of another language that names one piece only, in SAN's (D-113): Cf3 as Nf3, Tf1 as Rf1, e8=D as e8=Q;
+ * a small t too, which is no file. Any other text as it is: B stays the bishop, K the king, R the rook, a small letter a file.
+ */
+export function withSanPieces(move) {
+    return move
+        .replace(foreignPieceMove, (_, before, letter) => `${before}${foreignPieces[letter.toUpperCase()][1]}`)
+        .replace(foreignPromotion, (_, before, letter) => `${before}${foreignPieces[letter][1]}`);
+}
 // 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"],
@@ -233,6 +254,11 @@ const foreignPieces = {
     T: ["rook", "R"],
     D: ["queen", "Q"],
 };
+// A move written with one of those letters, standing alone in a text.
+const foreignMove = new RegExp(`(?<![\\p{L}\\d])[${Object.keys(foreignPieces).join("")}][a-h]?[1-8]?x?[a-h][1-8][+#]?(?![\\p{L}\\d])`, "gu");
+// A whole move with such a letter, after its number if any: Tf1, 4. Cxe5+, D d1; and a pawn's move to the last rank that becomes such a piece: e8=D, exd1T.
+const foreignPieceMove = /^(\s*(?:\d+\s*(?:\.[\s.]*|…\s*))?)([CSAFLTDt])(?=\s*[a-h]?[1-8]?[-x:×]?[a-h][1-8][+#]*[!?]*\s*$)/;
+const foreignPromotion = /^(\s*(?:\d+\s*(?:\.[\s.]*|…\s*))?[a-h]?[1-8]?[-x:×]?[a-h][18]=?)([CSAFLTD])(?=[+#]*[!?]*\s*$)/;
 // The legal moves of the positions seen last, by their key: about 4 KB each.
 const legalByPosition = new Map();
 const positionsKept = 1_000;

package/dist/core/index.d.ts

@@ -3,7 +3,7 @@ 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, Skewer } from "./facts.ts";
-export { Game, withSanLetters } from "./game.ts";
+export { foreignMovesIn, Game, withSanLetters, withSanPieces } 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";
@@ -12,9 +12,9 @@ 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 { bookMoves, bookPlaceOf, indexBook, indexOpenings, openingOf, outOfBookMove, positionKeysOf } from "./openings.ts";
+export type { BookPlace, Opening, OpeningBook, OpeningIndex } from "./openings.ts";
+export { pgnDate, readPgn, readPgnTags, readPgnUnplayed, writePgn } from "./pgn.ts";
 export type { Capture, Chances, DoubleAttack, Possibilities, StalemateTrap } from "./possibilities.ts";
 export type { BishopFacts, CentreSquare, KingFacts, Outpost, PawnFacts, PawnSquare, Phase, Profile, SideProfile } from "./profile.ts";
 export { movesOnly } from "./record.ts";

package/dist/core/index.js

@@ -2,12 +2,12 @@
 export { accountSide } from "./accounts.js";
 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 { foreignMovesIn, Game, withSanLetters, withSanPieces } 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 { bookMoves, bookPlaceOf, indexBook, indexOpenings, openingOf, outOfBookMove, positionKeysOf } from "./openings.js";
+export { pgnDate, readPgn, readPgnTags, readPgnUnplayed, writePgn } from "./pgn.js";
 export { movesOnly } from "./record.js";
 export { aiHostIn, aiModelIn, aiNameOf, annotatorOf, arrowOf, badges, closingOf, drawingsIn, drawingsText, gameReviewOf, isReviewed, reviewed, reviewOf, squareOf, unreviewed, unsigned, withAiHost, withAiModel, withAnnotator, withGameReview, } from "./review.js";

package/dist/core/openings.d.ts

@@ -12,8 +12,11 @@ export interface Opening {
     readonly variation?: string;
     /** How many plies the game had when it reached the opening's position. */
     readonly ply: number;
-    /** Whether the game's position now is a named one; when not, it left the book at the ply after `ply`. */
-    readonly inBook: boolean;
+}
+/** Where a game from the standard position stands in the book: the last named opening it reached, and how many of its first plies a line of the book reaches (D-68). */
+export interface BookPlace {
+    readonly opening?: Opening;
+    readonly plies: number;
 }
 /** The book's moves: each position on a line of Lichess's files to the moves its lines play from it, the theory the AI knows at the master level (D-15, D-60). */
 export type OpeningBook = Readonly<Record<string, readonly string[]>>;
@@ -27,9 +30,20 @@ export declare function indexOpenings(tsv: string): Record<string, [string, stri
 export declare function indexBook(tsv: string): Record<string, string[]>;
 /** The moves the book knows from a position, in SAN; none out of the book. */
 export declare function bookMoves(fen: string, book: OpeningBook): readonly string[];
-/** Whether a line of the book reaches a position, by any order of moves: one its lines play on from, or one an opening is named after. */
-export declare function inOpenings(fen: string, index: OpeningIndex, book: OpeningBook): boolean;
 /** The opening of a game from the standard position, the last named one its moves reached; none before the first, or from another position. */
 export declare function openingOf(record: GameRecord, index: OpeningIndex): Opening | undefined;
-/** The move number at which a game that reached an opening at `ply` left the book. */
-export declare function outOfBookMove(opening: Opening): number;
+/**
+ * Where a game stands in the book, from the keys of the positions it stood in, its start first: the last named position its moves reached, and its first
+ * plies whose position a line of the book reaches, by any order of moves, one its lines play on from or one an opening is named after; without the book,
+ * no ply is counted. None from another position than the standard one, whatever its FEN tag says.
+ */
+export declare function bookPlaceOf(keys: readonly string[], index: OpeningIndex, book?: OpeningBook): BookPlace | undefined;
+/** The keys of a record's positions, its start first, replayed to the book's depth for a game from the standard position: for a record no live game holds. */
+export declare function positionKeysOf(record: GameRecord): readonly string[];
+/** A position without its move counters, the key of the index and the book: the same position reached in another order is the same key. */
+export declare function positionKey(fen: string): string;
+/**
+ * The move number at which a game from the standard position left the book (D-68), the move of its first ply past the `inBook` plies a line of the book
+ * reaches; none while all its `plies` are the book's.
+ */
+export declare function outOfBookMove(plies: number, inBook: number): number | undefined;