@artymclabin/qa-review 0.3.7 → 0.3.9

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.3.8 - 2026-08-09
+
+- BACK TO REVIEW IS AN UNDO, NOT A RESTART: the finish panel's "Back to review"
+  sent the reviewer to item 1. You press it having just finished, because of
+  something about the item you just judged, so on a forty-item board getting
+  back to where you were meant clicking Next thirty-nine times. It now opens the
+  LAST item of the round.
+- COLLECT SEVERAL REFERENCES FOR ONE PASTE: right-clicking "Copy ref" ADDS this
+  item's reference line to the ones already collected and puts the whole list on
+  the clipboard, so a sweep of a board can be pasted into a chat in one go. A
+  plain click still copies just this item, and also ends the collection, so
+  there is a way out of a half-built list. The button reports how many are
+  collected. Right-clicking the same item twice is idempotent.
+  It does NOT call navigator.clipboard.readText(): appending to "whatever is on
+  the clipboard" would need a permission Firefox never grants a page, and on a
+  grant it would happily append a password manager's payload or whatever the
+  reviewer copied a minute earlier. The list lives in the panel, so the button
+  can only ever append references it produced itself.
+
 ## 0.3.7 - 2026-07-30
 
 - MOBILE PREVIEW SCROLLS TO THE ITEM: the phone-frame iframe loaded each page

package/README.md

@@ -1,177 +1,177 @@
-# qa-review
-
-Interactive on-page QA review for React apps: a spotlight walkthrough overlay
-that steps a reviewer through the elements of a real rendered page
-(approve / reject / note / undo / design-variation picking), plus a durable
-server-side verdict ledger with a self-provisioning Postgres store.
-
-Built for "founder reviews the page element by element" workflows: the reviewer
-opens the live page, the overlay dims everything except the current item, and
-every verdict is persisted immediately - refreshes, storage wipes, and device
-switches never lose progress.
-
-## Features
-
-- **Spotlight walkthrough** - dims the page except the current `[data-qa]`
-  target; card shows title/subtitle + Approve/Reject/Prev/Next.
-- **Round-based review** - the set of actionable (not-yet-approved) items is
-  frozen at load with a fixed denominator ("1 of N"), so approved items never
-  re-appear mid-round.
-- **Durable verdict ledger** - verdicts are saved per item as you go
-  (localStorage cache + server ledger). No bulk reset exists; a single item is
-  re-queued by invalidating just it (`verdict: null`).
-- **Undo, Peek (3s clean-page view), element-picker notes, keyboard driving**
-  (A/R/arrows/U/Esc), draggable panel.
-- **Design variations** - an item can expose N live-swappable variants; the
-  chosen variant is recorded with the approval.
-- **Session snapshots** - optional "Save review to database" submit that stores
-  the full run (summary + per-item results) for auditability.
-- **BYO auth** - the server handlers take an `authorize(req)` callback; plug in
-  any gate (SSO, password, none for local tools). Fail-closed.
-- **Self-provisioning Postgres storage** - the adapter creates its own
-  `qa_review_*` tables on first use (versioned, advisory-locked). A `site`
-  scope column lets one database serve many installs.
-- **Cross-page journey** - an ordered multi-page review: finishing a page
-  navigates immediately to the next page with pending items (activation query
-  params survive the hop); a completion panel shows only when the whole
-  journey is clean.
-- **Task items** - selectorless items render as a centered card with an
-  optional action-link button, for visit-this-page checks and decisions.
-- **NOT-ALTERED poka-yoke** - every verdict stores a content fingerprint; a
-  re-shown rejected item whose content still hashes identical gets a
-  system-computed "NOT ALTERED since your rejection" badge.
-- **Device-split approvals** - items can require per-device sign-off
-  (PC/mobile); approved only when every required device approved. Plain
-  historical approvals are grandfathered as fully approved.
-- **Sub-highlights** - `highlightWords` marks specific words inside the
-  spotlighted element, replacing "where to look" prose.
-- **Codenames** - a deterministic two-word codename per item ("red-apple")
-  with a Copy-ref button and an exported resolver, so humans and agents can
-  reference items by name. Included in state GET responses.
-- **Minimize bubble** - the panel collapses to a draggable floating bubble
-  (mouse + touch); tap to restore.
-- **No CSS toolchain required** - the overlay injects its own stylesheet;
-  brand colors come from a small theme prop.
-
-## Install
-
-```bash
-npm install @artymclabin/qa-review
-# or
-pnpm add @artymclabin/qa-review
-```
-
-Install straight from git if you want an unreleased commit:
-
-```bash
-npm install github:ArtyMcLabin/qa-review
-```
-
-For CI environments without registry access, vendor a tarball:
-
-```bash
-# in this repo
-npm pack   # -> artymclabin-qa-review-<version>.tgz
-# in the consumer
-pnpm add ./vendor/artymclabin-qa-review-<version>.tgz
-```
-
-Peer dependencies: `react`, `react-dom`, `lucide-react`.
-
-## Quick start (Next.js App Router)
-
-### 1. Server: mount the handlers
-
-```ts
-// src/lib/qa-review.ts
-import { createQAReviewHandlers } from "@artymclabin/qa-review/server";
-
-export const qaHandlers = createQAReviewHandlers({
-  site: "example-site", // scope for this install (one DB can serve many)
-  authorize: async (req) => {
-    const user = await verifyMySession(req); // your gate; null -> 401
-    return user ? { reviewer: user.name, displayName: user.name } : null;
-  },
-});
-```
-
-```ts
-// src/app/api/qa/state/route.ts
-import { qaHandlers } from "@/lib/qa-review";
-export const runtime = "nodejs";
-export const dynamic = "force-dynamic";
-export const GET = qaHandlers.stateGET;
-export const POST = qaHandlers.statePOST;
-```
-
-Mount `submitPOST`, `sessionsGET`, and `accessGET` the same way on their own
-routes as needed.
-
-### 2. Database
-
-Set the connection string (any Postgres - local, Neon, Supabase, RDS):
-
-```bash
-QA_REVIEW_DATABASE_URL=postgresql://user:password@db.example.com/mydb
-```
-
-No migrations to write: on the first request the adapter provisions
-`qa_review_state` (the per-item ledger), `qa_review_sessions` (session
-snapshots), and `qa_review_migrations` (its own version bookkeeping).
-
-### 3. Client: mark targets and mount the overlay
-
-```tsx
-// Any element you want reviewed gets a stable [data-qa] anchor:
-<section data-qa="hero">...</section>
-```
-
-```tsx
-"use client";
-import { QAReviewOverlay } from "@artymclabin/qa-review";
-
-const ITEMS = [
-  { id: "hero", title: "Hero headline", selector: '[data-qa="hero"]' },
-  { id: "pricing", title: "Pricing table", sub: "Check the currency.", selector: '[data-qa="pricing"]' },
-];
-
-export function PageQA() {
-  return (
-    <QAReviewOverlay
-      items={ITEMS}
-      target="example-site:/pricing" // one ledger bucket per reviewed surface
-      gateParam="qaReview"           // omit if activation is gated upstream
-      submitUrl="/api/qa/submit"     // omit to hide the session-save button
-      theme={{ accent: "#ffde4d" }}
-    />
-  );
-}
-```
-
-## API sketch
-
-```ts
-// client
-import {
-  QAReviewOverlay, // the overlay component
-  createQAStore,   // per-target verdict store (localStorage + server mirror)
-  targetFromLocation, // ?target= override helper (E2E isolation)
-} from "@artymclabin/qa-review";
-
-// server
-import {
-  createQAReviewHandlers, // { stateGET, statePOST, submitPOST, sessionsGET, accessGET }
-  createPostgresStorage,  // default storage; implement QAReviewStorage to swap
-} from "@artymclabin/qa-review/server";
-```
-
-State endpoint semantics (the ledger):
-
-- `GET ?target=...` -> `{ ok, verdicts: { itemId: { verdict, note, variant } } }`
-- `POST { target, itemId, verdict | note | variant }` -> merge-upsert one item
-- `POST { target, itemId, verdict: null }` -> delete that one item
-  (re-queues it on the next round). There is deliberately **no reset-all**.
-
-## License
-
-MIT
+# qa-review
+
+Interactive on-page QA review for React apps: a spotlight walkthrough overlay
+that steps a reviewer through the elements of a real rendered page
+(approve / reject / note / undo / design-variation picking), plus a durable
+server-side verdict ledger with a self-provisioning Postgres store.
+
+Built for "founder reviews the page element by element" workflows: the reviewer
+opens the live page, the overlay dims everything except the current item, and
+every verdict is persisted immediately - refreshes, storage wipes, and device
+switches never lose progress.
+
+## Features
+
+- **Spotlight walkthrough** - dims the page except the current `[data-qa]`
+  target; card shows title/subtitle + Approve/Reject/Prev/Next.
+- **Round-based review** - the set of actionable (not-yet-approved) items is
+  frozen at load with a fixed denominator ("1 of N"), so approved items never
+  re-appear mid-round.
+- **Durable verdict ledger** - verdicts are saved per item as you go
+  (localStorage cache + server ledger). No bulk reset exists; a single item is
+  re-queued by invalidating just it (`verdict: null`).
+- **Undo, Peek (3s clean-page view), element-picker notes, keyboard driving**
+  (A/R/arrows/U/Esc), draggable panel.
+- **Design variations** - an item can expose N live-swappable variants; the
+  chosen variant is recorded with the approval.
+- **Session snapshots** - optional "Save review to database" submit that stores
+  the full run (summary + per-item results) for auditability.
+- **BYO auth** - the server handlers take an `authorize(req)` callback; plug in
+  any gate (SSO, password, none for local tools). Fail-closed.
+- **Self-provisioning Postgres storage** - the adapter creates its own
+  `qa_review_*` tables on first use (versioned, advisory-locked). A `site`
+  scope column lets one database serve many installs.
+- **Cross-page journey** - an ordered multi-page review: finishing a page
+  navigates immediately to the next page with pending items (activation query
+  params survive the hop); a completion panel shows only when the whole
+  journey is clean.
+- **Task items** - selectorless items render as a centered card with an
+  optional action-link button, for visit-this-page checks and decisions.
+- **NOT-ALTERED poka-yoke** - every verdict stores a content fingerprint; a
+  re-shown rejected item whose content still hashes identical gets a
+  system-computed "NOT ALTERED since your rejection" badge.
+- **Device-split approvals** - items can require per-device sign-off
+  (PC/mobile); approved only when every required device approved. Plain
+  historical approvals are grandfathered as fully approved.
+- **Sub-highlights** - `highlightWords` marks specific words inside the
+  spotlighted element, replacing "where to look" prose.
+- **Codenames** - a deterministic two-word codename per item ("red-apple")
+  with a Copy-ref button and an exported resolver, so humans and agents can
+  reference items by name. Included in state GET responses.
+- **Minimize bubble** - the panel collapses to a draggable floating bubble
+  (mouse + touch); tap to restore.
+- **No CSS toolchain required** - the overlay injects its own stylesheet;
+  brand colors come from a small theme prop.
+
+## Install
+
+```bash
+npm install @artymclabin/qa-review
+# or
+pnpm add @artymclabin/qa-review
+```
+
+Install straight from git if you want an unreleased commit:
+
+```bash
+npm install github:ArtyMcLabin/qa-review
+```
+
+For CI environments without registry access, vendor a tarball:
+
+```bash
+# in this repo
+npm pack   # -> artymclabin-qa-review-<version>.tgz
+# in the consumer
+pnpm add ./vendor/artymclabin-qa-review-<version>.tgz
+```
+
+Peer dependencies: `react`, `react-dom`, `lucide-react`.
+
+## Quick start (Next.js App Router)
+
+### 1. Server: mount the handlers
+
+```ts
+// src/lib/qa-review.ts
+import { createQAReviewHandlers } from "@artymclabin/qa-review/server";
+
+export const qaHandlers = createQAReviewHandlers({
+  site: "example-site", // scope for this install (one DB can serve many)
+  authorize: async (req) => {
+    const user = await verifyMySession(req); // your gate; null -> 401
+    return user ? { reviewer: user.name, displayName: user.name } : null;
+  },
+});
+```
+
+```ts
+// src/app/api/qa/state/route.ts
+import { qaHandlers } from "@/lib/qa-review";
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+export const GET = qaHandlers.stateGET;
+export const POST = qaHandlers.statePOST;
+```
+
+Mount `submitPOST`, `sessionsGET`, and `accessGET` the same way on their own
+routes as needed.
+
+### 2. Database
+
+Set the connection string (any Postgres - local, Neon, Supabase, RDS):
+
+```bash
+QA_REVIEW_DATABASE_URL=postgresql://user:password@db.example.com/mydb
+```
+
+No migrations to write: on the first request the adapter provisions
+`qa_review_state` (the per-item ledger), `qa_review_sessions` (session
+snapshots), and `qa_review_migrations` (its own version bookkeeping).
+
+### 3. Client: mark targets and mount the overlay
+
+```tsx
+// Any element you want reviewed gets a stable [data-qa] anchor:
+<section data-qa="hero">...</section>
+```
+
+```tsx
+"use client";
+import { QAReviewOverlay } from "@artymclabin/qa-review";
+
+const ITEMS = [
+  { id: "hero", title: "Hero headline", selector: '[data-qa="hero"]' },
+  { id: "pricing", title: "Pricing table", sub: "Check the currency.", selector: '[data-qa="pricing"]' },
+];
+
+export function PageQA() {
+  return (
+    <QAReviewOverlay
+      items={ITEMS}
+      target="example-site:/pricing" // one ledger bucket per reviewed surface
+      gateParam="qaReview"           // omit if activation is gated upstream
+      submitUrl="/api/qa/submit"     // omit to hide the session-save button
+      theme={{ accent: "#ffde4d" }}
+    />
+  );
+}
+```
+
+## API sketch
+
+```ts
+// client
+import {
+  QAReviewOverlay, // the overlay component
+  createQAStore,   // per-target verdict store (localStorage + server mirror)
+  targetFromLocation, // ?target= override helper (E2E isolation)
+} from "@artymclabin/qa-review";
+
+// server
+import {
+  createQAReviewHandlers, // { stateGET, statePOST, submitPOST, sessionsGET, accessGET }
+  createPostgresStorage,  // default storage; implement QAReviewStorage to swap
+} from "@artymclabin/qa-review/server";
+```
+
+State endpoint semantics (the ledger):
+
+- `GET ?target=...` -> `{ ok, verdicts: { itemId: { verdict, note, variant } } }`
+- `POST { target, itemId, verdict | note | variant }` -> merge-upsert one item
+- `POST { target, itemId, verdict: null }` -> delete that one item
+  (re-queues it on the next round). There is deliberately **no reset-all**.
+
+## License
+
+MIT

package/dist/client/QAReviewOverlay.d.ts

@@ -4,7 +4,31 @@ import { type QAJourneyConfig } from "./journey.js";
 /** Was the pointer gesture a click (vs a drag)? Exported for tests. */
 export declare function isClickGesture(dx: number, dy: number): boolean;
 /** Note-reference text for a picked element: « label » (truncated) or tag. */
-export declare function pickedElementRef(textContent: string | null, tagName: string): string;
+export interface PickedElementDescriptor {
+    textContent?: string | null;
+    tagName: string;
+    /** aria-label, or the aria-labelledby target's text. */
+    ariaLabel?: string | null;
+    /** Text of an associated <label>, whether wrapping or `for=`-linked. */
+    labelText?: string | null;
+    placeholder?: string | null;
+    alt?: string | null;
+    title?: string | null;
+    /** Current value, for a control the reviewer has already filled in. */
+    value?: string | null;
+    name?: string | null;
+}
+/**
+ * 🚨 A form control has no `textContent`, so reading only that made every input,
+ * textarea and select come out as its bare tag name: a reviewer picking seven link
+ * fields got seven « input » refs with no way to say which row they meant. The
+ * order below is "what a human would call it" - its own text, then the accessible
+ * name, then the label a designer wrote, then what it holds - and the tag name only
+ * when the element genuinely has no name at all.
+ */
+export declare function pickedElementRef(el: PickedElementDescriptor): string;
+/** Read a live DOM element into the descriptor above. */
+export declare function describePickedElement(el: Element): PickedElementDescriptor;
 /**
  * Element-pick mode semantics (0.3.1): LEFT click picks and exits the mode;
  * RIGHT click picks and STAYS for multi-select (context menu suppressed).

package/dist/client/QAReviewOverlay.js

@@ -52,11 +52,63 @@ const CLICK_DRAG_THRESHOLD_PX = 6;
 export function isClickGesture(dx, dy) {
     return Math.hypot(dx, dy) < CLICK_DRAG_THRESHOLD_PX;
 }
-/** Note-reference text for a picked element: « label » (truncated) or tag. */
-export function pickedElementRef(textContent, tagName) {
-    const label = (textContent || "").replace(/\s+/g, " ").trim().slice(0, 48) || tagName.toLowerCase();
+/**
+ * 🚨 A form control has no `textContent`, so reading only that made every input,
+ * textarea and select come out as its bare tag name: a reviewer picking seven link
+ * fields got seven « input » refs with no way to say which row they meant. The
+ * order below is "what a human would call it" - its own text, then the accessible
+ * name, then the label a designer wrote, then what it holds - and the tag name only
+ * when the element genuinely has no name at all.
+ */
+export function pickedElementRef(el) {
+    const clean = (v) => (v || "").replace(/\s+/g, " ").trim();
+    const label = [
+        clean(el.textContent),
+        clean(el.ariaLabel),
+        clean(el.labelText),
+        clean(el.placeholder),
+        clean(el.alt),
+        clean(el.title),
+        clean(el.value),
+        clean(el.name),
+    ]
+        .find((c) => c.length > 0)
+        ?.slice(0, 48) || el.tagName.toLowerCase();
     return ` «${label}» `;
 }
+/** Read a live DOM element into the descriptor above. */
+export function describePickedElement(el) {
+    const labelledBy = el.getAttribute("aria-labelledby");
+    const labelledByText = labelledBy
+        ? labelledBy
+            .split(/\s+/)
+            .map((id) => el.ownerDocument?.getElementById(id)?.textContent ?? "")
+            .join(" ")
+        : null;
+    // A control's label is either an ancestor <label> or one pointing at its id.
+    let labelText = null;
+    const id = el.getAttribute("id");
+    if (id) {
+        const escaped = id.replace(/["\\]/g, "\\$&");
+        labelText = el.ownerDocument?.querySelector(`label[for="${escaped}"]`)?.textContent ?? null;
+    }
+    if (!labelText)
+        labelText = el.closest("label")?.textContent ?? null;
+    const isControl = ["INPUT", "TEXTAREA", "SELECT"].includes(el.tagName);
+    return {
+        // A control's own textContent is empty anyway; skipping it explicitly keeps the
+        // intent readable rather than relying on that emptiness.
+        textContent: isControl ? null : el.textContent,
+        tagName: el.tagName,
+        ariaLabel: el.getAttribute("aria-label") || labelledByText,
+        labelText,
+        placeholder: el.getAttribute("placeholder"),
+        alt: el.getAttribute("alt"),
+        title: el.getAttribute("title"),
+        value: isControl ? (el.value ?? null) : null,
+        name: el.getAttribute("name"),
+    };
+}
 /**
  * Element-pick mode semantics (0.3.1): LEFT click picks and exits the mode;
  * RIGHT click picks and STAYS for multi-select (context menu suppressed).
@@ -147,6 +199,8 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
     const [finished, setFinished] = React.useState(false);
     const [copied, setCopied] = React.useState(false);
     const [refCopied, setRefCopied] = React.useState(false);
+    /** Reference lines collected by right-clicking "Copy ref". See `appendRef`. */
+    const [refBuffer, setRefBuffer] = React.useState([]);
     const [save, setSave] = React.useState({ status: "idle" });
     // Minimized-to-bubble state (replaces the old 3s peek).
     const [minimized, setMinimized] = React.useState(false);
@@ -376,7 +430,7 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
                 return; // ignore the panel itself
             e.preventDefault();
             e.stopPropagation();
-            const ref = pickedElementRef(el.textContent, el.tagName);
+            const ref = pickedElementRef(describePickedElement(el));
             const ta = noteRef.current;
             if (ta) {
                 const s = ta.selectionStart ?? note.length;
@@ -701,17 +755,56 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
             window.prompt("Copy QA results:", json);
         });
     }, [buildPayload]);
+    /**
+     * Write `text` to the clipboard, falling back to a prompt when the API is
+     * unavailable (insecure origin, permission denied). One place, so the single
+     * and the collected copy cannot diverge.
+     */
+    const writeClipboard = React.useCallback((text, label) => {
+        navigator.clipboard.writeText(text).then(() => {
+            setRefCopied(true);
+            window.setTimeout(() => setRefCopied(false), 1500);
+        }, () => {
+            window.prompt(label, text);
+        });
+    }, []);
     const copyRef = React.useCallback(() => {
         if (!current)
             return;
         const line = formatQARef(target, current.id, current.title);
-        navigator.clipboard.writeText(line).then(() => {
-            setRefCopied(true);
-            window.setTimeout(() => setRefCopied(false), 1500);
-        }, () => {
-            window.prompt("Copy QA reference:", line);
+        // A plain click REPLACES, and therefore also ends a collection run - so the
+        // way out of a half-built list is the same button you started with.
+        setRefBuffer([]);
+        writeClipboard(line, "Copy QA reference:");
+    }, [current, target, writeClipboard]);
+    /**
+     * 🚨 COLLECT SEVERAL REFERENCES, PASTE THEM ONCE (Arty 2026-08-09: "qa
+     * interactive component - should have right click option on 'copy ref' button,
+     * to include an 'append to current clipboard'. Which should pretty much let us
+     * collect multiple references together to be able to paste them all in one.
+     * This way I would be able to copy multiple references in a single sweep and
+     * then paste them all together into claude code").
+     *
+     * 🚨 IT ACCUMULATES IN THE PANEL, NOT BY READING THE CLIPBOARD.
+     * `navigator.clipboard.readText()` is the obvious implementation and the wrong
+     * one: it needs a separate permission that Firefox does not grant to a page at
+     * all, and on a grant it would append to WHATEVER is on the clipboard -
+     * including a password manager's payload or the pasta the operator copied a
+     * minute ago off this very board. Keeping the list in the panel means the
+     * button can only ever append references it produced itself.
+     */
+    const appendRef = React.useCallback(() => {
+        if (!current)
+            return;
+        const line = formatQARef(target, current.id, current.title);
+        setRefBuffer((prev) => {
+            // Right-clicking the same item twice is a slip, not a request for a
+            // duplicate - so it is idempotent rather than additive.
+            const next = prev.includes(line) ? prev : [...prev, line];
+            writeClipboard(next.join("\n"), "Copy QA references:");
+            return next;
         });
-    }, [current, target]);
+    }, [current, target, writeClipboard]);
     // Persist the completed run as a session snapshot via the submit endpoint.
     const saveToDb = React.useCallback(async () => {
         if (!submitUrl)
@@ -767,8 +860,15 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
                                                     ? "Saved to database ✓"
                                                     : "Save review to database"] }), save.status === "error" && _jsx("p", { className: "qar-warn", children: save.message })] })), _jsxs("button", { type: "button", onClick: copyResults, className: "qar-btn-outline-accent", "data-qatip": "Copy all verdicts of this page as JSON", children: [_jsx(ClipboardCopy, { size: 16, "aria-hidden": true }), copied ? "Copied!" : "Copy JSON"] }), roundTotal > 0 && (_jsx("button", { type: "button", onClick: () => {
                                     setFinished(false);
-                                    setIndex(0);
-                                }, className: "qar-btn-outline", children: "Back to review" })), _jsx("button", { type: "button", onClick: exit, className: "qar-btn-ghost", children: "Exit QA mode" })] })] }) }), document.body);
+                                    // 🚨 THE LAST ITEM, NOT THE FIRST (Arty 2026-08-09: "Clicking
+                                    // on 'Back to review' in the QA interactive panel should go to
+                                    // the last item and not to the first item - as if it was undo
+                                    // instead of restart"). You press this having just finished,
+                                    // because of something about the item you just judged. Landing
+                                    // on item 1 of forty makes the button a restart, and getting
+                                    // back to where you were means clicking Next until you arrive.
+                                    setIndex(Math.max(0, roundTotal - 1));
+                                }, className: "qar-btn-outline", "data-qatip": "Go back to the last item you reviewed", children: "Back to review" })), _jsx("button", { type: "button", onClick: exit, className: "qar-btn-ghost", children: "Exit QA mode" })] })] }) }), document.body);
     }
     if (!current)
         return null;
@@ -821,7 +921,16 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
                             : { top: 24, left: 16 }),
                     width: CARD_W,
                     height: CARD_H,
-                }, children: [_jsxs("div", { className: "qar-card-header", onPointerDown: onCardDragStart, style: { cursor: "move" }, children: [_jsxs("span", { className: "qar-counter", "data-qatip": `Position in this page's review round${inJourney ? " · journey progress across the reviewed pages" : ""}. Drag this bar to move the panel.`, children: [index + 1, " of ", roundTotal, " to review", inJourney && (_jsxs("span", { className: "qar-muted", children: [" ", "\u00B7 page ", journeyIdx + 1, "/", journey.pages.length] }))] }), _jsxs("span", { className: "qar-header-tools", children: [current.device && (_jsx("span", { "data-qatip": DEVICE_EMOJI_TIP[current.device] ?? "target viewport(s)", children: current.device })), !currentIsTask && (_jsx("button", { type: "button", onClick: jump, "aria-label": "Jump to the highlighted section", "data-qatip": "Jump: scroll to the highlighted section", className: "qar-tool-btn", children: _jsx(Locate, { size: 14 }) })), _jsx("button", { type: "button", onClick: undo, disabled: !undoStack.length, "aria-label": "Undo the last approve/reject", "data-qatip": "Undo the last approve/reject (U or Ctrl+Z)", className: "qar-tool-btn", children: _jsx(Undo2, { size: 14 }) }), _jsx("button", { type: "button", onClick: () => setMobilePreview((v) => !v), "aria-label": "Toggle the mobile preview", "data-qatip": "Mobile preview: view this page in a phone-sized frame (for Approve Mobile on desktop)", className: `qar-tool-btn${mobilePreview ? " qar-picking" : ""}`, children: _jsx(Smartphone, { size: 14 }) }), _jsx("button", { type: "button", onClick: () => setMinimized(true), "aria-label": "Minimize to a floating bubble", "data-qatip": "Minimize: collapse into a floating bubble (M). Tap the bubble to restore.", className: "qar-tool-btn", children: _jsx(Minimize2, { size: 14 }) }), _jsx("button", { type: "button", onClick: exit, "aria-label": "Exit QA mode", "data-qatip": "Exit QA mode (Esc)", className: "qar-close-btn", children: _jsx(X, { size: 16 }) })] })] }), _jsxs("div", { className: "qar-ref-row", children: [_jsx("span", { className: "qar-codename", "data-qatip": "Stable codename for this item - say or paste it to reference the item in chat", children: codename }), _jsxs("button", { type: "button", onClick: copyRef, className: "qar-pick-btn", "data-qatip": "Copy a reference line (codename + target + item id) for chat/issues", children: [_jsx(ClipboardCopy, { size: 12 }), " ", refCopied ? "Copied!" : "Copy ref"] })] }), _jsxs("div", { className: "qar-card-body", children: [!rect && !currentIsTask && (_jsxs("p", { className: "qar-warn", children: ["Target not on this viewport (", current.selector, ") - may be a mobile-only element."] })), _jsx("h3", { className: "qar-item-title", children: current.title }), current.sub && (_jsx("div", { className: "qar-item-sub", children: current.sub
+                }, children: [_jsxs("div", { className: "qar-card-header", onPointerDown: onCardDragStart, style: { cursor: "move" }, children: [_jsxs("span", { className: "qar-counter", "data-qatip": `Position in this page's review round${inJourney ? " · journey progress across the reviewed pages" : ""}. Drag this bar to move the panel.`, children: [index + 1, " of ", roundTotal, " to review", inJourney && (_jsxs("span", { className: "qar-muted", children: [" ", "\u00B7 page ", journeyIdx + 1, "/", journey.pages.length] }))] }), _jsxs("span", { className: "qar-header-tools", children: [current.device && (_jsx("span", { "data-qatip": DEVICE_EMOJI_TIP[current.device] ?? "target viewport(s)", children: current.device })), !currentIsTask && (_jsx("button", { type: "button", onClick: jump, "aria-label": "Jump to the highlighted section", "data-qatip": "Jump: scroll to the highlighted section", className: "qar-tool-btn", children: _jsx(Locate, { size: 14 }) })), _jsx("button", { type: "button", onClick: undo, disabled: !undoStack.length, "aria-label": "Undo the last approve/reject", "data-qatip": "Undo the last approve/reject (U or Ctrl+Z)", className: "qar-tool-btn", children: _jsx(Undo2, { size: 14 }) }), _jsx("button", { type: "button", onClick: () => setMobilePreview((v) => !v), "aria-label": "Toggle the mobile preview", "data-qatip": "Mobile preview: view this page in a phone-sized frame (for Approve Mobile on desktop)", className: `qar-tool-btn${mobilePreview ? " qar-picking" : ""}`, children: _jsx(Smartphone, { size: 14 }) }), _jsx("button", { type: "button", onClick: () => setMinimized(true), "aria-label": "Minimize to a floating bubble", "data-qatip": "Minimize: collapse into a floating bubble (M). Tap the bubble to restore.", className: "qar-tool-btn", children: _jsx(Minimize2, { size: 14 }) }), _jsx("button", { type: "button", onClick: exit, "aria-label": "Exit QA mode", "data-qatip": "Exit QA mode (Esc)", className: "qar-close-btn", children: _jsx(X, { size: 16 }) })] })] }), _jsxs("div", { className: "qar-ref-row", children: [_jsx("span", { className: "qar-codename", "data-qatip": "Stable codename for this item - say or paste it to reference the item in chat", children: codename }), _jsxs("button", { type: "button", onClick: copyRef, onContextMenu: (e) => {
+                                    e.preventDefault();
+                                    appendRef();
+                                }, className: "qar-pick-btn", "data-qatip": "Click: copy this item's reference line. Right-click: ADD it to the ones already collected, so several can be pasted at once.", children: [_jsx(ClipboardCopy, { size: 12 }), " ", refCopied
+                                        ? refBuffer.length > 1
+                                            ? `Copied ${refBuffer.length}!`
+                                            : "Copied!"
+                                        : refBuffer.length > 0
+                                            ? `Copy ref (${refBuffer.length} collected)`
+                                            : "Copy ref"] })] }), _jsxs("div", { className: "qar-card-body", children: [!rect && !currentIsTask && (_jsxs("p", { className: "qar-warn", children: ["Target not on this viewport (", current.selector, ") - may be a mobile-only element."] })), _jsx("h3", { className: "qar-item-title", children: current.title }), current.sub && (_jsx("div", { className: "qar-item-sub", children: current.sub
                                     .split("\n")
                                     .map((line) => line.trim())
                                     .filter(Boolean)

package/dist/client/revisit.d.ts

@@ -6,23 +6,46 @@ export interface RevisitInfo {
     prevVerdict?: string;
     /** The reviewer's note from that prior verdict. */
     prevNote?: string;
+    /** Review round the prior verdict was given in. Absent on pre-0.4.0 rows. */
+    prevRound?: number;
 }
 export interface RevisitDisplay {
     /** Prominent "Back for review: ..." headline (reason, or generic change note). */
     headline: string | null;
-    /** "Your last verdict: reject - "note"" context line. */
+    /** "Your last verdict: reject" - WITHOUT the note (see priorNote). */
     prior: string | null;
+    /**
+     * The prior note, kept separate so the card can render it COLLAPSED. It used
+     * to be inlined into `prior` and repeated again under the NOT-ALTERED badge,
+     * so a reviewer read their own note up to three times per card (it also sits
+     * in the textarea below). Arty, 2026-08-04: "don't show a copy of it there
+     * since the note appears at the bottom anyway ... make the previous rejection
+     * note expandable in case I still want to review it."
+     */
+    priorNote: string | null;
     /** Show the prominent NOT-ALTERED badge (prior REJECT + identical content). */
     notAltered: boolean;
 }
 /**
  * Pure display logic for a re-queued item. Rules:
+ * - SAME ROUND -> nothing at all. Walking back over your own verdicts inside
+ *   one pass is navigation, not a revisit.
  * - a provided reason headlines as "Back for review: <reason>";
  * - no reason but a CHANGED fingerprint -> generic "Content changed since
  *   your last review.";
- * - a prior verdict renders as context ("Your last verdict: ...") with the
- *   saved note;
+ * - a prior verdict renders as context ("Your last verdict: reject"), with the
+ *   note handed back separately for collapsed rendering;
  * - prior REJECT + UNCHANGED fingerprint keeps the system-computed
  *   NOT-ALTERED badge (reason or not - the reviewer must see nothing moved).
+ *
+ * `currentRound` is the round being reviewed right now. When either side is
+ * unknown the comparison is skipped and the old behaviour stands, so ledgers
+ * written before 0.4.0 keep working.
  */
-export declare function describeRevisit(info: RevisitInfo | undefined, fpStatus: FingerprintStatus | null): RevisitDisplay | null;
+export declare function describeRevisit(info: RevisitInfo | undefined, fpStatus: FingerprintStatus | null, currentRound?: number): RevisitDisplay | null;
+/**
+ * True when a stored verdict belongs to the round being reviewed right now.
+ * Unknown on either side = "cannot tell", which must NOT suppress the badge - a
+ * missing round means a pre-0.4.0 row, and those are genuinely from earlier.
+ */
+export declare function isSameRound(prevRound?: number, currentRound?: number): boolean;

package/dist/client/revisit.js

@@ -1,27 +1,44 @@
 "use client";
 /**
  * Pure display logic for a re-queued item. Rules:
+ * - SAME ROUND -> nothing at all. Walking back over your own verdicts inside
+ *   one pass is navigation, not a revisit.
  * - a provided reason headlines as "Back for review: <reason>";
  * - no reason but a CHANGED fingerprint -> generic "Content changed since
  *   your last review.";
- * - a prior verdict renders as context ("Your last verdict: ...") with the
- *   saved note;
+ * - a prior verdict renders as context ("Your last verdict: reject"), with the
+ *   note handed back separately for collapsed rendering;
  * - prior REJECT + UNCHANGED fingerprint keeps the system-computed
  *   NOT-ALTERED badge (reason or not - the reviewer must see nothing moved).
+ *
+ * `currentRound` is the round being reviewed right now. When either side is
+ * unknown the comparison is skipped and the old behaviour stands, so ledgers
+ * written before 0.4.0 keep working.
  */
-export function describeRevisit(info, fpStatus) {
+export function describeRevisit(info, fpStatus, currentRound) {
     if (!info)
         return null;
+    if (isSameRound(info.prevRound, currentRound))
+        return null;
     const headline = info.reason
         ? `Back for review: ${info.reason}`
         : fpStatus === "changed"
             ? "Content changed since your last review."
             : null;
-    const prior = info.prevVerdict
-        ? `Your last verdict: ${info.prevVerdict}${info.prevNote ? ` - "${info.prevNote}"` : ""}`
-        : null;
+    const prior = info.prevVerdict ? `Your last verdict: ${info.prevVerdict}` : null;
+    const priorNote = info.prevNote ?? null;
     const notAltered = fpStatus === "unchanged" && info.prevVerdict === "reject";
     if (!headline && !prior && !notAltered)
         return null;
-    return { headline, prior, notAltered };
+    return { headline, prior, priorNote, notAltered };
+}
+/**
+ * True when a stored verdict belongs to the round being reviewed right now.
+ * Unknown on either side = "cannot tell", which must NOT suppress the badge - a
+ * missing round means a pre-0.4.0 row, and those are genuinely from earlier.
+ */
+export function isSameRound(prevRound, currentRound) {
+    if (typeof prevRound !== "number" || typeof currentRound !== "number")
+        return false;
+    return prevRound === currentRound;
 }

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@artymclabin/qa-review",
-  "version": "0.3.7",
-  "description": "Interactive on-page QA review overlay (spotlight walkthrough, approve/reject verdict ledger) with a framework-agnostic server handler factory and a self-provisioning Postgres store.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ArtyMcLabin/qa-review.git"
-  },
-  "type": "module",
-  "sideEffects": false,
-  "main": "./dist/client/index.js",
-  "types": "./dist/client/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/client/index.d.ts",
-      "default": "./dist/client/index.js"
-    },
-    "./client": {
-      "types": "./dist/client/index.d.ts",
-      "default": "./dist/client/index.js"
-    },
-    "./server": {
-      "types": "./dist/server/index.d.ts",
-      "default": "./dist/server/index.js"
-    }
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "test": "vitest run",
-    "prepare": "npm run build"
-  },
-  "peerDependencies": {
-    "lucide-react": ">=0.400.0",
-    "react": ">=18",
-    "react-dom": ">=18"
-  },
-  "dependencies": {
-    "postgres": "^3.4.5"
-  },
-  "devDependencies": {
-    "@types/node": "^22",
-    "@types/react": "^19",
-    "@types/react-dom": "^19",
-    "jsdom": "^26",
-    "lucide-react": "^1.25.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "typescript": "^5",
-    "vitest": "^3"
-  }
-}
+{
+  "name": "@artymclabin/qa-review",
+  "version": "0.3.9",
+  "description": "Interactive on-page QA review overlay (spotlight walkthrough, approve/reject verdict ledger) with a framework-agnostic server handler factory and a self-provisioning Postgres store.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArtyMcLabin/qa-review.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/client/index.js",
+  "types": "./dist/client/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "lucide-react": ">=0.400.0",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "postgres": "^3.4.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "jsdom": "^26",
+    "lucide-react": "^1.25.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5",
+    "vitest": "^3"
+  }
+}