@pompidup/kingdomino-engine 3.0.0 → 3.2.0

package/dist/index.d.ts

@@ -1,86 +1,211 @@
+/**
+ * All possible ground/terrain types in Kingdomino.
+ * Each type can form contiguous properties for scoring.
+ */
 declare const GROUND: readonly ["castle", "wheat", "forest", "sea", "plain", "swamp", "mine"];
+/** Union type of all terrain types */
 type Ground = (typeof GROUND)[number];
+/** Special ground type for empty/unplaced tiles */
 type EmptyGround = "empty";
+/** Number of crowns on a tile (0-3) */
 type Crown = number;
+/**
+ * Represents a single tile with terrain and crowns.
+ * Two tiles form a domino.
+ */
 type Tile = {
+    /** The terrain type of this tile */
     type: Ground;
+    /** Number of crowns (0-3), multiplier for scoring */
     crowns: Crown;
 };
+/**
+ * Represents an empty/unplaced tile on the kingdom grid.
+ */
 type EmptyTile = {
+    /** Always "empty" for unplaced tiles */
     type: EmptyGround;
+    /** Empty tiles have no crowns */
     crowns: 0;
 };
+/**
+ * Represents a domino piece consisting of two connected tiles.
+ * Dominoes are the main game pieces that players place on their kingdoms.
+ */
 type Domino = {
+    /** The left tile of the domino */
     left: Tile;
+    /** The right tile of the domino */
     right: Tile;
+    /** Unique number identifying this domino (1-48 in Classic mode) */
     number: number;
 };
+/**
+ * Represents a domino that has been revealed for player selection.
+ * Contains selection state for the current turn.
+ */
 type RevealsDomino = {
+    /** The actual domino piece */
     domino: Domino;
+    /** Whether this domino has been picked by a lord */
     picked: boolean;
+    /** ID of the lord who picked this domino, or null if unpicked */
     lordId: string | null;
+    /** Display position in the revealed set (for UI ordering) */
     position: number;
 };
 
+/**
+ * Represents a position on the kingdom grid.
+ * Origin (0,0) is at the top-left corner.
+ */
 type Position = {
+    /** Column index (0-8, left to right) */
     x: number;
+    /** Row index (0-8, top to bottom) */
     y: number;
 };
+/**
+ * Rotation angle for domino placement.
+ * - 0: Horizontal, left tile at position, right tile to the east
+ * - 90: Vertical, left tile at position, right tile to the south
+ * - 180: Horizontal, right tile at position, left tile to the east
+ * - 270: Vertical, right tile at position, left tile to the south
+ */
 type Rotation = 0 | 90 | 180 | 270;
+/**
+ * Represents a player's kingdom as a 2D grid of tiles.
+ * The grid is 9x9 to allow for the 5x5 maximum kingdom size
+ * with the castle at any position.
+ */
 type Kingdom = (Tile | EmptyTile)[][];
+/**
+ * The size of the kingdom grid (9x9).
+ * This allows for a 5x5 kingdom with the castle placed anywhere.
+ */
 declare const GRIDSIZE = 9;
+/**
+ * Maximum kingdom size (5x5 in standard rules, 7x7 for Mighty Duel).
+ */
+declare const MAX_KINGDOM_SIZE = 5;
 
+/**
+ * Represents a lord (player token) used for turn order and domino selection.
+ * In games with 2 players, each player has 2 lords.
+ * In games with 3-4 players, each player has 1 lord.
+ */
 type Lord = {
+    /** Unique identifier for this lord */
     id: string;
+    /** ID of the player who owns this lord */
     playerId: string;
+    /** Whether this lord has finished their turn */
     turnEnded: boolean;
+    /** Whether this lord has picked a domino this round */
     hasPick: boolean;
+    /** Whether this lord has placed/discarded a domino this round */
     hasPlace: boolean;
+    /** The domino this lord picked (if any) */
     dominoPicked?: Domino;
 };
 
+/**
+ * Represents a game mode with its configuration.
+ * Currently only "Classic" mode is available.
+ */
 type GameMode = {
+    /** Name of the game mode (e.g., "Classic") */
     name: string;
+    /** Description of the game mode */
     description: string;
 };
 
 type ObjectValues<T> = T[keyof T];
 
+/**
+ * Represents a player in the game.
+ */
 type Player = {
+    /** Unique identifier for the player */
     id: string;
+    /** Display name of the player */
     name: string;
+    /** The player's kingdom grid where dominoes are placed */
     kingdom: Kingdom;
+    /** If set, this player is controlled by a bot with the named strategy */
+    bot?: {
+        strategyName: string;
+    };
 };
+/**
+ * Payload for creating a new player.
+ */
 type PlayerPayload = {
+    /** Display name for the player (minimum 3 characters) */
     name: string;
 };
+/** Array of player creation payloads */
 type PlayersPayload = PlayerPayload[];
+/** Array of players */
 type Players = Player[];
+/**
+ * Available actions a player can perform during their turn.
+ */
 declare const playerActions: {
+    /** Place a previously picked domino on the kingdom */
     readonly placeDomino: "placeDomino";
+    /** Pick a domino from the revealed set */
     readonly pickDomino: "pickDomino";
+    /** Pass/discard when no valid placement exists */
     readonly pass: "pass";
 };
+/** Union type of all player actions */
 type PlayerActions = ObjectValues<typeof playerActions>;
 
+/**
+ * Basic rules that vary based on player count.
+ */
 type BasicRules = {
+    /** Number of lords per player */
     lords: number;
+    /** Maximum number of dominoes in the game */
     maxDominoes: number;
+    /** Number of dominoes revealed each turn */
     dominoesPerTurn: number;
+    /** Maximum number of turns in the game */
     maxTurns: number;
+    /** Maximum kingdom grid size (5 for standard, 7 for Mighty Duel) */
+    maxKingdomSize: number;
 };
+/**
+ * Optional extra rules that modify gameplay and scoring.
+ */
 type ExtraRule = {
+    /** Name of the rule (e.g., "The middle Kingdom", "Harmony") */
     name: string;
+    /** Description of what the rule does */
     description: string;
+    /** Game modes this rule is compatible with */
     mode: GameMode[];
+    /** Maximum number of players for this rule (optional) */
     playersLimit?: number;
 };
+/**
+ * Complete rules configuration loaded from data source.
+ */
 type Rules = {
+    /** Basic rules indexed by player count (1-4) */
     basic: Record<number, BasicRules>;
+    /** Available extra rules */
     extraRules: ExtraRule[];
 };
+/**
+ * Rules selected for a specific game instance.
+ */
 type SelectedRules = {
+    /** The basic rules for the current player count */
     basic: BasicRules;
+    /** Extra rules enabled for this game */
     extra: ExtraRule[];
 };
 
@@ -94,60 +219,147 @@ interface Err {
     readonly error: string;
 }
 
+/**
+ * Represents the complete state of a Kingdomino game.
+ * This is the main aggregate containing all game data.
+ */
 type Game = {
+    /** Unique identifier for the game */
     id: string;
+    /** Remaining dominoes in the draw pile */
     dominoes: Domino[];
+    /** Currently revealed dominoes available for picking */
     currentDominoes: RevealsDomino[];
+    /** Players participating in the game with their kingdoms */
     players: Player[];
+    /** Lords (player tokens) used for turn order and domino selection */
     lords: Lord[];
+    /** Current turn number (1-based) */
     turn: number;
+    /** Next required action or game step */
     nextAction: NextAction | NextStep;
+    /** Active rules for this game */
     rules: SelectedRules;
+    /** Game mode being played */
     mode: GameMode;
+    /** Optional seed for deterministic shuffle (replays, sharing) */
+    seed?: string;
 };
+/**
+ * Available game steps representing phases of game setup and completion.
+ */
 declare const gameSteps: {
+    /** Waiting for players to be added */
     readonly addPlayers: "addPlayers";
+    /** Optional rules selection phase */
     readonly options: "options";
+    /** Ready to start the game */
     readonly start: "start";
+    /** Game has ended, results available */
     readonly result: "result";
 };
+/** Union type of all possible game steps */
 type GameSteps = ObjectValues<typeof gameSteps>;
+/**
+ * Represents a player action that needs to be performed.
+ * Used during active gameplay.
+ */
 type NextAction = {
+    /** Discriminator for action type */
     type: "action";
+    /** ID of the lord who must perform the action */
     nextLord: string;
+    /** The action the lord must perform */
     nextAction: PlayerActions;
 };
+/**
+ * Represents a game phase transition.
+ * Used during setup and game end.
+ */
 type NextStep = {
+    /** Discriminator for step type */
     type: "step";
+    /** The current game step/phase */
     step: GameSteps;
 };
+/** Game state where a player action is required */
 type GameWithNextAction = Game & {
     nextAction: NextAction;
 };
+/** Game state where a phase transition is occurring */
 type GameWithNextStep = Game & {
     nextAction: NextStep;
 };
+/** Union of all possible game states */
 type GameState = GameWithNextAction | GameWithNextStep;
+/** Result wrapper for game state operations */
 type GameStateResult = Result<GameState>;
+/**
+ * Type guard to check if the game requires a player action.
+ * @param game - The game state to check
+ * @returns True if the game is waiting for a player action
+ */
 declare const isGameWithNextAction: (game: GameWithNextAction | GameWithNextStep) => game is GameWithNextAction;
+/**
+ * Type guard to check if the game is in a phase transition.
+ * @param game - The game state to check
+ * @returns True if the game is transitioning between phases
+ */
 declare const isGameWithNextStep: (game: GameWithNextAction | GameWithNextStep) => game is GameWithNextStep;
+/**
+ * Represents the score calculation for a kingdom.
+ */
 type Score = {
+    /** Total points earned */
     points: number;
+    /** Size of the largest contiguous property */
     maxPropertiesSize: number;
+    /** Total number of crowns in the kingdom */
     totalCrowns: number;
 };
+/**
+ * Score result for a specific player.
+ */
 type ScoreResult = {
+    /** Player's unique identifier */
     playerId: string;
+    /** Player's display name */
     playerName: string;
+    /** Detailed score breakdown */
     details: Score;
 };
+/**
+ * Final result including ranking position.
+ */
 type FinalResult = ScoreResult & {
+    /** Player's final position (1 = winner) */
     position: number;
 };
+/** Game state with final results calculated */
 type GameWithResults = Game & {
     result: FinalResult[];
 };
 
+/**
+ * Severity level for a validation issue.
+ * - "error": The state is corrupted and cannot be used safely.
+ * - "warning": The state is suspicious but may still work.
+ */
+type ValidationSeverity = "error" | "warning";
+/**
+ * Describes a single validation issue found in a game state.
+ */
+type ValidationIssue = {
+    /** JSON-path-like location of the issue (e.g. "players[0].kingdom") */
+    path: string;
+    /** Machine-readable code identifying the kind of issue */
+    code: string;
+    /** Human-readable description of the issue */
+    message: string;
+    /** Severity level */
+    severity: ValidationSeverity;
+};
+
 type GetModesCommand = Record<string, never>;
 
 type GetExtraRulesCommand = {
@@ -157,11 +369,21 @@ type GetExtraRulesCommand = {
 
 type CreateGameCommand = {
     mode: string;
+    seed?: string;
 };
 
+/**
+ * Input for a single player: either a name string (human) or an object with bot config.
+ */
+type PlayerInput = string | {
+    name: string;
+    bot?: {
+        strategyName: string;
+    };
+};
 type AddPlayersCommand = {
     game: GameState;
-    players: string[];
+    players: PlayerInput[];
 };
 
 type AddExtraRulesCommand = {
@@ -199,30 +421,943 @@ type CalculateScoreCommand = {
     kingdom: Kingdom;
 };
 
+/**
+ * Command to get all valid placements for a domino on a kingdom.
+ */
+type GetValidPlacementsCommand = {
+    /** The kingdom grid to check placements on */
+    kingdom: Kingdom;
+    /** The domino to find placements for */
+    domino: Domino;
+    /** Maximum kingdom size (default: 5, use 7 for Mighty Duel) */
+    maxKingdomSize?: number;
+};
+
+/**
+ * Command to check if a domino can be placed anywhere on a kingdom.
+ */
+type CanPlaceDominoCommand = {
+    /** The kingdom grid to check */
+    kingdom: Kingdom;
+    /** The domino to check placement for */
+    domino: Domino;
+    /** Maximum kingdom size (default: 5, use 7 for Mighty Duel) */
+    maxKingdomSize?: number;
+};
+
+/**
+ * Command to serialize a game state to JSON.
+ */
+type SerializeGameCommand = {
+    /** The game state to serialize */
+    game: GameState;
+};
+/**
+ * Command to deserialize a game state from JSON.
+ */
+type DeserializeGameCommand = {
+    /** The JSON string to deserialize */
+    json: string;
+};
+
+type GetDynastyResultCommand = {
+    games: GameWithResults[];
+};
+
+/**
+ * Represents a valid placement position with rotation.
+ */
+type ValidPlacement = {
+    position: Position;
+    rotation: Rotation;
+};
+
+type DynastyResult = {
+    playerId: string;
+    playerName: string;
+    totalPoints: number;
+    gamesPoints: number[];
+    position: number;
+};
+
+/**
+ * The main interface for interacting with the Kingdomino game engine.
+ *
+ * This interface provides all methods needed to manage a complete game lifecycle,
+ * from creation to scoring. Each method follows a command pattern and returns
+ * an updated game state.
+ *
+ * @example
+ * ```typescript
+ * import { createGameEngine, isGameWithNextAction } from '@pompidup/kingdomino-engine';
+ *
+ * const engine = createGameEngine({});
+ * let game = engine.createGame({ mode: 'Classic' });
+ * game = engine.addPlayers({ game, players: ['Alice', 'Bob'] });
+ * game = engine.startGame({ game });
+ *
+ * while (isGameWithNextAction(game)) {
+ *   // Handle player actions...
+ * }
+ *
+ * const results = engine.getResults({ game });
+ * ```
+ */
 type GameEngine = {
+    /**
+     * Retrieves all available game modes.
+     * @param command - Empty command object
+     * @returns Array of available game modes (e.g., 'Classic')
+     */
     getModes: (command: GetModesCommand) => GameMode[];
+    /**
+     * Retrieves available extra rules for a specific mode and player count.
+     * @param command - Contains mode name and number of players
+     * @returns Array of applicable extra rules
+     */
     getExtraRules: (command: GetExtraRulesCommand) => ExtraRule[];
+    /**
+     * Creates a new game instance with the specified mode.
+     * This is the first step in setting up a game.
+     * @param command - Contains the game mode name
+     * @returns Game state with next step 'addPlayers'
+     */
     createGame: (command: CreateGameCommand) => GameWithNextStep;
+    /**
+     * Adds players to the game and initializes their kingdoms.
+     * Each player receives an empty kingdom with a castle at the center.
+     * @param command - Contains game state and array of player names (1-4 players)
+     * @returns Game state with next step 'options' or 'start'
+     * @throws Error if player count is invalid or names are too short
+     */
     addPlayers: (command: AddPlayersCommand) => GameWithNextStep;
+    /**
+     * Adds optional extra rules to modify gameplay.
+     * @param command - Contains game state and array of extra rule names
+     * @returns Game state with next step 'start'
+     */
     addExtraRules: (command: AddExtraRulesCommand) => GameWithNextStep;
+    /**
+     * Starts the game, initializing lords, shuffling dominoes, and revealing the first set.
+     * @param command - Contains the game state
+     * @returns Game state with first player action required
+     */
     startGame: (command: StartGameCommand) => GameWithNextAction;
+    /**
+     * Allows a lord to choose a domino from the currently revealed set.
+     * The chosen domino is reserved for that lord to place later.
+     * @param command - Contains game state, lord ID, and domino number to pick
+     * @returns Updated game state with next action
+     */
     chooseDomino: (command: ChooseDominoCommand) => GameWithNextAction;
+    /**
+     * Places a domino on the lord's kingdom at the specified position and rotation.
+     * The domino must be adjacent to an existing tile and match terrain types.
+     * @param command - Contains game state, lord ID, position {x, y}, and rotation (0, 90, 180, 270)
+     * @returns Updated game state (may transition to 'result' step if game ends)
+     * @throws Error if placement is invalid
+     */
     placeDomino: (command: PlaceDominoCommand) => GameState;
+    /**
+     * Discards a domino when no valid placement exists.
+     * The lord forfeits placing the domino this turn.
+     * @param command - Contains game state and lord ID
+     * @returns Updated game state with next action
+     */
     discardDomino: (command: DiscardDominoCommand) => GameState;
+    /**
+     * Calculates and returns final results after the game ends.
+     * Applies extra rule bonuses and ranks players.
+     * @param command - Contains the final game state
+     * @returns Game state with complete results including positions
+     */
     getResults: (command: GetResultCommand) => GameWithResults;
+    /**
+     * Calculates the score for a single kingdom.
+     * Useful for showing live scores during gameplay.
+     * @param command - Contains the kingdom grid to score
+     * @returns Score with points, largest property size, and total crowns
+     */
     calculateScore: (command: CalculateScoreCommand) => Score;
+    /**
+     * Finds all valid placements for a domino on a kingdom.
+     * Useful for AI players or showing available moves to human players.
+     * @param command - Contains kingdom and domino to check
+     * @returns Array of valid position/rotation combinations
+     */
+    getValidPlacements: (command: GetValidPlacementsCommand) => ValidPlacement[];
+    /**
+     * Checks if a domino can be placed anywhere on a kingdom.
+     * Quick check before deciding to discard.
+     * @param command - Contains kingdom and domino to check
+     * @returns True if at least one valid placement exists
+     */
+    canPlaceDomino: (command: CanPlaceDominoCommand) => boolean;
+    /**
+     * Serializes the game state to a JSON string for persistence.
+     * @param command - Contains the game state to serialize
+     * @returns JSON string representation of the game
+     */
+    serialize: (command: SerializeGameCommand) => string;
+    /**
+     * Deserializes a JSON string back to a game state.
+     * @param command - Contains the JSON string to parse
+     * @returns The restored game state
+     * @throws Error if the JSON is invalid or incompatible
+     */
+    deserialize: (command: DeserializeGameCommand) => GameState;
+    /**
+     * Calculates dynasty results from multiple completed games.
+     * Sum total points across games, highest total wins.
+     * @param command - Contains array of completed games with results
+     * @returns Ranked dynasty results per player
+     */
+    getDynastyResults: (command: GetDynastyResultCommand) => DynastyResult[];
+};
+
+/**
+ * Error codes for domain-level errors.
+ * These codes can be used for i18n and programmatic error handling.
+ */
+declare const ErrorCode: {
+    readonly INVALID_STEP: "INVALID_STEP";
+    readonly STEP_EXECUTION_FAILED: "STEP_EXECUTION_FAILED";
+    readonly ACTION_EXECUTION_FAILED: "ACTION_EXECUTION_FAILED";
+    readonly LORD_NOT_FOUND: "LORD_NOT_FOUND";
+    readonly PLAYER_NOT_FOUND: "PLAYER_NOT_FOUND";
+    readonly DOMINO_NOT_FOUND: "DOMINO_NOT_FOUND";
+    readonly MODE_NOT_FOUND: "MODE_NOT_FOUND";
+    readonly INVALID_PLAYER_COUNT: "INVALID_PLAYER_COUNT";
+    readonly INVALID_PLAYER_NAME: "INVALID_PLAYER_NAME";
+    readonly INVALID_PLACEMENT: "INVALID_PLACEMENT";
+    readonly PLACEMENT_NOT_EMPTY: "PLACEMENT_NOT_EMPTY";
+    readonly PLACEMENT_NOT_ADJACENT: "PLACEMENT_NOT_ADJACENT";
+    readonly PLACEMENT_INVALID_TERRAIN: "PLACEMENT_INVALID_TERRAIN";
+    readonly PLACEMENT_OUT_OF_BOUNDS: "PLACEMENT_OUT_OF_BOUNDS";
+    readonly PLACEMENT_EXCEEDS_KINGDOM_SIZE: "PLACEMENT_EXCEEDS_KINGDOM_SIZE";
+    readonly NOT_YOUR_TURN: "NOT_YOUR_TURN";
+    readonly CANNOT_PICK: "CANNOT_PICK";
+    readonly CANNOT_PLACE: "CANNOT_PLACE";
+    readonly DOMINO_ALREADY_PICKED: "DOMINO_ALREADY_PICKED";
+    readonly UNDO_UNAVAILABLE: "UNDO_UNAVAILABLE";
+    readonly REDO_UNAVAILABLE: "REDO_UNAVAILABLE";
+};
+type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Structured domain error with code and context.
+ */
+interface DomainError {
+    /** Error code for programmatic handling */
+    code: ErrorCodeType;
+    /** Human-readable error message */
+    message: string;
+    /** Optional context data for debugging */
+    context?: Record<string, unknown>;
+}
+/**
+ * Creates a domain error object.
+ */
+declare const createDomainError: (code: ErrorCodeType, message: string, context?: Record<string, unknown>) => DomainError;
+/**
+ * Base class for domain errors thrown by handlers.
+ */
+declare class DomainException extends Error {
+    readonly code: ErrorCodeType;
+    readonly context?: Record<string, unknown>;
+    constructor(error: DomainError);
+}
+/**
+ * Error thrown when the game is in an invalid step for the requested action.
+ */
+declare class InvalidStepError extends DomainException {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a step execution fails.
+ */
+declare class StepExecutionError extends DomainException {
+    constructor(message: string, code?: ErrorCodeType, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when an action execution fails.
+ */
+declare class ActionExecutionError extends DomainException {
+    constructor(message: string, code?: ErrorCodeType, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a required entity is not found.
+ */
+declare class NotFoundError extends DomainException {
+    constructor(message: string, code?: ErrorCodeType, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when validation fails.
+ */
+declare class ValidationError extends DomainException {
+    constructor(message: string, code: ErrorCodeType, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when undo is requested but no previous state exists.
+ */
+declare class UndoError extends DomainException {
+    constructor(message?: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when redo is requested but no future state exists.
+ */
+declare class RedoError extends DomainException {
+    constructor(message?: string, context?: Record<string, unknown>);
+}
+
+/**
+ * Translation keys for internationalization support.
+ * Use these keys instead of hardcoded strings for translatable content.
+ */
+declare const TranslationKey: {
+    readonly ERROR_INVALID_STEP: "error.invalidStep";
+    readonly ERROR_STEP_EXECUTION_FAILED: "error.stepExecutionFailed";
+    readonly ERROR_ACTION_EXECUTION_FAILED: "error.actionExecutionFailed";
+    readonly ERROR_LORD_NOT_FOUND: "error.lordNotFound";
+    readonly ERROR_PLAYER_NOT_FOUND: "error.playerNotFound";
+    readonly ERROR_DOMINO_NOT_FOUND: "error.dominoNotFound";
+    readonly ERROR_MODE_NOT_FOUND: "error.modeNotFound";
+    readonly ERROR_INVALID_PLACEMENT: "error.invalidPlacement";
+    readonly ERROR_PLACEMENT_NOT_EMPTY: "error.placementNotEmpty";
+    readonly ERROR_PLACEMENT_NOT_ADJACENT: "error.placementNotAdjacent";
+    readonly ERROR_PLACEMENT_INVALID_TERRAIN: "error.placementInvalidTerrain";
+    readonly ERROR_PLACEMENT_OUT_OF_BOUNDS: "error.placementOutOfBounds";
+    readonly ERROR_PLACEMENT_EXCEEDS_KINGDOM_SIZE: "error.placementExceedsKingdomSize";
+    readonly ERROR_NOT_YOUR_TURN: "error.notYourTurn";
+    readonly ERROR_CANNOT_PICK: "error.cannotPick";
+    readonly ERROR_CANNOT_PLACE: "error.cannotPlace";
+    readonly ERROR_DOMINO_ALREADY_PICKED: "error.dominoAlreadyPicked";
+    readonly ERROR_INVALID_PLAYER_COUNT: "error.invalidPlayerCount";
+    readonly ERROR_INVALID_PLAYER_NAME: "error.invalidPlayerName";
+    readonly ERROR_UNDO_UNAVAILABLE: "error.undoUnavailable";
+    readonly ERROR_REDO_UNAVAILABLE: "error.redoUnavailable";
+    readonly MODE_CLASSIC: "mode.classic";
+    readonly RULE_MIDDLE_KINGDOM: "rule.middleKingdom";
+    readonly RULE_HARMONY: "rule.harmony";
+    readonly GROUND_CASTLE: "ground.castle";
+    readonly GROUND_WHEAT: "ground.wheat";
+    readonly GROUND_FOREST: "ground.forest";
+    readonly GROUND_SEA: "ground.sea";
+    readonly GROUND_PLAIN: "ground.plain";
+    readonly GROUND_SWAMP: "ground.swamp";
+    readonly GROUND_MINE: "ground.mine";
+    readonly PHASE_ADD_PLAYERS: "phase.addPlayers";
+    readonly PHASE_OPTIONS: "phase.options";
+    readonly PHASE_START: "phase.start";
+    readonly PHASE_RESULT: "phase.result";
+    readonly ACTION_PICK_DOMINO: "action.pickDomino";
+    readonly ACTION_PLACE_DOMINO: "action.placeDomino";
+    readonly ACTION_PASS: "action.pass";
 };
+type TranslationKeyType = (typeof TranslationKey)[keyof typeof TranslationKey];
+/**
+ * Default English translations.
+ */
+declare const defaultTranslations: Record<TranslationKeyType, string>;
+/**
+ * Maps ErrorCode values to their corresponding TranslationKey values.
+ * Used by handlers to translate error codes into localized messages.
+ */
+declare const errorCodeToTranslationKey: Record<ErrorCodeType, TranslationKeyType>;
+/**
+ * Translates an error code to a localized message.
+ * Convenience function combining errorCodeToTranslationKey lookup and translation.
+ */
+declare const translateErrorCode: (translator: Translator, code: ErrorCodeType, params?: Record<string, string | number>) => string;
+/**
+ * Translator interface for custom translations.
+ */
+interface Translator {
+    /**
+     * Translate a key to the current language.
+     * @param key - The translation key
+     * @param params - Optional parameters for interpolation
+     * @returns The translated string
+     */
+    t(key: TranslationKeyType, params?: Record<string, string | number>): string;
+}
+/**
+ * Creates a translator with the provided translations.
+ * Falls back to default English translations for missing keys.
+ *
+ * @param translations - Custom translations to use
+ * @returns A translator instance
+ */
+declare const createTranslator: (translations?: Partial<Record<TranslationKeyType, string>>) => Translator;
+/**
+ * Default translator using English translations.
+ */
+declare const defaultTranslator: Translator;
+
+type Logger = Readonly<{
+    info: (message: string) => void;
+    error: (message: string) => void;
+}>;
 
 type ShuffleMethod = <T>(array: T[]) => T[];
 
 type UuidMethod = () => string;
 
+/**
+ * Debug log verbosity level.
+ * - `minimal`: method name + phase only
+ * - `standard`: + game state summary + key params
+ * - `verbose`: + full game state JSON dump
+ */
+type DebugLogLevel = "minimal" | "standard" | "verbose";
+/**
+ * Summary of the current game state, extracted for quick inspection.
+ */
+type GameStateSummary = {
+    gameId: string;
+    turn: number;
+    nextAction: string;
+    playersCount: number;
+    dominoesRemaining: number;
+    currentDominoesCount: number;
+    lordsCount: number;
+};
+/**
+ * A single debug log entry emitted by the debug wrapper.
+ */
+type DebugLogEntry = {
+    timestamp: string;
+    method: string;
+    phase: "before" | "after" | "error";
+    summary: GameStateSummary | null;
+    params?: Record<string, unknown>;
+    error?: string;
+    durationMs?: number;
+    fullState?: GameState;
+};
+/**
+ * Custom debug logger interface.
+ * Consumers can provide their own to redirect debug output.
+ */
+type DebugLogger = {
+    log: (entry: DebugLogEntry) => void;
+};
+/**
+ * Configuration for the debug wrapper.
+ */
+type DebugOptions = {
+    /** Custom debug logger. Defaults to console-based logger. */
+    logger?: DebugLogger;
+    /** Verbosity level. Defaults to "standard". */
+    level?: DebugLogLevel;
+};
+/**
+ * Extracts a concise summary from a game state object.
+ */
+declare const summarizeGameState: (game: GameState) => GameStateSummary;
+/**
+ * Wraps a GameEngine to emit detailed debug log entries before and after each method call.
+ * Useful for UI developers to inspect engine behavior at every step.
+ *
+ * @param engine - The base game engine to wrap
+ * @param options - Debug configuration (logger, verbosity level)
+ * @returns A new GameEngine that emits debug logs
+ *
+ * @example
+ * ```typescript
+ * const debugEngine = wrapWithDebug(engine, { level: "verbose" });
+ * let game = debugEngine.createGame({ mode: "Classic" });
+ * // Console: [KDomino:Debug] ... BEFORE createGame
+ * // Console: [KDomino:Debug] ... AFTER  createGame | turn=0 ...
+ * ```
+ */
+declare const wrapWithDebug: (engine: GameEngine, options?: DebugOptions) => GameEngine;
+
+/**
+ * Optional callbacks for game events.
+ * Consumers provide these to react to state changes (UI updates, animations, logging).
+ * All callbacks are optional — only the ones you provide will be called.
+ *
+ * @example
+ * ```typescript
+ * const engine = createGameEngine({
+ *   events: {
+ *     onDominoPlaced: ({ game, lordId }) => {
+ *       console.log(`Lord ${lordId} placed a domino`);
+ *       animatePlacement(game);
+ *     },
+ *     onTurnEnd: ({ turn }) => console.log(`Turn ${turn} ended`),
+ *     onGameEnd: () => showResultsScreen(),
+ *   },
+ * });
+ * ```
+ */
+type GameEventCallbacks = {
+    /** Called after a new game is created */
+    onGameCreated?: (event: {
+        game: GameWithNextStep;
+    }) => void;
+    /** Called after players are added to the game */
+    onPlayersAdded?: (event: {
+        game: GameWithNextStep;
+    }) => void;
+    /** Called after the game starts (first dominoes revealed) */
+    onGameStarted?: (event: {
+        game: GameWithNextAction;
+    }) => void;
+    /** Called after a lord picks a domino */
+    onDominoPicked?: (event: {
+        game: GameState;
+        lordId: string;
+        dominoNumber: number;
+    }) => void;
+    /** Called after a lord places a domino on their kingdom */
+    onDominoPlaced?: (event: {
+        game: GameState;
+        lordId: string;
+    }) => void;
+    /** Called after a lord discards a domino (no valid placement) */
+    onDominoDiscarded?: (event: {
+        game: GameState;
+        lordId: string;
+    }) => void;
+    /** Called when a new turn begins */
+    onTurnStart?: (event: {
+        game: GameState;
+        turn: number;
+    }) => void;
+    /** Called when a turn ends (all lords have played) */
+    onTurnEnd?: (event: {
+        game: GameState;
+        turn: number;
+    }) => void;
+    /** Called when the game reaches the result phase */
+    onGameEnd?: (event: {
+        game: GameState;
+    }) => void;
+};
+/**
+ * Wraps a GameEngine to emit event callbacks after each state-changing method.
+ * Read-only methods (getModes, calculateScore, etc.) are passed through unchanged.
+ *
+ * Derived events:
+ * - `onTurnEnd` + `onTurnStart`: emitted when `chooseDomino` causes a turn increment
+ * - `onGameEnd`: emitted when `placeDomino` or `discardDomino` transitions to the "result" step
+ *
+ * @param engine - The base game engine to wrap
+ * @param callbacks - Optional event callbacks
+ * @returns A new GameEngine that emits events
+ */
+declare const wrapWithEvents: (engine: GameEngine, callbacks: GameEventCallbacks) => GameEngine;
+
+/**
+ * Configuration options for the game engine.
+ */
 type EngineConfig = {
+    /** Custom UUID generation method. Defaults to crypto.randomUUID() */
     uuidMethod?: UuidMethod;
+    /** Custom shuffle method. Defaults to Fisher-Yates algorithm */
     shuffleMethod?: ShuffleMethod;
+    /** Enable console logging. Defaults to false */
     logging?: boolean;
+    /** Custom logger instance. When provided, takes precedence over 'logging' option */
+    logger?: Logger;
+    /** Optional event callbacks for UI/animation integration */
+    events?: GameEventCallbacks;
+    /** Custom translator for i18n error messages. Defaults to English */
+    translator?: Translator;
+    /** Enable debug mode with detailed logging. Pass `true` for defaults or a `DebugOptions` object. */
+    debug?: boolean | DebugOptions;
+};
+
+/**
+ * Validates the integrity of a game state.
+ *
+ * Use this function after deserializing or restoring a persisted game state
+ * to detect corruptions before resuming gameplay.
+ *
+ * @param game - The game state to validate
+ * @returns An array of validation issues. Empty array means the state is valid.
+ *
+ * @example
+ * ```typescript
+ * const issues = validateGameState(game);
+ * if (issues.length > 0) {
+ *   console.error("Game state is corrupted:", issues);
+ * }
+ * ```
+ */
+declare const validateGameState: (game: Game) => ValidationIssue[];
+
+type DominoesRepository = {
+    getForMode: (mode: GameMode) => Domino[] | [];
+};
+
+type ModeRepository = {
+    getAvailables: () => GameMode[];
+};
+
+type RuleRepository = {
+    getAll: () => Rules;
+    getAllExtra: () => ExtraRule[];
 };
 
+/**
+ * Context provided to a bot strategy when choosing a domino to pick.
+ */
+type PickContext = {
+    game: GameWithNextAction;
+    lordId: string;
+    availableDominoes: RevealsDomino[];
+};
+/**
+ * Context provided to a bot strategy when choosing where to place a domino.
+ */
+type PlaceContext = {
+    game: GameWithNextAction;
+    lordId: string;
+    domino: Domino;
+    kingdom: Kingdom;
+    validPlacements: ValidPlacement[];
+};
+/**
+ * A bot strategy that decides which domino to pick and where to place it.
+ * Strategies are stateless — all information comes from the context.
+ */
+type BotStrategy = {
+    chooseDomino: (context: PickContext) => number;
+    choosePlacement: (context: PlaceContext) => ValidPlacement | null;
+};
+/**
+ * Bot strategy that makes random choices.
+ * Picks a random available domino and places it at a random valid position.
+ */
+declare const randomStrategy: BotStrategy;
+/**
+ * Bot strategy that maximizes the immediate score.
+ * Evaluates every valid placement and picks the one yielding the highest score.
+ * When picking a domino, simulates the best placement for each option.
+ */
+declare const greedyStrategy: BotStrategy;
+/**
+ * Bot strategy with 1-turn lookahead.
+ * When making decisions, considers not just the immediate score but also
+ * the best possible score achievable in the next turn by peeking at
+ * the upcoming domino batch from the draw pile.
+ */
+declare const advancedStrategy: BotStrategy;
+/**
+ * Bot strategy that searches the game tree with beam-search pruning.
+ * Explores all remaining turns, but limits the number of placements
+ * evaluated per domino to the top candidates (by greedy score).
+ * Since kingdoms are independent, this is a solo optimization (no adversarial search needed).
+ */
+declare const expertStrategy: BotStrategy;
+/**
+ * Executes a single bot turn using the given strategy and engine.
+ * Reads the current game state to determine the required action,
+ * asks the strategy for a decision, and executes it via the engine.
+ *
+ * @param engine - The game engine instance
+ * @param game - Current game state (must require a player action)
+ * @param strategy - The bot strategy to use for decisions
+ * @returns Updated game state after the bot's action
+ */
+declare const playBotTurn: (engine: GameEngine, game: GameWithNextAction, strategy: BotStrategy) => GameState;
+/**
+ * Checks if the current turn belongs to a bot player.
+ */
+declare const isBotTurn: (game: GameWithNextAction) => boolean;
+/**
+ * Plays all consecutive bot turns until a human turn or game end is reached.
+ * Resolves each bot's strategy by name from the registry (or custom map).
+ * Falls back to randomStrategy if the strategy name is not found.
+ *
+ * @param engine - The game engine instance
+ * @param game - Current game state
+ * @param customStrategies - Optional custom strategy map (name → BotStrategy)
+ * @returns Updated game state paused at the next human turn or game end
+ */
+declare const playBotTurns: (engine: GameEngine, game: GameState, customStrategies?: Record<string, BotStrategy>) => GameState;
+
+/**
+ * Built-in strategy names.
+ */
+type StrategyName = "random" | "greedy" | "advanced" | "expert";
+/**
+ * Resolves a strategy by name. Checks custom strategies first, then defaults.
+ * Returns undefined if the name is not found.
+ */
+declare const getStrategy: (name: string, custom?: Record<string, BotStrategy>) => BotStrategy | undefined;
+/**
+ * Returns the list of built-in strategy names.
+ */
+declare const getStrategyNames: () => string[];
+
+/**
+ * The types of state-changing actions that can be recorded.
+ */
+type ActionType = "createGame" | "addPlayers" | "addExtraRules" | "startGame" | "chooseDomino" | "placeDomino" | "discardDomino";
+/**
+ * Payload types for each action, containing only the command parameters
+ * (excluding the game state, which is too large to store).
+ */
+type ActionPayloadMap = {
+    createGame: {
+        mode: string;
+        seed?: string;
+    };
+    addPlayers: {
+        players: PlayerInput[];
+    };
+    addExtraRules: {
+        extraRules: string[];
+    };
+    startGame: Record<string, never>;
+    chooseDomino: {
+        lordId: string;
+        dominoPick: number;
+    };
+    placeDomino: {
+        lordId: string;
+        position: Position;
+        rotation: Rotation;
+    };
+    discardDomino: {
+        lordId: string;
+    };
+};
+/**
+ * A single recorded action in the game log.
+ */
+type ActionEntry<T extends ActionType = ActionType> = {
+    /** Auto-incrementing index (0-based) */
+    id: number;
+    /** Timestamp when the action was recorded (Date.now()) */
+    timestamp: number;
+    /** The type of action performed */
+    action: T;
+    /** Command parameters (excludes game state) */
+    payload: ActionPayloadMap[T];
+    /** Turn number after the action was applied */
+    turn: number;
+};
+/**
+ * An immutable log of all actions performed during a game.
+ * Can be used to replay a game or analyze player decisions.
+ *
+ * @example
+ * ```typescript
+ * const { engine, getLog } = wrapWithActionLog(baseEngine);
+ * let game = engine.createGame({ mode: 'Classic' });
+ * game = engine.addPlayers({ game, players: ['Alice', 'Bob'] });
+ * // ... play the game ...
+ * const log = getLog();
+ * console.log(log.entries); // all actions recorded
+ * ```
+ */
+type GameActionLog = {
+    /** The game ID this log belongs to */
+    gameId: string;
+    /** Immutable array of recorded actions */
+    entries: readonly ActionEntry[];
+};
+/**
+ * Creates an empty action log for a game.
+ */
+declare const createActionLog: (gameId: string) => GameActionLog;
+/**
+ * Appends an action to the log (immutable — returns a new log).
+ */
+declare const appendAction: (log: GameActionLog, entry: Omit<ActionEntry, "id" | "timestamp">) => GameActionLog;
+/**
+ * Returns all entries in the log.
+ */
+declare const getActions: (log: GameActionLog) => readonly ActionEntry[];
+/**
+ * Returns entries filtered by action type.
+ */
+declare const getActionsByType: (log: GameActionLog, type: ActionType) => readonly ActionEntry[];
+/**
+ * Returns entries filtered by turn number.
+ */
+declare const getActionsByTurn: (log: GameActionLog, turn: number) => readonly ActionEntry[];
+/**
+ * Wraps a GameEngine to automatically record every state-changing action.
+ * Read-only methods are passed through unchanged.
+ *
+ * @param engine - The base game engine to wrap
+ * @returns An object with the wrapped engine and a getLog() accessor
+ *
+ * @example
+ * ```typescript
+ * const { engine: logged, getLog } = wrapWithActionLog(baseEngine);
+ * let game = logged.createGame({ mode: 'Classic' });
+ * // ... play ...
+ * const log = getLog(); // retrieve the full action log
+ * ```
+ */
+declare const wrapWithActionLog: (engine: GameEngine) => {
+    engine: GameEngine;
+    getLog: () => GameActionLog;
+};
+/**
+ * Replays all actions from a log on a fresh engine to reconstruct the final game state.
+ * The engine should use the same configuration (especially shuffleMethod) as the original game
+ * to guarantee deterministic results when a seed is present.
+ *
+ * @param engine - A game engine instance (should match original config)
+ * @param log - The action log to replay
+ * @returns The final game state after replaying all actions
+ */
+declare const replayActions: (engine: GameEngine, log: GameActionLog) => GameState;
+
+/**
+ * Manages a history of game states for undo/redo support.
+ * Uses a snapshot-based approach: each state is stored as a full GameState.
+ *
+ * @example
+ * ```typescript
+ * let history = createGameHistory(initialGame);
+ * const newGame = engine.chooseDomino({ game: history.current, ... });
+ * history = pushState(history, newGame);
+ * history = undo(history); // back to initialGame
+ * history = redo(history); // forward to newGame
+ * ```
+ */
+type GameHistory = {
+    /** The current game state */
+    current: GameState;
+    /** Stack of previous states (most recent last) */
+    past: GameState[];
+    /** Stack of undone states (most recent last) */
+    future: GameState[];
+};
+/**
+ * Creates a new game history initialized with a game state.
+ *
+ * @param initialState - The starting game state
+ * @returns A new GameHistory with empty past and future
+ */
+declare const createGameHistory: (initialState: GameState) => GameHistory;
+/**
+ * Records a new game state in the history.
+ * The current state is pushed to the past stack, and the future stack is cleared
+ * (branching from a previous undo point discards the old future).
+ *
+ * @param history - The current history
+ * @param newState - The new game state to record
+ * @returns Updated history with the new state as current
+ */
+declare const pushState: (history: GameHistory, newState: GameState) => GameHistory;
+/**
+ * Reverts to the previous game state.
+ * The current state is moved to the future stack for potential redo.
+ *
+ * @param history - The current history
+ * @returns Updated history with the previous state as current
+ * @throws {UndoError} If there is no previous state to revert to
+ */
+declare const undo: (history: GameHistory) => GameHistory;
+/**
+ * Re-applies a previously undone game state.
+ * The current state is moved to the past stack.
+ *
+ * @param history - The current history
+ * @returns Updated history with the next undone state as current
+ * @throws {RedoError} If there is no undone state to re-apply
+ */
+declare const redo: (history: GameHistory) => GameHistory;
+/**
+ * Checks whether an undo operation is available.
+ */
+declare const canUndo: (history: GameHistory) => boolean;
+/**
+ * Checks whether a redo operation is available.
+ */
+declare const canRedo: (history: GameHistory) => boolean;
+/**
+ * Clears the undo/redo history, keeping only the current state.
+ *
+ * @param history - The current history
+ * @returns A new history with empty past and future
+ */
+declare const clearHistory: (history: GameHistory) => GameHistory;
+/**
+ * Returns the number of states in the past and future stacks.
+ */
+declare const getHistorySize: (history: GameHistory) => {
+    past: number;
+    future: number;
+};
+
+/**
+ * Serializes a game state to a JSON string.
+ * The serialized string includes version information for future compatibility.
+ *
+ * @param game - The game state to serialize
+ * @returns JSON string representation of the game
+ */
+declare const serializeGame: (game: GameState) => string;
+/**
+ * Deserializes a JSON string back to a game state.
+ * Validates the structure and version before returning.
+ *
+ * @param json - The JSON string to deserialize
+ * @returns Result containing the game state or an error
+ */
+declare const deserializeGame: (json: string) => Result<GameState>;
+/**
+ * Creates a save point for the current game state.
+ * Includes metadata for debugging and restore purposes.
+ */
+interface GameSavePoint {
+    /** Serialized game data */
+    serialized: string;
+    /** When the save was created */
+    createdAt: string;
+    /** Game ID for reference */
+    gameId: string;
+    /** Current turn number */
+    turn: number;
+}
+/**
+ * Creates a save point from a game state.
+ *
+ * @param game - The game state to save
+ * @returns A save point object with metadata
+ */
+declare const createSavePoint: (game: GameState) => GameSavePoint;
+/**
+ * Restores a game state from a save point.
+ *
+ * @param savePoint - The save point to restore from
+ * @returns Result containing the restored game state or an error
+ */
+declare const restoreFromSavePoint: (savePoint: GameSavePoint) => Result<GameState>;
+
+/**
+ * Creates a new Kingdomino game engine instance.
+ *
+ * @param config - Configuration options for the engine
+ * @returns A fully configured GameEngine instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const engine = createGameEngine({});
+ *
+ * // With logging
+ * const engine = createGameEngine({ logging: true });
+ *
+ * // With event callbacks
+ * const engine = createGameEngine({
+ *   events: {
+ *     onDominoPlaced: ({ lordId }) => console.log(`${lordId} placed`),
+ *     onGameEnd: () => console.log('Game over!'),
+ *   },
+ * });
+ * ```
+ */
 declare const createGameEngine: (config: Partial<EngineConfig>) => GameEngine;
 
-export { type AddExtraRulesCommand, type AddPlayersCommand, type BasicRules, type CalculateScoreCommand, type ChooseDominoCommand, type CreateGameCommand, type Crown, type DiscardDominoCommand, type Domino, type EmptyGround, type EmptyTile, type ExtraRule, type FinalResult, GRIDSIZE, GROUND, type Game, type GameEngine, type GameMode, type GameState, type GameStateResult, type GameSteps, type GameWithNextAction, type GameWithNextStep, type GameWithResults, type GetExtraRulesCommand, type GetModesCommand, type GetResultCommand, type Ground, type Kingdom, type Lord, type NextAction, type NextStep, type ObjectValues, type PlaceDominoCommand, type Player, type PlayerActions, type PlayerPayload, type Players, type PlayersPayload, type Position, type RevealsDomino, type Rotation, type Rules, type Score, type ScoreResult, type SelectedRules, type ShuffleMethod, type StartGameCommand, type Tile, type UuidMethod, createGameEngine, gameSteps, isGameWithNextAction, isGameWithNextStep, playerActions };
+export { type ActionEntry, ActionExecutionError, type ActionPayloadMap, type ActionType, type AddExtraRulesCommand, type AddPlayersCommand, type BasicRules, type BotStrategy, type CalculateScoreCommand, type CanPlaceDominoCommand, type ChooseDominoCommand, type CreateGameCommand, type Crown, type DebugLogEntry, type DebugLogLevel, type DebugLogger, type DebugOptions, type DeserializeGameCommand, type DiscardDominoCommand, type DomainError, DomainException, type Domino, type DominoesRepository, type DynastyResult, type EmptyGround, type EmptyTile, type EngineConfig, ErrorCode, type ErrorCodeType, type ExtraRule, type FinalResult, GRIDSIZE, GROUND, type Game, type GameActionLog, type GameEngine, type GameEventCallbacks, type GameHistory, type GameMode, type GameSavePoint, type GameState, type GameStateResult, type GameStateSummary, type GameSteps, type GameWithNextAction, type GameWithNextStep, type GameWithResults, type GetDynastyResultCommand, type GetExtraRulesCommand, type GetModesCommand, type GetResultCommand, type GetValidPlacementsCommand, type Ground, InvalidStepError, type Kingdom, type Logger, type Lord, MAX_KINGDOM_SIZE, type ModeRepository, type NextAction, type NextStep, NotFoundError, type ObjectValues, type PickContext, type PlaceContext, type PlaceDominoCommand, type Player, type PlayerActions, type PlayerInput, type PlayerPayload, type Players, type PlayersPayload, type Position, RedoError, type RevealsDomino, type Rotation, type RuleRepository, type Rules, type Score, type ScoreResult, type SelectedRules, type SerializeGameCommand, type ShuffleMethod, type StartGameCommand, StepExecutionError, type StrategyName, type Tile, TranslationKey, type TranslationKeyType, type Translator, UndoError, type UuidMethod, type ValidPlacement, ValidationError, type ValidationIssue, type ValidationSeverity, advancedStrategy, appendAction, canRedo, canUndo, clearHistory, createActionLog, createDomainError, createGameEngine, createGameHistory, createSavePoint, createTranslator, defaultTranslations, defaultTranslator, deserializeGame, errorCodeToTranslationKey, expertStrategy, gameSteps, getActions, getActionsByTurn, getActionsByType, getHistorySize, getStrategy, getStrategyNames, greedyStrategy, isBotTurn, isGameWithNextAction, isGameWithNextStep, playBotTurn, playBotTurns, playerActions, pushState, randomStrategy, redo, replayActions, restoreFromSavePoint, serializeGame, summarizeGameState, translateErrorCode, undo, validateGameState, wrapWithActionLog, wrapWithDebug, wrapWithEvents };