@pompidup/kingdomino-engine 2.3.0 → 3.1.0

package/dist/index.d.ts

@@ -1,87 +1,201 @@
+/**
+ * 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;
 };
-type Orientation = "vertical" | "horizontal";
-type Rotation = 0 | 180;
+/**
+ * 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;
 
+/**
+ * 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;
 };
+/**
+ * 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;
 };
+/**
+ * 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 (2-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[];
 };
 
@@ -95,56 +209,121 @@ 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;
 };
+/**
+ * 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[];
 };
@@ -184,7 +363,6 @@ type PlaceDominoCommand = {
     game: GameState;
     lordId: string;
     position: Position;
-    orientation: Orientation;
     rotation: Rotation;
 };
 
@@ -201,30 +379,549 @@ 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;
+};
+
+/**
+ * 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;
+};
+
+/**
+ * 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;
+};
+
+/**
+ * Represents a valid placement position with rotation.
+ */
+type ValidPlacement = {
+    position: Position;
+    rotation: Rotation;
+};
+
+/**
+ * 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 (2-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;
 };
 
 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;
 };
 
+/**
+ * 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 NOT_YOUR_TURN: "NOT_YOUR_TURN";
+    readonly CANNOT_PICK: "CANNOT_PICK";
+    readonly CANNOT_PLACE: "CANNOT_PLACE";
+    readonly DOMINO_ALREADY_PICKED: "DOMINO_ALREADY_PICKED";
+};
+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, 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>);
+}
+
+/**
+ * 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.
+ */
+interface PlayersAddedEvent extends BaseEvent {
+    type: typeof GameEventType.PLAYERS_ADDED;
+    playerNames: string[];
+    playerCount: number;
+}
+/**
+ * Event emitted when the game starts.
+ */
+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;
+}
+/**
+ * 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.
+ * Use these keys instead of hardcoded strings for translatable content.
+ */
+declare const TranslationKey: {
+    readonly ERROR_INVALID_STEP: "error.invalidStep";
+    readonly ERROR_LORD_NOT_FOUND: "error.lordNotFound";
+    readonly ERROR_PLAYER_NOT_FOUND: "error.playerNotFound";
+    readonly ERROR_DOMINO_NOT_FOUND: "error.dominoNotFound";
+    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_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 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>;
+/**
+ * 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;
+
+/**
+ * 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 custom shuffle for testing
+ * const engine = createGameEngine({
+ *   shuffleMethod: (array) => array, // No shuffle
+ * });
+ * ```
+ */
 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 Orientation, 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 { 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 };