@deepnoid/canvas 0.1.84 → 0.1.86

package/skills/deepnoid-canvas/references/components.md

@@ -0,0 +1,197 @@
+# 컴포넌트 API 레퍼런스
+
+## AnnotationEditor
+
+이미지 위에 어노테이션을 생성하고 편집할 수 있는 컴포넌트.
+
+### Import
+
+```tsx
+import { AnnotationEditor } from '@deepnoid/canvas';
+import type { AnnotationCanvasHandle } from '@deepnoid/canvas';
+```
+
+### Props
+
+| Prop | Type | Required | Default | 설명 |
+|------|------|----------|---------|------|
+| `image` | `string` | ✅ | — | 이미지 URL |
+| `drawing` | `AnnotationCanvasDrawing` | ✅ | — | 그리기 모드 및 스타일 설정 |
+| `events` | `AnnotationCanvasEvents` | ✅ | — | 이미지 로드 이벤트 핸들러 (빈 객체 가능) |
+| `annotations` | `Annotation[]` | — | `[]` | 어노테이션 목록 |
+| `setAnnotations` | `Dispatch<SetStateAction<Annotation[] \| undefined>>` | — | — | 어노테이션 변경 콜백 |
+| `options` | `AnnotationCanvasOptions` | — | — | 줌/팬 및 기타 옵션 |
+| `enableHotkeys` | `boolean` | — | `true` | 단축키 활성화 여부 |
+| `keepCrossOnImageChange` | `boolean` | — | `false` | 이미지 변경 시 가이드 십자선 유지 |
+
+### ref (AnnotationCanvasHandle)
+
+```tsx
+const canvasRef = useRef<AnnotationCanvasHandle>(null);
+<AnnotationEditor ref={canvasRef} ... />
+```
+
+| Method | 설명 |
+|--------|------|
+| `resetImageSize()` | 캔버스 크기 및 줌을 초기 상태로 리셋 |
+
+### 전체 사용 예시
+
+```tsx
+import { useState, useRef } from 'react';
+import { AnnotationEditor, DrawMode } from '@deepnoid/canvas';
+import type { Annotation, ApplyAnnotationStyle, AnnotationCanvasHandle } from '@deepnoid/canvas';
+
+const applyStyle: ApplyAnnotationStyle = ({ variant, context, annotation, drawLineSize, zoom }) => {
+  if (variant === 'drawRect') {
+    context.strokeStyle = annotation.selected ? '#00FF00' : '#FF4136';
+    context.lineWidth = drawLineSize / zoom;
+    if (annotation.type === DrawMode.RECTANGLE) {
+      context.strokeRect(annotation.x, annotation.y, annotation.width, annotation.height);
+    } else if (annotation.type === DrawMode.POLYGON) {
+      context.beginPath();
+      annotation.points.forEach((p, i) => i === 0 ? context.moveTo(p.x, p.y) : context.lineTo(p.x, p.y));
+      context.closePath();
+      context.stroke();
+    }
+  }
+  if (variant === 'drawText') {
+    if (annotation.label) {
+      context.fillStyle = '#FF4136';
+      context.font = `bold ${14 / zoom}px sans-serif`;
+      const tx = annotation.type === DrawMode.RECTANGLE ? annotation.x : Math.min(...annotation.points.map(p => p.x));
+      const ty = (annotation.type === DrawMode.RECTANGLE ? annotation.y : Math.min(...annotation.points.map(p => p.y))) - 5;
+      context.fillText(annotation.label.name, tx, ty);
+    }
+  }
+};
+
+function MyEditor() {
+  const canvasRef = useRef<AnnotationCanvasHandle>(null);
+  const [annotations, setAnnotations] = useState<Annotation[]>([]);
+  const [mode, setMode] = useState(DrawMode.RECTANGLE);
+
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <AnnotationEditor
+        ref={canvasRef}
+        image="https://example.com/image.jpg"
+        annotations={annotations}
+        setAnnotations={setAnnotations}
+        drawing={{
+          mode,
+          color: '#FF4136',
+          lineSize: 2,
+          applyStyle,
+          label: { id: 1, name: 'defect', type: 'bbox' },
+        }}
+        events={{
+          onImageLoadSuccess: () => console.log('loaded'),
+          onImageLoadError: (err) => console.error(err),
+        }}
+        options={{
+          panZoomEnabled: true,
+          zoom: { min: 0.5, max: 4, step: 0.9 },
+        }}
+        enableHotkeys
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## AnnotationViewer
+
+이미지 위에 어노테이션을 읽기 전용으로 표시하는 컴포넌트.
+
+### Import
+
+```tsx
+import { AnnotationViewer } from '@deepnoid/canvas';
+```
+
+### Props
+
+| Prop | Type | Required | Default | 설명 |
+|------|------|----------|---------|------|
+| `image` | `string` | ✅ | — | 이미지 URL |
+| `drawing` | `Pick<AnnotationCanvasDrawing, 'lineSize' \| 'applyStyle'>` | ✅ | — | 렌더링 스타일 설정 (`mode`, `color`, `label` 불필요) |
+| `events` | `Pick<AnnotationCanvasEvents, 'onImageLoadSuccess' \| 'onImageLoadError'>` | ✅ | — | 이미지 로드 이벤트 핸들러 (빈 객체 가능) |
+| `annotations` | `Annotation[]` | — | `[]` | 표시할 어노테이션 목록 |
+| `options` | `AnnotationCanvasOptions` | — | — | 줌/팬 및 기타 옵션 |
+| `enableHotkeys` | `boolean` | — | `true` | 단축키 활성화 여부 |
+
+> **AnnotationEditor와의 차이**: `drawing`에서 `mode`, `color`, `label`이 제외됩니다. `setAnnotations`도 불필요합니다. `keepCrossOnImageChange`도 없습니다.
+
+### 전체 사용 예시
+
+```tsx
+import { AnnotationViewer } from '@deepnoid/canvas';
+
+function MyViewer({ annotations }) {
+  return (
+    <div style={{ width: '100%', height: 600 }}>
+      <AnnotationViewer
+        image="https://example.com/image.jpg"
+        annotations={annotations}
+        drawing={{
+          lineSize: 2,
+          applyStyle, // Editor와 동일한 함수 재사용 가능
+        }}
+        events={{
+          onImageLoadSuccess: () => console.log('loaded'),
+        }}
+        options={{
+          panZoomEnabled: true,
+          zoom: { min: 0.5, max: 4 },
+        }}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Props 상세 타입
+
+### AnnotationCanvasDrawing
+
+```typescript
+type AnnotationCanvasDrawing = {
+  lineSize: number;                   // 선 두께 (필수)
+  applyStyle: ApplyAnnotationStyle;   // 커스텀 렌더링 함수 (필수)
+  label?: Label;                      // 새 어노테이션에 부여할 라벨 (Editor 전용)
+  mode?: DrawMode;                    // 그리기 모드 (Editor 전용)
+  color?: string;                     // HEX 색상, 새 어노테이션 그리기 시 사용 (Editor 전용)
+};
+```
+
+### AnnotationCanvasOptions
+
+```typescript
+type AnnotationCanvasOptions = {
+  panZoomEnabled?: boolean;           // 줌/팬 활성화 (기본: false)
+  zoom?: {
+    min?: number;                     // 최소 줌 (기본: 0.1)
+    max?: number;                     // 최대 줌 (기본: Infinity)
+    step?: number;                    // 줌 단계 (기본: 0.9)
+  };
+  ZoomButton?: ComponentType<{        // 커스텀 줌 버튼
+    onClick: () => void;
+    children: ReactNode;
+  }>;
+  resetOnImageChange?: boolean;       // 이미지 변경 시 줌 리셋 (기본: false)
+};
+```
+
+### AnnotationCanvasEvents
+
+```typescript
+type AnnotationCanvasEvents = {
+  onImageLoadSuccess?: () => void;
+  onImageLoadError?: (error: Error) => void;
+};
+```

package/skills/deepnoid-canvas/references/types.md

@@ -0,0 +1,231 @@
+# 타입 API 레퍼런스
+
+모든 public 타입은 `@deepnoid/canvas`에서 직접 import합니다.
+
+## Import
+
+```tsx
+import { DrawMode } from '@deepnoid/canvas';
+import type {
+  Annotation,
+  Rectangle,
+  Label,
+  ApplyAnnotationStyle,
+  AnnotationCanvasHandle,
+} from '@deepnoid/canvas';
+```
+
+---
+
+## DrawMode (Enum)
+
+어노테이션 그리기 모드를 지정하는 enum.
+
+```typescript
+enum DrawMode {
+  RECTANGLE = 'RECTANGLE',
+  POLYGON = 'POLYGON',
+}
+```
+
+### 사용 예시
+
+```tsx
+import { DrawMode } from '@deepnoid/canvas';
+
+// drawing.mode에 사용
+<AnnotationEditor drawing={{ mode: DrawMode.RECTANGLE, ... }} />
+
+// 어노테이션 타입 판별
+if (annotation.type === DrawMode.RECTANGLE) {
+  // RectangleAnnotation으로 좁혀짐
+  console.log(annotation.x, annotation.y, annotation.width, annotation.height);
+} else if (annotation.type === DrawMode.POLYGON) {
+  // PolygonAnnotation으로 좁혀짐
+  console.log(annotation.points);
+}
+```
+
+---
+
+## Annotation (Union Type)
+
+```typescript
+type Annotation = RectangleAnnotation | PolygonAnnotation;
+```
+
+`type` 필드로 discriminated union 판별.
+
+### RectangleAnnotation
+
+```typescript
+type RectangleAnnotation = {
+  type: DrawMode.RECTANGLE;
+  x: number;            // 좌상단 X (원본 이미지 px)
+  y: number;            // 좌상단 Y (원본 이미지 px)
+  width: number;        // 너비 (원본 이미지 px)
+  height: number;       // 높이 (원본 이미지 px)
+  label?: Label;        // 라벨 정보
+  color?: 'success' | 'warning' | 'danger';  // 상태 색상
+  selected?: boolean;   // 선택 상태 (엔진 내부 관리)
+  showOnlySelected?: boolean;
+};
+```
+
+### PolygonAnnotation
+
+```typescript
+type PolygonAnnotation = {
+  type: DrawMode.POLYGON;
+  points: { x: number; y: number }[];  // 꼭짓점 배열 (원본 이미지 px)
+  label?: Label;
+  color?: 'success' | 'warning' | 'danger';
+  selected?: boolean;
+  showOnlySelected?: boolean;
+};
+```
+
+### 데이터 예시
+
+```typescript
+// RectangleAnnotation
+const rect: Annotation = {
+  type: DrawMode.RECTANGLE,
+  x: 100,
+  y: 50,
+  width: 200,
+  height: 150,
+  label: { id: 1, name: 'defect', type: 'bbox' },
+  color: 'danger',
+};
+
+// PolygonAnnotation
+const polygon: Annotation = {
+  type: DrawMode.POLYGON,
+  points: [
+    { x: 100, y: 100 },
+    { x: 250, y: 80 },
+    { x: 300, y: 200 },
+    { x: 150, y: 250 },
+  ],
+  label: { id: 2, name: 'crack', type: 'polygon' },
+  color: 'warning',
+};
+```
+
+---
+
+## Rectangle (Type)
+
+사각형의 기하 정보만 담는 순수 타입. 어노테이션이 아닌 좌표 계산 등에 활용.
+
+```typescript
+type Rectangle = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+```
+
+---
+
+## Label (Type)
+
+어노테이션에 부여하는 라벨 정보.
+
+```typescript
+type Label = {
+  id: number;     // 라벨 고유 ID
+  name: string;   // 표시 이름 (applyStyle의 drawText에서 사용)
+  type: string;   // 라벨 분류 (자유 문자열, 예: 'bbox', 'polygon', 'seed')
+};
+```
+
+### 사용 예시
+
+```tsx
+const labels: Label[] = [
+  { id: 1, name: '결함', type: 'defect' },
+  { id: 2, name: '균열', type: 'crack' },
+  { id: 3, name: '정상', type: 'normal' },
+];
+
+// drawing.label에 설정하면 새로 그리는 어노테이션에 자동 부여
+<AnnotationEditor
+  drawing={{
+    mode: DrawMode.RECTANGLE,
+    label: labels[0],
+    lineSize: 2,
+    applyStyle,
+  }}
+  ...
+/>
+```
+
+---
+
+## ApplyAnnotationStyle (Type)
+
+어노테이션 렌더링 스타일을 완전 제어하는 콜백 함수 타입.
+
+```typescript
+type ApplyAnnotationStyle = (params: ApplyAnnotationStyleParams) => void;
+
+type ApplyAnnotationStyleParams = {
+  variant: 'drawRect' | 'drawText';       // 현재 렌더링 단계
+  context: CanvasRenderingContext2D;        // Canvas 2D 컨텍스트
+  annotation: Annotation;                  // 렌더링 대상 어노테이션
+  drawLineSize: number;                    // 설정된 선 두께 (현재 2px 고정)
+  zoom: number;                            // 현재 줌 배율
+};
+```
+
+### variant 설명
+
+| variant | 호출 시점 | 설정해야 할 Canvas 속성 |
+|---------|----------|------------------------|
+| `'drawRect'` | 도형 렌더링 | `strokeStyle`, `fillStyle`, `lineWidth`, `setLineDash` + 실제 도형 그리기 (`strokeRect`, `beginPath`/`stroke` 등) |
+| `'drawText'` | 라벨 텍스트 렌더링 | `fillStyle`, `font`, `textBaseline` + 실제 텍스트 그리기 (`fillText`) |
+
+상세 예제는 [apply-style.md](apply-style.md) 참조.
+
+---
+
+## AnnotationCanvasHandle (Interface)
+
+`ref`를 통해 캔버스를 프로그래밍 방식으로 제어.
+
+```typescript
+interface AnnotationCanvasHandle {
+  resetImageSize(): void;   // 캔버스 크기 및 줌을 초기 상태로 리셋
+}
+```
+
+### 사용 예시
+
+```tsx
+import { useRef } from 'react';
+import type { AnnotationCanvasHandle } from '@deepnoid/canvas';
+
+const ref = useRef<AnnotationCanvasHandle>(null);
+
+// 줌 리셋 버튼
+<button onClick={() => ref.current?.resetImageSize()}>초기화</button>
+<AnnotationEditor ref={ref} ... />
+```
+
+---
+
+## 전체 Export 요약
+
+| Export | Kind | import 방식 |
+|--------|------|------------|
+| `AnnotationEditor` | Component | `import { AnnotationEditor } from '@deepnoid/canvas'` |
+| `AnnotationViewer` | Component | `import { AnnotationViewer } from '@deepnoid/canvas'` |
+| `DrawMode` | Enum (value) | `import { DrawMode } from '@deepnoid/canvas'` |
+| `Annotation` | Type | `import type { Annotation } from '@deepnoid/canvas'` |
+| `Rectangle` | Type | `import type { Rectangle } from '@deepnoid/canvas'` |
+| `Label` | Type | `import type { Label } from '@deepnoid/canvas'` |
+| `ApplyAnnotationStyle` | Type | `import type { ApplyAnnotationStyle } from '@deepnoid/canvas'` |
+| `AnnotationCanvasHandle` | Interface | `import type { AnnotationCanvasHandle } from '@deepnoid/canvas'` |

package/skills/deepnoid-canvas/rules/annotations.md

@@ -0,0 +1,152 @@
+# 어노테이션 데이터 규칙
+
+## 규칙 1: 모든 어노테이션에 type 필드가 필수다
+
+`Annotation` 타입은 discriminated union이므로, `type` 필드가 없으면 타입 추론이 동작하지 않습니다.
+
+```tsx
+// ✅ 올바른 사용 — type 필드 포함
+const rect: Annotation = {
+  type: DrawMode.RECTANGLE,
+  x: 100,
+  y: 50,
+  width: 200,
+  height: 150,
+};
+
+const polygon: Annotation = {
+  type: DrawMode.POLYGON,
+  points: [
+    { x: 100, y: 100 },
+    { x: 200, y: 100 },
+    { x: 150, y: 200 },
+  ],
+};
+
+// ❌ 잘못된 사용 — type 누락
+const rect = { x: 100, y: 50, width: 200, height: 150 };
+```
+
+## 규칙 2: DrawMode enum을 사용해야 한다
+
+문자열 리터럴 대신 반드시 `DrawMode` enum을 사용합니다.
+
+```tsx
+import { DrawMode } from '@deepnoid/canvas';
+
+// ✅ 올바른 사용
+{ type: DrawMode.RECTANGLE, ... }
+{ type: DrawMode.POLYGON, ... }
+
+// ❌ 잘못된 사용 — 문자열 직접 사용 (타입 에러)
+{ type: 'RECTANGLE', ... }
+{ type: 'rectangle', ... }
+```
+
+## 규칙 3: 좌표는 원본 이미지 기준 픽셀 좌표다
+
+캔버스에 표시된 좌표가 아니라, 원본 이미지의 픽셀 좌표를 사용합니다. 줌/팬 변환은 엔진이 자동 처리합니다.
+
+```tsx
+// ✅ 올바른 사용 — 원본 이미지 좌표
+// 원본 이미지가 1920x1080일 때:
+{ type: DrawMode.RECTANGLE, x: 500, y: 300, width: 200, height: 150 }
+
+// ❌ 잘못된 사용 — 화면 표시 좌표를 그대로 사용
+// 캔버스가 50%로 축소되어 있어도 원본 좌표를 사용해야 함
+```
+
+## 규칙 4: RectangleAnnotation의 width/height는 양수여야 한다
+
+사용자가 역방향으로 드래그하면 엔진이 자동 정규화하지만, 외부에서 직접 생성 시 양수 값이어야 합니다.
+
+```tsx
+// ✅ 올바른 사용
+{ type: DrawMode.RECTANGLE, x: 100, y: 100, width: 200, height: 150 }
+
+// ❌ 잘못된 사용 — 음수 크기
+{ type: DrawMode.RECTANGLE, x: 300, y: 250, width: -200, height: -150 }
+```
+
+## 규칙 5: PolygonAnnotation의 points는 최소 3개여야 한다
+
+유효한 폴리곤을 형성하려면 최소 3개의 점이 필요합니다.
+
+```tsx
+// ✅ 올바른 사용 — 3개 이상의 점
+{
+  type: DrawMode.POLYGON,
+  points: [
+    { x: 100, y: 100 },
+    { x: 200, y: 100 },
+    { x: 150, y: 200 },
+  ],
+}
+
+// ❌ 잘못된 사용 — 2개 이하의 점
+{
+  type: DrawMode.POLYGON,
+  points: [
+    { x: 100, y: 100 },
+    { x: 200, y: 100 },
+  ],
+}
+```
+
+## 규칙 6: annotations 상태 관리는 React state로 한다
+
+`setAnnotations` 콜백으로 어노테이션이 변경될 때 외부 상태와 동기화됩니다.
+
+```tsx
+// ✅ 올바른 사용 — React state 관리
+const [annotations, setAnnotations] = useState<Annotation[]>([]);
+
+<AnnotationEditor
+  annotations={annotations}
+  setAnnotations={setAnnotations}
+  ...
+/>
+
+// ❌ 잘못된 사용 — ref나 외부 변수로 관리
+const annotationsRef = useRef<Annotation[]>([]);
+<AnnotationEditor
+  annotations={annotationsRef.current}
+  setAnnotations={(a) => { annotationsRef.current = a; }}
+  ...
+/>
+// → 리렌더링이 발생하지 않아 UI가 동기화되지 않음
+```
+
+## 규칙 7: selected 필드를 외부에서 직접 조작하지 않는다
+
+어노테이션 선택 상태는 엔진이 내부적으로 관리합니다. 외부에서 `selected: true`를 설정해도 동작하지만, 엔진과 충돌할 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — 선택은 캔버스 내 클릭으로
+// 사용자가 캔버스에서 어노테이션을 클릭하면 자동으로 selected 처리됨
+
+// ⚠️ 주의 — 외부에서 selected 설정
+setAnnotations(prev => prev.map(a =>
+  a === target ? { ...a, selected: true } : { ...a, selected: false }
+));
+// 가능하지만, setAnnotations가 다시 엔진에 전달되면서 불필요한 리렌더링 발생 가능
+```
+
+## 규칙 8: label은 선택적이지만, 텍스트 표시에 필요하다
+
+`label` 필드가 없으면 `drawText` variant에서 표시할 텍스트가 없습니다.
+
+```tsx
+// ✅ 텍스트 라벨이 필요한 경우
+{
+  type: DrawMode.RECTANGLE,
+  x: 100, y: 100, width: 200, height: 150,
+  label: { id: 1, name: 'defect', type: 'bbox' },
+}
+
+// ✅ 텍스트 라벨이 불필요한 경우 — label 생략 가능
+{
+  type: DrawMode.RECTANGLE,
+  x: 100, y: 100, width: 200, height: 150,
+}
+```

package/skills/deepnoid-canvas/rules/events.md

@@ -0,0 +1,124 @@
+# 이벤트 및 단축키 규칙
+
+## 규칙 1: annotationSelected 이벤트로 DrawMode 동기화
+
+캔버스에서 어노테이션을 클릭하면 `window`에 `annotationSelected` CustomEvent가 발생합니다.
+이를 통해 외부 UI의 그리기 모드를 자동 전환할 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — annotationSelected 이벤트 리스닝
+useEffect(() => {
+  const handler = (e: CustomEvent) => {
+    if (e.detail?.type) {
+      setDrawMode(e.detail.type); // DrawMode.RECTANGLE 또는 DrawMode.POLYGON
+    }
+  };
+  window.addEventListener('annotationSelected', handler);
+  return () => window.removeEventListener('annotationSelected', handler);
+}, []);
+
+// ❌ 잘못된 사용 — 이벤트 클린업 누락
+useEffect(() => {
+  window.addEventListener('annotationSelected', handler);
+  // return 없음 → 메모리 누수
+}, []);
+```
+
+## 규칙 2: enableHotkeys를 명시적으로 설정한다
+
+단축키는 기본적으로 비활성화되어 있습니다 (`enableHotkeys` 기본값: `true` in Editor, 단 명시적 설정 권장).
+
+```tsx
+// ✅ 올바른 사용 — 명시적 설정
+<AnnotationEditor enableHotkeys {...otherProps} />
+
+// ✅ 단축키 충돌이 있는 경우 비활성화
+<AnnotationEditor enableHotkeys={false} {...otherProps} />
+```
+
+### 지원 단축키
+
+| 키 | 기능 | 조건 |
+|---|---|---|
+| `Delete` | 선택된 어노테이션 삭제 | 어노테이션 선택 상태일 때 |
+| `Ctrl+Z` (Mac: `Cmd+Z`) | Undo | 히스토리가 있을 때 |
+| `Ctrl+Shift+Z` (Mac: `Cmd+Shift+Z`) | Redo | undo 후 히스토리가 있을 때 |
+| `X` | 선택 어노테이션만 보기 토글 | 언제든 |
+| `Escape` | 진행 중인 그리기 취소 | 폴리곤 점 찍기 중 등 |
+
+## 규칙 3: 이미지 로드 이벤트를 활용한다
+
+`events` prop으로 이미지 로드 성공/실패를 감지할 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — 로드 상태 관리
+const [imageLoaded, setImageLoaded] = useState(false);
+
+<AnnotationEditor
+  image={imageUrl}
+  events={{
+    onImageLoadSuccess: () => setImageLoaded(true),
+    onImageLoadError: (error) => {
+      console.error('이미지 로드 실패:', error);
+      setImageLoaded(false);
+    },
+  }}
+  ...
+/>
+
+// ❌ 잘못된 사용 — events를 undefined로 전달
+<AnnotationEditor
+  events={undefined}  // 타입 에러: events는 필수 prop
+  ...
+/>
+
+// ✅ 이벤트가 필요 없으면 빈 객체 전달
+<AnnotationEditor events={{}} ... />
+```
+
+## 규칙 4: 단축키와 외부 키 이벤트의 충돌에 주의한다
+
+`enableHotkeys`가 켜져 있으면 `window` 레벨에서 키 이벤트를 감지합니다.
+외부에서 같은 키(Delete, X, Ctrl+Z)를 사용하는 경우 충돌이 발생할 수 있습니다.
+
+```tsx
+// ✅ 충돌 방지 — 캔버스 영역에서만 단축키 활성화
+// enableHotkeys를 조건부로 제어
+const [canvasFocused, setCanvasFocused] = useState(false);
+
+<div
+  onFocus={() => setCanvasFocused(true)}
+  onBlur={() => setCanvasFocused(false)}
+>
+  <AnnotationEditor
+    enableHotkeys={canvasFocused}
+    ...
+  />
+</div>
+
+// ❌ 잘못된 사용 — 폼 입력이 있는 페이지에서 항상 enableHotkeys
+// → Delete 키로 텍스트 삭제 시 어노테이션도 삭제됨
+```
+
+## 규칙 5: setAnnotations 콜백은 비동기적으로 호출된다
+
+엔진 내부에서 어노테이션이 변경되면 `setAnnotations` 콜백이 호출됩니다.
+이 콜백 내에서 무거운 로직을 실행하면 성능에 영향을 줄 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — 가벼운 상태 업데이트만
+<AnnotationEditor
+  setAnnotations={setAnnotations}
+  ...
+/>
+
+// ⚠️ 주의 — 콜백 내 무거운 로직
+<AnnotationEditor
+  setAnnotations={(annotations) => {
+    setAnnotations(annotations);
+    // 매 마우스 이동마다 호출될 수 있어 성능 이슈
+    saveToServer(annotations); // ← debounce 권장
+  }}
+  ...
+/>
+```