Annotation Hand 책임을 정본 모듈로 수렴한다

[developer-1px]

Goal Anchor

• Outcome: Annotation을 생태계의 정본 API만으로 구성하고 Demo에는 fixture, copy, layout, 제품 정책과 조합만 남긴다.
• Done: Editing의 selector geometry API와 하나의 @interactive-os/json-document-annotation 공개 패키지로 Annotation Hand를 제공하고, Demo의 재사용 UI·gesture·projection·serialization 구현을 제거한다. 공개 API, 소유 패키지 API 문서, site Usage, source registration, owner 테스트와 실제 Demo 검증을 갖추며 영향 범위 production source LOC를 현재 1,168 LOC보다 줄인다.
• Don't: 현재 6개 도구, comment/reaction, move/resize, undo/cancel, raster 동작과 minimalist 시각 결과를 바꾸지 않는다. Host의 fixture, createId, 활성 도구, 문구, 스타일 토큰, 배치, output 조합 정책을 package가 소유하지 않는다. json-document-react에 Annotation 도메인 책임을 추가하지 않는다. merge는 이 이슈 범위가 아니다.

확정한 정본 경계

• @interactive-os/json-document-editing: selector 변환, annotation bounds, resize-handle geometry의 정본.
• @interactive-os/json-document-affordance: gesture lifecycle 정본을 유지한다.
• @interactive-os/json-document-web: pointer capture, SVG 좌표 변환, raster decode/rendering 정본을 유지한다.
• 신규 @interactive-os/json-document-annotation: tool descriptor, gesture→Intent orchestration, SVG shape projection, transient preview, resize handles, comment composer/preview, 접근 가능한 기본 Annotation Hand UI를 소유한다.
• Demo: fixture, createId, 활성 도구, 제품 문구, 스타일 토큰, layout, output 조합만 주입한다.
• Structured output은 정확한 AnnotationDocument를 표시하고 selection을 document serialization에 합치지 않는다.
• headless/React 패키지를 둘로 나누지 않고 신규 패키지 하나로 닫는다.

구현 순서

1. Editing geometry 공개 API와 owner 테스트
2. Annotation Hand 패키지와 contract 테스트
3. 소유 패키지 API reference, site Usage, source registration
4. Demo consumer migration과 route-local 중복 삭제
5. production source LOC, package 검증, site typecheck/test/build, 실제 Demo 상호작용 검증

실패 및 재계획 조건

• Demo에 shape, gesture, comment 동작 구현이 남는다.
• preview와 commit이 서로 다른 selector 계산을 사용한다.
• json-document-react가 Annotation 도메인 타입이나 동작을 알게 된다.
• 영향 범위 production source LOC가 1,168 LOC 미만이 되지 않는다.
• 기존 도구와 편집·취소·raster 동작 또는 minimalist 시각 결과가 달라진다.

제외

• W3C JSON-LD 모델 도입
• 네트워크 저장·협업 기능
• Database 또는 다른 Demo 변경
• PR merge와 worktree 정리

[developer-1px]

작업 계획

Goal Anchor

• Outcome: Annotation을 생태계 정본 API만으로 구성하고 Demo에는 fixture·copy·layout·제품 정책·조합만 남긴다.
• Done: Editing geometry API와 단일 Annotation Hand 공개 패키지, 문서·Usage·source registration·owner 테스트·실제 Demo 검증을 갖추고 영향 범위 production source LOC를 1,168 미만으로 줄인다.
• Don't: 기존 6개 도구와 편집·취소·raster·minimalist UI 동작을 바꾸지 않고, Host 정책이나 Annotation 도메인을 범용 React connector로 이동하지 않는다.

단계

1. Editing selector geometry 정본 API와 테스트
2. Annotation Hand package와 공개 surface
3. owner 문서·Usage·source registration
4. Demo migration과 중복 삭제
5. LOC·package/site·browser 검증

위험과 재계획 조건

• route-local reusable 동작 잔존
• preview/commit geometry 불일치
• production source LOC 순증
• 실제 Demo 동작 또는 시각 회귀

Database 작업은 별도 worktree/PR에서 진행 중이며 이 이슈에서는 변경하지 않는다. merge와 정리는 제외한다.

[developer-1px]

구현 진행

완료된 경계:

@interactive-os/json-document-editing
└─ selector transform / bounds / resize handle

@interactive-os/json-document-annotation
└─ tools / gesture→Intent / SVG / preview / resize / comment UI

Annotation Demo
└─ fixture / createId / copy / style / layout / composition

• preview와 commit이 같은 transformAnnotationSelector를 사용합니다.
• AnnotationHand 공개 API, owner test, README, 생성 API reference, site Usage와 source registration을 연결했습니다.
• Demo structured output은 selection을 섞지 않은 AnnotationDocument입니다.
• canonical closure guard가 Demo의 gesture/projection/comment UI 재도입을 거부합니다.
• 영향 범위 production source는 1,168 LOC에서 550 LOC로 618 LOC 감소했습니다.
• 검증: Annotation browser 10/10, site unit 47/47, Editing 73/73, package contract 2/2, site typecheck/build, docs/workspace/CI plan guard 통과.

남은 작업은 최종 diff 감사, 커밋·푸시, PR correlation입니다.

[developer-1px]

PR 생성 및 최종 검증

• PR: Annotation Hand 책임을 정본 모듈로 수렴한다 #589
• branch: issue-588-annotation-canonical-hand
• commits: bbd8552f, db517769
• production source: 1,168 → 550 LOC
• 실제 Annotation Demo의 6개 도구, comment/reaction, move/resize, cancel, raster download browser acceptance 10/10 통과
• package/site/docs/workspace/release·CI plan 검증 통과
• 원격 PR HEAD와 검증 worktree HEAD 일치
• 이슈 계약과 PR changed files의 양방향 대조 완료

남은 항목은 GitHub CI 완료와 별도 승인이 필요한 merge뿐입니다.

[developer-1px]

CI 보정

첫 Site job은 새 workspace의 source alias가 site TypeScript/Vite 설정에 누락되어 실패했습니다. site/tsconfig.json과 json-document-source-aliases.ts에 정본 source 경로를 등록하고, package dist를 지운 깨끗한 상태에서 site typecheck와 production build를 다시 통과시켰습니다.

• 수정 commit: 4c89fbc7
• 로컬 HEAD와 원격 PR HEAD 일치
• 같은 HEAD의 /demo/annotation을 다시 열어 Annotation Hand 상호작용 확인 완료