@artymclabin/qa-review 0.3.7

package/dist/client/device.d.ts

@@ -0,0 +1,28 @@
+import type { PersistedVerdict } from "./store.js";
+import type { QAReviewItem } from "./types.js";
+export type QADevice = "pc" | "mobile";
+export declare const DEVICE_LABEL: Record<QADevice, string>;
+export declare const DEVICE_TOOLTIP: Record<QADevice, string>;
+/** Required review devices for an item. Default: PC only. */
+export declare function requiredDevices(item: Pick<QAReviewItem, "devices">): QADevice[];
+/** Devices already approved on a ledger entry. */
+export declare function approvedDevicesOf(entry: PersistedVerdict | undefined): QADevice[];
+/**
+ * Fully approved = a recorded whole-item approval (incl. grandfathered plain
+ * approvals with no device data) OR every required device approved.
+ */
+export declare function isFullyApproved(entry: PersistedVerdict | undefined, required: readonly QADevice[]): boolean;
+/** Union of already-approved devices + a new approval. */
+export declare function nextApprovedDevices(entry: PersistedVerdict | undefined, device: QADevice): QADevice[];
+/**
+ * TOGGLE a device approval (0.3.1): clicking an approved device UNSETS it;
+ * clicking an unapproved one approves it. Returns the resulting device set +
+ * which action happened, so the caller can decide whether the item completed
+ * or fell back to pending.
+ */
+export declare function toggleDevice(effectiveApproved: readonly QADevice[], device: QADevice): {
+    devices: QADevice[];
+    action: "approve" | "unset";
+};
+/** Best-effort current-device detection (visual hint only - never a gate). */
+export declare function detectDevice(): QADevice;

package/dist/client/device.js

@@ -0,0 +1,57 @@
+"use client";
+export const DEVICE_LABEL = { pc: "PC", mobile: "Mobile" };
+export const DEVICE_TOOLTIP = {
+    pc: "review on PC",
+    mobile: "review on mobile",
+};
+/** Required review devices for an item. Default: PC only. */
+export function requiredDevices(item) {
+    return item.devices && item.devices.length ? item.devices : ["pc"];
+}
+/** Devices already approved on a ledger entry. */
+export function approvedDevicesOf(entry) {
+    return (entry?.approvedDevices ?? []).filter((d) => d === "pc" || d === "mobile");
+}
+/**
+ * Fully approved = a recorded whole-item approval (incl. grandfathered plain
+ * approvals with no device data) OR every required device approved.
+ */
+export function isFullyApproved(entry, required) {
+    if (!entry)
+        return false;
+    if (entry.verdict === "approve")
+        return true; // grandfathered / completed
+    if (entry.verdict === "reject")
+        return false;
+    const have = approvedDevicesOf(entry);
+    return required.length > 0 && required.every((d) => have.includes(d));
+}
+/** Union of already-approved devices + a new approval. */
+export function nextApprovedDevices(entry, device) {
+    const have = approvedDevicesOf(entry);
+    return have.includes(device) ? have : [...have, device];
+}
+/**
+ * TOGGLE a device approval (0.3.1): clicking an approved device UNSETS it;
+ * clicking an unapproved one approves it. Returns the resulting device set +
+ * which action happened, so the caller can decide whether the item completed
+ * or fell back to pending.
+ */
+export function toggleDevice(effectiveApproved, device) {
+    if (effectiveApproved.includes(device)) {
+        return { devices: effectiveApproved.filter((d) => d !== device), action: "unset" };
+    }
+    return { devices: [...effectiveApproved, device], action: "approve" };
+}
+/** Best-effort current-device detection (visual hint only - never a gate). */
+export function detectDevice() {
+    try {
+        if (typeof navigator !== "undefined" && /Mobi|Android|iPhone|iPad|iPod/i.test(navigator.userAgent)) {
+            return "mobile";
+        }
+    }
+    catch {
+        /* default below */
+    }
+    return "pc";
+}

package/dist/client/fingerprint.d.ts

@@ -0,0 +1,19 @@
+import type { QAReviewItem } from "./types.js";
+/** Collapse all whitespace runs so formatting-only DOM churn doesn't count. */
+export declare function normalizeText(text: string): string;
+/** Deterministic fingerprint of a text blob (normalized FNV-1a, hex). */
+export declare function fingerprintText(text: string): string;
+/**
+ * Fingerprint the CURRENT content of an item: anchored items hash the
+ * element's rendered innerText; off-DOM task items hash their question text
+ * (sub, falling back to title). Returns null when the anchor is not present
+ * (e.g. other-viewport element) - no judgement is made then.
+ */
+export declare function itemFingerprint(item: QAReviewItem, doc: Document): string | null;
+export type FingerprintStatus = "unchanged" | "changed";
+/**
+ * Compare the fingerprint STORED with the last verdict against the current
+ * one. Null when either side is unknown (no stored fp / anchor missing) - the
+ * badge only ever asserts what the system actually measured.
+ */
+export declare function fingerprintStatus(stored: string | null | undefined, current: string | null | undefined): FingerprintStatus | null;

package/dist/client/fingerprint.js

@@ -0,0 +1,40 @@
+"use client";
+// NOT-ALTERED poka-yoke: a content fingerprint is stored with every verdict.
+// When a previously-REJECTED item comes up again and the page content still
+// fingerprints the same, the card shows a SYSTEM-COMPUTED "NOT ALTERED since
+// your rejection" badge - judged by hashing, never by the operating agent, so
+// the reviewer instantly sees nothing was worked on. A differing fingerprint
+// shows a subtle "changed since last review" hint instead.
+import { fnv1a } from "../shared/codename.js";
+/** Collapse all whitespace runs so formatting-only DOM churn doesn't count. */
+export function normalizeText(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** Deterministic fingerprint of a text blob (normalized FNV-1a, hex). */
+export function fingerprintText(text) {
+    return fnv1a(normalizeText(text)).toString(16).padStart(8, "0");
+}
+/**
+ * Fingerprint the CURRENT content of an item: anchored items hash the
+ * element's rendered innerText; off-DOM task items hash their question text
+ * (sub, falling back to title). Returns null when the anchor is not present
+ * (e.g. other-viewport element) - no judgement is made then.
+ */
+export function itemFingerprint(item, doc) {
+    if (!item.selector)
+        return fingerprintText(item.sub ?? item.title);
+    const el = doc.querySelector(item.selector);
+    if (!el)
+        return null;
+    return fingerprintText(el.innerText ?? el.textContent ?? "");
+}
+/**
+ * Compare the fingerprint STORED with the last verdict against the current
+ * one. Null when either side is unknown (no stored fp / anchor missing) - the
+ * badge only ever asserts what the system actually measured.
+ */
+export function fingerprintStatus(stored, current) {
+    if (!stored || !current)
+        return null;
+    return stored === current ? "unchanged" : "changed";
+}

package/dist/client/highlight.d.ts

@@ -0,0 +1,17 @@
+export interface MatchRange {
+    start: number;
+    end: number;
+}
+/**
+ * Case-insensitive, all-occurrence match ranges of the phrases inside a text.
+ * Overlapping later matches are dropped so ranges never intersect. Pure and
+ * unit-tested; the DOM wrapper below applies the same logic per text node.
+ */
+export declare function findMatchRanges(text: string, phrases: readonly string[]): MatchRange[];
+/**
+ * Wrap phrase matches inside the element's text nodes with <mark> elements.
+ * Matches are found WITHIN single text nodes (phrases spanning element
+ * boundaries are not wrapped - keep highlight phrases short). Returns a
+ * cleanup function that fully restores the original DOM.
+ */
+export declare function applySubHighlights(el: HTMLElement, phrases: readonly string[]): () => void;

package/dist/client/highlight.js

@@ -0,0 +1,77 @@
+"use client";
+/**
+ * Case-insensitive, all-occurrence match ranges of the phrases inside a text.
+ * Overlapping later matches are dropped so ranges never intersect. Pure and
+ * unit-tested; the DOM wrapper below applies the same logic per text node.
+ */
+export function findMatchRanges(text, phrases) {
+    const hay = text.toLowerCase();
+    const ranges = [];
+    for (const raw of phrases) {
+        const needle = raw.toLowerCase().trim();
+        if (!needle)
+            continue;
+        let from = 0;
+        for (;;) {
+            const at = hay.indexOf(needle, from);
+            if (at === -1)
+                break;
+            ranges.push({ start: at, end: at + needle.length });
+            from = at + needle.length;
+        }
+    }
+    ranges.sort((a, b) => a.start - b.start || b.end - a.end);
+    const out = [];
+    for (const r of ranges) {
+        const last = out[out.length - 1];
+        if (last && r.start < last.end)
+            continue; // drop overlaps
+        out.push(r);
+    }
+    return out;
+}
+const MARK_CLASS = "qar-subhl";
+/**
+ * Wrap phrase matches inside the element's text nodes with <mark> elements.
+ * Matches are found WITHIN single text nodes (phrases spanning element
+ * boundaries are not wrapped - keep highlight phrases short). Returns a
+ * cleanup function that fully restores the original DOM.
+ */
+export function applySubHighlights(el, phrases) {
+    const doc = el.ownerDocument;
+    const walker = doc.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+    const textNodes = [];
+    for (let n = walker.nextNode(); n; n = walker.nextNode())
+        textNodes.push(n);
+    const marks = [];
+    for (const node of textNodes) {
+        const text = node.nodeValue ?? "";
+        const ranges = findMatchRanges(text, phrases);
+        if (!ranges.length)
+            continue;
+        const frag = doc.createDocumentFragment();
+        let cursor = 0;
+        for (const r of ranges) {
+            if (r.start > cursor)
+                frag.appendChild(doc.createTextNode(text.slice(cursor, r.start)));
+            const mark = doc.createElement("mark");
+            mark.className = MARK_CLASS;
+            mark.textContent = text.slice(r.start, r.end);
+            frag.appendChild(mark);
+            marks.push(mark);
+            cursor = r.end;
+        }
+        if (cursor < text.length)
+            frag.appendChild(doc.createTextNode(text.slice(cursor)));
+        node.parentNode?.replaceChild(frag, node);
+    }
+    return () => {
+        for (const mark of marks) {
+            const parent = mark.parentNode;
+            if (!parent)
+                continue;
+            parent.replaceChild(doc.createTextNode(mark.textContent ?? ""), mark);
+            parent.normalize();
+        }
+    };
+}

package/dist/client/index.d.ts

@@ -0,0 +1,12 @@
+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 { 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";
+export { describeRevisit, type RevisitInfo, type RevisitDisplay } from "./revisit.js";
+export { buildMobilePreviewUrl, isEmbeddedPreview, postVariantToPreview, parseVariantMessage, MOBILE_PREVIEW_WIDTH, MOBILE_PREVIEW_HEIGHT, PREVIEW_MARKER_PARAM, PREVIEW_MESSAGE_TYPE, type VariantMessage, } from "./preview.js";
+export { codenameFor, findByCodename, formatQARef, fnv1a, type CodenameEntry, } from "../shared/codename.js";
+export { ensureQAStyles } from "./styles.js";
+export { isTaskItem } from "./types.js";
+export type { QAReviewItem, QAReviewDevice, QAResult, QAVerdict, QASubmission, QATheme, } from "./types.js";

package/dist/client/index.js

@@ -0,0 +1,11 @@
+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 { 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";
+export { describeRevisit } from "./revisit.js";
+export { buildMobilePreviewUrl, isEmbeddedPreview, postVariantToPreview, parseVariantMessage, MOBILE_PREVIEW_WIDTH, MOBILE_PREVIEW_HEIGHT, PREVIEW_MARKER_PARAM, PREVIEW_MESSAGE_TYPE, } from "./preview.js";
+export { codenameFor, findByCodename, formatQARef, fnv1a, } from "../shared/codename.js";
+export { ensureQAStyles } from "./styles.js";
+export { isTaskItem } from "./types.js";

package/dist/client/journey.d.ts

@@ -0,0 +1,89 @@
+import type { VerdictMap } from "./store.js";
+export interface QAJourneyPage {
+    /** Pathname to navigate to (e.g. "/pricing"). */
+    path: string;
+    /** Ledger bucket for that page (e.g. "example-site:/pricing"). */
+    target: string;
+    /** Human label for the journey summary. Default: path. */
+    label?: string;
+    /** ALL reviewable item ids on that page (pending = not approved in ledger). */
+    itemIds: string[];
+}
+export interface QAJourneyConfig {
+    /** Ordered pages of the review journey. */
+    pages: QAJourneyPage[];
+}
+/** Index of the journey page whose target matches, or -1. */
+export declare function journeyIndex(pages: readonly QAJourneyPage[], target: string): number;
+/**
+ * ROUND-pending = items NOT approved in the ledger map (unreviewed OR
+ * rejected) - the overlay's round-freeze rule: rejected items re-present in
+ * FUTURE rounds. An empty/missing map counts every item as pending.
+ */
+export declare function countPending(itemIds: readonly string[], map: VerdictMap | null | undefined): number;
+/**
+ * NAVIGATION-pending (0.3.2 fix) = items the reviewer has not TOUCHED yet:
+ * no verdict AND no device approvals recorded. Approve, reject, AND partial
+ * device states all count as HANDLED for the current run's navigation -
+ * 🚨 counting fresh REJECTS as pending made the journey ping-pong forever
+ * between a rejected page and the next one (wraparound kept returning to the
+ * rejects). Rejected items still re-enter FUTURE rounds via countPending /
+ * the round freeze - they just never re-enter THIS run's walkthrough.
+ */
+export declare function countUnverdicted(itemIds: readonly string[], map: VerdictMap | null | undefined): number;
+/**
+ * Next journey page (excluding the current one) with pending items: searches
+ * FORWARD from the current page and wraps around, so a mid-journey start still
+ * covers earlier pages. Returns null when the whole journey is clean. Feed it
+ * NAVIGATION-pending counts (countUnverdicted) - never round counts, or pages
+ * with fresh rejects bounce the walkthrough back forever.
+ */
+export declare function nextPendingPage(pages: readonly QAJourneyPage[], pendingByTarget: Readonly<Record<string, number>>, currentIndex: number): QAJourneyPage | null;
+/**
+ * What the finished-state UI shows in a journey (0.3.1): an UNMISTAKABLE
+ * loading indicator from the moment the round exhausts until the next page
+ * unloads this one - never a blank screen (a reviewer almost exited thinking the
+ * review was done) - or the journey-complete panel.
+ */
+export declare function journeyFinishView(inJourney: boolean, journeyComplete: boolean): "standard" | "loading" | "complete";
+export type FinishAction = {
+    kind: "navigate";
+    page: QAJourneyPage;
+} | {
+    kind: "journey-complete";
+};
+/**
+ * What happens the moment a page's round is exhausted: navigate IMMEDIATELY
+ * to the next page with pending items (no interstitial, no success popup), or
+ * show the journey-complete panel when nothing is pending anywhere.
+ */
+export declare function resolveFinishAction(pages: readonly QAJourneyPage[], pendingByTarget: Readonly<Record<string, number>>, currentIndex: number): FinishAction;
+/**
+ * Build the navigation URL for a journey hop, preserving the current page's
+ * query params (QA gate param, auth key, ...) so activation survives the full
+ * page load. The per-page `target` override is dropped - the arriving page
+ * derives its own bucket.
+ */
+export declare function buildJourneyNavUrl(path: string, currentSearch: string): string;
+/** Within how many final round items the journey prefetch kicks in. */
+export declare const PREFETCH_WINDOW_ITEMS = 2;
+/** Prefetched counts older than this are considered stale. */
+export declare const PREFETCH_MAX_AGE_MS = 30000;
+/** Should the background prefetch start? (within the final N round items) */
+export declare function shouldPrefetch(index: number, roundTotal: number, windowItems?: number): boolean;
+/** Is a prefetched result still fresh enough to navigate on? */
+export declare function isPrefetchFresh(fetchedAt: number, now: number, maxAgeMs?: number): boolean;
+/**
+ * Warm the next journey page: add an idempotent <link rel="prefetch"> for the
+ * nav URL so the browser can fetch the document ahead of the hop. Best-effort
+ * hint - browsers may ignore it.
+ */
+export declare function ensurePrefetchLink(doc: Document, href: string): void;
+/**
+ * Fetch the ledger for every journey page (one state GET per target) and
+ * return NAVIGATION-pending counts (unverdicted items - see countUnverdicted;
+ * rejected/partial items are handled-this-run and must not re-attract
+ * navigation). A failed fetch counts that page's items as pending (never lose
+ * a page silently).
+ */
+export declare function fetchPendingCounts(stateUrl: string, pages: readonly QAJourneyPage[]): Promise<Record<string, number>>;

package/dist/client/journey.js

@@ -0,0 +1,134 @@
+// Cross-page journey support: pure helpers (unit-tested) used by the overlay
+// to compute per-page pending counts from the durable ledger, pick the next
+// page that still needs review, and build navigation URLs that PRESERVE the
+// QA activation params (gate param, auth key, etc.) across a full page load.
+/** Index of the journey page whose target matches, or -1. */
+export function journeyIndex(pages, target) {
+    return pages.findIndex((p) => p.target === target);
+}
+/**
+ * ROUND-pending = items NOT approved in the ledger map (unreviewed OR
+ * rejected) - the overlay's round-freeze rule: rejected items re-present in
+ * FUTURE rounds. An empty/missing map counts every item as pending.
+ */
+export function countPending(itemIds, map) {
+    return itemIds.filter((id) => map?.[id]?.verdict !== "approve").length;
+}
+/**
+ * NAVIGATION-pending (0.3.2 fix) = items the reviewer has not TOUCHED yet:
+ * no verdict AND no device approvals recorded. Approve, reject, AND partial
+ * device states all count as HANDLED for the current run's navigation -
+ * 🚨 counting fresh REJECTS as pending made the journey ping-pong forever
+ * between a rejected page and the next one (wraparound kept returning to the
+ * rejects). Rejected items still re-enter FUTURE rounds via countPending /
+ * the round freeze - they just never re-enter THIS run's walkthrough.
+ */
+export function countUnverdicted(itemIds, map) {
+    return itemIds.filter((id) => {
+        const e = map?.[id];
+        return !e?.verdict && !e?.approvedDevices?.length;
+    }).length;
+}
+/**
+ * Next journey page (excluding the current one) with pending items: searches
+ * FORWARD from the current page and wraps around, so a mid-journey start still
+ * covers earlier pages. Returns null when the whole journey is clean. Feed it
+ * NAVIGATION-pending counts (countUnverdicted) - never round counts, or pages
+ * with fresh rejects bounce the walkthrough back forever.
+ */
+export function nextPendingPage(pages, pendingByTarget, currentIndex) {
+    for (let step = 1; step < pages.length; step++) {
+        const p = pages[(currentIndex + step + pages.length) % pages.length];
+        if ((pendingByTarget[p.target] ?? 0) > 0)
+            return p;
+    }
+    return null;
+}
+/**
+ * What the finished-state UI shows in a journey (0.3.1): an UNMISTAKABLE
+ * loading indicator from the moment the round exhausts until the next page
+ * unloads this one - never a blank screen (a reviewer almost exited thinking the
+ * review was done) - or the journey-complete panel.
+ */
+export function journeyFinishView(inJourney, journeyComplete) {
+    if (!inJourney)
+        return "standard";
+    return journeyComplete ? "complete" : "loading";
+}
+/**
+ * What happens the moment a page's round is exhausted: navigate IMMEDIATELY
+ * to the next page with pending items (no interstitial, no success popup), or
+ * show the journey-complete panel when nothing is pending anywhere.
+ */
+export function resolveFinishAction(pages, pendingByTarget, currentIndex) {
+    const page = nextPendingPage(pages, pendingByTarget, currentIndex);
+    return page ? { kind: "navigate", page } : { kind: "journey-complete" };
+}
+/**
+ * Build the navigation URL for a journey hop, preserving the current page's
+ * query params (QA gate param, auth key, ...) so activation survives the full
+ * page load. The per-page `target` override is dropped - the arriving page
+ * derives its own bucket.
+ */
+export function buildJourneyNavUrl(path, currentSearch) {
+    const params = new URLSearchParams(currentSearch);
+    params.delete("target");
+    const qs = params.toString();
+    return qs ? `${path}?${qs}` : path;
+}
+/** Within how many final round items the journey prefetch kicks in. */
+export const PREFETCH_WINDOW_ITEMS = 2;
+/** Prefetched counts older than this are considered stale. */
+export const PREFETCH_MAX_AGE_MS = 30_000;
+/** Should the background prefetch start? (within the final N round items) */
+export function shouldPrefetch(index, roundTotal, windowItems = PREFETCH_WINDOW_ITEMS) {
+    return roundTotal > 0 && roundTotal - index <= windowItems;
+}
+/** Is a prefetched result still fresh enough to navigate on? */
+export function isPrefetchFresh(fetchedAt, now, maxAgeMs = PREFETCH_MAX_AGE_MS) {
+    return now - fetchedAt >= 0 && now - fetchedAt < maxAgeMs;
+}
+/**
+ * Warm the next journey page: add an idempotent <link rel="prefetch"> for the
+ * nav URL so the browser can fetch the document ahead of the hop. Best-effort
+ * hint - browsers may ignore it.
+ */
+export function ensurePrefetchLink(doc, href) {
+    const existing = Array.from(doc.querySelectorAll('link[data-qar-prefetch="1"]'));
+    if (existing.some((l) => l.getAttribute("href") === href))
+        return;
+    const link = doc.createElement("link");
+    link.rel = "prefetch";
+    link.href = href;
+    link.as = "document";
+    link.setAttribute("data-qar-prefetch", "1");
+    doc.head.appendChild(link);
+}
+/**
+ * Fetch the ledger for every journey page (one state GET per target) and
+ * return NAVIGATION-pending counts (unverdicted items - see countUnverdicted;
+ * rejected/partial items are handled-this-run and must not re-attract
+ * navigation). A failed fetch counts that page's items as pending (never lose
+ * a page silently).
+ */
+export async function fetchPendingCounts(stateUrl, pages) {
+    const out = {};
+    await Promise.all(pages.map(async (p) => {
+        let map = null;
+        try {
+            const r = await fetch(`${stateUrl}?target=${encodeURIComponent(p.target)}`, {
+                cache: "no-store",
+            });
+            if (r.ok) {
+                const d = (await r.json());
+                if (d?.ok && d.verdicts)
+                    map = d.verdicts;
+            }
+        }
+        catch {
+            map = null;
+        }
+        out[p.target] = countUnverdicted(p.itemIds, map);
+    }));
+    return out;
+}

package/dist/client/preview.d.ts

@@ -0,0 +1,30 @@
+/** Phone frame dimensions (iPhone-ish portrait). */
+export declare const MOBILE_PREVIEW_WIDTH = 390;
+export declare const MOBILE_PREVIEW_HEIGHT = 844;
+/** Marker param: an overlay whose URL carries it never activates. */
+export declare const PREVIEW_MARKER_PARAM = "qaMobilePreview";
+/** Current URL with the embed marker appended (QA params preserved). */
+export declare function buildMobilePreviewUrl(href: string): string;
+/** True when THIS document is the embedded preview (overlay must not mount). */
+export declare function isEmbeddedPreview(search: string): boolean;
+/**
+ * Scroll the preview iframe so `selector` is centred in the phone frame.
+ *
+ * Returns a cleanup function that cancels any pending retries, so a caller that
+ * switches items mid-flight does not have two scroll loops fighting.
+ *
+ * A missing element is NOT an error: plenty of items are desktop-only, and the
+ * overlay already surfaces "target not on this viewport" separately. We simply
+ * keep retrying until the attempts run out, in case it is merely late.
+ */
+export declare function scrollPreviewToSelector(iframe: HTMLIFrameElement | null, selector: string | undefined): () => void;
+export declare const PREVIEW_MESSAGE_TYPE = "qa-review:variant";
+export interface VariantMessage {
+    type: typeof PREVIEW_MESSAGE_TYPE;
+    itemId: string;
+    variant: number;
+}
+/** Post a variant change to the open preview iframe (same-origin). */
+export declare function postVariantToPreview(iframe: HTMLIFrameElement | null, itemId: string, variant: number): void;
+/** Parse a message event into a VariantMessage, or null if it isn't one. */
+export declare function parseVariantMessage(data: unknown): VariantMessage | null;

package/dist/client/preview.js

@@ -0,0 +1,116 @@
+"use client";
+// Mobile preview (0.3.5): render the CURRENT page in a phone-sized, framed
+// same-origin iframe on a dimmed backdrop, so "Approve Mobile" can be
+// exercised on desktop without devtools. The iframe URL keeps the QA
+// activation params but adds a marker param that tells the overlay INSIDE the
+// iframe to stay dormant (no nested review chrome).
+/** Phone frame dimensions (iPhone-ish portrait). */
+export const MOBILE_PREVIEW_WIDTH = 390;
+export const MOBILE_PREVIEW_HEIGHT = 844;
+/** Marker param: an overlay whose URL carries it never activates. */
+export const PREVIEW_MARKER_PARAM = "qaMobilePreview";
+/** Current URL with the embed marker appended (QA params preserved). */
+export function buildMobilePreviewUrl(href) {
+    const url = new URL(href);
+    url.searchParams.set(PREVIEW_MARKER_PARAM, "1");
+    return url.toString();
+}
+/** True when THIS document is the embedded preview (overlay must not mount). */
+export function isEmbeddedPreview(search) {
+    try {
+        return new URLSearchParams(search).has(PREVIEW_MARKER_PARAM);
+    }
+    catch {
+        return false;
+    }
+}
+/* --------------------------- scroll-to-item ------------------------------- */
+// 0.3.7 fix: the preview iframe loads the page at its TOP, so opening the phone
+// frame showed the header instead of the section under review - the reviewer had
+// to hunt for it by hand, on every item (a reviewer, 2026-07-30, reported twice).
+//
+// The frame is same-origin, so the parent can reach into its document directly.
+// We retry rather than scroll once: the iframe fires `load` before Next.js has
+// hydrated and before images have settled, and an early scroll gets undone by
+// the layout shift that follows.
+/** How many attempts, and how far apart, to land the scroll. */
+const SCROLL_ATTEMPTS = 12;
+const SCROLL_INTERVAL_MS = 120;
+/**
+ * Scroll the preview iframe so `selector` is centred in the phone frame.
+ *
+ * Returns a cleanup function that cancels any pending retries, so a caller that
+ * switches items mid-flight does not have two scroll loops fighting.
+ *
+ * A missing element is NOT an error: plenty of items are desktop-only, and the
+ * overlay already surfaces "target not on this viewport" separately. We simply
+ * keep retrying until the attempts run out, in case it is merely late.
+ */
+export function scrollPreviewToSelector(iframe, selector) {
+    if (!iframe || !selector)
+        return () => { };
+    let attempts = 0;
+    let timer;
+    let cancelled = false;
+    const tick = () => {
+        if (cancelled)
+            return;
+        attempts += 1;
+        try {
+            const doc = iframe.contentDocument;
+            const el = doc?.querySelector(selector);
+            if (el) {
+                // "center" keeps a tall section's top edge visible in a 844px frame,
+                // which "start" does not once a sticky header is in play.
+                el.scrollIntoView({ behavior: "auto", block: "center", inline: "nearest" });
+                // Keep going a couple more rounds: late-loading images below the fold
+                // routinely shove the target back off screen after a correct scroll.
+                if (attempts >= 3)
+                    return;
+            }
+        }
+        catch {
+            /* cross-origin or frame torn down mid-flight: nothing to do */
+        }
+        if (attempts < SCROLL_ATTEMPTS)
+            timer = setTimeout(tick, SCROLL_INTERVAL_MS);
+    };
+    tick();
+    return () => {
+        cancelled = true;
+        if (timer)
+            clearTimeout(timer);
+    };
+}
+/* ------------------------- live variant propagation ------------------------ */
+// When the phone-frame preview is OPEN and the reviewer picks a different
+// variation, the variant must apply INSIDE the iframe document without a
+// close+reopen. The parent posts the variant to the same-origin iframe; the
+// embedded (dormant) overlay applies it by running the consumer's own
+// variation callback there - so the DOM mutation executes in the iframe's
+// document, not just the parent.
+export const PREVIEW_MESSAGE_TYPE = "qa-review:variant";
+/** Post a variant change to the open preview iframe (same-origin). */
+export function postVariantToPreview(iframe, itemId, variant) {
+    const win = iframe?.contentWindow;
+    if (!win)
+        return;
+    const msg = { type: PREVIEW_MESSAGE_TYPE, itemId, variant };
+    try {
+        win.postMessage(msg, window.location.origin);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Parse a message event into a VariantMessage, or null if it isn't one. */
+export function parseVariantMessage(data) {
+    if (data &&
+        typeof data === "object" &&
+        data.type === PREVIEW_MESSAGE_TYPE &&
+        typeof data.itemId === "string" &&
+        typeof data.variant === "number") {
+        return data;
+    }
+    return null;
+}