An on-demand analysis panel for chess.com computer games. You press a button, it reads the position off the page, hands it to Stockfish 18, and shows you the best move with a board, arrows, candidate lines and commentary.
It is manual and read-only. It never dispatches an event at the board, so it cannot move a piece, and it does nothing at all until you press the button.
- rendered board with the best move drawn as an arrow (alternatives in grey)
- evaluation bar and signed score, always from White's point of view
- top three engine lines in SAN, with mate distances where they exist
- commentary derived from the analysis — how sharp the choice is, whether anything is hanging, material balance, mate threats
- search depth and nodes/sec
Stockfish 18 (stockfish-18-lite-single, 7MB WASM, NNUE). Single-threaded,
because multi-threading needs SharedArrayBuffer and cross-origin isolation
that an extension page cannot easily get. Even so it is far stronger than any
chess.com bot — think time is selectable up to 20 seconds.
It runs in an offscreen document, which matters: a content script inherits
chess.com's CSP and cannot load WASM, and an MV3 service worker cannot spawn a
Web Worker. An offscreen document is an extension-origin page, so our own
wasm-unsafe-eval applies and Workers are available.
Restricted to https://www.chess.com/play/computer*. On any other page the
content script is never injected and the panel is never built — scoped there it
does what chess.com's own Hint button does in bot games. guard.js re-checks on
every button press, because chess.com is an SPA and the route can change under a
live script.
npm install # dev-only: chess.js + jsdom for the tests
npm test # 59 testschrome://extensions → Developer mode → Load unpacked → this folder.
Two ways in, both showing the same thing:
- Toolbar popup — click the extension icon. This is the main UI and does not
depend on the content script at all: it injects its own reader into the tab
with
chrome.scripting, so it works even if the in-page panel failed to load. - In-page panel — appears top-right on a computer game. Press
Aor click Analyse position.
The popup applies the same /play/computer allowlist as the content script, so
it cannot be used as a way around the restriction.
It doesn't decide. Pressing the button is the assertion that it is your move, which is why there is no turn-detection heuristic anywhere in this codebase. That one design choice removed the most fragile part of the original attempt.
The position itself is read two independent ways — the piece elements, and the
move list replayed from the start — and cross-checked. If they disagree, it
refuses rather than analysing a position it misread. Chess.com renders no move
list and no highlights on /play/computer, so in practice the piece scrape plus
your button press supplies everything needed.
| file | role |
|---|---|
src/guard.js |
page allowlist, fail closed |
src/board-reader.js |
DOM → FEN, cross-validated |
src/commentary.js |
analysis → English, no language model |
src/popup.js |
toolbar popup — the main UI, injects its own reader |
src/content.js |
optional in-page panel |
src/ui.js |
board rendering and arrows, shared by both |
src/fen.js |
scraped grid → FEN |
src/offscreen.js |
Stockfish host, UCI driver |
src/background.js |
offscreen lifecycle + message relay |
board-reader.js depends on chess.com's markup (wc-chess-board,
piece wp square-51). When chess.com ships UI changes that is the first place
to look. The failure is safe: a misread refuses rather than guessing.