@pompidup/kingdomino-engine 3.5.1 → 3.7.0

package/dist/index.d.ts

@@ -73,6 +73,13 @@ type RevealsDomino = {
     lordId: string | null;
     /** Display position in the revealed set (for UI ordering) */
     position: number;
+    /**
+     * Id of the player this domino is reserved for (Kingdomino Origins
+     * "Neolithic" rule): set on the whole line by its first pick, the pair
+     * 1 & 4 or 2 & 3 going to that lord's player and the two other dominoes to
+     * the opponent. Only lords of this player can pick it. Absent otherwise.
+     */
+    reservedFor?: string;
 };
 
 /**
@@ -157,6 +164,17 @@ type QuestTile = {
     /** Target terrain type (only for localTrade and kingdomBorders quests) */
     terrain?: Ground;
 };
+/**
+ * A giant sent with `sendGiant` that the targeted opponent must now place on
+ * one of their own crowns (official rule: the opponent chooses the crown).
+ * While it is set, `nextAction` is `placeGiant` for a lord of the target.
+ */
+type PendingGiant = {
+    /** Lord who sent the giant; their turn resumes once the giant is placed */
+    fromLordId: string;
+    /** Player who received the giant and must choose the crown */
+    targetPlayerId: string;
+};
 /**
  * Complete Age of Giants-specific game state.
  * Stored as an optional field on Game and only present in AoG modes.
@@ -166,6 +184,8 @@ type AgeOfGiantsState = {
     giantPool: number;
     /** The 2 quest tiles drawn for this game */
     questTiles: QuestTile[];
+    /** Giant sent to an opponent, waiting for that opponent to choose a crown */
+    pendingGiant?: PendingGiant;
 };
 
 /**
@@ -322,8 +342,28 @@ type WarriorTile = {
     /** Combat power (1, 2, or 3) */
     power: number;
 };
-/** Discriminated union of all caveman tile types. */
+/**
+ * Discriminant values of `CavemanTile["kind"]`.
+ */
+declare const cavemanKinds: {
+    readonly hunterGatherer: "hunterGatherer";
+    readonly warrior: "warrior";
+};
+type CavemanKind = ObjectValues<typeof cavemanKinds>;
+/** Discriminated union of all caveman tile types (discriminant: `kind`). */
 type CavemanTile = HunterGathererTile | WarriorTile;
+/**
+ * Type guard to check if a caveman tile is a hunter-gatherer.
+ * @param caveman - The caveman tile to check
+ * @returns True if the tile is a `HunterGathererTile`
+ */
+declare const isHunterGathererTile: (caveman: CavemanTile) => caveman is HunterGathererTile;
+/**
+ * Type guard to check if a caveman tile is a warrior.
+ * @param caveman - The caveman tile to check
+ * @returns True if the tile is a `WarriorTile`
+ */
+declare const isWarriorTile: (caveman: CavemanTile) => caveman is WarriorTile;
 /**
  * A caveman tile placed on a player's kingdom.
  */
@@ -391,7 +431,12 @@ type BuildingTile = {
     id: number;
     /** Display name */
     name: string;
-    /** Cost in coins to purchase */
+    /**
+     * Intrinsic cost of the tile. On a Builders Board with `slotCosts` (every
+     * game started since the official 6-spot board), the price is carried by
+     * the spot the tile occupies instead (see `BuildersBoard.slotCosts`); this
+     * value is only used by boards without `slotCosts` (older saved games).
+     */
     cost: number;
     /** Immediate bonus when constructed (optional) */
     immediateBonus?: ImmediateBonus;
@@ -408,12 +453,26 @@ type BuildingTile = {
 type BuildingSlot = BuildingTile | null;
 /**
  * The Builders Board holding available building tiles for purchase.
+ *
+ * Official board: 6 spots whose construction cost is printed below them
+ * (5, 4, 3, 2, 1 and 0 coins, from the draw pile to the cheapest spot). At
+ * each new round the remaining tiles slide to the cheapest spots and the
+ * empty spots are filled from the draw pile.
  */
 type BuildersBoard = {
-    /** Visible building tiles available for purchase (4 slots) */
+    /**
+     * Visible building tiles available for purchase, one per spot (6 spots; 4 in
+     * games started before the official board). `null` is an empty spot.
+     */
     slots: BuildingSlot[];
     /** Remaining building tiles in the draw pile */
     drawPile: BuildingTile[];
+    /**
+     * Construction cost of each spot, aligned with `slots` (`[5, 4, 3, 2, 1, 0]`).
+     * Absent in games started before the official board: the price is then the
+     * tile's own `cost`.
+     */
+    slotCosts?: number[];
 };
 /**
  * A building that has been placed on a player's kingdom.
@@ -454,6 +513,11 @@ type Player = {
     towers?: number;
     /** Knights placed on the kingdom (Queendomino) */
     knights?: Knight[];
+    /**
+     * Extra knights granted by building immediate bonuses (Queendomino).
+     * Each one raises the player's knight limit above the base maximum.
+     */
+    bonusKnights?: number;
     /** Buildings placed on the kingdom (Queendomino) */
     buildings?: PlacedBuilding[];
     /** Fire tokens placed on the kingdom (Origins) */
@@ -519,6 +583,12 @@ type QueenDominoState = {
     dragonAvailable: boolean;
     /** Whether the Dragon has been used this round (resets each round) */
     dragonUsedThisRound: boolean;
+    /**
+     * Kingdom positions of the two squares of the domino the current lord has
+     * just placed. Knights may only be placed on these squares. Empty when the
+     * lord discarded their domino.
+     */
+    lastPlacedPositions?: Position[];
 };
 
 /**
@@ -559,6 +629,12 @@ type Rules = {
     basic: Record<number, BasicRules>;
     /** Age of Giants basic rules indexed by player count (2-5) */
     aogBasic?: Record<number, BasicRules>;
+    /**
+     * Basic rules specific to one game mode, indexed by mode name then player
+     * count. They take precedence over `basic` / `aogBasic` for that mode and
+     * player count (e.g. Queendomino at 2 players: 7x7 kingdom, 48 dominoes).
+     */
+    modeBasic?: Record<string, Record<number, BasicRules>>;
     /** Available extra rules */
     extraRules: ExtraRule[];
 };
@@ -573,742 +649,1228 @@ type SelectedRules = {
 };
 
 /**
- * Represents the complete state of a Kingdomino game.
- * This is the main aggregate containing all game data.
+ * Error codes for domain-level errors.
+ * These codes can be used for i18n and programmatic error handling.
  */
-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;
-    /** Queendomino-specific state (only present in QueenDomino mode) */
-    queendomino?: QueenDominoState;
-    /** Origins-specific state (only present in KingdominoOrigins modes) */
-    origins?: OriginsState;
-    /** Age of Giants-specific state (only present in AgeOfGiants modes) */
-    ageOfGiants?: AgeOfGiantsState;
+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 EXTRA_RULE_NOT_AVAILABLE: "EXTRA_RULE_NOT_AVAILABLE";
+    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 DOMINO_RESERVED: "DOMINO_RESERVED";
+    readonly UNDO_UNAVAILABLE: "UNDO_UNAVAILABLE";
+    readonly REDO_UNAVAILABLE: "REDO_UNAVAILABLE";
+    readonly CANNOT_PLACE_KNIGHT: "CANNOT_PLACE_KNIGHT";
+    readonly MAX_KNIGHTS_REACHED: "MAX_KNIGHTS_REACHED";
+    readonly KNIGHT_TERRITORY_OCCUPIED: "KNIGHT_TERRITORY_OCCUPIED";
+    readonly CANNOT_AFFORD_BUILDING: "CANNOT_AFFORD_BUILDING";
+    readonly NO_CONSTRUCTION_SQUARE: "NO_CONSTRUCTION_SQUARE";
+    readonly DRAGON_UNAVAILABLE: "DRAGON_UNAVAILABLE";
+    readonly QUEEN_HOLDER_CANNOT_USE_DRAGON: "QUEEN_HOLDER_CANNOT_USE_DRAGON";
+    readonly BUILDING_NOT_FOUND: "BUILDING_NOT_FOUND";
+    readonly INVALID_OPTIONAL_ACTION: "INVALID_OPTIONAL_ACTION";
+    readonly GIANT_POOL_EMPTY: "GIANT_POOL_EMPTY";
+    readonly GIANT_NOT_FOUND: "GIANT_NOT_FOUND";
+    readonly INVALID_GIANT_PLACEMENT: "INVALID_GIANT_PLACEMENT";
+    readonly NOT_AOG_MODE: "NOT_AOG_MODE";
+    readonly FIRE_TOKEN_POOL_EMPTY: "FIRE_TOKEN_POOL_EMPTY";
+    readonly FIRE_TOKEN_INVALID_POSITION: "FIRE_TOKEN_INVALID_POSITION";
+    readonly NO_PENDING_FIRE_TOKEN: "NO_PENDING_FIRE_TOKEN";
+    readonly CANNOT_RECRUIT_CAVEMAN: "CANNOT_RECRUIT_CAVEMAN";
+    readonly INSUFFICIENT_RESOURCES: "INSUFFICIENT_RESOURCES";
+    readonly INVALID_CAVEMAN_PLACEMENT: "INVALID_CAVEMAN_PLACEMENT";
+    readonly CAVEMAN_NOT_FOUND: "CAVEMAN_NOT_FOUND";
+    readonly NOT_TRIBE_MODE: "NOT_TRIBE_MODE";
+    readonly INVALID_PLAYER_ID: "INVALID_PLAYER_ID";
 };
+type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
 /**
- * Available game steps representing phases of game setup and completion.
+ * Structured domain error with code and context.
  */
-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>;
+interface DomainError {
+    /** Error code for programmatic handling */
+    code: ErrorCodeType;
+    /** Human-readable error message */
+    message: string;
+    /** Optional context data for debugging */
+    context?: Record<string, unknown>;
+}
 /**
- * Represents a player action that needs to be performed.
- * Used during active gameplay.
+ * Creates a domain error object.
  */
-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;
-};
+declare const createDomainError: (code: ErrorCodeType, message: string, context?: Record<string, unknown>) => DomainError;
 /**
- * Represents a game phase transition.
- * Used during setup and game end.
+ * Base class for domain errors thrown by handlers.
  */
-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>;
+declare class DomainException extends Error {
+    readonly code: ErrorCodeType;
+    readonly context?: Record<string, unknown>;
+    constructor(error: DomainError);
+}
 /**
- * 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
+ * Error thrown when the game is in an invalid step for the requested action.
  */
-declare const isGameWithNextAction: (game: GameWithNextAction | GameWithNextStep) => game is GameWithNextAction;
+declare class InvalidStepError extends DomainException {
+    constructor(message: string, context?: Record<string, unknown>);
+}
 /**
- * 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
+ * Error thrown when a step execution fails.
  */
-declare const isGameWithNextStep: (game: GameWithNextAction | GameWithNextStep) => game is GameWithNextStep;
+declare class StepExecutionError extends DomainException {
+    constructor(message: string, code?: ErrorCodeType, context?: Record<string, unknown>);
+}
 /**
- * Represents the score calculation for a kingdom.
+ * Error thrown when an action execution fails.
  */
-type Score = {
-    /** Total points earned */
-    points: number;
-    /** Size of the largest contiguous property */
-    maxPropertiesSize: number;
-    /** Total number of crowns in the kingdom */
-    totalCrowns: number;
-};
+declare class ActionExecutionError extends DomainException {
+    constructor(message: string, code?: ErrorCodeType, context?: Record<string, unknown>);
+}
 /**
- * Score result for a specific player.
+ * Error thrown when a required entity is not found.
  */
-type ScoreResult = {
-    /** Player's unique identifier */
-    playerId: string;
-    /** Player's display name */
-    playerName: string;
-    /** Detailed score breakdown */
-    details: Score;
-};
+declare class NotFoundError extends DomainException {
+    constructor(message: string, code?: ErrorCodeType, context?: Record<string, unknown>);
+}
 /**
- * Final result including ranking position.
+ * Error thrown when validation fails.
  */
-type FinalResult = ScoreResult & {
-    /** Player's final position (1 = winner) */
-    position: number;
-};
-/** Game state with final results calculated */
-type GameWithResults = Game & {
-    result: FinalResult[];
-};
-
-type AddExtraRulesCommand = {
-    game: GameState;
-    extraRules: string[];
-};
-
+declare class ValidationError extends DomainException {
+    constructor(message: string, code: ErrorCodeType, context?: Record<string, unknown>);
+}
 /**
- * Input for a single player: either a name string (human) or an object with bot config.
+ * Error thrown when undo is requested but no previous state exists.
  */
-type PlayerInput = string | {
-    name: string;
-    bot?: {
-        strategyName: string;
-    };
-};
-type AddPlayersCommand = {
-    game: GameState;
-    players: PlayerInput[];
-};
-
-type CalculateScoreCommand = {
-    kingdom: Kingdom;
-};
-
+declare class UndoError extends DomainException {
+    constructor(message?: string, context?: Record<string, unknown>);
+}
 /**
- * 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.
+ * Error thrown when redo is requested but no future state exists.
  */
-type ValidationSeverity = "error" | "warning";
+declare class RedoError extends DomainException {
+    constructor(message?: string, context?: Record<string, unknown>);
+}
+
 /**
- * Describes a single validation issue found in a game state.
+ * Translation keys for internationalization support.
+ * Use these keys instead of hardcoded strings for translatable content.
  */
-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;
+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_DOMINO_RESERVED: "error.dominoReserved";
+    readonly ERROR_INVALID_PLAYER_COUNT: "error.invalidPlayerCount";
+    readonly ERROR_INVALID_PLAYER_NAME: "error.invalidPlayerName";
+    readonly ERROR_EXTRA_RULE_NOT_AVAILABLE: "error.extraRuleNotAvailable";
+    readonly ERROR_UNDO_UNAVAILABLE: "error.undoUnavailable";
+    readonly ERROR_REDO_UNAVAILABLE: "error.redoUnavailable";
+    readonly MODE_CLASSIC: "mode.classic";
+    readonly MODE_QUEENDOMINO: "mode.queenDomino";
+    readonly MODE_ORIGINS_DISCOVERY: "mode.originsDiscovery";
+    readonly MODE_ORIGINS_TOTEM: "mode.originsTotem";
+    readonly MODE_ORIGINS_TRIBE: "mode.originsTribe";
+    readonly MODE_AGE_OF_GIANTS: "mode.ageOfGiants";
+    readonly MODE_AGE_OF_GIANTS_QUEENDOMINO: "mode.ageOfGiantsQueenDomino";
+    readonly RULE_MIDDLE_KINGDOM: "rule.middleKingdom";
+    readonly RULE_HARMONY: "rule.harmony";
+    readonly RULE_MIGHTY_DUEL: "rule.mightyDuel";
+    readonly RULE_DYNASTY: "rule.dynasty";
+    readonly RULE_EMPIRE_OF_FIRE: "rule.empireOfFire";
+    readonly RULE_HOMO_HABILIS: "rule.homoHabilis";
+    readonly RULE_NEOLITHIC: "rule.neolithic";
+    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 GROUND_GRASSLAND: "ground.grassland";
+    readonly GROUND_LAKE: "ground.lake";
+    readonly GROUND_JUNGLE: "ground.jungle";
+    readonly GROUND_QUARRY: "ground.quarry";
+    readonly GROUND_DESERT: "ground.desert";
+    readonly GROUND_VOLCANO: "ground.volcano";
+    readonly RESOURCE_MAMMOTH: "resource.mammoth";
+    readonly RESOURCE_FISH: "resource.fish";
+    readonly RESOURCE_MUSHROOM: "resource.mushroom";
+    readonly RESOURCE_FLINT: "resource.flint";
+    readonly CAVEMAN_HUNTER_GATHERER: "caveman.hunterGatherer";
+    readonly CAVEMAN_WARRIOR: "caveman.warrior";
+    readonly CAVEMAN_MAMMOTH_HUNTER: "caveman.mammothHunter";
+    readonly CAVEMAN_FISHERMAN: "caveman.fisherman";
+    readonly CAVEMAN_MUSHROOM_PICKER: "caveman.mushroomPicker";
+    readonly CAVEMAN_FLINT_COLLECTOR: "caveman.flintCollector";
+    readonly CAVEMAN_TRAPPER: "caveman.trapper";
+    readonly CAVEMAN_GATHERER: "caveman.gatherer";
+    readonly CAVEMAN_FIRE_LADY: "caveman.fireLady";
+    readonly CAVEMAN_WARRIOR_SMALL: "caveman.warriorSmall";
+    readonly CAVEMAN_WARRIOR_AMAZON: "caveman.warriorAmazon";
+    readonly CAVEMAN_WARRIOR_OAFISH: "caveman.warriorOafish";
+    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";
+    readonly ACTION_PLACE_KNIGHT: "action.placeKnight";
+    readonly ACTION_CONSTRUCT_BUILDING: "action.constructBuilding";
+    readonly ACTION_USE_DRAGON: "action.useDragon";
+    readonly ACTION_SKIP_OPTIONAL_ACTION: "action.skipOptionalAction";
+    readonly ACTION_PLACE_GIANT: "action.placeGiant";
+    readonly ACTION_SEND_GIANT: "action.sendGiant";
+    readonly ACTION_PLACE_FIRE_TOKEN: "action.placeFireToken";
+    readonly ACTION_RECRUIT_CAVEMAN: "action.recruitCaveman";
+    readonly ERROR_CANNOT_PLACE_KNIGHT: "error.cannotPlaceKnight";
+    readonly ERROR_MAX_KNIGHTS_REACHED: "error.maxKnightsReached";
+    readonly ERROR_KNIGHT_TERRITORY_OCCUPIED: "error.knightTerritoryOccupied";
+    readonly ERROR_CANNOT_AFFORD_BUILDING: "error.cannotAffordBuilding";
+    readonly ERROR_NO_CONSTRUCTION_SQUARE: "error.noConstructionSquare";
+    readonly ERROR_DRAGON_UNAVAILABLE: "error.dragonUnavailable";
+    readonly ERROR_QUEEN_HOLDER_CANNOT_USE_DRAGON: "error.queenHolderCannotUseDragon";
+    readonly ERROR_BUILDING_NOT_FOUND: "error.buildingNotFound";
+    readonly ERROR_INVALID_OPTIONAL_ACTION: "error.invalidOptionalAction";
+    readonly ERROR_GIANT_POOL_EMPTY: "error.giantPoolEmpty";
+    readonly ERROR_GIANT_NOT_FOUND: "error.giantNotFound";
+    readonly ERROR_INVALID_GIANT_PLACEMENT: "error.invalidGiantPlacement";
+    readonly ERROR_NOT_AOG_MODE: "error.notAogMode";
+    readonly ERROR_FIRE_TOKEN_POOL_EMPTY: "error.fireTokenPoolEmpty";
+    readonly ERROR_FIRE_TOKEN_INVALID_POSITION: "error.fireTokenInvalidPosition";
+    readonly ERROR_NO_PENDING_FIRE_TOKEN: "error.noPendingFireToken";
+    readonly ERROR_CANNOT_RECRUIT_CAVEMAN: "error.cannotRecruitCaveman";
+    readonly ERROR_INSUFFICIENT_RESOURCES: "error.insufficientResources";
+    readonly ERROR_INVALID_CAVEMAN_PLACEMENT: "error.invalidCavemanPlacement";
+    readonly ERROR_CAVEMAN_NOT_FOUND: "error.cavemanNotFound";
+    readonly ERROR_NOT_TRIBE_MODE: "error.notTribeMode";
+    readonly ERROR_INVALID_PLAYER_ID: "error.invalidPlayerId";
+    readonly SCORE_QUEEN: "score.queen";
+    readonly SCORE_BUILDING: "score.building";
+    readonly SCORE_WEALTH: "score.wealth";
+    readonly SCORE_TOTEM_MAMMOTH: "score.totemMammoth";
+    readonly SCORE_TOTEM_FISH: "score.totemFish";
+    readonly SCORE_TOTEM_MUSHROOM: "score.totemMushroom";
+    readonly SCORE_TOTEM_FLINT: "score.totemFlint";
+    readonly SCORE_RESOURCES: "score.resources";
+    readonly SCORE_WARRIORS: "score.warriors";
+    readonly SCORE_FIRE: "score.fire";
+    readonly QUEST_LOCAL_TRADE: "quest.localTrade";
+    readonly QUEST_KINGDOM_BORDERS: "quest.kingdomBorders";
+    readonly QUEST_HARMONY: "quest.harmony";
+    readonly QUEST_MIDDLE_KINGDOM: "quest.middleKingdom";
+    readonly QUEST_LOST_CORNER: "quest.lostCorner";
+    readonly QUEST_MEGALOMANIA: "quest.megalomania";
+    readonly QUEST_AUSTERE_KING: "quest.austereKing";
 };
-
+type TranslationKeyType = (typeof TranslationKey)[keyof typeof TranslationKey];
 /**
- * Command to check if a domino can be placed anywhere on a kingdom.
+ * Default English translations.
+ * Also available as `englishTranslations` / `translations.en`.
  */
-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;
-};
-
-type ChooseDominoCommand = {
-    game: GameState;
-    dominoPick: number;
-    lordId: string;
-};
-
-type ConstructBuildingCommand = {
-    game: GameWithNextAction;
-    lordId: string;
-    buildingId: number;
-    position: Position;
-};
-
-type CreateGameCommand = {
-    mode: string;
-    seed?: string;
-};
-
-type DiscardDominoCommand = {
-    game: GameState;
-    lordId: string;
-};
-
-type GetDynastyResultCommand = {
-    games: GameWithResults[];
-};
-
-type GetExtraRulesCommand = {
-    mode: GameMode["name"];
-    players: number;
-};
-
-type GetModesCommand = Record<string, never>;
-
-type GetResultCommand = {
-    game: GameState;
-};
-
+declare const defaultTranslations: Record<TranslationKeyType, string>;
+/** English translations (alias of `defaultTranslations`). */
+declare const englishTranslations: Record<TranslationKeyType, string>;
 /**
- * Command to get all valid placements for a domino on a kingdom.
+ * French translations.
  */
-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;
-};
-
-type PlaceDominoCommand = {
-    game: GameState;
-    lordId: string;
-    position: Position;
-    rotation: Rotation;
-};
-
-type PlaceFireTokenCommand = {
-    game: GameWithNextAction;
-    lordId: string;
-    position: Position;
-};
-
-type PlaceGiantCommand = {
-    game: GameWithNextAction;
-    lordId: string;
-    position: Position;
-};
-
-type PlaceKnightCommand = {
-    game: GameWithNextAction;
-    lordId: string;
-    position: Position;
-};
-
-type RecruitCavemanCommand = {
-    game: GameWithNextAction;
-    lordId: string;
-    /** ID of the caveman tile to recruit */
-    cavemanId: number;
-    /** Position on the kingdom to place the caveman */
-    position: Position;
-    /** Positions of resources to spend as payment */
-    resourcePositions: Position[];
-};
-
-type SendGiantCommand = {
-    game: GameWithNextAction;
-    lordId: string;
-    /** Index of the giant to send from the current player's giants array */
-    giantIndex: number;
-    /** ID of the opponent player to receive the giant */
-    targetPlayerId: string;
-    /** Position on the opponent's kingdom where the giant will cover a crown */
-    targetCrownPosition: Position;
-};
-
+declare const frenchTranslations: Record<TranslationKeyType, string>;
+/** Locales shipped with the engine. */
+declare const supportedLocales: readonly ["en", "fr"];
+/** A locale shipped with the engine. */
+type SupportedLocale = (typeof supportedLocales)[number];
 /**
- * Command to serialize a game state to JSON.
+ * Built-in translation dictionaries, indexed by locale.
+ * Every dictionary contains every `TranslationKey`.
+ *
+ * @example
+ * ```typescript
+ * const translator = createTranslator(localeTranslations.fr);
+ * ```
  */
-type SerializeGameCommand = {
-    /** The game state to serialize */
-    game: GameState;
-};
+declare const localeTranslations: Record<SupportedLocale, Record<TranslationKeyType, string>>;
 /**
- * Command to deserialize a game state from JSON.
+ * Maps every terrain type (`Ground`) to its translation key.
  */
-type DeserializeGameCommand = {
-    /** The JSON string to deserialize */
-    json: string;
-};
-
-type SkipOptionalActionCommand = {
-    game: GameWithNextAction;
-    lordId: string;
-};
-
-type StartGameCommand = {
-    game: GameState;
-};
-
-type UseDragonCommand = {
-    game: GameWithNextAction;
-    lordId: string;
-    buildingId: number;
-};
-
-type DynastyResult = {
-    playerId: string;
-    playerName: string;
-    totalPoints: number;
-    gamesPoints: number[];
-    position: number;
-};
-
+declare const groundToTranslationKey: Record<Ground, TranslationKeyType>;
 /**
- * Represents a valid placement position with rotation.
+ * Maps every player action (`PlayerActions`) to its translation key.
  */
-type ValidPlacement = {
-    position: Position;
-    rotation: Rotation;
-};
-
+declare const playerActionToTranslationKey: Record<PlayerActions, TranslationKeyType>;
 /**
- * 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 });
- * ```
+ * Maps every Origins resource type to its translation key.
  */
-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[];
-    /**
-     * Places a giant on a crown in the lord's kingdom (Age of Giants).
-     * Mandatory after placing a giant domino (A-F). The giant covers the crown for scoring.
-     * @param command - Contains game state, lord ID, and crown position
-     * @returns Updated game state with next action
-     */
-    placeGiant: (command: PlaceGiantCommand) => GameState;
-    /**
-     * Sends a giant from the lord's kingdom to an opponent's kingdom (Age of Giants).
-     * Optional after placing a footprint domino (49-54). The opponent chooses which crown is covered.
-     * @param command - Contains game state, lord ID, giant index, target player ID, and target crown position
-     * @returns Updated game state with next action
-     */
-    sendGiant: (command: SendGiantCommand) => GameState;
+declare const resourceToTranslationKey: Record<ResourceType, TranslationKeyType>;
+/**
+ * Maps every caveman tile kind (`CavemanKind`) to its translation key.
+ */
+declare const cavemanKindToTranslationKey: Record<CavemanKind, TranslationKeyType>;
+/**
+ * Maps every hunter-gatherer type to its translation key.
+ */
+declare const hunterGathererKindToTranslationKey: Record<HunterGathererKind, TranslationKeyType>;
+/**
+ * Maps every warrior type to its translation key.
+ */
+declare const warriorTypeToTranslationKey: Record<WarriorType, TranslationKeyType>;
+/**
+ * Maps game mode names (`GameMode["name"]`, as returned by `getModes`)
+ * to their translation key.
+ */
+declare const modeNameToTranslationKey: Readonly<Record<string, TranslationKeyType>>;
+/**
+ * Maps extra rule names (`ExtraRule["name"]`, as returned by `getExtraRules`)
+ * to their translation key.
+ */
+declare const extraRuleNameToTranslationKey: Readonly<Record<string, TranslationKeyType>>;
+/**
+ * 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 {
     /**
-     * Places a knight on the lord's kingdom at the specified position (Queendomino).
-     * @param command - Contains game state, lord ID, and position
-     * @returns Updated game state with next action
+     * Translate a key to the current language.
+     * @param key - The translation key
+     * @param params - Optional parameters for interpolation
+     * @returns The translated string
      */
-    placeKnight: (command: PlaceKnightCommand) => GameState;
+    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;
+/**
+ * Maps every Age of Giants quest type to the translation key of its name
+ * (used as `label` of `quest` score bonuses).
+ */
+declare const questTypeToTranslationKey: Record<QuestType, TranslationKeyType>;
+/**
+ * Maps every Origins totem (by resource type) to the translation key of its
+ * name (used as `label` of `totem` score bonuses).
+ */
+declare const totemToTranslationKey: Record<ResourceType, TranslationKeyType>;
+
+/**
+ * One scored territory (a group of orthogonally connected squares of the
+ * same terrain) of a kingdom. The castle is never part of a territory.
+ */
+type ScoreTerritory = {
+    /** Terrain shared by every square of the territory */
+    terrain: Ground;
+    /** Squares of the territory, sorted by row then column */
+    cells: Position[];
     /**
-     * Constructs a building on the lord's kingdom (Queendomino).
-     * @param command - Contains game state, lord ID, building ID, and position
-     * @returns Updated game state with next action
+     * Crowns counted for scoring (Origins: fire symbols). Crowns covered by an
+     * Age of Giants giant are not counted.
      */
-    constructBuilding: (command: ConstructBuildingCommand) => GameState;
+    crowns: number;
+    /** Crowns of the territory covered by giants (not counted in `crowns`) */
+    coveredCrowns: number;
+    /** Points scored by the territory: `cells.length * crowns` */
+    points: number;
+};
+/**
+ * Kinds of bonus that can appear in a score breakdown.
+ */
+declare const scoreBonusTypes: {
+    /** "The middle Kingdom" optional rule: castle in the middle (+10) */
+    readonly middleKingdom: "middleKingdom";
+    /** "Empire of Fire" optional rule (Origins): hut in the middle (+10) */
+    readonly empireOfFire: "empireOfFire";
+    /** "Harmony" optional rule: complete kingdom, no discarded domino (+5) */
+    readonly harmony: "harmony";
+    /** "Homo Habilis" optional rule (Origins): complete territory (+5) */
+    readonly homoHabilis: "homoHabilis";
+    /** Queendomino: the Queen counts as an extra crown on the largest territory */
+    readonly queen: "queen";
+    /** Queendomino: end-game scoring of one constructed building */
+    readonly building: "building";
+    /** Queendomino: Wealth, 1 point per 3 unused coins */
+    readonly wealth: "wealth";
+    /** Age of Giants: one quest tile */
+    readonly quest: "quest";
+    /** Origins Totem: one totem held by the player */
+    readonly totem: "totem";
+    /** Origins Totem: 1 point per wooden resource left in the kingdom */
+    readonly resources: "resources";
+    /** Origins Tribe: one hunter-gatherer */
+    readonly hunterGatherer: "hunterGatherer";
+    /** Origins Tribe: every warrior group */
+    readonly warriors: "warriors";
+    /** Origins: fire tokens placed in the kingdom's territories */
+    readonly fire: "fire";
+};
+/** Union of every bonus kind */
+type ScoreBonusType = ObjectValues<typeof scoreBonusTypes>;
+/**
+ * One bonus of a score breakdown.
+ */
+type ScoreBonus = {
+    /** Kind of bonus */
+    type: ScoreBonusType;
     /**
-     * Uses the dragon to destroy a building on the builders board (Queendomino).
-     * @param command - Contains game state, lord ID, and building ID
-     * @returns Updated game state with next action
+     * Translation key of the bonus name (see `TranslationKey`). Translate it
+     * with `translator.t(bonus.label, bonus.labelParams)`.
      */
-    useDragon: (command: UseDragonCommand) => GameState;
+    label: TranslationKeyType;
+    /** Interpolation parameters of the label (e.g. the building name) */
+    labelParams?: Record<string, string | number>;
+    /** Points granted by the bonus (may be 0 when its condition is not met) */
+    points: number;
     /**
-     * Places a fire token on the lord's kingdom after placing a volcano domino (Origins).
-     * @param command - Contains game state, lord ID, and target position
-     * @returns Updated game state with next action
+     * `true` while the game is in progress: the bonus is evaluated on the
+     * current state and may still change (or disappear) before the end of the
+     * game. `false` once the game is over.
      */
-    placeFireToken: (command: PlaceFireTokenCommand) => GameState;
+    provisional: boolean;
+    /** Building id (`building` bonuses) */
+    buildingId?: number;
+    /** Quest tile id (`quest` bonuses) */
+    questId?: number;
+    /** Quest type (`quest` bonuses) */
+    questType?: QuestType;
+    /** Target terrain of the quest (Local Trade, Kingdom Borders) */
+    terrain?: Ground;
+    /** Resource of the totem (`totem` bonuses) */
+    resource?: ResourceType;
+    /** Caveman tile id (`hunterGatherer` bonuses) */
+    cavemanId?: number;
+    /** Kingdom position the bonus relates to (building, hunter-gatherer) */
+    position?: Position;
+};
+/**
+ * Detailed score of one kingdom.
+ * Invariant: `total === territoryPoints + bonusPoints`, where
+ * `territoryPoints` is the sum of the territory points and `bonusPoints`
+ * the sum of the bonus points.
+ */
+type ScoreBreakdown = {
+    /** Every scored territory of the kingdom */
+    territories: ScoreTerritory[];
+    /** Every bonus applying to the player in the current game mode */
+    bonuses: ScoreBonus[];
+    /** Sum of the territory points */
+    territoryPoints: number;
+    /** Sum of the bonus points */
+    bonusPoints: number;
+    /** Total score: `territoryPoints + bonusPoints` */
+    total: number;
+};
+/**
+ * Mode-aware score of one player, as returned by `calculatePlayerScore`.
+ */
+type PlayerScore = {
+    /** Player's unique identifier */
+    playerId: string;
+    /** Player's display name */
+    playerName: string;
+    /** Total score (same as `breakdown.total`) */
+    points: number;
+    /** Size of the largest territory (tie-breaker) */
+    maxPropertiesSize: number;
+    /** Total crowns counted in the kingdom */
+    totalCrowns: number;
     /**
-     * Recruits a caveman from the cave board and places it on the lord's kingdom (Origins).
-     * @param command - Contains game state, lord ID, caveman ID, position, and resource positions to spend
-     * @returns Updated game state with next action
+     * `true` when the game is over: the score is the final score, identical
+     * to the one returned by `getResults`. `false` during the game: the score
+     * is a live estimate of the current state (end-of-game-only bonuses such
+     * as Harmony are not included yet).
      */
-    recruitCaveman: (command: RecruitCavemanCommand) => GameState;
+    final: boolean;
+    /** Detailed score */
+    breakdown: ScoreBreakdown;
+};
+
+/**
+ * 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;
+    /** Queendomino-specific state (only present in QueenDomino mode) */
+    queendomino?: QueenDominoState;
+    /** Origins-specific state (only present in KingdominoOrigins modes) */
+    origins?: OriginsState;
+    /** Age of Giants-specific state (only present in AgeOfGiants modes) */
+    ageOfGiants?: AgeOfGiantsState;
+};
+/**
+ * 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;
     /**
-     * Skips the current optional action (Queendomino/Origins).
-     * @param command - Contains game state and lord ID
-     * @returns Updated game state with next action
+     * Territory-by-territory and bonus-by-bonus score, computed by the same
+     * function as `calculatePlayerScore` (`breakdown.total === details.points`).
+     * Always set by `getResults`.
      */
-    skipOptionalAction: (command: SkipOptionalActionCommand) => GameState;
+    breakdown?: ScoreBreakdown;
 };
-
 /**
- * Error codes for domain-level errors.
- * These codes can be used for i18n and programmatic error handling.
+ * Final result including ranking position.
  */
-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";
-    readonly CANNOT_PLACE_KNIGHT: "CANNOT_PLACE_KNIGHT";
-    readonly MAX_KNIGHTS_REACHED: "MAX_KNIGHTS_REACHED";
-    readonly KNIGHT_TERRITORY_OCCUPIED: "KNIGHT_TERRITORY_OCCUPIED";
-    readonly CANNOT_AFFORD_BUILDING: "CANNOT_AFFORD_BUILDING";
-    readonly NO_CONSTRUCTION_SQUARE: "NO_CONSTRUCTION_SQUARE";
-    readonly DRAGON_UNAVAILABLE: "DRAGON_UNAVAILABLE";
-    readonly QUEEN_HOLDER_CANNOT_USE_DRAGON: "QUEEN_HOLDER_CANNOT_USE_DRAGON";
-    readonly BUILDING_NOT_FOUND: "BUILDING_NOT_FOUND";
-    readonly INVALID_OPTIONAL_ACTION: "INVALID_OPTIONAL_ACTION";
-    readonly GIANT_POOL_EMPTY: "GIANT_POOL_EMPTY";
-    readonly GIANT_NOT_FOUND: "GIANT_NOT_FOUND";
-    readonly INVALID_GIANT_PLACEMENT: "INVALID_GIANT_PLACEMENT";
-    readonly NOT_AOG_MODE: "NOT_AOG_MODE";
-    readonly FIRE_TOKEN_POOL_EMPTY: "FIRE_TOKEN_POOL_EMPTY";
-    readonly FIRE_TOKEN_INVALID_POSITION: "FIRE_TOKEN_INVALID_POSITION";
-    readonly NO_PENDING_FIRE_TOKEN: "NO_PENDING_FIRE_TOKEN";
-    readonly CANNOT_RECRUIT_CAVEMAN: "CANNOT_RECRUIT_CAVEMAN";
-    readonly INSUFFICIENT_RESOURCES: "INSUFFICIENT_RESOURCES";
-    readonly INVALID_CAVEMAN_PLACEMENT: "INVALID_CAVEMAN_PLACEMENT";
-    readonly CAVEMAN_NOT_FOUND: "CAVEMAN_NOT_FOUND";
-    readonly NOT_TRIBE_MODE: "NOT_TRIBE_MODE";
+type FinalResult = ScoreResult & {
+    /** Player's final position (1 = winner) */
+    position: number;
+};
+/** Game state with final results calculated */
+type GameWithResults = Game & {
+    result: FinalResult[];
 };
-type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
 /**
- * Structured domain error with code and context.
+ * Type guard to check if final results have been computed for the game
+ * (i.e. the state returned by `getResults`).
+ * @param game - The game state to check
+ * @returns True if the game carries a `result` array
  */
-interface DomainError {
-    /** Error code for programmatic handling */
-    code: ErrorCodeType;
-    /** Human-readable error message */
-    message: string;
-    /** Optional context data for debugging */
-    context?: Record<string, unknown>;
-}
+declare const isGameWithResults: (game: Game | GameWithResults) => game is GameWithResults;
+
+type AddExtraRulesCommand = {
+    game: GameState;
+    extraRules: string[];
+};
+
 /**
- * Creates a domain error object.
+ * Input for a single player: either a name string (human) or an object with
+ * an optional stable `id` and an optional bot config.
+ *
+ * Pass a stable `id` (e.g. your own user/account id) when the same person plays
+ * several games, such as a Dynasty: ids are otherwise regenerated by every
+ * `addPlayers` call. Ids must be non-empty and unique within one call.
  */
-declare const createDomainError: (code: ErrorCodeType, message: string, context?: Record<string, unknown>) => DomainError;
+type PlayerInput = string | {
+    id?: string;
+    name: string;
+    bot?: {
+        strategyName: string;
+    };
+};
+type AddPlayersCommand = {
+    game: GameState;
+    players: PlayerInput[];
+};
+
+type CalculatePlayerScoreCommand = {
+    /**
+     * Game state, at any stage: in progress (live score) or over (final
+     * score, also accepts the state returned by `getResults`).
+     */
+    game: Game;
+    /** Id of the player to score */
+    playerId: string;
+};
+
+type CalculateScoreCommand = {
+    kingdom: Kingdom;
+};
+
 /**
- * Base class for domain errors thrown by handlers.
+ * 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.
  */
-declare class DomainException extends Error {
-    readonly code: ErrorCodeType;
-    readonly context?: Record<string, unknown>;
-    constructor(error: DomainError);
-}
+type ValidationSeverity = "error" | "warning";
 /**
- * Error thrown when the game is in an invalid step for the requested action.
+ * Describes a single validation issue found in a game state.
  */
-declare class InvalidStepError extends DomainException {
-    constructor(message: string, context?: Record<string, unknown>);
-}
+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;
+};
+
 /**
- * Error thrown when a step execution fails.
+ * Command to check if a domino can be placed anywhere on a kingdom.
  */
-declare class StepExecutionError extends DomainException {
-    constructor(message: string, code?: ErrorCodeType, context?: Record<string, unknown>);
-}
+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;
+};
+
+type ChooseDominoCommand = {
+    game: GameState;
+    dominoPick: number;
+    lordId: string;
+};
+
+type ConstructBuildingCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    buildingId: number;
+    position: Position;
+};
+
+type CreateGameCommand = {
+    mode: string;
+    seed?: string;
+};
+
+type DiscardDominoCommand = {
+    game: GameState;
+    lordId: string;
+};
+
+/**
+ * How Dynasty results group a player across games.
+ * - `"playerId"` (default): by `playerId`. Pass stable ids to `addPlayers`
+ *   (`players: [{ id, name }]`) so the same person keeps one id across games.
+ * - `"playerName"`: by player name, for games whose players were added
+ *   without stable ids (ids are regenerated by every `addPlayers` call).
+ */
+type DynastyGroupBy = "playerId" | "playerName";
+type GetDynastyResultCommand = {
+    games: GameWithResults[];
+    /** Grouping key across games. Defaults to `"playerId"`. */
+    groupBy?: DynastyGroupBy;
+};
+
+type GetExtraRulesCommand = {
+    mode: GameMode["name"];
+    players: number;
+};
+
+type GetModesCommand = Record<string, never>;
+
+type GetResultCommand = {
+    game: GameState;
+};
+
 /**
- * Error thrown when an action execution fails.
+ * Command to query the valid targets of the current extension action
+ * (Queendomino, Origins, Age of Giants).
+ *
+ * Any game state is accepted: the query answers empty (`[]`, or `false` for
+ * `canSkipOptionalAction`) when the action is not the one the game waits for,
+ * when it does not exist in the game mode, or when `lordId` is not the lord
+ * that must play.
  */
-declare class ActionExecutionError extends DomainException {
-    constructor(message: string, code?: ErrorCodeType, context?: Record<string, unknown>);
-}
+type GetValidActionTargetsCommand = {
+    /** The current game state */
+    game: GameState;
+    /** Lord to check. Defaults to the lord that must play (`game.nextAction.nextLord`) */
+    lordId?: string;
+};
+/** Command for `getValidFireTokenPositions` (Origins `placeFireToken`). */
+type GetValidFireTokenPositionsCommand = GetValidActionTargetsCommand;
+/** Command for `getValidKnightPositions` (Queendomino `placeKnight`). */
+type GetValidKnightPositionsCommand = GetValidActionTargetsCommand;
+/** Command for `getValidBuildingPositions` (Queendomino `constructBuilding`). */
+type GetValidBuildingPositionsCommand = GetValidActionTargetsCommand;
+/** Command for `getAffordableBuildings` (Queendomino `constructBuilding`). */
+type GetAffordableBuildingsCommand = GetValidActionTargetsCommand;
+/** Command for `getValidDragonTargets` (Queendomino `useDragon`). */
+type GetValidDragonTargetsCommand = GetValidActionTargetsCommand;
+/** Command for `getValidCavemanPlacements` (Origins Tribe `recruitCaveman`). */
+type GetValidCavemanPlacementsCommand = GetValidActionTargetsCommand;
+/** Command for `getValidGiantPositions` (Age of Giants `placeGiant`). */
+type GetValidGiantPositionsCommand = GetValidActionTargetsCommand;
+/** Command for `getValidGiantTargets` (Age of Giants `sendGiant`). */
+type GetValidGiantTargetsCommand = GetValidActionTargetsCommand;
+/** Command for `canSkipOptionalAction` (`skipOptionalAction`). */
+type CanSkipOptionalActionCommand = GetValidActionTargetsCommand;
+
+/**
+ * Command for `getValidDominoPicks` (`chooseDomino`): any game state and an
+ * optional lord (default: the lord that must play).
+ */
+type GetValidDominoPicksCommand = GetValidActionTargetsCommand;
+
 /**
- * Error thrown when a required entity is not found.
+ * Command to get all valid placements for a domino on a kingdom.
  */
-declare class NotFoundError extends DomainException {
-    constructor(message: string, code?: ErrorCodeType, context?: Record<string, unknown>);
-}
+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;
+};
+
+type PlaceDominoCommand = {
+    game: GameState;
+    lordId: string;
+    position: Position;
+    rotation: Rotation;
+};
+
+type PlaceFireTokenCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    position: Position;
+};
+
+type PlaceGiantCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    position: Position;
+};
+
+type PlaceKnightCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    position: Position;
+};
+
+type RecruitCavemanCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    /** ID of the caveman tile to recruit */
+    cavemanId: number;
+    /** Position on the kingdom to place the caveman */
+    position: Position;
+    /** Positions of resources to spend as payment */
+    resourcePositions: Position[];
+};
+
+type SendGiantCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    /** Index of the giant to send from the current player's giants array */
+    giantIndex: number;
+    /** ID of the opponent player to receive the giant */
+    targetPlayerId: string;
+    /**
+     * Crown of the opponent's kingdom the giant will cover. Per the official
+     * rules the targeted opponent chooses it: omit it and the engine places the
+     * giant automatically when the opponent has a single free crown, or asks
+     * the opponent with a `placeGiant` action otherwise. When provided, it must
+     * be the crown chosen by the opponent.
+     */
+    targetCrownPosition?: Position;
+};
+
 /**
- * Error thrown when validation fails.
+ * Command to serialize a game state to JSON.
  */
-declare class ValidationError extends DomainException {
-    constructor(message: string, code: ErrorCodeType, context?: Record<string, unknown>);
-}
+type SerializeGameCommand = {
+    /** The game state to serialize */
+    game: GameState;
+};
 /**
- * Error thrown when undo is requested but no previous state exists.
+ * Command to deserialize a game state from JSON.
  */
-declare class UndoError extends DomainException {
-    constructor(message?: string, context?: Record<string, unknown>);
-}
+type DeserializeGameCommand = {
+    /** The JSON string to deserialize */
+    json: string;
+};
+
+type SkipOptionalActionCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+};
+
+type StartGameCommand = {
+    game: GameState;
+};
+
+type UseDragonCommand = {
+    game: GameWithNextAction;
+    lordId: string;
+    buildingId: number;
+};
+
+type DynastyResult = {
+    /**
+     * Player id. With `groupBy: "playerName"`, the id the player had in the
+     * first game where that name appears.
+     */
+    playerId: string;
+    playerName: string;
+    totalPoints: number;
+    gamesPoints: number[];
+    position: number;
+};
+
+type ShuffleMethod = <T>(array: T[]) => T[];
+
 /**
- * Error thrown when redo is requested but no future state exists.
+ * Price of recruiting one caveman of the cave board.
  */
-declare class RedoError extends DomainException {
-    constructor(message?: string, context?: Record<string, unknown>);
-}
+type RecruitmentCost = {
+    /** Where the caveman is taken from */
+    source: "visible" | "drawPile";
+    /** Number of resources to spend */
+    resourceCount: number;
+    /** Number of different resource types among the spent resources */
+    differentTypes: number;
+};
 
 /**
- * Translation keys for internationalization support.
- * Use these keys instead of hardcoded strings for translatable content.
+ * A caveman of the cave board that can be recruited now, with every valid way
+ * to pay for it (Origins Tribe).
  */
-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";
-    readonly ERROR_CANNOT_PLACE_KNIGHT: "error.cannotPlaceKnight";
-    readonly ERROR_MAX_KNIGHTS_REACHED: "error.maxKnightsReached";
-    readonly ERROR_KNIGHT_TERRITORY_OCCUPIED: "error.knightTerritoryOccupied";
-    readonly ERROR_CANNOT_AFFORD_BUILDING: "error.cannotAffordBuilding";
-    readonly ERROR_NO_CONSTRUCTION_SQUARE: "error.noConstructionSquare";
-    readonly ERROR_DRAGON_UNAVAILABLE: "error.dragonUnavailable";
-    readonly ERROR_QUEEN_HOLDER_CANNOT_USE_DRAGON: "error.queenHolderCannotUseDragon";
-    readonly ERROR_BUILDING_NOT_FOUND: "error.buildingNotFound";
-    readonly ERROR_INVALID_OPTIONAL_ACTION: "error.invalidOptionalAction";
-    readonly ERROR_GIANT_POOL_EMPTY: "error.giantPoolEmpty";
-    readonly ERROR_GIANT_NOT_FOUND: "error.giantNotFound";
-    readonly ERROR_INVALID_GIANT_PLACEMENT: "error.invalidGiantPlacement";
-    readonly ERROR_NOT_AOG_MODE: "error.notAogMode";
-    readonly ERROR_FIRE_TOKEN_POOL_EMPTY: "error.fireTokenPoolEmpty";
-    readonly ERROR_FIRE_TOKEN_INVALID_POSITION: "error.fireTokenInvalidPosition";
-    readonly ERROR_NO_PENDING_FIRE_TOKEN: "error.noPendingFireToken";
-    readonly ERROR_CANNOT_RECRUIT_CAVEMAN: "error.cannotRecruitCaveman";
-    readonly ERROR_INSUFFICIENT_RESOURCES: "error.insufficientResources";
-    readonly ERROR_INVALID_CAVEMAN_PLACEMENT: "error.invalidCavemanPlacement";
-    readonly ERROR_CAVEMAN_NOT_FOUND: "error.cavemanNotFound";
-    readonly ERROR_NOT_TRIBE_MODE: "error.notTribeMode";
+type CavemanRecruitmentOption = {
+    /** Caveman to pass as `cavemanId` to `recruitCaveman` */
+    cavemanId: number;
+    /** Visible caveman (2 different resources) or draw pile (4 different) */
+    source: RecruitmentCost["source"];
+    /** Every valid `resourcePositions` payment for this caveman */
+    resourceCombinations: Position[][];
 };
-type TranslationKeyType = (typeof TranslationKey)[keyof typeof TranslationKey];
 /**
- * Default English translations.
+ * Valid `recruitCaveman` arguments: any option, any of its resource
+ * combinations and any position can be combined. Both lists are empty when
+ * no recruitment is possible.
  */
-declare const defaultTranslations: Record<TranslationKeyType, string>;
+type ValidCavemanPlacements = {
+    /** Recruitable cavemen with their valid payments */
+    options: CavemanRecruitmentOption[];
+    /** Squares where the recruited caveman can be placed */
+    positions: Position[];
+};
 /**
- * Maps ErrorCode values to their corresponding TranslationKey values.
- * Used by handlers to translate error codes into localized messages.
+ * Valid `sendGiant` arguments: any giant index can be sent to any target
+ * player. Both lists are empty when no giant can be sent. The crown covered is
+ * chosen by the targeted opponent (see `getValidGiantPositions`).
  */
-declare const errorCodeToTranslationKey: Record<ErrorCodeType, TranslationKeyType>;
+type ValidGiantTargets = {
+    /** Indexes in the sender's `giants` array that can be sent */
+    giantIndexes: number[];
+    /** Opponents that can receive a giant */
+    targetPlayerIds: string[];
+};
+/** Signature shared by the valid-target queries. */
+type ValidActionTargetsUseCase<T> = (game: GameState, lordId?: string) => T;
+
 /**
- * Translates an error code to a localized message.
- * Convenience function combining errorCodeToTranslationKey lookup and translation.
+ * Represents a valid placement position with rotation.
  */
-declare const translateErrorCode: (translator: Translator, code: ErrorCodeType, params?: Record<string, string | number>) => string;
+type ValidPlacement = {
+    position: Position;
+    rotation: Rotation;
+};
+
 /**
- * Translator interface for custom translations.
+ * 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 });
+ * ```
  */
-interface Translator {
+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;
     /**
-     * Translate a key to the current language.
-     * @param key - The translation key
-     * @param params - Optional parameters for interpolation
-     * @returns The translated string
+     * 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'
      */
-    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;
+    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;
+    /**
+     * Numbers of the revealed dominoes `chooseDomino` accepts for the lord
+     * (default: the lord to play): the dominoes not picked yet and, with the
+     * Origins "Neolithic" rule, not reserved for the other player (the first
+     * pick of each line takes the pair 1 & 4 or 2 & 3 for the lord's player).
+     * @param command - Contains game state and optional lord ID
+     * @returns Domino numbers, or [] when the game does not wait for this lord to pick
+     */
+    getValidDominoPicks: (command: GetValidDominoPicksCommand) => number[];
+    /**
+     * 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[];
+    /**
+     * Places a giant on a crown in the lord's kingdom (Age of Giants).
+     * Mandatory after placing a giant domino (A-F). The giant covers the crown for scoring.
+     * @param command - Contains game state, lord ID, and crown position
+     * @returns Updated game state with next action
+     */
+    placeGiant: (command: PlaceGiantCommand) => GameState;
+    /**
+     * Sends a giant from the lord's kingdom to an opponent's kingdom (Age of Giants).
+     * Optional after placing a footprint domino (49-54). The opponent chooses which crown is covered.
+     * @param command - Contains game state, lord ID, giant index, target player ID, and target crown position
+     * @returns Updated game state with next action
+     */
+    sendGiant: (command: SendGiantCommand) => GameState;
+    /**
+     * Places a knight on the lord's kingdom at the specified position (Queendomino).
+     * @param command - Contains game state, lord ID, and position
+     * @returns Updated game state with next action
+     */
+    placeKnight: (command: PlaceKnightCommand) => GameState;
+    /**
+     * Constructs a building on the lord's kingdom (Queendomino).
+     * @param command - Contains game state, lord ID, building ID, and position
+     * @returns Updated game state with next action
+     */
+    constructBuilding: (command: ConstructBuildingCommand) => GameState;
+    /**
+     * Uses the dragon to destroy a building on the builders board (Queendomino).
+     * @param command - Contains game state, lord ID, and building ID
+     * @returns Updated game state with next action
+     */
+    useDragon: (command: UseDragonCommand) => GameState;
+    /**
+     * Places a fire token on the lord's kingdom after placing a volcano domino (Origins).
+     * @param command - Contains game state, lord ID, and target position
+     * @returns Updated game state with next action
+     */
+    placeFireToken: (command: PlaceFireTokenCommand) => GameState;
+    /**
+     * Recruits a caveman from the cave board and places it on the lord's kingdom (Origins).
+     * @param command - Contains game state, lord ID, caveman ID, position, and resource positions to spend
+     * @returns Updated game state with next action
+     */
+    recruitCaveman: (command: RecruitCavemanCommand) => GameState;
+    /**
+     * Skips the current optional action (Queendomino/Origins).
+     * @param command - Contains game state and lord ID
+     * @returns Updated game state with next action
+     */
+    skipOptionalAction: (command: SkipOptionalActionCommand) => GameState;
+    /**
+     * Squares where `placeFireToken` accepts the pending fire token (Origins).
+     * @param command - Contains game state and optional lord ID
+     * @returns Valid positions, or [] when no fire token is pending for the lord
+     */
+    getValidFireTokenPositions: (command: GetValidFireTokenPositionsCommand) => Position[];
+    /**
+     * Squares where `placeKnight` accepts a knight: squares of the domino just
+     * placed holding no knight yet, while the player still has a knight
+     * available (Queendomino).
+     * @param command - Contains game state and optional lord ID
+     * @returns Valid positions, or [] when placeKnight is not the current action
+     */
+    getValidKnightPositions: (command: GetValidKnightPositionsCommand) => Position[];
+    /**
+     * Construction squares where `constructBuilding` succeeds with any building
+     * of `getAffordableBuildings` (Queendomino).
+     * @param command - Contains game state and optional lord ID
+     * @returns Valid positions, or [] when no construction is possible
+     */
+    getValidBuildingPositions: (command: GetValidBuildingPositionsCommand) => Position[];
+    /**
+     * Buildings of the Builders Board the lord can pay for, buildable on any
+     * square of `getValidBuildingPositions` (Queendomino).
+     * @param command - Contains game state and optional lord ID
+     * @returns Buildings to pass to constructBuilding, or [] when none applies
+     */
+    getAffordableBuildings: (command: GetAffordableBuildingsCommand) => BuildingTile[];
+    /**
+     * Buildings of the Builders Board that `useDragon` accepts to burn
+     * (Queendomino): every building of the board when the Dragon is still in
+     * its cave this round, the lord does not host the Queen and can pay its
+     * 1 coin.
+     * @param command - Contains game state and optional lord ID
+     * @returns Buildings to pass to useDragon, or [] when the Dragon cannot be used
+     */
+    getValidDragonTargets: (command: GetValidDragonTargetsCommand) => BuildingTile[];
+    /**
+     * Valid `recruitCaveman` arguments: recruitable cavemen with every valid
+     * resource payment, and the squares for the caveman (Origins Tribe).
+     * @param command - Contains game state and optional lord ID
+     * @returns Options and positions (any combination is valid), both empty when none applies
+     */
+    getValidCavemanPlacements: (command: GetValidCavemanPlacementsCommand) => ValidCavemanPlacements;
+    /**
+     * Crowns where `placeGiant` accepts the giant (Age of Giants), including a
+     * giant sent by an opponent: the targeted player's own crowns.
+     * @param command - Contains game state and optional lord ID
+     * @returns Valid crown positions, or [] when placeGiant is not the current action
+     */
+    getValidGiantPositions: (command: GetValidGiantPositionsCommand) => Position[];
+    /**
+     * Valid `sendGiant` arguments: the lord's giants that can be sent and the
+     * opponents that can receive one (Age of Giants). The opponent chooses the crown.
+     * @param command - Contains game state and optional lord ID
+     * @returns Giant indexes and target player IDs (any pair is valid), both empty when none applies
+     */
+    getValidGiantTargets: (command: GetValidGiantTargetsCommand) => ValidGiantTargets;
+    /**
+     * Whether `skipOptionalAction` can skip the current action for the lord
+     * (false for placeGiant, which is mandatory).
+     * @param command - Contains game state and optional lord ID
+     * @returns True if the current action can be skipped
+     */
+    canSkipOptionalAction: (command: CanSkipOptionalActionCommand) => boolean;
+    /**
+     * Calculates the mode-aware score of one player, with its breakdown
+     * (territories and every bonus of the game mode: Queen, buildings, fire
+     * tokens, resources, totems, cavemen, quests, optional rules...).
+     *
+     * During the game the score is live (`final: false`): it reflects the
+     * current state and end-of-game-only bonuses (Harmony, Homo Habilis,
+     * Harmony quest) are not included yet. Once the game is over it is final
+     * and identical to the score returned by `getResults`.
+     * @param command - Contains the game state (any stage) and the player id
+     * @returns The player's score with its breakdown
+     * @throws NotFoundError if the player is not in the game
+     */
+    calculatePlayerScore: (command: CalculatePlayerScoreCommand) => PlayerScore;
+};
 
 type Logger = Readonly<{
     info: (message: string) => void;
     error: (message: string) => void;
 }>;
 
-type ShuffleMethod = <T>(array: T[]) => T[];
-
 type UuidMethod = () => string;
 
 /**
@@ -1419,6 +1981,19 @@ type GameEventCallbacks = {
         lordId: string;
         dominoNumber: number;
     }) => void;
+    /**
+     * Called after the first pick of a line chose the Neolithic pair (Origins,
+     * 2 players): `dominoNumbers` (pair 1 & 4 or 2 & 3) are reserved for the
+     * picking lord's player, `opponentDominoNumbers` for the other player.
+     * Emitted after `onDominoPicked`.
+     */
+    onNeolithicPairChosen?: (event: {
+        game: GameState;
+        lordId: string;
+        playerId: string;
+        dominoNumbers: number[];
+        opponentDominoNumbers: number[];
+    }) => void;
     /** Called after a lord places a domino on their kingdom */
     onDominoPlaced?: (event: {
         game: GameState;
@@ -1439,7 +2014,7 @@ type GameEventCallbacks = {
         game: GameState;
         turn: number;
     }) => void;
-    /** Called when the game reaches the result phase */
+    /** Called once when the game reaches the result phase, whatever the action that ended it */
     onGameEnd?: (event: {
         game: GameState;
     }) => void;
@@ -1482,14 +2057,31 @@ type GameEventCallbacks = {
         lordId: string;
         targetPlayerId: string;
     }) => void;
+    /** Called after extra rules are added to the game (setup) */
+    onExtraRulesAdded?: (event: {
+        game: GameWithNextStep;
+        extraRules: string[];
+    }) => void;
+    /** Called after a lord skips an optional action (QueenDomino, Origins, Age of Giants) */
+    onOptionalActionSkipped?: (event: {
+        game: GameState;
+        lordId: string;
+        /** The optional action that was skipped (e.g. `"placeKnight"`, `"sendGiant"`) */
+        skippedAction: PlayerActions;
+    }) => 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
+ * Derived events are detected centrally, by comparing the game state before
+ * and after every gameplay method (whatever the method that caused it):
+ * - `onTurnEnd` + `onTurnStart`: emitted when the turn number changes
+ * - `onGameEnd`: emitted exactly once, when the game transitions to the
+ *   "result" step (placeDomino, discardDomino, skipOptionalAction,
+ *   placeFireToken, recruitCaveman, useDragon, placeGiant, sendGiant…)
+ *
+ * The action-specific event is always emitted before the derived ones.
  *
  * @param engine - The base game engine to wrap
  * @param callbacks - Optional event callbacks
@@ -1561,6 +2153,88 @@ type RuleRepository = {
     getAllExtra: () => ExtraRule[];
 };
 
+/**
+ * Mode-aware evaluation and extension-action decisions of the built-in bots
+ * (Queendomino, Kingdomino Origins, Age of Giants).
+ *
+ * Every decision follows the same recipe, without re-implementing any rule:
+ * 1. enumerate the valid targets of the action (`getValidActionTargets`, whose
+ *    targets are guaranteed to be accepted by the action), plus "skip" when
+ *    `canSkipOptionalAction` allows it;
+ * 2. simulate each target with the pure use case of the action;
+ * 3. evaluate the resulting state with the mode-aware live score
+ *    (`computePlayerScore`) of the deciding player, plus a small value for the
+ *    assets the score does not count yet (coins, knights left, Tribe
+ *    resources), optionally minus the score of the best opponent;
+ * 4. keep the best target (the first one on ties, "skip" coming first).
+ */
+
+/**
+ * Common part of the context given to a bot strategy for an extension action.
+ */
+type ExtensionContext = {
+    game: GameWithNextAction;
+    /** Lord whose action it is (`game.nextAction.nextLord`) */
+    lordId: string;
+    /**
+     * Player who decides: the owner of the lord. For a giant sent by an
+     * opponent (`ageOfGiants.pendingGiant`), the targeted player.
+     */
+    playerId: string;
+    /** Whether returning `null` (skipping the action) is allowed */
+    canSkip: boolean;
+};
+/** `placeKnight` (Queendomino): squares where a knight can go. */
+type KnightContext = ExtensionContext & {
+    validPositions: Position[];
+};
+/** `constructBuilding` (Queendomino): any building on any square. */
+type BuildingContext = ExtensionContext & {
+    validPositions: Position[];
+    affordableBuildings: BuildingTile[];
+};
+/** A building to construct and its construction square. */
+type BuildingChoice = {
+    buildingId: number;
+    position: Position;
+};
+/** `useDragon` (Queendomino): buildings of the board the dragon can burn. */
+type DragonContext = ExtensionContext & {
+    targetBuildings: BuildingTile[];
+};
+/** `placeFireToken` (Origins): squares where the pending token can go. */
+type FireTokenContext = ExtensionContext & {
+    validPositions: Position[];
+};
+/** `recruitCaveman` (Origins Tribe): recruitable cavemen and squares. */
+type CavemanContext = ExtensionContext & {
+    recruitment: ValidCavemanPlacements;
+};
+/** A caveman to recruit, where to place it and how to pay for it. */
+type CavemanChoice = {
+    cavemanId: number;
+    position: Position;
+    resourcePositions: Position[];
+};
+/**
+ * `placeGiant` (Age of Giants, mandatory): crowns of the deciding player's
+ * kingdom the giant can cover.
+ */
+type GiantPositionContext = ExtensionContext & {
+    validPositions: Position[];
+    /** True when the giant was sent by an opponent (`pendingGiant`) */
+    sentByOpponent: boolean;
+};
+/** `sendGiant` (Age of Giants): giants that can be sent and their targets. */
+type SendGiantContext = ExtensionContext & {
+    targets: ValidGiantTargets;
+};
+/** A giant to send and the opponent receiving it. */
+type SendGiantChoice = {
+    giantIndex: number;
+    targetPlayerId: string;
+};
+
 /**
  * Context provided to a bot strategy when choosing a domino to pick.
  */
@@ -1580,38 +2254,72 @@ type PlaceContext = {
     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.
+ * A bot strategy that decides which domino to pick and where to place it,
+ * and optionally how to play the extension actions (Queendomino, Origins,
+ * Age of Giants). Strategies are stateless — all information comes from the
+ * context.
+ *
+ * Every extension method is optional: when a strategy does not define one,
+ * `playBotTurn` uses the choice of `greedyStrategy` (best immediate
+ * mode-aware score). An extension method is only called when the action has
+ * at least one valid target, and every target of its context is accepted by
+ * the action. Returning `null` skips the action (for the mandatory
+ * `placeGiant`, `null` falls back to the greedy choice).
  */
 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.
+    /** `placeKnight` (Queendomino): a square, or null to skip */
+    chooseKnightPosition?: (context: KnightContext) => Position | null;
+    /** `constructBuilding` (Queendomino): a building and square, or null */
+    chooseBuilding?: (context: BuildingContext) => BuildingChoice | null;
+    /** `useDragon` (Queendomino): id of the building to burn, or null */
+    chooseDragonTarget?: (context: DragonContext) => number | null;
+    /** `placeFireToken` (Origins): a square, or null to skip */
+    chooseFireTokenPosition?: (context: FireTokenContext) => Position | null;
+    /** `recruitCaveman` (Origins Tribe): a recruitment, or null to skip */
+    chooseCavemanRecruitment?: (context: CavemanContext) => CavemanChoice | null;
+    /** `placeGiant` (Age of Giants, mandatory): the crown to cover */
+    chooseGiantPosition?: (context: GiantPositionContext) => Position | null;
+    /** `sendGiant` (Age of Giants): a giant and its target, or null to skip */
+    chooseGiantToSend?: (context: SendGiantContext) => SendGiantChoice | null;
+};
+/** The extension-action methods of a strategy. */
+type BotExtensionChoices = Required<Omit<BotStrategy, "chooseDomino" | "choosePlacement">>;
+/**
+ * Bot strategy that makes random choices, seeded by the game seed and the
+ * decision point (the same game replayed with the same seed gets the same
+ * decisions). Picks a random available domino, places it at a random valid
+ * position, and plays every extension action on a random valid target, or
+ * skips it ("skip" being one more option when the action is optional).
  */
 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.
+ * Bot strategy that maximizes the immediate mode-aware score.
+ * Evaluates every valid placement and picks the one yielding the highest
+ * score (territories plus every bonus of the mode). When picking a domino,
+ * simulates the best placement for each option. Extension actions: the
+ * target with the best own score (taxes, buildings, fire tokens, cavemen,
+ * least costly crown for a giant), or skip when nothing improves it.
  */
-declare const greedyStrategy: BotStrategy;
+declare const greedyStrategy: BotStrategy & BotExtensionChoices;
 /**
  * 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.
+ * When making decisions, considers not just the immediate mode-aware score
+ * but also the best possible score achievable in the next turn by peeking at
+ * the upcoming domino batch from the draw pile. Extension actions: the target
+ * with the best own score minus half the best opponent's score (e.g. sending
+ * a giant to the leader, taking a Totem majority from them).
  */
-declare const advancedStrategy: BotStrategy;
+declare const advancedStrategy: BotStrategy & BotExtensionChoices;
 /**
  * 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).
+ * Explores the next turns, but limits the number of placements evaluated per
+ * domino to the top candidates (by greedy mode-aware score). Since kingdoms
+ * are independent, the domino search is a solo optimization. Extension
+ * actions: the target that maximizes the lead over the best opponent.
  */
-declare const expertStrategy: BotStrategy;
+declare const expertStrategy: BotStrategy & BotExtensionChoices;
 /**
  * Executes a single bot turn using the given strategy and engine.
  * Reads the current game state to determine the required action,
@@ -1653,28 +2361,52 @@ declare const getStrategy: (name: string, custom?: Record<string, BotStrategy>)
  */
 declare const getStrategyNames: () => string[];
 
+type CalculatePlayerScoreUseCase = (game: Game, playerId: string) => Result<PlayerScore>;
+
 type ConstructBuildingUseCase = (game: GameWithNextAction, lordId: string, buildingId: number, position: Position) => GameStateResult;
 
+/**
+ * Current action log format version.
+ *
+ * - `1` (or no `version` field): legacy logs. `createGame` may omit the seed,
+ *   player ids and lord ids are not recorded, so a replay regenerates them.
+ * - `2`: the effective seed, the game id, the player ids and the lord ids are
+ *   recorded, so a replay reproduces a strictly identical game state.
+ *
+ * Version 1 logs remain replayable.
+ */
+declare const ACTION_LOG_VERSION = 2;
 /**
  * The types of state-changing actions that can be recorded.
  */
-type ActionType = "createGame" | "addPlayers" | "addExtraRules" | "startGame" | "chooseDomino" | "placeDomino" | "discardDomino" | "placeGiant" | "sendGiant";
+type ActionType = "createGame" | "addPlayers" | "addExtraRules" | "startGame" | "chooseDomino" | "placeDomino" | "discardDomino" | "placeGiant" | "sendGiant" | "placeKnight" | "constructBuilding" | "useDragon" | "placeFireToken" | "recruitCaveman" | "skipOptionalAction";
 /**
  * Payload types for each action, containing only the command parameters
- * (excluding the game state, which is too large to store).
+ * (excluding the game state, which is too large to store), plus the ids the
+ * engine generated so that a replay reproduces them.
  */
 type ActionPayloadMap = {
     createGame: {
         mode: string;
+        /** Effective seed of the game (generated by the engine when the caller gave none) */
         seed?: string;
+        /** Id the engine generated for the game (restored on replay) */
+        gameId?: string;
     };
+    /**
+     * Players as `{ id, name, bot? }` objects carrying the ids the engine
+     * assigned (legacy logs may contain plain names).
+     */
     addPlayers: {
         players: PlayerInput[];
     };
     addExtraRules: {
         extraRules: string[];
     };
-    startGame: Record<string, never>;
+    startGame: {
+        /** Ids of the lords, in `game.lords` order (restored on replay) */
+        lordIds?: string[];
+    };
     chooseDomino: {
         lordId: string;
         dominoPick: number;
@@ -1687,6 +2419,10 @@ type ActionPayloadMap = {
     discardDomino: {
         lordId: string;
     };
+    /**
+     * `lordId` is the lord that played the action: the current lord, or a lord
+     * of the targeted player when it places a giant sent by an opponent.
+     */
     placeGiant: {
         lordId: string;
         position: Position;
@@ -1695,7 +2431,33 @@ type ActionPayloadMap = {
         lordId: string;
         giantIndex: number;
         targetPlayerId: string;
-        targetCrownPosition: Position;
+        targetCrownPosition?: Position;
+    };
+    placeKnight: {
+        lordId: string;
+        position: Position;
+    };
+    constructBuilding: {
+        lordId: string;
+        buildingId: number;
+        position: Position;
+    };
+    useDragon: {
+        lordId: string;
+        buildingId: number;
+    };
+    placeFireToken: {
+        lordId: string;
+        position: Position;
+    };
+    recruitCaveman: {
+        lordId: string;
+        cavemanId: number;
+        position: Position;
+        resourcePositions: Position[];
+    };
+    skipOptionalAction: {
+        lordId: string;
     };
 };
 /**
@@ -1716,6 +2478,8 @@ type ActionEntry<T extends ActionType = ActionType> = {
 /**
  * An immutable log of all actions performed during a game.
  * Can be used to replay a game or analyze player decisions.
+ * It is plain JSON: persist it with `JSON.stringify` and read it back with
+ * `JSON.parse`.
  *
  * @example
  * ```typescript
@@ -1728,6 +2492,8 @@ type ActionEntry<T extends ActionType = ActionType> = {
  * ```
  */
 type GameActionLog = {
+    /** Format version (see `ACTION_LOG_VERSION`); absent in legacy logs (version 1) */
+    version?: number;
     /** The game ID this log belongs to */
     gameId: string;
     /** Immutable array of recorded actions */
@@ -1774,12 +2540,18 @@ declare const wrapWithActionLog: (engine: GameEngine) => {
 };
 /**
  * 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)
+ * Version 2 logs (see `ACTION_LOG_VERSION`) record the effective seed and every
+ * generated id (game, players, lords), so the replayed state is strictly
+ * identical to the original one, whatever the replay engine's `uuidMethod`
+ * and `shuffleMethod`. Legacy logs (version 1) are still replayed; their ids
+ * are regenerated, and when they lack a seed the replay engine should use the
+ * same configuration (especially shuffleMethod) as the original game.
+ *
+ * @param engine - A game engine instance
  * @param log - The action log to replay
  * @returns The final game state after replaying all actions
+ * @throws Error if the log is empty, does not start with createGame, or has an unsupported version
  */
 declare const replayActions: (engine: GameEngine, log: GameActionLog) => GameState;
 
@@ -1870,7 +2642,7 @@ type PlaceKnightUseCase = (game: GameWithNextAction, lordId: string, position: P
 
 type RecruitCavemanUseCase = (game: GameWithNextAction, lordId: string, cavemanId: number, position: Position, resourcePositions: Position[]) => GameStateResult;
 
-type SendGiantUseCase = (game: GameWithNextAction, lordId: string, giantIndex: number, targetPlayerId: string, targetCrownPosition: Position) => GameStateResult;
+type SendGiantUseCase = (game: GameWithNextAction, lordId: string, giantIndex: number, targetPlayerId: string, targetCrownPosition?: Position) => GameStateResult;
 
 /**
  * Serializes a game state to a JSON string.
@@ -1918,6 +2690,11 @@ declare const createSavePoint: (game: GameState) => GameSavePoint;
 declare const restoreFromSavePoint: (savePoint: GameSavePoint) => Result<GameState>;
 
 type SkipOptionalActionUseCase = (game: GameWithNextAction, lordId: string) => GameStateResult;
+/**
+ * Whether `action` is an optional action that `skipOptionalAction` accepts.
+ * `placeDomino`, `pickDomino`, `pass` and `placeGiant` cannot be skipped.
+ */
+declare const isSkippableAction: (action: PlayerActions) => boolean;
 
 type UseDragonUseCase = (game: GameWithNextAction, lordId: string, buildingId: number) => GameStateResult;
 
@@ -1946,4 +2723,4 @@ type UseDragonUseCase = (game: GameWithNextAction, lordId: string, buildingId: n
  */
 declare const createGameEngine: (config: Partial<EngineConfig>) => GameEngine;
 
-export { type ActionEntry, ActionExecutionError, type ActionPayloadMap, type ActionType, type AddExtraRulesCommand, type AddPlayersCommand, type AgeOfGiantsState, type BasicRules, type BotStrategy, type BuildersBoard, type BuildingSlot, type BuildingTile, type BuildingsRepository, type CalculateScoreCommand, type CanPlaceDominoCommand, type CaveBoard, type CavemanTile, type CavemenRepository, type ChooseDominoCommand, type ConstructBuildingCommand, type ConstructBuildingUseCase, 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 EndGameScoring, type EndGameScoringType, type EngineConfig, ErrorCode, type ErrorCodeType, type ExtraRule, type FinalResult, type FireTokenPool, 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, type HunterGathererKind, type HunterGathererTile, type ImmediateBonus, type ImmediateBonusType, InvalidStepError, type Kingdom, type Knight, type Logger, type Lord, MAX_KINGDOM_SIZE, type ModeRepository, type NextAction, type NextStep, NotFoundError, type ObjectValues, type OriginsState, type OriginsSubMode, type PendingFireToken, type PickContext, type PlaceContext, type PlaceDominoCommand, type PlaceFireTokenCommand, type PlaceFireTokenUseCase, type PlaceGiantCommand, type PlaceGiantUseCase, type PlaceKnightCommand, type PlaceKnightUseCase, type PlacedBuilding, type PlacedCaveman, type PlacedFireToken, type PlacedGiant, type Player, type PlayerActions, type PlayerInput, type PlayerPayload, type Players, type PlayersPayload, type Position, type QueenDominoState, type QuestTile, type QuestTilesRepository, type QuestType, type RecruitCavemanCommand, type RecruitCavemanUseCase, RedoError, type Resource, type ResourceType, type RevealsDomino, type Rotation, type RuleRepository, type Rules, type Score, type ScoreResult, type SelectedRules, type SendGiantCommand, type SendGiantUseCase, type SerializeGameCommand, type ShuffleMethod, type SkipOptionalActionCommand, type SkipOptionalActionUseCase, type StartGameCommand, StepExecutionError, type StrategyName, type Tile, type TotemBonus, type TotemState, TranslationKey, type TranslationKeyType, type Translator, UndoError, type UseDragonCommand, type UseDragonUseCase, type UuidMethod, type ValidPlacement, ValidationError, type ValidationIssue, type ValidationSeverity, WARRIOR_POWER, type WarriorTile, type WarriorType, advancedStrategy, appendAction, canRedo, canUndo, clearHistory, createActionLog, createDomainError, createGameEngine, createGameHistory, createSavePoint, createTranslator, defaultTranslations, defaultTranslator, deserializeGame, errorCodeToTranslationKey, expertStrategy, gameSteps, getActions, getActionsByTurn, getActionsByType, getHistorySize, getStrategy, getStrategyNames, greedyStrategy, hunterGathererKinds, isBotTurn, isGameWithNextAction, isGameWithNextStep, originsSubModes, playBotTurn, playBotTurns, playerActions, pushState, questTypes, randomStrategy, redo, replayActions, resourceTypes, restoreFromSavePoint, serializeGame, summarizeGameState, translateErrorCode, undo, validateGameState, warriorTypes, wrapWithActionLog, wrapWithDebug, wrapWithEvents };
+export { ACTION_LOG_VERSION, type ActionEntry, ActionExecutionError, type ActionPayloadMap, type ActionType, type AddExtraRulesCommand, type AddPlayersCommand, type AgeOfGiantsState, type BasicRules, type BotExtensionChoices, type BotStrategy, type BuildersBoard, type BuildingChoice, type BuildingContext, type BuildingSlot, type BuildingTile, type BuildingsRepository, type CalculatePlayerScoreCommand, type CalculatePlayerScoreUseCase, type CalculateScoreCommand, type CanPlaceDominoCommand, type CanSkipOptionalActionCommand, type CaveBoard, type CavemanChoice, type CavemanContext, type CavemanKind, type CavemanRecruitmentOption, type CavemanTile, type CavemenRepository, type ChooseDominoCommand, type ConstructBuildingCommand, type ConstructBuildingUseCase, type CreateGameCommand, type Crown, type DebugLogEntry, type DebugLogLevel, type DebugLogger, type DebugOptions, type DeserializeGameCommand, type DiscardDominoCommand, type DomainError, DomainException, type Domino, type DominoesRepository, type DragonContext, type DynastyGroupBy, type DynastyResult, type EmptyGround, type EmptyTile, type EndGameScoring, type EndGameScoringType, type EngineConfig, ErrorCode, type ErrorCodeType, type ExtensionContext, type ExtraRule, type FinalResult, type FireTokenContext, type FireTokenPool, 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 GetAffordableBuildingsCommand, type GetDynastyResultCommand, type GetExtraRulesCommand, type GetModesCommand, type GetResultCommand, type GetValidActionTargetsCommand, type GetValidBuildingPositionsCommand, type GetValidCavemanPlacementsCommand, type GetValidDominoPicksCommand, type GetValidDragonTargetsCommand, type GetValidFireTokenPositionsCommand, type GetValidGiantPositionsCommand, type GetValidGiantTargetsCommand, type GetValidKnightPositionsCommand, type GetValidPlacementsCommand, type GiantPositionContext, type Ground, type HunterGathererKind, type HunterGathererTile, type ImmediateBonus, type ImmediateBonusType, InvalidStepError, type Kingdom, type Knight, type KnightContext, type Logger, type Lord, MAX_KINGDOM_SIZE, type ModeRepository, type NextAction, type NextStep, NotFoundError, type ObjectValues, type OriginsState, type OriginsSubMode, type PendingFireToken, type PendingGiant, type PickContext, type PlaceContext, type PlaceDominoCommand, type PlaceFireTokenCommand, type PlaceFireTokenUseCase, type PlaceGiantCommand, type PlaceGiantUseCase, type PlaceKnightCommand, type PlaceKnightUseCase, type PlacedBuilding, type PlacedCaveman, type PlacedFireToken, type PlacedGiant, type Player, type PlayerActions, type PlayerInput, type PlayerPayload, type PlayerScore, type Players, type PlayersPayload, type Position, type QueenDominoState, type QuestTile, type QuestTilesRepository, type QuestType, type RecruitCavemanCommand, type RecruitCavemanUseCase, RedoError, type Resource, type ResourceType, type RevealsDomino, type Rotation, type RuleRepository, type Rules, type Score, type ScoreBonus, type ScoreBonusType, type ScoreBreakdown, type ScoreResult, type ScoreTerritory, type SelectedRules, type SendGiantChoice, type SendGiantCommand, type SendGiantContext, type SendGiantUseCase, type SerializeGameCommand, type ShuffleMethod, type SkipOptionalActionCommand, type SkipOptionalActionUseCase, type StartGameCommand, StepExecutionError, type StrategyName, type SupportedLocale, type Tile, type TotemBonus, type TotemState, TranslationKey, type TranslationKeyType, type Translator, UndoError, type UseDragonCommand, type UseDragonUseCase, type UuidMethod, type ValidActionTargetsUseCase, type ValidCavemanPlacements, type ValidGiantTargets, type ValidPlacement, ValidationError, type ValidationIssue, type ValidationSeverity, WARRIOR_POWER, type WarriorTile, type WarriorType, advancedStrategy, appendAction, canRedo, canUndo, cavemanKindToTranslationKey, cavemanKinds, clearHistory, createActionLog, createDomainError, createGameEngine, createGameHistory, createSavePoint, createTranslator, defaultTranslations, defaultTranslator, deserializeGame, englishTranslations, errorCodeToTranslationKey, expertStrategy, extraRuleNameToTranslationKey, frenchTranslations, gameSteps, getActions, getActionsByTurn, getActionsByType, getHistorySize, getStrategy, getStrategyNames, greedyStrategy, groundToTranslationKey, hunterGathererKindToTranslationKey, hunterGathererKinds, isBotTurn, isGameWithNextAction, isGameWithNextStep, isGameWithResults, isHunterGathererTile, isSkippableAction, isWarriorTile, localeTranslations, modeNameToTranslationKey, originsSubModes, playBotTurn, playBotTurns, playerActionToTranslationKey, playerActions, pushState, questTypeToTranslationKey, questTypes, randomStrategy, redo, replayActions, resourceToTranslationKey, resourceTypes, restoreFromSavePoint, scoreBonusTypes, serializeGame, summarizeGameState, supportedLocales, totemToTranslationKey, translateErrorCode, undo, validateGameState, warriorTypeToTranslationKey, warriorTypes, wrapWithActionLog, wrapWithDebug, wrapWithEvents };