@deepnoid/canvas 0.1.84 → 0.1.86

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

@@ -0,0 +1,171 @@
+# 레이아웃, 줌/팬 규칙
+
+## 규칙 1: 컨테이너에 반드시 고정 크기를 설정한다
+
+`AnnotationEditor`/`AnnotationViewer`는 부모 컨테이너의 100% 크기를 차지합니다.
+부모에 크기가 없으면 캔버스가 0px로 렌더링됩니다.
+
+```tsx
+// ✅ 올바른 사용 — 고정 크기
+<div style={{ width: 800, height: 600 }}>
+  <AnnotationEditor ... />
+</div>
+
+// ✅ flex 레이아웃
+<div style={{ display: 'flex', height: '100vh' }}>
+  <aside style={{ width: 200 }}>사이드바</aside>
+  <div style={{ flex: 1 }}>
+    <AnnotationEditor ... />
+  </div>
+</div>
+
+// ❌ 잘못된 사용 — 크기 없는 컨테이너
+<div>
+  <AnnotationEditor ... />
+</div>
+// → 캔버스 크기가 0이 되어 아무것도 보이지 않음
+```
+
+## 규칙 2: panZoomEnabled로 줌/팬을 제어한다
+
+줌(마우스 휠)과 팬(우클릭 드래그)은 `options.panZoomEnabled`로 제어합니다.
+
+```tsx
+// ✅ 줌/팬 활성화
+<AnnotationEditor
+  options={{ panZoomEnabled: true }}
+  ...
+/>
+
+// ✅ 줌/팬 비활성화 (고정 뷰)
+<AnnotationEditor
+  options={{ panZoomEnabled: false }}
+  ...
+/>
+
+// ✅ 기본값: panZoomEnabled를 생략하면 옵션 객체 자체가 없어야 함
+<AnnotationEditor options={undefined} ... />
+```
+
+## 규칙 3: zoom 옵션으로 줌 범위를 제한한다
+
+줌 배율의 최소/최대/단계를 설정할 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — 줌 범위 설정
+<AnnotationEditor
+  options={{
+    panZoomEnabled: true,
+    zoom: {
+      min: 0.5,    // 최소 50% (기본: 0.1)
+      max: 4,      // 최대 400% (기본: Infinity)
+      step: 0.9,   // 한 스텝당 배율 변화 (기본: 0.9)
+    },
+  }}
+  ...
+/>
+
+// ✅ 일부만 설정 가능
+<AnnotationEditor
+  options={{
+    panZoomEnabled: true,
+    zoom: { max: 10 }, // min, step은 기본값 사용
+  }}
+  ...
+/>
+```
+
+## 규칙 4: ZoomButton으로 줌 비율 표시 및 리셋
+
+커스텀 줌 버튼 컴포넌트를 주입하여 현재 줌 비율 표시 및 클릭 시 줌 리셋이 가능합니다.
+
+```tsx
+// ✅ 올바른 사용 — 커스텀 ZoomButton
+const ZoomButton = ({ onClick, children }: { onClick: () => void; children: ReactNode }) => (
+  <button
+    onClick={onClick}
+    style={{ position: 'absolute', top: 10, left: 10, zIndex: 10 }}
+  >
+    {children}  {/* "125%" 같은 줌 비율 문자열 */}
+  </button>
+);
+
+<AnnotationEditor
+  options={{
+    panZoomEnabled: true,
+    ZoomButton,
+  }}
+  ...
+/>
+
+// ❌ 잘못된 사용 — ZoomButton에 잘못된 시그니처
+const ZoomButton = ({ zoom }) => <span>{zoom}</span>; // onClick과 children이 필요
+```
+
+## 규칙 5: resetOnImageChange로 이미지 전환 시 줌 상태를 제어한다
+
+이미지가 바뀔 때 줌/팬 상태를 초기화할지 유지할지 선택할 수 있습니다.
+
+```tsx
+// ✅ 이미지 전환 시 줌 리셋
+<AnnotationEditor
+  options={{ resetOnImageChange: true }}
+  ...
+/>
+
+// ✅ 이미지 전환 시 줌 유지 (기본값: false)
+<AnnotationEditor
+  options={{ resetOnImageChange: false }}
+  ...
+/>
+```
+
+## 규칙 6: ref로 캔버스 크기를 수동 리셋할 수 있다
+
+`AnnotationCanvasHandle` ref를 통해 프로그래밍 방식으로 캔버스를 리셋합니다.
+
+```tsx
+import { useRef } from 'react';
+import type { AnnotationCanvasHandle } from '@deepnoid/canvas';
+
+// ✅ 올바른 사용
+const canvasRef = useRef<AnnotationCanvasHandle>(null);
+
+<button onClick={() => canvasRef.current?.resetImageSize()}>
+  크기 초기화
+</button>
+<AnnotationEditor ref={canvasRef} ... />
+
+// ❌ 잘못된 사용 — 잘못된 타입
+const canvasRef = useRef<HTMLCanvasElement>(null); // AnnotationCanvasHandle이어야 함
+```
+
+## 규칙 7: keepCrossOnImageChange로 가이드 십자선 유지
+
+이미지가 변경될 때 마우스 위치의 가이드 십자선(crosshair)을 유지할 수 있습니다.
+`AnnotationEditor`에서만 사용 가능합니다.
+
+```tsx
+// ✅ 이미지 전환 시 십자선 유지 (연속 작업 시 편리)
+<AnnotationEditor keepCrossOnImageChange ... />
+
+// ✅ 기본 동작 — 이미지 전환 시 십자선 제거
+<AnnotationEditor keepCrossOnImageChange={false} ... />
+```
+
+## 규칙 8: 리사이즈 대응은 자동으로 처리된다
+
+컨테이너 크기가 변하면 내부 `ResizeObserver`가 자동으로 캔버스를 재설정합니다 (150ms debounce).
+별도의 리사이즈 처리가 필요 없습니다.
+
+```tsx
+// ✅ 리사이즈 대응 — 별도 처리 불필요
+<div style={{ width: '100%', height: '100%' }}>
+  <AnnotationEditor ... />
+</div>
+
+// ❌ 불필요한 사용 — 수동 리사이즈 핸들러
+window.addEventListener('resize', () => {
+  canvasRef.current?.resetImageSize(); // 불필요, 자동 처리됨
+});
+```

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

@@ -0,0 +1,142 @@
+# applyStyle 렌더링 규칙
+
+## 규칙 1: applyStyle은 반드시 제공해야 한다
+
+`drawing.applyStyle`은 필수 prop입니다. 이 함수 없이는 어노테이션이 화면에 표시되지 않습니다.
+
+```tsx
+// ✅ 올바른 사용
+<AnnotationEditor
+  drawing={{
+    lineSize: 2,
+    applyStyle: myStyleFunction,
+    mode: DrawMode.RECTANGLE,
+    color: '#FF4136',
+  }}
+  ...
+/>
+
+// ❌ 잘못된 사용 — applyStyle 누락
+<AnnotationEditor
+  drawing={{
+    lineSize: 2,
+    mode: DrawMode.RECTANGLE,
+  }}
+  ...
+/>
+```
+
+## 규칙 2: variant별로 분기 처리해야 한다
+
+`applyStyle`은 `drawRect`과 `drawText` 두 번 호출됩니다. 각 variant에 맞는 Canvas2D 속성을 설정해야 합니다.
+
+```tsx
+// ✅ 올바른 사용 — variant별 분기
+const applyStyle: ApplyAnnotationStyle = ({ variant, context, annotation, drawLineSize, zoom }) => {
+  if (variant === 'drawRect') {
+    context.strokeStyle = '#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') {
+    context.fillStyle = '#FF4136';
+    context.font = `bold ${14 / zoom}px sans-serif`;
+    // 텍스트 렌더링 로직...
+  }
+};
+
+// ❌ 잘못된 사용 — variant 무시
+const applyStyle: ApplyAnnotationStyle = ({ context, annotation }) => {
+  context.strokeStyle = '#FF4136';
+  context.strokeRect(annotation.x, annotation.y, annotation.width, annotation.height);
+};
+```
+
+## 규칙 3: 모든 크기 값에 zoom 보정을 적용해야 한다
+
+줌 배율이 변해도 어노테이션 선 두께, 폰트 크기, 대시 간격 등이 일정하게 보이려면 반드시 `/ zoom`으로 나누어야 합니다.
+
+```tsx
+// ✅ 올바른 사용 — zoom 보정
+context.lineWidth = drawLineSize / zoom;
+context.font = `bold ${14 / zoom}px sans-serif`;
+context.setLineDash([6 / zoom, 3 / zoom]);
+
+// ❌ 잘못된 사용 — zoom 보정 없음 (줌인하면 선이 점점 두꺼워짐)
+context.lineWidth = drawLineSize;
+context.font = `bold 14px sans-serif`;
+context.setLineDash([6, 3]);
+```
+
+## 규칙 4: annotation.type으로 분기하여 도형을 직접 그려야 한다
+
+`applyStyle`의 `drawRect` variant에서는 스타일 설정뿐 아니라 **실제 도형 그리기**까지 소비자가 담당합니다.
+
+```tsx
+// ✅ 올바른 사용 — 타입별 도형 그리기
+if (variant === 'drawRect') {
+  context.strokeStyle = '#FF4136';
+  context.lineWidth = drawLineSize / zoom;
+
+  if (annotation.type === DrawMode.RECTANGLE) {
+    const { x, y, width, height } = annotation;
+    context.strokeRect(x, y, width, height);
+  } else if (annotation.type === DrawMode.POLYGON) {
+    context.beginPath();
+    annotation.points.forEach((p, idx) => {
+      if (idx === 0) context.moveTo(p.x, p.y);
+      else context.lineTo(p.x, p.y);
+    });
+    context.closePath();
+    context.stroke();
+  }
+}
+
+// ❌ 잘못된 사용 — RECTANGLE만 처리하고 POLYGON 무시
+if (variant === 'drawRect') {
+  context.strokeRect(annotation.x, annotation.y, annotation.width, annotation.height);
+}
+```
+
+## 규칙 5: setLineDash 사용 후 반드시 초기화해야 한다
+
+Canvas2D 컨텍스트는 상태를 유지합니다. `setLineDash`로 점선을 설정하면 다음 어노테이션에도 영향을 줍니다.
+
+```tsx
+// ✅ 올바른 사용 — 조건부 dash + 초기화
+if (annotation.selected) {
+  context.setLineDash([6 / zoom, 3 / zoom]);
+} else {
+  context.setLineDash([]);
+}
+
+// ❌ 잘못된 사용 — selected일 때만 dash 설정, else 빠짐
+if (annotation.selected) {
+  context.setLineDash([6 / zoom, 3 / zoom]);
+}
+// → 다음 어노테이션도 점선으로 그려짐
+```
+
+## 규칙 6: annotation.color를 활용한 상태별 스타일링
+
+어노테이션의 `color` 필드(`'success' | 'warning' | 'danger'`)를 활용하여 상태별 색상을 적용할 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — color 필드 매핑
+const colorMap = {
+  success: 'rgba(36, 162, 91, 1)',
+  warning: 'rgba(237, 164, 16, 1)',
+  danger: 'rgba(255, 70, 132, 1)',
+};
+context.strokeStyle = colorMap[annotation.color ?? 'danger'];
+
+// ❌ 잘못된 사용 — color 필드를 직접 CSS 색상으로 사용
+context.strokeStyle = annotation.color; // 'danger'는 유효한 CSS 색상이 아님
+```

package/skills/deepnoid-canvas/setup.md

@@ -0,0 +1,147 @@
+# 소비자 프로젝트 설정 가이드
+
+## 1. 설치
+
+```bash
+# npm
+npm install @deepnoid/canvas
+
+# yarn
+yarn add @deepnoid/canvas
+```
+
+**Peer dependency**: React 19.0.0 이상 필수.
+
+## 2. Claude Code 스킬 설치
+
+패키지에 포함된 스킬을 프로젝트의 `.claude/skills/`에 복사합니다.
+
+```bash
+cp -r node_modules/@deepnoid/canvas/skills/deepnoid-canvas .claude/skills/
+```
+
+이후 Claude Code가 `@deepnoid/canvas` 관련 코드를 작성할 때 자동으로 스킬을 참조합니다.
+
+## 3. 기본 설정
+
+### 최소 구성 (Editor)
+
+```tsx
+import { useState } from 'react';
+import { AnnotationEditor, DrawMode } from '@deepnoid/canvas';
+import type { Annotation, ApplyAnnotationStyle } from '@deepnoid/canvas';
+
+// Step 1: applyStyle 함수 정의 (필수)
+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();
+    }
+  }
+};
+
+// Step 2: 컴포넌트 사용
+function AnnotationPage() {
+  const [annotations, setAnnotations] = useState<Annotation[]>([]);
+
+  return (
+    // Step 3: 반드시 고정 크기의 컨테이너로 감싸기
+    <div style={{ width: '100%', height: '100vh' }}>
+      <AnnotationEditor
+        image="https://example.com/image.jpg"
+        annotations={annotations}
+        setAnnotations={setAnnotations}
+        drawing={{
+          mode: DrawMode.RECTANGLE,
+          color: '#FF4136',
+          lineSize: 2,
+          applyStyle,
+        }}
+        events={{}}
+        enableHotkeys
+      />
+    </div>
+  );
+}
+```
+
+### 최소 구성 (Viewer)
+
+```tsx
+import { AnnotationViewer } from '@deepnoid/canvas';
+
+function ViewerPage({ annotations }) {
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <AnnotationViewer
+        image="https://example.com/image.jpg"
+        annotations={annotations}
+        drawing={{ lineSize: 2, applyStyle }}
+        events={{}}
+      />
+    </div>
+  );
+}
+```
+
+## 4. 권장 설정
+
+### 줌/팬 활성화
+
+```tsx
+<AnnotationEditor
+  options={{
+    panZoomEnabled: true,
+    zoom: { min: 0.5, max: 4, step: 0.9 },
+  }}
+  ...
+/>
+```
+
+### annotationSelected 이벤트 연동
+
+어노테이션 클릭 시 그리기 모드 자동 전환:
+
+```tsx
+const [mode, setMode] = useState(DrawMode.RECTANGLE);
+
+useEffect(() => {
+  const handler = (e: CustomEvent) => {
+    if (e.detail?.type) setMode(e.detail.type);
+  };
+  window.addEventListener('annotationSelected', handler);
+  return () => window.removeEventListener('annotationSelected', handler);
+}, []);
+
+<AnnotationEditor drawing={{ mode, ... }} ... />
+```
+
+### ref를 통한 줌 리셋 버튼
+
+```tsx
+import { useRef } from 'react';
+import type { AnnotationCanvasHandle } from '@deepnoid/canvas';
+
+const canvasRef = useRef<AnnotationCanvasHandle>(null);
+
+<button onClick={() => canvasRef.current?.resetImageSize()}>초기화</button>
+<AnnotationEditor ref={canvasRef} ... />
+```
+
+## 5. 체크리스트
+
+소비자 프로젝트 설정 후 확인 사항:
+
+- [ ] React 19+ 설치 확인
+- [ ] `applyStyle` 함수에서 `drawRect`/`drawText` variant 분기 처리
+- [ ] `applyStyle` 내 모든 크기 값에 `/ zoom` 보정 적용
+- [ ] 컨테이너 `div`에 고정 크기(width/height) 설정
+- [ ] RECTANGLE/POLYGON 모두에서 도형 그리기 처리
+- [ ] `events` prop에 최소 빈 객체 `{}` 전달