@designfever/web-review-kit 0.1.0 → 0.2.0

package/dist/{types-D_mNjOHx.d.cts → types-NiCp9JJQ.d.cts}

@@ -3,7 +3,7 @@ type ReviewItemScope = 'mobile' | 'tablet' | 'desktop' | 'wide' | 'dom';
 type ReviewWorkflowStatus = 'todo' | 'doing' | 'review' | 'hold' | 'done';
 type ReviewItemStatus = 'open' | 'resolved' | ReviewWorkflowStatus;
 type ReviewMode = 'idle' | 'note' | 'element' | 'area';
-type ReviewSource = 'local' | 'df-sheet' | 'supabase' | (string & {});
+type ReviewSource = 'local' | 'supabase' | (string & {});
 type ReviewSubmitStatus = 'idle' | 'submitting' | 'submitted' | 'failed';
 type ReviewViewportScope = Exclude<ReviewItemScope, 'dom'>;
 type DomAnchorStrategy = 'configured-attribute' | 'id' | 'class' | 'dom-path';
@@ -62,6 +62,7 @@ interface ReviewItem {
     kind: ReviewItemKind;
     title?: string;
     comment: string;
+    createdBy?: string;
     status: ReviewItemStatus;
     viewport: ViewportSize;
     devicePixelRatio?: number;
@@ -98,17 +99,6 @@ interface WebReviewKitAdapter {
 interface LocalAdapterOptions {
     storageKey?: string;
 }
-interface DfSheetAdapterOptions {
-    baseUrl?: string;
-    projectId: string;
-    pageId: string;
-    reviewProjectId?: string;
-    reviewPathPrefix?: string;
-    source?: string;
-    issueType?: string;
-    priority?: string;
-    token?: string;
-}
 interface SupabaseReviewClient {
     from(table: string): any;
     rpc?: (fn: string, args?: Record<string, unknown>) => any;
@@ -132,11 +122,12 @@ interface NumberedReviewItem {
     item: ReviewItem;
     scope: ReviewItemScope;
     label: string;
-    number: number;
+    number?: number;
     displayLabel: string;
 }
 interface WebReviewKitOptions {
     projectId: string;
+    userId?: string;
     adapter?: WebReviewKitAdapter;
     target?: WebReviewKitTarget | (() => WebReviewKitTarget | undefined);
     viewports?: {
@@ -150,6 +141,7 @@ interface WebReviewKitOptions {
         attribute?: string;
     };
     onRestoreItem?: (item: ReviewItem) => void | Promise<void>;
+    onCreateItem?: (item: ReviewItem) => void | Promise<void>;
     onItemsChange?: (items: ReviewItem[]) => void;
     onModeChange?: (mode: ReviewMode) => void;
     ui?: {
@@ -180,4 +172,4 @@ interface WebReviewKitTarget {
     getOverlayRect?: () => Pick<DOMRect, 'left' | 'top' | 'width' | 'height'>;
 }
 
-export type { DfSheetAdapterOptions as D, LocalAdapterOptions as L, NumberedReviewItem as N, ReviewWorkflowStatus as R, SupabaseReviewAdapterOptions as S, ViewportSize as V, WebReviewKitAdapter as W, ReviewItemStatus as a, WebReviewKitOptions as b, WebReviewKitController as c, ReviewViewportPreset as d, ReviewItem as e, ReviewItemScope as f, DomAnchor as g, DomAnchorCandidate as h, DomAnchorStrategy as i, DomSourceHint as j, RelativeSelection as k, ReviewItemKind as l, ReviewItemQuery as m, ReviewMarker as n, ReviewMode as o, ReviewPoint as p, ReviewRulerConfig as q, ReviewSelection as r, ReviewSource as s, ReviewSubmitStatus as t, ReviewViewportScope as u, SupabaseReviewClient as v, WebReviewKitTarget as w };
+export type { DomAnchor as D, LocalAdapterOptions as L, NumberedReviewItem as N, ReviewWorkflowStatus as R, SupabaseReviewAdapterOptions as S, ViewportSize as V, WebReviewKitAdapter as W, ReviewItemStatus as a, WebReviewKitOptions as b, WebReviewKitController as c, ReviewViewportPreset as d, ReviewItem as e, ReviewItemScope as f, DomAnchorCandidate as g, DomAnchorStrategy as h, DomSourceHint as i, RelativeSelection as j, ReviewItemKind as k, ReviewItemQuery as l, ReviewMarker as m, ReviewMode as n, ReviewPoint as o, ReviewRulerConfig as p, ReviewSelection as q, ReviewSource as r, ReviewSubmitStatus as s, ReviewViewportScope as t, SupabaseReviewClient as u, WebReviewKitTarget as v };

package/dist/{types-D_mNjOHx.d.ts → types-NiCp9JJQ.d.ts}

@@ -3,7 +3,7 @@ type ReviewItemScope = 'mobile' | 'tablet' | 'desktop' | 'wide' | 'dom';
 type ReviewWorkflowStatus = 'todo' | 'doing' | 'review' | 'hold' | 'done';
 type ReviewItemStatus = 'open' | 'resolved' | ReviewWorkflowStatus;
 type ReviewMode = 'idle' | 'note' | 'element' | 'area';
-type ReviewSource = 'local' | 'df-sheet' | 'supabase' | (string & {});
+type ReviewSource = 'local' | 'supabase' | (string & {});
 type ReviewSubmitStatus = 'idle' | 'submitting' | 'submitted' | 'failed';
 type ReviewViewportScope = Exclude<ReviewItemScope, 'dom'>;
 type DomAnchorStrategy = 'configured-attribute' | 'id' | 'class' | 'dom-path';
@@ -62,6 +62,7 @@ interface ReviewItem {
     kind: ReviewItemKind;
     title?: string;
     comment: string;
+    createdBy?: string;
     status: ReviewItemStatus;
     viewport: ViewportSize;
     devicePixelRatio?: number;
@@ -98,17 +99,6 @@ interface WebReviewKitAdapter {
 interface LocalAdapterOptions {
     storageKey?: string;
 }
-interface DfSheetAdapterOptions {
-    baseUrl?: string;
-    projectId: string;
-    pageId: string;
-    reviewProjectId?: string;
-    reviewPathPrefix?: string;
-    source?: string;
-    issueType?: string;
-    priority?: string;
-    token?: string;
-}
 interface SupabaseReviewClient {
     from(table: string): any;
     rpc?: (fn: string, args?: Record<string, unknown>) => any;
@@ -132,11 +122,12 @@ interface NumberedReviewItem {
     item: ReviewItem;
     scope: ReviewItemScope;
     label: string;
-    number: number;
+    number?: number;
     displayLabel: string;
 }
 interface WebReviewKitOptions {
     projectId: string;
+    userId?: string;
     adapter?: WebReviewKitAdapter;
     target?: WebReviewKitTarget | (() => WebReviewKitTarget | undefined);
     viewports?: {
@@ -150,6 +141,7 @@ interface WebReviewKitOptions {
         attribute?: string;
     };
     onRestoreItem?: (item: ReviewItem) => void | Promise<void>;
+    onCreateItem?: (item: ReviewItem) => void | Promise<void>;
     onItemsChange?: (items: ReviewItem[]) => void;
     onModeChange?: (mode: ReviewMode) => void;
     ui?: {
@@ -180,4 +172,4 @@ interface WebReviewKitTarget {
     getOverlayRect?: () => Pick<DOMRect, 'left' | 'top' | 'width' | 'height'>;
 }
 
-export type { DfSheetAdapterOptions as D, LocalAdapterOptions as L, NumberedReviewItem as N, ReviewWorkflowStatus as R, SupabaseReviewAdapterOptions as S, ViewportSize as V, WebReviewKitAdapter as W, ReviewItemStatus as a, WebReviewKitOptions as b, WebReviewKitController as c, ReviewViewportPreset as d, ReviewItem as e, ReviewItemScope as f, DomAnchor as g, DomAnchorCandidate as h, DomAnchorStrategy as i, DomSourceHint as j, RelativeSelection as k, ReviewItemKind as l, ReviewItemQuery as m, ReviewMarker as n, ReviewMode as o, ReviewPoint as p, ReviewRulerConfig as q, ReviewSelection as r, ReviewSource as s, ReviewSubmitStatus as t, ReviewViewportScope as u, SupabaseReviewClient as v, WebReviewKitTarget as w };
+export type { DomAnchor as D, LocalAdapterOptions as L, NumberedReviewItem as N, ReviewWorkflowStatus as R, SupabaseReviewAdapterOptions as S, ViewportSize as V, WebReviewKitAdapter as W, ReviewItemStatus as a, WebReviewKitOptions as b, WebReviewKitController as c, ReviewViewportPreset as d, ReviewItem as e, ReviewItemScope as f, DomAnchorCandidate as g, DomAnchorStrategy as h, DomSourceHint as i, RelativeSelection as j, ReviewItemKind as k, ReviewItemQuery as l, ReviewMarker as m, ReviewMode as n, ReviewPoint as o, ReviewRulerConfig as p, ReviewSelection as q, ReviewSource as r, ReviewSubmitStatus as s, ReviewViewportScope as t, SupabaseReviewClient as u, WebReviewKitTarget as v };

package/docs/README.md

@@ -1,37 +1,28 @@
 # df-web-review-kit docs
 
-현재 문서의 읽는 순서:
+Public docs are intentionally small. Keep implementation history, handoff notes, and internal operator decisions out of this package documentation.
 
-1. [Concept](concept.md)
-2. [Installation](installation.md)
-3. [Supabase setup](supabase.md)
-4. [Supabase review item SQL](supabase-review-items.md)
-5. [Supabase presence](supabase-presence.md)
-6. [Adapter handoff](adapter-handoff.md)
-7. [df-sheet next](df-sheet-next.md)
-8. [Review feedback 2026-06-20](review-feedback-2026-06-20.md)
-9. [Stabilize UI work guide](stabilize-ui-work-guide.md)
-10. [Smoke baseline 2026-06-20](smoke-baseline-2026-06-20.md)
-11. [Package split checkpoint](package-split-checkpoint.md)
+## Read This Order
 
-## 문서 역할
+1. [Installation](installation.md)
+2. [Custom adapter sample](adaptor.sample.ts)
+3. [DB setup](db-setup.md)
+4. [Architecture and runtime logic](architecture.md)
+5. [Figma overlay](figma-overlay.md)
+6. [Grid overlay](grid-overlay.md)
 
-- `concept.md`: 왜 이 package가 있고 어떤 문제를 해결하는지.
-- `installation.md`: host project에 설치하고 `/review` route에 붙이는 방법.
-- `supabase.md`: Supabase를 remote QA 저장소와 presence backend로 연결하는 방법.
-- `supabase-review-items.md`: 실제 table/RPC/RLS SQL.
-- `supabase-presence.md`: Supabase Realtime Presence adapter 구조.
-- `adapter-handoff.md`: package repo로 옮길 때 필요한 adapter contract 정리.
-- `df-sheet-next.md`: df-sheet를 source of record로 쓸 때 필요한 제품/API 방향.
-- `review-feedback-2026-06-20.md`: 빵빵/팡팡/오빵 package 리뷰 메모와 우선순위.
-- `stabilize-ui-work-guide.md`: anchor 안정화, UI token화, package split 전 작업 순서.
-- `smoke-baseline-2026-06-20.md`: 761 현재 기능 smoke 기준선 결과.
-- `package-split-checkpoint.md`: 765 package export/file/peer dependency와 host 소비 경계.
-- `initial-plan.md`: 초기 계획 기록. 현재 기준 문서가 아니다.
+## Document Roles
 
-## 현재 기준
+- `installation.md`: install the npm package, create the `/review` route, wire adapters, and run checks.
+- `adaptor.sample.ts`: copyable starting point for host-owned remote adapters.
+- `db-setup.md`: optional Supabase review item table/RPC/RLS/presence setup.
+- `architecture.md`: core/runtime, React shell, coordinate, anchor, and feature boundary notes.
+- `figma-overlay.md`: host requirements for the Figma overlay toggle.
+- `grid-overlay.md`: host requirements for the grid/helper overlay toggle.
 
-- `local`: 개인 draft 저장소.
-- `supabase`: 팀 공유 remote 저장소.
-- `df-sheet`: 나중에 issue workflow로 연결할 수 있는 remote destination.
-- local 번호는 개인 draft용이고, remote 번호는 remote source가 새로 발급하는 canonical 번호다.
+## Boundary
+
+- `local` is the default draft storage.
+- `supabase` is an optional adapter sample for users who configure their own backend.
+- `presence` is temporary session state, not QA item persistence.
+- `kuku` and operator keys belong to OpenClaw or a backend/admin service, not this public package.

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.