/**
 * memory_match.aigameplay — reducer 接口模板
 *
 * Agent 生成实际 reducer 时，必须导出以下函数。
 * 此文件是接口约束模板，不是可执行代码。
 *
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
 *
 * dispatch() 是一体化接口，内部执行完整的翻牌+配对+翻回逻辑后只返回最终状态，
 * 中间过程（翻牌动画、等待延迟、配对高亮、翻回动画）全部丢失。
 *
 * 渲染层需要按帧驱动动画链，因此必须使用下方的「分步函数」。
 *
 * dispatch() 的用途：无头测试、AI 模拟、跳过动画场景。
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 */

// ─── 配置类型 ─────────────────────────────────────────────────────────────────

export type MemoryMatchConfig = {
  /** 棋盘列数，默认 4 */
  cols: number;
  /** 棋盘行数，默认 4 */
  rows: number;
  /** 牌对数量，必须等于 (cols × rows) / 2 */
  pairCount: number;
  /** 同时最多可翻开的牌数，默认 2 */
  maxFaceUpCount: number;
  /** 不匹配后自动翻回的延迟（毫秒），默认 1000 */
  flipBackDelayMs: number;
  /** 预设牌面布局（可选，用于测试确定性布局；不提供时随机shuffle） */
  initialLayout?: number[];
};

// ─── 动作类型 ─────────────────────────────────────────────────────────────────

export type MemoryMatchAction =
  | { type: 'flip_card'; cardId: number }
  | { type: 'flip_back_mismatched' }
  | { type: 'reset' };

// ─── 状态类型 ─────────────────────────────────────────────────────────────────

export type CardState = 'face_down' | 'face_up' | 'matched';

export type Card = {
  /** 卡牌唯一 ID（0 ~ totalCards-1） */
  id: number;
  /** 配对组 ID（相同 pairId 的两张牌为一对） */
  pairId: number;
  /** 当前状态 */
  state: CardState;
};

export type MemoryMatchState = {
  /** 所有卡牌 */
  cards: Card[];
  /** 当前正面朝上（face_up）的卡牌 ID 列表（最多 maxFaceUpCount 张）*/
  faceUpCards: number[];
  /** 已成功配对的对数 */
  matchedPairs: number;
  /** 总对数 */
  totalPairs: number;
  /** 玩家翻牌总次数 */
  movesCount: number;
  /** 游戏是否结束 */
  gameOver: boolean;
  /** 是否胜利 */
  win: boolean;
  /** 是否有未处理的不匹配翻回（等待 flipBackMismatched 调用） */
  pendingFlipBack: boolean;
};

// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────

/** checkMatch 返回值 */
export type MatchCheckResult = {
  /** 两张 face_up 的牌 pairId 是否相同 */
  isMatch: boolean;
  /** 参与检测的卡牌 ID（应为2张） */
  cardIds: number[];
  /** 是否需要延迟翻回（isMatch=false 时为 true） */
  shouldFlipBack: boolean;
};

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// 必须导出的函数
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

// ─── 初始化 ──────────────────────────────────────────────────────────────────

/**
 * init：根据配置初始化游戏状态，随机（或按指定布局）排列卡牌
 */
export declare function init(config: MemoryMatchConfig): MemoryMatchState;

// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────

/**
 * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
 * - flip_card：翻开指定卡牌，若已有2张 face_up 则拒绝
 * - flip_back_mismatched：将不匹配的2张 face_up 牌翻回 face_down
 * - reset：重置到初始状态
 *
 * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
 */
export declare function dispatch(state: MemoryMatchState, action: MemoryMatchAction): MemoryMatchState;

/**
 * getState：返回当前状态快照
 */
export declare function getState(state: MemoryMatchState): MemoryMatchState;

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

/**
 * flipCard：翻开指定卡牌（face_down → face_up），更新 movesCount 和 faceUpCards。
 *
 * 场景层在玩家点击卡牌后，翻牌动画开始前调用（或动画完成后调用均可）。
 * 若 pendingFlipBack=true（有未处理的不匹配），返回状态不变（拒绝翻牌）。
 *
 * @param state   当前游戏状态（不可变）
 * @param cardId  目标卡牌 ID
 * @returns       更新后的游戏状态
 */
export declare function flipCard(state: MemoryMatchState, cardId: number): MemoryMatchState;

/**
 * checkMatch：检测当前 faceUpCards 中的两张牌是否配对。
 *
 * 场景层在第二张牌翻开动画完成后立即调用。
 * - isMatch=true：自动将两张牌更新为 matched，调用方播放配对成功动画
 * - isMatch=false：设置 pendingFlipBack=true，调用方在延迟后调用 flipBackMismatched
 *
 * @param state   当前游戏状态（faceUpCards 必须恰好有2张 face_up 牌）
 * @returns       配对检测结果
 */
export declare function checkMatch(state: MemoryMatchState): MatchCheckResult;

/**
 * flipBackMismatched：将 faceUpCards 中2张不匹配的牌翻回 face_down。
 *
 * 场景层在检测到 shouldFlipBack=true 后，等待 flipBackDelayMs 毫秒，
 * 然后调用此函数同步状态，并播放翻回动画。
 *
 * @param state   当前游戏状态（pendingFlipBack 必须为 true）
 * @returns       更新后的游戏状态（两张牌回到 face_down，faceUpCards 清空）
 */
export declare function flipBackMismatched(state: MemoryMatchState): MemoryMatchState;

/**
 * checkWin：检测是否所有牌对均已配对。
 *
 * 场景层在每次配对成功动画播放完毕后调用，判断是否触发胜利演出。
 *
 * @param state   当前游戏状态
 * @returns       true 表示所有牌均已配对（win=true）
 */
export declare function checkWin(state: MemoryMatchState): boolean;