chesspal 0.3.6 → 0.4.0

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/archive.d.ts

@@ -10,15 +10,15 @@ export declare function isOverOnTable(folder: string, name: string): boolean;
  */
 export declare function startOfNewGame(folder: string, now: Date, before?: CurrentGame): Date;
 /**
- * Writes the game to the archive, with the plans, how it ended and the AI's model and host last noted (D-82, D-97), and gives its name; the same game again rewrites the
- * same file. A game closed before any move is not kept, as Lichess aborts it: none.
+ * Writes the game to the archive, with the plans, how it ended, the AI's model and host last noted (D-82, D-97) and the opening's tags, and gives its name;
+ * the same game again rewrites the same file. A game closed before any move is not kept, as Lichess aborts it: none.
  */
-export declare function archiveGame(folder: string, current: CurrentGame): string | undefined;
+export declare function archiveGame(folder: string, current: CurrentGame, opening: OpeningTags): string | undefined;
 /**
  * Archives a game that has ended: its name in the archive, none for a game closed before any move, or, when that fails, a warning, since the game is saved in
  * game.json all the same.
  */
-export declare function archiveEnded(folder: string, current: CurrentGame): {
+export declare function archiveEnded(folder: string, current: CurrentGame, opening: OpeningTags): {
     archive?: string;
     warning?: string;
 };
@@ -26,16 +26,36 @@ export declare function archiveEnded(folder: string, current: CurrentGame): {
  * Writes the coach's judgments into a game over already in the archive, beside what the analyst may have written there since (Federico);
  * archives the game when it is not there.
  */
-export declare function archiveCoached(folder: string, current: CurrentGame): {
+export declare function archiveCoached(folder: string, current: CurrentGame, opening: OpeningTags): {
     archive?: string;
     warning?: string;
 };
 /** The name of a game over in the archive, when it is there. */
 export declare function archivedName(folder: string, current: CurrentGame): string | undefined;
+/**
+ * The opening a game reached, in its ECO and Opening tags, as the commands name it: none from another position or outside the book. With the PlyCount the
+ * archive adds, a game is listed from its tags alone.
+ */
+export interface OpeningTags {
+    readonly ECO?: string;
+    readonly Opening?: string;
+}
 /** The names of the games in the archive, the latest first: games/2026-11-02-153012.pgn. */
 export declare function archivedGames(folder: string): string[];
 /** A game of the archive by its name, as listed; refused when it is not there, or cannot be read. */
 export declare function archivedGame(folder: string, name: string): GameRecord;
+/** A game of the archive by its name, as listed, with its moves as written, neither checked nor played: for its tags and comments, quickly. */
+export declare function archivedGameUnplayed(folder: string, name: string): GameRecord;
+/** The tags of a game of the archive by its name, as listed, read without its moves; refused as archivedGame refuses. */
+export declare function archivedTags(folder: string, name: string): Readonly<Record<string, string>>;
+/**
+ * Whether the archive wrote a game's list tags, its PlyCount with its ECO and Opening, or none for a game that has no opening: a numeric PlyCount says so.
+ * A game an older Chesspal archived has none, and is read whole.
+ */
+export declare function hasListTags(tags: Readonly<Record<string, string>>): boolean;
+/** The refusal of a game asked by a name no game has, apart from a game that is there and cannot be read. */
+export declare class GameMissing extends Error {
+}
 /** The names of the games kept to study in a profile's folder, the latest kept first: study/2026-11-04-153012.pgn. */
 export declare function keptGames(root: string): string[];
 /** A game kept to study by its name, as listed; refused when it is not there, or cannot be read. */

package/dist/games/archive.js

@@ -1,7 +1,7 @@
 // The finished games, as PGN in games/ (D-9, D-41), with the AI's plans for the analyst (D-21); and the games played elsewhere, kept to study in study/ (D-68).
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { movesOnly, pgnDate, readPgn, unsigned, withAiHost, withAiModel, writePgn } from "../core/index.js";
+import { movesOnly, pgnDate, readPgn, readPgnTags, readPgnUnplayed, unsigned, withAiHost, withAiModel, writePgn } from "../core/index.js";
 import { aiHostOf, aiModelOf } from "./ai-model.js";
 import { coachWords, withCoach } from "./coach.js";
 import { endOf, loadGame } from "./current-game.js";
@@ -34,10 +34,10 @@ export function startOfNewGame(folder, now, before) {
     return start;
 }
 /**
- * Writes the game to the archive, with the plans, how it ended and the AI's model and host last noted (D-82, D-97), and gives its name; the same game again rewrites the
- * same file. A game closed before any move is not kept, as Lichess aborts it: none.
+ * Writes the game to the archive, with the plans, how it ended, the AI's model and host last noted (D-82, D-97) and the opening's tags, and gives its name;
+ * the same game again rewrites the same file. A game closed before any move is not kept, as Lichess aborts it: none.
  */
-export function archiveGame(folder, current) {
+export function archiveGame(folder, current, opening) {
     if (current.game.record.moves.length === 0) {
         return undefined;
     }
@@ -45,7 +45,7 @@ export function archiveGame(folder, current) {
     const path = join(folder, name);
     try {
         makeFolder(dirname(path));
-        writeAtomically(path, writePgn(withAiHost(withAiModel(endedRecord(folder, current), aiModelOf(folder)), aiHostOf(folder))));
+        writeAtomically(path, writePgn(withListTags(withAiHost(withAiModel(endedRecord(folder, current), aiModelOf(folder)), aiHostOf(folder)), opening)));
     }
     catch (error) {
         throw new Error(`Chesspal could not archive the game: ${error.message}`, { cause: error });
@@ -56,9 +56,9 @@ export function archiveGame(folder, current) {
  * Archives a game that has ended: its name in the archive, none for a game closed before any move, or, when that fails, a warning, since the game is saved in
  * game.json all the same.
  */
-export function archiveEnded(folder, current) {
+export function archiveEnded(folder, current, opening) {
     try {
-        const archive = archiveGame(folder, current);
+        const archive = archiveGame(folder, current, opening);
         return archive === undefined ? {} : { archive };
     }
     catch (error) {
@@ -69,10 +69,10 @@ export function archiveEnded(folder, current) {
  * Writes the coach's judgments into a game over already in the archive, beside what the analyst may have written there since (Federico);
  * archives the game when it is not there.
  */
-export function archiveCoached(folder, current) {
+export function archiveCoached(folder, current, opening) {
     const name = archivedName(folder, current);
     if (name === undefined) {
-        return archiveEnded(folder, current);
+        return archiveEnded(folder, current, opening);
     }
     try {
         writeAtomically(join(folder, name), writePgn(withCoach(archivedGame(folder, name), coachWords(folder, current))));
@@ -98,6 +98,28 @@ export function archivedGames(folder) {
 export function archivedGame(folder, name) {
     return gameNamed(folder, "games", name);
 }
+/** A game of the archive by its name, as listed, with its moves as written, neither checked nor played: for its tags and comments, quickly. */
+export function archivedGameUnplayed(folder, name) {
+    const [record] = readPgnUnplayed(gameText(folder, "games", name));
+    if (record === undefined) {
+        throw new Error(`${name} holds no game Chesspal can read.`);
+    }
+    return record;
+}
+/** The tags of a game of the archive by its name, as listed, read without its moves; refused as archivedGame refuses. */
+export function archivedTags(folder, name) {
+    return readPgnTags(gameText(folder, "games", name));
+}
+/**
+ * Whether the archive wrote a game's list tags, its PlyCount with its ECO and Opening, or none for a game that has no opening: a numeric PlyCount says so.
+ * A game an older Chesspal archived has none, and is read whole.
+ */
+export function hasListTags(tags) {
+    return /^\d+$/.test(tags.PlyCount ?? "");
+}
+/** The refusal of a game asked by a name no game has, apart from a game that is there and cannot be read. */
+export class GameMissing extends Error {
+}
 /** The names of the games kept to study in a profile's folder, the latest kept first: study/2026-11-04-153012.pgn. */
 export function keptGames(root) {
     return gameNames(root, "study");
@@ -211,24 +233,30 @@ function gameNames(folder, shelf) {
     }
 }
 function gameNamed(folder, shelf, name) {
+    const [record] = readPgn(gameText(folder, shelf, name));
+    if (record === undefined) {
+        throw new Error(`${name} holds no game Chesspal can read.`);
+    }
+    return record;
+}
+function gameText(folder, shelf, name) {
     // The name as listed, or without its folder or its .pgn.
     const file = `${(name.startsWith(`${shelf}/`) ? name.slice(shelf.length + 1) : name).trim().replace(/\.pgn$/, "")}.pgn`;
     const { what, list } = shelves[shelf];
     if (!namePattern.test(file)) {
-        throw new Error(`${name} is no game ${what}: give a name as ${list} writes it, such as ${shelf}/2026-11-02-153012.pgn.`);
+        throw new GameMissing(`${name} is no game ${what}: give a name as ${list} writes it, such as ${shelf}/2026-11-02-153012.pgn.`);
     }
-    let text;
     try {
-        text = readFileSync(join(folder, shelf, file), "utf8");
-    }
-    catch {
-        throw new Error(`There is no ${name} among the games ${what}: give a name as ${list} writes it.`);
+        return readFileSync(join(folder, shelf, file), "utf8");
     }
-    const [record] = readPgn(text);
-    if (record === undefined) {
-        throw new Error(`${name} holds no game Chesspal can read.`);
+    catch (error) {
+        const code = error.code;
+        // Only a file that is not there is a missing game: one busy or locked by another process is there, and may be read in a moment.
+        if (code === "ENOENT") {
+            throw new GameMissing(`There is no ${name} among the games ${what}: give a name as ${list} writes it.`);
+        }
+        throw new Error(`${name} could not be read (${code ?? error.message}): try again in a moment.`, { cause: error });
     }
-    return record;
 }
 /** Whether two records are the same game: the same tags and the same moves, whatever their comments say. */
 function sameGame(one, other) {
@@ -245,6 +273,11 @@ function endedRecord(folder, current) {
     const { record, outcome } = current.game;
     return withTermination(withCoach(record, coachWords(folder, current)), outcome);
 }
+/** The record with the tags past_games lists it from: the opening's, the commands' alone whatever the game brought, and how many plies it has. */
+function withListTags(record, opening) {
+    const tags = Object.fromEntries(Object.entries(record.tags).filter(([name]) => name !== "ECO" && name !== "Opening" && name !== "PlyCount"));
+    return { ...record, tags: { ...tags, ...opening, PlyCount: String(record.moves.length) } };
+}
 function withTermination(record, outcome) {
     return outcome.over && record.tags.Termination === undefined ? { ...record, tags: { ...record.tags, Termination: outcome.ending } } : record;
 }

package/dist/games/chat-start.d.ts

@@ -1,6 +1,6 @@
 /**
- * How a chat started, as the host's SessionStart hook says it: new, cleared, resumed or compacted; when, as an ISO date; its session, for the logs; and the
- * file where the host writes the chat, where Claude Code tells which model made each tool call (D-81).
+ * How a chat started, as the host's SessionStart hook says it: new, cleared, resumed or compacted; when, as an ISO date; its session, as the hooks have it;
+ * and the file where the host writes the chat, where Claude Code tells which model made each tool call (D-81).
  */
 export interface ChatStart {
     readonly source: string;

package/dist/games/chat-start.js

@@ -13,7 +13,12 @@ export function lastChatStart(folder) {
         if (typeof start.source !== "string" || typeof start.at !== "string") {
             return undefined;
         }
-        return { source: start.source, at: start.at, ...(typeof start.transcript === "string" ? { transcript: start.transcript } : {}) };
+        return {
+            source: start.source,
+            at: start.at,
+            ...(typeof start.session === "string" ? { session: start.session } : {}),
+            ...(typeof start.transcript === "string" ? { transcript: start.transcript } : {}),
+        };
     }
     catch {
         return undefined;

package/dist/games/current-game.d.ts

@@ -43,9 +43,9 @@ export interface GameEnd {
 export declare function loadGame(folder: string): CurrentGame | undefined;
 /**
  * Writes the current game to game.json, whole or not at all; from then on it is the one kept in memory. Refused with GameChanged when another process wrote
- * the file since this one read it: the change made on the game read before would lose theirs.
+ * the file since this one read it: the change made on the game read before would lose theirs. `first` runs just before the write, on the game read.
  */
-export declare function saveGame(folder: string, current: CurrentGame): void;
+export declare function saveGame(folder: string, current: CurrentGame, first?: () => void): void;
 /** The refusal of a save on a game another process changed since this one read it: what wrote it reads it again and starts over, once (rerunIfChanged). */
 export declare class GameChanged extends Error {
     constructor();

package/dist/games/current-game.js

@@ -23,15 +23,16 @@ export function loadGame(folder) {
 }
 /**
  * Writes the current game to game.json, whole or not at all; from then on it is the one kept in memory. Refused with GameChanged when another process wrote
- * the file since this one read it: the change made on the game read before would lose theirs.
+ * the file since this one read it: the change made on the game read before would lose theirs. `first` runs just before the write, on the game read.
  */
-export function saveGame(folder, current) {
+export function saveGame(folder, current, first) {
     const path = join(folder, fileName);
     whileLocked(path, () => {
         if (stampOf(path) !== kept.get(path)?.stamp) {
             kept.delete(path);
             throw new GameChanged();
         }
+        first?.();
         write(path, current);
     });
 }

package/dist/games/index.d.ts

@@ -1,11 +1,12 @@
 export { aiHostOf, aiModelOf, forgetTheAi, noteAiHost, noteAiModel } from "./ai-model.ts";
 export { type Analysis, type AnalysisStart, endAnalysis, forgetAnalyst, gameInAnalysis, startAnalysis } from "./analysis.ts";
-export { archiveCoached, archivedGame, archivedGames, archivedName, archivedWhen, archiveEnded, archiveGame, archiveName, deleteGame, gameStemOf, isGameName, isOverOnTable, keepToStudy, keptGame, keptGames, listedName, movesPgn, playerPgn, rewriteGame, startOfNewGame, } from "./archive.ts";
+export { archiveCoached, archivedGame, archivedGames, archivedGameUnplayed, archivedName, archivedTags, archivedWhen, archiveEnded, archiveGame, archiveName, deleteGame, GameMissing, gameStemOf, hasListTags, isGameName, isOverOnTable, keepToStudy, keptGame, keptGames, listedName, movesPgn, type OpeningTags, playerPgn, rewriteGame, startOfNewGame, } from "./archive.ts";
 export { type ChatStart, cleanSince, lastChatStart, saveChatStart } from "./chat-start.ts";
 export { type CoachHint, type CoachJudgment, type CoachLead, coachShown, coachStarted, coachWaitingSince, type CoachWords, coachWords, forgetCoach, keepHint, keepJudgment, keepLead, startCoach, withCoach } from "./coach.ts";
 export { bothSidesMoved, type CurrentGame, drawOfferOf, endOf, GameChanged, type GameEnd, gameStamp, loadGame, removeGame, rerunIfChanged, saveGame, type Shown, type Speaker, type TalkLine } from "./current-game.ts";
 export { makeFolder, renameOver, writeAtomically } from "./files.ts";
 export { commentWithPlan, currentPlan, planOf, withoutPlans } from "./plans.ts";
+export { forgetPositionShown, hostProcess, notePositionShown, type PositionShown, positionShownNote } from "./position-shown.ts";
 export { endTableTalk, loadTableTalk, saveTableTalk, type TableTalk, tableTalkStamp } from "./table-talk.ts";
 export { type Heard, heardLines, type Sayer, type Talk, talkLimits, talkLine, unheardWords, wakesTheChat, type Words, WordsRefused } from "./talk.ts";
 export { keepThought, notePondering, ponderingOn, ponderingUntil, type Thought, thoughtForLastMove, thoughtKey, waitingSince } from "./thoughts.ts";

package/dist/games/index.js

@@ -1,12 +1,13 @@
 // The player's games on disk: the current one in game.json, the finished ones in games/ (D-27, D-41), the games kept to study in study/ (D-68). Below the commands, above the core.
 export { aiHostOf, aiModelOf, forgetTheAi, noteAiHost, noteAiModel } from "./ai-model.js";
 export { endAnalysis, forgetAnalyst, gameInAnalysis, startAnalysis } from "./analysis.js";
-export { archiveCoached, archivedGame, archivedGames, archivedName, archivedWhen, archiveEnded, archiveGame, archiveName, deleteGame, gameStemOf, isGameName, isOverOnTable, keepToStudy, keptGame, keptGames, listedName, movesPgn, playerPgn, rewriteGame, startOfNewGame, } from "./archive.js";
+export { archiveCoached, archivedGame, archivedGames, archivedGameUnplayed, archivedName, archivedTags, archivedWhen, archiveEnded, archiveGame, archiveName, deleteGame, GameMissing, gameStemOf, hasListTags, isGameName, isOverOnTable, keepToStudy, keptGame, keptGames, listedName, movesPgn, playerPgn, rewriteGame, startOfNewGame, } from "./archive.js";
 export { cleanSince, lastChatStart, saveChatStart } from "./chat-start.js";
 export { coachShown, coachStarted, coachWaitingSince, coachWords, forgetCoach, keepHint, keepJudgment, keepLead, startCoach, withCoach } from "./coach.js";
 export { bothSidesMoved, drawOfferOf, endOf, GameChanged, gameStamp, loadGame, removeGame, rerunIfChanged, saveGame } from "./current-game.js";
 export { makeFolder, renameOver, writeAtomically } from "./files.js";
 export { commentWithPlan, currentPlan, planOf, withoutPlans } from "./plans.js";
+export { forgetPositionShown, hostProcess, notePositionShown, positionShownNote } from "./position-shown.js";
 export { endTableTalk, loadTableTalk, saveTableTalk, tableTalkStamp } from "./table-talk.js";
 export { heardLines, talkLimits, talkLine, unheardWords, wakesTheChat, WordsRefused } from "./talk.js";
 export { keepThought, notePondering, ponderingOn, ponderingUntil, thoughtForLastMove, thoughtKey, waitingSince } from "./thoughts.js";

package/dist/games/position-shown.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The position shown to a chat by its session, as the host names it to its hooks, and by the host's process, when it names one: the game by its start, none
+ * when there is none, its plies, the stamp of game.json after the move, when, and the keys of the player's words given with it.
+ */
+export interface PositionShown {
+    readonly session: string;
+    readonly process?: string;
+    readonly stamp?: string;
+    readonly started?: string;
+    readonly plies: number;
+    readonly at: string;
+    readonly given: readonly string[];
+}
+/**
+ * The Claude Code process this one runs in, as it names it to its hooks and to the MCP server alike, the same through /clear and /resume: none when it
+ * names none. Not documented: Priya measured it in Claude Code 2.1.323.
+ */
+export declare function hostProcess(): string | undefined;
+/** Notes the position shown to a chat, over the last one. */
+export declare function notePositionShown(folder: string, shown: PositionShown): void;
+/** The position a hook showed a chat of the folder, or undefined when there is no note, or it cannot be read. */
+export declare function positionShownNote(folder: string): PositionShown | undefined;
+/** Forgets the note; one that cannot go now is taken again, which changes nothing, or dropped once the game has moved on. */
+export declare function forgetPositionShown(folder: string): void;

package/dist/games/position-shown.js

@@ -0,0 +1,51 @@
+// The position a hook showed a chat outside its server (D-71), and the player's words on the board page it gave with it: `chesspal prompt` notes them
+// after playing the move the player wrote alone, and the chat's server takes them before its next tool, so that the AI moves without asking for status
+// and no tool gives those words again; the chat's doorbell does not ring for that move, which the chat hears from the prompt itself.
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeAtomically } from "./files.js";
+/**
+ * The Claude Code process this one runs in, as it names it to its hooks and to the MCP server alike, the same through /clear and /resume: none when it
+ * names none. Not documented: Priya measured it in Claude Code 2.1.323.
+ */
+export function hostProcess() {
+    const socket = process.env.CLAUDE_CODE_MESSAGING_SOCKET?.trim();
+    return socket === undefined || socket === "" ? undefined : socket;
+}
+/** Notes the position shown to a chat, over the last one. */
+export function notePositionShown(folder, shown) {
+    writeAtomically(join(folder, fileName), `${JSON.stringify(shown)}\n`);
+}
+/** The position a hook showed a chat of the folder, or undefined when there is no note, or it cannot be read. */
+export function positionShownNote(folder) {
+    try {
+        const shown = JSON.parse(readFileSync(join(folder, fileName), "utf8"));
+        if (typeof shown.session !== "string" || typeof shown.at !== "string" || !Number.isInteger(shown.plies)) {
+            return undefined;
+        }
+        // A note of an older Chesspal has no words.
+        const given = Array.isArray(shown.given) ? shown.given.filter((key) => typeof key === "string") : [];
+        return {
+            session: shown.session,
+            ...(typeof shown.process === "string" ? { process: shown.process } : {}),
+            ...(typeof shown.stamp === "string" ? { stamp: shown.stamp } : {}),
+            ...(typeof shown.started === "string" ? { started: shown.started } : {}),
+            plies: shown.plies,
+            at: shown.at,
+            given,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Forgets the note; one that cannot go now is taken again, which changes nothing, or dropped once the game has moved on. */
+export function forgetPositionShown(folder) {
+    try {
+        rmSync(join(folder, fileName), { force: true });
+    }
+    catch {
+        // Another process holds it for a moment.
+    }
+}
+const fileName = "position-shown.json";

package/dist/home/index.d.ts

@@ -1,3 +1,3 @@
 export { dataFolder, type System, tableFolder } from "./data-folder.ts";
 export { openFolder } from "./open-folder.ts";
-export { samePath } from "./same-path.ts";
+export { realPath, samePath } from "./same-path.ts";

package/dist/home/index.js

@@ -1,4 +1,4 @@
 // Where the player's data is (D-71): one folder for every chat, apart from the host's folder. Below the commands, beside the games and the profiles.
 export { dataFolder, tableFolder } from "./data-folder.js";
 export { openFolder } from "./open-folder.js";
-export { samePath } from "./same-path.js";
+export { realPath, samePath } from "./same-path.js";

package/dist/home/same-path.d.ts

@@ -1,2 +1,7 @@
-/** Whether two paths name the same folder: without regard to case on Windows. */
+/** Whether two paths name the same folder: as written, or through the links and junctions on their way; without regard to case on Windows. */
 export declare function samePath(one: string, other: string): boolean;
+/**
+ * A path with the links and junctions on its way followed, as a page's ports are counted from it: two names of one folder give one path. Case, drive
+ * letters and short names stay as written, so a path with no link stays as it was. A folder not made yet keeps the rest of its path as written.
+ */
+export declare function realPath(path: string): string;

package/dist/home/same-path.js

@@ -1,5 +1,24 @@
-import { resolve } from "node:path";
-/** Whether two paths name the same folder: without regard to case on Windows. */
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+/** Whether two paths name the same folder: as written, or through the links and junctions on their way; without regard to case on Windows. */
 export function samePath(one, other) {
-    return process.platform === "win32" ? resolve(one).toLowerCase() === resolve(other).toLowerCase() : resolve(one) === resolve(other);
+    // The same path as written needs no disk: only two different names may be one folder.
+    return sameText(resolve(one), resolve(other)) || sameText(realPath(one), realPath(other));
+}
+/**
+ * A path with the links and junctions on its way followed, as a page's ports are counted from it: two names of one folder give one path. Case, drive
+ * letters and short names stay as written, so a path with no link stays as it was. A folder not made yet keeps the rest of its path as written.
+ */
+export function realPath(path) {
+    const written = resolve(path);
+    try {
+        return realpathSync(written);
+    }
+    catch {
+        const parent = dirname(written);
+        return parent === written ? written : join(realPath(parent), basename(written));
+    }
+}
+function sameText(one, other) {
+    return process.platform === "win32" ? one.toLowerCase() === other.toLowerCase() : one === other;
 }

package/dist/host-files/host-files.d.ts

@@ -11,6 +11,11 @@ export declare function setUpHosts(folder: string, platform: string): string[];
 export declare function outdatedHostFiles(folder: string, platform: string): string[];
 /** Where Codex reads a folder's hooks, which it runs only once the player trusts them. */
 export declare function codexHooksPath(folder: string): string;
+/**
+ * Whether the host runs the doorbell's hook init writes, Claude Code and Codex by the names they give the server, so the player's act on the page wakes
+ * the chat; the command line, which names no host, is taken as one. Elsewhere the player tells the chat in its window.
+ */
+export declare function hasDoorbell(host: string | undefined): boolean;
 /** The instructions of the AI opponent, read from the package wherever it is installed: the MCP server's `instructions` tool gives them (D-102). */
 export declare function opponentInstructions(): string;
 /** The lines that start a chat, in the MCP server's instructions and in AGENTS.md: call `instructions`, then `status` (D-102). */