@vnejs/plugins.views.screens.checkers 0.2.1

package/src/modules/controller.ts

@@ -0,0 +1,50 @@
+import { ModuleController } from "@vnejs/module.components";
+
+import type { CheckersPluginConstants, CheckersPluginEvents, CheckersPluginParams, CheckersPluginSettings } from "../types.js";
+import { createInitialCheckersState, type CheckersPluginState } from "../utils/checkers.js";
+
+export class CheckersController extends ModuleController<
+  CheckersPluginEvents,
+  CheckersPluginConstants,
+  CheckersPluginSettings,
+  CheckersPluginParams,
+  CheckersPluginState
+> {
+  name = "checkers.controller";
+
+  EVENT_UPDATE_VIEW = this.EVENTS.CHECKERS.UPDATE;
+
+  CONTROLS = {};
+  CONTROLS_INDEX = this.PARAMS.CHECKERS.ZINDEX;
+
+  subscribe = () => {
+    this.on(this.EVENTS.CHECKERS.SHOW, this.onShow);
+    this.on(this.EVENTS.CHECKERS.HIDE, this.onHide);
+    this.on(this.EVENTS.CHECKERS.STATE_UPDATE, this.updateState);
+    this.on(this.EVENTS.CHECKERS.UPDATE_FAST, this.updateViewFast);
+    this.on(this.EVENTS.CHECKERS.FINISH, this.onFinish);
+  };
+
+  beforeShow = async () => {
+    this.shared.checkersAiBusy = false;
+    const initial = createInitialCheckersState();
+    const ai = {
+      white: this.shared.checkersAi?.white ?? this.CONST.CHECKERS.AI_TYPES.PLAYER,
+      black: this.shared.checkersAi?.black ?? this.CONST.CHECKERS.AI_TYPES.PLAYER,
+    };
+
+    await this.emit(this.EVENTS.CHECKERS.STATE_UPDATE, { ...initial, ai } satisfies Partial<CheckersPluginState>);
+    await this.emit(this.EVENTS.CHECKERS.GRID_UPDATE_ITEMS);
+  };
+
+  afterHide = () => {
+    this.shared.checkersAiBusy = false;
+    this.setDefaultState();
+  };
+
+  onFinish = async () => {
+    this.shared.checkersAiBusy = false;
+    await this.emit(this.EVENTS.CHECKERS.HIDE);
+    this.emitNext();
+  };
+}

package/src/modules/view.ts

@@ -0,0 +1,17 @@
+import { ModuleView } from "@vnejs/module.components";
+
+import { render } from "../view/index.js";
+import type { CheckersPluginConstants, CheckersPluginEvents, CheckersPluginParams, CheckersPluginSettings } from "../types.js";
+import type { CheckersPluginState } from "../utils/checkers.js";
+
+export class CheckersView extends ModuleView<CheckersPluginEvents, CheckersPluginConstants, CheckersPluginSettings, CheckersPluginParams, CheckersPluginState> {
+  name = "checkers.view";
+
+  EVENT_UPDATE_VIEW = this.EVENTS.CHECKERS.UPDATE;
+
+  LOC_LABEL = null;
+
+  TRANSITION = this.PARAMS.CHECKERS.TRANSITION;
+
+  renderFunc = render;
+}

package/src/tests/ai.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { BOARD_SIZE, type CheckersBoard, type CheckersPiece } from "../utils/board.js";
+import { isHangingMove, pickMove } from "../utils/ai.js";
+
+const emptyBoard = (): CheckersBoard => Array.from({ length: BOARD_SIZE }, () => Array.from({ length: BOARD_SIZE }, () => null));
+
+const piece = (id: string, color: CheckersPiece["color"]): CheckersPiece => ({ id, color, king: false });
+
+/** White at (5,2): (4,1) hangs to black at (3,0); (4,3) is safe. */
+const hangingScenarioBoard = (): CheckersBoard => {
+  const board = emptyBoard();
+  board[5]![2] = piece("w1", "white");
+  board[3]![0] = piece("b1", "black");
+  return board;
+};
+
+describe("checkers ai", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("isHangingMove is true when opponent gets a capture", () => {
+    const board = hangingScenarioBoard();
+    const hanging = { from: { row: 5, column: 2 }, to: { row: 4, column: 1 }, captures: [] };
+    const safe = { from: { row: 5, column: 2 }, to: { row: 4, column: 3 }, captures: [] };
+
+    expect(isHangingMove(board, hanging, "white")).toBe(true);
+    expect(isHangingMove(board, safe, "white")).toBe(false);
+  });
+
+  it("pickMove sacrifice prefers hanging moves", () => {
+    vi.spyOn(Math, "random").mockReturnValue(0);
+    const board = hangingScenarioBoard();
+    const move = pickMove(board, "white", "sacrifice");
+
+    expect(move).toEqual({ from: { row: 5, column: 2 }, to: { row: 4, column: 1 }, captures: [] });
+  });
+
+  it("pickMove strong prefers safe moves", () => {
+    vi.spyOn(Math, "random").mockReturnValue(0);
+    const board = hangingScenarioBoard();
+    const move = pickMove(board, "white", "strong");
+
+    expect(move).toEqual({ from: { row: 5, column: 2 }, to: { row: 4, column: 3 }, captures: [] });
+  });
+
+  it("pickMove random returns a legal move", () => {
+    vi.spyOn(Math, "random").mockReturnValue(0);
+    const board = hangingScenarioBoard();
+    const move = pickMove(board, "white", "random");
+
+    expect(move).not.toBeNull();
+    expect(move?.from).toEqual({ row: 5, column: 2 });
+  });
+
+  it("pickMove player returns null", () => {
+    const board = hangingScenarioBoard();
+    expect(pickMove(board, "white", "player")).toBeNull();
+  });
+});

package/src/tests/board.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+
+import { applyMove, createInitialBoard, getAllMoves, getWinner, countPieces } from "../utils/board.js";
+
+describe("checkers board", () => {
+  it("creates initial setup with 12 pieces each", () => {
+    const board = createInitialBoard();
+
+    expect(countPieces(board, "white")).toBe(12);
+    expect(countPieces(board, "black")).toBe(12);
+  });
+
+  it("white has simple opening moves", () => {
+    const board = createInitialBoard();
+    const moves = getAllMoves(board, "white");
+
+    expect(moves.length).toBeGreaterThan(0);
+    expect(moves.every((move) => move.captures.length === 0)).toBe(true);
+  });
+
+  it("detects win when side has no pieces", () => {
+    const board = createInitialBoard();
+    for (let row = 0; row < 8; row++) {
+      for (let column = 0; column < 8; column++) {
+        if (board[row]?.[column]?.color === "black") board[row]![column] = null;
+      }
+    }
+
+    expect(getWinner(board, "black")).toBe("white");
+  });
+
+  it("applies a simple move", () => {
+    const board = createInitialBoard();
+    const moves = getAllMoves(board, "white");
+    const move = moves[0]!;
+    const pieceId = board[move.from.row]![move.from.column]!.id;
+    const next = applyMove(board, move);
+
+    expect(next[move.from.row]![move.from.column]).toBeNull();
+    expect(next[move.to.row]![move.to.column]?.color).toBe("white");
+    expect(next[move.to.row]![move.to.column]?.id).toBe(pieceId);
+  });
+});

package/src/tests/checkers.test.ts

@@ -0,0 +1,58 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { spyEvent } from "@vnejs/test-utils";
+
+import { Checkers } from "../modules/checkers.js";
+import { createCheckersTestModule, registerCheckersPluginVne, SUBSCRIBE_EVENTS } from "./setup.js";
+
+describe("Checkers", () => {
+  beforeEach(() => {
+    registerCheckersPluginVne();
+  });
+
+  it("line exec show emits SHOW", async () => {
+    const { module, observer } = createCheckersTestModule(Checkers, { subscribe: false });
+    const show = spyEvent(observer, SUBSCRIBE_EVENTS.SHOW);
+
+    await (module as Checkers).init();
+    await (module as Checkers).onLineExec({ line: "show" });
+
+    expect(show).toHaveBeenCalledOnce();
+  });
+
+  it("line exec ignores unknown action", async () => {
+    const { module, observer } = createCheckersTestModule(Checkers, { subscribe: false });
+    const show = spyEvent(observer, SUBSCRIBE_EVENTS.SHOW);
+
+    await (module as Checkers).init();
+    await (module as Checkers).onLineExec({ line: "open" });
+
+    expect(show).not.toHaveBeenCalled();
+  });
+
+  it("line exec ai sets shared.checkersAi and emits next", async () => {
+    const { module } = createCheckersTestModule(Checkers, { subscribe: false });
+    const checkers = module as Checkers;
+    const emitNext = vi.spyOn(checkers, "emitNext");
+
+    await checkers.postinject();
+    await checkers.init();
+    await checkers.onLineExec({ line: "ai black strong" });
+
+    expect(checkers.shared.checkersAi).toEqual({ white: "player", black: "strong" });
+    expect(emitNext).toHaveBeenCalledOnce();
+  });
+
+  it("line exec ai with invalid args still emits next", async () => {
+    const { module } = createCheckersTestModule(Checkers, { subscribe: false });
+    const checkers = module as Checkers;
+    const emitNext = vi.spyOn(checkers, "emitNext");
+
+    await checkers.postinject();
+    await checkers.init();
+    await checkers.onLineExec({ line: "ai red random" });
+
+    expect(checkers.shared.checkersAi).toEqual({ white: "player", black: "player" });
+    expect(emitNext).toHaveBeenCalledOnce();
+  });
+});

package/src/tests/setup.ts

@@ -0,0 +1,34 @@
+import { CONSTANTS as CONTROLS_CONST, PLUGIN_NAME as CONTROLS, SUBSCRIBE_EVENTS as CONTROLS_EVENTS } from "@vnejs/contracts.controls";
+import { CONSTANTS, PARAMS, PLUGIN_NAME, SUBSCRIBE_EVENTS } from "@vnejs/contracts.views.screens.checkers";
+import { createTestModule as baseCreateTestModule, registerCoreVne, registerVnePlugin, stubSilentEvent } from "@vnejs/test-utils";
+
+export const registerCheckersPluginVne = () => {
+  registerCoreVne();
+  registerVnePlugin(CONTROLS, { constants: CONTROLS_CONST, events: CONTROLS_EVENTS });
+  registerVnePlugin(PLUGIN_NAME, { constants: CONSTANTS, events: SUBSCRIBE_EVENTS, params: PARAMS });
+};
+
+export const createCheckersTestModule = <T extends Parameters<typeof baseCreateTestModule>[0]>(
+  ModuleClass: T,
+  options: Parameters<typeof baseCreateTestModule>[1] = {},
+) => {
+  const result = baseCreateTestModule(ModuleClass, {
+    state: {
+      checkers: { isShow: false },
+      ...(options.state ?? {}),
+    },
+    ...options,
+  });
+
+  stubSilentEvent(result.observer, SUBSCRIBE_EVENTS.SHOW);
+  stubSilentEvent(result.observer, SUBSCRIBE_EVENTS.HIDE);
+  stubSilentEvent(result.observer, SUBSCRIBE_EVENTS.UPDATE);
+  stubSilentEvent(result.observer, SUBSCRIBE_EVENTS.UPDATE_FAST);
+  stubSilentEvent(result.observer, SUBSCRIBE_EVENTS.STATE_UPDATE);
+  stubSilentEvent(result.observer, SUBSCRIBE_EVENTS.GRID_UPDATE_ITEMS);
+  stubSilentEvent(result.observer, SUBSCRIBE_EVENTS.FINISH);
+
+  return result;
+};
+
+export { SUBSCRIBE_EVENTS, PARAMS, PLUGIN_NAME, CONTROLS_EVENTS };

package/src/types.ts

@@ -0,0 +1,23 @@
+import type { ModuleComponentsConstants, ModuleComponentsEvents, ModuleComponentsParams, ModuleComponentsSettings } from "@vnejs/module.components";
+import type { Constants as ControlsConstants, PluginName as ControlsPluginName } from "@vnejs/contracts.controls";
+import type {
+  Constants as ScenarioConstants,
+  PluginName as ScenarioPluginName,
+  SubscribeEvents as ScenarioSubscribeEvents,
+} from "@vnejs/contracts.core.scenario";
+import type { PluginName as LogsPluginName, SubscribeEvents as LogsSubscribeEvents } from "@vnejs/contracts.core.logs";
+import type { Constants, Params, PluginName, SubscribeEvents } from "@vnejs/contracts.views.screens.checkers";
+
+export type CheckersPluginEvents = ModuleComponentsEvents &
+  Record<PluginName, SubscribeEvents> &
+  Record<ScenarioPluginName, ScenarioSubscribeEvents> &
+  Record<LogsPluginName, LogsSubscribeEvents>;
+
+export type CheckersPluginConstants = ModuleComponentsConstants &
+  Record<PluginName, Constants> &
+  Record<ControlsPluginName, ControlsConstants> &
+  Record<ScenarioPluginName, ScenarioConstants>;
+
+export type CheckersPluginSettings = ModuleComponentsSettings;
+
+export type CheckersPluginParams = ModuleComponentsParams & Record<PluginName, Params>;

package/src/utils/ai.ts

@@ -0,0 +1,31 @@
+import { applyMove, getAllMoves, oppositeColor, type CheckersBoard, type CheckersColor, type CheckersMove } from "./board.js";
+
+export type CheckersAiType = "player" | "sacrifice" | "random" | "strong";
+
+export const isHangingMove = (board: CheckersBoard, move: CheckersMove, color: CheckersColor) => {
+  const nextBoard = applyMove(board, move);
+  const opponentMoves = getAllMoves(nextBoard, oppositeColor(color));
+  return opponentMoves.some((candidate) => candidate.captures.length > 0);
+};
+
+const pickRandom = <T>(items: T[]): T | null => {
+  if (items.length === 0) return null;
+  return items[Math.floor(Math.random() * items.length)] ?? null;
+};
+
+export const pickMove = (board: CheckersBoard, color: CheckersColor, type: CheckersAiType): CheckersMove | null => {
+  if (type === "player") return null;
+
+  const moves = getAllMoves(board, color);
+  if (moves.length === 0) return null;
+
+  if (type === "random") return pickRandom(moves);
+
+  const hanging = moves.filter((move) => isHangingMove(board, move, color));
+  const safe = moves.filter((move) => !isHangingMove(board, move, color));
+
+  if (type === "sacrifice") return pickRandom(hanging.length > 0 ? hanging : moves);
+  if (type === "strong") return pickRandom(safe.length > 0 ? safe : hanging.length > 0 ? hanging : moves);
+
+  return pickRandom(moves);
+};

package/src/utils/board.ts

@@ -0,0 +1,252 @@
+export type CheckersColor = "white" | "black";
+
+export type CheckersPiece = {
+  id: string;
+  color: CheckersColor;
+  king: boolean;
+};
+
+export type CheckersPos = {
+  row: number;
+  column: number;
+};
+
+export type CheckersMove = {
+  from: CheckersPos;
+  to: CheckersPos;
+  captures: CheckersPos[];
+};
+
+export type CheckersBoard = (CheckersPiece | null)[][];
+
+export const BOARD_SIZE = 8;
+
+export const oppositeColor = (color: CheckersColor): CheckersColor => (color === "white" ? "black" : "white");
+
+export const isDarkSquare = (row: number, column: number) => (row + column) % 2 === 1;
+
+export const inBounds = (row: number, column: number) => row >= 0 && row < BOARD_SIZE && column >= 0 && column < BOARD_SIZE;
+
+export const cloneBoard = (board: CheckersBoard): CheckersBoard => board.map((row) => row.map((cell) => (cell ? { ...cell } : null)));
+
+export const createInitialBoard = (): CheckersBoard => {
+  const board: CheckersBoard = Array.from({ length: BOARD_SIZE }, () => Array.from({ length: BOARD_SIZE }, () => null));
+  let nextId = 0;
+
+  for (let row = 0; row < BOARD_SIZE; row++) {
+    for (let column = 0; column < BOARD_SIZE; column++) {
+      if (!isDarkSquare(row, column)) continue;
+      if (row <= 2) board[row]![column] = { id: `piece-${nextId++}`, color: "black", king: false };
+      if (row >= 5) board[row]![column] = { id: `piece-${nextId++}`, color: "white", king: false };
+    }
+  }
+
+  return board;
+};
+
+const DIAGONALS = [
+  { dr: -1, dc: -1 },
+  { dr: -1, dc: 1 },
+  { dr: 1, dc: -1 },
+  { dr: 1, dc: 1 },
+] as const;
+
+const forwardRowDelta = (color: CheckersColor) => (color === "white" ? -1 : 1);
+
+const posKey = (pos: CheckersPos) => `${pos.row}:${pos.column}`;
+
+export const samePos = (a: CheckersPos, b: CheckersPos) => a.row === b.row && a.column === b.column;
+
+const getPiece = (board: CheckersBoard, pos: CheckersPos) => board[pos.row]?.[pos.column] ?? null;
+
+const setPiece = (board: CheckersBoard, pos: CheckersPos, piece: CheckersPiece | null) => {
+  board[pos.row]![pos.column] = piece;
+};
+
+const promoteIfNeeded = (piece: CheckersPiece, row: number): CheckersPiece => {
+  if (piece.king) return piece;
+  if (piece.color === "white" && row === 0) return { ...piece, king: true };
+  if (piece.color === "black" && row === BOARD_SIZE - 1) return { ...piece, king: true };
+  return piece;
+};
+
+const collectSimpleMoves = (board: CheckersBoard, from: CheckersPos, piece: CheckersPiece): CheckersMove[] => {
+  const moves: CheckersMove[] = [];
+  const deltas = piece.king ? DIAGONALS : DIAGONALS.filter(({ dr }) => dr === forwardRowDelta(piece.color));
+
+  for (const { dr, dc } of deltas) {
+    if (piece.king) {
+      let row = from.row + dr;
+      let column = from.column + dc;
+      while (inBounds(row, column) && !getPiece(board, { row, column })) {
+        moves.push({ from, to: { row, column }, captures: [] });
+        row += dr;
+        column += dc;
+      }
+      continue;
+    }
+
+    const row = from.row + dr;
+    const column = from.column + dc;
+    if (!inBounds(row, column) || getPiece(board, { row, column })) continue;
+    moves.push({ from, to: { row, column }, captures: [] });
+  }
+
+  return moves;
+};
+
+const collectImmediateCaptures = (board: CheckersBoard, from: CheckersPos, piece: CheckersPiece, capturedKeys: Set<string>): CheckersMove[] => {
+  const moves: CheckersMove[] = [];
+
+  for (const { dr, dc } of DIAGONALS) {
+    if (piece.king) {
+      let row = from.row + dr;
+      let column = from.column + dc;
+      let enemy: CheckersPos | null = null;
+
+      while (inBounds(row, column)) {
+        const occupant = getPiece(board, { row, column });
+
+        if (!occupant) {
+          if (enemy) {
+            moves.push({ from, to: { row, column }, captures: [enemy] });
+          }
+          row += dr;
+          column += dc;
+          continue;
+        }
+
+        if (enemy) break;
+        if (occupant.color === piece.color || capturedKeys.has(posKey({ row, column }))) break;
+
+        enemy = { row, column };
+        row += dr;
+        column += dc;
+      }
+      continue;
+    }
+
+    const mid: CheckersPos = { row: from.row + dr, column: from.column + dc };
+    const to: CheckersPos = { row: from.row + 2 * dr, column: from.column + 2 * dc };
+    if (!inBounds(to.row, to.column) || getPiece(board, to)) continue;
+
+    const victim = getPiece(board, mid);
+    if (!victim || victim.color === piece.color || capturedKeys.has(posKey(mid))) continue;
+
+    moves.push({ from, to, captures: [mid] });
+  }
+
+  return moves;
+};
+
+const expandCaptureChains = (
+  board: CheckersBoard,
+  from: CheckersPos,
+  piece: CheckersPiece,
+  origin: CheckersPos,
+  capturedSoFar: CheckersPos[],
+  capturedKeys: Set<string>,
+): CheckersMove[] => {
+  const immediate = collectImmediateCaptures(board, from, piece, capturedKeys);
+  if (immediate.length === 0) {
+    return capturedSoFar.length > 0 ? [{ from: origin, to: from, captures: capturedSoFar }] : [];
+  }
+
+  const results: CheckersMove[] = [];
+
+  for (const step of immediate) {
+    const nextBoard = cloneBoard(board);
+    setPiece(nextBoard, from, null);
+    for (const capture of step.captures) setPiece(nextBoard, capture, null);
+    const nextPiece = promoteIfNeeded(piece, step.to.row);
+    setPiece(nextBoard, step.to, nextPiece);
+
+    const nextCaptures = [...capturedSoFar, ...step.captures];
+    const nextKeys = new Set(capturedKeys);
+    for (const capture of step.captures) nextKeys.add(posKey(capture));
+
+    results.push(...expandCaptureChains(nextBoard, step.to, nextPiece, origin, nextCaptures, nextKeys));
+  }
+
+  return results;
+};
+
+export const getMovesFrom = (board: CheckersBoard, from: CheckersPos): CheckersMove[] => {
+  const piece = getPiece(board, from);
+  if (!piece) return [];
+
+  const captures = expandCaptureChains(board, from, piece, from, [], new Set());
+  if (captures.length > 0) return captures;
+  return collectSimpleMoves(board, from, piece);
+};
+
+export const getAllMoves = (board: CheckersBoard, color: CheckersColor, onlyFrom?: CheckersPos): CheckersMove[] => {
+  const moves: CheckersMove[] = [];
+
+  for (let row = 0; row < BOARD_SIZE; row++) {
+    for (let column = 0; column < BOARD_SIZE; column++) {
+      if (onlyFrom && !samePos(onlyFrom, { row, column })) continue;
+      const piece = board[row]?.[column];
+      if (!piece || piece.color !== color) continue;
+      moves.push(...getMovesFrom(board, { row, column }));
+    }
+  }
+
+  const hasCapture = moves.some((move) => move.captures.length > 0);
+  return hasCapture ? moves.filter((move) => move.captures.length > 0) : moves;
+};
+
+export const applyMove = (board: CheckersBoard, move: CheckersMove): CheckersBoard => {
+  const next = cloneBoard(board);
+  const piece = getPiece(next, move.from);
+  if (!piece) return next;
+
+  setPiece(next, move.from, null);
+  for (const capture of move.captures) setPiece(next, capture, null);
+  setPiece(next, move.to, promoteIfNeeded(piece, move.to.row));
+  return next;
+};
+
+/** Apply one hop of a multi-capture chain (first capture only). */
+export const applyCaptureStep = (board: CheckersBoard, from: CheckersPos, to: CheckersPos, capture: CheckersPos): CheckersBoard => {
+  const next = cloneBoard(board);
+  const piece = getPiece(next, from);
+  if (!piece) return next;
+
+  setPiece(next, from, null);
+  setPiece(next, capture, null);
+  setPiece(next, to, promoteIfNeeded(piece, to.row));
+  return next;
+};
+
+export const listBoardPieces = (board: CheckersBoard) => {
+  const pieces: Array<CheckersPiece & CheckersPos> = [];
+
+  for (let row = 0; row < BOARD_SIZE; row++) {
+    for (let column = 0; column < BOARD_SIZE; column++) {
+      const piece = board[row]?.[column];
+      if (!piece) continue;
+      pieces.push({ ...piece, row, column });
+    }
+  }
+
+  return pieces;
+};
+
+export const countPieces = (board: CheckersBoard, color: CheckersColor) => {
+  let count = 0;
+  for (const row of board) {
+    for (const cell of row) {
+      if (cell?.color === color) count++;
+    }
+  }
+  return count;
+};
+
+export const getWinner = (board: CheckersBoard, colorToMove: CheckersColor): CheckersColor | null => {
+  if (countPieces(board, colorToMove) === 0) return oppositeColor(colorToMove);
+  if (getAllMoves(board, colorToMove).length === 0) return oppositeColor(colorToMove);
+  return null;
+};
+
+export const findMove = (moves: CheckersMove[], from: CheckersPos, to: CheckersPos) => moves.find((move) => samePos(move.from, from) && samePos(move.to, to));

package/src/utils/checkers.ts

@@ -0,0 +1,96 @@
+import type { CheckersBoard, CheckersColor, CheckersMove, CheckersPiece, CheckersPos } from "./board.js";
+import { BOARD_SIZE, createInitialBoard, getAllMoves, isDarkSquare } 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 const statusForTurn = (turn: CheckersColor, winner: CheckersColor | null = 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,
+}: {
+  board: CheckersBoard;
+  selected?: CheckersPos | null;
+  legalMoves?: CheckersMove[];
+  gridRow?: number | null;
+  gridColumn?: number | null;
+}): CheckersGridItem[] => {
+  const legalKeys = new Set(legalMoves.map((move) => `${move.to.row}:${move.to.column}`));
+  const items: CheckersGridItem[] = [];
+
+  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 = (): Pick<
+  CheckersPluginState,
+  "board" | "turn" | "selected" | "legalMoves" | "winner" | "statusText" | "gridItems" | "gridIndex" | "gridsCount"
+> => {
+  const board = createInitialBoard();
+  const turn: CheckersColor = "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,
+  };
+};