@graphty/visual-review 0.1.0 → 0.1.2

package/README.md

@@ -22,6 +22,7 @@ your login.
 - [Seeding one story at a time](#seeding-one-story-at-a-time)
 - [Iterating on a story before a pull request exists](#iterating-on-a-story-before-a-pull-request-exists)
 - [Story parameters](#story-parameters)
+- [Reorganizing stories: renames](#reorganizing-stories-renames)
 - [What the gate does and does not guarantee](#what-the-gate-does-and-does-not-guarantee)
 - [Troubleshooting](#troubleshooting)
 
@@ -213,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
@@ -278,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:
@@ -297,7 +302,8 @@ starts the same server from your own shell.
     you decided have left it, and the count has gone down; **Accepted**, **Rejected** and
     **Excluded** show them with their decisions.
 
-Statuses: `changed` (differs from its baseline), `new` (no baseline, and on a pull request the
+Statuses: `changed` (differs from its baseline), `moved` (a renamed story that looks exactly as
+its old id's baseline; see [renames](#reorganizing-stories-renames)), `new` (no baseline, and on a pull request the
 story is new or looks different from the default branch's newest capture of it), `no baseline yet` (status
 `unseeded`: no baseline, and the pull request does not change it), `removed` (a baseline whose
 story no longer exists, lost a mode, or whose story's own parameters now exclude it), `unstable`
@@ -321,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) |
@@ -332,7 +340,8 @@ so; to change a decision, press U (or the Undo button) first. The same key twice
 ## What each decision does
 
 - **Accept**: the new screenshot becomes the baseline (or, for `removed`, the baseline is
-  deleted). Allowed on `changed`, `new` and `removed`.
+  deleted). Allowed on `changed`, `moved`, `new` and `removed`. For a renamed story the baseline
+  is written under the new id and the old id's baseline is deleted, in the same commit.
 - **Reject**: the difference is a regression. It always needs a reason, which is posted to the pull
   request as a comment with a machine-readable block an agent can read. The pull request stays
   blocked until its code changes so the capture matches the baseline again.
@@ -483,6 +492,45 @@ Inside a story, `isChromatic()` from `chromatic/isChromatic` is true during capt
 `chromatic=true`). A settings file `<baselines>/<project>/<story id>.json` overrides the story's
 parameters; the page's Exclude writes one with `disableSnapshot: true` and your reason.
 
+## Reorganizing stories: renames
+
+Storybook derives a story's id from its title, so moving stories in the sidebar (a new `title`,
+a new folder) gives every moved story a new id. Without help, each old id's baseline is reported
+`removed` and each new id is `new`, with no before and after to compare. A renames file keeps them
+paired. Add it in the pull request that moves the stories, at `<baselines>/<project>/renames.json`:
+
+```json
+[
+    { "from": "building-a-panel-fieldrow--default", "to": "components-panels-and-rows-fieldrow--default" },
+    { "from": "compact-theme-mantine-components-badge--dot", "to": "components-display-badge--dot" }
+]
+```
+
+Each entry is one story: `from` is its old id, `to` its new one. Modes map on their own, so
+`<from>.dark.png` is compared with the capture of `<to>` in the dark mode, and `<from>.light.png`
+with the light one; a mode the new story no longer has is still reported `removed`.
+
+- **Capture** compares the new id's capture with the old id's baseline. It reads `moved` when the
+  two look the same (only the name changed) and `changed` when they differ; either way the item
+  carries `from`, and the old baseline is not reported `removed`.
+- **The review page** shows each one as a pair, labeled "moved from &lt;old id&gt;" on the tile
+  and on the story screen, with the old id's baseline on the left. The grid has a **moved** filter,
+  and a component's Accept N undecided takes its moved stories too.
+- **Accepting** writes the baseline under the new id and deletes the old id's baseline in the same
+  accept commit. For a `moved` item the image is the same, so git sees a rename and the Git LFS
+  pointer does not change. The review record names both paths.
+- **The gate** blocks a `moved` item until it is accepted, like any change: a pull request that
+  moves stories cannot land without their baselines moving with them.
+- **A rename whose new id is not a story** in the Storybook is an error: capture reports it as a
+  `failed` item under the new id, with the reason, and the page lists it under Errors. Fix the
+  entry in `renames.json`. A rename whose old id is still a story is not a move, and does
+  nothing.
+- **An entry whose move was accepted** does nothing any more: the old baseline is gone and the new
+  id has its own. You can delete the file once the pull request has merged, or leave it.
+
+`renames.json` is read from the pull request's own checkout, like the baselines. Only baseline
+PNGs move: a settings file (`<old id>.json`) is not renamed; rename it in the same pull request.
+
 ## What the gate does and does not guarantee
 
 - A pull request cannot pass the gate while its capture of a seeded project holds anything but

package/capture/capture.mjs

@@ -21,6 +21,12 @@
  * second capture of an unstable one, and `baselines/<file>`: the baseline each changed, unstable
  * and removed item was compared with.
  *
+ * A story renamed in the project's `renames.json` (see loadRenames) is compared with the baseline
+ * of its old id, mode by mode: `moved` when it looks the same, `changed` otherwise, each carrying
+ * `from`; that old baseline is then not reported `removed`. A rename whose new id is not a story
+ * is a `failed` item under the new id, so the page lists it; one whose old id is still a story
+ * does nothing.
+ *
  * With `reference`, a directory holding the default branch's newest capture of the project (CI
  * downloads it on pull requests), a story with no baseline whose capture matches it is `unseeded`, not
  * `new`: seeding is per story, so a story nobody has accepted yet does not block every pull
@@ -153,6 +159,47 @@ export function storySettings(parameters, file) {
     };
 }
 
+/** A project's renames file, in its baselines directory. */
+const RENAMES = "renames.json";
+
+const STORY_ID = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * Reads a project's renames file, `<dir>/renames.json`: `[{ "from": "<old story id>", "to":
+ * "<new story id>" }]`, for stories whose id changed while they stayed the same story.
+ * @param {string} dir the project's baselines directory
+ * @returns {Promise<Map<string, string>>} the old id by new id; empty when there is no file
+ */
+async function loadRenames(dir) {
+    const path = join(dir, RENAMES);
+    let list;
+    try {
+        list = JSON.parse(await readFile(path, "utf8"));
+    } catch (e) {
+        if (e.code === "ENOENT") {
+            return new Map();
+        }
+        throw new Error(`${path}: ${e.message}`);
+    }
+    if (!Array.isArray(list)) {
+        throw new Error(`${path}: must be an array of { "from": "<old id>", "to": "<new id>" }`);
+    }
+    const byTo = new Map();
+    const froms = new Set();
+    list.forEach((r, i) => {
+        const ok = (v) => typeof v === "string" && v.length <= 200 && STORY_ID.test(v);
+        if (!ok(r?.from) || !ok(r?.to) || r.from === r.to) {
+            throw new Error(`${path}: entry ${i} must be { "from": "<old id>", "to": "<another id>" }`);
+        }
+        if (byTo.has(r.to) || froms.has(r.from)) {
+            throw new Error(`${path}: entry ${i} renames ${r.from} or to ${r.to} a second time`);
+        }
+        byTo.set(r.to, r.from);
+        froms.add(r.from);
+    });
+    return byTo;
+}
+
 async function pngsIn(dir) {
     try {
         return (await readdir(dir)).filter((f) => f.endsWith(".png")).sort();
@@ -485,9 +532,9 @@ export async function capture({
     const started = Date.now();
     await mkdir(join(out, "baselines"), { recursive: true });
     await mkdir(join(out, "second"), { recursive: true });
-    const ids = storyIds(JSON.parse(await readFile(join(storybook, "index.json"), "utf8"))).filter(
-        (id) => !stories || stories.some((p) => id.startsWith(p)),
-    );
+    const allIds = storyIds(JSON.parse(await readFile(join(storybook, "index.json"), "utf8")));
+    const ids = allIds.filter((id) => !stories || stories.some((p) => id.startsWith(p)));
+    const renames = await loadRenames(baselines);
     const refs = await loadReference(reference);
     const [server, base] = await serve(storybook);
     // One browser per worker: every page of a browser shares its one GPU process, so with
@@ -508,6 +555,35 @@ export async function capture({
         // A story whose own parameters exclude it while it still has a baseline is reported as
         // removed, so a pull request cannot drop a story from review without the owner seeing it.
         const newlyExcluded = new Set();
+        // Old baselines a rename compares a story with (or reports as a broken rename): not removed.
+        const renamed = new Set();
+        const renameErrors = [];
+        const known = new Set(allIds);
+        for (const [to, from] of stories ? [] : renames) {
+            if (known.has(to)) {
+                continue;
+            }
+            // Only a rename with an old baseline left to move is an error; once it is accepted the
+            // old baselines are gone, and the entry does nothing.
+            for (const file of existing) {
+                const [id, mode = null] = file.slice(0, -4).split(".");
+                if (id === from && BASELINE_NAME.test(file)) {
+                    renamed.add(file);
+                    renameErrors.push({
+                        id: to,
+                        mode,
+                        file: fileName(to, mode),
+                        from,
+                        threshold: DEFAULT_THRESHOLD,
+                        includeAA: false,
+                        ...EMPTY,
+                        status: "failed",
+                        reason: `${RENAMES} renames ${from} to ${to}, but the Storybook has no story ${to}: fix ${RENAMES}`,
+                    });
+                }
+            }
+        }
+        items.push(...renameErrors);
         for (const id of ids) {
             const s = storySettings(params[id] ?? {}, await loadSettings(baselines, id));
             for (const mode of s.modes) {
@@ -521,11 +597,22 @@ export async function capture({
                 if (s.disableSnapshot) {
                     items.push({ ...common, ...EMPTY, status: "excluded", reason: s.reason });
                 } else {
-                    jobs.push({ ...common, url: base + storyUrl(id, mode.globals), delay: s.delay });
+                    // Renamed: compared with the old id's baseline of this mode, while the new id
+                    // has none of its own (after the accept it does, and the rename is done).
+                    // A rename from an id that is still a story is not a move: it does nothing.
+                    const old =
+                        renames.has(id) && !known.has(renames.get(id)) ? fileName(renames.get(id), mode.name) : null;
+                    const from = old && !existing.has(file) && existing.has(old) ? renames.get(id) : null;
+                    if (from) {
+                        renamed.add(old);
+                    }
+                    jobs.push({ ...common, from, url: base + storyUrl(id, mode.globals), delay: s.delay });
                 }
             }
         }
-        const gone = stories ? [] : [...existing].filter((f) => !planned.has(f) && BASELINE_NAME.test(f));
+        const gone = stories
+            ? []
+            : [...existing].filter((f) => !planned.has(f) && !renamed.has(f) && BASELINE_NAME.test(f));
 
         const emojiFont = hasEmojiFont();
         if (emojiFont === false) {
@@ -576,10 +663,12 @@ export async function capture({
         }
 
         const run = async (browser, job) => {
-            const { url, delay, ...common } = job;
-            const baseline = await readBaseline(join(baselines, job.file));
+            const { url, delay, from, ...rest } = job;
+            // `from` only on a renamed story, so results.json of a project with no renames is as before.
+            const common = from ? { ...rest, from } : rest;
+            const baseline = await readBaseline(join(baselines, from ? fileName(from, job.mode) : job.file));
             const reference = baseline ? null : (refs.images.get(job.file) ?? null);
-            const opts = { threshold: job.threshold, includeAA: job.includeAA, reference };
+            const opts = { threshold: job.threshold, includeAA: job.includeAA, reference, moved: from !== null };
             const failed = (shot, prefix = "") => ({
                 ...common,
                 ...EMPTY,
@@ -602,16 +691,22 @@ export async function capture({
                 result = classify({ baseline, first: first.png, second: second.png, ...opts });
             }
             const { status } = result;
-            if (["changed", "new", "unseeded", "unstable"].includes(status)) {
-                await writeFile(join(out, job.file), first.png);
+            // A moved capture is also its baseline when the bytes are the same: the page reads it.
+            if (["changed", "moved", "new", "unseeded", "unstable"].includes(status)) {
+                // The capture results.json names: the second one when the first was a flake.
+                await writeFile(join(out, job.file), result.flaky ? second.png : first.png);
             }
             if (status === "unstable") {
                 await writeFile(join(out, "second", job.file), second.png);
             }
-            if (baseline && (status === "changed" || status === "unstable")) {
+            const ownBaseline = status === "moved" && result.baseline !== result.capture;
+            if (baseline && (status === "changed" || status === "unstable" || ownBaseline)) {
                 await writeFile(join(out, "baselines", job.file), baseline);
             }
-            const lines = status === "unchanged" ? [] : clip([...first.console, ...(second?.console ?? [])]);
+            const lines =
+                status === "unchanged" || status === "moved"
+                    ? []
+                    : clip([...first.console, ...(second?.console ?? [])]);
             return { ...common, ...result, reason: null, console: lines };
         };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/visual-review",
-  "version": "0.1.0",
+  "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/accept.mjs

@@ -26,7 +26,7 @@ import { isLfsPointer } from "./compare.mjs";
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
 
 /** The statuses an item can be accepted or rejected in; unstable and failed are only excluded. */
-const DECIDABLE = new Set(["changed", "new", "removed"]);
+const DECIDABLE = new Set(["changed", "moved", "new", "removed"]);
 const EXCLUDABLE = new Set([...DECIDABLE, "unstable", "failed"]);
 
 /**
@@ -354,7 +354,7 @@ async function commitAccepts({ repo, target, accepts, first, now, progress, conf
         const counts = { accept: 0, exclude: 0, remove: 0 };
         progress(`writing ${writes.length} ${writes.length === 1 ? "file" : "files"}`);
         for (const w of writes) {
-            items.push(await write(tree, w, counts, baselines));
+            items.push(...(await write(tree, w, counts, baselines)));
         }
         const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d+/, "");
         const record = `${baselines}/reviews/${stamp}-${isMaster ? "master" : `pr${target.pr}`}.json`;
@@ -441,8 +441,9 @@ export async function behindMaster(repo, head, project, { defaultBranch, baselin
  * @param {object} w the decision, its results item, and for an accept the verified bytes
  * @param {{ accept: number, exclude: number, remove: number }} counts tallied here
  * @param {string} baselines the baselines directory
- * @returns {Promise<{ path: string, from: string | null, to: string | null, reason: string | null }>}
- *     the record item
+ * @returns {Promise<{ path: string, from: string | null, to: string | null, reason: string | null,
+ *     movedFrom?: string, movedTo?: string }[]>} its record items: two for a renamed story, whose
+ *     baseline moves to its new name
  */
 async function write(tree, w, counts, baselines) {
     const dir = `${baselines}/${w.project}`;
@@ -453,17 +454,27 @@ async function write(tree, w, counts, baselines) {
         const bytes = `${JSON.stringify(settings, null, 2)}\n`;
         await put(join(tree, path), bytes);
         counts.exclude++;
-        return { path, from: old && sha256(old), to: sha256(bytes), reason: `exclude: ${w.reason}` };
+        return [{ path, from: old && sha256(old), to: sha256(bytes), reason: `exclude: ${w.reason}` }];
     }
     const path = `${dir}/${w.item.file}`;
     if (w.item.status === "removed") {
         await rm(join(tree, path), { force: true });
         counts.remove++;
-        return { path, from: w.item.baseline, to: null, reason: w.reason };
+        return [{ path, from: w.item.baseline, to: null, reason: w.reason }];
     }
     await put(join(tree, path), w.bytes);
     counts.accept++;
-    return { path, from: w.item.baseline, to: w.item.capture, reason: w.reason };
+    if (!w.item.from) {
+        return [{ path, from: w.item.baseline, to: w.item.capture, reason: w.reason }];
+    }
+    // A rename: the old id's baseline (of this mode) goes, the new one takes its place. For a
+    // moved item the bytes are the same, so git sees a rename and the LFS pointer is unchanged.
+    const oldPath = `${dir}/${w.item.mode === null ? w.item.from : `${w.item.from}.${w.item.mode}`}.png`;
+    await rm(join(tree, oldPath), { force: true });
+    return [
+        { path: oldPath, from: w.item.baseline, to: null, reason: w.reason, movedTo: path },
+        { path, from: null, to: w.item.capture, reason: w.reason, movedFrom: oldPath },
+    ];
 }
 
 // Two modes of one story excluded together write one settings file: keep one record item.

package/trusted/lib/compare.mjs

@@ -154,16 +154,21 @@ function crop(img, w, h) {
  * A story with no baseline is `unseeded` ("no baseline yet") when its capture matches
  * `reference`, master's newest capture of it: the pull request did not change it, so it needs no
  * review here. It is `new` when it differs from master's, or master has none (a new story).
+ *
+ * `moved` says the baseline is another story id's, named in the project's renames.json: a story
+ * that only moved (same image, new id) is `moved` rather than `unchanged`, so it still needs an
+ * accept, which writes its baseline under the new name.
  * @param {{ baseline: Buffer | null, first: Buffer | null, second?: Buffer | null,
- *     reference?: Buffer | null, threshold: number, includeAA: boolean }} input `first` is null
- *     when the story is gone
- * @returns {{ status: "unchanged" | "changed" | "new" | "unseeded" | "removed" | "unstable", flaky: boolean,
+ *     reference?: Buffer | null, threshold: number, includeAA: boolean, moved?: boolean }} input
+ *     `first` is null when the story is gone
+ * @returns {{ status: "unchanged" | "moved" | "changed" | "new" | "unseeded" | "removed" | "unstable", flaky: boolean,
  *     baseline: string | null, capture: string | null, size: number[] | null,
  *     baselineSize: number[] | null, changedPixels: number | null, bbox: number[] | null }}
  *     `capture` is the hash of the capture the status describes: the second one when flaky
  */
-export function classify({ baseline, first, second = null, reference = null, threshold, includeAA }) {
+export function classify({ baseline, first, second = null, reference = null, threshold, includeAA, moved = false }) {
     const options = { threshold, includeAA };
+    const matched = (r, flaky) => ({ ...r, status: moved ? "moved" : "unchanged", flaky });
     const none = { flaky: false, size: null, baselineSize: null, changedPixels: null, bbox: null };
     if (first === null) {
         return { status: "removed", ...none, baseline: sha256(baseline), capture: null };
@@ -175,12 +180,15 @@ export function classify({ baseline, first, second = null, reference = null, thr
         return { status, ...none, baseline: null, capture: sha256(first), size: pngSize(first) };
     }
     const vsFirst = compareImages(baseline, first, options);
-    if (vsFirst.status === "unchanged" || second === null) {
+    if (vsFirst.status === "unchanged") {
+        return matched(vsFirst, false);
+    }
+    if (second === null) {
         return { ...vsFirst, flaky: false };
     }
     const vsSecond = compareImages(baseline, second, options);
     if (vsSecond.status === "unchanged") {
-        return { ...vsSecond, flaky: true };
+        return matched(vsSecond, true);
     }
     return { ...vsFirst, status: agree() ? "changed" : "unstable", flaky: false };
 }

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;
@@ -159,12 +196,15 @@ export async function downloadCaptures(gh, run, projects, tmp) {
  * @returns {Promise<string | null>} the capture's directory, or null when no run has one
  */
 export async function newestMasterCapture(gh, project, tmp, { workflow, defaultBranch }) {
-    const { workflow_runs: runs } = await api(
-        gh,
-        `repos/{owner}/{repo}/actions/workflows/${encodeURIComponent(workflow)}/runs?branch=` +
-            `${encodeURIComponent(defaultBranch)}&event=push&per_page=10`,
-    );
-    for (const run of runs.map(toRun)) {
+    // The branch's newest commits, then each one's run: GitHub's list of a workflow's runs filtered
+    // by branch now and then answers with a stale page (runs from weeks ago), which made a pull
+    // request compare with an old capture or none. Commits and a run by head sha answer consistently.
+    const commits = await api(gh, `repos/{owner}/{repo}/commits?sha=${encodeURIComponent(defaultBranch)}&per_page=10`);
+    for (const { sha } of commits) {
+        const run = await newestCiRun(gh, sha, { workflow });
+        if (!run) {
+            continue;
+        }
         const dir = (await downloadCaptures(gh, run, [project], tmp))[project]?.dir;
         let results = null;
         try {

package/trusted/lib/results.mjs

@@ -8,9 +8,11 @@
 
 /**
  * Every status an item can have. `unseeded` ("no baseline yet") is a story with no baseline whose
- * capture matches master's newest capture of it, so the pull request did not change it.
+ * capture matches master's newest capture of it, so the pull request did not change it. `moved`
+ * is a story that looks exactly as the baseline of the id it was renamed from (`from`, named in
+ * the project's renames.json); a renamed story that looks different is `changed` with `from`.
  */
-const STATUSES = ["unchanged", "changed", "new", "unseeded", "removed", "unstable", "failed", "excluded"];
+const STATUSES = ["unchanged", "moved", "changed", "new", "unseeded", "removed", "unstable", "failed", "excluded"];
 
 /** The most items one file may hold (compact-mantine has about 830 today). */
 export const MAX_ITEMS = 5000;
@@ -26,6 +28,7 @@ const NAME = /^[a-z0-9][a-z0-9-]*$/;
 const HASHES = {
     unchanged: { baseline: true, capture: true },
     changed: { baseline: true, capture: true },
+    moved: { baseline: true, capture: true },
     new: { baseline: false, capture: true },
     unseeded: { baseline: false, capture: true },
     removed: { baseline: true, capture: false },
@@ -113,6 +116,14 @@ export function validateResults(r) {
         }
 
         check(STATUSES.includes(item.status), `${at}.status must be one of ${STATUSES.join(", ")}`);
+        // The story id a renamed story's baseline was read under (absent when it was not renamed).
+        check(
+            item.from === undefined ||
+                item.from === null ||
+                (typeof item.from === "string" && item.from.length <= 200 && NAME.test(item.from)),
+            `${at}.from must be a Storybook story id or null`,
+        );
+        check(item.status !== "moved" || typeof item.from === "string", `${at}.from is required for a moved item`);
         check(typeof item.flaky === "boolean", `${at}.flaky must be a boolean`);
         for (const key of ["baseline", "capture"]) {
             const v = item[key];

package/trusted/lib/serve.mjs

@@ -44,7 +44,7 @@ const HEADERS = {
  */
 const componentOf = (id) => id.split("--")[0];
 
-const REVIEWABLE = new Set(["changed", "new", "removed", "unstable", "failed"]);
+const REVIEWABLE = new Set(["changed", "moved", "new", "removed", "unstable", "failed"]);
 const WRITES = new Set(["decide", "accept-all", "finish"]);
 
 /**
@@ -434,9 +434,9 @@ export function createApp({ repo, gh, config, tmp, token, origin, masterRun, res
             if (!hash) {
                 return [404, { error: "no such image" }];
             }
-            const bytes = await readFile(kind === "capture" ? join(p.dir, file) : join(p.dir, "baselines", file)).catch(
-                () => null,
-            );
+            // A moved item's baseline is its capture's bytes, so the artifact holds only the capture.
+            const own = kind === "capture" || item.baseline === item.capture;
+            const bytes = await readFile(own ? join(p.dir, file) : join(p.dir, "baselines", file)).catch(() => null);
             if (!bytes || createHash("sha256").update(bytes).digest("hex") !== hash) {
                 return [409, { error: `${file} does not match results.json` }];
             }

package/trusted/page/review.css

@@ -187,6 +187,7 @@ td {
 }
 
 .badge.changed,
+.badge.moved,
 .badge.exclude {
     border-color: var(--accent);
     color: var(--accent);
@@ -444,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;
@@ -494,3 +501,9 @@ td {
     background: var(--card);
     color: var(--fg);
 }
+
+.tile .moved-from {
+    font-size: 12px;
+    word-break: break-all;
+    color: var(--accent);
+}

package/trusted/page/review.js

@@ -11,14 +11,14 @@ const app = document.getElementById("app");
 const crumbs = document.getElementById("crumbs");
 const statusLine = document.getElementById("status");
 
-const REVIEWABLE = ["changed", "new", "removed", "unstable", "failed"];
-const ACCEPTABLE = ["changed", "new", "removed"];
+const REVIEWABLE = ["changed", "moved", "new", "removed", "unstable", "failed"];
+const ACCEPTABLE = ["changed", "moved", "new", "removed"];
 // A story with no baseline that this pull request did not change: shown, never a decision here.
 const UNSEEDED = "unseeded";
 const NO_BASELINE = "no baseline yet";
 const statusLabel = (status) => (status === UNSEEDED ? NO_BASELINE : status);
-// Errors first (their own list), then what changed, then new, unstable and removed stories.
-const RANK = { failed: 0, changed: 1, new: 2, unstable: 3, removed: 4, unseeded: 5 };
+// Errors first (their own list), then what changed, then moved, new, unstable and removed stories.
+const RANK = { failed: 0, changed: 1, moved: 2, new: 3, unstable: 4, removed: 5, unseeded: 6 };
 const FLASH_MS = 333; // one image each third of a second: about 1.5 full cycles a second
 // "fit" (the default) shows the whole of both images in their panes, at one scale, never above real
 // size; 1 is real size: one CSS pixel per CSS pixel the story was drawn at, scrolling when larger.
@@ -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",
@@ -139,6 +144,8 @@ function loaded(url) {
 
 const componentOf = (id) => id.split("--")[0];
 const itemName = (item) => (item.mode ? `${item.id} (${item.mode})` : item.id);
+// A renamed story (renames.json) is compared with its old id's baseline: say which.
+const movedFrom = (item) => (item.from ? `moved from ${item.from}` : "");
 const short = (sha) => (sha ? sha.slice(0, 10) : "none");
 const decisionOf = (item) => state.data?.decisions[item.file] ?? null;
 const isLocal = () => state.target?.local === true;
@@ -213,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() {
@@ -459,6 +490,7 @@ function tile(item, number) {
             img,
             el("span", { class: "name" }, el("span", { class: "number" }, `${number}`), " ", item.mode ?? ""),
             el("span", { class: `badge ${item.status}` }, statusLabel(item.status)),
+            item.from ? el("span", { class: "moved-from", title: movedFrom(item) }, movedFrom(item)) : null,
             item.reReview ? el("span", { class: "badge warn", title: RE_REVIEW }, "re-review") : null,
         ),
         decisionLine(item),
@@ -697,7 +729,7 @@ function showGrid() {
                 `Needs a decision (${state.data.items.filter((i) => REVIEWABLE.includes(i.status) && !decisionOf(i)).length})`,
             ),
             filterButton("all", `All (${state.data.items.filter((i) => REVIEWABLE.includes(i.status)).length})`),
-            ["changed", "new", "unstable", "removed", "failed"]
+            ["changed", "moved", "new", "unstable", "removed", "failed"]
                 .filter((s) => counts[s])
                 .map((s) => filterButton(s, `${s} (${counts[s]})`)),
             counts[UNSEEDED] ? filterButton(UNSEEDED, `${NO_BASELINE} (${counts[UNSEEDED]})`) : null,
@@ -941,6 +973,7 @@ function showStory() {
                 itemName(item),
                 " ",
                 el("span", { class: `badge ${item.status}` }, statusLabel(item.status)),
+                item.from ? el("span", { class: "badge moved" }, movedFrom(item)) : null,
                 d
                     ? el("span", { class: `badge ${d.decision}` }, `${d.decision}${d.reason ? `: ${d.reason}` : ""}`)
                     : null,
@@ -968,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),
@@ -1049,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) };
             })(),
         );
     }
@@ -1174,7 +1231,15 @@ async function renderStage(item, view, keep) {
     };
     try {
         const diff = item.baseline && item.capture ? await diffOf(item) : null;
-        const left = item.baseline ? pane("Baseline", await imgOf("baseline")) : pane("No baseline");
+        const marked = view === "highlight" && diff !== null;
+        const baseName = item.from ? `Baseline of ${item.from}` : "Baseline";
+        const left = item.baseline
+            ? pane(
+                  marked ? `${baseName}, changed pixels in red` : baseName,
+                  await imgOf("baseline"),
+                  ...(marked ? [overlay(diff)] : []),
+              )
+            : pane("No baseline");
         let right;
         if (!item.capture) {
             right = pane(item.status === "failed" ? "No capture: it failed" : "No capture");
@@ -1195,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) {
@@ -1256,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;
@@ -1298,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;
 }
@@ -1562,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 });
@@ -1578,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}`;
 }
@@ -1654,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();
@@ -1721,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];