@mint-ui/map 1.2.0-test.20 → 1.2.0-test.21

package/dist/index.umd.js

@@ -805,7 +805,38 @@
   }();
 
   /**
-   * 폴리곤 offset 계산
+   * @fileoverview WoongCanvasLayer를 위한 유틸리티 함수들
+   *
+   * 이 파일은 좌표 변환, 히트 테스트, 색상 변환 등 WoongCanvasLayer에서
+   * 사용하는 다양한 유틸리티 함수들을 제공합니다.
+   *
+   * ## 주요 기능
+   * - **좌표 변환**: 지도 좌표(위경도) ↔ 화면 좌표(픽셀) 변환
+   * - **히트 테스트**: 마우스 클릭/호버 시 어떤 마커/폴리곤인지 찾기
+   * - **색상 변환**: 다양한 색상 형식 간 변환
+   * - **바운딩 박스**: 폴리곤의 경계 영역 계산
+   *
+   * @version 2.2.1
+   * @since 2.0.0
+   * @author 박건웅
+   */
+  /**
+   * 폴리곤 좌표를 화면 좌표로 변환
+   *
+   * GeoJSON MultiPolygon 형식의 폴리곤 데이터를 Canvas에서 그릴 수 있는
+   * 화면 좌표 배열로 변환합니다.
+   *
+   * @param polygonData - 변환할 폴리곤 데이터
+   * @param controller - 지도 컨트롤러 (좌표 변환용)
+   * @returns 변환된 좌표 배열 또는 null (변환 실패 시)
+   *
+   * @example
+   * ```typescript
+   * const offsets = computePolygonOffsets(polygonData, controller);
+   * if (offsets) {
+   *   // offsets[0][0][0] = [x, y] - 첫 번째 MultiPolygon의 첫 번째 Polygon의 첫 번째 점
+   * }
+   * ```
    */
 
   var computePolygonOffsets = function (polygonData, controller) {
@@ -841,7 +872,21 @@
     return result;
   };
   /**
-   * 마커 offset 계산
+   * 마커 좌표를 화면 좌표로 변환
+   *
+   * 마커의 지도 좌표(위경도)를 Canvas에서 그릴 수 있는 화면 좌표로 변환합니다.
+   *
+   * @param markerData - 변환할 마커 데이터
+   * @param controller - 지도 컨트롤러 (좌표 변환용)
+   * @returns 변환된 화면 좌표 또는 null (변환 실패 시)
+   *
+   * @example
+   * ```typescript
+   * const offset = computeMarkerOffset(markerData, controller);
+   * if (offset) {
+   *   console.log(`마커 위치: (${offset.x}, ${offset.y})`);
+   * }
+   * ```
    */
 
   var computeMarkerOffset = function (markerData, controller) {
@@ -852,7 +897,21 @@
     return controller.positionToOffset(markerData.position);
   };
   /**
-   * Point-in-Polygon 알고리즘
+   * Point-in-Polygon 알고리즘 (Ray Casting)
+   *
+   * 주어진 점이 폴리곤 내부에 있는지 확인하는 알고리즘입니다.
+   * Ray Casting 방식을 사용하여 홀수 번 교차하면 내부, 짝수 번 교차하면 외부로 판단합니다.
+   *
+   * @param point - 확인할 점의 좌표
+   * @param polygon - 폴리곤의 좌표 배열 (순서대로 연결된 점들)
+   * @returns 점이 폴리곤 내부에 있으면 true, 외부에 있으면 false
+   *
+   * @example
+   * ```typescript
+   * const point = { x: 100, y: 100 };
+   * const polygon = [[0, 0], [200, 0], [200, 200], [0, 200]];
+   * const isInside = isPointInPolygon(point, polygon); // true
+   * ```
    */
 
   var isPointInPolygon = function (point, polygon) {
@@ -872,13 +931,31 @@
   /**
    * 폴리곤 히트 테스트 (도넛 폴리곤 지원)
    *
-   * 로직:
-   * 1. 외부 폴리곤(첫 번째): 내부에 있어야 함
-   * 2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
+   * 클릭된 좌표가 폴리곤 내부에 있는지 확인합니다.
+   * 도넛 폴리곤(구멍이 있는 폴리곤)도 지원합니다.
+   *
+   * ## 도넛 폴리곤 처리 로직
+   * 1. **외부 폴리곤(첫 번째)**: 내부에 있어야 함
+   * 2. **내부 구멍들(나머지)**: 내부에 있으면 안 됨 (evenodd 규칙)
+   *
+   * ## 중요 사항
+   * 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됩니다:
+   * - 도넛 폴리곤 A: `isDonutPolygon=true`
+   * - 내부 폴리곤 B: `isDonutPolygon=false` (별도 데이터)
    *
-   * 중요: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됨
-   * - 도넛 폴리곤 A: isDonutPolygon=true
-   * - 내부 폴리곤 B: isDonutPolygon=false (별도 데이터)
+   * @param clickedOffset - 클릭된 좌표
+   * @param polygonData - 확인할 폴리곤 데이터
+   * @param getPolygonOffsets - 폴리곤 좌표를 가져오는 함수
+   * @returns 클릭된 좌표가 폴리곤 내부에 있으면 true, 외부에 있으면 false
+   *
+   * @example
+   * ```typescript
+   * const isHit = isPointInPolygonData(
+   *   { x: 100, y: 100 },
+   *   polygonData,
+   *   (data) => computePolygonOffsets(data, controller)
+   * );
+   * ```
    */
 
   var isPointInPolygonData = function (clickedOffset, polygonData, getPolygonOffsets) {
@@ -943,10 +1020,27 @@
   /**
    * 마커 히트 테스트 (클릭/hover 영역 체크)
    *
-   * 🎯 중요: 꼬리(tail)는 Hit Test 영역에서 제외됩니다!
-   * - markerOffset.y는 마커 최하단(꼬리 끝) 좌표
-   * - boxHeight는 마커 본체만 포함 (꼬리 제외)
-   * - tailHeight만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+   * 클릭된 좌표가 마커의 클릭 가능한 영역 내부에 있는지 확인합니다.
+   *
+   * ## 중요 사항
+   * **꼬리(tail)는 Hit Test 영역에서 제외됩니다!**
+   * - `markerOffset.y`는 마커 최하단(꼬리 끝) 좌표
+   * - `boxHeight`는 마커 본체만 포함 (꼬리 제외)
+   * - `tailHeight`만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+   *
+   * @param clickedOffset - 클릭된 좌표
+   * @param markerData - 확인할 마커 데이터
+   * @param getMarkerOffset - 마커 좌표를 가져오는 함수
+   * @returns 클릭된 좌표가 마커 내부에 있으면 true, 외부에 있으면 false
+   *
+   * @example
+   * ```typescript
+   * const isHit = isPointInMarkerData(
+   *   { x: 100, y: 100 },
+   *   markerData,
+   *   (data) => computeMarkerOffset(data, controller)
+   * );
+   * ```
    */
 
   var isPointInMarkerData = function (clickedOffset, markerData, getMarkerOffset) {
@@ -961,13 +1055,29 @@
 
     return clickedOffset.x >= x && clickedOffset.x <= x + boxWidth && clickedOffset.y >= y && clickedOffset.y <= y + boxHeight;
   };
+  /**
+   * HEX 색상을 RGBA 색상으로 변환
+   *
+   * 16진수 색상 코드를 RGBA 형식으로 변환합니다.
+   *
+   * @param hexColor - 변환할 HEX 색상 (예: "#FF0000" 또는 "FF0000")
+   * @param alpha - 알파 값 (0~1, 기본값: 1)
+   * @returns RGBA 형식의 색상 문자열
+   *
+   * @example
+   * ```typescript
+   * const rgba = hexToRgba('#FF0000', 0.5); // "rgba(255, 0, 0, 0.5)"
+   * const rgba2 = hexToRgba('FF0000', 1);   // "rgba(255, 0, 0, 1)"
+   * ```
+   */
+
   var hexToRgba = function (hexColor, alpha) {
     if (alpha === void 0) {
       alpha = 1;
-    } // NOTE: 입력된 hexColor에서 "#" 제거
+    } // 입력된 hexColor에서 "#" 제거
 
 
-    var hex = hexColor.replace('#', ''); // NOTE: 6자리일 경우 알파 값은 사용자가 제공한 alpha 값으로 설정
+    var hex = hexColor.replace('#', ''); // 6자리일 경우 알파 값은 사용자가 제공한 alpha 값으로 설정
 
     if (hex.length === 6) {
       var r = parseInt(hex.substring(0, 2), 16);
@@ -981,14 +1091,27 @@
   var tempCanvas = document.createElement('canvas');
   var tempCtx = tempCanvas.getContext('2d');
   /**
-   * 텍스트 박스의 너비를 계산합니다.
+   * 텍스트 박스의 너비를 계산
+   *
+   * Canvas 2D API의 measureText()를 사용하여 텍스트의 실제 너비를 측정하고,
+   * 패딩과 최소 너비를 고려하여 최종 박스 너비를 계산합니다.
    *
-   * @param {Object} params - 파라미터 객체
-   * @param {string} params.text - 측정할 텍스트
-   * @param {string} params.fontConfig - 폰트 설정 (예: 'bold 16px Arial')
-   * @param {number} params.padding - 텍스트 박스에 적용할 패딩 값
-   * @param {number} params.minWidth - 최소 너비
-   * @returns {number} 계산된 텍스트 박스의 너비
+   * @param params - 파라미터 객체
+   * @param params.text - 측정할 텍스트
+   * @param params.fontConfig - 폰트 설정 (예: 'bold 16px Arial')
+   * @param params.padding - 텍스트 박스에 적용할 패딩 값
+   * @param params.minWidth - 최소 너비
+   * @returns 계산된 텍스트 박스의 너비
+   *
+   * @example
+   * ```typescript
+   * const width = calculateTextBoxWidth({
+   *   text: 'Hello World',
+   *   fontConfig: 'bold 16px Arial',
+   *   padding: 10,
+   *   minWidth: 50
+   * });
+   * ```
    */
 
   var calculateTextBoxWidth = function (_a) {
@@ -1002,18 +1125,50 @@
     return Math.max(minWidth, textWidth + padding);
   };
 
+  /** 다중 레이어 관리를 위한 React Context */
+
   var KonvaMarkerContext = React.createContext(null);
+  /**
+   * 다중 WoongCanvasLayer 관리를 위한 Context Provider
+   *
+   * 여러 개의 WoongCanvasLayer가 동시에 사용될 때 이벤트 우선순위를 관리하고
+   * 전역 클릭/호버 이벤트를 조정합니다.
+   *
+   * @param children - Provider로 감쌀 React 컴포넌트들
+   * @returns Context Provider 컴포넌트
+   *
+   * @example
+   * ```tsx
+   * <KonvaMarkerProvider>
+   *   <WoongCanvasLayer zIndex={1} data={markers1} ... />
+   *   <WoongCanvasLayer zIndex={2} data={markers2} ... />
+   * </KonvaMarkerProvider>
+   * ```
+   */
+
   var KonvaMarkerProvider = function (_a) {
     var children = _a.children;
-    var controller = useMintMapController(); // Refs
+    var controller = useMintMapController(); // === Refs ===
+
+    /** 등록된 모든 컴포넌트 인스턴스들 (zIndex 내림차순 정렬) */
 
     var componentsRef = React.useRef([]);
+    /** 현재 호버된 컴포넌트 인스턴스 */
+
     var currentHoveredRef = React.useRef(null);
+    /** 현재 호버된 데이터 */
+
     var currentHoveredDataRef = React.useRef(null);
-    var draggingRef = React.useRef(false);
+    /** 드래그/줌 중 여부 (마우스 이동 이벤트 무시용) */
+
+    var draggingRef = React.useRef(false); // === 컴포넌트 관리 함수들 ===
+
     /**
-     * 컴포넌트 등록 (zIndex 내림차순 정렬)
-     * 높은 zIndex가 먼저 처리됨
+     * 컴포넌트 인스턴스 등록
+     *
+     * zIndex 내림차순으로 정렬하여 높은 우선순위의 컴포넌트가 먼저 이벤트를 처리하도록 합니다.
+     *
+     * @param instance - 등록할 컴포넌트 인스턴스
      */
 
     var registerComponent = React.useCallback(function (instance) {
@@ -1023,7 +1178,12 @@
       });
     }, []);
     /**
-     * 컴포넌트 등록 해제
+     * 컴포넌트 인스턴스 등록 해제
+     *
+     * 컴포넌트가 언마운트될 때 호출되어 Context에서 제거합니다.
+     * 현재 호버 중인 컴포넌트라면 호버 상태도 초기화합니다.
+     *
+     * @param instance - 등록 해제할 컴포넌트 인스턴스
      */
 
     var unregisterComponent = React.useCallback(function (instance) {
@@ -1036,9 +1196,15 @@
       componentsRef.current = componentsRef.current.filter(function (c) {
         return c !== instance;
       });
-    }, []);
+    }, []); // === 전역 이벤트 핸들러들 ===
+
     /**
-     * 전역 클릭 핸들러 (zIndex 우선순위)
+     * 전역 클릭 이벤트 핸들러
+     *
+     * zIndex 우선순위에 따라 등록된 컴포넌트들을 순회하며 클릭된 데이터를 찾습니다.
+     * 첫 번째로 히트된 컴포넌트의 이벤트만 처리합니다.
+     *
+     * @param event - 지도 클릭 이벤트 파라미터
      */
 
     var handleGlobalClick = React.useCallback(function (event) {
@@ -1048,7 +1214,7 @@
       var clickedOffset = controller.positionToOffset(event.param.position); // zIndex 순서대로 순회 (높은 것부터)
 
       for (var _i = 0, _b = componentsRef.current; _i < _b.length; _i++) {
-        var component = _b[_i]; // 🚫 상호작용이 비활성화된 컴포넌트는 스킵
+        var component = _b[_i]; // 상호작용이 비활성화된 컴포넌트는 스킵
 
         if (component.isInteractionDisabled()) continue;
         var data = component.findData(clickedOffset);
@@ -1065,7 +1231,12 @@
       }
     }, [controller]);
     /**
-     * 전역 마우스 이동 핸들러 (zIndex 우선순위)
+     * 전역 마우스 이동 이벤트 핸들러
+     *
+     * zIndex 우선순위에 따라 호버된 데이터를 찾고, 호버 상태가 변경되면
+     * 이전 호버를 해제하고 새로운 호버를 설정합니다.
+     *
+     * @param event - 지도 마우스 이동 이벤트 파라미터
      */
 
     var handleGlobalMouseMove = React.useCallback(function (event) {
@@ -1078,7 +1249,7 @@
       var newHoveredData = null;
 
       for (var _i = 0, _b = componentsRef.current; _i < _b.length; _i++) {
-        var component = _b[_i]; // 🚫 상호작용이 비활성화된 컴포넌트는 스킵
+        var component = _b[_i]; // 상호작용이 비활성화된 컴포넌트는 스킵
 
         if (component.isInteractionDisabled()) continue;
         var data = component.findData(mouseOffset);
@@ -1115,19 +1286,24 @@
       }
     }, [controller]);
     /**
-     * 줌/드래그 시작 (마우스 이동 이벤트 무시)
+     * 줌/드래그 시작 이벤트 핸들러
+     *
+     * 지도가 줌이나 드래그를 시작할 때 마우스 이동 이벤트를 무시하도록 설정합니다.
+     * 이는 성능 최적화와 불필요한 호버 이벤트 방지를 위한 것입니다.
      */
 
     var handleZoomStart = React.useCallback(function () {
       draggingRef.current = true;
     }, []);
     /**
-     * 지도 idle (마우스 이동 이벤트 재개)
+     * 지도 idle 이벤트 핸들러
+     *
+     * 지도가 idle 상태가 되면 마우스 이동 이벤트를 다시 활성화합니다.
      */
 
     var handleIdle = React.useCallback(function () {
       draggingRef.current = false;
-    }, []); // 이벤트 리스너 등록
+    }, []); // === 이벤트 리스너 등록 ===
 
     React.useEffect(function () {
       controller.addEventListener('CLICK', handleGlobalClick);
@@ -1140,7 +1316,7 @@
         controller.removeEventListener('ZOOMSTART', handleZoomStart);
         controller.removeEventListener('IDLE', handleIdle);
       };
-    }, [controller, handleGlobalClick, handleGlobalMouseMove, handleZoomStart, handleIdle]); // Context value 메모이제이션
+    }, [controller, handleGlobalClick, handleGlobalMouseMove, handleZoomStart, handleIdle]); // === Context value 메모이제이션 ===
 
     var contextValue = React.useMemo(function () {
       return {
@@ -1152,11 +1328,40 @@
       value: contextValue
     }, children);
   };
+  /**
+   * KonvaMarkerContext를 사용하기 위한 Hook
+   *
+   * @returns Context 값 또는 null (Provider 외부에서 사용 시)
+   *
+   * @example
+   * ```tsx
+   * const context = useKonvaMarkerContext();
+   * if (context) {
+   *   context.registerComponent(instance);
+   * }
+   * ```
+   */
+
   var useKonvaMarkerContext = function () {
     var context = React.useContext(KonvaMarkerContext);
     return context;
   };
 
+  /**
+   * @fileoverview WoongCanvasLayer 성능 최적화를 위한 상수 및 클래스
+   *
+   * 이 파일은 30,000개 이상의 마커/폴리곤을 60fps로 렌더링하기 위한
+   * 성능 최적화 상수와 최적화된 자료구조들을 제공합니다.
+   *
+   * ## 주요 구성 요소
+   * - **성능 최적화 상수**: 그리드 셀 크기, 캐시 크기, 컬링 여유 공간
+   * - **LRUCache**: 좌표 변환 결과 캐싱을 위한 LRU 캐시 구현
+   * - **SpatialHashGrid**: O(1) 수준의 빠른 Hit Test를 위한 공간 해시 그리드
+   *
+   * @version 2.2.1
+   * @since 2.0.0
+   * @author 박건웅
+   */
   // ============================================================================
   // 성능 최적화 상수 (30,000개 마커/폴리곤 기준 최적화)
   // ============================================================================
@@ -1205,12 +1410,29 @@
   var DEFAULT_MAX_CACHE_SIZE = 30000;
   /**
    * LRU (Least Recently Used) Cache
-   * 메모리 제한을 위한 캐시 구현 (최적화 버전)
    *
-   * 개선 사항:
-   * 1. get() 성능 향상: 접근 빈도 추적 없이 단순 조회만 수행 (delete+set 제거)
-   * 2. set() 버그 수정: 기존 키 업데이트 시 maxSize 체크 로직 개선
-   * 3. 메모리 효율: 단순 FIFO 캐시로 동작하여 오버헤드 최소화
+   * 메모리 제한을 위한 캐시 구현으로, 좌표 변환 결과를 캐싱하여
+   * 성능을 최적화합니다. WoongCanvasLayer의 특성에 맞게 최적화되었습니다.
+   *
+   * ## 주요 특징
+   * - **빠른 조회**: O(1) 해시 조회로 성능 최적화
+   * - **메모리 제한**: 최대 크기 초과 시 자동 eviction
+   * - **FIFO 방식**: 삽입 순서 기반 eviction (접근 빈도 추적 없음)
+   *
+   * ## 개선 사항
+   * 1. **get() 성능 향상**: 접근 빈도 추적 없이 단순 조회만 수행
+   * 2. **set() 버그 수정**: 기존 키 업데이트 시 maxSize 체크 로직 개선
+   * 3. **메모리 효율**: 단순 FIFO 캐시로 동작하여 오버헤드 최소화
+   *
+   * @template K 캐시 키 타입
+   * @template V 캐시 값 타입
+   *
+   * @example
+   * ```typescript
+   * const cache = new LRUCache<string, Offset>(1000);
+   * cache.set('marker-1', { x: 100, y: 200 });
+   * const offset = cache.get('marker-1'); // { x: 100, y: 200 }
+   * ```
    */
 
   var LRUCache =
@@ -1290,16 +1512,33 @@
   }();
   /**
    * Spatial Hash Grid (공간 해시 그리드)
-   * 공간 인덱싱을 위한 그리드 기반 자료구조 (개선 버전)
    *
-   * 개선 사항:
-   * 1. 중복 삽입 방지: 같은 항목을 여러 번 insert 해도 안전
-   * 2. 메모리 누수 방지: 기존 항목 자동 제거
-   * 3. 성능 최적화: 불필요한 배열 생성 최소화
+   * 공간 인덱싱을 위한 그리드 기반 자료구조로, 2D 공간을 격자로 나누어
+   * 특정 영역에 있는 객체들을 빠르게 찾을 수 있게 해줍니다.
+   *
+   * ## 주요 특징
+   * - **O(1) 조회**: 클릭 위치 주변의 객체들만 체크하여 성능 최적화
+   * - **메모리 효율**: 격자 기반으로 필요한 영역만 인덱싱
+   * - **중복 방지**: 같은 항목을 여러 번 삽입해도 안전
+   *
+   * ## 성능 비교
+   * - **일반 검색**: 30,000개 항목 전체 체크 → O(n)
+   * - **Spatial Hash**: 클릭 위치 주변 ~10개만 체크 → O(1) + O(10)
+   * - **성능 향상**: 약 3,000배 빠름! 🚀
+   *
+   * ## 개선 사항
+   * 1. **중복 삽입 방지**: 같은 항목을 여러 번 insert 해도 안전
+   * 2. **메모리 누수 방지**: 기존 항목 자동 제거
+   * 3. **성능 최적화**: 불필요한 배열 생성 최소화
+   *
+   * @template T 그리드에 저장할 객체 타입
    *
-   * 사용 사례:
-   * - 빠른 Hit Test (마우스 클릭 시 어떤 마커/폴리곤인지 찾기)
-   * - 30,000개 항목 → 클릭 위치 주변 ~10개만 체크 (3,000배 빠름)
+   * @example
+   * ```typescript
+   * const grid = new SpatialHashGrid<Marker>(50);
+   * grid.insert(marker, { x: 100, y: 200, width: 30, height: 40 });
+   * const nearby = grid.query(105, 205, 10); // (105, 205) 주변 10px 반경
+   * ```
    */
 
   var SpatialHashGrid =
@@ -1476,20 +1715,301 @@
      */
 
 
-    SpatialHashGrid.prototype.stats = function () {
-      var totalCellItems = 0;
-      this.grid.forEach(function (items) {
-        totalCellItems += items.length;
-      });
-      return {
-        totalCells: this.grid.size,
-        totalItems: this.itemToCells.size,
-        avgItemsPerCell: this.grid.size > 0 ? totalCellItems / this.grid.size : 0
-      };
+    SpatialHashGrid.prototype.stats = function () {
+      var totalCellItems = 0;
+      this.grid.forEach(function (items) {
+        totalCellItems += items.length;
+      });
+      return {
+        totalCells: this.grid.size,
+        totalItems: this.itemToCells.size,
+        avgItemsPerCell: this.grid.size > 0 ? totalCellItems / this.grid.size : 0
+      };
+    };
+
+    return SpatialHashGrid;
+  }();
+
+  /**
+   * @fileoverview 폴리곤 렌더링을 위한 유틸리티 및 팩토리 함수
+   *
+   * 이 파일은 WoongCanvasLayer의 POLYGON 모드에서 사용하는 폴리곤 렌더링
+   * 함수들을 제공합니다. 다양한 상태(기본, 선택, 호버)에 따른 렌더링과
+   * 도넛 폴리곤(구멍이 있는 폴리곤) 지원을 포함합니다.
+   *
+   * ## 주요 기능
+   * - **폴리곤 그리기**: Canvas 2D API를 사용한 폴리곤 렌더링
+   * - **도넛 폴리곤 지원**: evenodd fill rule을 사용한 구멍 처리
+   * - **상태별 렌더링**: 기본/선택/호버 상태에 따른 색상 및 스타일 적용
+   * - **팩토리 함수**: 렌더링 함수를 쉽게 생성할 수 있는 헬퍼
+   *
+   * @version 2.2.1
+   * @since 2.0.0
+   * @author 박건웅
+   */
+
+  /**
+   * 폴리곤 그리기 헬퍼 함수
+   *
+   * Canvas 2D API를 사용하여 폴리곤을 그리는 핵심 함수입니다.
+   * 도넛 폴리곤(구멍이 있는 폴리곤)도 지원합니다.
+   *
+   * @param ctx - Canvas 2D 렌더링 컨텍스트
+   * @param polygonOffsets - 변환된 폴리곤 좌표 배열
+   * @param isDonutPolygon - 도넛 폴리곤 여부
+   * @param fillColor - 채우기 색상
+   * @param strokeColor - 테두리 색상
+   * @param lineWidth - 테두리 두께
+   *
+   * @example
+   * ```typescript
+   * drawPolygon({
+   *   ctx,
+   *   polygonOffsets: [[[[100, 200], [200, 200], [200, 300], [100, 300]]]],
+   *   isDonutPolygon: false,
+   *   fillColor: 'rgba(255, 0, 0, 0.5)',
+   *   strokeColor: 'rgba(255, 0, 0, 1)',
+   *   lineWidth: 2
+   * });
+   * ```
+   */
+  var drawPolygon = function (_a) {
+    var ctx = _a.ctx,
+        polygonOffsets = _a.polygonOffsets,
+        isDonutPolygon = _a.isDonutPolygon,
+        fillColor = _a.fillColor,
+        strokeColor = _a.strokeColor,
+        lineWidth = _a.lineWidth;
+
+    for (var _i = 0, polygonOffsets_1 = polygonOffsets; _i < polygonOffsets_1.length; _i++) {
+      var multiPolygon = polygonOffsets_1[_i];
+
+      if (isDonutPolygon) {
+        ctx.beginPath(); // 1. 외부 폴리곤 그리기
+
+        if (multiPolygon[0] && multiPolygon[0].length > 0) {
+          ctx.moveTo(multiPolygon[0][0][0], multiPolygon[0][0][1]);
+
+          for (var i = 1; i < multiPolygon[0].length; i++) {
+            ctx.lineTo(multiPolygon[0][i][0], multiPolygon[0][i][1]);
+          }
+
+          ctx.closePath();
+        } // 2. 내부 폴리곤 (구멍들) 그리기 - 같은 path에 추가
+
+
+        for (var j = 1; j < multiPolygon.length; j++) {
+          var innerPolygon = multiPolygon[j];
+          if (innerPolygon.length === 0) continue;
+          ctx.moveTo(innerPolygon[0][0], innerPolygon[0][1]);
+
+          for (var i = 1; i < innerPolygon.length; i++) {
+            ctx.lineTo(innerPolygon[i][0], innerPolygon[i][1]);
+          }
+
+          ctx.closePath();
+        } // 3. evenodd fill rule로 구멍 뚫기
+
+
+        ctx.fillStyle = fillColor;
+        ctx.fill('evenodd'); // 4. 외곽선 그리기
+
+        ctx.strokeStyle = strokeColor;
+        ctx.lineWidth = lineWidth;
+        ctx.stroke();
+      } else {
+        // 일반 폴리곤
+        for (var _b = 0, multiPolygon_1 = multiPolygon; _b < multiPolygon_1.length; _b++) {
+          var polygonGroup = multiPolygon_1[_b];
+          if (!polygonGroup.length) continue;
+          ctx.beginPath();
+          var firstPoint = polygonGroup[0];
+          ctx.moveTo(firstPoint[0], firstPoint[1]);
+
+          for (var i = 1; i < polygonGroup.length; i++) {
+            var point = polygonGroup[i];
+            ctx.lineTo(point[0], point[1]);
+          }
+
+          ctx.closePath();
+          ctx.fillStyle = fillColor;
+          ctx.strokeStyle = strokeColor;
+          ctx.lineWidth = lineWidth;
+          ctx.fill();
+          ctx.stroke();
+        }
+      }
+    }
+  };
+  /**
+   * 폴리곤 Base Layer 렌더링 함수 팩토리
+   *
+   * 기본 상태의 폴리곤들을 렌더링하는 함수를 생성합니다.
+   * 선택된 폴리곤들은 Event Layer에서 렌더링되므로 제외됩니다.
+   *
+   * @param baseFillColor - 기본 폴리곤 채우기 색상
+   * @param baseStrokeColor - 기본 폴리곤 테두리 색상
+   * @param baseLineWidth - 기본 폴리곤 테두리 두께
+   * @returns Base Layer 렌더링 함수
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   *
+   * @example
+   * ```typescript
+   * const renderBase = renderPolygonBase(
+   *   'rgba(255, 100, 100, 0.5)',  // 기본 채우기 색상
+   *   'rgba(200, 50, 50, 0.8)',    // 기본 테두리 색상
+   *   2                             // 기본 테두리 두께
+   * );
+   * ```
+   */
+
+  var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth) {
+    return function (_a) {
+      var ctx = _a.ctx,
+          items = _a.items,
+          selectedIds = _a.selectedIds,
+          utils = _a.utils;
+
+      for (var _i = 0, items_1 = items; _i < items_1.length; _i++) {
+        var item = items_1[_i]; // 선택된 항목은 Event Layer에서 그림
+
+        if (selectedIds.has(item.id)) continue;
+        if (!item.paths) continue;
+        var polygonOffsets = utils.getOrComputePolygonOffsets(item);
+        if (!polygonOffsets) continue;
+        drawPolygon({
+          ctx: ctx,
+          polygonOffsets: polygonOffsets,
+          isDonutPolygon: item.isDonutPolygon || false,
+          fillColor: baseFillColor,
+          strokeColor: baseStrokeColor,
+          lineWidth: baseLineWidth
+        });
+      }
+    };
+  };
+  /**
+   * 폴리곤 Event Layer 렌더링 함수 팩토리
+   *
+   * 선택, 호버, 활성 상태의 폴리곤들을 렌더링하는 함수를 생성합니다.
+   * 다양한 상태에 따른 색상과 스타일을 지원하며, fallback 메커니즘을 제공합니다.
+   *
+   * ## 상태별 렌더링 우선순위
+   * 1. **Hovered**: 마우스가 올라간 폴리곤 (최우선)
+   * 2. **Active**: 마지막으로 선택된 폴리곤
+   * 3. **Selected**: 선택된 폴리곤들
+   * 4. **Base**: 기본 상태 (fallback)
+   *
+   * @param baseFillColor - 기본 폴리곤 채우기 색상 (필수, fallback용)
+   * @param baseStrokeColor - 기본 폴리곤 테두리 색상 (필수, fallback용)
+   * @param baseLineWidth - 기본 폴리곤 테두리 두께 (필수, fallback용)
+   * @param selectedFillColor - 선택된 폴리곤 채우기 색상 (선택, 기본값: baseFillColor)
+   * @param selectedStrokeColor - 선택된 폴리곤 테두리 색상 (선택, 기본값: baseStrokeColor)
+   * @param selectedLineWidth - 선택된 폴리곤 테두리 두께 (선택, 기본값: baseLineWidth)
+   * @param activeFillColor - 마지막 선택된 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
+   * @param activeStrokeColor - 마지막 선택된 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
+   * @param activeLineWidth - 마지막 선택된 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
+   * @param hoveredFillColor - Hover 시 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
+   * @param hoveredStrokeColor - Hover 시 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
+   * @param hoveredLineWidth - Hover 시 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
+   * @returns Event Layer 렌더링 함수
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   *
+   * @example
+   * ```typescript
+   * const renderEvent = renderPolygonEvent(
+   *   'rgba(255, 100, 100, 0.5)',  // baseFillColor
+   *   'rgba(200, 50, 50, 0.8)',    // baseStrokeColor
+   *   2,                            // baseLineWidth
+   *   'rgba(255, 193, 7, 0.7)',    // selectedFillColor
+   *   'rgba(255, 152, 0, 1)',      // selectedStrokeColor
+   *   4                             // selectedLineWidth
+   * );
+   * ```
+   */
+
+  var renderPolygonEvent = function (baseFillColor, baseStrokeColor, baseLineWidth, selectedFillColor, selectedStrokeColor, selectedLineWidth, activeFillColor, activeStrokeColor, activeLineWidth, hoveredFillColor, hoveredStrokeColor, hoveredLineWidth) {
+    // 기본값 설정 (base 기준)
+    var _selectedFillColor = selectedFillColor || baseFillColor;
+
+    var _selectedStrokeColor = selectedStrokeColor || baseStrokeColor;
+
+    var _selectedLineWidth = selectedLineWidth || baseLineWidth;
+
+    var _activeFillColor = activeFillColor || _selectedFillColor;
+
+    var _activeStrokeColor = activeStrokeColor || _selectedStrokeColor;
+
+    var _activeLineWidth = activeLineWidth || _selectedLineWidth;
+
+    var _hoveredFillColor = hoveredFillColor || _selectedFillColor;
+
+    var _hoveredStrokeColor = hoveredStrokeColor || _selectedStrokeColor;
+
+    var _hoveredLineWidth = hoveredLineWidth || _selectedLineWidth;
+
+    return function (_a) {
+      var ctx = _a.ctx,
+          hoveredItem = _a.hoveredItem,
+          utils = _a.utils,
+          selectedItems = _a.selectedItems,
+          selectedItem = _a.selectedItem; // 1. 선택된 항목들 그리기 (마지막 선택 항목과 호버된 항목 제외)
+
+      if (selectedItems === null || selectedItems === void 0 ? void 0 : selectedItems.length) {
+        for (var _i = 0, selectedItems_1 = selectedItems; _i < selectedItems_1.length; _i++) {
+          var item = selectedItems_1[_i]; // 마지막 선택 항목과 호버된 항목은 나중에 따로 그림
+
+          if (item.id === (selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.id) || (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id) === item.id) continue;
+          if (!item.paths) continue;
+          var polygonOffsets = utils.getOrComputePolygonOffsets(item);
+          if (!polygonOffsets) continue;
+          drawPolygon({
+            ctx: ctx,
+            polygonOffsets: polygonOffsets,
+            isDonutPolygon: item.isDonutPolygon || false,
+            fillColor: _selectedFillColor,
+            strokeColor: _selectedStrokeColor,
+            lineWidth: _selectedLineWidth
+          });
+        }
+      } // 2. 마지막 선택된 항목 그리기 (호버되지 않은 경우)
+
+
+      if ((selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.paths) && (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id) !== selectedItem.id) {
+        var polygonOffsets = utils.getOrComputePolygonOffsets(selectedItem);
+
+        if (polygonOffsets) {
+          drawPolygon({
+            ctx: ctx,
+            polygonOffsets: polygonOffsets,
+            isDonutPolygon: selectedItem.isDonutPolygon || false,
+            fillColor: _activeFillColor,
+            strokeColor: _activeStrokeColor,
+            lineWidth: _activeLineWidth
+          });
+        }
+      } // 3. 호버된 항목 그리기 (가장 위에 표시)
+
+
+      if (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.paths) {
+        var polygonOffsets = utils.getOrComputePolygonOffsets(hoveredItem);
+        if (!polygonOffsets) return;
+        var isSelected = selectedItems === null || selectedItems === void 0 ? void 0 : selectedItems.some(function (item) {
+          return item.id === hoveredItem.id;
+        });
+        drawPolygon({
+          ctx: ctx,
+          polygonOffsets: polygonOffsets,
+          isDonutPolygon: hoveredItem.isDonutPolygon || false,
+          fillColor: isSelected ? _activeFillColor : _hoveredFillColor,
+          strokeColor: isSelected ? _activeStrokeColor : _hoveredStrokeColor,
+          lineWidth: isSelected ? _activeLineWidth : _hoveredLineWidth
+        });
+      }
     };
-
-    return SpatialHashGrid;
-  }();
+  };
 
   var cn$3 = classNames__default["default"].bind(styles$1);
   function MintMapCore(_a) {
@@ -5431,233 +5951,6 @@
     }))));
   }
 
-  /**
-   * 폴리곤 렌더링 유틸리티
-   *
-   * 이 파일은 폴리곤 렌더링을 위한 헬퍼 함수와 팩토리 함수를 제공합니다.
-   */
-
-  /**
-   * 폴리곤 그리기 헬퍼 함수 (도넛 폴리곤 지원)
-   */
-  var drawPolygon = function (_a) {
-    var ctx = _a.ctx,
-        polygonOffsets = _a.polygonOffsets,
-        isDonutPolygon = _a.isDonutPolygon,
-        fillColor = _a.fillColor,
-        strokeColor = _a.strokeColor,
-        lineWidth = _a.lineWidth;
-
-    for (var _i = 0, polygonOffsets_1 = polygonOffsets; _i < polygonOffsets_1.length; _i++) {
-      var multiPolygon = polygonOffsets_1[_i];
-
-      if (isDonutPolygon) {
-        ctx.beginPath(); // 1. 외부 폴리곤 그리기
-
-        if (multiPolygon[0] && multiPolygon[0].length > 0) {
-          ctx.moveTo(multiPolygon[0][0][0], multiPolygon[0][0][1]);
-
-          for (var i = 1; i < multiPolygon[0].length; i++) {
-            ctx.lineTo(multiPolygon[0][i][0], multiPolygon[0][i][1]);
-          }
-
-          ctx.closePath();
-        } // 2. 내부 폴리곤 (구멍들) 그리기 - 같은 path에 추가
-
-
-        for (var j = 1; j < multiPolygon.length; j++) {
-          var innerPolygon = multiPolygon[j];
-          if (innerPolygon.length === 0) continue;
-          ctx.moveTo(innerPolygon[0][0], innerPolygon[0][1]);
-
-          for (var i = 1; i < innerPolygon.length; i++) {
-            ctx.lineTo(innerPolygon[i][0], innerPolygon[i][1]);
-          }
-
-          ctx.closePath();
-        } // 3. evenodd fill rule로 구멍 뚫기
-
-
-        ctx.fillStyle = fillColor;
-        ctx.fill('evenodd'); // 4. 외곽선 그리기
-
-        ctx.strokeStyle = strokeColor;
-        ctx.lineWidth = lineWidth;
-        ctx.stroke();
-      } else {
-        // 일반 폴리곤
-        for (var _b = 0, multiPolygon_1 = multiPolygon; _b < multiPolygon_1.length; _b++) {
-          var polygonGroup = multiPolygon_1[_b];
-          if (!polygonGroup.length) continue;
-          ctx.beginPath();
-          var firstPoint = polygonGroup[0];
-          ctx.moveTo(firstPoint[0], firstPoint[1]);
-
-          for (var i = 1; i < polygonGroup.length; i++) {
-            var point = polygonGroup[i];
-            ctx.lineTo(point[0], point[1]);
-          }
-
-          ctx.closePath();
-          ctx.fillStyle = fillColor;
-          ctx.strokeStyle = strokeColor;
-          ctx.lineWidth = lineWidth;
-          ctx.fill();
-          ctx.stroke();
-        }
-      }
-    }
-  };
-  /**
-   * 폴리곤 Base 렌더링 함수
-   *
-   * @param baseFillColor 기본 폴리곤 채우기 색상
-   * @param baseStrokeColor 기본 폴리곤 테두리 색상
-   * @param baseLineWidth 기본 폴리곤 테두리 두께
-   * @returns Base Layer 렌더링 함수
-   *
-   * @example
-   * const renderBase = renderPolygonBase(
-   *   'rgba(255, 100, 100, 0.5)',
-   *   'rgba(200, 50, 50, 0.8)',
-   *   2
-   * );
-   */
-
-  var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth) {
-    return function (_a) {
-      var ctx = _a.ctx,
-          items = _a.items,
-          selectedIds = _a.selectedIds,
-          utils = _a.utils;
-
-      for (var _i = 0, items_1 = items; _i < items_1.length; _i++) {
-        var item = items_1[_i]; // 선택된 항목은 Event Layer에서 그림
-
-        if (selectedIds.has(item.id)) continue;
-        if (!item.paths) continue;
-        var polygonOffsets = utils.getOrComputePolygonOffsets(item);
-        if (!polygonOffsets) continue;
-        drawPolygon({
-          ctx: ctx,
-          polygonOffsets: polygonOffsets,
-          isDonutPolygon: item.isDonutPolygon || false,
-          fillColor: baseFillColor,
-          strokeColor: baseStrokeColor,
-          lineWidth: baseLineWidth
-        });
-      }
-    };
-  };
-  /**
-   * 폴리곤 Event 렌더링 함수
-   *
-   * @param baseFillColor 기본 폴리곤 채우기 색상 (필수, fallback용)
-   * @param baseStrokeColor 기본 폴리곤 테두리 색상 (필수, fallback용)
-   * @param baseLineWidth 기본 폴리곤 테두리 두께 (필수, fallback용)
-   * @param selectedFillColor 선택된 폴리곤 채우기 색상 (선택, 기본값: baseFillColor)
-   * @param selectedStrokeColor 선택된 폴리곤 테두리 색상 (선택, 기본값: baseStrokeColor)
-   * @param selectedLineWidth 선택된 폴리곤 테두리 두께 (선택, 기본값: baseLineWidth)
-   * @param activeFillColor 마지막 선택된 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
-   * @param activeStrokeColor 마지막 선택된 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
-   * @param activeLineWidth 마지막 선택된 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
-   * @param hoveredFillColor Hover 시 폴리곤 채우기 색상 (선택, 기본값: selectedFillColor)
-   * @param hoveredStrokeColor Hover 시 폴리곤 테두리 색상 (선택, 기본값: selectedStrokeColor)
-   * @param hoveredLineWidth Hover 시 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
-   * @returns Event Layer 렌더링 함수
-   *
-   * @example
-   * const renderEvent = renderPolygonEvent(
-   *   'rgba(255, 100, 100, 0.5)',  // baseFillColor
-   *   'rgba(200, 50, 50, 0.8)',    // baseStrokeColor
-   *   2,                            // baseLineWidth
-   *   'rgba(255, 193, 7, 0.7)',    // selectedFillColor
-   *   'rgba(255, 152, 0, 1)',      // selectedStrokeColor
-   *   4                             // selectedLineWidth
-   * );
-   */
-
-  var renderPolygonEvent = function (baseFillColor, baseStrokeColor, baseLineWidth, selectedFillColor, selectedStrokeColor, selectedLineWidth, activeFillColor, activeStrokeColor, activeLineWidth, hoveredFillColor, hoveredStrokeColor, hoveredLineWidth) {
-    // 기본값 설정 (base 기준)
-    var _selectedFillColor = selectedFillColor || baseFillColor;
-
-    var _selectedStrokeColor = selectedStrokeColor || baseStrokeColor;
-
-    var _selectedLineWidth = selectedLineWidth || baseLineWidth;
-
-    var _activeFillColor = activeFillColor || _selectedFillColor;
-
-    var _activeStrokeColor = activeStrokeColor || _selectedStrokeColor;
-
-    var _activeLineWidth = activeLineWidth || _selectedLineWidth;
-
-    var _hoveredFillColor = hoveredFillColor || _selectedFillColor;
-
-    var _hoveredStrokeColor = hoveredStrokeColor || _selectedStrokeColor;
-
-    var _hoveredLineWidth = hoveredLineWidth || _selectedLineWidth;
-
-    return function (_a) {
-      var ctx = _a.ctx,
-          hoveredItem = _a.hoveredItem,
-          utils = _a.utils,
-          selectedItems = _a.selectedItems,
-          selectedItem = _a.selectedItem; // 1. 선택된 항목들 그리기 (마지막 선택 항목과 호버된 항목 제외)
-
-      if (selectedItems === null || selectedItems === void 0 ? void 0 : selectedItems.length) {
-        for (var _i = 0, selectedItems_1 = selectedItems; _i < selectedItems_1.length; _i++) {
-          var item = selectedItems_1[_i]; // 마지막 선택 항목과 호버된 항목은 나중에 따로 그림
-
-          if (item.id === (selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.id) || (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id) === item.id) continue;
-          if (!item.paths) continue;
-          var polygonOffsets = utils.getOrComputePolygonOffsets(item);
-          if (!polygonOffsets) continue;
-          drawPolygon({
-            ctx: ctx,
-            polygonOffsets: polygonOffsets,
-            isDonutPolygon: item.isDonutPolygon || false,
-            fillColor: _selectedFillColor,
-            strokeColor: _selectedStrokeColor,
-            lineWidth: _selectedLineWidth
-          });
-        }
-      } // 2. 마지막 선택된 항목 그리기 (호버되지 않은 경우)
-
-
-      if ((selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.paths) && (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id) !== selectedItem.id) {
-        var polygonOffsets = utils.getOrComputePolygonOffsets(selectedItem);
-
-        if (polygonOffsets) {
-          drawPolygon({
-            ctx: ctx,
-            polygonOffsets: polygonOffsets,
-            isDonutPolygon: selectedItem.isDonutPolygon || false,
-            fillColor: _activeFillColor,
-            strokeColor: _activeStrokeColor,
-            lineWidth: _activeLineWidth
-          });
-        }
-      } // 3. 호버된 항목 그리기 (가장 위에 표시)
-
-
-      if (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.paths) {
-        var polygonOffsets = utils.getOrComputePolygonOffsets(hoveredItem);
-        if (!polygonOffsets) return;
-        var isSelected = selectedItems === null || selectedItems === void 0 ? void 0 : selectedItems.some(function (item) {
-          return item.id === hoveredItem.id;
-        });
-        drawPolygon({
-          ctx: ctx,
-          polygonOffsets: polygonOffsets,
-          isDonutPolygon: hoveredItem.isDonutPolygon || false,
-          fillColor: isSelected ? _activeFillColor : _hoveredFillColor,
-          strokeColor: isSelected ? _activeStrokeColor : _hoveredStrokeColor,
-          lineWidth: isSelected ? _activeLineWidth : _hoveredLineWidth
-        });
-      }
-    };
-  };
-
   // 메인 컴포넌트
   // ============================================================================
 
@@ -5696,20 +5989,20 @@
     var divElement = divRef.current;
     var containerRef = React.useRef(null);
     var markerRef = React.useRef(); // --------------------------------------------------------------------------
-    // Konva Refs
+    // Konva Refs - Multi-Layer 아키텍처
     // --------------------------------------------------------------------------
 
     var stageRef = React.useRef(null);
     var baseLayerRef = React.useRef(null);
     var animationLayerRef = React.useRef(null);
     var eventLayerRef = React.useRef(null); // --------------------------------------------------------------------------
-    // Data Refs - 선택 및 Hover 상태 관리
+    // Data Refs - 데이터 동기화 및 상태 관리
     // --------------------------------------------------------------------------
 
     /** data prop을 ref로 추적 (stale closure 방지, useEffect에서 동기화) */
 
     var dataRef = React.useRef(data); // --------------------------------------------------------------------------
-    // State Refs - 선택 및 Hover 상태 관리
+    // State Refs - 선택 및 Hover 상태 관리 (성능 최적화)
     // --------------------------------------------------------------------------
 
     /** 상호작용 비활성화 상태 (Ref로 관리하여 클로저 문제 해결) */
@@ -5750,7 +6043,7 @@
      */
 
     var selectedItemsMapRef = React.useRef(new Map()); // --------------------------------------------------------------------------
-    // Drag Refs
+    // Drag Refs - 지도 드래그 상태 관리
     // --------------------------------------------------------------------------
 
     var draggingRef = React.useRef(false);
@@ -5759,7 +6052,7 @@
       x: 0,
       y: 0
     }); // --------------------------------------------------------------------------
-    // Performance Refs (캐싱 & 최적화)
+    // Performance Refs - 성능 최적화 (캐싱 & 인덱싱)
     // --------------------------------------------------------------------------
 
     /** 좌표 변환 결과 LRU 캐시 */
@@ -5774,7 +6067,7 @@
     /** 뷰포트 경계 캐시 (Viewport Culling) */
 
     var viewportRef = React.useRef(null); // --------------------------------------------------------------------------
-    // 유틸리티 함수: 뷰포트 관리
+    // 유틸리티 함수: 뷰포트 관리 (Viewport Culling)
     // --------------------------------------------------------------------------
 
     /**
@@ -5853,7 +6146,7 @@
 
       return result;
     }; // --------------------------------------------------------------------------
-    // 유틸리티 함수: 바운딩 박스 계산
+    // 유틸리티 함수: 바운딩 박스 계산 (Viewport Culling 최적화)
     // --------------------------------------------------------------------------
 
     /**
@@ -5967,11 +6260,14 @@
     var renderEvent = dataType === exports.CanvasDataType.MARKER ? props.renderEvent : function () {
       var polygonProps = props;
       return renderPolygonEvent(polygonProps.baseFillColor, polygonProps.baseStrokeColor, polygonProps.baseLineWidth, polygonProps.selectedFillColor, polygonProps.selectedStrokeColor, polygonProps.selectedLineWidth, polygonProps.activeFillColor, polygonProps.activeStrokeColor, polygonProps.activeLineWidth, polygonProps.hoveredFillColor, polygonProps.hoveredStrokeColor, polygonProps.hoveredLineWidth);
-    }();
+    }(); // --------------------------------------------------------------------------
+    // 렌더링 함수: Base Layer (기본 상태 렌더링)
+    // --------------------------------------------------------------------------
+
     /**
      * Base 레이어 렌더링 (뷰포트 컬링 적용, 선택된 마커 제외)
      *
-     * 🔥 최적화:
+     * 🔥 성능 최적화:
      * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
      * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
      * 3. 클로저로 최신 데이터 참조
@@ -6037,11 +6333,14 @@
 
 
       layer.batchDraw();
-    };
+    }; // --------------------------------------------------------------------------
+    // 렌더링 함수: Animation Layer (선택된 항목 애니메이션)
+    // --------------------------------------------------------------------------
+
     /**
      * Animation 레이어 렌더링 (선택된 마커 애니메이션)
      *
-     * 🔥 최적화: sceneFunc 내부에서 최신 items 참조
+     * 🔥 성능 최적화: sceneFunc 내부에서 최신 items 참조
      * - 선택 변경 시에만 재생성
      * - 지도 이동 시에는 기존 Animation 계속 실행
      */
@@ -6057,11 +6356,14 @@
         items: dataRef.current,
         utils: renderUtils
       });
-    };
+    }; // --------------------------------------------------------------------------
+    // 렌더링 함수: Event Layer (상호작용 상태 렌더링)
+    // --------------------------------------------------------------------------
+
     /**
      * Event 레이어 렌더링 (hover + 선택 상태 표시)
      *
-     * 🔥 최적화:
+     * 🔥 성능 최적화:
      * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
      * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
      * 3. 클로저로 최신 데이터 참조
@@ -6087,10 +6389,11 @@
         shape = new Konva__default["default"].Shape({
           name: 'event-render-shape',
           sceneFunc: function (context, shape) {
-            var ctx = context; // 클로저로 최신 ref 값 참조
+            var ctx = context; // 클로저로 최신 ref 값 참조 (안전한 처리)
 
             var selectedItems = Array.from(selectedItemsMapRef.current.values());
-            var hovered = hoveredItemRef.current; // topOnHover가 true이면 hover된 항목을 최상단에 렌더링
+            var hovered = hoveredItemRef.current;
+            var selectedItem = selectedItemRef.current; // topOnHover가 true이면 hover된 항목을 최상단에 렌더링
 
             if (topOnHover && hovered) {
               // 1. 먼저 일반 항목들 렌더링 (hover된 항목 제외)
@@ -6099,9 +6402,9 @@
                 hoveredItem: null,
                 utils: renderUtils,
                 selectedItems: selectedItems.filter(function (item) {
-                  return item.id !== hovered.id;
+                  return item && item.id !== hovered.id;
                 }),
-                selectedItem: selectedItemRef.current
+                selectedItem: selectedItem
               }); // 2. hover된 항목을 최상단에 렌더링
 
               var isHoveredInViewport = enableViewportCulling ? isInViewport(hovered) : true;
@@ -6112,7 +6415,7 @@
                   hoveredItem: hovered,
                   utils: renderUtils,
                   selectedItems: selectedItems,
-                  selectedItem: selectedItemRef.current
+                  selectedItem: selectedItem
                 });
               }
             } else {
@@ -6122,7 +6425,7 @@
                 hoveredItem: hovered,
                 utils: renderUtils,
                 selectedItems: selectedItems,
-                selectedItem: selectedItemRef.current
+                selectedItem: selectedItem
               });
             }
           },
@@ -6235,7 +6538,7 @@
         containerRef.current.style.transform = "translate(".concat(accumTranslateRef.current.x, "px, ").concat(accumTranslateRef.current.y, "px)");
       }
     }; // --------------------------------------------------------------------------
-    // Hit Test & 상태 관리
+    // Hit Test & 상태 관리 (이벤트 처리)
     // --------------------------------------------------------------------------
 
     /**
@@ -6405,7 +6708,7 @@
       }
     };
     /**
-     * 마우스 이동 이벤트 처리 (hover 감지)
+     * 마우스 이동 이벤트 처리 (hover 감지 및 상태 업데이트)
      */
 
 
@@ -6449,7 +6752,7 @@
       controller.setMapCursor('grab');
     };
     /**
-     * 마우스가 canvas를 벗어날 때 hover cleanup
+     * 마우스가 canvas를 벗어날 때 hover 상태 정리
      */
 
 
@@ -6509,7 +6812,7 @@
         }
       }
     }, [options]); // --------------------------------------------------------------------------
-    // Lifecycle: Konva 초기화 및 이벤트 리스너 등록
+    // Lifecycle: Konva 초기화 및 이벤트 리스너 등록 (컴포넌트 마운트)
     // --------------------------------------------------------------------------
 
     React.useEffect(function () {
@@ -6635,26 +6938,32 @@
       };
     }, []); // 초기화는 한 번만
     // --------------------------------------------------------------------------
-    // Lifecycle: disableInteraction 동기화
+    // Lifecycle: disableInteraction 동기화 (상호작용 상태 관리)
     // --------------------------------------------------------------------------
 
     React.useEffect(function () {
       disableInteractionRef.current = disableInteraction;
     }, [disableInteraction]); // --------------------------------------------------------------------------
-    // Lifecycle: 외부 selectedItems 동기화
+    // Lifecycle: 외부 selectedItems 동기화 (선택 상태 관리)
     // --------------------------------------------------------------------------
 
     React.useEffect(function () {
       if (!stageRef.current) return; // externalSelectedItems가 undefined면 외부 제어 안 함
 
-      if (externalSelectedItems === undefined) return; // 외부에서 전달된 selectedItems로 동기화
+      if (externalSelectedItems === undefined) return; // 외부에서 전달된 selectedItems로 동기화 (안전한 처리)
 
       var newSelectedIds = new Set();
-      var newSelectedItemsMap = new Map();
-      externalSelectedItems.forEach(function (item) {
-        newSelectedIds.add(item.id);
-        newSelectedItemsMap.set(item.id, item);
-      });
+      var newSelectedItemsMap = new Map(); // selectedItems가 배열인지 확인하고 안전하게 처리
+
+      if (Array.isArray(externalSelectedItems)) {
+        externalSelectedItems.forEach(function (item) {
+          if (item && item.id) {
+            newSelectedIds.add(item.id);
+            newSelectedItemsMap.set(item.id, item);
+          }
+        });
+      }
+
       selectedIdsRef.current = newSelectedIds;
       selectedItemsMapRef.current = newSelectedItemsMap; // 렌더링
 
@@ -6663,17 +6972,17 @@
       doRenderEvent();
     }, [externalSelectedItems]); // 배열 자체를 dependency로 사용
     // --------------------------------------------------------------------------
-    // Lifecycle: 외부 selectedItem 변경 시 Event Layer 리렌더링
+    // Lifecycle: 외부 selectedItem 변경 시 Event Layer 리렌더링 (단일 선택 관리)
     // --------------------------------------------------------------------------
 
     React.useEffect(function () {
-      if (!stageRef.current) return; // Ref 동기화
+      if (!stageRef.current) return; // Ref 동기화 (안전한 처리)
 
-      selectedItemRef.current = externalSelectedItem; // selectedItem이 변경되면 Event Layer만 다시 그림
+      selectedItemRef.current = externalSelectedItem || null; // selectedItem이 변경되면 Event Layer만 다시 그림
 
       doRenderEvent();
     }, [externalSelectedItem]); // --------------------------------------------------------------------------
-    // Lifecycle: 데이터 변경 시 렌더링
+    // Lifecycle: 데이터 변경 시 렌더링 (데이터 동기화 및 최적화)
     // --------------------------------------------------------------------------
 
     React.useEffect(function () {
@@ -6730,7 +7039,10 @@
       selectedItemsMapRef.current = newSelectedItemsMap; // 즉시 렌더링
 
       renderAllImmediate();
-    }, [data]);
+    }, [data]); // --------------------------------------------------------------------------
+    // Render - React Portal을 통한 DOM 렌더링
+    // --------------------------------------------------------------------------
+
     return reactDom.createPortal(React__default["default"].createElement("div", {
       ref: containerRef,
       style: {
@@ -9620,6 +9932,7 @@
   exports.calculateTextBoxWidth = calculateTextBoxWidth;
   exports.computeMarkerOffset = computeMarkerOffset;
   exports.computePolygonOffsets = computePolygonOffsets;
+  exports.drawPolygon = drawPolygon;
   exports.getClusterInfo = getClusterInfo;
   exports.getMapOfType = getMapOfType;
   exports.hexToRgba = hexToRgba;
@@ -9627,6 +9940,8 @@
   exports.isPointInPolygon = isPointInPolygon;
   exports.isPointInPolygonData = isPointInPolygonData;
   exports.log = log;
+  exports.renderPolygonBase = renderPolygonBase;
+  exports.renderPolygonEvent = renderPolygonEvent;
   exports.useKonvaMarkerContext = useKonvaMarkerContext;
   exports.useMarkerMoving = useMarkerMoving;
   exports.useMintMapController = useMintMapController;