@graphty/visual-review 0.1.1 → 0.1.3

package/README.md

@@ -170,8 +170,10 @@ copy the `visual` job and the gate's steps into it, keep those names, and set `w
 file.
 
 **`visual-seed.yml`** is started by hand to capture an older commit with the default branch's
-tool: `gh workflow run visual-seed.yml --ref main -f ref=<sha>`. See
-[Seeding](#seeding-one-story-at-a-time).
+tool: `gh workflow run visual-seed.yml --ref main -f ref=<sha>`. It captures every project seeded
+from the default branch; add `-f projects="web charts"` to capture only those. Each project is
+built and captured on its own, so one whose Storybook does not build at that commit fails alone.
+See [Seeding](#seeding-one-story-at-a-time).
 
 Both need nothing but the default `GITHUB_TOKEN`: the capture job reads Actions artifacts
 (`actions: read`); nothing in CI writes to the repository.
@@ -214,9 +216,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 +283,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 +329,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) |
@@ -456,6 +464,14 @@ the pull request.
   wider. It is never cropped to the content, so a small component sits in the full canvas and
   every capture of a project has the same size unless its story overflows. results.json records the scale as `scale`, and each review record
   copies it into its `subject`.
+- **Why captures rasterize on the CPU.** Chromium runs with `--disable-gpu-rasterization`, so the
+  page's text and shapes are drawn by the CPU; WebGL still runs on SwiftShader. Drawn through
+  SwiftShader, a glyph that sat on a sub-pixel boundary landed on either side of it from one
+  render to the next (a quarter-pixel shift of one letter, in 1 to 7 of 48 renders of the same
+  story), so stories with nothing moving read `unstable`, a different few on each run. With the
+  switch, 48 of 48 renders matched. The repository owner chose this on 2026-09-30, knowing it
+  changes how text is drawn in every story of every project: a baseline captured before it can
+  read `changed` once, and is accepted again.
 - **From GitHub Actions to the page.** Each `visual` job uploads `results.json` and the PNGs to
   review as an artifact `visual-<project>-<attempt>`, kept 30 days. The server lists open pull
   requests with `gh`, finds each one's newest run of the capturing workflow, and downloads those

package/capture/capture.mjs

@@ -54,10 +54,17 @@ const VIEWPORT = { width: 1200, height: 900 };
 /** Device pixels per CSS pixel, as Chromatic captures; recorded in results.json as `scale`. */
 const SCALE = 2;
 const RENDER_TIMEOUT = 30_000;
-const CHROMIUM_ARGS = [
+/**
+ * Chromium's switches for every capture. `--disable-gpu-rasterization` draws the page's text and
+ * shapes on the CPU: rasterized through SwiftShader, a glyph that sits on a sub-pixel boundary
+ * landed on either side of it from one render to the next, so a story with nothing moving read
+ * `unstable` (the README, "Why captures rasterize on the CPU"). WebGL still runs on SwiftShader.
+ */
+export const CHROMIUM_ARGS = [
     "--use-gl=angle",
     "--use-angle=swiftshader",
     "--enable-unsafe-swiftshader",
+    "--disable-gpu-rasterization",
     "--force-color-profile=srgb",
     "--disable-lcd-text",
     "--font-render-hinting=none",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/visual-review",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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/templates/visual-seed.yml

@@ -5,9 +5,11 @@
 # baselines can be seeded from it: `visual-review serve --master-run <this run's id>` lists the run
 # as the default branch, and Finish opens the seed pull request. Dispatch it from __BRANCH__:
 #   gh workflow run visual-seed.yml --ref __BRANCH__ -f ref=<sha>
-# Only the projects whose "seedFromDefaultBranch" is not false are captured. The capture job
-# repeats the "visual" job of the review workflow, except that it has no reference (every story
-# without a baseline is "new") and results.json names the captured commit.
+# Only the projects whose "seedFromDefaultBranch" is not false are captured, or, with
+# `-f projects="a b"`, only those of them named there. Each project is built and captured on its
+# own: one whose Storybook fails to build at that commit fails its own jobs and no other project's.
+# The capture job repeats the "visual" job of the review workflow, except that it has no reference
+# (every story without a baseline is "new") and results.json names the captured commit.
 
 name: Visual seed capture
 
@@ -18,6 +20,11 @@ on:
                 description: "The commit (or branch or tag) whose Storybooks are captured"
                 required: true
                 type: string
+            projects:
+                description: "The projects to capture, separated by spaces or commas (default: every one seeded from the default branch)"
+                required: false
+                type: string
+                default: ""
 
 permissions:
     contents: read
@@ -34,13 +41,23 @@ jobs:
                   sparse-checkout: visual-review.config.json
                   sparse-checkout-cone-mode: false
 
+            # A name that is not a project seeded from the default branch stops the run here, rather
+            # than seeding fewer projects than were asked for.
             - name: List the projects
               id: plan
+              env:
+                  WANT: ${{ inputs.projects }}
               run: |
-                  echo "projects=$(jq -c '(.baselines // "visual-baselines") as $b
+                  projects=$(jq -c --arg want "$WANT" '(.baselines // "visual-baselines") as $b
+                      | [$want | splits("[ ,]+") | select(. != "")] as $w
                       | [.projects | to_entries[] | select(.value.seedFromDefaultBranch != false)
-                         | {project: .key, storybook: .value.storybook, build: .value.build, baselines: $b}]' \
-                      visual-review.config.json)" >> "$GITHUB_OUTPUT"
+                         | {project: .key, storybook: .value.storybook, build: .value.build, baselines: $b}] as $all
+                      | ($w - [$all[].project]) as $unknown
+                      | if ($unknown | length) > 0
+                        then error("not a project seeded from the default branch: \($unknown | join(", "))")
+                        else [$all[] | select(($w | length) == 0 or (.project | IN($w[])))] end' \
+                      visual-review.config.json)
+                  echo "projects=$projects" >> "$GITHUB_OUTPUT"
 
     storybook:
         name: Build ${{ matrix.project }} at ${{ inputs.ref }}
@@ -71,9 +88,12 @@ jobs:
                   name: storybook-${{ matrix.project }}
                   path: ${{ matrix.storybook }}/
 
+    # Runs even when another project's build failed. A project whose own build failed has no
+    # Storybook artifact, so its job stops at the download, before installing anything.
     visual:
         name: visual (${{ matrix.project }})
         needs: [plan, storybook]
+        if: ${{ !cancelled() && needs.plan.result == 'success' }}
         runs-on: ubuntu-24.04
         timeout-minutes: 45
         strategy:
@@ -84,6 +104,12 @@ jobs:
             # The default branch's checkout: the capture tool, the config and the baselines come from here.
             - uses: actions/checkout@v4
 
+            - name: Download Storybook build
+              uses: actions/download-artifact@v4
+              with:
+                  name: storybook-${{ matrix.project }}
+                  path: ${{ matrix.storybook }}/
+
             - name: Restore this project's baseline images
               uses: actions/cache@v4
               with:
@@ -99,12 +125,6 @@ jobs:
             - name: Install Chromium
               run: __CLI__ install-browser
 
-            - name: Download Storybook build
-              uses: actions/download-artifact@v4
-              with:
-                  name: storybook-${{ matrix.project }}
-                  path: ${{ matrix.storybook }}/
-
             - name: Capture
               run: __CLI__ capture --project ${{ matrix.project }} --out "$RUNNER_TEMP/visual"
 

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/index.html

@@ -14,6 +14,6 @@
             <span id="status" role="status"></span>
             <button type="button" id="copy-link" title="Copy a link to this screen">Copy link</button>
         </header>
-        <main id="app"><p>Loading...</p></main>
+        <main id="app" tabindex="-1"><p>Loading...</p></main>
     </body>
 </html>

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;
@@ -501,3 +507,7 @@ td {
     word-break: break-all;
     color: var(--accent);
 }
+
+#app:focus {
+    outline: none;
+}

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();
@@ -1676,6 +1759,18 @@ function toggleView(view) {
     showStory();
 }
 
+// Safari on an iPad sends a hardware keyboard's keys only to a focused element, and tapping an
+// image or a button focuses nothing, so the shortcuts never arrived. The page itself holds focus
+// whenever nothing else does.
+function keepKeys() {
+    if (document.activeElement === null || document.activeElement === document.body) {
+        app.focus({ preventScroll: true });
+    }
+}
+document.addEventListener("pointerup", () => setTimeout(keepKeys));
+document.addEventListener("focusout", () => setTimeout(keepKeys));
+keepKeys();
+
 document.addEventListener("keydown", (e) => {
     if (!["story", "grid"].includes(state.screen) || e.ctrlKey || e.metaKey || e.altKey) {
         return;
@@ -1727,6 +1822,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];