@esengine/pathfinding 13.1.0 → 13.3.0

package/dist/chunk-NIKT3PQC.js

@@ -0,0 +1,3811 @@
+import {
+  EMPTY_PROGRESS,
+  PathfindingState
+} from "./chunk-YKA3PWU3.js";
+import {
+  createCollisionResolver,
+  createKDTree,
+  createORCASolver
+} from "./chunk-3VEX32JO.js";
+import {
+  __name,
+  __publicField
+} from "./chunk-T626JPC7.js";
+
+// src/core/IPathfinding.ts
+function createPoint(x, y) {
+  return {
+    x,
+    y
+  };
+}
+__name(createPoint, "createPoint");
+var EMPTY_PATH_RESULT = {
+  found: false,
+  path: [],
+  cost: 0,
+  nodesSearched: 0
+};
+function manhattanDistance(a, b) {
+  return Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
+}
+__name(manhattanDistance, "manhattanDistance");
+function euclideanDistance(a, b) {
+  const dx = a.x - b.x;
+  const dy = a.y - b.y;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+__name(euclideanDistance, "euclideanDistance");
+function chebyshevDistance(a, b) {
+  return Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y));
+}
+__name(chebyshevDistance, "chebyshevDistance");
+function octileDistance(a, b) {
+  const dx = Math.abs(a.x - b.x);
+  const dy = Math.abs(a.y - b.y);
+  const D = 1;
+  const D2 = Math.SQRT2;
+  return D * (dx + dy) + (D2 - 2 * D) * Math.min(dx, dy);
+}
+__name(octileDistance, "octileDistance");
+var DEFAULT_PATHFINDING_OPTIONS = {
+  maxNodes: 1e4,
+  heuristicWeight: 1,
+  allowDiagonal: true,
+  avoidCorners: true,
+  agentRadius: 0
+};
+
+// src/core/BinaryHeap.ts
+var _BinaryHeap = class _BinaryHeap {
+  /**
+   * @zh 创建二叉堆
+   * @en Create binary heap
+   *
+   * @param compare - @zh 比较函数，返回负数表示 a < b @en Compare function, returns negative if a < b
+   */
+  constructor(compare) {
+    __publicField(this, "heap", []);
+    __publicField(this, "compare");
+    this.compare = compare;
+  }
+  /**
+   * @zh 堆大小
+   * @en Heap size
+   */
+  get size() {
+    return this.heap.length;
+  }
+  /**
+   * @zh 是否为空
+   * @en Is empty
+   */
+  get isEmpty() {
+    return this.heap.length === 0;
+  }
+  /**
+   * @zh 插入元素
+   * @en Push element
+   */
+  push(item) {
+    this.heap.push(item);
+    this.bubbleUp(this.heap.length - 1);
+  }
+  /**
+   * @zh 弹出最小元素
+   * @en Pop minimum element
+   */
+  pop() {
+    if (this.heap.length === 0) {
+      return void 0;
+    }
+    const result = this.heap[0];
+    const last = this.heap.pop();
+    if (this.heap.length > 0) {
+      this.heap[0] = last;
+      this.sinkDown(0);
+    }
+    return result;
+  }
+  /**
+   * @zh 查看最小元素（不移除）
+   * @en Peek minimum element (without removing)
+   */
+  peek() {
+    return this.heap[0];
+  }
+  /**
+   * @zh 更新元素（重新排序）
+   * @en Update element (re-sort)
+   */
+  update(item) {
+    const index = this.heap.indexOf(item);
+    if (index !== -1) {
+      this.bubbleUp(index);
+      this.sinkDown(index);
+    }
+  }
+  /**
+   * @zh 检查是否包含元素
+   * @en Check if contains element
+   */
+  contains(item) {
+    return this.heap.indexOf(item) !== -1;
+  }
+  /**
+   * @zh 清空堆
+   * @en Clear heap
+   */
+  clear() {
+    this.heap.length = 0;
+  }
+  /**
+   * @zh 上浮操作
+   * @en Bubble up operation
+   */
+  bubbleUp(index) {
+    const item = this.heap[index];
+    while (index > 0) {
+      const parentIndex = Math.floor((index - 1) / 2);
+      const parent = this.heap[parentIndex];
+      if (this.compare(item, parent) >= 0) {
+        break;
+      }
+      this.heap[index] = parent;
+      index = parentIndex;
+    }
+    this.heap[index] = item;
+  }
+  /**
+   * @zh 下沉操作
+   * @en Sink down operation
+   */
+  sinkDown(index) {
+    const length = this.heap.length;
+    const item = this.heap[index];
+    while (true) {
+      const leftIndex = 2 * index + 1;
+      const rightIndex = 2 * index + 2;
+      let smallest = index;
+      if (leftIndex < length && this.compare(this.heap[leftIndex], this.heap[smallest]) < 0) {
+        smallest = leftIndex;
+      }
+      if (rightIndex < length && this.compare(this.heap[rightIndex], this.heap[smallest]) < 0) {
+        smallest = rightIndex;
+      }
+      if (smallest === index) {
+        break;
+      }
+      this.heap[index] = this.heap[smallest];
+      this.heap[smallest] = item;
+      index = smallest;
+    }
+  }
+};
+__name(_BinaryHeap, "BinaryHeap");
+var BinaryHeap = _BinaryHeap;
+
+// src/core/IndexedBinaryHeap.ts
+var _IndexedBinaryHeap = class _IndexedBinaryHeap {
+  /**
+   * @zh 创建带索引追踪的二叉堆
+   * @en Create indexed binary heap
+   *
+   * @param compare - @zh 比较函数，返回负数表示 a < b @en Compare function, returns negative if a < b
+   */
+  constructor(compare) {
+    __publicField(this, "heap", []);
+    __publicField(this, "compare");
+    this.compare = compare;
+  }
+  /**
+   * @zh 堆大小
+   * @en Heap size
+   */
+  get size() {
+    return this.heap.length;
+  }
+  /**
+   * @zh 是否为空
+   * @en Is empty
+   */
+  get isEmpty() {
+    return this.heap.length === 0;
+  }
+  /**
+   * @zh 插入元素
+   * @en Push element
+   */
+  push(item) {
+    item.heapIndex = this.heap.length;
+    this.heap.push(item);
+    this.bubbleUp(this.heap.length - 1);
+  }
+  /**
+   * @zh 弹出最小元素
+   * @en Pop minimum element
+   */
+  pop() {
+    if (this.heap.length === 0) {
+      return void 0;
+    }
+    const result = this.heap[0];
+    result.heapIndex = -1;
+    const last = this.heap.pop();
+    if (this.heap.length > 0) {
+      last.heapIndex = 0;
+      this.heap[0] = last;
+      this.sinkDown(0);
+    }
+    return result;
+  }
+  /**
+   * @zh 查看最小元素（不移除）
+   * @en Peek minimum element (without removing)
+   */
+  peek() {
+    return this.heap[0];
+  }
+  /**
+   * @zh 更新元素
+   * @en Update element
+   */
+  update(item) {
+    const index = item.heapIndex;
+    if (index >= 0 && index < this.heap.length && this.heap[index] === item) {
+      this.bubbleUp(index);
+      this.sinkDown(item.heapIndex);
+    }
+  }
+  /**
+   * @zh 检查是否包含元素
+   * @en Check if contains element
+   */
+  contains(item) {
+    const index = item.heapIndex;
+    return index >= 0 && index < this.heap.length && this.heap[index] === item;
+  }
+  /**
+   * @zh 从堆中移除指定元素
+   * @en Remove specific element from heap
+   */
+  remove(item) {
+    const index = item.heapIndex;
+    if (index < 0 || index >= this.heap.length || this.heap[index] !== item) {
+      return false;
+    }
+    item.heapIndex = -1;
+    if (index === this.heap.length - 1) {
+      this.heap.pop();
+      return true;
+    }
+    const last = this.heap.pop();
+    last.heapIndex = index;
+    this.heap[index] = last;
+    this.bubbleUp(index);
+    this.sinkDown(last.heapIndex);
+    return true;
+  }
+  /**
+   * @zh 清空堆
+   * @en Clear heap
+   */
+  clear() {
+    for (const item of this.heap) {
+      item.heapIndex = -1;
+    }
+    this.heap.length = 0;
+  }
+  /**
+   * @zh 上浮操作
+   * @en Bubble up operation
+   */
+  bubbleUp(index) {
+    const item = this.heap[index];
+    while (index > 0) {
+      const parentIndex = index - 1 >> 1;
+      const parent = this.heap[parentIndex];
+      if (this.compare(item, parent) >= 0) {
+        break;
+      }
+      parent.heapIndex = index;
+      this.heap[index] = parent;
+      index = parentIndex;
+    }
+    item.heapIndex = index;
+    this.heap[index] = item;
+  }
+  /**
+   * @zh 下沉操作
+   * @en Sink down operation
+   */
+  sinkDown(index) {
+    const length = this.heap.length;
+    const item = this.heap[index];
+    const halfLength = length >> 1;
+    while (index < halfLength) {
+      const leftIndex = (index << 1) + 1;
+      const rightIndex = leftIndex + 1;
+      let smallest = index;
+      let smallestItem = item;
+      const left = this.heap[leftIndex];
+      if (this.compare(left, smallestItem) < 0) {
+        smallest = leftIndex;
+        smallestItem = left;
+      }
+      if (rightIndex < length) {
+        const right = this.heap[rightIndex];
+        if (this.compare(right, smallestItem) < 0) {
+          smallest = rightIndex;
+          smallestItem = right;
+        }
+      }
+      if (smallest === index) {
+        break;
+      }
+      smallestItem.heapIndex = index;
+      this.heap[index] = smallestItem;
+      index = smallest;
+    }
+    item.heapIndex = index;
+    this.heap[index] = item;
+  }
+};
+__name(_IndexedBinaryHeap, "IndexedBinaryHeap");
+var IndexedBinaryHeap = _IndexedBinaryHeap;
+
+// src/core/AStarPathfinder.ts
+var _AStarPathfinder = class _AStarPathfinder {
+  constructor(map) {
+    __publicField(this, "map");
+    __publicField(this, "nodeCache", /* @__PURE__ */ new Map());
+    __publicField(this, "openList");
+    this.map = map;
+    this.openList = new IndexedBinaryHeap((a, b) => a.f - b.f);
+  }
+  /**
+   * @zh 查找路径
+   * @en Find path
+   */
+  findPath(startX, startY, endX, endY, options) {
+    const opts = {
+      ...DEFAULT_PATHFINDING_OPTIONS,
+      ...options
+    };
+    this.clear();
+    const startNode = this.map.getNodeAt(startX, startY);
+    const endNode = this.map.getNodeAt(endX, endY);
+    if (!startNode || !endNode) {
+      return EMPTY_PATH_RESULT;
+    }
+    if (!startNode.walkable || !endNode.walkable) {
+      return EMPTY_PATH_RESULT;
+    }
+    if (startNode.id === endNode.id) {
+      return {
+        found: true,
+        path: [
+          startNode.position
+        ],
+        cost: 0,
+        nodesSearched: 1
+      };
+    }
+    const start = this.getOrCreateAStarNode(startNode);
+    start.g = 0;
+    start.h = this.map.heuristic(startNode.position, endNode.position) * opts.heuristicWeight;
+    start.f = start.h;
+    start.opened = true;
+    this.openList.push(start);
+    let nodesSearched = 0;
+    const endPosition = endNode.position;
+    while (!this.openList.isEmpty && nodesSearched < opts.maxNodes) {
+      const current = this.openList.pop();
+      current.closed = true;
+      nodesSearched++;
+      if (current.node.id === endNode.id) {
+        return this.buildPath(current, nodesSearched);
+      }
+      const neighbors = this.map.getNeighbors(current.node);
+      for (const neighborNode of neighbors) {
+        if (!neighborNode.walkable) {
+          continue;
+        }
+        const neighbor = this.getOrCreateAStarNode(neighborNode);
+        if (neighbor.closed) {
+          continue;
+        }
+        const movementCost = this.map.getMovementCost(current.node, neighborNode);
+        const tentativeG = current.g + movementCost;
+        if (!neighbor.opened) {
+          neighbor.g = tentativeG;
+          neighbor.h = this.map.heuristic(neighborNode.position, endPosition) * opts.heuristicWeight;
+          neighbor.f = neighbor.g + neighbor.h;
+          neighbor.parent = current;
+          neighbor.opened = true;
+          this.openList.push(neighbor);
+        } else if (tentativeG < neighbor.g) {
+          neighbor.g = tentativeG;
+          neighbor.f = neighbor.g + neighbor.h;
+          neighbor.parent = current;
+          this.openList.update(neighbor);
+        }
+      }
+    }
+    return {
+      found: false,
+      path: [],
+      cost: 0,
+      nodesSearched
+    };
+  }
+  /**
+   * @zh 清理状态
+   * @en Clear state
+   */
+  clear() {
+    this.nodeCache.clear();
+    this.openList.clear();
+  }
+  /**
+   * @zh 获取或创建 A* 节点
+   * @en Get or create A* node
+   */
+  getOrCreateAStarNode(node) {
+    let astarNode = this.nodeCache.get(node.id);
+    if (!astarNode) {
+      astarNode = {
+        node,
+        g: Infinity,
+        h: 0,
+        f: Infinity,
+        parent: null,
+        closed: false,
+        opened: false,
+        heapIndex: -1
+      };
+      this.nodeCache.set(node.id, astarNode);
+    }
+    return astarNode;
+  }
+  /**
+   * @zh 构建路径结果
+   * @en Build path result
+   */
+  buildPath(endNode, nodesSearched) {
+    const path = [];
+    let current = endNode;
+    while (current) {
+      path.push(current.node.position);
+      current = current.parent;
+    }
+    path.reverse();
+    return {
+      found: true,
+      path,
+      cost: endNode.g,
+      nodesSearched
+    };
+  }
+};
+__name(_AStarPathfinder, "AStarPathfinder");
+var AStarPathfinder = _AStarPathfinder;
+function createAStarPathfinder(map) {
+  return new AStarPathfinder(map);
+}
+__name(createAStarPathfinder, "createAStarPathfinder");
+
+// src/core/PathCache.ts
+var DEFAULT_PATH_CACHE_CONFIG = {
+  maxEntries: 1e3,
+  ttlMs: 5e3,
+  enableApproximateMatch: false,
+  approximateRange: 2
+};
+var _PathCache = class _PathCache {
+  constructor(config = {}) {
+    __publicField(this, "config");
+    __publicField(this, "cache");
+    __publicField(this, "accessOrder");
+    this.config = {
+      ...DEFAULT_PATH_CACHE_CONFIG,
+      ...config
+    };
+    this.cache = /* @__PURE__ */ new Map();
+    this.accessOrder = [];
+  }
+  /**
+   * @zh 获取缓存的路径
+   * @en Get cached path
+   *
+   * @param startX - @zh 起点 X 坐标 @en Start X coordinate
+   * @param startY - @zh 起点 Y 坐标 @en Start Y coordinate
+   * @param endX - @zh 终点 X 坐标 @en End X coordinate
+   * @param endY - @zh 终点 Y 坐标 @en End Y coordinate
+   * @param mapVersion - @zh 地图版本号 @en Map version number
+   * @returns @zh 缓存的路径结果或 null @en Cached path result or null
+   */
+  get(startX, startY, endX, endY, mapVersion) {
+    const key = this.generateKey(startX, startY, endX, endY);
+    const entry = this.cache.get(key);
+    if (!entry) {
+      if (this.config.enableApproximateMatch) {
+        return this.getApproximate(startX, startY, endX, endY, mapVersion);
+      }
+      return null;
+    }
+    if (!this.isValid(entry, mapVersion)) {
+      this.cache.delete(key);
+      this.removeFromAccessOrder(key);
+      return null;
+    }
+    this.updateAccessOrder(key);
+    return entry.result;
+  }
+  /**
+   * @zh 设置缓存路径
+   * @en Set cached path
+   *
+   * @param startX - @zh 起点 X 坐标 @en Start X coordinate
+   * @param startY - @zh 起点 Y 坐标 @en Start Y coordinate
+   * @param endX - @zh 终点 X 坐标 @en End X coordinate
+   * @param endY - @zh 终点 Y 坐标 @en End Y coordinate
+   * @param result - @zh 路径结果 @en Path result
+   * @param mapVersion - @zh 地图版本号 @en Map version number
+   */
+  set(startX, startY, endX, endY, result, mapVersion) {
+    if (this.cache.size >= this.config.maxEntries) {
+      this.evictLRU();
+    }
+    const key = this.generateKey(startX, startY, endX, endY);
+    const entry = {
+      result,
+      timestamp: Date.now(),
+      mapVersion
+    };
+    this.cache.set(key, entry);
+    this.updateAccessOrder(key);
+  }
+  /**
+   * @zh 使所有缓存失效
+   * @en Invalidate all cache
+   */
+  invalidateAll() {
+    this.cache.clear();
+    this.accessOrder.length = 0;
+  }
+  /**
+   * @zh 使指定区域的缓存失效
+   * @en Invalidate cache for specified region
+   *
+   * @param minX - @zh 最小 X 坐标 @en Minimum X coordinate
+   * @param minY - @zh 最小 Y 坐标 @en Minimum Y coordinate
+   * @param maxX - @zh 最大 X 坐标 @en Maximum X coordinate
+   * @param maxY - @zh 最大 Y 坐标 @en Maximum Y coordinate
+   */
+  invalidateRegion(minX, minY, maxX, maxY) {
+    const keysToDelete = [];
+    for (const [key, entry] of this.cache) {
+      const path = entry.result.path;
+      if (path.length === 0) continue;
+      for (const point of path) {
+        if (point.x >= minX && point.x <= maxX && point.y >= minY && point.y <= maxY) {
+          keysToDelete.push(key);
+          break;
+        }
+      }
+    }
+    for (const key of keysToDelete) {
+      this.cache.delete(key);
+      this.removeFromAccessOrder(key);
+    }
+  }
+  /**
+   * @zh 获取缓存统计信息
+   * @en Get cache statistics
+   */
+  getStats() {
+    return {
+      size: this.cache.size,
+      maxSize: this.config.maxEntries
+    };
+  }
+  /**
+   * @zh 清理过期条目
+   * @en Clean up expired entries
+   */
+  cleanup() {
+    if (this.config.ttlMs === 0) return;
+    const now = Date.now();
+    const keysToDelete = [];
+    for (const [key, entry] of this.cache) {
+      if (now - entry.timestamp > this.config.ttlMs) {
+        keysToDelete.push(key);
+      }
+    }
+    for (const key of keysToDelete) {
+      this.cache.delete(key);
+      this.removeFromAccessOrder(key);
+    }
+  }
+  // =========================================================================
+  // 私有方法 | Private Methods
+  // =========================================================================
+  generateKey(startX, startY, endX, endY) {
+    return `${startX},${startY}->${endX},${endY}`;
+  }
+  isValid(entry, mapVersion) {
+    if (entry.mapVersion !== mapVersion) {
+      return false;
+    }
+    if (this.config.ttlMs > 0) {
+      const age = Date.now() - entry.timestamp;
+      if (age > this.config.ttlMs) {
+        return false;
+      }
+    }
+    return true;
+  }
+  getApproximate(startX, startY, endX, endY, mapVersion) {
+    const range = this.config.approximateRange;
+    for (let sx = startX - range; sx <= startX + range; sx++) {
+      for (let sy = startY - range; sy <= startY + range; sy++) {
+        for (let ex = endX - range; ex <= endX + range; ex++) {
+          for (let ey = endY - range; ey <= endY + range; ey++) {
+            const key = this.generateKey(sx, sy, ex, ey);
+            const entry = this.cache.get(key);
+            if (entry && this.isValid(entry, mapVersion)) {
+              this.updateAccessOrder(key);
+              return this.adjustPathForApproximate(entry.result, startX, startY, endX, endY);
+            }
+          }
+        }
+      }
+    }
+    return null;
+  }
+  adjustPathForApproximate(result, newStartX, newStartY, newEndX, newEndY) {
+    if (result.path.length === 0) {
+      return result;
+    }
+    const newPath = [];
+    const oldStart = result.path[0];
+    const oldEnd = result.path[result.path.length - 1];
+    if (newStartX !== oldStart.x || newStartY !== oldStart.y) {
+      newPath.push({
+        x: newStartX,
+        y: newStartY
+      });
+    }
+    newPath.push(...result.path);
+    if (newEndX !== oldEnd.x || newEndY !== oldEnd.y) {
+      newPath.push({
+        x: newEndX,
+        y: newEndY
+      });
+    }
+    return {
+      ...result,
+      path: newPath
+    };
+  }
+  updateAccessOrder(key) {
+    this.removeFromAccessOrder(key);
+    this.accessOrder.push(key);
+  }
+  removeFromAccessOrder(key) {
+    const index = this.accessOrder.indexOf(key);
+    if (index !== -1) {
+      this.accessOrder.splice(index, 1);
+    }
+  }
+  evictLRU() {
+    const lruKey = this.accessOrder.shift();
+    if (lruKey) {
+      this.cache.delete(lruKey);
+    }
+  }
+};
+__name(_PathCache, "PathCache");
+var PathCache = _PathCache;
+function createPathCache(config) {
+  return new PathCache(config);
+}
+__name(createPathCache, "createPathCache");
+
+// src/core/IncrementalAStarPathfinder.ts
+var _IncrementalAStarPathfinder = class _IncrementalAStarPathfinder {
+  /**
+   * @zh 创建增量 A* 寻路器
+   * @en Create incremental A* pathfinder
+   *
+   * @param map - @zh 寻路地图实例 @en Pathfinding map instance
+   * @param config - @zh 配置选项 @en Configuration options
+   */
+  constructor(map, config) {
+    __publicField(this, "map");
+    __publicField(this, "sessions", /* @__PURE__ */ new Map());
+    __publicField(this, "nextRequestId", 0);
+    __publicField(this, "affectedRegions", []);
+    __publicField(this, "maxRegionAge", 5e3);
+    __publicField(this, "cache");
+    __publicField(this, "enableCache");
+    __publicField(this, "mapVersion", 0);
+    __publicField(this, "cacheHits", 0);
+    __publicField(this, "cacheMisses", 0);
+    this.map = map;
+    this.enableCache = config?.enableCache ?? false;
+    this.cache = this.enableCache ? new PathCache(config?.cacheConfig) : null;
+  }
+  /**
+   * @zh 请求寻路（非阻塞）
+   * @en Request pathfinding (non-blocking)
+   */
+  requestPath(startX, startY, endX, endY, options) {
+    const id = this.nextRequestId++;
+    const priority = options?.priority ?? 50;
+    const opts = {
+      ...DEFAULT_PATHFINDING_OPTIONS,
+      ...options
+    };
+    const request = {
+      id,
+      startX,
+      startY,
+      endX,
+      endY,
+      options: opts,
+      priority,
+      createdAt: Date.now()
+    };
+    if (this.cache) {
+      const cached = this.cache.get(startX, startY, endX, endY, this.mapVersion);
+      if (cached) {
+        this.cacheHits++;
+        const session2 = {
+          request,
+          state: cached.found ? PathfindingState.Completed : PathfindingState.Failed,
+          options: opts,
+          openList: new IndexedBinaryHeap((a, b) => a.f - b.f),
+          nodeCache: /* @__PURE__ */ new Map(),
+          startNode: this.map.getNodeAt(startX, startY),
+          endNode: this.map.getNodeAt(endX, endY),
+          endPosition: {
+            x: endX,
+            y: endY
+          },
+          nodesSearched: cached.nodesSearched,
+          framesUsed: 0,
+          initialDistance: 0,
+          result: {
+            requestId: id,
+            found: cached.found,
+            path: [
+              ...cached.path
+            ],
+            cost: cached.cost,
+            nodesSearched: cached.nodesSearched,
+            framesUsed: 0,
+            isPartial: false
+          },
+          affectedByChange: false
+        };
+        this.sessions.set(id, session2);
+        return request;
+      }
+      this.cacheMisses++;
+    }
+    const startNode = this.map.getNodeAt(startX, startY);
+    const endNode = this.map.getNodeAt(endX, endY);
+    if (!startNode || !endNode || !startNode.walkable || !endNode.walkable) {
+      const session2 = {
+        request,
+        state: PathfindingState.Failed,
+        options: opts,
+        openList: new IndexedBinaryHeap((a, b) => a.f - b.f),
+        nodeCache: /* @__PURE__ */ new Map(),
+        startNode,
+        endNode,
+        endPosition: endNode?.position ?? {
+          x: endX,
+          y: endY
+        },
+        nodesSearched: 0,
+        framesUsed: 0,
+        initialDistance: 0,
+        result: this.createEmptyResult(id),
+        affectedByChange: false
+      };
+      this.sessions.set(id, session2);
+      return request;
+    }
+    if (startNode.id === endNode.id) {
+      const session2 = {
+        request,
+        state: PathfindingState.Completed,
+        options: opts,
+        openList: new IndexedBinaryHeap((a, b) => a.f - b.f),
+        nodeCache: /* @__PURE__ */ new Map(),
+        startNode,
+        endNode,
+        endPosition: endNode.position,
+        nodesSearched: 1,
+        framesUsed: 0,
+        initialDistance: 0,
+        result: {
+          requestId: id,
+          found: true,
+          path: [
+            startNode.position
+          ],
+          cost: 0,
+          nodesSearched: 1,
+          framesUsed: 0,
+          isPartial: false
+        },
+        affectedByChange: false
+      };
+      this.sessions.set(id, session2);
+      return request;
+    }
+    const initialDistance = this.map.heuristic(startNode.position, endNode.position);
+    const openList = new IndexedBinaryHeap((a, b) => a.f - b.f);
+    const nodeCache = /* @__PURE__ */ new Map();
+    const startAStarNode = {
+      node: startNode,
+      g: 0,
+      h: initialDistance * opts.heuristicWeight,
+      f: initialDistance * opts.heuristicWeight,
+      parent: null,
+      closed: false,
+      opened: true,
+      heapIndex: -1
+    };
+    nodeCache.set(startNode.id, startAStarNode);
+    openList.push(startAStarNode);
+    const session = {
+      request,
+      state: PathfindingState.InProgress,
+      options: opts,
+      openList,
+      nodeCache,
+      startNode,
+      endNode,
+      endPosition: endNode.position,
+      nodesSearched: 0,
+      framesUsed: 0,
+      initialDistance,
+      result: null,
+      affectedByChange: false
+    };
+    this.sessions.set(id, session);
+    return request;
+  }
+  /**
+   * @zh 执行一步搜索
+   * @en Execute one step of search
+   */
+  step(requestId, maxIterations) {
+    const session = this.sessions.get(requestId);
+    if (!session) {
+      return EMPTY_PROGRESS;
+    }
+    if (session.state !== PathfindingState.InProgress) {
+      return this.createProgress(session);
+    }
+    session.framesUsed++;
+    let iterations = 0;
+    while (!session.openList.isEmpty && iterations < maxIterations) {
+      const current = session.openList.pop();
+      current.closed = true;
+      session.nodesSearched++;
+      iterations++;
+      if (current.node.id === session.endNode.id) {
+        session.state = PathfindingState.Completed;
+        session.result = this.buildResult(session, current);
+        if (this.cache && session.result.found) {
+          const req = session.request;
+          this.cache.set(req.startX, req.startY, req.endX, req.endY, {
+            found: true,
+            path: session.result.path,
+            cost: session.result.cost,
+            nodesSearched: session.result.nodesSearched
+          }, this.mapVersion);
+        }
+        return this.createProgress(session);
+      }
+      this.expandNeighbors(session, current);
+      if (session.nodesSearched >= session.options.maxNodes) {
+        session.state = PathfindingState.Failed;
+        session.result = this.createEmptyResult(requestId);
+        return this.createProgress(session);
+      }
+    }
+    if (session.openList.isEmpty && session.state === PathfindingState.InProgress) {
+      session.state = PathfindingState.Failed;
+      session.result = this.createEmptyResult(requestId);
+    }
+    return this.createProgress(session);
+  }
+  /**
+   * @zh 暂停寻路
+   * @en Pause pathfinding
+   */
+  pause(requestId) {
+    const session = this.sessions.get(requestId);
+    if (session && session.state === PathfindingState.InProgress) {
+      session.state = PathfindingState.Paused;
+    }
+  }
+  /**
+   * @zh 恢复寻路
+   * @en Resume pathfinding
+   */
+  resume(requestId) {
+    const session = this.sessions.get(requestId);
+    if (session && session.state === PathfindingState.Paused) {
+      session.state = PathfindingState.InProgress;
+    }
+  }
+  /**
+   * @zh 取消寻路
+   * @en Cancel pathfinding
+   */
+  cancel(requestId) {
+    const session = this.sessions.get(requestId);
+    if (session && (session.state === PathfindingState.InProgress || session.state === PathfindingState.Paused)) {
+      session.state = PathfindingState.Cancelled;
+      session.result = this.createEmptyResult(requestId);
+    }
+  }
+  /**
+   * @zh 获取寻路结果
+   * @en Get pathfinding result
+   */
+  getResult(requestId) {
+    const session = this.sessions.get(requestId);
+    return session?.result ?? null;
+  }
+  /**
+   * @zh 获取当前进度
+   * @en Get current progress
+   */
+  getProgress(requestId) {
+    const session = this.sessions.get(requestId);
+    return session ? this.createProgress(session) : null;
+  }
+  /**
+   * @zh 清理已完成的请求
+   * @en Clean up completed request
+   */
+  cleanup(requestId) {
+    const session = this.sessions.get(requestId);
+    if (session) {
+      session.openList.clear();
+      session.nodeCache.clear();
+      this.sessions.delete(requestId);
+    }
+  }
+  /**
+   * @zh 通知障碍物变化
+   * @en Notify obstacle change
+   */
+  notifyObstacleChange(minX, minY, maxX, maxY) {
+    this.mapVersion++;
+    if (this.cache) {
+      this.cache.invalidateRegion(minX, minY, maxX, maxY);
+    }
+    const region = {
+      minX,
+      minY,
+      maxX,
+      maxY,
+      timestamp: Date.now()
+    };
+    this.affectedRegions.push(region);
+    for (const session of this.sessions.values()) {
+      if (session.state === PathfindingState.InProgress || session.state === PathfindingState.Paused) {
+        if (this.sessionAffectedByRegion(session, region)) {
+          session.affectedByChange = true;
+        }
+      }
+    }
+    this.cleanupOldRegions();
+  }
+  /**
+   * @zh 清理所有请求
+   * @en Clear all requests
+   */
+  clear() {
+    for (const session of this.sessions.values()) {
+      session.openList.clear();
+      session.nodeCache.clear();
+    }
+    this.sessions.clear();
+    this.affectedRegions.length = 0;
+  }
+  /**
+   * @zh 清空路径缓存
+   * @en Clear path cache
+   */
+  clearCache() {
+    if (this.cache) {
+      this.cache.invalidateAll();
+      this.cacheHits = 0;
+      this.cacheMisses = 0;
+    }
+  }
+  /**
+   * @zh 获取缓存统计信息
+   * @en Get cache statistics
+   */
+  getCacheStats() {
+    if (!this.cache) {
+      return {
+        enabled: false,
+        hits: 0,
+        misses: 0,
+        hitRate: 0,
+        size: 0
+      };
+    }
+    const total = this.cacheHits + this.cacheMisses;
+    const hitRate = total > 0 ? this.cacheHits / total : 0;
+    return {
+      enabled: true,
+      hits: this.cacheHits,
+      misses: this.cacheMisses,
+      hitRate,
+      size: this.cache.getStats().size
+    };
+  }
+  /**
+   * @zh 检查会话是否被障碍物变化影响
+   * @en Check if session is affected by obstacle change
+   */
+  isAffectedByChange(requestId) {
+    const session = this.sessions.get(requestId);
+    return session?.affectedByChange ?? false;
+  }
+  /**
+   * @zh 清除会话的变化标记
+   * @en Clear session's change flag
+   */
+  clearChangeFlag(requestId) {
+    const session = this.sessions.get(requestId);
+    if (session) {
+      session.affectedByChange = false;
+    }
+  }
+  // =========================================================================
+  // 私有方法 | Private Methods
+  // =========================================================================
+  /**
+   * @zh 展开邻居节点
+   * @en Expand neighbor nodes
+   */
+  expandNeighbors(session, current) {
+    const neighbors = this.map.getNeighbors(current.node);
+    for (const neighborNode of neighbors) {
+      if (!neighborNode.walkable) {
+        continue;
+      }
+      let neighbor = session.nodeCache.get(neighborNode.id);
+      if (!neighbor) {
+        neighbor = {
+          node: neighborNode,
+          g: Infinity,
+          h: 0,
+          f: Infinity,
+          parent: null,
+          closed: false,
+          opened: false,
+          heapIndex: -1
+        };
+        session.nodeCache.set(neighborNode.id, neighbor);
+      }
+      if (neighbor.closed) {
+        continue;
+      }
+      const movementCost = this.map.getMovementCost(current.node, neighborNode);
+      const tentativeG = current.g + movementCost;
+      if (!neighbor.opened) {
+        neighbor.g = tentativeG;
+        neighbor.h = this.map.heuristic(neighborNode.position, session.endPosition) * session.options.heuristicWeight;
+        neighbor.f = neighbor.g + neighbor.h;
+        neighbor.parent = current;
+        neighbor.opened = true;
+        session.openList.push(neighbor);
+      } else if (tentativeG < neighbor.g) {
+        neighbor.g = tentativeG;
+        neighbor.f = neighbor.g + neighbor.h;
+        neighbor.parent = current;
+        session.openList.update(neighbor);
+      }
+    }
+  }
+  /**
+   * @zh 创建进度对象
+   * @en Create progress object
+   */
+  createProgress(session) {
+    let estimatedProgress = 0;
+    if (session.state === PathfindingState.Completed) {
+      estimatedProgress = 1;
+    } else if (session.state === PathfindingState.InProgress && session.initialDistance > 0) {
+      const bestNode = session.openList.peek();
+      if (bestNode) {
+        const currentDistance = bestNode.h / session.options.heuristicWeight;
+        estimatedProgress = Math.max(0, Math.min(1, 1 - currentDistance / session.initialDistance));
+      }
+    }
+    return {
+      state: session.state,
+      nodesSearched: session.nodesSearched,
+      openListSize: session.openList.size,
+      estimatedProgress
+    };
+  }
+  /**
+   * @zh 构建路径结果
+   * @en Build path result
+   */
+  buildResult(session, endNode) {
+    const path = [];
+    let current = endNode;
+    while (current) {
+      path.push(current.node.position);
+      current = current.parent;
+    }
+    path.reverse();
+    return {
+      requestId: session.request.id,
+      found: true,
+      path,
+      cost: endNode.g,
+      nodesSearched: session.nodesSearched,
+      framesUsed: session.framesUsed,
+      isPartial: false
+    };
+  }
+  /**
+   * @zh 创建空结果
+   * @en Create empty result
+   */
+  createEmptyResult(requestId) {
+    return {
+      requestId,
+      found: false,
+      path: [],
+      cost: 0,
+      nodesSearched: 0,
+      framesUsed: 0,
+      isPartial: false
+    };
+  }
+  /**
+   * @zh 检查会话是否被区域影响
+   * @en Check if session is affected by region
+   */
+  sessionAffectedByRegion(session, region) {
+    for (const astarNode of session.nodeCache.values()) {
+      if (astarNode.opened || astarNode.closed) {
+        const pos = astarNode.node.position;
+        if (pos.x >= region.minX && pos.x <= region.maxX && pos.y >= region.minY && pos.y <= region.maxY) {
+          return true;
+        }
+      }
+    }
+    const start = session.request;
+    const end = session.endPosition;
+    if (start.startX >= region.minX && start.startX <= region.maxX && start.startY >= region.minY && start.startY <= region.maxY || end.x >= region.minX && end.x <= region.maxX && end.y >= region.minY && end.y <= region.maxY) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * @zh 清理过期的变化区域
+   * @en Clean up expired change regions
+   */
+  cleanupOldRegions() {
+    const now = Date.now();
+    let i = 0;
+    while (i < this.affectedRegions.length) {
+      if (now - this.affectedRegions[i].timestamp > this.maxRegionAge) {
+        this.affectedRegions.splice(i, 1);
+      } else {
+        i++;
+      }
+    }
+  }
+};
+__name(_IncrementalAStarPathfinder, "IncrementalAStarPathfinder");
+var IncrementalAStarPathfinder = _IncrementalAStarPathfinder;
+function createIncrementalAStarPathfinder(map) {
+  return new IncrementalAStarPathfinder(map);
+}
+__name(createIncrementalAStarPathfinder, "createIncrementalAStarPathfinder");
+
+// src/core/JPSPathfinder.ts
+var _JPSPathfinder = class _JPSPathfinder {
+  constructor(map) {
+    __publicField(this, "map");
+    __publicField(this, "width");
+    __publicField(this, "height");
+    __publicField(this, "openList");
+    __publicField(this, "nodeGrid");
+    this.map = map;
+    const bounds = this.getMapBounds();
+    this.width = bounds.width;
+    this.height = bounds.height;
+    this.openList = new BinaryHeap((a, b) => a.f - b.f);
+    this.nodeGrid = [];
+  }
+  /**
+   * @zh 寻找路径
+   * @en Find path
+   */
+  findPath(startX, startY, endX, endY, options) {
+    const opts = {
+      ...DEFAULT_PATHFINDING_OPTIONS,
+      ...options
+    };
+    if (!this.map.isWalkable(startX, startY) || !this.map.isWalkable(endX, endY)) {
+      return EMPTY_PATH_RESULT;
+    }
+    if (startX === endX && startY === endY) {
+      return {
+        found: true,
+        path: [
+          {
+            x: startX,
+            y: startY
+          }
+        ],
+        cost: 0,
+        nodesSearched: 1
+      };
+    }
+    this.initGrid();
+    this.openList.clear();
+    const startNode = this.getOrCreateNode(startX, startY);
+    startNode.g = 0;
+    startNode.h = this.heuristic(startX, startY, endX, endY) * opts.heuristicWeight;
+    startNode.f = startNode.h;
+    this.openList.push(startNode);
+    let nodesSearched = 0;
+    while (!this.openList.isEmpty && nodesSearched < opts.maxNodes) {
+      const current = this.openList.pop();
+      current.closed = true;
+      nodesSearched++;
+      if (current.x === endX && current.y === endY) {
+        return {
+          found: true,
+          path: this.buildPath(current),
+          cost: current.g,
+          nodesSearched
+        };
+      }
+      this.identifySuccessors(current, endX, endY, opts);
+    }
+    return {
+      found: false,
+      path: [],
+      cost: 0,
+      nodesSearched
+    };
+  }
+  /**
+   * @zh 清理状态
+   * @en Clear state
+   */
+  clear() {
+    this.openList.clear();
+    this.nodeGrid = [];
+  }
+  // =========================================================================
+  // 私有方法 | Private Methods
+  // =========================================================================
+  /**
+   * @zh 获取地图边界
+   * @en Get map bounds
+   */
+  getMapBounds() {
+    const mapAny = this.map;
+    if (typeof mapAny.width === "number" && typeof mapAny.height === "number") {
+      return {
+        width: mapAny.width,
+        height: mapAny.height
+      };
+    }
+    return {
+      width: 1e3,
+      height: 1e3
+    };
+  }
+  /**
+   * @zh 初始化节点网格
+   * @en Initialize node grid
+   */
+  initGrid() {
+    this.nodeGrid = [];
+    for (let i = 0; i < this.width; i++) {
+      this.nodeGrid[i] = [];
+    }
+  }
+  /**
+   * @zh 获取或创建节点
+   * @en Get or create node
+   */
+  getOrCreateNode(x, y) {
+    const xi = x | 0;
+    const yi = y | 0;
+    if (xi < 0 || xi >= this.width || yi < 0 || yi >= this.height) {
+      throw new Error("[JPSPathfinder] Invalid grid coordinates");
+    }
+    if (!this.nodeGrid[xi]) {
+      this.nodeGrid[xi] = [];
+    }
+    if (!this.nodeGrid[xi][yi]) {
+      this.nodeGrid[xi][yi] = {
+        x: xi,
+        y: yi,
+        g: Infinity,
+        h: 0,
+        f: Infinity,
+        parent: null,
+        closed: false
+      };
+    }
+    return this.nodeGrid[xi][yi];
+  }
+  /**
+   * @zh 启发式函数（八方向距离）
+   * @en Heuristic function (octile distance)
+   */
+  heuristic(x1, y1, x2, y2) {
+    const dx = Math.abs(x1 - x2);
+    const dy = Math.abs(y1 - y2);
+    return dx + dy + (Math.SQRT2 - 2) * Math.min(dx, dy);
+  }
+  /**
+   * @zh 识别后继节点（跳跃点）
+   * @en Identify successors (jump points)
+   */
+  identifySuccessors(node, endX, endY, opts) {
+    const neighbors = this.findNeighbors(node);
+    for (const neighbor of neighbors) {
+      const jumpPoint = this.jump(neighbor.x, neighbor.y, node.x, node.y, endX, endY);
+      if (jumpPoint) {
+        const jx = jumpPoint.x;
+        const jy = jumpPoint.y;
+        const jpNode = this.getOrCreateNode(jx, jy);
+        if (jpNode.closed) continue;
+        const dx = Math.abs(jx - node.x);
+        const dy = Math.abs(jy - node.y);
+        const distance = Math.sqrt(dx * dx + dy * dy);
+        const tentativeG = node.g + distance;
+        if (tentativeG < jpNode.g) {
+          jpNode.g = tentativeG;
+          jpNode.h = this.heuristic(jx, jy, endX, endY) * opts.heuristicWeight;
+          jpNode.f = jpNode.g + jpNode.h;
+          jpNode.parent = node;
+          if (!this.openList.contains(jpNode)) {
+            this.openList.push(jpNode);
+          } else {
+            this.openList.update(jpNode);
+          }
+        }
+      }
+    }
+  }
+  /**
+   * @zh 查找邻居（根据父节点方向剪枝）
+   * @en Find neighbors (pruned based on parent direction)
+   */
+  findNeighbors(node) {
+    const { x, y, parent } = node;
+    const neighbors = [];
+    if (!parent) {
+      for (let dx2 = -1; dx2 <= 1; dx2++) {
+        for (let dy2 = -1; dy2 <= 1; dy2++) {
+          if (dx2 === 0 && dy2 === 0) continue;
+          const nx = x + dx2;
+          const ny = y + dy2;
+          if (this.isWalkableAt(nx, ny)) {
+            if (dx2 !== 0 && dy2 !== 0) {
+              if (this.isWalkableAt(x + dx2, y) || this.isWalkableAt(x, y + dy2)) {
+                neighbors.push({
+                  x: nx,
+                  y: ny
+                });
+              }
+            } else {
+              neighbors.push({
+                x: nx,
+                y: ny
+              });
+            }
+          }
+        }
+      }
+      return neighbors;
+    }
+    const dx = Math.sign(x - parent.x);
+    const dy = Math.sign(y - parent.y);
+    if (dx !== 0 && dy !== 0) {
+      if (this.isWalkableAt(x, y + dy)) {
+        neighbors.push({
+          x,
+          y: y + dy
+        });
+      }
+      if (this.isWalkableAt(x + dx, y)) {
+        neighbors.push({
+          x: x + dx,
+          y
+        });
+      }
+      if (this.isWalkableAt(x, y + dy) || this.isWalkableAt(x + dx, y)) {
+        if (this.isWalkableAt(x + dx, y + dy)) {
+          neighbors.push({
+            x: x + dx,
+            y: y + dy
+          });
+        }
+      }
+      if (!this.isWalkableAt(x - dx, y) && this.isWalkableAt(x, y + dy)) {
+        if (this.isWalkableAt(x - dx, y + dy)) {
+          neighbors.push({
+            x: x - dx,
+            y: y + dy
+          });
+        }
+      }
+      if (!this.isWalkableAt(x, y - dy) && this.isWalkableAt(x + dx, y)) {
+        if (this.isWalkableAt(x + dx, y - dy)) {
+          neighbors.push({
+            x: x + dx,
+            y: y - dy
+          });
+        }
+      }
+    } else if (dx !== 0) {
+      if (this.isWalkableAt(x + dx, y)) {
+        neighbors.push({
+          x: x + dx,
+          y
+        });
+        if (!this.isWalkableAt(x, y + 1) && this.isWalkableAt(x + dx, y + 1)) {
+          neighbors.push({
+            x: x + dx,
+            y: y + 1
+          });
+        }
+        if (!this.isWalkableAt(x, y - 1) && this.isWalkableAt(x + dx, y - 1)) {
+          neighbors.push({
+            x: x + dx,
+            y: y - 1
+          });
+        }
+      }
+    } else if (dy !== 0) {
+      if (this.isWalkableAt(x, y + dy)) {
+        neighbors.push({
+          x,
+          y: y + dy
+        });
+        if (!this.isWalkableAt(x + 1, y) && this.isWalkableAt(x + 1, y + dy)) {
+          neighbors.push({
+            x: x + 1,
+            y: y + dy
+          });
+        }
+        if (!this.isWalkableAt(x - 1, y) && this.isWalkableAt(x - 1, y + dy)) {
+          neighbors.push({
+            x: x - 1,
+            y: y + dy
+          });
+        }
+      }
+    }
+    return neighbors;
+  }
+  /**
+   * @zh 跳跃函数（迭代版本，避免递归开销）
+   * @en Jump function (iterative version to avoid recursion overhead)
+   */
+  jump(startX, startY, px, py, endX, endY) {
+    const dx = startX - px;
+    const dy = startY - py;
+    let x = startX;
+    let y = startY;
+    while (true) {
+      if (!this.isWalkableAt(x, y)) {
+        return null;
+      }
+      if (x === endX && y === endY) {
+        return {
+          x,
+          y
+        };
+      }
+      if (dx !== 0 && dy !== 0) {
+        if (this.isWalkableAt(x - dx, y + dy) && !this.isWalkableAt(x - dx, y) || this.isWalkableAt(x + dx, y - dy) && !this.isWalkableAt(x, y - dy)) {
+          return {
+            x,
+            y
+          };
+        }
+        if (this.jumpStraight(x + dx, y, dx, 0, endX, endY) || this.jumpStraight(x, y + dy, 0, dy, endX, endY)) {
+          return {
+            x,
+            y
+          };
+        }
+        if (!this.isWalkableAt(x + dx, y) && !this.isWalkableAt(x, y + dy)) {
+          return null;
+        }
+      } else if (dx !== 0) {
+        if (this.isWalkableAt(x + dx, y + 1) && !this.isWalkableAt(x, y + 1) || this.isWalkableAt(x + dx, y - 1) && !this.isWalkableAt(x, y - 1)) {
+          return {
+            x,
+            y
+          };
+        }
+      } else if (dy !== 0) {
+        if (this.isWalkableAt(x + 1, y + dy) && !this.isWalkableAt(x + 1, y) || this.isWalkableAt(x - 1, y + dy) && !this.isWalkableAt(x - 1, y)) {
+          return {
+            x,
+            y
+          };
+        }
+      }
+      x += dx;
+      y += dy;
+    }
+  }
+  /**
+   * @zh 直线跳跃（水平或垂直方向）
+   * @en Straight jump (horizontal or vertical direction)
+   */
+  jumpStraight(startX, startY, dx, dy, endX, endY) {
+    let x = startX;
+    let y = startY;
+    while (true) {
+      if (!this.isWalkableAt(x, y)) {
+        return false;
+      }
+      if (x === endX && y === endY) {
+        return true;
+      }
+      if (dx !== 0) {
+        if (this.isWalkableAt(x + dx, y + 1) && !this.isWalkableAt(x, y + 1) || this.isWalkableAt(x + dx, y - 1) && !this.isWalkableAt(x, y - 1)) {
+          return true;
+        }
+      } else if (dy !== 0) {
+        if (this.isWalkableAt(x + 1, y + dy) && !this.isWalkableAt(x + 1, y) || this.isWalkableAt(x - 1, y + dy) && !this.isWalkableAt(x - 1, y)) {
+          return true;
+        }
+      }
+      x += dx;
+      y += dy;
+    }
+  }
+  /**
+   * @zh 检查位置是否可通行
+   * @en Check if position is walkable
+   */
+  isWalkableAt(x, y) {
+    if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
+      return false;
+    }
+    return this.map.isWalkable(x, y);
+  }
+  /**
+   * @zh 构建路径
+   * @en Build path
+   */
+  buildPath(endNode) {
+    const path = [];
+    let current = endNode;
+    while (current) {
+      path.unshift({
+        x: current.x,
+        y: current.y
+      });
+      current = current.parent;
+    }
+    return this.interpolatePath(path);
+  }
+  /**
+   * @zh 插值路径（在跳跃点之间填充中间点）
+   * @en Interpolate path (fill intermediate points between jump points)
+   */
+  interpolatePath(jumpPoints) {
+    if (jumpPoints.length < 2) {
+      return jumpPoints;
+    }
+    const path = [
+      jumpPoints[0]
+    ];
+    for (let i = 1; i < jumpPoints.length; i++) {
+      const prev = jumpPoints[i - 1];
+      const curr = jumpPoints[i];
+      const dx = curr.x - prev.x;
+      const dy = curr.y - prev.y;
+      const steps = Math.max(Math.abs(dx), Math.abs(dy));
+      const stepX = dx === 0 ? 0 : dx / Math.abs(dx);
+      const stepY = dy === 0 ? 0 : dy / Math.abs(dy);
+      let x = prev.x;
+      let y = prev.y;
+      for (let j = 0; j < steps; j++) {
+        if (x !== curr.x && y !== curr.y) {
+          x += stepX;
+          y += stepY;
+        } else if (x !== curr.x) {
+          x += stepX;
+        } else if (y !== curr.y) {
+          y += stepY;
+        }
+        if (x !== prev.x || y !== prev.y) {
+          path.push({
+            x,
+            y
+          });
+        }
+      }
+    }
+    return path;
+  }
+};
+__name(_JPSPathfinder, "JPSPathfinder");
+var JPSPathfinder = _JPSPathfinder;
+function createJPSPathfinder(map) {
+  return new JPSPathfinder(map);
+}
+__name(createJPSPathfinder, "createJPSPathfinder");
+
+// src/core/HPAPathfinder.ts
+var DEFAULT_HPA_CONFIG = {
+  clusterSize: 64,
+  maxEntranceWidth: 16,
+  cacheInternalPaths: true,
+  entranceStrategy: "end",
+  lazyIntraEdges: true
+};
+var _a;
+var SubMap = (_a = class {
+  constructor(parentMap, originX, originY, width, height) {
+    __publicField(this, "parentMap");
+    __publicField(this, "originX");
+    __publicField(this, "originY");
+    __publicField(this, "width");
+    __publicField(this, "height");
+    this.parentMap = parentMap;
+    this.originX = originX;
+    this.originY = originY;
+    this.width = width;
+    this.height = height;
+  }
+  /**
+   * @zh 局部坐标转全局坐标
+   * @en Convert local to global coordinates
+   */
+  localToGlobal(localX, localY) {
+    return {
+      x: this.originX + localX,
+      y: this.originY + localY
+    };
+  }
+  /**
+   * @zh 全局坐标转局部坐标
+   * @en Convert global to local coordinates
+   */
+  globalToLocal(globalX, globalY) {
+    return {
+      x: globalX - this.originX,
+      y: globalY - this.originY
+    };
+  }
+  isWalkable(x, y) {
+    if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
+      return false;
+    }
+    return this.parentMap.isWalkable(this.originX + x, this.originY + y);
+  }
+  getNodeAt(x, y) {
+    if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
+      return null;
+    }
+    const globalNode = this.parentMap.getNodeAt(this.originX + x, this.originY + y);
+    if (!globalNode) return null;
+    return {
+      id: y * this.width + x,
+      position: {
+        x,
+        y
+      },
+      cost: globalNode.cost,
+      walkable: globalNode.walkable
+    };
+  }
+  getNeighbors(node) {
+    const neighbors = [];
+    const { x, y } = node.position;
+    const directions = [
+      {
+        dx: 0,
+        dy: -1
+      },
+      {
+        dx: 1,
+        dy: -1
+      },
+      {
+        dx: 1,
+        dy: 0
+      },
+      {
+        dx: 1,
+        dy: 1
+      },
+      {
+        dx: 0,
+        dy: 1
+      },
+      {
+        dx: -1,
+        dy: 1
+      },
+      {
+        dx: -1,
+        dy: 0
+      },
+      {
+        dx: -1,
+        dy: -1
+      }
+      // NW
+    ];
+    for (const dir of directions) {
+      const nx = x + dir.dx;
+      const ny = y + dir.dy;
+      if (nx < 0 || nx >= this.width || ny < 0 || ny >= this.height) {
+        continue;
+      }
+      if (!this.isWalkable(nx, ny)) {
+        continue;
+      }
+      if (dir.dx !== 0 && dir.dy !== 0) {
+        if (!this.isWalkable(x + dir.dx, y) || !this.isWalkable(x, y + dir.dy)) {
+          continue;
+        }
+      }
+      const neighborNode = this.getNodeAt(nx, ny);
+      if (neighborNode) {
+        neighbors.push(neighborNode);
+      }
+    }
+    return neighbors;
+  }
+  heuristic(a, b) {
+    const dx = Math.abs(a.x - b.x);
+    const dy = Math.abs(a.y - b.y);
+    return dx + dy + (Math.SQRT2 - 2) * Math.min(dx, dy);
+  }
+  getMovementCost(from, to) {
+    const dx = Math.abs(to.position.x - from.position.x);
+    const dy = Math.abs(to.position.y - from.position.y);
+    const baseCost = dx !== 0 && dy !== 0 ? Math.SQRT2 : 1;
+    return baseCost * to.cost;
+  }
+}, __name(_a, "SubMap"), _a);
+var _a2;
+var Cluster = (_a2 = class {
+  constructor(id, originX, originY, width, height, parentMap) {
+    __publicField(this, "id");
+    __publicField(this, "originX");
+    __publicField(this, "originY");
+    __publicField(this, "width");
+    __publicField(this, "height");
+    __publicField(this, "subMap");
+    /** @zh 集群内的抽象节点 ID 列表 @en Abstract node IDs in this cluster */
+    __publicField(this, "nodeIds", []);
+    /** @zh 预计算的距离缓存 @en Precomputed distance cache */
+    __publicField(this, "distanceCache", /* @__PURE__ */ new Map());
+    /** @zh 预计算的路径缓存 @en Precomputed path cache */
+    __publicField(this, "pathCache", /* @__PURE__ */ new Map());
+    this.id = id;
+    this.originX = originX;
+    this.originY = originY;
+    this.width = width;
+    this.height = height;
+    this.subMap = new SubMap(parentMap, originX, originY, width, height);
+  }
+  /**
+   * @zh 检查点是否在集群内
+   * @en Check if point is in cluster
+   */
+  containsPoint(x, y) {
+    return x >= this.originX && x < this.originX + this.width && y >= this.originY && y < this.originY + this.height;
+  }
+  /**
+   * @zh 添加节点 ID
+   * @en Add node ID
+   */
+  addNodeId(nodeId) {
+    if (!this.nodeIds.includes(nodeId)) {
+      this.nodeIds.push(nodeId);
+    }
+  }
+  /**
+   * @zh 移除节点 ID
+   * @en Remove node ID
+   */
+  removeNodeId(nodeId) {
+    const idx = this.nodeIds.indexOf(nodeId);
+    if (idx !== -1) {
+      this.nodeIds.splice(idx, 1);
+    }
+  }
+  /**
+   * @zh 生成缓存键
+   * @en Generate cache key
+   */
+  getCacheKey(fromId, toId) {
+    return `${fromId}->${toId}`;
+  }
+  /**
+   * @zh 设置缓存
+   * @en Set cache
+   */
+  setCache(fromId, toId, cost, path) {
+    const key = this.getCacheKey(fromId, toId);
+    this.distanceCache.set(key, cost);
+    this.pathCache.set(key, path);
+  }
+  /**
+   * @zh 获取缓存的距离
+   * @en Get cached distance
+   */
+  getCachedDistance(fromId, toId) {
+    return this.distanceCache.get(this.getCacheKey(fromId, toId));
+  }
+  /**
+   * @zh 获取缓存的路径
+   * @en Get cached path
+   */
+  getCachedPath(fromId, toId) {
+    return this.pathCache.get(this.getCacheKey(fromId, toId));
+  }
+  /**
+   * @zh 清除缓存
+   * @en Clear cache
+   */
+  clearCache() {
+    this.distanceCache.clear();
+    this.pathCache.clear();
+  }
+  /**
+   * @zh 获取缓存大小
+   * @en Get cache size
+   */
+  getCacheSize() {
+    return this.distanceCache.size;
+  }
+}, __name(_a2, "Cluster"), _a2);
+var _HPAPathfinder = class _HPAPathfinder {
+  constructor(map, config) {
+    __publicField(this, "map");
+    __publicField(this, "config");
+    __publicField(this, "mapWidth");
+    __publicField(this, "mapHeight");
+    // 集群管理
+    __publicField(this, "clusters", []);
+    __publicField(this, "clusterGrid", []);
+    __publicField(this, "clustersX", 0);
+    __publicField(this, "clustersY", 0);
+    // 抽象图
+    __publicField(this, "abstractNodes", /* @__PURE__ */ new Map());
+    __publicField(this, "nodesByCluster", /* @__PURE__ */ new Map());
+    __publicField(this, "nextNodeId", 0);
+    // 入口统计
+    __publicField(this, "entranceCount", 0);
+    // 内部寻路器
+    __publicField(this, "localPathfinder");
+    // 完整路径缓存
+    __publicField(this, "pathCache");
+    __publicField(this, "mapVersion", 0);
+    __publicField(this, "preprocessed", false);
+    this.map = map;
+    this.config = {
+      ...DEFAULT_HPA_CONFIG,
+      ...config
+    };
+    const bounds = this.getMapBounds();
+    this.mapWidth = bounds.width;
+    this.mapHeight = bounds.height;
+    this.localPathfinder = new AStarPathfinder(map);
+    this.pathCache = new PathCache({
+      maxEntries: 1e3,
+      ttlMs: 0
+    });
+  }
+  // =========================================================================
+  // 公共 API | Public API
+  // =========================================================================
+  /**
+   * @zh 预处理地图（构建抽象图）
+   * @en Preprocess map (build abstract graph)
+   */
+  preprocess() {
+    this.clear();
+    this.buildClusters();
+    this.buildEntrances();
+    this.buildIntraEdges();
+    this.preprocessed = true;
+  }
+  /**
+   * @zh 寻找路径
+   * @en Find path
+   */
+  findPath(startX, startY, endX, endY, options) {
+    if (!this.preprocessed) {
+      this.preprocess();
+    }
+    const opts = {
+      ...DEFAULT_PATHFINDING_OPTIONS,
+      ...options
+    };
+    if (!this.map.isWalkable(startX, startY) || !this.map.isWalkable(endX, endY)) {
+      return EMPTY_PATH_RESULT;
+    }
+    if (startX === endX && startY === endY) {
+      return {
+        found: true,
+        path: [
+          {
+            x: startX,
+            y: startY
+          }
+        ],
+        cost: 0,
+        nodesSearched: 1
+      };
+    }
+    const cached = this.pathCache.get(startX, startY, endX, endY, this.mapVersion);
+    if (cached) {
+      return cached;
+    }
+    const startCluster = this.getClusterAt(startX, startY);
+    const endCluster = this.getClusterAt(endX, endY);
+    if (!startCluster || !endCluster) {
+      return EMPTY_PATH_RESULT;
+    }
+    let result;
+    if (startCluster.id === endCluster.id) {
+      result = this.findLocalPath(startX, startY, endX, endY, opts);
+    } else {
+      const startTemp = this.insertTempNode(startX, startY, startCluster);
+      const endTemp = this.insertTempNode(endX, endY, endCluster);
+      const abstractPath = this.abstractSearch(startTemp, endTemp, opts);
+      this.removeTempNode(startTemp, startCluster);
+      this.removeTempNode(endTemp, endCluster);
+      if (!abstractPath || abstractPath.length === 0) {
+        return EMPTY_PATH_RESULT;
+      }
+      result = this.refinePath(abstractPath, startX, startY, endX, endY, opts);
+    }
+    if (result.found) {
+      this.pathCache.set(startX, startY, endX, endY, result, this.mapVersion);
+    }
+    return result;
+  }
+  /**
+   * @zh 清理状态
+   * @en Clear state
+   */
+  clear() {
+    this.clusters = [];
+    this.clusterGrid = [];
+    this.abstractNodes.clear();
+    this.nodesByCluster.clear();
+    this.nextNodeId = 0;
+    this.entranceCount = 0;
+    this.pathCache.invalidateAll();
+    this.mapVersion++;
+    this.preprocessed = false;
+  }
+  /**
+   * @zh 通知地图区域变化
+   * @en Notify map region change
+   */
+  notifyRegionChange(minX, minY, maxX, maxY) {
+    const affectedClusters = this.getAffectedClusters(minX, minY, maxX, maxY);
+    for (const cluster of affectedClusters) {
+      cluster.clearCache();
+      for (const nodeId of cluster.nodeIds) {
+        const node = this.abstractNodes.get(nodeId);
+        if (node) {
+          node.edges = node.edges.filter((e) => e.isInterEdge);
+        }
+      }
+      this.buildClusterIntraEdges(cluster);
+    }
+    this.pathCache.invalidateRegion(minX, minY, maxX, maxY);
+    this.mapVersion++;
+  }
+  /**
+   * @zh 获取预处理统计信息
+   * @en Get preprocessing statistics
+   */
+  getStats() {
+    let cacheSize = 0;
+    for (const cluster of this.clusters) {
+      cacheSize += cluster.getCacheSize();
+    }
+    return {
+      clusters: this.clusters.length,
+      entrances: this.entranceCount,
+      abstractNodes: this.abstractNodes.size,
+      cacheSize
+    };
+  }
+  // =========================================================================
+  // 预处理方法 | Preprocessing Methods
+  // =========================================================================
+  getMapBounds() {
+    const mapAny = this.map;
+    if (typeof mapAny.width === "number" && typeof mapAny.height === "number") {
+      return {
+        width: mapAny.width,
+        height: mapAny.height
+      };
+    }
+    return {
+      width: 1e3,
+      height: 1e3
+    };
+  }
+  /**
+   * @zh 构建集群
+   * @en Build clusters
+   */
+  buildClusters() {
+    const clusterSize = this.config.clusterSize;
+    this.clustersX = Math.ceil(this.mapWidth / clusterSize);
+    this.clustersY = Math.ceil(this.mapHeight / clusterSize);
+    this.clusterGrid = [];
+    for (let cx = 0; cx < this.clustersX; cx++) {
+      this.clusterGrid[cx] = [];
+      for (let cy = 0; cy < this.clustersY; cy++) {
+        this.clusterGrid[cx][cy] = null;
+      }
+    }
+    let clusterId = 0;
+    for (let cy = 0; cy < this.clustersY; cy++) {
+      for (let cx = 0; cx < this.clustersX; cx++) {
+        const originX = cx * clusterSize;
+        const originY = cy * clusterSize;
+        const width = Math.min(clusterSize, this.mapWidth - originX);
+        const height = Math.min(clusterSize, this.mapHeight - originY);
+        const cluster = new Cluster(clusterId, originX, originY, width, height, this.map);
+        this.clusters.push(cluster);
+        this.clusterGrid[cx][cy] = clusterId;
+        this.nodesByCluster.set(clusterId, []);
+        clusterId++;
+      }
+    }
+  }
+  /**
+   * @zh 检测入口并创建抽象节点
+   * @en Detect entrances and create abstract nodes
+   */
+  buildEntrances() {
+    const clusterSize = this.config.clusterSize;
+    for (let cy = 0; cy < this.clustersY; cy++) {
+      for (let cx = 0; cx < this.clustersX; cx++) {
+        const clusterId = this.clusterGrid[cx][cy];
+        if (clusterId === null) continue;
+        const cluster1 = this.clusters[clusterId];
+        if (cx < this.clustersX - 1) {
+          const cluster2Id = this.clusterGrid[cx + 1][cy];
+          if (cluster2Id !== null) {
+            const cluster2 = this.clusters[cluster2Id];
+            this.detectAndCreateEntrances(cluster1, cluster2, "vertical");
+          }
+        }
+        if (cy < this.clustersY - 1) {
+          const cluster2Id = this.clusterGrid[cx][cy + 1];
+          if (cluster2Id !== null) {
+            const cluster2 = this.clusters[cluster2Id];
+            this.detectAndCreateEntrances(cluster1, cluster2, "horizontal");
+          }
+        }
+      }
+    }
+  }
+  /**
+   * @zh 检测并创建两个相邻集群之间的入口
+   * @en Detect and create entrances between two adjacent clusters
+   */
+  detectAndCreateEntrances(cluster1, cluster2, boundaryDirection) {
+    const spans = this.detectEntranceSpans(cluster1, cluster2, boundaryDirection);
+    for (const span of spans) {
+      this.createEntranceNodes(cluster1, cluster2, span, boundaryDirection);
+    }
+  }
+  /**
+   * @zh 检测边界上的连续可通行区间
+   * @en Detect continuous walkable spans on boundary
+   */
+  detectEntranceSpans(cluster1, cluster2, boundaryDirection) {
+    const spans = [];
+    if (boundaryDirection === "vertical") {
+      const x1 = cluster1.originX + cluster1.width - 1;
+      const x2 = cluster2.originX;
+      const startY = Math.max(cluster1.originY, cluster2.originY);
+      const endY = Math.min(cluster1.originY + cluster1.height, cluster2.originY + cluster2.height);
+      let spanStart = null;
+      for (let y = startY; y < endY; y++) {
+        const walkable1 = this.map.isWalkable(x1, y);
+        const walkable2 = this.map.isWalkable(x2, y);
+        if (walkable1 && walkable2) {
+          if (spanStart === null) {
+            spanStart = y;
+          }
+        } else {
+          if (spanStart !== null) {
+            spans.push({
+              start: spanStart,
+              end: y - 1
+            });
+            spanStart = null;
+          }
+        }
+      }
+      if (spanStart !== null) {
+        spans.push({
+          start: spanStart,
+          end: endY - 1
+        });
+      }
+    } else {
+      const y1 = cluster1.originY + cluster1.height - 1;
+      const y2 = cluster2.originY;
+      const startX = Math.max(cluster1.originX, cluster2.originX);
+      const endX = Math.min(cluster1.originX + cluster1.width, cluster2.originX + cluster2.width);
+      let spanStart = null;
+      for (let x = startX; x < endX; x++) {
+        const walkable1 = this.map.isWalkable(x, y1);
+        const walkable2 = this.map.isWalkable(x, y2);
+        if (walkable1 && walkable2) {
+          if (spanStart === null) {
+            spanStart = x;
+          }
+        } else {
+          if (spanStart !== null) {
+            spans.push({
+              start: spanStart,
+              end: x - 1
+            });
+            spanStart = null;
+          }
+        }
+      }
+      if (spanStart !== null) {
+        spans.push({
+          start: spanStart,
+          end: endX - 1
+        });
+      }
+    }
+    return spans;
+  }
+  /**
+   * @zh 为入口区间创建抽象节点
+   * @en Create abstract nodes for entrance span
+   */
+  createEntranceNodes(cluster1, cluster2, span, boundaryDirection) {
+    const spanLength = span.end - span.start + 1;
+    const maxWidth = this.config.maxEntranceWidth;
+    const strategy = this.config.entranceStrategy;
+    const positions = [];
+    if (spanLength <= maxWidth) {
+      positions.push(Math.floor((span.start + span.end) / 2));
+    } else {
+      const numNodes = Math.ceil(spanLength / maxWidth);
+      const spacing = spanLength / numNodes;
+      for (let i = 0; i < numNodes; i++) {
+        const pos = Math.floor(span.start + spacing * (i + 0.5));
+        positions.push(Math.min(pos, span.end));
+      }
+      if (strategy === "end") {
+        if (!positions.includes(span.start)) {
+          positions.unshift(span.start);
+        }
+        if (!positions.includes(span.end)) {
+          positions.push(span.end);
+        }
+      }
+    }
+    for (const pos of positions) {
+      let p1, p2;
+      if (boundaryDirection === "vertical") {
+        p1 = {
+          x: cluster1.originX + cluster1.width - 1,
+          y: pos
+        };
+        p2 = {
+          x: cluster2.originX,
+          y: pos
+        };
+      } else {
+        p1 = {
+          x: pos,
+          y: cluster1.originY + cluster1.height - 1
+        };
+        p2 = {
+          x: pos,
+          y: cluster2.originY
+        };
+      }
+      const node1 = this.createAbstractNode(p1, cluster1);
+      const node2 = this.createAbstractNode(p2, cluster2);
+      const interCost = 1;
+      node1.edges.push({
+        targetNodeId: node2.id,
+        cost: interCost,
+        isInterEdge: true,
+        innerPath: null
+      });
+      node2.edges.push({
+        targetNodeId: node1.id,
+        cost: interCost,
+        isInterEdge: true,
+        innerPath: null
+      });
+      this.entranceCount++;
+    }
+  }
+  /**
+   * @zh 创建抽象节点
+   * @en Create abstract node
+   */
+  createAbstractNode(position, cluster) {
+    const concreteId = position.y * this.mapWidth + position.x;
+    for (const nodeId of cluster.nodeIds) {
+      const existing = this.abstractNodes.get(nodeId);
+      if (existing && existing.concreteNodeId === concreteId) {
+        return existing;
+      }
+    }
+    const node = {
+      id: this.nextNodeId++,
+      position: {
+        x: position.x,
+        y: position.y
+      },
+      clusterId: cluster.id,
+      concreteNodeId: concreteId,
+      edges: []
+    };
+    this.abstractNodes.set(node.id, node);
+    cluster.addNodeId(node.id);
+    const clusterNodes = this.nodesByCluster.get(cluster.id);
+    if (clusterNodes) {
+      clusterNodes.push(node.id);
+    }
+    return node;
+  }
+  /**
+   * @zh 构建所有集群的 intra-edges
+   * @en Build intra-edges for all clusters
+   */
+  buildIntraEdges() {
+    for (const cluster of this.clusters) {
+      this.buildClusterIntraEdges(cluster);
+    }
+  }
+  /**
+   * @zh 构建单个集群的 intra-edges
+   * @en Build intra-edges for single cluster
+   */
+  buildClusterIntraEdges(cluster) {
+    const nodeIds = cluster.nodeIds;
+    if (nodeIds.length < 2) return;
+    if (this.config.lazyIntraEdges) {
+      this.buildLazyIntraEdges(cluster);
+    } else {
+      this.buildEagerIntraEdges(cluster);
+    }
+  }
+  /**
+   * @zh 延迟构建 intra-edges（只用启发式距离）
+   * @en Build lazy intra-edges (using heuristic distance only)
+   */
+  buildLazyIntraEdges(cluster) {
+    const nodeIds = cluster.nodeIds;
+    for (let i = 0; i < nodeIds.length; i++) {
+      for (let j = i + 1; j < nodeIds.length; j++) {
+        const node1 = this.abstractNodes.get(nodeIds[i]);
+        const node2 = this.abstractNodes.get(nodeIds[j]);
+        const heuristicCost = this.heuristic(node1.position, node2.position);
+        node1.edges.push({
+          targetNodeId: node2.id,
+          cost: heuristicCost,
+          isInterEdge: false,
+          innerPath: null
+          // 标记为未计算
+        });
+        node2.edges.push({
+          targetNodeId: node1.id,
+          cost: heuristicCost,
+          isInterEdge: false,
+          innerPath: null
+        });
+      }
+    }
+  }
+  /**
+   * @zh 立即构建 intra-edges（计算真实路径）
+   * @en Build eager intra-edges (compute actual paths)
+   */
+  buildEagerIntraEdges(cluster) {
+    const nodeIds = cluster.nodeIds;
+    const subPathfinder = new AStarPathfinder(cluster.subMap);
+    for (let i = 0; i < nodeIds.length; i++) {
+      for (let j = i + 1; j < nodeIds.length; j++) {
+        const node1 = this.abstractNodes.get(nodeIds[i]);
+        const node2 = this.abstractNodes.get(nodeIds[j]);
+        const local1 = cluster.subMap.globalToLocal(node1.position.x, node1.position.y);
+        const local2 = cluster.subMap.globalToLocal(node2.position.x, node2.position.y);
+        const result = subPathfinder.findPath(local1.x, local1.y, local2.x, local2.y);
+        if (result.found && result.path.length > 0) {
+          const globalPath = result.path.map((p) => {
+            const global = cluster.subMap.localToGlobal(p.x, p.y);
+            return global.y * this.mapWidth + global.x;
+          });
+          if (this.config.cacheInternalPaths) {
+            cluster.setCache(node1.id, node2.id, result.cost, globalPath);
+            cluster.setCache(node2.id, node1.id, result.cost, [
+              ...globalPath
+            ].reverse());
+          }
+          node1.edges.push({
+            targetNodeId: node2.id,
+            cost: result.cost,
+            isInterEdge: false,
+            innerPath: this.config.cacheInternalPaths ? globalPath : null
+          });
+          node2.edges.push({
+            targetNodeId: node1.id,
+            cost: result.cost,
+            isInterEdge: false,
+            innerPath: this.config.cacheInternalPaths ? [
+              ...globalPath
+            ].reverse() : null
+          });
+        }
+      }
+    }
+  }
+  /**
+   * @zh 按需计算 intra-edge 的真实路径
+   * @en Compute actual path for intra-edge on demand
+   */
+  computeIntraEdgePath(fromNode, toNode, edge) {
+    const cluster = this.clusters[fromNode.clusterId];
+    if (!cluster) return null;
+    const cachedPath = cluster.getCachedPath(fromNode.id, toNode.id);
+    const cachedCost = cluster.getCachedDistance(fromNode.id, toNode.id);
+    if (cachedPath && cachedCost !== void 0) {
+      edge.cost = cachedCost;
+      edge.innerPath = cachedPath;
+      return {
+        cost: cachedCost,
+        path: cachedPath
+      };
+    }
+    const subPathfinder = new AStarPathfinder(cluster.subMap);
+    const local1 = cluster.subMap.globalToLocal(fromNode.position.x, fromNode.position.y);
+    const local2 = cluster.subMap.globalToLocal(toNode.position.x, toNode.position.y);
+    const result = subPathfinder.findPath(local1.x, local1.y, local2.x, local2.y);
+    if (result.found && result.path.length > 0) {
+      const globalPath = result.path.map((p) => {
+        const global = cluster.subMap.localToGlobal(p.x, p.y);
+        return global.y * this.mapWidth + global.x;
+      });
+      if (this.config.cacheInternalPaths) {
+        cluster.setCache(fromNode.id, toNode.id, result.cost, globalPath);
+        cluster.setCache(toNode.id, fromNode.id, result.cost, [
+          ...globalPath
+        ].reverse());
+      }
+      edge.cost = result.cost;
+      edge.innerPath = globalPath;
+      const reverseEdge = toNode.edges.find((e) => e.targetNodeId === fromNode.id);
+      if (reverseEdge) {
+        reverseEdge.cost = result.cost;
+        reverseEdge.innerPath = [
+          ...globalPath
+        ].reverse();
+      }
+      return {
+        cost: result.cost,
+        path: globalPath
+      };
+    }
+    return null;
+  }
+  // =========================================================================
+  // 搜索方法 | Search Methods
+  // =========================================================================
+  /**
+   * @zh 获取指定位置的集群
+   * @en Get cluster at position
+   */
+  getClusterAt(x, y) {
+    const cx = Math.floor(x / this.config.clusterSize);
+    const cy = Math.floor(y / this.config.clusterSize);
+    if (cx < 0 || cx >= this.clustersX || cy < 0 || cy >= this.clustersY) {
+      return null;
+    }
+    const clusterId = this.clusterGrid[cx]?.[cy];
+    if (clusterId === null || clusterId === void 0) {
+      return null;
+    }
+    return this.clusters[clusterId] || null;
+  }
+  /**
+   * @zh 获取受影响的集群
+   * @en Get affected clusters
+   */
+  getAffectedClusters(minX, minY, maxX, maxY) {
+    const affected = [];
+    const clusterSize = this.config.clusterSize;
+    const minCX = Math.floor(minX / clusterSize);
+    const maxCX = Math.floor(maxX / clusterSize);
+    const minCY = Math.floor(minY / clusterSize);
+    const maxCY = Math.floor(maxY / clusterSize);
+    for (let cy = minCY; cy <= maxCY; cy++) {
+      for (let cx = minCX; cx <= maxCX; cx++) {
+        if (cx >= 0 && cx < this.clustersX && cy >= 0 && cy < this.clustersY) {
+          const clusterId = this.clusterGrid[cx]?.[cy];
+          if (clusterId !== null && clusterId !== void 0) {
+            affected.push(this.clusters[clusterId]);
+          }
+        }
+      }
+    }
+    return affected;
+  }
+  /**
+   * @zh 插入临时节点
+   * @en Insert temporary node
+   */
+  insertTempNode(x, y, cluster) {
+    const concreteId = y * this.mapWidth + x;
+    for (const nodeId of cluster.nodeIds) {
+      const existing = this.abstractNodes.get(nodeId);
+      if (existing && existing.concreteNodeId === concreteId) {
+        return existing;
+      }
+    }
+    const tempNode = {
+      id: this.nextNodeId++,
+      position: {
+        x,
+        y
+      },
+      clusterId: cluster.id,
+      concreteNodeId: concreteId,
+      edges: []
+    };
+    this.abstractNodes.set(tempNode.id, tempNode);
+    cluster.addNodeId(tempNode.id);
+    const subPathfinder = new AStarPathfinder(cluster.subMap);
+    const localPos = cluster.subMap.globalToLocal(x, y);
+    for (const existingNodeId of cluster.nodeIds) {
+      if (existingNodeId === tempNode.id) continue;
+      const existingNode = this.abstractNodes.get(existingNodeId);
+      if (!existingNode) continue;
+      const targetLocalPos = cluster.subMap.globalToLocal(existingNode.position.x, existingNode.position.y);
+      const result = subPathfinder.findPath(localPos.x, localPos.y, targetLocalPos.x, targetLocalPos.y);
+      if (result.found && result.path.length > 0) {
+        const globalPath = result.path.map((p) => {
+          const global = cluster.subMap.localToGlobal(p.x, p.y);
+          return global.y * this.mapWidth + global.x;
+        });
+        tempNode.edges.push({
+          targetNodeId: existingNode.id,
+          cost: result.cost,
+          isInterEdge: false,
+          innerPath: globalPath
+        });
+        existingNode.edges.push({
+          targetNodeId: tempNode.id,
+          cost: result.cost,
+          isInterEdge: false,
+          innerPath: [
+            ...globalPath
+          ].reverse()
+        });
+      }
+    }
+    return tempNode;
+  }
+  /**
+   * @zh 移除临时节点
+   * @en Remove temporary node
+   */
+  removeTempNode(node, cluster) {
+    for (const existingNodeId of cluster.nodeIds) {
+      if (existingNodeId === node.id) continue;
+      const existingNode = this.abstractNodes.get(existingNodeId);
+      if (existingNode) {
+        existingNode.edges = existingNode.edges.filter((e) => e.targetNodeId !== node.id);
+      }
+    }
+    cluster.removeNodeId(node.id);
+    this.abstractNodes.delete(node.id);
+  }
+  /**
+   * @zh 在抽象图上进行 A* 搜索
+   * @en Perform A* search on abstract graph
+   */
+  abstractSearch(startNode, endNode, opts) {
+    const openList = new IndexedBinaryHeap((a, b) => a.f - b.f);
+    const nodeMap = /* @__PURE__ */ new Map();
+    const endPosition = endNode.position;
+    const h = this.heuristic(startNode.position, endPosition) * opts.heuristicWeight;
+    const startSearchNode = {
+      node: startNode,
+      g: 0,
+      h,
+      f: h,
+      parent: null,
+      closed: false,
+      opened: true,
+      heapIndex: -1
+    };
+    openList.push(startSearchNode);
+    nodeMap.set(startNode.id, startSearchNode);
+    let nodesSearched = 0;
+    while (!openList.isEmpty && nodesSearched < opts.maxNodes) {
+      const current = openList.pop();
+      current.closed = true;
+      nodesSearched++;
+      if (current.node.id === endNode.id) {
+        return this.reconstructPath(current);
+      }
+      for (const edge of current.node.edges) {
+        let neighbor = nodeMap.get(edge.targetNodeId);
+        if (!neighbor) {
+          const neighborNode = this.abstractNodes.get(edge.targetNodeId);
+          if (!neighborNode) continue;
+          const nh = this.heuristic(neighborNode.position, endPosition) * opts.heuristicWeight;
+          neighbor = {
+            node: neighborNode,
+            g: Infinity,
+            h: nh,
+            f: Infinity,
+            parent: null,
+            closed: false,
+            opened: false,
+            heapIndex: -1
+          };
+          nodeMap.set(edge.targetNodeId, neighbor);
+        }
+        if (neighbor.closed) continue;
+        const tentativeG = current.g + edge.cost;
+        if (!neighbor.opened) {
+          neighbor.g = tentativeG;
+          neighbor.f = tentativeG + neighbor.h;
+          neighbor.parent = current;
+          neighbor.opened = true;
+          openList.push(neighbor);
+        } else if (tentativeG < neighbor.g) {
+          neighbor.g = tentativeG;
+          neighbor.f = tentativeG + neighbor.h;
+          neighbor.parent = current;
+          openList.update(neighbor);
+        }
+      }
+    }
+    return null;
+  }
+  /**
+   * @zh 重建抽象路径
+   * @en Reconstruct abstract path
+   */
+  reconstructPath(endNode) {
+    const path = [];
+    let current = endNode;
+    while (current) {
+      path.unshift(current.node);
+      current = current.parent;
+    }
+    return path;
+  }
+  /**
+   * @zh 细化抽象路径为具体路径
+   * @en Refine abstract path to concrete path
+   */
+  refinePath(abstractPath, startX, startY, endX, endY, opts) {
+    if (abstractPath.length === 0) {
+      return EMPTY_PATH_RESULT;
+    }
+    const fullPath = [];
+    let totalCost = 0;
+    let nodesSearched = abstractPath.length;
+    for (let i = 0; i < abstractPath.length - 1; i++) {
+      const fromNode = abstractPath[i];
+      const toNode = abstractPath[i + 1];
+      const edge = fromNode.edges.find((e) => e.targetNodeId === toNode.id);
+      if (!edge) {
+        const segResult = this.findLocalPath(fromNode.position.x, fromNode.position.y, toNode.position.x, toNode.position.y, opts);
+        if (segResult.found) {
+          this.appendPath(fullPath, segResult.path);
+          totalCost += segResult.cost;
+          nodesSearched += segResult.nodesSearched;
+        }
+      } else if (edge.isInterEdge) {
+        if (fullPath.length === 0 || fullPath[fullPath.length - 1].x !== fromNode.position.x || fullPath[fullPath.length - 1].y !== fromNode.position.y) {
+          fullPath.push({
+            x: fromNode.position.x,
+            y: fromNode.position.y
+          });
+        }
+        fullPath.push({
+          x: toNode.position.x,
+          y: toNode.position.y
+        });
+        totalCost += edge.cost;
+      } else if (edge.innerPath && edge.innerPath.length > 0) {
+        const concretePath = edge.innerPath.map((id) => ({
+          x: id % this.mapWidth,
+          y: Math.floor(id / this.mapWidth)
+        }));
+        this.appendPath(fullPath, concretePath);
+        totalCost += edge.cost;
+      } else {
+        const computed = this.computeIntraEdgePath(fromNode, toNode, edge);
+        if (computed && computed.path.length > 0) {
+          const concretePath = computed.path.map((id) => ({
+            x: id % this.mapWidth,
+            y: Math.floor(id / this.mapWidth)
+          }));
+          this.appendPath(fullPath, concretePath);
+          totalCost += computed.cost;
+        } else {
+          const segResult = this.findLocalPath(fromNode.position.x, fromNode.position.y, toNode.position.x, toNode.position.y, opts);
+          if (segResult.found) {
+            this.appendPath(fullPath, segResult.path);
+            totalCost += segResult.cost;
+            nodesSearched += segResult.nodesSearched;
+          }
+        }
+      }
+    }
+    if (fullPath.length > 0 && (fullPath[0].x !== startX || fullPath[0].y !== startY)) {
+      const firstPoint = fullPath[0];
+      if (Math.abs(firstPoint.x - startX) <= 1 && Math.abs(firstPoint.y - startY) <= 1) {
+        fullPath.unshift({
+          x: startX,
+          y: startY
+        });
+      } else {
+        const segResult = this.findLocalPath(startX, startY, firstPoint.x, firstPoint.y, opts);
+        if (segResult.found) {
+          fullPath.splice(0, 0, ...segResult.path.slice(0, -1));
+          totalCost += segResult.cost;
+        }
+      }
+    }
+    if (fullPath.length > 0) {
+      const lastPoint = fullPath[fullPath.length - 1];
+      if (lastPoint.x !== endX || lastPoint.y !== endY) {
+        if (Math.abs(lastPoint.x - endX) <= 1 && Math.abs(lastPoint.y - endY) <= 1) {
+          fullPath.push({
+            x: endX,
+            y: endY
+          });
+        } else {
+          const segResult = this.findLocalPath(lastPoint.x, lastPoint.y, endX, endY, opts);
+          if (segResult.found) {
+            fullPath.push(...segResult.path.slice(1));
+            totalCost += segResult.cost;
+          }
+        }
+      }
+    }
+    return {
+      found: fullPath.length > 0,
+      path: fullPath,
+      cost: totalCost,
+      nodesSearched
+    };
+  }
+  /**
+   * @zh 追加路径（避免重复点）
+   * @en Append path (avoid duplicate points)
+   */
+  appendPath(fullPath, segment) {
+    if (segment.length === 0) return;
+    let startIdx = 0;
+    if (fullPath.length > 0) {
+      const last = fullPath[fullPath.length - 1];
+      if (last.x === segment[0].x && last.y === segment[0].y) {
+        startIdx = 1;
+      }
+    }
+    for (let i = startIdx; i < segment.length; i++) {
+      fullPath.push({
+        x: segment[i].x,
+        y: segment[i].y
+      });
+    }
+  }
+  /**
+   * @zh 局部寻路
+   * @en Local pathfinding
+   */
+  findLocalPath(startX, startY, endX, endY, opts) {
+    return this.localPathfinder.findPath(startX, startY, endX, endY, opts);
+  }
+  /**
+   * @zh 启发式函数（Octile 距离）
+   * @en Heuristic function (Octile distance)
+   */
+  heuristic(a, b) {
+    const dx = Math.abs(a.x - b.x);
+    const dy = Math.abs(a.y - b.y);
+    return dx + dy + (Math.SQRT2 - 2) * Math.min(dx, dy);
+  }
+};
+__name(_HPAPathfinder, "HPAPathfinder");
+var HPAPathfinder = _HPAPathfinder;
+function createHPAPathfinder(map, config) {
+  return new HPAPathfinder(map, config);
+}
+__name(createHPAPathfinder, "createHPAPathfinder");
+
+// src/interfaces/IPathPlanner.ts
+var EMPTY_PLAN_RESULT = {
+  found: false,
+  path: [],
+  cost: 0,
+  nodesSearched: 0
+};
+var PathPlanState = /* @__PURE__ */ (function(PathPlanState2) {
+  PathPlanState2["Idle"] = "idle";
+  PathPlanState2["InProgress"] = "in_progress";
+  PathPlanState2["Completed"] = "completed";
+  PathPlanState2["Failed"] = "failed";
+  PathPlanState2["Cancelled"] = "cancelled";
+  return PathPlanState2;
+})({});
+function isIncrementalPlanner(planner) {
+  return "supportsIncremental" in planner && planner.supportsIncremental === true;
+}
+__name(isIncrementalPlanner, "isIncrementalPlanner");
+
+// src/interfaces/ICollisionResolver.ts
+var EMPTY_COLLISION_RESULT = {
+  collided: false,
+  penetration: 0,
+  normal: {
+    x: 0,
+    y: 0
+  },
+  closestPoint: {
+    x: 0,
+    y: 0
+  }
+};
+
+// src/interfaces/IFlowController.ts
+var PassPermission = /* @__PURE__ */ (function(PassPermission2) {
+  PassPermission2["Proceed"] = "proceed";
+  PassPermission2["Wait"] = "wait";
+  PassPermission2["Yield"] = "yield";
+  return PassPermission2;
+})({});
+var DEFAULT_FLOW_CONTROLLER_CONFIG = {
+  detectionRadius: 3,
+  minAgentsForCongestion: 3,
+  defaultCapacity: 2,
+  waitPointDistance: 1.5,
+  yieldSpeedMultiplier: 0.3
+};
+
+// src/adapters/NavMeshPathPlannerAdapter.ts
+var _NavMeshPathPlannerAdapter = class _NavMeshPathPlannerAdapter {
+  constructor(navMesh) {
+    __publicField(this, "navMesh");
+    __publicField(this, "type", "navmesh");
+    this.navMesh = navMesh;
+  }
+  findPath(start, end, options) {
+    const result = this.navMesh.findPathWithObstacles(start.x, start.y, end.x, end.y, options ? {
+      agentRadius: options.agentRadius
+    } : void 0);
+    if (!result.found) {
+      return EMPTY_PLAN_RESULT;
+    }
+    return {
+      found: true,
+      path: result.path.map((p) => ({
+        x: p.x,
+        y: p.y
+      })),
+      cost: result.cost,
+      nodesSearched: result.nodesSearched
+    };
+  }
+  isWalkable(position) {
+    return this.navMesh.isWalkable(position.x, position.y);
+  }
+  getNearestWalkable(position) {
+    const polygon = this.navMesh.findPolygonAt(position.x, position.y);
+    if (polygon) {
+      return {
+        x: position.x,
+        y: position.y
+      };
+    }
+    const polygons = this.navMesh.getPolygons();
+    if (polygons.length === 0) {
+      return null;
+    }
+    let nearestDist = Infinity;
+    let nearestPoint = null;
+    for (const poly of polygons) {
+      const dx = poly.center.x - position.x;
+      const dy = poly.center.y - position.y;
+      const dist = dx * dx + dy * dy;
+      if (dist < nearestDist) {
+        nearestDist = dist;
+        nearestPoint = {
+          x: poly.center.x,
+          y: poly.center.y
+        };
+      }
+    }
+    return nearestPoint;
+  }
+  clear() {
+  }
+  dispose() {
+  }
+};
+__name(_NavMeshPathPlannerAdapter, "NavMeshPathPlannerAdapter");
+var NavMeshPathPlannerAdapter = _NavMeshPathPlannerAdapter;
+function createNavMeshPathPlanner(navMesh) {
+  return new NavMeshPathPlannerAdapter(navMesh);
+}
+__name(createNavMeshPathPlanner, "createNavMeshPathPlanner");
+
+// src/adapters/GridPathfinderAdapter.ts
+var _GridPathfinderAdapter = class _GridPathfinderAdapter {
+  constructor(pathfinder, map, options, type = "grid", config) {
+    __publicField(this, "pathfinder");
+    __publicField(this, "map");
+    __publicField(this, "options");
+    __publicField(this, "type");
+    __publicField(this, "cellSize");
+    this.pathfinder = pathfinder;
+    this.map = map;
+    this.options = options;
+    this.type = type;
+    this.cellSize = config?.cellSize ?? 1;
+  }
+  /**
+   * @zh 像素坐标转网格坐标
+   * @en Convert pixel coordinate to grid coordinate
+   */
+  toGridCoord(pixel) {
+    return Math.floor(pixel / this.cellSize);
+  }
+  /**
+   * @zh 网格坐标转像素坐标（单元格中心）
+   * @en Convert grid coordinate to pixel coordinate (cell center)
+   */
+  toPixelCoord(grid) {
+    return grid * this.cellSize + this.cellSize * 0.5;
+  }
+  findPath(start, end) {
+    const startGridX = this.toGridCoord(start.x);
+    const startGridY = this.toGridCoord(start.y);
+    const endGridX = this.toGridCoord(end.x);
+    const endGridY = this.toGridCoord(end.y);
+    const result = this.pathfinder.findPath(startGridX, startGridY, endGridX, endGridY, this.options);
+    if (!result.found) {
+      return EMPTY_PLAN_RESULT;
+    }
+    return {
+      found: true,
+      path: result.path.map((p) => ({
+        x: this.toPixelCoord(p.x),
+        y: this.toPixelCoord(p.y)
+      })),
+      cost: result.cost,
+      nodesSearched: result.nodesSearched
+    };
+  }
+  isWalkable(position) {
+    return this.map.isWalkable(this.toGridCoord(position.x), this.toGridCoord(position.y));
+  }
+  getNearestWalkable(position) {
+    const x = this.toGridCoord(position.x);
+    const y = this.toGridCoord(position.y);
+    if (this.map.isWalkable(x, y)) {
+      return {
+        x: this.toPixelCoord(x),
+        y: this.toPixelCoord(y)
+      };
+    }
+    for (let radius = 1; radius <= 10; radius++) {
+      for (let dx = -radius; dx <= radius; dx++) {
+        for (let dy = -radius; dy <= radius; dy++) {
+          if (Math.abs(dx) === radius || Math.abs(dy) === radius) {
+            if (this.map.isWalkable(x + dx, y + dy)) {
+              return {
+                x: this.toPixelCoord(x + dx),
+                y: this.toPixelCoord(y + dy)
+              };
+            }
+          }
+        }
+      }
+    }
+    return null;
+  }
+  clear() {
+    this.pathfinder.clear();
+  }
+  dispose() {
+    this.pathfinder.clear();
+  }
+};
+__name(_GridPathfinderAdapter, "GridPathfinderAdapter");
+var GridPathfinderAdapter = _GridPathfinderAdapter;
+function createAStarPlanner(map, options, config) {
+  return new GridPathfinderAdapter(new AStarPathfinder(map), map, options, "astar", config);
+}
+__name(createAStarPlanner, "createAStarPlanner");
+function createJPSPlanner(map, options, config) {
+  return new GridPathfinderAdapter(new JPSPathfinder(map), map, options, "jps", config);
+}
+__name(createJPSPlanner, "createJPSPlanner");
+function createHPAPlanner(map, hpaConfig, options, adapterConfig) {
+  return new GridPathfinderAdapter(new HPAPathfinder(map, hpaConfig), map, options, "hpa", adapterConfig);
+}
+__name(createHPAPlanner, "createHPAPlanner");
+
+// src/adapters/IncrementalGridPathPlannerAdapter.ts
+function toPathPlanState(state) {
+  switch (state) {
+    case PathfindingState.Idle:
+      return PathPlanState.Idle;
+    case PathfindingState.InProgress:
+      return PathPlanState.InProgress;
+    case PathfindingState.Completed:
+      return PathPlanState.Completed;
+    case PathfindingState.Failed:
+      return PathPlanState.Failed;
+    case PathfindingState.Cancelled:
+      return PathPlanState.Cancelled;
+    default:
+      return PathPlanState.Idle;
+  }
+}
+__name(toPathPlanState, "toPathPlanState");
+var _IncrementalGridPathPlannerAdapter = class _IncrementalGridPathPlannerAdapter {
+  constructor(map, options, config) {
+    __publicField(this, "type", "incremental-astar");
+    __publicField(this, "supportsIncremental", true);
+    __publicField(this, "pathfinder");
+    __publicField(this, "map");
+    __publicField(this, "options");
+    __publicField(this, "cellSize");
+    /**
+     * @zh 活跃请求 ID 集合（用于跟踪）
+     * @en Active request IDs set (for tracking)
+     */
+    __publicField(this, "activeRequests", /* @__PURE__ */ new Set());
+    /**
+     * @zh 每个请求的累计搜索节点数
+     * @en Accumulated searched nodes per request
+     */
+    __publicField(this, "requestTotalNodes", /* @__PURE__ */ new Map());
+    this.map = map;
+    this.options = options;
+    this.cellSize = config?.cellSize ?? 1;
+    this.pathfinder = new IncrementalAStarPathfinder(map, config);
+  }
+  /**
+   * @zh 像素坐标转网格坐标
+   * @en Convert pixel coordinate to grid coordinate
+   */
+  toGridCoord(pixel) {
+    return Math.floor(pixel / this.cellSize);
+  }
+  /**
+   * @zh 网格坐标转像素坐标（单元格中心）
+   * @en Convert grid coordinate to pixel coordinate (cell center)
+   */
+  toPixelCoord(grid) {
+    return grid * this.cellSize + this.cellSize * 0.5;
+  }
+  // =========================================================================
+  // IPathPlanner 基础接口 | IPathPlanner Base Interface
+  // =========================================================================
+  findPath(start, end, options) {
+    const startGridX = this.toGridCoord(start.x);
+    const startGridY = this.toGridCoord(start.y);
+    const endGridX = this.toGridCoord(end.x);
+    const endGridY = this.toGridCoord(end.y);
+    const request = this.pathfinder.requestPath(startGridX, startGridY, endGridX, endGridY, this.options);
+    let progress = this.pathfinder.step(request.id, 1e5);
+    while (progress.state === PathfindingState.InProgress) {
+      progress = this.pathfinder.step(request.id, 1e5);
+    }
+    const result = this.pathfinder.getResult(request.id);
+    this.pathfinder.cleanup(request.id);
+    if (!result || !result.found) {
+      return EMPTY_PLAN_RESULT;
+    }
+    return {
+      found: true,
+      path: result.path.map((p) => ({
+        x: this.toPixelCoord(p.x),
+        y: this.toPixelCoord(p.y)
+      })),
+      cost: result.cost,
+      nodesSearched: result.nodesSearched
+    };
+  }
+  isWalkable(position) {
+    return this.map.isWalkable(this.toGridCoord(position.x), this.toGridCoord(position.y));
+  }
+  getNearestWalkable(position) {
+    const x = this.toGridCoord(position.x);
+    const y = this.toGridCoord(position.y);
+    if (this.map.isWalkable(x, y)) {
+      return {
+        x: this.toPixelCoord(x),
+        y: this.toPixelCoord(y)
+      };
+    }
+    for (let radius = 1; radius <= 10; radius++) {
+      for (let dx = -radius; dx <= radius; dx++) {
+        for (let dy = -radius; dy <= radius; dy++) {
+          if (Math.abs(dx) === radius || Math.abs(dy) === radius) {
+            if (this.map.isWalkable(x + dx, y + dy)) {
+              return {
+                x: this.toPixelCoord(x + dx),
+                y: this.toPixelCoord(y + dy)
+              };
+            }
+          }
+        }
+      }
+    }
+    return null;
+  }
+  clear() {
+    this.pathfinder.clear();
+    this.activeRequests.clear();
+    this.requestTotalNodes.clear();
+  }
+  dispose() {
+    this.pathfinder.clear();
+    this.activeRequests.clear();
+    this.requestTotalNodes.clear();
+  }
+  // =========================================================================
+  // IIncrementalPathPlanner 增量接口 | IIncrementalPathPlanner Incremental Interface
+  // =========================================================================
+  requestPath(start, end, options) {
+    const startGridX = this.toGridCoord(start.x);
+    const startGridY = this.toGridCoord(start.y);
+    const endGridX = this.toGridCoord(end.x);
+    const endGridY = this.toGridCoord(end.y);
+    const request = this.pathfinder.requestPath(startGridX, startGridY, endGridX, endGridY, this.options);
+    this.activeRequests.add(request.id);
+    this.requestTotalNodes.set(request.id, 0);
+    return {
+      id: request.id,
+      state: PathPlanState.InProgress
+    };
+  }
+  step(requestId, iterations) {
+    const progress = this.pathfinder.step(requestId, iterations);
+    const prevTotal = this.requestTotalNodes.get(requestId) ?? 0;
+    const newTotal = prevTotal + progress.nodesSearched;
+    this.requestTotalNodes.set(requestId, newTotal);
+    return {
+      state: toPathPlanState(progress.state),
+      estimatedProgress: progress.estimatedProgress,
+      nodesSearched: progress.nodesSearched,
+      totalNodesSearched: newTotal
+    };
+  }
+  getResult(requestId) {
+    const result = this.pathfinder.getResult(requestId);
+    if (!result) {
+      return null;
+    }
+    if (!result.found) {
+      return EMPTY_PLAN_RESULT;
+    }
+    return {
+      found: true,
+      path: result.path.map((p) => ({
+        x: this.toPixelCoord(p.x),
+        y: this.toPixelCoord(p.y)
+      })),
+      cost: result.cost,
+      nodesSearched: result.nodesSearched
+    };
+  }
+  cancel(requestId) {
+    this.pathfinder.cancel(requestId);
+  }
+  cleanup(requestId) {
+    this.pathfinder.cleanup(requestId);
+    this.activeRequests.delete(requestId);
+    this.requestTotalNodes.delete(requestId);
+  }
+  getActiveRequestCount() {
+    return this.activeRequests.size;
+  }
+};
+__name(_IncrementalGridPathPlannerAdapter, "IncrementalGridPathPlannerAdapter");
+var IncrementalGridPathPlannerAdapter = _IncrementalGridPathPlannerAdapter;
+function createIncrementalAStarPlanner(map, options, config) {
+  return new IncrementalGridPathPlannerAdapter(map, options, config);
+}
+__name(createIncrementalAStarPlanner, "createIncrementalAStarPlanner");
+
+// src/adapters/ORCALocalAvoidanceAdapter.ts
+var DEFAULT_ORCA_PARAMS = {
+  neighborDist: 15,
+  maxNeighbors: 10,
+  timeHorizon: 2,
+  timeHorizonObst: 1
+};
+var _ORCALocalAvoidanceAdapter = class _ORCALocalAvoidanceAdapter {
+  constructor(config) {
+    __publicField(this, "type", "orca");
+    __publicField(this, "solver");
+    __publicField(this, "kdTree");
+    __publicField(this, "defaultParams");
+    this.solver = createORCASolver(config);
+    this.kdTree = createKDTree();
+    this.defaultParams = {
+      ...DEFAULT_ORCA_PARAMS
+    };
+  }
+  /**
+   * @zh 设置默认 ORCA 参数
+   * @en Set default ORCA parameters
+   *
+   * @param params - @zh 参数 @en Parameters
+   */
+  setDefaultParams(params) {
+    Object.assign(this.defaultParams, params);
+  }
+  /**
+   * @zh 获取默认 ORCA 参数
+   * @en Get default ORCA parameters
+   */
+  getDefaultParams() {
+    return this.defaultParams;
+  }
+  computeAvoidanceVelocity(agent, neighbors, obstacles, deltaTime) {
+    const orcaAgent = this.toORCAAgent(agent);
+    const orcaNeighbors = neighbors.map((n) => this.toORCAAgent(n));
+    const orcaObstacles = obstacles.map((o) => this.toORCAObstacle(o));
+    const result = this.solver.computeNewVelocityWithResult(orcaAgent, orcaNeighbors, orcaObstacles, deltaTime);
+    return {
+      velocity: result.velocity,
+      feasible: result.feasible
+    };
+  }
+  computeBatchAvoidance(agents, obstacles, deltaTime) {
+    const results = /* @__PURE__ */ new Map();
+    const orcaAgents = agents.map((a) => this.toORCAAgent(a));
+    const orcaObstacles = obstacles.map((o) => this.toORCAObstacle(o));
+    this.kdTree.build(orcaAgents);
+    for (let i = 0; i < agents.length; i++) {
+      const agent = orcaAgents[i];
+      const neighborResults = this.kdTree.queryNeighbors(agent.position, agent.neighborDist, agent.maxNeighbors, agent.id);
+      const result = this.solver.computeNewVelocityWithResult(agent, neighborResults.map((r) => r.agent), orcaObstacles, deltaTime);
+      results.set(agents[i].id, {
+        velocity: result.velocity,
+        feasible: result.feasible
+      });
+    }
+    return results;
+  }
+  dispose() {
+    this.kdTree.clear();
+  }
+  toORCAAgent(agent) {
+    return {
+      id: agent.id,
+      position: {
+        x: agent.position.x,
+        y: agent.position.y
+      },
+      velocity: {
+        x: agent.velocity.x,
+        y: agent.velocity.y
+      },
+      preferredVelocity: {
+        x: agent.preferredVelocity.x,
+        y: agent.preferredVelocity.y
+      },
+      radius: agent.radius,
+      maxSpeed: agent.maxSpeed,
+      neighborDist: this.defaultParams.neighborDist,
+      maxNeighbors: this.defaultParams.maxNeighbors,
+      timeHorizon: this.defaultParams.timeHorizon,
+      timeHorizonObst: this.defaultParams.timeHorizonObst
+    };
+  }
+  toORCAObstacle(obstacle) {
+    return {
+      vertices: obstacle.vertices.map((v) => ({
+        x: v.x,
+        y: v.y
+      }))
+    };
+  }
+};
+__name(_ORCALocalAvoidanceAdapter, "ORCALocalAvoidanceAdapter");
+var ORCALocalAvoidanceAdapter = _ORCALocalAvoidanceAdapter;
+function createORCAAvoidance(config) {
+  return new ORCALocalAvoidanceAdapter(config);
+}
+__name(createORCAAvoidance, "createORCAAvoidance");
+
+// src/adapters/CollisionResolverAdapter.ts
+var _CollisionResolverAdapter = class _CollisionResolverAdapter {
+  constructor(config) {
+    __publicField(this, "type", "default");
+    __publicField(this, "resolver");
+    this.resolver = createCollisionResolver(config);
+  }
+  detectCollision(position, radius, obstacles) {
+    if (obstacles.length === 0) {
+      return EMPTY_COLLISION_RESULT;
+    }
+    const result = this.resolver.detectCollisions(position, radius, obstacles.map((o) => ({
+      vertices: o.vertices.map((v) => ({
+        x: v.x,
+        y: v.y
+      }))
+    })));
+    return {
+      collided: result.collided,
+      penetration: result.penetration,
+      normal: {
+        x: result.normal.x,
+        y: result.normal.y
+      },
+      closestPoint: {
+        x: result.closestPoint.x,
+        y: result.closestPoint.y
+      }
+    };
+  }
+  resolveCollision(position, radius, obstacles) {
+    if (obstacles.length === 0) {
+      return {
+        x: position.x,
+        y: position.y
+      };
+    }
+    const resolved = this.resolver.resolveCollision(position, radius, obstacles.map((o) => ({
+      vertices: o.vertices.map((v) => ({
+        x: v.x,
+        y: v.y
+      }))
+    })));
+    return {
+      x: resolved.x,
+      y: resolved.y
+    };
+  }
+  validateVelocity(position, velocity, radius, obstacles, deltaTime) {
+    if (obstacles.length === 0) {
+      return {
+        x: velocity.x,
+        y: velocity.y
+      };
+    }
+    const result = this.resolver.validateVelocity(position, velocity, radius, obstacles.map((o) => ({
+      vertices: o.vertices.map((v) => ({
+        x: v.x,
+        y: v.y
+      }))
+    })), deltaTime);
+    return {
+      x: result.x,
+      y: result.y
+    };
+  }
+  detectAgentCollision(posA, radiusA, posB, radiusB) {
+    const result = this.resolver.detectAgentCollision(posA, radiusA, posB, radiusB);
+    return {
+      collided: result.collided,
+      penetration: result.penetration,
+      normal: {
+        x: result.normal.x,
+        y: result.normal.y
+      },
+      closestPoint: {
+        x: result.closestPoint.x,
+        y: result.closestPoint.y
+      }
+    };
+  }
+  dispose() {
+  }
+};
+__name(_CollisionResolverAdapter, "CollisionResolverAdapter");
+var CollisionResolverAdapter = _CollisionResolverAdapter;
+function createDefaultCollisionResolver(config) {
+  return new CollisionResolverAdapter(config);
+}
+__name(createDefaultCollisionResolver, "createDefaultCollisionResolver");
+
+// src/adapters/FlowController.ts
+var _FlowController = class _FlowController {
+  constructor(config = {}) {
+    __publicField(this, "type", "fifo-priority");
+    __publicField(this, "config");
+    __publicField(this, "zoneStates", /* @__PURE__ */ new Map());
+    __publicField(this, "agentZoneMap", /* @__PURE__ */ new Map());
+    __publicField(this, "agentResults", /* @__PURE__ */ new Map());
+    __publicField(this, "nextZoneId", 1);
+    __publicField(this, "currentTime", 0);
+    this.config = {
+      ...DEFAULT_FLOW_CONTROLLER_CONFIG,
+      ...config
+    };
+  }
+  /**
+   * @zh 更新流量控制状态
+   * @en Update flow control state
+   */
+  update(agents, deltaTime) {
+    this.currentTime += deltaTime;
+    this.agentResults.clear();
+    this.detectDynamicCongestion(agents);
+    this.updateZoneQueues(agents);
+    this.computeFlowControlResults(agents);
+    this.cleanupEmptyZones();
+  }
+  /**
+   * @zh 获取代理的流量控制结果
+   * @en Get flow control result for an agent
+   */
+  getFlowControl(agentId) {
+    return this.agentResults.get(agentId) ?? {
+      permission: PassPermission.Proceed,
+      waitPosition: null,
+      speedMultiplier: 1,
+      zone: null,
+      queuePosition: 0
+    };
+  }
+  /**
+   * @zh 获取所有拥堵区域
+   * @en Get all congestion zones
+   */
+  getCongestionZones() {
+    return Array.from(this.zoneStates.values()).map((s) => s.zone);
+  }
+  /**
+   * @zh 添加静态拥堵区域
+   * @en Add static congestion zone
+   */
+  addStaticZone(center, radius, capacity) {
+    const zoneId = this.nextZoneId++;
+    const zone = {
+      id: zoneId,
+      center: {
+        x: center.x,
+        y: center.y
+      },
+      radius,
+      agentIds: [],
+      capacity,
+      congestionLevel: 0
+    };
+    this.zoneStates.set(zoneId, {
+      zone,
+      queue: [],
+      passingAgents: /* @__PURE__ */ new Set(),
+      isStatic: true
+    });
+    return zoneId;
+  }
+  /**
+   * @zh 移除静态拥堵区域
+   * @en Remove static congestion zone
+   */
+  removeStaticZone(zoneId) {
+    const state = this.zoneStates.get(zoneId);
+    if (state?.isStatic) {
+      for (const agentId of state.zone.agentIds) {
+        this.agentZoneMap.delete(agentId);
+      }
+      this.zoneStates.delete(zoneId);
+    }
+  }
+  /**
+   * @zh 清除所有状态
+   * @en Clear all state
+   */
+  clear() {
+    this.zoneStates.clear();
+    this.agentZoneMap.clear();
+    this.agentResults.clear();
+    this.currentTime = 0;
+  }
+  /**
+   * @zh 释放资源
+   * @en Dispose resources
+   */
+  dispose() {
+    this.clear();
+  }
+  // =========================================================================
+  // 私有方法 | Private Methods
+  // =========================================================================
+  /**
+   * @zh 检测动态拥堵区域
+   * @en Detect dynamic congestion zones
+   */
+  detectDynamicCongestion(agents) {
+    const clusters = this.clusterAgents(agents);
+    for (const cluster of clusters) {
+      if (cluster.length < this.config.minAgentsForCongestion) {
+        continue;
+      }
+      const center = this.computeClusterCenter(cluster);
+      const radius = this.computeClusterRadius(cluster, center);
+      const existingZone = this.findZoneContaining(center);
+      if (existingZone && !existingZone.isStatic) {
+        this.updateDynamicZone(existingZone, cluster, center, radius);
+      } else if (!existingZone) {
+        this.createDynamicZone(cluster, center, radius);
+      }
+    }
+  }
+  /**
+   * @zh 聚类代理
+   * @en Cluster agents
+   */
+  clusterAgents(agents) {
+    const clusters = [];
+    const visited = /* @__PURE__ */ new Set();
+    const detectionRadiusSq = this.config.detectionRadius * this.config.detectionRadius;
+    for (const agent of agents) {
+      if (visited.has(agent.id) || !agent.destination) {
+        continue;
+      }
+      const cluster = [
+        agent
+      ];
+      visited.add(agent.id);
+      const queue = [
+        agent
+      ];
+      while (queue.length > 0) {
+        const current = queue.shift();
+        for (const other of agents) {
+          if (visited.has(other.id) || !other.destination) {
+            continue;
+          }
+          const dx = other.position.x - current.position.x;
+          const dy = other.position.y - current.position.y;
+          const distSq = dx * dx + dy * dy;
+          if (distSq <= detectionRadiusSq) {
+            visited.add(other.id);
+            cluster.push(other);
+            queue.push(other);
+          }
+        }
+      }
+      if (cluster.length >= this.config.minAgentsForCongestion) {
+        clusters.push(cluster);
+      }
+    }
+    return clusters;
+  }
+  /**
+   * @zh 计算聚类中心
+   * @en Compute cluster center
+   */
+  computeClusterCenter(cluster) {
+    let sumX = 0, sumY = 0;
+    for (const agent of cluster) {
+      sumX += agent.position.x;
+      sumY += agent.position.y;
+    }
+    return {
+      x: sumX / cluster.length,
+      y: sumY / cluster.length
+    };
+  }
+  /**
+   * @zh 计算聚类半径
+   * @en Compute cluster radius
+   */
+  computeClusterRadius(cluster, center) {
+    let maxDistSq = 0;
+    for (const agent of cluster) {
+      const dx = agent.position.x - center.x;
+      const dy = agent.position.y - center.y;
+      const distSq = dx * dx + dy * dy;
+      maxDistSq = Math.max(maxDistSq, distSq);
+    }
+    return Math.sqrt(maxDistSq) + this.config.detectionRadius * 0.5;
+  }
+  /**
+   * @zh 查找包含点的区域
+   * @en Find zone containing point
+   */
+  findZoneContaining(point) {
+    for (const state of this.zoneStates.values()) {
+      const dx = point.x - state.zone.center.x;
+      const dy = point.y - state.zone.center.y;
+      const distSq = dx * dx + dy * dy;
+      if (distSq <= state.zone.radius * state.zone.radius) {
+        return state;
+      }
+    }
+    return null;
+  }
+  /**
+   * @zh 更新动态区域
+   * @en Update dynamic zone
+   */
+  updateDynamicZone(state, cluster, center, radius) {
+    state.zone.center = center;
+    state.zone.radius = Math.max(state.zone.radius, radius);
+    state.zone.agentIds = cluster.map((a) => a.id);
+    state.zone.congestionLevel = Math.min(1, cluster.length / (state.zone.capacity * 2));
+  }
+  /**
+   * @zh 创建动态区域
+   * @en Create dynamic zone
+   */
+  createDynamicZone(cluster, center, radius) {
+    const zoneId = this.nextZoneId++;
+    const capacityEstimate = Math.max(this.config.defaultCapacity, Math.floor(Math.PI * radius * radius / (Math.PI * 0.5 * 0.5 * 4)));
+    const zone = {
+      id: zoneId,
+      center,
+      radius,
+      agentIds: cluster.map((a) => a.id),
+      capacity: capacityEstimate,
+      congestionLevel: Math.min(1, cluster.length / (capacityEstimate * 2))
+    };
+    this.zoneStates.set(zoneId, {
+      zone,
+      queue: [],
+      passingAgents: /* @__PURE__ */ new Set(),
+      isStatic: false
+    });
+  }
+  /**
+   * @zh 更新区域队列
+   * @en Update zone queues
+   */
+  updateZoneQueues(agents) {
+    const agentMap = new Map(agents.map((a) => [
+      a.id,
+      a
+    ]));
+    for (const state of this.zoneStates.values()) {
+      const zone = state.zone;
+      const newAgentIds = [];
+      for (const agent of agents) {
+        if (!agent.destination) continue;
+        const dx = agent.position.x - zone.center.x;
+        const dy = agent.position.y - zone.center.y;
+        const distSq = dx * dx + dy * dy;
+        const expandedRadius = zone.radius + this.config.waitPointDistance;
+        if (distSq <= expandedRadius * expandedRadius) {
+          newAgentIds.push(agent.id);
+          const existingEntry = state.queue.find((e) => e.agentId === agent.id);
+          if (!existingEntry) {
+            state.queue.push({
+              agentId: agent.id,
+              enterTime: agent.enterTime ?? this.currentTime,
+              priority: agent.priority
+            });
+            this.agentZoneMap.set(agent.id, zone.id);
+          }
+        }
+      }
+      state.queue = state.queue.filter((entry) => {
+        const agent = agentMap.get(entry.agentId);
+        if (!agent || !agent.destination) {
+          state.passingAgents.delete(entry.agentId);
+          this.agentZoneMap.delete(entry.agentId);
+          return false;
+        }
+        const dx = agent.position.x - zone.center.x;
+        const dy = agent.position.y - zone.center.y;
+        const distSq = dx * dx + dy * dy;
+        const expandedRadius = zone.radius + this.config.waitPointDistance * 2;
+        if (distSq > expandedRadius * expandedRadius) {
+          state.passingAgents.delete(entry.agentId);
+          this.agentZoneMap.delete(entry.agentId);
+          return false;
+        }
+        return true;
+      });
+      state.queue.sort((a, b) => {
+        if (a.priority !== b.priority) {
+          return a.priority - b.priority;
+        }
+        return a.enterTime - b.enterTime;
+      });
+      zone.agentIds = state.queue.map((e) => e.agentId);
+      zone.congestionLevel = Math.min(1, zone.agentIds.length / (zone.capacity * 2));
+    }
+  }
+  /**
+   * @zh 计算流量控制结果
+   * @en Compute flow control results
+   */
+  computeFlowControlResults(agents) {
+    const agentMap = new Map(agents.map((a) => [
+      a.id,
+      a
+    ]));
+    for (const state of this.zoneStates.values()) {
+      const zone = state.zone;
+      const capacity = zone.capacity;
+      let passingCount = 0;
+      for (const entry of state.queue) {
+        const agent = agentMap.get(entry.agentId);
+        if (!agent) continue;
+        const dx = agent.position.x - zone.center.x;
+        const dy = agent.position.y - zone.center.y;
+        const distSq = dx * dx + dy * dy;
+        const isInsideZone = distSq <= zone.radius * zone.radius;
+        const queuePosition = state.queue.findIndex((e) => e.agentId === entry.agentId);
+        if (passingCount < capacity) {
+          state.passingAgents.add(entry.agentId);
+          passingCount++;
+          const speedMult = isInsideZone && zone.congestionLevel > 0.5 ? 1 - (zone.congestionLevel - 0.5) : 1;
+          this.agentResults.set(entry.agentId, {
+            permission: PassPermission.Proceed,
+            waitPosition: null,
+            speedMultiplier: speedMult,
+            zone,
+            queuePosition
+          });
+        } else if (state.passingAgents.has(entry.agentId) && isInsideZone) {
+          this.agentResults.set(entry.agentId, {
+            permission: PassPermission.Yield,
+            waitPosition: null,
+            speedMultiplier: this.config.yieldSpeedMultiplier,
+            zone,
+            queuePosition
+          });
+        } else {
+          const waitPos = this.computeWaitPosition(agent, zone);
+          this.agentResults.set(entry.agentId, {
+            permission: PassPermission.Wait,
+            waitPosition: waitPos,
+            speedMultiplier: 0,
+            zone,
+            queuePosition
+          });
+        }
+      }
+    }
+  }
+  /**
+   * @zh 计算等待位置
+   * @en Compute wait position
+   */
+  computeWaitPosition(agent, zone) {
+    const dx = agent.position.x - zone.center.x;
+    const dy = agent.position.y - zone.center.y;
+    const dist = Math.sqrt(dx * dx + dy * dy);
+    if (dist < 1e-3) {
+      return {
+        x: zone.center.x + zone.radius + this.config.waitPointDistance,
+        y: zone.center.y
+      };
+    }
+    const dirX = dx / dist;
+    const dirY = dy / dist;
+    const waitDist = zone.radius + this.config.waitPointDistance;
+    return {
+      x: zone.center.x + dirX * waitDist,
+      y: zone.center.y + dirY * waitDist
+    };
+  }
+  /**
+   * @zh 清理空的动态区域
+   * @en Cleanup empty dynamic zones
+   */
+  cleanupEmptyZones() {
+    const toRemove = [];
+    for (const [zoneId, state] of this.zoneStates) {
+      if (!state.isStatic && state.queue.length === 0) {
+        toRemove.push(zoneId);
+      }
+    }
+    for (const zoneId of toRemove) {
+      this.zoneStates.delete(zoneId);
+    }
+  }
+};
+__name(_FlowController, "FlowController");
+var FlowController = _FlowController;
+function createFlowController(config) {
+  return new FlowController(config);
+}
+__name(createFlowController, "createFlowController");
+
+export {
+  createPoint,
+  EMPTY_PATH_RESULT,
+  manhattanDistance,
+  euclideanDistance,
+  chebyshevDistance,
+  octileDistance,
+  DEFAULT_PATHFINDING_OPTIONS,
+  BinaryHeap,
+  IndexedBinaryHeap,
+  AStarPathfinder,
+  createAStarPathfinder,
+  DEFAULT_PATH_CACHE_CONFIG,
+  PathCache,
+  createPathCache,
+  IncrementalAStarPathfinder,
+  createIncrementalAStarPathfinder,
+  JPSPathfinder,
+  createJPSPathfinder,
+  DEFAULT_HPA_CONFIG,
+  HPAPathfinder,
+  createHPAPathfinder,
+  EMPTY_PLAN_RESULT,
+  PathPlanState,
+  isIncrementalPlanner,
+  EMPTY_COLLISION_RESULT,
+  PassPermission,
+  DEFAULT_FLOW_CONTROLLER_CONFIG,
+  NavMeshPathPlannerAdapter,
+  createNavMeshPathPlanner,
+  GridPathfinderAdapter,
+  createAStarPlanner,
+  createJPSPlanner,
+  createHPAPlanner,
+  IncrementalGridPathPlannerAdapter,
+  createIncrementalAStarPlanner,
+  DEFAULT_ORCA_PARAMS,
+  ORCALocalAvoidanceAdapter,
+  createORCAAvoidance,
+  CollisionResolverAdapter,
+  createDefaultCollisionResolver,
+  FlowController,
+  createFlowController
+};
+//# sourceMappingURL=chunk-NIKT3PQC.js.map