@designfever/web-review-kit 0.8.2 → 0.8.4

package/docs/README.md

@@ -22,12 +22,14 @@ Public docs are intentionally small. Keep implementation history, handoff notes,
 - `testing.md`: Vitest adapter contract and core pure-function unit coverage, plus local verification commands.
 - `adaptor.sample.ts`: copyable starting point for host-owned remote adapters.
 - `db-setup.md`: optional Supabase review item table/RPC/RLS/presence setup.
-- `architecture.md`: core/runtime, React shell, coordinate, anchor, and feature boundary notes.
-- `figma-overlay.md`: host requirements for the Figma overlay toggle.
+- `architecture.md`: core/runtime, React shell, coordinate, anchor, sitemap, and feature ownership boundaries.
+- `figma-overlay.md`: host helper requirements plus package image overlay state and interaction rules.
 - `grid-overlay.md`: host requirements for the grid/helper overlay toggle.
 
 ## Release History
 
+- [0.8.4](release-notes-0.8.4.md): reliable viewport capture for zero-size gradient elements.
+- [0.8.3](release-notes-0.8.3.md): code-review bug fixes (hidden draft composer, select hotkeys, overlay state writes, URL hash), sitemap state persistence/filtering, tests, and feature-module cleanup.
 - [0.8.2](release-notes-0.8.2.md): Figma image layer edit/delete tooltip removal.
 - [0.8.1](release-notes-0.8.1.md): QA prompt prefix, QA filtering, counters, tooltip, long-content, and outside marker fixes.
 - [0.8.0](release-notes-0.8.0.md): next minor release notes for QA attachments, adapter contract, capture, source inspector, and dev fixture changes.

package/docs/architecture.md

@@ -211,29 +211,55 @@ hooks and returns provider values; it should not become a render component.
 - `hooks/use.review.section.outline.ts`: Source Tree outline extraction, filter/collapse state, refresh scheduling, and entry actions.
 - `hooks/use.review.command.key.ts`: hide-all-overlays-while-command-held tracking across host and iframe.
 
+### Sitemap Feature Boundary
+
+Sitemap state and row derivation are intentionally separate:
+
+- `sitemap/modal.tsx`: owns search, sort, status filters, and collapsed-folder UI state.
+- `sitemap/tree.ts`: converts the page list into visible tree or flat result rows.
+- `sitemap/count.ts`: owns the QA count shape, viewport column keys, and count aggregation.
+- `sitemap/row.tsx`: renders the shared page, folder, and All QA row content.
+
+The modal mounts on first open and is hidden instead of unmounted on close. This
+preserves search, sort, collapsed folders, active status filters, and scroll
+position while the review shell remains mounted.
+
+Page rows show only that page's direct QA count. Folder rows aggregate their
+descendant pages. Enabled status filters use OR with each other and AND with the
+search query; while status filtering is active, only matching pages are shown
+as flat full paths so a parent folder aggregate cannot look like a match.
+
 ### Comment Policy
 
 Prefer comments only at module boundaries or non-obvious runtime contracts. Avoid
 file-wide restatements of import names, prop-by-prop explanations, or comments
 that duplicate what a function name already says.
 
-## Figma Overlay Direction
+## Figma Image Feature Boundary
 
 Figma overlay work should stay outside core unless it needs target runtime primitives.
 
-Preferred direction:
+Current ownership:
 
 ```txt
 src/react-shell/figma/
-  controls.tsx
-  sync.ts
-  overlay.state.ts
+  image.controller.ts          # image store list and mutations
+  image.overlay.controller.ts  # React effects and overlay commands
+  image.overlay.state.ts       # route-keyed localStorage and migration
+  images.panel*.tsx            # shell panel UI
+
+src/react-shell/target/
+  figma.image.overlay.ts       # iframe DOM rendering and drag behavior
 
 src/figma/
-  matching.ts
-  types.ts
+  image.types.ts               # public image/store contracts
 ```
 
+`image.overlay.controller.ts` re-exports the overlay types used by existing
+shell modules, but persistence and normalization live in
+`image.overlay.state.ts`. Keep storage migrations and default-value cleanup out
+of the React controller.
+
 Shared coordinate math can reuse `core/geometry.ts` or move to a future shared module if both core and Figma need it heavily.
 
 Avoid turning `core` into a feature bucket. Core should stay focused on target review runtime behavior.

package/docs/figma-overlay.md

@@ -88,6 +88,30 @@ overlays into the iframe instead. Those overlays use:
 - `#df-review-figma-image-target-root`
 - `.df-review-figma-image-target-overlay`
 
+## Image Overlay State
+
+Package-managed image overlay controls are stored separately for each project,
+page, viewport, and optional slot. The localStorage key starts with:
+
+```txt
+df-review-figma-image-overlay-state:
+```
+
+Each target stores the selected image, per-image visibility, opacity, lock,
+normal/invert mode, vertical offset, and the images that were visible before a
+hide-all action. Default state removes the storage entry instead of leaving an
+empty route key behind. Storage events keep another tab on the same origin in
+sync.
+
+`src/react-shell/figma/image.overlay.state.ts` owns the storage shape,
+normalization, and the legacy flat-state migration. The React effects and user
+commands stay in `image.overlay.controller.ts`; iframe DOM creation and drag
+behavior stay in `src/react-shell/target/figma.image.overlay.ts`.
+
+When the store refreshes its image list, removed image IDs are pruned. If the
+effective state did not change, the controller preserves the existing state
+identity so it does not rewrite the same localStorage value.
+
 The image overlay hit layer is interactive only when the image can be dragged.
 During element review mode or `Option` source selection, the shell temporarily
 locks both host helper layers and package image overlays with

package/docs/release-notes-0.8.3.md

@@ -0,0 +1,48 @@
+# 릴리즈 노트: 0.8.3
+
+전체 코드 리뷰에서 나온 버그 수정과 중복 코드 정리를 담은 patch release. 동작 오류 4건을 고치고, sitemap 사용성을 개선하고, 큰 feature 파일을 역할별로 분리하고 문서를 현행화했다.
+
+비교 기준: `0.8.2`
+
+## 버그 수정
+
+- Source Tree panel이 열린 상태에서 DOM/Area draft를 시작하면 docked composer가 panel 뒤에 가려져 사용할 수 없던 문제를 수정했다. composer가 있을 때 draft host를 panel보다 위로 올린다.
+- `<select>`에 포커스가 있을 때 shell 단축키(`e`, `a`, `r`, `g`, `f`)가 동작하던 문제를 수정했다. select에서 글자 입력은 option 이동이므로 다른 입력 요소와 동일하게 단축키를 차단한다.
+- Figma image overlay 상태 동기화의 no-change guard가 항상 새 객체 비교로 실패해, 이미지 목록이 갱신될 때마다 동일한 상태를 localStorage에 다시 쓰던 문제를 수정했다.
+- shell이 `history.replaceState()`로 URL을 갱신할 때 `#hash`가 유실되던 문제를 수정했다.
+
+## 개선
+
+- Sitemap modal을 닫아도 unmount 하지 않고 숨겨서, 다시 열면 검색어·정렬·폴더 접힘·목록 스크롤이 마지막 상태 그대로 복원된다. 첫 오픈 전에는 기존처럼 mount 하지 않는다.
+- Sitemap header의 요약 카운트(`N todo · N review · N hold`)를 클릭하면 해당 status QA가 있는 페이지만 필터링한다. 켜진 status끼리는 OR, 검색어와는 AND로 동작하고, 활성 필터는 색상과 밑줄로 표시한다. 필터 중에는 tree 대신 매칭 페이지를 전체 경로의 평평한 목록으로 보여준다.
+
+## 내부 정리
+
+- `isEditableEventTarget` 4벌 복사본을 `core/hotkey.ts` 하나로 통합했다. 복사본 간 드리프트(SELECT 누락)가 위 단축키 버그의 원인이었다.
+- `captureDomDraft`/`captureAreaDraft`의 동일한 capture 로직을 draft 접근자를 받는 함수 하나로 합쳤다.
+- shell settings의 localStorage 접근을 `readStorage`/`writeStorage` 헬퍼로 통일해 SSR guard와 try/catch 반복을 제거했다.
+- unknown error 메시지 추출을 `core/error.ts`의 `getErrorMessage`로 공유한다.
+- Figma image overlay controller의 selected image setter 6개를 공통 updater로 축소했다.
+- Figma image overlay의 저장 상태 로직과 sitemap의 QA 집계·row UI를 각각 분리해 controller와 modal의 역할을 줄였다.
+- 상태 identity, storage migration, sitemap 집계, row 이벤트 전파처럼 이름만으로 의도가 드러나지 않는 runtime contract에 주석을 추가했다.
+- 기존 `image.overlay.controller.ts`와 `sitemap/tree.ts` import 경로는 re-export로 유지해 공개 API와 내부 소비 코드의 호환성을 보존했다.
+- 동일한 구현이 중복된 source candidate key builder와 도달 불가능한 supabase `externalIssueUrl` fallback을 제거했다.
+- git에 추적되던 `dist` 빌드 산출물을 제거하고 `.gitignore`에 추가했다. 배포 패키지에는 영향이 없다.
+
+## 문서
+
+- Architecture 문서에 sitemap의 modal/tree/count/row 책임과 direct page count·folder aggregate 규칙을 추가했다.
+- Figma overlay 문서에 route·viewport별 localStorage 상태, legacy migration, storage event 동기화, 불필요한 재저장 방지 구조를 추가했다.
+- Testing 문서에 새 hotkey, URL hash, Figma overlay storage, sitemap filter/state 회귀 테스트와 전체 release 검증 명령을 반영했다.
+- root README와 docs index가 0.8.3 릴리즈 노트 및 현재 architecture/Figma 문서를 가리키도록 갱신했다.
+
+## 검증
+
+- `pnpm typecheck`
+- `pnpm typecheck:dev`
+- `pnpm test`
+- `pnpm lint:dead-code`
+- `pnpm build`
+- `pnpm build:dev`
+- `npm pack --dry-run --json`
+- dev review shell 브라우저 테스트: Source Tree 위 draft composer 표시, select 단축키 차단, URL hash 유지, sitemap status 필터와 검색 조합, 닫기/재오픈 상태 복원, Figma image panel 렌더링을 확인했다. Vite error overlay와 console error는 없었다.

package/docs/release-notes-0.8.4.md

@@ -0,0 +1,23 @@
+# 릴리즈 노트: 0.8.4
+
+`html2canvas`가 크기 0인 gradient 요소를 렌더링할 때 color stop을
+`NaN`으로 계산해 선택 영역 캡처가 실패하던 문제를 수정한 patch release.
+
+비교 기준: `0.8.3`
+
+## 버그 수정
+
+- 캡처용 document clone에서 너비나 높이가 0인 요소의 gradient 배경을
+  제거한다. 화면에 보이지 않는 요소만 대상으로 하므로 캡처 결과의
+  가시 콘텐츠에는 영향을 주지 않는다.
+- `CanvasGradient.addColorStop()`에 non-finite 값이 전달되면서 발생하던
+  `Selected region capture failed` 오류를 방지한다.
+
+## 검증
+
+- `pnpm test`
+- `pnpm typecheck`
+- `pnpm build`
+- `pnpm lint:dead-code`
+- Kia Worldwide `1920x1080` review shell에서 Element 선택 후 WebP attachment
+  생성 확인

package/docs/testing.md

@@ -14,9 +14,11 @@ Use the full package check before release or when touching public types:
 ```bash
 pnpm typecheck
 pnpm test
+pnpm lint:dead-code
 pnpm build
 pnpm typecheck:dev
 pnpm build:dev
+npm pack --dry-run --json
 ```
 
 ## Current Coverage
@@ -33,15 +35,19 @@ pnpm build:dev
 
 The Supabase coverage uses an in-memory PostgREST/RPC mock. It does not contact a real Supabase project.
 
-### Pure function unit suites
+### Regression and unit suites
 
-Colocated `*.test.ts` files cover the core pure-function modules that refactors depend on:
+Colocated `*.test.ts` and `*.test.tsx` files cover the runtime contracts that
+refactors depend on:
 
 - `src/core/geometry.test.ts`: coordinate conversion (host/target spaces), clamping, selection shapes, popover placement.
-- `src/core/hotkey.test.ts`: hotkey matching with modifiers, Korean IME key aliases, physical key-code fallback.
+- `src/core/hotkey.test.ts`: hotkey matching with modifiers, Korean IME key aliases, physical key-code fallback, and editable-target blocking including `<select>`.
 - `src/core/location.test.ts`: page URL building and review-internal query param stripping.
 - `src/core/review/scope.test.ts`: viewport preset matching, scope inference, and item numbering/draft labels.
-- `src/route.test.ts`: route path normalization (`index.html`, query/hash) and item route keys.
+- `src/react-shell/route.test.ts`: shell URL updates preserve the current hash while changing target or selected QA item.
+- `src/react-shell/figma/image.overlay.controller.test.tsx`: unchanged image-list refreshes do not rewrite overlay state in localStorage.
+- `src/react-shell/sitemap/tree.test.ts`: status filters use OR with each other, AND with search, and return flat full-path page rows.
+- `src/react-shell/sitemap/modal.test.tsx`: closing and reopening the sitemap preserves search and status-filter state.
 - `src/figma/parse.test.ts`: Figma URL/node-ref parsing, including non-figma host rejection.
 - `src/vite/figma-asset.test.ts`: asset storage key validation, including path traversal rejection, and mime/format helpers.
 - `src/vite/figma-image-store.server.test.ts`: dev middleware request guards — cross-origin (CSRF) rejection, JSON content-type enforcement, body size limit.
@@ -59,6 +65,8 @@ Add or extend Vitest coverage when changing:
 - Supabase row mapping, RPC payloads, or review URL generation
 - attachment upload contracts
 - status, assignee, or external link fields
+- route-keyed Figma image overlay storage or migration behavior
+- sitemap count aggregation, filtering, sorting, or close/reopen state
 - coordinate/scope/route/parsing helpers listed above (extend the colocated suite)
 
 ## Known Behavior Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designfever/web-review-kit",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "type": "module",
   "description": "Designfever web page review overlay toolkit.",
   "license": "Apache-2.0",