@designfever/web-review-kit 0.5.0 → 0.7.0

package/docs/code-review-0.6.0.md

@@ -0,0 +1,232 @@
+# 코드 리뷰 및 정리: 0.6.0 → 0.7.0 준비
+
+리뷰 대상: `df-web-review-kit@0.6.0` (`origin/main` 기준)
+작업 브랜치: `chore/0.7.0-code-review-cleanup`
+범위: `src/**` 구조 정리, 죽은 코드/죽은 export 제거, dead-code 검사 설정 추가
+
+---
+
+## 요약
+
+0.6.0에서 기능이 늘며 가장 크게 비대한 파일은 `src/react-shell/style.ts`였다. 단일 함수 안에 3,500줄 이상 CSS 문자열이 들어 있었고, Source Tree / QA list / composer / modal / ruler 스타일이 한 파일에 섞여 있었다.
+
+이번 0.7.0 준비 브랜치에서는 위험도가 낮은 정리부터 적용했다.
+
+1. `react-shell/style.ts`를 7개 스타일 chunk로 분리
+2. 실제 미사용 함수/타입/상수와 내부 전용 helper의 잘못된 export 제거
+3. `knip` 설정과 `pnpm lint:dead-code` 스크립트 추가
+4. `typecheck`, `typecheck:dev`, `lint:dead-code`, `build` 통과 확인
+
+---
+
+## 1. 한 파일에 몰린 곳
+
+### 정리 전 상위 파일
+
+| 파일 | LOC | 문제 |
+|---|---:|---|
+| `src/react-shell/style.ts` | 3,579 | 단일 함수가 전체 review shell CSS 문자열을 보유 |
+| `src/react-shell/review/shell.tsx` | 2,306 | `ReviewShell` 단일 컴포넌트에 상태/핸들러/렌더가 많이 남음 |
+| `src/core/web.review.kit.view.ts` | 1,937 | overlay, scroll, draft, anchor 책임이 한 클래스에 집중 |
+| `src/core/overlay.style.ts` | 1,025 | core overlay CSS 덩어리 |
+| `src/core/dom.anchor.ts` | 818 | anchor 후보/매칭 로직 집중 |
+| `src/react-shell/source.open.ts` | 785 | Source Tree 기능 확장으로 커짐 |
+
+### 이번 브랜치에서 처리한 부분
+
+`src/react-shell/style.ts`를 작은 조립 파일로 줄이고, CSS는 역할별 파일로 이동했다.
+
+| 파일 | 역할 | 현재 LOC |
+|---|---|---:|
+| `src/react-shell/style.ts` | style tag 주입 + chunk 조립 | 26 |
+| `src/react-shell/style/base.ts` | token, reset, topbar 공통 | 401 |
+| `src/react-shell/style/sitemap.ts` | sitemap modal/table | 317 |
+| `src/react-shell/style/modals.ts` | settings/edit/prompt modal | 606 |
+| `src/react-shell/style/toolbar.ts` | tools, side rail, presence | 530 |
+| `src/react-shell/style/qa-panel.ts` | QA panel/list/card/actions | 722 |
+| `src/react-shell/style/stage.ts` | stage/frame/target/device | 138 |
+| `src/react-shell/style/source-inspector.ts` | source outline/popover/candidate | 153 |
+| `src/react-shell/style/section-outline.ts` | section outline panel | 539 |
+| `src/react-shell/style/ruler.ts` | ruler + responsive media query | 262 |
+
+동작 변화 없이 문자열을 나눠서 `ensureReviewShellStyle()`에서 concat만 하도록 정리했다.
+
+> 0.7.0 후속(아래 6장)에서 `stage.ts`를 `stage` / `source-inspector` / `section-outline` 3개로 더 쪼갰다.
+
+---
+
+## 2. 죽은 코드 / 죽은 export 정리
+
+`knip` 결과를 기준으로 public entry false positive와 실제 내부 전용 helper를 구분했다.
+
+### 삭제한 실제 미사용 코드
+
+| 파일 | 삭제 내용 |
+|---|---|
+| `src/react-shell/prompt/prompt.ts` | 미사용 `formatItemMeta`, `formatDate` 삭제 |
+| `src/react-shell/source.open.ts` | 미사용 `SOURCE_SELECTOR`, `getSourceHintElement`, `getElementSourceHint` 삭제 |
+| `src/core/geometry.ts` | 미사용 `getAreaPopoverPosition` 삭제 |
+| `src/core/location.ts` | 미사용 alias `getNormalizedPath` 삭제 |
+| `src/core/review/format.ts` | 미사용 `formatAreaDraftMeta` 삭제 |
+
+### export만 제거하고 내부 helper로 남긴 것
+
+아래 항목은 같은 파일 내부에서는 쓰이지만 외부 export가 필요 없던 helper다. 삭제하지 않고 `export`만 제거했다.
+
+- `src/react-shell/anchor.restore.ts`
+  - `getReviewItemExpectedDocumentRect`
+  - `getReviewAnchorMatchScore`
+  - `getElementDocumentRect`
+  - `getReviewTextFingerprintScore`
+  - `getReviewFingerprintTokens`
+  - `isScrollableReviewAnchorElement`
+- `src/react-shell/prompt/prompt.ts`
+  - `formatPromptViewport`
+  - `formatPromptPoint`
+  - `formatPromptSelection`
+  - `decodePromptHtmlEntities`
+  - `getPromptAnchorCandidates`
+  - `formatPromptSourceHint`
+- `src/core/geometry.ts`
+  - `rectanglesIntersect`
+  - `getPopoverBounds`
+- `src/react-shell/route.ts`
+  - `normalizeReviewPathPrefix`
+  - `getHashRoutePath`
+- `src/react-shell/settings.ts`
+  - `normalizeStoredReviewSidePanel`
+  - `normalizeStoredReviewQaStatusFilter`
+- `src/react-shell/viewport.ts`
+  - `getFallbackPreset`
+  - `getViewportPresetDistance`
+- `src/react-shell/target/target.ts`
+  - `HIDE_SCROLLBAR_STYLE_ID`
+  - `FIGMA_POINTER_LOCK_STYLE_ID`
+- `src/react-shell/review/shell.actions.ts`
+  - `listReviewItems`
+  - `listSitemapReviewItems`
+- 내부 타입 export 축소
+  - `src/core/review/draft.ts`
+  - `src/react-shell/sitemap/tree.ts`
+  - `src/react-shell/source.open.ts`
+  - `src/react-shell/types.ts`
+
+---
+
+## 3. Dead-code 검사 설정
+
+추가 파일:
+
+- `knip.json`
+
+추가 스크립트:
+
+```json
+"lint:dead-code": "knip"
+```
+
+설정 의도:
+
+- public entry는 `src/index.ts`, `src/react-shell.tsx`, `src/vite.ts`로 명시
+- 검사 대상은 `src/**/*.{ts,tsx}`로 제한
+- `dist/**`와 `docs/adaptor.sample.ts` 같은 빌드 산출물/샘플은 검사 대상 밖에 둬서 false positive를 막음
+
+현재 `pnpm lint:dead-code`는 이 설정으로 0 issue 통과한다.
+
+---
+
+## 4. 아직 남은 큰 덩어리
+
+이번 브랜치에서는 위험도가 낮은 style split + dead-code cleanup까지만 적용했다. 아래는 별도 브랜치에서 작은 단위로 나누는 게 안전하다.
+
+### `src/react-shell/review/shell.tsx` (2,306 LOC)
+
+남은 책임:
+
+- source panel resize / delayed close
+- source candidate popover state
+- section outline filtering / expand state
+- prompt modal copy/open 흐름
+- QA list selection + card action bridge
+
+추천 다음 작업:
+
+1. `use.source.panel.ts`
+2. `use.section.outline.ts`
+3. `use.prompt.modal.ts`
+4. `use.qa.selection.ts`
+
+`ReviewShell`은 layout assembly + child component wiring 정도로 줄이는 게 목표다.
+
+### `src/core/web.review.kit.view.ts` (1,937 LOC)
+
+남은 책임:
+
+- overlay 렌더링
+- scroll sync
+- draft 작성/취소/저장
+- anchor restore
+- marker lifecycle
+
+추천 다음 작업:
+
+1. draft controller 분리
+2. marker renderer 분리
+3. scroll/restore orchestration 분리
+4. view class는 조립/라이프사이클만 담당
+
+---
+
+## 5. 검증
+
+실행한 명령:
+
+```bash
+pnpm lint:dead-code
+pnpm typecheck
+pnpm typecheck:dev
+pnpm build
+```
+
+결과:
+
+- `pnpm lint:dead-code` 통과
+- `pnpm typecheck` 통과
+- `pnpm typecheck:dev` 통과
+- `pnpm build` 통과
+
+`pnpm build` 결과로 `dist/**` 산출물이 갱신됐고, 기존 chunk hash는 `chunk-IN36JHEU` → `chunk-BDP7FS4Q`로 변경됐다.
+
+---
+
+## 6. 0.7.0 후속 정리 (continued)
+
+같은 브랜치에서 Figma image 기능이 추가된 뒤, 위험도 낮은 정리를 한 단계 더 진행했다. 모두 동작/공개 API 변화 없는 내부 리팩터이며 단계별 커밋으로 나눴다.
+
+### CSS
+
+- `shell.tsx`에 인라인으로 박혀 있던 source-select 단축키 CSS(65줄)를 `react-shell/review/source.shortcut.style.ts`로 추출 (`createSourceShortcutStyle`).
+- 비대했던 `style/stage.ts`(827줄)를 도메인 기준으로 3분할: `stage.ts`(138) / `source-inspector.ts`(153) / `section-outline.ts`(539). 실제 내용이 stage가 아니라 section/source 위주였던 점을 반영.
+
+### 네이밍 (내부 한정, export 무변경)
+
+- `dom.anchor.ts`: `primary` → `primaryCandidate`, `safeClosest` → `tryClosest`.
+- `normalizeStoredReviewSidePanel` 등 정상 normalizer는 형제 함수와의 일관성 때문에 유지.
+
+### 주석
+
+- `dom.anchor.ts`의 경로 생성(`getDomPath`/`getDomPathBetween`)·스코어링(`getTextFingerprintScore`/`getSelectionMatchScore`) 알고리즘, `view.ts`의 큰 메서드(`createNotePopover`/`createAdjustmentControls`), 매직 넘버(z-index `2147483646`, 길이 제한 160/120, `roundRatio` 정밀도) 설명 추가.
+
+### 파일 분할 (안전 범위)
+
+| 원본 | 추출 | 결과 |
+|---|---|---|
+| `vite.ts` (1492) | `vite/figma-asset.ts` (포맷/경로 헬퍼 10개) | 1424 |
+| `core/web.review.kit.view.ts` (1937) | `core/draft.metrics.ts` (draft adjustment 순수 geometry) | 1901 |
+| `react-shell/figma/images.panel.tsx` (737) | `figma/image-panel.utils.ts` (순수 유틸 8개) | 669 |
+
+§4의 `web.review.kit.view.ts` 항목 중 "draft controller 분리"의 첫 조각으로 순수 geometry부터 뽑았다. `shell.tsx`의 대규모 hook 분리와 `images.panel`의 `ImageCard` 컴포넌트 분리(drag 상태·ref 결합으로 회귀 위험 큼)는 여전히 후속 작업으로 남겨 둔다.
+
+### 검증
+
+각 단계마다 `pnpm typecheck` 통과, 추출 단계는 `pnpm lint:dead-code`(knip) 0 issue, 최종 `pnpm build` 통과 확인.

package/docs/db-setup.md

@@ -4,9 +4,11 @@ Supabase is an optional backend adapter. A host project may use it for canonical
 
 ## Environment
 
+Start from [.env.sample](../.env.sample), then fill Supabase values only in the host project that uses the Supabase adapter.
+
 ```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

package/docs/figma-image-mvp-0.7.0.md

@@ -0,0 +1,327 @@
+# Figma Image MVP 0.7.0 Structure Note
+
+This is the investigation note for Todo 802, `Figma 이미지 MVP 구조 조사`.
+It records the minimum 0.7.0 scope before implementation.
+
+## Goal
+
+0.7.0 should add a dev/local Figma image management MVP without breaking the
+current host-helper flow.
+
+- If a Figma image store is configured, the review shell uses the new image
+  management flow.
+- If no Figma image store is configured, the shell keeps the current Figma
+  helper fallback: dispatch the host keyboard shortcut and detect the host
+  overlay.
+- `FIGMA_TOKEN` is required only by the Figma image server/dev endpoint when it
+  renders or adds an image. It must not become a package-wide or browser env
+  requirement.
+- Rendered images should be downloaded into a local/dev asset cache. Prefer webp
+  when an image transformer is configured, but keep `png`/`jpg` fallback without
+  adding a package dependency. Always keep the original `figmaUrl`, `fileKey`,
+  and `nodeId` so the image can be regenerated later.
+- Removing keyboard shortcut helpers from host projects belongs after the MVP
+  has stabilized.
+
+## Current State
+
+### Existing Review Adapters
+
+`WebReviewKitAdapter` is a QA item persistence contract:
+
+- `get`
+- `list`
+- `create`
+- `update`
+- `remove`
+
+`ReviewShellAdapter` wraps that contract for shell sources, status handling,
+submission sync, and write-mode checks. It is intentionally centered on
+`ReviewItem`.
+
+Do not overload this adapter for Figma image bindings in 0.7.0. Figma images
+need their own small store contract so QA item source switching, status updates,
+and submission sync do not become coupled to image management.
+
+### Current Figma Integration
+
+The current Figma integration is only a host-helper toggle:
+
+- `docs/figma-overlay.md` states that the package does not fetch Figma data or
+  own a server-side token.
+- `src/react-shell/figma.ts` reads `window.__figma` and builds a Figma frame
+  link from `fileKey->nodeId`.
+- `src/react-shell/hooks/use.review.target.overlay.ts` dispatches `KeyF` into
+  the iframe target when the Figma overlay is toggled.
+- `src/react-shell/settings.ts` and `use.review.settings.ts` store the current
+  `figma-token` setting in browser `localStorage`.
+- `dev/src/main.tsx` currently provides a dev `window.__figma` fixture.
+
+This flow should remain as the fallback for projects that have no image store.
+
+### Dev Server Gap
+
+`src/vite.ts` currently exports source/data locator plugins only. There is no
+middleware endpoint yet.
+
+A local `fileAdapter` cannot be browser-only, because browser code cannot write
+a JSON file. The local MVP should add a Vite/dev-server endpoint and expose a
+browser store client that calls that endpoint.
+
+## Proposed 0.7.0 Shape
+
+### Public/Shell Option
+
+Add an optional shell-level Figma image config. Keep it absent by default.
+
+```ts
+type ReviewShellFigmaImagesOptions = {
+  store?: ReviewFigmaImageStore;
+  enabled?: boolean;
+};
+
+interface ReviewShellProps {
+  // existing props...
+  figmaImages?: ReviewShellFigmaImagesOptions;
+}
+```
+
+Fallback rule:
+
+- `figmaImages?.store` exists: show/use Figma image management UI.
+- `figmaImages?.store` is missing: keep the current host-helper overlay button
+  and keyboard shortcut behavior.
+
+### Store Contract
+
+The 0.7.0 contract should be separate from `WebReviewKitAdapter`.
+
+```ts
+type ReviewFigmaImageTarget =
+  | { type: 'route'; projectId: string; pageUrl: string; slot?: string }
+  | { type: 'figma-node'; projectId: string; fileKey: string; nodeId: string };
+
+type ReviewFigmaImage = {
+  id: string;
+  projectId: string;
+  target: ReviewFigmaImageTarget;
+  figmaUrl: string;
+  fileKey: string;
+  nodeId: string;
+  imageUrl: string;
+  imageFormat: 'webp' | 'png' | 'jpg';
+  mimeType: string;
+  label?: string;
+  order: number;
+  storageKey?: string;
+  width?: number;
+  height?: number;
+  byteSize?: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type ReviewFigmaImageStore = {
+  listImages(target: ReviewFigmaImageTarget): Promise<ReviewFigmaImage[]>;
+  addImage(input: {
+    target: ReviewFigmaImageTarget;
+    figmaUrl: string;
+    imageFormat?: 'webp' | 'png' | 'jpg';
+  }): Promise<ReviewFigmaImage>;
+  deleteImage(id: string): Promise<void>;
+  reorderImages(input: {
+    target: ReviewFigmaImageTarget;
+    imageIds: string[];
+  }): Promise<ReviewFigmaImage[]>;
+  updateImage(
+    id: string,
+    patch: Partial<Pick<ReviewFigmaImage, 'label' | 'order'>>
+  ): Promise<ReviewFigmaImage>;
+};
+```
+
+`addImage` owns the internal image rendering/upload/cache step. The UI should
+not know whether the returned `imageUrl` came from a local dev server,
+OpenClaw-hosted upload, or a future Cloudflare-backed uploader.
+
+Default target output is `image/webp` with a quality setting around 90-95 for
+review/reference overlays, but the package should not force an image conversion
+dependency for the dev MVP. Without a configured transformer, the local cache
+stores the actual Figma render format (`png` or `jpg`) and records that real
+`mimeType`/`imageFormat` in metadata.
+
+### Module Layout
+
+Use the architecture doc's existing direction, but convert the current single
+`src/react-shell/figma.ts` file into a small module when implementation begins.
+
+```txt
+src/figma/
+  image.types.ts
+  parse.ts
+
+src/react-shell/figma/
+  image.client.ts
+  image.panel.tsx
+  image.state.ts
+  frame.ts
+
+src/vite.ts
+  reviewFigmaImageStore()
+```
+
+Suggested responsibilities:
+
+- `src/figma/parse.ts`: parse Figma node copy links into `fileKey` and `nodeId`.
+- `src/react-shell/figma/image.client.ts`: browser client for the dev endpoint
+  or any host-provided store.
+- `src/react-shell/figma/image.panel.tsx`: list/add/delete/reorder UI.
+- `src/vite.ts`: dev middleware for local JSON metadata and Figma rendering.
+
+### Local MVP Endpoint
+
+Add a dev plugin instead of trying to write files from browser code.
+
+```ts
+reviewFigmaImageStore({
+  enabled: true,
+  projectId: 'df-web-review-kit',
+  dataFile: '.df-review/figma-images.json',
+});
+```
+
+Endpoint shape can stay internal for 0.7.0, but should map directly to the
+store contract:
+
+- `GET /__dfwr/figma-images`
+- `POST /__dfwr/figma-images`
+- `PATCH /__dfwr/figma-images/:id`
+- `DELETE /__dfwr/figma-images/:id`
+
+The dev endpoint reads `FIGMA_TOKEN` from server env only when it needs to call
+Figma. Do not expose `VITE_FIGMA_TOKEN`.
+
+Token validation is intentionally lazy:
+
+- Store missing or disabled: no token check, keep the current host-helper
+  fallback.
+- Store enabled but no image render/add request has happened: no token check.
+- Image render/add request: require `FIGMA_TOKEN` from the dev/server
+  environment and return `DFWR_FIGMA_TOKEN_MISSING` when it is absent.
+
+## Impact Files
+
+Expected package-side implementation files:
+
+- `.env.sample`: document server-only `FIGMA_TOKEN` separately from browser
+  `VITE_*` values.
+- `src/types.ts` or `src/figma/image.types.ts`: shared Figma image types.
+- `src/index.ts`: export public Figma image types/parser only if needed by host
+  projects.
+- `src/react-shell/types.ts`: add optional `figmaImages`.
+- `src/react-shell/review/shell.tsx`: pass state/actions into the panel and
+  preserve existing fallback behavior.
+- `src/react-shell/topbar.tsx`: keep the existing overlay toggle available when
+  no image store exists.
+- `src/react-shell/review/settings.modal.tsx` and
+  `src/react-shell/hooks/use.review.settings.ts`: stop treating browser
+  `figma-token` as the new API token. Keep it only for legacy host helpers if
+  needed.
+- `src/vite.ts`: add the dev local metadata endpoint.
+- `dev/vite.config.ts` and `dev/src/main.tsx`: wire the local MVP for dogfood.
+
+Token helpers already added for the implementation steps:
+
+- `readReviewFigmaToken()` / `requireReviewFigmaToken()` validate an explicit
+  token/env object without reading browser globals.
+- `readReviewFigmaServerToken()` / `requireReviewFigmaServerToken()` are
+  exported from `@designfever/web-review-kit/vite` for dev/server-only code.
+- `ReviewFigmaTokenError` carries `DFWR_FIGMA_TOKEN_MISSING` so UI/API callers
+  can show a clear setup error.
+
+Parser/render helpers already added for the implementation steps:
+
+- `parseReviewFigmaNodeRef()` accepts either a Figma copy link or existing
+  `fileKey->nodeId` value.
+- URL `node-id` values are normalized from Figma web form like `4-228` to API
+  form like `4:228`.
+- `createReviewFigmaFrameUrl()` centralizes Figma frame link generation.
+- `renderReviewFigmaServerImage()` is exported from
+  `@designfever/web-review-kit/vite` and calls Figma `/v1/images/:fileKey` with
+  a server-side token.
+- The Figma API render URL is a temporary source URL. The local file adapter now
+  downloads it into the dev asset cache before writing JSON metadata.
+
+Local metadata store helpers already added for the implementation steps:
+
+- `createReviewFigmaImageStoreClient()` creates a browser-side
+  `ReviewFigmaImageStore` that calls the dev endpoint.
+- `reviewFigmaImageStore()` is exported from
+  `@designfever/web-review-kit/vite` and adds the local dev middleware.
+- The default endpoint is `/__dfwr/figma-images`.
+- The dev fixture stores metadata at `.df-review/figma-images.json`; the
+  `.df-review` folder is gitignored.
+- The local middleware downloads rendered image binaries into
+  `.df-review/figma-assets` by default and stores the served local asset URL as
+  `imageUrl`.
+- The asset endpoint defaults to `/__dfwr/figma-images/assets`.
+- `cacheAssets: false` keeps the old temporary render URL behavior for debugging.
+- `transformAsset` can convert the downloaded data before it is written, which
+  is where a future sharp/Cloudflare webp conversion step should plug in.
+
+Review page multi-image UI already added for the implementation steps:
+
+- When `figmaImages.store` is configured, the shell shows a Figma Images side
+  panel.
+- The panel supports list, add, delete, reorder, select, and overlay opacity
+  controls for the current route + viewport target.
+- When no store is configured, the legacy host-helper Figma overlay fallback is
+  still used.
+
+Release snapshot helpers already added for the implementation steps:
+
+- `createReviewFigmaImagesSnapshot()` clones and sorts image metadata for JSON
+  persistence.
+- `createReviewFigmaReleaseSnapshot()` returns a release-shaped JSON object
+  with `figmaImagesSnapshot`.
+- `collectReviewFigmaReleaseSnapshot()` can collect images through any
+  `ReviewFigmaImageStore` for a set of targets.
+- The local Vite middleware exposes
+  `GET/POST /__dfwr/figma-images/snapshot` for dev release JSON snapshots.
+
+Expected host-project follow-up files after stabilization:
+
+- `lexus_official_v2026/src/helper/helper.review-kit.ts`: remove per-project
+  helper wiring only after 0.7.0 fallback has been verified.
+- Host review route files: pass the image store config only for projects that
+  opt into the new flow.
+
+## Release Boundary
+
+There is no runtime "review release" model in the current package code. The
+existing release files are package release notes.
+
+For 0.7.0, do not introduce a release table or separate release image store.
+Todo 808 can keep this simple by snapshotting the current image list as JSON on
+whatever release object gets introduced:
+
+```ts
+figmaImagesSnapshot: ReviewFigmaImage[];
+```
+
+That is enough to ensure old review releases do not change when the current
+project/page Figma bindings are edited later.
+
+## Verification Plan
+
+For Todo 802, this document is the artifact.
+
+For the following implementation todos:
+
+- Adapter missing: `/review` still works with current keyboard shortcut/Figma
+  helper fallback.
+- Adapter configured and `FIGMA_TOKEN` missing: adding/rendering a Figma image
+  returns a clear error without breaking the rest of the review shell.
+- Adapter configured and `FIGMA_TOKEN` present: a Figma node copy link can be
+  added, listed, deleted, reordered, and survives dev server restart.
+- Existing QA adapters still pass `pnpm typecheck` and `pnpm build`.

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,7 +61,7 @@ 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 local = localAdapter({
@@ -111,7 +128,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({
@@ -218,7 +235,19 @@ export default defineConfig({
 
 Captured DOM nodes will include `data-wrk-source-file`, `data-wrk-source-line`, and `data-wrk-source-column`. Data locator also injects `__wrkDataFile` and `__wrkDataLine` props into page data section objects so the shell can expose matching `data-wrk-data-*` hints when host components forward those props to section wrappers.
 
-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. If the file path is absolute, it opens directly. If the plugin stores relative paths, pass `sourceRoot` when mounting the shell.
+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({
@@ -226,9 +255,7 @@ mountReviewShell({
   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,
@@ -242,9 +269,13 @@ Set `sourceInspector.enabled` to `false` when source code opening should be unav
 
 Use this only in dev/review builds. Source paths are written into the browser DOM and can be persisted with QA items.
 
+Source Tree filter/options, side panel state, and QA status filter are browser-local UI preferences. They are stored in localStorage and are not sent through the adapter.
+
+In React shell mode, DOM/area draft composers dock into the QA panel when the shell provides a composer host. This keeps mobile Safari keyboard/viewport resize from moving a floating composer layer over the target frame.
+
 ## 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:
 
@@ -257,12 +288,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: