English | 简体中文
Three minutes a day to understand one chess move.
Chess Moment is a mobile-first, interactive chess daily for beginners and casual players. Each day brings one short lesson: read the story, play the key moves on a real board, get instant green/red feedback with an explanation for every mistake, and ask an AI coach when you are stuck. The whole site is static — no account, no install, no cost.
AI assistants and agents: for a structured, machine-friendly description of this project, see README_FOR_AI.md.
Works directly in a mobile browser; on iPhone it can be added to the home screen like an app.
Beginners don't lack large platforms — they lack a low-friction daily habit: a three-minute lesson with a real board to touch, where every wrong move is explained immediately. Chess Moment turns "read a story → play a few moves → get instant explanations" into a daily push, with all logic running locally in the browser. No backend, no sign-up.
Every lesson combines a culture/history story, a tap-or-drag board challenge, explanations of wrong moves, an instant review after completion, and hover glossary for chess notation. Correct moves get a green ring, wrong moves get red with a reason; the opponent replies automatically after each correct move; reasonable-but-not-best alternatives get an amber explanation.
Every move is validated in the browser by a built-in rules engine. Correct moves show a green feedback ring and trigger the opponent's automatic reply; the teaching win-probability bar updates after each move.
Usage Guide · Rules Engine Design
Ask a question in the "Ask Coach" box and get an AI answer in the page language. The coach is prompt-constrained to explain ideas, rules and notation — never to reveal the solution moves. It works out of the box (an obfuscated OpenRouter free-model key is embedded), or you can plug in your own OpenRouter / DeepSeek / Zhipu GLM key in "AI Settings". If every AI path fails, it falls back to pre-written answers so users are never blocked.
Configuration · Feature Design
All lesson content and UI copy exist in both languages. English pages live in the en/ subdirectory; the site auto-redirects by browser language, and a manual toggle remembers your choice.
The homepage automatically shows "today's" lesson (matched by month/day); all other lessons become archive cards with tags, prerequisite links, and a problem-report button (email).
The same lesson data also generates a second reading form: a text-plus-static-board-image article for WeChat official accounts, plus a structured payload. The WeChat "Read original" link goes straight to that lesson's interactive page.
Lesson JSON (content/*.json) is the single source of truth. Build scripts validate every lesson against real chess rules (chess.js), then generate bilingual interactive pages, WeChat preview pages, static board PNGs and publishing payloads. Board interaction, move validation and the AI coach all run locally in the browser — there is no backend.
content/*.json → validate (real chess rules) → _site/ (zh pages + en/ pages + WeChat previews + board PNGs) → GitHub Pages
Architecture · Content Schema and Validation
Requires Node.js 20+ (local development uses 22, CI uses 24).
git clone https://github.com/petrel2015/chess-moment.git
cd chess-moment
npm ci
npm test # 173 tests: schema, chess rules, build, walkthrough regression, i18n
npm run build # generates _site/ (interactive pages + WeChat previews + board PNGs)
python3 -m http.server 8000 --directory _siteOpen http://localhost:8000. There is no bundler and no dev server — edit code and refresh.
- Add one file
content/YYYY-MM-DD-topic.json(copy the structure of an existing lesson, with both Chinese and English copy). - Run
npm test— the validator checks schema, FEN, move legality (including opponent replies), odds normalization, quick-question pairing and prerequisite dead links. - Run
npm run buildand play through every step locally. - Commit and push; GitHub Actions deploys automatically.
Full field reference in the Development Guide.
- Vanilla HTML / CSS / JavaScript (ES Modules) — no framework, no bundler
- Node.js scripts for validation and build (
node:testrunner) - chess.js — build-time chess rule validation
- pngjs — static board PNG composition for WeChat
- A small in-house rules engine (
assets/chess-engine.mjs) — browser-side move legality, check and checkmate - GitHub Actions + GitHub Pages deployment
| Document | Description |
|---|---|
| Usage Guide | How to use lessons, the AI coach and language switching |
| Configuration | AI coach providers and keys, build-time environment variables |
| Development Guide | Directory layout, tests, build, full authoring workflow |
| Architecture | Data flow, frontend modules, determinism boundaries |
| Deployment | GitHub Pages and release flow |
| Troubleshooting | Diagnosing common issues |
| Privacy | How data is handled and what leaves the browser |
| FAQ | Frequently asked questions |
Design documents for major features (background, goals, non-goals, compatibility) are indexed in Feature Documentation.
- Changelog: CHANGELOG.md（中文：CHANGELOG.zh.md）
- Roadmap: see
doc/ROADMAP.md(next: learning paths, engine evaluation, automated production)
Found a mistake in a lesson or a bug on the page? Use the in-page "Report" button (opens an email) or open an issue. There is no formal contribution process yet — issues are welcome.
No open-source license has been chosen yet. Until one is added, all rights are reserved by the author.