chesspal 0.1.0 → 0.2.0

package/dist/games/talk.js

@@ -1,4 +1,4 @@
-// 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).
+// The talk on the board page (D-51): 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 };
@@ -25,7 +25,7 @@ export function talkLine(current, sayer, text, at, ply = isGame(current) ? curre
     }
     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. */
+/** Words refused, and why, for the page to say it in the player's language: none, the move's characters spent, more than a line or what is left holds. */
 export class WordsRefused extends Error {
     reason;
     most;
@@ -35,18 +35,6 @@ export class WordsRefused extends Error {
         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;
@@ -63,6 +51,18 @@ export function heardLines(current, given) {
         return line.who === "ai" ? undefined : !waiting.has(key) ? "answered" : given.has(key) ? "read" : "sent";
     });
 }
+/** 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. */
+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). */
+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);
+}
 /**
  * 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

package/dist/home/open-folder.js

@@ -1,4 +1,4 @@
-// The data folder shown to the player in the system's own file manager (T-119): Explorer, Finder, or the Linux desktop's.
+// The data folder shown to the player in the system's own file manager: 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) {

package/dist/host-files/{ponder-agents.d.ts → agents.d.ts}

@@ -1,12 +1,20 @@
 import type { AiLevel } from "../core/index.ts";
+/** The agents that think for the AI, by their names. */
+export declare const ponderAgents: readonly string[];
+/** The coach's agent (D-88). */
+export declare const coachAgent = "chesspal-coach";
+/** The analyst's agent, which reviews a game over on the board page when the player wants it (D-89). */
+export declare const analystAgent = "chesspal-analyst";
 /** The agent that thinks for the AI at a level: on the quick model at the beginner and club levels, on the AI's own above. */
 export declare function ponderAgentFor(level: AiLevel): string;
 /** Whether the AI's thoughts on the player's time come from a quicker model than its own at a level. */
 export declare function onQuickModel(level: AiLevel): boolean;
 /** Whether the player's folder has the agent, as init writes it: a folder set up before it has none, and the AI then plays as before. */
-export declare function hasPonderAgent(folder: string, agent: string): boolean;
+export declare function hasAgent(folder: string, agent: string): boolean;
 /** The agents' files, as Claude Code reads them from .claude/agents: Chesspal's whole, rewritten by init. */
-export declare function ponderAgentFiles(folder: string): {
+export declare function agentFiles(folder: string): {
     path: string;
     text: string;
 }[];
+/** Instructions for the AI, by their file's name in the package's instructions folder. */
+export declare function instructions(name: string): string;

package/dist/host-files/agents.js

@@ -0,0 +1,53 @@
+// The agents that work in the background in Claude Code: those that think for the opponent on the player's time (D-72), one on the host's quick model for the
+// lower levels, one on the AI's own for the higher; the coach, with the helps on (D-88), and the analyst of a game over (D-89), on the AI's own model.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const quickAgent = "chesspal-ponder-quick";
+const ownAgent = "chesspal-ponder";
+/** The agents that think for the AI, by their names. */
+export const ponderAgents = [quickAgent, ownAgent];
+/** The coach's agent (D-88). */
+export const coachAgent = "chesspal-coach";
+/** The analyst's agent, which reviews a game over on the board page when the player wants it (D-89). */
+export const analystAgent = "chesspal-analyst";
+/** The agent that thinks for the AI at a level: on the quick model at the beginner and club levels, on the AI's own above. */
+export function ponderAgentFor(level) {
+    return onQuickModel(level) ? quickAgent : ownAgent;
+}
+/** Whether the AI's thoughts on the player's time come from a quicker model than its own at a level. */
+export function onQuickModel(level) {
+    return level === "beginner" || level === "club";
+}
+/** Whether the player's folder has the agent, as init writes it: a folder set up before it has none, and the AI then plays as before. */
+export function hasAgent(folder, agent) {
+    return existsSync(agentPath(folder, agent));
+}
+/** The agents' files, as Claude Code reads them from .claude/agents: Chesspal's whole, rewritten by init. */
+export function agentFiles(folder) {
+    const ponder = instructions("ponder");
+    const thinking = "Chesspal's opponent thinking on the player's time. Started by the AI in the background after its move, as ai_move says.";
+    return [
+        { agent: quickAgent, model: "haiku", description: thinking, tools: ["ponder"], text: ponder },
+        { agent: ownAgent, model: "inherit", description: thinking, tools: ["ponder"], text: ponder },
+        // Its description tells the chat it starts the agent only as ai_move says, never to ask it about the game (Priya).
+        { agent: coachAgent, model: "inherit", description: "Chesspal's coach. Started only as Chesspal's answers say, in the background, never to answer the player.", tools: ["coach"], text: instructions("coach") },
+        {
+            agent: analystAgent,
+            model: "inherit",
+            description: "Chesspal's analyst. Started only as Chesspal's answers say, in the background, to review a game over on the board page; never to answer the player.",
+            tools: ["analyse_game", "annotate_game", "look", "position"],
+            text: `${instructions("analyst-agent")}\n${instructions("analysis")}`,
+        },
+    ].map(({ agent, model, description, tools, text }) => ({
+        path: agentPath(folder, agent),
+        // The tools it works with: Claude Code gives an agent its MCP tools loaded, with no search first (Priya).
+        text: ["---", `name: ${agent}`, `description: ${description}`, `tools: ${tools.map((tool) => `mcp__chesspal__${tool}`).join(", ")}`, `model: ${model}`, "---", "", text, ""].join("\n"),
+    }));
+}
+/** Instructions for the AI, by their file's name in the package's instructions folder. */
+export function instructions(name) {
+    return readFileSync(new URL(`../../instructions/${name}.md`, import.meta.url), "utf8").trim();
+}
+function agentPath(folder, agent) {
+    return join(folder, ".claude", "agents", `${agent}.md`);
+}

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

@@ -4,7 +4,12 @@
  * the files written.
  */
 export declare function setUpHosts(folder: string, platform: string): string[];
-/** Where Codex reads a folder's hooks, which it runs only once the player allows them in /hooks (T-125). */
+/**
+ * The files an older init wrote in a folder, or left out, that this version would write otherwise, by their paths in it: the AI and the page then ask the
+ * player to run init again. None in a folder init never set up.
+ */
+export declare function outdatedHostFiles(folder: string, platform: string): string[];
+/** Where Codex reads a folder's hooks, which it runs only once the player trusts them. */
 export declare function codexHooksPath(folder: string): string;
-/** The instructions of the AI opponent, read from the package wherever it is installed (T-8). */
+/** The instructions of the AI opponent, read from the package wherever it is installed. */
 export declare function opponentInstructions(): string;

package/dist/host-files/host-files.js

@@ -1,7 +1,8 @@
+// What `chesspal init` writes in a player's folder for each AI host: the opponent's instructions, the MCP server, the hooks and the agents.
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { makeFolder, writeAtomically } from "../games/index.js";
-import { ponderAgentFiles } from "./ponder-agents.js";
+import { agentFiles, instructions } from "./agents.js";
 /**
  * Sets up the player's folder for Claude Code and Codex (D-31): .mcp.json with the chesspal server, AGENTS.md with the opponent's instructions between
  * Chesspal's marks, CLAUDE.md importing it, the hosts' settings with the server approved, and their hooks. What the player wrote there stays; it returns
@@ -9,33 +10,47 @@ import { ponderAgentFiles } from "./ponder-agents.js";
  */
 export function setUpHosts(folder, platform) {
     makeFolder(folder);
-    const changes = [mcpFile(folder, platform), agentsFile(folder), claudeFile(folder), claudeSettingsFile(folder), ...ponderAgentChanges(folder), codexConfigFile(folder, platform), codexHooksFile(folder)];
-    const written = changes.filter((change) => change !== undefined);
+    const written = hostChanges(folder, platform);
     for (const { path, text } of written) {
         makeFolder(join(path, ".."));
         writeAtomically(path, text);
     }
     return written.map(({ path }) => path);
 }
-/** Where Codex reads a folder's hooks, which it runs only once the player allows them in /hooks (T-125). */
+/**
+ * The files an older init wrote in a folder, or left out, that this version would write otherwise, by their paths in it: the AI and the page then ask the
+ * player to run init again. None in a folder init never set up.
+ */
+export function outdatedHostFiles(folder, platform) {
+    if (!markedBlock.test(textOf(join(folder, "AGENTS.md")) ?? "")) {
+        return [];
+    }
+    return hostChanges(folder, platform).map(({ path }) => relative(folder, path));
+}
+/** Where Codex reads a folder's hooks, which it runs only once the player trusts them. */
 export function codexHooksPath(folder) {
     return join(folder, ".codex", "hooks.json");
 }
-/** The instructions of the AI opponent, read from the package wherever it is installed (T-8). */
+/** The instructions of the AI opponent, read from the package wherever it is installed. */
 export function opponentInstructions() {
-    return readFileSync(new URL("../../instructions/opponent.md", import.meta.url), "utf8").trim();
+    return instructions("opponent");
 }
 // The marks around Chesspal's lines in AGENTS.md: init rewrites what lies between them, and the player's own text stays around them.
 const startMark = "<!-- chesspal: these lines up to the end mark are Chesspal's, and chesspal init rewrites them; write your own after it. -->";
 const endMark = "<!-- chesspal: end -->";
 const markedBlock = /<!-- chesspal: (?!end)[^\n]*\n[\s\S]*?<!-- chesspal: end -->/;
+/** What init writes for each host, missing or changed: what the player wrote there stays. */
+function hostChanges(folder, platform) {
+    const changes = [mcpFile(folder, platform), agentsFile(folder), claudeFile(folder), claudeSettingsFile(folder), ...ponderAgentChanges(folder), codexConfigFile(folder, platform), codexHooksFile(folder)];
+    return changes.filter((change) => change !== undefined);
+}
 /** How a host starts the server: on Windows through cmd, which finds npm's shim. */
 function chesspalServer(platform) {
     return platform === "win32" ? { command: "cmd", args: ["/c", "chesspal", "mcp"] } : { command: "chesspal", args: ["mcp"] };
 }
-/** Claude Code's agents that think on the player's time, Chesspal's whole: written when they are missing or changed. */
+/** Claude Code's agents that work on the player's time, thinking for the opponent and coaching, Chesspal's whole: written when they are missing or changed. */
 function ponderAgentChanges(folder) {
-    return ponderAgentFiles(folder).filter(({ path, text }) => textOf(path) !== text);
+    return agentFiles(folder).filter(({ path, text }) => textOf(path) !== text);
 }
 /** .mcp.json with the chesspal server, beside the servers already there, keeping the environment the player gave it, as CHESSPAL_HOME in a playtest. */
 function mcpFile(folder, platform) {
@@ -112,14 +127,14 @@ function codexConfigFile(folder, platform) {
     const text = rest === "" ? table : `${rest}\n\n${table}`;
     return text === before ? undefined : { path, text };
 }
-/** Codex's hooks, read once the player has reviewed them in /hooks: the doorbell of the moves on the page (T-62) and how each chat starts (T-104), beside the player's own. */
+/** Codex's hooks, read once the player has trusted them: the doorbell of the moves on the page and how each chat starts, beside the player's own. */
 function codexHooksFile(folder) {
     const path = codexHooksPath(folder);
     const config = jsonOf(path);
     const hooks = isObject(config.hooks) ? config.hooks : {};
     return changed(path, { ...config, hooks: withHook(withHook(hooks, "Stop", codexBellHook), "SessionStart", codexChatHook) });
 }
-// Codex's Stop hook for the doorbell (T-62): it holds the turn until the player acts on the page, then Codex goes on; a day at most. On Windows Codex runs
+// Codex's Stop hook for the doorbell: it holds the turn until the player acts on the page, then Codex goes on; a day at most. On Windows Codex runs
 // it in PowerShell, where `chesspal` would be npm's .ps1 shim, which a strict execution policy stops.
 const codexBellHook = {
     type: "command",
@@ -128,7 +143,7 @@ const codexBellHook = {
     timeout: 86_400,
     statusMessage: "Waiting for your move on the board page",
 };
-// Codex's SessionStart hook (T-104): it notes how each chat starts, as Claude Code's does (D-57).
+// Codex's SessionStart hook: it notes how each chat starts, as Claude Code's does (D-57).
 const codexChatHook = { type: "command", command: "chesspal chat", commandWindows: "chesspal.cmd chat" };
 /** A JSON file's new content, when it differs from what is there. */
 function changed(path, value) {

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

@@ -1,2 +1,2 @@
-export { codexHooksPath, opponentInstructions, setUpHosts } from "./host-files.ts";
-export { hasPonderAgent, onQuickModel, ponderAgentFor } from "./ponder-agents.ts";
+export { analystAgent, coachAgent, hasAgent, instructions, onQuickModel, ponderAgentFor, ponderAgents } from "./agents.ts";
+export { codexHooksPath, opponentInstructions, outdatedHostFiles, setUpHosts } from "./host-files.ts";

package/dist/host-files/index.js

@@ -1,3 +1,3 @@
-// The files through which an AI host finds Chesspal in the player's folder (T-7): the server, the opponent's instructions, the hosts' settings.
-export { codexHooksPath, opponentInstructions, setUpHosts } from "./host-files.js";
-export { hasPonderAgent, onQuickModel, ponderAgentFor } from "./ponder-agents.js";
+// The files through which an AI host finds Chesspal in the player's folder: the server, the opponent's instructions, the hosts' settings.
+export { analystAgent, coachAgent, hasAgent, instructions, onQuickModel, ponderAgentFor, ponderAgents } from "./agents.js";
+export { codexHooksPath, opponentInstructions, outdatedHostFiles, setUpHosts } from "./host-files.js";

package/dist/index.d.ts

@@ -1,4 +1,2 @@
-export type { Context } from "./commands/context.ts";
-export { commands } from "./commands/index.ts";
-export type { AnyCommand, Command } from "./commands/registry.ts";
+export { type AnyCommand, type Command, commands, type Context } from "./commands/index.ts";
 export { version } from "./version.ts";

package/dist/index.js

@@ -1,2 +1,3 @@
+// Chesspal's public API: what a program that imports the package reaches.
 export { commands } from "./commands/index.js";
 export { version } from "./version.js";

package/dist/page/app/anchor.js

@@ -0,0 +1,88 @@
+// The move shown, kept in the page's address as #2026-11-04-184025/31: the game by its name and how many of its moves are shown, so that a reload keeps it and
+// a link brings the player back to it.
+import { useEffect, useRef, useState } from "preact/hooks";
+/** The place an address's hash names, or none: #2026-11-04-184025/31 a move of a game, #2026-11-04-184025 the game as it is. */
+export function anchorOf(hash) {
+    const [, game, plies] = new RegExp(`^#?(${stem})(?:/(\\d{1,4}))?$`).exec(hash) ?? [];
+    return game === undefined ? undefined : plies === undefined ? { game } : { game, plies: Number(plies) };
+}
+/** The hash of a place in a game, as anchorOf reads it. */
+export function hashOf(anchor) {
+    return anchor.plies === undefined ? `#${anchor.game}` : `#${anchor.game}/${anchor.plies}`;
+}
+/** A game's name in the address, from its name in the player's folder: games/2026-11-04-184025.pgn and study/2026-11-04-184025.pgn are 2026-11-04-184025. */
+export function anchorName(name) {
+    return new RegExp(`(${stem})\\.pgn$`).exec(name)?.[1];
+}
+// A game's name without its folder and .pgn, the time it started, as games/archive.ts writes it: the page cannot import that module.
+const stem = /\d{4}-\d{2}-\d{2}-\d{6}/.source;
+/**
+ * What the page does with the place the address names: goes to its move on the game shown; drops it while a game goes on; waits while its game opens in
+ * analysis, `asked` already; else opens its game in analysis, but the game just played, which opens on the player's yes alone (D-89): the link waits for
+ * it while the table is set (D-77), and goes once another game shows (Zoe).
+ */
+export function anchorAction(wanted, games, asked) {
+    if (wanted.game === games.shown) {
+        return "view";
+    }
+    if (games.going) {
+        return "drop";
+    }
+    if (wanted.game === games.played) {
+        return games.shown === undefined ? "wait" : "drop";
+    }
+    return wanted.game === asked ? "wait" : "open";
+}
+/** The hash of the move shown: the game alone at its end, and while it goes on, when the player wants the position as it is (Zoe). */
+export function shownHash(games, viewing) {
+    return games.shown === undefined ? "" : hashOf(viewing === undefined || games.going ? { game: games.shown } : { game: games.shown, plies: viewing });
+}
+/**
+ * Keeps the move shown in the address, and goes to the place the address names as the page opens or as the player writes it (anchorAction); `open` opens a
+ * game in analysis and says whether it did. A link never shows its move on another game.
+ */
+export function useAnchor(games, viewing, view, open) {
+    const { ready, shown, played, going } = games;
+    const [wanted, setWanted] = useState(() => anchorOf(location.hash));
+    const asked = useRef(undefined);
+    useEffect(() => {
+        const heard = () => {
+            asked.current = undefined;
+            setWanted(anchorOf(location.hash));
+        };
+        window.addEventListener("hashchange", heard);
+        return () => window.removeEventListener("hashchange", heard);
+    }, []);
+    useEffect(() => {
+        if (!ready || wanted === undefined) {
+            return;
+        }
+        const action = anchorAction(wanted, games, asked.current);
+        if (action === "view") {
+            view(wanted.plies);
+        }
+        if (action === "view" || action === "drop") {
+            setWanted(undefined);
+        }
+        if (action !== "open") {
+            return;
+        }
+        const game = wanted.game;
+        asked.current = game;
+        void open(game).then((opened) => {
+            // A place written since stays wanted (Federico).
+            if (!opened && asked.current === game) {
+                setWanted(undefined);
+            }
+        });
+    }, [ready, shown, played, going, wanted]);
+    useEffect(() => {
+        if (!ready || wanted !== undefined) {
+            return;
+        }
+        const hash = shownHash(games, viewing);
+        if (hash !== location.hash) {
+            history.replaceState(history.state, "", hash === "" ? location.pathname + location.search : hash);
+        }
+    }, [ready, shown, going, viewing, wanted]);
+}