@rxflow/manhattan 0.0.2-alpha.8 → 0.0.3

package/README.md

@@ -2,33 +2,237 @@
 
 Manhattan 路由算法，用于 ReactFlow 生成正交路径，支持障碍物避让。
 
+## 特性
+
+- **A* 寻路算法** - 高效的路径搜索，支持早期终止优化
+- **正交路径生成** - 生成符合 Manhattan 风格的直角路径
+- **障碍物避让** - 自动绕过节点障碍物
+- **四叉树优化** - 使用 QuadTree 加速空间查询
+- **自适应步长** - 根据节点密度和距离自动调整网格步长
+- **路径缓存** - LRU 缓存机制提升重复查询性能
+- **全局网格对齐** - 确保所有路径点对齐到全局网格
+- **圆角支持** - 可配置的路径转角圆角半径
+- **性能监控** - 内置性能指标收集和日志
+
 ## 安装
 
 ```bash
 npm install @rxflow/manhattan
 # or
 pnpm add @rxflow/manhattan
+yarn add @rxflow/manhattan
 ```
 
-## 使用
+## 基本使用
 
 ```tsx
 import { getManHattanPath } from '@rxflow/manhattan';
+import { useReactFlow } from '@xyflow/react';
+
+function CustomEdge({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, source, target }) {
+  const { getNodes } = useReactFlow();
+  const nodeLookup = new Map(getNodes().map(n => [n.id, n]));
+
+  const path = getManHattanPath({
+    sourceNodeId: source,
+    targetNodeId: target,
+    sourceX,
+    sourceY,
+    targetX,
+    targetY,
+    sourcePosition,
+    targetPosition,
+    nodeLookup,
+    options: {
+      step: 10,
+      borderRadius: 5,
+    }
+  });
+
+  return <path d={path} />;
+}
+```
+
+## API
+
+### getManHattanPath(params)
+
+生成 Manhattan 风格的 SVG 路径字符串。
+
+#### 参数
+
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| sourceNodeId | string | ✓ | 源节点 ID |
+| targetNodeId | string | ✓ | 目标节点 ID |
+| sourceX | number | ✓ | 源锚点 X 坐标 |
+| sourceY | number | ✓ | 源锚点 Y 坐标 |
+| targetX | number | ✓ | 目标锚点 X 坐标 |
+| targetY | number | ✓ | 目标锚点 Y 坐标 |
+| sourcePosition | Position | ✓ | 源锚点位置 (top/right/bottom/left) |
+| targetPosition | Position | ✓ | 目标锚点位置 |
+| nodeLookup | NodeLookup | ✓ | ReactFlow 节点查找 Map |
+| options | ManhattanRouterOptions | - | 路由配置选项 |
+
+#### 返回值
+
+返回 SVG 路径字符串，可直接用于 `<path d={...} />` 元素。
 
+### ManhattanRouterOptions
+
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| step | number | 10 | 网格步长（像素） |
+| maxLoopCount | number | 2000 | 最大迭代次数 |
+| precision | number | 1 | 坐标精度（小数位数） |
+| borderRadius | number | 5 | 转角圆角半径 |
+| extensionDistance | number | 20 | 路径延伸距离 |
+| padding | number \| object | 20 | 节点边界框内边距 |
+| startDirections | Direction[] | ['top', 'right', 'bottom', 'left'] | 允许的起始方向 |
+| endDirections | Direction[] | ['top', 'right', 'bottom', 'left'] | 允许的结束方向 |
+| excludeNodes | string[] | [] | 排除的节点 ID |
+| excludeShapes | string[] | [] | 排除的节点类型 |
+| adaptiveStep | AdaptiveStepConfig | - | 自适应步长配置 |
+| performance | PerformanceConfig | - | 性能优化配置 |
+| debug | DebugConfig | - | 调试配置 |
+
+### AdaptiveStepConfig
+
+```typescript
+interface AdaptiveStepConfig {
+  enabled: boolean;        // 是否启用自适应步长
+  minStep: number;         // 最小步长 (默认: 5)
+  maxStep: number;         // 最大步长 (默认: 50)
+  densityThreshold: number; // 密度阈值 (默认: 0.3)
+  distanceThreshold: number; // 距离阈值 (默认: 500)
+}
+```
+
+### PerformanceConfig
+
+```typescript
+interface PerformanceConfig {
+  enableCache: boolean;      // 启用路径缓存
+  cacheSize: number;         // 缓存大小 (默认: 100)
+  enableQuadTree: boolean;   // 启用四叉树优化
+  earlyTermination: boolean; // 启用早期终止
+}
+```
+
+### DebugConfig
+
+```typescript
+interface DebugConfig {
+  enableLogging: boolean;  // 启用日志
+  enableMetrics: boolean;  // 启用性能指标
+  logLevel: 'error' | 'warn' | 'info' | 'debug';
+}
+```
+
+## 高级用法
+
+### 自定义障碍物排除
+
+```typescript
 const path = getManHattanPath({
-  sourceNodeId: 'node-1',
-  targetNodeId: 'node-2',
-  nodeLookup,
-  // ... other options
+  // ...基本参数
+  options: {
+    excludeNodes: ['node-3', 'node-4'],  // 排除特定节点
+    excludeShapes: ['group'],             // 排除特定类型
+    excludeTerminals: ['source'],         // 排除源/目标节点
+  }
 });
 ```
 
-## 特性
+### 性能优化配置
 
-- A* 寻路算法
-- 正交路径生成
-- 障碍物避让
-- 高性能计算
+```typescript
+const path = getManHattanPath({
+  // ...基本参数
+  options: {
+    performance: {
+      enableCache: true,
+      cacheSize: 200,
+      enableQuadTree: true,
+      earlyTermination: true,
+    },
+    adaptiveStep: {
+      enabled: true,
+      minStep: 5,
+      maxStep: 30,
+    }
+  }
+});
+```
+
+### 调试模式
+
+```typescript
+const path = getManHattanPath({
+  // ...基本参数
+  options: {
+    debug: {
+      enableLogging: true,
+      enableMetrics: true,
+      logLevel: 'debug',
+    }
+  }
+});
+```
+
+## 工具类
+
+### GlobalGrid
+
+全局网格对齐工具，确保所有路径点对齐到统一网格。
+
+```typescript
+import { GlobalGrid } from '@rxflow/manhattan';
+
+const grid = new GlobalGrid(10);
+const snapped = grid.snapToGrid({ x: 15, y: 23 }); // { x: 20, y: 20 }
+```
+
+### ObstacleMap
+
+障碍物地图，用于空间查询和碰撞检测。
+
+```typescript
+import { ObstacleMap } from '@rxflow/manhattan';
+
+const map = new ObstacleMap(options);
+map.build(nodeLookup, sourceId, targetId, sourceAnchor, targetAnchor);
+const accessible = map.isAccessible(point);
+```
+
+### ErrorRecovery
+
+错误恢复工具，提供回退路径生成。
+
+```typescript
+import { ErrorRecovery } from '@rxflow/manhattan';
+
+const fallback = ErrorRecovery.generateFallbackPath(start, end);
+const validated = ErrorRecovery.validateAndFixConfig(config);
+```
+
+## 架构
+
+```
+@rxflow/manhattan
+├── getManHattanPath.ts    # 主入口函数
+├── geometry/              # 几何类 (Point, Rectangle)
+├── obstacle/              # 障碍物处理 (ObstacleMap, QuadTree)
+├── pathfinder/            # A* 寻路算法
+├── options/               # 配置解析
+├── svg/                   # SVG 路径转换
+└── utils/                 # 工具函数
+    ├── GlobalGrid.ts      # 全局网格
+    ├── AdaptiveStepCalculator.ts  # 自适应步长
+    ├── PerformanceMonitor.ts      # 性能监控
+    ├── ErrorRecovery.ts   # 错误恢复
+    └── heuristics.ts      # 启发式函数
+```
 
 ## License
 

package/cjs/getManHattanPath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getManHattanPath.d.ts","sourceRoot":"","sources":["../src/getManHattanPath.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,QAAQ,EAAE,MAAM,eAAe,CAAA;AAG3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,UAAU,EAAa,MAAM,WAAW,CAAA;AAM9E;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAEhB,cAAc,EAAE,QAAQ,CAAC;IACzB,cAAc,EAAE,QAAQ,CAAC;IACzB;;OAEG;IACH,UAAU,EAAE,UAAU,CAAA;IAEtB;;OAEG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAgbvE"}
+{"version":3,"file":"getManHattanPath.d.ts","sourceRoot":"","sources":["../src/getManHattanPath.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,QAAQ,EAAE,MAAM,eAAe,CAAA;AAG3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAMnE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAEhB,cAAc,EAAE,QAAQ,CAAC;IACzB,cAAc,EAAE,QAAQ,CAAC;IACzB;;OAEG;IACH,UAAU,EAAE,UAAU,CAAA;IAEtB;;OAEG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAydvE"}

package/cjs/getManHattanPath.js

@@ -69,10 +69,12 @@ function getManHattanPath(params) {
   const targetNode = nodeLookup.get(targetNodeId);
   if (!sourceNode || !targetNode) {
     // Fallback to simple straight line if nodes not found
-    console.warn('Source or target node not found in nodeLookup');
+    console.warn('[getManHattanPath] Source or target node not found in nodeLookup');
     const start = new _geometry.Point(sourceX, sourceY);
     const end = new _geometry.Point(targetX, targetY);
-    return (0, _svg.pointsToPath)([start, end], options.precision);
+    // Use ErrorRecovery to generate a proper fallback path
+    const fallbackPath = _utils.ErrorRecovery.generateFallbackPath(start, end);
+    return (0, _svg.pointsToPath)(fallbackPath, options.precision, options.borderRadius);
   }
 
   // Get node dimensions using ReactFlow's priority logic
@@ -107,10 +109,8 @@ function getManHattanPath(params) {
 
   // Check if smooth step path intersects with any obstacles
   if (smoothStepPoints.length > 0 && !(0, _utils.pathIntersectsObstacles)(smoothStepPoints, nodeLookup)) {
-    console.log('[getManHattanPath] Using ReactFlow getSmoothStepPath (no obstacles)');
     return smoothStepPath;
   }
-  console.log('[getManHattanPath] SmoothStepPath intersects obstacles, using Manhattan routing');
 
   // Build obstacle map with anchor information
   const obstacleMap = new _obstacle.ObstacleMap(options).build(nodeLookup, sourceNodeId, targetNodeId, sourceAnchor, targetAnchor);
@@ -118,23 +118,80 @@ function getManHattanPath(params) {
   // Find route
   let route = (0, _pathfinder.findRoute)(sourceBBox, targetBBox, sourceAnchor, targetAnchor, obstacleMap, options);
 
-  // Fallback to straight line if no route found
+  // Fallback to Z-shaped path if no route found
   if (!route) {
-    console.warn('Unable to find Manhattan route, using straight line fallback');
-    route = [sourceAnchor, targetAnchor];
+    console.warn('[getManHattanPath] Unable to find Manhattan route, using fallback path');
+    route = _utils.ErrorRecovery.generateFallbackPath(sourceAnchor, targetAnchor);
   }
-  console.log('[getManHattanPath] Route from findRoute:', route.map(p => `(${p.x}, ${p.y})`));
-  console.log('[getManHattanPath] Source anchor:', `(${sourceAnchor.x}, ${sourceAnchor.y})`);
-  console.log('[getManHattanPath] Target anchor:', `(${targetAnchor.x}, ${targetAnchor.y})`);
 
   // If using smart point generation (sourcePosition/targetPosition specified),
   // the route already contains the correct extension points, so skip manual processing
   const useSmartPoints = sourcePosition || targetPosition;
   if (useSmartPoints) {
-    console.log('[getManHattanPath] Using smart points, skipping manual extension point processing');
+    // Post-process route to fix X coordinates for horizontal anchors
+    // This ensures the extension distance is fixed and not affected by grid alignment
+    const isSourceHorizontal = sourcePosition === _react.Position.Left || sourcePosition === _react.Position.Right;
+    const isTargetHorizontal = targetPosition === _react.Position.Left || targetPosition === _react.Position.Right;
+    if (isSourceHorizontal && isTargetHorizontal && route.length > 0) {
+      // Calculate expected extension X coordinates
+      const sourceExtensionX = sourcePosition === _react.Position.Right ? sourceAnchor.x + options.extensionDistance : sourceAnchor.x - options.extensionDistance;
+      const targetExtensionX = targetPosition === _react.Position.Left ? targetAnchor.x - options.extensionDistance : targetAnchor.x + options.extensionDistance;
+
+      // Find the horizontal segment (where Y stays constant but X changes significantly)
+      // This divides the path into source-side and target-side
+      let horizontalSegmentStart = -1;
+      let horizontalSegmentEnd = -1;
+      for (let i = 0; i < route.length - 1; i++) {
+        const curr = route[i];
+        const next = route[i + 1];
+        const isHorizontalMove = Math.abs(curr.y - next.y) < 1 && Math.abs(curr.x - next.x) > options.step;
+        if (isHorizontalMove) {
+          horizontalSegmentStart = i;
+          horizontalSegmentEnd = i + 1;
+          break;
+        }
+      }
+
+      // Fix route points
+      for (let i = 0; i < route.length; i++) {
+        const point = route[i];
+        if (horizontalSegmentStart >= 0) {
+          if (i <= horizontalSegmentStart) {
+            // Source side - all vertical segment points should use sourceExtensionX
+            route[i] = new _geometry.Point(sourceExtensionX, point.y);
+          } else if (i >= horizontalSegmentEnd) {
+            // Target side - all vertical segment points should use targetExtensionX
+            route[i] = new _geometry.Point(targetExtensionX, point.y);
+          }
+        }
+      }
+
+      // Remove redundant points (consecutive points on same line)
+      const optimized = [];
+      for (let i = 0; i < route.length; i++) {
+        const point = route[i];
+        if (optimized.length < 2) {
+          optimized.push(point);
+        } else {
+          const prev = optimized[optimized.length - 1];
+          const prevPrev = optimized[optimized.length - 2];
+
+          // Check if prev is on the same line as prevPrev and point
+          const sameX = Math.abs(prevPrev.x - prev.x) < 1 && Math.abs(prev.x - point.x) < 1;
+          const sameY = Math.abs(prevPrev.y - prev.y) < 1 && Math.abs(prev.y - point.y) < 1;
+          if (sameX || sameY) {
+            // prev is redundant, replace it with current point
+            optimized[optimized.length - 1] = point;
+          } else {
+            optimized.push(point);
+          }
+        }
+      }
+      route = optimized;
+    }
+
     // Add source and target anchors to route
     const finalRoute = [sourceAnchor, ...route, targetAnchor];
-    console.log('[getManHattanPath] Final route:', finalRoute.map(p => `(${p.x}, ${p.y})`));
     return (0, _svg.pointsToPath)(finalRoute, options.precision, options.borderRadius);
   }
 
@@ -157,7 +214,6 @@ function getManHattanPath(params) {
       // This is likely an extension point, remove it
       if (onRight && firstPoint.x > sourceAnchor.x || onLeft && firstPoint.x < sourceAnchor.x || onBottom && firstPoint.y > sourceAnchor.y || onTop && firstPoint.y < sourceAnchor.y) {
         route.shift();
-        console.log('[getManHattanPath] Removed extension point from route start');
       }
     }
   }
@@ -176,7 +232,6 @@ function getManHattanPath(params) {
       // This is likely an extension point, remove it
       if (onLeft && lastPoint.x < targetAnchor.x || onRight && lastPoint.x > targetAnchor.x || onTop && lastPoint.y < targetAnchor.y || onBottom && lastPoint.y > targetAnchor.y) {
         route.pop();
-        console.log('[getManHattanPath] Removed extension point from route end');
       }
     }
   }
@@ -202,7 +257,6 @@ function getManHattanPath(params) {
         route.unshift(new _geometry.Point(extendX, firstPoint.y)); // Corner point
       }
       route.unshift(extensionPoint); // Extension point (fixed distance)
-      console.log('[getManHattanPath] Inserted source extension (right):', `(${extendX}, ${sourceAnchor.y})`);
     } else if (onLeft) {
       // Anchor on left edge - extend left by step + borderRadius
       const extendX = sourceAnchor.x - extensionDistance;
@@ -211,7 +265,6 @@ function getManHattanPath(params) {
         route.unshift(new _geometry.Point(extendX, firstPoint.y));
       }
       route.unshift(extensionPoint);
-      console.log('[getManHattanPath] Inserted source extension (left):', `(${extendX}, ${sourceAnchor.y})`);
     } else if (onBottom) {
       // Anchor on bottom edge - extend down by step + borderRadius
       const extendY = sourceAnchor.y + extensionDistance;
@@ -220,7 +273,6 @@ function getManHattanPath(params) {
         route.unshift(new _geometry.Point(firstPoint.x, extendY));
       }
       route.unshift(extensionPoint);
-      console.log('[getManHattanPath] Inserted source extension (down):', `(${sourceAnchor.x}, ${extendY})`);
     } else if (onTop) {
       // Anchor on top edge - extend up by step + borderRadius
       const extendY = sourceAnchor.y - extensionDistance;
@@ -229,33 +281,25 @@ function getManHattanPath(params) {
         route.unshift(new _geometry.Point(firstPoint.x, extendY));
       }
       route.unshift(extensionPoint);
-      console.log('[getManHattanPath] Inserted source extension (up):', `(${sourceAnchor.x}, ${extendY})`);
     }
   }
 
   // Remove redundant points after source extension
   // If the first route point has the same x or y coordinate as the source anchor, it's redundant
-  if (route.length > 2) {
-    const firstRoutePoint = route[0]; // Extension point
-    const secondRoutePoint = route[1]; // Corner point (if exists)
+  if (route.length > 3) {
     const thirdRoutePoint = route[2]; // Original A* point
-
     // Check if the third point (original A* point) is redundant
     // It's redundant if it's on the same line as the corner point and can be skipped
     const sameX = Math.abs(thirdRoutePoint.x - sourceAnchor.x) < tolerance;
     const sameY = Math.abs(thirdRoutePoint.y - sourceAnchor.y) < tolerance;
     if (sameX || sameY) {
-      // The third point is aligned with the source anchor, likely redundant
-      // Check if we can skip it by connecting corner point directly to the next point
-      if (route.length > 3) {
-        const fourthPoint = route[3];
-        // If corner point and fourth point form a straight line, remove the third point
-        const cornerToThird = Math.abs(secondRoutePoint.x - thirdRoutePoint.x) < tolerance || Math.abs(secondRoutePoint.y - thirdRoutePoint.y) < tolerance;
-        const thirdToFourth = Math.abs(thirdRoutePoint.x - fourthPoint.x) < tolerance || Math.abs(thirdRoutePoint.y - fourthPoint.y) < tolerance;
-        if (cornerToThird && thirdToFourth) {
-          console.log('[getManHattanPath] Removing redundant point:', `(${thirdRoutePoint.x}, ${thirdRoutePoint.y})`);
-          route.splice(2, 1); // Remove the third point
-        }
+      const secondRoutePoint = route[1]; // Corner point (if exists)
+      const fourthPoint = route[3];
+      // If corner point and fourth point form a straight line, remove the third point
+      const cornerToThird = Math.abs(secondRoutePoint.x - thirdRoutePoint.x) < tolerance || Math.abs(secondRoutePoint.y - thirdRoutePoint.y) < tolerance;
+      const thirdToFourth = Math.abs(thirdRoutePoint.x - fourthPoint.x) < tolerance || Math.abs(thirdRoutePoint.y - fourthPoint.y) < tolerance;
+      if (cornerToThird && thirdToFourth) {
+        route.splice(2, 1); // Remove the third point
       }
     }
   }
@@ -265,8 +309,6 @@ function getManHattanPath(params) {
   // where the middle segment goes to target edge and then moves along it
   // Use target bbox with padding (same as ObstacleMap)
   const targetBBoxWithPadding = targetBBox.moveAndExpand(options.paddingBox);
-  console.log('[getManHattanPath] Route before zigzag check:', route.map(p => `(${p.x}, ${p.y})`));
-  console.log('[getManHattanPath] Target BBox with padding:', `x=${targetBBoxWithPadding.x}, y=${targetBBoxWithPadding.y}`);
   if (route.length >= 3) {
     let i = 0;
     while (i < route.length - 2) {
@@ -280,17 +322,14 @@ function getManHattanPath(params) {
       const p2OnTargetTopEdge = Math.abs(p2.y - targetBBoxWithPadding.y) < tolerance;
       const p2OnTargetBottomEdge = Math.abs(p2.y - (targetBBoxWithPadding.y + targetBBoxWithPadding.height)) < tolerance;
       const p2OnTargetEdge = p2OnTargetLeftEdge || p2OnTargetRightEdge || p2OnTargetTopEdge || p2OnTargetBottomEdge;
-      console.log(`[getManHattanPath] Checking i=${i}: p2=(${p2.x}, ${p2.y}), onEdge=${p2OnTargetEdge}`);
       if (p2OnTargetEdge) {
         // Check if p1 -> p2 -> p3 forms a zigzag
         const p1ToP2Horizontal = Math.abs(p1.y - p2.y) < tolerance;
         const p2ToP3Vertical = Math.abs(p2.x - p3.x) < tolerance;
         const p1ToP2Vertical = Math.abs(p1.x - p2.x) < tolerance;
         const p2ToP3Horizontal = Math.abs(p2.y - p3.y) < tolerance;
-        console.log(`[getManHattanPath] Zigzag pattern: H->V=${p1ToP2Horizontal && p2ToP3Vertical}, V->H=${p1ToP2Vertical && p2ToP3Horizontal}`);
         if (p1ToP2Horizontal && p2ToP3Vertical || p1ToP2Vertical && p2ToP3Horizontal) {
           // We have a zigzag at target edge, remove p2 and p3
-          console.log('[getManHattanPath] Removing zigzag at target edge:', `(${p2.x}, ${p2.y})`, `and (${p3.x}, ${p3.y})`);
           route.splice(i + 1, 2); // Remove p2 and p3
           continue;
         }
@@ -319,7 +358,6 @@ function getManHattanPath(params) {
         route.push(new _geometry.Point(extendX, lastPoint.y)); // Corner point
       }
       route.push(extensionPoint); // Extension point (fixed distance)
-      console.log('[getManHattanPath] Inserted target extension (left):', `(${extendX}, ${targetAnchor.y})`);
     } else if (onRight) {
       // Anchor on right edge - extend right by step + borderRadius
       const extendX = targetAnchor.x + extensionDistance;
@@ -328,7 +366,6 @@ function getManHattanPath(params) {
         route.push(new _geometry.Point(extendX, lastPoint.y));
       }
       route.push(extensionPoint);
-      console.log('[getManHattanPath] Inserted target extension (right):', `(${extendX}, ${targetAnchor.y})`);
     } else if (onTop) {
       // Anchor on top edge - extend up by step + borderRadius
       const extendY = targetAnchor.y - extensionDistance;
@@ -337,7 +374,6 @@ function getManHattanPath(params) {
         route.push(new _geometry.Point(lastPoint.x, extendY));
       }
       route.push(extensionPoint);
-      console.log('[getManHattanPath] Inserted target extension (up):', `(${targetAnchor.x}, ${extendY})`);
     } else if (onBottom) {
       // Anchor on bottom edge - extend down by step + borderRadius
       const extendY = targetAnchor.y + extensionDistance;
@@ -346,7 +382,6 @@ function getManHattanPath(params) {
         route.push(new _geometry.Point(lastPoint.x, extendY));
       }
       route.push(extensionPoint);
-      console.log('[getManHattanPath] Inserted target extension (down):', `(${targetAnchor.x}, ${extendY})`);
     }
   }
 
@@ -354,7 +389,6 @@ function getManHattanPath(params) {
   // Similar logic for target side
   if (route.length > 2) {
     const lastIdx = route.length - 1;
-    const lastRoutePoint = route[lastIdx]; // Extension point
     const secondLastPoint = route[lastIdx - 1]; // Corner point (if exists)
     const thirdLastPoint = route[lastIdx - 2]; // Original A* point
 
@@ -367,7 +401,6 @@ function getManHattanPath(params) {
         const fourthToThird = Math.abs(fourthLastPoint.x - thirdLastPoint.x) < tolerance || Math.abs(fourthLastPoint.y - thirdLastPoint.y) < tolerance;
         const thirdToSecond = Math.abs(thirdLastPoint.x - secondLastPoint.x) < tolerance || Math.abs(thirdLastPoint.y - secondLastPoint.y) < tolerance;
         if (fourthToThird && thirdToSecond) {
-          console.log('[getManHattanPath] Removing redundant point:', `(${thirdLastPoint.x}, ${thirdLastPoint.y})`);
           route.splice(lastIdx - 2, 1); // Remove the third-to-last point
         }
       }
@@ -400,7 +433,6 @@ function getManHattanPath(params) {
         const p3ToP4Horizontal = Math.abs(p3.y - p4.y) < tolerance;
         if (p3ToP4Horizontal) {
           // Pattern: horizontal -> vertical -> horizontal (zigzag)
-          console.log('[getManHattanPath] Removing zigzag at target edge:', `(${p2.x}, ${p2.y})`, `and (${p3.x}, ${p3.y})`);
           route.splice(i + 1, 2); // Remove p2 and p3
           continue;
         }
@@ -411,7 +443,6 @@ function getManHattanPath(params) {
 
   // Add source and target anchors to route
   const finalRoute = [sourceAnchor, ...route, targetAnchor];
-  console.log('[getManHattanPath] Final route:', finalRoute.map(p => `(${p.x}, ${p.y})`));
 
   // Convert to SVG path string
   return (0, _svg.pointsToPath)(finalRoute, options.precision, options.borderRadius);

package/cjs/obstacle/ObstacleMap.d.ts

@@ -2,29 +2,61 @@ import { Point } from '../geometry';
 import type { ResolvedOptions, NodeLookup } from '../options';
 /**
  * ObstacleMap class for managing obstacles in pathfinding
- * Uses a grid-based spatial partitioning for efficient queries
+ * Feature: manhattan-optimization
+ *
+ * Uses QuadTree for efficient spatial queries (O(log n) instead of O(n))
+ * Includes query caching for repeated accessibility checks
  */
 export declare class ObstacleMap {
     private options;
-    private mapGridSize;
-    private map;
+    private quadTree;
+    private obstacles;
     private sourceAnchor?;
     private targetAnchor?;
+    private accessibilityCache;
+    private cacheHits;
+    private cacheMisses;
     constructor(options: ResolvedOptions);
     /**
-     * Build obstacle map from node lookup
+     * Get cache statistics for performance monitoring
      */
-    build(nodeLookup: NodeLookup, sourceNodeId: string, targetNodeId: string, sourceAnchor?: Point, targetAnchor?: Point): ObstacleMap;
+    getCacheStats(): {
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /**
+     * Clear the accessibility cache
+     */
+    clearCache(): void;
     /**
-     * Shrink bbox to exclude the area around the anchor point
-     * This allows paths to start/end at the anchor but prevents crossing the node
+     * Build obstacle map from node lookup using QuadTree
      */
-    private shrinkBBoxAroundAnchor;
+    build(nodeLookup: NodeLookup, sourceNodeId: string, targetNodeId: string, sourceAnchor?: Point, targetAnchor?: Point): ObstacleMap;
     /**
      * Check if a point is accessible (not inside any obstacle)
-     * Uses binary search optimization: step -> step/2 -> step/4 -> ... -> 1px
+     * Uses QuadTree for efficient spatial queries with caching
      */
     isAccessible(point: Point, checkRadius?: number): boolean;
+    /**
+     * Check if an anchor point has sufficient clearance around it
+     * This ensures the path can start/end at the anchor without being blocked
+     */
+    hasAnchorClearance(anchor: Point, direction: 'top' | 'right' | 'bottom' | 'left'): boolean;
+    /**
+     * Check accessibility without using cache (for internal use)
+     */
+    private isAccessibleWithoutCache;
+    /**
+     * Find the nearest accessible point from an anchor in a given direction
+     * Uses binary search for efficiency
+     */
+    findNearestAccessiblePoint(anchor: Point, direction: 'top' | 'right' | 'bottom' | 'left', maxDistance: number): Point | null;
+    /**
+     * Batch check accessibility for multiple points (optimized)
+     * Returns array of booleans in same order as input points
+     */
+    areAccessible(points: Point[]): boolean[];
     /**
      * Check accessibility using binary search optimization
      * Tries step -> step/2 -> step/4 -> ... -> 1px

package/cjs/obstacle/ObstacleMap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ObstacleMap.d.ts","sourceRoot":"","sources":["../../src/obstacle/ObstacleMap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAa,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAG7D;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,GAAG,CAA0B;IACrC,OAAO,CAAC,YAAY,CAAC,CAAO;IAC5B,OAAO,CAAC,YAAY,CAAC,CAAO;gBAEhB,OAAO,EAAE,eAAe;IAMpC;;OAEG;IACH,KAAK,CACH,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,KAAK,EACpB,YAAY,CAAC,EAAE,KAAK,GACnB,WAAW;IAiEd;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA6D9B;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,GAAE,MAAU,GAAG,OAAO;IAiD5D;;;OAGG;IACH,OAAO,CAAC,4BAA4B;CAqCrC"}
+{"version":3,"file":"ObstacleMap.d.ts","sourceRoot":"","sources":["../../src/obstacle/ObstacleMap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAa,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAI7D;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,SAAS,CAAmD;IACpE,OAAO,CAAC,YAAY,CAAC,CAAO;IAC5B,OAAO,CAAC,YAAY,CAAC,CAAO;IAG5B,OAAO,CAAC,kBAAkB,CAAkC;IAC5D,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,WAAW,CAAY;gBAEnB,OAAO,EAAE,eAAe;IAIpC;;OAEG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IASlE;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;OAEG;IACH,KAAK,CACH,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,KAAK,EACpB,YAAY,CAAC,EAAE,KAAK,GACnB,WAAW;IA8Cd;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,GAAE,MAAU,GAAG,OAAO;IAoD5D;;;OAGG;IACH,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO;IA0C1F;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAShC;;;OAGG;IACH,0BAA0B,CACxB,MAAM,EAAE,KAAK,EACb,SAAS,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,EAC9C,WAAW,EAAE,MAAM,GAClB,KAAK,GAAG,IAAI;IAyDf;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE;IAIzC;;;OAGG;IACH,OAAO,CAAC,4BAA4B;CAqCrC"}