@designfever/web-review-kit 0.1.0 → 0.2.0

package/docs/concept.md

@@ -1,102 +0,0 @@
-# Concept
-
-`df-web-review-kit`는 웹 프로젝트 안에 넣는 review shell이다. QA 전용 SaaS나 Chrome extension이 아니라, 프로젝트가 가진 route, viewport, DOM, style context를 그대로 사용해 검수 이슈를 남기는 toolkit이다.
-
-## 해결하려는 문제
-
-웹 QA는 보통 다음 정보가 빠져서 다시 확인하는 시간이 길어진다.
-
-- 정확한 page route
-- viewport size
-- scroll position
-- DOM anchor
-- 깨진 영역의 좌표
-- 사람이 남긴 comment
-- 누가 같은 page를 보고 있는지
-
-review-kit은 이 정보를 review item 하나에 묶어서 저장하고, `/review?...` link로 다시 복원한다.
-
-## 기본 UX
-
-1. `/review`를 연다.
-2. sitemap에서 target page를 고른다.
-3. mobile/tablet/desktop/wide viewport를 고른다.
-4. iframe 안에서 note, DOM note, area item을 만든다.
-5. 개인이 처리할 것은 `local` draft에 둔다.
-6. 팀 공유가 필요한 것만 remote source에 등록한다.
-7. remote item link를 공유하거나 AI prompt로 복사한다.
-
-## Source 개념
-
-### local
-
-개인 draft 저장소다. `localStorage` 기반이라 빠르고, 실험/개인 처리용 QA를 remote에 섞지 않는다.
-
-local item의 `#id`는 개인 브라우저 안에서만 의미가 있다. 여러 사람이 같은 번호를 가질 수 있다.
-
-### remote
-
-팀이 같이 보는 source of record다. 현재 검증 source는 `supabase`다.
-
-local item을 remote에 등록하면 local id/number를 보존하지 않고 remote source가 새 id와 canonical `reviewNumber`를 발급한다. 등록 성공 후 local draft는 삭제한다.
-
-### df-sheet
-
-df-sheet는 issue workflow와 연결되는 remote destination 후보다. review-kit이 df-sheet issue editor가 되면 안 되고, local QA를 issue로 등록하고 restore link를 제공하는 역할이 맞다.
-
-## Item 종류
-
-- `note`: 화면 특정 지점에 남기는 comment.
-- `dom`: DOM element에 anchor를 둔 note.
-- `area`: 사용자가 드래그한 영역.
-
-표시 범위는 mobile/tablet/desktop/wide와 연결된다. DOM item은 viewport가 달라도 anchor를 찾아 복원하는 것을 목표로 한다.
-
-## Presence
-
-Presence는 저장소가 아니다. 현재 접속한 사용자의 page/source/viewport 상태만 공유한다.
-
-현재 UI는 같은 page에 들어온 사용자 id만 page header 쪽에 보여준다. sitemap 같은 상위 화면에서는 page별 접속자 표시로 확장할 수 있다.
-
-## 패키지 경계
-
-Package가 담당하는 것:
-
-- review shell UI
-- iframe target loading
-- marker 생성과 restore
-- prompt generation
-- adapter contract
-- local adapter
-- Supabase adapter
-- presence adapter contract
-
-Host project가 담당하는 것:
-
-- `/review` route 생성
-- page glob 전달
-- viewport preset 전달
-- project id와 storage key 결정
-- remote adapter env와 auth 결정
-- Supabase client 생성
-
-## 0.1 목표
-
-0.1은 완전한 review platform이 아니라, 프로젝트별로 붙여 쓸 수 있는 최소 안정 package다.
-
-포함:
-
-- local draft
-- Supabase remote CRUD
-- Supabase Presence
-- stable remote review number
-- prompt copy
-- route/viewport/scroll/marker restore
-
-보류:
-
-- screenshot upload
-- full df-sheet workflow
-- auth/member 기반 production RLS
-- sitemap presence dashboard
-- Chrome extension

package/docs/df-sheet-adapter.md

@@ -1,336 +0,0 @@
-# df-sheet adapter implementation plan
-
-## Goal
-
-`dfSheetAdapter` connects df-web-review-kit QA items to df-sheet issues.
-
-The first production pilot is Lexus. Keep the adapter local and project-tested
-before exposing it as a package export.
-
-## Current decision
-
-- Use `issues.id` as the canonical QA item id.
-- Add only one df-sheet field: `issues.review_metadata jsonb null`.
-- Store human-readable QA content in `description`.
-- Store restore data in `review_metadata`.
-- Store screenshots through df-sheet `/api/upload`, then attach the returned URL
-  to `issues.attachments`.
-- Use a project/page scoped integration token, not an open unauthenticated API.
-- Publish the adapter only after the Lexus pilot validates create, list, update,
-  delete, upload, and deep-link restore.
-
-## Required df-sheet changes
-
-### Database
-
-Add a nullable JSON field to `issues`.
-
-```sql
-alter table issues
-add column if not exists review_metadata jsonb null;
-```
-
-### API
-
-Pass `review_metadata` through the existing issue APIs.
-
-- `POST /api/issues`
-  - accept `body.review_metadata`
-  - insert it into `issues.review_metadata`
-- `PATCH /api/issues/:id`
-  - accept `body.review_metadata`
-  - update `issues.review_metadata`
-- `GET /api/issues`
-  - include `review_metadata` in list responses
-- `GET /api/issues/:id`
-  - include `review_metadata` in detail responses
-
-Do not hide adapter metadata in `description`. df-sheet uses Tiptap JSON there,
-so a hidden JSON block would be fragile.
-
-### Auth
-
-Add an integration token path for adapter calls.
-
-Recommended rules:
-
-- token is sent with `Authorization: Bearer <token>`
-- token is scoped to one `project_id`
-- token is scoped to one `page_id`
-- token can only create/list/read/update/delete issues in that scope
-- token can upload attachments for those issues
-
-Do not expose issue CRUD without auth.
-
-## Adapter config
-
-```ts
-type DfSheetAdapterOptions = {
-  baseUrl: string;
-  projectId: string;
-  pageId: string;
-  token: string;
-  issueType?: string;
-  issuePriority?: "low" | "medium" | "high" | "urgent";
-};
-```
-
-Example usage during the Lexus pilot:
-
-```ts
-createWebReviewKit({
-  projectId: "lexus-official-v2026",
-  adapter: createDfSheetAdapter({
-    baseUrl: "https://df-sheet.vercel.app",
-    projectId: "<df-sheet-project-id>",
-    pageId: "<df-sheet-page-id>",
-    token: "<integration-token>",
-    issueType: "task",
-    issuePriority: "medium",
-  }),
-});
-```
-
-If the target project has no backend proxy, assume the browser can see this
-token. Keep the token project/page scoped so leakage impact is limited.
-
-## Adapter contract changes
-
-Current adapter contract:
-
-```ts
-interface WebReviewKitAdapter {
-  list(query: ReviewItemQuery): Promise<ReviewItem[]>;
-  create(item: ReviewItem): Promise<ReviewItem>;
-  update(id: string, patch: Partial<Omit<ReviewItem, "id" | "createdAt">>): Promise<ReviewItem>;
-  remove(id: string): Promise<void>;
-}
-```
-
-Add `get(id)` for deep-link restore:
-
-```ts
-interface WebReviewKitAdapter {
-  get(id: string): Promise<ReviewItem | null>;
-  list(query: ReviewItemQuery): Promise<ReviewItem[]>;
-  create(item: ReviewItem): Promise<ReviewItem>;
-  update(id: string, patch: Partial<Omit<ReviewItem, "id" | "createdAt">>): Promise<ReviewItem>;
-  remove(id: string): Promise<void>;
-}
-```
-
-`localAdapter` should implement `get(id)` from local storage.
-
-## Status mapping
-
-df-web-review-kit:
-
-- `todo`
-- `doing`
-- `review`
-- `hold`
-- `done`
-
-df-sheet:
-
-- `todo`
-- `in_progress`
-- `review`
-- `on_hold`
-- `done`
-
-Mapping:
-
-```ts
-const toDfSheetStatus = {
-  todo: "todo",
-  doing: "in_progress",
-  review: "review",
-  hold: "on_hold",
-  done: "done",
-} as const;
-
-const fromDfSheetStatus = {
-  todo: "todo",
-  in_progress: "doing",
-  review: "review",
-  on_hold: "hold",
-  done: "done",
-} as const;
-```
-
-## Review metadata shape
-
-The metadata must be enough to rebuild a `ReviewItem` from a df-sheet issue.
-
-```ts
-type DfSheetReviewMetadata = {
-  schema: "df-web-review-kit";
-  version: 1;
-  reviewProjectId: string;
-  routeKey: string;
-  pageUrl: string;
-  originalUrl?: string;
-  normalizedPath: string;
-  scope?: ReviewItemScope;
-  kind: ReviewItemKind;
-  viewport: ViewportSize;
-  devicePixelRatio?: number;
-  scroll?: {
-    x: number;
-    y: number;
-  };
-  anchor?: DomAnchor;
-  marker?: ReviewMarker;
-  selection?: ReviewSelection;
-  reviewUrl?: string;
-};
-```
-
-Avoid storing screenshot data URLs in metadata. Use `attachments`.
-
-## Issue mapping
-
-### ReviewItem to Issue
-
-```ts
-{
-  project_id: options.projectId,
-  page_id: options.pageId,
-  title: item.title || makeIssueTitle(item),
-  description: makeIssueDescription(item),
-  status: toDfSheetStatus[normalizeReviewItemStatus(item.status)],
-  priority: options.issuePriority ?? "medium",
-  type: options.issueType ?? "task",
-  attachments: item.screenshot ? [uploadedScreenshot] : [],
-  links: makeReviewUrl(item),
-  review_metadata: makeReviewMetadata(item),
-}
-```
-
-### Issue to ReviewItem
-
-```ts
-{
-  id: issue.id,
-  externalIssueId: issue.id,
-  projectId: metadata.reviewProjectId,
-  routeKey: metadata.routeKey,
-  pageUrl: metadata.pageUrl,
-  originalUrl: metadata.originalUrl,
-  normalizedPath: metadata.normalizedPath,
-  scope: metadata.scope,
-  kind: metadata.kind,
-  title: issue.title,
-  comment: extractComment(issue.description),
-  status: fromDfSheetStatus[issue.status],
-  viewport: metadata.viewport,
-  devicePixelRatio: metadata.devicePixelRatio,
-  scroll: metadata.scroll,
-  anchor: metadata.anchor,
-  marker: metadata.marker,
-  selection: metadata.selection,
-  screenshot: undefined,
-  createdAt: issue.created_at,
-  updatedAt: issue.updated_at ?? issue.created_at,
-}
-```
-
-## Deep link flow
-
-Target URL:
-
-```txt
-/review?target=/path&w=390&h=720&item=<issue.id>
-```
-
-Flow:
-
-1. `ReviewShell` reads `item` from the query string.
-2. It calls `adapter.get(itemId)`.
-3. The adapter fetches `GET /api/issues/:id`.
-4. It maps the df-sheet issue to `ReviewItem`.
-5. `ReviewShell` restores target route and viewport from the item metadata.
-6. It reloads the target iframe.
-7. It highlights the restored item after the target document is ready.
-
-The query params `target`, `w`, and `h` are hints for early shell rendering.
-`adapter.get(item)` is the source of truth.
-
-## List sync
-
-MVP behavior:
-
-- load list on review shell mount
-- reload after create/update/delete
-- reload when target route changes
-- reload on manual refresh
-- optionally reload when the window regains focus
-
-Do not start with realtime sync. Add Supabase realtime later only if the Lexus
-pilot shows that multiple reviewers need live updates.
-
-## Delete behavior
-
-Use the existing df-sheet delete API for the pilot:
-
-```txt
-DELETE /api/issues/:id
-```
-
-If teams want QA history preserved later, add an archive/hidden status in
-df-sheet instead of hard delete.
-
-## Implementation phases
-
-### Phase 1: contract
-
-- add `adapter.get(id)`
-- update `localAdapter`
-- update review shell deep-link restore to use adapter data instead of local
-  storage only
-
-### Phase 2: df-sheet adapter
-
-- add `src/adapters/df-sheet.ts`
-- implement `createDfSheetAdapter(options)`
-- implement issue/status/metadata mapping helpers
-- implement screenshot upload helper
-- keep the adapter unexported or internally linked during Lexus pilot
-
-### Phase 3: Lexus pilot
-
-- configure Lexus review shell with df-sheet adapter options
-- test create/list/update/delete
-- test screenshot attachment upload
-- test `/review?...&item=<issue.id>` restore
-- test status changes from both review-kit and df-sheet
-
-### Phase 4: package export
-
-After the Lexus pilot is stable:
-
-- export as `@designfever/web-review-kit/adapters/df-sheet`
-- include adapter files in package build
-- update README with installation/config examples
-- publish npm package
-
-## Verification checklist
-
-- `pnpm typecheck`
-- `pnpm build`
-- create text QA from Lexus review page
-- create capture QA with screenshot
-- list reload shows created issues
-- status update maps both directions
-- delete removes item from list
-- deep link restores route, viewport, and highlighted QA
-- df-sheet issue detail shows title, description, status, attachment, and link
-
-## Open questions
-
-- Lexus df-sheet `project_id`
-- Lexus df-sheet `page_id`
-- integration token creation and rotation flow
-- whether df-sheet should expose an issue type dedicated to QA
-- whether delete should become archive after the pilot

package/docs/df-sheet-next.md

@@ -1,222 +0,0 @@
-# df-sheet adapter next plan
-
-## 목적
-
-df-sheet를 `df-web-review-kit`의 remote destination으로 계속 사용할 때의 역할과 필요한 df-sheet 쪽 변경을 분리해서 정리한다.
-
-Supabase 실험 문서는 adapter 구조 검증용이고, 이 문서는 df-sheet 제품/운영 흐름 기준이다.
-
-## 현재 위치
-
-현재 `dfSheetAdapter`는 review-kit item을 df-sheet issue로 보낸다.
-
-현재 동작:
-
-- `create`: local QA item을 df-sheet issue로 등록
-- `list`: df-sheet issue 목록을 review item으로 변환
-- `get`: issue detail을 review item으로 변환
-- `update/remove`: review-kit 안에서는 read-only로 막음
-- restore data: `issues.review_metadata`
-- review link: issue metadata/link에 `/review?...&item=<issueId>` 저장
-
-현재 shell adapter에서는 df-sheet config에 `updateStatus`와 `remove`를 넣지 않는다. 따라서 df-sheet source에서는 상태 변경 dropdown은 readonly badge로만 둘 수 있고, 삭제 버튼도 숨긴다.
-
-## 권장 역할
-
-df-sheet는 source of record가 되어야 한다. review-kit은 다음 역할까지만 한다.
-
-- local에서 만든 QA를 df-sheet issue로 등록
-- df-sheet issue를 현재 page/viewport에서 restore
-- issue status를 표시
-- 필요 시 status update만 좁게 허용
-
-review-kit이 df-sheet의 전체 issue editor가 되면 안 된다.
-
-## 상태 변경 정책
-
-generic `update`는 넣지 않는다.
-
-df-sheet 상태를 review-kit에서 바꾸고 싶다면 `updateStatus`만 추가한다.
-
-```ts
-{
-  label: 'df-sheet',
-  get,
-  list,
-  create,
-  statusOptions: DF_SHEET_STATUS_OPTIONS,
-  updateStatus: async ({ id, status, statusOption, statusIndex }) => {
-    return dfSheet.updateIssueStatus(id, {
-      status,
-      statusIndex,
-      statusLabel: statusOption.label,
-    });
-  },
-}
-```
-
-상태 기준:
-
-- 저장 identity: `statusOption.value`
-- 표시명: `statusOption.label`
-- 외부 매핑 보조값: `statusIndex`
-
-df-sheet의 실제 status vocabulary가 다르면 adapter에서 mapping한다.
-
-```ts
-const DF_SHEET_STATUS_OPTIONS = [
-  { value: 'todo', label: '작업전' },
-  { value: 'doing', label: '작업중' },
-  { value: 'review', label: '검토 필요' },
-  { value: 'hold', label: '보류' },
-  { value: 'done', label: '완료' },
-] as const;
-```
-
-## df-sheet API 제안
-
-현재 issue CRUD API를 그대로 넓히기보다 review-kit 전용 endpoint를 두는 쪽이 안전하다.
-
-추천 endpoint:
-
-```txt
-GET    /api/review-kit/issues
-GET    /api/review-kit/issues/:id
-POST   /api/review-kit/issues
-PATCH  /api/review-kit/issues/:id/status
-```
-
-선택 endpoint:
-
-```txt
-DELETE /api/review-kit/issues/:id
-```
-
-요청은 integration token 기준으로 project/page scope를 제한한다.
-
-```http
-Authorization: Bearer <review-kit-token>
-```
-
-Token scope:
-
-- `project_id`
-- `page_id`
-- allowed actions: `create`, `read`, optional `update_status`, optional `delete`
-
-브라우저에서 직접 token을 쓰는 경우 누출을 전제로 작게 scope를 잡는다. production에서는 backend proxy 또는 df-sheet domain cookie auth를 우선 검토한다.
-
-## DB 필드
-
-`issues.review_metadata jsonb`는 유지한다.
-
-```sql
-alter table issues
-add column if not exists review_metadata jsonb null;
-```
-
-`review_metadata`에 들어가는 값:
-
-- review item id
-- review number
-- route/normalized path
-- viewport
-- scroll
-- anchor
-- marker
-- selection
-- original comment
-- review link
-- schema/source/version
-
-사람이 읽어야 하는 내용은 `title`/`description`에 둔다. restore에 필요한 구조 데이터는 `review_metadata`에 둔다.
-
-## create flow
-
-1. local item 선택
-2. review-kit이 df-sheet `POST /api/review-kit/issues` 호출
-3. df-sheet가 issue 생성
-4. df-sheet가 issue id/url 반환
-5. remote 등록 성공 시 local item은 삭제하고, 실패 시에만 `syncSubmission`으로 실패 상태를 기록
-
-remote issue id를 local id로 덮어쓰지 않는다. 대신 remote 등록 payload에서는 사람이 볼 번호로 `reviewNumber`를 보낸다.
-
-## list/get flow
-
-`list`는 route 기준으로 좁게 가져온다.
-
-```txt
-project_id=<df-sheet-project-id>
-page_id=<df-sheet-page-id>
-review_source=df-web-review-kit
-review_route_key=<target route>
-```
-
-응답에는 `review_metadata`가 반드시 포함되어야 한다. metadata가 없거나 source/schema가 맞지 않으면 adapter는 review item으로 변환하지 않는다.
-
-## status update flow
-
-df-sheet에서 status 변경을 허용하려면 issue 전체 patch가 아니라 status-only endpoint를 쓴다.
-
-```txt
-PATCH /api/review-kit/issues/:id/status
-```
-
-Body:
-
-```json
-{
-  "status": "doing"
-}
-```
-
-Response는 updated issue와 `review_metadata`를 포함한다.
-
-review-kit adapter는 이 응답을 `ReviewItem`으로 변환한다.
-
-## delete policy
-
-초기에는 df-sheet delete를 review-kit에서 열지 않는 편이 낫다.
-
-이유:
-
-- remote issue 삭제는 팀 공유 데이터에 직접 영향이 크다.
-- review-kit list에서 실수 클릭으로 삭제될 수 있다.
-- df-sheet 내부 권한/감사 로그와 맞춰야 한다.
-
-필요하면 `remove`를 adapter에 넣고, UI는 확인 modal을 추가한다. 현재 shell의 local 삭제 UX와 같은 즉시 삭제 방식으로 remote delete를 열면 안 된다.
-
-## package 관점
-
-df-sheet adapter를 package에 포함할 때도 df-sheet 전용 타입/설정은 adapter 내부에 묶는다.
-
-`ReviewShellAdapter`는 계속 storage-agnostic이어야 한다.
-
-좋은 방향:
-
-- `dfSheetAdapter(options)`는 core `WebReviewKitAdapter` 구현
-- `dfSheetShellAdapter(options)` 또는 helper는 shell-facing adapter config 생성
-- page/review에서는 helper를 조립해서 넘김
-
-예시:
-
-```ts
-const dfSheet = dfSheetAdapter(options);
-
-const REVIEW_ADAPTERS = [
-  localReviewShellAdapter(local),
-  dfSheetReviewShellAdapter(dfSheet, {
-    pageId: options.pageId,
-    statusOptions: DF_SHEET_STATUS_OPTIONS,
-    canUpdateStatus: false,
-  }),
-];
-```
-
-## 남은 결정
-
-- df-sheet에서 review-kit 전용 endpoint를 새로 만들지, 기존 `/api/issues`를 확장할지.
-- status update를 review-kit에서 허용할지.
-- integration token을 cookie auth와 병행할지.
-- df-sheet issue status vocabulary와 review-kit status value를 1:1로 맞출지.
-- remote delete를 허용할지.