The tutor was recommending incorrect moves in family mode because
theoreticalAlternatives were only provided when currentFeedback existed.
In family mode, the tutor needs access to all possible theoretical moves
from the variation tree at all times, not just after a move is played.
Changes:
- Modified currentFeedback in openingPracticeMode to always provide
theoreticalMoves in family mode, even when no feedback exists yet
- Added comprehensive tests for French Defense family mode
- Added tests for opening loader functionality
- Fixed missing timestamp property in test fixtures
This fixes the issue where asking the tutor how do I play French Defense?
at the start would result in wrong move recommendations.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Added UNDO_TO_MOVE action that both navigates AND truncates history
- Added undoToMove() function to OpeningTrainingContext
- Updated handleUndoDeviation to use undoToMove instead of navigate
Previously, the Undo button only navigated back but didn't remove
the deviation moves, so the session remained in off-book state.
Created 21 test cases covering:
- Variation tree building
- Position navigation
- Move validation across variations
- Branch point detection
- End of line detection
All tests pass (21/21).
The variationPositionInfo and theoreticalMoves useMemo hooks were called
after conditional early returns, violating React's Rules of Hooks.
Moved both hooks to be called unconditionally before any early returns.
Added null checks inside the hooks to handle missing session/tree safely.
- Add missing 'src' property to OpeningMetadata test fixtures
- Add missing 'id' and 'description' properties to Personality test fixtures
- Add missing 'isPlayerWhite' property to EvaluationBar test cases
All tests now pass TypeScript validation. No changes to production code.
When a user makes an incorrect move, they can now immediately try again
without clicking Try Again. The wrong move is undone, error sound plays,
and the user can make another attempt right away.
Changes:
- Remove setFeedback(incorrect) on wrong moves
- Remove handleTryAgain function (no longer needed)
- Simplify button logic: Show Next when correct, Skip otherwise
- Skip button now always visible during puzzle solving
This matches Chess.com UX where incorrect moves just play a sound
and let you retry instantly.
- Add family training mode where users select an opening family (e.g. "Italian Game")
and can play any variation within that family
- Create variation tree data structure to efficiently track which variations
match the current move sequence
- FamilySelector now navigates directly to /learning/openings/family/[familyName]
instead of showing a second selector for individual variations
- OpeningTrainer displays matching variations, possible moves, and current line
- LLM tutor explains which variation is being played and mentions alternatives
- Remove the OpeningSelector step from the flow for a simpler UX
The new flow:
1. User selects an opening family (e.g. "Sicilian Defense")
2. Training starts immediately with all variations loaded
3. User can play any move that exists in any variation
4. The UI shows which variations are still possible
5. The AI tutor guides the user through the repertoire
When a user makes an incorrect move in a puzzle, now only that move
is undone (like chess.com) instead of resetting the entire puzzle.
This improves usability by letting users retry from the same position
rather than having to redo all previous correct moves.
- Add 30s timeout to Stockfish evaluation to prevent hanging promises
- Add FEN validation and depth cap (max 30) to Stockfish API route
- Create ErrorBoundary component with specialized fallbacks for chess game and tutor
- Extract useChessSounds hook for better audio management
- Add React.memo to EvaluationBar and CapturedPieces for performance
- Add useMemo to CapturedPieces for sorted pieces calculation
- Improve tacticDetection to return empty array instead of "none" type
- Add filterMeaningfulTactics and hasTactics helper functions
- Translate hardcoded UI strings (stockfishLevel, download, evalChange)
- Update translations for EN, DE, FR, IT, PL
- Add uuid to Jest transformIgnorePatterns for ESM compatibility
- Update tests to use new filterMeaningfulTactics function
- Added wikipediaSlug field to 8,698 openings across all ECO files
- Rebuilt moveIndex.json with Wikipedia slug references
- Updated docker-entrypoint.sh to rebuild index after slug updates
This enables Wikipedia summaries for openings like:
- King's Gambit (king-s-gambit)
- Ruy Lopez (ruy-lopez)
- And 65 other opening families
The Wikipedia integration provides historical context and strategic
explanations for openings during training sessions.
- Update .gitignore to allow moveIndex.json (needed at build time)
- Exclude only eco*.json files (too large for git)
- Add uuid package dependency for sessionManager
Fixes:
- Next.js build error: Module not found moveIndex.json
- Build error: Module not found uuid
- Create CHANGELOG.md documenting v1.1.0 release
- Update README with opening training mode details
- Update README with tactical practice mode details
- Reorganize README into learning modes section
- Add mobile app information
- Maintain dual licensing documentation
Key additions:
- Opening Training: 12,379 openings with AI guidance
- Tactical Practice: 8 patterns with 20+ puzzles each
- Enhanced game mode with opening context awareness
- Mobile support via Capacitor
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Restore all 12,379 openings from commit 8ed402b
- Rebuild move index with 12,377 sequences
- Fix merge issue that overwrote with test fixtures
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Update jest.config.ts for new test structure
- Update playwright.config.ts for e2e test setup
- Update opening database files (12,379 entries)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add tutor message guardrail to prevent rapid-fire messages
- Track last message by move index
- Wait for both player and opponent moves before speaking
- Speak immediately when player deviates from theory
- Add deviation dialog with three options:
- Continue Playing (Start Game) - transitions to game mode
- Undo & Return to Opening - returns to theory
- Explore This Variation - continues off-book practice
- Implement smooth game mode transition:
- Pass opening context from trainer to game
- Tutor welcomes player with context about their study
- Computer makes first move if needed in starting position
- Fix generate-test-fixtures script:
- Add safety check to prevent overwriting real data
- Restore full opening database (12,379 openings)
- Rebuild move index (12,377 sequences)
- Add clear warnings about test fixtures
- Update ChessGame to accept openingContext prop
- Update Tutor to display contextual greeting in game mode
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Make it explicit why dual licensing is NECESSARY (not optional):
- App Store and Google Play terms are incompatible with GPL-3.0
- FSF considers App Store distribution a GPL violation
- Mobile builds must exclude GPL code for platform compliance
Also clarify:
- Only copyright holder (KaProblem) can distribute proprietary mobile apps
- Third parties cannot distribute GPL apps on app stores (platform restrictions)
- Third parties cannot create proprietary versions from this code
- Contributors grant dual licensing rights for App Store compliance
Updates:
- Add 'Why Dual Licensing?' section explaining App Store restrictions
- Update copyright holder to KaProblem (https://www.kaproblem.com)
- Add App Store compliance context throughout documentation
- Clarify that this protects copyright holder's exclusive distribution rights
This prevents:
- Third parties from releasing proprietary mobile apps
- Confusion about why dual licensing exists
- GPL violations on app stores
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit implements iOS/Android mobile app support using Capacitor
and adds a comprehensive opening training feature with LLM-powered
explanations.
## Mobile App Infrastructure
- Add Capacitor configuration for iOS/Android builds
- Create mobile build script that excludes API routes
- Update Next.js config for conditional static export
- Add layout components with generateStaticParams for static builds
- Generate 500+ static pages for offline mobile use
## Chess Engine Abstraction
- Create ChessEngine interface for pluggable implementations
- Add LocalEngine (GPL - uses stockfish.js in browser)
- Add RemoteEngine (proprietary - calls API server)
- Factory pattern selects engine based on environment
- Enables GPL compliance for web, proprietary for mobile
## Opening Training Feature
- Interactive opening repertoire training
- Move validation with engine-backed feedback
- LLM explanations using Gemini API
- Wikipedia integration for opening context
- Opening family grouping (e4, d4, c4, etc.)
- Session state management
- Real-time move feedback with evaluation
Components:
- OpeningSelector: Browse and select openings by family
- OpeningTrainer: Main training interface with chessboard
- MoveFeedback: Display move quality and LLM explanations
- WikipediaSummary: Show opening history and context
- ErrorBoundary: Graceful error handling
Services:
- openingLoader: Load and filter opening database
- engineService: Engine evaluation wrapper
- moveValidator: Validate moves against repertoire
- feedbackGenerator: Generate contextual feedback
- wikipediaService: Fetch and cache Wikipedia data
- sessionManager: Track training session state
## Wikipedia Integration
- Automatic Wikipedia article fetching for openings
- Client-side and server-side caching
- Sanitized summaries with proper formatting
- Link opening database to Wikipedia slugs
- API endpoints for on-demand fetching
## Docker Improvements
- Add entrypoint script for automatic data setup
- Fetch Wikipedia data on first container startup
- Generate opening move index automatically
- Remove generated data from git (public/openings/*.json, public/wikipedia/*.json)
- Add READMEs explaining data requirements
- Update .gitignore for generated files
## Dual Licensing Strategy
- Add LICENSING.md explaining dual licensing approach
- GPL-3.0 for web builds (includes Stockfish)
- Proprietary option for mobile builds (no GPL code)
- Single codebase, multiple licensing models
- Legal compliance documented
## API Endpoints
- POST /api/v1/llm/opening-explanation - Get LLM move explanations
- GET /api/v1/wikipedia/summary - Fetch Wikipedia summaries
## Type Updates
- Add openingTraining types
- Update Tutor component to use ChessEngine interface
- Add Gemini error handling types
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add comprehensive API documentation section
- Document Stockfish evaluation endpoint (POST /api/v1/stockfish)
- Document LLM chat endpoint (POST /api/v1/llm/chat)
- Document personalities endpoint (GET /api/v1/personalities)
- Include request/response examples and usage with curl
- Link to detailed API docs in docs/ folder
- No mention of specific use cases, just general API availability
- Replace window.confirm() with a custom styled modal dialog
- Match existing modal styling (header, content, footer pattern)
- Add Flag icon and AlertTriangle warning icon
- Use localized Cancel button text from common translations
- Improved UX with X close button and proper button styling
- Add window.confirm() before resigning to prevent accidental resignation
- Add 'resignConfirm' translation key in all 5 languages (EN, DE, FR, IT, PL)
- Messages are localized and warn that the action cannot be undone
- Fix page.test.tsx: Use stable mock router reference to prevent infinite loop
The useRouter mock was returning a new object on every render, causing
the useEffect with router dependency to re-run infinitely
- Update README to document resign button and analyze game features
- Add Polish language to multi-language support
- Document game export feature (PGN/FEN download)
- Add saved games and game continuation feature
- Document settings management and Clear All Data feature
- Add comprehensive User Experience Features section covering:
- Game management (save/resume/export)
- Customization options (languages, personalities, colors)
- Analysis tools (evaluation bar, opening explorer, position analysis)
- Modern interface features (responsive design, dark mode)
- Update typical game flow to include new features
- Improve feature descriptions with more detail
- Add download button to game history section with modal
- Support downloading game as PGN or current position as FEN
- Add translations for download feature in all 5 languages (EN, DE, FR, IT, PL)
- Fix bug where first moves were missing from history: now wait for evalP0 (pre-analysis) before allowing player moves
- This ensures all moves are properly tracked with evaluations and tactics detection
- Add 'Clear All Data' button in Danger Zone section
- Implement confirmation dialog before clearing
- Clear all localStorage and redirect to onboarding
- Add translations for clearAllData, clearAllDataConfirm, and clearAllDataDescription in all 5 languages (EN, DE, FR, IT, PL)
- Style with red theme to indicate destructive action
- Reorganize StartScreen: Start New Game button always visible at top
- Move unfinished games section below the start button
- Remove '2.' prefix from startGame translations (all languages)
- Update startNewGame translations to be button-appropriate
- Fix TypeScript errors: Update GameImportModal, GameAnalysisModal, and GameOverModal to use SupportedLanguage type instead of hardcoded language union
- Delete local branches: codex/add-polish-as-ui-language and codex/add-option-to-continue-game-from-position
Added comprehensive documentation for the debug mode feature including:
- Environment variable configuration (NEXT_PUBLIC_DEBUG)
- What debug mode shows (prompts, responses, timestamps)
- How to use the debug panel (copy, clear, expand)
- Why it's useful (troubleshooting, learning, bug reports)
- Example use cases (verify positions, check evaluations, etc.)
- Warning about production usage
This helps users understand how to enable and use debug mode to
troubleshoot AI behavior and understand how the system works.
When Stockfish detects a forced mate, it sets the mate field and resets
the score to 0. The previous code was showing '0 cp' which was misleading.
Changes:
- Format evaluation strings to show 'Mate in X' when mate is detected
- Only show delta (centipawn change) when neither position has a mate
- Update eval instruction to specifically mention mate situations
- Add explanation of mate notation in the prompt
Example output now:
- Pre-Eval: -326 cp
- Post-Eval: Mate in 3
(instead of showing '0 cp' which was confusing)
Stefan