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
- The home page lists the current account's studies, one card per study, grouped by side and followed by a New study card. Each card has Edit and Practice buttons, which open the study page and a practice session (with Bullet joined to Practice's right end, the bullet icon, which starts a Bullet run), its badge, which opens the study's Stats page, and two icons: duplicate and archive.
- Archive moves the study, at once and without a confirmation, to the archive, and a note at the bottom of the window says so for a few seconds with Undo (
PUT /api/studies/{id}/archivedwith{archived};studies.archived_at). Archived studies are kept, with their practice history, but are off the Practice page, the profile's list and the Community page and leaderboards; their sharing setting is kept for when they come back. A “Show archived (n)” switch, after the studies and just above Import (it stays there when on), remembered in the browser, shows them in an Archived section above it, by side (Openings for White, then for Black, a side with none left out): faded cards with a dashed border and a grey, still badge, with Edit, Restore, duplicate and a bin, which deletes the study for good after a confirmation. - Duplicate swaps the card's buttons for the copy's name (the study's own plus “(copy)”, or “(copy 2)” and so on if taken, selected) with Duplicate and Cancel; Escape cancels.
POST /api/studies/{id}/duplicatewith{name}copies the moves and comments, side, starting point, Explorer settings, calculated stats and games; the copy is private, so it doesn't appear twice on the leaderboards, and its practice history starts afresh. It shows first among its side's studies. - Order: drag a card to reorder it within its side (or within the archive), as the games on a Games page; the New study card stays last. The order is saved for all the account's studies (
PUT /api/studies/orderwith{ids};studies.position); the Practice page keeps its own order, by knowledge. A study never placed (new, imported or duplicated since the last reordering) comes first, the latest first; until the first reordering, that is every study. - A study with games shows a badge by its name (a book icon and the number of games) linking to its Games page; studies without games don't.
- 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.”
- New study opens a blank study page.
- Below the studies, Import a study from a file creates a study from a study file and opens it. A file that can't be read is refused with a message saying what is wrong and where; nothing is created.
- 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.
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" }
]
}
formatandversion(required): always"lirep-study"and1. A later, incompatible format would get a new version number; files of an unknown version are refused.name(required): the study's name.side(required):"white"or"black", the side the repertoire is for.moves(required): the main line, a list of moves from the initial position. Each move hassan, the move in standard algebraic notation; an optionalcomment; and optionalvariations, a list of lines (each a list of moves) played instead of that move, from the same position, in the order they appear in the editor. Variations can themselves contain variations. This is how PGN writes variations, in parentheses after the move they replace.start(optional): the starting point, as the list of moves leading to it from the initial position. Leave it out for none.explorerSettings(optional): the Opening Explorer settings the study's stats are calculated with (source,database,minRating,player,speeds, as in the editor). Missing fields take their defaults.games(optional): the study's games, in the order of its Games page. Each has an optionalsection(its section's name, up to 60 characters; left out for a game without a section),pgn(the game as PGN text, headers included) and an optionalcomment. Sections are created in the order their first game appears; empty sections are not in the file. For example:"games": [ { "section": "Master games", "pgn": "[White \"Carlsen, M.\"]\n[Black \"Anand, V.\"]\n[Result \"1-0\"]\n\n1. e4 c5 2. Nf3 d6 1-0", "comment": "Model game" }, { "section": "My games", "pgn": "1. e4 c5 2. Nc3 *" } ]
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.
- 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. The comment field below the tree opens on its own for a position that has a comment, and otherwise with the toolbar's Comment button. Store comments on their tree nodes and auto-save them with the study.
Navigation and actions
- The Go to start navigation button 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 in the header, 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. - For saved studies, the header's “⋯” menu holds the Share with the community checkbox, Export to file (see Study files) and a Delete study button. Require confirmation before
DELETE /api/studies/{id}, then return to the home page. Deletion is owner-scoped and removes that study's practice state.
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.
- Adding games: Add games opens a text field for PGN (one game or several, as exported by most databases) or Lichess game links, one per line (
lichess.org/<id>, as copied from the address bar or Lichess's share button), or both. Each linked game's PGN is fetched from Lichess's public export, without clock times or engine evaluations. Choose a section: None (the default), an existing one, or a new one. Games that can't be read (an illegal move, for example) are reported by their number and skipped; the others are added at the end of the section. - The cards: each section shows its games as cards: a small board with the game's final position, and the players above and below it on their own side of the board, with their ratings and scores, then the event and year (all from the PGN headers). The × in a card's corner (shown on hover) deletes the game. While the pointer is over a card, the board replays the game from the start (a move every 0.22 s), and returns to the final position when the pointer leaves.
- Order and sections: drag a card to reorder it or move it to another section, empty ones included, or to the top of the page, among the games without a section; drag a section by its grip (⠿) to reorder the sections. From the keyboard, Alt+← / Alt+→ on a focused card moves it (into the neighbouring section at either end), and ↑ / ↓ on a section's grip moves the section. ✎ renames a section; × removes an empty section; New section adds one.
- Open games in Lichess or Lirep: a switch at the top of the page (Lichess by default), remembered in the browser. On Lichess, a card opens the game's own Lichess page in a new tab when it was played there (its PGN's
Siteheader is a Lichess game link), otherwise Lichess's analysis board with the game's moves. - A game: in Lirep, clicking a card opens the game (
games.html?id={studyId}&game={gameId}) in the same read-only view as a shared opening: the board with the move list, the Opening Explorer and Stockfish, and a link to Lichess's analysis board. The Explorer shows its moves alone, without the editor's marks. The tools start with the study's Explorer settings and the editor's Stockfish depth; the gear beside them changes both for the page only, without saving anything, so the study, its stats and the editor keep their own. Comments are on positions, as in the editor: the comment field under the moves opens on its own for a position that has a comment (the PGN's own included), and otherwise with the Comment button or C; they are saved as you type, in the game's PGN. The "⋯" menu in the header changes the game's section and deletes the game. Variations inside a game's PGN are not shown, and games starting from a custom position (aFENheader) can't be opened in this view yet. - Limits: up to 500 games and 50 sections per study, 100,000 characters per game and 10,000 per comment.
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.
- 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 starts at 1600+ with Blitz games, as the Browse page's openings are calculated with; that's a one-time default — picking a different threshold just overwrites it the same way.
- A third Lichess database, Player, shows one player's own games as the study's side (like the Player tab of Lichess's explorer). It asks for a Lichess username, defaulting to the signed-in user, keeps the time-control filter, and has no rating filter. Player data exists only on Lichess, so choosing it switches the source to Lichess. Scores calculated from it are not ranked on the Community page, since they describe one person.
- In Masters mode, disable the rating and speed controls; they do not filter the Masters database. Label the Lirep source distinctly; its current local dataset is Lichess games from February to April 2016 (about 16.7 million rated games).
- Render each move with SAN, a white/draw/black outcome bar and percentages, its game count, and its share of the games in this position. Clicking a row plays/adds that move in the current tree, subject to the studied-side one-child rule.
- Show the study's repertoire in the list. Moves already in the tree from this position get a check mark and a green edge. On the opponent's turn, replies played in at least 5% of games that the tree lacks get an orange edge (“Not prepared” on hover).
- Indicate the data fetch time as a relative age, with the exact timestamp available on hover. Lichess's Explorer is queried from the browser with the user's own token, one request at a time and at least 500 ms apart, pausing a minute after an HTTP 429; the panel's requests go ahead of a running calculation's. Responses are cached in the browser for a year (24 hours for the player database); responses from the local Lirep explorer are not cached.
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.
- Goal: a number of moves, or a target expected score. Where: anywhere in the study, or only after the selected move (in its subtree, or answering it if it's an unanswered reply). Either way, the expected score shown is the whole study's, from its starting point.
- Advanced: your most played moves considered in a position (6), the games a move needs to be one (100), the share of games under which a reply is left out (0.2%), and the moves allowed, by the centipawns they may lose against Stockfish's best: any (the default), best only (10), excellent or better (25), good or better (50), up to inaccuracies (100), or a number of your own. The loss is Stockfish's evaluation of the position before the move minus that after it, for your side, each within ±10 pawns (a mate counts as 10). Stockfish then evaluates the position before each move tried and after it, at the depth in the settings, whatever the end-of-prep value.
- Suggest one move adds one, Run goes on to the goal, Stop ends a run after the position being looked at. A status line says what it is doing, and when Lichess asks to wait.
- Each suggestion is a row: the reply it answers, your move, and the expected score with it and those above it (and its gain). Clicking a row shows its position on the board, without moves, until you navigate; once added, it goes there.
- Suggestions are worked out on a copy of the study holding the earlier ones not yet added, and nothing goes into the study until added: Add adds a row's line (with the suggested moves it goes through), Add all every row. Added moves come last among their siblings, so the study's order is kept. A line passing a position where you already have another move isn't added.
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.