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

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 패키지를 둘로 나누지 않고 신규 패키지 하나로 닫는다.

구현 순서

Editing geometry 공개 API와 owner 테스트
Annotation Hand 패키지와 contract 테스트
소유 패키지 API reference, site Usage, source registration
Demo consumer migration과 route-local 중복 삭제
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 정리

작업 계획

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로 이동하지 않는다.

단계

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

위험과 재계획 조건

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

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

구현 진행

완료된 경계:

@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입니다.

PR 생성 및 최종 검증

PR: refactor(annotation): 선택·gesture·출력의 정본 경계 통합 #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뿐입니다.

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 상호작용 확인 완료

후속 실행 계획 — #725 건강도 감사의 Annotation 단계

사용자의 “좋아 다음” 요청으로 기존 #588 / #589를 이어간다. 원격 PR은 2026-08-26 이후 변경되지 않았고, 기존 worktree 등록은 없다. 별도 이슈/PR로 구현을 복제하지 않는다.

Goal Anchor

Outcome: Annotation을 생태계의 정본 API만으로 구성하고 Demo에는 fixture, copy, layout, 제품 정책과 조합만 남긴다.
Done: Editing geometry와 단일 Annotation Hand 패키지를 통해 기존 계약의 재사용 UI·gesture·projection·serialization 경계를 닫고, owner 문서·Usage·source registration·테스트 및 실제 Demo 검증을 갖춘다. production source는 기존 계약의 1,168 LOC 미만을 유지한다.
Don't: 기존 6개 도구, comment/reaction, move/resize, undo/cancel, raster 및 시각 결과를 유지한다. 활성 도구·제품 스타일 값은 Host에 남기고 범용 React connector에 Annotation 책임을 넣지 않는다. merge는 수행하지 않는다.

이번에 닫을 기존 계약의 누락

최신 main을 기존 PR branch에 통합한다. 과거 CI 실패는 API Annotation 메뉴 항목이 browser 기대 목록에 빠진 건으로 확인했으며, 현재 navigation 계약에 맞춰 검증을 복구한다.
Editing의 Annotation selection 전이를 Key Selection 정본에 연결한다. 기존 AnnotationSelection 형태, 선택한 순서, primary 및 Undo/Redo 복원 결과를 보존한다. 새 Selection family나 공개 명령은 도입하지 않는다.
preview/commit이 같은 geometry 결과를 사용하는지 확인한다. Hand의 일반 Undo/Redo/Delete 키 해석은 기존 Web resolver를 소비한다. 도구 단축키는 Annotation 정책으로 유지한다.
이슈에서 명시한 Host의 활성 도구·스타일 값 주입을 실제 public props와 Usage에서 성립시킨다. pointer/gesture 결과와 기존 6개 도구·댓글·raster 동작을 검증한다.
owner API·source registration·문서, 영향 package/site 검사와 기존 browser acceptance를 갱신하고 같은 PR에 푸시한다.

검증과 경계

선택 순서가 Key Selection의 universe 순서로 바뀌지 않도록 호환 사례를 먼저 고정한다.
rejected preview/commit, Undo/Redo 선택 복원, 단축키의 수정키, Host-controlled 도구를 검사한다.
최신 main과의 충돌 해결은 기존 Annotation 변경 및 새 base의 기능 보존에 한정한다. Database #587이나 앞선 JSON 주소와 값 검증을 Core 정본으로 통일한다 #732/기본 단축키 해석을 정본 키맵과 chord로 통일한다 #734 구현을 가져오지 않는다.
기존 Chrome profile을 재사용하며 자동 제어가 불가능하면 로컬 검증 한계를 명시한다. 이전 #734는 현재 CI가 모두 통과한 상태다.

중간 기록 — 재사용과 호환성을 함께 닫는 기준

이번 통합에서 같은 선택 엔진을 쓴다고 모든 도메인의 순서를 같게 만들면 안 된다는 점을 확인했습니다.

Key Selection은 membership, primary fallback, reconcile을 담당합니다.
Annotation은 기존 선택 순서를 Key context의 순서로 제공합니다. 예를 들어 문서 순서가 A/B/C여도 C→A를 선택했다면 공개 ids는 [C,A]입니다.
이 경계를 통해 새 Selection family나 명령을 만들지 않고 기존 공개 형태와 Undo/Redo 복원을 유지합니다.

최신 main의 변경도 기존 계약에 포함해 보존하고 있습니다.

책임	최종 소유자	Host가 남기는 것
선택 전이·primary·reconcile	Selection Key → Editing Annotation projection	없음
move/resize pointer lifecycle	UI `useInteractionHandle` → Affordance/Web	없음
생성 gesture와 selector preview/commit	Annotation Hand → Affordance/Editing/Web	`createId`, 활성 도구
Undo/Redo/Delete 키 해석	Web keyboard resolver	도구 사용 정책
출력 직렬화·저장/복원·비동기 raster 결과	Annotation `useAnnotationOutput` → Core/Web	출력 탭·문구·CodeBlock·링크·배치

기존 PR 이후 main에 추가된 복사 가능한 출력 패널과 Save/Restore/Image UI를 제거하면 기능 보존 계약을 위반합니다. 그래서 출력 lifecycle을 같은 Annotation 패키지의 hook으로 제공하고, 화면 조합은 Host에 유지했습니다. 이 hook은 새로운 편집 명령이 아니며 기존 Core commit과 Web raster API를 조합합니다. Structured JSON은 selection을 섞지 않은 정확한 AnnotationDocument입니다.

읽을 코드와 검증 사례:

packages/json-document-editing/src/annotation-selection.ts: 도메인 표현과 정본 선택 엔진의 경계
packages/json-document-editing/tests/annotation-editor.test.ts: 역순 다중 선택, 삭제 reconcile, Undo/Redo 선택 복원, 퇴화한 arrow 거부
packages/json-document-annotation/src/annotation-hand.tsx: Host-controlled tool과 정본 handle/keyboard 소비
packages/json-document-annotation/tests/annotation-output.test.tsx: 문서 owner가 바뀌었을 때 저장 상태 격리, 늦게 도착한 raster 결과 무시

현재 owner 검증과 site guard를 실행 중이며, 아직 최종 완료 보고는 아닙니다.

PR 갱신 및 검증 기록 — 37f6702c

PR: refactor(annotation): 선택·gesture·출력의 정본 경계 통합 #589
원격 PR HEAD와 검증 worktree HEAD 일치, 작업 트리 clean
최신 main 통합 후 최종 PR diff 45개 파일을 Goal Anchor와 양방향 대조했습니다. 이슈 본문은 유지했습니다.
영향 production source는 Annotation package src, Editing annotation*, Annotation Demo 파일 전체 기준 710 LOC입니다. 줄 수 외에도 route-local 선택·gesture·geometry·직렬화 구현을 제거했는지 확인했습니다.

계약별 증거

계약	구현·검증
공통 선택 문법 + Annotation 호환성	Selection 24, Editing 282 tests; 역순 선택·primary fallback·외부 reconcile·Undo/Redo
동일 geometry로 preview/commit	Editing 공개 geometry API; path bounds도 같은 함수 소비; 퇴화한 arrow 거부 시 문서·선택·history 불변
Host 정책 보존	`tool`/`onToolChange`, `createId`, style/labels 주입; 제어된 도구 및 수정키/IME 테스트
기존 제품 동작 보존	Annotation·출력 복사 browser 13/13, site shell 19/19(각 setup 1 포함); 댓글·reaction·move/resize·cancel·PNG·저장/복원
정본 출력과 비동기 lifecycle	Annotation owner 7 tests; 정확한 문서 JSON, 교체된 owner로 복원 금지, stale raster completion과 rejection 처리
생태계 등록	30 packages / 1,047 API exports, Usage/source registration, site guard·typecheck, 138 site unit tests, Pages build/static/HTTP 검사
배포·CI 연결	plan/release tests 17/17; PR CI 실행 중

검증 한계

외부 kit는 tarball 생성 후 로컬 설치 단계에서 ENOSPC로 중단됐습니다. 검증 스크립트의 임시 디렉터리는 자동 정리됐으며, 당시 디스크 여유는 약 296 MiB였습니다. 사용자의 파일이나 기존 작업 트리는 정리하지 않았습니다. 설치·실행 완료 여부는 원격 External kit job으로 확인 중입니다.
처음 합동 browser 실행은 중도 종료됐고, 위 통과 수치는 분리 실행에서 확보한 완료 결과입니다.
Playwright 상호작용과 화면 캡처에서 페이지 오류 없이 댓글/도구 표시를 확인했습니다. 기존 Chrome profile의 자동 제어 연결이 없어 사용자 세션의 직접 상호작용 검증은 완료하지 못했습니다.

읽을 순서

Annotation selection adapter: 공개 표현을 바꾸지 않고 공통 엔진을 재사용하는 경계입니다. membership은 엔진에, 선택 순서는 domain context에 둡니다.
Annotation editor tests: 내부 구현이 달라져도 유지되어야 할 관측 가능한 계약을 봅니다.
Annotation Demo: Host에 남은 정책·배치·조합과 패키지에 옮긴 동작을 비교합니다.
Output lifecycle tests: 직렬화 결과에서 selection을 제외하는 이유와 비동기 결과의 소유권을 확인합니다.

이번 단계에서 Core의 공개 명령이나 Selection family는 늘지 않았습니다. Annotation-specific UI 계약을 기존 공통 편집 문법의 소비자로 연결한 변경입니다. merge는 수행하지 않았습니다.

CI 후속 확인 — 37f6702c

로컬 디스크 공간 부족으로 끝내지 못했던 외부 소비자 설치·실행 검증은 원격 External kit에서 통과했습니다.

현재 Plan / External kit는 성공이며 Package / Site의 전체 검증이 진행 중입니다. PR 본문에도 원격 증거를 반영했습니다. 로컬 작업 트리는 clean이고 PR은 열린 상태이며 merge하지 않았습니다.

완료 조건 보완 — 실제 source 탭 연결

최종 공개 surface 감사에서 등록 데이터와 실제 탐색 결과를 대조했습니다. annotation-selection.ts를 raw source로 등록하는 것만으로는 Usage의 탭에 나타나지 않았습니다. 현재 source 탐색기는 package 내부의 상대 .js import를 자동으로 따라가지 않기 때문입니다.

이는 #588의 “site Usage와 정본 implementation source 연결” Done에 직접 해당하는 누락입니다. 전체 source 탐색기의 정책은 변경하지 않고, 기존 공개 API 등록 방식으로 createAnnotationEditor의 구현을 구성하는 domain projection과 Key owner를 연결했습니다. geometry 공개 API들도 자기 소유 파일에 연결했습니다.

unit test: 실제 discoverDemoSources 결과에서 Hand, output, geometry, selection projection, Key owner 및 API Reference 경로를 확인
browser test: Annotation Usage에서 다섯 source 탭을 열고 구현 코드와 소유 패키지 API 링크를 확인

등록 파일의 존재와 사용자가 구현까지 찾아갈 수 있다는 것은 별개의 검증이라는 점이 이번 보완의 핵심입니다.

최신 PR HEAD — ba163a3f

37f6702c의 전체 CI는 Plan / Package / Site / External kit 모두 성공했습니다.
후속 ba163a3f는 Usage source 등록과 검증 3개 파일만 변경합니다. 편집 동작·패키지 API는 동일합니다.
실제 Annotation source 탭 5개와 소유 API 링크를 확인한 browser 검사를 포함해 Annotation·복사 browser 14/14가 통과했습니다(서버 setup 1 포함).
영향 workbench unit 17/17, site typecheck/guard, Pages build/static/HTTP 검사를 통과했습니다.
로컬 전체 unit 재실행에서는 기존 app-shell/docs-route 탐색의 대기 시간 초과가 반복됐습니다. 임계값을 변경하지 않았고, 최신 HEAD의 전체 CI를 재실행 중입니다.
최종 PR diff 46개 파일, production source 710 LOC. 원격 HEAD와 로컬 검증 worktree가 일치하며 작업 트리는 clean입니다.

source 탭에서도 annotation-selection.ts → Key owner 구현까지 읽을 수 있습니다. PR은 열린 상태로 유지하며 merge는 수행하지 않았습니다.

머지 완료

사용자의 이번 merge 요청에 따라 PR #589를 squash 머지했습니다.

검증 HEAD: ba163a3ffc2bbd95a6c916ce4ae113a2085c1498
CI: Plan / Package / Site / External kit 모두 성공
머지 커밋: 02741ec3c49a502c628704ed676fd406bbe0cf19
PR 상태 MERGED, 이슈 Annotation Hand 책임을 정본 모듈로 수렴한다 #588 상태 CLOSED

검증한 PR HEAD와 머지된 main의 Git tree가 동일함을 확인했습니다. squash가 커밋 이력을 정리한 뒤에도 실제 파일 내용은 검증한 결과와 같습니다.

이번 작업의 미리보기 서버, worktree, 작업용 clone의 로컬 branch와 원격 branch를 정리했습니다. 작업용 clone의 main ref는 머지 커밋으로 fast-forward했습니다. 다른 PR의 작업 트리와 원본 checkout의 미커밋 변경은 보존했으며, 원본 checkout의 main은 이동하지 않았습니다.

최종 상태: landed-clean.

Navigation Menu

Repository navigation

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

Goal Anchor

확정한 정본 경계

구현 순서

실패 및 재계획 조건

제외

작업 계획

Goal Anchor

단계

위험과 재계획 조건

구현 진행

PR 생성 및 최종 검증

CI 보정

Goal Anchor

이번에 닫을 기존 계약의 누락

검증과 경계

계약별 증거

검증 한계

읽을 순서

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

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

Description

Goal Anchor

확정한 정본 경계

구현 순서

실패 및 재계획 조건

제외

Activity

developer-1px commented on Aug 26, 2026

작업 계획

Goal Anchor

단계

위험과 재계획 조건

developer-1px commented on Aug 26, 2026

구현 진행

developer-1px commented on Aug 26, 2026

PR 생성 및 최종 검증

developer-1px commented on Aug 26, 2026

CI 보정

developer-1px commented on Sep 8, 2026

Goal Anchor

이번에 닫을 기존 계약의 누락

검증과 경계

developer-1px commented on Sep 8, 2026

developer-1px commented on Sep 8, 2026

계약별 증거

검증 한계

읽을 순서

developer-1px commented on Sep 8, 2026

developer-1px commented on Sep 8, 2026

developer-1px commented on Sep 8, 2026

developer-1px commented on Sep 8, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions