/**
 * word_connect.aigameplay — reducer 接口模板
 *
 * Agent 生成实际 reducer 时，必须导出以下函数。
 * 此文件是接口约束模板，不是可执行代码。
 *
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
 *
 * dispatch() 是一体化接口，内部完成路径验证 + 单词判定后只返回最终状态，
 * 中间过程（实时路径连线、逐格高亮、有效/无效动画）全部丢失。
 *
 * 渲染层需要实时绘制连线、逐格高亮、播放验证动画，
 * 因此必须使用下方的「分步函数」逐步驱动，每步之间同步渲染状态。
 *
 * dispatch() 的用途：无头测试、AI 模拟、跳过动画等场景。
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 */

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

export type WordConnectConfig = {
  /** 网格行数 */
  rows: number;
  /** 网格列数 */
  cols: number;
  /** 目标单词列表（全大写） */
  wordList: string[];
  /** 初始网格字母（二维数组，行×列） */
  initialLetters: string[][];
  /** 是否允许斜方向连线 */
  allowDiagonal: boolean;
  /** 单词最小长度 */
  minWordLength: number;
  /** 是否启用计时模式 */
  timedMode: boolean;
  /** 计时时长（ms，仅 timedMode=true 时有效） */
  timeLimitMs?: number;
  /** 找到单词后是否消除格子并补充 */
  eliminateFoundLetters: boolean;
};

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

export type WordConnectAction =
  | { type: 'startTrace'; row: number; col: number }
  | { type: 'extendTrace'; row: number; col: number }
  | { type: 'completeTrace' }
  | { type: 'tick'; deltaMs: number }
  | { type: 'reset' };

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

export type GridCell = {
  letter: string;
  found: boolean;
  foundWordId: string | null;
};

export type CellPos = { row: number; col: number };

export type FoundWord = {
  word: string;
  path: CellPos[];
  score: number;
};

export type WordConnectState = {
  grid: GridCell[][];
  wordList: string[];
  foundWords: FoundWord[];
  currentPath: {
    cells: CellPos[];
    letters: string;
  };
  score: number;
  timer: number;
  gameOver: boolean;
  win: boolean;
  lastCompleteResult: CompleteTraceResult | null;
};

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

export type ExtendTraceResult = {
  path: CellPos[];
  letters: string;
  valid: boolean;
  reason: 'ok' | 'not_adjacent' | 'already_in_path';
};

export type CompleteTraceResult = {
  word: string;
  isValid: boolean;
  reason: 'found' | 'too_short' | 'not_in_list' | 'already_found';
  score: number;
  path: CellPos[];
};

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

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

/**
 * init：根据配置初始化游戏状态（构建网格、设置词库和计时器）
 */
export declare function init(config: WordConnectConfig): WordConnectState;

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

/**
 * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
 *
 * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
 */
export declare function dispatch(state: WordConnectState, action: WordConnectAction): WordConnectState;

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

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

/**
 * startTrace：玩家按下某格，开始连线路径
 * 场景层高亮起始格子，开始绘制连线 Graphics
 */
export declare function startTrace(
  state: WordConnectState,
  row: number,
  col: number,
): { path: CellPos[]; letters: string };

/**
 * extendTrace：玩家滑动到相邻格子，延伸路径
 * 场景层实时绘制连线到新格子，高亮选中格
 *
 * - valid=false 且 reason='not_adjacent'：目标格不相邻，忽略
 * - valid=false 且 reason='already_in_path'：格子已在路径中，忽略
 * - valid=true：格子加入路径，更新 letters
 */
export declare function extendTrace(
  state: WordConnectState,
  row: number,
  col: number,
): ExtendTraceResult;

/**
 * completeTrace：玩家抬起手指，验证并提交当前路径组成的单词
 * 场景层根据 isValid 播放有效（绿色消失）或无效（红色闪烁清除）动画
 */
export declare function completeTrace(
  state: WordConnectState,
): CompleteTraceResult;

/**
 * validateWord：检查字母串是否为有效单词（在词库中 + 未找到过）
 * 纯逻辑函数，渲染层一般不直接调用（由 completeTrace 内部使用）
 */
export declare function validateWord(
  letters: string,
  wordList: string[],
  foundWords: FoundWord[],
): { valid: boolean; reason: CompleteTraceResult['reason'] };

/**
 * markWordFound：将有效单词记录到 foundWords，更新 grid 格子的 found 状态
 * 场景层根据 path 对格子精灵播放标记动画（颜色变化、锁定图标等）
 */
export declare function markWordFound(
  state: WordConnectState,
  word: string,
  path: CellPos[],
): { foundWords: FoundWord[]; score: number };

/**
 * checkWin：检查是否找到所有目标单词
 */
export declare function checkWin(
  state: WordConnectState,
): { win: boolean };