chesspal 0.3.5 → 0.4.0

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";
@@ -8,28 +8,43 @@ import { defineCommand } from "../registry/index.js";
 export const pastGames = defineCommand({
     name: "past_games",
     description: "Lists the games played with this player, the latest first: when, your colour, the result, the opening, how long, and its name in the "
-        + "archive. With game, that game's PGN with your comments and plans; to comment a game with the player, analyse_game. new_game already gives the "
-        + "last three. Example: past_games {}.",
-    input: z.object({ game: z.string().optional().describe("a game's name, as the list writes it: its PGN") }),
+        + "archive. With search, only the games whose line holds every word of it; the colour and the result are yours, the AI's. With game, that game's "
+        + "PGN with your comments and plans; to comment a game with the player, analyse_game. new_game already gives the last three. Example, the "
+        + 'Sicilians the player lost: past_games {search: "Sicilian won"}.',
+    input: z.object({
+        search: z.string().optional().describe("words the game's line must all hold: a date, your colour, won, lost, drew or unfinished as you did, an opening"),
+        game: z.string().optional().describe("a game's name, as the list writes it: its PGN"),
+    }),
     readOnly: true,
     idempotent: true,
-    run: ({ game }, context) => {
+    run: ({ search, game }, context) => {
         const folder = gameFolder(context.home());
-        return game === undefined ? { games: pastGameLines(folder, listed) } : { pgn: writePgn(archivedGame(folder, game)) };
+        return game === undefined ? { games: pastGameLines(folder, listed, search), searched: search?.trim() ? true : undefined } : { pgn: writePgn(archivedGame(folder, game)) };
+    },
+    format: (past) => {
+        if ("pgn" in past) {
+            return past.pgn;
+        }
+        return past.games.length > 0 ? past.games.join("\n") : past.searched ? "No game played holds all those words." : "No game played yet.";
     },
-    format: (past) => ("pgn" in past ? past.pgn : past.games.length === 0 ? "No game played yet." : past.games.join("\n")),
 });
-/** The latest games of the archive, one line each as the AI reads them: none when there is no archive. A game closed before any move is no game played. */
-export function pastGameLines(folder, count) {
+/**
+ * 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. 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 !== "");
     const lines = [];
     for (const name of archivedGames(folder)) {
         if (lines.length === count) {
             break;
         }
         try {
-            const record = archivedGame(folder, name);
-            if (record.moves.length > 0) {
-                lines.push(pastGameLine(name, record));
+            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))) {
+                lines.push(line);
             }
         }
         catch {
@@ -39,14 +54,26 @@ export function pastGameLines(folder, count) {
     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,26 +29,26 @@ 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") {
             return `Next: ${reviewedLine(game.end.archive)} When they want another game, ${newGameStep}`;
         }
         return game.end.analyst === "offer"
-            ? `Next: when the player wants this game gone over, ${analystLine(game.end.archive)} When they want another game, ${newGameStep}`
+            ? `Next: when the player wants this game gone over, ${analystLine(game.end.archive, game.end.codex === true)} When they want another game, ${newGameStep}`
             : `Next: when the player wants another game, ${newGameStep}`;
     }
     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;

package/dist/core/openings.js

@@ -2,6 +2,7 @@
 import { Chess } from "chess.js";
 /** No line of the book is longer: past it, no position is looked up. */
 const bookDepth = 40;
+const standardStart = positionKey(new Chess().fen());
 /** The index of the openings in Lichess's TSV files (eco, name, pgn), each line keyed by the position its moves reach. */
 export function indexOpenings(tsv) {
     const index = {};
@@ -37,39 +38,61 @@ export function indexBook(tsv) {
 export function bookMoves(fen, book) {
     return book[positionKey(fen)] ?? [];
 }
-/** 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 function inOpenings(fen, index, book) {
-    const key = positionKey(fen);
-    return book[key] !== undefined || index[key] !== undefined;
-}
 /** 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 function openingOf(record, index) {
-    if (record.tags.FEN !== undefined && record.tags.FEN !== new Chess().fen()) {
+    return bookPlaceOf(positionKeysOf(record), index)?.opening;
+}
+/**
+ * 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 function bookPlaceOf(keys, index, book) {
+    if (!standardStartKey(keys[0])) {
         return undefined;
     }
-    const chess = new Chess();
-    const plies = Math.min(record.moves.length, bookDepth);
+    const last = Math.min(keys.length - 1, bookDepth);
     let found;
-    for (let ply = 1; ply <= plies; ply++) {
-        chess.move(record.moves[ply - 1].san);
-        const named = index[positionKey(chess.fen())];
+    let plies = 0;
+    for (let ply = 1; ply <= last; ply++) {
+        const key = keys[ply];
+        const named = index[key];
         if (named !== undefined) {
             found = { named, ply };
         }
+        if (book !== undefined && plies === ply - 1 && (named !== undefined || book[key] !== undefined)) {
+            plies = ply;
+        }
     }
-    if (found === undefined) {
-        return undefined;
+    return found === undefined ? { plies } : { opening: openingNamed(found.named, found.ply), plies };
+}
+/** 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 function positionKeysOf(record) {
+    const start = positionKey(record.tags.FEN ?? new Chess().fen());
+    if (!standardStartKey(start)) {
+        return [start];
     }
-    const [eco, name] = found.named;
+    const chess = new Chess();
+    return [start, ...record.moves.slice(0, bookDepth).map(({ san }) => positionKey(chess.move(san).after))];
+}
+/** 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 function positionKey(fen) {
+    return fen.split(" ").slice(0, 4).join(" ");
+}
+/**
+ * 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 function outOfBookMove(plies, inBook) {
+    return plies > inBook ? Math.floor(inBook / 2) + 1 : undefined;
+}
+/** The opening a name of the index stands for, reached at `ply`. */
+function openingNamed([eco, name], ply) {
     const colon = name.indexOf(":");
     const family = colon < 0 ? name : name.slice(0, colon);
-    const opening = { eco, name, family, ply: found.ply, inBook: found.ply === record.moves.length };
+    const opening = { eco, name, family, ply };
     return colon < 0 ? opening : { ...opening, variation: name.slice(colon + 1).trim() };
 }
-/** The move number at which a game that reached an opening at `ply` left the book. */
-export function outOfBookMove(opening) {
-    return Math.floor(opening.ply / 2) + 1;
-}
 /** The moves from a position that at least one line in fifty plays, the most played first, with the trap's name when all their lines are traps. */
 function bookOf(counts) {
     const total = [...counts.values()].reduce((sum, count) => sum + count.lines, 0);
@@ -92,7 +115,7 @@ function linesOf(tsv) {
         return [{ eco, name, moves }];
     });
 }
-/** A position without its move counters: the same position reached in another order is the same key. */
-function positionKey(fen) {
-    return fen.split(" ").slice(0, 4).join(" ");
+/** Whether a position's key is the standard start's: the one check of where the book applies. */
+function standardStartKey(key) {
+    return key === standardStart;
 }

package/dist/core/pgn.d.ts

@@ -6,5 +6,9 @@ import { type GameRecord } from "./record.ts";
 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 games of a PGN text as readPgn gives them, but with their moves as written, neither checked nor played: for what the tags and comments say, quickly. */
+export declare function readPgnUnplayed(text: string): GameRecord[];
+/** The tags of a PGN text's first game, read without its moves: none checked, none played. */
+export declare function readPgnTags(text: string): Readonly<Record<string, string>>;
 /** 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

@@ -14,7 +14,25 @@ export function writePgn(record) {
 }
 /** 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();
+    return new PgnReader(text, true).read();
+}
+/** The games of a PGN text as readPgn gives them, but with their moves as written, neither checked nor played: for what the tags and comments say, quickly. */
+export function readPgnUnplayed(text) {
+    return new PgnReader(text, false).read();
+}
+/** The tags of a PGN text's first game, read without its moves: none checked, none played. */
+export function readPgnTags(text) {
+    const tags = {};
+    for (const line of text.split("\n")) {
+        const tag = tagPattern.exec(line);
+        if (tag !== null) {
+            tags[tag[1]] = tag[2].replace(/\\(.)/g, "$1");
+        }
+        else if (line.trim() !== "" || Object.keys(tags).length > 0) {
+            break;
+        }
+    }
+    return tags;
 }
 /** The day of a date, in its own time zone, as PGN's Date tag writes it: 2026.11.02. */
 export function pgnDate(date) {
@@ -24,6 +42,8 @@ export function pgnDate(date) {
 // 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));
+// A line holding a tag alone, as writePgn writes it.
+const tagPattern = /^\s*\[\s*(\w+)\s*"((?:[^"\\]|\\.)*)"\s*\]\s*$/;
 // The judgments written after a move, NAGs $1 to $6.
 const glyphs = ["!", "?", "!!", "??", "!?", "?!"];
 const nagOfGlyph = new Map(glyphs.map((glyph, index) => [glyph, index + 1]));
@@ -33,16 +53,20 @@ const lineLength = 79;
 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;
+    // Whether the moves are played, so checked and written as Chesspal writes them, or taken as written.
+    plays;
     records = [];
     tags = [];
     comments = [];
     moves = [];
     game;
+    begun = false;
     result;
     depth = 0;
     at = 0;
-    constructor(text) {
+    constructor(text, plays) {
         this.text = text;
+        this.plays = plays;
     }
     read() {
         for (let index = 0; index < this.text.length; index = tokenPattern.lastIndex) {
@@ -94,7 +118,7 @@ class PgnReader {
     }
     tag(name, value) {
         // A tag after the moves starts the next game, when the last one had no result.
-        if (this.game !== undefined) {
+        if (this.begun) {
             this.finish();
         }
         this.tags.push([name, value]);
@@ -106,7 +130,10 @@ class PgnReader {
         }
         const [, san = "", glyph = ""] = /^(.*?)([!?]*)$/.exec(token) ?? [];
         const game = this.started();
-        if (san !== "") {
+        if (san !== "" && game === undefined) {
+            this.moves.push({ san, nags: [], comments: [] });
+        }
+        else if (san !== "" && game !== undefined) {
             const played = game.playRecorded(san);
             if (!played.played) {
                 throw this.error(this.at, played.message, game.position.moveNumber);
@@ -129,9 +156,10 @@ class PgnReader {
         // 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. */
+    /** The game the moves are played on, made from the tags at the first move; none when they are taken as written. */
     started() {
-        if (this.game === undefined) {
+        this.begun = true;
+        if (this.game === undefined && this.plays) {
             try {
                 this.game = new Game({ tags: Object.fromEntries(this.tags), moves: [] });
             }
@@ -156,6 +184,7 @@ class PgnReader {
         this.comments = [];
         this.moves = [];
         this.game = undefined;
+        this.begun = false;
         this.result = undefined;
     }
     error(index, message, moveNumber) {

package/dist/games/analysis.d.ts

@@ -1,11 +1,13 @@
 /**
  * The game in analysis: its name as the lists write it, when the analysis last changed it, whether the player brought it on the page and the AI has not
- * gone over it yet, the moves whose note the chat corrected with the player, which the analyst leaves (D-101), and the run of the analyst that took it.
+ * gone over it yet, and whether they asked there for a new review of it; the moves whose note the chat corrected with the player, which the analyst leaves
+ * (D-101), and the run of the analyst that took it.
  */
 export interface Analysis {
     readonly game: string;
     readonly at: string;
     readonly brought?: true;
+    readonly redo?: true;
     readonly corrected?: readonly string[];
     readonly analyst?: AnalystRun;
 }
@@ -16,11 +18,12 @@ export interface AnalystRun {
     readonly since: string;
 }
 /**
- * How a game is named in analysis: brought to the page by the player, with the moves the chat just corrected, taken by a run of the analyst, or afresh,
- * without the corrections and the analyst it had.
+ * How a game is named in analysis: brought to the page by the player, for a new review too, with the moves the chat just corrected, taken by a run of the
+ * analyst, or afresh, without the corrections and the analyst it had.
  */
 export interface AnalysisStart {
     readonly brought?: boolean;
+    readonly redo?: boolean;
     readonly corrected?: readonly string[];
     readonly analyst?: AnalystRun;
     readonly afresh?: boolean;
@@ -30,7 +33,7 @@ export interface AnalysisStart {
  * unless it starts afresh, in one write, so that the page never sees it leave the analysis; the analyst stays with the game it took, whichever the page
  * opens meanwhile (Federico), and goes when that game starts afresh.
  */
-export declare function startAnalysis(folder: string, game: string, now: Date, { brought, corrected, analyst, afresh }?: AnalysisStart): void;
+export declare function startAnalysis(folder: string, game: string, now: Date, { brought, redo, corrected, analyst, afresh }?: AnalysisStart): void;
 /** Lets the analyst go from the game it took, when that game's review is deleted while the page shows another. */
 export declare function forgetAnalyst(folder: string): void;
 /** The game in analysis, or none when there is none, or analysis.json cannot be read. */