@designfever/web-review-kit 0.6.0 → 0.7.1

package/docs/installation.md

@@ -3,6 +3,7 @@
 Install `df-web-review-kit` in a host project and mount the review shell on a `/review` route.
 
 The default setup is local-only. Remote DB and presence are optional adapters.
+For the QA adapter and Figma image store split, see [Adapter boundaries](adapters.md).
 
 ## Package Install
 
@@ -16,6 +17,22 @@ Supabase is optional. Install it only in host projects that use the Supabase ada
 pnpm add @supabase/supabase-js
 ```
 
+## Environment
+
+Copy the repository [.env.sample](../.env.sample) into the host project as `.env.local`.
+
+```bash
+cp node_modules/@designfever/web-review-kit/.env.sample .env.local
+```
+
+For a local-only setup, set only the project id:
+
+```env
+VITE_REVIEW_PROJECT_ID=my-project
+```
+
+Supabase and source-opening values are optional. Leave Supabase URL/key empty when the review shell should use local browser storage only.
+
 ## Vite Route
 
 Create a review entry such as:
@@ -44,8 +61,9 @@ import {
   localAdapter,
 } from '@designfever/web-review-kit';
 
-const REVIEW_PROJECT_ID = 'my-project';
+const REVIEW_PROJECT_ID = import.meta.env.VITE_REVIEW_PROJECT_ID || 'my-project';
 const REVIEW_PATH_PREFIX = '/review';
+const REVIEW_USER_ID = import.meta.env.VITE_REVIEW_USER_ID || '';
 
 const local = localAdapter({
   storageKey: `${REVIEW_PROJECT_ID}-review-items`,
@@ -111,7 +129,7 @@ import {
 } from '@designfever/web-review-kit';
 import { createClient } from '@supabase/supabase-js';
 
-const REVIEW_PROJECT_ID = 'my-project';
+const REVIEW_PROJECT_ID = import.meta.env.VITE_REVIEW_PROJECT_ID || 'my-project';
 const REVIEW_PATH_PREFIX = '/review';
 
 const local = localAdapter({
@@ -138,6 +156,7 @@ const remote = supabaseClient
 const adapters = [
   {
     label: 'local',
+    defaultUserId: REVIEW_USER_ID,
     get: (id) => local.get(id),
     list: (query) => local.list(query),
     create: (item) => local.create(item),
@@ -151,6 +170,7 @@ const adapters = [
     ? [
         {
           label: 'supabase',
+          defaultUserId: REVIEW_USER_ID,
           get: (id) => remote.get(id),
           list: (query) => remote.list(query),
           create: (item) => remote.create(item),
@@ -220,15 +240,25 @@ Captured DOM nodes will include `data-wrk-source-file`, `data-wrk-source-line`,
 
 In the review shell, hold `Option` over the target iframe to show source candidates from the DOM ancestry. Click the target to pin the candidate list, then choose which file to open. The side rail Source Tree panel lists section/source/data candidates and can scroll to a section or open its source/data file. It can also show live box metrics, text/font metadata, media URLs, and class tags for each node. If the file path is absolute, it opens directly. If the plugin stores relative paths, pass `sourceRoot` when mounting the shell.
 
+Source opening reads these optional host env values from `.env.local`:
+
+```env
+VITE_REVIEW_SOURCE_ROOT=/absolute/path/to/project
+VITE_REVIEW_SOURCE_EDITOR=cursor
+VITE_REVIEW_SOURCE_URL_TEMPLATE=
+```
+
+`VITE_REVIEW_SOURCE_ROOT` is needed when the locator stores relative paths. Absolute source paths can open without it. `VITE_REVIEW_SOURCE_EDITOR` supports `vscode`, `cursor`, `webstorm`, and `custom`. Use `VITE_REVIEW_SOURCE_URL_TEMPLATE` only with `custom`; the template supports `{path}`, `{encodedPath}`, `{line}`, and `{column}`.
+
+In Vite/ESM hosts, env values override matching `sourceRoot`, `sourceInspector.editor`, and `sourceInspector.urlTemplate` init values. Init values still work as a fallback for existing projects and CommonJS consumers.
+
 ```tsx
 mountReviewShell({
   projectId: REVIEW_PROJECT_ID,
   pages,
   adapters,
   reviewPathPrefix: REVIEW_PATH_PREFIX,
-  sourceRoot: import.meta.env.VITE_REVIEW_SOURCE_ROOT,
   sourceInspector: {
-    editor: 'vscode', // 'vscode' | 'cursor' | 'webstorm' | 'custom'
     maxDepth: 9,
     hoverOutline: true,
     includePlacer: false,
@@ -248,7 +278,7 @@ In React shell mode, DOM/area draft composers dock into the QA panel when the sh
 
 ## Custom Adapter
 
-If a team or host project owns its own QA backend, keep that adapter in the host project or in a separate package. Start from [adaptor.sample.ts](adaptor.sample.ts) and map its `WebReviewKitAdapter` methods to your backend API.
+If a team or host project owns its own QA backend, keep that adapter in the host project or in a separate package. Start from [adaptor.sample.ts](adaptor.sample.ts) and map its `WebReviewKitAdapter` methods to your backend API. Do not put Figma image storage into the QA adapter; use a separate `ReviewFigmaImageStore`.
 
 The sample explains the main interfaces:
 
@@ -261,12 +291,17 @@ Private keys, admin credentials, canonical numbering, and permission checks shou
 
 ## Environment
 
+The full copyable template is [.env.sample](../.env.sample).
+
 ```env
-VITE_REVIEW_PROJECT_ID=df-web-review-kit
-VITE_REVIEW_SUPABASE_URL=https://your-project.supabase.co
+VITE_REVIEW_PROJECT_ID=my-project
+VITE_REVIEW_SUPABASE_URL=
 VITE_REVIEW_SUPABASE_ANON_KEY=
 VITE_REVIEW_SUPABASE_TABLE=review_items
 VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE=false
+VITE_REVIEW_SOURCE_ROOT=/absolute/path/to/project
+VITE_REVIEW_SOURCE_EDITOR=cursor
+VITE_REVIEW_SOURCE_URL_TEMPLATE=
 ```
 
 Rules:

package/docs/release-notes-0.7.0.md

@@ -0,0 +1,132 @@
+# 릴리즈 노트: 0.7.0
+
+0.6.0 release 이후 변경 사항 정리.
+
+비교 기준: `0.6.0`
+검토 기준: `main` release candidate
+
+## 주요 변경
+
+- Figma reference image workflow를 review shell 안으로 옮겼다.
+- Figma image local cache와 Vite plugin helper를 추가했다.
+- QA 작성 필드를 `fields` option으로 확장해 title을 선택적으로 받을 수 있게 했다.
+- QA item에 optional assignee 표시/변경 flow를 추가했다.
+- adapter `defaultUserId`로 Settings `user-id` 기본값을 줄 수 있게 했다.
+- 느린 remote adapter, 특히 df-sheet 연동에서 list/create/update/delete pending 상태를 UI로 표시한다.
+- deep link item restore와 QA list focus 위치 보정을 개선했다.
+- right rail Figma icon stroke를 다른 rail icon과 분리해 맞췄다.
+- 릴리즈 직전 QA mutation failure feedback과 Figma image target key 보정을 반영했다.
+- Sitemap modal에 페이지 검색 필터를 추가했다.
+- Sitemap tree row를 ASCII prefix 대신 접기/펼치기 가능한 folder explorer 형태로 바꿨다.
+- Sitemap tree depth를 더 빨리 읽을 수 있게 indent 영역에 subtle guide line을 추가했다.
+- Sitemap tree guide line을 folder caret 중앙축에 맞추고 body row divider 대신 hover/active block highlight를 사용하도록 정리했다.
+- Sitemap body row 높이를 줄이고 상태 컬럼을 Todo/Review/Hold count 중심으로 정리했다.
+
+## 변경
+
+### Figma Image Workflow
+
+review shell에서 Figma reference image를 등록하고 target page 위에 overlay로 올릴 수 있게 했다.
+
+- dev server plugin이 Figma API 호출과 local asset cache를 담당한다.
+- Figma token은 server env의 `FIGMA_TOKEN`을 우선 사용하고, 없으면
+  Settings의 browser-local `figma-token`을 image store 요청 fallback으로 사용한다.
+- metadata는 `.df-review/figma-images.json`, asset은 `.df-review/figma-assets/`에 저장한다.
+- review shell에서는 image manager panel과 layer controls를 제공한다.
+- 일반 route에서는 host가 연결한 overlay control만 사용할 수 있게 boundary를 분리했다.
+
+### QA Fields
+
+adapter option에 `fields`를 추가했다.
+
+- `fields.title`이 true일 때만 QA 작성/수정 화면에 title input을 표시한다.
+- title은 optional field이며 없으면 기존 comment-only 작성 흐름을 유지한다.
+- local fallback에는 assignee sample을 넣지 않고 host adapter가 필요한 field만 선언한다.
+- `defaultUserId`는 Settings localStorage `user-id`가 비어 있을 때 기본 reviewer id로 사용한다.
+
+### Assignee
+
+status와 분리된 optional assignee flow를 추가했다.
+
+- `assigneeTitle`로 select label을 host가 지정할 수 있다.
+- `assigneeOptions`로 담당자 목록을 넣는다.
+- `updateAssignee`가 있는 adapter에서만 list item assignee 변경을 허용한다.
+- edit modal에서는 assignee를 수정하지 않는다.
+
+### Remote Adapter Pending UI
+
+remote adapter가 느릴 때 빈 상태처럼 보이지 않도록 loading/pending feedback을 추가했다.
+
+- QA list 로딩 중 spinner와 loading text를 표시한다.
+- refresh 중에는 refresh button을 disabled + spinner 상태로 둔다.
+- QA 등록/수정/삭제/status/assignee 변경 중에는 item/form 단위 pending 상태를 표시한다.
+- create 실패 시 작성 form에 error message를 표시한다.
+
+### Deep Link Restore
+
+remote list가 늦게 도착하는 경우에도 URL의 `item` query를 복원할 수 있게 보정했다.
+
+- initial item restore를 list loading 이후 한 번 더 시도한다.
+- focus scroll 후 layout/animation 때문에 위치가 틀어지는 케이스를 다시 보정한다.
+- df-sheet처럼 list 응답이 느린 adapter에서 deep link item focus 실패를 줄였다.
+
+### Release Candidate Fixes
+
+- QA status/assignee/submit/delete 실패 시 unhandled rejection으로 남기지 않고 toast로 feedback을 표시한다.
+- QA edit 실패는 toast와 edit modal inline error를 함께 유지한다.
+- Figma image target key가 review shell과 dev overlay에서 query/hash를 포함한 normalized target을 사용하도록 보정했다.
+- Sitemap modal에서 페이지 이름/경로를 검색할 수 있고, 일치하는 하위 page의 상위 folder context를 유지한다.
+- Sitemap folder row는 caret으로 접고 펼칠 수 있으며, 검색 중에는 일치 항목의 상위 folder를 자동으로 펼친다.
+- Sitemap folder depth는 세로 guide line으로 보강해 깊은 경로도 한눈에 구분되게 했다.
+- Sitemap body row divider를 제거하고 hover/active block highlight로 행 구분을 처리한다.
+- Sitemap list는 Total 대신 Todo/Review/Hold state count를 직접 보여준다.
+
+## Host 적용 메모
+
+### Lexus dogfood integration
+
+- Lexus host에서 df-sheet adapter로 title/assignee/status update flow를 확인했다.
+- df-sheet list loading 동안 empty state 대신 loading state가 뜨는지 확인했다.
+- direct URL item restore가 list load 이후 active item을 잡는지 확인했다.
+- Lexus 배포 전에는 `link:../df-web-review-kit`를 published package version으로 바꿔야 한다.
+
+### Vite plugin
+
+Figma image local cache를 쓰는 host는 Vite config에 review-kit plugin helper를 연결해야 한다.
+
+- `reviewFigmaImageStore()`는 dev/local cache endpoint를 제공한다.
+- 개발팀 공용 token은 `FIGMA_TOKEN` server env로 둔다.
+- Vercel 등 검수 환경에서 개인 token이 필요하면 Settings의 Figma token을 사용한다.
+- image format 변환이 필요하면 host가 `sharp` 같은 변환기를 plugin option으로 연결한다.
+
+## 문서
+
+- README quick start에 `fields`, `assigneeTitle`, `assigneeOptions`, `updateAssignee` 예시를 추가했다.
+- custom adapter sample에 optional title/assignee field와 update flow를 추가했다.
+- QA adapter와 Figma image store boundary 문서를 추가했다.
+- Figma image MVP 구조 note를 추가했다.
+
+## 검증
+
+아래 명령을 확인했다.
+
+- `pnpm run typecheck`
+- `pnpm run typecheck:dev`
+- `pnpm run lint:dead-code`
+- `pnpm run build`
+- `pnpm run build:dev`
+- `npm pack --dry-run --json`
+
+수동 확인:
+
+- Lexus dogfood review page에서 df-sheet QA list loading state
+- df-sheet QA create form title field
+- QA list item status/assignee pending state
+- direct URL item restore and focus
+- Figma rail/menu icon stroke
+
+## 메모
+
+- `package.json` version은 `0.7.0`이다.
+- npm publish 전에는 registry login 상태와 latest published version을 확인해야 한다.
+- Lexus target app의 React SVG prop warning(`fill-rule`, `clip-rule`)은 review-kit package warning이 아니다.

package/docs/release-notes-0.7.1.md

@@ -0,0 +1,34 @@
+# 릴리즈 노트: 0.7.1
+
+0.7.0 release 이후 fallback 설정을 보강한 patch release.
+
+비교 기준: `0.7.0`
+검토 기준: `main`
+
+## 변경
+
+- Figma image create 요청에서 server env `FIGMA_TOKEN`을 우선 사용하고, 없으면 Settings의 browser-local `figma-token`을 fallback으로 사용한다.
+- list/update/delete 요청에는 Figma token header를 보내지 않고, Figma API가 필요한 create path에서만 token을 전달한다.
+- adapter `defaultUserId`로 Settings `user-id` 기본값을 줄 수 있게 했다.
+- Settings localStorage `user-id`가 있으면 저장값을 우선 사용하고, 비어 있을 때만 adapter 기본값을 사용한다.
+- dev adapter sample과 installation guide에 `VITE_REVIEW_USER_ID` 예시를 추가했다.
+- 페이지 전환 후 Source Tree가 빈 상태로 남지 않도록 iframe load/DOM mutation 이후 component outline을 다시 읽는다.
+
+## 검증
+
+- `pnpm run typecheck`
+- `pnpm run typecheck:dev`
+- `pnpm run lint:dead-code`
+- `pnpm run build`
+- `npm pack --dry-run --json`
+
+수동 확인:
+
+- Settings modal에서 `VITE_REVIEW_USER_ID=env-reviewer`가 Review user ID 기본값으로 표시되는지 확인했다.
+- About help text에서 Figma token fallback 안내가 표시되는지 확인했다.
+- fake fetch로 Figma token header가 addImage create 요청에만 붙는지 확인했다.
+- review shell에서 Source Tree를 연 뒤 `/components/`로 이동해 tree가 토글 없이 현재 DOM 기준으로 유지되는지 확인했다.
+
+## 메모
+
+- npm `0.7.0`은 `070e2e2` 기준으로 이미 publish되어, 이 patch는 `0.7.1`로 배포한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designfever/web-review-kit",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "Designfever web page review overlay toolkit.",
   "license": "Apache-2.0",
@@ -41,13 +41,15 @@
   "files": [
     "dist",
     "docs",
-    "README.md"
+    "README.md",
+    ".env.sample"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/react-shell.tsx src/vite.ts --format esm,cjs --dts --sourcemap --clean --external react --external react-dom --external react/jsx-runtime",
     "dev": "tsup src/index.ts src/react-shell.tsx src/vite.ts --format esm,cjs --dts --sourcemap --watch --external react --external react-dom --external react/jsx-runtime",
     "dev:review": "vite --config dev/vite.config.ts",
     "build:dev": "vite build --config dev/vite.config.ts",
+    "lint:dead-code": "knip",
     "prepare": "pnpm build",
     "typecheck": "tsc --noEmit",
     "typecheck:dev": "tsc --noEmit -p tsconfig.dev.json"
@@ -64,8 +66,10 @@
   },
   "devDependencies": {
     "@supabase/supabase-js": "^2.108.2",
+    "@types/node": "^26.0.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
+    "knip": "^6.20.0",
     "lucide-react": "^1.20.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",