@artymclabin/qa-review 0.3.7

package/dist/client/revisit.d.ts

@@ -0,0 +1,28 @@
+import type { FingerprintStatus } from "./fingerprint.js";
+export interface RevisitInfo {
+    /** Why the item was re-queued (set by the invalidation call). */
+    reason?: string;
+    /** The reviewer's verdict before invalidation. */
+    prevVerdict?: string;
+    /** The reviewer's note from that prior verdict. */
+    prevNote?: string;
+}
+export interface RevisitDisplay {
+    /** Prominent "Back for review: ..." headline (reason, or generic change note). */
+    headline: string | null;
+    /** "Your last verdict: reject - "note"" context line. */
+    prior: string | null;
+    /** Show the prominent NOT-ALTERED badge (prior REJECT + identical content). */
+    notAltered: boolean;
+}
+/**
+ * Pure display logic for a re-queued item. Rules:
+ * - 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;
+ * - prior REJECT + UNCHANGED fingerprint keeps the system-computed
+ *   NOT-ALTERED badge (reason or not - the reviewer must see nothing moved).
+ */
+export declare function describeRevisit(info: RevisitInfo | undefined, fpStatus: FingerprintStatus | null): RevisitDisplay | null;

package/dist/client/revisit.js

@@ -0,0 +1,27 @@
+"use client";
+/**
+ * Pure display logic for a re-queued item. Rules:
+ * - 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;
+ * - prior REJECT + UNCHANGED fingerprint keeps the system-computed
+ *   NOT-ALTERED badge (reason or not - the reviewer must see nothing moved).
+ */
+export function describeRevisit(info, fpStatus) {
+    if (!info)
+        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 notAltered = fpStatus === "unchanged" && info.prevVerdict === "reject";
+    if (!headline && !prior && !notAltered)
+        return null;
+    return { headline, prior, notAltered };
+}

package/dist/client/store.d.ts

@@ -0,0 +1,100 @@
+import type { QAVerdict } from "./types.js";
+export interface PersistedVerdict {
+    verdict?: QAVerdict;
+    variant?: number;
+    note?: string;
+    /** Content fingerprint at verdict time (NOT-ALTERED poka-yoke). */
+    fp?: string;
+    /** Per-device approvals ("pc"/"mobile") for device-split items. */
+    approvedDevices?: string[];
+    /** Server-computed codename (present in state GET responses; read-only). */
+    codename?: string;
+    /** Why the item was re-queued (set via invalidation; read-only here). */
+    revisitReason?: string;
+    /** Verdict in effect before the invalidation (read-only here). */
+    prevVerdict?: string;
+}
+/** item id -> persisted verdict/variant/note. */
+export type VerdictMap = Record<string, PersistedVerdict>;
+/** One queued server write. `patch: null` = delete (undo / invalidation). */
+export interface PendingOp {
+    itemId: string;
+    patch: PersistedVerdict | null;
+}
+export interface QAStoreOptions {
+    /** Review bucket this store reads/writes (e.g. "example-site:/pricing"). */
+    target: string;
+    /** State endpoint URL. Default "/api/qa/state". */
+    stateUrl?: string;
+    /** localStorage key builder. Default: target-suffixed generic key. */
+    storageKey?: (target: string) => string;
+    /** Debounce for real-time note persistence, ms. Default 600. */
+    noteDebounceMs?: number;
+}
+/**
+ * Per-target verdict store. Construct one per review bucket; the overlay
+ * creates its own from props, and page wrappers may construct an identical one
+ * to persist variant picks outside the overlay.
+ */
+export declare class QAStore {
+    readonly target: string;
+    private readonly stateUrl;
+    private readonly key;
+    private readonly pendingKey;
+    private readonly noteDebounceMs;
+    private flushing;
+    private noteTimers;
+    constructor(opts: QAStoreOptions);
+    /**
+     * Load the local verdict map. Returns an empty map (every item unreviewed)
+     * when the key was never written or is unparseable. NEVER seeds approvals.
+     */
+    load(): VerdictMap;
+    save(map: VerdictMap): void;
+    /** Merge-write a single item's fields locally (read-modify-write). */
+    persistLocal(id: string, patch: PersistedVerdict): void;
+    /** Delete a single item's verdict locally (undo). */
+    removeLocal(id: string): void;
+    /** Read the persisted pending-op queue. */
+    pendingOps(): PendingOp[];
+    private savePending;
+    /** POST one op to the state endpoint. Resolves false on any failure. */
+    private sendOp;
+    /**
+     * Replay the pending queue in order; stops at the first failure (the rest
+     * retries on the next action). Concurrency-guarded so parallel triggers
+     * cannot double-send.
+     */
+    flush(): Promise<void>;
+    /** Enqueue one op (persisted) and immediately try to flush the queue. */
+    private enqueue;
+    /**
+     * Merge-write one item locally AND to the server ledger in REAL TIME.
+     * The write is queued+flushed, so a failure is retried on the next action.
+     */
+    persist(id: string, patch: PersistedVerdict): void;
+    /** Merge-write a single item's chosen variant only (local + server). */
+    persistVariant(id: string, variant: number): void;
+    /**
+     * Real-time note persistence, debounced (default 600ms after the last
+     * keystroke). An empty note clears the stored note.
+     */
+    persistNoteDebounced(id: string, note: string): void;
+    /** Cancel a pending debounced note write (e.g. a verdict is about to carry it). */
+    cancelPendingNote(id: string): void;
+    /** Undo: delete one item's verdict locally AND on the server (verdict: null). */
+    remove(id: string): void;
+    /**
+     * Read the durable server verdict map. Flushes the pending queue first and
+     * replays any STILL-pending ops over the result, so an offline verdict is
+     * never clobbered by hydration. Returns null if the server is unavailable.
+     */
+    serverLoad(): Promise<VerdictMap | null>;
+}
+/** Convenience factory (equivalent to `new QAStore(opts)`). */
+export declare function createQAStore(opts: QAStoreOptions): QAStore;
+/**
+ * Read a `?target=` override from the current URL (useful for isolating E2E
+ * runs from the real review bucket). Falls back to the given default.
+ */
+export declare function targetFromLocation(defaultTarget: string): string;

package/dist/client/store.js

@@ -0,0 +1,234 @@
+"use client";
+const DEFAULT_STATE_URL = "/api/qa/state";
+const defaultStorageKey = (target) => `qa-review-verdicts:${target}`;
+function hasStorage() {
+    try {
+        return typeof window !== "undefined" && !!window.localStorage;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Per-target verdict store. Construct one per review bucket; the overlay
+ * creates its own from props, and page wrappers may construct an identical one
+ * to persist variant picks outside the overlay.
+ */
+export class QAStore {
+    target;
+    stateUrl;
+    key;
+    pendingKey;
+    noteDebounceMs;
+    flushing = false;
+    noteTimers = new Map();
+    constructor(opts) {
+        this.target = opts.target;
+        this.stateUrl = opts.stateUrl ?? DEFAULT_STATE_URL;
+        this.key = (opts.storageKey ?? defaultStorageKey)(opts.target);
+        this.pendingKey = `${this.key}::pending`;
+        this.noteDebounceMs = opts.noteDebounceMs ?? 600;
+    }
+    /* ------------------------------ local cache ------------------------------ */
+    /**
+     * Load the local verdict map. Returns an empty map (every item unreviewed)
+     * when the key was never written or is unparseable. NEVER seeds approvals.
+     */
+    load() {
+        if (!hasStorage())
+            return {};
+        const raw = window.localStorage.getItem(this.key);
+        if (raw === null)
+            return {};
+        try {
+            const parsed = JSON.parse(raw);
+            return parsed && typeof parsed === "object" ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    save(map) {
+        if (!hasStorage())
+            return;
+        window.localStorage.setItem(this.key, JSON.stringify(map));
+    }
+    /** Merge-write a single item's fields locally (read-modify-write). */
+    persistLocal(id, patch) {
+        const map = this.load();
+        map[id] = { ...map[id], ...patch };
+        this.save(map);
+    }
+    /** Delete a single item's verdict locally (undo). */
+    removeLocal(id) {
+        if (!hasStorage())
+            return;
+        const map = this.load();
+        delete map[id];
+        this.save(map);
+    }
+    /* ----------------------- write-behind pending queue ----------------------- */
+    // Every server write goes through this queue. On success it drains
+    // immediately (real-time); on failure the ops stay (persisted in
+    // localStorage so they survive a reload) and are replayed IN ORDER before
+    // any later server interaction. A verdict is never lost silently.
+    /** Read the persisted pending-op queue. */
+    pendingOps() {
+        if (!hasStorage())
+            return [];
+        const raw = window.localStorage.getItem(this.pendingKey);
+        if (raw === null)
+            return [];
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    savePending(ops) {
+        if (!hasStorage())
+            return;
+        if (ops.length === 0)
+            window.localStorage.removeItem(this.pendingKey);
+        else
+            window.localStorage.setItem(this.pendingKey, JSON.stringify(ops));
+    }
+    /** POST one op to the state endpoint. Resolves false on any failure. */
+    async sendOp(op) {
+        try {
+            const body = op.patch === null
+                ? { target: this.target, itemId: op.itemId, verdict: null }
+                : { target: this.target, itemId: op.itemId, ...op.patch };
+            const r = await fetch(this.stateUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+            });
+            return r.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Replay the pending queue in order; stops at the first failure (the rest
+     * retries on the next action). Concurrency-guarded so parallel triggers
+     * cannot double-send.
+     */
+    async flush() {
+        if (this.flushing)
+            return;
+        this.flushing = true;
+        try {
+            let ops = this.pendingOps();
+            while (ops.length) {
+                const ok = await this.sendOp(ops[0]);
+                if (!ok)
+                    break; // offline / server down: keep the queue, retry later
+                ops = this.pendingOps().slice(1); // re-read: actions may have enqueued
+                this.savePending(ops);
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /** Enqueue one op (persisted) and immediately try to flush the queue. */
+    enqueue(op) {
+        this.savePending([...this.pendingOps(), op]);
+        void this.flush();
+    }
+    /* ----------------------------- real-time API ------------------------------ */
+    /**
+     * Merge-write one item locally AND to the server ledger in REAL TIME.
+     * The write is queued+flushed, so a failure is retried on the next action.
+     */
+    persist(id, patch) {
+        this.persistLocal(id, patch);
+        this.enqueue({ itemId: id, patch });
+    }
+    /** Merge-write a single item's chosen variant only (local + server). */
+    persistVariant(id, variant) {
+        this.persist(id, { variant });
+    }
+    /**
+     * Real-time note persistence, debounced (default 600ms after the last
+     * keystroke). An empty note clears the stored note.
+     */
+    persistNoteDebounced(id, note) {
+        const t = this.noteTimers.get(id);
+        if (t)
+            clearTimeout(t);
+        this.noteTimers.set(id, setTimeout(() => {
+            this.noteTimers.delete(id);
+            this.persist(id, { note: note.trim() });
+        }, this.noteDebounceMs));
+    }
+    /** Cancel a pending debounced note write (e.g. a verdict is about to carry it). */
+    cancelPendingNote(id) {
+        const t = this.noteTimers.get(id);
+        if (t) {
+            clearTimeout(t);
+            this.noteTimers.delete(id);
+        }
+    }
+    /** Undo: delete one item's verdict locally AND on the server (verdict: null). */
+    remove(id) {
+        this.cancelPendingNote(id);
+        this.removeLocal(id);
+        this.enqueue({ itemId: id, patch: null });
+    }
+    /* ------------------------------ server read ------------------------------- */
+    /**
+     * Read the durable server verdict map. Flushes the pending queue first and
+     * replays any STILL-pending ops over the result, so an offline verdict is
+     * never clobbered by hydration. Returns null if the server is unavailable.
+     */
+    async serverLoad() {
+        await this.flush();
+        let map = null;
+        try {
+            const r = await fetch(`${this.stateUrl}?target=${encodeURIComponent(this.target)}`, {
+                cache: "no-store",
+            });
+            if (r.ok) {
+                const d = (await r.json());
+                if (d?.ok && d.verdicts)
+                    map = d.verdicts;
+            }
+        }
+        catch {
+            map = null;
+        }
+        if (!map)
+            return null;
+        // Replay unflushed local ops on top - local intent wins until delivered.
+        for (const op of this.pendingOps()) {
+            if (op.patch === null)
+                delete map[op.itemId];
+            else
+                map[op.itemId] = { ...map[op.itemId], ...op.patch };
+        }
+        return map;
+    }
+}
+/** Convenience factory (equivalent to `new QAStore(opts)`). */
+export function createQAStore(opts) {
+    return new QAStore(opts);
+}
+/**
+ * Read a `?target=` override from the current URL (useful for isolating E2E
+ * runs from the real review bucket). Falls back to the given default.
+ */
+export function targetFromLocation(defaultTarget) {
+    try {
+        if (typeof window === "undefined")
+            return defaultTarget;
+        return new URLSearchParams(window.location.search).get("target") || defaultTarget;
+    }
+    catch {
+        return defaultTarget;
+    }
+}

package/dist/client/styles.d.ts

@@ -0,0 +1,3 @@
+export declare const QA_STYLES: string;
+/** Inject the overlay stylesheet once per document. */
+export declare function ensureQAStyles(): void;

package/dist/client/styles.js

@@ -0,0 +1,211 @@
+"use client";
+// Injected stylesheet for the overlay chrome. Framework-agnostic on purpose:
+// no Tailwind (or any CSS toolchain) required in the consumer. Brand colors
+// come from CSS custom properties (see QATheme) so one stylesheet serves every
+// install; neutral grays/greens/reds are fixed.
+const ACCENT = "var(--qar-accent)";
+const ON_ACCENT = "var(--qar-accent-contrast)";
+const PANEL = "var(--qar-panel-bg)";
+const INPUT = "var(--qar-input-bg)";
+/** Alpha-blend the accent (keeps theme a single color value). */
+const mix = (pct) => `color-mix(in srgb, ${ACCENT} ${pct}%, transparent)`;
+export const QA_STYLES = `
+.qar-theme{--qar-accent:#ffde4d;--qar-accent-contrast:#0a0b12;--qar-panel-bg:#10121c;--qar-input-bg:#181b28;}
+.qar-theme, .qar-theme *{box-sizing:border-box;}
+.qar-theme button{font-family:inherit;cursor:pointer;}
+.qar-theme button:disabled{cursor:default;}
+
+/* ---- spotlight / dim ---- */
+.qar-spotlight{pointer-events:none;position:fixed;z-index:99998;border-radius:8px;transition:all .2s;
+  box-shadow:0 0 0 2px ${ACCENT},0 0 0 9999px rgba(0,0,0,.72);}
+.qar-dim{pointer-events:none;position:fixed;inset:0;z-index:99998;background:rgba(0,0,0,.72);}
+
+/* ---- review card ---- */
+.qar-card{position:fixed;z-index:99999;display:flex;flex-direction:column;border-radius:12px;
+  border:1px solid ${mix(50)};background:${PANEL};padding:16px;box-shadow:0 0 40px -8px ${mix(50)};}
+.qar-card-header{margin-bottom:8px;display:flex;align-items:center;justify-content:space-between;font-size:12px;}
+.qar-counter{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-weight:700;color:${ACCENT};}
+.qar-header-tools{display:flex;align-items:center;gap:8px;color:#94a3b8;}
+.qar-tool-btn{display:inline-flex;align-items:center;justify-content:center;border-radius:4px;
+  border:1px solid #475569;background:transparent;padding:4px;color:#cbd5e1;}
+.qar-tool-btn:hover{background:#1e293b;}
+.qar-tool-btn:disabled{opacity:.3;}
+.qar-tool-btn:disabled:hover{background:transparent;}
+.qar-close-btn{display:inline-flex;border:none;background:none;padding:0;color:inherit;}
+.qar-close-btn:hover{color:#e2e8f0;}
+
+.qar-card-body{min-height:0;flex:1;overflow-y:auto;padding-right:4px;text-align:left;}
+.qar-warn{margin:0 0 8px;border-radius:4px;background:rgba(127,29,29,.3);padding:4px 8px;font-size:11px;color:#fca5a5;}
+.qar-item-title{margin:0;font-size:14px;font-weight:700;color:#fff;}
+.qar-item-sub{margin-top:4px;display:flex;flex-direction:column;gap:4px;font-size:12px;line-height:1.625;color:#94a3b8;}
+.qar-item-sub p{margin:0;}
+.qar-recorded{margin:8px 0 0;font-size:11px;font-weight:600;}
+.qar-recorded-approve{color:#4ade80;}
+.qar-recorded-reject{color:#f87171;}
+
+/* ---- variations picker ---- */
+.qar-var-wrap{margin-top:12px;}
+.qar-var-label{margin:0 0 6px;font-size:10px;font-weight:700;text-transform:uppercase;letter-spacing:.05em;color:#94a3b8;}
+.qar-var-btns{display:flex;flex-wrap:wrap;gap:6px;}
+.qar-var-btn{height:28px;width:28px;border-radius:6px;border:1px solid ${mix(40)};background:transparent;
+  font-size:12px;font-weight:700;color:${ACCENT};transition:background-color .15s,color .15s;}
+.qar-var-btn:hover{background:${mix(12)};}
+.qar-var-btn.qar-on{border-color:${ACCENT};background:${ACCENT};color:${ON_ACCENT};}
+.qar-var-note{margin:4px 0 0;font-size:10px;color:#64748b;}
+
+/* ---- note ---- */
+.qar-note-row{margin-top:12px;display:flex;align-items:center;justify-content:space-between;}
+.qar-note-label{font-size:10px;color:#64748b;}
+.qar-pick-btn{display:inline-flex;align-items:center;gap:4px;border-radius:4px;border:1px solid #475569;
+  background:transparent;padding:2px 6px;font-size:10px;color:#cbd5e1;}
+.qar-pick-btn:hover{background:#1e293b;}
+.qar-pick-btn.qar-picking{border-color:${ACCENT};background:${ACCENT};color:${ON_ACCENT};}
+.qar-note-input{margin-top:4px;width:100%;resize:none;border-radius:6px;border:1px solid #334155;
+  background:${INPUT};padding:6px 8px;font-size:12px;color:#e2e8f0;outline:none;font-family:inherit;}
+.qar-note-input:focus{border-color:${mix(60)};}
+.qar-note-input::placeholder{color:#64748b;}
+
+/* ---- action row ---- */
+.qar-actions{margin-top:12px;display:flex;align-items:center;gap:8px;}
+.qar-nav-btn{display:flex;height:36px;width:36px;align-items:center;justify-content:center;border-radius:8px;
+  border:1px solid #334155;background:transparent;color:#cbd5e1;}
+.qar-nav-btn:hover{background:#1e293b;}
+.qar-nav-btn:disabled{opacity:.3;background:transparent;}
+.qar-reject-btn{display:flex;flex:1;align-items:center;justify-content:center;gap:6px;border-radius:8px;
+  border:1px solid rgba(239,68,68,.5);background:rgba(127,29,29,.2);padding:8px 12px;font-size:14px;font-weight:700;color:#fca5a5;}
+.qar-reject-btn:hover{background:rgba(127,29,29,.4);}
+.qar-approve-btn{display:flex;flex:1;align-items:center;justify-content:center;gap:6px;border-radius:8px;
+  border:none;background:${ACCENT};padding:8px 12px;font-size:14px;font-weight:700;color:${ON_ACCENT};}
+.qar-approve-btn:hover{filter:brightness(1.05);}
+.qar-footer{margin-top:8px;display:flex;align-items:center;justify-content:space-between;font-size:10px;color:#64748b;}
+.qar-footer-green{color:#22c55e;}
+
+/* ---- finish panel ---- */
+.qar-finish-backdrop{position:fixed;inset:0;z-index:100000;display:flex;align-items:center;justify-content:center;
+  background:rgba(0,0,0,.8);padding:16px;}
+.qar-finish-card{width:100%;max-width:28rem;border-radius:16px;border:1px solid ${mix(40)};background:${PANEL};
+  padding:24px;text-align:center;box-shadow:0 0 50px -10px ${mix(50)};}
+.qar-finish-icon{margin:0 auto 12px;display:block;color:${ACCENT};}
+.qar-finish-title{margin:0;font-size:20px;line-height:28px;font-weight:900;color:${ACCENT};}
+.qar-finish-stats{margin:8px 0 0;font-size:14px;color:#cbd5e1;}
+.qar-green{font-weight:700;color:#4ade80;}
+.qar-red{font-weight:700;color:#f87171;}
+.qar-finish-autosaved{margin-top:12px;display:inline-flex;align-items:center;gap:6px;font-size:11px;color:#86efac;}
+.qar-finish-actions{margin-top:16px;display:flex;flex-direction:column;gap:8px;}
+.qar-btn-primary{display:inline-flex;align-items:center;justify-content:center;gap:8px;border-radius:8px;border:none;
+  background:${ACCENT};padding:8px 16px;font-size:14px;font-weight:700;color:${ON_ACCENT};}
+.qar-btn-primary:hover{filter:brightness(1.05);}
+.qar-btn-primary:disabled{opacity:.6;filter:none;}
+.qar-btn-outline-accent{display:inline-flex;align-items:center;justify-content:center;gap:8px;border-radius:8px;
+  border:1px solid ${mix(40)};background:transparent;padding:8px 16px;font-size:14px;font-weight:700;color:${ACCENT};}
+.qar-btn-outline-accent:hover{background:${mix(10)};}
+.qar-btn-outline{border-radius:8px;border:1px solid #475569;background:transparent;padding:8px 16px;font-size:14px;color:#cbd5e1;}
+.qar-btn-outline:hover{background:#1e293b;}
+.qar-btn-ghost{border:none;background:none;border-radius:8px;padding:8px 16px;font-size:14px;color:#64748b;}
+.qar-btn-ghost:hover{color:#cbd5e1;}
+
+/* ---- misc ---- */
+.qar-muted{color:#64748b;font-weight:400;}
+
+/* ---- task-item action link ---- */
+.qar-action-link{margin-top:10px;display:inline-flex;align-items:center;gap:6px;border-radius:8px;
+  border:1px solid ${mix(40)};padding:6px 12px;font-size:12px;font-weight:700;color:${ACCENT};text-decoration:none;}
+.qar-action-link:hover{background:${mix(10)};}
+
+/* ---- journey summary ---- */
+.qar-journey{margin-top:14px;display:flex;flex-direction:column;gap:4px;text-align:left;font-size:12px;color:#cbd5e1;}
+.qar-journey-row{display:flex;justify-content:space-between;gap:12px;padding:2px 8px;border-radius:4px;}
+.qar-journey-row.qar-current{background:${mix(8)};}
+.qar-journey-left{color:${ACCENT};font-weight:700;}
+.qar-journey-done{color:#4ade80;}
+.qar-journey-nav{margin:6px 0 0;font-size:12px;color:#86efac;}
+
+/* ---- 0.3.0: note field fills the card ---- */
+.qar-card-body{display:flex;flex-direction:column;}
+.qar-note-input{flex:1 1 auto;min-height:110px;}
+
+/* ---- 0.3.0: NOT-ALTERED fingerprint badges ---- */
+.qar-fp-unchanged{margin:8px 0 0;border-radius:6px;border:1px solid rgba(239,68,68,.6);
+  background:rgba(127,29,29,.35);padding:6px 8px;font-size:12px;font-weight:700;color:#fecaca;}
+.qar-fp-unchanged small{display:block;margin-top:4px;font-weight:400;color:#fca5a5;}
+.qar-fp-changed{margin:8px 0 0;font-size:11px;color:#94a3b8;}
+
+/* ---- sub-highlight mark: injected into PAGE content, i.e. OUTSIDE any
+   .qar-theme scope - so it must never depend on scoped vars without a
+   fallback (0.3.1 fix: unfallbacked vars made the mark compute to no
+   background at all = invisible highlights). ---- */
+mark.qar-subhl{background:color-mix(in srgb, var(--qar-accent, #ffde4d) 40%, transparent);
+  color:inherit;border-radius:3px;padding:0 2px;
+  box-shadow:0 0 0 1px color-mix(in srgb, var(--qar-accent, #ffde4d) 70%, transparent);}
+
+/* ---- 0.3.0: codename / copy-ref ---- */
+.qar-ref-row{margin-top:6px;display:flex;align-items:center;gap:6px;font-size:10px;color:#64748b;}
+.qar-codename{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;color:${ACCENT};}
+
+/* ---- 0.3.0: device-split approvals ---- */
+.qar-approve-alt{display:flex;flex:1;align-items:center;justify-content:center;gap:6px;border-radius:8px;
+  border:1px solid ${mix(50)};background:${mix(12)};padding:8px 12px;font-size:14px;font-weight:700;color:${ACCENT};}
+.qar-approve-alt:hover{background:${mix(20)};}
+.qar-dev-done{opacity:.55;}
+.qar-partial-note{margin:6px 0 0;font-size:11px;color:#86efac;}
+
+/* ---- 0.3.0: minimize bubble ---- */
+.qar-card-header{touch-action:none;}
+.qar-bubble{position:fixed;z-index:99999;display:flex;align-items:center;justify-content:center;
+  width:52px;height:52px;border-radius:9999px;border:1px solid ${mix(60)};background:${PANEL};color:${ACCENT};
+  box-shadow:0 0 24px -6px ${mix(60)};cursor:pointer;touch-action:none;user-select:none;}
+.qar-bubble-count{position:absolute;top:-4px;right:-4px;display:flex;align-items:center;justify-content:center;
+  min-width:18px;height:18px;border-radius:9999px;background:${ACCENT};color:${ON_ACCENT};font-size:10px;font-weight:700;padding:0 4px;}
+
+/* ---- 0.3.1: journey loading indicator ---- */
+.qar-loading-card{display:flex;flex-direction:column;align-items:center;gap:12px;border-radius:16px;
+  border:1px solid ${mix(40)};background:${PANEL};padding:28px 36px;color:#e2e8f0;font-size:14px;font-weight:700;
+  box-shadow:0 0 50px -10px ${mix(50)};}
+.qar-spinner{width:28px;height:28px;border-radius:9999px;border:3px solid ${mix(25)};
+  border-top-color:${ACCENT};animation:qar-spin .8s linear infinite;}
+@keyframes qar-spin{to{transform:rotate(360deg);}}
+
+/* ---- 0.3.1: INSTANT tooltips (replace the ~500ms native title delay) ---- */
+.qar-theme [data-qatip]{position:relative;}
+/* Exactly ONE tooltip per hover point: suppress an ancestor's tooltip while a
+   descendant tooltip target is hovered (0.3.4 double-tooltip fix). */
+.qar-theme [data-qatip]:has([data-qatip]:hover)::after{display:none;}
+.qar-theme [data-qatip]:hover::after{content:attr(data-qatip);position:absolute;bottom:calc(100% + 6px);
+  left:50%;transform:translateX(-50%);z-index:100001;width:max-content;max-width:230px;white-space:normal;
+  border-radius:6px;border:1px solid #334155;background:#0b1020;padding:4px 8px;
+  font-size:11px;font-weight:400;line-height:1.4;color:#e2e8f0;text-align:left;pointer-events:none;}
+.qar-theme .qar-actions [data-qatip]:hover::after,
+.qar-theme .qar-footer [data-qatip]:hover::after{bottom:auto;top:calc(-6px - 2.6em);}
+
+/* ---- 0.3.3: re-queue context ---- */
+.qar-revisit{margin:8px 0 0;border-radius:6px;border:1px solid ${mix(55)};background:${mix(12)};
+  padding:6px 8px;font-size:12px;font-weight:700;color:${ACCENT};}
+.qar-revisit-prior{margin:6px 0 0;font-size:11px;color:#94a3b8;}
+
+/* ---- 0.3.5: round-scoped counters ---- */
+.qar-finish-alltime{margin:6px 0 0;font-size:11px;color:#64748b;}
+
+/* ---- 0.3.5: mobile preview ---- */
+.qar-preview-backdrop{position:fixed;inset:0;z-index:99997;display:flex;align-items:center;
+  justify-content:center;background:rgba(0,0,0,.82);}
+.qar-preview-frame{position:relative;width:390px;max-width:96vw;height:min(844px,90vh);
+  border-radius:24px;border:2px solid ${mix(50)};background:#000;overflow:hidden;
+  box-shadow:0 0 60px -12px ${mix(60)};}
+.qar-preview-frame iframe{display:block;width:100%;height:100%;border:0;background:#fff;}
+.qar-preview-close{position:absolute;top:8px;right:8px;display:inline-flex;align-items:center;
+  justify-content:center;width:28px;height:28px;border-radius:9999px;border:1px solid ${mix(60)};
+  background:${PANEL};color:${ACCENT};}
+.qar-preview-close:hover{filter:brightness(1.2);}
+`;
+const STYLE_ID = "qa-review-styles";
+/** Inject the overlay stylesheet once per document. */
+export function ensureQAStyles() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(STYLE_ID))
+        return;
+    const el = document.createElement("style");
+    el.id = STYLE_ID;
+    el.textContent = QA_STYLES;
+    document.head.appendChild(el);
+}