@designfever/web-review-kit 0.7.2 → 0.8.0

package/docs/code-review-0.6.0.md

@@ -1,232 +0,0 @@
-# 코드 리뷰 및 정리: 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/figma-image-mvp-0.7.0.md

@@ -1,330 +0,0 @@
-# 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`.