@designfever/web-review-kit 0.6.0 → 0.7.1

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,330 @@
+# 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 previous Figma integration was only a host-helper toggle:
+
+- `docs/figma-overlay.md` documents the host-helper toggle and the image store
+  token fallback.
+- `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 first when it needs to call
+Figma. If the env token is absent, the browser Settings token stored as
+`figma-token` can be sent to the same-origin image store request as a fallback.
+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: use `FIGMA_TOKEN` from the dev/server environment
+  first, then the Settings `figma-token` request fallback. Return
+  `DFWR_FIGMA_TOKEN_MISSING` when both are 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`: keep `figma-token` as a
+  browser-local review fallback for users who cannot set server env.
+- `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 both `FIGMA_TOKEN` plus Settings `figma-token` are
+  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/figma-overlay.md

@@ -1,12 +1,14 @@
 # Figma Overlay
 
-The Figma overlay button in the review shell toggles a host-page helper. The package does not fetch Figma data by itself and does not own a server-side Figma token.
+The Figma overlay button in the review shell toggles a host-page helper. The
+Figma image manager can also call the review-kit image store when the host wires
+one.
 
 ## User Flow
 
 - Open `/review`.
 - Click the settings button.
-- Enter a Figma token if the host helper requires one.
+- Enter a Figma token if the host helper or image store fallback requires one.
 - Click the Figma overlay button or press `f`.
 
 The token is stored in browser localStorage with this key:
@@ -15,7 +17,11 @@ The token is stored in browser localStorage with this key:
 figma-token
 ```
 
-Treat this as a dev/debug convenience. Do not use it for private server tokens.
+For Figma image add/render requests, the server/dev process uses `FIGMA_TOKEN`
+first. If that env token is missing, the browser sends this Settings token to
+the same-origin image store request as a fallback.
+
+Treat this as a review/debug convenience. Do not expose `VITE_FIGMA_TOKEN`.
 
 ## Availability
 
@@ -49,4 +55,5 @@ If the button does nothing:
 - Confirm the helper renders `.helper-figma-root` or `.helper-figma-loading-backdrop`.
 - Confirm the current viewport preset is `mobile` or `wide`.
 
-If the overlay needs a private Figma integration, move that work to a backend/admin service and expose only browser-safe state to the host page.
+If the overlay needs a private shared Figma integration, move that work to a
+backend/admin service and expose only browser-safe state to the host page.