@designfever/web-review-kit 0.6.0 → 0.7.1

package/.env.sample

@@ -0,0 +1,32 @@
+# df-web-review-kit host project env sample
+# Copy this file into the host project as `.env.local`.
+# Vite exposes `VITE_*` values to browser code, so keep secrets out of here.
+
+# Review project id. Used for storage keys, remote item filtering, and presence.
+VITE_REVIEW_PROJECT_ID=my-project
+
+# Optional default reviewer id. Settings localStorage user-id still wins.
+VITE_REVIEW_USER_ID=
+
+# Optional server/dev-only Figma image rendering token.
+# This must stay in the dev/server process env. Do not expose it as VITE_*.
+FIGMA_TOKEN=
+
+# Optional Supabase remote adapter and presence.
+# Leave URL/key empty for local-only review.
+VITE_REVIEW_SUPABASE_URL=
+VITE_REVIEW_SUPABASE_ANON_KEY=
+VITE_REVIEW_SUPABASE_TABLE=review_items
+VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE=false
+
+# Optional source opening / Source Tree.
+# Set this when source hints store relative paths. Absolute source paths can
+# open without it.
+VITE_REVIEW_SOURCE_ROOT=/absolute/path/to/project
+
+# Supported values: vscode, cursor, webstorm, custom.
+VITE_REVIEW_SOURCE_EDITOR=cursor
+
+# Required only when VITE_REVIEW_SOURCE_EDITOR=custom.
+# Supported placeholders: {path}, {encodedPath}, {line}, {column}.
+VITE_REVIEW_SOURCE_URL_TEMPLATE=

package/README.md

@@ -21,12 +21,14 @@ This package does not own internal operator tools, private admin keys, or produc
 ## Docs
 
 - [Installation](docs/installation.md): install the package and mount `/review`.
+- [.env.sample](.env.sample): copyable host project env template for local, Supabase, and source opening.
+- [Adapter boundaries](docs/adapters.md): QA adapter vs Figma image store responsibilities.
 - [Custom adapter sample](docs/adaptor.sample.ts): starting point for host-owned remote adapters.
 - [DB setup](docs/db-setup.md): optional Supabase `review_items` setup, RLS, presence notes, and validation.
 - [Architecture and runtime logic](docs/architecture.md): core runtime, React shell, coordinate, anchor, and extension boundaries.
 - [Figma overlay](docs/figma-overlay.md): how the shell toggles a host Figma overlay.
 - [Grid overlay](docs/grid-overlay.md): how the shell toggles a host grid/helper overlay.
-- [Release notes 0.6.0](docs/release-notes-0.6.0.md): latest shell/source tree changes and validation notes.
+- [Release notes 0.7.0](docs/release-notes-0.7.0.md): latest Figma image, QA field, and remote adapter loading changes.
 
 ## Quick Start
 
@@ -46,7 +48,7 @@ import {
   localAdapter,
 } from '@designfever/web-review-kit';
 
-const projectId = 'my-project';
+const projectId = import.meta.env.VITE_REVIEW_PROJECT_ID || 'my-project';
 const local = localAdapter({
   storageKey: `${projectId}-review-items`,
 });
@@ -62,8 +64,16 @@ mountReviewShell({
       get: (id) => local.get(id),
       list: (query) => local.list(query),
       create: (item) => local.create(item),
+      fields: { title: true },
       statusOptions: REVIEW_WORKFLOW_STATUS_OPTIONS,
       updateStatus: ({ id, status }) => local.update(id, { status }),
+      assigneeTitle: 'Assignee',
+      assigneeOptions: [
+        { value: 'planning', label: 'Planning' },
+        { value: 'frontend', label: 'Frontend' },
+      ],
+      updateAssignee: ({ id, assigneeId, assigneeName }) =>
+        local.update(id, { assigneeId, assigneeName }),
       syncSubmission: ({ id, patch }) => local.update(id, patch),
       remove: (id) => local.remove(id),
     },
@@ -72,21 +82,36 @@ mountReviewShell({
 });
 ```
 
-See [Installation](docs/installation.md) for route files, Supabase adapter wiring, viewport presets, and verification commands.
+See [Installation](docs/installation.md) for route files, `.env.sample`, Supabase adapter wiring, viewport presets, and verification commands.
 
-## Optional Supabase Env
+## Environment
 
-Only host projects that choose the Supabase adapter need these values.
+Copy [.env.sample](.env.sample) into the host project as `.env.local`, then fill only the values that project needs.
+
+Local-only review needs only `VITE_REVIEW_PROJECT_ID`.
+
+```env
+VITE_REVIEW_PROJECT_ID=my-project
+```
+
+Only host projects that choose the Supabase adapter need Supabase values.
 
 ```env
-VITE_REVIEW_PROJECT_ID=df-web-review-kit
-VITE_REVIEW_SUPABASE_URL=https://your-project.supabase.co
+VITE_REVIEW_SUPABASE_URL=
 VITE_REVIEW_SUPABASE_ANON_KEY=
 VITE_REVIEW_SUPABASE_TABLE=review_items
 VITE_REVIEW_SUPABASE_PRESENCE_PRIVATE=false
 ```
 
-Browser env must use a Supabase `anon` key only. Do not put `service_role` or OpenClaw operator secrets in a host browser env or in this package.
+Source opening / Source Tree can also be configured from env.
+
+```env
+VITE_REVIEW_SOURCE_ROOT=/absolute/path/to/project
+VITE_REVIEW_SOURCE_EDITOR=cursor
+VITE_REVIEW_SOURCE_URL_TEMPLATE=
+```
+
+Browser env must use a Supabase `anon` key only. Do not put `service_role`, OpenClaw operator secrets, or private admin keys in a host browser env or in this package.
 
 ## Public Imports
 
@@ -133,14 +158,14 @@ export default defineConfig({
 
 When source hints are available, hold `Option` over the review target to inspect source candidates from the DOM ancestry. Click the target to pin the candidate list, then choose a file to open. The side rail can also open a Source Tree panel with section/source/data links, live box metrics, text/font/media metadata, and class tags. DOM QA cards show a source action when the saved item has source hints. Source Tree filter/options, QA panel mode, and QA status filter are stored in browser localStorage. Keep these plugins disabled for production builds because they write source paths into the DOM.
 
+In Vite/ESM hosts, source opening reads `VITE_REVIEW_SOURCE_ROOT`, `VITE_REVIEW_SOURCE_EDITOR`, and `VITE_REVIEW_SOURCE_URL_TEMPLATE` from the host env. Env values override matching `sourceRoot`, `sourceInspector.editor`, and `sourceInspector.urlTemplate` init values; init values still work as a fallback for existing projects and CommonJS consumers. Use `VITE_REVIEW_SOURCE_URL_TEMPLATE` only with `VITE_REVIEW_SOURCE_EDITOR=custom`; the template supports `{path}`, `{encodedPath}`, `{line}`, and `{column}`.
+
 ```tsx
 mountReviewShell({
   projectId: REVIEW_PROJECT_ID,
   pages,
   adapters,
-  sourceRoot: import.meta.env.VITE_REVIEW_SOURCE_ROOT,
   sourceInspector: {
-    editor: 'cursor', // 'vscode' | 'cursor' | 'webstorm' | 'custom'
     maxDepth: 9,
     hoverOutline: true,
     includePlacer: false,