chesspal 0.0.1 → 0.1.0

package/dist/games/current-game.js

@@ -0,0 +1,128 @@
+// The player's current game on disk (D-27, D-41): game.json, its PGN and the talk on the board page inside, written whole at every change, and kept in
+// memory while nobody else changes it.
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { Game, readPgn, writePgn } from "../core/index.js";
+import { writeAtomically } from "./files.js";
+/** The current game of a folder, as it is on disk, or undefined when there is none. A game.json Chesspal cannot read throws: nothing overwrites it. */
+export function loadGame(folder) {
+    const path = join(folder, fileName);
+    const stamp = stampOf(path);
+    if (stamp === undefined) {
+        kept.delete(path);
+        return undefined;
+    }
+    const known = kept.get(path);
+    if (known?.stamp === stamp) {
+        return known.current;
+    }
+    const current = parsed(readFileSync(path, "utf8"), path);
+    kept.set(path, { stamp, current });
+    return current;
+}
+/** Writes the current game to game.json, whole or not at all; from then on it is the one kept in memory. */
+export function saveGame(folder, current) {
+    const path = join(folder, fileName);
+    const file = {
+        format: 1,
+        ai: current.ai,
+        started: current.started,
+        pgn: writePgn(current.game.record),
+        ...(current.talk.length === 0 ? {} : { talk: current.talk }),
+        ...(current.clock === undefined ? {} : { clock: savedClockOf(current.clock) }),
+        ...(drawOfferOf(current) === undefined ? {} : { drawOffer: current.drawOffer }),
+    };
+    try {
+        writeAtomically(path, `${JSON.stringify(file, null, 2)}\n`);
+    }
+    catch (error) {
+        // The live game may hold a move the file does not: the next call reads the file again.
+        kept.delete(path);
+        throw new Error(`Chesspal could not save the game: ${error.message} Nothing changed.`, { cause: error });
+    }
+    kept.set(path, { stamp: stampOf(path) ?? "", current });
+}
+/** How the game ended, or undefined while it goes on: by the board, or by what the record says, such as a resignation. */
+export function endOf(game) {
+    const { tags } = game.record;
+    const { outcome } = game;
+    if (tags.Result === undefined || tags.Result === "*") {
+        return undefined;
+    }
+    const termination = tags.Termination ?? (outcome.over ? outcome.ending : undefined);
+    return termination === undefined ? { result: tags.Result } : { result: tags.Result, termination };
+}
+/** The draw offer that stands: none once the game is over (D-65). */
+export function drawOfferOf(current) {
+    return endOf(current.game) === undefined ? current.drawOffer : undefined;
+}
+/** Whether each side has made a move in the game, before which no draw is agreed (FIDE 5.2.3, D-65). */
+export function bothSidesMoved(game) {
+    return game.record.moves.length >= 2;
+}
+/** A stamp of the folder's game.json that changes whenever it is written, whoever writes it; undefined when there is none. */
+export function gameStamp(folder) {
+    return stampOf(join(folder, fileName));
+}
+const fileName = "game.json";
+/** A line of the talk as game.json and talk.json keep it. */
+export const savedLine = z.object({ who: z.enum(["player", "ai"]), text: z.string(), ply: z.int().min(0), at: z.iso.datetime(), agent: z.literal(true).optional() });
+const savedClock = z.object({
+    base: z.int().positive(),
+    increment: z.int().min(0),
+    white: z.number().min(0),
+    black: z.number().min(0),
+    since: z.iso.datetime(),
+    waiting: z.literal(true).optional(),
+});
+const gameFile = z.object({
+    format: z.literal(1),
+    ai: z.enum(["white", "black"]),
+    started: z.iso.datetime(),
+    pgn: z.string(),
+    talk: z.array(savedLine).optional(),
+    clock: savedClock.optional(),
+    drawOffer: z.enum(["player", "ai"]).optional(),
+});
+// The games read or written in this process, by their file, with the file's stamp then: a call reads a file again only when another process changed it.
+const kept = new Map();
+function stampOf(path) {
+    // The file's id changes at every rename: a write within the same tick of the clock, and of the same size, is seen too.
+    const stats = statSync(path, { bigint: true, throwIfNoEntry: false });
+    return stats === undefined ? undefined : `${stats.ino}:${stats.mtimeNs}:${stats.size}`;
+}
+function parsed(text, path) {
+    try {
+        const file = gameFile.parse(JSON.parse(text));
+        const records = readPgn(file.pgn);
+        const [record] = records;
+        if (record === undefined || records.length > 1) {
+            throw new Error(`its PGN holds ${records.length} games`);
+        }
+        return {
+            game: new Game(record),
+            ai: file.ai,
+            started: file.started,
+            talk: file.talk ?? [],
+            ...(file.clock === undefined ? {} : { clock: clockOf(file.clock) }),
+            ...(file.drawOffer === undefined ? {} : { drawOffer: file.drawOffer }),
+        };
+    }
+    catch (error) {
+        throw new Error(`${path} is not a game Chesspal can read (${problemOf(error)}): ask the player to fix it or move it away, since Chesspal never overwrites it.`);
+    }
+}
+/** The clock as game.json keeps it, flat, in milliseconds. */
+function savedClockOf({ control, left, since, waiting }) {
+    return { base: control.base, increment: control.increment, white: left.white, black: left.black, since, ...(waiting === true ? { waiting } : {}) };
+}
+function clockOf({ base, increment, white, black, since, waiting }) {
+    return { control: { base, increment }, left: { white, black }, since, ...(waiting === true ? { waiting } : {}) };
+}
+function problemOf(error) {
+    if (error instanceof z.ZodError) {
+        return error.issues.map((issue) => `${issue.path.join(".") || "the file"}: ${issue.message}`).join("; ");
+    }
+    return error.message;
+}

package/dist/games/files.d.ts

@@ -0,0 +1,9 @@
+/** Writes a file whole or not at all: a temporary file beside it, then renamed over it (D-27). A failure says what to do about it. */
+export declare function writeAtomically(path: string, text: string | Uint8Array): void;
+/** Makes a folder, and those above it, when missing. A failure says what to do about it. */
+export declare function makeFolder(path: string): void;
+/**
+ * Renames a file or a folder. Windows refuses while another program holds a file in it open (an editor, an antivirus, a sync client): Chesspal waits a
+ * little and tries again, half a second at most.
+ */
+export declare function renameOver(from: string, to: string): void;

package/dist/games/files.js

@@ -0,0 +1,52 @@
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+/** Writes a file whole or not at all: a temporary file beside it, then renamed over it (D-27). A failure says what to do about it. */
+export function writeAtomically(path, text) {
+    const temporary = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(temporary, text);
+        renameOver(temporary, path);
+    }
+    catch (error) {
+        throw new Error(problemOf(error, path), { cause: error });
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/** Makes a folder, and those above it, when missing. A failure says what to do about it. */
+export function makeFolder(path) {
+    try {
+        mkdirSync(path, { recursive: true });
+    }
+    catch (error) {
+        throw new Error(`${path} could not be made (${error.message}): check that it is a folder, and can be written.`, { cause: error });
+    }
+}
+const attempts = 10;
+/**
+ * Renames a file or a folder. Windows refuses while another program holds a file in it open (an editor, an antivirus, a sync client): Chesspal waits a
+ * little and tries again, half a second at most.
+ */
+export function renameOver(from, to) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            if (attempt === attempts || !isHeld(error)) {
+                throw error;
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10 * attempt);
+        }
+    }
+}
+function isHeld(error) {
+    return error.syscall === "rename" && (error.code === "EPERM" || error.code === "EACCES" || error.code === "EBUSY");
+}
+function problemOf(error, path) {
+    if (isHeld(error)) {
+        return `${path} is held open by another program, or is read-only (${error.code}, ${attempts} tries): close that program, or make the file writable.`;
+    }
+    return `${path} could not be written (${error.message}): check that its folder can be written.`;
+}

package/dist/games/index.d.ts

@@ -0,0 +1,10 @@
+export { aiModelOf, noteAiModel } from "./ai-model.ts";
+export { type Analysis, endAnalysis, gameInAnalysis, startAnalysis } from "./analysis.ts";
+export { archivedGame, archivedGames, archivedName, archivedWhen, archiveEnded, archiveGame, keepToStudy, keptGame, keptGames, movesPgn, playerPgn, rewriteGame, startOfNewGame } from "./archive.ts";
+export { type ChatStart, cleanSince, lastChatStart, saveChatStart } from "./chat-start.ts";
+export { bothSidesMoved, type CurrentGame, drawOfferOf, endOf, type GameEnd, gameStamp, loadGame, saveGame, type Speaker, type TalkLine } from "./current-game.ts";
+export { makeFolder, renameOver, writeAtomically } from "./files.ts";
+export { commentWithPlan, currentPlan, planOf, withoutPlans } from "./plans.ts";
+export { endTableTalk, loadTableTalk, saveTableTalk, type TableTalk } from "./table-talk.ts";
+export { type Heard, heardLines, playerLinesThisMove, type Sayer, type Talk, talkLimits, talkLine, unheardWords, wakesTheChat, type Words, WordsRefused } from "./talk.ts";
+export { keepThought, type Thought, thoughtForLastMove, thoughtKey, waitingSince } from "./thoughts.ts";

package/dist/games/index.js

@@ -0,0 +1,11 @@
+// The player's games on disk: the current one in game.json, the finished ones in games/ (D-27, D-41), the games kept to study in study/ (D-68). Below the commands, above the core.
+export { aiModelOf, noteAiModel } from "./ai-model.js";
+export { endAnalysis, gameInAnalysis, startAnalysis } from "./analysis.js";
+export { archivedGame, archivedGames, archivedName, archivedWhen, archiveEnded, archiveGame, keepToStudy, keptGame, keptGames, movesPgn, playerPgn, rewriteGame, startOfNewGame } from "./archive.js";
+export { cleanSince, lastChatStart, saveChatStart } from "./chat-start.js";
+export { bothSidesMoved, drawOfferOf, endOf, gameStamp, loadGame, saveGame } from "./current-game.js";
+export { makeFolder, renameOver, writeAtomically } from "./files.js";
+export { commentWithPlan, currentPlan, planOf, withoutPlans } from "./plans.js";
+export { endTableTalk, loadTableTalk, saveTableTalk } from "./table-talk.js";
+export { heardLines, playerLinesThisMove, talkLimits, talkLine, unheardWords, wakesTheChat, WordsRefused } from "./talk.js";
+export { keepThought, thoughtForLastMove, thoughtKey, waitingSince } from "./thoughts.js";

package/dist/games/plans.d.ts

@@ -0,0 +1,9 @@
+import type { GameRecord } from "../core/index.ts";
+/** The comment of the AI's move, when it has one, with its plan. */
+export declare function commentWithPlan(comment: string | undefined, plan: string): string;
+/** The plan a move's comment carries, if it carries one. */
+export declare function planOf(comment: string | undefined): string | undefined;
+/** The plan the AI wrote last, if it wrote one. */
+export declare function currentPlan(record: GameRecord): string | undefined;
+/** The record without the AI's plans: what the player may see while the game goes on. */
+export declare function withoutPlans(record: GameRecord): GameRecord;

package/dist/games/plans.js

@@ -0,0 +1,23 @@
+/** The comment of the AI's move, when it has one, with its plan. */
+export function commentWithPlan(comment, plan) {
+    return comment === undefined ? `[%plan ${plan}]` : `${comment} [%plan ${plan}]`;
+}
+/** The plan a move's comment carries, if it carries one. */
+export function planOf(comment) {
+    return planPattern.exec(comment ?? "")?.[1];
+}
+/** The plan the AI wrote last, if it wrote one. */
+export function currentPlan(record) {
+    for (let index = record.moves.length - 1; index >= 0; index--) {
+        const plan = planOf(record.moves[index]?.comment);
+        if (plan !== undefined) {
+            return plan;
+        }
+    }
+    return undefined;
+}
+/** The record without the AI's plans: what the player may see while the game goes on. */
+export function withoutPlans(record) {
+    return { ...record, moves: record.moves.map((move) => ({ ...move, comment: move.comment?.replace(planPattern, "") })) };
+}
+const planPattern = /\s*\[%plan ([^\]]*)\]/;

package/dist/games/table-talk.d.ts

@@ -0,0 +1,12 @@
+import { type TalkLine } from "./current-game.ts";
+/** What the player and the AI said with no game on the page, and since when: it keys the player's lines apart from any game's. */
+export interface TableTalk {
+    readonly started: string;
+    readonly talk: readonly TalkLine[];
+}
+/** The talk with no game: empty when there is none, or talk.json cannot be read, since it is only words. */
+export declare function loadTableTalk(folder: string): TableTalk;
+/** Writes the talk with no game, whole or not at all. */
+export declare function saveTableTalk(folder: string, table: TableTalk): void;
+/** Forgets the talk with no game, when a game starts. */
+export declare function endTableTalk(folder: string): void;

package/dist/games/table-talk.js

@@ -0,0 +1,25 @@
+// The talk on the board page before the first game (D-77): talk.json, in the folder of the profile's games, until a game starts and its talk goes in game.json.
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { savedLine } from "./current-game.js";
+import { writeAtomically } from "./files.js";
+/** The talk with no game: empty when there is none, or talk.json cannot be read, since it is only words. */
+export function loadTableTalk(folder) {
+    try {
+        return tableFile.parse(JSON.parse(readFileSync(join(folder, fileName), "utf8")));
+    }
+    catch {
+        return { started: "", talk: [] };
+    }
+}
+/** Writes the talk with no game, whole or not at all. */
+export function saveTableTalk(folder, table) {
+    writeAtomically(join(folder, fileName), `${JSON.stringify(table, null, 2)}\n`);
+}
+/** Forgets the talk with no game, when a game starts. */
+export function endTableTalk(folder) {
+    rmSync(join(folder, fileName), { force: true });
+}
+const fileName = "talk.json";
+const tableFile = z.object({ started: z.iso.datetime(), talk: z.array(savedLine) });

package/dist/games/talk.d.ts

@@ -0,0 +1,40 @@
+import { type CurrentGame, type Speaker, type TalkLine } from "./current-game.ts";
+import type { TableTalk } from "./table-talk.ts";
+/** The most the player may write in a move, in all their lines, and the most a line of the AI's may hold (D-54); with the helps on, as an analyst's note (D-78). */
+export declare const talkLimits: {
+    readonly player: 200;
+    readonly ai: 300;
+    readonly aiHelps: 700;
+};
+/** Who says a line: the player, the AI in the chat, or the AI's agent thinking on the player's time (D-72), whose lines are the AI's on the page. */
+export type Sayer = Speaker | "agent";
+/** A talk: a game's, going on or over, or the one with no game, where both talk freely as between games (D-74, D-77). */
+export type Talk = CurrentGame | TableTalk;
+/**
+ * A new line of the talk, said when the game has `ply` moves: refused when it is empty or too long. The player writes 200 characters a move in all, the
+ * words sent with the move included; the AI speaks once a move of theirs, on their time, and its agent's word leaves it an answer to what they write after (D-54, D-72).
+ */
+export declare function talkLine(current: Talk, sayer: Sayer, text: string, at: Date, ply?: number, aiMost?: number): TalkLine;
+/** Words refused, and why, for the page to say it in the player's language (T-11): none, the move's characters spent, more than a line or what is left holds. */
+export declare class WordsRefused extends Error {
+    readonly reason: "empty" | "spent" | "long" | "longer-than-left";
+    readonly most: number;
+    constructor(message: string, reason: WordsRefused["reason"], most?: number);
+}
+/** The lines the player wrote since the AI's last move: those it answers with its next move, and the 200 characters of this move are counted on them. */
+export declare function playerLinesThisMove(current: CurrentGame): TalkLine[];
+/** How many characters the player may still write for this move; between games a whole line each time, with no count (D-74). */
+export declare function wordsLeft(current: Talk): number;
+/** Whether the player's last line wakes the chat: the first of a move, and between games the first since the AI last spoke (D-54, D-74). */
+export declare function wakesTheChat(current: Talk): boolean;
+/** Words of the player's, with the key that tells them apart across games. */
+export interface Words {
+    readonly key: string;
+    readonly text: string;
+}
+/** What the player said that the AI has not answered, but for the words whose keys are in `given`. */
+export declare function unheardWords(current: Talk, given: ReadonlySet<string>): Words[];
+/** How far a line of the player's got: written, read by the AI in this chat, or answered by its words or its move. */
+export type Heard = "sent" | "read" | "answered";
+/** How far each line of the talk got: the player's by `Heard`, the AI's undefined (D-53). */
+export declare function heardLines(current: Talk, given: ReadonlySet<string>): (Heard | undefined)[];

package/dist/games/talk.js

@@ -0,0 +1,131 @@
+// The talk on the board page (D-51, T-65): the player's words and the AI's answers, kept in game.json beside the PGN, or in talk.json with no game (D-77).
+import { endOf } from "./current-game.js";
+/** The most the player may write in a move, in all their lines, and the most a line of the AI's may hold (D-54); with the helps on, as an analyst's note (D-78). */
+export const talkLimits = { player: 200, ai: 300, aiHelps: 700 };
+/**
+ * A new line of the talk, said when the game has `ply` moves: refused when it is empty or too long. The player writes 200 characters a move in all, the
+ * words sent with the move included; the AI speaks once a move of theirs, on their time, and its agent's word leaves it an answer to what they write after (D-54, D-72).
+ */
+export function talkLine(current, sayer, text, at, ply = isGame(current) ? current.game.record.moves.length : 0, aiMost = talkLimits.ai) {
+    const who = sayer === "agent" ? "ai" : sayer;
+    const words = text.trim();
+    const most = who === "player" ? wordsLeft(current) : aiMost;
+    if (words === "") {
+        throw new WordsRefused("There is nothing to say: write the words first.", "empty");
+    }
+    if (who === "player" && most === 0) {
+        throw new WordsRefused(`You have written your ${talkLimits.player} characters until the AI's next move: write again after it.`, "spent");
+    }
+    if (words.length > most) {
+        const more = who === "player" && most < talkLimits.player;
+        throw new WordsRefused(`The words are ${words.length} characters long: write at most ${most}${more ? " more until the AI's next move" : ""}.`, more ? "longer-than-left" : "long", most);
+    }
+    if (who === "ai" && isGame(current)) {
+        refuseAiWords(current, sayer === "agent");
+    }
+    return { who, text: words, ply, at: at.toISOString(), ...(sayer === "agent" ? { agent: true } : {}) };
+}
+/** Words refused, and why, for the page to say it in the player's language (T-11): none, the move's characters spent, more than a line or what is left holds. */
+export class WordsRefused extends Error {
+    reason;
+    most;
+    constructor(message, reason, most = 0) {
+        super(message);
+        this.reason = reason;
+        this.most = most;
+    }
+}
+/** The lines the player wrote since the AI's last move: those it answers with its next move, and the 200 characters of this move are counted on them. */
+export function playerLinesThisMove(current) {
+    const since = sinceAiMoved(current);
+    return current.talk.filter((line) => line.who === "player" && line.ply >= since);
+}
+/** How many characters the player may still write for this move; between games a whole line each time, with no count (D-74). */
+export function wordsLeft(current) {
+    if (!going(current)) {
+        return talkLimits.player;
+    }
+    return Math.max(talkLimits.player - playerLinesThisMove(current).reduce((sum, line) => sum + line.text.length, 0), 0);
+}
+/** Whether the player's last line wakes the chat: the first of a move, and between games the first since the AI last spoke (D-54, D-74). */
+export function wakesTheChat(current) {
+    return going(current) ? playerLinesThisMove(current).length === 1 : unanswered(current).length === 1;
+}
+/** What the player said that the AI has not answered, but for the words whose keys are in `given`. */
+export function unheardWords(current, given) {
+    return unanswered(current).filter(({ key }) => !given.has(key)).map(({ key, line }) => ({ key, text: line.text }));
+}
+/** How far each line of the talk got: the player's by `Heard`, the AI's undefined (D-53). */
+export function heardLines(current, given) {
+    const waiting = new Set(unanswered(current).map(({ key }) => key));
+    return current.talk.map((line, index) => {
+        const key = keyOf(current, index);
+        return line.who === "ai" ? undefined : !waiting.has(key) ? "answered" : given.has(key) ? "read" : "sent";
+    });
+}
+/**
+ * The AI speaks apart from its move once a move of the player's, on their time, with something to say or to answer (D-72), and never while its move waits:
+ * it speaks in the move's comment then. Its agent speaks only first, when the player has written nothing to answer, and its word leaves the chat one answer
+ * to what they write after. Between games it talks freely, about the game just over or to start another (D-74).
+ */
+function refuseAiWords(current, byAgent) {
+    const { game, ai } = current;
+    const since = sinceAiMoved(current);
+    if (endOf(game) !== undefined) {
+        return;
+    }
+    if (game.position.turn === ai) {
+        throw new Error("It is your move: speak in ai_move's comment. Nothing changed.");
+    }
+    const spoken = current.talk.filter((line) => line.who === "ai" && line.ply >= since);
+    if (byAgent) {
+        refuseAgentWords(current, spoken);
+        return;
+    }
+    if (spoken.some((line) => line.agent !== true)) {
+        throw new Error("You have spoken once for this move: say the rest in ai_move's comment. Nothing changed.");
+    }
+    if (spoken.length > 0 && unanswered(current).length === 0) {
+        throw new Error("You have said a word on the player's time already: speak again only to answer them, else in ai_move's comment. Nothing changed.");
+    }
+}
+/** The agent's word on the player's time: one, and none once they have written, since the chat answers them. */
+function refuseAgentWords(current, spoken) {
+    if (spoken.length > 0) {
+        throw new Error("You have spoken for this move already: say nothing more. Nothing changed.");
+    }
+    if (unanswered(current).length > 0) {
+        throw new Error("The player has written to you, and the AI in the chat answers them: say nothing. Nothing changed.");
+    }
+}
+/** How many moves the game had just after the AI's last move, 0 before it: what is said since then waits for its next move. */
+function sinceAiMoved(current) {
+    const moves = current.game.record.moves.length;
+    // The last move is the AI's when the AI is not to move; else the AI's is the one before it.
+    const lastIsAi = current.game.position.turn !== current.ai;
+    return lastIsAi ? moves : moves >= 2 ? moves - 1 : 0;
+}
+/** The player's lines after the AI's last words and its last move, each with a key of its own across games. */
+function unanswered(current) {
+    const { talk } = current;
+    const lastSaid = talk.findLastIndex((line) => line.who === "ai");
+    return talk.flatMap((line, index) => index > lastSaid && line.who === "player" && !aiMovedSince(current, line.ply) ? [{ key: keyOf(current, index), line }] : []);
+}
+/** Whether the AI has moved since the game had `ply` moves: the last move is the AI's when the AI is not to move, and two moves on, one of them is. */
+function aiMovedSince(current, ply) {
+    if (!isGame(current)) {
+        return false;
+    }
+    const moves = current.game.record.moves.length;
+    return moves > ply + 1 || (moves === ply + 1 && current.game.position.turn !== current.ai);
+}
+function isGame(current) {
+    return "game" in current;
+}
+/** Whether a game goes on, with its limits to the talk; none with no game or once it is over. */
+function going(current) {
+    return isGame(current) && endOf(current.game) === undefined;
+}
+function keyOf(current, index) {
+    return `${current.started}#${index}`;
+}

package/dist/games/thoughts.d.ts

@@ -0,0 +1,15 @@
+import type { CurrentGame } from "./current-game.ts";
+/** The AI's answer to one reply of the player's: the reply and its move in SAN, and why in one sentence. */
+export interface Thought {
+    readonly reply: string;
+    readonly move: string;
+    readonly why: string;
+}
+/** The key of the position the player is to move in: the game, by its start, and how many moves it has. */
+export declare function thoughtKey(current: CurrentGame, ply?: number): string;
+/** Keeps a thought for a position, in place of one for the same reply; thoughts of another position go. The thoughts kept now. */
+export declare function keepThought(folder: string, key: string, thought: Thought): Thought[];
+/** The thought for the player's last move, when the AI is to move and thought of it on their time. */
+export declare function thoughtForLastMove(folder: string, current: CurrentGame): Thought | undefined;
+/** Since when the AI has waited for the player's move in a position: the first time it asked, `now` then, kept with its thoughts. */
+export declare function waitingSince(folder: string, key: string, now: Date): Date;

package/dist/games/thoughts.js

@@ -0,0 +1,60 @@
+// What the AI thought on the player's time (D-72): its answers to the player's likely replies, in thoughts.json beside game.json, hidden from the player
+// as its plan is (D-29), and kept only for the position they were thought on: the next position's replace them.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { writeAtomically } from "./files.js";
+/** The key of the position the player is to move in: the game, by its start, and how many moves it has. */
+export function thoughtKey(current, ply = current.game.record.moves.length) {
+    return `${current.started}#${ply}`;
+}
+/** Keeps a thought for a position, in place of one for the same reply; thoughts of another position go. The thoughts kept now. */
+export function keepThought(folder, key, thought) {
+    const kept = keptAt(folder, key);
+    const thoughts = [...kept.thoughts.filter((one) => one.reply !== thought.reply), thought];
+    if (thoughts.length > mostThoughts) {
+        throw new Error(`You have ${mostThoughts} thoughts for this position already: they are enough. Nothing changed.`);
+    }
+    write(folder, { ...kept, thoughts });
+    return thoughts;
+}
+/** The thought for the player's last move, when the AI is to move and thought of it on their time. */
+export function thoughtForLastMove(folder, current) {
+    const { moves } = current.game.record;
+    const last = moves.at(-1);
+    return last === undefined ? undefined : keptAt(folder, thoughtKey(current, moves.length - 1)).thoughts.find((thought) => thought.reply === last.san);
+}
+/** Since when the AI has waited for the player's move in a position: the first time it asked, `now` then, kept with its thoughts. */
+export function waitingSince(folder, key, now) {
+    const kept = keptAt(folder, key);
+    if (kept.since !== undefined) {
+        return new Date(kept.since);
+    }
+    write(folder, { ...kept, since: now.toISOString() });
+    return now;
+}
+/** The most thoughts kept for a position: a few likely replies, not every legal one. */
+const mostThoughts = 8;
+const fileName = "thoughts.json";
+const thoughtsFile = z.object({
+    key: z.string(),
+    thoughts: z.array(z.object({ reply: z.string(), move: z.string(), why: z.string() })),
+    since: z.iso.datetime().optional(),
+});
+/** What is kept for a position: nothing yet when the file is for another, or missing. */
+function keptAt(folder, key) {
+    const kept = read(folder);
+    return kept?.key === key ? kept : { key, thoughts: [] };
+}
+function read(folder) {
+    try {
+        return thoughtsFile.parse(JSON.parse(readFileSync(join(folder, fileName), "utf8")));
+    }
+    catch {
+        // None yet, or one Chesspal cannot read: thoughts are only a help, and the next one written replaces it.
+        return undefined;
+    }
+}
+function write(folder, kept) {
+    writeAtomically(join(folder, fileName), `${JSON.stringify(kept, null, 2)}\n`);
+}

package/dist/home/data-folder.d.ts

@@ -0,0 +1,12 @@
+/** What the data folder is found from: the environment, the system, the user's own folder, and where the system says Documents is. */
+export interface System {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly platform: string;
+    readonly home: string;
+    /** What `reg query` prints of Documents' place, or undefined when it cannot run. */
+    readonly registry: () => string | undefined;
+    /** A file's text, or undefined when it cannot be read: the XDG user dirs on Linux. */
+    readonly readText: (path: string) => string | undefined;
+}
+/** The player's data folder: CHESSPAL_HOME when set, else the system's Documents with Chesspal's folder in it. */
+export declare function dataFolder(system?: System): string;

package/dist/home/data-folder.js

@@ -0,0 +1,55 @@
+// The player's data folder (D-71): Documents\My Games\Chesspal on Windows, wherever the system keeps Documents, OneDrive too; Documents/Chesspal
+// elsewhere, where Linux's XDG user dirs put Documents; CHESSPAL_HOME in its place, for the tests and the playtests.
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+/** The player's data folder: CHESSPAL_HOME when set, else the system's Documents with Chesspal's folder in it. */
+export function dataFolder(system = thisSystem()) {
+    const chosen = system.env.CHESSPAL_HOME?.trim();
+    const path = system.platform === "win32" ? win32 : posix;
+    if (chosen !== undefined && chosen !== "") {
+        return path.resolve(chosen);
+    }
+    if (system.platform === "win32") {
+        return win32.join(windowsDocuments(system), "My Games", "Chesspal");
+    }
+    return posix.join(system.platform === "darwin" ? posix.join(system.home, "Documents") : xdgDocuments(system), "Chesspal");
+}
+// Where Windows keeps Documents for this user, as Explorer's known folder does: the registry names it, with variables such as %USERPROFILE%.
+const shellFolders = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders";
+function thisSystem() {
+    return { env: process.env, platform: process.platform, home: homedir(), registry: readRegistry, readText };
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Documents as the XDG user dirs name it, in the system's language, such as ~/Documenti, as GLib reads them; ~/Documents when they say nothing usable. */
+function xdgDocuments({ env, home, readText }) {
+    const config = env.XDG_CONFIG_HOME?.startsWith("/") === true ? env.XDG_CONFIG_HOME : posix.join(home, ".config");
+    const named = /^\s*XDG_DOCUMENTS_DIR\s*=\s*"([^"]*)"/m.exec(readText(posix.join(config, "user-dirs.dirs")) ?? "")?.[1];
+    const filled = named?.replace(/^\$HOME(?=\/|$)/, home);
+    return filled !== undefined && posix.isAbsolute(filled) ? posix.normalize(filled) : posix.join(home, "Documents");
+}
+// About 40 ms, once a process: PowerShell would say the same in 270. reg writes in the console's code page, which breaks a folder with accents: UTF-8 first.
+function readRegistry() {
+    const command = `"chcp 65001 >nul & reg query "${shellFolders}" /v Personal"`;
+    const answer = spawnSync("cmd.exe", ["/d", "/s", "/c", command], { encoding: "utf8", windowsHide: true, windowsVerbatimArguments: true, timeout: 5_000 });
+    return answer.status === 0 ? answer.stdout : undefined;
+}
+/** Documents as the registry names it, with its variables filled in; the user's own Documents when the registry says nothing usable. */
+function windowsDocuments({ env, home, registry }) {
+    const named = /^\s*Personal\s+REG_(?:EXPAND_)?SZ\s+(.+?)\s*$/m.exec(registry() ?? "")?.[1];
+    const filled = named?.replace(/%([^%]+)%/g, (whole, name) => valueOf(env, name) ?? whole);
+    return filled !== undefined && win32.isAbsolute(filled) && !/[%�]/.test(filled) ? filled : win32.join(valueOf(env, "USERPROFILE") ?? home, "Documents");
+}
+// Windows's variables, whatever their case.
+function valueOf(env, name) {
+    const key = Object.keys(env).find((one) => one.toLowerCase() === name.toLowerCase());
+    return key === undefined ? undefined : env[key];
+}

package/dist/home/index.d.ts

@@ -0,0 +1,2 @@
+export { dataFolder, type System } from "./data-folder.ts";
+export { openFolder } from "./open-folder.ts";

package/dist/home/index.js

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

package/dist/home/open-folder.d.ts

@@ -0,0 +1,2 @@
+/** Opens a folder in the system's file manager, without waiting for it to close: whether the manager started, for the page to say so when it did not. */
+export declare function openFolder(folder: string, platform: string): Promise<boolean>;

package/dist/home/open-folder.js

@@ -0,0 +1,14 @@
+// The data folder shown to the player in the system's own file manager (T-119): Explorer, Finder, or the Linux desktop's.
+import { spawn } from "node:child_process";
+/** Opens a folder in the system's file manager, without waiting for it to close: whether the manager started, for the page to say so when it did not. */
+export function openFolder(folder, platform) {
+    const manager = platform === "win32" ? "explorer.exe" : platform === "darwin" ? "open" : "xdg-open";
+    return new Promise((done) => {
+        const opened = spawn(manager, [folder], { detached: true, stdio: "ignore" });
+        opened.once("spawn", () => {
+            opened.unref();
+            done(true);
+        });
+        opened.once("error", () => done(false));
+    });
+}