cm-chessboard 8.12.17 → 8.12.19

package/README.md

@@ -207,9 +207,13 @@ The event has the following **`event.type`**:
   Return `true` or `false` to validate the start square. `false` cancels the move.
 - **`INPUT_EVENT_TYPE.validateMoveInput`**: To validate the users move input. `event.squareFrom` and `event.squareTo`
   contain the coordinates. Return `true` or `false` to validate the move. `false` cancels the move.
-  `event.probe` is `true` when the target square still holds one of the mover's own pieces (e.g. clicking another own
-  piece, or a chess960 castling target). A falsy result then means "re-select that piece" rather than an illegal move,
-  so you can suppress illegal-move feedback when `event.probe` is set.
+  The validator runs once at most per sequence of actions that describe a move (e.g. click starting piece, click destination),
+  so side effects like updating game position state or triggering sounds can run here.
+  One special case is moving a piece to a square occupied by another friendly piece. This kind of move can be useful
+  when you want to allow chess960 castling style (moving the king into the rook position) or when you want to allow
+  recapture premoves. Return `true` to commit it (e.g. castling by clicking the rook). When you return `false` here the
+  clicked own piece simply becomes the new selection, so if you show illegal-move feedback, skip it when `event.squareTo`
+  still holds one of the mover's own pieces.
 - **`INPUT_EVENT_TYPE.moveInputCanceled`**: The user canceled the move with clicking again on the start square, clicking
   outside the board or right click.
 - **`INPUT_EVENT_TYPE.moveInputFinished`**: Fired after the move was made, also when canceled.
@@ -243,6 +247,12 @@ chessboard.enableMoveInput((event) => {
 
 Disables moves via user input.
 
+### cancelMoveInput()
+
+Cancels a move input that is currently in progress (a piece picked up or a square selected), without disabling move
+input. Fires a `moveInputCanceled` event with `event.reason === "canceled"`. It is a no-op when no move input is in
+progress. Useful to abort a move from your own UI, e.g. on an "escape" key press or a cancel button.
+
 ### isMoveInputEnabled()
 
 Returns `true` if move input is currently enabled for white or black.
@@ -419,6 +429,17 @@ const chessboard = new Chessboard(document.getElementById("board"), {
 
 When `movePieceForm` is enabled, press **Shift+Option+E** (Mac) or **Shift+Alt+E** (Windows/Linux) to focus the "Move from" input field.
 
+## Testing
+
+The unit tests use the tiny [Teevi](https://github.com/shaack/teevi) framework and run in a real browser.
+
+- **In the browser (no install needed):** open [`test/index.html`](test/index.html) directly, or run `npm test`, which
+  just prints that hint.
+- **Headless (optional):** `npm run test:headless` runs the same suite in headless Chrome and exits non-zero on failure,
+  which is handy for CI. To keep cm-chessboard dependency-free, [puppeteer](https://pptr.dev) is **not** a project
+  dependency; install it **globally** for this: `npm install -g puppeteer`. The runner starts its own static server, so
+  nothing else is required.
+
 ## Usage with JS Frameworks
 
 - Works with **Vue** out of the box

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cm-chessboard",
-  "version": "8.12.17",
+  "version": "8.12.19",
   "description": "A JavaScript chessboard which is lightweight, ES6 module based, responsive, SVG rendered and without dependencies.",
   "keywords": [
     "chess",
@@ -16,7 +16,8 @@
   "module": "./src/Chessboard.js",
   "browser": "./src/Chessboard.js",
   "scripts": {
-    "test": "tput setaf 4;echo 'Run test/index.html in your browser for unit testing.'; echo ''; exit 0"
+    "test": "tput setaf 4;echo 'Run test/index.html in your browser for unit testing, or `npm run test:headless` (needs a global puppeteer).'; echo ''; exit 0",
+    "test:headless": "node test/headless.mjs"
   },
   "repository": {
     "type": "git",

package/src/Chessboard.js

@@ -77,6 +77,7 @@ export class Chessboard {
     async setPiece(square, piece, animated = false) {
         const positionFrom = this.state.position.clone()
         this.state.position.setPiece(square, piece)
+        this.view.visualMoveInput.positionChanged()
         this.state.invokeExtensionPoints(EXTENSION_POINT.positionChanged)
         return this.positionAnimationsQueue.enqueuePositionChange(positionFrom, this.state.position.clone(), animated)
     }
@@ -84,6 +85,7 @@ export class Chessboard {
     async movePiece(squareFrom, squareTo, animated = false) {
         const positionFrom = this.state.position.clone()
         this.state.position.movePiece(squareFrom, squareTo)
+        this.view.visualMoveInput.positionChanged()
         this.state.invokeExtensionPoints(EXTENSION_POINT.positionChanged)
         return this.positionAnimationsQueue.enqueuePositionChange(positionFrom, this.state.position.clone(), animated)
     }
@@ -93,6 +95,7 @@ export class Chessboard {
         const positionTo = new Position(fen)
         if (positionFrom.getFen() !== positionTo.getFen()) {
             this.state.position.setFen(fen)
+            this.view.visualMoveInput.positionChanged()
             this.state.invokeExtensionPoints(EXTENSION_POINT.positionChanged)
         }
         return this.positionAnimationsQueue.enqueuePositionChange(positionFrom, this.state.position.clone(), animated)
@@ -131,6 +134,11 @@ export class Chessboard {
         this.view.disableMoveInput()
     }
 
+    // Cancel a move input that is currently in progress (leaves move input enabled).
+    cancelMoveInput() {
+        this.view.visualMoveInput.cancelMoveInput()
+    }
+
     isMoveInputEnabled() {
         return this.state.inputWhiteEnabled || this.state.inputBlackEnabled
     }

package/src/view/ChessboardView.js

@@ -410,18 +410,13 @@ export class ChessboardView {
         this.chessboard.state.invokeExtensionPoints(EXTENSION_POINT.moveInput, data)
     }
 
-    validateMoveInputCallback(squareFrom, squareTo, probe = false) {
+    validateMoveInputCallback(squareFrom, squareTo) {
         const data = {
             chessboard: this.chessboard,
             type: INPUT_EVENT_TYPE.validateMoveInput,
             squareFrom: squareFrom,
             squareTo: squareTo,
-            piece: this.chessboard.getPiece(squareFrom),
-            // true when this is only a speculative check whether the clicked
-            // same-color piece is a legal target (e.g. chess960 castling). A
-            // falsy result then means "re-select this piece", not an illegal
-            // move, so consumers can suppress illegal-move feedback.
-            probe: probe
+            piece: this.chessboard.getPiece(squareFrom)
         }
         if (this.chessboard.state.moveInputCallback) {
             data.moveInputCallbackResult = this.chessboard.state.moveInputCallback(data)

package/src/view/VisualMoveInput.js

@@ -24,7 +24,9 @@ export const MOVE_CANCELED_REASON = {
     movedOutOfBoard: "movedOutOfBoard",
     draggedBack: "draggedBack", // dragged to the start square
     clickedAnotherPiece: "clickedAnotherPiece", // of the same color
-    touchCanceled: "touchCanceled"
+    touchCanceled: "touchCanceled",
+    movedPieceChanged: "movedPieceChanged", // the held piece changed on the board, most likely got captured
+    canceled: "canceled" // cancelled programmatically via chessboard.cancelMoveInput()
 }
 
 const DRAG_THRESHOLD = 4
@@ -37,6 +39,7 @@ export class VisualMoveInput {
         this.moveInputState = null
         this.fromSquare = null
         this.toSquare = null
+        this.movedPiece = null
 
         this.setMoveInputState(MOVE_INPUT_STATE.waitForInputStart)
     }
@@ -59,8 +62,8 @@ export class VisualMoveInput {
         this.view.movingOverSquareCallback(fromSquare, toSquare)
     }
 
-    validateMoveInputCallback(fromSquare, toSquare, probe = false) {
-        const result = this.view.validateMoveInputCallback(fromSquare, toSquare, probe)
+    validateMoveInputCallback(fromSquare, toSquare) {
+        const result = this.view.validateMoveInputCallback(fromSquare, toSquare)
         this.chessboard.state.moveInputProcess.resolve(result)
         return result
     }
@@ -171,7 +174,10 @@ export class VisualMoveInput {
                     throw new Error("moveInputState")
                 }
                 this.toSquare = params.square
-                if (this.toSquare && this.validateMoveInputCallback(this.fromSquare, this.toSquare)) {
+                // if the move was already validated, don't trigger the validator again so possible user side effects run once at most
+                const validated = params.validated !== undefined ? 
+                    params.validated : this.validateMoveInputCallback(this.fromSquare, this.toSquare)
+                if (this.toSquare && validated) {
                     this.chessboard.movePiece(this.fromSquare, this.toSquare, prevState === MOVE_INPUT_STATE.clickTo).then(() => {
                         if (prevState === MOVE_INPUT_STATE.clickTo) {
                             this.view.setPieceVisibility(this.toSquare, true)
@@ -298,11 +304,11 @@ export class VisualMoveInput {
                     const startPieceName = this.chessboard.getPiece(this.fromSquare)
                     const startPieceColor = startPieceName ? startPieceName.substring(0, 1) : null
                     if (color && startPieceColor === pieceColor) {
-                        // added to allow chess960 castling. This is only a probe:
-                        // a falsy result means the user re-selected another own
-                        // piece, not that an illegal move was attempted.
-                        const result = this.validateMoveInputCallback(this.fromSquare, square, true)
-                        if(!result) {
+                        // added to allow moves into own pieces, useful for chess960 castle style or recapture premoves
+                        // result holds false if the user legality checker deemed the move into another own piece as illegal
+                        // in that case, we start a new move by selecting the target piece
+                        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, {
@@ -314,6 +320,10 @@ export class VisualMoveInput {
                             } else {
                                 this.setMoveInputState(MOVE_INPUT_STATE.reset)
                             }
+                        } else {
+                            // if the user deemed the move into own piece legal, execute it
+                            // but prevent validating the move again with the validated flag
+                            this.setMoveInputState(MOVE_INPUT_STATE.moveDone, {square: square, validated: true})
                         }
                     } else {
                         this.setMoveInputState(MOVE_INPUT_STATE.moveDone, {square: square})
@@ -425,6 +435,40 @@ export class VisualMoveInput {
         this.moveInputCanceledCallback(this.fromSquare, null, MOVE_CANCELED_REASON.secondaryClick)
     }
 
+    // Cancel a move input that is currently in progress. No-op when idle.
+    cancelMoveInput() {
+        if (this.moveInputState !== MOVE_INPUT_STATE.waitForInputStart) {
+            const moveStartSquare = this.fromSquare
+            this.view.redrawPieces()
+            this.setMoveInputState(MOVE_INPUT_STATE.reset)
+            this.moveInputCanceledCallback(moveStartSquare, null, MOVE_CANCELED_REASON.canceled)
+        }
+    }
+
+    // Called after the board position changed (setPosition/movePiece/setPiece).
+    // If the piece we are holding changed on its square — most likely captured
+    // by an external position update — cancel the in-progress move input.
+    positionChanged() {
+        // Only cancel while actually holding a piece. Never in moveDone/reset:
+        // completing a move itself goes through movePiece() and must not self-cancel.
+        const holdingStates = [
+            MOVE_INPUT_STATE.pieceClickedThreshold,
+            MOVE_INPUT_STATE.clickTo,
+            MOVE_INPUT_STATE.secondClickThreshold,
+            MOVE_INPUT_STATE.dragTo,
+            MOVE_INPUT_STATE.clickDragTo
+        ]
+        if (this.fromSquare && holdingStates.includes(this.moveInputState) &&
+            this.chessboard.getPiece(this.fromSquare) !== this.movedPiece) {
+            const moveStartSquare = this.fromSquare
+            // drop the stale held piece so the reset branch does not stamp it
+            // back onto the square, overwriting the piece just placed there
+            this.movedPiece = null
+            this.setMoveInputState(MOVE_INPUT_STATE.reset)
+            this.moveInputCanceledCallback(moveStartSquare, null, MOVE_CANCELED_REASON.movedPieceChanged)
+        }
+    }
+
     isDragging() {
         return this.moveInputState === MOVE_INPUT_STATE.dragTo || this.moveInputState === MOVE_INPUT_STATE.clickDragTo
     }

package/test/TestArrows.js

@@ -0,0 +1,33 @@
+/**
+ * Author and copyright: Stefan Haack (https://shaack.com)
+ * Repository: https://github.com/shaack/cm-chessboard
+ * License: MIT, see file 'LICENSE'
+ */
+
+import {describe, it, assert} from "../node_modules/teevi/src/teevi.js"
+import {Chessboard} from "../src/Chessboard.js"
+import {ARROW_TYPE, Arrows} from "../src/extensions/arrows/Arrows.js"
+
+describe("TestArrows", () => {
+
+    it("should add, get and remove arrows", () => {
+        const chessboard = new Chessboard(document.getElementById("TestArrows"), {
+            assetsUrl: "../assets/",
+            extensions: [{class: Arrows}]
+        })
+        chessboard.addArrow(ARROW_TYPE.default, "e2", "e4")
+        chessboard.addArrow(ARROW_TYPE.danger, "d2", "d4")
+        assert.equal(chessboard.getArrows().length, 2)
+        assert.equal(chessboard.getArrows(ARROW_TYPE.danger).length, 1)
+        assert.equal(chessboard.getArrows(undefined, "e2").length, 1)
+        assert.equal(chessboard.getArrows(undefined, "e2", "e4").length, 1)
+        assert.equal(chessboard.getArrows(undefined, "a1").length, 0)
+        chessboard.removeArrows(undefined, "e2")
+        assert.equal(chessboard.getArrows().length, 1)
+        assert.equal(chessboard.getArrows()[0].from, "d2")
+        chessboard.removeArrows()
+        assert.equal(chessboard.getArrows().length, 0)
+        chessboard.destroy()
+    })
+
+})

package/test/TestChessboard.js

@@ -5,7 +5,7 @@
  */
 
 import {describe, it, assert} from "../node_modules/teevi/src/teevi.js"
-import {PIECE, Chessboard} from "../src/Chessboard.js"
+import {PIECE, COLOR, Chessboard} from "../src/Chessboard.js"
 import {FEN} from "../src/model/Position.js"
 
 describe("TestChessboard", () => {
@@ -69,6 +69,49 @@ describe("TestChessboard", () => {
         chessboard.destroy()
     })
 
+    it("should move a piece via the api", async () => {
+        const chessboard = new Chessboard(document.getElementById("TestBoard"), {
+            assetsUrl: "../assets/",
+            position: FEN.start,
+            style: {animationDuration: 0}
+        })
+        await chessboard.movePiece("e2", "e4", false)
+        assert.equal(chessboard.getPiece("e2"), null)
+        assert.equal(chessboard.getPiece("e4"), "wp")
+        chessboard.destroy()
+    })
+
+    it("should remove a piece when set to null", () => {
+        const chessboard = new Chessboard(document.getElementById("TestBoard"), {
+            assetsUrl: "../assets/",
+            position: FEN.start
+        })
+        chessboard.setPiece("e2", null)
+        assert.equal(chessboard.getPiece("e2"), null)
+        chessboard.destroy()
+    })
+
+    it("should create an empty board from FEN.empty", () => {
+        const chessboard = new Chessboard(document.getElementById("TestBoard"), {
+            assetsUrl: "../assets/",
+            position: FEN.empty
+        })
+        assert.equal("" + chessboard.getPosition(), "8/8/8/8/8/8/8/8")
+        chessboard.destroy()
+    })
+
+    it("should set and get the orientation", async () => {
+        const chessboard = new Chessboard(document.getElementById("TestBoard"), {
+            assetsUrl: "../assets/",
+            position: FEN.start,
+            style: {animationDuration: 0}
+        })
+        assert.equal(chessboard.getOrientation(), COLOR.white)
+        await chessboard.setOrientation(COLOR.black)
+        assert.equal(chessboard.getOrientation(), COLOR.black)
+        chessboard.destroy()
+    })
+
     // Regression for https://github.com/shaack/cm-chessboard/issues/154
     //
     // A setPosition() call with a null diff (positionFrom === positionTo)

package/test/TestMarkers.js

@@ -39,4 +39,19 @@ describe("TestMarkers", () => {
         chessboard.destroy()
     })
 
+    it("should add different marker types and remove all markers at once", () => {
+        const chessboard = new Chessboard(document.getElementById("TestMarkers"), {
+            assetsUrl: "../assets/",
+            extensions: [{class: Markers}]
+        })
+        chessboard.addMarker(MARKER_TYPE.dot, "e4")
+        chessboard.addMarker(MARKER_TYPE.circle, "d4")
+        chessboard.addMarker(MARKER_TYPE.circleDanger, "c4")
+        assert.equal(chessboard.getMarkers().length, 3)
+        assert.equal(chessboard.getMarkers(MARKER_TYPE.dot).length, 1)
+        chessboard.removeMarkers()
+        assert.equal(chessboard.getMarkers().length, 0)
+        chessboard.destroy()
+    })
+
 })

package/test/TestPosition.js

@@ -39,5 +39,41 @@ describe("TestPosition", () => {
         assert.equal(rooks.length, 1)
         assert.equal(rooks[0].square, "f5")
     })
+    it("should round-trip every square through index conversion", () => {
+        for (let i = 0; i < 64; i++) {
+            assert.equal(Position.squareToIndex(Position.indexToSquare(i)), i)
+        }
+    })
+    it("should set, get and remove a piece", () => {
+        const position = new Position(FEN.empty)
+        assert.equal(position.getPiece("e4"), null)
+        position.setPiece("e4", "wq")
+        assert.equal(position.getPiece("e4"), "wq")
+        position.setPiece("e4", null)
+        assert.equal(position.getPiece("e4"), null)
+    })
+    it("should move a piece", () => {
+        const position = new Position("8/8/8/8/8/8/4P3/8")
+        position.movePiece("e2", "e4")
+        assert.equal(position.getPiece("e2"), null)
+        assert.equal(position.getPiece("e4"), "wp")
+    })
+    it("should represent an empty board as FEN", () => {
+        const position = new Position(FEN.empty)
+        assert.equal(position.getFen(), "8/8/8/8/8/8/8/8")
+    })
+    it("should store only the piece placement of a full FEN", () => {
+        const position = new Position("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1")
+        assert.equal(position.getFen(), "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR")
+    })
+    it("should count the pieces of the start position", () => {
+        const position = new Position(FEN.start)
+        assert.equal(position.getPieces().length, 32)
+        assert.equal(position.getPieces(COLOR.white).length, 16)
+        assert.equal(position.getPieces(COLOR.black, PIECE_TYPE.pawn).length, 8)
+    })
+    it("should return no pieces for an empty board", () => {
+        assert.equal(new Position(FEN.empty).getPieces().length, 0)
+    })
 })
 

package/test/TestVisualMoveInput.js

@@ -7,11 +7,34 @@
 import {describe, it, assert} from "../node_modules/teevi/src/teevi.js"
 import {Chessboard} from "../src/Chessboard.js"
 import {COLOR, INPUT_EVENT_TYPE} from "../src/view/ChessboardView.js"
+import {MOVE_CANCELED_REASON} from "../src/view/VisualMoveInput.js"
 import {FEN} from "../src/model/Position.js"
 
 const STATE_WAIT_FOR_INPUT_START = "waitForInputStart"
 const STATE_PIECE_CLICKED_THRESHOLD = "pieceClickedThreshold"
 const STATE_CLICK_TO = "clickTo"
+const STATE_DRAG_TO = "dragTo"
+
+// Synthetic pointer events. The mouse path reads e.target / e.clientX directly,
+// so it drives the real state machine without needing document.elementFromPoint.
+const squareTarget = (name) => ({getAttribute: (n) => (n === "data-square" ? name : null)})
+const mouseDown = (name, x = 100, y = 100) => ({
+    type: "mousedown", button: 0, target: squareTarget(name),
+    clientX: x, clientY: y, preventDefault: () => {}
+})
+const mouseMove = (name, x, y) => ({
+    type: "mousemove", target: squareTarget(name), clientX: x, clientY: y, pageX: x, pageY: y
+})
+const mouseUp = (name) => ({type: "mouseup", target: squareTarget(name)})
+const tick = () => new Promise((resolve) => setTimeout(resolve, 30))
+
+function newBoard() {
+    return new Chessboard(document.getElementById("TestBoard"), {
+        assetsUrl: "../assets/",
+        position: FEN.start,
+        style: {animationDuration: 0}
+    })
+}
 
 describe("TestVisualMoveInput", () => {
 
@@ -39,39 +62,300 @@ describe("TestVisualMoveInput", () => {
         chessboard.destroy()
     })
 
-    it("should mark the same-color reselect validation as a probe", async () => {
+    // Regression for https://github.com/shaack/cm-chessboard/pull/174
+    it("should validate once and finish the move when moving into own piece is marked as valid", async () => {
         const chessboard = new Chessboard(document.getElementById("TestBoard"), {
             assetsUrl: "../assets/",
             position: FEN.start
         })
-        let probeSeen
+        let validateCallCount = 0
+        let moveInputFinishedCount = 0
         chessboard.enableMoveInput((event) => {
             if (event.type === INPUT_EVENT_TYPE.validateMoveInput) {
-                probeSeen = event.probe
-                return false // reject -> this is a re-selection, not a real move
+                validateCallCount++
+                return true // accept the castling-by-clicking-the-rook move
+            } else if (event.type === INPUT_EVENT_TYPE.moveInputFinished) {
+                moveInputFinishedCount++
             }
             return true
         }, COLOR.white)
         const visualMoveInput = chessboard.view.visualMoveInput
 
-        // simulate an existing click-to-move selection of the white e2 pawn
-        // (moveInputStartedCallback sets up the internal moveInputProcess task)
-        visualMoveInput.moveInputStartedCallback("e2")
+        // simulate an existing click-to-move selection of the white king on e1
+        visualMoveInput.moveInputStartedCallback("e1")
         visualMoveInput.moveInputState = STATE_CLICK_TO
-        visualMoveInput.fromSquare = "e2"
+        visualMoveInput.fromSquare = "e1"
 
-        // click another own (white) piece, the d1 queen -> chess960 probe branch
+        // castle by clicking the rook on h1 -> same-color-click branch
         visualMoveInput.onPointerDown({
             type: "touchstart",
-            target: {getAttribute: (name) => (name === "data-square" ? "d1" : null)},
+            target: {getAttribute: (name) => (name === "data-square" ? "h1" : null)},
             touches: [{clientX: 100, clientY: 100}],
             preventDefault: () => {}
         })
 
-        assert.equal(probeSeen, true)
+        assert.equal(validateCallCount, 1)
 
         await new Promise((resolve) => setTimeout(resolve))
+        // the move must complete (not get stuck in `clickTo`), firing moveInputFinished exactly once
+        assert.equal(moveInputFinishedCount, 1)
+
         chessboard.destroy()
     })
 
+    it("should complete a click-to-move (select, then click destination)", async () => {
+        const board = newBoard()
+        let finished = 0
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputFinished) finished++
+            return true
+        }, COLOR.white)
+        const vmi = board.view.visualMoveInput
+
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        assert.equal(vmi.moveInputState, STATE_CLICK_TO)
+
+        vmi.onPointerDown(mouseDown("e4"))
+        await tick()
+        assert.equal(board.getPiece("e4"), "wp")
+        assert.equal(board.getPiece("e2"), null)
+        assert.equal(finished, 1)
+        board.destroy()
+    })
+
+    it("should complete a drag move to a new square", async () => {
+        const board = newBoard()
+        board.enableMoveInput(() => true, COLOR.white)
+        const vmi = board.view.visualMoveInput
+
+        vmi.onPointerDown(mouseDown("e2", 100, 100))
+        vmi.onPointerMove(mouseMove("e4", 100, 140)) // past DRAG_THRESHOLD -> dragTo
+        assert.equal(vmi.moveInputState, STATE_DRAG_TO)
+        vmi.onPointerUp(mouseUp("e4"))
+        await tick()
+        assert.equal(board.getPiece("e4"), "wp")
+        assert.equal(board.getPiece("e2"), null)
+        board.destroy()
+    })
+
+    // Regression for https://github.com/shaack/cm-chessboard/issues/170 (PR #171)
+    it("should cancel when a piece is dragged back to its origin", async () => {
+        const board = newBoard()
+        let canceledReason
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceledReason = e.reason
+            return true
+        }, COLOR.white)
+        const vmi = board.view.visualMoveInput
+
+        vmi.onPointerDown(mouseDown("e2", 100, 100))
+        vmi.onPointerMove(mouseMove("e2", 100, 140)) // -> dragTo
+        assert.equal(vmi.moveInputState, STATE_DRAG_TO)
+        vmi.onPointerUp(mouseUp("e2")) // dropped back on origin
+        await tick()
+
+        assert.equal(canceledReason, MOVE_CANCELED_REASON.draggedBack)
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        assert.equal(board.getPiece("e2"), "wp") // piece stays put
+        board.destroy()
+    })
+
+    // Regression for https://github.com/shaack/cm-chessboard/issues/170
+    it("should re-select when clicking another own piece", async () => {
+        const board = newBoard()
+        let canceledReason
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.validateMoveInput) return false // not a legal move onto own piece
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceledReason = e.reason
+            return true
+        }, COLOR.white)
+        const vmi = board.view.visualMoveInput
+
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        assert.equal(vmi.moveInputState, STATE_CLICK_TO)
+
+        vmi.onPointerDown(mouseDown("d1")) // own white queen
+        assert.equal(canceledReason, MOVE_CANCELED_REASON.clickedAnotherPiece)
+        assert.equal(vmi.fromSquare, "d1")
+        assert.equal(vmi.moveInputState, STATE_PIECE_CLICKED_THRESHOLD)
+        await tick()
+        board.destroy()
+    })
+
+    // Regression for https://github.com/shaack/cm-chessboard/pull/173
+    it("should cancel an in-progress move on right click", async () => {
+        const board = newBoard()
+        let canceledReason
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceledReason = e.reason
+            return true
+        }, COLOR.white)
+        const vmi = board.view.visualMoveInput
+
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        assert.equal(vmi.moveInputState, STATE_CLICK_TO)
+
+        vmi.onContextMenu({preventDefault: () => {}})
+        assert.equal(canceledReason, MOVE_CANCELED_REASON.secondaryClick)
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        await tick()
+        board.destroy()
+    })
+
+    it("should ignore input when move input is disabled", () => {
+        const board = newBoard()
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        board.destroy()
+    })
+
+    it("should ignore a piece of the disabled color", () => {
+        const board = newBoard()
+        board.enableMoveInput(() => true, COLOR.white)
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e7")) // black pawn, black input disabled
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        board.destroy()
+    })
+
+    it("should not start a move when moveInputStarted returns false", () => {
+        const board = newBoard()
+        board.enableMoveInput((e) => e.type !== INPUT_EVENT_TYPE.moveInputStarted, COLOR.white)
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        board.destroy()
+    })
+
+    // Regression for https://github.com/shaack/cm-chessboard/pull/165
+    it("should cancel and keep the new position when the held piece is captured via setPosition", async () => {
+        const board = newBoard()
+        let canceled = null
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceled = {square: e.squareFrom, reason: e.reason}
+            return true
+        }, COLOR.white)
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        assert.equal(vmi.moveInputState, STATE_CLICK_TO)
+
+        // the opponent captures the held e2 pawn (e2 now holds a black knight)
+        const capturedFen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPnPPP/RNBQKBNR"
+        await board.setPosition(capturedFen)
+
+        assert.equal(canceled && canceled.reason, MOVE_CANCELED_REASON.movedPieceChanged)
+        assert.equal(canceled && canceled.square, "e2") // the real start square, not null
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        // the position must not be corrupted back to the white pawn
+        assert.equal("" + board.getPosition(), capturedFen)
+        await tick()
+        board.destroy()
+    })
+
+    it("should not cancel a normal move completion", async () => {
+        const board = newBoard()
+        let canceledReason
+        let finished = 0
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceledReason = e.reason
+            if (e.type === INPUT_EVENT_TYPE.moveInputFinished) finished++
+            return true
+        }, COLOR.white)
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        vmi.onPointerDown(mouseDown("e4")) // completes via moveDone -> movePiece()
+        await tick()
+        assert.equal(board.getPiece("e4"), "wp")
+        assert.equal(canceledReason, undefined) // the guard must prevent a spurious cancel
+        assert.equal(finished, 1)
+        board.destroy()
+    })
+
+    it("should cancel when the held piece is captured via movePiece or setPiece", async () => {
+        // via setPiece
+        let board = newBoard()
+        let reason
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) reason = e.reason
+            return true
+        }, COLOR.white)
+        let vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        await board.setPiece("e2", "bn")
+        assert.equal(reason, MOVE_CANCELED_REASON.movedPieceChanged)
+        await tick()
+        board.destroy()
+
+        // via movePiece (a black pawn captures onto e2)
+        board = newBoard()
+        reason = undefined
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) reason = e.reason
+            return true
+        }, COLOR.white)
+        vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        await board.movePiece("d7", "e2")
+        assert.equal(reason, MOVE_CANCELED_REASON.movedPieceChanged)
+        await tick()
+        board.destroy()
+    })
+
+    it("should cancel an in-progress click selection via cancelMoveInput()", async () => {
+        const board = newBoard()
+        let canceled = null
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceled = {square: e.squareFrom, reason: e.reason}
+            return true
+        }, COLOR.white)
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2"))
+        vmi.onPointerUp(mouseUp("e2"))
+        assert.equal(vmi.moveInputState, STATE_CLICK_TO)
+
+        board.cancelMoveInput()
+        assert.equal(canceled && canceled.reason, MOVE_CANCELED_REASON.canceled)
+        assert.equal(canceled && canceled.square, "e2")
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        await tick()
+        board.destroy()
+    })
+
+    it("should cancel a drag in progress via cancelMoveInput() without moving the piece", async () => {
+        const board = newBoard()
+        board.enableMoveInput(() => true, COLOR.white)
+        const vmi = board.view.visualMoveInput
+        vmi.onPointerDown(mouseDown("e2", 100, 100))
+        vmi.onPointerMove(mouseMove("e4", 100, 140)) // -> dragTo
+        assert.equal(vmi.moveInputState, STATE_DRAG_TO)
+
+        board.cancelMoveInput()
+        assert.equal(vmi.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        assert.equal(board.getPiece("e2"), "wp")
+        assert.equal(board.getPiece("e4"), null)
+        await tick()
+        board.destroy()
+    })
+
+    it("should be a no-op when cancelMoveInput() is called with no move in progress", () => {
+        const board = newBoard()
+        let canceledCount = 0
+        board.enableMoveInput((e) => {
+            if (e.type === INPUT_EVENT_TYPE.moveInputCanceled) canceledCount++
+            return true
+        }, COLOR.white)
+        board.cancelMoveInput()
+        assert.equal(canceledCount, 0)
+        assert.equal(board.view.visualMoveInput.moveInputState, STATE_WAIT_FOR_INPUT_START)
+        board.destroy()
+    })
+
 })

package/test/headless.mjs

@@ -0,0 +1,109 @@
+/**
+ * Author and copyright: Stefan Haack (https://shaack.com)
+ * Repository: https://github.com/shaack/cm-chessboard
+ * License: MIT, see file 'LICENSE'
+ *
+ * Optional headless test runner. Serves the project over a tiny static server
+ * and runs test/index.html in headless Chrome, then prints the Teevi summary
+ * and exits non-zero on failure.
+ *
+ * Puppeteer is intentionally NOT a project dependency (cm-chessboard ships
+ * without dependencies). Install it globally to use this runner:
+ *
+ *     npm install -g puppeteer
+ *     npm run test:headless
+ *
+ * The regular `npm test` just points you at test/index.html in a browser and
+ * needs nothing installed.
+ */
+
+import {createServer} from "http"
+import {createRequire} from "module"
+import {execSync} from "child_process"
+import {readFile} from "fs/promises"
+import {fileURLToPath} from "url"
+import {dirname, join, normalize, extname} from "path"
+
+const projectRoot = normalize(join(dirname(fileURLToPath(import.meta.url)), ".."))
+
+// Resolve the globally installed puppeteer without adding a project dependency.
+function loadPuppeteer() {
+    let globalRoot
+    try {
+        globalRoot = execSync("npm root -g", {encoding: "utf8"}).trim()
+    } catch {
+        globalRoot = ""
+    }
+    for (const base of [globalRoot + "/", projectRoot + "/"]) {
+        try {
+            return createRequire(base)("puppeteer")
+        } catch { /* try next */ }
+    }
+    console.error(
+        "\nCould not find puppeteer. This headless runner needs it installed globally:\n" +
+        "    npm install -g puppeteer\n" +
+        "Or just open test/index.html in a browser (see `npm test`).\n")
+    process.exit(2)
+}
+
+const MIME = {
+    ".html": "text/html", ".js": "text/javascript", ".mjs": "text/javascript",
+    ".css": "text/css", ".svg": "image/svg+xml", ".json": "application/json",
+    ".png": "image/png", ".map": "application/json"
+}
+
+function startServer() {
+    const server = createServer(async (req, res) => {
+        const urlPath = decodeURIComponent(req.url.split("?")[0])
+        const filePath = normalize(join(projectRoot, urlPath))
+        if (!filePath.startsWith(projectRoot)) { // block path traversal
+            res.writeHead(403).end()
+            return
+        }
+        try {
+            const body = await readFile(filePath)
+            res.writeHead(200, {"Content-Type": MIME[extname(filePath)] || "application/octet-stream"})
+            res.end(body)
+        } catch {
+            res.writeHead(404).end()
+        }
+    })
+    return new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => resolve({server, port: server.address().port}))
+    })
+}
+
+const puppeteer = loadPuppeteer()
+const {server, port} = await startServer()
+const url = `http://127.0.0.1:${port}/test/index.html`
+
+let exitCode = 1
+const browser = await puppeteer.launch({headless: "new"})
+try {
+    const page = await browser.newPage()
+    const errors = []
+    page.on("pageerror", (e) => errors.push(e.message))
+    await page.goto(url, {waitUntil: "networkidle0", timeout: 30000})
+    await page.waitForFunction(
+        () => /All \d+ tests passed|\d+ tests, \d+ passed, \d+ failed/.test(document.body.innerText),
+        {timeout: 30000})
+    const {summary, fails} = await page.evaluate(() => {
+        const text = document.body.innerText
+        const m = text.match(/All \d+ tests passed|\d+ tests, \d+ passed, \d+ failed/)
+        const fails = []
+        document.querySelectorAll("div").forEach((d) => {
+            if (d.innerText && d.innerText.includes("→ fail")) {
+                fails.push(d.innerText.replace(/\s+/g, " ").trim().slice(0, 500))
+            }
+        })
+        return {summary: m ? m[0] : "NO SUMMARY", fails}
+    })
+    console.log(summary)
+    for (const f of fails) console.log("  FAIL: " + f)
+    for (const e of errors.slice(0, 10)) console.log("  pageerror: " + e)
+    exitCode = /failed|NO SUMMARY/.test(summary) ? 1 : 0
+} finally {
+    await browser.close()
+    server.close()
+}
+process.exit(exitCode)

package/test/index.html

@@ -20,11 +20,13 @@
 <div class="board" id="TestBoard"></div>
 <div class="board" id="TestPosition"></div>
 <div class="board" id="TestMarkers"></div>
+<div class="board" id="TestArrows"></div>
 <script type="module">
     import {teevi} from "../node_modules/teevi/src/teevi.js"
     import "./TestChessboard.js"
     import "./TestPiecesAnimation.js"
     import "./TestMarkers.js"
+    import "./TestArrows.js"
     import "./TestPosition.js"
     import "./TestVisualMoveInput.js"
     teevi.run()