feat(heatmap): board overlay for next-move frequencies

[atamano]

Takes over #18 (Jeff Palmer's heatmap overlay) and reworks it to fit the architecture and clear the blocking bugs found in review. The feature, the styling, and the full 13-locale i18n are Jeff's; this branch keeps them and rebuilds the data path underneath.

Closes #18. Co-authored with @jeffpalm.

What the feature does

A "Heatmap" toggle by the board's Export button. On, every candidate next move at the current position tints its destination square cold-to-hot by how often it was played, with the opening name, share %, and game count on the square.

What changed from #18

Collision bug — was dropping games (blocking). The overlay keyed cells by destination square and, when two moves shared one (Nf3/f3 from the very first move, Rae1/Rfe1 later), kept only the most-played and silently discarded the other's games, so shares no longer summed to 100%. Squares now aggregate every move that lands on them. Verified: buildHeatmap with Nf3(10)+f3(4) yields one f3 cell of 14 games, sum preserved.

ECO catalog no longer touches the main thread (architecture). #18 added use-eco-lookup.ts, which dynamic-imported the ~830 kB eco-data object literal onto the main thread to name openings — a second parse of a catalog the worker already holds, against the CLAUDE.md rule that classification lives in the worker. That hook is deleted; naming now goes through a lookupEco Comlink method on the scanner worker. Confirmed on the production build: the only chunks containing the catalog are worker chunks (Comlink.expose), the main-thread React chunk is 248 kB with zero EPD entries, and toggling the heatmap fetches nothing.

Sample-size floor (consistency). The 3% share threshold ignored sample size, so a 2-game node could paint a saturated square — the exact thing confidence-badge was added to stop. A cell now needs ≥5 games and ≥3% share to be tinted; below either, the label still shows, untinted.

Single-ECO-match label no longer vanishes. The shared-family strip now requires ≥2 named cells, so a lone match keeps its name instead of being reduced to nothing.

Gradient carries magnitude in more than hue. Lightness and alpha ramp with intensity alongside hue, so the scale survives grayscale and red/blue color deficiency and lets the wood grain show at the cold end. (The relative-to-max normalization is kept but its trade-off is now documented honestly: the % label carries the absolute magnitude.)

Simpler, more robust fade. The hand-rolled displayed/ref/phase/rAF machine is replaced by a CSS mount animation for fade-in (reliable from the first frame) plus an opacity transition for fade-out.

Smaller fixes. Toggle can no longer get stuck on-and-disabled (it's never disabled); dead title tooltip removed; Switch labelled via aria-labelledby instead of a wrapping <label>; the 3.8 MB of screenshots in docs/heatmap/ are gone (they belong in the PR, not the repo).

Verification

• typecheck clean; lint 0 errors (2 new React-Compiler advisories on the fade timer / async lookup effects, both legitimate uses); production build succeeds.
• Drove it end-to-end: scanned 500 Lichess games, toggled on/off/on, drilled 1.d4 — gradient reads correctly (Nf6 45%·60 hot, d5 33%·44 mid, rarer replies cool), sub-5-game cells untinted, names differentiate. Zero console errors.

Note: this branch also carries 63f238b (chessendings.com docs), which was already committed here — shout if you'd rather it land on master separately.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
openingscanner	Ready	Preview, Comment	Jul 12, 2026 12:30pm

[atamano]

Closing for now — putting the heatmap on pause. Branch and work stay put; can reopen later.