Studies

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 Studies page and editor show a short sign-in prompt and a Sign in link. If a requested study ID does not belong to the account or does not exist, show “Study not found.”

Study list

• Load the current account's studies and render one card per study, followed by a New study card.
• Each card shows the study name, up to the first six SAN moves of its main line, and the main-line move count. Append “+ variations” if the tree contains more nodes than the main line. An empty repertoire says “No moves yet.”
• Selecting a study opens its editor. New study opens a blank editor.
• If the account has no studies, still show New study; the list need not block on a special empty state.

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.

Editor layout and move editing

The editor contains a name input and side badge/selector, then a chessboard, a clickable move tree with controls, an Opening Explorer panel, and a Stockfish panel. 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.

• Moves can be entered by making a legal board move or by selecting a SAN move from Explorer or Stockfish. Append the move under the currently selected node. If that same SAN child already exists, navigate to it instead of duplicating it.
• At positions where it is the studied side's turn, allow at most one child. Replaying the existing move is valid; attempting a different move must not alter the tree and must explain that the existing move must be deleted first.
• At opponent-to-move positions, allow any number of distinct children, creating variations. Keep the user's current branch as the preferred forward-navigation branch.
• Render the move list in PGN style. The first child is the unparenthesized main line; sibling alternatives appear in parentheses at their branch point. Show correct move numbers for White and Black moves, including Black's number when a variation resumes. Clicking any move selects that position and updates the board, tree highlight, Explorer, and enabled engine analysis.
• Mark moves made by the studied side in blue, the currently selected node with a background highlight, and the custom starting point in yellow. The starting-point style takes precedence if both markers apply.
• Allow a plain-text comment on the selected move/position, including the starting position. Show a marker on moves with comments and edit the selected position's comment in the comment field below the tree. Store comments on their tree nodes and auto-save them with the study.

Navigation and actions

• Go to start selects the study's starting point, or the true root when no custom starting point is set. Delete this move deletes the selected node and its entire descendant subtree, then selects its parent. Disable deletion at the root.
• Left/Right arrow steps backward/forward along the currently followed branch. Up jumps to the study's starting point; Down follows the selected branch to its end. Click the ? button or press ? to toggle the shortcut list. Enter in a comment saves and leaves the field; Shift+Enter inserts a newline. Do not intercept navigation keys while an input, select, or textarea has focus, or when a modifier key is held.
• Auto-save the whole tree, side, Explorer settings, and starting point with POST /api/studies / PUT /api/studies/{id} after a short debounce. A new study is created after it has a non-empty name. Show saving/saved/error status, preserve local edits on failure, and retry when the user edits again or reconnects. Links wait for pending edits to save before leaving; browser navigation warns while edits remain unsaved. There are no Cancel or Save buttons.
• Show a Delete study button at the bottom for saved studies. Require confirmation before DELETE /api/studies/{id}, then return to the study list. Deletion is owner-scoped and removes that study's practice state.

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 is below the board and updates for the currently selected FEN. Its enable checkbox hides the panel and disables its settings when off. Changing a setting fetches data for the current position. Show a loading state while fetching and a recoverable unavailable message on failure.

• Offer a data source selector between Lirep and Lichess. Lichess provides Players and Masters databases; Lirep provides its local rated-player database. Masters is only selectable with Lichess. For Players/Lirep, offer minimum rating and Bullet, Blitz, Rapid, Classical speed filters. Default speeds are Blitz, Rapid, Classical; require at least one checked speed.
• Minimum rating is a fixed threshold stored on the study, like every other Explorer setting. A brand-new study's picker starts pre-selected at the signed-in player's own bracket (resolved from Rapid, then Blitz, then Classical; 1500 if no rating exists), but that's a one-time default, not a standing "current rating" mode — picking a different threshold just overwrites it the same way.
• In Masters mode, disable the rating and speed controls; they do not filter the Masters database. Label the Lirep source distinctly; its current local test dataset is March 2016.
• Render each move with SAN, a white/draw/black outcome bar and percentages, and game counts. Clicking a row plays/adds that move in the current tree, subject to the studied-side one-child rule.
• Indicate the data fetch time as a relative age, with the exact timestamp available on hover. The backend cache is shared and keyed by provider, database, query filters, and FEN; Explorer entries expire after 24 hours.

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

The checkbox lazily starts a local Stockfish WASM worker on first use. Analyze the current position with MultiPV 5. Draw up to five ranked arrows on the board, green through red, and show a matching ranked list with SAN and evaluation. 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 the option off clears arrows/results and terminates the worker. Game-over positions show a game-over state and no candidate moves.

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 study list/editor, tree helpers, study API, Explorer service, and shared Stockfish client.