---
title: ChessTB Explorer
emoji: ♟️
colorFrom: green
colorTo: blue
sdk: docker
pinned: true
app_port: 7860
license: gpl-3.0
short_description: "Interactive tablebase probing: WDL/DTZ/DTC/DTM/DTM50"
---

# ChessTB Explorer ♟️

Interactive tablebase probing interface with WDL/DTZ/DTC/DTM/DTM50 metrics.

This Hugging Face Space is deployed from
[PunisherChess/ChessTB-Explorer-Render](https://github.com/PunisherChess/ChessTB-Explorer-Render)
at commit `4969e401fa41ef1b86458cac4b6a31f9b11e08d0`.
The original authors' license and third-party notices are retained.

The application probes the public `chesstb/chesstb` bucket over HTTP byte
ranges, using the explorer's existing bounded page cache. Sources are
searched per table with raw generator output under `full/` preferred over
shipping tables at the bucket root. Castling materials use `full/castling/`
and `castling/`, respectively.
Availability of each metric depends on the published tables for that material.

`ADMIN_TOKEN` and `FLASK_SECRET_KEY` are configured as Space secrets.
The probing library follows the maintained `add-chesstb-tablebases` branch
of `noobpwnftw/python-chess`.

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://chesstb-explorer-render.onrender.com)

A single-page web application for exploring **ChessTB** chess endgame
tablebases. Paste or build any position on an interactive board and
instantly see every legal move ranked by **Distance to Zeroing (DTZ)**,
**Distance to Conversion (DTC)**, **Distance to Mate (DTM)**, and **DTM
under the 50-move rule (DTM50)** - straight from the tablebase, with no
chess engine involved.

The backend is a small Flask application that probes the tablebase through
a modified fork of [`python-chess`](https://github.com/noobpwnftw/python-chess/tree/add-chesstb-tablebases)
(the `chess.chesstb` module - see [Installation](#installation)). The frontend is
a React app built around
[Chessground](https://github.com/lichess-org/chessground) (lichess.org's
board component) and [chessops](https://github.com/niklasf/chessops) for
move generation/validation, supporting both Standard chess and Chess960
(Fischer Random).

> This tool only *displays* tablebase results - it does not generate,
> verify, or ship any tablebase data itself. See
> [Getting the tablebase files](#getting-the-tablebase-files) below.

> The probe endpoints are unauthenticated by design - evaluating a
> position is this app's public functionality. The `/admin` cache
> dashboard is gated behind `ADMIN_TOKEN`, a secret configured by the deployment
> (see [Security notes](#security-notes)).

---

## Features

- **Interactive board**: drag-and-drop moves, click-to-place pieces from
  the spare-piece trays, pawn promotion dialog, board flip (orientation
  persisted locally across visits), undo/redo.
- **Chess960 (Fischer Random) support**: a **Chess960 Mode** switch in
  the settings panel changes castling interpretation without altering the
  current board position: dragging a king onto its own rook castles the
  Chess960 way, and X-FEN/Shredder-FEN rook-file castling-rights letters
  (e.g. `HAha`) are accepted in the FEN box. Carried through the shared
  URL (`&variant=chess960`), the saved in-progress game, and PGN
  import/export (`[Variant "Chess960"]`). Off by default.
- **Lock**: a padlock button beside the FEN box that restricts board
  interaction to legal moves only: dragging, click-to-move, and the
  spare-piece trays are limited to the side to move's legal destinations,
  and off-board drops are disabled. Unlocked by default; a manual toggle
  is remembered locally across visits. Auto-play also engages Lock for
  the duration of a run (unless already locked by hand), and disables the
  padlock button until the run stops.
- **Four ranked move tables side by side**: DTZ, DTC, DTM, and DTM50
  columns, each independently sorted best-move-first. Exact metric ties
  prefer immediate checkmate, then use SAN order with promotions along
  the same path ordered queen, rook, bishop, knight. A better-scoring
  underpromotion still ranks first. Includes:
  - score text colour-coded by outcome (win / cursed win / draw /
    blessed loss / loss)
  - a **warning dot** on any move flagged cursed win or blessed loss,
    with a hover tooltip explaining the 50-move-rule nuance; a DTZ score
    that may still be a ply off after the moves are cross-checked shows a
    second tooltip line
  - an **info dot** on a draw by insufficient material, keeping the score
    text itself reading as a plain "Draw"
  - dot messages on touch or pen input: tapping a dot shows its tooltip
    text as a notice and does not play the move
  - an outcome summary (wins / draws / losses / unknown) across legal moves,
    respecting the halfmove clock and 50-move rule. It uses DTM50 outcomes,
    or DTC when DTM50 is unavailable. Without either, clock-independent
    draws, cursed wins and blessed losses count as draws; unresolved
    wins/losses count as unknown.
  - an optional pinned **Root Row** above rank 1, showing the current
    position's own score for each metric as a reference point - toggled
    from the settings panel (**Show Root Row**, off by default) and
    persisted locally
- **Best-move arrows**: the top DTZ, DTC, DTM, and DTM50 moves are drawn
  as colour-coded arrows directly on the board.
- **Auto-play**: automatically plays the best move for any of the four
  metrics on a timer. The per-move delay
  is set from the settings panel (**Autoplay Delay**, 0s–2.5s in 50ms
  steps, 1.25s by default). The countdown starts after the current
  position's tablebase results are displayed, giving you the full delay
  to read them before the next move. A metric's button is disabled when its
  table isn't present for the current material, or when the position is
  already a draw.
- **PGN import/export**: paste a PGN to load its full move tree, including
  variations, at the starting position. Step through it or click any move
  in the PGN panel, or download the current game as a PGN file.
- **CSV export** of the current move table, including the Root Row line
  ahead of rank 1 when that setting is on.
- **Move-list / PGN panel** with full undo/redo and click-to-jump - jumping
  to an earlier point in the line re-uses the cached probe instead of
  re-querying the tablebase.
- **Shareable positions**: the FEN (and, in Chess960 Mode, the active
  variant) is written to the URL hash on every move, so a link to the
  page reproduces the exact position and ruleset.
- **Session persistence**: the in-progress game (not just the position)
  survives a trip to the admin dashboard and back.
- **Board and piece set**: Libre Brown board, CBurnett piece set.
- **Streaming probes**: `/probe/stream` reports progress via
  Server-Sent Events while child positions are being probed, so the UI
  shows a live progress bar instead of a blank pause on slower lookups.
- **Hover pre-fetch**: hovering a move in the table warms the cache for
  the resulting position before selection.
- **Admin cache dashboard** (`/admin`, behind `ADMIN_TOKEN`) - live
  hit-rate stats for both LRU caches, thread-pool configuration, and a
  one-click cache-clear button.
- **Machine-readable API**: the full HTTP API is described by an OpenAPI
  3.0 document served at `/openapi.yaml`.
- **Keyboard shortcuts**: `Enter` Apply, `F` Flip, `C` Clear, `←`/`→`
  Back/Forward. The Board Settings panel lists them on devices with hover.

---

## Architecture at a glance

```
Browser (React app - see frontend/)
  ├─ engine/board.js      - chessops-backed position/rules state, chessground
  │                           wrapper (drag/drop, history, arrows), active variant
  ├─ engine/tablebase.js  - talks to /probe/stream, exposes results as state
  ├─ engine/theme.js      - board/piece-set theming
  ├─ hooks/useExplorer.js - FEN box, PGN, auto-play, settings, keyboard shortcuts
  └─ components/          - the rendered page (board, results table, PGN panel, dialogs)
        │  HTTP (JSON) / SSE (text/event-stream) - {fen, variant}
        ▼
Flask app (app.py)
  ├─ /probe, /probe/stream   - evaluate a FEN under a variant, rank every legal move
  ├─ /admin, /admin/cache/*  - cache dashboard + stats API
  └─ /openapi.yaml           - API specification
        │
        ▼
tablebase_router.py - searches TABLEBASE_PATH in order for every material,
including castling positions and recursive dependencies
        │
        ▼
chesstb.open_tablebase(...) per source   (noobpwnftw's modified python-chess fork)
        │
        ▼
ChessTB tablebase files - local disk, or a remote http(s) URL (probed
in place over byte ranges by default, or downloaded and cached to local
disk per material - see remote/remote_direct.py, remote/remote_fallback.py,
and "Getting the tablebase files" below)
```

The React app is built with Vite into `static/dist/` (`app.js`,
`app.css`), which the Flask template loads as same-origin assets, as the
Content-Security-Policy (`script-src 'self'`) requires. See
[Frontend build](#frontend-build) below.

This covers the main explorer page's (`index.html`) module graph - see
[Project structure](#project-structure) below for the complete file set,
including `admin.js` (the `/admin` dashboard's client script, a plain
server-rendered page with no build step).

The Python modules and the frontend `engine/` modules carry a file-level
docstring/header comment describing their responsibilities, and the
move-ranking algorithm itself - including
its treatment of the 50-move rule - is documented inline in `app.py`
above `evaluate_all_moves()` and the `_effective_move_wdl`/
`_effective_distance`/`_order_rank` helpers it calls.

---

## Frontend build

The explorer page is a React app (`frontend/`) built with Vite into
`static/dist/`, which the Flask app serves alongside its own
static assets. The build output is checked in, so running the app needs
no frontend server or build step. Rebuild after changing anything under
`frontend/src/`:

```bash
cd frontend
npm ci
npm run build      # writes static/dist/app.js, app.css, admin.css, fonts/
```

`frontend/src/engine/` and `frontend/src/vendor/` hold the position/rules
engine (chessops + Chessground) and the tablebase client, consumed by
the React components in `frontend/src/components/`. Shared UI primitives
(`Icon`, `Button`, `Segmented`, `Panel`) are in `frontend/src/components/ui/`.
Piece SVGs and the piece-set stylesheet are in `static/` and are linked
directly from the page template.

### Styling

Stylesheets are in `frontend/src/styles/` and are bundled by Vite into
`static/dist/app.css` (explorer page) and `static/dist/admin.css` (`/admin`).
`tokens.css` defines the colour, type, spacing, radius, elevation, motion,
and control-size custom properties; other files reference them instead of
literal values. Files are imported into the `reset`, `vendor`, and `app`
cascade layers by `index.css` and `admin.css`.

| Token group | Custom properties |
|---|---|
| Type scale | `--text-xs` 12 px, `--text-sm` 13 px, `--text-md` 14 px, `--text-lg` 16 px, `--text-xl` 20 px |
| Spacing | `--space-1` to `--space-6` (4 px to 32 px) |
| Controls | `--control-h`, `--control-h-sm` (44 px on touch-primary devices) |
| Board | `--board-light`, `--board-dark`, `--board-highlight`, read by `engine/theme.js` |

Sizes are authored in `rem`, so the large-screen root font size scaling
applies to all text and controls.

### Page layout

| Viewport | Layout |
|---|---|
| Above 1180 px | Three-column CSS grid (board, results, PGN). The results and PGN columns take the board column's height and scroll internally. |
| 768 to 1180 px | Board row above a results and PGN row; the page scrolls. |
| Below 768 px | Three horizontally swipeable screens (board, results, PGN) with a bottom navigation bar (`ScreenNav`). Header and navigation heights include the device safe-area insets, and screen heights use `dvh`. The header shows the subtitle below the title, and the board is sized to the visible height so the whole board screen fits. |

The side-to-move toggle and the board form one group (`.board-group`) as wide
as the board, with a fixed small gap between them at every screen size. Free
vertical space in the board column sits above the group.

The results panel is a `results` size container. At 49 rem wide and above it
shows the four metric columns; below that it shows one metric at a time,
selected with the metric tabs, regardless of viewport width. The desktop
layout reserves 50 rem for this panel before growing the board, so the
four-metric view can appear as soon as the three columns fit. The results
table is a fixed header table above a scrolling body table, so the scrollbar
starts at the first moves row. The body reserves no scrollbar gutter: while
its rows overflow, its table is widened by the scrollbar's measured width, so
columns keep the header's position and width whether or not a scrollbar shows.
The PGN move-number column width is set by `--pgn-rank-w` in `tokens.css`.

### Display scaling

Sizing is CSS-only and is defined in `frontend/src/styles/layout.css`.

- **Text:** above 1180 px, the root font size of the explorer page
  (`html.explorer`) is 100% of the browser default up to a 1536 x 780 window
  and rises to at most 125% (20 px), following the window's width and
  height. Browser zoom and the browser default font size apply.
- **Board:** above 1180 px, `--board-size` fills the window height in
  multiples of 8 px, from 20.5 rem up to `--board-size-max` (720 px, defined
  in `tokens.css`), and leaves at least 40 rem for the results table. The
  left column is as wide as the board, so it is capped at 720 px as well.
  The width the board column does not use goes to the results column, so
  the total content width stays constant.
- **Tablet layout:** at 1180 px and below, the root font size is the
  browser default and `--board-size` is `--board-size-cap`, defined in
  `tokens.css` as
  `min(720px, clamp(18.75rem, min(23.4375vw, 41.6667vh), 31.5rem))`.
- **Phone layout:** below 768 px, `--board-size` is the smaller of
  `--board-size-cap` (`min(360px, 88vw)` up to 480 px wide) and the height
  that remains after the header, bottom navigation, and the controls
  above the board, with a floor of 14 rem. The board screen therefore
  fits the visible height regardless of browser toolbar size. Below the
  floor, the screen scrolls from its top.
- `--board-fit-h` includes the fixed height above the board in the left
  column and requires an update when that height changes. This applies to
  both the desktop definition in `layout.css` and the phone definition in
  `responsive.css`.
- `html.explorer` is set in `templates/index.html` and `frontend/index.html`.
  `/admin` does not use it.

---

## Prerequisites

- **Python 3.10+**
- **Git**, available on `PATH` - `pip install -r requirements.txt` fetches the
  `python-chess` fork directly from GitHub (`chess @ git+https://...`),
  which requires `git` to be installed even though the package itself is
  Python.
- **A ChessTB tablebase directory or URL**: either a local directory on
  disk, or an `http(s)://` base URL serving the same layout remotely with
  no local download (see [Getting the tablebase files](#getting-the-tablebase-files)).
  The app starts without one, but every probe will fail until
  `TABLEBASE_PATH` points at the required sources. See
  [Configuration reference](#configuration-reference).
- A modern browser (the frontend uses `fetch`, `ReadableStream`, and CSS
  container queries).

---

## Installation

1. **Create and activate a virtual environment:**

   ```bash
   python -m venv .venv
   source .venv/bin/activate      # Windows: .venv\Scripts\activate
   ```

2. **Install dependencies:**

   ```bash
   pip install -r requirements.txt
   ```

   This pulls in the **modified `python-chess` fork** (not the plain
   PyPI `chess` package; see the comments in `requirements.txt` for why
   that distinction matters).

3. **Get the tablebase files**: see the next section. When using the
   remote (no-download) option requires no fetch; continue to step 4 and
   point `TABLEBASE_PATH` at the URL.

4. **Configure `config.py`**: open it and set `TABLEBASE_PATH` to the
   directory (or URL) from step 3:

   ```python
   TABLEBASE_PATH = "/data/chesstb"
   ```

   or, for the remote option:

   ```python
   TABLEBASE_PATH = "https://huggingface.co/buckets/chesstb/chesstb/resolve"
   ```

   This alone covers every piece count. See
   [Getting the tablebase files](#getting-the-tablebase-files) for
   the ordered source list, which includes shipping tables for both ordinary
   and castling materials.

   Every other setting in `config.py` has a default and a comment
   explaining what it does - see
   [Configuration reference](#configuration-reference) for the complete
   list. Edit the values directly. To enable the header's source repository button,
   set `SOURCE_REPOSITORY_URL` there too.

5. **Run the app:**

   ```bash
   python app.py
   ```

   By default (`DEBUG = False` in `config.py`) this serves the app via
   **waitress**, a production-grade pure-Python WSGI server - see
   [Running in production](#running-in-production) below. Set
   `DEBUG = True` in `config.py` to use Flask's development server
   (auto-reload, interactive debugger) for local development.

6. Open **http://127.0.0.1:7860** in a browser.

   The built frontend (`static/dist/`) is checked in; see
   [Frontend build](#frontend-build) when changing `frontend/src/`.

---

## Getting the tablebase files

Where the tablebase *data* lives is a separate question from where this
*app* runs - Option A below points `TABLEBASE_PATH` at a plain
`http(s)://` URL, so it works identically regardless of which platform
serves the app itself (Render, Hugging Face Spaces, a local machine,
etc.); `remote/remote_source.py` speaks plain HTTP byte-range requests,
nothing more, and has no dependency on any one host. See
[Deploying to Render](#deploying-to-render) for the app side of that
distinction.

ChessTB tablebase files are available two ways:

### Option A: Remote, no local download (recommended)

Tables are available in the [ChessTB bucket](https://huggingface.co/buckets/chesstb/chesstb).
Shipping tables are grouped by metric; raw generator output is under `full/`.
Both use `castling/` for tables with castling rights.
WDL/DTZ cover 3–8 pieces; DTC/DTM/DTM50 cover 3–6 pieces.

Set `TABLEBASE_PATH` to the bucket root:

```python
TABLEBASE_PATH = "https://huggingface.co/buckets/chesstb/chesstb/resolve"
```

The explorer prefers raw generator output under `full/`, falls back to
shipping tables, and selects `castling/` paths automatically, including
for recursive dependencies. This applies to Standard chess and Chess960.
Local roots use the same layout. An explicit list of source directories
is also supported.

`REMOTE_MODE` selects the remote access mode, which stays fixed for the
life of the process:

- **`"direct"` (default)**: `remote/remote_direct.py` probes the remote
  tables **in place**, fetching only the `REMOTE_PAGE_SIZE_BYTES`-sized
  byte ranges each probe reads and keeping them in an in-memory
  LRU bounded by `REMOTE_PAGE_CACHE_BYTES`. Nothing is written to disk.
  This uses `chess.chesstb`'s table-source seam
  (`Tablebase.WDL_FILE` / `_TableFile._open_source`), which the pinned
  fork (see `requirements.txt`) provides.
- **`"download"`**: `remote/remote_fallback.py` fetches each table
  **in full** the first time a probe touches its material and caches it
  in a temporary local directory (bounded by
  `REMOTE_PAGE_CACHE_BYTES` as an on-disk budget, evicting
  least-recently-used files, removed entirely when the app stops). Every
  probe after the first is then a local mmap read.

`"direct"` is the better default for browsing across many materials, which
is what this app does. `"download"` is preferable when a long session
repeatedly probes a small set of materials, or on a high-latency link: a
ChessTB probe is not a narrow read - a dropped-frame table is reconstructed by walking
its children, and pawn positions reach promotion sub-tables - so one cold
probe can open several materials and issue several fetches against each.
That is also why `REMOTE_PAGE_SIZE_BYTES` should stay large. See each
module's docstring for the full design.

Both remote modes cache successful signed CDN redirects until 60 seconds
before expiry, allowing subsequent byte-range reads to bypass the resolver.
A failed cached URL is retried through the original URL to obtain a fresh
redirect. Resolver and CDN connection pools stay open for reuse.
Complete cached responses are returned immediately by `/probe/stream`,
without rebuilding the board or queuing child probes. Queued child work is
cancelled when a stream disconnects or its pre-warm deadline expires;
already running probes can finish and warm the shared cache.
Table contents and paths are assumed to remain fixed; existence
and size metadata stay cached for the process lifetime, including missing
files. Restart the app after adding or moving tables.

Remote access suits a machine without a couple of terabytes of local disk
for the full tablebase set. Its costs are probe latency on first touch of
any given material (depending on the connection to the CDN), temporary
local disk usage in `"download"` mode, and the requirement of a network
connection. Remote access uses the `requests` package (see
`requirements.txt`).

### Option B: Local directory, over FTP

The same tables are also distributed over FTP for a fully local, offline
setup:

```
ftp://chessdb:chessdb@ftp.chessdb.cn/pub/chesstb/
```

Any FTP client works, for example:

```bash
# lftp
lftp -e "mirror --parallel=4 /pub/chesstb/ /data/chesstb; quit" \
     ftp://chessdb:chessdb@ftp.chessdb.cn

# curl (single file)
curl "ftp://chessdb:chessdb@ftp.chessdb.cn/pub/chesstb/<path-to-file>" -o <local-file>
```

Tablebase sets are large and grow quickly with piece count - check
available disk space before mirroring the full archive, and consider
mirroring only the required subsets (piece counts). Point
`TABLEBASE_PATH` at the selected directory.

---

Regardless of how it is configured, if `TABLEBASE_PATH` is unset, missing/unreachable, or
points at a location with no usable tables, the app still starts (with a
warning in the logs) - every `/probe` request will then return an error,
and `/health` reports `"degraded"`.

---

## Configuration reference

All configuration lives in **`config.py`**, as plain Python values. Open
it and edit the settings directly - each one has a comment above it
explaining what it does. The table below is the complete reference.

The defaults target a single process on Hugging Face CPU Basic
(2 vCPU, 16 GB RAM). The decoded-block cache has a shared 512 MiB
budget, and each of the four default remote sources has a 2 GiB page
cache budget, totaling 8.5 GiB of byte-cache budgets. Caches fill on
demand; this is not a cap on process memory. Root-response and child-probe
caches are limited by entry count, with memory use depending on response
size. The remaining RAM accommodates those results, table/index metadata,
Python object overhead, and active requests. Revisit the budgets if you
add remote sources or run multiple application processes.

| Setting                     | Default          | Description |
|-----------------------------|-------------------|-------------|
| `TABLEBASE_PATH`            | Public bucket root (also readable from a `TABLEBASE_PATH` env var) | Directory containing the ChessTB tablebase files, **or** an `http(s)://` base URL serving the same layout remotely (e.g. a Hugging Face storage bucket - see [Getting the tablebase files](#getting-the-tablebase-files)). Required for probing to work. A list of directories and URLs, tried left-to-right (a hybrid source), is accepted as a literal in `config.py` only. On Render, set this from the service's Environment tab (or `render.yaml`'s prompt) instead of editing the file. |
| `DEBUG`                     | `False`           | `True` runs `app.py` via Flask's own dev server (auto-reload, detailed tracebacks) instead of waitress. Leave `False` - which serves via waitress - for anything reachable from another machine. See [Running in production](#running-in-production). |
| `HOST`                      | `"0.0.0.0"`       | Interface the server (waitress, or the dev server if `DEBUG = True`) binds to. |
| `PORT`                      | `7860` (also readable from a `PORT` env var) | Port the server listens on. Render injects its own `PORT` at deploy time and this picks it up automatically - nothing to set for a Render deployment. |
| `WAITRESS_THREADS`          | `4`               | Worker threads in waitress's request-handling pool. Only relevant when `DEBUG = False`. Needs to be more than 1 so a long-lived `/probe/stream` connection can't block other requests. |
| `PROBE_THREADS`             | `2`               | Worker threads in the probe thread pool for evaluating a position's legal moves in parallel. Set an explicit integer to match the host's CPU count, or `None` to scale automatically (`min(16, cpu*2)`). |
| `PROBE_PARALLEL_THRESHOLD`  | `4`               | Minimum number of child positions before probing switches from sequential to the thread pool. |
| `PROBE_TIMEOUT_SECS`        | `30`              | Wall-clock timeout for each probe phase. `/probe` gives the root probe and the child-move batch independent budgets, so worst-case `/probe` latency can approach `2 × PROBE_TIMEOUT_SECS`. Also bounds how long a request waits on another thread's in-flight probe of the same FEN before giving up with a retryable `probe_timeout` error. |
| `EVALUATE_CACHE_SIZE`       | `16384`            | Max entries in the root-FEN result cache (full JSON responses). |
| `PROBE_CACHE_SIZE`          | `262144`           | Max entries in the child-position probe cache (raw `chess.chesstb.ProbeResult` objects - WDL/DTZ/DTC/DTM/DTM50 together). |
| `BLOCK_CACHE_BYTES`         | `536870912` (512 MiB) | Size, in bytes, of `chesstb`'s own internal cache of decoded/decompressed tablebase blocks (shared across the WDL/DTZ/DTC/DTM/DTM50 tables). Raising this trades RAM for fewer repeated disk reads/HTTP fetches + decompressions across a session - most worthwhile when `PROBE_PARALLEL_THRESHOLD` is set high enough that probing runs mostly serially. |
| `REMOTE_MODE`               | `"direct"`        | **Remote tablebase entries only.** `"direct"` probes the remote tables in place over byte ranges (nothing written to disk); `"download"` fetches each table in full on first touch and caches it on local disk. See [Getting the tablebase files](#getting-the-tablebase-files). |
| `REMOTE_PAGE_CACHE_BYTES`   | `2147483648` (2 GiB) | **Remote tablebase entries only.** Soft budget, in bytes, per remote source in `TABLEBASE_PATH`, shared across that source's tables: the in-memory page cache in `"direct"` mode, the on-disk cache of whole downloaded files in `"download"` mode. See [Getting the tablebase files](#getting-the-tablebase-files). |
| `REMOTE_PAGE_SIZE_BYTES`    | `262144` (256 KiB) | **Remote tablebase entries only.** Size, in bytes, of one page. In `"direct"` mode this is the granularity of every fetch, so it trades over-fetching against round trips per probe; in `"download"` mode it is only the chunk size used while streaming a full file down. |
| `REMOTE_TIMEOUT_SECS`       | `20`              | **Remote tablebase entries only.** Per-HTTP-request timeout for existence/size checks and the download itself. |
| `REMOTE_MAX_RETRIES`        | `3`               | **Remote tablebase entries only.** Attempts for a single remote request before it's treated as failed. |
| `REMOTE_POOL_MAXSIZE`       | `None`            | **Remote tablebase entries only.** Size of each remote backend's HTTP connection pool. `None` computes `max(PROBE_THREADS * 2, 20)`. |
| `PROBE_RATE_LIMIT`          | `"60 per minute"` | Per-client-IP request limit on `/probe` and `/probe/stream`, using [flask-limiter](https://flask-limiter.readthedocs.io/)'s string syntax. Left empty, rate limiting is disabled entirely. See [Security notes](#security-notes). |
| `ADMIN_LOGIN_RATE_LIMIT`    | `"5 per minute"`  | Per-client-IP request limit on `/admin/login`, same string syntax as `PROBE_RATE_LIMIT`, applied independently of it. Covers both failed and successful login attempts. Left empty, login attempts are not rate limited. See [Security notes](#security-notes). |
| `PREFETCH_RATE_LIMIT`       | `"30 per minute"` | Per-client-IP request limit for hover prefetch requests marked with `X-Prefetch: 1`. Left empty, prefetch requests share `PROBE_RATE_LIMIT`. See [Security notes](#security-notes). |
| `TRUSTED_PROXY_COUNT`       | `1` (also readable from a `TRUSTED_PROXY_COUNT` env var) | Number of trusted reverse-proxy hops in front of this app. In production this configures [waitress's own `trusted_proxy_count`](https://docs.pylonsproject.org/projects/waitress/en/stable/proxy-headers.html) (waitress parses `X-Forwarded-For`/`X-Forwarded-Proto` and corrects `REMOTE_ADDR`/`wsgi.url_scheme` itself, ahead of Flask); [Werkzeug's `ProxyFix`](https://werkzeug.palletsprojects.com/en/latest/middleware/proxy_fix/) makes the same correction for the `DEBUG = True` dev-server path, which doesn't run under waitress. Both rate limiters key on the corrected address, and `request.scheme`/`request.is_secure` read the corrected scheme. `1` matches this project's own `render.yaml` topology (Render's edge/load-balancer, once). Set it to match the deployment's reverse-proxy chain, or set it to `0` for a deployment with no reverse proxy in front of it at all. See [Security notes](#security-notes). |
| `ADMIN_TOKEN`                | `""` (from `ADMIN_TOKEN` env var) | Shared secret required to reach `/admin` and `/admin/cache/*`. Read from the environment rather than hardcoded, so it can be set as a platform secret. Left unset, admin routes respond `503` rather than running unprotected. See [Security notes](#security-notes). |
| `FLASK_SECRET_KEY`           | `""` (from `FLASK_SECRET_KEY` env var) | Key used to sign the admin session cookie. Read from the environment for the same reason as `ADMIN_TOKEN`. Left unset, a random key is generated at process startup instead, so every restart requires logging in again. |
| `SESSION_COOKIE_SECURE`      | `False` (also readable from a `SESSION_COOKIE_SECURE` env var, `"true"`/anything else) | Whether the admin session cookie set by `/admin/login` requires HTTPS. Independent of `DEBUG`. Defaults `False` to match a plain-HTTP local installation; set to `"true"` for any deployment the browser reaches over HTTPS (including behind a TLS-terminating reverse proxy such as Render's - `render.yaml` already sets this explicitly for that deployment). See [Security notes](#security-notes). |
| `SOURCE_REPOSITORY_URL`                 | `""` (also readable from a `SOURCE_REPOSITORY_URL` env var) | Repository URL for the source repository button shown in the header of every page. Edited directly like any other non-secret value here, or set as an env var on a given deployment. Left empty, the button is omitted. |

Invalid values (wrong type, out of range) cause the app to log an error
and exit at startup rather than run with a silently-wrong configuration.

---

## Running in production

`python app.py` serves the app via **[waitress](https://docs.pylonsproject.org/projects/waitress/)**,
a production-grade, pure-Python WSGI server, whenever `DEBUG` in
`config.py` is `False` (the default) - no separate `gunicorn`/`waitress`
command or extra process is needed on top of the app itself. Setting
`DEBUG = True` in `config.py` switches `app.py` over to Flask's own dev
server instead (auto-reload + interactive debugger), which is meant for
local development only and should not be used for anything reachable
from another machine.

```bash
# Production (default): DEBUG = False in config.py: serves via waitress
python app.py

# Local development: set DEBUG = True in config.py first, then run the
# same command: Flask dev server, auto-reload + debugger
python app.py
```

- `HOST` / `PORT` control the interface and port waitress binds to, same
  as for the dev server. `PORT` is also readable from a `PORT`
  environment variable (see [Configuration reference](#configuration-reference)),
  which is what lets the same image bind correctly on Render - or any
  other platform that assigns the port at deploy time - with no edits.
- `WAITRESS_THREADS` (default `4`) sizes waitress's own pool of
  request-handling threads. This needs to be more than 1 for the same
  reason the dev server needs `threaded=True`: `/probe/stream` holds a
  connection open via Server-Sent Events for the whole duration of a
  probe, and a single-threaded server would let that one connection block
  every other request - including the browser's own concurrent requests
  for CSS/JS/piece images on first page load. It's independent of
  `PROBE_THREADS`, which sizes the thread pool used internally to
  parallelise tablebase probing rather than to serve HTTP requests.
- `TRUSTED_PROXY_COUNT` (default `1`) configures waitress's own
  `trusted_proxy_count`, so `request.remote_addr` and `request.scheme`
  reflect the real client IP and scheme behind Render's edge/load-balancer
  rather than that proxy's own address/hop - see
  [Security notes](#security-notes).
- Waitress handles `/probe/stream`'s streamed response natively; no
  additional configuration is needed for SSE to work correctly.
- The probe endpoints are unauthenticated by design; only `/admin` and
  `/admin/cache/*` require a credential (see
  [Security notes](#security-notes)).

---

## Deploying to Render

This project deploys to [Render](https://render.com) as a single Docker
web service, built straight from this GitHub repository. Render watches
the connected branch and rebuilds/redeploys automatically on every push.

There are two ways to set it up:

### Option 1: Blueprint (`render.yaml`, recommended)

This repository ships a [`render.yaml`](render.yaml) at its root
describing the service (Docker runtime, health check, environment
variables). Render finds it automatically:

1. Push this repository to GitHub.
2. In the [Render Dashboard](https://dashboard.render.com), click
   **New → Blueprint** and connect the repo.
3. Render reads `render.yaml` and requests the one setting required
   before the first deploy can run: **`TABLEBASE_PATH`** - the
   `http(s)://` base URL of the remote tablebase (see
   [Getting the tablebase files](#getting-the-tablebase-files)).
   `ADMIN_TOKEN` and `FLASK_SECRET_KEY` are generated automatically.
4. Click **Apply** / **Create**. Render builds the image from this
   repo's `Dockerfile` and deploys it.

Every subsequent push to the connected branch redeploys automatically.
To change `TABLEBASE_PATH`, `ADMIN_TOKEN`, or any other setting later,
edit it from the service's **Environment** tab in the Render Dashboard;
see [Configuration reference](#configuration-reference) for which
settings are env-overridable this way versus which live only in
`config.py`.

### Option 2: Manual Web Service (no `render.yaml`)

The service can also be configured manually without the Blueprint file:

1. Push this repository to GitHub.
2. In the Render Dashboard, click **New → Web Service** and connect the
   repo.
3. Set **Runtime** to **Docker** (Render should detect the `Dockerfile`
   at the repo root automatically).
4. Under **Environment**, add:
   - `TABLEBASE_PATH`: required; same as Option 1 above.
   - `ADMIN_TOKEN`: optional but recommended; any secret string, or
     use Render's "Generate" button. While it is unset, `/admin`
     responds `503`.
   - `FLASK_SECRET_KEY`: optional; when omitted, a random key is
     generated at process startup and admin sessions don't survive a
     restart.
   - `SESSION_COOKIE_SECURE`: set to `true`. Render always terminates
     TLS at its edge, so the browser reaches this deployment over HTTPS
     even though the app itself just speaks plain HTTP to Render's
     proxy; `config.py`'s own default (`false`) is tuned for a local
     plain-HTTP installation instead. (Option 1's `render.yaml` sets
     this automatically - it is a manual step here because Option 2
     skips that file.)
   - `SOURCE_REPOSITORY_URL`: optional; the repository URL, which enables the
     header's source repository button.
   - Leave `PORT` alone - Render sets it itself, and `config.py` already
     reads it (see [Configuration reference](#configuration-reference)).
5. Under **Health Check Path**, set `/health` (matches the route in
   `app.py`; Render won't mark a deploy healthy until this returns `200`,
   which itself only happens once the sources in `TABLEBASE_PATH` have
   opened successfully).
6. Click **Create Web Service**.

### Choosing a plan

Probing is CPU-bound (block decompression on every request), so a
dedicated vCPU - Render's **Starter** tier or above - gives lower probe
latency than the **Free** tier's shared/limited CPU. Free works
for casual or low-traffic use; the service spins down after inactivity
(a slow first request after waking up) and probes are slower under load. Either way, `REMOTE_MODE = "direct"` (the default)
means no persistent disk is needed regardless of plan - see
`config.py`'s "Remote (URL) tablebase entries only" section and
[Getting the tablebase files](#getting-the-tablebase-files).

---

## Usage guide

- **Set a position**: type or paste a FEN into the FEN box and press
  `Enter` or **Apply**. The move rankings and best-move arrows update
  automatically. The castling-availability field accepts `-` or any
  combination of `K`, `Q`, `k`, `q` (each requiring a matching king and
  rook on their home squares); in **Chess960 Mode** it additionally
  accepts X-FEN/Shredder-FEN rook-file letters (`a`-`h` / `A`-`H`). A
  position with a castling right is evaluated the same as any other,
  reported as not covered if the loaded tablebase set has no table for it
  (see `TABLEBASE_PATH` in
  [Configuration reference](#configuration-reference)).
- **Chess960 (Fischer Random)**: toggle **Chess960 Mode** in the settings
  panel to switch castling interpretation. This does not move any pieces
  or randomize a new starting position - it only changes how castling
  moves/rights on the *current* board are interpreted, and drops the
  current move line the same way a board edit does (a line built under
  one variant isn't reinterpreted as the other). With it on, drag a king
  onto its own rook to castle; the destination square and resulting rook
  position follow standard Chess960 rules regardless of where the king
  and rook started. The setting is carried in the shared URL
  (`&variant=chess960`), the saved in-progress game, and PGN
  import/export (a `[Variant "Chess960"]` header).
- **Edit the board directly**: drag pieces around the board, drag a piece
  off the board to remove it, or click a spare piece in either tray and
  then click a square to place it (click again / press `Esc` to cancel).
  Board edits reset the current move line the same way **Clear** does.
- **Lock the board**: click the padlock button beside the FEN box to
  restrict drag-and-drop, click-to-move, and the spare-piece trays to
  legal moves for the side to move; the button turns gold while active.
  Click again to unlock. The choice is remembered locally across visits.
  Starting auto-play locks the board automatically for the run (unless
  already locked) and disables the padlock button until it stops.
- **Play moves**: click any move in one of the four ranked tables to
  play it, or drag a piece on the board through a legal move.
- **Navigate history**: the Undo/Redo arrow buttons or `←`/`→`, or click
  any move in the PGN panel to jump straight to that point in the line.
- **Auto-play**: click the ▶ button above the DTZ, DTC, DTM, or DTM50
  columns
  to have the app play that metric's best move on a timer (delay set by
  **Autoplay Delay** in settings, 1.25s by default); click again (the
  button shows ■ while running) to stop. Any manual navigation stops auto-play.
- **Import/export a game**: **Import** in the PGN panel opens a dialog to
  paste PGN text. **Import Game** loads the full game and its variations
  into the PGN panel, starting before the first move; **Export**
  downloads the full game and its variations as `chesstb_game.pgn` with
  standard headers.
- **Export the move table**: the **CSV** button downloads the current
  DTZ/DTC/DTM/DTM50 rankings as a CSV file.
- **Share a position**: the URL updates live with `#fen=...`; sending
  that link reproduces the exact position.
- **Change settings**: the ⚙ button in the header opens a **Show Root
  Row** switch for the results table, a **Chess960 Mode** switch, and an
  **Autoplay Delay** slider; the choices are persisted across visits.
- **Admin dashboard**: the gauge icon in the header opens `/admin`, prompting for the
  `ADMIN_TOKEN` on first visit, then showing live hit-rate stats for both
  caches and the thread-pool configuration, auto-refreshing every 5
  seconds.

---

## API

The full HTTP API - `/probe`, `/probe/stream`, `/health`,
`/admin/cache/stats`, `/admin/cache/clear`, `/admin/login`,
`/admin/logout` - is documented as an OpenAPI 3.0 specification served
live by the running app at:

```
http://127.0.0.1:7860/openapi.yaml
```

`openapi.yaml` documents every endpoint's request/response shapes; the
ranking algorithm behind `moves_dtz` / `moves_dtc` / `moves_dtm` /
`moves_dtm50` is documented inline in `app.py`'s own module docstring and
its `evaluate_all_moves()` function. `/admin/cache/*` require an
`Authorization: Bearer <ADMIN_TOKEN>` header or an authenticated session
cookie from `/admin/login` - see [Security notes](#security-notes).

Quick example:

```bash
curl -X POST http://127.0.0.1:7860/probe \
     -H "Content-Type: application/json" \
     -d '{"fen": "4k3/8/8/8/8/8/8/4K2R w - - 0 1"}'
```

`variant` is optional and defaults to `"standard"` when omitted. It is
never inferred from the FEN itself - the orthodox starting array is
itself a legal Chess960 starting position, so the same FEN text is
ambiguous without it:

```bash
curl -X POST http://127.0.0.1:7860/probe \
     -H "Content-Type: application/json" \
     -d '{"fen": "r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1", "variant": "chess960"}'
```

---

## Project structure

```
.
├── LICENSE                 # GPL-3.0-or-later license text for this project
├── THIRD_PARTY_LICENSES.md # Licenses and attributions for bundled third-party code, fonts, and the piece set
├── Dockerfile               # Container build used for Render (and any other Docker host)
├── render.yaml              # Render Blueprint: service definition, health check, env vars
├── app.py                  # Flask backend: routes, probing, caching
├── config.py               # All configuration, as plain Python values - see "Configuration reference"
├── openapi.yaml            # OpenAPI 3.0 specification, served at /openapi.yaml
├── requirements.txt
├── README.md
├── .gitattributes, .gitignore, .dockerignore
├── tablebase_router.py     # Ordered local/remote source lookup for every material
├── tablebase_opening.py    # Per-material table-opening lock policy, shared by tablebase_router.py and both remote backends
├── dtz_anchor.py           # Resolves rounded DTZ values by cross-checking the moves of a position
├── remote/
│   ├── remote_source.py     # Generic HTTP byte-range client shared by both remote backends - see its own module docstring
│   ├── remote_direct.py     # REMOTE_MODE="direct": probe remote tables in place over byte ranges - see its own module docstring
│   └── remote_fallback.py   # REMOTE_MODE="download": whole-file download, cached to local disk on first touch - see its own module docstring
├── templates/
│   ├── index.html          # Main explorer UI - mounts the React app (see frontend/)
│   └── admin.html          # Cache dashboard
├── frontend/                # React app for the explorer page - see "Frontend build"
│   ├── package.json, package-lock.json
│   ├── vite.config.js       # Builds into ../static/dist with fixed filenames (no cache-busting hash)
│   ├── index.html, admin.html  # Build entries (script and stylesheet)
│   └── src/
│       ├── main.jsx, App.jsx
│       ├── engine/          # Position/rules engine and tablebase client (chessops + Chessground)
│       ├── vendor/          # Vendored Chessground (script and base stylesheet) + chessops, bundled by the build
│       ├── hooks/useExplorer.js  # FEN box, PGN, auto-play, settings, keyboard shortcuts
│       ├── components/      # Board, results table, PGN panel, dialogs, settings panel
│       │   └── ui/          # Icon, Button, Segmented, Panel
│       ├── styles/          # Tokens, base, layout, component and chess stylesheets - see "Styling"
│       └── assets/fonts/    # Inter and JetBrains Mono (woff2)
└── static/
    ├── dist/                # Built frontend (see "Frontend build"): app.js, app.css, admin.css, fonts/
    ├── css/
    │   └── pieces-cburnett.css   # Piece-set stylesheet linked by templates/index.html
    ├── js/
    │   └── admin.js          # Admin dashboard client
    └── pieces/cburnett/     # Piece-set SVGs
```

---

## Security notes

- The `/probe` and `/probe/stream` endpoints are intentionally
  unauthenticated - evaluating a chess position is this app's public,
  core functionality. `/admin` and `/admin/cache/*` are gated behind
  `ADMIN_TOKEN` (see below); every other route requires no credential.
- **Rate limiting** on `/probe` and `/probe/stream` is controlled by
  `PROBE_RATE_LIMIT`, and on `/admin/login` separately by
  `ADMIN_LOGIN_RATE_LIMIT` (both in `config.py`'s "Rate limiting"
  section), each applied per client IP via
  [flask-limiter](https://flask-limiter.readthedocs.io/). A client over
  either limit gets a `429` with a JSON error body. `PROBE_RATE_LIMIT`'s
  default, `"60 per minute"`, covers normal browsing and
  autoplay at its default delay - raise it if legitimate autoplay at a
  fast delay setting gets throttled, lower it if the deployment sees
  abuse, or set either limit to `""` to disable it entirely.
  `ADMIN_LOGIN_RATE_LIMIT` defaults to `"5 per minute"`, tight enough to
  slow down repeated `ADMIN_TOKEN` guesses. Both limiters key on
  `request.remote_addr` as corrected by `TRUSTED_PROXY_COUNT` (see
  below) and their state lives in-process (`memory://`), which is
  sufficient for a single-container deployment (e.g. one Render Web
  Service instance) but isn't shared across multiple replicas.
- **`TRUSTED_PROXY_COUNT`** (`config.py`'s "Rate limiting" section) is
  what `request.remote_addr`, and therefore both rate limiters above,
  is corrected against, so it reads the real client IP from
  `X-Forwarded-For` rather than the address of the reverse proxy
  in front of this app. The same setting also governs whether
  `X-Forwarded-Proto` is trusted, correcting `request.scheme` /
  `request.is_secure` (and any externally-generated URL) when TLS
  terminates at that reverse proxy rather than at this app itself. In
  production (`DEBUG = False`) this configures [waitress's own `trusted_proxy_count`](https://docs.pylonsproject.org/projects/waitress/en/stable/proxy-headers.html):
  waitress parses both headers and corrects `REMOTE_ADDR`/`wsgi.url_scheme`
  itself, before Flask ever sees the request, so it takes priority here.
  [Werkzeug's `ProxyFix`](https://werkzeug.palletsprojects.com/en/latest/middleware/proxy_fix/)
  makes the equivalent correction for the `DEBUG = True` Flask-dev-server
  path, which doesn't run under waitress at all. Defaults to `1`,
  matching this project's own `render.yaml` topology; set it to match
  the deployment if that differs, or to `0` for a deployment with no
  reverse proxy in front of it at all.
- **Admin access** is controlled by `ADMIN_TOKEN` (`config.py`'s "Admin"
  section), read from the environment rather than hardcoded - set it as
  a platform secret (e.g. a Render environment variable, generated
  automatically by `render.yaml`'s `generateValue: true`) rather than
  committing it. Visiting `/admin` with no active session shows a login
  form; a correct token there starts a signed, `HttpOnly`,
  `SameSite=Lax` session cookie (`Secure` too, where configured - see
  `SESSION_COOKIE_SECURE` below). API clients can instead send
  `Authorization: Bearer <ADMIN_TOKEN>` directly, no session needed.
  Token comparison uses `hmac.compare_digest` (constant-time, resistant
  to timing attacks). Leaving `ADMIN_TOKEN` unset does **not** open the
  admin panel to everyone - every admin route responds `503` instead.
- **`SESSION_COOKIE_SECURE`** (`config.py`'s "Admin" section) controls
  whether the admin session cookie above requires HTTPS, independently
  of `DEBUG` - `DEBUG` is a development/runtime behavior switch, not a
  reliable indicator of the deployment's transport security, so
  `DEBUG = False` alone does not imply HTTPS is in front of this
  app. Read from a `SESSION_COOKIE_SECURE` env var (`"true"` or anything
  else, case-insensitive), defaulting `False` to match this project's own
  plain-HTTP local installation - a browser won't send a
  `Secure` cookie back over a plain HTTP connection, so `/admin/login`
  would otherwise appear to succeed while every subsequent authenticated
  `/admin/*` request came back `401`. Set to `"true"` for any deployment
  the browser reaches over HTTPS (including behind a TLS-terminating
  reverse proxy - the browser's own connection is what the `Secure`
  attribute governs, not the internal hop between the proxy and this
  process); `render.yaml` already sets this explicitly for the Render
  deployment it configures, since Render always terminates TLS at its
  edge.
- The app serves via **waitress**, a production-grade WSGI server, by
  default (`DEBUG = False` in `config.py`) - see [Running in production](#running-in-production).
  Only set `DEBUG = True` (which switches to Flask's own dev server) for
  local development, never for anything reachable from another machine.
- A `Content-Security-Policy` is set on every response: scripts and fonts
  are restricted to `'self'` (no inline scripts, no third-party sources);
  styles allow `'self'` plus `'unsafe-inline'` (needed for inline
  `style` attributes set by the React app and in `admin.html`); images
  allow `'self'` plus `data:`; `connect-src`/`default-src` are `'self'`
  too, so `fetch`/SSE calls can only reach this same origin. `object-src`,
  `base-uri`, and `form-action` are locked to `'none'`/`'self'`/`'self'`,
  and `frame-ancestors 'self' https://huggingface.co` allows the Hugging
  Face Space page to embed the app. `X-Content-Type-Options:
  nosniff` and `Referrer-Policy: strict-origin-when-cross-origin` are set
  too. Request bodies are capped at 4 KB.
- `config.py` itself holds no secrets - `ADMIN_TOKEN` and
  `FLASK_SECRET_KEY` are the only two secrets, and they are read only from
  the environment so the file stays safe to commit as-is. Every other
  setting is a non-sensitive value.

---

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| Every probe returns "Position not covered by the loaded tablebase." | Check `TABLEBASE_PATH` and the startup logs. Set the tablebase root; `full/` and `castling/` directories are resolved automatically. For an explicit source list, include every required directory. |
| A FEN is rejected with "Invalid castling availability" | The submitted castling-availability field is something other than `-` or a combination of `K`, `Q`, `k`, `q` (or, in Chess960 Mode, rook-file letters `a`-`h`/`A`-`H`), or names a castling right without a matching king and rook on the board. |
| A FEN with `a`-`h`/`A`-`H` castling-rights letters is rejected even though the position looks fine | Those letters are only accepted with **Chess960 Mode** on (settings panel, or `variant: "chess960"` on the API) - Standard mode only accepts `K`, `Q`, `k`, `q`, matching Standard chess's fixed castling-rook squares. |
| Dragging a king onto its own rook doesn't castle | **Chess960 Mode** is off - enable it in the settings panel (or send `variant: "chess960"` on the API) for Chess960-style king-onto-rook castling; in Standard mode a king can only reach its rook's square by regular king movement. |
| `/health` returns `503 degraded` | The tablebase failed to open - check `TABLEBASE_PATH` and file permissions. |
| `ModuleNotFoundError: No module named 'chess.chesstb'` | Plain PyPI `chess` was installed instead of the fork. Re-run `pip install -r requirements.txt` and confirm it pulled `chess` from `noobpwnftw/python-chess` (the `add-chesstb-tablebases` branch) rather than plain PyPI `chess` - see the note at the top of `requirements.txt`. |
| `ModuleNotFoundError: No module named 'config'` | `config.py` is missing from alongside `app.py`. It ships with the repository - if it was deleted or moved, restore it from the repo (or re-clone) and re-apply any edits, such as `TABLEBASE_PATH`. |
| App logs `Configuration error: ...` and exits immediately | A value in `config.py` is the wrong type or out of range for that setting (e.g. a string where an integer is expected, or a negative cache size) - the error message names which setting and why. Fix it in `config.py` and re-run `python app.py`. |
| Admin dashboard panels stuck on "Loading…" | Check the browser console for a CSP violation and verify that the app is running and reachable at the `/admin` URL. |
| A drag, drop, or spare-piece placement on the board is silently rejected | The board is Locked - the padlock button beside the FEN box is highlighted gold. Lock restricts board interaction to legal moves and disables the spare-piece trays and off-board drops; click the padlock again to unlock and edit freely. |
| Probing feels slow on positions with many legal moves, or doesn't scale with `PROBE_THREADS` | Confirm `lz4` is installed (`pip show lz4`, or `python -c "import lz4"`) - without it, `chess.chesstb`'s block decompression runs in pure Python and holds the GIL, so `PROBE_THREADS` can't achieve real parallelism. `pip install lz4` (already in `requirements.txt`) and restart. Otherwise, tune `PROBE_THREADS`, `PROBE_PARALLEL_THRESHOLD`, and `PROBE_TIMEOUT_SECS` in `config.py`. Note that `tablebase_router.py` guards each material's first open with a lock keyed by `(kind, material)`, so two threads racing to open the *same* never-before-seen material collapse onto one read, while distinct materials of the same kind open concurrently. If any configured tier uses `REMOTE_MODE="download"`, opens fall back to one lock shared per kind, so several distinct never-before-seen materials of that kind then open one at a time instead - either way, this only affects the very first probe against any given material. |
| `ModuleNotFoundError: No module named 'waitress'` | The active environment's dependencies are out of date - re-run `pip install -r requirements.txt` to pick up `waitress`. `app.py` imports it unconditionally at the top of the file, before `config.DEBUG` is even read, so setting `DEBUG = True` does **not** avoid this - waitress has to be installed either way. |
| Every probe on a remote `TABLEBASE_PATH` returns "Position not covered..." or `/health` is `degraded` | Confirm the URL is reachable and correct (try opening `TABLEBASE_PATH/wdl/KQK.lzw` - or any small material's `.lzw` - directly in a browser). Check the startup log's "TABLEBASE_PATH opened remotely at: ..." line (or a warning in its place) for the actual failure. |
| A probe occasionally returns `503` with `error_code: "probe_timeout"` | Another concurrent request was already probing the same position and didn't finish within `PROBE_TIMEOUT_SECS`. This is transient and retryable - the original probe has usually landed in the child-probe cache before a retry, so the retry is inexpensive. Frequent occurrences suggest raising `PROBE_TIMEOUT_SECS`, or that a slow remote `TABLEBASE_PATH` is the underlying bottleneck. |
| Remote probing feels slow, or repeated probes against the same material keep hitting the network | Check `REMOTE_TIMEOUT_SECS`/`REMOTE_MAX_RETRIES` aren't causing retries on a slow link, and consider raising `REMOTE_PAGE_CACHE_BYTES` - a too-small budget evicts cached pages (`"direct"`) or downloaded files (`"download"`) before later probes can reuse them. `GET /admin/cache/stats` surfaces this per tier as `tablebase_cache.<low|high|castling>.remote_page_cache` or `.remote_disk_cache` respectively. On a high-latency link also try raising `REMOTE_PAGE_SIZE_BYTES`, or `REMOTE_MODE = "download"`. See [Configuration reference](#configuration-reference). |
| On Render, the deploy never goes live / stays stuck "deploying" | Render's health check (`healthCheckPath: /health` in `render.yaml`, or the equivalent field on a manually-created service - see [Deploying to Render](#deploying-to-render)) only passes once `/health` returns `200`, which itself requires the sources in `TABLEBASE_PATH` to have opened successfully. Check the service's **Logs** tab for the same "opened remotely at: ..." / warning line described above. |
| On Render, the service responds but the page never loads / connection refused | Typically a `PORT` mismatch. Confirm `config.py` reads `PORT` from the environment (see [Configuration reference](#configuration-reference)) and that nothing else in a custom start command overrides `HOST`/`PORT`. |

---

## Credits

- Tablebase data & format: [ChessTB / chessdb.cn](https://www.chessdb.cn/)
- Tablebase probing support: [noobpwnftw/python-chess (`add-chesstb-tablebases` branch)](https://github.com/noobpwnftw/python-chess/tree/add-chesstb-tablebases), a fork of [niklasf/python-chess](https://github.com/niklasf/python-chess)
- Remote (URL) tablebase support for the fork's `chess.chesstb` module - see `remote/remote_source.py`, `remote/remote_direct.py` and `remote/remote_fallback.py`
- Board UI: [Chessground](https://github.com/lichess-org/chessground)
- Move generation/validation on the client, for both Standard chess and
  Chess960: [chessops](https://github.com/niklasf/chessops)
- Production WSGI server: [waitress](https://docs.pylonsproject.org/projects/waitress/)
- Piece set: [cburnett](https://github.com/lichess-org/lila/blob/master/COPYING.md), a commonly-used community set found in most web chess UIs.

## License

ChessTB Explorer is licensed under `GPL-3.0-or-later`; see [`LICENSE`](LICENSE).
Bundled third-party components and their licenses are listed in
[`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md).