/**
 * draw_line_puzzle.aigameplay — reducer 接口模板
 *
 * Agent 生成实际 reducer 时，必须导出以下函数。
 * 此文件是接口约束模板，不是可执行代码。
 *
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
 *
 * dispatch() 是一体化接口，内部完成整个画线 → 验证 → 角色移动流程，
 * 中间过程（实时墨水消耗、线段碰撞点、角色逐帧位置）全部丢失。
 *
 * 渲染层需要实时绘制线段、显示墨水条、逐帧更新角色位置，
 * 因此必须使用下方的「分步函数」逐步驱动，每步之间同步渲染状态。
 *
 * dispatch() 的用途：无头测试、AI 模拟、跳过动画等场景。
 * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 */

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

export type Vec2 = { x: number; y: number };

export type Rect = { x: number; y: number; width: number; height: number };

export type DrawLinePuzzleConfig = {
  /** 场景宽度（px） */
  sceneWidth: number;
  /** 场景高度（px） */
  sceneHeight: number;
  /** 最大墨水总长度（px） */
  maxInkLength: number;
  /** 角色移动速度（px/s） */
  characterSpeed: number;
  /** 折点最小间距（小于此值则合并，px） */
  lineSegmentSnap: number;
  /** 是否启用时间限制 */
  timeLimitEnabled: boolean;
  /** 时间限制（ms，仅 timeLimitEnabled=true 时有效） */
  timeLimitMs?: number;
  /** 起点吸附半径（角色在此范围内则路径起点有效，px） */
  snapRadius: number;
  /** 场景障碍物列表 */
  obstacles: Rect[];
  /** 起始点 */
  startPoint: Vec2;
  /** 目标点 */
  endPoint: Vec2;
  /** 目标到达判定半径（px） */
  targetRadius: number;
};

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

export type DrawLinePuzzleAction =
  | { type: 'startLine'; point: Vec2 }
  | { type: 'extendLine'; point: Vec2 }
  | { type: 'finishLine' }
  | { type: 'tick'; deltaMs: number }
  | { type: 'reset' };

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

export type CharacterState = 'idle' | 'moving' | 'arrived' | 'blocked';

export type DrawnLine = {
  id: string;
  points: Vec2[];
  length: number;
};

export type DrawLinePuzzleState = {
  lines: DrawnLine[];
  activeLine: DrawnLine | null;
  character: {
    position: Vec2;
    state: CharacterState;
    pathProgress: number;
    currentPathPoints: Vec2[];
  };
  target: {
    position: Vec2;
    radius: number;
  };
  inkUsed: number;
  timeLeft: number;
  gameOver: boolean;
  win: boolean;
};

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

export type ExtendLineResult = {
  newSegment: { from: Vec2; to: Vec2 } | null;
  inkUsed: number;
  inkExceeded: boolean;
  blocked: boolean;
};

export type ValidatePathResult = {
  valid: boolean;
  reason: 'ok' | 'no_path' | 'obstacle_blocked' | 'no_start_connection' | 'no_end_connection';
};

export type CharacterMoveResult = {
  position: Vec2;
  progress: number;
  arrived: boolean;
};

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

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

/**
 * init：根据配置初始化游戏状态
 */
export declare function init(config: DrawLinePuzzleConfig): DrawLinePuzzleState;

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

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

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

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

/**
 * startLine：开始绘制新线段
 * 场景层创建新的 Phaser.Graphics 对象，移动到起始点
 */
export declare function startLine(
  state: DrawLinePuzzleState,
  point: Vec2,
): { lineId: string; inkUsed: number };

/**
 * extendLine：延伸当前线段到新点
 * 场景层在 Graphics 上实时追加 lineTo，更新墨水进度条 HUD
 *
 * - blocked=true：新线段与障碍物相交，拒绝追加
 * - inkExceeded=true：墨水不足，拒绝追加
 * - newSegment=null：小于 lineSegmentSnap，忽略（合并到上一点）
 */
export declare function extendLine(
  state: DrawLinePuzzleState,
  point: Vec2,
): ExtendLineResult;

/**
 * finishLine：封存当前绘制的线段
 * 场景层调用后，Graphics 对象变为静态，不再追加
 */
export declare function finishLine(
  state: DrawLinePuzzleState,
): { lines: DrawnLine[]; totalInkUsed: number };

/**
 * validatePath：检查所有已绘制线段是否能构成从 startPoint 到 endPoint 的有效路径
 * 场景层根据 valid 高亮路径（绿色=有效，红色=无效）
 */
export declare function validatePath(
  state: DrawLinePuzzleState,
): ValidatePathResult;

/**
 * executeCharacterMove：逐帧推进角色沿路径移动
 * 场景层每帧调用，根据返回 position 更新角色精灵位置
 *
 * - arrived=true：角色到达目标，场景层调用 checkWin()
 */
export declare function executeCharacterMove(
  state: DrawLinePuzzleState,
  deltaMs: number,
): CharacterMoveResult;

/**
 * checkWin：检查是否胜利（角色是否已到达目标）
 */
export declare function checkWin(
  state: DrawLinePuzzleState,
): { win: boolean };