@vnejs/plugins.views.screens.checkers 0.2.1

package/dist/utils/checkers.d.ts

@@ -0,0 +1,42 @@
+import type { CheckersBoard, CheckersColor, CheckersMove, CheckersPiece, CheckersPos } from "./board.js";
+export type CheckersGridItem = {
+    row: number;
+    column: number;
+    isDark: boolean;
+    piece: CheckersPiece | null;
+    isSelected?: boolean;
+    isLegalTarget?: boolean;
+    isFocus?: boolean;
+};
+export type CheckersPluginState = {
+    isShow: boolean;
+    isForce: boolean;
+    board?: CheckersBoard;
+    turn?: CheckersColor;
+    selected?: CheckersPos | null;
+    legalMoves?: CheckersMove[];
+    winner?: CheckersColor | null;
+    statusText?: string;
+    gridRow?: number | null;
+    gridColumn?: number | null;
+    gridItems?: CheckersGridItem[];
+    gridIndex?: number;
+    gridsCount?: number;
+    ai?: {
+        white: string;
+        black: string;
+    };
+};
+export type CheckersCellClickPayload = {
+    row?: number;
+    column?: number;
+};
+export declare const statusForTurn: (turn: CheckersColor, winner?: CheckersColor | null) => "Black to move" | "Black wins" | "White to move" | "White wins";
+export declare const buildGridItems: ({ board, selected, legalMoves, gridRow, gridColumn, }: {
+    board: CheckersBoard;
+    selected?: CheckersPos | null;
+    legalMoves?: CheckersMove[];
+    gridRow?: number | null;
+    gridColumn?: number | null;
+}) => CheckersGridItem[];
+export declare const createInitialCheckersState: () => Pick<CheckersPluginState, "board" | "turn" | "selected" | "legalMoves" | "winner" | "statusText" | "gridItems" | "gridIndex" | "gridsCount">;

package/dist/utils/checkers.js

@@ -0,0 +1,40 @@
+import { BOARD_SIZE, createInitialBoard, getAllMoves, isDarkSquare } from "./board.js";
+export const statusForTurn = (turn, winner = null) => {
+    if (winner)
+        return winner === "white" ? "White wins" : "Black wins";
+    return turn === "white" ? "White to move" : "Black to move";
+};
+export const buildGridItems = ({ board, selected = null, legalMoves = [], gridRow = null, gridColumn = null, }) => {
+    const legalKeys = new Set(legalMoves.map((move) => `${move.to.row}:${move.to.column}`));
+    const items = [];
+    for (let row = 0; row < BOARD_SIZE; row++) {
+        for (let column = 0; column < BOARD_SIZE; column++) {
+            items.push({
+                row,
+                column,
+                isDark: isDarkSquare(row, column),
+                piece: board[row]?.[column] ?? null,
+                isSelected: selected?.row === row && selected?.column === column,
+                isLegalTarget: legalKeys.has(`${row}:${column}`),
+                isFocus: gridRow === row && gridColumn === column,
+            });
+        }
+    }
+    return items;
+};
+export const createInitialCheckersState = () => {
+    const board = createInitialBoard();
+    const turn = "white";
+    const legalMoves = getAllMoves(board, turn);
+    return {
+        board,
+        turn,
+        selected: null,
+        legalMoves: [],
+        winner: null,
+        statusText: statusForTurn(turn),
+        gridItems: buildGridItems({ board, legalMoves: [] }),
+        gridIndex: 0,
+        gridsCount: 1,
+    };
+};

package/dist/view/index.d.ts

@@ -0,0 +1,3 @@
+import type { ViewRenderFunc } from "@vnejs/module.components";
+import type { CheckersPluginState } from "../utils/checkers.js";
+export declare const render: ViewRenderFunc<CheckersPluginState>;

package/dist/view/index.js

@@ -0,0 +1,196 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Flex, PositionBox, Screen, Text, createRenderFunc, useCallback, useEffect, useMemo, useState, useStoreState } from "@vnejs/uis.react";
+import { getVneLength } from "@vnejs/uis.utils";
+import { listBoardPieces } from "../utils/board.js";
+const SELECTED_OPACITY = 0.7;
+const GRAVEYARD_STACK = 0.55;
+const cellBackground = (item) => {
+    if (item.isFocus)
+        return "rgba(255, 214, 64, 0.85)";
+    if (item.isLegalTarget)
+        return "rgba(80, 200, 120, 0.75)";
+    if (item.isSelected)
+        return "rgba(90, 160, 255, 0.8)";
+    return item.isDark ? "rgba(60, 40, 20, 0.95)" : "rgba(220, 200, 160, 0.95)";
+};
+const pieceLook = (piece) => {
+    const isWhite = piece.color === "white";
+    return {
+        width: "62%",
+        height: "62%",
+        borderRadius: "50%",
+        background: isWhite ? "#f4f0e6" : "#1a1a1a",
+        border: `${getVneLength(6)} solid ${piece.king ? "#d4af37" : isWhite ? "#bbb" : "#444"}`,
+        boxSizing: "border-box",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+    };
+};
+const kingMarkLook = () => ({
+    width: "50%",
+    height: "50%",
+    borderRadius: "50%",
+    boxSizing: "border-box",
+    border: `${getVneLength(6)} solid #d4af37`,
+    background: "transparent",
+});
+const CheckersScreen = ({ store, onMount, PARAMS, emit, EVENTS }) => {
+    const { isShow = false, isForce = false, board, gridItems = [], gridRow = null, gridColumn = null, selected = null, statusText = "", } = useStoreState(store, onMount);
+    const transition = PARAMS.CHECKERS.TRANSITION;
+    const propsByView = PARAMS.CHECKERS.VIEW_PROPS;
+    const rows = PARAMS.CHECKERS.ROWS;
+    const columns = PARAMS.CHECKERS.COLUMNS;
+    const cellSize = PARAMS.CHECKERS.CELL_SIZE;
+    const cellGap = PARAMS.CHECKERS.CELL_GAP;
+    const graveyardGap = PARAMS.CHECKERS.GRAVEYARD_GAP;
+    const boardSize = columns * cellSize + (columns - 1) * cellGap;
+    const playfieldWidth = cellSize + graveyardGap + boardSize + graveyardGap + cellSize;
+    const boardPieces = useMemo(() => (board ? listBoardPieces(board) : []), [board]);
+    const selectedId = useMemo(() => {
+        if (!selected || !board)
+            return null;
+        return board[selected.row]?.[selected.column]?.id ?? null;
+    }, [board, selected]);
+    const [visualPieces, setVisualPieces] = useState([]);
+    useEffect(() => {
+        if (!isShow) {
+            setVisualPieces([]);
+            return;
+        }
+        setVisualPieces((prev) => {
+            const nextById = new Map(boardPieces.map((piece) => [piece.id, piece]));
+            const next = [];
+            let whiteGraveyardCount = 0;
+            let blackGraveyardCount = 0;
+            for (const piece of prev) {
+                if (piece.zone === "graveyard") {
+                    if (piece.color === "white")
+                        whiteGraveyardCount = Math.max(whiteGraveyardCount, piece.graveyardIndex + 1);
+                    else
+                        blackGraveyardCount = Math.max(blackGraveyardCount, piece.graveyardIndex + 1);
+                }
+            }
+            for (const piece of prev) {
+                const live = nextById.get(piece.id);
+                if (live) {
+                    next.push({
+                        id: live.id,
+                        color: live.color,
+                        king: live.king,
+                        row: live.row,
+                        column: live.column,
+                        opacity: selectedId === live.id ? SELECTED_OPACITY : 1,
+                        zone: "board",
+                        graveyardIndex: 0,
+                    });
+                    nextById.delete(piece.id);
+                    continue;
+                }
+                if (piece.zone === "graveyard") {
+                    next.push(piece);
+                    continue;
+                }
+                const graveyardIndex = piece.color === "white" ? whiteGraveyardCount++ : blackGraveyardCount++;
+                next.push({
+                    ...piece,
+                    opacity: 1,
+                    zone: "graveyard",
+                    graveyardIndex,
+                });
+            }
+            for (const piece of nextById.values()) {
+                next.push({
+                    id: piece.id,
+                    color: piece.color,
+                    king: piece.king,
+                    row: piece.row,
+                    column: piece.column,
+                    opacity: selectedId === piece.id ? SELECTED_OPACITY : 1,
+                    zone: "board",
+                    graveyardIndex: 0,
+                });
+            }
+            return next;
+        });
+    }, [boardPieces, isShow, selectedId]);
+    const propsScreen = useMemo(() => ({ ...propsByView.screen, isShow, isForce }), [isShow, isForce, propsByView.screen]);
+    const propsStatus = useMemo(() => ({ ...propsByView.status, text: statusText, width: playfieldWidth }), [statusText, propsByView.status, playfieldWidth]);
+    const cellLen = useMemo(() => getVneLength(cellSize), [cellSize]);
+    const gapLen = useMemo(() => getVneLength(cellGap), [cellGap]);
+    const graveyardGapLen = useMemo(() => getVneLength(graveyardGap), [graveyardGap]);
+    const stepLen = useMemo(() => (cellGap ? `calc(${cellLen} + ${gapLen})` : cellLen), [cellGap, cellLen, gapLen]);
+    const boardOffsetX = useMemo(() => `calc(${cellLen} + ${graveyardGapLen})`, [cellLen, graveyardGapLen]);
+    const blackGraveyardX = useMemo(() => `calc(${cellLen} + ${graveyardGapLen} + ${getVneLength(boardSize)} + ${graveyardGapLen})`, [boardSize, cellLen, graveyardGapLen]);
+    const playfieldStyle = useMemo(() => ({
+        position: "relative",
+        width: getVneLength(playfieldWidth),
+        height: getVneLength(boardSize),
+        boxSizing: "border-box",
+    }), [boardSize, playfieldWidth]);
+    const boardStyle = useMemo(() => ({
+        position: "absolute",
+        top: 0,
+        left: boardOffsetX,
+        display: "grid",
+        gridTemplateColumns: `repeat(${columns}, ${cellLen})`,
+        gridTemplateRows: `repeat(${rows}, ${cellLen})`,
+        gap: gapLen,
+        width: getVneLength(boardSize),
+        height: getVneLength(boardSize),
+        boxSizing: "border-box",
+    }), [boardOffsetX, boardSize, cellLen, columns, gapLen, rows]);
+    const graveyardStyle = useCallback((side) => ({
+        position: "absolute",
+        top: 0,
+        left: side === "left" ? 0 : blackGraveyardX,
+        width: cellLen,
+        height: getVneLength(boardSize),
+        boxSizing: "border-box",
+        borderRadius: getVneLength(12),
+        background: "rgba(255, 255, 255, 0.06)",
+    }), [blackGraveyardX, boardSize, cellLen]);
+    const cellBaseStyle = useMemo(() => ({
+        width: cellLen,
+        height: cellLen,
+        boxSizing: "border-box",
+        transition: `background-color ${transition}ms`,
+    }), [cellLen, transition]);
+    const piecesLayerStyle = useMemo(() => ({
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+    }), []);
+    const pieceTransform = useCallback((piece) => {
+        if (piece.zone === "graveyard") {
+            const x = piece.color === "white" ? "0px" : blackGraveyardX;
+            const y = `calc(${piece.graveyardIndex} * ${cellLen} * ${GRAVEYARD_STACK})`;
+            return `translate(${x}, ${y})`;
+        }
+        return `translate(calc(${boardOffsetX} + ${piece.column} * ${stepLen}), calc(${piece.row} * ${stepLen}))`;
+    }, [blackGraveyardX, boardOffsetX, cellLen, stepLen]);
+    const onCellClick = useCallback((row, column) => {
+        void emit(EVENTS.CHECKERS.CELL_CLICK, { row, column });
+    }, [emit, EVENTS.CHECKERS.CELL_CLICK]);
+    return (_jsx(Screen, { ...propsScreen, children: _jsx(PositionBox, { ...propsByView.position, children: _jsxs(Flex, { ...propsByView.flex, children: [_jsx(Text, { ...propsStatus }), _jsxs("div", { style: playfieldStyle, children: [_jsx("div", { style: graveyardStyle("left") }), _jsx("div", { style: graveyardStyle("right") }), _jsx("div", { style: boardStyle, children: gridItems.map((item) => {
+                                    const isFocus = gridRow === item.row && gridColumn === item.column;
+                                    return (_jsx("div", { onClick: () => onCellClick(item.row, item.column), "vne-cursor-type": "pointer", style: {
+                                            ...cellBaseStyle,
+                                            background: cellBackground({ ...item, isFocus }),
+                                        } }, `${item.row}-${item.column}`));
+                                }) }), _jsx("div", { style: piecesLayerStyle, children: visualPieces.map((piece) => (_jsx("div", { style: {
+                                        position: "absolute",
+                                        top: 0,
+                                        left: 0,
+                                        width: cellLen,
+                                        height: cellLen,
+                                        display: "flex",
+                                        alignItems: "center",
+                                        justifyContent: "center",
+                                        transform: pieceTransform(piece),
+                                        opacity: piece.opacity,
+                                        transition: `transform ${transition}ms, opacity ${transition}ms`,
+                                        willChange: "transform, opacity",
+                                    }, children: _jsx("div", { style: pieceLook(piece), children: piece.king ? _jsx("div", { style: kingMarkLook() }) : null }) }, piece.id))) })] })] }) }) }));
+};
+export const render = createRenderFunc(CheckersScreen);

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@vnejs/plugins.views.screens.checkers",
+  "version": "0.2.1",
+  "description": "",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test": "npx @vnejs/monorepo test",
+    "build": "npx @vnejs/monorepo package",
+    "publish:major:plugin": "npm run publish:major",
+    "publish:minor:plugin": "npm run publish:minor",
+    "publish:patch:plugin": "npm run publish:patch",
+    "publish:major": "npx @vnejs/monorepo publish major --access public",
+    "publish:minor": "npx @vnejs/monorepo publish minor --access public",
+    "publish:patch": "npx @vnejs/monorepo publish patch --access public"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@vnejs/contracts.views.screens.checkers": "~0.2.0"
+  },
+  "peerDependencies": {
+    "@vnejs/helpers": "~0.2.0",
+    "@vnejs/module.core": "~0.2.0",
+    "@vnejs/module.components": "~0.2.0",
+    "@vnejs/module.controller.accept": "~0.2.0",
+    "@vnejs/module.controller.arrows.grid": "~0.2.0",
+    "@vnejs/contracts.controls": "~0.2.0",
+    "@vnejs/shared": "~0.2.0",
+    "@vnejs/uis.react": "~0.2.0"
+  },
+  "devDependencies": {
+    "@vnejs/configs.ts-common": "~0.2.0",
+    "@vnejs/configs.vitest": "~0.2.0",
+    "@vnejs/test-utils": "~0.2.0",
+    "@vnejs/contracts.controls": "~0.2.0",
+    "@vnejs/contracts.views.screens.checkers": "~0.2.0",
+    "@vnejs/helpers": "~0.2.0",
+    "@vnejs/module.core": "~0.2.0",
+    "@vnejs/module.components": "~0.2.0",
+    "@vnejs/module.controller.accept": "~0.2.0",
+    "@vnejs/module.controller.arrows.grid": "~0.2.0",
+    "@vnejs/shared": "~0.2.0",
+    "@vnejs/uis.react": "~0.2.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+import "@vnejs/contracts.views.screens.checkers";
+
+import { regPlugin } from "@vnejs/shared";
+import { CONSTANTS, PARAMS, PLUGIN_NAME, SUBSCRIBE_EVENTS } from "@vnejs/contracts.views.screens.checkers";
+
+import { CheckersController } from "./modules/controller.js";
+import { CheckersControllerAccept } from "./modules/controller.accept.js";
+import { CheckersControllerGrid } from "./modules/controller.grid.js";
+import { Checkers } from "./modules/checkers.js";
+import { CheckersView } from "./modules/view.js";
+
+regPlugin(PLUGIN_NAME, { constants: CONSTANTS, events: SUBSCRIBE_EVENTS, params: PARAMS }, [
+  CheckersController,
+  CheckersControllerGrid,
+  CheckersControllerAccept,
+  Checkers,
+  CheckersView,
+]);

package/src/modules/checkers.ts

@@ -0,0 +1,52 @@
+import { tokenizeExecLine } from "@vnejs/helpers";
+import { ModuleCore } from "@vnejs/module.core";
+
+import type { LineExecHandlerArg } from "@vnejs/module.core";
+import type { CheckersAiColor, CheckersAiType } from "@vnejs/contracts.views.screens.checkers";
+
+import type { CheckersPluginConstants, CheckersPluginEvents, CheckersPluginParams, CheckersPluginSettings } from "../types.js";
+
+const AI_COLOR_VALUES = new Set<string>(["white", "black"]);
+const AI_TYPE_VALUES = new Set<string>(["player", "sacrifice", "random", "strong"]);
+
+export class Checkers extends ModuleCore<CheckersPluginEvents, CheckersPluginConstants, CheckersPluginSettings, CheckersPluginParams> {
+  name = "checkers";
+
+  postinject = () => {
+    this.shared.checkersAi ??= {
+      white: this.CONST.CHECKERS.AI_TYPES.PLAYER,
+      black: this.CONST.CHECKERS.AI_TYPES.PLAYER,
+    };
+    this.shared.checkersAiBusy ??= false;
+  };
+
+  init = () => this.emit(this.EVENTS.SCENARIO.LINE_EXEC_REG, { module: this.name, handler: this.onLineExec });
+
+  onLineExec = ({ line = "" }: LineExecHandlerArg = {}) => {
+    const [action = "", colorRaw = "", typeRaw = ""] = tokenizeExecLine(line).map(String);
+
+    if (action === this.CONST.CHECKERS.EXEC_ACTIONS.SHOW) {
+      this.emitLog({ action });
+      return this.emit(this.EVENTS.CHECKERS.SHOW);
+    }
+
+    if (action !== this.CONST.CHECKERS.EXEC_ACTIONS.AI) return;
+
+    if (!AI_COLOR_VALUES.has(colorRaw) || !AI_TYPE_VALUES.has(typeRaw)) {
+      this.emitLog({ action, color: colorRaw, type: typeRaw, error: "invalid_args" });
+      this.emitNext();
+      return;
+    }
+
+    const color = colorRaw as CheckersAiColor;
+    const type = typeRaw as CheckersAiType;
+
+    this.shared.checkersAi = {
+      ...this.shared.checkersAi,
+      [color]: type,
+    };
+
+    this.emitLog({ action, color, type });
+    this.emitNext();
+  };
+}

package/src/modules/controller.accept.ts

@@ -0,0 +1,202 @@
+import { ModuleControllerAccept } from "@vnejs/module.controller.accept";
+import type { ControlsPopPayload, ControlsPushPayload } from "@vnejs/contracts.controls";
+
+import type { CheckersAiType } from "@vnejs/contracts.views.screens.checkers";
+
+import type { CheckersPluginConstants, CheckersPluginEvents, CheckersPluginParams, CheckersPluginSettings } from "../types.js";
+import { applyMove, findMove, getAllMoves, getWinner, oppositeColor, samePos, type CheckersPos } from "../utils/board.js";
+import { pickMove } from "../utils/ai.js";
+import { buildGridItems, statusForTurn, type CheckersCellClickPayload, type CheckersPluginState } from "../utils/checkers.js";
+
+export class CheckersControllerAccept extends ModuleControllerAccept<
+  CheckersPluginEvents,
+  CheckersPluginConstants,
+  CheckersPluginSettings,
+  CheckersPluginParams,
+  CheckersPluginState
+> {
+  name = "checkers.controller.accept";
+
+  EVENT_SHOW = this.EVENTS.CHECKERS.SHOW;
+  EVENT_HIDE = this.EVENTS.CHECKERS.HIDE;
+  EVENT_ACCEPT = this.EVENTS.CHECKERS.ACCEPT;
+  EVENT_STATE_UPDATE = this.EVENTS.CHECKERS.STATE_UPDATE;
+
+  CONTROLS_ZINDEX = this.PARAMS.CHECKERS.ZINDEX;
+
+  subscribe = () => {
+    this.on(this.EVENT_SHOW, this.onShow);
+    this.on(this.EVENT_HIDE, this.onHide);
+    this.on(this.EVENT_ACCEPT, this.onAccept);
+    if (this.EVENT_STATE_UPDATE) this.on(this.EVENT_STATE_UPDATE, this.updateState);
+    this.on(this.EVENTS.CHECKERS.CELL_CLICK, this.onCellClick);
+    this.on(this.EVENTS.CHECKERS.AI_TURN, this.onAiTurn);
+  };
+
+  onShow = () => void this.onShowAndMaybeAi();
+
+  onShowAndMaybeAi = async () => {
+    await this.emit(this.EVENTS.CONTROLS.PUSH, {
+      key: this.name,
+      controls: this.CONTROLS,
+      index: this.CONTROLS_ZINDEX + 1,
+      checkNext: true,
+    } satisfies ControlsPushPayload);
+
+    // SHOW handlers run in parallel with controller.beforeShow — wait for board.
+    await this.waitCheck(() => Boolean(this.state.board && this.state.turn));
+    await this.onAiTurn();
+  };
+
+  onHide = () => {
+    this.shared.checkersAiBusy = false;
+    this.setDefaultState();
+
+    return this.emit(this.EVENTS.CONTROLS.POP, { key: this.name } satisfies ControlsPopPayload);
+  };
+
+  controllerFor = (turn: NonNullable<CheckersPluginState["turn"]>) =>
+    (this.state.ai?.[turn] ?? this.shared.checkersAi?.[turn] ?? this.CONST.CHECKERS.AI_TYPES.PLAYER) as CheckersAiType;
+
+  isHumanTurn = () => {
+    const turn = this.state.turn;
+    if (!turn) return false;
+    return this.controllerFor(turn) === this.CONST.CHECKERS.AI_TYPES.PLAYER;
+  };
+
+  onCellClick = async ({ row, column }: CheckersCellClickPayload = {}) => {
+    if (this.shared.checkersAiBusy || !this.isHumanTurn()) return;
+    if (row == null || column == null) return;
+
+    await this.emit(this.EVENTS.CHECKERS.STATE_UPDATE, {
+      gridRow: row,
+      gridColumn: column,
+    } satisfies Partial<CheckersPluginState>);
+    await this.emit(this.EVENTS.CHECKERS.UPDATE_FAST);
+    await this.onAccept();
+  };
+
+  onAccept = async () => {
+    if (this.shared.checkersAiBusy) return;
+
+    if (this.state.winner) {
+      await this.emit(this.EVENTS.CHECKERS.FINISH);
+      return;
+    }
+
+    if (!this.isHumanTurn()) return;
+
+    const { gridRow, gridColumn, board, turn, selected } = this.state;
+    if (gridRow == null || gridColumn == null || !board || !turn) return;
+
+    const focus: CheckersPos = { row: gridRow, column: gridColumn };
+    const piece = board[focus.row]?.[focus.column] ?? null;
+
+    if (selected && findMove(this.state.legalMoves ?? [], selected, focus)) {
+      await this.playMove(selected, focus);
+      return;
+    }
+
+    if (piece && piece.color === turn) {
+      const all = getAllMoves(board, turn);
+      const legalMoves = all.filter((move) => samePos(move.from, focus));
+      if (legalMoves.length === 0) return;
+
+      const nextSelected = selected && samePos(selected, focus) ? null : focus;
+      const nextLegal = nextSelected ? legalMoves : [];
+
+      await this.emitBoardState({
+        selected: nextSelected,
+        legalMoves: nextLegal,
+      });
+      return;
+    }
+
+    if (selected) {
+      await this.emitBoardState({ selected: null, legalMoves: [] });
+    }
+  };
+
+  onAiTurn = async () => {
+    if (this.state.winner || !this.state.board || !this.state.turn) return;
+    if (this.isHumanTurn()) return;
+    if (this.shared.checkersAiBusy) return;
+
+    this.shared.checkersAiBusy = true;
+
+    try {
+      while (!this.state.winner && this.state.board && this.state.turn && !this.isHumanTurn()) {
+        await this.waitTimeout(this.PARAMS.CHECKERS.AI_DELAY);
+
+        const { board, turn } = this.state;
+        if (!board || !turn || this.state.winner) break;
+
+        const move = pickMove(board, turn, this.controllerFor(turn));
+        if (!move) break;
+
+        const played = await this.playMove(move.from, move.to, { scheduleAi: false });
+        if (!played) break;
+      }
+    } finally {
+      this.shared.checkersAiBusy = false;
+    }
+  };
+
+  playMove = async (from: CheckersPos, to: CheckersPos, { scheduleAi = true }: { scheduleAi?: boolean } = {}) => {
+    const { board, turn } = this.state;
+    if (!board || !turn) return false;
+
+    // Always resolve against current legal moves — `legalMoves: []` after a move is truthy and must not win over getAllMoves.
+    const move = findMove(getAllMoves(board, turn), from, to);
+    if (!move) return false;
+
+    const nextBoard = applyMove(board, move);
+    const nextTurn = oppositeColor(turn);
+    const winner = getWinner(nextBoard, nextTurn);
+
+    await this.emitBoardState({
+      board: nextBoard,
+      turn: nextTurn,
+      selected: null,
+      legalMoves: [],
+      winner,
+      statusText: statusForTurn(nextTurn, winner),
+    });
+
+    if (winner) {
+      await this.waitTimeout(this.PARAMS.CHECKERS.TRANSITION);
+      await this.emit(this.EVENTS.CHECKERS.FINISH);
+      return true;
+    }
+
+    if (scheduleAi) await this.onAiTurn();
+    return true;
+  };
+
+  emitBoardState = async (
+    patch: Partial<CheckersPluginState> & {
+      board?: CheckersPluginState["board"];
+      selected?: CheckersPluginState["selected"];
+      legalMoves?: CheckersPluginState["legalMoves"];
+    },
+  ) => {
+    const board = patch.board ?? this.state.board;
+    if (!board) return;
+
+    const selected = patch.selected !== undefined ? patch.selected : this.state.selected;
+    const legalMoves = patch.legalMoves !== undefined ? patch.legalMoves : this.state.legalMoves;
+    const gridItems = buildGridItems({
+      board,
+      selected: selected ?? null,
+      legalMoves: legalMoves ?? [],
+      gridRow: this.state.gridRow ?? null,
+      gridColumn: this.state.gridColumn ?? null,
+    });
+
+    await this.emit(this.EVENTS.CHECKERS.STATE_UPDATE, {
+      ...patch,
+      gridItems,
+    } satisfies Partial<CheckersPluginState>);
+    await this.emit(this.EVENTS.CHECKERS.UPDATE_FAST);
+  };
+}

package/src/modules/controller.grid.ts

@@ -0,0 +1,43 @@
+import { ModuleControllerArrowsGrid } from "@vnejs/module.controller.arrows.grid";
+
+import type { CheckersPluginConstants, CheckersPluginEvents, CheckersPluginParams, CheckersPluginSettings } from "../types.js";
+import { buildGridItems, type CheckersPluginState } from "../utils/checkers.js";
+import { createInitialBoard } from "../utils/board.js";
+
+export class CheckersControllerGrid extends ModuleControllerArrowsGrid<
+  CheckersPluginEvents,
+  CheckersPluginConstants,
+  CheckersPluginSettings,
+  CheckersPluginParams,
+  CheckersPluginState
+> {
+  name = "checkers.controller.grid";
+
+  EVENT_SHOW = this.EVENTS.CHECKERS.SHOW;
+  EVENT_HIDE = this.EVENTS.CHECKERS.HIDE;
+  EVENT_STATE_UPDATE = this.EVENTS.CHECKERS.STATE_UPDATE;
+  EVENT_UPDATE_FAST = this.EVENTS.CHECKERS.UPDATE_FAST;
+  EVENT_GRID_NEXT = this.EVENTS.CHECKERS.GRID_NEXT;
+  EVENT_GRID_PREV = this.EVENTS.CHECKERS.GRID_PREV;
+  EVENT_GRID_CLEAR = this.EVENTS.CHECKERS.GRID_CLEAR;
+  EVENT_GRID_UPDATE_ITEMS = this.EVENTS.CHECKERS.GRID_UPDATE_ITEMS;
+
+  CONTROLS_ZINDEX = this.PARAMS.CHECKERS.ZINDEX;
+
+  isDisableGridChangeHorizontal = true;
+  isDisableGridChangeVertical = true;
+
+  getMaxRows = () => this.PARAMS.CHECKERS.ROWS;
+  getMaxColumns = () => this.PARAMS.CHECKERS.COLUMNS;
+
+  getGridItems = async () => {
+    const board = this.state.board ?? createInitialBoard();
+    return buildGridItems({
+      board,
+      selected: this.state.selected ?? null,
+      legalMoves: this.state.legalMoves ?? [],
+      gridRow: this.state.gridRow ?? null,
+      gridColumn: this.state.gridColumn ?? null,
+    });
+  };
+}