cm-chessboard 8.10.0 → 8.11.0

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,207 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+cm-chessboard is a lightweight, dependency-free JavaScript chessboard library. It's ES6 module-based, responsive, SVG-rendered, and used in production on chessmail.eu/chessmail.de.
+
+**Key Philosophy:** The core is intentionally minimal. Functionality is extended through an extension system rather than adding features to the core.
+
+## Development Commands
+
+### Running Tests
+
+```bash
+# Tests use the Teevi framework and must be run in a browser
+# Open test/index.html directly to run the test suite
+```
+
+### No Build Step
+This project has no build process. It uses native ES6 modules that run directly in modern browsers.
+
+## Architecture
+
+### Core Components (MVC Pattern)
+
+The codebase follows a clean MVC architecture:
+
+1. **Model Layer** (`src/model/`)
+   - `Position.js` - Board state representation using FEN notation. Contains 64-square array and FEN parsing/serialization
+   - `ChessboardState.js` - Manages application state (orientation, input flags, extension points)
+   - `Extension.js` - Base class for all extensions. Defines EXTENSION_POINT constants
+
+2. **View Layer** (`src/view/`)
+   - `ChessboardView.js` - SVG rendering, board drawing, piece rendering, coordinate display
+   - `VisualMoveInput.js` - Handles user interaction (drag & drop, click to move)
+   - `PositionAnimationsQueue.js` - Queues and executes piece animations
+
+3. **Controller** (`src/Chessboard.js`)
+   - Main API class that coordinates model and view
+   - Entry point for all public methods
+   - Instantiates extensions from props
+
+4. **Utilities** (`src/lib/`)
+   - `Svg.js` - SVG DOM manipulation helpers
+   - `Utils.js` - General utilities (URL handling, object merging)
+
+### Data Flow
+
+1. User calls API method on `Chessboard` instance
+2. `Chessboard` updates `Position` in `ChessboardState`
+3. Extension points are invoked via `state.invokeExtensionPoints()`
+4. Animation is queued in `PositionAnimationsQueue`
+5. `ChessboardView` renders the changes to SVG
+
+### Extension System
+
+Extensions are the primary way to add functionality. They:
+- Extend the `Extension` base class
+- Register callbacks at extension points using `registerExtensionPoint(EXTENSION_POINT.*, callback)`
+- Can add methods directly to the chessboard instance (e.g., `chessboard.addMarker = this.addMarker.bind(this)`)
+
+**Available Extension Points** (defined in `Extension.js`):
+- `positionChanged` - Piece positions changed
+- `boardChanged` - Board orientation changed
+- `boardResized` - Board was resized
+- `moveInputToggled` - Move input enabled/disabled
+- `moveInput` - Move events (started, validating, canceled, finished)
+- `beforeRedrawBoard` / `afterRedrawBoard` - Board redraw lifecycle
+- `animation` - Animation lifecycle hooks
+- `destroy` - Cleanup before board destruction
+
+**Included Extensions** (`src/extensions/`):
+- `markers/` - Visual markers on squares (frames, circles, dots)
+- `arrows/` - Drawing arrows between squares
+- `right-click-annotator/` - Right-click UI for annotations (uses markers + arrows)
+- `accessibility/` - Screen reader support, braille notation, keyboard input
+- `promotion-dialog/` - UI dialog for pawn promotion
+- `persistence/` - Save/restore board state to localStorage
+- `html-layer/` - Overlay HTML content on the board
+- `auto-border-none/` - Utility extension
+
+## Important Implementation Details
+
+### Coordinate System
+- Squares are represented as strings: "a1", "h8", etc.
+- Internally uses 0-63 index (Position.squareToIndex / indexToSquare)
+- Orientation affects rendering but not internal representation
+
+### FEN Handling
+- Position class only stores the piece placement (first part of full FEN)
+- Full FEN format is supported in setPosition() but only piece positions are stored
+- Use `FEN.start` and `FEN.empty` constants
+
+### Piece Naming
+- Format: `{color}{type}` - e.g., "wp" (white pawn), "bk" (black king)
+- Color: "w" or "b"
+- Type: "p", "n", "b", "r", "q", "k"
+
+### SVG Rendering
+- Pieces are rendered from SVG sprites (40x40px tiles)
+- Sprite can be cached in a hidden div for performance
+- Board uses multiple SVG groups as layers (board, coordinates, markers, pieces, etc.)
+- Responsive sizing via ResizeObserver or window resize events
+
+### Move Input System
+- Implemented in `VisualMoveInput.js`
+- Supports both drag-and-drop and click-to-move
+- Callback receives event objects with types from `INPUT_EVENT_TYPE`
+- Returns true/false to validate moves
+- Move input can be enabled per color (white/black/both)
+
+### Animation Queue
+- All position changes are queued to prevent conflicts
+- Animations return Promises that resolve when complete
+- Queue ensures sequential execution even with rapid API calls
+
+## Writing Extensions
+
+Template for a new extension:
+
+```javascript
+import {Extension, EXTENSION_POINT} from "../../model/Extension.js"
+
+export class MyExtension extends Extension {
+    constructor(chessboard, props = {}) {
+        super(chessboard)
+
+        // Set default props
+        this.props = {
+            myOption: true
+        }
+        Object.assign(this.props, props)
+
+        // Register extension points
+        this.registerExtensionPoint(EXTENSION_POINT.positionChanged, (data) => {
+            // React to position changes
+        })
+
+        // Add methods to chessboard instance
+        chessboard.myMethod = this.myMethod.bind(this)
+    }
+
+    myMethod() {
+        // Implementation
+    }
+}
+```
+
+Enable extension in chessboard props:
+```javascript
+extensions: [{class: MyExtension, props: {myOption: false}}]
+```
+
+## Common Patterns
+
+### Adding a piece
+```javascript
+board.setPiece("e4", "wn", true) // animated
+```
+
+### Moving pieces
+```javascript
+board.movePiece("e2", "e4", true) // animated
+```
+
+### Setting entire position
+```javascript
+board.setPosition(FEN.start, true) // animated
+```
+
+### Enabling move input
+```javascript
+board.enableMoveInput((event) => {
+    if (event.type === INPUT_EVENT_TYPE.validateMoveInput) {
+        // Validate the move
+        return isLegalMove(event.squareFrom, event.squareTo)
+    }
+}, COLOR.white) // Optional: restrict to one side
+```
+
+### Creating markers (requires Markers extension)
+```javascript
+board.addMarker(MARKER_TYPE.dot, "e4")
+board.removeMarkers(MARKER_TYPE.frame) // Remove by type
+board.removeMarkers() // Remove all
+```
+
+## Assets Structure
+
+- `assets/pieces/` - SVG sprite files for piece sets (standard.svg, staunty.svg)
+- `assets/extensions/` - Assets needed by extensions (markers SVG, arrow SVG, etc.)
+- `assets/chessboard.css` - Core styles
+- Extension-specific CSS must be included separately when using extensions
+
+## Examples
+
+The `examples/` directory contains working examples demonstrating:
+- Simple board creation
+- Move input and validation
+- Different visual styles
+- All included extensions
+- Animation examples
+- Responsive boards
+- Multiple boards on one page
+
+Reference examples when implementing new features or debugging issues.

package/README.md

@@ -15,12 +15,13 @@ in [chess-console](https://shaack.com/projekte/chess-console/examples/load-pgn.h
 - Uses SVG for rendering
 - [Allows adding extensions to extend the
 functionality](https://shaack.com/projekte/cm-chessboard/examples/extensions/arrows-extension.html)
+- [Supports chess960 (Freestyle) castling input](https://shaack.com/projekte/cm-chessboard/examples/validate-moves-chess960.html)
 
 ## Extensions
 
-The core of cm-chessboard is small, fast and reduced to the essentials. You can easily extend its functionality with extensions.
+The core of cm-chessboard is small, fast and reduced to the essentials. You can extend its functionality with extensions.
 
-- [RightClickAnnotator](https://shaack.com/projekte/cm-chessboard/examples/extensions/right-click-annotator.html) ⇨ Uses [Markers Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/markers-extension.html) and [Arrows Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/arrows-extension.html) and adds the handling mouse events to draw them on the board.
+- [RightClickAnnotator](https://shaack.com/projekte/cm-chessboard/examples/extensions/right-click-annotator.html) ⇨ Uses [Markers Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/markers-extension.html) and [Arrows Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/arrows-extension.html). Adds the handling of mouse events to draw them on the board.
   - [Markers Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/markers-extension.html) ⇨ create markers on specific squares
   - [Arrows Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/arrows-extension.html) ⇨ renders arrows on the chessboard
 - [Accessibility Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/accessibility-extension.html) ⇨ makes the chessboard more accessible

package/examples/validate-moves-chess960.html

@@ -0,0 +1,121 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>cm-chessboard</title>
+    <meta name="viewport" content="width=device-width, user-scalable=yes, initial-scale=1.0"/>
+    <link rel="stylesheet" href="styles/examples.css"/>
+    <link rel="stylesheet" href="../assets/chessboard.css"/>
+    <link rel="stylesheet" href="../assets/extensions/markers/markers.css"/>
+    <link rel="stylesheet" href="../assets/extensions/arrows/arrows.css"/>
+    <link rel="stylesheet" href="../assets/extensions/promotion-dialog/promotion-dialog.css"/>
+</head>
+<body>
+<h1><a href="../">cm-chessboard</a></h1>
+<h2>Example: Input enabled with move validation and promotion dialog</h2>
+<p>Input enabled for white. <a href="https://github.com/jhlywa/chess.js">chess.js</a> does the validation and answers
+    with random moves.</p>
+<div class="board board-large" id="board"></div>
+<div id="output"></div>
+
+<script type="module">
+    import {INPUT_EVENT_TYPE, COLOR, Chessboard, BORDER_TYPE} from "../src/Chessboard.js"
+    import {MARKER_TYPE, Markers} from "../src/extensions/markers/Markers.js"
+    import {PROMOTION_DIALOG_RESULT_TYPE, PromotionDialog} from "../src/extensions/promotion-dialog/PromotionDialog.js"
+    import {Accessibility} from "../src/extensions/accessibility/Accessibility.js"
+    import {Chess} from "https://cdn.jsdelivr.net/npm/chess.mjs@2/src/Chess.js"
+    import {RightClickAnnotator} from "../src/extensions/right-click-annotator/RightClickAnnotator.js"
+
+    const chess = new Chess("bnrqnkrb/pppppppp/8/8/8/8/PPPPPPPP/BNRQNKRB w KQkq - 0 1", {chess960: true})
+
+    let seed = 71
+
+    function random() {
+        const x = Math.sin(seed++) * 10000
+        return x - Math.floor(x)
+    }
+
+    function makeEngineMove(chessboard) {
+        const possibleMoves = chess.moves({verbose: true})
+        if (possibleMoves.length > 0) {
+            const randomIndex = Math.floor(random() * possibleMoves.length)
+            const randomMove = possibleMoves[randomIndex]
+            setTimeout(() => { // smoother with 500ms delay
+                chess.move({from: randomMove.from, to: randomMove.to})
+                chessboard.setPosition(chess.fen(), true)
+                chessboard.enableMoveInput(inputHandler, COLOR.white)
+            }, 500)
+        }
+    }
+
+    function inputHandler(event) {
+        console.log("inputHandler", event)
+        if (event.type === INPUT_EVENT_TYPE.movingOverSquare) {
+            return // ignore this event
+        }
+        if (event.type !== INPUT_EVENT_TYPE.moveInputFinished) {
+            event.chessboard.removeLegalMovesMarkers()
+        }
+        if (event.type === INPUT_EVENT_TYPE.moveInputStarted) {
+            // mark legal moves
+            const moves = chess.moves({square: event.squareFrom, verbose: true})
+            event.chessboard.addLegalMovesMarkers(moves)
+            return moves.length > 0
+        } else if (event.type === INPUT_EVENT_TYPE.validateMoveInput) {
+            const move = {from: event.squareFrom, to: event.squareTo, promotion: event.promotion}
+            const result = chess.move(move)
+            if (result) {
+                event.chessboard.state.moveInputProcess.then(() => { // wait for the move input process has finished
+                    event.chessboard.setPosition(chess.fen(), true).then(() => { // update position, maybe castled and wait for animation has finished
+                        makeEngineMove(event.chessboard)
+                    })
+                })
+            } else {
+                // promotion?
+                let possibleMoves = chess.moves({square: event.squareFrom, verbose: true})
+                for (const possibleMove of possibleMoves) {
+                    if (possibleMove.promotion && possibleMove.to === event.squareTo) {
+                        event.chessboard.showPromotionDialog(event.squareTo, COLOR.white, (result) => {
+                            console.log("promotion result", result)
+                            if (result.type === PROMOTION_DIALOG_RESULT_TYPE.pieceSelected) {
+                                chess.move({
+                                    from: event.squareFrom,
+                                    to: event.squareTo,
+                                    promotion: result.piece.charAt(1)
+                                })
+                                event.chessboard.setPosition(chess.fen(), true)
+                                makeEngineMove(event.chessboard)
+                            } else {
+                                // promotion canceled
+                                event.chessboard.enableMoveInput(inputHandler, COLOR.white)
+                                event.chessboard.setPosition(chess.fen(), true)
+                            }
+                        })
+                        return true
+                    }
+                }
+            }
+            return result
+        } else if (event.type === INPUT_EVENT_TYPE.moveInputFinished) {
+            if (event.legalMove) {
+                event.chessboard.disableMoveInput()
+            }
+        }
+    }
+
+    const board = new Chessboard(document.getElementById("board"), {
+        position: chess.fen(),
+        assetsUrl: "../assets/",
+        style: {borderType: BORDER_TYPE.none, pieces: {file: "pieces/staunty.svg"}, animationDuration: 300},
+        orientation: COLOR.white,
+        extensions: [
+            {class: Markers, props: {autoMarkers: MARKER_TYPE.square}},
+            {class: RightClickAnnotator},
+            {class: PromotionDialog},
+            {class: Accessibility, props: {visuallyHidden: true}}
+        ]
+    })
+    board.enableMoveInput(inputHandler, COLOR.white)
+</script>
+</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cm-chessboard",
-  "version": "8.10.0",
+  "version": "8.11.0",
   "description": "A JavaScript chessboard which is lightweight, ES6 module based, responsive, SVG rendered and without dependencies.",
   "keywords": [
     "chess",

package/src/view/VisualMoveInput.js

@@ -286,16 +286,20 @@ export class VisualMoveInput {
                     const startPieceName = this.chessboard.getPiece(this.fromSquare)
                     const startPieceColor = startPieceName ? startPieceName.substring(0, 1) : null
                     if (color && startPieceColor === pieceColor) {
-                        this.moveInputCanceledCallback(this.fromSquare, square, MOVE_CANCELED_REASON.clickedAnotherPiece)
-                        if (this.moveInputStartedCallback(square)) {
-                            this.setMoveInputState(MOVE_INPUT_STATE.pieceClickedThreshold, {
-                                square: square,
-                                piece: pieceName,
-                                point: point,
-                                type: e.type
-                            })
-                        } else {
-                            this.setMoveInputState(MOVE_INPUT_STATE.reset)
+                        // added to allow chess960 castling
+                        const result = this.validateMoveInputCallback(this.fromSquare, square)
+                        if(!result) {
+                            this.moveInputCanceledCallback(this.fromSquare, square, MOVE_CANCELED_REASON.clickedAnotherPiece)
+                            if (this.moveInputStartedCallback(square)) {
+                                this.setMoveInputState(MOVE_INPUT_STATE.pieceClickedThreshold, {
+                                    square: square,
+                                    piece: pieceName,
+                                    point: point,
+                                    type: e.type
+                                })
+                            } else {
+                                this.setMoveInputState(MOVE_INPUT_STATE.reset)
+                            }
                         }
                     } else {
                         this.setMoveInputState(MOVE_INPUT_STATE.moveDone, {square: square})