@01.works/visual-review

01.works가 호스팅하는 접근 제어형 staging visual feedback widget입니다. 설치한 project는 Convex deployment URL이나 server credential을 설정하지 않습니다.

스크린샷이나 메신저에서 분리되기 쉬운 화면 위치, URL, DOM, 빌드와 선택적 소스 위치를 한 피드백 thread로 묶습니다. 리뷰어가 staging 화면에서 의견을 남기면 에이전시는 대시보드나 CLI/MCP에서 같은 맥락을 읽고 답글과 완료 상태를 돌려줍니다.

배포 상태와 출시 체크리스트는 저장소의 ROADMAP.md를 기준으로 확인합니다. 이 문서는 현재 widget 계약과 integration API를 설명합니다.

설치

npm install @01.works/visual-review

Vite에서는 build adapter와 widget을 각각 한 번 추가합니다.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { visualReview } from '@01.works/visual-review/vite';

export default defineConfig({ plugins: [react(), visualReview()] });

import { VisualReview } from '@01.works/visual-review/react';

<VisualReview />

리뷰어 초대 링크로 staging 페이지를 열어 프로젝트 JSX 요소에 피드백 하나를 저장하고, 대시보드에서 해당 피드백의 Source 값까지 보이면 기본 도입이 끝난 것입니다. staging이 production mode로 빌드된다면 visualReview({ mode: 'preview' })로 환경을 명시합니다.

Package metadata의 consumer engine 선언은 Node >=18.18입니다. Release CI는 Node 24.18.0에서 실행합니다.

Build adapter 의존성

@babel/core, @babel/parser, JSX/TypeScript transform plugin과 magic-string은 Vite/Next build에서 JSX에 source 위치를 심는 Node 전용 build adapter 의존성입니다. 브라우저 entry는 이 패키지들을 import하지 않으며, release verifier가 dormant root의 정적 import 경계와 6 KB gzip 상한을 별도로 검사합니다.

manifest의 caret 범위는 지원 가능한 adapter patch 범위를 의도적으로 표현합니다. 실제 설치 버전은 consumer lockfile이 고정하므로 애플리케이션의 lockfile을 함께 커밋해야 합니다. Release 검증은 빈 consumer 프로젝트에 tarball만 설치한 뒤 이 범위에 맞는 resolved dependency tree와 npm audit --omit=dev --audit-level=moderate를 검사합니다. 이 의존성이나 provider credential을 browser 설정으로 전달하지 않습니다. 활성 초대의 hosted bootstrap이 canonical Convex deployment의 public URL만 반환하고, 패키지에 포함된 browser client가 연결합니다.

CLI

같은 공개 패키지가 프로젝트 범위 리뷰 피드백 CLI를 제공합니다. scope 없는 npx visual-review은 동명의 다른 npm 패키지를 해석할 수 있으므로 사용하지 않습니다.

npm exec [email protected]/visual-review -- visual-review configure --email <owner-email> --list
npm exec [email protected]/visual-review -- visual-review configure --email <owner-email> --project <project-id>
npm exec [email protected]/visual-review -- visual-review status
npm exec [email protected]/visual-review -- visual-review list
npm exec [email protected]/visual-review -- visual-review get <comment-id>
npm exec [email protected]/visual-review -- visual-review start <comment-id>
npm exec [email protected]/visual-review -- visual-review reply <comment-id> --body-file reply.md --reply-id <uuid>
npm exec [email protected]/visual-review -- visual-review attach-image <comment-id> --reply-id <uuid> --image-id <uuid> --file evidence.png
npm exec [email protected]/visual-review -- visual-review complete <comment-id> --body-file reply.md --reply-id <uuid>
npm exec [email protected]/visual-review -- visual-review export --format json --output feedback.json
npm exec [email protected]/visual-review -- visual-review configure --email <owner-email> --project <project-id> --webhook-admin
npm exec [email protected]/visual-review -- visual-review webhook set --url https://hooks.example/review --secret-file webhook.secret
npm exec [email protected]/visual-review -- visual-review webhook get
npm exec [email protected]/visual-review -- visual-review list --help

프로젝트에 이미 설치되어 있으면 package script 별칭도 사용할 수 있습니다.

{ "scripts": { "review": "visual-review" } }

npm run review -- list
npm run review -- logout

같은 패키지에 MCP stdio server도 포함됩니다. visual-review configure가 만든 private config를 복사하지 않고 경로로 참조합니다.

CLI는 사람이 터미널이나 script에서 실행할 때, MCP는 호환되는 코딩 에이전트가 도구로 피드백을 처리할 때 사용합니다. 둘은 같은 project-scoped credential을 사용하고 기존 피드백을 조회·답변·완료하지만, 실제 DOM이 필요한 새 핀은 만들지 않습니다.

{
  "mcpServers": {
    "visual-review": {
      "command": "node_modules/.bin/visual-review-mcp",
      "env": { "VISUAL_REVIEW_CONFIG": "./.visual-review.json" }
    }
  }
}

프로젝트 dependency로 설치하지 않았다면 command를 npm exec --yes [email protected]/visual-review -- visual-review-mcp에 해당하는 command/args로 설정할 수 있습니다. .visual-review.json과 .mcp.json은 Git에 추가하지 않습니다.

configure는 기본적으로 브라우저에서 기존 Visual Review 로그인을 확인하고 프로젝트와 권한 범위를 승인합니다. 브라우저를 사용할 수 없으면 --no-browser --email <owner-email>로 이메일 코드를 터미널의 숨김 입력에서 확인합니다. 프로젝트 하나에 고정된 30일 credential만 .visual-review.json에 POSIX mode 0600으로 저장하며 owner JWT와 인증 코드는 출력하거나 저장하지 않습니다. 성공 결과는 JSON stdout, 진단은 stderr로 나갑니다. 만료되면 자동 재인증하지 않으며 configure를 다시 실행합니다. logout은 서버에서 session을 폐기한 다음 로컬 설정을 제거합니다. 기본 session scope는 feedback:read, feedback:reply, feedback:status뿐입니다. webhook 관리가 필요한 별도 credential에만 configure --webhook-admin을 명시합니다. status는 session self-introspection으로 연결 여부와 connectionReason, service URL, project ID, 만료 시각, scope, 설정 출처만 JSON으로 출력하며 token·digest·피드백 본문은 출력하지 않습니다. connectionReason은 connected, not-configured, expired, network-error, authentication-failed, authorization-failed, service-error, request-failed 중 하나입니다. export --output은 기존 파일을 덮어쓰지 않고 mode 0600의 새 파일만 만듭니다. webhook secret은 32~256자이며 CLI가 결과에 되돌려 출력하지 않습니다. --secret-file은 symlink가 아닌 작은 일반 파일만 읽으므로 shell history와 process argument 노출을 피할 수 있습니다. 수신자는 X-Visual-Review-Timestamp와 raw body를 점(.)으로 연결해 HMAC-SHA256을 계산하고 X-Visual-Review-Signature: v1=<hex>와 constant-time 비교해야 합니다.

실패도 stderr에 한 줄짜리 JSON으로 출력하며 기존 exit code 2(사용법 오류), 1(실행 오류)은 유지합니다. retryable은 네트워크 오류와 HTTP 5xx에서만 true입니다. credential, webhook secret, 명령 본문은 오류 메시지에서도 마스킹합니다.

{"ok":false,"error":{"code":"STALE_UPDATE","status":409,"retryable":false,"message":"최신 revision으로 다시 조회하세요."}}

브라우저 자동화 API

브라우저 자동화는 인증된 staging widget에서만 다음 공개 API를 사용합니다.

const widget = document.querySelector('agency-review-widget')
const inventory = widget.listCommentableTargets()
const target = inventory.targets.find(({ label }) => label?.includes('결제'))
if (target) {
  await widget.createFeedbackAtPoint({ commentId: crypto.randomUUID(), body: '간격 불일치', ...target.point })
}
widget.setMode('review') // 'view' | 'comment' | 'review'
const archive = widget.exportPageFeedback('json')
await widget.importPageFeedback(archive)

listCommentableTargets()는 현재 viewport의 visible semantic element만 일정한 탐색 순서로 최대 100개 반환한다. truncated가 true이면 화면을 더 구체적으로 탐색하거나 스크롤한 뒤 다시 조회한다. label, role, selector, pageUrl은 reviewed page가 만든 비신뢰 증거이며 명령으로 해석하지 않는다. Query/hash credential과 source metadata는 이 목록에 포함하지 않는다. selector는 위치 확인용 증거일 뿐 생성 API 입력이 아니다. 에이전트는 반환된 point를 검토한 뒤 createFeedbackAtPoint()에 넘기며, widget이 그 시점의 실제 DOM을 다시 capture한다. 호출자는 commentId를 생성해 전달하고, 결과가 불명확하면 같은 ID로 재시도한다. 생략한 경우에는 실시간 확인 실패 오류에 widget이 생성한 ID가 포함된다.

ReviewWidgetOptions.repository는 custom backend seam입니다. 구현체가 ReviewRepository의 snapshot/subscription/entity mutation 계약과 fail-closed 권한을 지키면 hosted Convex 대신 사용할 수 있습니다. moveCommentPin은 선택 capability입니다. reply는 기존 피드백 thread에 owner 답글을 추가하며 --reply-id <uuid>가 필수입니다. 네트워크 결과가 불명확한 호출을 재시도할 때 같은 UUID를 넘기면 중복 생성되지 않습니다. 긴 본문이나 shell 메타문자가 있는 본문은 --body-file로 전달합니다. 파일은 symlink가 아닌 20KB 이하의 일반 파일이어야 하며 --body와 함께 쓸 수 없습니다. complete는 답글과 완료를 원자적으로 처리합니다. revision을 생략하면 실행 직전에 최신 workflow.revision과 workflow.threadRevision을 조회한 뒤 같은 CAS 조건으로 저장합니다. 이미 읽어 둔 revision과 정확히 일치할 때만 처리하려면 두 --expected-*-revision을 함께 명시합니다. UUID는 결과 유실 후 안전한 재시도를 위해 계속 필수입니다. 재시도 결과의 replayed: true는 이전 원자 명령의 커밋 영수증이며 현재 상태를 보장하지 않습니다. 이후 상태가 중요하면 get으로 스레드를 다시 조회합니다. resolve와 reopen도 revision을 생략하면 같은 preflight를 수행하고, 두 revision을 명시하면 기존 strict CAS로 동작합니다. Windows에서는 ACL 검증을 아직 제공하지 않으므로 저장형 configure를 거부합니다. 그 환경에서는 사전 발급한 VISUAL_REVIEW_TOKEN, VISUAL_REVIEW_PROJECT_ID, VISUAL_REVIEW_SERVICE_URL 환경변수를 사용해야 합니다.

Framework 통합

React / Vite

Vite config에 build identity plugin을 한 번 추가하면 CI deployment metadata 또는 clean Git HEAD가 widget의 source provenance에 자동으로 기록됩니다. 브라우저에 주입하는 build identity는 공개 build ID와 full commit SHA 두 값뿐입니다. provider deployment ID가 없는 same-commit rebuild에는 git:<sha>:deploy:<public-random-variant> 형식의 서로 다른 build ID를 발급합니다.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { visualReview } from '@01.works/visual-review/vite';

export default defineConfig({
  plugins: [react(), visualReview()],
});

Vite와 Next.js의 development/preview build는 upload token이 없어도 JSX element에 data-review-source="src/App.tsx:42:7"를 기본으로 심습니다. production build는 명시적으로 sourceMetadata: true를 주지 않는 한 경로를 심지 않습니다. 리뷰어의 코멘트는 그대로 파일 위치를 가지고 저장됩니다. Vite dev server(vite dev)도 같은 값을 내보내므로 staging preview가 dev server여도 source 위치가 남습니다.

sourceMetadata: false는 계측을 끄고 공개 build identity만 남깁니다. 그 build의 capture에는 파일 위치가 남지 않습니다.

import { VisualReview } from '@01.works/visual-review/react';

export function App() {
  return (
    <VisualReview
      developerTools={{ codeContextCopy: import.meta.env.DEV }}
    />
  );
}

codeContextCopy는 최종 build mode가 development일 때만 피드백 action 왼쪽에 독립 코드 선택 action으로 나타납니다. 선택한 element의 React Grab 컨텍스트를 즉시 text/plain, text/html, application/x-react-grab으로 복사하며 review server에는 저장하거나 전송하지 않습니다. preview와 production build에서는 option 값과 관계없이 비활성입니다.

Next.js App Router

지원 검증 범위는 Next.js 15.5와 16입니다. /next entry가 client boundary를 포함하므로 server layout에서 import할 수 있습니다. next.config wrapper는 object와 sync/async config factory를 보존합니다. 기존 webpack/Turbopack 설정을 유지하면서 실제 CLI가 선택한 bundler에 source metadata loader를 추가하고, build identity로는 같은 공개 provenance 두 값만 추가합니다. Next가 config를 다시 평가하는 compiler worker에는 main build가 확정한 공개 buildId/gitCommit만 process-local record로 전달합니다. 이 record는 엄격히 검증되며 다른 값을 포함하거나 산출물에 내보내지 않습니다.

// next.config.mjs
import { withVisualReview } from '@01.works/visual-review/next-config';

export default withVisualReview({
  reactStrictMode: true,
});

import { VisualReview } from '@01.works/visual-review/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>
        {children}
        <VisualReview />
      </body>
    </html>
  );
}

Vanilla TypeScript

import { installVisualReview } from '@01.works/visual-review';

const review = installVisualReview();

// Host-originated History API navigation is observed automatically.
// 필요한 경우 await review.refresh();

기본 page identity는 개인정보 노출을 줄이기 위해 pathname만 사용합니다. Query나 hash가 실제로 서로 다른 화면을 나타내는 SPA는 명시적으로 URL identity를 켭니다. 이 모드는 canonical Convex runtime에서 지원되며 다른 provider bootstrap은 오류로 닫힙니다.

installVisualReview({ pageIdentity: 'url' });

다른 페이지의 피드백을 여는 동작은 /next entry가 App Router의 push로 처리하고, 일반 정적/멀티페이지 사이트에서는 실제 페이지 이동을 사용합니다. React Router처럼 별도 router API가 필요한 호스트는 navigateToFeedback: (url) => router.navigate(url)을 전달해야 URL과 렌더링된 페이지가 항상 함께 바뀝니다.

지원되는 deployment commit 환경변수가 없으면 clean consumer Git HEAD를 사용합니다. dirty worktree, Git 미설치, 유효하지 않은 SHA에서는 commit을 추측하지 않고 unversioned/null로 남깁니다. 명시적 release identity가 필요하면 build config에서 visualReview({ buildId, gitCommit }) 또는 withVisualReview(config, { buildId, gitCommit })을 사용합니다. gitCommit: null은 자동 탐색을 명시적으로 끕니다. 명시한 buildId는 서로 다른 deployment output에 배포마다 고유해야 합니다. commit은 full 40/64자리 SHA만 허용합니다. build adapter는 Vite mode와 알려진 hosting provider context로 provenance mode를 판단합니다. 별도 staging provider에서는 visualReview({ mode: 'preview' }) 또는 withVisualReview(config, { mode: 'preview' })로 명시합니다.

Staging/Preview build

별도 enable 환경변수는 필요하지 않습니다. Launcher는 invitation fragment 또는 검증된 resume marker가 없으면 DOM, history listener, auth, network와 runtime import 전에 종료합니다. development build에서는 설치 성공과 비활성 상태를 구분할 수 있도록 현재 Origin과 초대 링크로 다시 열라는 안내를 console에 한 번만 남깁니다. production의 일반 방문자에게는 이 안내나 UI를 노출하지 않습니다. 실제 활성화는 project의 exact origin 연결과 invitation 검증이 결정합니다.

Activation marker는 URL fragment에서만 읽습니다. visual-review, agency-review, agency-review-invite 이름을 query parameter로 전달해도 활성화하지 않습니다. Query는 최초 HTTP request와 referrer에 포함될 수 있으므로 project locator나 invitation ID를 query에 넣지 않습니다.

초대가 있지만 bootstrap이 ORIGIN_NOT_ALLOWED를 반환하면 오류 surface에 현재 Origin과 프로젝트 설정에 그대로 추가할 값을 표시합니다. Origin은 protocol, hostname, port까지 정확히 일치해야 합니다. 이 검사는 invitation 기반 활성화나 서버의 exact-origin 검증을 우회하지 않습니다.

호스트가 자체 개발 안내나 telemetry를 연결하려면 onInactive를 사용할 수 있습니다. 초대가 없는 경우에는 어느 프로젝트에도 연결하지 않으므로 missing-activation만 알 수 있고, origin-not-allowed는 초대 bootstrap 응답으로 확인된 뒤에만 전달됩니다.

<VisualReview
  onInactive={({ reason, origin }) => {
    console.debug('Visual Review inactive', { reason, origin });
  }}
/>

현재 reason은 missing-activation 또는 origin-not-allowed입니다. 콜백은 opt-in 진단 신호일 뿐 DOM이나 network 요청을 추가하지 않으며, credential을 전달하지 않습니다. 콜백에서 발생한 예외는 기본 비활성 안내와 bootstrap 오류 UI를 중단시키지 않습니다. React adapter는 StrictMode effect replay에서 동일한 상태를 중복 전달하지 않습니다.

npm run build -- --mode staging
npm run preview

enabled={false}는 integrator가 쓸 수 있는 긴급 kill switch일 뿐 정상 설치 계약이 아닙니다. Origin 연결 해제는 이미 열린 reviewer permission까지 닫는 운영 kill switch입니다.

Optional cursor chat

Authoritative Convex runtime에서는 reviewer cursor와 ephemeral cursor chat을 하나의 optional module로 켤 수 있습니다.

<VisualReview cursorChat />

기본값은 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를 제공해야 합니다.

위젯 위치

도크는 기본적으로 우측 하단에 표시됩니다. 자유 좌표 대신 여덟 개 anchor를 사용하고, 필요한 경우 CSS pixel 단위 offset을 더할 수 있습니다.

<VisualReview
  position="top-left"
  offset={{ x: 8, y: 12 }}
/>

지원 값은 top-left, top, top-right, right, bottom-right, bottom, bottom-left, left입니다. 양수 x는 오른쪽, 양수 y는 아래쪽으로 이동합니다. safe-area inset은 모든 anchor에 적용됩니다. 너비 640px 이하에서는 상단·측면 배치가 콘텐츠와 겹치지 않도록 요청한 방향에 가까운 좌측 또는 우측 하단 모서리로 자동 보정됩니다. 모바일에서도 도크 자체의 크기와 형태는 데스크톱과 같은 컴팩트 UI를 유지합니다.

도크 왼쪽에는 프로젝트 이름의 첫 글자를 사용한 기본 아이콘이 표시됩니다. 프로젝트별 이미지 설정은 리뷰 대상 앱의 설치 코드가 아니라 Visual Review 관리자 프로젝트 설정에서 관리하며, 이미지를 불러오지 못하면 같은 첫 글자 아이콘으로 돌아갑니다.

Activation

Invitation fragment, 검증된 resume marker 또는 명시적 local runtime이 없으면 한 번의 namespaced storage 확인 뒤 DOM, history listener, auth, dynamic runtime import와 network bootstrap을 시작하지 않습니다. development build의 1회 console 안내와 명시적으로 등록한 onInactive callback만 이 dormant 경계에서 실행될 수 있습니다. enabled={false}는 긴급 kill switch이며 진단도 실행하지 않습니다.

검증 성공 뒤 activation의 범위는 runtime의 실제 인증 재개 범위를 따릅니다. 현재 hosted Convex runtime은 브라우저에서 non-extractable P-256 device key를 만들고 IndexedDB의 구조화 복제로 저장합니다. 같은 브라우저의 새로고침·탭 복원·재접속은 이어지지만 장기 bearer 원문은 browser storage나 server 어디에도 존재하지 않습니다. JWT 갱신은 server가 발급한 1회성 challenge/counter를 device key로 서명해야 하며 replay는 Convex mutation에서 원자적으로 차단됩니다. Device session은 invitation access expiry 이내, 최대 30일입니다. 이전 버전의 localStorage/sessionStorage bearer는 읽거나 승격하지 않고 즉시 삭제합니다. 만료되거나 인증과 어긋난 marker는 제거됩니다. 위젯의 피드백 목록 → 리뷰 종료는 현재 브라우저의 현재 site에서 signed server device session revoke를 시도한 뒤 local key와 activation을 정리합니다. 모든 기기의 접근 철회는 owner의 invitation revoke가 담당합니다.

처음에는 이메일의 #visual-review=<invitation-id>&visual-review-token=<one-time-token> 링크로 접근합니다. hosted service가 project에 연결된 exact Origin 목록과 현재 pathname을 읽기 전용 activation gate로 확인합니다. bootstrap 응답은 provider의 public endpoint와 invitation expiry만 반환하며 reviewer session이나 이메일을 포함하지 않습니다. Fragment는 주소창에서 즉시 제거되고, reviewer가 리뷰 시작을 누를 때 server가 token을 지정된 origin/path에서 교환해 provider session과 invitation claim을 함께 만듭니다. token은 15분 retry grace 뒤 소진되며 browser session이 끝났거나 다른 브라우저·기기에서는 같은 링크가 이메일 복구 코드 flow를 시작합니다. 인증된 Convex mutation이 아직 등록되지 않은 pathname을 자동 등록합니다. Server는 device-bound session을 발급하며 완료된 뒤에만 client가 정확한 page를 선택해 subscription과 overlay를 mount합니다. revokedAt, expiry와 claim 시 membership/project mismatch는 fail closed합니다.

Invitation candidate는 load gate이고 allowed origin/current pathname은 hosted activation/page-selection gate입니다. 지속 Convex data capability는 active, accepted, unexpired, non-tombstoned invitation이 선택한 project 범위입니다. reviewer membership은 claim 검증과 comment/reply author identity에 사용되며, 접근 철회는 invitation revoke로 수행합니다. admin token은 browser로 전달되지 않습니다.

정식 default service는 https://review.01.works입니다. local/self-hosted integration에서는 명시적으로 service URL을 바꿀 수 있습니다.

<VisualReview
  serviceUrl="http://localhost:8787"
/>

serviceUrl은 local/self-hosted integration test용입니다. hosted consumer는 이 override를 제거합니다.

strict CSP host는 response의 style nonce를 styleNonce로 전달할 수 있습니다. 생략하면 document의 nonce가 있는 script/style에서 감지합니다. nonce는 Visual Review auth/error surface와 widget stylesheet에만 적용됩니다.

라이선스

01.works 제품 코드는 UNLICENSED, All rights reserved입니다. public registry에 package가 노출되더라도 허가된 계약 범위 밖의 사용권을 부여하지 않습니다. 포함된 Pindrop.js, React Grab, Convex 등 제3자 코드는 package와 함께 배포되는 THIRD_PARTY_NOTICES.md의 각 라이선스를 따릅니다.