Chess

The whole game is this one HTML file — no build step, no libraries (the optional Stockfish engine is a separate file it loads on demand; see below). All the JavaScript lives in a single function (an IIFE) at the bottom, split into labelled sections with // === banners, mirroring the structure of the Python/Tkinter version this was ported from:

• The rules live in one shared file, src/rules.js, used by this page, the course and the tests. They are pure functions over an 8×8 array of single-letter piece codes (uppercase White, lowercase Black, null empty), with no DOM and no shared state: move generation (pseudoMovesFor, generateLegalMoves, attackedBy), positions to and from FEN, play(position, move), algebraic notation, the draw rules, and PGN. tests/rules.test.js checks move generation by perft: counting every move sequence to a fixed depth and comparing with published counts for standard test positions (197,281 sequences four plies from the start, for example).
• Notation (toSAN) — turns a move into algebraic notation (Nf3, exd5, O-O, e8=Q+), disambiguating with a file or rank only when another legal move of the same piece type shares the destination square. parseMove reads typed moves leniently.
• The screen & the glue (RENDER, ANIMATION, FLOW) — the only code allowed to touch the DOM. render() paints state onto the board; FLOW changes state in response to clicks.

A move is a plain array, not a class

Every move is [fr, fc, tr, tc, flag, extra] — from-square, to-square, and an optional flag ("double", "ep", "promo", "O-O", "O-O-O") with an extra payload (the promotion piece letter, for "promo"). pseudoMovesFor generates every geometrically legal move for one piece — including castling and en passant — without checking whether it leaves its own king in check.

Legality is "does this expose my king?"

generateLegalMoves takes every pseudo-legal move, plays it on a cloned board, finds that side's king, and asks attackedBy whether the opponent attacks that square. Only moves that leave the king safe are legal. This is the same trick chess engines have used for decades: generate loosely, filter by simulation, rather than hand-coding pin and discovered-check logic.

attackedBy is the whole rulebook in one function

To ask "is this square attacked by color X", the function checks, from that square outward: the eight knight-jump offsets for an enemy knight, the eight adjacent squares for an enemy king, the two diagonal-forward squares for an enemy pawn, then walks the four diagonals for a bishop/queen and the four ranks/files for a rook/queen, stopping at the first piece it meets in each direction. Check detection, castling-through-check, and "is this move legal" all reduce to calls to this one function.

The computer opponent is Stockfish, talking UCI

The engine is Stockfish.js — the open-source Stockfish 18 compiled to WebAssembly (the ~7 MB "lite, single-threaded" build, GPLv3), vendored in chess/engine/. It runs in a Web Worker so it never freezes the page, and is only downloaded the first time you pick the computer as opponent. The page talks to it in plain-text UCI, the protocol every chess GUI uses: it sends position startpos moves e2e4 e7e5 … (the whole game, so the engine also sees repetitions; a game that began from a loaded position sends position fen … instead), then go depth N, and waits for a bestmove g1f3 line. That string is matched against this page's own legal-move list, and played through the same makeMove a click uses — so the engine can never make a move the rules here don't allow.

Strength levels set Stockfish's Skill Level option (0–20, which makes it deliberately choose weaker moves) together with a search-depth cap. If you undo or start a new game while it's thinking, the page sends stop and throws away the answer that comes back.

Game review: winning chances, not centipawns

A second Stockfish worker (so the opponent is never disturbed) evaluates every position of the game at depth 14. src/review.js converts each score into White's winning chances, 2 / (1 + e^{−0.00368·cp}) − 1, the curve Lichess uses. It then grades each move by how far it lowered the mover's chances: 0.1 is an inaccuracy, 0.2 a mistake, 0.3 a blunder. Working in chances rather than centipawns means a slip from +8 to +6 in a won position barely counts, while +0.3 to −1.0 does. Per-move accuracy follows Lichess's formula, and a side's accuracy is their average. Moves that follow the opening book are labelled "book", unless the engine calls them a mistake: the book contains traps too, fool's mate among them. tests/review.test.js covers the grading, the book and a fast UCI reader checked against the move generator.

The engine worker is driven strictly by the UCI rules: a new search waits for the stopped search's bestmove before sending options. Sending options mid-search can make the single-threaded WebAssembly build abort, which is how this was found. A worker the browser kills is restarted.

The coach is the analysis engine, asked before each move

When you move against Stockfish with the coach on, the move is held while the second Stockfish worker evaluates the positions before and after it at depth 11. The position before has usually been evaluated already, in the background, while you were thinking. If the move costs 0.2 of winning chances (0.3 on Light), the move is not played. src/motifs.js names what the engine's reply would do: fork, pin, skewer, loose piece, discovered attack, back-rank mate and so on. Its rules were tuned against the theme labels of about 11,000 Lichess puzzles. The coach's searches run one at a time through a small queue, because a new search would stop the one running.

Opening names from a public-domain catalogue

The 3,864 named lines of lichess-org/chess-openings (CC0) are replayed through the rules by tests/build-openings.js into src/openings-data.js, which is loaded once the page is idle. Positions are matched by placement, side to move and castling rights, so a transposition finds its name whatever the move order.

Draws are counted, not guessed

After every move the page stores a position key: the pieces, the side to move, the castling rights, and the en-passant square, but only when an en-passant capture is actually possible (that is the FIDE definition of "the same position"). Threefold repetition means the newest key occurs three times. The 50-move rule reads the FEN half-move counter, which resets on every capture and pawn move. Insufficient material means only kings remain, plus at most one knight or bishop, or bishops that all stand on squares of one colour. The checks run in that order after the test for mate, so a move that mates always wins.

Clocks run on timestamps

Each side's remaining time is stored as a number. The clock that is running is that number minus the time since its Date.now() start, so a slow or throttled browser tab can't make it drift. A 100 ms timer only repaints the display and notices when a flag falls.

Undo is snapshots, not reverse moves

Before every move, the entire board, castling rights, en-passant square and last move are cloned onto a history stack (same approach as the Go and Othello ports). Undo pops the stack and restores it wholesale — no move has to be "run backwards".

Board flip = re-reading one array

cells[r][c] always maps to the DOM cell for logical square (r, c), regardless of orientation; only buildGrid()'s construction order changes when flipped, walking visual rows/columns and computing which logical square lands there. Every other function only ever thinks in logical coordinates.

The 3D view is the same board, transformed

Switching to 3D doesn't swap in a 3D engine. The very same board gets a CSS perspective and a rotateX(tilt) rotateZ(rotation) transform, with transform-style: preserve-3d carried down to every square. Each piece then applies the inverse rotation — rotateZ(-rotation) rotateX(-tilt), read from two CSS variables — around its base, so the flat Unicode glyph stands up and faces you like a real chessman wherever the board is turned. Four faces folded down with rotateX/Y(±90°) make the board's sides. Because it's still the same DOM, the browser maps clicks through the transform onto the right square, so moves, highlights, animation, undo and the engine all work unchanged. A drag longer than a few pixels turns the board, and the click at the end of it is swallowed so it can't also move a piece.

Staunton pieces: SVG in 2D, real geometry in 3D

With Pieces: Staunton, the flat board shows Colin M.L. Burnett's classic SVG set (the one used on Wikipedia and lichess, here under the GPL). In 3D the pieces become actual 3D models drawn with three.js (WebGL, vendored, only downloaded when first needed). Each piece is a LatheGeometry — a profile of radius against height, spun around its axis like wood on a lathe — plus a few extra parts: rook battlements, the queen's coronet of spheres, the king's cross, and a knight's head that is a 2D silhouette extruded into a solid. A directional light casts soft shadows onto a board whose squares are painted into a canvas texture from the same CSS colours as the flat board. The hidden DOM board is still the one source of truth: a click on the 3D view is raycast to a square (a piece you can see wins, unless a highlighted target square is under the pointer) and handed to that square's normal click handler.

Look = CSS variables + a data attribute

Board colours are CSS custom properties. Choosing "Walnut" just sets data-board="walnut" on <html>; a CSS rule redefines --sq-light/--sq-dark; the browser repaints. Pieces are plain Unicode glyphs (♔♞♟…) in one fixed ink colour — White's glyphs are hollow outlines and Black's are solid silhouettes, so the two sides read apart without any per-piece color logic at all.