@01.works/visual-review 0.11.0 → 0.13.0

package/README.md

@@ -34,6 +34,62 @@ credential을 browser 설정으로 전달하지 않습니다.
 npm install @01.works/visual-review
 ```
 
+## CLI
+
+같은 공개 패키지가 프로젝트 범위 리뷰 피드백 CLI를 제공합니다. scope 없는
+`npx visual-review`은 동명의 다른 npm 패키지를 해석할 수 있으므로 사용하지 않습니다.
+
+```bash
+npm exec --package=@01.works/visual-review -- visual-review configure --email <owner-email> --list
+npm exec --package=@01.works/visual-review -- visual-review configure --email <owner-email> --project <project-id>
+npm exec --package=@01.works/visual-review -- visual-review list
+npm exec --package=@01.works/visual-review -- visual-review get <comment-id>
+npm exec --package=@01.works/visual-review -- visual-review reply <comment-id> --body "수정했습니다."
+npm exec --package=@01.works/visual-review -- visual-review export --format json --output feedback.json
+npm exec --package=@01.works/visual-review -- visual-review webhook set --url https://hooks.example/review --secret "$WEBHOOK_SECRET"
+npm exec --package=@01.works/visual-review -- visual-review webhook get
+```
+
+프로젝트에 이미 설치되어 있으면 package script 별칭도 사용할 수 있습니다.
+
+```json
+{ "scripts": { "review": "visual-review" } }
+```
+
+```bash
+npm run review -- list
+npm run review -- logout
+```
+
+`configure`는 이메일 코드를 터미널의 숨김 입력으로 확인한 뒤, 프로젝트 하나에
+고정된 30일 credential만 `.visual-review.json`에 POSIX mode 0600으로 저장합니다. owner
+JWT와 인증 코드는 출력하거나 저장하지 않습니다. 성공 결과는 JSON stdout, 진단은
+stderr로 나갑니다. 만료되면 자동 재인증하지 않으며 `configure`를 다시 실행합니다.
+`logout`은 서버에서 session을 폐기한 다음 로컬 설정을 제거합니다.
+`export --output`은 기존 파일을 덮어쓰지 않고 mode 0600의 새 파일만 만듭니다. webhook
+secret은 32~256자이며 CLI가 결과에 되돌려 출력하지 않습니다. 수신자는
+`X-Visual-Review-Timestamp`와 raw body를 점(`.`)으로 연결해 HMAC-SHA256을 계산하고
+`X-Visual-Review-Signature: v1=<hex>`와 constant-time 비교해야 합니다.
+
+브라우저 자동화는 인증된 staging widget에서만 다음 공개 API를 사용합니다.
+
+```js
+const widget = document.querySelector('agency-review-widget')
+await widget.createFeedbackAtPoint({ body: '간격 불일치', clientX: 420, clientY: 180 })
+widget.setMode('review') // 'view' | 'comment' | 'review'
+const archive = widget.exportPageFeedback('json')
+await widget.importPageFeedback(archive)
+```
+
+`ReviewWidgetOptions.repository`는 custom backend seam입니다. 구현체가
+`ReviewRepository`의 snapshot/subscription/entity mutation 계약과 fail-closed 권한을
+지키면 hosted Convex 대신 사용할 수 있습니다. `moveCommentPin`은 선택 capability입니다.
+`reply`는 기존 피드백 thread에 owner 답글을 추가합니다. 네트워크 결과가 불명확한
+호출을 재시도할 때는 같은 `--reply-id <uuid>`를 넘기면 중복 생성되지 않습니다.
+Windows에서는 ACL 검증을 아직 제공하지 않으므로 저장형 `configure`를 거부합니다.
+그 환경에서는 사전 발급한 `VISUAL_REVIEW_TOKEN`, `VISUAL_REVIEW_PROJECT_ID`,
+`VISUAL_REVIEW_SERVICE_URL` 환경변수를 사용해야 합니다.
+
 ### React / Vite
 
 Vite config에 build identity plugin을 한 번 추가하면 CI deployment metadata 또는
@@ -66,9 +122,7 @@ capture에는 파일 위치가 남지 않습니다.
 import { VisualReview } from '@01.works/visual-review/react';
 
 export function App() {
-  return (
-    <VisualReview developerTools={{ codeContextCopy: import.meta.env.DEV }} />
-  );
+  return <VisualReview />;
 }
 ```
 
@@ -183,20 +237,23 @@ npm run preview
 `enabled={false}`는 integrator가 쓸 수 있는 긴급 kill switch일 뿐 정상 설치 계약이
 아닙니다. Origin 연결 해제는 이미 열린 reviewer permission까지 닫는 운영 kill switch입니다.
 
-## 실시간 협업
+## Optional cursor chat
 
-`collaboration`의 두 기능은 기본적으로 꺼져 있습니다.
+Authoritative Convex runtime에서는 reviewer cursor와 ephemeral cursor chat을 하나의 optional
+module로 켤 수 있습니다.
 
 ```tsx
-<VisualReview collaboration={{ cursors: true, chat: true }} />
+<VisualReview cursorChat />
 ```
 
-`cursors`와 `chat`은 저장하지 않는 presence를 사용합니다. `chat`을 켜면 일반 입력
-요소 밖에서 `/`를 눌러 현재 cursor room의 ephemeral 채팅을 열 수 있습니다.
-따라서 저장되는 page chat은 없고, legacy `reviewMessages`는 read-only 호환 data로만
-남습니다. 둘 모두 유효한
-invitation과 같은 deny-by-default project 권한을 전제로 하며 browser flag 자체는
-권한을 부여하지 않습니다.
+기본값은 `false`입니다. 꺼져 있으면 cursor-chat UI와 repository는 각각 lazy chunk 뒤에
+남아 DOM, pointer listener, subscription과 mutation을 만들지 않습니다. 켜면 같은 page의
+reviewer끼리 cursor와 최대 280자의 말풍선을 공유하고, editable element 밖에서 `/`를 눌러
+입력창을 엽니다. 메시지는 comment로 저장되지 않고 25초 TTL의 Convex presence로만
+오갑니다. 연결 오류는 이 optional module만 중단하며 pin/thread/reply 기능은 계속됩니다.
+
+Self-hosted custom runtime은 `cursorChatRepository`와 `cursorChatRoomId`를 제공해야 합니다.
+Instant runtime과 `/v1/collaboration/room` 호환 경로는 제공하지 않습니다.
 
 ## 위젯 위치
 

package/THIRD_PARTY_NOTICES.md

@@ -44,10 +44,6 @@ The bundled selection engine uses `react-grab/primitives`, and the widget UI
 adapts interface elements from the initial UI snapshot below. The bundled
 dock adapts drag thresholds, edge-snap geometry, velocity projection, and
 orientation from the newer dock snapshot below.
-An explicitly enabled developer tool also uses React Grab's context and
-clipboard primitives on first use for code context copying without initializing
-another toolbar, shortcut, or telemetry surface.
-
 - Repository: https://github.com/aidenybai/react-grab
 - Version first integrated: `0.1.50`
 - Initial UI snapshot commit: `2a39bc29e5f8bdbd69095cf1d33d91634576cd20`