@designfever/web-review-kit 0.7.3 → 0.8.1

package/docs/adaptor.sample.ts

@@ -1,5 +1,7 @@
 import {
   REVIEW_WORKFLOW_STATUS_OPTIONS,
+  type ReviewAttachment,
+  type ReviewAttachmentUploadInput,
   type ReviewItem,
   type ReviewItemQuery,
   type ReviewItemStatus,
@@ -17,17 +19,21 @@ type RemoteReviewAdapterOptions = {
   source?: ReviewSource;
   token?: string;
   fields?: ReviewShellAdapter['fields'];
+  attachmentUploadPath?: string;
   assigneeTitle?: string;
   assigneeOptions?: ReviewShellAssigneeOption[];
 };
 
 type RemoteReviewItemResponse = ReviewItem | { item: ReviewItem };
+type RemoteReviewAttachmentResponse =
+  | ReviewAttachment
+  | { attachment: ReviewAttachment };
 
 /*
  * WebReviewKitAdapter is the core storage contract.
  *
  * ReviewItem is the full QA payload. Persist it as structured JSON so marker,
- * anchor, selection, viewport, scroll, status, and external issue fields survive.
+ * anchor, selection, viewport, scroll, status, and external link fields survive.
  *
  * ReviewItemQuery is used by the shell for current-page lists and sitemap counts.
  * A remote backend should support at least projectId, routeKey, status, source,
@@ -101,12 +107,14 @@ 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'].
+ * canWrite can be true or limited to ['dom', 'area'].
  * update enables title/comment edits in the QA panel.
  * fields enables optional UI fields such as title. Omit title to keep comment-only UI.
  * updateStatus drives the status buttons in the QA panel.
  * assigneeOptions + updateAssignee drive the assignee select next to status.
  * assigneeTitle customizes the empty option/field label. Defaults to "Assignee".
+ * uploadAttachment lets paste/capture flows upload File/Blob data before the
+ * returned metadata is stored on ReviewItem.attachments.
  * remove enables delete actions for this source.
  */
 export function createRemoteReviewShellAdapter(
@@ -129,10 +137,44 @@ export function createRemoteReviewShellAdapter(
     assigneeOptions: options.assigneeOptions ?? [],
     updateAssignee: ({ id, assigneeId, assigneeName }) =>
       adapter.update(id, { assigneeId, assigneeName }),
+    uploadAttachment: options.attachmentUploadPath
+      ? (input) => uploadReviewAttachment(input, options)
+      : undefined,
     remove: (id) => adapter.remove(id),
   };
 }
 
+async function uploadReviewAttachment(
+  input: ReviewAttachmentUploadInput,
+  options: RemoteReviewAdapterOptions
+) {
+  if (!options.attachmentUploadPath) {
+    throw new Error('remote review attachment upload path is not configured');
+  }
+
+  const name =
+    input.name || (input.file instanceof File ? input.file.name : 'attachment');
+  const mime = input.mime || input.file.type;
+  const form = new FormData();
+  form.set('file', input.file, name);
+  form.set('name', name);
+  if (mime) form.set('mime', mime);
+  if (input.kind) form.set('kind', input.kind);
+  if (input.item) form.set('item_id', input.item.id);
+  if (input.metadata) form.set('metadata', JSON.stringify(input.metadata));
+
+  return readReviewAttachment(
+    await requestJson<RemoteReviewAttachmentResponse>(
+      options.attachmentUploadPath,
+      options,
+      {
+        method: 'POST',
+        body: form,
+      }
+    )
+  );
+}
+
 function appendParam(
   params: URLSearchParams,
   key: string,
@@ -160,7 +202,11 @@ async function requestJson<T>(
   const headers = new Headers(init.headers);
 
   headers.set('Accept', 'application/json');
-  if (init.body && !headers.has('Content-Type')) {
+  if (
+    init.body &&
+    !(init.body instanceof FormData) &&
+    !headers.has('Content-Type')
+  ) {
     headers.set('Content-Type', 'application/json');
   }
   if (options.token) {
@@ -185,6 +231,10 @@ function readReviewItem(response: RemoteReviewItemResponse) {
   return 'item' in response ? response.item : response;
 }
 
+function readReviewAttachment(response: RemoteReviewAttachmentResponse) {
+  return 'attachment' in response ? response.attachment : response;
+}
+
 function ensureTrailingSlash(value: string) {
   return value.endsWith('/') ? value : `${value}/`;
 }

package/docs/architecture.md

@@ -17,7 +17,7 @@ React shell
 
 Core runtime
   -> mounts a shadow DOM overlay
-  -> handles note/area/DOM selection
+  -> handles area/DOM selection
   -> creates markers and highlights over the target viewport
   -> persists ReviewItem records through the configured adapter
 ```
@@ -33,14 +33,14 @@ createWebReviewKit({
 });
 ```
 
-`ui.panel: false` means the React shell owns the side panel and toolbar. Core still owns target overlays such as note pins, area selection boxes, DOM hover outlines, saved item markers, and highlights.
+`ui.panel: false` means the React shell owns the side panel and toolbar. Core still owns target overlays such as area selection boxes, DOM hover outlines, saved item markers, and highlights.
 
 When the React shell provides a composer host, core docks DOM/area draft composer UI into the QA panel instead of rendering it as a floating target overlay. Core still owns draft creation, anchor capture, geometry, and adapter submission; React shell only provides the stable panel host.
 
 ## Core Modules
 
 - `web.review.kit.app.ts`: controller lifecycle, state transitions, adapter calls, item creation, restore flow.
-- `web.review.kit.view.ts`: vanilla DOM renderer for core overlay UI.
+- `web.review.kit.view.ts`: thin render orchestrator. Decides which overlay layers to render and docks the draft composer into the shell panel. All DOM building lives in `view/`.
 - `draft.metrics.ts`: pure geometry for draft adjustment (nudge/scale) previews, kept out of the renderer.
 - `dom.anchor.ts`: selector candidate generation, anchor rebinding, text fingerprint matching.
 - `geometry.ts`: target-space and host-space coordinate conversion.
@@ -50,6 +50,21 @@ When the React shell provides a composer host, core docks DOM/area draft compose
 - `scroll.ts`: scroll restore helpers.
 - `location.ts`: public URL and route key helpers.
 
+### Core View Modules (`src/core/view/`)
+
+The overlay renderer is split by role. Modules never reach into the app directly; they receive `WebReviewKitViewConfig` (options + state getter + actions) or the narrower `DraftLayerContext` defined in `view/types.ts`.
+
+- `dom.draft.ts`: DOM draft layer — pin, highlight, composer popover, adjustment (nudge/scale) controls, pin/composer drag.
+- `area.draft.ts`: area draft form, on-page selection overlay, and floating/docked composer popover.
+- `selection.layers.ts`: element-pick hover layer and area drag-select layer.
+- `markers.ts`: stored item marker/highlight layer.
+- `panel.ts`: built-in side panel for standalone core usage (header, toolbar, item list). Disabled under the React shell.
+- `form.widgets.ts`: shared draft form widgets (title input, assignee select, save/cancel actions, drag handle).
+- `draft.capture.ts`: viewport capture button and capture payload builders.
+- `composer.position.ts`: composer sizing/clamping and drag wiring (pure placement math).
+- `draft.text.ts`: metric/adjustment display formatting and the saved-comment adjustment suffix.
+- `icons.ts`: stateless SVG icon and spinner builders.
+
 ## Coordinate Spaces
 
 Core uses two coordinate spaces:
@@ -103,6 +118,105 @@ The default local adapter is for draft/local review work. Supabase is optional h
 
 React shell should call the core controller instead of duplicating target overlay logic.
 
+### React Shell Runtime Map
+
+`review/shell.tsx` is the React shell entrypoint. It creates instance-scoped
+config, refs, and zustand store objects, then delegates runtime wiring and layout
+assembly to smaller modules.
+
+```mermaid
+flowchart TD
+  Shell["review/shell.tsx"]
+  Config["store/shell.config.ts"]
+  Store["store/create.review.shell.store.ts"]
+  Refs["store/shell.refs.ts"]
+  Runtime["hooks/use.review.shell.runtime.ts"]
+  Providers["review/shell.providers.tsx"]
+  FrameContainer["review/shell.frame.container.tsx"]
+  Frame["review/shell.frame.tsx"]
+  Containers["feature *.container.tsx"]
+  Views["presentational UI components"]
+
+  Shell --> Config
+  Shell --> Store
+  Shell --> Refs
+  Shell --> Runtime
+  Runtime --> Providers
+  Providers --> FrameContainer
+  FrameContainer --> Frame
+  Frame --> Containers
+  Containers --> Views
+```
+
+The store is created once per mounted `ReviewShell` instance. There is no
+module-level shell store, so a host app using zustand does not share this state.
+
+### State Ownership
+
+| Layer | Files | Owns |
+|---|---|---|
+| Shell config | `store/shell.config.ts` | Normalized props and mostly static shell options |
+| Shell refs | `store/shell.refs.ts` | iframe, frame scroll, controller, and one-shot pending refs |
+| Zustand store | `store/*.slice.ts` | Target, QA, side panel, and local UI state |
+| Runtime hooks | `hooks/use.review.shell.*`, feature hooks | Effects, adapter refresh, core controller wiring, and action composition |
+| Runtime contexts | `review/shell.providers.tsx`, `*.context.tsx` | Non-store controllers consumed by feature containers |
+| Containers | `*.container.tsx` | Read store/context and bind actions to views |
+| Presentational views | non-container `.tsx` components | Render UI from explicit props |
+
+### Container Pattern
+
+Feature UI should not receive long prop chains from `ReviewShell`. Containers
+read the closest state source directly, then pass only render-ready props to
+presentational components.
+
+```mermaid
+flowchart LR
+  Store["zustand store"]
+  Config["config/ref contexts"]
+  RuntimeContext["runtime contexts"]
+  Container["feature container"]
+  View["presentational view"]
+
+  Store --> Container
+  Config --> Container
+  RuntimeContext --> Container
+  Container --> View
+```
+
+When adding shell behavior, prefer this flow:
+
+1. Put persistent UI state in the matching zustand slice.
+2. Put instance config in `shell.config.ts`.
+3. Put DOM/controller refs in `shell.refs.ts`.
+4. Put side effects and adapter/core orchestration in a focused hook.
+5. Expose cross-feature commands through `ReviewShellActions` only when multiple
+   containers need the same command.
+
+### Shell Hook Decomposition
+
+`hooks/use.review.shell.runtime.ts` is the runtime assembler. It composes smaller
+hooks and returns provider values; it should not become a render component.
+
+- `hooks/use.review.shell.state.ts`: bridge from zustand/config/refs into runtime hook inputs.
+- `hooks/use.review.shell.data.ts`: item list, filters, counts, target URL, and derived view data.
+- `hooks/use.review.shell.refresh.ts`: adapter refresh for current route and sitemap counts.
+- `hooks/use.review.shell.effects.ts`: shell-level effects such as pending restore, frame recentering, and Figma pointer lock.
+- `hooks/use.review.shell.runtime.actions.ts`: local command builders for transient UI, mode, panels, and iframe load.
+- `hooks/use.review.shell.actions.value.ts`: final `ReviewShellActions` context value.
+- `hooks/use.review.controller.ts`: core runtime wiring (init/reload/restore/mode).
+- `hooks/use.review.item.actions.ts`: QA item mutations and prompt/link copy actions.
+- `hooks/use.review.side.panel.ts`: side panel selection, availability fallback, and browser-local persistence.
+- `hooks/use.review.target.navigation.ts`: address parsing, page/source switching, selected-item clearing, and shell URL sync.
+- `hooks/use.review.source.inspector.ts`: source inspector state and target-iframe shortcut binding.
+- `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.
+
+### 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 overlay work should stay outside core unless it needs target runtime primitives.

package/docs/figma-overlay.md

@@ -23,6 +23,42 @@ the same-origin image store request as a fallback.
 
 Treat this as a review/debug convenience. Do not expose `VITE_FIGMA_TOKEN`.
 
+### Security note: browser-stored token
+
+The Settings token lives in plain `localStorage`. A Figma personal access token
+grants read access to every file the account can see, so any XSS on the host
+origin can read this key and exfiltrate it. Reduce the blast radius:
+
+- Prefer the server-side `FIGMA_TOKEN` env path. Only fall back to the Settings
+  token when a dev/reviewer genuinely cannot set server env.
+- When you must use the Settings token, use a short-lived or narrowly scoped
+  token and clear it from Settings when you are done.
+- Never commit or share the token, and never expose it as `VITE_FIGMA_TOKEN`
+  (that ships it to every browser bundle).
+
+The token is only sent to the same-origin image store endpoint via the
+`X-Figma-Token` header; it is not sent to `api.figma.com` from the browser.
+
+## Dev Server Image Store Hardening
+
+The `reviewFigmaImageStore()` Vite plugin runs only under `vite dev` (`apply:
+'serve'`); it is not part of `vite build` output, so production/Vercel deploys
+are unaffected. Because the dev endpoint is unauthenticated, its middleware
+applies minimal request checks:
+
+- **Cross-origin block**: browser requests whose `Origin` does not match the
+  request `Host` (and is not loopback) are rejected with `403`. Requests without
+  an `Origin` header (curl, scripts) and same-origin requests — including LAN IP
+  access for mobile testing — are allowed.
+- **JSON content type**: request bodies must be `application/json`. This blocks
+  `text/plain` "simple" cross-site POSTs that would otherwise skip a CORS
+  preflight. Rejected with `415`.
+- **Body size limit**: JSON bodies are capped (default 25 MB, configurable via
+  the `maxRequestBytes` plugin option). Oversized bodies are rejected with `413`.
+
+These guards protect the developer's local `FIGMA_TOKEN` and `.df-review`
+working files from CSRF-style requests made by other pages open in the browser.
+
 ## Availability
 
 The shell currently enables the Figma overlay on viewport presets whose `kind` is:
@@ -46,6 +82,18 @@ Expected behavior:
 
 The review shell uses those selectors only to detect whether the overlay is active.
 
+When the package-managed Figma image store is configured, the shell renders image
+overlays into the iframe instead. Those overlays use:
+
+- `#df-review-figma-image-target-root`
+- `.df-review-figma-image-target-overlay`
+
+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
+`pointer-events: none` so target selection is not blocked. Releasing `Option`
+restores the image overlay hit area.
+
 ## Troubleshooting
 
 If the button does nothing:
@@ -54,6 +102,9 @@ If the button does nothing:
 - Confirm the host helper listens for `KeyF`.
 - Confirm the helper renders `.helper-figma-root` or `.helper-figma-loading-backdrop`.
 - Confirm the current viewport preset is `mobile` or `wide`.
+- If `Option` source selection cannot pick an element under a Figma image
+  overlay, confirm the overlay root uses the package selectors above or the host
+  helper selectors listed in Host Requirements.
 
 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.

package/docs/grid-overlay.md

@@ -21,11 +21,16 @@ Expected behavior:
   - `.helper.onShow`
 
 The review shell uses those signals to keep the toolbar button state in sync.
+It also injects a small stacking-order safeguard so recognized grid/helper
+layers render above host Figma helpers and package-managed Figma image overlays.
 
 ## Notes
 
 - The package does not prescribe the grid design.
 - The grid overlay is not persisted as QA data.
+- Recognized grid roots are `.helper.onShow`, `body.is-help .helper`,
+  `#df-review-grid-overlay`, `.df-review-grid-overlay`, and
+  `[data-df-review-grid-overlay]`.
 - Use project-specific CSS/helper code in the host page when the grid differs by brand or design system.
 
 ## Troubleshooting

package/docs/installation.md

@@ -8,7 +8,7 @@ For the QA adapter and Figma image store split, see [Adapter boundaries](adapter
 ## Package Install
 
 ```bash
-pnpm add @designfever/web-review-kit react react-dom
+pnpm add @designfever/web-review-kit react react-dom zustand
 ```
 
 Supabase is optional. Install it only in host projects that use the Supabase adapter.
@@ -17,7 +17,7 @@ Supabase is optional. Install it only in host projects that use the Supabase ada
 pnpm add @supabase/supabase-js
 ```
 
-## Environment
+## Environment Reference
 
 Copy the repository [.env.sample](../.env.sample) into the host project as `.env.local`.
 
@@ -109,6 +109,29 @@ mountReviewShell({
 
 If omitted, the default label is `Responsive CSS px adjustments`. This option only changes the label before the generated `x`, `y`, and `scale` values.
 
+## Prompt Handoff
+
+Use `initialPrompt` for the global review handoff modal, and `qaPrompt` for the custom instruction prepended to every copied QA item prompt.
+
+```tsx
+mountReviewShell({
+  projectId: REVIEW_PROJECT_ID,
+  pages,
+  adapters,
+  initialPrompt: [
+    'You are fixing QA issues in this project.',
+    'Read AGENTS.md and the project README before editing.',
+  ].join('\n'),
+  qaPrompt: [
+    'Follow this project coding style before touching the selected QA item.',
+    'Keep the fix limited to the target route and viewport unless the bug is shared.',
+  ].join('\n'),
+  reviewPathPrefix: REVIEW_PATH_PREFIX,
+});
+```
+
+If `qaPrompt` is omitted, copied QA prompts keep the package default header.
+
 ## Supabase Adapter
 
 Host projects that choose Supabase create the client themselves and pass it into the package adapter.
@@ -236,9 +259,9 @@ 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.
+Captured DOM nodes will include `data-wrk-source-file`, `data-wrk-source-line`, and `data-wrk-source-column`. When TypeScript is available in the host toolchain, the source locator parses TSX/JSX and also adds `data-wrk-source-component` to intrinsic JSX nodes. For function component render paths, it records the parent JSX call site as `data-wrk-source-parent-*` hints so Source Tree can open the file that used the component. Data locator 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. 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.
+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. When parent usage hints exist, each row shows `used in` with the parent component and call-site file/position, plus an action to open that usage source. 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`:
 
@@ -268,11 +291,11 @@ mountReviewShell({
 });
 ```
 
-Set `sourceInspector.enabled` to `false` when source code opening should be unavailable. Use `sourceInspector.ignore` to hide infrastructure files from source candidates and the Source Tree. Use `sourceInspector.maxDepth` to cap Source Tree traversal depth. Set `sourceInspector.hoverOutline` to `false` to disable iframe target outlines while hovering Source Tree items. Set `sourceInspector.includePlacer` to `true` when primitive Placer nodes should appear in Source Tree. The `data-font` overlay still belongs to the target project markup and is not required for source opening.
+Set `sourceInspector.enabled` to `false` when source code opening should be unavailable. Use `sourceInspector.ignore` to hide infrastructure files from source candidates and the Source Tree. Use `sourceInspector.maxDepth` to cap Source Tree traversal depth. Set `sourceInspector.hoverOutline` to `false` to disable iframe target outlines while hovering Source Tree items. Set `sourceInspector.includePlacer` to `true` when primitive Placer nodes should appear in Source Tree or source candidate lists. 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.
 
-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.
+Source Tree filter/options, side panel state, QA status filter, and tooltip visibility 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.
 
@@ -287,6 +310,20 @@ The sample explains the main interfaces:
 - `WebReviewKitAdapter`: core CRUD contract.
 - `ReviewShellAdapter`: React shell wiring for source labels, write modes, status updates, and delete actions.
 
+### External Links
+
+`ReviewItem.externalLinks` can carry multiple external issue/sheet links. Each link should include `label` and `url`, with optional `title` and `icon`.
+
+If `externalLinks` is omitted, the shell still falls back to `externalIssueUrl` and renders it as a single `Remote` action. Use `externalLinks` when a host needs separate sheet, issue, preview, or admin links for the same QA item.
+
+### Attachments and Capture
+
+`ReviewItem.attachments` stores uploaded QA attachment metadata. Use `ReviewShellAdapter.uploadAttachment` to upload pasted files or iframe captures before adding the returned `ReviewAttachment` to an item.
+
+The upload method receives a browser `File | Blob` plus optional `kind`, `name`, `mime`, `item`, and `metadata`, then returns `url`, `name`, `mime`, `size`, and optional storage metadata. If `uploadAttachment` is omitted and a draft contains attachments, submit fails with adapter feedback instead of silently dropping files.
+
+Iframe captures are emitted as WebP when the DOM renderer succeeds and fall back to SVG only when raster capture is unavailable. Capture is based on same-origin iframe DOM access; it works on `localhost` and same-origin review hosts and is not HTTPS-only.
+
 Private keys, admin credentials, canonical numbering, and permission checks should stay in your backend, not in browser code.
 
 ## Environment
@@ -338,7 +375,7 @@ Open `http://127.0.0.1:5177/review/`.
 
 Fixture pages:
 
-- `/`: note, area, and DOM marker creation
+- `/`: area and DOM marker creation
 - `/components/`: controls and panel spacing
 - `/long-form/`: scroll and anchor restore
 
@@ -348,6 +385,7 @@ Package repo:
 
 ```bash
 pnpm typecheck
+pnpm test
 pnpm build
 pnpm typecheck:dev
 pnpm build:dev
@@ -363,6 +401,6 @@ pnpm build
 Manual smoke:
 
 1. Open `/review`.
-2. Create local note, DOM marker, and area marker.
+2. Create local DOM marker and area marker.
 3. If Supabase is enabled, submit a local item to remote.
 4. Confirm local draft removal, remote list display, status update, delete, and deep-link restore.

package/docs/release-notes-0.8.0.md

@@ -0,0 +1,175 @@
+# 릴리즈 노트: 0.8.0
+
+0.7.3 이후 QA 작성, source inspection, iframe capture, dev review fixture를 함께 보강한 minor release.
+
+비교 기준: `0.7.3`
+검토 기준: `main` release candidate
+
+## 주요 변경
+
+- QA item에 여러 외부 링크를 표시할 수 있는 `externalLinks` 필드를 추가했다.
+- QA DOM/area composer에서 paste attachment와 iframe viewport capture를 같은 attachment queue로 다룬다.
+- `ReviewShellAdapter.uploadAttachment`와 `ReviewItem.attachments` contract를 추가했다.
+- point-only Note QA를 제거하고 `ReviewItem.kind`를 `dom | area`로 정리했다.
+- Vitest adapter contract suite를 추가해 local/Supabase adapter의 CRUD, 필터, legacy row 처리를 검증한다.
+- iframe viewport capture는 WebP를 우선 생성하고, raster capture가 실패하면 SVG attachment로 fallback한다.
+- source locator가 TSX/JSX AST를 읽어 `data-wrk-source-component`를 주입한다.
+- Source Tree가 function component의 parent JSX call site를 `used in`으로 표시하고 바로 열 수 있다.
+- Option source inspector의 후보 매칭을 DOM path, component stack, QA target, text, 반복 index 기준으로 개선했다.
+- Source Tree가 component hierarchy를 더 잘 보여주도록 root 수집과 기본 표시 depth를 보정했다.
+- dev review fixture를 page/section/card/component 단위로 나눠 Source Tree와 후보 매칭을 검증하기 쉽게 만들었다.
+- Option source selection 중 Figma image overlay hit layer가 target hit-test를 가로채지 않도록 pointer lock을 분리했다.
+- icon-only control에 hover/focus tooltip을 추가하고 Settings에서 표시 여부를 끌 수 있게 했다.
+- keyboard shortcut matching이 한글 입력 상태의 물리 키를 함께 인식한다.
+- DF logo help modal에 shortcut list를 추가하고 prompt/help modal shell을 공통 component로 정리했다.
+
+## 변경
+
+### QA External Links
+
+`ReviewItem.externalLinks`를 추가해 한 QA item에서 여러 remote issue, sheet, admin URL을 표시할 수 있게 했다.
+
+- 각 link는 `label`, `url`, optional `title`, optional `icon`을 가진다.
+- QA card는 `externalLinks`를 우선 렌더링한다.
+- 기존 `externalIssueUrl`만 있는 item은 `Remote` link로 fallback 렌더링한다.
+- remote submit 후 local draft의 외부 링크 필드는 중복되지 않도록 정리한다.
+
+### Attachments and Capture
+
+QA draft에 attachment queue를 추가했다.
+
+- image paste는 draft attachment로 들어가고, 제출 전에 adapter `uploadAttachment`로 업로드된다.
+- DOM/area draft는 attachment만 있어도 제출할 수 있다.
+- `ReviewAttachment`는 `url`, `name`, `mime`, `size`, optional `kind`, `metadata`를 저장한다.
+- `ReviewAttachmentUploadInput`은 browser `File | Blob`과 draft item context를 함께 넘긴다.
+- iframe capture는 현재 viewport, marker, selection을 합성한 attachment를 만든다.
+- capture metadata에는 route, viewport, scroll, marker, selection, timestamp, renderer 정보가 들어간다.
+- capture는 same-origin iframe DOM 접근이 가능한 환경에서 동작한다. HTTPS 전용 기능은 아니다.
+
+### Adapter Contract and Note Removal
+
+QA item kind를 DOM/area 중심으로 정리했다.
+
+- `ReviewItemKind`는 `dom | area`만 허용한다.
+- `ReviewMode`는 `idle | element | area`만 남긴다.
+- point-only Note QA toolbar, shortcut, draft layer, popover style을 제거했다.
+- 기존 DOM QA는 `kind: 'dom'`으로 저장된다.
+- local/Supabase adapter는 legacy `note` row를 QA list에 노출하지 않는다.
+- legacy `capture` row는 local adapter에서 `area`로 정규화한다.
+
+Adapter 회귀를 줄이기 위해 Vitest를 추가했다.
+
+- `pnpm test`는 `vitest run`을 실행한다.
+- `pnpm test:watch`는 watch 모드로 Vitest를 실행한다.
+- `src/adapters/adapter.contract.test.ts`에서 local adapter와 Supabase adapter mock을 같은 contract로 검증한다.
+- contract는 `create/list/get/update/remove`, route/status filter, attachments, externalLinks, assignee/status 보존, legacy `note` 필터링을 확인한다.
+
+### Capture Format
+
+capture output은 용량을 줄이기 위해 WebP를 우선 사용한다.
+
+- `html2canvas`로 iframe DOM을 rasterize한 뒤 `image/webp`로 인코딩한다.
+- 실패하면 기존 SVG clone을 canvas에 그려 WebP로 다시 시도한다.
+- 두 raster path가 모두 실패할 때만 `image/svg+xml` attachment로 저장한다.
+- WebP metadata에는 `captureRenderer`와 `captureScale`이 기록된다.
+
+### Source Locator and Source Tree
+
+source opening의 실제 후보 품질을 높였다.
+
+- Vite `reviewSourceLocator()`가 TypeScript가 있는 host에서 TSX/JSX를 파싱한다.
+- intrinsic JSX node에 component 이름을 `data-wrk-source-component`로 주입한다.
+- function component render path에는 parent JSX call site를 `data-wrk-source-parent-*` hint로 전달한다.
+- Source Tree는 nested source roots를 flat root로 중복 수집하지 않고 parent/child hierarchy로 보여준다.
+- Source Tree row는 parent usage가 있으면 `used in` meta와 usage source open action을 보여준다.
+- 기본 표시 depth를 늘려 dev fixture처럼 page/section/card로 나뉜 구조가 바로 보인다.
+- `includePlacer: false`일 때 Placer 계열 primitive는 Source Tree와 candidate list에서 숨긴다.
+
+### Source Candidate Matching
+
+Option source inspector 후보 정렬을 보강했다.
+
+- 후보 dedupe 기준을 file-only에서 source identity 기준으로 바꿨다.
+- target element, QA data attribute, component stack, text match, section hint, line/column을 함께 점수화한다.
+- 같은 component가 반복되는 카드/리스트는 `#1/3`, `#2/3`처럼 반복 index를 표시한다.
+- candidate popover에는 `23:9 · component · target · qa · text · #1/3`처럼 선택 이유를 노출한다.
+- file별 후보는 최대 3개, 전체 후보는 최대 8개까지 보여준다.
+
+### Figma Overlay Interaction
+
+Option source selection과 Figma overlay의 hit-test 충돌을 막았다.
+
+- 기존 element review mode의 Figma pointer lock은 유지한다.
+- Option source selection용 pointer lock을 별도 style id로 분리했다.
+- lock 대상에 host helper selector와 package Figma image overlay selector를 함께 포함했다.
+- Option 키를 누른 동안 overlay image가 source target hit-test를 가로채지 않고, 키를 떼면 기존 overlay 조작이 복구된다.
+
+### Icon Tooltips
+
+아이콘만 있는 주요 control에 커스텀 tooltip을 추가했다.
+
+- topbar action, overlay toggle, side rail, QA card action, Source Tree action, Figma image action에 기능명을 표시한다.
+- tooltip은 `hover`와 `focus-visible`에서 표시되어 마우스와 키보드 탐색 모두에서 확인할 수 있다.
+- Settings의 Tooltips 옵션으로 custom tooltip과 해당 control의 native `title` tooltip을 함께 끌 수 있다.
+- tooltip 표시 여부는 `df-review-tooltips-enabled` localStorage key에 browser-local UI preference로 저장된다.
+
+### Shortcuts and Help
+
+단축키 접근성을 정리했다.
+
+- `G/F/R/E/A` shell shortcut은 한글 입력 상태에서도 `ㅎ/ㄹ/ㄱ/ㄷ/ㅁ`로 동작한다.
+- `Shift+Q`와 Figma dev overlay `Shift+F`도 같은 hotkey matcher를 사용한다.
+- side rail 순서를 Figma Images, QA, Component List로 정리하고 `Shift+1/2/3` panel shortcut을 추가했다.
+- DF logo로 여는 help modal에 shortcut list를 추가했다.
+- 기존 설명글은 제거하고 header에 package version만 표시한다.
+- help/prompt modal은 max-height를 제한하고 header 아래 body만 내부 스크롤되게 정리했다.
+- help/prompt 계열 modal은 공통 `ReviewModal` component가 wrapper를 담당하고 contents는 children으로 받는다.
+
+### Dev Review Fixture
+
+`pnpm dev:review` fixture를 release 검증용으로 더 현실적으로 나눴다.
+
+- page routing, nav, home, components, long-form fixture를 분리했다.
+- home fixture는 hero/action list/smoke grid/card 계층을 가진다.
+- components fixture는 controls, metrics panel, state preview grid로 나뉜다.
+- long-form fixture는 scroll, anchor restore, Source Tree depth 확인에 사용한다.
+
+## Host 영향
+
+- attachment paste/capture를 저장하려면 host `ReviewShellAdapter`에 `uploadAttachment`를 구현해야 한다.
+- `uploadAttachment`가 없는 adapter에서 attachment가 포함된 draft를 제출하면 저장하지 않고 error feedback을 표시한다.
+- `note` kind를 저장하거나 반환하던 host adapter는 `dom` 또는 `area`로 매핑해야 한다.
+- capture는 browser package dependency로 `html2canvas`를 사용한다.
+- source locator component/parent usage hint는 TypeScript가 host dependency로 있을 때만 동작한다. 없으면 기존 file/line/column hint만 사용한다.
+- source hints는 DOM에 source path와 component 이름을 쓰므로 dev/review build에서만 켜야 한다.
+- 기존 `externalIssueUrl`만 쓰는 host는 계속 동작한다. 여러 링크가 필요할 때만 `externalLinks`를 추가하면 된다.
+- Figma image overlay를 쓰는 host는 Option source selection 중 overlay drag가 잠깐 비활성화된다.
+
+## 문서
+
+- README 최신 release note 링크를 0.8.0으로 갱신했다.
+- docs index에 0.8.0 release note와 0.7.3 patch note를 정리했다.
+- installation guide에 external links, attachment upload, WebP capture contract를 정리했다.
+- adapter boundary 문서에 QA attachment, item kind, contract test, Figma image store 책임 분리를 반영했다.
+- Vitest adapter contract 문서를 추가했다.
+- Figma overlay 문서에 package image overlay selector와 source selection pointer lock behavior를 추가했다.
+
+## 검증
+
+아래 명령을 확인했다.
+
+- `pnpm typecheck`
+- `pnpm test`
+- `pnpm typecheck:dev`
+- `pnpm build`
+- `pnpm build:dev`
+
+수동 확인:
+
+- iframe fake Figma image overlay에서 Option down/up hit-test가 overlay -> target -> overlay 순서로 바뀌는지 확인했다.
+- source candidate 반복 카드가 `#1/3`, `#2/3`, `#3/3`으로 구분되는지 확인했다.
+- Source Tree가 `/`, `/components/`, `/long-form/` fixture에서 depth 있는 hierarchy와 `used in` parent usage를 보여주는지 확인했다.
+- viewport capture가 WebP attachment와 renderer metadata를 생성하는지 확인했다.
+- icon-only control hover 시 tooltip이 표시되고 Settings에서 끄면 사라지는지 확인했다.
+- 한글 키 synthetic event로 shell shortcut이 처리되는지 확인했다.
+- DF logo help modal에서 shortcut list 13개와 modal layout을 확인했다.