chesspal 0.2.3 → 0.3.0

package/dist/commands/ratings.js

@@ -0,0 +1,45 @@
+// The player's ratings read again from the sites (D-105, D-106): when their names there change, and when the page opens a day after the last reading;
+// never from a tool of the AI's.
+import { listProfiles, profileFolder, saveReadings } from "../profiles/index.js";
+import { readingsStale, readSites } from "../sites/index.js";
+/** A day, in milliseconds: the page reads the ratings again once they are older. */
+export const ratingsAge = 24 * 60 * 60 * 1000;
+/**
+ * Reads a profile's ratings again when its names on the sites changed, a site did not answer ten minutes ago or more, or the last reading is older than `olderThan`
+ * milliseconds: whether new readings were kept. One reading at a time of the same names in this process.
+ */
+export function refreshRatings(context, id, olderThan = Infinity) {
+    const home = context.home();
+    const profile = listProfiles(home).find((one) => one.id === id);
+    if (profile === undefined || context.fetch === undefined) {
+        return Promise.resolve(false);
+    }
+    const key = [home, id, profile.accounts?.lichess, profile.accounts?.chesscom].join("\n");
+    const going = reading.get(key);
+    if (going !== undefined) {
+        return going;
+    }
+    const read = readAgain(context, profile, context.fetch, olderThan).finally(() => reading.delete(key));
+    reading.set(key, read);
+    return read;
+}
+const reading = new Map();
+async function readAgain(context, { id, accounts, sites }, fetch, olderThan) {
+    const home = context.home();
+    const age = sites === undefined ? Infinity : context.now().getTime() - Date.parse(sites.read);
+    if (!readingsStale(sites, accounts, context.now()) && age < olderThan) {
+        return false;
+    }
+    if (accounts === undefined) {
+        saveReadings(profileFolder(home, id), undefined);
+        return true;
+    }
+    const read = await readSites(accounts, fetch, sites, context.now());
+    // The names may have changed while the sites answered: what they said of the names before is not kept, and the change reads its own.
+    const now = listProfiles(home).find((one) => one.id === id);
+    if (now?.accounts?.lichess !== accounts.lichess || now?.accounts?.chesscom !== accounts.chesscom) {
+        return false;
+    }
+    saveReadings(profileFolder(home, id), read);
+    return true;
+}

package/dist/commands/registry.d.ts

@@ -55,5 +55,5 @@ export declare function isBoolean(field: z.ZodType): boolean;
 export declare function isList(field: z.ZodType): boolean;
 /** The type of a field of a command's input, past optional, default and nullable: string, boolean, array… */
 export declare function baseType(field: z.ZodType): string;
-/** Whether a field takes numbers, alone or in a list: the command line reads them as text and turns them into numbers. */
+/** Whether a field takes numbers, alone, in a list or as one of its choices: the command line reads them as text and turns them into numbers. */
 export declare function takesNumbers(field: z.ZodType): boolean;

package/dist/commands/registry.js

@@ -37,10 +37,11 @@ export function isList(field) {
 export function baseType(field) {
     return baseDefinition(field).type;
 }
-/** Whether a field takes numbers, alone or in a list: the command line reads them as text and turns them into numbers. */
+/** Whether a field takes numbers, alone, in a list or as one of its choices: the command line reads them as text and turns them into numbers. */
 export function takesNumbers(field) {
     const definition = baseDefinition(field);
-    return definition.type === "number" || (definition.type === "array" && definition.element !== undefined && baseType(definition.element) === "number");
+    const numbers = (one) => one !== undefined && baseType(one) === "number";
+    return definition.type === "number" || (definition.type === "array" && numbers(definition.element)) || (definition.type === "union" && (definition.options ?? []).some(numbers));
 }
 function inputIssue(command, issue, given, written) {
     const path = issue.path.map(String).join(".");

package/dist/commands/say.d.ts

@@ -1,16 +1,21 @@
 import { type Mood } from "../core/index.ts";
-import { type Sayer, type Talk, type Words } from "../games/index.ts";
+import { type Sayer, type Shown, type Talk, type Words } from "../games/index.ts";
 import type { Context } from "./context.ts";
 /**
  * Adds a line to the talk of the current game, going on or just over, and saves it; the AI's mood once the game is over, which the archive keeps too (D-70).
  * With no game the line goes in the talk before it (D-77). A line refused changes nothing: it throws, in words for whoever spoke.
  */
-export declare function say(folder: string, who: Sayer, text: string, at: Date, mood?: Mood): Talk;
+export declare function say(folder: string, who: Sayer, text: string, at: Date, mood?: Mood, shown?: Shown): Talk;
+/** Words of the player's as the AI is given them: their text, and in analysis the move the board page showed as they wrote, 52...♚f6 (D-101). */
+export interface Written {
+    readonly text: string;
+    readonly place?: string;
+}
 /** What the player wrote on the board page that the AI has not been given in this chat, given now: each game tool gives it once; never to an agent (D-89). */
-export declare function newWords(context: Context): string[];
+export declare function newWords(context: Context): Written[];
 /** Every word of the player's the AI has not answered, given again: status gives them all, for a chat that lost them in a summary. */
-export declare function unansweredWords(context: Context): string[];
+export declare function unansweredWords(context: Context): Written[];
 /** What the player wrote on the board page that the AI has not been given in this chat, still to give: the AI's move would count as its answer. */
 export declare function waitingWords(context: Context, given?: ReadonlySet<string>): Words[];
-/** Gives the words to the AI: from now on they count as given in this chat. Their text. */
-export declare function give(context: Context, words: readonly Words[]): string[];
+/** Gives the words to the AI: from now on they count as given in this chat. Their text, with the move shown in analysis. */
+export declare function give(context: Context, words: readonly Words[]): Written[];

package/dist/commands/say.js

@@ -1,22 +1,24 @@
 // The talk on the board page (D-51): a line of the player's or the AI's, saved with the game, and the player's words the AI has not been given yet.
 import { endWithMood } from "../core/index.js";
-import { archiveEnded, endOf, loadGame, loadTableTalk, saveGame, saveTableTalk, talkLimits, talkLine, unheardWords } from "../games/index.js";
+import { archiveEnded, endOf, gameInAnalysis, loadGame, loadTableTalk, saveGame, saveTableTalk, talkLimits, talkLine, unheardWords } from "../games/index.js";
 import { gameFolder, helpsIn } from "../profiles/index.js";
+import { shownMove } from "./answer-lines.js";
 import { gameAt } from "./clock.js";
 /**
  * Adds a line to the talk of the current game, going on or just over, and saves it; the AI's mood once the game is over, which the archive keeps too (D-70).
  * With no game the line goes in the talk before it (D-77). A line refused changes nothing: it throws, in words for whoever spoke.
  */
-export function say(folder, who, text, at, mood) {
+export function say(folder, who, text, at, mood, shown) {
     const current = gameAt(folder, at);
     if (current === undefined) {
-        return sayAtTable(folder, who, text, at, mood);
+        return sayAtTable(folder, who, text, at, mood, shown);
     }
-    if (mood !== undefined && endOf(current.game) === undefined) {
+    const going = endOf(current.game) === undefined;
+    if (mood !== undefined && going) {
         throw new Error("While the game goes on your mood comes with ai_move: say it without mood. Nothing changed.");
     }
-    // With the helps on the AI writes as long as the analyst (D-78).
-    current.talk.push(talkLine(current, who, text, at, undefined, aiMost(folder, who, text)));
+    // With the helps on the AI writes as long as the analyst (D-78), and once the game is over as long, to talk it over (D-101).
+    current.talk.push(talkLine(current, who, text, at, undefined, aiMost(folder, who, text, going), shown));
     if (mood !== undefined) {
         endWithMood(current.game, mood);
     }
@@ -45,7 +47,7 @@ export function waitingWords(context, given = context.given) {
         return [];
     }
 }
-/** Gives the words to the AI: from now on they count as given in this chat. Their text. */
+/** Gives the words to the AI: from now on they count as given in this chat. Their text, with the move shown in analysis. */
 export function give(context, words) {
     const before = context.given.size;
     for (const { key } of words) {
@@ -54,14 +56,19 @@ export function give(context, words) {
     if (context.given.size > before) {
         context.heard?.();
     }
-    return words.map(({ text }) => text);
+    const analysed = words.some((word) => word.shown !== undefined) ? gameInAnalysis(gameFolder(context.home()))?.game : undefined;
+    return words.map(({ text, shown }) => shown === undefined ? { text } : { text, place: placeOf(shown, analysed) });
 }
-/** The most a line of the AI's may hold in the games of `folder`: an analyst's note with the helps on (D-78); a longer one with them off is refused. */
-function aiMost(folder, who, text) {
+/** Where the page stood: the move shown, as the player saw it, or the start; with the game's name when the page shows another now. */
+function placeOf({ game, move }, analysed) {
+    return `${move === undefined ? "the start" : shownMove(move)}${game === analysed ? "" : ` of ${game}`}`;
+}
+/** The most a line of the AI's may hold in the games of `folder`: an analyst's note with the helps on (D-78), or with no game going on (D-101); a longer one is refused. */
+function aiMost(folder, who, text, going) {
     if (who !== "ai") {
         return talkLimits.ai;
     }
-    if (helpsIn(folder)) {
+    if (!going || helpsIn(folder)) {
         return talkLimits.aiHelps;
     }
     if (text.trim().length > talkLimits.ai) {
@@ -70,7 +77,7 @@ function aiMost(folder, who, text) {
     return talkLimits.ai;
 }
 /** A line of the talk with no game, which starts it the first time; no mood, which only the end of a game takes. */
-function sayAtTable(folder, who, text, at, mood) {
+function sayAtTable(folder, who, text, at, mood, shown) {
     if (who === "agent") {
         throw new Error("There is no game to think on. Nothing changed.");
     }
@@ -78,7 +85,8 @@ function sayAtTable(folder, who, text, at, mood) {
         throw new Error("There is no game: a mood goes with a game's end. Say it without mood. Nothing changed.");
     }
     const before = loadTableTalk(folder);
-    const table = { started: before.started === "" ? at.toISOString() : before.started, talk: [...before.talk, talkLine(before, who, text, at, undefined, aiMost(folder, who, text))] };
+    const line = talkLine(before, who, text, at, undefined, aiMost(folder, who, text, false), shown);
+    const table = { started: before.started === "" ? at.toISOString() : before.started, talk: [...before.talk, line] };
     saveTableTalk(folder, table);
     return table;
 }

package/dist/commands/status.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { type GameSummary } from "./game-summary.ts";
+import { type Written } from "./say.ts";
 import { type Speech } from "./speech.ts";
 interface Status {
     version: string;
@@ -16,12 +17,13 @@ interface Status {
     /** Why the game on disk cannot be read, when it cannot. */
     problem?: string;
     /** What the player wrote on the board page that the AI has not answered yet, all of it. */
-    words?: string[];
+    words?: Written[];
     /** The game in analysis on the board page once none goes on (D-69), which the player may have brought there. */
     analysis?: {
         game: string;
         brought?: true;
-        analyst?: true;
+        analyst?: "done" | "offer";
+        review?: string;
     };
     /** A game going on from before this chat, told once a chat: the player says whether to go on with it. */
     fromBefore?: true;
@@ -29,6 +31,8 @@ interface Status {
     coach?: true;
     /** The files an older init wrote in the player's folder, which this version would write otherwise. */
     outdated?: string[];
+    /** The chat has not read the opponent's instructions since it started, or was cleared or summarized (D-102). */
+    unread?: true;
 }
 /** What Chesspal sees now, the first call of a chat: a dashboard under 150 tokens while the player is to move, with the next step. */
 export declare const status: import("./registry.ts").Command<z.ZodObject<{}, z.core.$strip>, Status>;

package/dist/commands/status.js

@@ -1,23 +1,26 @@
 import { z } from "zod";
+import { gameReviewOf, leadOf, reviewOf } from "../core/index.js";
 import { archivedName, cleanSince, endOf, gameInAnalysis, lastChatStart } from "../games/index.js";
-import { coachAgent, outdatedHostFiles } from "../host-files/index.js";
+import { outdatedHostFiles } from "../host-files/index.js";
 import { gameFolder } from "../profiles/index.js";
 import { version } from "../version.js";
-import { agentsLine, analystLine, analystRuns, coachOnEnd, coachRuns, reviewedLine, withAnalyst } from "./agents.js";
-import { closingLines, newGameStep, positionLines, sidesLine, wordLines } from "./answer-lines.js";
+import { analystLine, analystRuns, coachOnEnd, coachOnEndLine, coachRuns, goneOver, reviewedLine, withAnalyst } from "./agents.js";
+import { closingLines, newGameStep, positionLines, shownMoves, sidesLine, wordLines } from "./answer-lines.js";
 import { gameAt } from "./clock.js";
 import { summaryOf, withThought } from "./game-summary.js";
+import { instructionsRead } from "./instructions.js";
 import { levelText } from "./levels.js";
 import { closedPage, pageGiven, pageLine } from "./page-link.js";
 import { playerLine } from "./profiles.js";
 import { defineCommand } from "./registry.js";
 import { unansweredWords } from "./say.js";
 import { speechLine, speechOf } from "./speech.js";
+import { namedGame } from "./study.js";
 /** What Chesspal sees now, the first call of a chat: a dashboard under 150 tokens while the player is to move, with the next step. */
 export const status = defineCommand({
     name: "status",
     description: "Shows what Chesspal sees now: its version, the profile's folder and the game, with your next step. Call it at the start of every chat, "
-        + "before anything else.",
+        + "with `instructions`.",
     input: z.object({}),
     // Read only for the host: a flag that has fallen is written, as the time already decided.
     readOnly: true,
@@ -28,7 +31,10 @@ export const status = defineCommand({
         const folder = gameFolder(context.home());
         const player = playerLine(context);
         const speech = speechOf(folder, context.language);
-        const outdated = outdatedHostFiles(context.folder, context.platform);
+        const chatStart = lastChatStart(context.folder);
+        const first = firstInChat(context, chatStart?.at);
+        // An older init's files are told once a chat, at its first status: reading them all is the slowest part of a status.
+        const outdated = context.told === undefined || first ? outdatedHostFiles(context.folder, context.platform) : [];
         const status = { version, folder, ...(player === undefined ? {} : { player }), ...(speech === undefined ? {} : { speech }), ...(outdated.length === 0 ? {} : { outdated }) };
         if (context.page !== undefined) {
             status.page = context.page;
@@ -36,7 +42,9 @@ export const status = defineCommand({
         if (closedPage(context) !== undefined) {
             status.pageClosed = true;
         }
-        const first = firstInChat(context);
+        if (!instructionsRead(context, chatStart?.at)) {
+            status.unread = true;
+        }
         try {
             const current = gameAt(folder, context.now());
             // With no game the player may have written before the first (D-77).
@@ -49,7 +57,8 @@ export const status = defineCommand({
                 if (status.pageClosed === true) {
                     pageGiven(context, current.started);
                 }
-                if (first && endOf(current.game) === undefined && fromBeforeChat(context, current.started)) {
+                // A game a summarized or resumed chat still holds is its own; without the host's word of the chat's start, any game began before it.
+                if (first && endOf(current.game) === undefined && (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).
@@ -59,8 +68,14 @@ export const status = defineCommand({
             }
             const analysis = current === undefined || status.game?.end !== undefined ? gameInAnalysis(folder) : undefined;
             if (analysis !== undefined) {
-                // The analyst agent goes over a game the player brought, where it runs, and the chat over what it reviewed (D-89).
-                status.analysis = { game: analysis.game, ...(analysis.brought === true ? { brought: true } : {}), ...(analystRuns(context) ? { analyst: true } : {}) };
+                // The analyst agent goes over a game the player brought, or whose review was deleted, where it runs, and the chat over what it reviewed (D-89).
+                const review = analysis.brought === true ? undefined : reviewProgress(context, analysis.game);
+                status.analysis = {
+                    game: analysis.game,
+                    ...(analysis.brought === true ? { brought: true } : {}),
+                    ...(analystRuns(context) ? { analyst: goneOver(context, analysis.game) ? "done" : "offer" } : {}),
+                    ...(review === undefined ? {} : { review }),
+                };
             }
         }
         catch (error) {
@@ -68,8 +83,9 @@ export const status = defineCommand({
         }
         return status;
     },
-    format: ({ version, folder, page, pageClosed, player, speech, game, problem, words = [], analysis, fromBefore, coach, outdated }) => [
+    format: ({ version, folder, page, pageClosed, player, speech, game, problem, words = [], analysis, fromBefore, coach, outdated, unread }) => [
         `Chesspal ${version}. Folder: ${folder}`,
+        ...(unread === true ? [unreadLine] : []),
         ...(outdated === undefined ? [] : [outdatedLine(outdated)]),
         ...(page === undefined ? [] : [pageLine(page, pageClosed === true)]),
         ...(player === undefined ? [] : [player]),
@@ -84,45 +100,73 @@ function outdatedLine(files) {
     return `This folder was set up by an older Chesspal (${files.join(", ")}): tell the player, in their language, to close this chat, run "chesspal init" `
         + "in this folder and open a new chat. Until then the agents and your instructions are the old ones.";
 }
+// The opponent's instructions, which the chat reads before its first reply (D-102).
+const unreadLine = "Call `instructions` before you answer the player, if you have not called it since this chat started or was summarized.";
 // The game going on as a chat starts: the player may have come back for it, or want another.
 const fromBeforeLine = "A game from before this chat is going on: ask the player whether to go on with it. For a new one, " + newGameStep;
 /**
  * Whether this is the chat's first status: once a chat where the MCP server keeps what it told, again in a chat cleared or summarized, since its start keys
  * it (D-57); never on the command line.
  */
-function firstInChat(context) {
-    const key = `game before ${lastChatStart(context.folder)?.at ?? ""}`;
+function firstInChat(context, chatStart) {
+    const key = `game before ${chatStart ?? ""}`;
     if (context.told === undefined || context.told.has(key)) {
         return false;
     }
     context.told.add(key);
     return true;
 }
-/** Whether a game began before the chat: one a summarized or resumed chat still holds is its own; without the host's word, any game is. */
-function fromBeforeChat(context, started) {
-    const start = lastChatStart(context.folder);
-    return start === undefined || cleanSince(start, started);
-}
-/** The game in analysis; the next step when the player has just brought it on the board page. */
-function analysisLine({ game, brought, analyst }) {
-    if (brought === true) {
-        return analyst === true
+/**
+ * The game in analysis, with how far its review has got; the next step when the player has just brought it on the board page, unless an analyst is at it
+ * already; the analyst agent for a game whose review was deleted, where it runs (Stefano).
+ */
+function analysisLine({ game, brought, analyst, review }) {
+    if (brought === true && analyst !== "done") {
+        return analyst === "offer"
             ? `The player brought ${game} on the board page to analyse it. Next: ${analystLine(game)}`
             : `The player brought ${game} on the board page to analyse it. Next: call analyse_game {"game": "${game}"}, then keep your review on that page with annotate_game, and go over it with them.`;
     }
-    return analyst === true
-        ? `In analysis on the board page: ${game}. ${reviewedLine(game)}`
-        : `In analysis on the board page: ${game}; analyse_game {"game": "${game}"} goes over it with the player.`;
+    const shown = `In analysis on the board page: ${game}${review === undefined ? "" : ` (${review})`}`;
+    if (analyst === "done") {
+        return `${shown}. ${reviewedLine(game)}`;
+    }
+    return analyst === "offer" ? `${shown}. When the player wants it gone over, ${analystLine(game)}` : `${shown}; analyse_game {"game": "${game}"} goes over it with the player.`;
+}
+/**
+ * How far the review of a game has got, as the board page shows it (Priya): done once it holds the word on the whole game and who is ahead after every move
+ * but the last; the analyst may still write notes after its word, so that alone is not the end.
+ */
+function reviewProgress(context, game) {
+    try {
+        const { record } = namedGame(context, game);
+        const worded = gameReviewOf(record) !== undefined;
+        const estimated = record.moves.filter(({ comment }) => leadOf(comment) !== undefined).length;
+        if (worded && estimated >= record.moves.length - 1) {
+            return "its review is done";
+        }
+        const noted = record.moves.filter(({ comment }) => {
+            const review = reviewOf(comment);
+            return review !== undefined && (review.badge !== "book" || review.note !== undefined);
+        }).length;
+        const word = worded ? ", its word on the game written" : "";
+        return noted === 0 && estimated === 0 && !worded
+            ? "no review yet"
+            : `its review so far: notes on ${noted} moves, who is ahead after ${estimated} of ${record.moves.length}${word}`;
+    }
+    catch {
+        return undefined;
+    }
 }
 /**
  * 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 ? [agentsLine([coachAgent])] : []), ...(brought ? wordLines(words) : closingLines(game, words, pageClosed))];
+    const closing = [...(coach ? [coachOnEndLine] : []), ...(brought ? wordLines(words) : closingLines(game, words, pageClosed))];
     if (game === undefined) {
         return ["No game.", ...closing];
     }
-    const moves = game.lastMoves === "" ? [] : [`Moves: ${game.lastMoves}`];
+    // With the figurines, as every answer writes moves: in letters the AI copied them into its message (Priya).
+    const moves = game.lastMoves === "" ? [] : [`Moves: ${shownMoves(game.lastMoves)}`];
     return [`Game: ${sidesLine(game.ai)}, ${levelText(game.level)}.`, ...moves, ...positionLines(game), ...closing];
 }

package/dist/commands/study.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { Game, type GameRecord } from "../core/index.ts";
-import { type CurrentGame } from "../games/index.ts";
+import { type CurrentGame, type Shown } from "../games/index.ts";
 import type { Context } from "./context.ts";
 /** What look and position take to show any position of a game that is over. */
 export declare const studyInput: {
@@ -21,10 +21,20 @@ export interface StudiedPosition {
 export declare function noGameGoingOn(context: Context): CurrentGame | undefined;
 /** The game played or kept to study by that name; without one, the current game over, or else the latest of the archive; refused while a game goes on. */
 export declare function gameToStudy(context: Context, name?: string): Studied;
+/**
+ * The game look and position show: without a name, for the chat, the one in analysis on the board page, which the player's words there name by their move
+ * alone (D-101, Priya); else as gameToStudy. An agent names its game, since the page may turn to another meanwhile.
+ */
+export declare function gameShown(context: Context, name?: string): Studied;
 /** A game played or kept to study by its name as the lists write it, or without its folder or its .pgn; refused when it is not there. */
 export declare function namedGame(context: Context, name: string): Required<Studied>;
 /** The index of a move in the game's record, given as analyse_game numbers it: 12. for White's, 12... for Black's, 12...Kf8 too. */
 export declare function moveIndex(record: GameRecord, move: string): number;
+/**
+ * A position of a game over as the board page shows it in analysis (D-101): the game's name, how many of its moves it shows, and the last of them numbered;
+ * none for a game or a position there is not, or while a game goes on.
+ */
+export declare function shownPosition(context: Context, game: string, at: number): Shown | undefined;
 /** The number of each move of a game as the analysis writes it: 1. for White's first move, 1... for Black's. */
 export declare function moveNumbers(record: GameRecord): string[];
 /**

package/dist/commands/study.js

@@ -2,13 +2,13 @@
 // goes on, nothing is studied: the analysis would help the game being played (D-60, D-62).
 import { z } from "zod";
 import { Game } from "../core/index.js";
-import { archivedGame, archivedGames, archivedName, endOf, keptGame, listedName } from "../games/index.js";
+import { archivedGame, archivedGames, archivedName, endOf, gameInAnalysis, keptGame, listedName } from "../games/index.js";
 import { gameFolder } from "../profiles/index.js";
 import { gameAt } from "./clock.js";
 import { colourName } from "./view.js";
 /** What look and position take to show any position of a game that is over. */
 export const studyInput = {
-    game: z.string().optional().describe("a game's name, as past_games, study_games or analyse_game writes it: one of its positions"),
+    game: z.string().optional().describe("a game's name, as past_games, study_games or analyse_game writes it: one of its positions; without it, the game on the board page"),
     move: z.string().optional().describe("the position after this move of a game over, as analyse_game numbers it: 12. for White's, 12... for Black's"),
 };
 /** The current game when it is over, or none; refused while it goes on, for every game: games are analysed once the one being played is over. */
@@ -27,16 +27,31 @@ export function gameToStudy(context, name) {
     if (name !== undefined) {
         return namedGame(context, name);
     }
-    if (current !== undefined) {
+    // A game closed before any move has nothing to study: the one before it is the last played.
+    if (current !== undefined && current.game.record.moves.length > 0) {
         // The archive's record, which keeps the AI's review (D-69).
         const archived = archivedName(folder, current);
         return archived === undefined ? { record: current.game.record } : { record: archivedGame(folder, archived), name: archived };
     }
-    const [latest] = archivedGames(folder);
-    if (latest === undefined) {
-        throw new Error("There is no game to study: play one with new_game, or give analyse_game the PGN of a game played elsewhere.");
+    for (const latest of archivedGames(folder)) {
+        const record = archivedGame(folder, latest);
+        if (record.moves.length > 0) {
+            return { record, name: latest };
+        }
     }
-    return { record: archivedGame(folder, latest), name: latest };
+    throw new Error("There is no game to study: play one with new_game, or give analyse_game the PGN of a game played elsewhere.");
+}
+/**
+ * The game look and position show: without a name, for the chat, the one in analysis on the board page, which the player's words there name by their move
+ * alone (D-101, Priya); else as gameToStudy. An agent names its game, since the page may turn to another meanwhile.
+ */
+export function gameShown(context, name) {
+    const analysis = name === undefined && context.agent === undefined ? gameInAnalysis(gameFolder(context.home())) : undefined;
+    if (analysis === undefined) {
+        return gameToStudy(context, name);
+    }
+    noGameGoingOn(context);
+    return namedGame(context, analysis.game);
 }
 /** A game played or kept to study by its name as the lists write it, or without its folder or its .pgn; refused when it is not there. */
 export function namedGame(context, name) {
@@ -48,6 +63,23 @@ export function namedGame(context, name) {
 export function moveIndex(record, move) {
     return plyOf(record, moveNumbers(record), move);
 }
+/**
+ * A position of a game over as the board page shows it in analysis (D-101): the game's name, how many of its moves it shows, and the last of them numbered;
+ * none for a game or a position there is not, or while a game goes on.
+ */
+export function shownPosition(context, game, at) {
+    try {
+        noGameGoingOn(context);
+        const { name, record } = namedGame(context, game);
+        if (!Number.isInteger(at) || at < 0 || at > record.moves.length) {
+            return undefined;
+        }
+        return at === 0 ? { game: name, at } : { game: name, at, move: `${moveNumbers(record)[at - 1]}${record.moves[at - 1].san}` };
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The number of each move of a game as the analysis writes it: 1. for White's first move, 1... for Black's. */
 export function moveNumbers(record) {
     const start = new Game({ tags: record.tags, moves: [] }).position;

package/dist/commands/view.d.ts

@@ -1,10 +1,22 @@
-import type { Facts, Material, Side } from "../core/index.ts";
-/** The view after the player's move: the check, the pieces attacked, then what is at risk, the pins, the checks and the moves of each piece. */
-export declare function compactView(facts: Facts, turn: Side): string[];
+import type { Chances, Facts, Material, Possibilities, Side } from "../core/index.ts";
+/** What the moves would do (D-100), and the other side's threats, none in check. */
+export interface Possible {
+    readonly possibilities: Possibilities;
+    readonly threats: Chances | undefined;
+    /** The level sees the threats' double attacks and discovered checks, and the stalemate traps: from the strong level up. */
+    readonly strong: boolean;
+}
+/**
+ * The view after the player's move, in the masters' order (D-100): the check, the checks, the captures, the threats, what the moves would do, the pins,
+ * skewers and loose pieces, the pieces attacked, the moves of each piece.
+ */
+export declare function compactView(facts: Facts, turn: Side, possible?: Possible): string[];
 /** The view of a level without the tactical facts (D-60): the check and the legal moves by piece, which are the rules (D-17). */
 export declare function boardView(facts: Facts, turn: Side): string[];
-/** The whole view, for look: every piece with its attackers and defenders, then the same lines as the compact view. */
-export declare function fullView(facts: Facts, turn: Side): string[];
+/** The whole view, for look: the same lines as the compact view, with every piece's attackers and defenders. */
+export declare function fullView(facts: Facts, turn: Side, possible?: Possible): string[];
+/** What the moves of the side to move would do, in one line for a move of the analysis: fork Nc7+ (Ke8 Ra8); stalemate Qf7; none when nothing. */
+export declare function tacticsText(facts: Facts, possibilities: Possibilities, withTraps: boolean): string | undefined;
 /** What is at risk, in one line for a move of the analysis (D-68): undefended Black Nf6; by a cheaper piece White Qd1; outnumbered Black Pe5; none when nothing is. */
 export declare function riskLine(facts: Facts): string | undefined;
 export declare function colourName(side: Side): string;