@designfever/web-review-kit 0.3.0 → 0.4.1

package/dist/{types-Cf2x5ky6.d.cts → types-D_qYtwTs.d.cts}

@@ -6,7 +6,7 @@ type ReviewMode = 'idle' | 'note' | 'element' | 'area';
 type ReviewSource = 'local' | 'supabase' | (string & {});
 type ReviewSubmitStatus = 'idle' | 'submitting' | 'submitted' | 'failed';
 type ReviewViewportScope = Exclude<ReviewItemScope, 'dom'>;
-type DomAnchorStrategy = 'configured-attribute' | 'id' | 'class' | 'dom-path';
+type DomAnchorStrategy = 'configured-attribute' | 'attribute' | 'id' | 'class' | 'dom-path';
 interface ReviewRulerConfig {
     enabled?: boolean;
     unit?: string;
@@ -119,6 +119,8 @@ interface ReviewViewportPreset {
     width: number;
     height: number;
     scope?: Exclude<ReviewItemScope, 'dom'>;
+    designWidth?: number;
+    designHeight?: number;
 }
 interface NumberedReviewItem {
     item: ReviewItem;
@@ -132,6 +134,7 @@ interface WebReviewKitOptions {
     userId?: string;
     adapter?: WebReviewKitAdapter;
     target?: WebReviewKitTarget | (() => WebReviewKitTarget | undefined);
+    adjustmentLabel?: string;
     viewports?: {
         presets?: ReviewViewportPreset[];
     };

package/dist/{types-Cf2x5ky6.d.ts → types-D_qYtwTs.d.ts}

@@ -6,7 +6,7 @@ type ReviewMode = 'idle' | 'note' | 'element' | 'area';
 type ReviewSource = 'local' | 'supabase' | (string & {});
 type ReviewSubmitStatus = 'idle' | 'submitting' | 'submitted' | 'failed';
 type ReviewViewportScope = Exclude<ReviewItemScope, 'dom'>;
-type DomAnchorStrategy = 'configured-attribute' | 'id' | 'class' | 'dom-path';
+type DomAnchorStrategy = 'configured-attribute' | 'attribute' | 'id' | 'class' | 'dom-path';
 interface ReviewRulerConfig {
     enabled?: boolean;
     unit?: string;
@@ -119,6 +119,8 @@ interface ReviewViewportPreset {
     width: number;
     height: number;
     scope?: Exclude<ReviewItemScope, 'dom'>;
+    designWidth?: number;
+    designHeight?: number;
 }
 interface NumberedReviewItem {
     item: ReviewItem;
@@ -132,6 +134,7 @@ interface WebReviewKitOptions {
     userId?: string;
     adapter?: WebReviewKitAdapter;
     target?: WebReviewKitTarget | (() => WebReviewKitTarget | undefined);
+    adjustmentLabel?: string;
     viewports?: {
         presets?: ReviewViewportPreset[];
     };

package/docs/adaptor.sample.ts

@@ -98,6 +98,7 @@ export function createRemoteReviewAdapter(
  * label becomes the URL source, for example /review?source=remote.
  * create controls whether the shell can write to this adapter.
  * canWrite can be true or limited to ['dom', 'note', 'area'].
+ * update enables comment edits in the QA panel.
  * updateStatus drives the status buttons in the QA panel.
  * remove enables delete actions for this source.
  */
@@ -111,6 +112,7 @@ export function createRemoteReviewShellAdapter(
     get: (id) => adapter.get(id),
     list: (query) => adapter.list(query),
     create: (item) => adapter.create(item),
+    update: (id, patch) => adapter.update(id, patch),
     canWrite: true,
     statusOptions: REVIEW_WORKFLOW_STATUS_OPTIONS,
     updateStatus: ({ id, status }) =>

package/docs/architecture.md

@@ -61,8 +61,11 @@ Persisted review data uses target-space viewport values plus optional anchor-rel
 When a user creates a DOM or area item, core tries to capture:
 
 - an explicit configured anchor such as `data-qa-id`
+- common test/section attributes such as `data-testid`, `data-cy`, or `data-section-id`
 - a meaningful `id`
+- semantic attributes such as `aria-label`, `title`, `name`, or `href`
 - a meaningful class
+- a scoped DOM path from the nearest stable ancestor
 - a DOM path fallback
 - a short text fingerprint
 

package/docs/installation.md

@@ -64,6 +64,7 @@ mountReviewShell({
       get: (id) => local.get(id),
       list: (query) => local.list(query),
       create: (item) => local.create(item),
+      update: (id, patch) => local.update(id, patch),
       statusOptions: REVIEW_WORKFLOW_STATUS_OPTIONS,
       updateStatus: ({ id, status }) => local.update(id, { status }),
       syncSubmission: ({ id, patch }) => local.update(id, patch),
@@ -74,6 +75,22 @@ mountReviewShell({
 });
 ```
 
+## Adjustment Label
+
+DOM adjust mode appends adjustment metrics to the saved QA comment. Use `adjustmentLabel` when a host project wants that prompt line to match its own responsive CSS workflow.
+
+```tsx
+mountReviewShell({
+  projectId: REVIEW_PROJECT_ID,
+  pages,
+  adapters,
+  adjustmentLabel: 'Responsive CSS px adjustments',
+  reviewPathPrefix: REVIEW_PATH_PREFIX,
+});
+```
+
+If omitted, the default label is `Responsive CSS px adjustments`. This option only changes the label before the generated `x`, `y`, and `scale` values.
+
 ## Supabase Adapter
 
 Host projects that choose Supabase create the client themselves and pass it into the package adapter.
@@ -124,6 +141,7 @@ const adapters = [
     get: (id) => local.get(id),
     list: (query) => local.list(query),
     create: (item) => local.create(item),
+    update: (id, patch) => local.update(id, patch),
     statusOptions: REVIEW_WORKFLOW_STATUS_OPTIONS,
     updateStatus: ({ id, status }) => local.update(id, { status }),
     syncSubmission: ({ id, patch }) => local.update(id, patch),
@@ -136,6 +154,7 @@ const adapters = [
           get: (id) => remote.get(id),
           list: (query) => remote.list(query),
           create: (item) => remote.create(item),
+          update: (id, patch) => remote.update(id, patch),
           statusOptions: REVIEW_WORKFLOW_STATUS_OPTIONS,
           updateStatus: ({ id, status }) => remote.update(id, { status }),
           remove: (id) => remote.remove(id),
@@ -189,7 +208,7 @@ export default defineConfig({
 });
 ```
 
-Captured DOM nodes will include `data-wrk-source-file`, `data-wrk-source-line`, and `data-wrk-source-column`. In the review shell, `Option` + click inside the target iframe opens that source in VS Code. If the file path is absolute, it opens directly. If the plugin stores relative paths, pass `sourceRoot` when mounting the shell.
+Captured DOM nodes will include `data-wrk-source-file`, `data-wrk-source-line`, and `data-wrk-source-column`. 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. If the file path is absolute, it opens directly. If the plugin stores relative paths, pass `sourceRoot` when mounting the shell.
 
 ```tsx
 mountReviewShell({
@@ -198,9 +217,15 @@ mountReviewShell({
   adapters,
   reviewPathPrefix: REVIEW_PATH_PREFIX,
   sourceRoot: import.meta.env.VITE_REVIEW_SOURCE_ROOT,
+  sourceInspector: {
+    editor: 'vscode', // 'vscode' | 'cursor' | 'webstorm' | 'custom'
+    // urlTemplate: 'my-editor://open?file={encodedPath}&line={line}&column={column}',
+  },
 });
 ```
 
+Set `sourceInspector.enabled` to `false` when source code opening should be unavailable. The `data-font` overlay still belongs to the target project markup and is not required for source opening.
+
 Use this only in dev/review builds. Source paths are written into the browser DOM and can be persisted with QA items.
 
 ## Custom Adapter

package/docs/release-notes-0.3.0.md

@@ -0,0 +1,94 @@
+# 릴리즈 노트: 0.3.0
+
+0.2.0 mainline merge 이후 변경 사항 정리.
+
+비교 기준: `49f2665` (`Merge pull request #7 ... feat: release web review kit 0.2.0`)
+검토 기준 HEAD: `a82b204` (`release: 0.3.0`)
+
+## 주요 변경
+
+- 개발용 Vite source locator export `@designfever/web-review-kit/vite`를 추가했다.
+- DOM 리뷰 대상에 source file hint를 주입하고, 리뷰 shell에서 VS Code로 바로 여는 동작을 추가했다.
+- QA item card에서 comment를 수정할 수 있게 했다.
+- ruler 가독성, 측정 label, light theme 대비를 개선했다.
+- `data-font`를 가진 요소에 source-select font hint overlay를 표시한다.
+- 입력 필드에서 글을 쓰는 중 review hotkey가 실행되지 않도록 수정했다.
+
+## 추가
+
+### 리뷰 대상 Source Locator
+
+Host project가 Vite에서 `reviewSourceLocator()`를 선택적으로 사용할 수 있다. 이 plugin은 React dev JSX runtime을 감싸서 렌더링된 DOM node에 source attribute를 주입한다.
+
+- `data-wrk-source-file`
+- `data-wrk-source-line`
+- `data-wrk-source-column`
+
+Source hint가 있으면 review shell에서 해당 source 위치를 VS Code로 열 수 있다. 절대 경로 source path와 `sourceRoot` 기준 상대 경로를 모두 지원한다.
+
+Public package 변경:
+
+- `./vite` package export 추가
+- `src/vite.ts` 추가
+- `ReviewShellProps`에 optional `sourceRoot` 추가
+- `DomSourceHint`에 `line`, `column` 추가
+
+### Review Shell Source Action
+
+Review shell에서 다음 동작을 지원한다.
+
+- Target iframe 안에서 `Option` + click으로 클릭한 source hint 열기
+- Option key 활성화 중 source hover 표시
+- `data-font` metadata가 있는 요소의 source-select font hint overlay 표시
+- 저장된 source hint가 있는 QA card에 source open action 표시
+- Source hint가 없거나 source root가 필요한 경우 toast feedback 표시
+
+### QA Comment 수정
+
+Active adapter가 update를 지원하면 QA item card에 edit action을 표시한다. Edit modal은 빈 comment를 막고, active adapter로 저장한 뒤 review data를 새로고침하고 toast feedback을 보여준다.
+
+Adapter normalization에 `canUpdate`를 추가해서 read-only source에서는 edit action을 숨길 수 있게 했다.
+
+## 변경
+
+### Ruler UI
+
+- 측정 label을 Figma 전용 문구가 아니라 중립적인 `width x height unit` 형식으로 바꿨다.
+- Dark/light theme 모두에서 ruler label, coordinate chip, guide line, popover 가독성을 개선했다.
+- 후속 fix에서 light theme ruler 대비를 한 번 더 개선했다.
+
+### Review Shell Workflow
+
+- QA item list 정렬 기준을 `updatedAt`에서 `createdAt`으로 바꿨다. 이제 기존 item을 수정해도 목록 최상단으로 튀지 않는다.
+- Supabase list ordering도 remote source에서 같은 동작을 하도록 `created_at` 기준으로 바꿨다.
+- Quick add toolbar는 DOM element capture와 area capture 중심으로 정리했다.
+- Edit comment modal은 settings modal의 visual system을 재사용한다.
+
+### Prompt Context
+
+DOM source hint가 있으면 review item prompt에 source line context를 포함한다.
+
+## 수정
+
+- Focus가 `input`, `textarea`, `select`, `contenteditable` 안에 있을 때 review hotkey를 무시한다.
+- DOM source 추출이 새 `data-wrk-source-*` attribute와 기존 `data-file` / `data-component` 계열 attribute를 모두 읽도록 했다.
+
+## 문서
+
+- README에 public import `@designfever/web-review-kit/vite`를 문서화했다.
+- Installation docs에 source locator 설정, `sourceRoot`, source path가 DOM에 기록되는 dev/review build 주의사항을 추가했다.
+
+## 검증
+
+검토한 main branch 기준으로 아래 명령을 확인했다.
+
+- `pnpm typecheck`
+- `pnpm typecheck:dev`
+- `pnpm build`
+- `pnpm build:dev`
+
+## 메모
+
+- `package.json` version은 `0.3.0`이다.
+- `0.3.0` release commit은 `a82b204`다.
+- 이 노트를 작성한 시점에는 local/remote 모두 `0.3.0` git tag가 없었다.

package/docs/release-notes-0.4.0.md

@@ -0,0 +1,144 @@
+# 릴리즈 노트: 0.4.0
+
+0.3.0 release 이후 변경 사항 정리.
+
+비교 기준: `a82b204` (`release: 0.3.0`)
+검토 기준: `0.4.0` release commit
+
+## 주요 변경
+
+- Source inspector를 단일 source open에서 후보 선택형 inspector로 확장했다.
+- DOM anchor 후보를 더 많이 수집하고, 클릭한 실제 DOM element를 우선 anchor로 사용하도록 개선했다.
+- Sitemap을 QA 현황판처럼 쓸 수 있게 remaining, review, hold, online 기준 집계와 정렬을 추가했다.
+- 전체 QA 보기와 review link restore 흐름을 정리했다.
+- DOM/area draft composer를 draggable workflow로 바꾸고, DOM 위치 보정 모드를 추가했다.
+- QA panel에 status filter를 추가하고, status select chevron과 spacing을 정리했다.
+- Presence 표시를 QA list에서 분리해 상단 toolbar 아래 별도 row로 옮겼다.
+
+## 추가
+
+### Source Inspector
+
+Review target에서 `Option`을 누른 상태로 hover하면 DOM ancestry에서 source 후보를 수집해 outline으로 표시한다. 클릭하면 후보 list가 고정되고, 사용자가 열 source를 직접 고를 수 있다.
+
+Source open 옵션을 확장했다.
+
+- `sourceInspector.editor`: `vscode`, `cursor`, `webstorm`, `custom`
+- `sourceInspector.urlTemplate`: custom editor URL template
+- 후보별 line/column confidence에 따라 위치 포함 여부 결정
+- `sourceRoot` 기준 relative path resolve 유지
+
+문서도 `Option + click` 단일 동작 설명에서 후보 선택형 flow로 갱신했다.
+
+### Figma Frame Link
+
+Target iframe이 `window.__figma`에 frame config를 제공하면 review frame 옆에 Figma frame link를 표시한다.
+
+- `desktopNodeId`
+- `mobileNodeId`
+- viewport preset 종류에 맞는 frame URL 선택
+
+Target page 새 창 열기 action도 같은 link stack에 배치했다.
+
+### Sitemap QA Overview
+
+Sitemap modal에 페이지별 QA 현황 집계를 추가했다.
+
+- remaining total
+- review count
+- hold count
+- online users
+- All QA summary row
+- page, total, review, hold, online 기준 정렬
+
+Folder/group row는 하위 page의 QA count와 online user를 합산해서 보여준다.
+
+### 전체 QA 보기
+
+Sitemap에서 All QA row를 선택하면 현재 page에 묶이지 않은 전체 QA list를 볼 수 있다. QA panel title도 All pages 상태를 구분해서 표시한다.
+
+### QA Item Link Copy
+
+QA item card에서 개별 review item link를 복사할 수 있게 했다. 복사한 link를 target input에 붙여넣으면 source, viewport, item id를 해석해 해당 item으로 복원한다.
+
+## 변경
+
+### DOM Anchor
+
+Anchor 후보 수집 우선순위를 개선했다.
+
+- 클릭한 실제 target element 우선
+- `data-testid`, `data-cy`, `data-section-id`, `data-component` 계열 attribute 지원
+- `aria-label`, `title`, `name`, `href` 같은 semantic attribute 지원
+- 안정적인 ancestor 기준 scoped DOM path 추가
+- full DOM path는 fallback confidence로 낮춤
+
+이 변경으로 nested component나 반복 section 안에서 DOM item 복원 안정성이 좋아졌다.
+
+### Draft Composer
+
+DOM/area draft composer workflow를 조정했다.
+
+- composer drag handle 추가
+- composer를 shell 밖 클릭으로 cancel 가능
+- 선택 영역 옆에 composer 배치
+- composer drag 중 shell z-index와 pointer handling 정리
+- composer metric, spacing, action layout 통일
+
+### DOM 위치 보정 모드
+
+DOM review composer에 위치 보정 mode를 추가했다.
+
+- DOM nudge adjustment
+- scale key 조정
+- adjustment HUD 표시
+- toggle icon을 SVG 기반으로 정리
+
+### QA Panel
+
+QA list header에 status filter를 추가했다.
+
+- All status / Todo / Doing / Review / Hold / Done 필터
+- status별 count 표시
+- remaining count와 active item count를 함께 표시
+- QA source select와 status select chevron spacing 통일
+
+### Presence
+
+Page presence 표시를 QA list header에서 제거했다. 대신 상단 toolbar 아래 별도 row에 chip으로 표시한다.
+
+- 기본은 첫 사용자 + `+N` 접힘 표시
+- `+N` 클릭 시 전체 사용자 펼침
+- iframe/device 내부에 겹치지 않도록 review shell row에 배치
+
+## 수정
+
+- 초기 review link restore timing을 안정화했다.
+- 붙여넣은 review link에서 target, source, viewport, item id를 해석하도록 수정했다.
+- QA card action layout과 restore timing을 정리했다.
+- Status select chevron이 status별 background style에 덮이는 문제를 수정했다.
+- MO preset design width ratio를 390 기준으로 조정했다.
+- Sitemap count column 구조와 typography를 정리했다.
+
+## 문서
+
+- README에 `sourceInspector` mount option 예시를 추가했다.
+- Installation docs에 source inspector 후보 선택 flow와 editor option을 추가했다.
+- Architecture docs에 anchor 후보 수집 전략을 보강했다.
+
+## 검증
+
+검토한 main branch 기준으로 아래 명령을 확인했다.
+
+- `pnpm typecheck`
+- `pnpm typecheck:dev`
+- `pnpm build`
+- `pnpm build:dev`
+- `git diff --check`
+- Puppeteer smoke checks for QA status select, presence row, and expand/collapse behavior
+
+## 메모
+
+- 이 노트는 0.4.0 publishing 전 검토용이다.
+- `package.json` version은 `0.4.0`이다.
+- npm publish 전에는 registry login 상태를 확인해야 한다.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@designfever/web-review-kit",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Designfever web page review overlay toolkit.",
-  "license": "UNLICENSED",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Designfever/df-web-review-kit.git"