@artymclabin/qa-review 0.3.7

package/CHANGELOG.md

@@ -0,0 +1,174 @@
+# Changelog
+
+## 0.3.7 - 2026-07-30
+
+- MOBILE PREVIEW SCROLLS TO THE ITEM: the phone-frame iframe loaded each page
+  at its top, so opening the preview showed the header rather than the section
+  under review. scrollPreviewToSelector() now reaches into the same-origin
+  frame and centres the current item's element. It RETRIES rather than
+  scrolling once, because the iframe fires load before hydration and before
+  images settle and an early scroll gets undone by the layout shift that
+  follows; it keeps scrolling for a couple of rounds after a successful hit for
+  the same reason, and is bounded at 12 attempts so a genuinely absent element
+  (desktop-only items) cannot loop forever. Returns a cleanup that cancels
+  pending retries.
+- Wired both on iframe load (opening the preview) and on a selector-keyed
+  effect (advancing to the next item while the preview stays open, where the
+  iframe is deliberately not reloaded and load never fires again).
+
+## 0.3.6 - 2026-07-21
+
+- MOBILE PREVIEW LIVE VARIANT UPDATE: picking a variation while the phone-frame
+  preview is OPEN now applies the new variant inside the iframe without a
+  close+reopen. The parent posts a same-origin variant message to the iframe;
+  the embedded (dormant) overlay runs the item's OWN variation callback there,
+  so the DOM mutation executes in the iframe document. The frame also syncs the
+  current variant on load. New exports: postVariantToPreview, parseVariantMessage.
+- MINIMIZE BUBBLE DOCKS LEFT: the floating bubble now defaults to the LEFT side
+  of the screen when minimized (still fully draggable).
+
+## 0.3.5 - 2026-07-21
+
+- JOURNEY PRELOAD: within the final 2 items of a round the overlay prefetches
+  the other pages' pending counts in the background and warms the likely next
+  page with a <link rel="prefetch"> hint. Round exhaustion then navigates
+  INSTANTLY on the cached result (30s freshness window; stale/missing falls
+  back to the on-demand fetch + loading card).
+- MOBILE PREVIEW: a panel button renders the current page in a phone-sized
+  (390x844) framed same-origin iframe on a dimmed backdrop - Approve Mobile
+  without devtools. The QA card stays usable on top; a close control (or the
+  toggle) returns to normal. The iframe URL keeps the QA params plus a
+  qaMobilePreview marker that keeps the embedded overlay dormant.
+- ROUND-SCOPED COUNTERS: the finish panel now leads with THIS ROUND's
+  approved/rejected (verdicts recorded in this run); ledger totals moved to a
+  smaller line labeled "all-time on this page". The footer decided-counter is
+  session-based and the approved total is labeled "approved all-time".
+
+## 0.3.4 - 2026-07-21
+
+- TOOLTIP DE-NESTING: exactly one tooltip per hover point. Container elements
+  no longer carry tooltips that overlap a child control's (Copy-ref row ->
+  codename span; card header -> counter; bubble -> single carrier), plus a
+  CSS :has() guard suppresses any ancestor tooltip while a descendant tooltip
+  target is hovered. Rendered-DOM invariant test: no [data-qatip] element may
+  have a [data-qatip] ancestor.
+- COPY-REF FORMAT: the copied reference is now brace-wrapped:
+  `{ qa-ref: <codename> | <target> # <itemId> | <title> }`.
+- Robustness: the auto-bubble listener no-ops when matchMedia is unavailable.
+
+## 0.3.3 - 2026-07-21
+
+- RE-QUEUE CONTEXT: invalidation (state POST verdict:null) accepts an optional
+  `revisitReason`. With a reason the row is KEPT - verdict moves to
+  prev_verdict, note + fingerprint stay, reason is stored - and the card for
+  the re-queued item prominently shows "Back for review: <reason>" plus
+  "Your last verdict: <verdict> - '<note>'", combined with the fingerprint
+  badges (NOT ALTERED / changed). No reason + changed fingerprint shows a
+  generic "Content changed since your last review." Recording a new verdict
+  consumes the context; verdict:null WITHOUT a reason keeps the old
+  hard-delete (undo). State GET returns revisitReason + prevVerdict for
+  audits. Migration id 3: revisit_reason + prev_verdict columns.
+
+## 0.3.2 - 2026-07-21
+
+- CRITICAL journey fix: the walkthrough ping-ponged forever between a page
+  with fresh REJECTS and the next page (rejected items counted as pending for
+  navigation, so wraparound kept returning to them). Navigation-pending is now
+  UNVERDICTED only (no verdict and no device approvals) - approve, reject,
+  and partial device states all count as handled for the current run.
+  Rejected items still re-enter FUTURE rounds (round/ledger semantics
+  unchanged); the journey-complete panel shows when every page has zero
+  unverdicted items. New `countUnverdicted` export.
+
+## 0.3.1 - 2026-07-21
+
+- JOURNEY LOADING INDICATOR: finishing a page in a journey now shows an
+  unmistakable spinner card ("Loading <next page>…" / "Checking remaining
+  pages…") from the moment the round exhausts until the next page unloads -
+  never a blank screen.
+- DEVICE APPROVE TOGGLE: Approve PC / Approve Mobile (and single Approve)
+  buttons toggle - clicking an approved device UNSETS that approval and the
+  item returns to pending when it loses full approval. Unsets persist in real
+  time (fully-approved rows are cleared and re-written with the remaining
+  device approvals + retained note/variant/fingerprint, in queue order).
+- AUTO-BUBBLE: switching the viewport to a mobile-ish width (<=767px, e.g.
+  devtools responsive emulation) auto-minimizes the panel to the bubble;
+  switching back auto-restores. Manual minimize/restore wins until the next
+  switch.
+- SUB-HIGHLIGHT RENDER FIX: highlight marks live in page content, outside the
+  .qar-theme var scope - the 0.3.0 rule depended on un-fallbacked vars and
+  computed to NO background (invisible highlights). The rule now carries hard
+  var() fallbacks and the overlay mirrors its theme vars onto <html> so marks
+  follow the consumer theme.
+- ELEMENT-PICK MULTI-SELECT: in note pick-element mode, LEFT click keeps the
+  pick-and-exit behavior; RIGHT click picks WITHOUT exiting (native context
+  menu suppressed) so several elements can be referenced in a row.
+- INSTANT TOOLTIPS: all overlay tooltips are zero-delay CSS tooltips
+  ([data-qatip]) instead of the ~500ms native title delay.
+
+## 0.3.0 - 2026-07-21
+
+- NOT-ALTERED POKA-YOKE: every verdict stores a normalized content fingerprint
+  (anchored items hash the element innerText; task items their question). A
+  re-shown REJECTED item whose content still fingerprints identical gets a
+  prominent SYSTEM-COMPUTED "NOT ALTERED since your rejection" badge (+ the
+  saved rejection note); a differing fingerprint shows a subtle "changed since
+  last review" hint. Judged by hashing, never by an operating agent.
+- DEVICE-SPLIT APPROVALS: `devices?: ("pc"|"mobile")[]` (default pc). One
+  approve button per required device; the item counts approved and advances
+  only when EVERY required device is approved (reject stays whole-item).
+  Plain historical approvals are GRANDFATHERED as fully approved; the round
+  recomputes device-aware on load. Detected device gets the primary-styled
+  hint button (all stay clickable) with per-device tooltips.
+- IMMEDIATE JOURNEY NAV: no "page complete" interstitial - finishing a page
+  navigates instantly to the next pending page; the completion panel shows
+  only when the WHOLE journey is clean.
+- SUB-HIGHLIGHT: `highlightWords?: string[]` wraps matching words/phrases
+  inside the spotlighted element with a secondary mark.
+- CODENAMES + COPY-REF: deterministic two-word codename per (target, itemId)
+  shown on the card with a "Copy ref" button; `codenameFor`/`findByCodename`
+  resolver exported (client + server) and codenames attached to state GET
+  responses.
+- MINIMIZE BUBBLE: replaces the 3s peek - the panel collapses to a draggable
+  floating bubble (mouse + touch pointer events); tap restores. Panel drag is
+  pointer-based now too. Note textarea stretches to fill the card. Tooltips
+  on every icon/abbreviation.
+- Server: migration 2 adds `fp`, `approved_pc`, `approved_mobile` to
+  qa_review_state; state POST accepts `fp` + `approvedDevices`.
+
+## 0.2.0 - 2026-07-21
+
+- JOURNEY: cross-page review flow. `journey` prop (ordered pages with path /
+  target / label / itemIds): when a page's round is done the finish panel shows
+  per-page pending counts (one state GET per target; failed fetch = page counts
+  as pending) and auto-navigates (3s, cancellable) to the next page with
+  pending items - wrapping past the end, never the current page. Activation
+  query params (gate param, auth key) are preserved on the hop; the per-page
+  `target` override is dropped. Prev at the first item goes back to the
+  previous journey page; Next past the last item opens the journey summary.
+  Header shows "page X/N" progress.
+- TASK ITEMS: `selector` is now optional - an item without one renders as a
+  centered card (no spotlight, full-page dim) with an optional `action` link
+  button (new tab). Same approve/reject/note/undo + real-time persistence.
+
+## 0.1.1 - 2026-07-21
+
+- REAL-TIME persistence unified across consumers (SSoT fix): every
+  approve/reject, note change (debounced, default 600ms), and undo writes to
+  the server ledger immediately; the session-snapshot submit is optional
+  either way.
+- Write-behind offline resilience: failed server writes queue in localStorage
+  (survive reloads), replay in order on the next action, and hydration replays
+  still-pending ops over the server map so an offline verdict is never
+  clobbered or lost silently.
+- Finish panel unified: the auto-saved note always shows and the copy button
+  is canonically labeled "Copy JSON" in all configurations.
+
+## 0.1.0 - 2026-07-21
+
+- Initial release: spotlight QA review overlay (round-based review frozen at
+  load, fixed denominator, undo, 3s peek, element-picker notes, design
+  variations, keyboard driving), client verdict store (localStorage cache +
+  durable server mirror, single-item invalidation, no reset-all), server
+  handler factory (state ledger, session submit, sessions list, access probe,
+  BYO `authorize`), self-provisioning Postgres storage with `site` scoping.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arty McLabin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +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

package/dist/client/QAReviewOverlay.d.ts

@@ -0,0 +1,59 @@
+import * as React from "react";
+import type { QAReviewItem, QATheme } from "./types.js";
+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;
+/**
+ * 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).
+ */
+export declare function shouldExitPickMode(button: "left" | "right"): boolean;
+/** Viewport width at/below which the panel auto-minimizes to the bubble. */
+export declare const AUTO_BUBBLE_MAX_WIDTH_PX = 767;
+export type BubbleEvent = {
+    type: "viewport";
+    mobile: boolean;
+} | {
+    type: "manual";
+    minimized: boolean;
+};
+/**
+ * Auto-bubble state machine (0.3.1): a VIEWPORT switch always applies its
+ * auto state (mobile-ish width -> bubble, desktop -> panel); a MANUAL
+ * minimize/restore wins immediately and holds until the NEXT viewport switch.
+ * Exported for tests.
+ */
+export declare function nextMinimized(current: boolean, ev: BubbleEvent): boolean;
+export interface QAReviewOverlayProps {
+    items: QAReviewItem[];
+    /** Review bucket - persisted with every verdict (e.g. "example-site:/pricing"). */
+    target: string;
+    /**
+     * URL param that must be present to activate the overlay (e.g. "qaReview").
+     * Omit when activation is handled upstream (auth-gated lazy mount): the
+     * overlay is then active immediately on mount.
+     */
+    gateParam?: string;
+    /** State-ledger endpoint. Default "/api/qa/state". */
+    stateUrl?: string;
+    /**
+     * Session-snapshot endpoint (e.g. "/api/qa/submit"). When set, the finish
+     * panel shows a "Save review to database" button POSTing the full run there.
+     * The snapshot is OPTIONAL either way: per-item verdicts always persist to
+     * the state ledger in real time as they are decided.
+     */
+    submitUrl?: string;
+    /** localStorage key builder. Default: `qa-review-verdicts:<target>`. */
+    storageKey?: (target: string) => string;
+    /** Brand colors for the overlay chrome (defaults are a dark yellow theme). */
+    theme?: Partial<QATheme>;
+    /**
+     * Cross-page review journey (ordered pages with their ledger targets +
+     * item ids). The page whose `target` equals this overlay's `target` is the
+     * current journey position.
+     */
+    journey?: QAJourneyConfig;
+}
+export declare function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl, storageKey, theme, journey, }: QAReviewOverlayProps): React.ReactPortal | null;