@pompidup/kingdomino-engine 3.1.0 → 3.2.0

package/dist/index.d.ts

@@ -84,6 +84,10 @@ type Kingdom = (Tile | EmptyTile)[][];
  * 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.
@@ -128,6 +132,10 @@ type 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.
@@ -166,6 +174,8 @@ type BasicRules = {
     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.
@@ -184,7 +194,7 @@ type ExtraRule = {
  * Complete rules configuration loaded from data source.
  */
 type Rules = {
-    /** Basic rules indexed by player count (2-4) */
+    /** Basic rules indexed by player count (1-4) */
     basic: Record<number, BasicRules>;
     /** Available extra rules */
     extraRules: ExtraRule[];
@@ -232,6 +242,8 @@ type 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.
@@ -328,6 +340,26 @@ 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 = {
@@ -337,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 = {
@@ -387,6 +429,8 @@ type GetValidPlacementsCommand = {
     kingdom: Kingdom;
     /** The domino to find placements for */
     domino: Domino;
+    /** Maximum kingdom size (default: 5, use 7 for Mighty Duel) */
+    maxKingdomSize?: number;
 };
 
 /**
@@ -397,6 +441,8 @@ type CanPlaceDominoCommand = {
     kingdom: Kingdom;
     /** The domino to check placement for */
     domino: Domino;
+    /** Maximum kingdom size (default: 5, use 7 for Mighty Duel) */
+    maxKingdomSize?: number;
 };
 
 /**
@@ -414,6 +460,10 @@ type DeserializeGameCommand = {
     json: string;
 };
 
+type GetDynastyResultCommand = {
+    games: GameWithResults[];
+};
+
 /**
  * Represents a valid placement position with rotation.
  */
@@ -422,6 +472,14 @@ type ValidPlacement = {
     rotation: Rotation;
 };
 
+type DynastyResult = {
+    playerId: string;
+    playerName: string;
+    totalPoints: number;
+    gamesPoints: number[];
+    position: number;
+};
+
 /**
  * The main interface for interacting with the Kingdomino game engine.
  *
@@ -468,7 +526,7 @@ type GameEngine = {
     /**
      * 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 (2-4 players)
+     * @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
      */
@@ -548,29 +606,13 @@ type GameEngine = {
      * @throws Error if the JSON is invalid or incompatible
      */
     deserialize: (command: DeserializeGameCommand) => GameState;
-};
-
-type ShuffleMethod = <T>(array: T[]) => T[];
-
-type UuidMethod = () => string;
-
-type Logger = Readonly<{
-    info: (message: string) => void;
-    error: (message: string) => void;
-}>;
-
-/**
- * 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;
+    /**
+     * 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[];
 };
 
 /**
@@ -592,10 +634,13 @@ declare const ErrorCode: {
     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];
 /**
@@ -631,7 +676,7 @@ declare class InvalidStepError extends DomainException {
  * Error thrown when a step execution fails.
  */
 declare class StepExecutionError extends DomainException {
-    constructor(message: string, context?: Record<string, unknown>);
+    constructor(message: string, code?: ErrorCodeType, context?: Record<string, unknown>);
 }
 /**
  * Error thrown when an action execution fails.
@@ -651,143 +696,18 @@ declare class NotFoundError extends DomainException {
 declare class ValidationError extends DomainException {
     constructor(message: string, code: ErrorCodeType, context?: Record<string, unknown>);
 }
-
-/**
- * All possible game event types.
- */
-declare const GameEventType: {
-    readonly GAME_CREATED: "game:created";
-    readonly PLAYERS_ADDED: "game:playersAdded";
-    readonly GAME_STARTED: "game:started";
-    readonly DOMINO_PICKED: "domino:picked";
-    readonly DOMINO_PLACED: "domino:placed";
-    readonly DOMINO_DISCARDED: "domino:discarded";
-    readonly TURN_CHANGED: "turn:changed";
-    readonly GAME_ENDED: "game:ended";
-};
-type GameEventTypeValue = (typeof GameEventType)[keyof typeof GameEventType];
-/**
- * Base event structure with common properties.
- */
-interface BaseEvent {
-    /** Event type identifier */
-    type: GameEventTypeValue;
-    /** Timestamp when the event occurred */
-    timestamp: string;
-    /** Game ID this event belongs to */
-    gameId: string;
-}
-/**
- * Event emitted when a new game is created.
- */
-interface GameCreatedEvent extends BaseEvent {
-    type: typeof GameEventType.GAME_CREATED;
-    mode: string;
-}
 /**
- * Event emitted when players are added to the game.
+ * Error thrown when undo is requested but no previous state exists.
  */
-interface PlayersAddedEvent extends BaseEvent {
-    type: typeof GameEventType.PLAYERS_ADDED;
-    playerNames: string[];
-    playerCount: number;
+declare class UndoError extends DomainException {
+    constructor(message?: string, context?: Record<string, unknown>);
 }
 /**
- * Event emitted when the game starts.
+ * Error thrown when redo is requested but no future state exists.
  */
-interface GameStartedEvent extends BaseEvent {
-    type: typeof GameEventType.GAME_STARTED;
-    firstLordId: string;
-}
-/**
- * Event emitted when a lord picks a domino.
- */
-interface DominoPickedEvent extends BaseEvent {
-    type: typeof GameEventType.DOMINO_PICKED;
-    lordId: string;
-    playerId: string;
-    domino: Domino;
-}
-/**
- * Event emitted when a lord places a domino.
- */
-interface DominoPlacedEvent extends BaseEvent {
-    type: typeof GameEventType.DOMINO_PLACED;
-    lordId: string;
-    playerId: string;
-    domino: Domino;
-    position: Position;
-    rotation: Rotation;
+declare class RedoError extends DomainException {
+    constructor(message?: string, context?: Record<string, unknown>);
 }
-/**
- * Event emitted when a lord discards a domino.
- */
-interface DominoDiscardedEvent extends BaseEvent {
-    type: typeof GameEventType.DOMINO_DISCARDED;
-    lordId: string;
-    playerId: string;
-    domino: Domino;
-}
-/**
- * Event emitted when the turn changes.
- */
-interface TurnChangedEvent extends BaseEvent {
-    type: typeof GameEventType.TURN_CHANGED;
-    previousTurn: number;
-    newTurn: number;
-    nextLordId: string;
-}
-/**
- * Event emitted when the game ends.
- */
-interface GameEndedEvent extends BaseEvent {
-    type: typeof GameEventType.GAME_ENDED;
-    results: FinalResult[];
-    winner: {
-        playerId: string;
-        playerName: string;
-        score: number;
-    };
-}
-/**
- * Union type of all game events.
- */
-type GameEvent = GameCreatedEvent | PlayersAddedEvent | GameStartedEvent | DominoPickedEvent | DominoPlacedEvent | DominoDiscardedEvent | TurnChangedEvent | GameEndedEvent;
-/**
- * Event listener function type.
- */
-type GameEventListener<T extends GameEvent = GameEvent> = (event: T) => void;
-/**
- * Event emitter for game events.
- * Allows subscribing to specific event types or all events.
- */
-declare class GameEventEmitter {
-    private listeners;
-    /**
-     * Subscribe to a specific event type.
-     *
-     * @param eventType - The event type to listen for, or "*" for all events
-     * @param listener - The callback function to invoke
-     * @returns Unsubscribe function
-     */
-    on<T extends GameEvent>(eventType: T["type"] | "*", listener: GameEventListener<T>): () => void;
-    /**
-     * Emit an event to all registered listeners.
-     *
-     * @param event - The event to emit
-     */
-    emit(event: GameEvent): void;
-    /**
-     * Remove all listeners for a specific event type or all listeners.
-     *
-     * @param eventType - Optional event type to clear, clears all if not provided
-     */
-    clear(eventType?: GameEventTypeValue | "*"): void;
-}
-/**
- * Creates an event with common properties filled in.
- */
-declare const createEvent: <T extends GameEvent>(gameId: string, type: T["type"], data: Omit<T, "type" | "timestamp" | "gameId">) => T;
 
 /**
  * Translation keys for internationalization support.
@@ -795,20 +715,26 @@ declare const createEvent: <T extends GameEvent>(gameId: string, type: T["type"]
  */
 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";
@@ -832,6 +758,16 @@ 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.
  */
@@ -857,6 +793,503 @@ declare const createTranslator: (translations?: Partial<Record<TranslationKeyTyp
  */
 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.
@@ -916,12 +1349,15 @@ declare const restoreFromSavePoint: (savePoint: GameSavePoint) => Result<GameSta
  * // With logging
  * const engine = createGameEngine({ logging: true });
  *
- * // With custom shuffle for testing
+ * // With event callbacks
  * const engine = createGameEngine({
- *   shuffleMethod: (array) => array, // No shuffle
+ *   events: {
+ *     onDominoPlaced: ({ lordId }) => console.log(`${lordId} placed`),
+ *     onGameEnd: () => console.log('Game over!'),
+ *   },
  * });
  * ```
  */
 declare const createGameEngine: (config: Partial<EngineConfig>) => GameEngine;
 
-export { ActionExecutionError, type AddExtraRulesCommand, type AddPlayersCommand, type BasicRules, type CalculateScoreCommand, type CanPlaceDominoCommand, type ChooseDominoCommand, type CreateGameCommand, type Crown, type DeserializeGameCommand, type DiscardDominoCommand, type DomainError, DomainException, type Domino, type DominoDiscardedEvent, type DominoPickedEvent, type DominoPlacedEvent, type EmptyGround, type EmptyTile, type EngineConfig, ErrorCode, type ErrorCodeType, type ExtraRule, type FinalResult, GRIDSIZE, GROUND, type Game, type GameCreatedEvent, type GameEndedEvent, type GameEngine, type GameEvent, GameEventEmitter, type GameEventListener, GameEventType, type GameEventTypeValue, type GameMode, type GameSavePoint, type GameStartedEvent, type GameState, type GameStateResult, type GameSteps, type GameWithNextAction, type GameWithNextStep, type GameWithResults, type GetExtraRulesCommand, type GetModesCommand, type GetResultCommand, type GetValidPlacementsCommand, type Ground, InvalidStepError, type Kingdom, type Lord, type NextAction, type NextStep, NotFoundError, type ObjectValues, type PlaceDominoCommand, type Player, type PlayerActions, type PlayerPayload, type Players, type PlayersAddedEvent, type PlayersPayload, type Position, type RevealsDomino, type Rotation, type Rules, type Score, type ScoreResult, type SelectedRules, type SerializeGameCommand, type ShuffleMethod, type StartGameCommand, StepExecutionError, type Tile, TranslationKey, type TranslationKeyType, type Translator, type TurnChangedEvent, type UuidMethod, type ValidPlacement, ValidationError, createDomainError, createEvent, createGameEngine, createSavePoint, createTranslator, defaultTranslations, defaultTranslator, deserializeGame, gameSteps, isGameWithNextAction, isGameWithNextStep, playerActions, restoreFromSavePoint, serializeGame };
+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 };