Repository navigation
Annotation Hand 책임을 정본 모듈로 수렴한다 #588
Description
Activity
작업 계획
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입니다.
- preview와 commit이 같은
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 경로를 등록하고, packagedist를 지운 깨끗한 상태에서 site typecheck와 production build를 다시 통과시켰습니다.- 수정 commit:
4c89fbc7 - 로컬 HEAD와 원격 PR HEAD 일치
- 같은 HEAD의
/demo/annotation을 다시 열어 Annotation Hand 상호작용 확인 완료
- 수정 commit:
후속 실행 계획 — #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, Editingannotation*, 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 kitjob으로 확인 중입니다. - 처음 합동 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 내부의 상대.jsimport를 자동으로 따라가지 않기 때문입니다.이는 #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 링크를 확인
등록 파일의 존재와 사용자가 구현까지 찾아갈 수 있다는 것은 별개의 검증이라는 점이 이번 보완의 핵심입니다.
- unit test: 실제
최신 PR HEAD —
ba163a3f37f6702c의 전체 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.- 검증 HEAD:
Goal Anchor
@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보다 줄인다.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를 소유한다.createId, 활성 도구, 제품 문구, 스타일 토큰, layout, output 조합만 주입한다.AnnotationDocument를 표시하고 selection을 document serialization에 합치지 않는다.구현 순서
실패 및 재계획 조건
json-document-react가 Annotation 도메인 타입이나 동작을 알게 된다.제외