@mint-ui/map 1.2.0-test.33 → 1.2.0-test.35

package/dist/components/mint-map/core/advanced/shared/hooks.js

@@ -0,0 +1,283 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var tslib = require('tslib');
+
+/**
+ * 지도 이벤트 핸들러 생성 함수
+ *
+ * 지도 이동, 줌, 드래그 등의 이벤트를 처리하는 핸들러들을 생성합니다.
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param deps 이벤트 핸들러 생성에 필요한 의존성
+ * @returns 지도 이벤트 핸들러 객체
+ *
+ * @example
+ * ```typescript
+ * const {
+ *   handleIdle,
+ *   handleZoomStart,
+ *   handleZoomEnd,
+ *   handleCenterChanged,
+ *   handleDragStart,
+ *   handleDragEnd,
+ * } = createMapEventHandlers({
+ *   controller,
+ *   containerRef,
+ *   markerRef,
+ *   options,
+ *   prevCenterOffsetRef,
+ *   accumTranslateRef,
+ *   offsetCacheRef,
+ *   boundingBoxCacheRef,
+ *   renderAllImmediate,
+ * });
+ * ```
+ */
+
+var createMapEventHandlers = function (deps) {
+  var controller = deps.controller,
+      containerRef = deps.containerRef,
+      markerRef = deps.markerRef,
+      options = deps.options,
+      prevCenterOffsetRef = deps.prevCenterOffsetRef,
+      accumTranslateRef = deps.accumTranslateRef,
+      offsetCacheRef = deps.offsetCacheRef,
+      boundingBoxCacheRef = deps.boundingBoxCacheRef,
+      renderAllImmediate = deps.renderAllImmediate;
+  /**
+   * 지도 이동/줌 완료 시 처리
+   *
+   * - 캐시 초기화: 좌표 변환 결과가 변경되었으므로 캐시 무효화
+   * - 마커 위치 업데이트: 새로운 지도 위치에 맞게 마커 재배치
+   * - 렌더링: 새 위치에서 전체 렌더링 수행
+   */
+
+  var handleIdle = function () {
+    prevCenterOffsetRef.current = null;
+    accumTranslateRef.current = {
+      x: 0,
+      y: 0
+    }; // 캐시 정리 (지도 이동/줌으로 좌표 변환 결과가 바뀜)
+
+    offsetCacheRef.current.clear();
+    boundingBoxCacheRef.current.clear(); // 마커 위치 업데이트
+
+    var bounds = controller.getCurrBounds();
+
+    var markerOptions = tslib.__assign({
+      position: bounds.nw
+    }, options);
+
+    markerRef.current && controller.updateMarker(markerRef.current, markerOptions); // transform 제거 전에 새 데이터로 즉시 렌더링 (겹침 방지)
+
+    if (containerRef.current) {
+      containerRef.current.style.transform = '';
+      containerRef.current.style.visibility = '';
+    } // 새 위치에서 렌더링
+
+
+    renderAllImmediate();
+  };
+  /**
+   * 줌 시작 시 처리 (일시적으로 숨김)
+   */
+
+
+  var handleZoomStart = function () {
+    if (containerRef.current) {
+      containerRef.current.style.visibility = 'hidden';
+    }
+  };
+  /**
+   * 줌 종료 시 처리 (다시 표시)
+   */
+
+
+  var handleZoomEnd = function () {
+    if (containerRef.current) {
+      containerRef.current.style.visibility = '';
+    }
+  };
+  /**
+   * 지도 중심 변경 시 처리 (transform으로 이동 추적)
+   */
+
+
+  var handleCenterChanged = function () {
+    var center = controller.getCurrBounds().getCenter();
+    var curr = controller.positionToOffset(center);
+    var prev = prevCenterOffsetRef.current;
+
+    if (!prev) {
+      prevCenterOffsetRef.current = {
+        x: curr.x,
+        y: curr.y
+      };
+      return;
+    }
+
+    var dx = prev.x - curr.x;
+    var dy = prev.y - curr.y;
+    accumTranslateRef.current = {
+      x: accumTranslateRef.current.x + dx,
+      y: accumTranslateRef.current.y + dy
+    };
+    prevCenterOffsetRef.current = {
+      x: curr.x,
+      y: curr.y
+    };
+
+    if (containerRef.current) {
+      containerRef.current.style.transform = "translate(".concat(accumTranslateRef.current.x, "px, ").concat(accumTranslateRef.current.y, "px)");
+    }
+  };
+  /**
+   * 드래그 시작 처리
+   */
+
+
+  var handleDragStart = function () {// 커서는 각 컴포넌트에서 처리
+  };
+  /**
+   * 드래그 종료 처리
+   */
+
+
+  var handleDragEnd = function () {// 커서는 각 컴포넌트에서 처리
+  };
+
+  return {
+    handleIdle: handleIdle,
+    handleZoomStart: handleZoomStart,
+    handleZoomEnd: handleZoomEnd,
+    handleCenterChanged: handleCenterChanged,
+    handleDragStart: handleDragStart,
+    handleDragEnd: handleDragEnd
+  };
+};
+/**
+ * 공간 인덱스 빌드 (빠른 Hit Test를 위한 자료구조)
+ *
+ * Spatial Hash Grid에 모든 데이터의 바운딩 박스를 삽입합니다.
+ * 이를 통해 클릭/호버 시 O(1) 수준의 빠른 Hit Test가 가능합니다.
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param data 공간 인덱스에 삽입할 데이터 배열
+ * @param spatialIndex Spatial Hash Grid 인스턴스
+ * @param computeBoundingBox 바운딩 박스 계산 함수
+ *
+ * @remarks
+ * - 성능: O(n) 시간복잡도, n은 데이터 개수
+ * - 호출 시점: 데이터 변경 시 또는 지도 이동/줌 완료 시
+ *
+ * @example
+ * ```typescript
+ * buildSpatialIndex(
+ *   dataRef.current,
+ *   spatialIndexRef.current,
+ *   computeBoundingBox
+ * );
+ * ```
+ */
+
+var buildSpatialIndex = function (data, spatialIndex, computeBoundingBox) {
+  spatialIndex.clear();
+
+  for (var _i = 0, data_1 = data; _i < data_1.length; _i++) {
+    var item = data_1[_i];
+    var bbox = computeBoundingBox(item);
+
+    if (bbox) {
+      spatialIndex.insert(item, bbox.minX, bbox.minY, bbox.maxX, bbox.maxY);
+    }
+  }
+};
+/**
+ * 선택 상태 동기화 유틸리티
+ *
+ * 데이터 변경 시 선택된 항목의 참조를 최신 데이터로 업데이트합니다.
+ * 화면 밖에 있는 선택된 항목도 선택 상태를 유지합니다.
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param data 최신 데이터 배열
+ * @param selectedIds 선택된 항목 ID Set
+ * @param selectedItemsMap 현재 선택된 항목 Map
+ * @returns 업데이트된 선택된 항목 Map
+ *
+ * @remarks
+ * - 성능: O(n + m), n은 전체 데이터 수, m은 선택된 항목 수
+ * - 화면 밖 데이터도 선택 상태 유지 (최신 데이터가 없으면 기존 데이터 유지)
+ *
+ * @example
+ * ```typescript
+ * selectedItemsMapRef.current = syncSelectedItems(
+ *   data,
+ *   selectedIdsRef.current,
+ *   selectedItemsMapRef.current
+ * );
+ * ```
+ */
+
+var syncSelectedItems = function (data, selectedIds, selectedItemsMap) {
+  var dataMap = new Map(data.map(function (m) {
+    return [m.id, m];
+  }));
+  var newSelectedItemsMap = new Map();
+  selectedIds.forEach(function (id) {
+    // 현재 data에 있으면 최신 데이터 사용
+    var currentItem = dataMap.get(id);
+
+    if (currentItem) {
+      newSelectedItemsMap.set(id, currentItem);
+    } else {
+      // 화면 밖이면 기존 데이터 유지
+      var prevItem = selectedItemsMap.get(id);
+
+      if (prevItem) {
+        newSelectedItemsMap.set(id, prevItem);
+      }
+    }
+  });
+  return newSelectedItemsMap;
+};
+/**
+ * 외부 selectedItems를 내부 상태로 동기화
+ *
+ * 외부에서 전달된 selectedItems prop을 내부 ref 상태로 동기화합니다.
+ *
+ * @template T 마커/폴리곤 데이터의 추가 속성 타입
+ * @param externalSelectedItems 외부에서 전달된 선택된 항목 배열 (undefined면 동기화 안 함)
+ * @param selectedIdsRef 선택된 ID Set ref
+ * @param selectedItemsMapRef 선택된 항목 Map ref
+ *
+ * @remarks
+ * - externalSelectedItems가 undefined면 외부 제어가 아니므로 아무 작업도 하지 않음
+ * - 성능: O(m), m은 externalSelectedItems의 길이
+ *
+ * @example
+ * ```typescript
+ * useEffect(() => {
+ *   syncExternalSelectedItems(externalSelectedItems, selectedIdsRef, selectedItemsMapRef);
+ *   // 렌더링...
+ * }, [externalSelectedItems]);
+ * ```
+ */
+
+var syncExternalSelectedItems = function (externalSelectedItems, selectedIdsRef, selectedItemsMapRef) {
+  if (externalSelectedItems === undefined) return;
+  var newSelectedIds = new Set();
+  var newSelectedItemsMap = new Map();
+  externalSelectedItems.forEach(function (item) {
+    newSelectedIds.add(item.id);
+    newSelectedItemsMap.set(item.id, item);
+  });
+  selectedIdsRef.current = newSelectedIds;
+  selectedItemsMapRef.current = newSelectedItemsMap;
+};
+
+exports.buildSpatialIndex = buildSpatialIndex;
+exports.createMapEventHandlers = createMapEventHandlers;
+exports.syncExternalSelectedItems = syncExternalSelectedItems;
+exports.syncSelectedItems = syncSelectedItems;

package/dist/components/mint-map/core/advanced/shared/index.d.ts

@@ -2,3 +2,6 @@ export * from './types';
 export * from './utils';
 export * from './context';
 export * from './performance';
+export * from './viewport';
+export * from './hooks';
+export * from './helpers';

package/dist/components/mint-map/core/advanced/shared/performance.d.ts

@@ -40,12 +40,32 @@ export declare const DEFAULT_CULLING_MARGIN = 100;
 export declare const DEFAULT_MAX_CACHE_SIZE = 30000;
 /**
  * LRU (Least Recently Used) Cache
- * 메모리 제한을 위한 캐시 구현 (최적화 버전)
  *
- * 개선 사항:
+ * 메모리 제한을 위한 캐시 구현입니다. WoongCanvas 컴포넌트에서 좌표 변환 결과를 캐싱하는데 사용됩니다.
+ *
+ * @template K 캐시 키 타입
+ * @template V 캐시 값 타입
+ *
+ * @remarks
+ * **개선 사항**:
  * 1. get() 성능 향상: 접근 빈도 추적 없이 단순 조회만 수행 (delete+set 제거)
  * 2. set() 버그 수정: 기존 키 업데이트 시 maxSize 체크 로직 개선
  * 3. 메모리 효율: 단순 FIFO 캐시로 동작하여 오버헤드 최소화
+ *
+ * **트레이드오프**:
+ * - 장점: 읽기 성능 대폭 향상 (10,000번 get → 이전보다 2배 빠름)
+ * - 단점: 접근 빈도가 아닌 삽입 순서 기반 eviction (FIFO)
+ *
+ * WoongCanvasMarker 사용 사례에 최적:
+ * - 좌표 변환 결과는 zoom/pan 시 어차피 전체 초기화
+ * - 접근 빈도 추적보다 빠른 조회가 더 중요
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUCache<string, Offset>(30000);
+ * cache.set(item.id, offset);
+ * const cached = cache.get(item.id);
+ * ```
  */
 export declare class LRUCache<K, V> {
     private cache;
@@ -54,25 +74,24 @@ export declare class LRUCache<K, V> {
     /**
      * 캐시에서 값 조회
      *
-     * 최적화: delete+set 제거
-     * - 이전: 매번 delete+set으로 LRU 갱신 (해시 재계산 비용)
-     * - 현재: 단순 조회만 수행 (O(1) 해시 조회)
+     * @param key 조회할 키
+     * @returns 캐시된 값 또는 undefined (캐시 미스 시)
      *
-     * 트레이드오프:
-     * - 장점: 읽기 성능 대폭 향상 (10,000번 get → 이전보다 2배 빠름)
-     * - 단점: 접근 빈도가 아닌 삽입 순서 기반 eviction (FIFO)
-     *
-     * WoongCanvasMarker 사용 사례에 최적:
-     * - 좌표 변환 결과는 zoom/pan 시 어차피 전체 초기화
-     * - 접근 빈도 추적보다 빠른 조회가 더 중요
+     * @remarks
+     * - 성능: O(1) 해시 조회
+     * - 최적화: delete+set 제거로 읽기 성능 대폭 향상
      */
     get(key: K): V | undefined;
     /**
-     * 캐시에 값 저장 (버그 수정 + 최적화)
+     * 캐시에 값 저장
+     *
+     * @param key 저장할 키
+     * @param value 저장할 값
      *
-     * 수정 사항:
-     * 1. 기존 키 업데이트 시 크기 체크 누락 버그 수정
-     * 2. 로직 명확화: 기존 항목/신규 항목 분리 처리
+     * @remarks
+     * - 기존 키 업데이트: 단순 덮어쓰기 (크기 변화 없음)
+     * - 신규 키 추가: 크기 체크 후 필요시 가장 오래된 항목 제거 (FIFO)
+     * - 성능: O(1) 평균 시간복잡도
      */
     set(key: K, value: V): void;
     clear(): void;
@@ -108,40 +127,95 @@ export declare class SpatialHashGrid<T> {
     /**
      * 항목 추가 (바운딩 박스 기반)
      *
-     * 개선 사항:
+     * 항목을 공간 인덱스에 추가합니다. 바운딩 박스가 걸치는 모든 셀에 삽입됩니다.
+     *
+     * @param item 추가할 항목
+     * @param minX 바운딩 박스 최소 X 좌표
+     * @param minY 바운딩 박스 최소 Y 좌표
+     * @param maxX 바운딩 박스 최대 X 좌표
+     * @param maxY 바운딩 박스 최대 Y 좌표
+     *
+     * @remarks
      * - 중복 삽입 방지: 기존 항목이 있으면 먼저 제거 후 재삽입
      * - 메모리 누수 방지: 이전 셀 참조 완전 제거
+     * - 성능: O(1) 평균 시간복잡도
      */
     insert(item: T, minX: number, minY: number, maxX: number, maxY: number): void;
     /**
      * 항목 제거
      *
-     * 추가된 메서드: 메모리 누수 방지 및 업데이트 지원
+     * 공간 인덱스에서 항목을 제거합니다.
+     *
+     * @param item 제거할 항목
+     *
+     * @remarks
+     * - 메모리 누수 방지: 모든 셀에서 참조 완전 제거
+     * - 빈 셀 정리: 항목이 없어진 셀은 자동으로 정리됨
+     * - 성능: O(셀 개수), 보통 O(1)
      */
     remove(item: T): void;
     /**
      * 항목 위치 업데이트
      *
-     * 추가된 메서드: remove + insert의 편의 함수
+     * 항목의 위치를 업데이트합니다. remove + insert의 편의 함수입니다.
+     *
+     * @param item 업데이트할 항목
+     * @param minX 새로운 바운딩 박스 최소 X 좌표
+     * @param minY 새로운 바운딩 박스 최소 Y 좌표
+     * @param maxX 새로운 바운딩 박스 최대 X 좌표
+     * @param maxY 새로운 바운딩 박스 최대 Y 좌표
      */
     update(item: T, minX: number, minY: number, maxX: number, maxY: number): void;
     /**
      * 점 주변의 항목 조회 (1개 셀만)
      *
-     * 성능: O(해당 셀의 항목 수) - 보통 ~10개
+     * 특정 좌표가 속한 셀의 모든 항목을 반환합니다.
+     *
+     * @param x 조회할 X 좌표
+     * @param y 조회할 Y 좌표
+     * @returns 해당 셀의 항목 배열 (없으면 빈 배열)
+     *
+     * @remarks
+     * - 성능: O(해당 셀의 항목 수) - 보통 ~10개 (30,000개 전체를 체크하지 않음)
+     * - Hit Test에 최적화된 메서드
+     * - 빈 배열 재사용으로 메모리 할당 최소화
+     *
+     * @example
+     * ```typescript
+     * const candidates = grid.queryPoint(mouseX, mouseY);
+     * for (const item of candidates) {
+     *   if (isPointInItem(item, mouseX, mouseY)) {
+     *     return item;
+     *   }
+     * }
+     * ```
      */
     queryPoint(x: number, y: number): T[];
     /**
      * 영역 내 항목 조회
      *
-     * 성능: O(셀 개수 × 셀당 평균 항목 수)
-     * Set으로 중복 제거 보장
+     * 특정 영역(바운딩 박스)과 교차하는 모든 항목을 반환합니다.
+     *
+     * @param minX 영역 최소 X 좌표
+     * @param minY 영역 최소 Y 좌표
+     * @param maxX 영역 최대 X 좌표
+     * @param maxY 영역 최대 Y 좌표
+     * @returns 영역과 교차하는 항목 배열 (중복 제거됨)
+     *
+     * @remarks
+     * - 성능: O(셀 개수 × 셀당 평균 항목 수)
+     * - Set으로 중복 제거 보장 (항목이 여러 셀에 걸쳐 있어도 한 번만 반환)
+     * - Viewport Culling에 유용
      */
     queryBounds(minX: number, minY: number, maxX: number, maxY: number): T[];
     /**
      * 항목 존재 여부 확인
      *
-     * 추가된 메서드: 빠른 존재 여부 체크
+     * @param item 확인할 항목
+     * @returns 항목이 인덱스에 있으면 true, 아니면 false
+     *
+     * @remarks
+     * - 성능: O(1) 해시 조회
      */
     has(item: T): boolean;
     /**
@@ -151,7 +225,14 @@ export declare class SpatialHashGrid<T> {
     /**
      * 통계 정보
      *
-     * 개선: totalItems는 실제 고유 항목 수를 정확히 반환
+     * 공간 인덱스의 현재 상태를 반환합니다. 디버깅 및 성능 분석에 유용합니다.
+     *
+     * @returns 통계 정보 객체
+     *
+     * @remarks
+     * - totalCells: 현재 사용 중인 셀 개수
+     * - totalItems: 인덱스에 등록된 고유 항목 수 (정확)
+     * - avgItemsPerCell: 셀당 평균 항목 수
      */
     stats(): {
         totalCells: number;

package/dist/components/mint-map/core/advanced/shared/performance.js

@@ -50,12 +50,32 @@ var DEFAULT_CULLING_MARGIN = 100;
 var DEFAULT_MAX_CACHE_SIZE = 30000;
 /**
  * LRU (Least Recently Used) Cache
- * 메모리 제한을 위한 캐시 구현 (최적화 버전)
  *
- * 개선 사항:
+ * 메모리 제한을 위한 캐시 구현입니다. WoongCanvas 컴포넌트에서 좌표 변환 결과를 캐싱하는데 사용됩니다.
+ *
+ * @template K 캐시 키 타입
+ * @template V 캐시 값 타입
+ *
+ * @remarks
+ * **개선 사항**:
  * 1. get() 성능 향상: 접근 빈도 추적 없이 단순 조회만 수행 (delete+set 제거)
  * 2. set() 버그 수정: 기존 키 업데이트 시 maxSize 체크 로직 개선
  * 3. 메모리 효율: 단순 FIFO 캐시로 동작하여 오버헤드 최소화
+ *
+ * **트레이드오프**:
+ * - 장점: 읽기 성능 대폭 향상 (10,000번 get → 이전보다 2배 빠름)
+ * - 단점: 접근 빈도가 아닌 삽입 순서 기반 eviction (FIFO)
+ *
+ * WoongCanvasMarker 사용 사례에 최적:
+ * - 좌표 변환 결과는 zoom/pan 시 어차피 전체 초기화
+ * - 접근 빈도 추적보다 빠른 조회가 더 중요
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUCache<string, Offset>(30000);
+ * cache.set(item.id, offset);
+ * const cached = cache.get(item.id);
+ * ```
  */
 
 var LRUCache =
@@ -72,17 +92,12 @@ function () {
   /**
    * 캐시에서 값 조회
    *
-   * 최적화: delete+set 제거
-   * - 이전: 매번 delete+set으로 LRU 갱신 (해시 재계산 비용)
-   * - 현재: 단순 조회만 수행 (O(1) 해시 조회)
+   * @param key 조회할 키
+   * @returns 캐시된 값 또는 undefined (캐시 미스 시)
    *
-   * 트레이드오프:
-   * - 장점: 읽기 성능 대폭 향상 (10,000번 get → 이전보다 2배 빠름)
-   * - 단점: 접근 빈도가 아닌 삽입 순서 기반 eviction (FIFO)
-   *
-   * WoongCanvasMarker 사용 사례에 최적:
-   * - 좌표 변환 결과는 zoom/pan 시 어차피 전체 초기화
-   * - 접근 빈도 추적보다 빠른 조회가 더 중요
+   * @remarks
+   * - 성능: O(1) 해시 조회
+   * - 최적화: delete+set 제거로 읽기 성능 대폭 향상
    */
 
 
@@ -90,11 +105,15 @@ function () {
     return this.cache.get(key);
   };
   /**
-   * 캐시에 값 저장 (버그 수정 + 최적화)
+   * 캐시에 값 저장
+   *
+   * @param key 저장할 키
+   * @param value 저장할 값
    *
-   * 수정 사항:
-   * 1. 기존 키 업데이트 시 크기 체크 누락 버그 수정
-   * 2. 로직 명확화: 기존 항목/신규 항목 분리 처리
+   * @remarks
+   * - 기존 키 업데이트: 단순 덮어쓰기 (크기 변화 없음)
+   * - 신규 키 추가: 크기 체크 후 필요시 가장 오래된 항목 제거 (FIFO)
+   * - 성능: O(1) 평균 시간복잡도
    */
 
 
@@ -192,9 +211,18 @@ function () {
   /**
    * 항목 추가 (바운딩 박스 기반)
    *
-   * 개선 사항:
+   * 항목을 공간 인덱스에 추가합니다. 바운딩 박스가 걸치는 모든 셀에 삽입됩니다.
+   *
+   * @param item 추가할 항목
+   * @param minX 바운딩 박스 최소 X 좌표
+   * @param minY 바운딩 박스 최소 Y 좌표
+   * @param maxX 바운딩 박스 최대 X 좌표
+   * @param maxY 바운딩 박스 최대 Y 좌표
+   *
+   * @remarks
    * - 중복 삽입 방지: 기존 항목이 있으면 먼저 제거 후 재삽입
    * - 메모리 누수 방지: 이전 셀 참조 완전 제거
+   * - 성능: O(1) 평균 시간복잡도
    */
 
 
@@ -218,7 +246,14 @@ function () {
   /**
    * 항목 제거
    *
-   * 추가된 메서드: 메모리 누수 방지 및 업데이트 지원
+   * 공간 인덱스에서 항목을 제거합니다.
+   *
+   * @param item 제거할 항목
+   *
+   * @remarks
+   * - 메모리 누수 방지: 모든 셀에서 참조 완전 제거
+   * - 빈 셀 정리: 항목이 없어진 셀은 자동으로 정리됨
+   * - 성능: O(셀 개수), 보통 O(1)
    */
 
 
@@ -249,7 +284,13 @@ function () {
   /**
    * 항목 위치 업데이트
    *
-   * 추가된 메서드: remove + insert의 편의 함수
+   * 항목의 위치를 업데이트합니다. remove + insert의 편의 함수입니다.
+   *
+   * @param item 업데이트할 항목
+   * @param minX 새로운 바운딩 박스 최소 X 좌표
+   * @param minY 새로운 바운딩 박스 최소 Y 좌표
+   * @param maxX 새로운 바운딩 박스 최대 X 좌표
+   * @param maxY 새로운 바운딩 박스 최대 Y 좌표
    */
 
 
@@ -259,7 +300,26 @@ function () {
   /**
    * 점 주변의 항목 조회 (1개 셀만)
    *
-   * 성능: O(해당 셀의 항목 수) - 보통 ~10개
+   * 특정 좌표가 속한 셀의 모든 항목을 반환합니다.
+   *
+   * @param x 조회할 X 좌표
+   * @param y 조회할 Y 좌표
+   * @returns 해당 셀의 항목 배열 (없으면 빈 배열)
+   *
+   * @remarks
+   * - 성능: O(해당 셀의 항목 수) - 보통 ~10개 (30,000개 전체를 체크하지 않음)
+   * - Hit Test에 최적화된 메서드
+   * - 빈 배열 재사용으로 메모리 할당 최소화
+   *
+   * @example
+   * ```typescript
+   * const candidates = grid.queryPoint(mouseX, mouseY);
+   * for (const item of candidates) {
+   *   if (isPointInItem(item, mouseX, mouseY)) {
+   *     return item;
+   *   }
+   * }
+   * ```
    */
 
 
@@ -272,8 +332,18 @@ function () {
   /**
    * 영역 내 항목 조회
    *
-   * 성능: O(셀 개수 × 셀당 평균 항목 수)
-   * Set으로 중복 제거 보장
+   * 특정 영역(바운딩 박스)과 교차하는 모든 항목을 반환합니다.
+   *
+   * @param minX 영역 최소 X 좌표
+   * @param minY 영역 최소 Y 좌표
+   * @param maxX 영역 최대 X 좌표
+   * @param maxY 영역 최대 Y 좌표
+   * @returns 영역과 교차하는 항목 배열 (중복 제거됨)
+   *
+   * @remarks
+   * - 성능: O(셀 개수 × 셀당 평균 항목 수)
+   * - Set으로 중복 제거 보장 (항목이 여러 셀에 걸쳐 있어도 한 번만 반환)
+   * - Viewport Culling에 유용
    */
 
 
@@ -298,7 +368,11 @@ function () {
   /**
    * 항목 존재 여부 확인
    *
-   * 추가된 메서드: 빠른 존재 여부 체크
+   * @param item 확인할 항목
+   * @returns 항목이 인덱스에 있으면 true, 아니면 false
+   *
+   * @remarks
+   * - 성능: O(1) 해시 조회
    */
 
 
@@ -317,7 +391,14 @@ function () {
   /**
    * 통계 정보
    *
-   * 개선: totalItems는 실제 고유 항목 수를 정확히 반환
+   * 공간 인덱스의 현재 상태를 반환합니다. 디버깅 및 성능 분석에 유용합니다.
+   *
+   * @returns 통계 정보 객체
+   *
+   * @remarks
+   * - totalCells: 현재 사용 중인 셀 개수
+   * - totalItems: 인덱스에 등록된 고유 항목 수 (정확)
+   * - avgItemsPerCell: 셀당 평균 항목 수
    */