@designfever/web-review-kit 0.1.0 → 0.3.0

package/docs/adaptor.sample.ts

@@ -0,0 +1,182 @@
+import {
+  REVIEW_WORKFLOW_STATUS_OPTIONS,
+  type ReviewItem,
+  type ReviewItemQuery,
+  type ReviewItemStatus,
+  type ReviewSource,
+  type WebReviewKitAdapter,
+} from '@designfever/web-review-kit';
+import type {
+  ReviewShellAdapter,
+} from '@designfever/web-review-kit/react-shell';
+
+type RemoteReviewAdapterOptions = {
+  baseUrl: string;
+  projectId: string;
+  source?: ReviewSource;
+  token?: string;
+};
+
+type RemoteReviewItemResponse = ReviewItem | { item: ReviewItem };
+
+/*
+ * 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.
+ *
+ * ReviewItemQuery is used by the shell for current-page lists and sitemap counts.
+ * A remote backend should support at least projectId, routeKey, status, source,
+ * and pageId when the host project needs page-level grouping.
+ *
+ * Keep private tokens, admin keys, numbering, and permission checks in your
+ * backend. Browser code should only call browser-safe endpoints.
+ */
+export function createRemoteReviewAdapter(
+  options: RemoteReviewAdapterOptions
+): WebReviewKitAdapter {
+  const source = options.source ?? 'remote';
+
+  return {
+    async get(id) {
+      return readReviewItem(
+        await requestJson<RemoteReviewItemResponse>(
+          `/review-items/${encodeURIComponent(id)}`,
+          options
+        )
+      );
+    },
+
+    async list(query) {
+      const rows = await requestJson<RemoteReviewItemResponse[]>(
+        `/review-items?${createListParams(query, source).toString()}`,
+        options
+      );
+
+      return rows.map(readReviewItem);
+    },
+
+    async create(item) {
+      return readReviewItem(
+        await requestJson<RemoteReviewItemResponse>('/review-items', options, {
+          method: 'POST',
+          body: JSON.stringify({
+            project_id: options.projectId,
+            source,
+            item,
+          }),
+        })
+      );
+    },
+
+    async update(id, patch) {
+      return readReviewItem(
+        await requestJson<RemoteReviewItemResponse>(
+          `/review-items/${encodeURIComponent(id)}`,
+          options,
+          {
+            method: 'PATCH',
+            body: JSON.stringify({ patch }),
+          }
+        )
+      );
+    },
+
+    async remove(id) {
+      await requestJson<void>(
+        `/review-items/${encodeURIComponent(id)}`,
+        options,
+        { method: 'DELETE' }
+      );
+    },
+  };
+}
+
+/*
+ * ReviewShellAdapter is the React shell wiring.
+ *
+ * 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'].
+ * updateStatus drives the status buttons in the QA panel.
+ * remove enables delete actions for this source.
+ */
+export function createRemoteReviewShellAdapter(
+  options: RemoteReviewAdapterOptions
+): ReviewShellAdapter {
+  const adapter = createRemoteReviewAdapter(options);
+
+  return {
+    label: options.source ?? 'remote',
+    get: (id) => adapter.get(id),
+    list: (query) => adapter.list(query),
+    create: (item) => adapter.create(item),
+    canWrite: true,
+    statusOptions: REVIEW_WORKFLOW_STATUS_OPTIONS,
+    updateStatus: ({ id, status }) =>
+      adapter.update(id, { status: normalizeRemoteStatus(status) }),
+    remove: (id) => adapter.remove(id),
+  };
+}
+
+function appendParam(
+  params: URLSearchParams,
+  key: string,
+  value: string | undefined
+) {
+  if (value) params.set(key, value);
+}
+
+function createListParams(query: ReviewItemQuery, source: ReviewSource) {
+  const params = new URLSearchParams();
+  params.set('project_id', query.projectId);
+  params.set('source', query.source ?? source);
+  appendParam(params, 'page_id', query.pageId);
+  appendParam(params, 'route_key', query.routeKey ?? query.normalizedPath);
+  appendParam(params, 'status', query.status);
+  return params;
+}
+
+async function requestJson<T>(
+  path: string,
+  options: RemoteReviewAdapterOptions,
+  init: RequestInit = {}
+) {
+  const url = new URL(path, ensureTrailingSlash(options.baseUrl));
+  const headers = new Headers(init.headers);
+
+  headers.set('Accept', 'application/json');
+  if (init.body && !headers.has('Content-Type')) {
+    headers.set('Content-Type', 'application/json');
+  }
+  if (options.token) {
+    headers.set('Authorization', `Bearer ${options.token}`);
+  }
+
+  const response = await fetch(url, {
+    ...init,
+    headers,
+    credentials: 'include',
+  });
+
+  if (!response.ok) {
+    throw new Error(`remote review adapter request failed: ${response.status}`);
+  }
+  if (response.status === 204) return undefined as T;
+
+  return response.json() as Promise<T>;
+}
+
+function readReviewItem(response: RemoteReviewItemResponse) {
+  return 'item' in response ? response.item : response;
+}
+
+function ensureTrailingSlash(value: string) {
+  return value.endsWith('/') ? value : `${value}/`;
+}
+
+function normalizeRemoteStatus(status: ReviewItemStatus) {
+  if (status === 'open') return 'todo';
+  if (status === 'resolved') return 'done';
+  return status;
+}

package/docs/architecture.md

@@ -0,0 +1,125 @@
+# Architecture and Runtime Logic
+
+`df-web-review-kit` has two main runtime surfaces:
+
+- `core`: a vanilla DOM runtime that can mount review overlays on a same-origin target page.
+- `react-shell`: a React review app that hosts pages in an iframe and controls the core runtime.
+
+This split keeps the target-page overlay independent from React while allowing the review shell to provide richer workflow UI.
+
+## High-Level Flow
+
+```txt
+React shell
+  -> renders topbar, QA panel, iframe, ruler, settings
+  -> creates core runtime with createWebReviewKit()
+  -> passes iframe target geometry through getReviewKitTarget()
+
+Core runtime
+  -> mounts a shadow DOM overlay
+  -> handles note/area/DOM selection
+  -> creates markers and highlights over the target viewport
+  -> persists ReviewItem records through the configured adapter
+```
+
+In the React shell, core is created with:
+
+```ts
+createWebReviewKit({
+  target: () => getReviewKitTarget({ frameScrollRef, iframeRef }),
+  ui: {
+    panel: false,
+  },
+});
+```
+
+`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.
+
+## 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.
+- `dom.anchor.ts`: selector candidate generation, anchor rebinding, text fingerprint matching.
+- `geometry.ts`: target-space and host-space coordinate conversion.
+- `review/item.ts`: marker, selection, highlight, and fallback resolution.
+- `review/scope.ts`: viewport scope grouping and numbering.
+- `review/format.ts`: compact item/draft metadata labels.
+- `scroll.ts`: scroll restore helpers.
+- `location.ts`: public URL and route key helpers.
+
+## Coordinate Spaces
+
+Core uses two coordinate spaces:
+
+- **Target space**: coordinates relative to the iframe or target page viewport.
+- **Host space**: coordinates relative to the review shell page that contains the iframe.
+
+Persisted review data uses target-space viewport values plus optional anchor-relative values. Rendering converts target-space markers and selections into host-space overlay positions.
+
+## Anchor and Restore Logic
+
+When a user creates a DOM or area item, core tries to capture:
+
+- an explicit configured anchor such as `data-qa-id`
+- a meaningful `id`
+- a meaningful class
+- a DOM path fallback
+- a short text fingerprint
+
+Restore prefers anchor-relative coordinates because absolute viewport coordinates drift after layout changes. If an anchor cannot be resolved, core falls back to the original viewport coordinate adjusted by saved scroll position.
+
+## Adapter Boundary
+
+Core never owns persistence storage directly. It only calls the configured `WebReviewKitAdapter`:
+
+- `list`
+- `get`
+- `create`
+- `update`
+- `remove`
+
+The default local adapter is for draft/local review work. Supabase is optional host wiring, not a required backend.
+
+## React Shell Boundary
+
+`react-shell` owns reviewer workflow UI:
+
+- iframe target routing
+- QA list and item actions
+- viewport presets
+- sitemap modal
+- settings modal
+- ruler UI
+- presence UI
+- host overlay toggles such as grid and Figma
+
+React shell should call the core controller instead of duplicating target overlay logic.
+
+## Figma Overlay Direction
+
+Figma overlay work should stay outside core unless it needs target runtime primitives.
+
+Preferred direction:
+
+```txt
+src/react-shell/figma/
+  controls.tsx
+  sync.ts
+  overlay.state.ts
+
+src/figma/
+  matching.ts
+  types.ts
+```
+
+Shared coordinate math can reuse `core/geometry.ts` or move to a future shared module if both core and Figma need it heavily.
+
+Avoid turning `core` into a feature bucket. Core should stay focused on target review runtime behavior.
+
+## Extension Rules
+
+- Put target overlay primitives in `core`.
+- Put reviewer workflow UI in `react-shell`.
+- Put feature-specific integration logic, such as Figma matching, in its own module.
+- Keep adapter contracts storage-agnostic.
+- Prefer anchor-relative data for anything that must survive layout changes.

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.