@designfever/web-review-kit 0.1.0 → 0.3.0

package/docs/smoke-baseline-2026-06-20.md

@@ -1,41 +0,0 @@
-# Smoke baseline 2026-06-20
-
-Scope: `packages/df-web-review-kit` task 761, before UI token/chrome changes.
-
-Environment:
-
-- Branch: `uforgot/feat/review-kit-stabilize-ui`
-- Dev URL: `http://127.0.0.1:5181/review/?target=%2F&w=540&h=1080`
-- Timestamp: `2026-06-20 11:31:21 KST`
-- `.env`: Supabase URL, anon key, table, presence-private flags were present. Secret values were not logged.
-
-Commands:
-
-```bash
-pnpm review-kit:build
-pnpm exec vite --host 127.0.0.1 --port 5181 --strictPort
-```
-
-Checklist result:
-
-| Check | Result | Note |
-| --- | --- | --- |
-| Local note create | Pass | Created `smoke-761 local note` from review shell UI. |
-| Local element QA create | Pass | Created `smoke-761 local element`; item had `anchor` and `selection`. |
-| Local area QA create | Pass* | CDP drag event was unreliable for the area drawer, so a synthetic area item was inserted through the same local storage shape to validate listing/rendering baseline. Manual browser drag still needs a quick human pass if this becomes a regression point. |
-| Item restore after scroll | Pass | Stable lower-page item restored from `scrollY 0` to `6487`, target top `517`. |
-| Remote submit to Supabase | Pass | Local item submitted; remote source showed canonical `#10`. |
-| Remote source list | Pass | `source=supabase` listed the smoke item plus existing remote items. |
-| Remote status change | Pass | Status changed from `todo` to `doing` and persisted after refresh. |
-| Remote delete | Pass | Smoke item deleted from Supabase; no longer present after refresh. |
-| `/review?source=supabase&target=...&item=...` restore | Pass | Remote item URL restored to the lower-page anchor before deletion: `/review/?target=%2F&w=540&h=1080&source=supabase&item=852662d1-410a-46b9-b047-b0abba55e83f`. |
-
-Cleanup:
-
-- Deleted the remote smoke item from Supabase.
-- Removed local `smoke-761` items from localStorage.
-
-Notes:
-
-- Figma overlay loaded because the local token was available; this was not part of the 761 smoke scope.
-- The area creation interaction should be manually spot-checked once UI chrome work starts, because automated pointer drag did not open the area note drawer reliably in CDP.

package/docs/stabilize-ui-work-guide.md

@@ -1,243 +0,0 @@
-# Stabilize UI work guide
-
-Branch:
-
-```txt
-uforgot/feat/review-kit-stabilize-ui
-```
-
-Purpose:
-
-`df-web-review-kit`를 package로 분리하기 전에 0.1 기반을 안정화하고, review shell chrome을 token 기반 UI로 정리한다.
-
-## Scope
-
-In scope:
-
-- Fix DOM anchor restore bug.
-- Establish smoke test baseline for current review workflow.
-- Introduce `df-review-token` layer inspired by Vercel Geist tokens.
-- Apply tokenized UI to review shell chrome.
-- Split only the React shell parts that block the UI cleanup.
-- Prepare package split checklist.
-
-Out of scope:
-
-- Figma overlay module migration.
-- Editing proposal feature.
-- Source patch AI adapter.
-- Full rewrite of `react-shell.tsx`.
-
-Follow-up branches:
-
-```txt
-uforgot/feat/review-kit-figma-module
-uforgot/feat/review-kit-editing-proposal
-```
-
-## Work order
-
-### 0. Fix anchor restore
-
-Files:
-
-```txt
-src/react-shell/anchor-restore.ts
-src/core/web-review-kit-app.ts
-```
-
-Goal:
-
-Element-mode review items must restore by DOM anchor even when their `scope` is a viewport scope such as `mobile` or `desktop`.
-
-Context:
-
-Current `queryReviewItemAnchorElement` exits unless `item.scope === 'dom'`, but element-mode items can be stored as `kind: note` with `anchor + selection` and viewport scope.
-
-Deliverable:
-
-- Shared or local predicate that treats `scope === 'dom'` or `kind === 'note' && anchor && selection` as anchor-restorable.
-- Anchor restore path uses that predicate.
-
-Verification:
-
-- Create an element-mode QA item.
-- Scroll away.
-- Click the item in the QA list.
-- The target element is restored by selector/anchor, not only by stale coordinates.
-
-### 1. Capture smoke baseline
-
-Goal:
-
-Before UI changes, confirm the current workflow still works.
-
-Deliverable:
-
-- Manual smoke checklist result in the PR/commit notes or a short docs note.
-
-Verification checklist:
-
-- Local note create.
-- Local element QA create.
-- Local area QA create.
-- Item restore after scroll.
-- Remote submit to Supabase.
-- Remote source list.
-- Remote status change.
-- Remote delete.
-- `/review?source=supabase&target=...&item=...` restore.
-
-### 2. Add review token layer
-
-Files:
-
-```txt
-src/react-shell/style.ts
-src/core/overlay-style.ts
-```
-
-Goal:
-
-Adopt a developer-tool UI tone using Vercel Geist as reference, without depending on Vercel token names at runtime.
-
-Rules:
-
-- Use `df-review-token` or `--df-review-*` naming.
-- Do not expose `geist` or `vercel` as public API names.
-- Keep light/dark theme support.
-- Use neutral surfaces, restrained color, clear state colors.
-- Do not change target page styling.
-
-Deliverable:
-
-- CSS custom properties for color, spacing, radius, typography, shadow/border.
-- Existing chrome components consume those variables.
-
-Verification:
-
-- Dark and light themes render correctly.
-- Buttons, selects, cards, modals, and overlay controls keep usable contrast.
-- Target iframe content is not affected.
-
-### 3. Apply UI chrome refresh
-
-Files:
-
-```txt
-src/react-shell.tsx
-src/react-shell/style.ts
-src/core/overlay-style.ts
-```
-
-Goal:
-
-Refresh only the review tool UI, not the host website UI.
-
-Targets:
-
-- Topbar.
-- Path input and load/copy buttons.
-- Source select and refresh button.
-- Viewport preset buttons.
-- Grid, Figma, ruler, settings controls.
-- QA cards.
-- Prompt/settings/sitemap modals.
-
-Deliverable:
-
-- More consistent developer-tool chrome.
-- Icon buttons stay compact.
-- Text does not overflow in compact panels.
-
-Verification:
-
-- Mobile, tablet, desktop, wide review presets.
-- QA list open/closed states.
-- Empty state and filtered state.
-- Prompt/settings/sitemap modals.
-
-### 4. Split only blocking React shell parts
-
-Goal:
-
-Reduce `react-shell.tsx` risk without turning this branch into a rewrite.
-
-Allowed splits:
-
-- `Topbar`.
-- `ItemList`.
-- `SettingsModal`.
-- `PromptModal`.
-- `SitemapModal`.
-
-Rules:
-
-- Split only when the UI token work becomes hard to review in one file.
-- Keep behavior unchanged.
-- Avoid new state architecture in this branch.
-
-Deliverable:
-
-- Smaller reviewable components if needed.
-- No broad refactor.
-
-Verification:
-
-- Typecheck passes.
-- Existing interactions still work.
-
-### 5. Package split checkpoint
-
-Goal:
-
-Make the package ready to split after this branch, before Figma module migration.
-
-Checklist:
-
-- `package.json` export map is accurate.
-- `files` list is intentional.
-- `react` and `react-dom` stay peer dependencies.
-- Decide whether `lucide-react` is peer or bundled.
-- `src`, `dist`, and `docs` publishing policy is explicit.
-- Host project consumes the package through the same exported API.
-
-Deliverable:
-
-- Short package split note or checklist update.
-
-Verification:
-
-```bash
-pnpm --dir packages/df-web-review-kit typecheck
-pnpm exec tsc --noEmit
-pnpm review-kit:build
-```
-
-## Figma module boundary for next branch
-
-Figma overlay migration should start only after this branch is stable.
-
-Boundary:
-
-- Package core renders overlay.
-- Host provides image URL/blob or a Figma asset adapter.
-- Browser-exposed Figma token and Figma REST fetch do not enter package core.
-- Current viewport replaces host zustand `isMobile/clientWidth` dependency.
-
-Expected next branch:
-
-```txt
-uforgot/feat/review-kit-figma-module
-```
-
-## Completion criteria
-
-This branch is ready for review when:
-
-- Anchor restore bug is fixed.
-- Smoke baseline is documented.
-- UI token layer is in place.
-- Review shell chrome is visually consistent.
-- Typecheck and build pass.
-- Figma migration remains out of scope.

package/docs/supabase-presence.md

@@ -1,198 +0,0 @@
-# Supabase presence adapter
-
-## 목적
-
-`df-web-review-kit`의 `ReviewPresenceAdapter` contract를 Supabase Realtime Presence로 구현하고 운영하기 위한 문서다.
-
-Lexus pilot Supabase project:
-
-```txt
-name: bb-qa
-url: https://vhqnvfkamnpgyqclohso.supabase.co
-```
-
-공식 문서 기준:
-
-- Presence는 접속자/활성 문서 같은 느리게 변하는 상태 공유에 맞다: https://supabase.com/docs/guides/realtime/presence
-- Realtime은 Broadcast, Presence, Postgres Changes를 제공한다: https://supabase.com/docs/guides/realtime
-- DB 변경 fan-out은 Broadcast가 scalability/security 측면에서 권장되고, Postgres Changes는 단순하지만 scale이 약하다: https://supabase.com/docs/guides/realtime/subscribing-to-database-changes
-- private Broadcast/Presence는 `realtime.messages` RLS policy와 `private: true` channel 설정이 필요하다: https://supabase.com/docs/guides/realtime/authorization
-
-## 현재 결론
-
-이번 presence 요구사항은 Supabase Presence가 맞다.
-
-목표는 "QA item이 바뀌면 실시간으로 동기화"가 아니라 "현재 누가 어떤 page/viewport/source를 보고 있는지"다. 따라서 Postgres Changes나 Broadcast보다 Presence가 먼저다.
-
-현재 shell UI는 두 단계로 보여준다.
-
-- 우측 QA panel: 현재 page에 있는 user id만 표시
-- sitemap: page별 user id 표시
-
-## Channel 전략
-
-권장 channel topic:
-
-```txt
-review-presence-<projectId>
-```
-
-page별 channel이 아니라 project 단위 channel을 쓴다. 그래야 `/review`를 열어 둔 사람이 서로 다른 page를 보고 있어도 sitemap에서 "누가 어느 페이지에 있는지"를 볼 수 있다.
-
-Payload의 `target`/`routeKey`로 page를 구분한다.
-
-topic은 Supabase Realtime 호환성을 위해 `:` 같은 구분자를 쓰지 않고, adapter에서 `channelPrefix`와 `projectId`를 alphanumeric/`_`/`-` slug로 normalize한다.
-
-## Adapter implementation
-
-현재 구현 위치:
-
-```txt
-packages/df-web-review-kit/src/react-shell/supabase-presence.ts
-```
-
-현재 package adapter는 Supabase client를 직접 생성하지 않고 `client`를 주입받는다. Host page 쪽에서 `@supabase/supabase-js`의 `createClient()`를 호출해 넘긴다. 이렇게 하면 package 본체가 Supabase dependency에 강하게 묶이지 않는다.
-
-현재 구현 특징:
-
-- channel topic은 `review-presence-<projectId>`로 생성한다.
-- `projectId`, `sessionId`, `userId`, `routeKey`, `target`, `source`, `viewport`, `mode`, `selectedItemId`, `selectedReviewNumber`를 track한다.
-- StrictMode/HMR에서 같은 topic channel이 중복으로 남지 않도록 bridge/refCount를 둔다.
-- `presenceState()` 결과는 `sessionId` 기준으로 dedupe한다.
-- primary Supabase presence 연결이 실패하면 `createFallbackPresenceAdapter()`로 local BroadcastChannel presence를 쓸 수 있다.
-
-## Public dev mode
-
-초기 연결 검증은 public channel로도 가능하다.
-
-```ts
-const presence = createSupabasePresenceAdapter({
-  client: supabase,
-  private: false,
-});
-```
-
-주의:
-
-- public channel은 같은 Supabase project key를 가진 사용자가 topic을 알면 subscribe 가능하다.
-- dev smoke test까지만 허용한다.
-
-## Private production mode
-
-production은 private channel을 권장한다.
-
-```ts
-const presence = createSupabasePresenceAdapter({
-  client: supabase,
-  private: true,
-});
-```
-
-client는 인증 세션을 가진 Supabase client여야 한다. private channel은 Realtime Authorization policy가 필요하다.
-
-## RLS sketch
-
-Supabase Realtime Authorization은 `realtime.messages`에 대한 RLS policy로 Broadcast/Presence 권한을 계산한다.
-
-project membership table을 둔다고 가정한다.
-
-```sql
-create table if not exists public.review_project_members (
-  project_id text not null,
-  user_id uuid not null references auth.users(id) on delete cascade,
-  created_at timestamptz not null default now(),
-  primary key (project_id, user_id)
-);
-
-alter table public.review_project_members enable row level security;
-
-create policy review_project_members_read_own
-  on public.review_project_members
-  for select
-  to authenticated
-  using ((select auth.uid()) = user_id);
-
-create index if not exists review_project_members_user_project_idx
-  on public.review_project_members (user_id, project_id);
-```
-
-Presence topic은 `review-presence-<projectId>` 형식이므로 RLS에서 topic을 project id로 해석한다.
-
-```sql
-create or replace function public.review_presence_project_id(topic text)
-returns text
-language sql
-immutable
-as $$
-  select nullif(regexp_replace(topic, '^review-presence-', ''), topic);
-$$;
-```
-
-Presence read/write policy:
-
-```sql
-create policy "authenticated can listen to review presence"
-on realtime.messages
-for select
-to authenticated
-using (
-  realtime.messages.extension = 'presence'
-  and exists (
-    select 1
-    from public.review_project_members member
-    where member.user_id = (select auth.uid())
-      and member.project_id = public.review_presence_project_id((select realtime.topic()))
-  )
-);
-
-create policy "authenticated can track review presence"
-on realtime.messages
-for insert
-to authenticated
-with check (
-  realtime.messages.extension = 'presence'
-  and exists (
-    select 1
-    from public.review_project_members member
-    where member.user_id = (select auth.uid())
-      and member.project_id = public.review_presence_project_id((select realtime.topic()))
-  )
-);
-```
-
-RLS performance notes:
-
-- `auth.uid()`는 `(select auth.uid())` 형태로 감싸서 per-row 호출을 줄인다.
-- RLS 조건에서 조회하는 `(user_id, project_id)`는 composite index를 둔다.
-- policy가 복잡해질수록 channel join latency가 늘 수 있다.
-
-## Env
-
-Lexus pilot에 붙일 때 후보 env:
-
-```txt
-VITE_REVIEW_SUPABASE_URL=https://vhqnvfkamnpgyqclohso.supabase.co
-VITE_REVIEW_SUPABASE_ANON_KEY=
-VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE=false
-```
-
-브라우저에는 anon key만 둔다. service role key는 절대 넣지 않는다.
-
-`VITE_REVIEW_SUPABASE_ANON_KEY`가 비어 있으면 shell은 local BroadcastChannel presence로 fallback한다.
-
-## QA checklist
-
-1. Settings에서 각 브라우저에 다른 `User ID` 입력
-2. Browser A/B: 같은 target page로 `/review?target=/&w=540&h=1080`
-3. A/B 양쪽 우측 QA panel에서 서로의 user id 확인
-4. Browser B를 다른 target page로 이동
-5. A의 우측 QA panel에서는 B가 사라지고, sitemap에서는 B가 이동한 page에 표시되는지 확인
-6. B에서 viewport 변경 후 presence payload의 viewport가 바뀌는지 devtools로 확인
-7. B에서 다른 QA item 선택 후 `selectedReviewNumber`가 payload에 들어가는지 devtools로 확인
-8. B tab close 후 A에서 B가 사라지는지 확인
-
-## Open decisions
-
-- public dev mode를 package에 남길지.
-- private presence를 실제 production에서 쓸 때 auth/member policy를 어디까지 package 문서화할지.
-- sitemap presence를 별도 dashboard로 키울지.