docs: 마이그레이션 문서 개선 (#145)

- Before (v0.1) / After (v0.2) 표기로 이전/현재 명확히 구분
- 이벤트 비교를 같은 수준으로 수정
- 불필요한 섹션 제거, 신규 기능 소개 제거
- 커스텀 오버레이 비교를 실제 v0.1 코드 기반으로

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: zeakd

website/src/content/docs/guides/migration-from-v1.mdx

@@ -4,117 +4,133 @@ category: guides
 order: 7
 ---
 
-## 요약
+0.2는 React 19 전용으로 재작성되었습니다.
 
-0.2는 React 19 전용으로 재작성되었습니다. 주요 변경 사항:
+## React 19 필수
 
-- **이벤트**: `<Listener>` 컴포넌트 제거 → `on*` props (기본), `useListener()` 훅 (escape hatch)
-- **인증 키**: `ncpClientId` (레거시) → `ncpKeyId` (표준)
-- **오버레이**: `<Overlay element={...}>` 제거 → `useOverlay()` 훅
-- **CustomOverlay**: 신규 컴포넌트
-- **InfoWindow**: children 대신 `content` prop (문자열)
-- **Layer**: `CadastralLayer`, `StreetLayer`, `TrafficLayer` 신규
+`peerDependencies`가 `react@^19.0.0`으로 변경되었습니다.
 
 ## 인증 키
 
-```diff
-- <NavermapsProvider ncpClientId="YOUR_KEY">
-+ <NavermapsProvider ncpKeyId="YOUR_KEY">
-```
+NCP 콘솔에서 발급받은 키를 `ncpKeyId`로 전달합니다.
+기존 `ncpClientId`도 동작하지만, `ncpKeyId`가 현재 NCP 표준입니다.
 
-`ncpClientId`, `govClientId`, `finClientId`도 호환되지만, `ncpKeyId`가 현재 표준입니다.
+```tsx
+<NavermapsProvider ncpKeyId="YOUR_NCP_KEY_ID">
+  <Container style={{ width: '100%', height: '400px' }}>
+    <NaverMap
+      defaultCenter={{ lat: 37.5666, lng: 126.9784 }}
+      defaultZoom={16}
+    />
+  </Container>
+</NavermapsProvider>
+```
 
 ## 이벤트 핸들링
 
-0.1의 `<Listener>` 컴포넌트가 제거되었습니다.
-표준 이벤트는 `on*` props로 처리합니다.
-
-```diff
-- import { Marker, Listener } from 'react-naver-maps';
-+ import { Marker } from 'react-naver-maps';
-
-- <Marker position={pos}>
--   <Listener type="click" listener={(e) => handleClick(e)} />
-- </Marker>
-+ <Marker position={pos} onClick={(e) => handleClick(e)} />
-```
-
-`on*` props에 없는 이벤트(KVO changed, 생명주기 등)는 `useListener()` 훅을 사용합니다.
+`<Listener>` 컴포넌트가 제거되었습니다. `on*` props를 사용합니다.
 
 ```tsx
-import { useListener, useMap } from 'react-naver-maps';
-
-const map = useMap();
-useListener(map, 'idle', () => console.log('idle'));
+// Before (v0.1)
+<Marker position={position}>
+  <Listener type="click" listener={handleClick} />
+  <Listener type="rightclick" listener={handleRightClick} />
+</Marker>
+
+// After (v0.2)
+<Marker position={position} onClick={handleClick} onRightclick={handleRightClick} />
 ```
 
-## Overlay 컴포넌트
+`on*` props에 없는 이벤트(KVO changed, idle 등)는 `useListener()` 훅을 사용합니다.
 
-0.1의 `<Overlay element={...}>` 컴포넌트가 제거되었습니다.
-네이티브 오버레이 인스턴스를 React에 연결하려면 `useOverlay()` 훅을 사용합니다.
+```tsx
+function IdleTracker() {
+  const map = useMap();
 
-```diff
-- import { Overlay } from 'react-naver-maps';
-- const [marker] = useState(() => new navermaps.Marker({ position }));
-- <Overlay element={marker} />
+  useListener(map, 'idle', () => {
+    console.log('지도 이동 완료');
+  });
 
-+ import { useOverlay, useMap } from 'react-naver-maps';
-+ const map = useMap();
-+ const marker = useOverlay(() => new navermaps.Marker({ position, map }));
+  return null;
+}
 ```
 
-공식 [CustomOverlay 패턴](https://navermaps.github.io/maps.js.ncp/docs/tutorial-6-CustomOverlay.html)(OverlayView 상속)도 `useOverlay`로 연결할 수 있습니다.
-자세한 내용은 [useOverlay API Reference](/react-naver-maps/api-references/use-overlay/)를 참고하세요.
-
-## InfoWindow
+## 커스텀 오버레이
 
-0.1에서 children으로 React 엘리먼트를 전달하던 방식은 더 이상 지원되지 않습니다.
-`content` prop에 HTML 문자열을 전달하세요.
+`<Overlay element={...}>` + `<Listener>` 조합이 제거되었습니다.
+`useOverlay()` + `useListener()` 훅으로 대체됩니다.
 
-```diff
-- <InfoWindow position={pos}>
--   <div>정보</div>
-- </InfoWindow>
-
-+ <InfoWindow position={pos} content="<div>정보</div>" />
+```tsx
+// Before (v0.1)
+function MyCustomMarkers() {
+  const navermaps = useNavermaps();
+
+  const [marker1] = useState(
+    () =>
+      new navermaps.Marker({
+        position: { lat: 37.5666, lng: 126.9784 },
+      }),
+  );
+
+  const marker2Ref = useRef(null);
+  if (!marker2Ref.current) {
+    marker2Ref.current = new navermaps.Marker({
+      position: { lat: 37.5657, lng: 126.9755 },
+    });
+  }
+  const marker2 = marker2Ref.current;
+
+  useListener(marker1, 'click', () => alert('서울시청'));
+
+  return (
+    <>
+      <Overlay element={marker1} />
+      <Overlay element={marker2}>
+        <Listener type="click" listener={() => alert('덕수궁')} />
+      </Overlay>
+    </>
+  );
+}
+
+// After (v0.2)
+function MyCustomMarkers() {
+  const navermaps = useNavermaps();
+  const map = useMap();
+
+  const marker1 = useOverlay(
+    () =>
+      new navermaps.Marker({
+        map,
+        position: { lat: 37.5666, lng: 126.9784 },
+      }),
+  );
+
+  const marker2 = useOverlay(
+    () =>
+      new navermaps.Marker({
+        map,
+        position: { lat: 37.5657, lng: 126.9755 },
+      }),
+  );
+
+  useListener(marker1, 'click', () => alert('서울시청'));
+  useListener(marker2, 'click', () => alert('덕수궁'));
+
+  return null;
+}
 ```
 
-React 컴포넌트를 렌더링해야 한다면 `<CustomOverlay>`를 사용하세요.
-
-## 스크립트 로딩
-
-`loadNavermapsScript()`가 내부 전용으로 변경되었습니다.
-Provider 외부에서 미리 로드하려면 `preloadNavermaps()`를 사용합니다.
-
-```diff
-- import { loadNavermapsScript } from 'react-naver-maps';
-- await loadNavermapsScript({ ncpClientId: 'KEY' });
-
-+ import { preloadNavermaps } from 'react-naver-maps';
-+ preloadNavermaps({ ncpKeyId: 'KEY' });
-```
+네이버맵 공식 [CustomOverlay 패턴](https://navermaps.github.io/maps.js.ncp/docs/tutorial-6-CustomOverlay.html)(OverlayView 상속)도 동일하게 `useOverlay`로 연결할 수 있습니다.
+자세한 내용은 [useOverlay API Reference](/react-naver-maps/api-references/use-overlay/)를 참고하세요.
 
-## 제거된 export 목록
+## 제거된 API
 
 | 0.1                          | 0.2 대체                              |
 | ---------------------------- | ------------------------------------- |
-| `<Listener>`                 | `on*` props 또는 `useListener()` 훅   |
 | `<Overlay>`                  | `useOverlay()` 훅                     |
-| `EventTargetContext`         | 내부 전용                             |
-| `useContainerContext()`      | 내부 전용                             |
+| `<Listener>`                 | `on*` props 또는 `useListener()` 훅   |
+| `useListener()` (0.1 버전)   | `useListener()` (콜백 안정화 개선)    |
+| `EventTargetContext`         | 제거                                  |
+| `useContainerContext()`      | 제거                                  |
 | `loadNavermapsScript()`      | `preloadNavermaps()`                  |
 | `RenderAfterNavermapsLoaded` | `<NavermapsProvider>` + `<Container>` |
-
-## 신규 API
-
-| API                  | 설명                                       |
-| -------------------- | ------------------------------------------ |
-| `useOverlay()`       | 네이티브 오버레이를 React 생명주기에 연결  |
-| `useListener()`      | 네이티브 이벤트 escape hatch               |
-| `<CustomOverlay>`    | React children을 지도 좌표에 Portal 렌더링 |
-| `<CadastralLayer>`   | 지적도 레이어                              |
-| `<StreetLayer>`      | 거리뷰 레이어                              |
-| `<TrafficLayer>`     | 실시간 교통 레이어                         |
-| `preloadNavermaps()` | Provider 외부에서 스크립트 미리 로드       |
-| `useKVO()`           | KVO 속성 감시                              |
-| `useControlledKVO()` | controlled 패턴 KVO 동기화                 |