@graphty/visual-review 0.1.0 → 0.1.1

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)
 
@@ -297,7 +298,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`
@@ -332,7 +334,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 +486,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.1",
   "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

@@ -159,12 +159,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);
@@ -494,3 +495,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.
@@ -139,6 +139,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;
@@ -459,6 +461,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 +700,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 +944,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,
@@ -1174,7 +1178,9 @@ 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 left = item.baseline
+            ? pane(item.from ? `Baseline of ${item.from}` : "Baseline", await imgOf("baseline"))
+            : pane("No baseline");
         let right;
         if (!item.capture) {
             right = pane(item.status === "failed" ? "No capture: it failed" : "No capture");