@graphty/visual-review 0.1.1 → 0.1.2

package/README.md

@@ -214,9 +214,11 @@ token is kept in the work directory, so the URL stays valid across restarts; del
 ### Links to a screen
 
 The address always names the screen you are on, after the token: the targets list; a pull
-request (or master) and project with the grid's filter and text; or one story with its view and
-zoom, for example
-`#token=...&target=123&project=web&filter=undecided&item=button--primary.dark.png&view=flash&zoom=2`.
+request (or master) and project with the grid's filter and text; or one story with its view,
+zoom, changed box and blink, for example
+`#token=...&target=123&project=web&filter=undecided&item=button--primary.dark.png&view=flash&zoom=2&box=on&blink=off`.
+A link's `box` and `blink` apply to the page it opens; the choice this browser remembers for B
+and L is left as it was.
 Opening that address, in another tab or on another device, opens the same screen. **Copy link**
 at the top right copies it. The link carries your session token, so it works on your iPad the way
 the printed URL does; keep it to yourself as you would that URL. All of it sits after `#`, which a
@@ -279,11 +281,13 @@ starts the same server from your own shell.
    other to the same place, and **Fit to screen** returns to the whole image. (On an iPad,
    pinching zooms the whole page; use the zoom buttons to zoom the images.) **Next changed box**
    (N) scrolls both panes until the next region of changed pixels is in view and outlines it;
-   "box i of k" counts them. The views, each shown in the right pane at the same scale and place:
+   "box i of k" counts them. **Box** (B) turns that outline on and off; the page remembers the
+   choice in this browser. The views, each shown in the right pane at the same scale and place:
    **Side by side**; **Flash**, which shows baseline and new one after the other in the same
    place, about 1.5 times a second (the images themselves, not an overlay), keeping the zoom and
-   scroll it was opened at; **Highlight**, pixelmatch's changed pixels in red over the dimmed
-   baseline; and **Spotlight**, the new image dimmed everywhere except around the changed pixels
+   scroll it was opened at; **Highlight**, the changed pixels in solid red laid over both images
+   themselves, in both panes, where **Blink** (L) flashes the red pixels on and off at Flash's
+   pace (remembered in this browser); and **Spotlight**, the new image dimmed everywhere except around the changed pixels
    (each grown by 10 image pixels), which finds a one-pixel change. Flash, Highlight and
    Spotlight need two images; on a new or removed story they are off and the page says why
    ("New story, no baseline", "Only one image: this story was removed"). Badges here:
@@ -323,6 +327,8 @@ for them. Seed them from the default branch (below), or accept them on the pull
 | S            | Spotlight the changes; S again returns to side by side                         |
 | Z            | Next zoom: fit to screen, real size, 2x, 4x, 8x, then fit again                |
 | N            | Next changed box                                                               |
+| B            | Outline the changed box, or stop outlining it                                  |
+| L            | In Highlight: blink the red changed pixels, or hold them on                    |
 | Space (hold) | Flash while held                                                               |
 | Shift+A      | Accept every undecided item of this project without opening it (asks first)    |
 | Escape       | Back to the grid from a story, wherever the focus is (the reason box included) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/visual-review",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Self-hosted visual review of Storybook stories: capture in GitHub Actions, keep the baselines in git (Git LFS), accept or reject each change in a local page, and gate pull requests",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",

package/trusted/lib/github.mjs

@@ -10,8 +10,8 @@
  */
 
 import { execFile } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 import { validateResults } from "./results.mjs";
 
@@ -114,9 +114,48 @@ export async function visualJobs(gh, run, attempt, projects) {
     );
 }
 
+// Downloads in flight, by target directory: concurrent refreshes of one run await the same one.
+const downloading = new Map();
+
+/**
+ * Downloads one artifact into `dir`, unless it is already there. It is extracted into a sibling
+ * temporary directory and renamed into place only once its results.json is there, so `dir` either
+ * does not exist or holds a whole artifact; a failed or interrupted download leaves nothing behind.
+ * An artifact without results.json is discarded, and its readers report the capture as failed.
+ * @param {Function} gh the gh runner
+ * @param {number} runId the run
+ * @param {string} name the artifact
+ * @param {string} dir where it goes
+ * @returns {Promise<void>} settles when `dir` is complete, or the artifact had no results.json
+ */
+function download(gh, runId, name, dir) {
+    if (existsSync(join(dir, "results.json"))) {
+        return Promise.resolve();
+    }
+    if (!downloading.has(dir)) {
+        const done = (async () => {
+            // A directory without results.json is left over from before downloads were atomic.
+            rmSync(dir, { recursive: true, force: true });
+            mkdirSync(dirname(dir), { recursive: true });
+            const part = mkdtempSync(`${dir}.part-`);
+            try {
+                await gh(["run", "download", String(runId), "-n", name, "-D", part]);
+                if (existsSync(join(part, "results.json"))) {
+                    renameSync(part, dir);
+                }
+            } finally {
+                rmSync(part, { recursive: true, force: true });
+            }
+        })().finally(() => downloading.delete(dir));
+        downloading.set(dir, done);
+    }
+    return downloading.get(dir);
+}
+
 /**
  * Downloads each project's capture artifact from the highest attempt that uploaded one, into
- * `<tmp>/<run>-<attempt>/<project>/`. An artifact already downloaded is not fetched again.
+ * `<tmp>/<run>-<attempt>/<project>/`. An artifact already downloaded is not fetched again, and
+ * concurrent calls for the same one share a single download.
  * @param {Function} gh the gh runner
  * @param {{ id: number }} run the run
  * @param {string[]} projects project ids
@@ -139,9 +178,7 @@ export async function downloadCaptures(gh, run, projects, tmp) {
             continue;
         }
         const dir = join(tmp, `${run.id}-${newest.attempt}`, project);
-        if (!existsSync(join(dir, "results.json"))) {
-            await gh(["run", "download", String(run.id), "-n", newest.name, "-D", dir]);
-        }
+        await download(gh, run.id, newest.name, dir);
         out[project] = { dir, attempt: newest.attempt };
     }
     return out;

package/trusted/page/review.css

@@ -445,6 +445,12 @@ td {
     image-rendering: pixelated;
 }
 
+/* Highlight's changed pixels, over the image: no checkerboard behind them. */
+.sheet > canvas.diffmark {
+    background: none;
+    pointer-events: none;
+}
+
 .boxmark {
     position: absolute;
     box-sizing: border-box;

package/trusted/page/review.js

@@ -29,6 +29,9 @@ const SPOT_ALPHA = 190; // the spotlight's dimming, out of 255, as Chromatic's f
 const RE_REVIEW = "re-review: your earlier accept was replaced by master's baseline";
 // The grid's decision filters, and how a decision reads on a tile.
 const DECISIONS = { accept: "Accepted", reject: "Rejected", exclude: "Excluded" };
+// The reviewer's own display choices (the changed box, blinking the overlay), kept in this browser.
+const OPTIONS_KEY = "visual-review:options";
+const saved = loadOptions();
 
 const state = {
     targets: [],
@@ -45,6 +48,8 @@ const state = {
     view: "side", // side | flash | highlight | spotlight
     zoom: "fit",
     box: 0, // which changed box "next changed box" is on
+    showBox: saved.showBox ?? true, // outline the changed box (B)
+    blink: saved.blink ?? false, // blink the changed pixels Highlight lays over the images (L)
     held: null, // the view to return to when Space is released
     pending: "reject", // what Enter in the reason box does
     screen: "targets",
@@ -215,6 +220,30 @@ function stopFlash() {
     flashTimer = null;
 }
 
+// Local storage can be missing or refuse (a private window, blocked site data): the page then uses
+// the defaults and forgets the choices, and nothing else changes.
+function loadOptions() {
+    try {
+        return JSON.parse(localStorage.getItem(OPTIONS_KEY) ?? "{}") ?? {};
+    } catch {
+        return {};
+    }
+}
+
+function saveOptions() {
+    try {
+        localStorage.setItem(OPTIONS_KEY, JSON.stringify({ showBox: state.showBox, blink: state.blink }));
+    } catch {
+        // Not remembered; the choice still holds for this page.
+    }
+}
+
+function toggleOption(key) {
+    state[key] = !state[key];
+    saveOptions();
+    showStory();
+}
+
 // ---------------------------------------------------------------- screen: targets
 
 async function loadTargets() {
@@ -972,6 +1001,30 @@ function showStory() {
                 viewButton("flash", "Flash", "F, or hold Space"),
                 viewButton("highlight", "Highlight", "H"),
                 viewButton("spotlight", "Spotlight", "S"),
+                el(
+                    "button",
+                    {
+                        type: "button",
+                        "aria-pressed": String(state.showBox),
+                        title: "B: outline the changed box",
+                        onclick: () => toggleOption("showBox"),
+                    },
+                    "Box",
+                ),
+                el(
+                    "button",
+                    {
+                        type: "button",
+                        "aria-pressed": String(state.blink),
+                        disabled: view !== "highlight",
+                        title:
+                            view === "highlight"
+                                ? "L: blink the changed pixels"
+                                : "Blink flashes the changed pixels that Highlight lays over the images",
+                        onclick: () => toggleOption("blink"),
+                    },
+                    "Blink",
+                ),
                 note ? el("span", { id: "single-note", class: "meta" }, note) : null,
                 el("span", { class: "spacer" }),
                 ZOOMS.map(zoomButton),
@@ -1053,7 +1106,7 @@ async function diffOf(item) {
                     diffMask: true,
                 });
                 const grown = grow(mask, w, h);
-                return { w, h, a: pa, b: pb, grown, boxes: regions(grown, w, h) };
+                return { w, h, a: pa, b: pb, mask, grown, boxes: regions(grown, w, h) };
             })(),
         );
     }
@@ -1178,8 +1231,14 @@ async function renderStage(item, view, keep) {
     };
     try {
         const diff = item.baseline && item.capture ? await diffOf(item) : null;
+        const marked = view === "highlight" && diff !== null;
+        const baseName = item.from ? `Baseline of ${item.from}` : "Baseline";
         const left = item.baseline
-            ? pane(item.from ? `Baseline of ${item.from}` : "Baseline", await imgOf("baseline"))
+            ? pane(
+                  marked ? `${baseName}, changed pixels in red` : baseName,
+                  await imgOf("baseline"),
+                  ...(marked ? [overlay(diff)] : []),
+              )
             : pane("No baseline");
         let right;
         if (!item.capture) {
@@ -1201,11 +1260,22 @@ async function renderStage(item, view, keep) {
                 tag.textContent = showingNew ? "Flash: new" : "Flash: baseline";
             }, FLASH_MS);
         } else if (view === "highlight") {
-            right = pane("Changed pixels in red over the dimmed baseline", highlight(item, diff));
+            right = pane("New, changed pixels in red", await imgOf("capture"), overlay(diff));
         } else {
             right = pane("Spotlight: the new image, dimmed except around each change", spotlight(diff));
         }
         stage.replaceChildren(left, right);
+        if (marked && state.blink) {
+            // Both panes' overlays on and off together, at Flash's pace.
+            const marks = [...stage.querySelectorAll(".diffmark")];
+            let on = true;
+            flashTimer = setInterval(() => {
+                on = !on;
+                for (const m of marks) {
+                    m.style.visibility = on ? "visible" : "hidden";
+                }
+            }, FLASH_MS);
+        }
         const frames = [...stage.querySelectorAll(".frame")];
         // Zoomed, scrolling one pane scrolls the other to the same place.
         for (const f of frames) {
@@ -1262,14 +1332,16 @@ function showBox(stage, boxes, jump) {
         const [left, top] = [Math.max(0, x * factor - 2), Math.max(0, y * factor - 2)];
         const [right, bottom] = [Math.min(sw, (x + w) * factor + 2), Math.min(sh, (y + h) * factor + 2)];
         sheet.querySelector(".boxmark")?.remove();
-        const mark = el("div", { class: "boxmark" });
-        Object.assign(mark.style, {
-            left: `${left}px`,
-            top: `${top}px`,
-            width: `${right - left}px`,
-            height: `${bottom - top}px`,
-        });
-        sheet.append(mark);
+        if (state.showBox) {
+            const mark = el("div", { class: "boxmark" });
+            Object.assign(mark.style, {
+                left: `${left}px`,
+                top: `${top}px`,
+                width: `${right - left}px`,
+                height: `${bottom - top}px`,
+            });
+            sheet.append(mark);
+        }
         if (!jump) {
             frame.scrollLeft = 0;
             frame.scrollTop = 0;
@@ -1304,16 +1376,18 @@ async function nextBox() {
     showBox(document.getElementById("stage"), boxes, true);
 }
 
-// pixelmatch's own picture: the changed pixels in red over the dimmed baseline.
-function highlight(item, diff) {
-    const canvas = el("canvas", { width: String(diff.w), height: String(diff.h) });
+// The changed pixels alone, in solid red, transparent everywhere else: laid over an image in the
+// same grid cell, so it lines up with the image at every zoom.
+function overlay(diff) {
+    const canvas = el("canvas", { width: String(diff.w), height: String(diff.h), class: "diffmark" });
     const ctx = canvas.getContext("2d");
     const out = ctx.createImageData(diff.w, diff.h);
-    pixelmatch(diff.a, diff.b, out.data, diff.w, diff.h, {
-        threshold: item.threshold,
-        includeAA: item.includeAA,
-        alpha: 0.2,
-    });
+    for (let i = 0; i < diff.w * diff.h; i++) {
+        if (diff.mask[i * 4 + 3] !== 0) {
+            out.data[i * 4] = 255;
+            out.data[i * 4 + 3] = 255;
+        }
+    }
     ctx.putImageData(out, 0, 0);
     return canvas;
 }
@@ -1568,7 +1642,7 @@ function finishOutcome() {
 // ---------------------------------------------------------------- the address
 
 // Every screen is in the address, after the session token, so a copied link opens it again:
-// #token=...&target=123&project=p&filter=undecided&q=text&item=file.png&view=side&zoom=fit
+// #token=...&target=123&project=p&filter=undecided&q=text&item=file.png&view=side&zoom=fit&box=on&blink=off
 // Only the fragment holds it: a browser never sends a fragment to a server or in a Referer.
 function hashFor() {
     const p = new URLSearchParams({ token });
@@ -1584,6 +1658,8 @@ function hashFor() {
         p.set("item", current().file);
         p.set("view", state.held ?? state.view);
         p.set("zoom", String(state.zoom));
+        p.set("box", state.showBox ? "on" : "off");
+        p.set("blink", state.blink ? "on" : "off");
     }
     return `#${p}`;
 }
@@ -1660,6 +1736,13 @@ async function route() {
         state.view = VIEWS.includes(p.get("view")) ? p.get("view") : "side";
         const zoom = p.get("zoom") === "fit" ? "fit" : Number(p.get("zoom"));
         state.zoom = ZOOMS.includes(zoom) ? zoom : "fit";
+        // A link's box and blink apply to this page; the browser's remembered choice is unchanged.
+        if (["on", "off"].includes(p.get("box"))) {
+            state.showBox = p.get("box") === "on";
+        }
+        if (["on", "off"].includes(p.get("blink"))) {
+            state.blink = p.get("blink") === "on";
+        }
         state.box = 0;
         say("");
         showStory();
@@ -1727,6 +1810,12 @@ document.addEventListener("keydown", (e) => {
         f: () => toggleView("flash"),
         h: () => toggleView("highlight"),
         s: () => toggleView("spotlight"),
+        b: () => toggleOption("showBox"),
+        l: () => {
+            if (state.view === "highlight") {
+                toggleOption("blink");
+            }
+        },
         n: nextBox,
         z: () => {
             state.zoom = ZOOMS[(ZOOMS.indexOf(state.zoom) + 1) % ZOOMS.length];