Studies

Detailed behavior for the repertoire list and study editor.

Purpose and access

A study is a named opening repertoire for one fixed side, represented as a tree of chess positions and moves. It is private to the Lichess account that created it. All study screens require Lichess sign-in.

When signed out, the home page shows a short introduction to Lirep with a Sign in link, and the editor shows a short sign-in prompt. If a requested study ID does not belong to the account or does not exist, show “Study not found.”

Home page

Study data model

Persist id, name, side, tree, explorerSettings, optional startNodeId, and calculation data. The tree is a node map: each node has an ID, SAN move (null at the root), parent ID, and ordered child IDs. Keep a root ID and next ID. Child order matters: the first child is the main line; later children are variations.

The side is chosen as Playing White or Playing Black only when creating a study. Show a selector for a new study and a read-only badge for an existing one. The server must ignore attempts to change the side during an update.

Study files

A study can be saved to a file (Export to file, in the editor's ⋯ menu) and created again from one (Import a study from a file, on the home page). Export and import use the same format, so an exported file imports back to the same study. The file is JSON, named <study name>.lirep.json, one study per file:

{
  "format": "lirep-study",
  "version": 1,
  "name": "Sicilian Defense: Kveinis Variation",
  "side": "black",
  "start": ["e4", "c5", "Nf3", "e6", "d4", "cxd4", "Nxd4", "Qb6"],
  "explorerSettings": { "source": "lichess", "database": "lichess", "minRating": 2000, "player": null, "speeds": ["blitz"] },
  "moves": [
    { "san": "e4" }, { "san": "c5" }, { "san": "Nf3" }, { "san": "e6" },
    { "san": "d4" }, { "san": "cxd4" }, { "san": "Nxd4" }, { "san": "Qb6" },
    { "san": "Nc3" }, { "san": "Bc5" },
    { "san": "Na4", "variations": [
      [{ "san": "Be3" }, { "san": "Nc6" }, { "san": "Nxc6", "comment": "The main alternative" }]
    ] },
    { "san": "Qa5+" }, { "san": "c3" }
  ]
}

Import checks every game the way the Games page does (its PGN must be readable, its moves legal), and every move of the study: it must be legal in its position, appear only once among the alternatives in a position, and, as in the editor, a position where the studied side moves has only one prepared move. Moves written in another valid way (Ng1f3) are stored in standard form (Nf3). The study's stats, practice history and sharing are not in the file: an imported study is a new study, shared like any other new study, with its stats to be calculated.

Editor layout and move editing

The editor has a one-line header: the side as a pawn (♙ or ♟, “Playing White/Black” on hover), the name as a title with a pencil, the starting point as a chip (“Starts after 2.c3”, which jumps there), and the save status; on the right, Stats and Practice links and a “⋯” menu. Clicking the name or the pencil turns it into a field: Enter or leaving the field saves the new name, Esc cancels. A new study shows the side selector and the name field instead, and switches to the title once it is saved. Below 980px the links wrap onto a second line. Then comes the chessboard with navigation buttons (start, previous, next, end of line, flip) on the left, and on the right the move tree with its toolbar above a tools panel whose toggles, Opening Explorer and Stockfish, sit in a bar at its bottom (so they stay in place while the tools open above them), which can be on together (the Explorer above, Stockfish's single row of candidates below it, next to the bar). Both are off by default, so the tree has the whole column above the slim toggle bar; Stockfish adds one line, and the Explorer, when on, takes the larger share of the column. Which are on is remembered in this browser. The right column is as tall as the board column; the tree and the tools scroll inside it. From 981px wide, the board is sized so that, scrolled all the way down, the board and its navigation fill the window height and the header is out of view, a kind of full-screen mode; the page widens to fit, as long as about 610px remain for the moves and tools. Above and below the board, as during a Lichess game, a row shows each side's material lead: the pieces it has more of than the other side (e.g. ♞♞), then the point difference (+2) on the side ahead, counting queen 9, rook 5, bishop and knight 3, pawn 1; the rows follow the board when it is flipped. Below 980px wide, everything stacks: header, board, navigation, tree, tools. New studies start at the normal initial chess position with an empty root. Apply the user's Lichess board theme and piece set when available; otherwise use the default board appearance.

Navigation and actions

Games page

Each study has a Games page (games.html?id={studyId}), linked from the editor's header, the Stats page and, when the study has games, its home card. It holds games related to the opening (master games, historical games, your own), either on their own at the top of the page or in sections you name and order below them. Games are private to the study's owner and deleted with the study.

The games are stored as their PGN text, unchanged, with their section, place and comment (GET/POST /api/studies/{id}/games, PUT /api/studies/{id}/games-layout for the order of sections and games, PUT …/games/{gameId}/pgn for the game with its comments, rewritten by chess.js, which drops variations and annotation symbols, DELETE …/games/{gameId}). They are included in study files. A game's comment, on the whole game, is from before comments were on positions: the viewer shows it on the starting position, and it moves into the PGN when the game's comments are next saved.

A shared opening's games can be seen by others, read-only, from its game count on the community leaderboards (games.html?id={studyId}&shared=1, GET /api/community/studies/{id}/games), with the author's comments as text under the moves. Not when the author is anonymous or has a pen name, as the games' PGN would give their name away.

Starting point

The starting point changes where Stats calculations begin, not the tree or move numbering. Default is the actual root (startNodeId: null). When a non-root node is selected, the action sets that node as the starting point; selecting the active starting node changes the action to Clear starting point. Clearing restores the root default.

Visually color the designated move muted blue and show a badge by the study name with its actual move notation. Do not renumber the move tree. Auto-save this toggle like other study edits. If deleting a subtree removes the chosen node, clear the starting point. Backend calculations must also fall back to the true root if a stored ID no longer exists.

Opening Explorer

Explorer sits in the tools panel next to the board and updates for the currently selected FEN while it is on. Its move list shows six moves; the rest scroll inside it. Its settings collapse to a one-line summary (e.g. “Lichess · 2000+ · blitz, rapid”) with a Change button; a note says they are also the settings the study's stats are calculated with. Changing a setting fetches data for the current position. Show a loading state while fetching and a recoverable unavailable message on failure.

Explorer is not anonymous in this app: a signed-in Lichess session is required. On an HTTP 429, report that the user must wait before retrying rather than rapidly retrying.

Stockfish

Turning Stockfish on lazily starts a local Stockfish WASM worker. Analyze the current position with MultiPV 5, to the depth shown right after its toggle: 12 by default, changed 4 at a time (from 4 to 24) with the arrows beside it, remembered in this browser, and rerun at once when changed. Draw up to eight arrows on the board: Stockfish's five best moves, plus, when the Explorer is on, its moves played in at least 5% of games that those lines miss, which Stockfish then evaluates with a restricted search. An arrow's colour gives the move's quality, from the winning chances it loses against the best move (Lichess's curve, on a −1 to 1 scale): best (up to 0.02), good (up to 0.1), inaccuracy (up to 0.2), mistake (up to 0.3), blunder. Its width grows with the square root of the move's share of games in the Explorer, so rare moves stay visible; with the Explorer off, all arrows have the same width. The most played arrows are drawn underneath. The same moves appear on one line as clickable chips with SAN and evaluation, best first, in their arrows' colours (scrolling sideways when they don't fit); hovering one shows its quality and how often it is played. While Stockfish is on, an evaluation gauge like Lichess's stands at the left edge of the board card: White's share, from Lichess's win-chance curve (2 / (1 + e−0.00368208·cp) − 1, rescaled to 0–100%), fills from White's side of the board and flips with it; a forced mate fills it for the side that mates, and a checkmate or draw on the board shows the result. Selecting a candidate plays it like an Explorer row. Re-analyze whenever the selected node changes; stop/discard stale searches when navigation moves on. Turning it off clears arrows/results and terminates the worker. Game-over positions show a game-over state and no candidate moves.

Suggested moves

The 💡 button, left of the settings gear, swaps the tools for the suggested moves, as the gear does for the settings. They add your moves one at a time, each the one raising the study's expected score most (frontend/src/suggest.ts; tools/optimal_repertoire.py does the same from the command line). The expected score is the Stats page's, with the end-of-prep value and Stockfish depth chosen in the settings. An addition answers an opponent reply the study leaves unanswered, after one of your moves inside a line or after a line's last move (extending it), with one of your most played moves there. Replies are looked at by the best gain they could give, and only those that could beat the best found need Explorer data. Not always optimal: a move worth little alone, but much with the next one, is missed. The algorithm in detail.

Auto-save and errors

Study CRUD and calculation data are account-scoped in SQLite. Auto-save edits after a short debounce and show a persistent status. If a save fails, keep the editor state and show the error; retry after another edit or when connectivity returns. Require a non-empty name before creating a new study. Deleting a study requires confirmation and removes its practice history.

Relevant behavior is implemented across the home page/study page, tree helpers, study API, Explorer service, and shared Stockfish client.