chesspal 0.5.0 → 0.7.0

package/README.md

@@ -49,7 +49,7 @@ In the steps below, copy each command, paste it in the terminal (Ctrl+V or right
   ```
 
   Choose **Sign in with ChatGPT** and sign in in your browser.
-- **Antigravity**, Google's, with a Google account (the free plan is enough: Chesspal plays with Gemini Flash). On Windows, in Command Prompt:
+- **Antigravity**, Google's, with a Google account (the free plan is enough: Chesspal plays with Gemini Flash). Still experimental: now and then it may miss your move on the board, and then a message in its window wakes it. On Windows, in Command Prompt:
 
   ```bash
   curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
@@ -105,10 +105,10 @@ Coming later: an AI coach that helps you grow, exercises chosen on your weak poi
 ## What you need
 
 - **Node.js 22.13** or newer, with **npm 10.9.2** or newer, which comes with it.
-- **An AI agent** with your own subscription: [Claude Code](https://code.claude.com/docs/en/setup), with a paid Claude plan, [Codex](https://developers.openai.com/codex), with a ChatGPT account, or [Antigravity](https://antigravity.google/docs/getting-started), with a Google account.
+- **An AI agent** with your own subscription: [Claude Code](https://code.claude.com/docs/en/setup), with a paid Claude plan, [Codex](https://developers.openai.com/codex), with a ChatGPT account, or [Antigravity](https://antigravity.google/docs/getting-started), with a Google account, still experimental.
 - **A web browser**, for the board page.
 
-Chesspal works with any agent that can use Chesspal's tools (MCP) and the files on your computer: we develop it with Claude Code, and Codex and Antigravity are connected too.
+Chesspal works with any agent that can use Chesspal's tools (MCP) and the files on your computer: we develop it with Claude Code, Codex is connected too, and Antigravity is supported but still experimental.
 
 ## Good to know
 

package/dist/commands/analysis/analyse.js

@@ -1,11 +1,11 @@
 // The analyst's tool (D-21, D-68): a game over, move by move in one call, facts only and never a judgment, with the analyst's instructions once in a chat.
 import { z } from "zod";
 import { accountSide, clockOfComment, clockText, closingOf, Game, gameReviewOf, isReviewed, leadOf, leadText, levelOf, materialOf, readPgn, reviewed, reviewOf, timeControlOfTag, timeControlText, withGameReview, withLead, } from "../../core/index.js";
-import { gameInAnalysis, isGameName, keepToStudy, lastChatStart, planOf, rewriteGame, startAnalysis } from "../../games/index.js";
+import { gameInAnalysis, isGameName, keepToStudy, lastChatStart, planOf, rewriteGame, startAnalysis, stoppedAnalysis } from "../../games/index.js";
 import { analystAgent, instructionsFile } from "../../host-files/index.js";
 import { activeProfile, gameFolder } from "../../profiles/index.js";
 import { pointsAtSite, siteGameName, siteOfGameName } from "../../sites/index.js";
-import { analystOf, anotherAnalyst, balanceText, bookOpening, bookPlace, bookPlies, colourName, gameToStudy, knownTag, moveNumbers, namedGame, noGameGoingOn, riskLine, shownMove, speechLine, speechOf, tacticsText, } from "../answers/index.js";
+import { analysisStopped, analystOf, anotherAnalyst, balanceText, bookOpening, bookPlace, bookPlies, colourName, gameToStudy, knownTag, moveNumbers, namedGame, noGameGoingOn, riskLine, shownMove, speechLine, speechOf, tacticsText, } from "../answers/index.js";
 import { playerLine, siteText } from "../profiles/index.js";
 import { defineCommand } from "../registry/index.js";
 import { profileSiteGames } from "./site-games.js";
@@ -78,6 +78,11 @@ export const analyseGame = defineCommand({
 function oneAnalyst(context, studied) {
     const { name } = studied;
     const holder = name === undefined ? undefined : analystOf(context, name);
+    // The analyst that held the game when the player stopped its analysis is not let back in; one started later is, the player asking again.
+    const heldWhenStopped = name === undefined ? undefined : stoppedAnalysis(gameFolder(context.home()))?.analyst;
+    if (name !== undefined && heldWhenStopped?.game === name && heldWhenStopped.run === context.agentRun) {
+        throw new Error(analysisStopped(name));
+    }
     if (holder !== undefined && holder === context.agentRun) {
         return;
     }

package/dist/commands/analysis/annotate.js

@@ -2,10 +2,10 @@
 // whole game, kept in the game's PGN for the board page. The judgment is the AI's alone: Chesspal gives no criteria (D-6, D-43).
 import { z } from "zod";
 import { annotatorOf, badges, figurinesOf, foreignMovesIn, Game, gameReviewOf, leadOf, reviewed, reviewOf, withAnnotator, withGameReview, withLead } from "../../core/index.js";
-import { gameInAnalysis, rewriteGame, startAnalysis } from "../../games/index.js";
+import { gameInAnalysis, rewriteGame, startAnalysis, stoppedAnalysis } from "../../games/index.js";
 import { analystAgent } from "../../host-files/index.js";
 import { gameFolder } from "../../profiles/index.js";
-import { analystOf, analystRuns, anotherAnalyst, arrowsInput, drawingsOf, leadFrom, moveIndex, moveNumbers, namedGame, noGameGoingOn, noteInput, squaresInput } from "../answers/index.js";
+import { analysisStopped, analystOf, analystRuns, anotherAnalyst, arrowsInput, drawingsOf, leadFrom, moveIndex, moveNumbers, namedGame, noGameGoingOn, noteInput, squaresInput } from "../answers/index.js";
 import { defineCommand } from "../registry/index.js";
 const summaryLimit = 1500;
 const closingLimit = 400;
@@ -53,6 +53,10 @@ export const annotateGame = defineCommand({
             throw new Error(`${anotherAnalyst} Nothing changed.`);
         }
         const folder = gameFolder(context.home());
+        // A review whose analysis the player stopped on the page is not written on, nor brought back to the page, by whoever was at it (Stefano).
+        if (stoppedAnalysis(folder)?.game === studied.name) {
+            throw new Error(analysisStopped(studied.name));
+        }
         const numbers = moveNumbers(studied.record);
         // Where the analyst reviews the games, the chat's notes are corrections it made with the player: the analyst, at work then or later, leaves those notes
         // and is told of them at each call, and the chat is not asked for the analyst's work (D-101, Priya). Only a call the host ties to the chat is its own.

package/dist/commands/answers/agents.d.ts

@@ -53,3 +53,5 @@ export declare function analystOf(context: Context, game: string): string | unde
 export declare function analystQuietAt(context: Context): Date | undefined;
 /** What stops an analyst agent on a game another analyst has taken: the chat hears of the review from that one (Priya). */
 export declare const anotherAnalyst: string;
+/** What refuses a review's writes once the player has stopped its analysis on the board page: the analyst that held it ends, the chat waits for the player. */
+export declare function analysisStopped(game: string): string;

package/dist/commands/answers/agents.js

@@ -136,3 +136,8 @@ const analystQuiet = 30 * 60 * 1000;
 export const anotherAnalyst = "Stop now: another analyst is reviewing this game. End with one line for the AI that started you: its review is on its way to the "
     + "board page, and its end comes to you by itself; meanwhile talk the game over with the player whenever they ask. Should it never come, the player has "
     + "the game analysed again from the board page's list of analyses.";
+/** What refuses a review's writes once the player has stopped its analysis on the board page: the analyst that held it ends, the chat waits for the player. */
+export function analysisStopped(game) {
+    return `Stop now: the player stopped the analysis of ${game} on the board page; what was written of its review stays. Nothing changed. An analyst agent ends `
+        + "with one line for the AI that started it: the player stopped the analysis. Go over the game again only when the player asks, with analyse_game first.";
+}

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

@@ -1,4 +1,4 @@
-export { agentRuns, agentsLine, analystLine, analystOf, analystOnView, analystQuietAt, analystRuns, anotherAnalyst, coachOnEnd, coachOnEndLine, coachRuns, goneOver, reviewedLine, withAnalyst } from "./agents.ts";
+export { agentRuns, agentsLine, analysisStopped, analystLine, analystOf, analystOnView, analystQuietAt, analystRuns, anotherAnalyst, coachOnEnd, coachOnEndLine, coachRuns, goneOver, reviewedLine, withAnalyst } from "./agents.ts";
 export { clockLine, clockSummaryOf, gameAt } from "./clock.ts";
 export { arrowsInput, drawingsOf, noteInput, squaresInput } from "./drawings.ts";
 export { aheadWords, leadFrom, leadInput } from "./lead-input.ts";
@@ -8,6 +8,6 @@ export { openingTags } from "./opening-tags.ts";
 export { playMove, PositionChanged, positionIn, refuseOtherGame, refuseUnseenPosition, samePosition } from "./play-move.ts";
 export { give, newWords, say, unansweredWords, waitingWords, type Written } from "./say.ts";
 export { type Speech, speechLine, speechOf } from "./speech.ts";
-export { gameShown, gameToStudy, knownTag, moveIndex, moveNumbers, namedGame, noGameGoingOn, positionAfter, positionLine, shownPosition, type Studied, studyInput } from "./study.ts";
+export { gameShown, gameToStudy, knownTag, moveIndex, moveNumbers, namedGame, noGameGoingOn, positionAfter, positionAfterLine, positionLine, shownPosition, type Studied, studyInput, type VariationInput } from "./study.ts";
 export { endText, gameGoingOn, type GameSummary, lastMoves, type MovePlayed, summaryOf, withThought } from "./summary.ts";
 export { balanceText, boardView, colourName, compactView, fullView, materialText, riskLine, tacticsText } from "./view.ts";

package/dist/commands/answers/index.js

@@ -1,6 +1,6 @@
 // What the commands share to answer the AI: the lines it reads, the game's summary and view, the clock, the talk, the moves played, the games to study.
 // Above the registry only, below every other command folder.
-export { agentRuns, agentsLine, analystLine, analystOf, analystOnView, analystQuietAt, analystRuns, anotherAnalyst, coachOnEnd, coachOnEndLine, coachRuns, goneOver, reviewedLine, withAnalyst } from "./agents.js";
+export { agentRuns, agentsLine, analysisStopped, analystLine, analystOf, analystOnView, analystQuietAt, analystRuns, anotherAnalyst, coachOnEnd, coachOnEndLine, coachRuns, goneOver, reviewedLine, withAnalyst } from "./agents.js";
 export { clockLine, clockSummaryOf, gameAt } from "./clock.js";
 export { arrowsInput, drawingsOf, noteInput, squaresInput } from "./drawings.js";
 export { aheadWords, leadFrom, leadInput } from "./lead-input.js";
@@ -10,6 +10,6 @@ export { openingTags } from "./opening-tags.js";
 export { playMove, PositionChanged, positionIn, refuseOtherGame, refuseUnseenPosition, samePosition } from "./play-move.js";
 export { give, newWords, say, unansweredWords, waitingWords } from "./say.js";
 export { speechLine, speechOf } from "./speech.js";
-export { gameShown, gameToStudy, knownTag, moveIndex, moveNumbers, namedGame, noGameGoingOn, positionAfter, positionLine, shownPosition, studyInput } from "./study.js";
+export { gameShown, gameToStudy, knownTag, moveIndex, moveNumbers, namedGame, noGameGoingOn, positionAfter, positionAfterLine, positionLine, shownPosition, studyInput } from "./study.js";
 export { endText, gameGoingOn, lastMoves, summaryOf, withThought } from "./summary.js";
 export { balanceText, boardView, colourName, compactView, fullView, materialText, riskLine, tacticsText } from "./view.js";

package/dist/commands/answers/lines.js

@@ -90,8 +90,10 @@ export function nextStep(game, words = [], pageClosed = false, doorbell = true)
     const step = pageClosed ? closedPageGameStep : newGameStep;
     // Words written on a game in analysis: the chat answers them there, and corrects the review where they show it wrong (D-101).
     if (words.some((word) => word.place !== undefined) && (game === undefined || game.end !== undefined)) {
+        const written = words.findLast((word) => word.variation !== undefined);
+        const variation = written?.variation === undefined ? undefined : `line: "${written.variation}"${written.variationGame === undefined ? "" : `, game: "${written.variationGame}"`}`;
         return "Next: answer the player with ai_say, about the move they were looking at. When they show you something the review missed, first correct that move's "
-            + "note with annotate_game, that move only.";
+            + `note with annotate_game, that move only.${variation === undefined ? "" : ` The facts after their variation: look {${variation}}.`}`;
     }
     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}`;

package/dist/commands/answers/say.d.ts

@@ -6,10 +6,16 @@ import type { Context } from "../registry/index.ts";
  * 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, 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). */
+/**
+ * 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), with the
+ * variation they played there as PGN writes it (D-116).
+ */
 export interface Written {
     readonly text: string;
     readonly place?: string;
+    readonly variation?: string;
+    /** The game of the variation, when it is not the one in analysis. */
+    readonly variationGame?: 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): Written[];

package/dist/commands/answers/say.js

@@ -1,9 +1,9 @@
 // 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, gameInAnalysis, loadGame, loadTableTalk, saveGame, saveTableTalk, talkLimits, talkLine, unheardWords } from "../../games/index.js";
+import { archiveMood, endOf, gameInAnalysis, loadGame, loadTableTalk, saveGame, saveTableTalk, talkLimits, talkLine, unheardWords } from "../../games/index.js";
 import { gameFolder, helpsIn } from "../../profiles/index.js";
 import { gameAt } from "./clock.js";
-import { shownMove } from "./lines.js";
+import { shownMove, shownMoves } from "./lines.js";
 import { openingTags } from "./opening-tags.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).
@@ -25,7 +25,7 @@ export function say(folder, who, text, at, mood, shown) {
     }
     saveGame(folder, current);
     if (mood !== undefined) {
-        archiveEnded(folder, current, openingTags(current.game.record));
+        archiveMood(folder, current, mood, openingTags(current.game.record));
     }
     return current;
 }
@@ -58,11 +58,29 @@ export function give(context, words) {
         context.heard?.();
     }
     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) });
+    return words.map(({ text, shown }) => {
+        if (shown === undefined) {
+            return { text };
+        }
+        const place = placeOf(shown, analysed);
+        if (shown.variation === undefined) {
+            return { text, place };
+        }
+        return shown.game === analysed ? { text, place, variation: shown.variation.text } : { text, place, variation: shown.variation.text, variationGame: shown.game };
+    });
 }
-/** 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}`}`;
+/**
+ * Where the page stood: the move shown, as the player saw it, or the start; on a variation, its move shown and the whole variation, or the game's move with
+ * the variation set aside (D-116); with the game's name when the page shows another now.
+ */
+function placeOf({ game, move, variation }, analysed) {
+    const there = move === undefined ? "the start" : shownMove(move);
+    const other = game === analysed ? "" : variation === undefined ? ` of ${game}` : ` in ${game}`;
+    if (variation === undefined) {
+        return `${there}${other}`;
+    }
+    const line = `the variation ${shownMoves(variation.text)}`;
+    return `${variation.move === undefined ? `${there}, ${line} set aside` : `${shownMove(variation.move)} of ${line}`}${other}`;
 }
 /** 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) {

package/dist/commands/answers/study.d.ts

@@ -6,16 +6,24 @@ import type { Context } from "../registry/index.ts";
 export declare const studyInput: {
     game: z.ZodOptional<z.ZodString>;
     move: z.ZodOptional<z.ZodString>;
+    line: z.ZodOptional<z.ZodString>;
 };
 /** A game to study: its record, and its name in the archive when it is there. */
 export interface Studied {
     readonly record: GameRecord;
     readonly name?: string;
 }
-/** A position of a game: the game as it stood after a move, and that move as the analysis writes it (12...Kf8); none at the start. */
+/**
+ * A position of a game: the game as it stood after a move, and that move as the analysis writes it (12...Kf8); none at the start. After a variation, the
+ * variation as PGN writes it and the game's own move it takes the place of, none past the game's end.
+ */
 export interface StudiedPosition {
     readonly game: Game;
     readonly move?: string;
+    readonly variation?: {
+        readonly text: string;
+        readonly instead?: string;
+    };
 }
 /** 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. */
 export declare function noGameGoingOn(context: Context): CurrentGame | undefined;
@@ -32,9 +40,20 @@ export declare function namedGame(context: Context, name: string): Required<Stud
 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.
+ * none for a game or a position there is not, or while a game goes on. With the variation the player played there (D-116), refused when it cannot be played.
  */
-export declare function shownPosition(context: Context, game: string, at: number): Shown | undefined;
+export declare function shownPosition(context: Context, game: string, at: number, variation?: VariationInput): Shown | undefined;
+/** A variation as the board page sends it (D-116): how many of the game's moves come before it, its moves, and how many of them the board shows. */
+export interface VariationInput {
+    readonly at: number;
+    readonly moves: readonly string[];
+    readonly cursor: number;
+}
+/**
+ * The position after a variation written as the AI writes it, 12...Kf8 13.Nxe5 Bxe2: from the position `move` names, or else from the number of its first
+ * move; refused when neither says where it starts, or they disagree.
+ */
+export declare function positionAfterLine(record: GameRecord, move: string | undefined, line: string): StudiedPosition;
 /** 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[];
 /**
@@ -44,5 +63,8 @@ export declare function moveNumbers(record: GameRecord): string[];
 export declare function positionAfter(record: GameRecord, move?: string): StudiedPosition;
 /** A tag PGN leaves unknown with ? or -, as nothing. */
 export declare function knownTag(tag: string | undefined): string | undefined;
-/** Where a position of a game studied stands: After 12...Kf8 in games/2026-11-02-153012.pgn: White to move. */
-export declare function positionLine({ game, move }: StudiedPosition, name?: string): string;
+/**
+ * Where a position of a game studied stands: After 12...Kf8 in games/2026-11-02-153012.pgn: White to move. After a variation, with the game's move it takes
+ * the place of: After the variation 12...Kf8 13.Nxe5 Bxe2 (the game: 12...Qd7) in games/2026-11-02-153012.pgn: White to move.
+ */
+export declare function positionLine({ game, move, variation }: StudiedPosition, name?: string): string;

package/dist/commands/answers/study.js

@@ -10,6 +10,8 @@ import { colourName } from "./view.js";
 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; 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"),
+    line: z.string().max(800).optional().describe("a variation played on a scratch board from the position move names, or from the number of its first move: 12...Kf8 13.Nxe5 Bxe2; the position after it. "
+        + "The game stays as it is"),
 };
 /** 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. */
 export function noGameGoingOn(context) {
@@ -65,20 +67,46 @@ export function moveIndex(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.
+ * none for a game or a position there is not, or while a game goes on. With the variation the player played there (D-116), refused when it cannot be played.
  */
-export function shownPosition(context, game, at) {
+export function shownPosition(context, game, at, variation) {
+    let studied;
     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}` };
+        studied = namedGame(context, game);
     }
     catch {
         return undefined;
     }
+    const { name, record } = studied;
+    if (!Number.isInteger(at) || at < 0 || at > record.moves.length) {
+        return undefined;
+    }
+    const shown = at === 0 ? { game: name, at } : { game: name, at, move: `${moveNumbers(record)[at - 1]}${record.moves[at - 1].san}` };
+    return variation === undefined ? shown : { ...shown, variation: shownVariation(record, variation) };
+}
+/**
+ * The position after a variation written as the AI writes it, 12...Kf8 13.Nxe5 Bxe2: from the position `move` names, or else from the number of its first
+ * move; refused when neither says where it starts, or they disagree.
+ */
+export function positionAfterLine(record, move, line) {
+    const moves = lineMoves(line);
+    if (moves.length === 0) {
+        throw new Error("The line has no moves: write them as PGN does, 12...Kf8 13.Nxe5 Bxe2.");
+    }
+    if (moves.length > mostLinePlies) {
+        throw new Error(`The line has ${moves.length} moves: give at most ${mostLinePlies}.`);
+    }
+    const first = firstNumber.exec(moves[0]);
+    const from = move === undefined ? lineStart(record, first) : positionAfter(record, move).game.record.moves.length;
+    const label = nextLabel(new Game({ ...record, moves: record.moves.slice(0, from) }));
+    if (first !== null && label !== `${Number(first[1])}${first[2] === "." ? "." : "..."}`) {
+        const where = move === undefined ? "" : ` after ${move.trim()}`;
+        throw new Error(`The line starts with ${first[0]}, but the next move${where} is ${label}: number its first move so, or give move, the game's move it leaves from.`);
+    }
+    const played = playLine(record, from, moves);
+    const instead = record.moves[from] === undefined ? undefined : `${moveNumbers(record)[from]}${record.moves[from].san}`;
+    return { game: played.game, variation: instead === undefined ? { text: played.text } : { text: played.text, instead } };
 }
 /** 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) {
@@ -105,12 +133,52 @@ export function positionAfter(record, move) {
 export function knownTag(tag) {
     return tag === undefined || /^[?.\-\s]*$/.test(tag) ? undefined : tag;
 }
-/** Where a position of a game studied stands: After 12...Kf8 in games/2026-11-02-153012.pgn: White to move. */
-export function positionLine({ game, move }, name) {
-    const where = `${move === undefined ? "At the start" : `After ${move}`}${name === undefined ? "" : ` in ${name}`}`;
+/**
+ * Where a position of a game studied stands: After 12...Kf8 in games/2026-11-02-153012.pgn: White to move. After a variation, with the game's move it takes
+ * the place of: After the variation 12...Kf8 13.Nxe5 Bxe2 (the game: 12...Qd7) in games/2026-11-02-153012.pgn: White to move.
+ */
+export function positionLine({ game, move, variation }, name) {
+    const after = variation === undefined
+        ? move === undefined ? "At the start" : `After ${move}`
+        : `After the variation ${variation.text} (${variation.instead === undefined ? "past the game's end" : `the game: ${variation.instead}`})`;
+    const where = `${after}${name === undefined ? "" : ` in ${name}`}`;
     const { outcome, position } = game;
     return `${where}: ${outcome.over ? `the board ends the game by ${outcome.ending}` : `${colourName(position.turn)} to move`}.`;
 }
+/**
+ * The variation the page showed with the player's words (D-116), its moves played from the game's first `at` on a scratch board: refused at the first that
+ * cannot be played, or when the game has no such position. The moves are kept in SAN as chess.js writes them, whatever the page sent.
+ */
+function shownVariation(record, variation) {
+    const { at, moves, cursor } = variation;
+    if (!Number.isInteger(at) || at < 0 || at > record.moves.length || moves.length === 0 || moves.length > mostLinePlies) {
+        throw new Error(`A variation leaves from one of the game's ${record.moves.length + 1} positions and has 1 to ${mostLinePlies} moves.`);
+    }
+    if (!Number.isInteger(cursor) || cursor < 0 || cursor > moves.length) {
+        throw new Error(`The variation shows one of its ${moves.length} moves, or none: its cursor goes from 0 to ${moves.length}.`);
+    }
+    const played = playLine(record, at, moves);
+    const sans = played.game.record.moves.slice(at).map(({ san }) => san);
+    return { at, moves: sans, cursor, text: played.text, ...(cursor === 0 ? {} : { move: played.numbered[cursor - 1] }) };
+}
+/**
+ * Plays moves on a scratch board from the game's first `from` moves (D-28), each in SAN, with figurines or as squares, with or without its number: refused
+ * at the first that cannot be played, with why. The game itself never changes.
+ */
+function playLine(record, from, moves) {
+    const game = new Game({ ...record, moves: record.moves.slice(0, from) });
+    const numbered = [];
+    for (const written of moves) {
+        const label = nextLabel(game);
+        const played = game.play(written);
+        if (!played.played) {
+            const before = numbered.length === 0 ? "" : ` after ${pgnText(numbered)}`;
+            throw new Error(`${label}${written.replace(numberBefore, "")} cannot be played${before}: ${played.message} The game stays as it is.`);
+        }
+        numbered.push(`${label}${played.move.san}`);
+    }
+    return { game, numbered, text: pgnText(numbered) };
+}
 function plyOf(record, numbers, move) {
     const [, number, dots, san] = movePattern.exec(move) ?? [];
     if (number === undefined) {
@@ -136,3 +204,46 @@ function isMove(record, ply, written) {
     return played.played && played.move.san === record.moves[ply].san;
 }
 const movePattern = /^\s*(\d+)\s*(\.\.\.|\.|…)?\s*(\S+)?\s*$/;
+/** The most moves a variation holds, on the page and in look and position. */
+const mostLinePlies = 100;
+/** The number written before a move, 12. or 12... or 12…, and what it says. */
+const firstNumber = /^(\d+)\s*(\.\.\.|…|\.)/;
+const numberBefore = /^\d+\s*(?:\.+|…)\s*/;
+/** The number the next move of a game takes as PGN writes it: 13. for White's, 13... for Black's. */
+function nextLabel(game) {
+    const { moveNumber, turn } = game.position;
+    return `${moveNumber}${turn === "white" ? "." : "..."}`;
+}
+/** Numbered moves as PGN writes them: the number before White's moves, and before the first when it is Black's. */
+function pgnText(numbered) {
+    return numbered.map((move, index) => index > 0 && move.includes("...") ? move.replace(/^\d+\.\.\./, "") : move).join(" ");
+}
+/** A line's moves, each with the number written before it when there is one: "12... Kf8 13. Nxe5" is 12...Kf8 and 13.Nxe5. */
+function lineMoves(line) {
+    const moves = [];
+    let number = "";
+    for (const word of line.trim().split(/\s+/).filter((word) => word !== "")) {
+        if (/^\d+\s*(?:\.+|…)$/.test(word)) {
+            number = word;
+        }
+        else {
+            moves.push(`${number}${word}`);
+            number = "";
+        }
+    }
+    return moves;
+}
+/** How many of the game's moves come before a line by the number of its first move, 12... after White's 12th; refused without one or out of the game. */
+function lineStart(record, first) {
+    if (first === null) {
+        throw new Error("Say where the line starts: number its first move, 12...Kf8, or give move, the game's move it leaves from.");
+    }
+    const start = new Game({ tags: record.tags, moves: [] }).position;
+    const ply = (Number(first[1]) - start.moveNumber) * 2 + (first[2] === "." ? 0 : 1) - (start.turn === "black" ? 1 : 0);
+    if (ply < 0 || ply > record.moves.length) {
+        const numbers = moveNumbers(record);
+        const span = numbers.length === 0 ? "it has no moves" : `its moves go from ${numbers[0]}${record.moves[0].san} to ${numbers.at(-1)}${record.moves.at(-1).san}`;
+        throw new Error(`The game has no position before ${first[0]}: ${span}.`);
+    }
+    return ply;
+}

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

@@ -19,6 +19,7 @@ interface StudyView {
 export declare const look: import("../registry/registry.ts").Command<z.ZodObject<{
     game: z.ZodOptional<z.ZodString>;
     move: z.ZodOptional<z.ZodString>;
+    line: z.ZodOptional<z.ZodString>;
     only: z.ZodOptional<z.ZodEnum<{
         board: "board";
     }>>;

package/dist/commands/game/look.js

@@ -3,7 +3,7 @@ import { boardText, materialOf, sees } from "../../core/index.js";
 import { archivedName, endOf } from "../../games/index.js";
 import { analystAgent } from "../../host-files/index.js";
 import { gameFolder } from "../../profiles/index.js";
-import { analystOnView, fullView, gameAt, gameShown, headLines, materialText, newWords, positionAfter, positionLine, studyInput, summaryOf, wordLines } from "../answers/index.js";
+import { analystOnView, fullView, gameAt, gameShown, headLines, materialText, newWords, positionAfter, positionAfterLine, positionLine, studyInput, summaryOf, wordLines } from "../answers/index.js";
 import { defineCommand } from "../registry/index.js";
 import { refuseUnseen } from "./levels.js";
 /** The whole view (D-26), when the compact one after the player's move is not enough; or the board for the player, where the host does not show it (D-36). */
@@ -13,15 +13,15 @@ export const look = defineCommand({
         + "moves of each piece. The views of player_move, status and new_game give attackers and defenders only for the pieces attacked: call look "
         + 'before you attack or capture a piece that is not attacked yet, or plan an exchange. With only: "board", the board as text for the player, to '
         + "copy into your message where they do not see it. With move, and game for a game of the archive, the same of any position of a game over, to "
-        + 'analyse it. Example: look {}, look {move: "12..."}.',
+        + 'analyse it; with line, of the position after a variation played from there on a scratch board. Example: look {}, look {move: "12..."}, look {line: "12...Kf8 13.Nxe5"}.',
     input: z.object({ only: z.enum(["board"]).optional().describe("board: only the board as text, for the player"), ...studyInput }),
     // Read only for the host: a flag that has fallen is written, as the time already decided.
     readOnly: true,
     idempotent: true,
     sharedWith: [analystAgent],
-    run: ({ only, game, move }, context) => {
-        if (game !== undefined || move !== undefined) {
-            return studyLook(context, only, game, move);
+    run: ({ only, game, move, line }, context) => {
+        if (game !== undefined || move !== undefined || line !== undefined) {
+            return studyLook(context, only, game, move, line);
         }
         const current = gameAt(gameFolder(context.home()), context.now());
         if (current === undefined) {
@@ -45,10 +45,10 @@ export const look = defineCommand({
         return [...("game" in look ? gameLines(look.game) : studyLines(look.study)), ...wordLines(look.words), ...(look.analyst === undefined ? [] : [look.analyst])].join("\n");
     },
 });
-/** A position of a game over, as the view of the game going on gives it. */
-function studyLook(context, only, name, move) {
+/** A position of a game over, or after a variation from it (D-116), as the view of the game going on gives it. */
+function studyLook(context, only, name, move, line) {
     const studied = gameShown(context, name);
-    const at = positionAfter(studied.record, move);
+    const at = line === undefined ? positionAfter(studied.record, move) : positionAfterLine(studied.record, move, line);
     const { position } = at.game;
     if (only === "board") {
         return { board: boardText(position.fen) };

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

@@ -9,6 +9,7 @@ type Described = Profile & {
 export declare const position: import("../registry/registry.ts").Command<z.ZodObject<{
     game: z.ZodOptional<z.ZodString>;
     move: z.ZodOptional<z.ZodString>;
+    line: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, Described>;
 /** The profile as lines for the AI, White's facts before Black's; a line with nothing to say is left out. */
 export declare function profileLines(profile: Profile): string[];

package/dist/commands/game/position.js

@@ -3,7 +3,7 @@ import {} from "../../core/index.js";
 import { archivedName, endOf } from "../../games/index.js";
 import { analystAgent } from "../../host-files/index.js";
 import { gameFolder } from "../../profiles/index.js";
-import { analystOnView, colourName, gameAt, gameShown, materialText, positionAfter, positionLine, studyInput } from "../answers/index.js";
+import { analystOnView, colourName, gameAt, gameShown, materialText, positionAfter, positionAfterLine, positionLine, studyInput } from "../answers/index.js";
 import { defineCommand } from "../registry/index.js";
 import { refuseUnseen } from "./levels.js";
 /** The positional profile of the game in progress (D-19), or of any position of a game over (D-68): separate facts, never a score. */
@@ -13,15 +13,15 @@ export const position = defineCommand({
         + "outposts, centre, space, control, mobility, development and castling, king safety, the phase, the draw rules and, with only kings and pawns, "
         + "the rule of the square and the opposition. Facts only, never a score: weigh them yourself. Call it when you set or change your plan: out of "
         + "the opening, after a big exchange, in the endgame; not at every move. With move, and game for a game of the archive, the facts of any position of a "
-        + 'game over, to analyse it. Example: position {}, position {move: "24."}.',
+        + 'game over, to analyse it; with line, after a variation played from there on a scratch board. Example: position {}, position {move: "24."}.',
     input: z.object(studyInput),
     readOnly: true,
     idempotent: true,
     sharedWith: [analystAgent],
-    run: ({ game, move }, context) => {
-        if (game !== undefined || move !== undefined) {
+    run: ({ game, move, line }, context) => {
+        if (game !== undefined || move !== undefined || line !== undefined) {
             const studied = gameShown(context, game);
-            const at = positionAfter(studied.record, move);
+            const at = line === undefined ? positionAfter(studied.record, move) : positionAfterLine(studied.record, move, line);
             return withAnalystLine({ ...at.game.profile, where: positionLine(at, studied.name) }, analystOnView(context, studied.name));
         }
         const current = gameAt(gameFolder(context.home()), context.now());

package/dist/commands/index.d.ts

@@ -1,6 +1,6 @@
 import type { AnyCommand } from "./registry/index.ts";
 export { analyseGame, deleteReview, siteGames, SiteGamesRefused } from "./analysis/index.ts";
-export { analystOf, analystQuietAt, bookOpening, bookPlies, gameAt, gameToStudy, namedGame, playMove, PositionChanged, positionIn, samePosition, say, shownPosition } from "./answers/index.ts";
+export { analystOf, analystQuietAt, bookOpening, bookPlies, gameAt, gameToStudy, namedGame, playMove, PositionChanged, positionIn, samePosition, say, shownPosition, type VariationInput } from "./answers/index.ts";
 export { aiMove, answerDraw, ChatNotClear, DrawRefused, endGame, type MoveSentAlone, newGame, offerDraw, playMoveSentAlone, pliesBeforeClearing, startNewGame } from "./game/index.ts";
 export { chooseDrawnAvatar, deleteGame, editProfile, GameGoingOn, newProfile, ratingsAge, refreshRatings, useProfile } from "./profiles/index.ts";
 export { type AnyCommand, baseType, type Caller, type Command, commandLineFieldProblem, type Context, defaultContext, homeForOneCall, inputProblems, isBoolean, isList, type SeenPosition, speaksItalian, takesNumbers, } from "./registry/index.ts";

package/dist/core/index.d.ts

@@ -11,7 +11,7 @@ export { aiLevels, layersOf, levelForPlayer, levelOf, levelTag, sees, suggestedL
 export type { AiLevel, Layer } from "./levels.ts";
 export { materialOf } from "./material.ts";
 export type { Material } from "./material.ts";
-export { endWithMood, type Mood, moodAt, type MoodNow, moodOf, moods, moodTag, withoutMoods } from "./moods.ts";
+export { endWithMood, type Mood, moodAt, type MoodNow, moodOf, moods, moodTag, recordWithMood, withoutMoods } from "./moods.ts";
 export { bookMoves, bookPlaceOf, indexBook, indexOpenings, openingOf, outOfBookMove, positionKeysOf } from "./openings.ts";
 export type { BookPlace, Opening, OpeningBook, OpeningIndex } from "./openings.ts";
 export { pgnDate, readPgn, readPgnTags, readPgnUnplayed, writePgn } from "./pgn.ts";

package/dist/core/index.js

@@ -6,7 +6,7 @@ export { foreignMovesIn, Game, withSanLetters, withSanPieces } from "./game.js";
 export { leadOf, leadText, readLead, withLead } from "./lead.js";
 export { aiLevels, layersOf, levelForPlayer, levelOf, levelTag, sees, suggestedLevel } from "./levels.js";
 export { materialOf } from "./material.js";
-export { endWithMood, moodAt, moodOf, moods, moodTag, withoutMoods } from "./moods.js";
+export { endWithMood, moodAt, moodOf, moods, moodTag, recordWithMood, withoutMoods } from "./moods.js";
 export { bookMoves, bookPlaceOf, indexBook, indexOpenings, openingOf, outOfBookMove, positionKeysOf } from "./openings.js";
 export { pgnDate, readPgn, readPgnTags, readPgnUnplayed, writePgn } from "./pgn.js";
 export { movesOnly } from "./record.js";

package/dist/core/moods.d.ts

@@ -15,6 +15,8 @@ export declare function moodTag(mood: Mood): string;
 export declare function moodOf(comment: string | undefined): Mood | undefined;
 /** Gives the AI's mood on the last move of a game that has ended, in place of the one it had: the face the game ends with. A game without moves keeps none. */
 export declare function endWithMood(game: Game, mood: Mood): void;
+/** A game's record with the mood it ends with on its last move, in place of the one it had, as endWithMood gives it: the rest of the record as it is. */
+export declare function recordWithMood(record: GameRecord, mood: Mood): GameRecord;
 /** The AI's mood after the first `plies` moves of a record: the last it gave, while it lasts, else neutral. A mood on the player's move is the one the game ended with. */
 export declare function moodAt(record: GameRecord, ai: Side, plies?: number): MoodNow;
 /** The record without moods: another game's are not the AI's. */

package/dist/core/moods.js

@@ -14,11 +14,15 @@ export function moodOf(comment) {
 /** Gives the AI's mood on the last move of a game that has ended, in place of the one it had: the face the game ends with. A game without moves keeps none. */
 export function endWithMood(game, mood) {
     const plies = game.record.moves.length;
-    const comment = game.record.moves[plies - 1]?.comment?.replace(moodPattern, "");
     if (plies > 0) {
-        game.annotate(plies, { comment: comment === undefined || comment === "" ? moodTag(mood) : `${comment} ${moodTag(mood)}` });
+        game.annotate(plies, { comment: withMood(game.record.moves[plies - 1]?.comment, mood) });
     }
 }
+/** A game's record with the mood it ends with on its last move, in place of the one it had, as endWithMood gives it: the rest of the record as it is. */
+export function recordWithMood(record, mood) {
+    const last = record.moves.length - 1;
+    return { ...record, moves: record.moves.map((move, index) => index === last ? { ...move, comment: withMood(move.comment, mood) } : move) };
+}
 /** The AI's mood after the first `plies` moves of a record: the last it gave, while it lasts, else neutral. A mood on the player's move is the one the game ended with. */
 export function moodAt(record, ai, plies = record.moves.length) {
     // The ply count from white's move of the first move number: 1 when black moves first.
@@ -43,3 +47,8 @@ export function withoutMoods(record) {
 }
 const neutral = { mood: "neutral", left: 0 };
 const moodPattern = /\s*\[%mood ([a-z]+)\]/;
+// A move's comment with the mood in place of the one it had.
+function withMood(comment, mood) {
+    const kept = comment?.replace(moodPattern, "");
+    return kept === undefined || kept === "" ? moodTag(mood) : `${kept} ${moodTag(mood)}`;
+}