llm-chess-mcp 0.4.4 → 0.4.8

package/README.md

@@ -16,31 +16,15 @@ judgment; the MCP server handles all the computation.
 | **Maia3 5M** (ONNX) | Human-like move probabilities conditioned on Elo | In-process (`onnxruntime-node`) |
 | **Lichess explorer** | Real human game statistics | HTTP (needs token) |
 
-Everything runs inside the Node process — no external engine process or Python
+Everything runs inside the Node process. No external engine process or Python
 runtime is required at deploy time. The published package bundles the Maia3 5M
 model; other export variants are not runtime options unless their ONNX files are
 provided separately.
 
-## Install
+## Build from source
 
-Requires Node.js 20 or newer.
-
-No install needed — run it directly with `npx`:
-
-```bash
-npx -y llm-chess-mcp
-```
-
-The Maia3 model is already bundled, so there's no Python, torch, or engine
-binaries to install. `npx` fetches the package on first run and caches it.
-
-To install it permanently instead:
-
-```bash
-npm install -g llm-chess-mcp
-```
-
-### Build from source
+The published runtime supports Node.js 20.3 and newer. Repository maintenance
+uses Node.js 22.13 or newer because pnpm 11 and the coverage gate require it.
 
 ```bash
 pnpm install
@@ -52,24 +36,6 @@ pnpm test
 the MCP transport tests. `pnpm check` runs the full local gate; use
 `pnpm release:check` before publishing.
 
-### Maintainers
-
-[Architecture](docs/architecture.md) describes runtime and service boundaries.
-
-Local quality commands:
-
-```bash
-pnpm typecheck
-pnpm test:coverage
-pnpm contract:check
-pnpm check
-pnpm test:package
-```
-
-`pnpm test:stress` runs the short real-engine concurrency check.
-`pnpm test:live` queries Lichess only when `LICHESS_TOKEN` is set; otherwise it
-skips without making a network request.
-
 ## Transports
 
 stdio remains the default transport and requires no flags. To expose a local
@@ -93,100 +59,25 @@ HTTP options:
 --allowed-host <host>    Allowed Host/Origin hostname; repeat as needed
 ```
 
-Binding to `0.0.0.0` or `::` requires at least one `--allowed-host`. HTTP mode
-does not provide authentication or TLS; use a trusted network or an
-authenticated reverse proxy when exposing it beyond localhost. Origin values
-are validated when present, but the server does not emit browser CORS headers.
-
-### Reverse-proxy deployment
+The package also exposes a typed ESM API:
 
-The HTTP server is intended to run behind a reverse proxy for any non-local
-deployment. The proxy owns TLS termination, client authentication, external
-rate/connection limits, and any future CORS policy. Bind this process to
-localhost only; never expose its port directly through a firewall, container
-port mapping, or load balancer.
+```js
+import { serveHttp } from "llm-chess-mcp";
 
-For example, start the backend with the public hostname that Nginx will pass
-through as `Host`:
-
-```bash
-node dist/index.js --transport http --host 127.0.0.1 --port 3000 \
-  --allowed-host chess-mcp.example.com
-```
-
-This is a minimal Nginx layout. It assumes an identity-aware auth service is
-available only on localhost at `127.0.0.1:4180`; configure that service and
-the certificate paths for the deployment. The limits are examples, not a
-substitute for capacity planning.
-
-```nginx
-limit_req_zone $binary_remote_addr zone=mcp_req:10m rate=5r/s;
-limit_conn_zone $binary_remote_addr zone=mcp_conn:10m;
-
-server {
-    listen 443 ssl;
-    server_name chess-mcp.example.com;
-    ssl_certificate     /etc/ssl/certs/chess-mcp.pem;
-    ssl_certificate_key /etc/ssl/private/chess-mcp.key;
-
-    location = /_mcp_auth {
-        internal;
-        proxy_pass http://127.0.0.1:4180/auth;
-        proxy_pass_request_body off;
-        proxy_set_header Content-Length "";
-        proxy_set_header X-Original-Method $request_method;
-        proxy_set_header X-Original-URI $request_uri;
-    }
-
-    location = /mcp {
-        auth_request /_mcp_auth;
-        limit_req zone=mcp_req burst=20 nodelay;
-        limit_conn mcp_conn 10;
-        client_max_body_size 2m;
-
-        proxy_pass http://127.0.0.1:3000;
-        proxy_http_version 1.1;
-        proxy_set_header Connection "";
-        proxy_set_header Host $host;
-        proxy_set_header X-Forwarded-Proto https;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-User "";
-        proxy_set_header X-Forwarded-Email "";
-        proxy_buffering off;
-        proxy_read_timeout 90s;
-
-        # Intentionally no Access-Control-Allow-* headers: browser CORS is unsupported.
-    }
-}
+const server = await serveHttp({ port: 3000, bodyTimeoutMs: 15_000 });
+await server.close();
 ```
 
-The application does not trust forwarded identity headers and does not assign
-games to authenticated users. All games in one process share one `GameStore`;
-the opaque `game_id` is the capability to operate a game within the trusted
-deployment, not an OAuth token or user identity. Do not disclose it across
-trust boundaries.
-
-This server does not implement MCP OAuth discovery, bearer-token validation,
-or browser CORS. A proxy may authenticate access to the endpoint, but that is
-deployment policy rather than an application-level identity or ownership
-model. Browser clients are unsupported unless a proxy deliberately adds and
-maintains the required CORS policy.
-
-### Export Maia3 to ONNX (build-time only)
-
-This step needs Python + PyTorch once. It downloads the Maia3 checkpoint, verifies
-the reimplementation against the original, and exports `models/maia3-5m.onnx`.
+`bodyTimeoutMs` limits HTTP body upload time; it is not a whole-tool deadline.
+The deprecated `requestTimeoutMs` alias remains supported when `bodyTimeoutMs`
+is omitted.
 
-```bash
-uv venv .venv-maia3 --python 3.13
-uv pip install --python .venv-maia3/bin/python -r scripts/requirements.txt
-uv pip install --python .venv-maia3/bin/python "maia3 @ git+https://github.com/CSSLab/maia3.git@1e13597c42d4858b7cfd7cfdae01e297263364b2"
-pnpm export:maia3            # -> models/maia3-5m.onnx
-```
-
-The resulting `.onnx` is committed/bundled; end users never need Python or torch.
+Binding to `0.0.0.0` or `::` requires at least one `--allowed-host`. HTTP mode
+does not provide authentication or TLS; use a trusted network or an
+authenticated reverse proxy when exposing it beyond localhost. Origin values
+are validated when present, but the server does not emit browser CORS headers.
 
-### Lichess token (optional)
+## Lichess token (optional)
 
 The opening explorer now requires authentication. Generate a personal access token
 at <https://lichess.org/account/oauth/token/create> and set it in `.env`:
@@ -203,7 +94,9 @@ Explorer filters are strict. Speeds are `ultraBullet`, `bullet`, `blitz`,
 `1200`, `1400`, `1600`, `1800`, `2000`, `2200`, and `2500`. `masters` accepts
 neither filter. Invalid filters fail locally. Transient failures (network,
 timeout, 429, and 5xx) are retried once within a 12-second total budget;
-invalid requests and other 4xx responses are not retried.
+invalid requests and other 4xx responses are not retried. Responses must be
+valid UTF-8 JSON and are limited to 1 MiB, 256 moves, and 256 characters per
+move or opening string.
 
 ## Configure in your MCP client
 
@@ -372,13 +265,18 @@ rejected:
 - Up to 1,000 games are retained per process; idle games expire after one hour.
 - `move_evaluate` accepts at most 10 moves per call.
 - Imported PGNs are limited to 1 MiB and 4,096 plies.
+- Custom FENs reject inconsistent castling/en-passant metadata and impossible
+  pawn or promotion material.
 - Stockfish accepts up to 32 active or queued analyses.
+- Lichess Explorer requests run one at a time and share 429 cooldowns.
 - HTTP retains at most 64 MCP sessions; sessions with no active request expire
   after 30 minutes. An open GET/SSE stream keeps its session active.
 - HTTP accepts bodies up to 2 MiB. It permits 16 concurrent POSTs and downstream
-  compute/network jobs process-wide, with two of each per session. Work keeps
-  its slot after a raw disconnect until it settles. HTTP also caps connections
-  at 128 and applies bounded header, upload, socket, and keep-alive timeouts.
+  compute/network jobs process-wide, with two of each per session. A separately
+  bounded control lane keeps MCP cancellation available when normal POST slots
+  are full. Work keeps its slot after a raw disconnect until it settles. HTTP
+  also caps connections at 128 and applies a 15-second body upload deadline
+  plus bounded header, socket, and keep-alive timeouts.
 
 Programmatic users can override the HTTP limits through `HttpServerOptions`.
 These safeguards do not replace public-edge quotas: a public deployment must
@@ -386,10 +284,12 @@ still enforce request, connection, and authentication limits at the reverse
 proxy.
 
 MCP cancellation notifications, session deletion, and server shutdown propagate
-to Stockfish, Maia, and Lichess work. Stockfish stops safely at its UCI queue
-boundary; Lichess fetch and retry waits abort immediately. ONNX Runtime cannot
-interrupt an inference already executing, so Maia discards its result after the
-native call returns. A raw HTTP disconnect alone is not a cancellation signal.
+to body uploads and Stockfish, Maia, and Lichess work. Stockfish stops safely at
+its UCI queue boundary, drains queued work during shutdown, and rejects new
+analysis until teardown completes. Lichess fetch and retry waits abort immediately. ONNX
+Runtime cannot interrupt an inference already executing, so Maia discards its
+result after the native call returns. A raw HTTP disconnect alone is not a
+cancellation signal.
 
 ## Intents
 
@@ -425,6 +325,20 @@ Go deeper only when you need to:
 - `opening_explorer` — real-game statistics
 - `move_evaluate` — score a specific move (or compare several)
 
+## Export Maia3 to ONNX
+
+This step needs Python + PyTorch once. It downloads the Maia3 checkpoint, verifies
+the reimplementation against the original, and exports `models/maia3-5m.onnx`.
+
+```bash
+uv venv .venv-maia3 --python 3.13
+uv pip install --python .venv-maia3/bin/python -r scripts/requirements.txt
+uv pip install --python .venv-maia3/bin/python "maia3 @ git+https://github.com/CSSLab/maia3.git@1e13597c42d4858b7cfd7cfdae01e297263364b2"
+pnpm export:maia3            # -> models/maia3-5m.onnx
+```
+
+The resulting `.onnx` is committed/bundled.
+
 ## Maia3 ONNX verification
 
 The exported ONNX model is regression-tested against the upstream Maia3

package/dist/chess-copy.d.ts

@@ -0,0 +1,4 @@
+import { Chess } from "chess.js";
+export declare function assertSafeFenCounters(fen: string): void;
+export declare function assertLegalPosition(chess: Chess): void;
+export declare function snapshotChess(chess: Chess): Chess;

package/dist/chess-copy.js

@@ -0,0 +1,126 @@
+import { Chess } from "chess.js";
+import { ChessError } from "./errors.js";
+const ORIGINAL_PIECES = {
+    q: 1,
+    r: 2,
+    n: 2,
+};
+function squareColor(square) {
+    return ((square.charCodeAt(0) - 97 + Number(square[1])) % 2);
+}
+function hasPiece(chess, square, type, color) {
+    const piece = chess.get(square);
+    return piece?.type === type && piece.color === color;
+}
+function assertCastlingPosition(chess, color) {
+    const rank = color === "w" ? "1" : "8";
+    const rights = chess.getCastlingRights(color);
+    if ((rights.k || rights.q) &&
+        !hasPiece(chess, `e${rank}`, "k", color)) {
+        throw new ChessError("INVALID_FEN", "FEN castling rights require a home king");
+    }
+    if (rights.k && !hasPiece(chess, `h${rank}`, "r", color)) {
+        throw new ChessError("INVALID_FEN", "FEN kingside castling rights require a home rook");
+    }
+    if (rights.q && !hasPiece(chess, `a${rank}`, "r", color)) {
+        throw new ChessError("INVALID_FEN", "FEN queenside castling rights require a home rook");
+    }
+}
+function assertEnPassantPosition(chess) {
+    const fields = chess.fen({ forceEnpassantSquare: true }).split(" ");
+    const target = fields[3];
+    if (!target || target === "-")
+        return;
+    const turn = chess.turn();
+    const file = target[0];
+    const targetRank = turn === "w" ? "6" : "3";
+    const pawnRank = turn === "w" ? "5" : "4";
+    const originRank = turn === "w" ? "7" : "2";
+    const pawnColor = turn === "w" ? "b" : "w";
+    const targetSquare = target;
+    const pawnSquare = `${file}${pawnRank}`;
+    const originSquare = `${file}${originRank}`;
+    if (target[1] !== targetRank ||
+        chess.get(targetSquare) !== undefined ||
+        !hasPiece(chess, pawnSquare, "p", pawnColor) ||
+        chess.get(originSquare) !== undefined ||
+        fields[4] !== "0" ||
+        (turn === "w" && fields[5] === "1")) {
+        throw new ChessError("INVALID_FEN", "FEN en passant target does not match a double pawn move");
+    }
+}
+function moveDescriptor(move) {
+    const base = { from: move.from, to: move.to };
+    return move.promotion ? { ...base, promotion: move.promotion } : base;
+}
+function isSafeDecimal(value, minimum) {
+    return (/^(?:0|[1-9]\d*)$/.test(value) &&
+        Number.isSafeInteger(Number(value)) &&
+        Number(value) >= minimum);
+}
+export function assertSafeFenCounters(fen) {
+    const fields = fen.split(/\s+/);
+    if (fields.length >= 5 && !isSafeDecimal(fields[4] ?? "", 0)) {
+        throw new ChessError("INVALID_FEN", "FEN halfmove clock must be a non-negative safe decimal integer");
+    }
+    if (fields.length >= 6 && !isSafeDecimal(fields[5] ?? "", 1)) {
+        throw new ChessError("INVALID_FEN", "FEN fullmove number must be a positive safe decimal integer");
+    }
+}
+export function assertLegalPosition(chess) {
+    for (const color of ["w", "b"]) {
+        if (chess.findPiece({ type: "k", color }).length !== 1) {
+            throw new ChessError("INVALID_FEN", "FEN must contain exactly one king per side");
+        }
+        const pawns = chess.findPiece({ type: "p", color });
+        if (pawns.some((square) => square[1] === "1" || square[1] === "8")) {
+            throw new ChessError("INVALID_FEN", "FEN pawns cannot occupy the first or eighth rank");
+        }
+        if (pawns.length > 8) {
+            throw new ChessError("INVALID_FEN", "FEN cannot contain more than eight pawns per side");
+        }
+        const promotedPieces = Object.entries(ORIGINAL_PIECES).reduce((total, [type, original]) => total +
+            Math.max(0, chess.findPiece({ type: type, color }).length -
+                original), 0);
+        const promotedBishops = [0, 1].reduce((total, squareColorValue) => total +
+            Math.max(0, chess
+                .findPiece({ type: "b", color })
+                .filter((square) => squareColor(square) === squareColorValue)
+                .length - 1), 0);
+        const promoted = promotedPieces + promotedBishops;
+        if (promoted > 8 - pawns.length) {
+            throw new ChessError("INVALID_FEN", "FEN contains more promoted material than missing pawns allow");
+        }
+        assertCastlingPosition(chess, color);
+    }
+    assertEnPassantPosition(chess);
+    const turn = chess.turn();
+    const previous = turn === "w" ? "b" : "w";
+    const previousKing = chess.findPiece({ type: "k", color: previous })[0];
+    if (previousKing && chess.isAttacked(previousKing, turn)) {
+        throw new ChessError("INVALID_FEN", "FEN cannot leave the side that just moved in check");
+    }
+}
+export function snapshotChess(chess) {
+    assertLegalPosition(chess);
+    const history = chess.history({ verbose: true });
+    const initialFen = history[0]?.before ?? chess.fen();
+    assertSafeFenCounters(initialFen);
+    const snapshot = new Chess(initialFen);
+    const comments = new Map(chess.getComments().map(({ fen, comment }) => [fen, comment]));
+    for (const [key, value] of Object.entries(chess.getHeaders())) {
+        snapshot.setHeader(key, value);
+    }
+    const restoreComment = () => {
+        const comment = comments.get(snapshot.fen());
+        if (comment !== undefined)
+            snapshot.setComment(comment);
+    };
+    restoreComment();
+    for (const move of history) {
+        snapshot.move(moveDescriptor(move));
+        restoreComment();
+    }
+    assertSafeFenCounters(snapshot.fen());
+    return snapshot;
+}

package/dist/chess.d.ts

@@ -0,0 +1,13 @@
+import { Chess } from "chess.js";
+import type { Move } from "chess.js";
+export { assertLegalPosition, assertSafeFenCounters, snapshotChess, } from "./chess-copy.js";
+export { MAX_PGN_BYTES, MAX_PGN_PLIES, parseImportedPgn, pgnOf } from "./pgn.js";
+import type { ChessState, DrawResult } from "./domain.js";
+export declare const MAX_EVALUATED_MOVES = 10;
+export declare function drawResult(chess: Chess): DrawResult | null;
+export declare function stateOf<Revision extends number>(chess: Chess, revision: Revision): ChessState & {
+    revision: Revision;
+};
+export declare function parseMove(chess: Chess, move: string): Move;
+export declare function playParsedMove(chess: Chess, move: Move): Move;
+export declare function pvToSan(chess: Chess, pv: readonly string[]): string[];

package/dist/chess.js

@@ -1,21 +1,14 @@
 import { Chess } from "chess.js";
+export { assertLegalPosition, assertSafeFenCounters, snapshotChess, } from "./chess-copy.js";
+export { MAX_PGN_BYTES, MAX_PGN_PLIES, parseImportedPgn, pgnOf } from "./pgn.js";
 import { ChessError } from "./errors.js";
 export const MAX_EVALUATED_MOVES = 10;
-export const MAX_PGN_BYTES = 1024 * 1024;
-export const MAX_PGN_PLIES = 4096;
 function moveDescriptor(move) {
     const base = { from: move.from, to: move.to };
     return move.promotion ? { ...base, promotion: move.promotion } : base;
 }
-export function snapshotChess(chess) {
-    const history = chess.history({ verbose: true });
-    const snapshot = new Chess(history[0]?.before ?? chess.fen());
-    for (const move of history)
-        snapshot.move(moveDescriptor(move));
-    return snapshot;
-}
 export function drawResult(chess) {
-    if (!chess.isDraw())
+    if (chess.isCheckmate() || !chess.isDraw())
         return null;
     if (chess.isStalemate())
         return "stalemate";
@@ -27,37 +20,21 @@ export function drawResult(chess) {
         return "fifty_move_rule";
     return "draw";
 }
-export function parseImportedPgn(pgn) {
-    if (Buffer.byteLength(pgn, "utf8") > MAX_PGN_BYTES) {
-        throw new ChessError("PGN_TOO_LARGE", `PGN exceeds the ${MAX_PGN_BYTES}-byte limit`);
-    }
-    let chess;
-    try {
-        chess = new Chess();
-        chess.loadPgn(pgn);
-    }
-    catch {
-        throw new ChessError("INVALID_PGN", "invalid or illegal PGN");
-    }
-    if (chess.history().length > MAX_PGN_PLIES) {
-        throw new ChessError("PGN_TOO_MANY_MOVES", `PGN exceeds the ${MAX_PGN_PLIES}-ply limit`);
-    }
-    return chess;
-}
 export function stateOf(chess, revision) {
     const last = chess.history({ verbose: true }).at(-1);
+    const isCheckmate = chess.isCheckmate();
     return {
         fen: chess.fen(),
         turn: chess.turn(),
         revision,
         isCheck: chess.isCheck(),
-        isCheckmate: chess.isCheckmate(),
+        isCheckmate,
         isStalemate: chess.isStalemate(),
-        isDraw: chess.isDraw(),
+        isDraw: !isCheckmate && chess.isDraw(),
         isGameOver: chess.isGameOver(),
-        isInsufficientMaterial: chess.isInsufficientMaterial(),
-        isThreefoldRepetition: chess.isThreefoldRepetition(),
-        isDrawByFiftyMoves: chess.isDrawByFiftyMoves(),
+        isInsufficientMaterial: !isCheckmate && chess.isInsufficientMaterial(),
+        isThreefoldRepetition: !isCheckmate && chess.isThreefoldRepetition(),
+        isDrawByFiftyMoves: !isCheckmate && chess.isDrawByFiftyMoves(),
         moveNumber: chess.moveNumber(),
         history: chess.history(),
         lastMove: last ? { san: last.san, uci: last.lan } : null,
@@ -71,8 +48,10 @@ export function stateOf(chess, revision) {
 }
 export function parseMove(chess, move) {
     const legal = chess.moves({ verbose: true });
-    const san = move.replace(/[+#]$/, "");
-    const found = legal.find((candidate) => candidate.san.replace(/[+#]$/, "") === san) ??
+    const found = legal.find((candidate) => candidate.san === move) ??
+        (!/[+#]$/.test(move)
+            ? legal.find((candidate) => candidate.san.replace(/[+#]$/, "") === move)
+            : undefined) ??
         legal.find((candidate) => candidate.lan === move);
     if (!found)
         throw new ChessError("ILLEGAL_MOVE", `illegal move: ${move}`);

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+export type TransportKind = "stdio" | "http";
+export type CliOptions = {
+    transport: TransportKind;
+    host: string;
+    port: number;
+    path: string;
+    allowedHosts: string[];
+    help: boolean;
+};
+export declare const HELP = "Usage: llm-chess-mcp [options]\n\nOptions:\n  --transport <stdio|http>  Transport to use (default: stdio)\n  --http                    Shortcut for --transport http\n  --host <host>             HTTP bind host (default: 127.0.0.1)\n  --port <port>             HTTP listen port (default: 3000)\n  --path <path>             HTTP endpoint path (default: /mcp)\n  --allowed-host <host>     Allowed HTTP Host/Origin hostname (repeatable)\n  -h, --help                Show this help\n";
+export declare function parseCli(args: string[]): CliOptions;

package/dist/cli.js

@@ -1,3 +1,4 @@
+import { canonicalHttpHostname, DEFAULT_HTTP_HOST, DEFAULT_HTTP_PATH, DEFAULT_HTTP_PORT, isCanonicalHttpPath, isWildcardHttpBindHost, } from "./http-config.js";
 export const HELP = `Usage: llm-chess-mcp [options]
 
 Options:
@@ -22,9 +23,9 @@ function splitOption(arg) {
 }
 export function parseCli(args) {
     let transport = "stdio";
-    let host = "127.0.0.1";
-    let port = 3_000;
-    let path = "/mcp";
+    let host = DEFAULT_HTTP_HOST;
+    let port = DEFAULT_HTTP_PORT;
+    let path = DEFAULT_HTTP_PATH;
     let help = false;
     let hasHttpOption = false;
     const allowedHosts = [];
@@ -89,19 +90,27 @@ export function parseCli(args) {
     if (!Number.isInteger(port) || port < 1 || port > 65_535) {
         throw new Error("--port must be between 1 and 65535");
     }
-    if (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
+    if (!isCanonicalHttpPath(path)) {
         throw new Error("--path must be an absolute URL path without query or fragment");
     }
-    if (!host || allowedHosts.some((value) => !value)) {
-        throw new Error("HTTP hostnames must not be empty");
+    const canonicalAllowedHosts = allowedHosts.map(canonicalHttpHostname);
+    if (!host || canonicalAllowedHosts.some((value) => value === null)) {
+        throw new Error("HTTP hostnames must be non-empty hostnames");
     }
     if (transport === "stdio" && hasHttpOption) {
         throw new Error("HTTP options require --transport http");
     }
     if (transport === "http" &&
-        (host === "0.0.0.0" || host === "::" || host === "[::]") &&
-        allowedHosts.length === 0) {
+        isWildcardHttpBindHost(host) &&
+        canonicalAllowedHosts.length === 0) {
         throw new Error("wildcard HTTP binding requires at least one --allowed-host");
     }
-    return { transport, host, port, path, allowedHosts, help };
+    return {
+        transport,
+        host,
+        port,
+        path,
+        allowedHosts: canonicalAllowedHosts,
+        help,
+    };
 }

package/dist/domain.d.ts

@@ -0,0 +1,114 @@
+import type { Chess } from "chess.js";
+export declare const EXPLORER_ERROR_KINDS: readonly ["disabled", "invalid_input", "timeout", "network", "auth", "rate_limited", "upstream", "http", "invalid_response"];
+export type ExplorerErrorKind = (typeof EXPLORER_ERROR_KINDS)[number];
+export declare const COLORS: readonly ["w", "b"];
+export type Color = (typeof COLORS)[number];
+export declare const PIECES: readonly ["p", "n", "b", "r", "q", "k"];
+export type Piece = (typeof PIECES)[number];
+export declare const PROMOTIONS: readonly ["n", "b", "r", "q"];
+export type Promotion = (typeof PROMOTIONS)[number];
+export declare const DRAW_RESULTS: readonly ["stalemate", "insufficient_material", "threefold_repetition", "fifty_move_rule", "draw"];
+export type DrawResult = (typeof DRAW_RESULTS)[number];
+export declare const MOVE_EVALUATION_RESULTS: readonly ["ongoing", "checkmate", "stalemate", "insufficient_material", "threefold_repetition", "fifty_move_rule", "draw"];
+export type MoveEvaluationResult = (typeof MOVE_EVALUATION_RESULTS)[number];
+export declare const ANALYSIS_LEVELS: readonly ["fast", "normal", "deep"];
+export type AnalysisLevel = (typeof ANALYSIS_LEVELS)[number];
+export declare const MOVE_CLASSIFICATIONS: readonly ["best", "excellent", "good", "inaccuracy", "mistake", "blunder"];
+export type MoveClassification = (typeof MOVE_CLASSIFICATIONS)[number];
+export declare const INTENTS: readonly ["best", "strong", "natural", "balanced", "ease_off", "give_chance"];
+export type Intent = (typeof INTENTS)[number];
+export interface GameRecord {
+    chess: Chess;
+    createdAt: number;
+    lastAccessedAt: number;
+    revision: number;
+}
+export interface ChessState {
+    fen: string;
+    turn: Color;
+    revision: number;
+    isCheck: boolean;
+    isCheckmate: boolean;
+    isStalemate: boolean;
+    isDraw: boolean;
+    isGameOver: boolean;
+    isInsufficientMaterial: boolean;
+    isThreefoldRepetition: boolean;
+    isDrawByFiftyMoves: boolean;
+    moveNumber: number;
+    history: string[];
+    lastMove: {
+        san: string;
+        uci: string;
+    } | null;
+    castling: {
+        whiteKingside: boolean;
+        whiteQueenside: boolean;
+        blackKingside: boolean;
+        blackQueenside: boolean;
+    };
+}
+export type Wdl = [number, number, number];
+export interface SfLine {
+    multipv: number;
+    scoreCp: number | null;
+    scoreMate: number | null;
+    wdl: Wdl | null;
+    pv: string[];
+}
+export interface Maia3Move {
+    uci: string;
+    san: string;
+    prob: number;
+}
+export interface LichessMove {
+    uci: string;
+    san: string;
+    white: number;
+    draws: number;
+    black: number;
+    count: number;
+    averageRating: number | null;
+}
+export interface Objective {
+    rank: number | null;
+    moverCp: number | null;
+    whiteCp: number | null;
+    cpLoss: number | null;
+    moverMate: number | null;
+    whiteMate: number | null;
+    wdl: Wdl | null;
+}
+export interface HumanModel {
+    maia3Prob: number | null;
+    selfElo: number;
+    opponentElo: number;
+}
+type OpeningStatsValues = {
+    games: number | null;
+    frequency: number | null;
+    white: number | null;
+    draws: number | null;
+    black: number | null;
+    averageRating: number | null;
+};
+export type OpeningStats = ({
+    status: "available" | "no_data";
+} & OpeningStatsValues) | ({
+    status: "unavailable";
+    reason: ExplorerErrorKind;
+} & OpeningStatsValues) | ({
+    status: "disabled";
+} & OpeningStatsValues);
+export interface Candidate {
+    uci: string;
+    san: string;
+    objective: Objective;
+    human: HumanModel;
+    opening: OpeningStats;
+}
+export interface MoveSensitivity {
+    level: "low" | "medium" | "high";
+    topMoveSpreadCp: number | null;
+}
+export {};