@designfever/web-review-kit 0.1.0 → 0.2.0

package/docs/db-setup.md

@@ -0,0 +1,253 @@
+# DB Setup
+
+Supabase is an optional backend adapter. A host project may use it for canonical QA items and Realtime Presence, but the public package does not own the Supabase project or any operator secrets.
+
+## Environment
+
+```env
+VITE_REVIEW_PROJECT_ID=df-web-review-kit
+VITE_REVIEW_SUPABASE_URL=https://your-project.supabase.co
+VITE_REVIEW_SUPABASE_ANON_KEY=
+VITE_REVIEW_SUPABASE_TABLE=review_items
+VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE=false
+```
+
+Use only an `anon` key in browser env. Keep `service_role`, OpenClaw `KUKU_*`, and future admin keys in an operator layer or backend service.
+
+## Review Item Schema
+
+Run this in the Supabase SQL editor to create the tables, indexes, RPC, and grants.
+
+```sql
+create table if not exists public.review_items (
+  id text primary key,
+  project_id text not null,
+  route_key text not null,
+  source text not null default 'supabase',
+  review_number integer,
+  status text not null default 'todo',
+  item jsonb not null,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+create unique index if not exists review_items_project_review_number_idx
+  on public.review_items (project_id, source, review_number)
+  where review_number is not null;
+
+create index if not exists review_items_project_route_updated_idx
+  on public.review_items (project_id, source, route_key, updated_at desc);
+
+create index if not exists review_items_project_status_idx
+  on public.review_items (project_id, source, status);
+
+create table if not exists public.review_project_counters (
+  project_id text not null,
+  source text not null default 'supabase',
+  next_review_number integer not null default 1,
+  updated_at timestamptz not null default now(),
+  primary key (project_id, source),
+  constraint review_project_counters_next_review_number_check
+    check (next_review_number > 0)
+);
+
+create or replace function public.create_review_item(
+  p_id text,
+  p_project_id text,
+  p_route_key text,
+  p_source text,
+  p_status text,
+  p_item jsonb
+)
+returns public.review_items
+language plpgsql
+security invoker
+set search_path = public
+as $$
+declare
+  v_review_number integer;
+  v_now timestamptz := now();
+  v_row public.review_items;
+begin
+  insert into public.review_project_counters (
+    project_id,
+    source,
+    next_review_number,
+    updated_at
+  )
+  select
+    p_project_id,
+    p_source,
+    coalesce(max(review_number), 0) + 2,
+    v_now
+  from public.review_items
+  where project_id = p_project_id
+    and source = p_source
+  on conflict (project_id, source) do update
+    set next_review_number = greatest(
+          public.review_project_counters.next_review_number + 1,
+          excluded.next_review_number
+        ),
+        updated_at = excluded.updated_at
+  returning next_review_number - 1 into v_review_number;
+
+  insert into public.review_items (
+    id,
+    project_id,
+    route_key,
+    source,
+    review_number,
+    status,
+    item,
+    created_at,
+    updated_at
+  )
+  values (
+    p_id,
+    p_project_id,
+    p_route_key,
+    p_source,
+    v_review_number,
+    p_status,
+    p_item || jsonb_build_object(
+      'id', p_id,
+      'reviewNumber', v_review_number,
+      'projectId', p_project_id,
+      'routeKey', p_route_key,
+      'normalizedPath', coalesce(nullif(p_item->>'normalizedPath', ''), p_route_key),
+      'status', p_status,
+      'externalIssueId', p_id,
+      'submittedAt', coalesce(p_item->>'submittedAt', v_now::text),
+      'submitStatus', coalesce(p_item->>'submitStatus', 'submitted'),
+      'createdAt', v_now::text,
+      'updatedAt', v_now::text
+    ),
+    v_now,
+    v_now
+  )
+  returning * into v_row;
+
+  return v_row;
+end;
+$$;
+
+grant execute on function public.create_review_item(
+  text,
+  text,
+  text,
+  text,
+  text,
+  jsonb
+) to anon;
+
+grant select, insert, update, delete on public.review_items to anon;
+grant select, insert, update on public.review_project_counters to anon;
+```
+
+## RLS Policies
+
+Run this after the schema SQL. Replace `df-web-review-kit` if `VITE_REVIEW_PROJECT_ID` uses a different value.
+
+```sql
+alter table public.review_items enable row level security;
+alter table public.review_project_counters enable row level security;
+
+drop policy if exists review_items_sample_read on public.review_items;
+create policy review_items_sample_read
+  on public.review_items
+  for select
+  to anon
+  using (project_id = 'df-web-review-kit');
+
+drop policy if exists review_items_sample_insert on public.review_items;
+create policy review_items_sample_insert
+  on public.review_items
+  for insert
+  to anon
+  with check (project_id = 'df-web-review-kit');
+
+drop policy if exists review_items_sample_update on public.review_items;
+create policy review_items_sample_update
+  on public.review_items
+  for update
+  to anon
+  using (project_id = 'df-web-review-kit')
+  with check (project_id = 'df-web-review-kit');
+
+drop policy if exists review_items_sample_delete on public.review_items;
+create policy review_items_sample_delete
+  on public.review_items
+  for delete
+  to anon
+  using (project_id = 'df-web-review-kit');
+
+drop policy if exists review_project_counters_sample_read on public.review_project_counters;
+create policy review_project_counters_sample_read
+  on public.review_project_counters
+  for select
+  to anon
+  using (project_id = 'df-web-review-kit');
+
+drop policy if exists review_project_counters_sample_insert on public.review_project_counters;
+create policy review_project_counters_sample_insert
+  on public.review_project_counters
+  for insert
+  to anon
+  with check (project_id = 'df-web-review-kit');
+
+drop policy if exists review_project_counters_sample_update on public.review_project_counters;
+create policy review_project_counters_sample_update
+  on public.review_project_counters
+  for update
+  to anon
+  using (project_id = 'df-web-review-kit')
+  with check (project_id = 'df-web-review-kit');
+```
+
+## Adapter Behavior
+
+- `list`: reads by `project_id`, `source`, optional `route_key`, optional `status`.
+- `create`: discards local draft number and calls `create_review_item` for a canonical `review_number`.
+- `update`: updates row columns and the nested `item` JSON.
+- `remove`: deletes the row.
+
+Remote numbers are canonical. Local draft numbers can overlap between browsers and are not reused as remote numbers.
+
+## Presence
+
+Supabase Presence is optional session state. It is not QA item storage.
+
+Default topic:
+
+```txt
+review-presence-<projectId>
+```
+
+The adapter normalizes unsafe topic characters. `private=false` is enough for quick dev validation. `private=true` requires an authenticated Supabase session and Realtime authorization policies for `realtime.messages`.
+
+Use project-level channels instead of page-level channels so the sitemap can show who is on each page.
+
+## Security
+
+The RLS policies above are sample/dev policies. Anyone with the anon key and allowed `project_id` can create, update, and delete QA rows.
+
+For production, use one of these instead:
+
+- Supabase Auth plus project member table based RLS
+- Supabase Edge Function
+- host project backend proxy
+- private admin service
+
+Never put a `service_role` key in browser env.
+
+## Validation
+
+1. Open `/review?source=supabase`.
+2. Create a local item.
+3. Submit it to remote.
+4. Confirm the local draft disappears.
+5. Confirm remote list/get works.
+6. Change status.
+7. Delete the remote item.
+8. Create another remote item and confirm the number is not reused.
+9. If presence is enabled, open two browser tabs and confirm each user appears on the active page or sitemap.

package/docs/figma-overlay.md

@@ -0,0 +1,52 @@
+# 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.
+
+## User Flow
+
+- Open `/review`.
+- Click the settings button.
+- Enter a Figma token if the host helper requires one.
+- Click the Figma overlay button or press `f`.
+
+The token is stored in browser localStorage with this key:
+
+```txt
+figma-token
+```
+
+Treat this as a dev/debug convenience. Do not use it for private server tokens.
+
+## Availability
+
+The shell currently enables the Figma overlay on viewport presets whose `kind` is:
+
+- `mobile`
+- `wide`
+
+Other viewport kinds show the unavailable message.
+
+## Host Requirements
+
+The target page inside the iframe must already support the Figma helper.
+
+Expected behavior:
+
+- The target page reacts to a `KeyboardEvent` with `code: 'KeyF'`.
+- The target page mounts a visible Figma helper layer.
+- The helper root uses one of these selectors:
+  - `.helper-figma-root`
+  - `.helper-figma-loading-backdrop`
+
+The review shell uses those selectors only to detect whether the overlay is active.
+
+## Troubleshooting
+
+If the button does nothing:
+
+- Confirm the iframe target page is same-origin and can receive dispatched keyboard events.
+- 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 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.

package/docs/grid-overlay.md

@@ -0,0 +1,38 @@
+# Grid Overlay
+
+The grid overlay button in the review shell toggles a host-page layout/helper overlay. It is for visual alignment while reviewing pages.
+
+## User Flow
+
+- Open `/review`.
+- Click the grid button or press `g`.
+- The target page toggles its own grid/helper layer.
+
+## Host Requirements
+
+The target page inside the iframe must already support the grid helper.
+
+Expected behavior:
+
+- The target page reacts to a `KeyboardEvent` with `code: 'KeyG'`.
+- The target page toggles a visible grid/helper layer.
+- The active state is reflected by one of these:
+  - `document.body.classList.contains('is-help')`
+  - `.helper.onShow`
+
+The review shell uses those signals to keep the toolbar button state in sync.
+
+## Notes
+
+- The package does not prescribe the grid design.
+- The grid overlay is not persisted as QA data.
+- Use project-specific CSS/helper code in the host page when the grid differs by brand or design system.
+
+## Troubleshooting
+
+If the icon state does not change:
+
+- Confirm the target page helper is mounted.
+- Confirm it listens for `KeyG`.
+- Confirm it sets `body.is-help` or `.helper.onShow`.
+- Confirm the iframe is same-origin and keyboard events are not blocked.

package/docs/installation.md

@@ -1,30 +1,29 @@
 # Installation
 
-Host project에 `df-web-review-kit`를 설치하고 `/review` route에서 `mountReviewShell()`을 호출한다.
+Install `df-web-review-kit` in a host project and mount the review shell on a `/review` route.
 
-## Package install
+The default setup is local-only. Remote DB and presence are optional adapters.
 
-NPM package로 사용할 때:
+## Package Install
 
 ```bash
 pnpm add @designfever/web-review-kit react react-dom
 ```
 
-Supabase remote/presence를 쓰면 host project에 Supabase client도 설치한다.
+Supabase is optional. Install it only in host projects that use the Supabase adapter.
 
 ```bash
 pnpm add @supabase/supabase-js
 ```
 
-Lexus repo 안에서 검증할 때는 file dependency를 사용한다.
+## Vite Route
 
-```json
-"@designfever/web-review-kit": "file:packages/df-web-review-kit"
-```
-
-## Vite route
+Create a review entry such as:
 
-Vite project에서는 `page/review/index.html`과 `page/review/index.tsx` 같은 review entry를 만든다.
+```txt
+page/review/index.html
+page/review/index.tsx
+```
 
 Minimal `index.html`:
 
@@ -33,7 +32,7 @@ Minimal `index.html`:
 <script type="module" src="./index.tsx"></script>
 ```
 
-Minimal `index.tsx`:
+Minimal local-only `index.tsx`:
 
 ```tsx
 import {
@@ -46,6 +45,8 @@ import {
 } from '@designfever/web-review-kit';
 
 const REVIEW_PROJECT_ID = 'my-project';
+const REVIEW_PATH_PREFIX = '/review';
+
 const local = localAdapter({
   storageKey: `${REVIEW_PROJECT_ID}-review-items`,
 });
@@ -69,13 +70,13 @@ mountReviewShell({
       remove: (id) => local.remove(id),
     },
   ],
-  reviewPathPrefix: '/review',
+  reviewPathPrefix: REVIEW_PATH_PREFIX,
 });
 ```
 
-## Supabase remote example
+## Supabase Adapter
 
-Supabase를 붙일 때는 host project에서 client를 만들고 package adapter에 주입한다.
+Host projects that choose Supabase create the client themselves and pass it into the package adapter.
 
 ```tsx
 import {
@@ -93,7 +94,7 @@ import {
 } from '@designfever/web-review-kit';
 import { createClient } from '@supabase/supabase-js';
 
-const REVIEW_PROJECT_ID = 'lexus-official-v2026';
+const REVIEW_PROJECT_ID = 'my-project';
 const REVIEW_PATH_PREFIX = '/review';
 
 const local = localAdapter({
@@ -157,13 +158,35 @@ const presence = supabaseClient
       localPresence
     )
   : localPresence;
+
+mountReviewShell({
+  projectId: REVIEW_PROJECT_ID,
+  pages,
+  adapters,
+  presence,
+  reviewPathPrefix: REVIEW_PATH_PREFIX,
+});
 ```
 
-그 다음 `mountReviewShell({ adapters, presence, ... })`에 넘긴다.
+See [DB setup](db-setup.md) before enabling Supabase in a shared environment.
+
+## 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.
+
+The sample explains the main interfaces:
+
+- `ReviewItem`: the full QA payload to persist as structured JSON.
+- `ReviewItemQuery`: filters used by page lists and sitemap counts.
+- `WebReviewKitAdapter`: core CRUD contract.
+- `ReviewShellAdapter`: React shell wiring for source labels, write modes, status updates, and delete actions.
+
+Private keys, admin credentials, canonical numbering, and permission checks should stay in your backend, not in browser code.
 
 ## Environment
 
 ```env
+VITE_REVIEW_PROJECT_ID=df-web-review-kit
 VITE_REVIEW_SUPABASE_URL=https://your-project.supabase.co
 VITE_REVIEW_SUPABASE_ANON_KEY=
 VITE_REVIEW_SUPABASE_TABLE=review_items
@@ -172,13 +195,13 @@ VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE=false
 
 Rules:
 
-- browser env에는 Supabase `anon` key만 넣는다.
-- `service_role` key는 절대 browser env에 넣지 않는다.
-- package는 Supabase dependency를 직접 만들지 않는다. host project가 `createClient()`를 호출한다.
+- Browser env uses a Supabase `anon` key only.
+- Never expose `service_role` in browser env.
+- OpenClaw/operator secrets stay outside the host browser and outside this package.
 
-## Viewport preset
+## Viewport Presets
 
-Project별 design width가 다르면 `presets`를 넘긴다.
+Pass `presets` when a project has custom design widths.
 
 ```tsx
 mountReviewShell({
@@ -194,29 +217,41 @@ mountReviewShell({
 });
 ```
 
-## Development commands
-
-Lexus repo 기준:
+## Local Dev Harness
 
 ```bash
 pnpm dev:review
-pnpm review-kit:typecheck
-pnpm typecheck:review
-pnpm review-kit:build
-pnpm build:review
 ```
 
-Package source를 수정하면 `pnpm review-kit:build`로 `dist`를 갱신한다.
+Open `http://127.0.0.1:5177/review/`.
+
+Fixture pages:
+
+- `/`: note, area, and DOM marker creation
+- `/components/`: controls and panel spacing
+- `/long-form/`: scroll and anchor restore
+
+## Checks
+
+Package repo:
+
+```bash
+pnpm typecheck
+pnpm build
+pnpm typecheck:dev
+pnpm build:dev
+```
+
+Host repo:
 
-## Publish checklist
+```bash
+pnpm typecheck
+pnpm build
+```
 
-0.1 package 배포 전 확인:
+Manual smoke:
 
-- `packages/df-web-review-kit/package.json`의 `files`에 `dist`, `src`, `docs`, `README.md` 포함
-- `pnpm review-kit:typecheck`
-- `pnpm review-kit:build`
-- local source에서 note/dom/area 생성 확인
-- local item을 remote로 등록하면 local draft 삭제 확인
-- remote source에서 status update/delete 확인
-- `/review?source=supabase&target=...&item=...` restore 확인
-- Supabase `reviewNumber`가 삭제 후 재사용되지 않는지 확인
+1. Open `/review`.
+2. Create local note, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designfever/web-review-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Designfever web page review overlay toolkit.",
   "license": "UNLICENSED",
@@ -41,21 +41,26 @@
   "scripts": {
     "build": "tsup src/index.ts src/react-shell.tsx --format esm,cjs --dts --sourcemap --clean --external react --external react-dom --external react/jsx-runtime",
     "dev": "tsup src/index.ts src/react-shell.tsx --format esm,cjs --dts --sourcemap --watch --external react --external react-dom --external react/jsx-runtime",
+    "dev:review": "vite --config dev/vite.config.ts",
+    "build:dev": "vite build --config dev/vite.config.ts",
     "prepare": "pnpm build",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "typecheck:dev": "tsc --noEmit -p tsconfig.dev.json"
   },
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18"
   },
   "devDependencies": {
+    "@supabase/supabase-js": "^2.108.2",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "lucide-react": "^1.20.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "tsup": "^8.3.6",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.2",
+    "vite": "^8.0.8"
   },
   "packageManager": "pnpm@9.0.0"
 }