@artymclabin/qa-review 0.3.12 → 0.3.13

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.3.13 - 2026-10-07
+
+- JOURNEY-WIDE TOTALS: in a cross-page journey the footer and the finish card
+  now show approve/reject totals across EVERY page (`whole journey: N approved
+  · M rejected · T items`), next to the page line (now labelled `this page,
+  all runs`). Previously the only ledger count was page-scoped and unlabelled,
+  so at the end of a ten-page journey with 12 verdicts it read "1 approved".
+  New exports: `fetchJourneyVerdicts`, `tallyJourney`, `VerdictTally`.
+- RUN SNAPSHOT SAVES ITSELF: when `submitUrl` is set, the whole-run snapshot
+  is POSTed automatically once per finished round. The "Save session
+  snapshot (optional)" button is gone - it asked the reviewer for a decision
+  with no stake in it. A failed save shows as a warning line.
+
 ## 0.3.10 - 2026-09-19
 
 - OUTSIDE TAP MINIMIZES THE PANEL, ON MOBILE: the only way to collapse the

package/dist/client/QAReviewOverlay.js

@@ -34,7 +34,7 @@ import { createPortal } from "react-dom";
 import { Check, X, ChevronLeft, ChevronRight, ClipboardCopy, PartyPopper, Database, Undo2, Crosshair, Locate, ExternalLink, Minimize2, Monitor, Smartphone, ClipboardCheck, } from "lucide-react";
 import { isTaskItem } from "./types.js";
 import { QAStore } from "./store.js";
-import { buildJourneyNavUrl, ensurePrefetchLink, fetchPendingCounts, isPrefetchFresh, journeyFinishView, journeyIndex, nextPendingPage, resolveFinishAction, shouldPrefetch, } from "./journey.js";
+import { buildJourneyNavUrl, ensurePrefetchLink, fetchJourneyVerdicts, fetchPendingCounts, isPrefetchFresh, journeyFinishView, journeyIndex, nextPendingPage, resolveFinishAction, shouldPrefetch, tallyJourney, } from "./journey.js";
 import { fingerprintStatus, itemFingerprint } from "./fingerprint.js";
 import { DEVICE_LABEL, DEVICE_TOOLTIP, approvedDevicesOf, detectDevice, isFullyApproved, requiredDevices, toggleDevice, } from "./device.js";
 import { applySubHighlights } from "./highlight.js";
@@ -211,6 +211,8 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
     // Journey: pending counts (for the journey-complete panel only - page-level
     // completion navigates IMMEDIATELY with no interstitial).
     const [journeyCounts, setJourneyCounts] = React.useState(null);
+    // Ledger maps of every journey page, for journey-wide approve/reject totals.
+    const [journeyMaps, setJourneyMaps] = React.useState(null);
     const [journeyComplete, setJourneyComplete] = React.useState(false);
     // The journey page a full-page navigation is in flight to (loading label).
     const [navigatingTo, setNavigatingTo] = React.useState(null);
@@ -725,6 +727,21 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [active, finished, inJourney, index, roundTotal]);
+    // Journey-wide totals: load every page's ledger once on activation and
+    // again when the round finishes (other tabs/sessions may have written).
+    React.useEffect(() => {
+        if (!active || !inJourney)
+            return;
+        let cancelled = false;
+        void fetchJourneyVerdicts(stateUrl ?? DEFAULT_STATE_URL, journey.pages).then((maps) => {
+            if (!cancelled)
+                setJourneyMaps(maps);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [active, inJourney, finished]);
     // Journey: the moment this page's round is done, resolve the next step and
     // navigate IMMEDIATELY (no interstitial, no success popup). Uses the
     // PREFETCHED counts when fresh (instant hop); falls back to an on-demand
@@ -851,6 +868,23 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
             setSave({ status: "error", message: "Network error - use Copy JSON instead." });
         }
     }, [submitUrl, buildPayload]);
+    // 🚨 The run snapshot saves ITSELF when a round finishes (0.3.13). It used to
+    // be a "Save session snapshot (optional)" button, which asked the reviewer to
+    // make a decision with no stake in it: Arty 2026-10-07, "Either save it or
+    // don't save it. If it's useful, save it... Why did you ask me to click that
+    // button instead?" Once per finish; a failure surfaces as a warning only.
+    const snapshotDoneRef = React.useRef(false);
+    React.useEffect(() => {
+        if (!finished) {
+            snapshotDoneRef.current = false;
+            return;
+        }
+        // Nothing decided this round = nothing to snapshot.
+        if (!submitUrl || snapshotDoneRef.current || Object.keys(sessionVerdicts).length === 0)
+            return;
+        snapshotDoneRef.current = true;
+        void saveToDb();
+    }, [finished, submitUrl, saveToDb, sessionVerdicts]);
     if (!active || !hydrated || typeof document === "undefined")
         return null;
     // Inline CSS-variable overrides for the injected default theme.
@@ -863,6 +897,8 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
     // LEDGER (all-time on this page) vs THIS ROUND (acted on in this run).
     const approved = Object.values(results).filter((r) => r.verdict === "approve").length;
     const rejected = Object.values(results).filter((r) => r.verdict === "reject").length;
+    const liveMap = Object.fromEntries(Object.values(results).map((r) => [r.id, { verdict: r.verdict }]));
+    const journeyTally = inJourney && journeyMaps ? tallyJourney(journey.pages, journeyMaps, { [target]: liveMap }) : null;
     const sessionApproved = Object.values(sessionVerdicts).filter((v) => v === "approve").length;
     const sessionRejected = Object.values(sessionVerdicts).filter((v) => v === "reject").length;
     /* ------------------------------ finish panel ------------------------------ */
@@ -876,14 +912,10 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
                             ? `Loading ${navigatingTo.label ?? navigatingTo.path}…`
                             : "Checking remaining pages…", _jsx("span", { className: "qar-muted", style: { fontSize: 11, fontWeight: 400 }, children: "The review continues on the next page - do not close this tab." })] }) }), document.body);
         }
-        return createPortal(_jsx("div", { className: "qar-theme qar-finish-backdrop", style: themeStyle, children: _jsxs("div", { className: "qar-finish-card", children: [_jsx(PartyPopper, { className: "qar-finish-icon", size: 40, "aria-hidden": true }), _jsx("h2", { className: "qar-finish-title", children: inJourney ? "Journey complete" : "QA review complete" }), _jsxs("p", { className: "qar-finish-stats", "data-qatip": "Verdicts you recorded in THIS review run", children: [_jsxs("span", { className: "qar-green", children: [sessionApproved, " approved"] }), " \u00B7", " ", _jsxs("span", { className: "qar-red", children: [sessionRejected, " rejected"] }), " \u00B7 this round"] }), _jsxs("p", { className: "qar-finish-alltime", "data-qatip": "Ledger totals for this page across all runs (durable review database)", children: ["all-time on this page: ", approved, " approved \u00B7 ", rejected, " rejected \u00B7 ", total, " items"] }), _jsxs("p", { className: "qar-finish-autosaved", "data-qatip": "Every verdict was written to the server ledger the moment you decided it", children: [_jsx(Database, { size: 14, "aria-hidden": true }), " Auto-saved to the review database as you go."] }), inJourney && journeyCounts && (_jsx("div", { className: "qar-journey", children: journey.pages.map((p, i) => {
+        return createPortal(_jsx("div", { className: "qar-theme qar-finish-backdrop", style: themeStyle, children: _jsxs("div", { className: "qar-finish-card", children: [_jsx(PartyPopper, { className: "qar-finish-icon", size: 40, "aria-hidden": true }), _jsx("h2", { className: "qar-finish-title", children: inJourney ? "Journey complete" : "QA review complete" }), _jsxs("p", { className: "qar-finish-stats", "data-qatip": "Verdicts you recorded in THIS review run", children: [_jsxs("span", { className: "qar-green", children: [sessionApproved, " approved"] }), " \u00B7", " ", _jsxs("span", { className: "qar-red", children: [sessionRejected, " rejected"] }), " \u00B7 this round"] }), _jsxs("p", { className: "qar-finish-alltime", "data-qatip": "Ledger totals for this page across all runs (durable review database)", children: ["this page, all runs: ", approved, " approved \u00B7 ", rejected, " rejected \u00B7 ", total, " items"] }), journeyTally && (_jsxs("p", { className: "qar-finish-alltime", "data-qatip": "Ledger totals across every page of this journey", children: ["whole journey: ", journeyTally.approved, " approved \u00B7 ", journeyTally.rejected, " rejected \u00B7", " ", journeyTally.total, " items"] })), _jsxs("p", { className: "qar-finish-autosaved", "data-qatip": "Every verdict was written to the server ledger the moment you decided it", children: [_jsx(Database, { size: 14, "aria-hidden": true }), " Auto-saved to the review database as you go."] }), inJourney && journeyCounts && (_jsx("div", { className: "qar-journey", children: journey.pages.map((p, i) => {
                             const left = journeyCounts[p.target] ?? 0;
                             return (_jsxs("div", { className: `qar-journey-row${i === journeyIdx ? " qar-current" : ""}`, children: [_jsxs("span", { children: [p.label ?? p.path, i === journeyIdx ? " (here)" : ""] }), _jsx("span", { className: left === 0 ? "qar-journey-done" : "qar-journey-left", children: left === 0 ? "✓ done" : `${left} left` })] }, p.target));
-                        }) })), _jsxs("div", { className: "qar-finish-actions", children: [submitUrl && (_jsxs(_Fragment, { children: [_jsxs("button", { type: "button", onClick: saveToDb, disabled: save.status === "saving" || save.status === "ok", className: "qar-btn-primary", "data-qatip": "Store a snapshot of this whole run (verdicts are already saved individually)", children: [_jsx(Database, { size: 16, "aria-hidden": true }), save.status === "saving"
-                                                ? "Saving…"
-                                                : save.status === "ok"
-                                                    ? "Snapshot saved ✓"
-                                                    : "Save session snapshot (optional)"] }), save.status !== "ok" && (_jsx("p", { className: "qar-finish-autosaved", style: { marginTop: 4 }, children: "Your verdicts above are already saved - this only logs a snapshot of the whole run." })), 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: () => {
+                        }) })), _jsxs("div", { className: "qar-finish-actions", children: [save.status === "error" && (_jsxs("p", { className: "qar-warn", children: ["Run snapshot not saved: ", 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);
                                     // 🚨 THE LAST ITEM, NOT THE FIRST (Arty 2026-08-09: "Clicking
                                     // on 'Back to review' in the QA interactive panel should go to
@@ -988,5 +1020,5 @@ export function QAReviewOverlay({ items, target, gateParam, stateUrl, submitUrl,
                                 return (_jsxs("button", { type: "button", onClick: () => approveDevice(d), className: cls, "data-qatip": `${DEVICE_TOOLTIP[d]}${isHint ? " (A)" : ""}${done ? " - already approved" : ""}`, children: [multiDevice ? (d === "pc" ? (_jsx(Monitor, { size: 16, "aria-hidden": true })) : (_jsx(Smartphone, { size: 16, "aria-hidden": true }))) : (_jsx(Check, { size: 16, "aria-hidden": true })), multiDevice ? `${done ? "✓ " : ""}${DEVICE_LABEL[d]}` : "Approve"] }, d));
                             }), _jsx("button", { type: "button", onClick: next, disabled: !hasNext, "aria-label": "Next item", "data-qatip": index >= roundTotal - 1 && inJourney
                                     ? "Finish this page and continue the journey (→)"
-                                    : "Next item (→)", className: "qar-nav-btn", children: _jsx(ChevronRight, { size: 16 }) })] }), _jsxs("div", { className: "qar-footer", children: [_jsx("span", { "data-qatip": "Keyboard shortcuts", children: "keys: A approve \u00B7 R reject \u00B7 \u2190/\u2192 \u00B7 U undo \u00B7 M minimize \u00B7 Esc" }), _jsxs("span", { children: [_jsxs("span", { className: "qar-footer-green", "data-qatip": "Items decided in this round", children: [decidedInRound, "/", roundTotal, " this round"] }), " ", _jsxs("span", { "data-qatip": "Fully approved items on this page across all runs (ledger)", children: ["\u00B7 ", approvedCount, " approved all-time"] })] })] })] })] }), document.body);
+                                    : "Next item (→)", className: "qar-nav-btn", children: _jsx(ChevronRight, { size: 16 }) })] }), _jsxs("div", { className: "qar-footer", children: [_jsx("span", { "data-qatip": "Keyboard shortcuts", children: "keys: A approve \u00B7 R reject \u00B7 \u2190/\u2192 \u00B7 U undo \u00B7 M minimize \u00B7 Esc" }), _jsxs("span", { children: [_jsxs("span", { className: "qar-footer-green", "data-qatip": "Items decided in this round", children: [decidedInRound, "/", roundTotal, " this round"] }), " ", journeyTally ? (_jsxs("span", { "data-qatip": "Ledger totals across every page of this journey", children: ["\u00B7 journey: ", journeyTally.approved, " approved \u00B7 ", journeyTally.rejected, " rejected"] })) : (_jsxs("span", { "data-qatip": "Items on this page across all runs (ledger)", children: ["\u00B7 this page: ", approvedCount, " approved \u00B7 ", rejected, " rejected"] }))] })] })] })] }), document.body);
 }

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
 export { QAReviewOverlay, isClickGesture, nextMinimized, AUTO_BUBBLE_MAX_WIDTH_PX, type BubbleEvent, type QAReviewOverlayProps, } from "./QAReviewOverlay.js";
 export { QAStore, createQAStore, targetFromLocation, type QAStoreOptions, type PersistedVerdict, type PendingOp, type VerdictMap, } from "./store.js";
-export { journeyIndex, countPending, countUnverdicted, nextPendingPage, buildJourneyNavUrl, fetchPendingCounts, resolveFinishAction, journeyFinishView, shouldPrefetch, isPrefetchFresh, ensurePrefetchLink, PREFETCH_WINDOW_ITEMS, PREFETCH_MAX_AGE_MS, type FinishAction, type QAJourneyConfig, type QAJourneyPage, } from "./journey.js";
+export { journeyIndex, countPending, countUnverdicted, nextPendingPage, buildJourneyNavUrl, fetchPendingCounts, fetchJourneyVerdicts, tallyJourney, resolveFinishAction, journeyFinishView, shouldPrefetch, isPrefetchFresh, ensurePrefetchLink, PREFETCH_WINDOW_ITEMS, PREFETCH_MAX_AGE_MS, type FinishAction, type QAJourneyConfig, type QAJourneyPage, type VerdictTally, } from "./journey.js";
 export { normalizeText, fingerprintText, itemFingerprint, fingerprintStatus, type FingerprintStatus, } from "./fingerprint.js";
 export { requiredDevices, approvedDevicesOf, isFullyApproved, nextApprovedDevices, toggleDevice, detectDevice, DEVICE_LABEL, DEVICE_TOOLTIP, type QADevice, } from "./device.js";
 export { findMatchRanges, applySubHighlights, type MatchRange } from "./highlight.js";

package/dist/client/index.js

@@ -1,6 +1,6 @@
 export { QAReviewOverlay, isClickGesture, nextMinimized, AUTO_BUBBLE_MAX_WIDTH_PX, } from "./QAReviewOverlay.js";
 export { QAStore, createQAStore, targetFromLocation, } from "./store.js";
-export { journeyIndex, countPending, countUnverdicted, nextPendingPage, buildJourneyNavUrl, fetchPendingCounts, resolveFinishAction, journeyFinishView, shouldPrefetch, isPrefetchFresh, ensurePrefetchLink, PREFETCH_WINDOW_ITEMS, PREFETCH_MAX_AGE_MS, } from "./journey.js";
+export { journeyIndex, countPending, countUnverdicted, nextPendingPage, buildJourneyNavUrl, fetchPendingCounts, fetchJourneyVerdicts, tallyJourney, resolveFinishAction, journeyFinishView, shouldPrefetch, isPrefetchFresh, ensurePrefetchLink, PREFETCH_WINDOW_ITEMS, PREFETCH_MAX_AGE_MS, } from "./journey.js";
 export { normalizeText, fingerprintText, itemFingerprint, fingerprintStatus, } from "./fingerprint.js";
 export { requiredDevices, approvedDevicesOf, isFullyApproved, nextApprovedDevices, toggleDevice, detectDevice, DEVICE_LABEL, DEVICE_TOOLTIP, } from "./device.js";
 export { findMatchRanges, applySubHighlights } from "./highlight.js";

package/dist/client/journey.d.ts

@@ -87,3 +87,21 @@ export declare function ensurePrefetchLink(doc: Document, href: string): void;
  * a page silently).
  */
 export declare function fetchPendingCounts(stateUrl: string, pages: readonly QAJourneyPage[]): Promise<Record<string, number>>;
+/** Ledger verdict map per journey page target (null = fetch failed). */
+export declare function fetchJourneyVerdicts(stateUrl: string, pages: readonly QAJourneyPage[]): Promise<Record<string, VerdictMap | null>>;
+export interface VerdictTally {
+    approved: number;
+    rejected: number;
+    total: number;
+}
+/**
+ * Approve / reject / item totals over a whole journey (0.3.13). Counts only the
+ * page's declared `itemIds`, so stale ledger rows for retired items never
+ * inflate the numbers. `overrides` replaces a page's ledger map with live state
+ * (the current page's in-memory verdicts are fresher than any fetch).
+ *
+ * 🚨 Arty 2026-10-07: the panel said "1 approved, 0 rejected" at the end of a
+ * ten-page journey he had just walked through with 12 verdicts - the count was
+ * page-scoped and unlabeled, so it read as the whole review.
+ */
+export declare function tallyJourney(pages: readonly QAJourneyPage[], maps: Readonly<Record<string, VerdictMap | null | undefined>>, overrides?: Readonly<Record<string, VerdictMap>>): VerdictTally;

package/dist/client/journey.js

@@ -112,6 +112,14 @@ export function ensurePrefetchLink(doc, href) {
  * a page silently).
  */
 export async function fetchPendingCounts(stateUrl, pages) {
+    const maps = await fetchJourneyVerdicts(stateUrl, pages);
+    const out = {};
+    for (const p of pages)
+        out[p.target] = countUnverdicted(p.itemIds, maps[p.target]);
+    return out;
+}
+/** Ledger verdict map per journey page target (null = fetch failed). */
+export async function fetchJourneyVerdicts(stateUrl, pages) {
     const out = {};
     await Promise.all(pages.map(async (p) => {
         let map = null;
@@ -128,7 +136,32 @@ export async function fetchPendingCounts(stateUrl, pages) {
         catch {
             map = null;
         }
-        out[p.target] = countUnverdicted(p.itemIds, map);
+        out[p.target] = map;
     }));
     return out;
 }
+/**
+ * Approve / reject / item totals over a whole journey (0.3.13). Counts only the
+ * page's declared `itemIds`, so stale ledger rows for retired items never
+ * inflate the numbers. `overrides` replaces a page's ledger map with live state
+ * (the current page's in-memory verdicts are fresher than any fetch).
+ *
+ * 🚨 Arty 2026-10-07: the panel said "1 approved, 0 rejected" at the end of a
+ * ten-page journey he had just walked through with 12 verdicts - the count was
+ * page-scoped and unlabeled, so it read as the whole review.
+ */
+export function tallyJourney(pages, maps, overrides = {}) {
+    const t = { approved: 0, rejected: 0, total: 0 };
+    for (const p of pages) {
+        const map = overrides[p.target] ?? maps[p.target];
+        t.total += p.itemIds.length;
+        for (const id of p.itemIds) {
+            const v = map?.[id]?.verdict;
+            if (v === "approve")
+                t.approved++;
+            else if (v === "reject")
+                t.rejected++;
+        }
+    }
+    return t;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artymclabin/qa-review",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "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": {