@designfever/web-review-kit 0.1.0

package/docs/initial-plan.md

@@ -0,0 +1,226 @@
+# df-web-review-kit 초기 정리
+
+## 결정된 방향
+
+- Repository: `Designfever/df-web-review-kit`
+- NPM package: `@designfever/web-review-kit`
+- 목적: QA 전용 도구가 아니라 웹 페이지 위에 얹는 검수용 toolkit.
+- 1차 대상: Lexus, KIA, Toyota 같은 웹 프로젝트.
+- 설치 방식: 각 프로젝트에 npm package로 설치하고, 프로젝트별 설정만 넣는다.
+- 단축키: 기본은 `Shift + Q`로 QA mode 진입.
+- Chrome extension은 1차 대상이 아니다. 소스 접근 없는 사이트까지 다뤄야 할 때 adapter/wrapper로 나중에 검토한다.
+
+## 큰 구조
+
+패키지는 core와 module, adapter로 나눈다.
+
+- Core
+  - overlay root 생성
+  - keyboard shortcut 관리
+  - panel/modal/layer 공통 UI
+  - 현재 URL/viewport/scroll 상태 수집
+  - module lifecycle 관리
+- QA module
+  - 현재 페이지 기준 QA list 표시
+  - text-only QA 등록
+  - 화면 영역 드래그 캡처 QA 등록
+  - DOM anchor 계산
+- Grid module
+  - 기존 grid helper를 나중에 module로 이관
+  - 1차 MVP에는 인터페이스만 열어둔다
+- Figma module
+  - Figma overlay helper를 나중에 module로 이관
+  - 1차 MVP에는 인터페이스만 열어둔다
+- Adapter
+  - 저장소/외부 서비스 연동만 담당
+  - core와 QA module은 df-sheet, GitHub, localStorage 같은 저장소를 직접 알지 않는다
+
+## Adapter로 뺀다는 뜻
+
+Core는 "무엇을 수집하고 어떤 UI를 보여줄지"만 담당한다.
+Adapter는 "수집한 QA item을 어디에 저장하고 어떻게 읽어올지"만 담당한다.
+
+예시:
+
+- Lexus: `dfSheetAdapter`
+- 초기 개발/검증: `localAdapter`
+- 미래 확장: `githubIssueAdapter`, `jsonFileAdapter` 등
+
+이렇게 분리하면 df-sheet 연동 방식이 바뀌어도 overlay core를 건드리지 않아도 된다.
+
+## 1차 MVP
+
+우선 df-sheet 연동 없이 local adapter로 기능을 검증한다.
+
+1. npm package scaffold
+2. target project에서 초기화 가능한 API
+3. `Shift + Q`로 QA mode toggle
+4. 현재 URL 기준 QA list 표시
+5. text-only QA 생성
+6. drag capture QA 생성
+7. DOM anchor + relative coordinate 저장
+8. local adapter 저장/조회/삭제
+
+1차에서 Figma overlay와 grid helper를 완성하려고 하지 않는다.
+다만 나중에 붙일 수 있게 module 구조는 처음부터 열어둔다.
+
+## Local adapter 저장 방식
+
+이름은 local adapter지만 실제 저장은 둘로 나눈다.
+
+- Metadata: `localStorage`
+- Screenshot/blob: `IndexedDB`
+
+이유:
+
+- `localStorage`에 screenshot data URL을 계속 넣으면 용량이 빨리 찬다.
+- IndexedDB는 이미지 blob 저장에 더 적합하다.
+
+## QA item 기본 데이터
+
+```ts
+type ReviewItem = {
+  id: string;
+  projectId: string;
+  pageUrl: string;
+  normalizedPath: string;
+  kind: "text" | "capture";
+  title?: string;
+  comment: string;
+  status: "open" | "resolved";
+  viewport: {
+    width: number;
+    height: number;
+  };
+  scroll?: {
+    x: number;
+    y: number;
+  };
+  anchor?: DomAnchor;
+  selection?: RelativeSelection;
+  screenshotAssetId?: string;
+  externalIssueId?: string;
+  createdAt: string;
+  updatedAt: string;
+};
+```
+
+## DOM anchor 전략
+
+단순 viewport 좌표만 저장하면 반응형 화면에서 위치가 틀어진다.
+따라서 선택 영역과 가장 가까운 DOM element를 anchor로 잡고, 그 element 기준 상대 좌표를 저장한다.
+
+Anchor 우선순위:
+
+1. `data-qa-id` 또는 package 설정으로 지정한 attribute
+2. `id`가 안정적인 element
+3. 의미 있는 class/name/role 기반 selector
+4. 텍스트 fingerprint
+5. DOM path fallback
+
+Relative coordinate 예시:
+
+```ts
+type RelativeSelection = {
+  x: number; // (selection.left - anchor.left) / anchor.width
+  y: number; // (selection.top - anchor.top) / anchor.height
+  width: number; // selection.width / anchor.width
+  height: number; // selection.height / anchor.height
+};
+```
+
+나중에 다시 표시할 때는 현재 anchor rect를 찾고 위 비율로 위치를 복원한다.
+
+## QA 생성 흐름
+
+Text-only:
+
+1. 사용자가 QA mode에서 text 등록 선택
+2. 현재 URL, viewport width/height 저장
+3. 사용자가 comment 입력
+4. adapter에 저장
+
+Capture:
+
+1. 사용자가 capture 선택
+2. 깨진 영역을 drag로 선택
+3. 선택 영역 screenshot 생성
+4. 선택 영역과 가장 가까운 DOM anchor 계산
+5. anchor 기준 relative coordinate 저장
+6. comment 입력
+7. adapter에 저장
+
+Screenshot 구현은 처음에는 `html2canvas` 계열로 시작할 수 있다.
+단, cross-origin image/video/canvas는 깨질 수 있으니 정확도가 중요해지면 browser extension 또는 native capture 방식도 검토한다.
+
+## df-sheet 연동 방향
+
+df-sheet adapter는 QA item을 df-sheet issue로 매핑한다.
+
+- 생성: QA item 생성 시 df-sheet issue 생성
+- 조회: 현재 URL에 해당하는 unresolved issue만 QA list에 표시
+- 해결: df-sheet issue status가 `done`이면 QA list에서 제외
+- 첨부: capture screenshot은 issue attachment로 등록
+- Metadata: page URL, viewport, anchor, selection 정보를 issue에 저장
+
+df-sheet에 dedicated metadata field가 없으면 1차는 description이나 hidden JSON block으로 저장할 수 있다.
+다만 장기적으로는 issue metadata field를 추가하는 편이 낫다.
+
+## 예상 초기화 API
+
+```ts
+import { createWebReviewKit, localAdapter } from "@designfever/web-review-kit";
+
+createWebReviewKit({
+  projectId: "lexus-renewal",
+  adapter: localAdapter({
+    storageKey: "lexus-review-items",
+  }),
+  hotkeys: {
+    qa: "Shift+Q",
+  },
+  anchors: {
+    attribute: "data-qa-id",
+  },
+  modules: {
+    qa: true,
+    grid: false,
+    figma: false,
+  },
+});
+```
+
+## 나중에 붙일 모듈
+
+Grid helper:
+
+- breakpoint/grid overlay
+- column/gutter 표시
+- 프로젝트별 grid preset
+
+Figma helper:
+
+- Figma screenshot 또는 frame overlay
+- opacity/blend mode 조절
+- viewport별 기준 이미지 전환
+
+둘 다 core overlay와 단축키/패널 시스템은 공유하되, QA 저장소와는 강하게 묶지 않는다.
+
+## 열어둔 질문
+
+- package 배포를 public npm으로 할지 private npm으로 할지
+- target project가 Next/Vite/vanilla를 모두 포함하는지
+- React dependency를 peer로 둘지, framework-agnostic DOM package로 갈지
+- df-sheet 인증은 cookie 기반인지 token 기반인지
+- df-sheet에 QA metadata 전용 field를 추가할지
+- target site에 `data-qa-id`를 어느 정도 심을지
+- screenshot 정확도를 어디까지 요구할지
+
+## 다음 세션에서 할 일
+
+1. package scaffold 선택: Vite library, tsup, or rollup
+2. core API 타입 먼저 작성
+3. local adapter 인터페이스 작성
+4. QA overlay 최소 UI 구현
+5. Lexus/KIA/Toyota 중 하나에 playground로 붙여 검증
+

package/docs/installation.md

@@ -0,0 +1,222 @@
+# Installation
+
+Host project에 `df-web-review-kit`를 설치하고 `/review` route에서 `mountReviewShell()`을 호출한다.
+
+## Package install
+
+NPM package로 사용할 때:
+
+```bash
+pnpm add @designfever/web-review-kit react react-dom
+```
+
+Supabase remote/presence를 쓰면 host project에 Supabase client도 설치한다.
+
+```bash
+pnpm add @supabase/supabase-js
+```
+
+Lexus repo 안에서 검증할 때는 file dependency를 사용한다.
+
+```json
+"@designfever/web-review-kit": "file:packages/df-web-review-kit"
+```
+
+## Vite route
+
+Vite project에서는 `page/review/index.html`과 `page/review/index.tsx` 같은 review entry를 만든다.
+
+Minimal `index.html`:
+
+```html
+<div id="root"></div>
+<script type="module" src="./index.tsx"></script>
+```
+
+Minimal `index.tsx`:
+
+```tsx
+import {
+  createReviewPagesFromGlob,
+  mountReviewShell,
+} from '@designfever/web-review-kit/react-shell';
+import {
+  REVIEW_WORKFLOW_STATUS_OPTIONS,
+  localAdapter,
+} from '@designfever/web-review-kit';
+
+const REVIEW_PROJECT_ID = 'my-project';
+const local = localAdapter({
+  storageKey: `${REVIEW_PROJECT_ID}-review-items`,
+});
+
+const pages = createReviewPagesFromGlob(import.meta.glob('/**/index.tsx'), {
+  exclude: (href) => href === '/review/',
+});
+
+mountReviewShell({
+  projectId: REVIEW_PROJECT_ID,
+  pages,
+  adapters: [
+    {
+      label: 'local',
+      get: (id) => local.get(id),
+      list: (query) => local.list(query),
+      create: (item) => local.create(item),
+      statusOptions: REVIEW_WORKFLOW_STATUS_OPTIONS,
+      updateStatus: ({ id, status }) => local.update(id, { status }),
+      syncSubmission: ({ id, patch }) => local.update(id, patch),
+      remove: (id) => local.remove(id),
+    },
+  ],
+  reviewPathPrefix: '/review',
+});
+```
+
+## Supabase remote example
+
+Supabase를 붙일 때는 host project에서 client를 만들고 package adapter에 주입한다.
+
+```tsx
+import {
+  createFallbackPresenceAdapter,
+  createLocalPresenceAdapter,
+  createSupabasePresenceAdapter,
+  type ReviewShellAdapter,
+  type SupabasePresenceClient,
+} from '@designfever/web-review-kit/react-shell';
+import {
+  REVIEW_WORKFLOW_STATUS_OPTIONS,
+  localAdapter,
+  supabaseAdapter,
+  type SupabaseReviewClient,
+} from '@designfever/web-review-kit';
+import { createClient } from '@supabase/supabase-js';
+
+const REVIEW_PROJECT_ID = 'lexus-official-v2026';
+const REVIEW_PATH_PREFIX = '/review';
+
+const local = localAdapter({
+  storageKey: `${REVIEW_PROJECT_ID}-review-items`,
+});
+
+const supabaseClient = import.meta.env.VITE_REVIEW_SUPABASE_ANON_KEY
+  ? createClient(
+      import.meta.env.VITE_REVIEW_SUPABASE_URL,
+      import.meta.env.VITE_REVIEW_SUPABASE_ANON_KEY
+    )
+  : null;
+
+const remote = supabaseClient
+  ? supabaseAdapter({
+      client: supabaseClient as unknown as SupabaseReviewClient,
+      table: import.meta.env.VITE_REVIEW_SUPABASE_TABLE || 'review_items',
+      projectId: REVIEW_PROJECT_ID,
+      source: 'supabase',
+      reviewPathPrefix: REVIEW_PATH_PREFIX,
+    })
+  : null;
+
+const adapters = [
+  {
+    label: 'local',
+    get: (id) => local.get(id),
+    list: (query) => local.list(query),
+    create: (item) => local.create(item),
+    statusOptions: REVIEW_WORKFLOW_STATUS_OPTIONS,
+    updateStatus: ({ id, status }) => local.update(id, { status }),
+    syncSubmission: ({ id, patch }) => local.update(id, patch),
+    remove: (id) => local.remove(id),
+  },
+  ...(remote
+    ? [
+        {
+          label: 'supabase',
+          get: (id) => remote.get(id),
+          list: (query) => remote.list(query),
+          create: (item) => remote.create(item),
+          statusOptions: REVIEW_WORKFLOW_STATUS_OPTIONS,
+          updateStatus: ({ id, status }) => remote.update(id, { status }),
+          remove: (id) => remote.remove(id),
+        } satisfies ReviewShellAdapter,
+      ]
+    : []),
+] satisfies ReviewShellAdapter[];
+
+const localPresence = createLocalPresenceAdapter({
+  channelName: `${REVIEW_PROJECT_ID}:review-presence`,
+});
+
+const presence = supabaseClient
+  ? createFallbackPresenceAdapter(
+      createSupabasePresenceAdapter({
+        client: supabaseClient as unknown as SupabasePresenceClient,
+        channelPrefix: 'review-presence',
+        private: import.meta.env.VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE === 'true',
+      }),
+      localPresence
+    )
+  : localPresence;
+```
+
+그 다음 `mountReviewShell({ adapters, presence, ... })`에 넘긴다.
+
+## Environment
+
+```env
+VITE_REVIEW_SUPABASE_URL=https://your-project.supabase.co
+VITE_REVIEW_SUPABASE_ANON_KEY=
+VITE_REVIEW_SUPABASE_TABLE=review_items
+VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE=false
+```
+
+Rules:
+
+- browser env에는 Supabase `anon` key만 넣는다.
+- `service_role` key는 절대 browser env에 넣지 않는다.
+- package는 Supabase dependency를 직접 만들지 않는다. host project가 `createClient()`를 호출한다.
+
+## Viewport preset
+
+Project별 design width가 다르면 `presets`를 넘긴다.
+
+```tsx
+mountReviewShell({
+  projectId: REVIEW_PROJECT_ID,
+  pages,
+  adapters,
+  presets: [
+    { label: 'Mobile', kind: 'mobile', width: 540, height: 1080, designWidth: 540 },
+    { label: 'Tablet', kind: 'tablet', width: 768, height: 1024, designWidth: 768 },
+    { label: 'Desktop', kind: 'desktop', width: 1440, height: 900, designWidth: 1440 },
+    { label: 'Wide', kind: 'wide', width: 1980, height: 1080, designWidth: 1980 },
+  ],
+});
+```
+
+## Development commands
+
+Lexus repo 기준:
+
+```bash
+pnpm dev:review
+pnpm review-kit:typecheck
+pnpm typecheck:review
+pnpm review-kit:build
+pnpm build:review
+```
+
+Package source를 수정하면 `pnpm review-kit:build`로 `dist`를 갱신한다.
+
+## Publish checklist
+
+0.1 package 배포 전 확인:
+
+- `packages/df-web-review-kit/package.json`의 `files`에 `dist`, `src`, `docs`, `README.md` 포함
+- `pnpm review-kit:typecheck`
+- `pnpm review-kit:build`
+- local source에서 note/dom/area 생성 확인
+- local item을 remote로 등록하면 local draft 삭제 확인
+- remote source에서 status update/delete 확인
+- `/review?source=supabase&target=...&item=...` restore 확인
+- Supabase `reviewNumber`가 삭제 후 재사용되지 않는지 확인

package/docs/package-split-checkpoint.md

@@ -0,0 +1,79 @@
+# Package split checkpoint
+
+Date: 2026-06-20
+Branch: `uforgot/feat/review-kit-stabilize-ui`
+
+## Goal
+
+Prepare `packages/df-web-review-kit` to behave like an independent package before moving Figma overlay or editing proposal work into it.
+
+This checkpoint is not the actual repo split and does not publish the package.
+
+## Public entrypoints
+
+Only these imports are public:
+
+```ts
+import { createWebReviewKit, localAdapter } from '@designfever/web-review-kit';
+import { mountReviewShell } from '@designfever/web-review-kit/react-shell';
+```
+
+The package export map exposes:
+
+- `.` → core API, adapters, shared types.
+- `./react-shell` → review shell UI, presence adapters, page glob helper.
+- `./package.json` → package metadata for tooling.
+
+`src/*` paths are not public API.
+
+## Publish/file policy
+
+`package.json#files` intentionally includes only:
+
+- `dist`
+- `docs`
+- `README.md`
+
+`src` is kept in the repo for development but excluded from the package file list so consumers rely on the exported API and generated declarations.
+
+## Dependency policy
+
+- `react` and `react-dom` stay peer dependencies.
+- `lucide-react` stays bundled into the built `react-shell` output for now. It is a dev/build dependency, not a host peer dependency.
+- Figma token/API/fetch logic must not enter package core in this branch.
+
+## Host consumption policy
+
+The Lexus host imports the package through the same public package entrypoints it would use after a repo split:
+
+- `@designfever/web-review-kit`
+- `@designfever/web-review-kit/react-shell`
+
+Vite no longer aliases those package imports to `packages/df-web-review-kit/src` in dev. The host resolves the installed file dependency under `node_modules`, so `pnpm review-kit:build` must be run after package source changes to refresh `dist` and sync the installed package.
+
+## Review/test page policy
+
+The Lexus `/review` page remains the integration smoke page. It is a consumer of the package, not part of the package surface.
+
+If this package is moved to a separate repo later, keep a small playground/example app outside the package publish files so review-shell behavior can still be manually verified.
+
+## Verification gate
+
+Before moving this item to review, run:
+
+```bash
+pnpm review-kit:typecheck
+pnpm review-kit:build
+pnpm exec tsc --noEmit
+pnpm exec vite build --mode seo
+pnpm --dir packages/df-web-review-kit pack --pack-destination /tmp/df-web-review-kit-pack
+```
+
+Manual smoke:
+
+- Open `/review`.
+- Confirm empty QA state.
+- Inject or create a local QA item.
+- Confirm card and prompt modal still render.
+- Confirm settings and sitemap modals still open.
+- Confirm browser console has no errors/warnings.

package/docs/presence-handoff.md

@@ -0,0 +1,138 @@
+# review-kit presence handoff
+
+## 목적
+
+QA 작업 중 "누가 어떤 review page를 보고 있는지"를 보여주기 위한 presence 기능 handoff 문서다.
+
+Presence는 저장소가 아니다. `local`, `df-sheet`, `supabase` 같은 review item adapter는 영속 데이터 CRUD를 맡고, presence adapter는 현재 접속 세션 상태만 공유한다.
+
+## 현재 구현
+
+추가된 파일:
+
+- `src/react-shell/presence.ts`
+- `src/react-shell/types.ts`
+- `src/react-shell.tsx`
+- Lexus mount: `page/review/index.tsx`
+
+현재 `page/review/index.tsx`는 local 개발용 presence adapter를 붙인다.
+
+```ts
+import { createLocalPresenceAdapter } from '@designfever/web-review-kit/react-shell';
+
+const REVIEW_PRESENCE_ADAPTER = createLocalPresenceAdapter({
+  channelName: `${REVIEW_PROJECT_ID}:review-presence`,
+});
+
+mountReviewShell({
+  projectId: REVIEW_PROJECT_ID,
+  pages,
+  adapters: REVIEW_ADAPTERS,
+  presence: REVIEW_PRESENCE_ADAPTER,
+});
+```
+
+현재 Lexus pilot은 `VITE_REVIEW_SUPABASE_ANON_KEY`가 있으면 Supabase Presence를 쓰고, 없으면 `createLocalPresenceAdapter()`로 fallback한다.
+
+`createLocalPresenceAdapter()`는 `BroadcastChannel` 기반이다. 같은 origin의 여러 review 탭에서만 동작한다. 실제 팀 공유용 구현은 Supabase adapter를 사용한다.
+
+```env
+VITE_REVIEW_SUPABASE_URL=https://vhqnvfkamnpgyqclohso.supabase.co
+VITE_REVIEW_SUPABASE_ANON_KEY=
+VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE=false
+```
+
+## Public contract
+
+```ts
+type ReviewPresenceAdapter = {
+  label: string;
+  connect: (
+    context: ReviewPresenceContext
+  ) => Promise<ReviewPresenceSession> | ReviewPresenceSession;
+};
+
+type ReviewPresenceSession = {
+  update: (state: Partial<ReviewPresenceState>) => void | Promise<void>;
+  subscribe: (
+    callback: (users: ReviewPresenceUser[]) => void
+  ) => () => void;
+  disconnect: () => void | Promise<void>;
+};
+```
+
+`ReviewPresenceState`는 현재 이 shape을 사용한다.
+
+```ts
+type ReviewPresenceState = {
+  projectId: string;
+  sessionId: string;
+  userId: string;
+  displayName: string;
+  color: string;
+  routeKey: string;
+  target: string;
+  source: 'local' | 'df-sheet';
+  viewport: {
+    label: string;
+    width: number;
+    height: number;
+    kind: 'mobile' | 'tablet' | 'desktop' | 'wide';
+  };
+  mode: 'idle' | 'note' | 'element' | 'area';
+  selectedItemId?: string | null;
+  selectedReviewNumber?: number | null;
+  status: 'idle' | 'reviewing' | 'editing';
+  updatedAt: string;
+};
+```
+
+## Shell behavior
+
+- Settings의 `User ID`가 비어 있으면 presence는 연결하지 않는다.
+- `User ID`가 있으면 우측 QA list header 아래에 `online N`과 user chip을 보여준다.
+- user chip에는 `displayName`, `target`, `viewport.label`을 표시한다.
+- 현재 탭은 `is-self` class로 표시된다.
+- 업데이트는 느린 상태만 보낸다:
+  - route/target
+  - source
+  - viewport
+  - review mode
+  - selected item/review number
+  - status
+- scroll, mousemove, cursor 위치는 보내지 않는다.
+
+## 왜 storage adapter와 분리했나
+
+storage adapter:
+
+- `get`
+- `list`
+- `create`
+- `updateStatus`
+- `remove`
+- remote promote/move
+
+presence adapter:
+
+- `connect`
+- `update`
+- `subscribe`
+- `disconnect`
+
+수명주기가 다르다. storage는 item의 영속 상태이고, presence는 websocket session 상태다. 같은 adapter array에 넣으면 API가 어색해지고, remote item source를 바꾸는 일과 협업 session을 바꾸는 일이 섞인다.
+
+## 다음 작업
+
+1. `supabasePresenceAdapter` 추가
+2. `@supabase/supabase-js`를 peer/dev dependency로 둘지 별도 package adapter로 분리할지 결정
+3. Supabase project/env 연결
+4. private channel + Realtime Authorization 적용
+5. 두 브라우저 또는 두 기기에서 같은 project presence 확인
+
+## 주의점
+
+- Presence payload는 작게 유지한다.
+- high-frequency state는 Presence에 넣지 않는다.
+- 현재 `ReviewSource`가 `'local' | 'df-sheet'`로 고정되어 있어서 source generalization 작업과 Supabase storage adapter 작업이 만나면 타입을 먼저 풀어야 한다.
+- `User ID`는 현재 localStorage 기반이다. 실제 remote presence에서는 auth user id나 project member id로 바꾸는 편이 맞다.