Caissa

A chess study plugin for Obsidian: embed positions, study openings and endgames, browse World Championship games, and annotate PGNs inside your notes. Named after Caïssa, the muse of chess.

• Pick from a built-in library of openings and variations (Sicilian → Dragon, Najdorf, Yugoslav…)
• Play any position against Stockfish with adjustable strength (level 0–20) — fully offline, click-to-move, with promotion/undo/new-game controls
• Study canonical endgame techniques — basic mates, Lucena, Philidor, Vancura, opposition, wrong-bishop draw, and more
• Browse bundled World Championship games — 68 hand-picked decisive/famous games from 1886 (Steinitz–Zukertort) through 2024 (Gukesh–Ding)
• Paste a PGN from anywhere (Lichess, chess.com, ChessBase, your own play) and play through it with full headers
• Pull a Lichess game directly with lichess: <url> — no token needed
• Step through moves with prev/next controls or click any move in the list
• Drop multiple boards in the same note to compare variations side by side
• Two-column white/black move list right next to the board
• 7 piece styles to choose from — classic, modern, retro, and more (see Piece sets)
• Optional Opening Explorer panel showing win/draw/loss percentages for every candidate next move (powered by Lichess, opt-in)

Privacy

This plugin does not read or write your system clipboard. Insert commands open a modal so you can paste FEN, PGN, or a Lichess URL yourself. Board export offers Save as PNG/SVG downloads and a Copy as SVG modal where you select the markup and copy with your own shortcut.

Optional features fetch data only when you use them: Lichess game import (lichess: blocks) and the Opening Explorer call the public Lichess API. Stockfish analysis runs entirely offline in a Web Worker bundled with the plugin — no network calls.

Contents

• Quick start
• Screenshots
• Usage — Inline picker, Sizing and layout, Loading whole games, Built-in openings, Endgames, World Championship games, Piece sets
• Commands
• Export a board as PNG or SVG
• Captured pieces and material balance
• Annotations: arrows and square highlights
• Keyboard shortcuts
• Engine analysis (Stockfish, offline)
• Play against Stockfish
• Opening Explorer (win / draw / loss bars)
• Block options reference — every key you can put in a chess block
• Settings
• Privacy
• Development
• Credits

Quick start

If you only read three examples, read these. Each is a complete, self-contained block — paste it into any note and it just works.

1. Pull up a known opening:

```chess
opening: Sicilian Defense
variation: Dragon
```

2. Drop in a PGN you copied from anywhere:

```chess
[White "Carlsen, Magnus"]
[Black "Nakamura, Hikaru"]
[Result "1-0"]

1. e4 e5 2. Nf3 Nf6 3. Nxe5 d6 4. Nf3 Nxe4 ...
```

3. Play a real game against Stockfish from any starting position:

```chess
opening: Italian Game
play: white
level: 5
```

That's the whole mental model: every block is a starting position plus optional behavior. See Block options reference for every key you can use, or keep reading for guided examples.

Screenshots

Images live in assets/ (same paths work on GitHub and in Obsidian’s Markdown preview when the README is opened from the vault).

Opening study

A built-in opening with the two-column move list and board layout:

Free board

Blank board mode: both colors are human, moves persist in the block as moves: / freeboard::

Usage

Add a fenced code block with the language chess:

```chess
opening: Sicilian Defense
variation: Dragon
```

That renders the full Dragon line with a board, an interactive move list, and step controls. Anything you can put in a code block is supported, so you can have several variations stacked in the same note:

## Sicilian Defense

### Najdorf

```chess
opening: Sicilian Defense
variation: Najdorf
```

### Dragon

```chess
opening: Sicilian Defense
variation: Dragon
title: My Dragon notes
```

### Yugoslav Attack against the Dragon

```chess
opening: Sicilian Defense
variation: Yugoslav Attack
```

Inline picker

Don't want to look up slugs? Drop a blank chess block — either the Insert chess board command or just type the fences yourself:

```chess
```

The rendered block grows a little dropdown strip across the top: pick a category (Openings, Endgames, World Championship), then a specific opening/variation/endgame/game from a second dropdown. Your selection is written back into the block's source as opening: … / variation: … / endgame: … / wccgame: …, so the result is the same as if you'd typed it by hand — and it survives reload, sync, and copy-paste.

This is the friendliest way to use the plugin if you don't already have a position in mind.

See Block options reference for every key you can put in a chess block.

Sizing and layout

opening: Sicilian Defense
variation: Dragon
size: large       # small | medium (default) | large | full
showMoves: true   # set false to hide the right-hand move list
interactive: false  # set false to hide the prev/next/flip buttons

• small ≈ 240px board, medium ≈ 360px (default), large ≈ 500px.
• size: full makes the board fill the writing area's width and pushes the move list below it.
• The board's column also auto-collapses to a single stacked layout when the writing pane is narrower than ~520px (mobile screens, narrow split-pane editing). This uses CSS container queries so it responds to the pane width, not the whole window.
• showMoves: false lets the board take the row by itself without an empty side column.

If both opening and moves are provided, moves wins (handy for adding extra moves past the book). If pgn or lichess is set, those win over everything else (they bring their own moves and headers).

Pick the position to show on first render

By default a block opens at the starting position (move 0) so you can step through. If you'd rather land on a specific move — to highlight a critical position, jump straight to a tactic, or open a long PGN at the interesting middlegame — use startMove:

```chess
opening: Sicilian Defense
variation: Najdorf
startMove: 12
```

startMove is a 0-indexed step into the move list (0 = starting position, 1 = after White's first move, 2 = after Black's first reply, and so on). Out-of-range values clamp to the last move, so startMove: 999 on a 30-move game just opens at the end. Stepping with ←/→ works normally from there — it's purely the initial render position, not a hard limit.

Loading whole games

Paste a PGN

If the entire body of the block looks like a PGN — that is, it starts with a [Tag "value"] header, or contains move tokens with no key: value lines — the plugin treats the whole block as a PGN. No pgn: prefix needed:

```chess
[Event "Norway Chess"]
[Site "Stavanger NOR"]
[Date "2024.05.27"]
[White "Carlsen, Magnus"]
[Black "Nakamura, Hikaru"]
[Result "1-0"]
[WhiteElo "2830"]
[BlackElo "2789"]
[ECO "C42"]
[Opening "Russian Game"]

1. e4 e5 2. Nf3 Nf6 3. Nxe5 d6 4. Nf3 Nxe4 5. d4 d5 6. Bd3 Bd6 ...
```

The plugin renders a clean game-info strip above the board (players · result · event · date · ECO/opening), strips any { [%eval ...] [%clk ...] } annotations, and walks the mainline. Variations and comments are dropped.

PGNs from Lichess, chess.com (Share → PGN), ChessBase, SCID, and the Lichess pgn-extract tool all paste cleanly.

Pull a Lichess game by URL

If you'd rather just point at a Lichess game, use the lichess key:

```chess
lichess: https://lichess.org/q7ZvsdUF
```

A bare game ID also works (lichess: q7ZvsdUF). The plugin fetches the PGN from https://lichess.org/game/export/<id> over HTTPS — no token required for this endpoint, unlike the Opening Explorer. Results are cached in memory for the session.

You can combine lichess: with sizing/orientation keys:

```chess
lichess: https://lichess.org/q7ZvsdUF
size: full
orientation: black
```

Built-in openings

Italian Game · Ruy Lopez · Sicilian Defense (Najdorf, Dragon, Yugoslav, Accelerated Dragon, Scheveningen, Sveshnikov, Taimanov, Kan, Classical, Closed, Alapin, Smith-Morra) · French Defense · Caro-Kann · Scandinavian · Pirc · Alekhine's · Queen's Gambit (QGA, QGD, Slav, Semi-Slav, Tarrasch, Albin) · King's Indian · Nimzo-Indian · Grünfeld · English · Réti · London System.

Use the Insert chess opening from library command (Cmd/Ctrl+P) to fuzzy-search and insert a block for any of them.

Endgames

The plugin ships ten canonical endgame techniques. Use them with endgame: <slug>:

All five mating endgames ship a verified mating sequence you can step through with next. KQK, KRK, and the two-rook ladder use hand-crafted demo lines from a central starting position. For the two hardest mates we ship real games that were actually played out: KBNK uses the ending of Karttunen vs Rasik (European Club Cup 2003), picked up at move 84 with 23 moves of W-manoeuvre to mate; KBBK uses Joe Leslie-Hurd's 2005 tablebase analysis of the longest forced KBBK mate, with both sides playing perfectly to mate-in-19. The five non-mating positions (Lucena, Philidor, Vancura, K+P opposition, wrong-bishop) are study positions where the technique itself depends on best play from both sides, so the plugin lets you explore them without forcing a fixed line.

Example:

```chess
endgame: lucena
```

Use the Insert chess endgame from library command for a fuzzy picker.

World Championship games

The plugin ships 68 hand-picked World Championship games covering 20 matches from 1886 (Steinitz–Zukertort) through 2024 (Gukesh–Ding). Each is referenced by a stable slug formatted <year>-<player1>-<player2>-<game>:

```chess
wccgame: 1972-fischer-spassky-06
```

That renders Fischer's famous game 6 against Spassky from Reykjavik with full headers, the result, the ECO code, and a clickable move list.

Use the Insert chess world championship game command for a two-step picker (match → game). PGNs are sourced from PGN Mentor and bundled inline with the plugin — no network calls at runtime.

To curate or extend the bundled set, edit scripts/wcc-curated.json and re-run node scripts/fetch-wcc-games.mjs.

Piece sets

Set the global default in Settings → Community plugins → Caissa → Piece set, or override per board with pieces: <name>.

Commands

• Insert chess board — drops an empty chess code block at the cursor.
• Insert chess opening from library — fuzzy-search modal for openings and variations.
• Insert chess endgame from library — fuzzy-search the bundled endgame techniques.
• Insert chess world championship game — two-step picker (match → game) over the bundled WCC corpus.
• Insert chess board from FEN — modal to paste a FEN string into a new block.
• Insert chess game from PGN — modal to paste PGN text into a new block.
• Insert chess game from Lichess link — modal to paste a Lichess game URL or ID.
• Start openings quiz — opens a modal that endlessly serves up positions from the bundled opening repertoire and asks for the next book move. Move spelling variants (Nf3 vs Ngf3) are normalized via chess.js so anything legal counts. Tracks correct/total and a streak per session.

Or, drop a blank chess block (the Insert chess board command) and use the inline picker — a category dropdown lets you switch between Openings, Endgames, and World Championship right inside the rendered block, without typing slugs.

Export a board as PNG or SVG

Right-click any rendered board (long-press on touch) for a context menu with:

• Copy as SVG — opens a modal with the SVG markup to select and copy yourself.
• Save as PNG — downloads a caissa-board-<position>.png file at 2× resolution (720×720 by default).
• Save as SVG — downloads a caissa-board-<position>.svg file.

Exports always reflect the current position on screen (after stepping moves or flipping), and use whichever piece set / colors / annotations you've configured for the block — what you see is what you export.

Captured pieces and material balance

Every board automatically shows a captured-pieces tray above and below it, plus a +N material badge next to the side that's ahead. The piece glyphs use whichever piece set is active for the board so the tray always matches.

• Pieces captured by White appear on White's side (bottom of the board by default; top if you flip with F).
• Pieces captured by Black appear on Black's side.
• The +N badge shows pawn-equivalent material — promotions are accounted for, so a queened pawn shows as +8 rather than +1 once it promotes.
• Trays auto-hide on positions where nothing has been captured (a fresh starting position, an endgame study with no captures), so they never add empty space.

You can hide the trays globally in Settings → Caissa → Show captured pieces, or per-block with captured: false.

Annotations: arrows and square highlights

Annotate any board with arrows (move suggestions, threats, plans) and square highlights (key squares, weak squares, mating nets). Both are declarative — no clicks involved — so they survive note round-trips and look the same on every device.

```chess
fen: r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3
arrows: f3e5 g1f3-blue
highlights: e5 f7-red
```

Token grammar:

• arrows: <from><to>[-color] — list of square pairs, whitespace-separated. e2e4 g1f3 d2d4-blue.
• highlights: <square>[-color] — list of squares, whitespace-separated. d4 e4-red f5-yellow.

Color presets: green (default), red, yellow, blue. You can also pass any 3, 6, or 8-character hex code without the # (e.g. e2e4-ff5500). Unknown colors silently fall back to green so a typo never breaks the board.

Highlights render as a colored ring inside the square (so the piece glyph stays readable); arrows render as a thick filled triangle on top of the board, matching the convention from Lichess and chess.com analysis boards.

Keyboard shortcuts

Click any rendered chess block (or Tab into it — a soft accent ring shows it's focused) and use:

Shortcuts are scoped to the focused block, so multiple boards on the same page never fight for keys, and typing in any text input still works normally.

Engine analysis (Stockfish, offline)

Caissa ships a bundled offline copy of Stockfish 10 (the asm.js build by Niklas Fiekas, ~1.5 MB), so you can run engine analysis with zero network calls and on a plane. The engine is lazy-loaded on first use — if you never set analyze: true, no worker is spawned and no extra memory is allocated.

Add analyze: true to any chess block to turn on the analysis panel:

```chess
opening: Sicilian Defense
variation: Najdorf
analyze: true
```

That gives you:

• An evaluation bar to the left of the engine panel, showing the position from White's perspective (clamped at ±5 pawns for the bar; the numeric label is exact).
• The top 3 principal variations — eval, search depth, and the move sequence Stockfish recommends.
• A whole-game eval graph under the board with an Analyze game button. Click it once to evaluate every position in the loaded PGN at depth 12; the resulting sparkline shows where evaluation swings happened. Click anywhere on the graph to jump the board to that position.

Notes and tradeoffs:

• The engine is the pure-JS asm.js Stockfish 10 (no NNUE, no WebAssembly). Strength is around 3000+ Elo at depth 16 — more than enough for spotting tactics, blunders, and trends. If you need NNUE/cloud-grade analysis, run an analysis on Lichess and paste the PGN back in.
• Each block runs analysis serially through one shared worker; the worker stays alive across blocks so subsequent positions analyze fast.
• "Analyze game" on a 60-move game at depth 12 takes roughly 30–90 seconds depending on hardware.

The engine is bundled directly into main.js. Bundle size impact: the plugin grows from ~250 KB to ~1.8 MB. There are no extra files to install, no network downloads, and no telemetry.

Play against Stockfish

Set up any position you'd render normally (start position, an opening, an endgame, a custom FEN), then add play: white (or black, or random) to start a game from that exact position against the bundled Stockfish:

```chess
opening: Italian Game
play: white
level: 5
```

How it works:

• Click to move. Click a friendly piece to select it (legal targets light up as dots; capture squares get rings); click a destination square to play. Clicking the same square again deselects.
• Promotions trigger a popup with Queen / Rook / Bishop / Knight choices.
• Game over is detected automatically — checkmate, stalemate, threefold repetition, insufficient material, or 50-move rule. The status line below the board updates in place.
• Undo rolls back to the last position where it was your turn (your move + the engine's reply).
• New game resets to the configured starting position. If you set play: random the controller picks a side at mount time and a fresh "new game" keeps that side.
• The captured-pieces tray + material badge work as usual so you can see how a game is going at a glance.

Strength control via level: 0–20:

Lower levels also use shallower searches so weak moves come back fast — at level: 0 the engine plays nearly instantly. At level: 20 each move can take a couple seconds depending on hardware.

Notes:

• The board, captured tray, piece set, colors, and orientation all respect the same pieces / light / dark / coordinates config you'd use on a normal block.
• play is mutually exclusive with stepping through a fixed PGN — once you set play, the move list becomes a passive transcript and the prev/next/last buttons are gone.
• play plus lichess: <url> isn't supported (the lichess loader runs first); paste the PGN inline if you want to play a position from a Lichess game.

Opening Explorer (win / draw / loss bars)

Optionally show a Lines panel under each board with the win/draw/loss percentage for every candidate next move at the current position, exactly like Lichess's analysis page.

One-time setup

1. Settings → Community plugins → Caissa → Lichess API token — paste a token here.
2. To create a token, go to lichess.org/account/oauth/token, click Create new personal access token, give it any name (no scopes needed), generate it, and copy the token.
3. Toggle on Enable opening explorer.

That's it. The panel now appears under every chess board and updates as you step through moves.

Why a token?

Lichess started requiring authentication on its Opening Explorer API in March 2026 to mitigate DDoS abuse. The token is free, takes 30 seconds to create, and is rate-limited to 25 requests / minute (more than enough for normal study). Your token is stored locally in the plugin's settings file inside your vault — it is never sent anywhere except to Lichess.

Data sources

• Masters database — over-the-board games played by 2200+ rated players (high-quality opening theory).
• Lichess players — a much larger database covering all rated games on Lichess (good for offbeat lines).

You can switch sources globally in settings, or per board with explorerSource: lichess.

Privacy

When the explorer is enabled, the plugin sends the current board position (FEN) and your Lichess API token to https://explorer.lichess.ovh over HTTPS. Nothing else is transmitted; your notes, vault contents, and other settings stay local. The explorer is off by default — you have to opt in.

When you use the lichess: <id> key, the plugin makes a separate, anonymous HTTPS request to https://lichess.org/game/export/<id> to download the PGN of that one specific game. No token is sent and no other request is made. This only happens for blocks that explicitly use the lichess: key.

Results are cached in memory for the session, so stepping back and forth through a line never refetches.

Block options reference

Every key you can put inside a chess code block. All keys are optional and may appear in any order. Per-block keys always override the matching global setting.

Position (pick one — the first one set wins)

Display

Annotations

Engine

Opening Explorer

Settings

Settings → Community plugins → Caissa lets you customize:

• Default piece set (7 styles to choose from — see Piece sets)
• Light / dark square colors
• Last-move highlight color
• Whether to show coordinates and interactive controls by default
• Default board orientation
• Opening Explorer enable / disable, data source, max lines, Lichess API token

Per-block settings always override the global defaults.

Development

npm install
npm run dev      # watch + rebuild main.js
npm run build    # type-check and produce a production main.js
npm run lint     # eslint over src/

To test locally, this folder lives at <Vault>/.obsidian/plugins/caissa/. After building, reload Obsidian and enable Caissa under Settings → Community plugins.

Credits

• Move logic: chess.js
• Opening statistics: Lichess Opening Explorer (CC0)
• World Championship game PGNs: PGN Mentor (records of historical OTB games are not subject to copyright; only the move sequences are bundled, with the original event headers preserved)
• Piece artwork (sourced from the Lichess (lila) repository; see lila's COPYING.md for canonical license info):
  • cburnett — Colin M.L. Burnett (GPLv2+)
  • merida — Armando Hernández Marroquín (GPLv2+)
  • staunty — sadsnake1 (CC BY-NC-SA 4.0)
  • caliente — avi (CC BY-NC-SA 4.0)
  • pixel — therealqtpi (AGPLv3+)
  • letter — synthesized in this plugin

The CC BY-NC-SA 4.0 sets (staunty, caliente) include a non-commercial restriction. Distributing them as part of this free, open-source plugin is fine; if you fork this plugin and intend to sell it, remove those sets first.

To refresh the bundled SVGs from upstream, run node scripts/fetch-piece-sets.mjs and commit the regenerated src/chess/piece-data.generated.ts.

Release

Push a tag matching manifest.json version (no leading v, e.g. 1.0.3). The release workflow builds main.js, attests main.js and styles.css, and publishes a GitHub release with main.js, manifest.json, and styles.css.

Support