chesspal 0.0.1 → 0.2.0

package/dist/commands/answer-lines.js

@@ -0,0 +1,144 @@
+// The lines an AI reads in a tool's answer about the current game: where it stands, the move just played, the player's words and what to do next.
+import { figurinesOf, materialOf, sees } from "../core/index.js";
+import { talkLimits } from "../games/index.js";
+import { onQuickModel } from "../host-files/index.js";
+import { analystLine, reviewedLine } from "./agents.js";
+import { clockLine } from "./clock.js";
+import { endText } from "./game-summary.js";
+import { boardView, colourName, compactView, materialText } from "./view.js";
+/** Where the game stands: the AI's position to decide on, with its last move unless the lines before named it; the player's turn; or how it ended. */
+export function positionLines(game, withLastMove = true) {
+    if (game.end !== undefined || game.turn !== game.ai) {
+        return [whereLine(game), ...offerLines(game), ...clockLines(game), ...moodLines(game)];
+    }
+    return [
+        ...headLines(game, withLastMove),
+        ...(game.facts === undefined ? [] : (sees(game.level, "tactics") ? compactView : boardView)(game.facts, game.turn)),
+        ...(game.book === undefined ? [] : [`Book moves, most named lines first: ${game.book.join(", ")}`]),
+        ...(game.plan === undefined ? [] : [`Plan: ${game.plan}`]),
+        ...(game.thought === undefined ? [] : [thoughtLine(game.thought, game.level)]),
+        ...moodLines(game),
+        ...(game.helps === "coached" ? [`${helpsLine} ${coachLine}`] : game.helps === "on" ? [helpsLine] : game.helps === "off now" ? [helpsOffLine] : []),
+    ];
+}
+/** The helps turned on: the AI may teach as the analyst does (D-62, D-78), never playing for the player. */
+const helpsLine = "Helps on: the player wants to learn. Tell your intentions, never their best move; draw arrows and squares to show what you say, and write up to "
+    + `${talkLimits.aiHelps} characters.`;
+/**
+ * Where a coach runs, a coach, not the AI, judges the player's moves, and the AI knows it, so that it neither makes up what the coach said nor looks for it
+ * (D-88, Priya); where none runs, nobody judges them before the analyst (D-80).
+ */
+const coachLine = "A coach, not you, judges their moves and gives them hints on the board page; you don't see what it writes.";
+/** The helps turned off during a game: what the AI said and drew before no longer holds (Priya, round of D-78). */
+const helpsOffLine = `Helps off now: play as at a tournament again: no intentions or arrows, comments of ${talkLimits.ai} characters at most.`;
+/** The head of a view: where the game stands, the last move unless the lines before named it, the opening, the material as the player sees it, and the FEN. */
+export function headLines(game, withLastMove = true) {
+    return [
+        whereLine(game),
+        ...offerLines(game),
+        ...(withLastMove && game.lastMove !== undefined ? [`Last move: ${lastMoveText(game.lastMove)}.`] : []),
+        ...(game.opening === undefined ? [] : [`Opening: ${game.opening}`]),
+        `Material: ${materialText(materialOf(game.fen))}`,
+        ...clockLines(game),
+        `FEN: ${game.fen}`,
+    ];
+}
+/** The last move, as the player is shown it, with its squares: 4.♞g5 (f3-g5). */
+export function lastMoveText({ move, from, to }) {
+    return `${shownMove(move)} (${from}-${to})`;
+}
+/**
+ * A numbered move as the player is shown it, with the pieces' figurines (D-86): the form alone, without the SAN, which the AI copied into its message
+ * (Priya, test of D-86): 4.Ng5 is 4.♞g5.
+ */
+export function shownMove(move) {
+    const [, number = "", san = move] = /^(\d+\.+)(.+)$/.exec(move) ?? [];
+    return `${number}${figurinesOf(san)}`;
+}
+/** The lines after a move, which the line before named: its note, where the game stands, a warning. closingLines end them. */
+export function moveLines({ note, game, warning }) {
+    return [...(note === undefined ? [] : [`Note: ${note}`]), ...positionLines(game, false), ...(warning === undefined ? [] : [warning])];
+}
+/** The last lines of a tool's answer: the player's words from the board page, then the next step, which stays the last line. */
+export function closingLines(game, words = [], pageClosed = false) {
+    return [...wordLines(words), nextStep(game, words, pageClosed)];
+}
+/** The player's words from the board page, one line each: lines they broke are joined, so no line of theirs reads as one of Chesspal's. */
+export function wordLines(words) {
+    return words.map((text) => `Player wrote on the board page: «${text.replace(/\s+/g, " ")}»`);
+}
+/**
+ * What the AI does next: the one line every host reads, even where the server's instructions are not shown. Words of the player's ask for an answer. With the
+ * board page open in no browser, a new game starts there, never in the chat.
+ */
+export function nextStep(game, words = [], pageClosed = false) {
+    const step = pageClosed ? closedPageGameStep : newGameStep;
+    if (game === undefined) {
+        return words.length === 0 ? `Next: when the player wants a game, ${step}` : `Next: answer the player with ai_say. When they want a game, ${step}`;
+    }
+    if (game.end !== undefined) {
+        const analysis = game.end.analyst === "offer"
+            ? ` To go over it, on their yes, ${analystLine(game.end.archive)}`
+            : game.end.analyst === "done"
+                ? ` ${reviewedLine(game.end.archive)}`
+                : "";
+        return words.length === 0
+            ? "Next: tell the player how the game ended, with ai_say and how you feel as its mood if they play on the board page; then offer them, in words, another game or "
+                + `to go over this one${analysis === "" ? " (analyse_game)." : `.${analysis}`} For another, ${step}`
+            : `Next: answer the player with ai_say.${analysis} When they want another game, ${step}`;
+    }
+    if (game.turn === game.ai && game.clock?.waiting === true) {
+        return "Next: don't move yet: the player starts the game with Start on the board page, and the doorbell wakes you then. End your turn.";
+    }
+    if (game.turn === game.ai) {
+        return words.length === 0
+            ? "Next: choose your move, then call ai_move with it, your plan and any comment."
+            : "Next: choose your move, then call ai_move with it, your plan and a comment that answers the player.";
+    }
+    if (game.drawOffer === "player") {
+        return "Next: accept the draw with end_game draw_agreed, or answer with ai_say and wait for the player's move.";
+    }
+    return words.length === 0 ? "Next: wait for the player's move, then call player_move with it." : "Next: answer the player with ai_say, then wait for their move.";
+}
+/** How a new game starts: the player chooses it in the board page's window, which new_game without choices opens (D-85). */
+export const newGameStep = "call new_game without choices: it opens the board page's New game window, where the player chooses the colour, the clock and the level.";
+// With the page open in no browser the window cannot open: the player opens the page and presses New game.
+const closedPageGameStep = "they start it on the board page with its New game button, where they choose the colour, the clock and the level: tell them so with "
+    + "the page's address, and never offer to set it up in the chat.";
+/** Who plays what, from the AI's side. */
+export function sidesLine(ai) {
+    return `you play ${colourName(ai)}, the player ${colourName(ai === "white" ? "black" : "white")}`;
+}
+/** The draw offer that stands, and how to answer it or what becomes of it (D-65). */
+function offerLines({ drawOffer, turn, ai }) {
+    if (drawOffer === "ai") {
+        return ["Your draw offer stands until the player moves; if they accept it in the chat, end_game draw_agreed ends the game."];
+    }
+    if (drawOffer === "player") {
+        return [turn === ai ? "The player offers a draw: end_game draw_agreed accepts it; your move declines it." : "The player offers a draw before their move; your next move declines it."];
+    }
+    return [];
+}
+/** What the AI thought on the player's time, saying by which model and that Chesspal checked only that it is legal: the facts do not cover every blunder (Anatolij). */
+function thoughtLine({ move, why }, level) {
+    return `Thought on their time ${onQuickModel(level) ? "by a quicker model" : "by your model"} (legal, not checked): ${move}, ${why}`;
+}
+/** The AI's mood while it lasts, and how long its face shows it (D-70). */
+function moodLines({ mood }) {
+    if (mood === undefined) {
+        return [];
+    }
+    const shown = mood.left === 0 ? "until your next move" : `for ${mood.left} more of your moves`;
+    return [`Your mood: ${mood.mood}, on your face ${shown}, then neutral by itself.`];
+}
+/** Who is to move, or how the game ended. */
+function clockLines(game) {
+    return game.clock === undefined ? [] : [clockLine(game.clock, game.ai)];
+}
+function whereLine(game) {
+    if (game.end !== undefined) {
+        const archived = game.end.archive === undefined ? "" : ` Archived in ${game.end.archive}.`;
+        return `Game over: ${endText(game.end)}.${archived}`;
+    }
+    return `${game.turn === game.ai ? "You" : "Player"} (${colourName(game.turn)}) to move, move ${game.moveNumber}.`;
+}

package/dist/commands/clock.d.ts

@@ -0,0 +1,15 @@
+import { type Side } from "../core/index.ts";
+import { type CurrentGame } from "../games/index.ts";
+/** What the AI reads of the clock: the time control, and the time each side has left when the command ran, in milliseconds. */
+export interface ClockSummary {
+    control: string;
+    left: Record<Side, number>;
+    /** The clocks wait for the player to start them. */
+    waiting?: true;
+}
+/** The current game of a folder `now`, or undefined: a game whose side to move has run out of time is over, saved and archived first. */
+export declare function gameAt(folder: string, now: Date): CurrentGame | undefined;
+/** The clock of a game `now`, as the AI reads it; none in a game without one. */
+export declare function clockSummaryOf(current: CurrentGame, now: Date): ClockSummary | undefined;
+/** The clock's line: Clock: you 4:32, player 5:01 (10+5), and whether the clocks still wait for the player. */
+export declare function clockLine({ control, left, waiting }: ClockSummary, ai: Side): string;

package/dist/commands/clock.js

@@ -0,0 +1,45 @@
+// The clock in the commands (D-13): a flag that falls ends the game as soon as a command reads it, and the clock's line for the AI.
+import { canMate, clockText, Game, timeControlText, timeLeft } from "../core/index.js";
+import { archiveEnded, endOf, loadGame, saveGame } from "../games/index.js";
+import { colourName } from "./view.js";
+/** The current game of a folder `now`, or undefined: a game whose side to move has run out of time is over, saved and archived first. */
+export function gameAt(folder, now) {
+    const current = loadGame(folder);
+    if (current?.clock === undefined || endOf(current.game) !== undefined) {
+        return current;
+    }
+    const { turn } = current.game.position;
+    if (timeLeft(current.clock, turn, now)[turn] > 0) {
+        return current;
+    }
+    const ended = outOfTime(current, turn, now);
+    saveGame(folder, ended);
+    // An archive that cannot be written leaves the game in game.json, where status shows it, until a new game archives it.
+    archiveEnded(folder, ended);
+    return ended;
+}
+/** The clock of a game `now`, as the AI reads it; none in a game without one. */
+export function clockSummaryOf(current, now) {
+    const { clock, game } = current;
+    if (clock === undefined) {
+        return undefined;
+    }
+    const left = endOf(game) === undefined ? timeLeft(clock, game.position.turn, now) : { ...clock.left };
+    return { control: timeControlText(clock.control), left, ...(clock.waiting === true && endOf(game) === undefined ? { waiting: true } : {}) };
+}
+/** The clock's line: Clock: you 4:32, player 5:01 (10+5), and whether the clocks still wait for the player. */
+export function clockLine({ control, left, waiting }, ai) {
+    const player = ai === "white" ? "black" : "white";
+    const line = `Clock: you ${clockText(left[ai])}, player ${clockText(left[player])} (${control}).`;
+    return waiting === true ? `${line} The clocks wait: they start with the player's first move, or with Start on the board page when your move is first.` : line;
+}
+/** The game lost on time by `loser`, or drawn when the other side could not mate with any series of legal moves (FIDE 6.9). */
+function outOfTime(current, loser, now) {
+    const winner = loser === "white" ? "black" : "white";
+    const ending = canMate(current.game.position.fen, winner)
+        ? { Result: loser === "white" ? "0-1" : "1-0", Termination: `${colourName(loser)} lost on time` }
+        : { Result: "1/2-1/2", Termination: `${colourName(loser)} ran out of time and ${colourName(winner)} cannot mate` };
+    const { record } = current.game;
+    const clock = { ...current.clock, left: { ...current.clock.left, [loser]: 0 }, since: now.toISOString() };
+    return { ...current, game: new Game({ ...record, tags: { ...record.tags, ...ending } }), clock };
+}

package/dist/commands/coach.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/** What coach answers: stop, the moves to work on, the words kept and what comes next, or still the player's move; with the game's key and the position. */
+type Coached = {
+    stop: "moved" | "waited" | "helps" | "started";
+} | {
+    start: string[];
+} | {
+    kept: Place;
+    then: "lead" | "wait" | "moved" | "over";
+    saved: string[];
+    hintLeft: boolean;
+} | {
+    waiting: Place;
+};
+/** The game, by its key, and the position in it the coach works on. */
+interface Place {
+    readonly game: string;
+    readonly position: number;
+}
+/**
+ * The coach (D-80, D-88), for the agent that judges the player's moves and gives them hints with the helps on: every fact, never the opponent's plan; its
+ * words go to the board page alone, never to the opponent. Its calls are not the chat's, and the server refuses them from the chat. Offered to Claude Code alone.
+ */
+export declare const coach: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodOptional<z.ZodString>;
+    position: z.ZodOptional<z.ZodInt>;
+    ahead: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    badge: z.ZodOptional<z.ZodEnum<{
+        brilliant: "brilliant";
+        great: "great";
+        best: "best";
+        excellent: "excellent";
+        good: "good";
+        inaccuracy: "inaccuracy";
+        mistake: "mistake";
+        miss: "miss";
+        blunder: "blunder";
+    }>>;
+    note: z.ZodOptional<z.ZodString>;
+    hint: z.ZodOptional<z.ZodString>;
+    arrows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    squares: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    done: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, Coached>;
+export {};

package/dist/commands/coach.js

@@ -0,0 +1,344 @@
+import { z } from "zod";
+import { badges, Game, leadText, levelOf, materialOf, withSanLetters } from "../core/index.js";
+import { archiveCoached, coachWaitingSince, coachWords, endOf, keepHint, keepJudgment, keepLead, loadGame, startCoach } from "../games/index.js";
+import { coachAgent } from "../host-files/index.js";
+import { activeProfile, gameFolder, helpsIn } from "../profiles/index.js";
+import { clockLine, clockSummaryOf } from "./clock.js";
+import { arrowsInput, drawingsOf, noteInput, squaresInput } from "./drawings.js";
+import { lastMoves } from "./game-summary.js";
+import { aheadWords, leadFrom, leadInput } from "./lead-input.js";
+import { knownMoves, openingLine } from "./opening-book.js";
+import { waitForPlayer, wordsOf } from "./ponder.js";
+import { profileLines } from "./position.js";
+import { defineCommand } from "./registry.js";
+import { speechLine, speechOf } from "./speech.js";
+import { colourName, compactView, materialText, riskLine } from "./view.js";
+// The badges the coach gives: the book's is Chesspal's, never a judgment (D-69).
+const judgments = badges.filter((badge) => badge !== "book");
+/**
+ * The coach (D-80, D-88), for the agent that judges the player's moves and gives them hints with the helps on: every fact, never the opponent's plan; its
+ * words go to the board page alone, never to the opponent. Its calls are not the chat's, and the server refuses them from the chat. Offered to Claude Code alone.
+ */
+export const coach = defineCommand({
+    name: "coach",
+    description: "For the chesspal-coach agent only, never from the chat: Chesspal's answers say when to start it. coach {} gives the player's move to judge and the position "
+        + "they are to move in; coach {game, position, ahead, badge, note, hint, arrows, squares} keeps who is ahead there, while the game goes on, and your judgment and your hint, "
+        + "each only when there is something to say; coach {game, position, done: true} waits for their move, once who is ahead is kept. Whenever it says stop, stop. "
+        + 'Example: coach {game: "t3k9qa", position: 24, ahead: -0.8, badge: "mistake", note: "It leaves the d5 pawn without a defender.", hint: "Look at what defends their king now."}.',
+    input: z.object({
+        game: z.string().optional().describe("the game's key, as coach {} gives it"),
+        position: z.int().min(0).optional().describe("the position's number, as coach {} gives it"),
+        ahead: leadInput.optional().describe("who is ahead in the position the player is to move in, for the page's bar: pawns from White's side, 1.5 for White, -3 for Black, 0 for even, or a mate "
+            + 'you see in moves of the side that mates, "#3" for White\'s, "#-3" for Black\'s'),
+        badge: z.enum(judgments).optional().describe("your badge on the player's move, as chess.com names them, only on a move that stands out, never on a routine one"),
+        note: noteInput.optional().describe("why, on the player's move, in a sentence or two, in their language"),
+        hint: noteInput.optional().describe("a hint for their turn, in a sentence or two, in their language, only when there is something to find: what is on the board (a piece, a square, a file, a "
+            + "threat of the opponent's, a goal), never what to play"),
+        arrows: arrowsInput.describe("only with a hint: arrows on the board as it is now, never a move the player can play: Rf2e1; R red: a threat of the opponent's; B blue: a plan or a target; "
+            + "Y yellow: a line; G green: a good idea"),
+        squares: squaresInput.describe("only with a hint: squares to mark on the board as it is now: Rf2; colours as for arrows"),
+        done: z.boolean().optional().describe("true once you have kept your words, who is ahead always while the game goes on: it waits for the player's move"),
+    }),
+    byAgents: [coachAgent],
+    host: "claude-code",
+    run: async ({ game, position, ahead, badge, note, hint, arrows, squares, done = false }, context) => {
+        const folder = gameFolder(context.home());
+        const current = loadGame(folder);
+        const words = { ahead, badge, note, hint, arrows, squares };
+        const writes = Object.values(words).some((word) => word !== undefined);
+        if (!helpsIn(folder)) {
+            return { stop: "helps" };
+        }
+        if (game === undefined || position === undefined) {
+            if (writes || done || game !== undefined || position !== undefined) {
+                throw new Error("Give the game's key and the position's number with it: call coach {} first, which gives them. Nothing changed.");
+            }
+            const start = current === undefined ? undefined : startOf(current, folder, context);
+            if (start === undefined || current === undefined) {
+                return { stop: "moved" };
+            }
+            // The chat may start a second coach on the same position, told again before the first called: one judges it (Priya).
+            return startCoach(folder, current) ? { start } : { stop: "started" };
+        }
+        // A new game may have started while the coach thought on the last one: its words never go to another game (Federico).
+        if (current === undefined || gameKey(current) !== game || position > current.game.record.moves.length) {
+            return { stop: "moved" };
+        }
+        const place = { game, position };
+        if (!done) {
+            return keep(folder, current, place, words);
+        }
+        if (writes) {
+            throw new Error(`Keep your words first, then call ${call(place, "done: true")} alone. Nothing changed.`);
+        }
+        // The bar on the page needs who is ahead in every position the player is to move in while the game goes on (D-90, Stefano).
+        if (leadMissing(folder, current, position)) {
+            throw new Error(`Who is ahead is still missing here: first ${aheadCall(place)}, then ${call(place, "done: true")}. Nothing changed.`);
+        }
+        const since = coachWaitingSince(folder, current, position, context.now());
+        const waited = await waitForPlayer(context, since, () => !theirTurn(loadGame(folder), place));
+        return waited === "waiting" ? { waiting: place } : { stop: waited };
+    },
+    format: (coached) => {
+        if ("stop" in coached) {
+            return coached.stop === "helps"
+                ? "Stop now: the player has turned the helps off. End with one word."
+                : coached.stop === "started"
+                    ? "Stop now: another coach works on this position. End with one word."
+                    : coached.stop === "moved"
+                        ? "Stop now: the player has moved, or the game is over. End with one word."
+                        : "Stop now: you have waited long enough. End with one word.";
+        }
+        if ("start" in coached) {
+            return coached.start.join("\n");
+        }
+        if ("kept" in coached) {
+            return keptText(coached);
+        }
+        return `Still the player's move: call ${call(coached.waiting, "done: true")} again.`;
+    },
+});
+/**
+ * What a call kept, and what comes next: who is ahead when it is still missing, then wait for the player's move; or stop, as they have moved or the game is
+ * over, with the hint that came too late.
+ */
+function keptText({ kept, then, saved, hintLeft }) {
+    const what = saved.length === 0 ? "nothing" : saved.join(", ");
+    if (then === "lead") {
+        return `Kept on the board page: ${what}. Who is ahead is still missing: now ${aheadCall(kept)}, then ${call(kept, "done: true")} alone.`;
+    }
+    if (then === "wait") {
+        return `Kept on the board page: ${what}. Now call ${call(kept, "done: true")} alone.`;
+    }
+    const late = hintLeft ? ", so your hint is not kept" : "";
+    return then === "moved"
+        ? `Kept: ${what}; the player has moved${late}. Stop now: end with one word.`
+        : `Kept for the game's record: ${what}; the game is over${late}. Stop now: end with one word.`;
+}
+/** A call of coach on a game's position, with what else it gives. */
+function call({ game, position }, rest) {
+    return `coach {game: "${game}", position: ${position}, ${rest}}`;
+}
+/** The call that gives who is ahead, with how to write it. */
+function aheadCall(place) {
+    return `call ${call(place, "ahead")}, in pawns from White's side (1.5, -3, 0) or a mate you see ("#3" White's, "#-3" Black's)`;
+}
+/** Whether who is ahead is still to give in a position the player is to move in, while the game goes on. */
+function leadMissing(folder, current, position) {
+    const { leads = [] } = coachWords(folder, current);
+    return endOf(current.game) === undefined && sideToMoveAt(current, position) !== current.ai && !leads.some((lead) => lead.position === position);
+}
+/** The game's short key, from its start: the coach names the game it works on, so that its words never go to the next one. */
+function gameKey(current) {
+    return Math.floor(Date.parse(current.started) / 1000).toString(36);
+}
+/** How many plies of the game the coach shows: enough to follow it, few enough for its budget. */
+const pliesShown = 40;
+/**
+ * What the coach works on, from the position the player is to move in, or the game over: the game, the player's move the opponent answered, or their own
+ * that ended the game, with the position they played it in and the book there, and the position now with the hint it gave last; none while the opponent is
+ * to move.
+ */
+function startOf(current, folder, context) {
+    const { game, ai } = current;
+    const { record } = game;
+    const plies = record.moves.length;
+    const over = endOf(game);
+    const player = ai === "white" ? "black" : "white";
+    const judged = judgedPly(current, plies);
+    if ((game.position.turn === ai && over === undefined) || (over !== undefined && judged === undefined)) {
+        return undefined;
+    }
+    const place = { game: gameKey(current), position: plies };
+    const ender = game.position.turn === ai ? "the player's" : "the opponent's";
+    const head = over === undefined
+        ? `Game "${place.game}", position ${plies}: the player (${colourName(player)}) to move, move ${game.position.moveNumber}; the opponent plays ${colourName(ai)} at the `
+            + `${levelOf(record)} level.`
+        : `Game "${place.game}", position ${plies}: the game is over, ${over.result}${over.termination === undefined ? "" : `, ${over.termination}`}, with ${ender} move.`;
+    const speech = speechOf(folder, context.language);
+    const clock = clockSummaryOf(current, context.now());
+    const keepLine = over === undefined
+        ? `Keep your words: ${call(place, "ahead, badge, note, hint, arrows, squares")}, who is ahead always, the rest only when there is something to say; then `
+            + `${call(place, "done: true")}.`
+        : `No hint: the game is over. Keep your judgment, when their move stands out: ${call(place, "badge, note")}; then end with one word.`;
+    return [
+        head,
+        speech === undefined ? "The player speaks English." : speechLine(speech),
+        ...playerLines(context),
+        ...movesLines(record),
+        ...(clock === undefined ? [] : [clockLine(clock, ai)]),
+        ...(judged === undefined ? [] : judgedLines(current, judged, player)),
+        ...(over === undefined ? nowLines(current, folder, player) : []),
+        keepLine,
+    ];
+}
+/** The game's moves as the coach reads them, with the position a game set up began in, the last ones of a long game, and its opening by the book (Anatolij). */
+function movesLines(record) {
+    const opening = openingLine(record);
+    return [
+        ...(record.tags.FEN === undefined ? [] : [`The game began from a set position: ${record.tags.FEN}`]),
+        `${record.moves.length > pliesShown ? `Moves (the last ${pliesShown} plies)` : "Moves"}: ${lastMoves(record, pliesShown)}`,
+        ...(opening === undefined ? [] : [`Opening: ${opening}`]),
+    ];
+}
+/**
+ * The plies up to the player's move a judgment at `position` is for: the one the opponent answered, or the player's own when the opponent is to move, as
+ * after their move that ended the game (D-88); none before their first move.
+ */
+function judgedPly(current, position) {
+    const ply = sideToMoveAt(current, position) === current.ai ? position : position - 1;
+    return ply >= 1 ? ply : undefined;
+}
+/**
+ * The player's move to judge, the position they played it in with the book there, and, when the opponent answered it, what it left at risk and the checks
+ * it let the opponent give (Anatolij), and the answer with its words.
+ */
+function judgedLines({ game }, ply, player) {
+    const { record } = game;
+    const before = new Game({ tags: record.tags, moves: record.moves.slice(0, ply - 1) });
+    const played = { tags: record.tags, moves: record.moves.slice(0, ply) };
+    const book = knownMoves(before.position.fen);
+    const lines = [
+        `Their move to judge: ${lastMoves(played, 1)}. The position they played it in:`,
+        `FEN: ${before.position.fen}`,
+        `Material: ${materialText(materialOf(before.position.fen))}`,
+        ...compactView(before.facts, player),
+        ...(book.length === 0 ? [] : [`Book moves there, most named lines first: ${book.join(", ")}`]),
+    ];
+    if (ply === record.moves.length) {
+        return lines;
+    }
+    const after = new Game(played).facts;
+    const answer = lastMoves({ tags: record.tags, moves: record.moves.slice(0, ply + 1) }, 1);
+    const said = wordsOf(record.moves[ply]?.comment);
+    return [
+        ...lines,
+        `After their move: at risk ${riskLine(after) ?? "none"}; the opponent's checks: ${after.checks.join(" ") || "none"}.`,
+        said === undefined ? `The opponent answered ${answer} and said nothing.` : `The opponent answered ${answer} and said: «${said}»`,
+    ];
+}
+/**
+ * The position the player is to move in, for who is ahead and the hint, with its positional facts too (D-90), and what the coach said on their turn
+ * before.
+ */
+function nowLines(current, folder, player) {
+    const { game } = current;
+    const plies = game.record.moves.length;
+    const { hint, leads = [] } = coachWords(folder, current);
+    const lead = leads.find(({ position }) => position === plies - 2)?.lead;
+    return [
+        "Now, for who is ahead and your hint:",
+        `FEN: ${game.position.fen}`,
+        ...compactView(game.facts, player),
+        ...profileLines(game.profile),
+        ...(lead === undefined ? [] : [`Who you saw ahead on their turn before: ${leadText(lead)}, ${aheadWords(lead)}`]),
+        ...(hint === undefined || hint.position !== plies - 2 ? [] : [`Your hint on their turn before: «${hint.text}»`]),
+    ];
+}
+/** How the player says they play, and their rating, when their profile says so. */
+function playerLines(context) {
+    const { level, rating } = activeProfile(context.home());
+    const parts = [level === undefined ? undefined : `plays at the ${level} level`, rating === undefined ? undefined : `is rated ${rating.value} on ${rating.site}`];
+    const said = parts.filter((part) => part !== undefined);
+    return said.length === 0 ? [] : [`The player ${said.join(" and ")}.`];
+}
+/** Keeps the judgment of the player's move the opponent answered at `position`, or that ended the game, and the hint for their turn while it is still theirs. */
+function keep(folder, current, place, { ahead, badge, note, hint, arrows, squares }) {
+    const { position } = place;
+    const judging = badge !== undefined || note !== undefined;
+    const over = endOf(current.game) !== undefined;
+    const toMove = theirTurn(current, place);
+    if (hint === undefined && (arrows !== undefined || squares !== undefined)) {
+        throw new Error("Arrows and squares show your hint: give them with it. Nothing changed.");
+    }
+    if (!judging && hint === undefined && ahead === undefined) {
+        throw new Error(`Give who is ahead (ahead), your judgment (badge, note), your hint (hint, arrows, squares); or ${call(place, "done: true")}. Nothing changed.`);
+    }
+    // On the position the game ended in there is no turn to help and the result says who won; a position before it keeps who was ahead there, when the game
+    // ended while the coach thought (Federico).
+    const ended = over && position === current.game.record.moves.length;
+    if (ended && (hint !== undefined || ahead !== undefined)) {
+        throw new Error("The game is over: no hint and no ahead. Keep your judgment, when their move stands out, or end with one word. Nothing changed.");
+    }
+    if (ahead !== undefined && sideToMoveAt(current, position) === current.ai) {
+        throw new Error("Who is ahead is for a position the player is to move in, as coach {} gives it: here the opponent is to move. Nothing changed.");
+    }
+    const lead = ahead === undefined ? undefined : leadFrom(ahead);
+    // The player's move to judge: the one the opponent answered, or their own that ended the game (D-88).
+    const ply = judgedPly(current, position);
+    if (judging && (ply === undefined || (ply === position && !ended))) {
+        throw new Error("There is no move of the player's to judge here: give only your hint. Nothing changed.");
+    }
+    const legal = toMove ? current.game.legalMoves() : [];
+    if (hint !== undefined && toMove) {
+        refuseMoves(hint, arrows ?? [], legal);
+    }
+    if (judging && ply !== undefined) {
+        // A note that names a move the player could play in the position it was given for waits until none of them is legal on their turn: until then it
+        // would play for them (Anatolij).
+        const then = toMove ? legal : new Game({ tags: current.game.record.tags, moves: current.game.record.moves.slice(0, position) }).legalMoves();
+        const held = note === undefined ? [] : [...new Set(namedMoves(note, then))];
+        keepJudgment(folder, current, { ply, ...(badge === undefined ? {} : { badge }), ...(note === undefined ? {} : { note }), ...(held.length === 0 ? {} : { held }) });
+    }
+    if (hint !== undefined && toMove) {
+        keepHint(folder, current, { position, text: hint, ...drawingsOf(arrows, squares) });
+    }
+    // Who is ahead in the position the player was to move in, kept even once they have moved: the bar and the chart show it on that position.
+    if (lead !== undefined) {
+        keepLead(folder, current, { position, lead });
+    }
+    const saved = [
+        judging ? "your judgment" : undefined,
+        lead === undefined ? undefined : `who is ahead, ${aheadWords(lead)}`,
+        hint !== undefined && toMove ? "your hint" : undefined,
+    ].filter((part) => part !== undefined);
+    const hintLeft = hint !== undefined && !toMove;
+    if (over) {
+        // The game went to the archive with the move that ended it: the judgment goes there too.
+        archiveCoached(folder, current);
+        return { kept: place, then: "over", saved, hintLeft };
+    }
+    if (!toMove) {
+        return { kept: place, then: "moved", saved, hintLeft };
+    }
+    return { kept: place, then: leadMissing(folder, current, position) ? "lead" : "wait", saved, hintLeft };
+}
+/** Whether the player is still to move in the position the coach works on, in the same game going on. */
+function theirTurn(current, { game, position }) {
+    return current !== undefined && gameKey(current) === game && endOf(current.game) === undefined && current.game.record.moves.length === position
+        && current.game.position.turn !== current.ai;
+}
+/** The side to move after `position` plies of the game. */
+function sideToMoveAt({ game }, position) {
+    const { turn } = game.position;
+    return (game.record.moves.length - position) % 2 === 0 ? turn : turn === "white" ? "black" : "white";
+}
+/** Refuses a hint that plays for the player: a move they may play now written in it, or drawn as an arrow (Anatolij). */
+function refuseMoves(hint, arrows, legal) {
+    const drawn = arrows.map((arrow) => legal.find((move) => move.from === arrow.slice(1, 3) && move.to === arrow.slice(3, 5))?.san).filter((san) => san !== undefined);
+    const named = [...namedMoves(hint, legal), ...drawn];
+    if (named.length > 0) {
+        throw new Error(`Your hint gives the player a move they may play now (${[...new Set(named)].join(", ")}): point at what is on the board, a piece, a square, a file, a threat, a goal, `
+            + "never what to play, and mark squares rather than draw their move. Nothing changed.");
+    }
+}
+/** The moves a text names that the player may play now: a piece's move, a capture, a promotion or a castling, in letters or figurines; a square alone is no move. */
+function namedMoves(text, legal) {
+    const sanOf = new Map(legal.map((move) => [moveKey(move.san), move.san]));
+    const written = withSanLetters(text).match(moveWords) ?? [];
+    return written.map((word) => sanOf.get(moveKey(word))).filter((san) => san !== undefined);
+}
+// A move as SAN writes it, but a pawn's move to a square, which reads as the square: Nf3, Nbxd2, exd5, e8=Q, O-O; never the opponent's, after "...".
+const moveWords = /(?<![\p{L}\d]|\.\.\.|…)(?:O-O(?:-O)?|0-0(?:-0)?|[KQRBN][a-h]?[1-8]?x?[a-h][1-8]|[a-h]x[a-h][1-8](?:=[QRBN])?|[a-h][18]=[QRBN])(?![\p{L}\d])/gu;
+/**
+ * A move as the coach may write it and Chesspal lists it, alike: its piece and capture, the square it goes to and its promotion; a castling as it is. A
+ * piece on a square without the capture names that piece, never a move taking it (Priya and Anatolij).
+ */
+function moveKey(san) {
+    const bare = san.replace(/[+#!?]+$/, "").replaceAll("0", "O");
+    if (bare.startsWith("O-O")) {
+        return bare;
+    }
+    const [, piece = "", capture = "", to = "", promotion = ""] = /^([KQRBN])?[a-h]?[1-8]?(x?)([a-h][1-8])(=[QRBN])?$/.exec(bare) ?? [];
+    return `${piece}${capture}${to}${promotion}`;
+}