From e202360fd01cee2155d9555798c756824e561f83 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 08:58:29 +0200
Subject: [PATCH 01/16] feat: the HTML report writes snap_diff_manifest.json
 beside it

Lists each changed and new screenshot with the repo path a reviewer
would commit it to and its file relative to the report directory, so a
page reading the uploaded report artifact can accept it without
re-running the suite.
---
 lib/snap_diff/reporters/html.rb               | 24 +++++-
 .../reporters/templates/report.html.erb       |  2 +-
 test/unit/reporters/html_reporter_test.rb     | 85 ++++++++++++++++++-
 3 files changed, 107 insertions(+), 4 deletions(-)

diff --git a/lib/snap_diff/reporters/html.rb b/lib/snap_diff/reporters/html.rb
index 3f4e4105..514f4e5a 100644
--- a/lib/snap_diff/reporters/html.rb
+++ b/lib/snap_diff/reporters/html.rb
@@ -165,7 +165,8 @@ def compared_entry_for(name, compare)
         {
           name: name,
           original: resolve_image(compare.base_image_path),
-          new: resolve_image(compare.image_path)
+          new: resolve_image(compare.image_path),
+          accept: accept_paths(compare.image_path)
         }.merge(failure_details(compare)).compact
       end
 
@@ -228,7 +229,8 @@ def new_screenshot_entry(name, path)
         image = resolve_image(path)
         return entry unless image
 
-        entry.merge(new: image, git_add: "git add -- #{Shellwords.escape(display_path(path))}")
+        entry.merge(new: image, accept: accept_paths(path),
+          git_add: "git add -- #{Shellwords.escape(display_path(path))}")
       end
 
       # Relative to the project root, where the user runs `git add` -- the
@@ -239,6 +241,16 @@ def display_path(path)
         relative.start_with?("..") ? path.to_s : relative
       end
 
+      # Raw paths for snap_diff_manifest.json (the template leaves them out):
+      # the capture is both what is committed (`path`, the baseline's own
+      # path, which the failing run already overwrote) and what the report
+      # dir holds (`file`). String keys: entries pass through JSON in dump_state.
+      def accept_paths(capture)
+        return unless capture && File.exist?(capture)
+
+        {"path" => display_path(capture), "file" => Pathname(capture).expand_path.relative_path_from(output_path.dirname.expand_path).to_s}
+      end
+
       def resolve_image(path)
         return unless path
 
@@ -257,6 +269,14 @@ def data_uri(pathname)
       def write_report
         FileUtils.mkdir_p(output_path.dirname)
         File.write(output_path, render)
+        write_manifest
+      end
+
+      # What a reviewer page may accept: the captures that differ or are new.
+      def write_manifest
+        accepted = entries.select { |entry| %w[changed new].include?(entry[:status]) && entry[:accept] }
+        manifest = accepted.map { |entry| {"name" => entry[:name], "status" => entry[:status]}.merge(entry[:accept]) }
+        File.write(output_path.dirname / "snap_diff_manifest.json", JSON.pretty_generate("version" => 1, "entries" => manifest))
       end
     end
   end
diff --git a/lib/snap_diff/reporters/templates/report.html.erb b/lib/snap_diff/reporters/templates/report.html.erb
index 9237553c..f3565b8b 100644
--- a/lib/snap_diff/reporters/templates/report.html.erb
+++ b/lib/snap_diff/reporters/templates/report.html.erb
@@ -244,7 +244,7 @@
 <script>
 (function() {
   'use strict';
-  var DATA = <%= @entries.to_json.gsub("</", "<\\/") %>;
+  var DATA = <%= @entries.map { |entry| entry.except(:accept) }.to_json.gsub("</", "<\\/") %>;
   var state = { current: 0, view: 'both', annotated: false, zoom: 100, search: '' };
   var $ = function(id) { return document.getElementById(id); };
 
diff --git a/test/unit/reporters/html_reporter_test.rb b/test/unit/reporters/html_reporter_test.rb
index 668bb569..cb823062 100644
--- a/test/unit/reporters/html_reporter_test.rb
+++ b/test/unit/reporters/html_reporter_test.rb
@@ -453,7 +453,7 @@ def synchronize
 
     reporter.finalize
 
-    assert_equal reporter.entries.map { |e| e.transform_keys(&:to_s) }, report_data
+    assert_equal reporter.entries.map { |e| e.except(:accept).transform_keys(&:to_s) }, report_data
     assert_equal ["changed"], report_data.map { |e| e["status"] }
     html = @output_path.read
     assert_includes html, "<title>SnapDiff Report — 1 changed</title>"
@@ -482,8 +482,91 @@ def synchronize
     assert @output_path.exist?
   end
 
+  # --- snap_diff_manifest.json: what a reviewer page may accept ----------
+
+  test "the manifest names the changed capture and the baseline it replaces" do
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    assertion = build_failing_assertion("index")
+    reporter.record([assertion])
+    reporter.finalize
+
+    entry = manifest.fetch("entries").sole
+    assert_equal 1, manifest.fetch("version")
+    assert_equal %w[index changed], entry.values_at("name", "status")
+    assert_equal reporter.send(:display_path, assertion.compare.image_path), entry["path"]
+    assert_no_match(/\.base\.png\z/, entry["path"])
+    assert_equal assertion.compare.image_path.to_s, (@output_dir / entry["file"]).realpath.to_s
+  end
+
+  test "the manifest lists a new capture with its status" do
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    capture_new_screenshot(reporter, "signup")
+    reporter.finalize
+
+    assert_equal [{"name" => "signup", "status" => "new", "path" => "screenshots/signup.png", "file" => "screenshots/signup.png"}],
+      manifest.fetch("entries")
+    assert_predicate @output_dir / "screenshots/signup.png", :exist?
+  end
+
+  test "the manifest carries file paths when images are embedded" do
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path, embed_images: true)
+    reporter.record([build_failing_assertion("index")])
+    capture_new_screenshot(reporter, "signup")
+    reporter.finalize
+
+    manifest.fetch("entries").each do |entry|
+      assert_no_match(/^data:/, entry["file"])
+      assert_predicate @output_dir / entry["file"], :exist?
+    end
+    assert_equal 2, manifest.fetch("entries").size
+  end
+
+  test "the manifest leaves out re-recorded entries and entries with no capture on disk" do
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    reporter.record([build_rerecorded_assertion("accepted")])
+    reporter.record([SnapDiff::ScreenshotAssertion.new("gone", path: @output_dir / "screenshots/gone.png")])
+    capture_new_screenshot(reporter, "kept")
+    reporter.finalize
+
+    assert_equal ["kept"], manifest.fetch("entries").map { |e| e["name"] }
+  end
+
+  test "the report data does not carry the manifest paths" do
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    reporter.record([build_failing_assertion("index")])
+    reporter.finalize
+
+    assert_not_includes report_data.sole.keys, "accept"
+  end
+
+  test "the manifest survives the fork-parallel dump and merge" do
+    worker = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    worker.record([build_failing_assertion("index")])
+    capture_new_screenshot(worker, "signup")
+    state = JSON.parse(JSON.generate(worker.dump_state))
+
+    parent = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    parent.merge_state!(state)
+    parent.finalize
+
+    assert_equal [%w[index changed], %w[signup new]], manifest.fetch("entries").map { |e| e.values_at("name", "status") }
+    manifest.fetch("entries").each { |e| assert_predicate @output_dir / e["file"], :exist? }
+  end
+
+  test "no report means no manifest" do
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    reporter.record([build_passing_assertion("ok")])
+    reporter.finalize
+
+    assert_not (@output_dir / "snap_diff_manifest.json").exist?
+  end
+
   private
 
+  def manifest
+    JSON.parse((@output_dir / "snap_diff_manifest.json").read)
+  end
+
   # A capture under a project rooted at @output_dir, tallied the way
   # ScreenshotMatcher tallies it. The root is pinned for the rest of the
   # test so display paths are predictable.

From cad1db77b80275e08517ea00991c908c0c137ec7 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 09:24:28 +0200
Subject: [PATCH 02/16] feat: a review page that accepts or rejects screenshots
 from a PR

One self-contained HTML file, shipped in the gem, for a project to host
on its GitHub Pages. A reviewer pastes a fine-grained token, the page
downloads the CI run's report artifact, shows each changed or new
screenshot next to the committed baseline, and on submit commits the
accepted captures to the PR branch in one commit and posts one comment
listing what was accepted and rejected.

The link's run, artifact and PR are checked against each other before
anything is shown; only image files at screenshot paths can be written;
the branch update never forces; the token stays in memory for the page
load.
---
 .gitignore                      |   1 +
 lib/snap_diff/review/index.html | 471 ++++++++++++++++++++++++++++++++
 2 files changed, 472 insertions(+)
 create mode 100644 lib/snap_diff/review/index.html

diff --git a/.gitignore b/.gitignore
index ca07113a..82d398f6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,6 +20,7 @@
 *.diff.png
 *.base.png
 snap_diff_report.html
+snap_diff_manifest.json
 
 *.attempt_*.webp
 *.diff.webp
diff --git a/lib/snap_diff/review/index.html b/lib/snap_diff/review/index.html
new file mode 100644
index 00000000..bb18bc61
--- /dev/null
+++ b/lib/snap_diff/review/index.html
@@ -0,0 +1,471 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<!-- script-src carries the sha256 (base64) of the exact text of the one inline script element below. Recompute it whenever that script changes, or the page will not run. -->
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'sha256-MW6NpEd5ZbwAohpVGXi77Ygw4qUokSaEtb0r/RfQOQ0='; style-src 'unsafe-inline'; img-src blob:; connect-src https://api.github.com https://*.blob.core.windows.net; base-uri 'none'; form-action 'none'">
+<meta name="referrer" content="no-referrer">
+<title>snap_diff review</title>
+<style>
+  :root { --bg: #fff; --fg: #1f2328; --muted: #59636e; --line: #d1d9e0; --panel: #f6f8fa;
+    --accept: #1a7f37; --reject: #cf222e; --accent: #0969da; color-scheme: light dark; }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg: #0d1117; --fg: #e6edf3; --muted: #9198a1; --line: #3d444d; --panel: #151b23;
+      --accept: #3fb950; --reject: #f85149; --accent: #4493f8; }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.5 system-ui, sans-serif; }
+  header, footer { padding: 8px 16px; border-bottom: 1px solid var(--line); display: flex; gap: 12px; align-items: center; flex-wrap: wrap; }
+  footer { border-top: 1px solid var(--line); border-bottom: 0; position: sticky; bottom: 0; background: var(--bg); }
+  h1 { font-size: 16px; margin: 0; }
+  .muted { color: var(--muted); }
+  .spacer { flex: 1; }
+  button { font: inherit; padding: 4px 12px; border: 1px solid var(--line); border-radius: 6px; background: var(--panel); color: var(--fg); cursor: pointer; }
+  button:disabled { opacity: .5; cursor: default; }
+  button.on.accept, .badge.accept { background: var(--accept); border-color: var(--accept); color: #fff; }
+  button.on.reject, .badge.reject { background: var(--reject); border-color: var(--reject); color: #fff; }
+  button.on.view { border-color: var(--accent); color: var(--accent); }
+  input { font: inherit; padding: 4px 8px; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); color: var(--fg); width: 32em; max-width: 100%; }
+  #msg { margin: 16px; padding: 8px 12px; border-radius: 6px; border: 1px solid var(--line); background: var(--panel); white-space: pre-wrap; }
+  #msg.error { border-color: var(--reject); }
+  #msg:empty { display: none; }
+  #token-form { margin: 16px; display: flex; gap: 8px; flex-wrap: wrap; }
+  main { display: grid; grid-template-columns: 260px 1fr; min-height: calc(100vh - 120px); }
+  nav { border-right: 1px solid var(--line); overflow-y: auto; }
+  nav button { display: flex; width: 100%; gap: 6px; border: 0; border-bottom: 1px solid var(--line); border-radius: 0; background: none; text-align: left; padding: 6px 12px; }
+  nav button.current { background: var(--panel); box-shadow: inset 3px 0 var(--accent); }
+  nav .name { flex: 1; overflow-wrap: anywhere; }
+  .badge { font-size: 12px; padding: 0 6px; border-radius: 10px; border: 1px solid var(--line); white-space: nowrap; }
+  #viewer { padding: 12px 16px; min-width: 0; }
+  .toolbar { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin-bottom: 12px; }
+  .images { display: grid; gap: 12px; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); }
+  figure { margin: 0; }
+  figcaption { font-size: 12px; color: var(--muted); }
+  img { max-width: 100%; border: 1px solid var(--line); display: block; cursor: zoom-in; }
+  #confirm { width: 100%; display: flex; gap: 8px; align-items: flex-start; flex-wrap: wrap; }
+  #confirm ul { max-height: 30vh; overflow: auto; margin: 4px 0; }
+  [hidden] { display: none !important; }
+  a { color: var(--accent); }
+</style>
+</head>
+<body>
+<header>
+  <h1>snap_diff review</h1>
+  <span id="where" class="muted"></span>
+  <span class="spacer"></span>
+  <button id="forget" type="button" hidden>Forget token</button>
+</header>
+<div id="msg" role="status"></div>
+<form id="token-form" hidden>
+  <label for="token">GitHub token (fine-grained: Actions read, Contents write, Pull requests write). Kept in memory for this page load only.</label>
+  <input id="token" type="password" autocomplete="off" required>
+  <button type="submit">Load screenshots</button>
+</form>
+<main id="review" hidden>
+  <nav id="list"></nav>
+  <section id="viewer"></section>
+</main>
+<footer id="bar" hidden>
+  <span id="counter"></span>
+  <span class="muted">Keys: A accept, R reject, J/K next/previous, T flip base/new</span>
+  <span class="spacer"></span>
+  <button id="submit" type="button" disabled>Submit review</button>
+  <div id="confirm" hidden><div id="confirm-text"></div><button id="confirm-yes" type="button">Yes, submit</button><button id="confirm-no" type="button">Cancel</button></div>
+</footer>
+<script>
+(() => {
+"use strict";
+const API = "https://api.github.com";
+// Captured before anything else runs, so a page holding a handle to this window cannot swap it later.
+const doFetch = fetch.bind(window);
+const MAX_ZIP = 100 * 1024 * 1024, MAX_FILE = 20 * 1024 * 1024, MAX_TOTAL = 200 * 1024 * 1024, MAX_ENTRIES = 500;
+const PERM = { actions: "Actions: read", contents: "Contents: write", pullsRead: "Pull requests: read", pulls: "Pull requests: write", user: "read your own user profile" };
+const $ = (id) => document.getElementById(id);
+const params = new URLSearchParams(location.search);
+const repo = params.get("repo"), pr = params.get("pr"), run = params.get("run"), artifact = params.get("artifact");
+let token = null, inflatedTotal = 0, head = null, entries = [], current = 0, view = "side", flipped = false, busy = false;
+
+function el(tag, props, ...children) {
+  const node = Object.assign(document.createElement(tag), props);
+  node.append(...children.filter((c) => c != null));
+  return node;
+}
+
+function say(text, isError) {
+  $("msg").textContent = text;
+  $("msg").className = isError ? "error" : "";
+}
+
+// Only https links from the API go into an href.
+function link(text, url) {
+  return /^https:\/\//.test(url || "") ? el("a", { href: url, textContent: text, target: "_blank", rel: "noopener" }) : text;
+}
+
+// Names come from the artifact: no markdown, mentions or issue refs reach the commit or comment.
+const clean = (s) => String(s).replace(/[^\w .\/-]/g, "?").slice(0, 80);
+const sameRepo = (fullName) => typeof fullName === "string" && fullName.toLowerCase() === repo.toLowerCase();
+const encodePath = (path) => path.split("/").map(encodeURIComponent).join("/");
+
+async function api(method, path, body, perm, accept) {
+  let res;
+  try {
+    res = await doFetch(API + path, {
+      method,
+      headers: { Authorization: "Bearer " + token, Accept: accept || "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28",
+        ...(body ? { "Content-Type": "application/json" } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (_) {
+    throw Object.assign(new Error(`Could not reach GitHub (${method} ${path}): network failure or the request was blocked (CORS/CSP). Check your connection and try again.`), { fatal: true });
+  }
+  if (res.ok) return res;
+  let detail = "";
+  try { detail = (await res.json()).message || ""; } catch (_) { /* body is not JSON; status says enough */ }
+  const text = res.status === 401 ? "The token is invalid or expired. Paste a new one."
+    : res.status === 403 ? `The token lacks permission: ${perm}. ${detail}`
+    : `GitHub answered ${res.status} to ${method} ${path}. ${detail}`;
+  throw Object.assign(new Error(text), { status: res.status, detail });
+}
+const json = async (promise) => (await promise).json();
+
+// Minimal zip reader: sizes come from the central directory (local headers may defer them to a data descriptor).
+// ponytail: no ZIP64, so artifacts over 4 GB or 65535 files fail loudly; add ZIP64 if a report ever gets that big.
+function unzip(buf) {
+  const v = new DataView(buf), u8 = new Uint8Array(buf), damaged = (why) => new Error(`The artifact zip is damaged (${why}).`);
+  let eocd = -1;
+  for (let i = buf.byteLength - 22; i >= Math.max(0, buf.byteLength - 65557); i--) {
+    if (v.getUint32(i, true) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error("The artifact download is not a zip file.");
+  const files = new Map(), names = new TextDecoder();
+  let p = v.getUint32(eocd + 16, true);
+  for (let n = v.getUint16(eocd + 10, true); n > 0; n--) {
+    if (p + 46 > buf.byteLength || v.getUint32(p, true) !== 0x02014b50) throw damaged("bad central directory");
+    const flags = v.getUint16(p + 8, true), method = v.getUint16(p + 10, true);
+    const csize = v.getUint32(p + 20, true), size = v.getUint32(p + 24, true), local = v.getUint32(p + 42, true);
+    const nameLen = v.getUint16(p + 28, true);
+    const name = names.decode(u8.subarray(p + 46, p + 46 + nameLen));
+    p += 46 + nameLen + v.getUint16(p + 30, true) + v.getUint16(p + 32, true);
+    if (name.endsWith("/")) continue;
+    if (local + 30 > buf.byteLength || v.getUint32(local, true) !== 0x04034b50) throw damaged(`bad local header for ${name}`);
+    const start = local + 30 + v.getUint16(local + 26, true) + v.getUint16(local + 28, true);
+    if (start + csize > buf.byteLength) throw damaged(`${name} runs past the end`);
+    files.set(name, { name, method, size, encrypted: (flags & 1) === 1, data: u8.subarray(start, start + csize) });
+  }
+  return files;
+}
+
+// Inflates into a buffer of the declared size and stops the moment the output would exceed it.
+async function inflate(file) {
+  if (file.encrypted) throw new Error(`${file.name} is encrypted.`);
+  if (file.size > MAX_FILE) throw new Error(`${file.name} is larger than 20 MB.`);
+  if ((inflatedTotal += file.size) > MAX_TOTAL) throw Object.assign(new Error("The artifact unpacks to more than 200 MB; the review page refuses it."), { fatal: true });
+  if (file.method === 0) {
+    if (file.data.length !== file.size) throw new Error(`${file.name} does not match its declared size.`);
+    return file.data;
+  }
+  if (file.method !== 8) throw new Error(`Unsupported compression method ${file.method} for ${file.name}.`);
+  const reader = new Blob([file.data]).stream().pipeThrough(new DecompressionStream("deflate-raw")).getReader();
+  const out = new Uint8Array(file.size);
+  let n = 0;
+  for (let r = await reader.read(); !r.done; r = await reader.read()) {
+    if (n + r.value.length > file.size) { reader.cancel(); throw new Error(`${file.name} inflates past its declared size.`); }
+    out.set(r.value, n);
+    n += r.value.length;
+  }
+  if (n !== file.size) throw new Error(`${file.name} does not match its declared size.`);
+  return out;
+}
+
+const MIME = { png: "image/png", webp: "image/webp" };
+const ascii = (b, from, to) => String.fromCharCode(...b.subarray(from, to));
+const MAGIC = {
+  png: (b) => [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a].every((x, i) => b[i] === x),
+  webp: (b) => ascii(b, 0, 4) === "RIFF" && ascii(b, 8, 12) === "WEBP",
+};
+function imageUrl(bytes, ext) {
+  return URL.createObjectURL(new Blob([bytes], { type: MIME[ext] }));
+}
+
+// The manifest path becomes a tree path in a commit: only an image inside the repo, never under .git*.
+function pathProblem(path, ext) {
+  if (typeof path !== "string" || path === "" || path.startsWith("/")) return "is not a relative path";
+  if (!/^[A-Za-z0-9._ \/-]+$/.test(path)) return "has characters other than letters, digits, . _ space / -";
+  const segments = path.split("/");
+  if (segments.some((s) => s === "" || s === "." || s === "..")) return "has empty, . or .. segments";
+  if (segments.some((s) => s.toLowerCase().startsWith(".git"))) return "touches a .git* file";
+  if (path.split(".").pop().toLowerCase() !== ext) return `does not end in .${ext} like its capture`;
+  return null;
+}
+
+// The committed file at the run's commit, or null when the repo has none there (404).
+async function baseline(path) {
+  let res;
+  try {
+    res = await api("GET", `/repos/${repo}/contents/${encodePath(path)}?ref=${head.sha}`, null, PERM.contents, "application/vnd.github.raw");
+  } catch (e) {
+    if (e.status === 404) return null;
+    throw e;
+  }
+  const tooBig = new Error(`The committed ${path} is larger than 20 MB.`);
+  if (Number(res.headers.get("content-length")) > MAX_FILE) throw tooBig;
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  if (bytes.length > MAX_FILE) throw tooBig;
+  return bytes;
+}
+
+async function readEntry(m, zip) {
+  const name = clean(m.name);
+  if (m.status !== "changed" && m.status !== "new") throw new Error(`${name}: unknown status ${clean(m.status)}.`);
+  const ext = typeof m.file === "string" ? m.file.split(".").pop().toLowerCase() : "";
+  if (!Object.hasOwn(MIME, ext)) throw new Error(`${name}: capture ${m.file} is not a .png or .webp.`);
+  const problem = pathProblem(m.path, ext);
+  if (problem) throw new Error(`${name}: refusing path ${m.path}: it ${problem}.`);
+  const capture = zip.get(m.file);
+  if (!capture) throw new Error(`${name}: the artifact is missing ${m.file}.`);
+  const bytes = await inflate(capture);
+  if (!MAGIC[ext](bytes)) throw new Error(`${name}: ${m.file} is not a real .${ext} image.`);
+  // The "before" image is the committed baseline at the run's commit, not a file the artifact claims it is.
+  const before = await baseline(m.path);
+  if (m.status === "new" && before) throw new Error(`${name}: ${m.path} already exists in the repo; it is not new.`);
+  if (m.status === "changed" && !before) throw new Error(`${name}: ${m.path} has no committed baseline at the run's commit.`);
+  const entry = { name, status: m.status, path: m.path, bytes, decision: null, images: { new: imageUrl(bytes, ext) } };
+  if (before) {
+    entry.images.base = imageUrl(before, ext);
+    const stem = m.file.slice(0, -(ext.length + 1));
+    for (const [key, suffix] of [["diff", ".diff."], ["baseDiff", ".base.diff."], ["heatmap", ".heatmap.diff."]]) {
+      const sibling = zip.get(stem + suffix + ext);
+      if (sibling) entry.images[key] = imageUrl(await inflate(sibling), ext);
+    }
+  }
+  return entry;
+}
+
+// The link carries four independent numbers; each must point at the same PR head before anything is shown.
+async function verifyLink() {
+  say(`Reading CI run ${run}…`);
+  const runInfo = await json(api("GET", `/repos/${repo}/actions/runs/${run}`, null, PERM.actions));
+  const headRepo = runInfo.head_repository && runInfo.head_repository.full_name;
+  if (!sameRepo(headRepo)) throw new Error(`This run is from a fork (${headRepo || "unknown repository"}). Fork PRs are not supported yet.`);
+  if (!/^[0-9a-f]{40}$/.test(runInfo.head_sha || "")) throw new Error(`CI run ${run} has no head commit.`);
+
+  const expired = new Error(`Artifact ${artifact} has expired or was not found. Re-run CI to get a fresh report.`);
+  let art;
+  try {
+    art = await json(api("GET", `/repos/${repo}/actions/artifacts/${artifact}`, null, PERM.actions));
+  } catch (e) {
+    throw e.status === 404 || e.status === 410 ? expired : e;
+  }
+  if (art.expired) throw expired;
+  if (!(art.size_in_bytes <= MAX_ZIP)) throw new Error(`Artifact ${artifact} is larger than 100 MB; the review page refuses it.`);
+  if (!art.workflow_run || String(art.workflow_run.id) !== run) throw new Error(`Artifact ${artifact} was not made by CI run ${run}. This link is wrong; use the one from the PR comment.`);
+
+  const pull = await json(api("GET", `/repos/${repo}/pulls/${pr}`, null, PERM.pullsRead));
+  if (pull.state !== "open") throw new Error(`PR #${pr} is ${pull.state}, not open.`);
+  if (!sameRepo(pull.head && pull.head.repo && pull.head.repo.full_name)) throw new Error(`PR #${pr} comes from a fork. Fork PRs are not supported yet.`);
+  if (pull.head.sha !== runInfo.head_sha) throw new Error(`PR #${pr} has new commits since CI run ${run}, or the run is not for this PR. Re-run CI and review the new report.`);
+  const branch = pull.head.ref;
+  if (!branch || branch === pull.base.ref || branch === pull.base.repo.default_branch) throw new Error(`Refusing to commit to ${branch}: it is the PR's base branch or the default branch.`);
+  return { sha: runInfo.head_sha, branch };
+}
+
+async function load() {
+  entries.forEach((e) => Object.values(e.images).forEach((url) => URL.revokeObjectURL(url)));
+  entries = [];
+  current = 0;
+  inflatedTotal = 0;
+  $("review").hidden = $("bar").hidden = true;
+  head = await verifyLink();
+
+  say(`Downloading artifact ${artifact}…`);
+  const tooBig = new Error(`Artifact ${artifact} is larger than 100 MB; the review page refuses it.`);
+  const res = await api("GET", `/repos/${repo}/actions/artifacts/${artifact}/zip`, null, PERM.actions);
+  if (Number(res.headers.get("content-length")) > MAX_ZIP) throw tooBig;
+  const buf = await res.arrayBuffer();
+  if (buf.byteLength > MAX_ZIP) throw tooBig;
+  const zip = unzip(buf);
+  const manifestFile = zip.get("snap_diff_manifest.json");
+  if (!manifestFile) throw new Error("The artifact has no snap_diff_manifest.json. The report was made by a snap_diff version without the review page.");
+  const manifest = JSON.parse(new TextDecoder().decode(await inflate(manifestFile)));
+  if (manifest.version !== 1 || !Array.isArray(manifest.entries)) throw new Error("snap_diff_manifest.json has an unknown format.");
+  if (manifest.entries.length > MAX_ENTRIES) throw new Error(`The manifest lists ${manifest.entries.length} screenshots; the review page handles at most ${MAX_ENTRIES}.`);
+
+  const problems = [];
+  for (const m of manifest.entries) {
+    try {
+      entries.push(await readEntry(m, zip));
+    } catch (e) {
+      // Only a bad entry is left out; an API failure or a blown budget stops the whole load.
+      if (e.status || e.fatal) throw e;
+      problems.push(e.message);
+    }
+  }
+  const note = problems.length ? `Left out ${problems.length} screenshot(s):\n${problems.join("\n")}` : "";
+  if (!entries.length) { say(note || "Nothing to review: this report has no changed or new screenshots.", Boolean(note)); return; }
+  say(note, Boolean(note));
+  $("review").hidden = $("bar").hidden = false;
+  render();
+}
+
+const LABELS = { base: "Baseline (committed)", new: "New capture", diff: "Diff on new", baseDiff: "Diff on baseline", heatmap: "Heatmap" };
+function figure(entry, key) {
+  return el("figure", {}, el("figcaption", { textContent: LABELS[key] }),
+    el("a", { href: entry.images[key], target: "_blank", rel: "noopener" }, el("img", { src: entry.images[key], alt: `${entry.name}: ${LABELS[key]}` })));
+}
+
+function render() {
+  const list = $("list");
+  list.replaceChildren(...entries.map((e, i) =>
+    el("button", { type: "button", className: i === current ? "current" : "", onclick: () => { current = i; flipped = false; render(); } },
+      el("span", { className: "name", textContent: e.name }), el("span", { className: "badge", textContent: e.status }),
+      e.decision ? el("span", { className: "badge " + e.decision, textContent: e.decision === "accept" ? "accepted" : "rejected" }) : null)));
+  list.children[current].scrollIntoView({ block: "nearest" });
+
+  const e = entries[current], hasBase = Boolean(e.images.base);
+  const decide = (d, label) => el("button", { type: "button", className: d + (e.decision === d ? " on" : ""), textContent: label, disabled: busy, onclick: () => mark(d) });
+  const viewButton = (v, label) => el("button", { type: "button", className: "view" + (view === v ? " on" : ""), textContent: label, onclick: () => { view = v; render(); } });
+  const shown = !hasBase ? ["new"] : view === "side" ? ["base", "new"] : [flipped ? "base" : "new"];
+  const extras = ["diff", "heatmap", "baseDiff"].filter((k) => e.images[k]);
+  $("viewer").replaceChildren(
+    el("div", { className: "toolbar" },
+      el("strong", { textContent: e.name }), el("span", { className: "muted", textContent: `${e.status} · ${e.path} · ${current + 1}/${entries.length}` }),
+      el("span", { className: "spacer" }), decide("accept", "Accept"), decide("reject", "Reject")),
+    hasBase ? el("div", { className: "toolbar" }, viewButton("side", "Side by side"), viewButton("toggle", "Toggle"),
+      view === "toggle" ? el("button", { type: "button", textContent: `Showing ${flipped ? "baseline" : "new"} — flip (T)`, onclick: flip }) : null) : null,
+    el("div", { className: "images" }, ...shown.map((k) => figure(e, k))),
+    extras.length ? el("h3", { textContent: "Differences" }) : null,
+    el("div", { className: "images" }, ...extras.map((k) => figure(e, k))));
+
+  const counts = { accept: 0, reject: 0, none: 0 };
+  entries.forEach((x) => counts[x.decision || "none"]++);
+  $("counter").textContent = `${counts.accept} accepted · ${counts.reject} rejected · ${counts.none} undecided`;
+  $("submit").disabled = busy || counts.accept + counts.reject === 0;
+}
+
+function mark(d) {
+  if (busy) return;
+  const e = entries[current];
+  e.decision = e.decision === d ? null : d;
+  $("confirm").hidden = true;
+  $("submit").hidden = false;
+  render();
+}
+function move(step) { current = Math.min(entries.length - 1, Math.max(0, current + step)); flipped = false; render(); }
+function flip() { if (view === "toggle") { flipped = !flipped; render(); } }
+
+function base64(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
+  return btoa(s);
+}
+
+async function submit() {
+  const accepted = entries.filter((e) => e.decision === "accept"), rejected = entries.filter((e) => e.decision === "reject");
+  const login = (await json(api("GET", "/user", null, PERM.user))).login;
+  let commit = null;
+  if (accepted.length) {
+    const tree = [];
+    for (const e of accepted) {
+      say(`Uploading ${e.name}…`);
+      const blob = await json(api("POST", `/repos/${repo}/git/blobs`, { content: base64(e.bytes), encoding: "base64" }, PERM.contents));
+      tree.push({ path: e.path, mode: "100644", type: "blob", sha: blob.sha });
+    }
+    say("Creating the commit…");
+    const parent = await json(api("GET", `/repos/${repo}/git/commits/${head.sha}`, null, PERM.contents));
+    const newTree = await json(api("POST", `/repos/${repo}/git/trees`, { base_tree: parent.tree.sha, tree }, PERM.contents));
+    const message = `Accept screenshot baselines\n\n${accepted.map((e) => `- ${e.name}`).join("\n")}\n\nReviewed with the snap_diff review page by @${login}`;
+    commit = await json(api("POST", `/repos/${repo}/git/commits`, { message, tree: newTree.sha, parents: [head.sha] }, PERM.contents));
+    const ref = encodePath(head.branch);
+    try {
+      await api("PATCH", `/repos/${repo}/git/refs/heads/${ref}`, { sha: commit.sha, force: false }, PERM.contents);
+    } catch (e) {
+      if (e.status !== 422) throw e;
+      const now = await json(api("GET", `/repos/${repo}/git/ref/heads/${ref}`, null, PERM.contents));
+      if (now.object.sha !== head.sha) throw new Error(`This PR has new commits since CI run ${run}. Re-run CI and review the new report.`);
+      throw new Error(`GitHub refused to update ${head.branch}: ${e.detail || e.message}`);
+    }
+  }
+  say("Posting the PR comment…");
+  const lines = [`Screenshot review by @${login} (CI run ${run}):`, ""];
+  if (accepted.length) lines.push(`Accepted in ${commit.sha}:`, ...accepted.map((e) => `- \`${e.name}\``), "");
+  if (rejected.length) lines.push("Rejected:", ...rejected.map((e) => `- \`${e.name}\``), "");
+  let comment;
+  try {
+    comment = await json(api("POST", `/repos/${repo}/issues/${pr}/comments`, { body: lines.join("\n").trim() }, PERM.pulls));
+  } catch (e) {
+    if (commit) throw Object.assign(new Error(`Committed ${commit.sha}, but the comment failed: ${e.message}`), { locked: true });
+    throw e;
+  }
+
+  $("msg").className = "";
+  $("msg").replaceChildren(
+    `Done. ${accepted.length} accepted, ${rejected.length} rejected. `,
+    commit ? link(`Commit ${commit.sha.slice(0, 7)}`, commit.html_url) : "No commit (nothing accepted).", " · ",
+    link("PR comment", comment.html_url));
+}
+
+function fail(e) {
+  say(e.message, true);
+  if (e.status === 401) { token = null; $("token-form").hidden = false; }
+}
+
+// The page commits with the reviewer's token, so it only serves the repository it is published for.
+function hostAllows() {
+  const host = location.hostname, segment = (location.pathname.split("/")[1] || "").toLowerCase();
+  const [owner, name] = repo.toLowerCase().split("/");
+  if (host === "localhost" || host === "127.0.0.1") return true;
+  if (host.endsWith(".github.io")) return host === `${owner}.github.io` && segment === name;
+  return segment === name;
+}
+
+const DIGITS = /^[1-9][0-9]{0,18}$/;
+const REPO = /^[A-Za-z0-9-]{1,39}\/(?!\.\.?$)[A-Za-z0-9._-]{1,100}$/;
+if (window.opener || window.top !== window) {
+  say("Open this review page directly in its own tab, not from another page or inside a frame.", true);
+} else if (!REPO.test(repo || "") || ![pr, run, artifact].every((n) => DIGITS.test(n || ""))) {
+  say("This link is missing or has invalid parameters. It needs ?repo=owner/name&pr=<number>&run=<run id>&artifact=<artifact id>, as posted in the PR comment by the snap_diff upload-screenshots action.", true);
+} else if (!hostAllows()) {
+  say(`This review page is published for a different repository and will not review ${repo}. Use the review page of ${repo} itself.`, true);
+} else {
+  $("where").textContent = `${repo} · PR #${pr} · run ${run}`;
+  $("token-form").hidden = false;
+  $("token-form").addEventListener("submit", (ev) => {
+    ev.preventDefault();
+    token = $("token").value.trim();
+    $("token").value = "";
+    $("token-form").hidden = true;
+    $("forget").hidden = false;
+    load().catch(fail);
+  });
+  $("forget").addEventListener("click", () => { token = null; location.reload(); });
+  $("submit").addEventListener("click", () => {
+    const paths = entries.filter((e) => e.decision === "accept").map((e) => e.path);
+    $("confirm-text").replaceChildren(...(paths.length
+      ? [`Commit these ${paths.length} file(s) to ${head.branch} and comment on PR #${pr}:`, el("ul", {}, ...paths.map((p) => el("li", { textContent: p })))]
+      : [`Comment the rejections on PR #${pr}?`]));
+    $("confirm").hidden = false;
+    $("submit").hidden = true;
+  });
+  $("confirm-no").addEventListener("click", () => { $("confirm").hidden = true; $("submit").hidden = false; });
+  $("confirm-yes").addEventListener("click", () => {
+    $("confirm").hidden = true;
+    busy = true;
+    render();
+    // Success, or a commit already on the branch, keeps the page locked: a second submit would commit again.
+    submit().then(render, (e) => {
+      if (!e.locked) { busy = false; $("submit").hidden = false; }
+      render();
+      fail(e);
+    });
+  });
+  document.addEventListener("keydown", (ev) => {
+    if (!entries.length || ev.target.tagName === "INPUT" || ev.ctrlKey || ev.metaKey || ev.altKey) return;
+    const action = { a: () => mark("accept"), r: () => mark("reject"), j: () => move(1), k: () => move(-1), t: flip }[ev.key.toLowerCase()];
+    if (action) { ev.preventDefault(); action(); }
+  });
+}
+})();
+</script>
+</body>
+</html>

From 0f9b141598cc366b0b2de0f5bedda3de62e50e31 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 09:34:35 +0200
Subject: [PATCH 03/16] test: drive the review page against a fake GitHub API

Six browser scenarios: accept/reject commits the exact zip bytes and
comments; a link whose artifact or PR does not belong to the run is
refused before download; a moved branch is not overwritten; a manifest
cannot write non-images or files outside screenshot paths; a bad token
asks again. A unit test keeps the page's CSP script hash in step with
its script.
---
 test/integration/review_page_test.rb | 156 +++++++++++++++++++++++++++
 test/support/fake_github_api.rb      |  98 +++++++++++++++++
 test/unit/review_page_csp_test.rb    |  22 ++++
 3 files changed, 276 insertions(+)
 create mode 100644 test/integration/review_page_test.rb
 create mode 100644 test/support/fake_github_api.rb
 create mode 100644 test/unit/review_page_csp_test.rb

diff --git a/test/integration/review_page_test.rb b/test/integration/review_page_test.rb
new file mode 100644
index 00000000..693ad9d6
--- /dev/null
+++ b/test/integration/review_page_test.rb
@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "base64"
+require "support/setup_capybara_drivers"
+require "support/fake_github_api"
+
+# Drives lib/snap_diff/review/index.html in a real browser against a fake
+# GitHub API. The page is a black box: only what it shows and what it sends.
+class ReviewPageTest < Minitest::Test
+  TOKEN = "ghp_test_token"
+  HOMEPAGE = "doc/screenshots/linux/homepage.png"
+  SIGNUP = "doc/screenshots/linux/signup.png"
+
+  def setup
+    @homepage_png = File.binread(TEST_IMAGES_DIR / "a.png")
+    @signup_png = File.binread(TEST_IMAGES_DIR / "c.png")
+    @baseline_png = File.binread(TEST_IMAGES_DIR / "b.png")
+  end
+
+  def teardown
+    @session&.quit
+  end
+
+  def test_accept_one_reject_one_commits_exact_bytes_and_comments
+    review do |fake|
+      fake.baselines[HOMEPAGE] = @baseline_png
+    end
+    page.find("#list button", text: "homepage").click
+    page.click_button "Accept", exact: true
+    page.find("#list button", text: "signup").click
+    page.click_button "Reject", exact: true
+    submit
+
+    page.assert_text "Done. 1 accepted, 1 rejected."
+    sent = fake.requests
+    blob = only(sent, "POST", "/repos/o/r/git/blobs").json
+    assert_equal "base64", blob[:encoding]
+    assert_equal @homepage_png, Base64.strict_decode64(blob[:content])
+
+    tree = only(sent, "POST", "/repos/o/r/git/trees").json
+    assert_equal [HOMEPAGE], tree[:tree].map { _1[:path] }
+    assert_equal fake.git_sha("tree of head"), tree[:base_tree]
+
+    commit = only(sent, "POST", "/repos/o/r/git/commits").json
+    assert_equal [FakeGithub::HEAD_SHA], commit[:parents]
+
+    patch = only(sent, "PATCH", "/repos/o/r/git/refs/heads/feature").json
+    assert_equal false, patch[:force]
+    assert_equal fake.git_sha(commit.to_json), patch[:sha]
+
+    comment = only(sent, "POST", "/repos/o/r/issues/7/comments").json[:body]
+    assert_includes comment, "homepage"
+    assert_includes comment, "signup"
+
+    assert_equal ["Bearer #{TOKEN}"], sent.map(&:authorization).uniq
+    page.assert_selector :link, "Commit #{patch[:sha][0, 7]}", href: "https://github.com/o/r/commit/#{patch[:sha]}"
+  end
+
+  def test_artifact_from_another_run_is_refused_before_download
+    review { |fake| fake.artifact[:workflow_run][:id] = 99 }
+
+    page.assert_text "was not made by CI run 11"
+    refute_includes fake.requests.map(&:path), "/repos/o/r/actions/artifacts/22/zip"
+    assert_empty fake.writes
+  end
+
+  def test_pr_head_that_moved_since_the_run_is_refused_before_download
+    review { |fake| fake.pull[:head][:sha] = "b2" * 20 }
+
+    page.assert_text "has new commits since CI run 11"
+    refute_includes fake.requests.map(&:path), "/repos/o/r/actions/artifacts/22/zip"
+    assert_empty fake.writes
+  end
+
+  def test_branch_that_moved_between_load_and_submit_is_reported_and_not_commented
+    review do |fake|
+      fake.baselines[HOMEPAGE] = @baseline_png
+      fake.patch_status = 422
+      fake.moved_ref_sha = "c3" * 20
+    end
+    page.find("#list button", text: "homepage").click
+    page.click_button "Accept", exact: true
+    submit
+
+    page.assert_text "This PR has new commits since CI run 11"
+    assert_equal 1, fake.requests.count { _1.method == "PATCH" }
+    assert_empty fake.requests.select { _1.path.end_with?("/comments") }
+  end
+
+  def test_malicious_manifest_entries_cannot_be_accepted_or_written
+    entries = [
+      {name: "rake", status: "new", path: "Rakefile", file: "good.png"},
+      {name: "workflow", status: "new", path: ".github/x.png", file: "good.png"},
+      {name: "fake", status: "new", path: "doc/fake.png", file: "fake.png"},
+      {name: "fine", status: "new", path: "doc/fine.png", file: "good.png"}
+    ]
+    review(entries: entries, files: {"good.png" => @signup_png, "fake.png" => "not a png at all"})
+
+    page.assert_text "Left out 3 screenshot(s)"
+    page.assert_text "refusing path Rakefile"
+    page.assert_text "refusing path .github/x.png"
+    page.assert_text "fake.png is not a real .png image"
+    page.assert_selector "#list button", count: 1
+    page.click_button "Accept", exact: true
+    submit
+
+    page.assert_text "Done. 1 accepted, 0 rejected."
+    tree = only(fake.requests, "POST", "/repos/o/r/git/trees").json
+    assert_equal ["doc/fine.png"], tree[:tree].map { _1[:path] }
+  end
+
+  def test_bad_token_asks_for_the_token_again_and_requests_nothing_else
+    review { |fake| fake.runs_status = 401 }
+
+    page.assert_text "The token is invalid or expired"
+    page.assert_selector "#token-form"
+    assert_equal ["/repos/o/r/actions/runs/11"], fake.requests.map(&:path)
+  end
+
+  private
+
+  attr_reader :fake
+
+  def page = @session
+
+  def review(entries: nil, files: nil)
+    entries ||= [
+      {name: "homepage", status: "changed", path: HOMEPAGE, file: "linux/homepage.png"},
+      {name: "signup", status: "new", path: SIGNUP, file: "linux/signup.png"}
+    ]
+    files ||= {"linux/homepage.png" => @homepage_png, "linux/signup.png" => @signup_png}
+    zip = FakeGithub.zip({"snap_diff_manifest.json" => JSON.generate(version: 1, entries: entries)}.merge(files))
+    @fake = FakeGithub.new(zip: zip)
+    yield @fake if block_given?
+    # the zip size is read when the fake is built; keep the artifact record honest
+    @fake.artifact[:size_in_bytes] = zip.bytesize
+
+    @session = Capybara::Session.new(Capybara.javascript_driver, @fake)
+    @session.config.default_max_wait_time = 10
+    @session.visit "/?repo=o/r&pr=7&run=11&artifact=22"
+    @session.fill_in "token", with: TOKEN
+    @session.click_button "Load screenshots"
+  end
+
+  def submit
+    page.click_button "Submit review"
+    page.click_button "Yes, submit"
+  end
+
+  def only(requests, verb, path)
+    found = requests.select { _1.method == verb && _1.path == path }
+    assert_equal 1, found.size, "expected exactly one #{verb} #{path}, saw #{requests.map { "#{_1.method} #{_1.path}" }}"
+    found.first
+  end
+end
diff --git a/test/support/fake_github_api.rb b/test/support/fake_github_api.rb
new file mode 100644
index 00000000..041bbb0d
--- /dev/null
+++ b/test/support/fake_github_api.rb
@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "rack"
+require "zlib"
+
+# Serves the review page (rewritten to talk to itself) and a fake GitHub REST
+# API from one Rack app, and records every API request it sees.
+class FakeGithub
+  PAGE = Pathname.new(File.expand_path("../../lib/snap_diff/review/index.html", __dir__))
+  HEAD_SHA = "a1" * 20
+  Request = Struct.new(:method, :path, :query, :authorization, :json)
+
+  # The exact text between <script> and </script>; the CSP hashes it.
+  def self.script_sha256(html)
+    "sha256-#{[Digest::SHA256.digest(html[%r{<script>(.*?)</script>}m, 1])].pack("m0")}"
+  end
+
+  # A stored-or-deflated zip with just what the page's reader needs.
+  def self.zip(files)
+    out = +"".b
+    central = +"".b
+    files.each do |name, bytes|
+      bytes = bytes.b
+      deflater = Zlib::Deflate.new(Zlib::DEFAULT_COMPRESSION, -Zlib::MAX_WBITS)
+      packed = deflater.deflate(bytes, Zlib::FINISH)
+      crc = Zlib.crc32(bytes)
+      fields = [20, 0, 8, 0, 0, crc, packed.bytesize, bytes.bytesize, name.bytesize, 0]
+      central << [0x02014b50, 20].pack("Vv") << fields.pack("vvvvvVVVvv") << [0, 0, 0, 0, out.bytesize].pack("vvvVV") << name.b
+      out << [0x04034b50].pack("V") << fields.pack("vvvvvVVVvv") << name.b << packed
+    end
+    out << central << [0x06054b50, 0, 0, files.size, files.size, central.bytesize, out.bytesize - central.bytesize, 0].pack("VvvvvVVv")
+  end
+
+  attr_reader :requests
+  attr_accessor :run, :artifact, :pull, :zip, :baselines, :runs_status, :patch_status, :moved_ref_sha
+
+  def initialize(zip:, baselines: {})
+    @zip = zip
+    @baselines = baselines
+    @requests = []
+    @run = {id: 11, head_sha: HEAD_SHA, head_branch: "feature", event: "pull_request", head_repository: {full_name: "o/r"}}
+    @artifact = {id: 22, expired: false, size_in_bytes: zip.bytesize, workflow_run: {id: 11}}
+    @pull = {state: "open", head: {sha: HEAD_SHA, ref: "feature", repo: {full_name: "o/r"}}, base: {ref: "main", repo: {default_branch: "main"}}}
+  end
+
+  def writes = requests.reject { _1.method == "GET" }
+
+  def git_sha(text) = Digest::SHA1.hexdigest(text)
+
+  def call(env)
+    req = Rack::Request.new(env)
+    return page(req) if req.path_info == "/"
+
+    body = req.body.read
+    json = body.empty? ? nil : JSON.parse(body, symbolize_names: true)
+    requests << Request.new(req.request_method, req.path_info, req.query_string, env["HTTP_AUTHORIZATION"], json)
+    route(req.request_method, req.path_info, json)
+  end
+
+  private
+
+  def route(verb, path, json)
+    case "#{verb} #{path}"
+    when "GET /user" then reply(200, login: "reviewer")
+    when %r{\AGET /repos/o/r/actions/runs/\d+\z} then runs_status ? reply(runs_status, message: "Bad credentials") : reply(200, run)
+    when %r{\AGET /repos/o/r/actions/artifacts/\d+\z} then reply(200, artifact)
+    when %r{\AGET /repos/o/r/actions/artifacts/\d+/zip\z} then [303, {"location" => "/blob/artifact.zip"}, []]
+    when "GET /blob/artifact.zip" then [200, {"content-type" => "application/zip"}, [zip]]
+    when %r{\AGET /repos/o/r/pulls/\d+\z} then reply(200, pull)
+    when %r{\AGET /repos/o/r/contents/(.+)\z}
+      (bytes = baselines[$1]) ? [200, {"content-type" => "application/vnd.github.raw"}, [bytes]] : reply(404, message: "Not Found")
+    when "POST /repos/o/r/git/blobs" then reply(201, sha: git_sha(json[:content]))
+    when %r{\AGET /repos/o/r/git/commits/\h{40}\z} then reply(200, sha: HEAD_SHA, tree: {sha: git_sha("tree of head")})
+    when "POST /repos/o/r/git/trees" then reply(201, sha: git_sha(json.to_json))
+    when "POST /repos/o/r/git/commits" then reply(201, sha: git_sha(json.to_json), html_url: "https://github.com/o/r/commit/#{git_sha(json.to_json)}")
+    when %r{\APATCH /repos/o/r/git/refs/heads/.+\z}
+      patch_status ? reply(patch_status, message: "Update is not a fast forward") : reply(200, object: {sha: json[:sha]})
+    when %r{\AGET /repos/o/r/git/refs?/heads/.+\z} then reply(200, object: {sha: moved_ref_sha || HEAD_SHA})
+    when %r{\APOST /repos/o/r/issues/\d+/comments\z} then reply(201, html_url: "https://github.com/o/r/pull/7#issuecomment-1")
+    else reply(404, message: "fake has no route for #{verb} #{path}")
+    end
+  end
+
+  def reply(status, hash) = [status, {"content-type" => "application/json"}, [JSON.generate(hash)]]
+
+  # The page under test with its two hooks used: the API origin and the CSP.
+  # Changing the script changes its hash, so the hash is recomputed here.
+  def page(req)
+    origin = "#{req.scheme}://#{req.host_with_port}"
+    html = PAGE.read
+    html = html.sub('const API = "https://api.github.com";', %(const API = "#{origin}";))
+    html = html.sub("connect-src https://api.github.com", "connect-src #{origin}")
+    html = html.sub(/'sha256-[^']+'/, "'#{self.class.script_sha256(html)}'")
+    [200, {"content-type" => "text/html"}, [html]]
+  end
+end
diff --git a/test/unit/review_page_csp_test.rb b/test/unit/review_page_csp_test.rb
new file mode 100644
index 00000000..4de6bd1c
--- /dev/null
+++ b/test/unit/review_page_csp_test.rb
@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "support/fake_github_api"
+
+class ReviewPageCspTest < Minitest::Test
+  def test_csp_script_hash_matches_the_inline_script
+    html = FakeGithub::PAGE.read
+
+    assert_equal 1, html.scan(/<script\b/).size, "the page must have exactly one inline script"
+    declared = html[/<meta http-equiv="Content-Security-Policy" content="[^"]*script-src '(sha256-[^']+)'/, 1]
+    refute_nil declared, "the CSP meta has no script-src 'sha256-...'"
+    actual = FakeGithub.script_sha256(html)
+
+    assert_equal actual, declared, <<~MSG
+      The CSP script hash in lib/snap_diff/review/index.html is stale (the browser would refuse to run the page).
+      Recompute it: take the exact text between <script> and </script> and run
+        ruby -rdigest -e 'puts "sha256-" + [Digest::SHA256.digest(File.read("lib/snap_diff/review/index.html")[%r{<script>(.*?)</script>}m, 1])].pack("m0")'
+      then paste the result into the meta's script-src.
+    MSG
+  end
+end

From d98318ec50e4ef88dd5473999698a0f55fc3f8b9 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 09:36:54 +0200
Subject: [PATCH 04/16] fix: the review page no longer shows "null" for a new
 screenshot

replaceChildren renders a null child as the text "null"; the parts a
new screenshot lacks (the base/new toggle, the differences heading) are
now left out instead.
---
 lib/snap_diff/review/index.html      | 7 ++++---
 test/integration/review_page_test.rb | 2 ++
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/lib/snap_diff/review/index.html b/lib/snap_diff/review/index.html
index bb18bc61..0502804f 100644
--- a/lib/snap_diff/review/index.html
+++ b/lib/snap_diff/review/index.html
@@ -4,7 +4,7 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <!-- script-src carries the sha256 (base64) of the exact text of the one inline script element below. Recompute it whenever that script changes, or the page will not run. -->
-<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'sha256-MW6NpEd5ZbwAohpVGXi77Ygw4qUokSaEtb0r/RfQOQ0='; style-src 'unsafe-inline'; img-src blob:; connect-src https://api.github.com https://*.blob.core.windows.net; base-uri 'none'; form-action 'none'">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'sha256-kFkAY+0J3mvs3+iH1JY0RXC8LrKjgogdjhlwH6hlPy4='; style-src 'unsafe-inline'; img-src blob:; connect-src https://api.github.com https://*.blob.core.windows.net; base-uri 'none'; form-action 'none'">
 <meta name="referrer" content="no-referrer">
 <title>snap_diff review</title>
 <style>
@@ -327,7 +327,8 @@ <h1>snap_diff review</h1>
   const viewButton = (v, label) => el("button", { type: "button", className: "view" + (view === v ? " on" : ""), textContent: label, onclick: () => { view = v; render(); } });
   const shown = !hasBase ? ["new"] : view === "side" ? ["base", "new"] : [flipped ? "base" : "new"];
   const extras = ["diff", "heatmap", "baseDiff"].filter((k) => e.images[k]);
-  $("viewer").replaceChildren(
+  // replaceChildren would print a null as the text "null": optional parts are filtered out.
+  $("viewer").replaceChildren(...[
     el("div", { className: "toolbar" },
       el("strong", { textContent: e.name }), el("span", { className: "muted", textContent: `${e.status} · ${e.path} · ${current + 1}/${entries.length}` }),
       el("span", { className: "spacer" }), decide("accept", "Accept"), decide("reject", "Reject")),
@@ -335,7 +336,7 @@ <h1>snap_diff review</h1>
       view === "toggle" ? el("button", { type: "button", textContent: `Showing ${flipped ? "baseline" : "new"} — flip (T)`, onclick: flip }) : null) : null,
     el("div", { className: "images" }, ...shown.map((k) => figure(e, k))),
     extras.length ? el("h3", { textContent: "Differences" }) : null,
-    el("div", { className: "images" }, ...extras.map((k) => figure(e, k))));
+    el("div", { className: "images" }, ...extras.map((k) => figure(e, k)))].filter((c) => c != null));
 
   const counts = { accept: 0, reject: 0, none: 0 };
   entries.forEach((x) => counts[x.decision || "none"]++);
diff --git a/test/integration/review_page_test.rb b/test/integration/review_page_test.rb
index 693ad9d6..0a9eddd3 100644
--- a/test/integration/review_page_test.rb
+++ b/test/integration/review_page_test.rb
@@ -29,6 +29,8 @@ def test_accept_one_reject_one_commits_exact_bytes_and_comments
     page.find("#list button", text: "homepage").click
     page.click_button "Accept", exact: true
     page.find("#list button", text: "signup").click
+    page.assert_text "New capture"
+    refute_match(/\bnull\b/, page.text)
     page.click_button "Reject", exact: true
     submit
 

From 14f7a2f48d4b06c08d66b9fb074ad8c3080515c2 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 09:45:07 +0200
Subject: [PATCH 05/16] fix: the manifest names each screenshot by its path
 from the git root

The review page commits a screenshot at its manifest path, and the gem
reads baselines with git show HEAD:<path from the git root>. Paths were
relative to SnapDiff.config.root, so a suite whose root is a
subdirectory of the repository (this gem's own, monorepos, engines)
would have been accepted into the wrong file.
---
 lib/snap_diff/reporters/html.rb           | 10 ++++--
 test/unit/reporters/html_reporter_test.rb | 39 ++++++++++++++++++++---
 2 files changed, 43 insertions(+), 6 deletions(-)

diff --git a/lib/snap_diff/reporters/html.rb b/lib/snap_diff/reporters/html.rb
index 514f4e5a..f2823722 100644
--- a/lib/snap_diff/reporters/html.rb
+++ b/lib/snap_diff/reporters/html.rb
@@ -10,6 +10,7 @@
 # SnapDiff::Reporting.
 require "snap_diff/reporting"
 require "snap_diff/config"
+require "snap_diff/vcs"
 
 module SnapDiff
   module Reporters
@@ -244,11 +245,16 @@ def display_path(path)
       # Raw paths for snap_diff_manifest.json (the template leaves them out):
       # the capture is both what is committed (`path`, the baseline's own
       # path, which the failing run already overwrote) and what the report
-      # dir holds (`file`). String keys: entries pass through JSON in dump_state.
+      # dir holds (`file`). `path` is relative to the git root, the form
+      # Vcs hands `git show HEAD:`; with no repository nothing can be
+      # committed. String keys: entries pass through JSON in dump_state.
       def accept_paths(capture)
         return unless capture && File.exist?(capture)
 
-        {"path" => display_path(capture), "file" => Pathname(capture).expand_path.relative_path_from(output_path.dirname.expand_path).to_s}
+        git_root = SnapDiff::Vcs.git_root_for(SnapDiff.config.root.to_s)
+        return unless git_root
+
+        {"path" => Pathname(capture).realpath.relative_path_from(Pathname(git_root).realpath).to_s, "file" => Pathname(capture).expand_path.relative_path_from(output_path.dirname.expand_path).to_s}
       end
 
       def resolve_image(path)
diff --git a/test/unit/reporters/html_reporter_test.rb b/test/unit/reporters/html_reporter_test.rb
index cb823062..16bd1c99 100644
--- a/test/unit/reporters/html_reporter_test.rb
+++ b/test/unit/reporters/html_reporter_test.rb
@@ -493,12 +493,14 @@ def synchronize
     entry = manifest.fetch("entries").sole
     assert_equal 1, manifest.fetch("version")
     assert_equal %w[index changed], entry.values_at("name", "status")
-    assert_equal reporter.send(:display_path, assertion.compare.image_path), entry["path"]
+    git_root = Pathname(SnapDiff::Vcs.git_root_for(SnapDiff.config.root.to_s)).realpath
+    assert_equal assertion.compare.image_path.realpath.relative_path_from(git_root).to_s, entry["path"]
     assert_no_match(/\.base\.png\z/, entry["path"])
     assert_equal assertion.compare.image_path.to_s, (@output_dir / entry["file"]).realpath.to_s
   end
 
   test "the manifest lists a new capture with its status" do
+    git_init_output_dir
     reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
     capture_new_screenshot(reporter, "signup")
     reporter.finalize
@@ -508,7 +510,30 @@ def synchronize
     assert_predicate @output_dir / "screenshots/signup.png", :exist?
   end
 
+  # The reviewer page commits `path` at the git root, where vcs.rb reads
+  # `git show HEAD:<path>` -- not at the project root, which may be a subdirectory.
+  test "the manifest path is relative to the git root when the project root is a subdirectory" do
+    git_init_output_dir
+    project = @output_dir / "sub"
+    project.mkpath
+    SnapDiff::Vcs.instance_variable_get(:@git_roots).delete(project.to_s)
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    capture_new_screenshot(reporter, "x", root: project)
+    reporter.finalize
+
+    assert_equal "sub/screenshots/x.png", manifest.fetch("entries").sole["path"]
+  end
+
+  test "an entry outside any git repository is not in the manifest" do
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    SnapDiff::Vcs.stub(:git_root_for, false) { capture_new_screenshot(reporter, "x") }
+    reporter.finalize
+
+    assert_empty manifest.fetch("entries")
+  end
+
   test "the manifest carries file paths when images are embedded" do
+    git_init_output_dir
     reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path, embed_images: true)
     reporter.record([build_failing_assertion("index")])
     capture_new_screenshot(reporter, "signup")
@@ -522,6 +547,7 @@ def synchronize
   end
 
   test "the manifest leaves out re-recorded entries and entries with no capture on disk" do
+    git_init_output_dir
     reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
     reporter.record([build_rerecorded_assertion("accepted")])
     reporter.record([SnapDiff::ScreenshotAssertion.new("gone", path: @output_dir / "screenshots/gone.png")])
@@ -540,6 +566,7 @@ def synchronize
   end
 
   test "the manifest survives the fork-parallel dump and merge" do
+    git_init_output_dir
     worker = SnapDiff::Reporters::HTML.new(output_path: @output_path)
     worker.record([build_failing_assertion("index")])
     capture_new_screenshot(worker, "signup")
@@ -563,6 +590,10 @@ def synchronize
 
   private
 
+  def git_init_output_dir
+    system("git", "-C", @output_dir.to_s, "init", "-q", exception: true)
+  end
+
   def manifest
     JSON.parse((@output_dir / "snap_diff_manifest.json").read)
   end
@@ -570,12 +601,12 @@ def manifest
   # A capture under a project rooted at @output_dir, tallied the way
   # ScreenshotMatcher tallies it. The root is pinned for the rest of the
   # test so display paths are predictable.
-  def capture_new_screenshot(reporter, name, dir: "screenshots")
-    path = @output_dir / dir / "#{name}.png"
+  def capture_new_screenshot(reporter, name, dir: "screenshots", root: @output_dir)
+    path = root / dir / "#{name}.png"
     path.dirname.mkpath
     FileUtils.cp(File.expand_path("a.png", TEST_IMAGES_DIR), path)
     original_root = SnapDiff.config.root
-    SnapDiff.config.root = @output_dir
+    SnapDiff.config.root = root
     @restore_root ||= -> { SnapDiff.config.root = original_root }
     reporter.record([SnapDiff::ScreenshotAssertion.new(name, path: path)])
     path

From e56aea484fb7a91a954229f5b96e52863c0f8b79 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 09:57:16 +0200
Subject: [PATCH 06/16] feat: install and auto-update the review page on a
 project's GitHub Pages

The deploy-review-page action publishes the page shipped in the locked
gem version (either gem name) to gh-pages:snap-diff/index.html, leaving
the rest of that branch alone; a consumer workflow re-runs it when
Gemfile.lock changes, so a gem bump updates the page. This repository
publishes its own copy from lib/ with the page: input.

upload-screenshots adds a Review & accept link to the job summary and PR
comment when the page is installed. Docs cover install, the token to
create, limits and the security model.
---
 .github/actions/deploy-review-page/action.yml | 101 ++++++++++++++++++
 .github/actions/upload-screenshots/action.yml |  26 +++++
 .github/workflows/review-page.yml             |  30 ++++++
 CHANGELOG.md                                  |   7 ++
 README.md                                     |   1 +
 docs/ci-integration.md                        |  79 ++++++++++++++
 docs/organization.md                          |   2 +-
 docs/reporters.md                             |   5 +
 8 files changed, 250 insertions(+), 1 deletion(-)
 create mode 100644 .github/actions/deploy-review-page/action.yml
 create mode 100644 .github/workflows/review-page.yml

diff --git a/.github/actions/deploy-review-page/action.yml b/.github/actions/deploy-review-page/action.yml
new file mode 100644
index 00000000..cebc642f
--- /dev/null
+++ b/.github/actions/deploy-review-page/action.yml
@@ -0,0 +1,101 @@
+---
+name: 'Deploy the SnapDiff review page'
+description: 'Publish the click-to-accept review page to gh-pages at snap-diff/index.html'
+inputs:
+  page:
+    description: 'Path to an index.html to publish (skips the snap_diff-capybara gem lookup)'
+    default: ''
+  token:
+    description: 'Token that can push to gh-pages (the job needs contents: write)'
+    default: ${{ github.token }}
+runs:
+  using: 'composite'
+  steps:
+    - name: Resolve the review page
+      id: resolve
+      shell: bash
+      env:
+        PAGE: ${{ inputs.page }}
+      run: |
+        set -euo pipefail
+        if [ -n "$PAGE" ]; then
+          echo "file=$(realpath "$PAGE")" >> "$GITHUB_OUTPUT"
+          echo "source=from $PAGE" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        # No checkout assumed beyond the lockfile: the version the app locks is the
+        # version whose page it gets, so a Dependabot bump republishes the page.
+        lock=$(ls Gemfile.lock gems.locked 2>/dev/null | head -n 1 || true)
+        [ -n "$lock" ] || { echo "::error::No Gemfile.lock or gems.locked here (is actions/checkout before this step?). Pass page: to publish a file instead."; exit 1; }
+
+        # Only a GEM section is a released version; GIT and PATH entries have no .gem to fetch.
+        # The gem publishes under both names; fetch whichever one the app locks. tr: CRLF lockfiles.
+        found=$(tr -d '\r' < "$lock" | awk '/^[A-Z][A-Z ]*$/ {section=$0} section=="GEM" && /^    (snap_diff-capybara|capybara-screenshot-diff) \(/ {gsub(/[()]/, "", $2); print $1, $2; exit}')
+        if [ -z "$found" ]; then
+          echo "::error::snap_diff-capybara (or capybara-screenshot-diff) is not under a GEM section of $lock (it is a GIT/PATH gem or missing). Pass page: with a path to a review page index.html."
+          exit 1
+        fi
+        name=${found% *}
+        version=${found#* }
+
+        work=$(mktemp -d "$RUNNER_TEMP/snap-diff-gem.XXXXXX")
+        (cd "$work" && gem fetch "$name" -v "$version" && gem unpack "$name-$version.gem" --target .)
+        file="$work/$name-$version/lib/snap_diff/review/index.html"
+        [ -f "$file" ] || { echo "::error::$name $version has no review page; upgrade."; exit 1; }
+        echo "file=$file" >> "$GITHUB_OUTPUT"
+        echo "source=($name $version)" >> "$GITHUB_OUTPUT"
+
+    - name: Publish to gh-pages
+      shell: bash
+      env:
+        PAGE_FILE: ${{ steps.resolve.outputs.file }}
+        SOURCE: ${{ steps.resolve.outputs.source }}
+        TOKEN: ${{ inputs.token }}
+        REPO: ${{ github.repository }}
+      run: |
+        set -euo pipefail
+        # A scratch clone, so it works whatever checkout ran (or none) and never
+        # touches the caller's working tree or branch.
+        work=$(mktemp -d "$RUNNER_TEMP/gh-pages.XXXXXX")
+        cd "$work"
+        git init -q .
+        git remote add origin "https://x-access-token:${TOKEN}@github.com/${REPO}.git"
+
+        # 0 = branch exists, 2 = it does not; anything else (bad token) must fail, not create a branch.
+        status=0
+        git ls-remote --exit-code --heads origin gh-pages > /dev/null 2>&1 || status=$?
+        case "$status" in
+          0)
+            git fetch -q --depth=1 origin gh-pages
+            git checkout -q -b gh-pages FETCH_HEAD
+            ;;
+          2)
+            git checkout -q --orphan gh-pages
+            touch .nojekyll
+            ;;
+          *)
+            echo "::error::Could not reach $REPO to look for gh-pages (git exit $status). Check the token and contents: write."
+            exit 1
+            ;;
+        esac
+
+        mkdir -p snap-diff
+        cp "$PAGE_FILE" snap-diff/index.html
+        git add .
+        if git diff --cached --quiet; then
+          echo "snap-diff/index.html is already up to date."
+        else
+          git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
+            commit -q -m "Update the snap_diff review page $SOURCE"
+          git push -q origin gh-pages
+        fi
+
+        owner=$(printf '%s' "${REPO%%/*}" | tr '[:upper:]' '[:lower:]')
+        cat >> "$GITHUB_STEP_SUMMARY" <<EOF
+        ### SnapDiff review page
+
+        https://${owner}.github.io/${REPO#*/}/snap-diff/
+
+        First time? Settings -> Pages -> Build and deployment -> Deploy from a branch -> gh-pages / (root).
+        EOF
diff --git a/.github/actions/upload-screenshots/action.yml b/.github/actions/upload-screenshots/action.yml
index 7a937a8e..7852792c 100644
--- a/.github/actions/upload-screenshots/action.yml
+++ b/.github/actions/upload-screenshots/action.yml
@@ -74,6 +74,30 @@ runs:
         retention-days: ${{ inputs.retention-days }}
         path: ${{ inputs.report-path }}/
 
+    - name: Check for the review page
+      id: review
+      if: steps.check-report.outputs.exists == 'true' && github.event_name == 'pull_request'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+        REPO: ${{ github.repository }}
+        PR: ${{ github.event.pull_request.number }}
+        RUN_ID: ${{ github.run_id }}
+        ARTIFACT_ID: ${{ steps.upload-report-full.outputs.artifact-id }}
+      run: |
+        # 404 = deploy-review-page never ran here: silent. Anything else is worth a warning, but never fails the job.
+        code=$(curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $GH_TOKEN" \
+          "https://api.github.com/repos/$REPO/contents/snap-diff/index.html?ref=gh-pages") || code="curl failed"
+        case "$code" in
+          200)
+            owner=$(printf '%s' "${REPO%%/*}" | tr '[:upper:]' '[:lower:]')
+            url="https://${owner}.github.io/${REPO#*/}/snap-diff/?repo=${REPO}&pr=${PR}&run=${RUN_ID}&artifact=${ARTIFACT_ID}"
+            echo "row=| [Review & accept]($url) | Accept or reject in the browser |" >> "$GITHUB_OUTPUT"
+            ;;
+          404) ;;
+          *) echo "::warning::Could not check for the review page (status: $code); no Review & accept link." ;;
+        esac
+
     - name: Job summary
       if: steps.check-report.outputs.exists == 'true'
       shell: bash
@@ -85,6 +109,7 @@ runs:
         |----------|------|
         | HTML report (inline) | ${{ steps.upload-report.outputs.artifact-url || 'N/A' }} |
         | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
+        ${{ steps.review.outputs.row }}
         EOF
 
     - name: Find existing PR comment
@@ -111,3 +136,4 @@ runs:
           | HTML report (inline) | ${{ steps.upload-report.outputs.artifact-url || 'N/A' }} |
           | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
           | [All artifacts](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}#artifacts) | Browse all |
+          ${{ steps.review.outputs.row }}
diff --git a/.github/workflows/review-page.yml b/.github/workflows/review-page.yml
new file mode 100644
index 00000000..71743532
--- /dev/null
+++ b/.github/workflows/review-page.yml
@@ -0,0 +1,30 @@
+---
+name: Review page
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - 'lib/snap_diff/review/**'
+      - '.github/actions/deploy-review-page/**'
+      - '.github/workflows/review-page.yml'
+  workflow_dispatch:
+
+# Two pushes racing to gh-pages would fail the second as a non-fast-forward.
+concurrency:
+  group: review-page
+
+jobs:
+  deploy:
+    name: Publish the review page
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: ./.github/actions/deploy-review-page
+        with:
+          page: lib/snap_diff/review/index.html
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 64b0677e..efc5e566 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,13 @@ kept as history. This entry is the one to read if you are coming from **1.15.1**
   selects `record = :all` for the run that sees it, outranking `record =` and `fail_if_new`; a
   `record:` on the screenshot still outranks it. `1` and `true` turn it on; any other value is the
   same as not setting it. Unset, the mode reads as before (`:none` under CI, `:once` off it).
+- **Accept or reject screenshots in the browser.** The HTML report now writes
+  `snap_diff_manifest.json` beside it, and `deploy-review-page` publishes a review page
+  (shipped in the gem, `lib/snap_diff/review/`) to your `gh-pages` at `snap-diff/`, kept
+  current from the version in `Gemfile.lock`. A reviewer marks each changed or new screenshot
+  Accept or Reject; the accepted ones become one commit on the PR branch and a PR comment
+  lists the decisions. `upload-screenshots` links to it once it is installed. See
+  [docs/ci-integration.md](docs/ci-integration.md#accept-or-reject-screenshots-in-the-browser)
 
 - **AI triage (optional, offline-first, advisory by default).** `SnapDiff::Reporters::AISimple`
   classifies every failed comparison as `flaky` / `intentional` / `real_bug`,
diff --git a/README.md b/README.md
index 699b2032..389a3798 100644
--- a/README.md
+++ b/README.md
@@ -115,6 +115,7 @@ Add diff artifacts to `.gitignore` — these are generated at runtime and should
 *.diff.webp
 *.base.webp
 snap_diff_report.html
+snap_diff_manifest.json
 ```
 
 If you skip Step 2 and push to CI, the build will fail — `fail_if_new` is `true` by default in CI.
diff --git a/docs/ci-integration.md b/docs/ci-integration.md
index c4e11e1e..15f2473c 100644
--- a/docs/ci-integration.md
+++ b/docs/ci-integration.md
@@ -191,6 +191,85 @@ jobs:
 
 </details>
 
+## Accept or reject screenshots in the browser
+
+A static page, hosted on your repository's own GitHub Pages, that lists every changed and new
+screenshot of a CI run with its diff. A reviewer marks each one Accept or Reject and presses
+Submit. The accepted images land as **one commit on the PR branch**, byte-identical to what CI
+captured, and **one PR comment** lists what was accepted (with the commit SHA) and rejected. The
+check stays red for the rejected ones. Once the page is installed,
+[`upload-screenshots`](#2-reusable-composite-action-recommended) adds a "Review & accept" link to
+the job summary, and to the PR comment when `pr-comment: 'true'`.
+
+### Install
+
+Copy this workflow:
+
+```yaml
+# .github/workflows/review-page.yml
+name: Review page
+on:
+  push:
+    branches: [ main ]       # your default branch
+    paths: [ Gemfile.lock ]
+  workflow_dispatch:
+permissions:
+  contents: write
+concurrency:
+  group: snap-diff-review-page   # two racing runs would reject one push
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: snap-diff/snap_diff-capybara/.github/actions/deploy-review-page@master
+```
+
+Run it once with "Run workflow". It publishes `snap-diff/index.html` to the `gh-pages` branch
+(created if missing, everything else on the branch is left alone) and prints the page URL
+(`https://<owner>.github.io/<repo>/snap-diff/`) in the job summary. Then, once the branch exists,
+enable Pages: Settings -> Pages -> Build and deployment -> Deploy from a branch -> `gh-pages` /
+`(root)`.
+
+### Auto-update
+
+The page ships inside the gem. The workflow reads the `snap_diff-capybara` version locked in
+`Gemfile.lock` (or `gems.locked`) and publishes the page from that exact release. A Dependabot
+bundler bump changes `Gemfile.lock`, so merging it republishes the page. A gem that is locked from
+git or a path has no release to read: pass `page:` with a path to an `index.html` instead.
+
+### The token
+
+The page asks the reviewer for a fine-grained personal access token. Create it under Settings ->
+Developer settings -> Fine-grained tokens:
+
+- Repository access: only this repository
+- Actions: Read
+- Contents: Read and write
+- Pull requests: Read and write
+- A short expiry
+
+### Limits
+
+- Same-repository PRs only. A PR from a fork is refused: the token cannot write to the fork.
+- It reads the run's report artifact, so it works until `retention-days` (default `2`) expires.
+  After that, re-run CI.
+- The page works only for the repository that hosts it, and refuses to run inside a frame or a
+  window opened by another page.
+- Pages must be served from the `gh-pages` branch (root) of this repository: not the "GitHub
+  Actions" source, not `main`:`/docs`. A user-site repository named `<owner>.github.io` is not
+  supported.
+- A custom-domain site must keep the `/<repo>/` path segment, so the page stays at
+  `/<repo>/snap-diff/`.
+- If the PR branch has new commits since the CI run, nothing is written: re-run CI and review again.
+
+### Security model
+
+The page cross-checks the ids in its link (run, PR and artifact) against GitHub before it writes
+anything. It writes only `.png` and `.webp` image bytes, only at the screenshot paths CI listed in
+`snap_diff_manifest.json`. It never force-pushes: a moved branch is an error, not an overwrite. The
+token is kept in memory for the page load and is never stored.
+
 ## Update Baselines in CI
 
 When intentional UI changes are made, baselines need to be re-recorded. Baselines are
diff --git a/docs/organization.md b/docs/organization.md
index 541f6f27..004e5859 100644
--- a/docs/organization.md
+++ b/docs/organization.md
@@ -33,7 +33,7 @@ version control system (git).
 
 Screenshots are compared to the previously COMMITTED version of the same screenshot.
 
-**Note:** When a screenshot differs, diff artifacts (`.diff.png`, `.heatmap.diff.png`, etc.) are generated alongside the baseline. Add `*.diff.png`, `*.base.png`, `*.diff.webp`, `*.base.webp`, and `snap_diff_report.html` to your `.gitignore`. Clean up artifacts with `rake snap_diff:clean`.
+**Note:** When a screenshot differs, diff artifacts (`.diff.png`, `.heatmap.diff.png`, etc.) are generated alongside the baseline. Add `*.diff.png`, `*.base.png`, `*.diff.webp`, `*.base.webp`, `snap_diff_report.html`, and `snap_diff_manifest.json` to your `.gitignore`. Clean up artifacts with `rake snap_diff:clean`.
 
 ## Screenshot groups
 
diff --git a/docs/reporters.md b/docs/reporters.md
index b70d50b1..e1479c75 100644
--- a/docs/reporters.md
+++ b/docs/reporters.md
@@ -24,6 +24,11 @@ committing it is what accepts it). Their count in the report is the summary line
 
 **Note:** The report is not written when every screenshot matched and none is new.
 
+Beside the report it writes `snap_diff_manifest.json`: one entry per changed or new screenshot with
+its `name`, `status`, repo-relative baseline `path` and the capture `file`. The
+[browser review page](ci-integration.md#accept-or-reject-screenshots-in-the-browser) reads it; add
+it to your `.gitignore` next to `snap_diff_report.html`.
+
 ## The end-of-run summary
 
 Every run ends with what it actually did, whether or not you require a reporter:

From 552eb0ad36dadf5c2d5a456f79820c31158b0565 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 09:57:16 +0200
Subject: [PATCH 07/16] ci: upload this suite's HTML report from where it is
 written

The functional job used the default report-path (doc/screenshots), but
the suite's SnapDiff root is test/fixtures/app, so a failing run never
uploaded its HTML report.
---
 .github/workflows/test.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 6dc565a0..22460eab 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -95,6 +95,8 @@ jobs:
         if: failure()
         with:
           name: base-screenshots
+          # The suite writes its report under its own SnapDiff root.
+          report-path: test/fixtures/app/doc/screenshots
           pr-comment: 'true'
 
       - name: Uploading Coverage Report

From 6584b6839ed72be47d9b7216653ddb4b04bddd35 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 10:14:25 +0200
Subject: [PATCH 08/16] fix: link the review page only when it is actually
 served

Checking for the file on gh-pages linked a 404 whenever Pages serves
another source (this repository served master). Probe the page URL
instead: 200 links, 404 stays silent, anything else warns.
---
 .github/actions/upload-screenshots/action.yml | 15 ++++++++-------
 docs/ci-integration.md                        |  6 +++---
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/.github/actions/upload-screenshots/action.yml b/.github/actions/upload-screenshots/action.yml
index 7852792c..a1e3838c 100644
--- a/.github/actions/upload-screenshots/action.yml
+++ b/.github/actions/upload-screenshots/action.yml
@@ -79,23 +79,24 @@ runs:
       if: steps.check-report.outputs.exists == 'true' && github.event_name == 'pull_request'
       shell: bash
       env:
-        GH_TOKEN: ${{ github.token }}
         REPO: ${{ github.repository }}
         PR: ${{ github.event.pull_request.number }}
         RUN_ID: ${{ github.run_id }}
         ARTIFACT_ID: ${{ steps.upload-report-full.outputs.artifact-id }}
       run: |
-        # 404 = deploy-review-page never ran here: silent. Anything else is worth a warning, but never fails the job.
-        code=$(curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $GH_TOKEN" \
-          "https://api.github.com/repos/$REPO/contents/snap-diff/index.html?ref=gh-pages") || code="curl failed"
+        # Probe the page we are about to link: a file on gh-pages proves nothing if Pages serves
+        # something else. 404 = not installed (silent); anything else is a warning, never a failure.
+        owner=$(printf '%s' "${REPO%%/*}" | tr '[:upper:]' '[:lower:]')
+        page="https://${owner}.github.io/${REPO#*/}/snap-diff/"
+        # -L: a custom domain redirects from github.io
+        code=$(curl -sL --max-time 10 -o /dev/null -w '%{http_code}' "$page") || code="curl failed"
         case "$code" in
           200)
-            owner=$(printf '%s' "${REPO%%/*}" | tr '[:upper:]' '[:lower:]')
-            url="https://${owner}.github.io/${REPO#*/}/snap-diff/?repo=${REPO}&pr=${PR}&run=${RUN_ID}&artifact=${ARTIFACT_ID}"
+            url="${page}?repo=${REPO}&pr=${PR}&run=${RUN_ID}&artifact=${ARTIFACT_ID}"
             echo "row=| [Review & accept]($url) | Accept or reject in the browser |" >> "$GITHUB_OUTPUT"
             ;;
           404) ;;
-          *) echo "::warning::Could not check for the review page (status: $code); no Review & accept link." ;;
+          *) echo "::warning::Could not check the review page at $page (status: $code); no Review & accept link." ;;
         esac
 
     - name: Job summary
diff --git a/docs/ci-integration.md b/docs/ci-integration.md
index 15f2473c..3ad33385 100644
--- a/docs/ci-integration.md
+++ b/docs/ci-integration.md
@@ -197,9 +197,9 @@ A static page, hosted on your repository's own GitHub Pages, that lists every ch
 screenshot of a CI run with its diff. A reviewer marks each one Accept or Reject and presses
 Submit. The accepted images land as **one commit on the PR branch**, byte-identical to what CI
 captured, and **one PR comment** lists what was accepted (with the commit SHA) and rejected. The
-check stays red for the rejected ones. Once the page is installed,
-[`upload-screenshots`](#2-reusable-composite-action-recommended) adds a "Review & accept" link to
-the job summary, and to the PR comment when `pr-comment: 'true'`.
+check stays red for the rejected ones. Once the page is installed and served,
+[`upload-screenshots`](#2-reusable-composite-action-recommended) adds a "Review & accept" link to the job summary, and to the PR comment when
+`pr-comment: 'true'`. The link appears only when the page URL actually answers 200.
 
 ### Install
 

From 73023a47f329b59dbe54a82770745ba88b478c20 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 10:43:12 +0200
Subject: [PATCH 09/16] fix: the manifest lists each screenshot file once, and
 only files in the report

Real CI output had one baseline captured by six tests and new captures
saved outside the report directory. Accepting two entries for one file
fails the commit, and a capture outside the report is not in the
uploaded artifact. Keep the last capture per path, and leave out
captures the artifact cannot contain.
---
 lib/snap_diff/reporters/html.rb           |  6 +++-
 test/unit/reporters/html_reporter_test.rb | 43 ++++++++++++++++++-----
 2 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/lib/snap_diff/reporters/html.rb b/lib/snap_diff/reporters/html.rb
index f2823722..7f321b4a 100644
--- a/lib/snap_diff/reporters/html.rb
+++ b/lib/snap_diff/reporters/html.rb
@@ -254,7 +254,10 @@ def accept_paths(capture)
         git_root = SnapDiff::Vcs.git_root_for(SnapDiff.config.root.to_s)
         return unless git_root
 
-        {"path" => Pathname(capture).realpath.relative_path_from(Pathname(git_root).realpath).to_s, "file" => Pathname(capture).expand_path.relative_path_from(output_path.dirname.expand_path).to_s}
+        file = Pathname(capture).expand_path.relative_path_from(output_path.dirname.expand_path).to_s
+        return if file.start_with?("..") # outside the report dir, so not in the artifact
+
+        {"path" => Pathname(capture).realpath.relative_path_from(Pathname(git_root).realpath).to_s, "file" => file}
       end
 
       def resolve_image(path)
@@ -281,6 +284,7 @@ def write_report
       # What a reviewer page may accept: the captures that differ or are new.
       def write_manifest
         accepted = entries.select { |entry| %w[changed new].include?(entry[:status]) && entry[:accept] }
+        accepted = accepted.reverse.uniq { |entry| entry[:accept]["path"] }.reverse # one file, one entry: the last capture
         manifest = accepted.map { |entry| {"name" => entry[:name], "status" => entry[:status]}.merge(entry[:accept]) }
         File.write(output_path.dirname / "snap_diff_manifest.json", JSON.pretty_generate("version" => 1, "entries" => manifest))
       end
diff --git a/test/unit/reporters/html_reporter_test.rb b/test/unit/reporters/html_reporter_test.rb
index 16bd1c99..bdcbb3e2 100644
--- a/test/unit/reporters/html_reporter_test.rb
+++ b/test/unit/reporters/html_reporter_test.rb
@@ -485,18 +485,19 @@ def synchronize
   # --- snap_diff_manifest.json: what a reviewer page may accept ----------
 
   test "the manifest names the changed capture and the baseline it replaces" do
-    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
     assertion = build_failing_assertion("index")
+    report_dir = assertion.compare.image_path.dirname
+    reporter = SnapDiff::Reporters::HTML.new(output_path: report_dir / "report.html")
     reporter.record([assertion])
     reporter.finalize
 
-    entry = manifest.fetch("entries").sole
-    assert_equal 1, manifest.fetch("version")
+    entry = manifest(report_dir).fetch("entries").sole
+    assert_equal 1, manifest(report_dir).fetch("version")
     assert_equal %w[index changed], entry.values_at("name", "status")
     git_root = Pathname(SnapDiff::Vcs.git_root_for(SnapDiff.config.root.to_s)).realpath
     assert_equal assertion.compare.image_path.realpath.relative_path_from(git_root).to_s, entry["path"]
     assert_no_match(/\.base\.png\z/, entry["path"])
-    assert_equal assertion.compare.image_path.to_s, (@output_dir / entry["file"]).realpath.to_s
+    assert_equal assertion.compare.image_path.to_s, (report_dir / entry["file"]).realpath.to_s
   end
 
   test "the manifest lists a new capture with its status" do
@@ -532,10 +533,34 @@ def synchronize
     assert_empty manifest.fetch("entries")
   end
 
+  # Several tests may capture the same name: one file on disk, so one entry
+  # (the last recorded) -- duplicate tree paths would 422 the accept commit.
+  test "the manifest lists one entry per path" do
+    first = build_failing_assertion("index")
+    report_dir = first.compare.image_path.dirname
+    reporter = SnapDiff::Reporters::HTML.new(output_path: report_dir / "report.html")
+    reporter.record([first])
+    reporter.record([build_failing_assertion("index")])
+    reporter.finalize
+
+    assert_equal 2, reporter.entries.size
+    assert_equal 1, manifest(report_dir).fetch("entries").size
+  end
+
+  # The artifact is the report directory: a capture outside it cannot be fetched.
+  test "the manifest leaves out captures outside the report directory" do
+    git_init_output_dir
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_dir / "report/report.html")
+    capture_new_screenshot(reporter, "outside")
+    reporter.finalize
+
+    assert_empty JSON.parse((@output_dir / "report/snap_diff_manifest.json").read).fetch("entries")
+  end
+
   test "the manifest carries file paths when images are embedded" do
     git_init_output_dir
     reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path, embed_images: true)
-    reporter.record([build_failing_assertion("index")])
+    capture_new_screenshot(reporter, "index")
     capture_new_screenshot(reporter, "signup")
     reporter.finalize
 
@@ -568,7 +593,7 @@ def synchronize
   test "the manifest survives the fork-parallel dump and merge" do
     git_init_output_dir
     worker = SnapDiff::Reporters::HTML.new(output_path: @output_path)
-    worker.record([build_failing_assertion("index")])
+    capture_new_screenshot(worker, "index")
     capture_new_screenshot(worker, "signup")
     state = JSON.parse(JSON.generate(worker.dump_state))
 
@@ -576,7 +601,7 @@ def synchronize
     parent.merge_state!(state)
     parent.finalize
 
-    assert_equal [%w[index changed], %w[signup new]], manifest.fetch("entries").map { |e| e.values_at("name", "status") }
+    assert_equal [%w[index new], %w[signup new]], manifest.fetch("entries").map { |e| e.values_at("name", "status") }
     manifest.fetch("entries").each { |e| assert_predicate @output_dir / e["file"], :exist? }
   end
 
@@ -594,8 +619,8 @@ def git_init_output_dir
     system("git", "-C", @output_dir.to_s, "init", "-q", exception: true)
   end
 
-  def manifest
-    JSON.parse((@output_dir / "snap_diff_manifest.json").read)
+  def manifest(dir = @output_dir)
+    JSON.parse((dir / "snap_diff_manifest.json").read)
   end
 
   # A capture under a project rooted at @output_dir, tallied the way

From f797a963731d246068e808d0cca3bdc73fb157b2 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 10:55:44 +0200
Subject: [PATCH 10/16] refactor: one size-capped body reader in the review
 page, leaner comments and docs

Behaviour unchanged: the declared/actual size checks shared by baseline
and artifact downloads now live in one helper; a test line that repeated
the fake's default and doc sentences that said the same thing twice are
gone.
---
 docs/ci-integration.md               | 11 +++++------
 lib/snap_diff/reporters/html.rb      | 10 ++++------
 lib/snap_diff/review/index.html      | 22 +++++++++++-----------
 test/integration/review_page_test.rb |  2 --
 4 files changed, 20 insertions(+), 25 deletions(-)

diff --git a/docs/ci-integration.md b/docs/ci-integration.md
index 3ad33385..f6b1d88a 100644
--- a/docs/ci-integration.md
+++ b/docs/ci-integration.md
@@ -197,9 +197,9 @@ A static page, hosted on your repository's own GitHub Pages, that lists every ch
 screenshot of a CI run with its diff. A reviewer marks each one Accept or Reject and presses
 Submit. The accepted images land as **one commit on the PR branch**, byte-identical to what CI
 captured, and **one PR comment** lists what was accepted (with the commit SHA) and rejected. The
-check stays red for the rejected ones. Once the page is installed and served,
-[`upload-screenshots`](#2-reusable-composite-action-recommended) adds a "Review & accept" link to the job summary, and to the PR comment when
-`pr-comment: 'true'`. The link appears only when the page URL actually answers 200.
+check stays red for the rejected ones. Once the page URL answers,
+[`upload-screenshots`](#2-reusable-composite-action-recommended) links to it from the job summary,
+and from the PR comment when `pr-comment: 'true'`.
 
 ### Install
 
@@ -254,8 +254,6 @@ Developer settings -> Fine-grained tokens:
 - Same-repository PRs only. A PR from a fork is refused: the token cannot write to the fork.
 - It reads the run's report artifact, so it works until `retention-days` (default `2`) expires.
   After that, re-run CI.
-- The page works only for the repository that hosts it, and refuses to run inside a frame or a
-  window opened by another page.
 - Pages must be served from the `gh-pages` branch (root) of this repository: not the "GitHub
   Actions" source, not `main`:`/docs`. A user-site repository named `<owner>.github.io` is not
   supported.
@@ -268,7 +266,8 @@ Developer settings -> Fine-grained tokens:
 The page cross-checks the ids in its link (run, PR and artifact) against GitHub before it writes
 anything. It writes only `.png` and `.webp` image bytes, only at the screenshot paths CI listed in
 `snap_diff_manifest.json`. It never force-pushes: a moved branch is an error, not an overwrite. The
-token is kept in memory for the page load and is never stored.
+token is kept in memory for the page load and is never stored. The page serves only the
+repository that hosts it, and refuses to run inside a frame or a window opened by another page.
 
 ## Update Baselines in CI
 
diff --git a/lib/snap_diff/reporters/html.rb b/lib/snap_diff/reporters/html.rb
index 7f321b4a..c0ae359d 100644
--- a/lib/snap_diff/reporters/html.rb
+++ b/lib/snap_diff/reporters/html.rb
@@ -242,12 +242,10 @@ def display_path(path)
         relative.start_with?("..") ? path.to_s : relative
       end
 
-      # Raw paths for snap_diff_manifest.json (the template leaves them out):
-      # the capture is both what is committed (`path`, the baseline's own
-      # path, which the failing run already overwrote) and what the report
-      # dir holds (`file`). `path` is relative to the git root, the form
-      # Vcs hands `git show HEAD:`; with no repository nothing can be
-      # committed. String keys: entries pass through JSON in dump_state.
+      # For snap_diff_manifest.json: the capture overwrote the baseline, so it
+      # is both what to commit (`path`, from the git root) and what the
+      # artifact holds (`file`, from the report dir). String keys: entries
+      # pass through JSON in dump_state.
       def accept_paths(capture)
         return unless capture && File.exist?(capture)
 
diff --git a/lib/snap_diff/review/index.html b/lib/snap_diff/review/index.html
index 0502804f..f40528f7 100644
--- a/lib/snap_diff/review/index.html
+++ b/lib/snap_diff/review/index.html
@@ -4,7 +4,7 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <!-- script-src carries the sha256 (base64) of the exact text of the one inline script element below. Recompute it whenever that script changes, or the page will not run. -->
-<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'sha256-kFkAY+0J3mvs3+iH1JY0RXC8LrKjgogdjhlwH6hlPy4='; style-src 'unsafe-inline'; img-src blob:; connect-src https://api.github.com https://*.blob.core.windows.net; base-uri 'none'; form-action 'none'">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'sha256-wpjmEhx8OPozWD40aKg4vHv7DVPpOX4rvBY086X2M4Y='; style-src 'unsafe-inline'; img-src blob:; connect-src https://api.github.com https://*.blob.core.windows.net; base-uri 'none'; form-action 'none'">
 <meta name="referrer" content="no-referrer">
 <title>snap_diff review</title>
 <style>
@@ -208,11 +208,15 @@ <h1>snap_diff review</h1>
     if (e.status === 404) return null;
     throw e;
   }
-  const tooBig = new Error(`The committed ${path} is larger than 20 MB.`);
-  if (Number(res.headers.get("content-length")) > MAX_FILE) throw tooBig;
-  const bytes = new Uint8Array(await res.arrayBuffer());
-  if (bytes.length > MAX_FILE) throw tooBig;
-  return bytes;
+  return new Uint8Array(await body(res, MAX_FILE, `The committed ${path} is larger than 20 MB.`));
+}
+
+// The declared length stops a big download before it starts; the real length catches a missing header.
+async function body(res, max, tooBig) {
+  if (Number(res.headers.get("content-length")) > max) throw new Error(tooBig);
+  const buf = await res.arrayBuffer();
+  if (buf.byteLength > max) throw new Error(tooBig);
+  return buf;
 }
 
 async function readEntry(m, zip) {
@@ -279,12 +283,8 @@ <h1>snap_diff review</h1>
   head = await verifyLink();
 
   say(`Downloading artifact ${artifact}…`);
-  const tooBig = new Error(`Artifact ${artifact} is larger than 100 MB; the review page refuses it.`);
   const res = await api("GET", `/repos/${repo}/actions/artifacts/${artifact}/zip`, null, PERM.actions);
-  if (Number(res.headers.get("content-length")) > MAX_ZIP) throw tooBig;
-  const buf = await res.arrayBuffer();
-  if (buf.byteLength > MAX_ZIP) throw tooBig;
-  const zip = unzip(buf);
+  const zip = unzip(await body(res, MAX_ZIP, `Artifact ${artifact} is larger than 100 MB; the review page refuses it.`));
   const manifestFile = zip.get("snap_diff_manifest.json");
   if (!manifestFile) throw new Error("The artifact has no snap_diff_manifest.json. The report was made by a snap_diff version without the review page.");
   const manifest = JSON.parse(new TextDecoder().decode(await inflate(manifestFile)));
diff --git a/test/integration/review_page_test.rb b/test/integration/review_page_test.rb
index 0a9eddd3..404ed9aa 100644
--- a/test/integration/review_page_test.rb
+++ b/test/integration/review_page_test.rb
@@ -135,8 +135,6 @@ def review(entries: nil, files: nil)
     zip = FakeGithub.zip({"snap_diff_manifest.json" => JSON.generate(version: 1, entries: entries)}.merge(files))
     @fake = FakeGithub.new(zip: zip)
     yield @fake if block_given?
-    # the zip size is read when the fake is built; keep the artifact record honest
-    @fake.artifact[:size_in_bytes] = zip.bytesize
 
     @session = Capybara::Session.new(Capybara.javascript_driver, @fake)
     @session.config.default_max_wait_time = 10

From 32d8872c1c44d74567e2214484c6a8883988f0ae Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 11:33:38 +0200
Subject: [PATCH 11/16] revert: drop the GitHub Pages review page

It worked end to end, but every reviewer had to paste a fine-grained
token on each visit, and a static page cannot hold a secret. Accepting
moves to a PR comment that an Actions workflow carries out with the
repository's own token; the manifest stays.
---
 .github/actions/deploy-review-page/action.yml | 101 ----
 .github/actions/upload-screenshots/action.yml |  27 -
 .github/workflows/review-page.yml             |  30 --
 CHANGELOG.md                                  |   7 -
 docs/ci-integration.md                        |  78 ---
 lib/snap_diff/review/index.html               | 472 ------------------
 test/integration/review_page_test.rb          | 156 ------
 test/support/fake_github_api.rb               |  98 ----
 test/unit/review_page_csp_test.rb             |  22 -
 9 files changed, 991 deletions(-)
 delete mode 100644 .github/actions/deploy-review-page/action.yml
 delete mode 100644 .github/workflows/review-page.yml
 delete mode 100644 lib/snap_diff/review/index.html
 delete mode 100644 test/integration/review_page_test.rb
 delete mode 100644 test/support/fake_github_api.rb
 delete mode 100644 test/unit/review_page_csp_test.rb

diff --git a/.github/actions/deploy-review-page/action.yml b/.github/actions/deploy-review-page/action.yml
deleted file mode 100644
index cebc642f..00000000
--- a/.github/actions/deploy-review-page/action.yml
+++ /dev/null
@@ -1,101 +0,0 @@
----
-name: 'Deploy the SnapDiff review page'
-description: 'Publish the click-to-accept review page to gh-pages at snap-diff/index.html'
-inputs:
-  page:
-    description: 'Path to an index.html to publish (skips the snap_diff-capybara gem lookup)'
-    default: ''
-  token:
-    description: 'Token that can push to gh-pages (the job needs contents: write)'
-    default: ${{ github.token }}
-runs:
-  using: 'composite'
-  steps:
-    - name: Resolve the review page
-      id: resolve
-      shell: bash
-      env:
-        PAGE: ${{ inputs.page }}
-      run: |
-        set -euo pipefail
-        if [ -n "$PAGE" ]; then
-          echo "file=$(realpath "$PAGE")" >> "$GITHUB_OUTPUT"
-          echo "source=from $PAGE" >> "$GITHUB_OUTPUT"
-          exit 0
-        fi
-
-        # No checkout assumed beyond the lockfile: the version the app locks is the
-        # version whose page it gets, so a Dependabot bump republishes the page.
-        lock=$(ls Gemfile.lock gems.locked 2>/dev/null | head -n 1 || true)
-        [ -n "$lock" ] || { echo "::error::No Gemfile.lock or gems.locked here (is actions/checkout before this step?). Pass page: to publish a file instead."; exit 1; }
-
-        # Only a GEM section is a released version; GIT and PATH entries have no .gem to fetch.
-        # The gem publishes under both names; fetch whichever one the app locks. tr: CRLF lockfiles.
-        found=$(tr -d '\r' < "$lock" | awk '/^[A-Z][A-Z ]*$/ {section=$0} section=="GEM" && /^    (snap_diff-capybara|capybara-screenshot-diff) \(/ {gsub(/[()]/, "", $2); print $1, $2; exit}')
-        if [ -z "$found" ]; then
-          echo "::error::snap_diff-capybara (or capybara-screenshot-diff) is not under a GEM section of $lock (it is a GIT/PATH gem or missing). Pass page: with a path to a review page index.html."
-          exit 1
-        fi
-        name=${found% *}
-        version=${found#* }
-
-        work=$(mktemp -d "$RUNNER_TEMP/snap-diff-gem.XXXXXX")
-        (cd "$work" && gem fetch "$name" -v "$version" && gem unpack "$name-$version.gem" --target .)
-        file="$work/$name-$version/lib/snap_diff/review/index.html"
-        [ -f "$file" ] || { echo "::error::$name $version has no review page; upgrade."; exit 1; }
-        echo "file=$file" >> "$GITHUB_OUTPUT"
-        echo "source=($name $version)" >> "$GITHUB_OUTPUT"
-
-    - name: Publish to gh-pages
-      shell: bash
-      env:
-        PAGE_FILE: ${{ steps.resolve.outputs.file }}
-        SOURCE: ${{ steps.resolve.outputs.source }}
-        TOKEN: ${{ inputs.token }}
-        REPO: ${{ github.repository }}
-      run: |
-        set -euo pipefail
-        # A scratch clone, so it works whatever checkout ran (or none) and never
-        # touches the caller's working tree or branch.
-        work=$(mktemp -d "$RUNNER_TEMP/gh-pages.XXXXXX")
-        cd "$work"
-        git init -q .
-        git remote add origin "https://x-access-token:${TOKEN}@github.com/${REPO}.git"
-
-        # 0 = branch exists, 2 = it does not; anything else (bad token) must fail, not create a branch.
-        status=0
-        git ls-remote --exit-code --heads origin gh-pages > /dev/null 2>&1 || status=$?
-        case "$status" in
-          0)
-            git fetch -q --depth=1 origin gh-pages
-            git checkout -q -b gh-pages FETCH_HEAD
-            ;;
-          2)
-            git checkout -q --orphan gh-pages
-            touch .nojekyll
-            ;;
-          *)
-            echo "::error::Could not reach $REPO to look for gh-pages (git exit $status). Check the token and contents: write."
-            exit 1
-            ;;
-        esac
-
-        mkdir -p snap-diff
-        cp "$PAGE_FILE" snap-diff/index.html
-        git add .
-        if git diff --cached --quiet; then
-          echo "snap-diff/index.html is already up to date."
-        else
-          git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
-            commit -q -m "Update the snap_diff review page $SOURCE"
-          git push -q origin gh-pages
-        fi
-
-        owner=$(printf '%s' "${REPO%%/*}" | tr '[:upper:]' '[:lower:]')
-        cat >> "$GITHUB_STEP_SUMMARY" <<EOF
-        ### SnapDiff review page
-
-        https://${owner}.github.io/${REPO#*/}/snap-diff/
-
-        First time? Settings -> Pages -> Build and deployment -> Deploy from a branch -> gh-pages / (root).
-        EOF
diff --git a/.github/actions/upload-screenshots/action.yml b/.github/actions/upload-screenshots/action.yml
index a1e3838c..7a937a8e 100644
--- a/.github/actions/upload-screenshots/action.yml
+++ b/.github/actions/upload-screenshots/action.yml
@@ -74,31 +74,6 @@ runs:
         retention-days: ${{ inputs.retention-days }}
         path: ${{ inputs.report-path }}/
 
-    - name: Check for the review page
-      id: review
-      if: steps.check-report.outputs.exists == 'true' && github.event_name == 'pull_request'
-      shell: bash
-      env:
-        REPO: ${{ github.repository }}
-        PR: ${{ github.event.pull_request.number }}
-        RUN_ID: ${{ github.run_id }}
-        ARTIFACT_ID: ${{ steps.upload-report-full.outputs.artifact-id }}
-      run: |
-        # Probe the page we are about to link: a file on gh-pages proves nothing if Pages serves
-        # something else. 404 = not installed (silent); anything else is a warning, never a failure.
-        owner=$(printf '%s' "${REPO%%/*}" | tr '[:upper:]' '[:lower:]')
-        page="https://${owner}.github.io/${REPO#*/}/snap-diff/"
-        # -L: a custom domain redirects from github.io
-        code=$(curl -sL --max-time 10 -o /dev/null -w '%{http_code}' "$page") || code="curl failed"
-        case "$code" in
-          200)
-            url="${page}?repo=${REPO}&pr=${PR}&run=${RUN_ID}&artifact=${ARTIFACT_ID}"
-            echo "row=| [Review & accept]($url) | Accept or reject in the browser |" >> "$GITHUB_OUTPUT"
-            ;;
-          404) ;;
-          *) echo "::warning::Could not check the review page at $page (status: $code); no Review & accept link." ;;
-        esac
-
     - name: Job summary
       if: steps.check-report.outputs.exists == 'true'
       shell: bash
@@ -110,7 +85,6 @@ runs:
         |----------|------|
         | HTML report (inline) | ${{ steps.upload-report.outputs.artifact-url || 'N/A' }} |
         | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
-        ${{ steps.review.outputs.row }}
         EOF
 
     - name: Find existing PR comment
@@ -137,4 +111,3 @@ runs:
           | HTML report (inline) | ${{ steps.upload-report.outputs.artifact-url || 'N/A' }} |
           | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
           | [All artifacts](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}#artifacts) | Browse all |
-          ${{ steps.review.outputs.row }}
diff --git a/.github/workflows/review-page.yml b/.github/workflows/review-page.yml
deleted file mode 100644
index 71743532..00000000
--- a/.github/workflows/review-page.yml
+++ /dev/null
@@ -1,30 +0,0 @@
----
-name: Review page
-
-on:
-  push:
-    branches: [ master ]
-    paths:
-      - 'lib/snap_diff/review/**'
-      - '.github/actions/deploy-review-page/**'
-      - '.github/workflows/review-page.yml'
-  workflow_dispatch:
-
-# Two pushes racing to gh-pages would fail the second as a non-fast-forward.
-concurrency:
-  group: review-page
-
-jobs:
-  deploy:
-    name: Publish the review page
-    runs-on: ubuntu-latest
-    timeout-minutes: 3
-    permissions:
-      contents: write
-
-    steps:
-      - uses: actions/checkout@v7
-
-      - uses: ./.github/actions/deploy-review-page
-        with:
-          page: lib/snap_diff/review/index.html
diff --git a/CHANGELOG.md b/CHANGELOG.md
index efc5e566..64b0677e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,13 +24,6 @@ kept as history. This entry is the one to read if you are coming from **1.15.1**
   selects `record = :all` for the run that sees it, outranking `record =` and `fail_if_new`; a
   `record:` on the screenshot still outranks it. `1` and `true` turn it on; any other value is the
   same as not setting it. Unset, the mode reads as before (`:none` under CI, `:once` off it).
-- **Accept or reject screenshots in the browser.** The HTML report now writes
-  `snap_diff_manifest.json` beside it, and `deploy-review-page` publishes a review page
-  (shipped in the gem, `lib/snap_diff/review/`) to your `gh-pages` at `snap-diff/`, kept
-  current from the version in `Gemfile.lock`. A reviewer marks each changed or new screenshot
-  Accept or Reject; the accepted ones become one commit on the PR branch and a PR comment
-  lists the decisions. `upload-screenshots` links to it once it is installed. See
-  [docs/ci-integration.md](docs/ci-integration.md#accept-or-reject-screenshots-in-the-browser)
 
 - **AI triage (optional, offline-first, advisory by default).** `SnapDiff::Reporters::AISimple`
   classifies every failed comparison as `flaky` / `intentional` / `real_bug`,
diff --git a/docs/ci-integration.md b/docs/ci-integration.md
index f6b1d88a..c4e11e1e 100644
--- a/docs/ci-integration.md
+++ b/docs/ci-integration.md
@@ -191,84 +191,6 @@ jobs:
 
 </details>
 
-## Accept or reject screenshots in the browser
-
-A static page, hosted on your repository's own GitHub Pages, that lists every changed and new
-screenshot of a CI run with its diff. A reviewer marks each one Accept or Reject and presses
-Submit. The accepted images land as **one commit on the PR branch**, byte-identical to what CI
-captured, and **one PR comment** lists what was accepted (with the commit SHA) and rejected. The
-check stays red for the rejected ones. Once the page URL answers,
-[`upload-screenshots`](#2-reusable-composite-action-recommended) links to it from the job summary,
-and from the PR comment when `pr-comment: 'true'`.
-
-### Install
-
-Copy this workflow:
-
-```yaml
-# .github/workflows/review-page.yml
-name: Review page
-on:
-  push:
-    branches: [ main ]       # your default branch
-    paths: [ Gemfile.lock ]
-  workflow_dispatch:
-permissions:
-  contents: write
-concurrency:
-  group: snap-diff-review-page   # two racing runs would reject one push
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: snap-diff/snap_diff-capybara/.github/actions/deploy-review-page@master
-```
-
-Run it once with "Run workflow". It publishes `snap-diff/index.html` to the `gh-pages` branch
-(created if missing, everything else on the branch is left alone) and prints the page URL
-(`https://<owner>.github.io/<repo>/snap-diff/`) in the job summary. Then, once the branch exists,
-enable Pages: Settings -> Pages -> Build and deployment -> Deploy from a branch -> `gh-pages` /
-`(root)`.
-
-### Auto-update
-
-The page ships inside the gem. The workflow reads the `snap_diff-capybara` version locked in
-`Gemfile.lock` (or `gems.locked`) and publishes the page from that exact release. A Dependabot
-bundler bump changes `Gemfile.lock`, so merging it republishes the page. A gem that is locked from
-git or a path has no release to read: pass `page:` with a path to an `index.html` instead.
-
-### The token
-
-The page asks the reviewer for a fine-grained personal access token. Create it under Settings ->
-Developer settings -> Fine-grained tokens:
-
-- Repository access: only this repository
-- Actions: Read
-- Contents: Read and write
-- Pull requests: Read and write
-- A short expiry
-
-### Limits
-
-- Same-repository PRs only. A PR from a fork is refused: the token cannot write to the fork.
-- It reads the run's report artifact, so it works until `retention-days` (default `2`) expires.
-  After that, re-run CI.
-- Pages must be served from the `gh-pages` branch (root) of this repository: not the "GitHub
-  Actions" source, not `main`:`/docs`. A user-site repository named `<owner>.github.io` is not
-  supported.
-- A custom-domain site must keep the `/<repo>/` path segment, so the page stays at
-  `/<repo>/snap-diff/`.
-- If the PR branch has new commits since the CI run, nothing is written: re-run CI and review again.
-
-### Security model
-
-The page cross-checks the ids in its link (run, PR and artifact) against GitHub before it writes
-anything. It writes only `.png` and `.webp` image bytes, only at the screenshot paths CI listed in
-`snap_diff_manifest.json`. It never force-pushes: a moved branch is an error, not an overwrite. The
-token is kept in memory for the page load and is never stored. The page serves only the
-repository that hosts it, and refuses to run inside a frame or a window opened by another page.
-
 ## Update Baselines in CI
 
 When intentional UI changes are made, baselines need to be re-recorded. Baselines are
diff --git a/lib/snap_diff/review/index.html b/lib/snap_diff/review/index.html
deleted file mode 100644
index f40528f7..00000000
--- a/lib/snap_diff/review/index.html
+++ /dev/null
@@ -1,472 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<!-- script-src carries the sha256 (base64) of the exact text of the one inline script element below. Recompute it whenever that script changes, or the page will not run. -->
-<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'sha256-wpjmEhx8OPozWD40aKg4vHv7DVPpOX4rvBY086X2M4Y='; style-src 'unsafe-inline'; img-src blob:; connect-src https://api.github.com https://*.blob.core.windows.net; base-uri 'none'; form-action 'none'">
-<meta name="referrer" content="no-referrer">
-<title>snap_diff review</title>
-<style>
-  :root { --bg: #fff; --fg: #1f2328; --muted: #59636e; --line: #d1d9e0; --panel: #f6f8fa;
-    --accept: #1a7f37; --reject: #cf222e; --accent: #0969da; color-scheme: light dark; }
-  @media (prefers-color-scheme: dark) {
-    :root { --bg: #0d1117; --fg: #e6edf3; --muted: #9198a1; --line: #3d444d; --panel: #151b23;
-      --accept: #3fb950; --reject: #f85149; --accent: #4493f8; }
-  }
-  * { box-sizing: border-box; }
-  body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.5 system-ui, sans-serif; }
-  header, footer { padding: 8px 16px; border-bottom: 1px solid var(--line); display: flex; gap: 12px; align-items: center; flex-wrap: wrap; }
-  footer { border-top: 1px solid var(--line); border-bottom: 0; position: sticky; bottom: 0; background: var(--bg); }
-  h1 { font-size: 16px; margin: 0; }
-  .muted { color: var(--muted); }
-  .spacer { flex: 1; }
-  button { font: inherit; padding: 4px 12px; border: 1px solid var(--line); border-radius: 6px; background: var(--panel); color: var(--fg); cursor: pointer; }
-  button:disabled { opacity: .5; cursor: default; }
-  button.on.accept, .badge.accept { background: var(--accept); border-color: var(--accept); color: #fff; }
-  button.on.reject, .badge.reject { background: var(--reject); border-color: var(--reject); color: #fff; }
-  button.on.view { border-color: var(--accent); color: var(--accent); }
-  input { font: inherit; padding: 4px 8px; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); color: var(--fg); width: 32em; max-width: 100%; }
-  #msg { margin: 16px; padding: 8px 12px; border-radius: 6px; border: 1px solid var(--line); background: var(--panel); white-space: pre-wrap; }
-  #msg.error { border-color: var(--reject); }
-  #msg:empty { display: none; }
-  #token-form { margin: 16px; display: flex; gap: 8px; flex-wrap: wrap; }
-  main { display: grid; grid-template-columns: 260px 1fr; min-height: calc(100vh - 120px); }
-  nav { border-right: 1px solid var(--line); overflow-y: auto; }
-  nav button { display: flex; width: 100%; gap: 6px; border: 0; border-bottom: 1px solid var(--line); border-radius: 0; background: none; text-align: left; padding: 6px 12px; }
-  nav button.current { background: var(--panel); box-shadow: inset 3px 0 var(--accent); }
-  nav .name { flex: 1; overflow-wrap: anywhere; }
-  .badge { font-size: 12px; padding: 0 6px; border-radius: 10px; border: 1px solid var(--line); white-space: nowrap; }
-  #viewer { padding: 12px 16px; min-width: 0; }
-  .toolbar { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin-bottom: 12px; }
-  .images { display: grid; gap: 12px; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); }
-  figure { margin: 0; }
-  figcaption { font-size: 12px; color: var(--muted); }
-  img { max-width: 100%; border: 1px solid var(--line); display: block; cursor: zoom-in; }
-  #confirm { width: 100%; display: flex; gap: 8px; align-items: flex-start; flex-wrap: wrap; }
-  #confirm ul { max-height: 30vh; overflow: auto; margin: 4px 0; }
-  [hidden] { display: none !important; }
-  a { color: var(--accent); }
-</style>
-</head>
-<body>
-<header>
-  <h1>snap_diff review</h1>
-  <span id="where" class="muted"></span>
-  <span class="spacer"></span>
-  <button id="forget" type="button" hidden>Forget token</button>
-</header>
-<div id="msg" role="status"></div>
-<form id="token-form" hidden>
-  <label for="token">GitHub token (fine-grained: Actions read, Contents write, Pull requests write). Kept in memory for this page load only.</label>
-  <input id="token" type="password" autocomplete="off" required>
-  <button type="submit">Load screenshots</button>
-</form>
-<main id="review" hidden>
-  <nav id="list"></nav>
-  <section id="viewer"></section>
-</main>
-<footer id="bar" hidden>
-  <span id="counter"></span>
-  <span class="muted">Keys: A accept, R reject, J/K next/previous, T flip base/new</span>
-  <span class="spacer"></span>
-  <button id="submit" type="button" disabled>Submit review</button>
-  <div id="confirm" hidden><div id="confirm-text"></div><button id="confirm-yes" type="button">Yes, submit</button><button id="confirm-no" type="button">Cancel</button></div>
-</footer>
-<script>
-(() => {
-"use strict";
-const API = "https://api.github.com";
-// Captured before anything else runs, so a page holding a handle to this window cannot swap it later.
-const doFetch = fetch.bind(window);
-const MAX_ZIP = 100 * 1024 * 1024, MAX_FILE = 20 * 1024 * 1024, MAX_TOTAL = 200 * 1024 * 1024, MAX_ENTRIES = 500;
-const PERM = { actions: "Actions: read", contents: "Contents: write", pullsRead: "Pull requests: read", pulls: "Pull requests: write", user: "read your own user profile" };
-const $ = (id) => document.getElementById(id);
-const params = new URLSearchParams(location.search);
-const repo = params.get("repo"), pr = params.get("pr"), run = params.get("run"), artifact = params.get("artifact");
-let token = null, inflatedTotal = 0, head = null, entries = [], current = 0, view = "side", flipped = false, busy = false;
-
-function el(tag, props, ...children) {
-  const node = Object.assign(document.createElement(tag), props);
-  node.append(...children.filter((c) => c != null));
-  return node;
-}
-
-function say(text, isError) {
-  $("msg").textContent = text;
-  $("msg").className = isError ? "error" : "";
-}
-
-// Only https links from the API go into an href.
-function link(text, url) {
-  return /^https:\/\//.test(url || "") ? el("a", { href: url, textContent: text, target: "_blank", rel: "noopener" }) : text;
-}
-
-// Names come from the artifact: no markdown, mentions or issue refs reach the commit or comment.
-const clean = (s) => String(s).replace(/[^\w .\/-]/g, "?").slice(0, 80);
-const sameRepo = (fullName) => typeof fullName === "string" && fullName.toLowerCase() === repo.toLowerCase();
-const encodePath = (path) => path.split("/").map(encodeURIComponent).join("/");
-
-async function api(method, path, body, perm, accept) {
-  let res;
-  try {
-    res = await doFetch(API + path, {
-      method,
-      headers: { Authorization: "Bearer " + token, Accept: accept || "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28",
-        ...(body ? { "Content-Type": "application/json" } : {}) },
-      body: body ? JSON.stringify(body) : undefined,
-    });
-  } catch (_) {
-    throw Object.assign(new Error(`Could not reach GitHub (${method} ${path}): network failure or the request was blocked (CORS/CSP). Check your connection and try again.`), { fatal: true });
-  }
-  if (res.ok) return res;
-  let detail = "";
-  try { detail = (await res.json()).message || ""; } catch (_) { /* body is not JSON; status says enough */ }
-  const text = res.status === 401 ? "The token is invalid or expired. Paste a new one."
-    : res.status === 403 ? `The token lacks permission: ${perm}. ${detail}`
-    : `GitHub answered ${res.status} to ${method} ${path}. ${detail}`;
-  throw Object.assign(new Error(text), { status: res.status, detail });
-}
-const json = async (promise) => (await promise).json();
-
-// Minimal zip reader: sizes come from the central directory (local headers may defer them to a data descriptor).
-// ponytail: no ZIP64, so artifacts over 4 GB or 65535 files fail loudly; add ZIP64 if a report ever gets that big.
-function unzip(buf) {
-  const v = new DataView(buf), u8 = new Uint8Array(buf), damaged = (why) => new Error(`The artifact zip is damaged (${why}).`);
-  let eocd = -1;
-  for (let i = buf.byteLength - 22; i >= Math.max(0, buf.byteLength - 65557); i--) {
-    if (v.getUint32(i, true) === 0x06054b50) { eocd = i; break; }
-  }
-  if (eocd < 0) throw new Error("The artifact download is not a zip file.");
-  const files = new Map(), names = new TextDecoder();
-  let p = v.getUint32(eocd + 16, true);
-  for (let n = v.getUint16(eocd + 10, true); n > 0; n--) {
-    if (p + 46 > buf.byteLength || v.getUint32(p, true) !== 0x02014b50) throw damaged("bad central directory");
-    const flags = v.getUint16(p + 8, true), method = v.getUint16(p + 10, true);
-    const csize = v.getUint32(p + 20, true), size = v.getUint32(p + 24, true), local = v.getUint32(p + 42, true);
-    const nameLen = v.getUint16(p + 28, true);
-    const name = names.decode(u8.subarray(p + 46, p + 46 + nameLen));
-    p += 46 + nameLen + v.getUint16(p + 30, true) + v.getUint16(p + 32, true);
-    if (name.endsWith("/")) continue;
-    if (local + 30 > buf.byteLength || v.getUint32(local, true) !== 0x04034b50) throw damaged(`bad local header for ${name}`);
-    const start = local + 30 + v.getUint16(local + 26, true) + v.getUint16(local + 28, true);
-    if (start + csize > buf.byteLength) throw damaged(`${name} runs past the end`);
-    files.set(name, { name, method, size, encrypted: (flags & 1) === 1, data: u8.subarray(start, start + csize) });
-  }
-  return files;
-}
-
-// Inflates into a buffer of the declared size and stops the moment the output would exceed it.
-async function inflate(file) {
-  if (file.encrypted) throw new Error(`${file.name} is encrypted.`);
-  if (file.size > MAX_FILE) throw new Error(`${file.name} is larger than 20 MB.`);
-  if ((inflatedTotal += file.size) > MAX_TOTAL) throw Object.assign(new Error("The artifact unpacks to more than 200 MB; the review page refuses it."), { fatal: true });
-  if (file.method === 0) {
-    if (file.data.length !== file.size) throw new Error(`${file.name} does not match its declared size.`);
-    return file.data;
-  }
-  if (file.method !== 8) throw new Error(`Unsupported compression method ${file.method} for ${file.name}.`);
-  const reader = new Blob([file.data]).stream().pipeThrough(new DecompressionStream("deflate-raw")).getReader();
-  const out = new Uint8Array(file.size);
-  let n = 0;
-  for (let r = await reader.read(); !r.done; r = await reader.read()) {
-    if (n + r.value.length > file.size) { reader.cancel(); throw new Error(`${file.name} inflates past its declared size.`); }
-    out.set(r.value, n);
-    n += r.value.length;
-  }
-  if (n !== file.size) throw new Error(`${file.name} does not match its declared size.`);
-  return out;
-}
-
-const MIME = { png: "image/png", webp: "image/webp" };
-const ascii = (b, from, to) => String.fromCharCode(...b.subarray(from, to));
-const MAGIC = {
-  png: (b) => [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a].every((x, i) => b[i] === x),
-  webp: (b) => ascii(b, 0, 4) === "RIFF" && ascii(b, 8, 12) === "WEBP",
-};
-function imageUrl(bytes, ext) {
-  return URL.createObjectURL(new Blob([bytes], { type: MIME[ext] }));
-}
-
-// The manifest path becomes a tree path in a commit: only an image inside the repo, never under .git*.
-function pathProblem(path, ext) {
-  if (typeof path !== "string" || path === "" || path.startsWith("/")) return "is not a relative path";
-  if (!/^[A-Za-z0-9._ \/-]+$/.test(path)) return "has characters other than letters, digits, . _ space / -";
-  const segments = path.split("/");
-  if (segments.some((s) => s === "" || s === "." || s === "..")) return "has empty, . or .. segments";
-  if (segments.some((s) => s.toLowerCase().startsWith(".git"))) return "touches a .git* file";
-  if (path.split(".").pop().toLowerCase() !== ext) return `does not end in .${ext} like its capture`;
-  return null;
-}
-
-// The committed file at the run's commit, or null when the repo has none there (404).
-async function baseline(path) {
-  let res;
-  try {
-    res = await api("GET", `/repos/${repo}/contents/${encodePath(path)}?ref=${head.sha}`, null, PERM.contents, "application/vnd.github.raw");
-  } catch (e) {
-    if (e.status === 404) return null;
-    throw e;
-  }
-  return new Uint8Array(await body(res, MAX_FILE, `The committed ${path} is larger than 20 MB.`));
-}
-
-// The declared length stops a big download before it starts; the real length catches a missing header.
-async function body(res, max, tooBig) {
-  if (Number(res.headers.get("content-length")) > max) throw new Error(tooBig);
-  const buf = await res.arrayBuffer();
-  if (buf.byteLength > max) throw new Error(tooBig);
-  return buf;
-}
-
-async function readEntry(m, zip) {
-  const name = clean(m.name);
-  if (m.status !== "changed" && m.status !== "new") throw new Error(`${name}: unknown status ${clean(m.status)}.`);
-  const ext = typeof m.file === "string" ? m.file.split(".").pop().toLowerCase() : "";
-  if (!Object.hasOwn(MIME, ext)) throw new Error(`${name}: capture ${m.file} is not a .png or .webp.`);
-  const problem = pathProblem(m.path, ext);
-  if (problem) throw new Error(`${name}: refusing path ${m.path}: it ${problem}.`);
-  const capture = zip.get(m.file);
-  if (!capture) throw new Error(`${name}: the artifact is missing ${m.file}.`);
-  const bytes = await inflate(capture);
-  if (!MAGIC[ext](bytes)) throw new Error(`${name}: ${m.file} is not a real .${ext} image.`);
-  // The "before" image is the committed baseline at the run's commit, not a file the artifact claims it is.
-  const before = await baseline(m.path);
-  if (m.status === "new" && before) throw new Error(`${name}: ${m.path} already exists in the repo; it is not new.`);
-  if (m.status === "changed" && !before) throw new Error(`${name}: ${m.path} has no committed baseline at the run's commit.`);
-  const entry = { name, status: m.status, path: m.path, bytes, decision: null, images: { new: imageUrl(bytes, ext) } };
-  if (before) {
-    entry.images.base = imageUrl(before, ext);
-    const stem = m.file.slice(0, -(ext.length + 1));
-    for (const [key, suffix] of [["diff", ".diff."], ["baseDiff", ".base.diff."], ["heatmap", ".heatmap.diff."]]) {
-      const sibling = zip.get(stem + suffix + ext);
-      if (sibling) entry.images[key] = imageUrl(await inflate(sibling), ext);
-    }
-  }
-  return entry;
-}
-
-// The link carries four independent numbers; each must point at the same PR head before anything is shown.
-async function verifyLink() {
-  say(`Reading CI run ${run}…`);
-  const runInfo = await json(api("GET", `/repos/${repo}/actions/runs/${run}`, null, PERM.actions));
-  const headRepo = runInfo.head_repository && runInfo.head_repository.full_name;
-  if (!sameRepo(headRepo)) throw new Error(`This run is from a fork (${headRepo || "unknown repository"}). Fork PRs are not supported yet.`);
-  if (!/^[0-9a-f]{40}$/.test(runInfo.head_sha || "")) throw new Error(`CI run ${run} has no head commit.`);
-
-  const expired = new Error(`Artifact ${artifact} has expired or was not found. Re-run CI to get a fresh report.`);
-  let art;
-  try {
-    art = await json(api("GET", `/repos/${repo}/actions/artifacts/${artifact}`, null, PERM.actions));
-  } catch (e) {
-    throw e.status === 404 || e.status === 410 ? expired : e;
-  }
-  if (art.expired) throw expired;
-  if (!(art.size_in_bytes <= MAX_ZIP)) throw new Error(`Artifact ${artifact} is larger than 100 MB; the review page refuses it.`);
-  if (!art.workflow_run || String(art.workflow_run.id) !== run) throw new Error(`Artifact ${artifact} was not made by CI run ${run}. This link is wrong; use the one from the PR comment.`);
-
-  const pull = await json(api("GET", `/repos/${repo}/pulls/${pr}`, null, PERM.pullsRead));
-  if (pull.state !== "open") throw new Error(`PR #${pr} is ${pull.state}, not open.`);
-  if (!sameRepo(pull.head && pull.head.repo && pull.head.repo.full_name)) throw new Error(`PR #${pr} comes from a fork. Fork PRs are not supported yet.`);
-  if (pull.head.sha !== runInfo.head_sha) throw new Error(`PR #${pr} has new commits since CI run ${run}, or the run is not for this PR. Re-run CI and review the new report.`);
-  const branch = pull.head.ref;
-  if (!branch || branch === pull.base.ref || branch === pull.base.repo.default_branch) throw new Error(`Refusing to commit to ${branch}: it is the PR's base branch or the default branch.`);
-  return { sha: runInfo.head_sha, branch };
-}
-
-async function load() {
-  entries.forEach((e) => Object.values(e.images).forEach((url) => URL.revokeObjectURL(url)));
-  entries = [];
-  current = 0;
-  inflatedTotal = 0;
-  $("review").hidden = $("bar").hidden = true;
-  head = await verifyLink();
-
-  say(`Downloading artifact ${artifact}…`);
-  const res = await api("GET", `/repos/${repo}/actions/artifacts/${artifact}/zip`, null, PERM.actions);
-  const zip = unzip(await body(res, MAX_ZIP, `Artifact ${artifact} is larger than 100 MB; the review page refuses it.`));
-  const manifestFile = zip.get("snap_diff_manifest.json");
-  if (!manifestFile) throw new Error("The artifact has no snap_diff_manifest.json. The report was made by a snap_diff version without the review page.");
-  const manifest = JSON.parse(new TextDecoder().decode(await inflate(manifestFile)));
-  if (manifest.version !== 1 || !Array.isArray(manifest.entries)) throw new Error("snap_diff_manifest.json has an unknown format.");
-  if (manifest.entries.length > MAX_ENTRIES) throw new Error(`The manifest lists ${manifest.entries.length} screenshots; the review page handles at most ${MAX_ENTRIES}.`);
-
-  const problems = [];
-  for (const m of manifest.entries) {
-    try {
-      entries.push(await readEntry(m, zip));
-    } catch (e) {
-      // Only a bad entry is left out; an API failure or a blown budget stops the whole load.
-      if (e.status || e.fatal) throw e;
-      problems.push(e.message);
-    }
-  }
-  const note = problems.length ? `Left out ${problems.length} screenshot(s):\n${problems.join("\n")}` : "";
-  if (!entries.length) { say(note || "Nothing to review: this report has no changed or new screenshots.", Boolean(note)); return; }
-  say(note, Boolean(note));
-  $("review").hidden = $("bar").hidden = false;
-  render();
-}
-
-const LABELS = { base: "Baseline (committed)", new: "New capture", diff: "Diff on new", baseDiff: "Diff on baseline", heatmap: "Heatmap" };
-function figure(entry, key) {
-  return el("figure", {}, el("figcaption", { textContent: LABELS[key] }),
-    el("a", { href: entry.images[key], target: "_blank", rel: "noopener" }, el("img", { src: entry.images[key], alt: `${entry.name}: ${LABELS[key]}` })));
-}
-
-function render() {
-  const list = $("list");
-  list.replaceChildren(...entries.map((e, i) =>
-    el("button", { type: "button", className: i === current ? "current" : "", onclick: () => { current = i; flipped = false; render(); } },
-      el("span", { className: "name", textContent: e.name }), el("span", { className: "badge", textContent: e.status }),
-      e.decision ? el("span", { className: "badge " + e.decision, textContent: e.decision === "accept" ? "accepted" : "rejected" }) : null)));
-  list.children[current].scrollIntoView({ block: "nearest" });
-
-  const e = entries[current], hasBase = Boolean(e.images.base);
-  const decide = (d, label) => el("button", { type: "button", className: d + (e.decision === d ? " on" : ""), textContent: label, disabled: busy, onclick: () => mark(d) });
-  const viewButton = (v, label) => el("button", { type: "button", className: "view" + (view === v ? " on" : ""), textContent: label, onclick: () => { view = v; render(); } });
-  const shown = !hasBase ? ["new"] : view === "side" ? ["base", "new"] : [flipped ? "base" : "new"];
-  const extras = ["diff", "heatmap", "baseDiff"].filter((k) => e.images[k]);
-  // replaceChildren would print a null as the text "null": optional parts are filtered out.
-  $("viewer").replaceChildren(...[
-    el("div", { className: "toolbar" },
-      el("strong", { textContent: e.name }), el("span", { className: "muted", textContent: `${e.status} · ${e.path} · ${current + 1}/${entries.length}` }),
-      el("span", { className: "spacer" }), decide("accept", "Accept"), decide("reject", "Reject")),
-    hasBase ? el("div", { className: "toolbar" }, viewButton("side", "Side by side"), viewButton("toggle", "Toggle"),
-      view === "toggle" ? el("button", { type: "button", textContent: `Showing ${flipped ? "baseline" : "new"} — flip (T)`, onclick: flip }) : null) : null,
-    el("div", { className: "images" }, ...shown.map((k) => figure(e, k))),
-    extras.length ? el("h3", { textContent: "Differences" }) : null,
-    el("div", { className: "images" }, ...extras.map((k) => figure(e, k)))].filter((c) => c != null));
-
-  const counts = { accept: 0, reject: 0, none: 0 };
-  entries.forEach((x) => counts[x.decision || "none"]++);
-  $("counter").textContent = `${counts.accept} accepted · ${counts.reject} rejected · ${counts.none} undecided`;
-  $("submit").disabled = busy || counts.accept + counts.reject === 0;
-}
-
-function mark(d) {
-  if (busy) return;
-  const e = entries[current];
-  e.decision = e.decision === d ? null : d;
-  $("confirm").hidden = true;
-  $("submit").hidden = false;
-  render();
-}
-function move(step) { current = Math.min(entries.length - 1, Math.max(0, current + step)); flipped = false; render(); }
-function flip() { if (view === "toggle") { flipped = !flipped; render(); } }
-
-function base64(bytes) {
-  let s = "";
-  for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
-  return btoa(s);
-}
-
-async function submit() {
-  const accepted = entries.filter((e) => e.decision === "accept"), rejected = entries.filter((e) => e.decision === "reject");
-  const login = (await json(api("GET", "/user", null, PERM.user))).login;
-  let commit = null;
-  if (accepted.length) {
-    const tree = [];
-    for (const e of accepted) {
-      say(`Uploading ${e.name}…`);
-      const blob = await json(api("POST", `/repos/${repo}/git/blobs`, { content: base64(e.bytes), encoding: "base64" }, PERM.contents));
-      tree.push({ path: e.path, mode: "100644", type: "blob", sha: blob.sha });
-    }
-    say("Creating the commit…");
-    const parent = await json(api("GET", `/repos/${repo}/git/commits/${head.sha}`, null, PERM.contents));
-    const newTree = await json(api("POST", `/repos/${repo}/git/trees`, { base_tree: parent.tree.sha, tree }, PERM.contents));
-    const message = `Accept screenshot baselines\n\n${accepted.map((e) => `- ${e.name}`).join("\n")}\n\nReviewed with the snap_diff review page by @${login}`;
-    commit = await json(api("POST", `/repos/${repo}/git/commits`, { message, tree: newTree.sha, parents: [head.sha] }, PERM.contents));
-    const ref = encodePath(head.branch);
-    try {
-      await api("PATCH", `/repos/${repo}/git/refs/heads/${ref}`, { sha: commit.sha, force: false }, PERM.contents);
-    } catch (e) {
-      if (e.status !== 422) throw e;
-      const now = await json(api("GET", `/repos/${repo}/git/ref/heads/${ref}`, null, PERM.contents));
-      if (now.object.sha !== head.sha) throw new Error(`This PR has new commits since CI run ${run}. Re-run CI and review the new report.`);
-      throw new Error(`GitHub refused to update ${head.branch}: ${e.detail || e.message}`);
-    }
-  }
-  say("Posting the PR comment…");
-  const lines = [`Screenshot review by @${login} (CI run ${run}):`, ""];
-  if (accepted.length) lines.push(`Accepted in ${commit.sha}:`, ...accepted.map((e) => `- \`${e.name}\``), "");
-  if (rejected.length) lines.push("Rejected:", ...rejected.map((e) => `- \`${e.name}\``), "");
-  let comment;
-  try {
-    comment = await json(api("POST", `/repos/${repo}/issues/${pr}/comments`, { body: lines.join("\n").trim() }, PERM.pulls));
-  } catch (e) {
-    if (commit) throw Object.assign(new Error(`Committed ${commit.sha}, but the comment failed: ${e.message}`), { locked: true });
-    throw e;
-  }
-
-  $("msg").className = "";
-  $("msg").replaceChildren(
-    `Done. ${accepted.length} accepted, ${rejected.length} rejected. `,
-    commit ? link(`Commit ${commit.sha.slice(0, 7)}`, commit.html_url) : "No commit (nothing accepted).", " · ",
-    link("PR comment", comment.html_url));
-}
-
-function fail(e) {
-  say(e.message, true);
-  if (e.status === 401) { token = null; $("token-form").hidden = false; }
-}
-
-// The page commits with the reviewer's token, so it only serves the repository it is published for.
-function hostAllows() {
-  const host = location.hostname, segment = (location.pathname.split("/")[1] || "").toLowerCase();
-  const [owner, name] = repo.toLowerCase().split("/");
-  if (host === "localhost" || host === "127.0.0.1") return true;
-  if (host.endsWith(".github.io")) return host === `${owner}.github.io` && segment === name;
-  return segment === name;
-}
-
-const DIGITS = /^[1-9][0-9]{0,18}$/;
-const REPO = /^[A-Za-z0-9-]{1,39}\/(?!\.\.?$)[A-Za-z0-9._-]{1,100}$/;
-if (window.opener || window.top !== window) {
-  say("Open this review page directly in its own tab, not from another page or inside a frame.", true);
-} else if (!REPO.test(repo || "") || ![pr, run, artifact].every((n) => DIGITS.test(n || ""))) {
-  say("This link is missing or has invalid parameters. It needs ?repo=owner/name&pr=<number>&run=<run id>&artifact=<artifact id>, as posted in the PR comment by the snap_diff upload-screenshots action.", true);
-} else if (!hostAllows()) {
-  say(`This review page is published for a different repository and will not review ${repo}. Use the review page of ${repo} itself.`, true);
-} else {
-  $("where").textContent = `${repo} · PR #${pr} · run ${run}`;
-  $("token-form").hidden = false;
-  $("token-form").addEventListener("submit", (ev) => {
-    ev.preventDefault();
-    token = $("token").value.trim();
-    $("token").value = "";
-    $("token-form").hidden = true;
-    $("forget").hidden = false;
-    load().catch(fail);
-  });
-  $("forget").addEventListener("click", () => { token = null; location.reload(); });
-  $("submit").addEventListener("click", () => {
-    const paths = entries.filter((e) => e.decision === "accept").map((e) => e.path);
-    $("confirm-text").replaceChildren(...(paths.length
-      ? [`Commit these ${paths.length} file(s) to ${head.branch} and comment on PR #${pr}:`, el("ul", {}, ...paths.map((p) => el("li", { textContent: p })))]
-      : [`Comment the rejections on PR #${pr}?`]));
-    $("confirm").hidden = false;
-    $("submit").hidden = true;
-  });
-  $("confirm-no").addEventListener("click", () => { $("confirm").hidden = true; $("submit").hidden = false; });
-  $("confirm-yes").addEventListener("click", () => {
-    $("confirm").hidden = true;
-    busy = true;
-    render();
-    // Success, or a commit already on the branch, keeps the page locked: a second submit would commit again.
-    submit().then(render, (e) => {
-      if (!e.locked) { busy = false; $("submit").hidden = false; }
-      render();
-      fail(e);
-    });
-  });
-  document.addEventListener("keydown", (ev) => {
-    if (!entries.length || ev.target.tagName === "INPUT" || ev.ctrlKey || ev.metaKey || ev.altKey) return;
-    const action = { a: () => mark("accept"), r: () => mark("reject"), j: () => move(1), k: () => move(-1), t: flip }[ev.key.toLowerCase()];
-    if (action) { ev.preventDefault(); action(); }
-  });
-}
-})();
-</script>
-</body>
-</html>
diff --git a/test/integration/review_page_test.rb b/test/integration/review_page_test.rb
deleted file mode 100644
index 404ed9aa..00000000
--- a/test/integration/review_page_test.rb
+++ /dev/null
@@ -1,156 +0,0 @@
-# frozen_string_literal: true
-
-require "test_helper"
-require "base64"
-require "support/setup_capybara_drivers"
-require "support/fake_github_api"
-
-# Drives lib/snap_diff/review/index.html in a real browser against a fake
-# GitHub API. The page is a black box: only what it shows and what it sends.
-class ReviewPageTest < Minitest::Test
-  TOKEN = "ghp_test_token"
-  HOMEPAGE = "doc/screenshots/linux/homepage.png"
-  SIGNUP = "doc/screenshots/linux/signup.png"
-
-  def setup
-    @homepage_png = File.binread(TEST_IMAGES_DIR / "a.png")
-    @signup_png = File.binread(TEST_IMAGES_DIR / "c.png")
-    @baseline_png = File.binread(TEST_IMAGES_DIR / "b.png")
-  end
-
-  def teardown
-    @session&.quit
-  end
-
-  def test_accept_one_reject_one_commits_exact_bytes_and_comments
-    review do |fake|
-      fake.baselines[HOMEPAGE] = @baseline_png
-    end
-    page.find("#list button", text: "homepage").click
-    page.click_button "Accept", exact: true
-    page.find("#list button", text: "signup").click
-    page.assert_text "New capture"
-    refute_match(/\bnull\b/, page.text)
-    page.click_button "Reject", exact: true
-    submit
-
-    page.assert_text "Done. 1 accepted, 1 rejected."
-    sent = fake.requests
-    blob = only(sent, "POST", "/repos/o/r/git/blobs").json
-    assert_equal "base64", blob[:encoding]
-    assert_equal @homepage_png, Base64.strict_decode64(blob[:content])
-
-    tree = only(sent, "POST", "/repos/o/r/git/trees").json
-    assert_equal [HOMEPAGE], tree[:tree].map { _1[:path] }
-    assert_equal fake.git_sha("tree of head"), tree[:base_tree]
-
-    commit = only(sent, "POST", "/repos/o/r/git/commits").json
-    assert_equal [FakeGithub::HEAD_SHA], commit[:parents]
-
-    patch = only(sent, "PATCH", "/repos/o/r/git/refs/heads/feature").json
-    assert_equal false, patch[:force]
-    assert_equal fake.git_sha(commit.to_json), patch[:sha]
-
-    comment = only(sent, "POST", "/repos/o/r/issues/7/comments").json[:body]
-    assert_includes comment, "homepage"
-    assert_includes comment, "signup"
-
-    assert_equal ["Bearer #{TOKEN}"], sent.map(&:authorization).uniq
-    page.assert_selector :link, "Commit #{patch[:sha][0, 7]}", href: "https://github.com/o/r/commit/#{patch[:sha]}"
-  end
-
-  def test_artifact_from_another_run_is_refused_before_download
-    review { |fake| fake.artifact[:workflow_run][:id] = 99 }
-
-    page.assert_text "was not made by CI run 11"
-    refute_includes fake.requests.map(&:path), "/repos/o/r/actions/artifacts/22/zip"
-    assert_empty fake.writes
-  end
-
-  def test_pr_head_that_moved_since_the_run_is_refused_before_download
-    review { |fake| fake.pull[:head][:sha] = "b2" * 20 }
-
-    page.assert_text "has new commits since CI run 11"
-    refute_includes fake.requests.map(&:path), "/repos/o/r/actions/artifacts/22/zip"
-    assert_empty fake.writes
-  end
-
-  def test_branch_that_moved_between_load_and_submit_is_reported_and_not_commented
-    review do |fake|
-      fake.baselines[HOMEPAGE] = @baseline_png
-      fake.patch_status = 422
-      fake.moved_ref_sha = "c3" * 20
-    end
-    page.find("#list button", text: "homepage").click
-    page.click_button "Accept", exact: true
-    submit
-
-    page.assert_text "This PR has new commits since CI run 11"
-    assert_equal 1, fake.requests.count { _1.method == "PATCH" }
-    assert_empty fake.requests.select { _1.path.end_with?("/comments") }
-  end
-
-  def test_malicious_manifest_entries_cannot_be_accepted_or_written
-    entries = [
-      {name: "rake", status: "new", path: "Rakefile", file: "good.png"},
-      {name: "workflow", status: "new", path: ".github/x.png", file: "good.png"},
-      {name: "fake", status: "new", path: "doc/fake.png", file: "fake.png"},
-      {name: "fine", status: "new", path: "doc/fine.png", file: "good.png"}
-    ]
-    review(entries: entries, files: {"good.png" => @signup_png, "fake.png" => "not a png at all"})
-
-    page.assert_text "Left out 3 screenshot(s)"
-    page.assert_text "refusing path Rakefile"
-    page.assert_text "refusing path .github/x.png"
-    page.assert_text "fake.png is not a real .png image"
-    page.assert_selector "#list button", count: 1
-    page.click_button "Accept", exact: true
-    submit
-
-    page.assert_text "Done. 1 accepted, 0 rejected."
-    tree = only(fake.requests, "POST", "/repos/o/r/git/trees").json
-    assert_equal ["doc/fine.png"], tree[:tree].map { _1[:path] }
-  end
-
-  def test_bad_token_asks_for_the_token_again_and_requests_nothing_else
-    review { |fake| fake.runs_status = 401 }
-
-    page.assert_text "The token is invalid or expired"
-    page.assert_selector "#token-form"
-    assert_equal ["/repos/o/r/actions/runs/11"], fake.requests.map(&:path)
-  end
-
-  private
-
-  attr_reader :fake
-
-  def page = @session
-
-  def review(entries: nil, files: nil)
-    entries ||= [
-      {name: "homepage", status: "changed", path: HOMEPAGE, file: "linux/homepage.png"},
-      {name: "signup", status: "new", path: SIGNUP, file: "linux/signup.png"}
-    ]
-    files ||= {"linux/homepage.png" => @homepage_png, "linux/signup.png" => @signup_png}
-    zip = FakeGithub.zip({"snap_diff_manifest.json" => JSON.generate(version: 1, entries: entries)}.merge(files))
-    @fake = FakeGithub.new(zip: zip)
-    yield @fake if block_given?
-
-    @session = Capybara::Session.new(Capybara.javascript_driver, @fake)
-    @session.config.default_max_wait_time = 10
-    @session.visit "/?repo=o/r&pr=7&run=11&artifact=22"
-    @session.fill_in "token", with: TOKEN
-    @session.click_button "Load screenshots"
-  end
-
-  def submit
-    page.click_button "Submit review"
-    page.click_button "Yes, submit"
-  end
-
-  def only(requests, verb, path)
-    found = requests.select { _1.method == verb && _1.path == path }
-    assert_equal 1, found.size, "expected exactly one #{verb} #{path}, saw #{requests.map { "#{_1.method} #{_1.path}" }}"
-    found.first
-  end
-end
diff --git a/test/support/fake_github_api.rb b/test/support/fake_github_api.rb
deleted file mode 100644
index 041bbb0d..00000000
--- a/test/support/fake_github_api.rb
+++ /dev/null
@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-require "json"
-require "rack"
-require "zlib"
-
-# Serves the review page (rewritten to talk to itself) and a fake GitHub REST
-# API from one Rack app, and records every API request it sees.
-class FakeGithub
-  PAGE = Pathname.new(File.expand_path("../../lib/snap_diff/review/index.html", __dir__))
-  HEAD_SHA = "a1" * 20
-  Request = Struct.new(:method, :path, :query, :authorization, :json)
-
-  # The exact text between <script> and </script>; the CSP hashes it.
-  def self.script_sha256(html)
-    "sha256-#{[Digest::SHA256.digest(html[%r{<script>(.*?)</script>}m, 1])].pack("m0")}"
-  end
-
-  # A stored-or-deflated zip with just what the page's reader needs.
-  def self.zip(files)
-    out = +"".b
-    central = +"".b
-    files.each do |name, bytes|
-      bytes = bytes.b
-      deflater = Zlib::Deflate.new(Zlib::DEFAULT_COMPRESSION, -Zlib::MAX_WBITS)
-      packed = deflater.deflate(bytes, Zlib::FINISH)
-      crc = Zlib.crc32(bytes)
-      fields = [20, 0, 8, 0, 0, crc, packed.bytesize, bytes.bytesize, name.bytesize, 0]
-      central << [0x02014b50, 20].pack("Vv") << fields.pack("vvvvvVVVvv") << [0, 0, 0, 0, out.bytesize].pack("vvvVV") << name.b
-      out << [0x04034b50].pack("V") << fields.pack("vvvvvVVVvv") << name.b << packed
-    end
-    out << central << [0x06054b50, 0, 0, files.size, files.size, central.bytesize, out.bytesize - central.bytesize, 0].pack("VvvvvVVv")
-  end
-
-  attr_reader :requests
-  attr_accessor :run, :artifact, :pull, :zip, :baselines, :runs_status, :patch_status, :moved_ref_sha
-
-  def initialize(zip:, baselines: {})
-    @zip = zip
-    @baselines = baselines
-    @requests = []
-    @run = {id: 11, head_sha: HEAD_SHA, head_branch: "feature", event: "pull_request", head_repository: {full_name: "o/r"}}
-    @artifact = {id: 22, expired: false, size_in_bytes: zip.bytesize, workflow_run: {id: 11}}
-    @pull = {state: "open", head: {sha: HEAD_SHA, ref: "feature", repo: {full_name: "o/r"}}, base: {ref: "main", repo: {default_branch: "main"}}}
-  end
-
-  def writes = requests.reject { _1.method == "GET" }
-
-  def git_sha(text) = Digest::SHA1.hexdigest(text)
-
-  def call(env)
-    req = Rack::Request.new(env)
-    return page(req) if req.path_info == "/"
-
-    body = req.body.read
-    json = body.empty? ? nil : JSON.parse(body, symbolize_names: true)
-    requests << Request.new(req.request_method, req.path_info, req.query_string, env["HTTP_AUTHORIZATION"], json)
-    route(req.request_method, req.path_info, json)
-  end
-
-  private
-
-  def route(verb, path, json)
-    case "#{verb} #{path}"
-    when "GET /user" then reply(200, login: "reviewer")
-    when %r{\AGET /repos/o/r/actions/runs/\d+\z} then runs_status ? reply(runs_status, message: "Bad credentials") : reply(200, run)
-    when %r{\AGET /repos/o/r/actions/artifacts/\d+\z} then reply(200, artifact)
-    when %r{\AGET /repos/o/r/actions/artifacts/\d+/zip\z} then [303, {"location" => "/blob/artifact.zip"}, []]
-    when "GET /blob/artifact.zip" then [200, {"content-type" => "application/zip"}, [zip]]
-    when %r{\AGET /repos/o/r/pulls/\d+\z} then reply(200, pull)
-    when %r{\AGET /repos/o/r/contents/(.+)\z}
-      (bytes = baselines[$1]) ? [200, {"content-type" => "application/vnd.github.raw"}, [bytes]] : reply(404, message: "Not Found")
-    when "POST /repos/o/r/git/blobs" then reply(201, sha: git_sha(json[:content]))
-    when %r{\AGET /repos/o/r/git/commits/\h{40}\z} then reply(200, sha: HEAD_SHA, tree: {sha: git_sha("tree of head")})
-    when "POST /repos/o/r/git/trees" then reply(201, sha: git_sha(json.to_json))
-    when "POST /repos/o/r/git/commits" then reply(201, sha: git_sha(json.to_json), html_url: "https://github.com/o/r/commit/#{git_sha(json.to_json)}")
-    when %r{\APATCH /repos/o/r/git/refs/heads/.+\z}
-      patch_status ? reply(patch_status, message: "Update is not a fast forward") : reply(200, object: {sha: json[:sha]})
-    when %r{\AGET /repos/o/r/git/refs?/heads/.+\z} then reply(200, object: {sha: moved_ref_sha || HEAD_SHA})
-    when %r{\APOST /repos/o/r/issues/\d+/comments\z} then reply(201, html_url: "https://github.com/o/r/pull/7#issuecomment-1")
-    else reply(404, message: "fake has no route for #{verb} #{path}")
-    end
-  end
-
-  def reply(status, hash) = [status, {"content-type" => "application/json"}, [JSON.generate(hash)]]
-
-  # The page under test with its two hooks used: the API origin and the CSP.
-  # Changing the script changes its hash, so the hash is recomputed here.
-  def page(req)
-    origin = "#{req.scheme}://#{req.host_with_port}"
-    html = PAGE.read
-    html = html.sub('const API = "https://api.github.com";', %(const API = "#{origin}";))
-    html = html.sub("connect-src https://api.github.com", "connect-src #{origin}")
-    html = html.sub(/'sha256-[^']+'/, "'#{self.class.script_sha256(html)}'")
-    [200, {"content-type" => "text/html"}, [html]]
-  end
-end
diff --git a/test/unit/review_page_csp_test.rb b/test/unit/review_page_csp_test.rb
deleted file mode 100644
index 4de6bd1c..00000000
--- a/test/unit/review_page_csp_test.rb
+++ /dev/null
@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-require "test_helper"
-require "support/fake_github_api"
-
-class ReviewPageCspTest < Minitest::Test
-  def test_csp_script_hash_matches_the_inline_script
-    html = FakeGithub::PAGE.read
-
-    assert_equal 1, html.scan(/<script\b/).size, "the page must have exactly one inline script"
-    declared = html[/<meta http-equiv="Content-Security-Policy" content="[^"]*script-src '(sha256-[^']+)'/, 1]
-    refute_nil declared, "the CSP meta has no script-src 'sha256-...'"
-    actual = FakeGithub.script_sha256(html)
-
-    assert_equal actual, declared, <<~MSG
-      The CSP script hash in lib/snap_diff/review/index.html is stale (the browser would refuse to run the page).
-      Recompute it: take the exact text between <script> and </script> and run
-        ruby -rdigest -e 'puts "sha256-" + [Digest::SHA256.digest(File.read("lib/snap_diff/review/index.html")[%r{<script>(.*?)</script>}m, 1])].pack("m0")'
-      then paste the result into the meta's script-src.
-    MSG
-  end
-end

From d19dbf84def85d715bb3918d0aec3c2f42d593ad Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 11:42:13 +0200
Subject: [PATCH 12/16] feat: Accept and Reject in the CI report build the PR
 comment that accepts

In a CI run (GITHUB_RUN_ID set) each screenshot the manifest lists gets
Accept and Reject (Y / N), and Copy review command copies
/snap-diff accept run=<id> <files> plus a reject line, shown in a
read-only field too. Local reports are unchanged.
---
 lib/snap_diff/reporters/html.rb               | 30 ++++++-
 .../reporters/templates/report.html.erb       | 87 ++++++++++++++++++-
 test/integration/review_controls_test.rb      | 75 ++++++++++++++++
 test/unit/reporters/html_reporter_test.rb     | 56 +++++++++++-
 4 files changed, 241 insertions(+), 7 deletions(-)
 create mode 100644 test/integration/review_controls_test.rb

diff --git a/lib/snap_diff/reporters/html.rb b/lib/snap_diff/reporters/html.rb
index c0ae359d..e0412d73 100644
--- a/lib/snap_diff/reporters/html.rb
+++ b/lib/snap_diff/reporters/html.rb
@@ -130,6 +130,25 @@ def render
         ERB.new(File.read(self.class.template_path)).result(binding)
       end
 
+      # Review controls (Accept/Reject, the PR comment command) exist only in
+      # a CI run, where the run id names the artifact the bot reads.
+      def review
+        run = ENV["GITHUB_RUN_ID"].to_s
+        return if run.empty?
+
+        {run: run, files: manifest_entries.map { |entry| entry[:accept]["file"] }}
+      end
+
+      # The entries the page shows. In a CI run those a reviewer may accept
+      # carry their manifest `file`; the rest of :accept stays internal.
+      def report_data
+        entries.map do |entry|
+          data = entry.except(:accept)
+          data[:file] = entry[:accept]["file"] if review && manifest_entry?(entry)
+          data
+        end
+      end
+
       def self.template_path
         File.expand_path("templates/report.html.erb", __dir__)
       end
@@ -279,11 +298,16 @@ def write_report
         write_manifest
       end
 
+      def manifest_entry?(entry) = %w[changed new].include?(entry[:status]) && entry[:accept]
+
+      # One file, one entry: the last capture.
+      def manifest_entries
+        entries.select { |entry| manifest_entry?(entry) }.reverse.uniq { |entry| entry[:accept]["path"] }.reverse
+      end
+
       # What a reviewer page may accept: the captures that differ or are new.
       def write_manifest
-        accepted = entries.select { |entry| %w[changed new].include?(entry[:status]) && entry[:accept] }
-        accepted = accepted.reverse.uniq { |entry| entry[:accept]["path"] }.reverse # one file, one entry: the last capture
-        manifest = accepted.map { |entry| {"name" => entry[:name], "status" => entry[:status]}.merge(entry[:accept]) }
+        manifest = manifest_entries.map { |entry| {"name" => entry[:name], "status" => entry[:status]}.merge(entry[:accept]) }
         File.write(output_path.dirname / "snap_diff_manifest.json", JSON.pretty_generate("version" => 1, "entries" => manifest))
       end
     end
diff --git a/lib/snap_diff/reporters/templates/report.html.erb b/lib/snap_diff/reporters/templates/report.html.erb
index f3565b8b..da519c91 100644
--- a/lib/snap_diff/reporters/templates/report.html.erb
+++ b/lib/snap_diff/reporters/templates/report.html.erb
@@ -153,6 +153,18 @@
     .zoom-fit { font-size: .625rem; font-family: var(--font); font-weight: 500; background: none; border: 1px solid var(--border); border-radius: var(--radius-sm); color: var(--text2); padding: .2rem .5rem; cursor: pointer; transition: all .1s; }
     .zoom-fit:hover { background: var(--bg4); color: var(--text); }
 
+<% if review %>
+    /* Review controls (CI runs only) */
+    .review-btn { padding: .3rem .625rem; font-size: .625rem; font-family: var(--font); font-weight: 500; background: var(--bg); color: var(--text3); border: 1px solid var(--border); border-radius: var(--radius); cursor: pointer; white-space: nowrap; }
+    .review-btn:hover { color: var(--text2); border-color: var(--text3); }
+    .review-btn.accept.active { background: var(--green-dim); color: var(--green); border-color: var(--green); }
+    .review-btn.reject.active { background: var(--red-dim); color: var(--red); border-color: var(--red); }
+    #review-panel { display: flex; align-items: flex-start; gap: .5rem; padding: .375rem .75rem; background: var(--bg2); border-top: 1px solid var(--border); flex-shrink: 0; }
+    #review-side { display: flex; flex-direction: column; gap: .25rem; align-items: flex-start; }
+    #review-count, #review-hint { font-size: .625rem; color: var(--text2); }
+    #review-command { flex: 1; min-width: 0; height: 2.75rem; resize: none; font-family: var(--font-mono); font-size: .625rem; background: var(--surface); color: var(--text); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: .25rem .4rem; }
+<% end %>
+
     /* Scrollbar */
     ::-webkit-scrollbar { width: 5px; height: 5px; }
     ::-webkit-scrollbar-track { background: transparent; }
@@ -224,6 +236,12 @@
       <button class="toggle-btn" id="annotate-toggle" title="Show annotated versions (A)">
         <span class="toggle-pip"></span> Annotated
       </button>
+<% if review %>
+      <div class="sep"></div>
+      <span class="toolbar-label">Review</span>
+      <button class="review-btn accept" id="review-accept" title="Accept (Y)" hidden>Accept</button>
+      <button class="review-btn reject" id="review-reject" title="Reject (N)" hidden>Reject</button>
+<% end %>
     </div>
 
     <div id="ai-bar"><span id="ai-verdict" class="ai-badge"></span><span id="ai-text"></span></div>
@@ -232,6 +250,17 @@
       <div id="view-inner"></div>
     </div>
 
+<% if review %>
+    <div id="review-panel">
+      <div id="review-side">
+        <span id="review-count"></span>
+        <button class="review-btn" id="review-copy">Copy review command</button>
+        <span id="review-hint">Paste this as a comment on the pull request.</span>
+      </div>
+      <textarea id="review-command" readonly aria-label="Review command"></textarea>
+    </div>
+<% end %>
+
     <div id="zoom-bar">
       <button class="zoom-btn" id="zoom-out" title="Zoom out (-)"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="8"/><path d="M8 11h6"/></svg></button>
       <span class="zoom-label" id="zoom-label">100%</span>
@@ -244,7 +273,10 @@
 <script>
 (function() {
   'use strict';
-  var DATA = <%= @entries.map { |entry| entry.except(:accept) }.to_json.gsub("</", "<\\/") %>;
+  var DATA = <%= report_data.to_json.gsub("</", "<\\/") %>;
+<% if review %>
+  var REVIEW = <%= review.to_json.gsub("</", "<\\/") %>;
+<% end %>
   var state = { current: 0, view: 'both', annotated: false, zoom: 100, search: '' };
   var $ = function(id) { return document.getElementById(id); };
 
@@ -449,8 +481,55 @@
     /* Update button states */
     viewBtns.forEach(function(b) { b.classList.toggle('active', b.dataset.view === state.view); });
     annotateBtn.classList.toggle('active', state.annotated);
+<% if review %>
+    syncReview();
+<% end %>
   }
 
+<% if review %>
+  /* ── Review (CI runs): build the PR comment command ───────────────────
+     Decisions are keyed by manifest file, so entries sharing a file share
+     the decision. */
+  var decisions = {};
+  var reviewAccept = $('review-accept'), reviewReject = $('review-reject');
+  var reviewCommand = $('review-command'), reviewCount = $('review-count');
+
+  function reviewText() {
+    var accepted = REVIEW.files.filter(function(f) { return decisions[f] === 'accept'; });
+    var rejected = REVIEW.files.filter(function(f) { return decisions[f] === 'reject'; });
+    var lines = [];
+    if (accepted.length) lines.push('/snap-diff accept run=' + REVIEW.run + ' ' + accepted.join(' '));
+    if (rejected.length) lines.push('/snap-diff reject ' + rejected.join(' '));
+    return { text: lines.join('\n'), accepted: accepted.length, rejected: rejected.length };
+  }
+  function syncReview() {
+    var file = DATA[state.current] && DATA[state.current].file;
+    [[reviewAccept, 'accept'], [reviewReject, 'reject']].forEach(function(pair) {
+      pair[0].hidden = !file;
+      pair[0].classList.toggle('active', !!file && decisions[file] === pair[1]);
+    });
+    var r = reviewText();
+    reviewCount.textContent = r.accepted + ' accepted \u00b7 ' + r.rejected + ' rejected';
+    reviewCommand.value = r.text;
+  }
+  function decide(choice) {
+    var file = DATA[state.current] && DATA[state.current].file;
+    if (!file) return;
+    if (decisions[file] === choice) delete decisions[file]; else decisions[file] = choice;
+    syncReview();
+  }
+  reviewAccept.addEventListener('click', function() { decide('accept'); });
+  reviewReject.addEventListener('click', function() { decide('reject'); });
+  $('review-copy').addEventListener('click', function() {
+    var text = reviewCommand.value;
+    if (!text) return;
+    var select = function() { reviewCommand.focus(); reviewCommand.select(); };
+    try {
+      navigator.clipboard.writeText(text).catch(select);
+    } catch (e) { select(); }
+  });
+<% end %>
+
   /* ── View switching ───────────────────────────────────────────────── */
   viewBtns.forEach(function(btn) {
     btn.addEventListener('click', function() { state.view = this.dataset.view; render(); buildSidebar(); });
@@ -554,7 +633,7 @@
 
   /* ── Keyboard ──────────────────────────────────────────────────────── */
   document.addEventListener('keydown', function(e) {
-    if (e.target.tagName === 'INPUT') { if (e.key === 'Escape') searchEl.blur(); return; }
+    if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') { if (e.key === 'Escape') searchEl.blur(); return; }
     switch (e.key) {
       case 'ArrowRight': case 'ArrowDown': e.preventDefault(); selectNext(); break;
       case 'ArrowLeft':  case 'ArrowUp':   e.preventDefault(); selectPrev(); break;
@@ -563,6 +642,10 @@
       case '3': state.view = 'new'; render(); buildSidebar(); break;
       case '4': state.view = 'heatmap'; render(); buildSidebar(); break;
       case 'a': case 'A': state.annotated = !state.annotated; render(); buildSidebar(); break;
+<% if review %>
+      case 'y': case 'Y': decide('accept'); break;
+      case 'n': case 'N': decide('reject'); break;
+<% end %>
       case '/': e.preventDefault(); searchEl.focus(); break;
       case '+': case '=': zoomTo(state.zoom + 25); break;
       case '-': zoomTo(state.zoom - 25); break;
diff --git a/test/integration/review_controls_test.rb b/test/integration/review_controls_test.rb
new file mode 100644
index 00000000..aae468e0
--- /dev/null
+++ b/test/integration/review_controls_test.rb
@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "snap_diff/reporters/html"
+require "support/setup_capybara_drivers"
+
+# The report's review controls, driven in a real browser: a reviewer clicks
+# Accept and Reject and the read-only field shows the PR comment command.
+class ReviewControlsTest < ActiveSupport::TestCase
+  setup do
+    @dir = Pathname.new(Dir.mktmpdir).realpath
+    system("git", "-C", @dir.to_s, "init", "-q", exception: true)
+    @original_root = SnapDiff.config.root
+    SnapDiff.config.root = @dir
+    @original_run_id = ENV["GITHUB_RUN_ID"]
+    ENV["GITHUB_RUN_ID"] = "99"
+    @session = Capybara::Session.new(Capybara.javascript_driver)
+  end
+
+  teardown do
+    @session.quit
+    ENV["GITHUB_RUN_ID"] = @original_run_id
+    SnapDiff.config.root = @original_root
+    FileUtils.remove_entry(@dir)
+  end
+
+  test "Accept and Reject build the exact PR comment command" do
+    # "one" and "one again" are two entries of the same file.
+    report = write_report(%w[one one_again two], files: {"one_again" => "one"})
+    @session.visit "file://#{report}"
+
+    assert_equal "", command, "nothing is decided yet"
+    @session.click_button "Accept"
+    assert_equal "/snap-diff accept run=99 screenshots/one.png", command
+    assert_equal "1 accepted · 0 rejected", @session.find("#review-count").text
+
+    @session.find("body").send_keys(:right) # one_again: shares the decision
+    assert @session.has_css?("#review-accept.active")
+
+    @session.find("body").send_keys(:right)
+    @session.click_button "Reject"
+    assert_equal "/snap-diff accept run=99 screenshots/one.png\n/snap-diff reject screenshots/two.png", command
+    assert_equal "1 accepted · 1 rejected", @session.find("#review-count").text
+
+    @session.click_button "Accept" # two: reject -> accept
+    assert_equal "/snap-diff accept run=99 screenshots/one.png screenshots/two.png", command
+
+    @session.find("body").send_keys("n")
+    assert_equal "/snap-diff accept run=99 screenshots/one.png\n/snap-diff reject screenshots/two.png", command
+  end
+
+  test "a local report has no review controls" do
+    ENV["GITHUB_RUN_ID"] = nil
+    @session.visit "file://#{write_report(%w[one])}"
+
+    assert @session.has_css?("#topbar-title", text: "one")
+    assert @session.has_no_button?("Accept")
+    assert @session.has_no_css?("#review-command")
+  end
+
+  private
+
+  def command = @session.find("#review-command").value
+
+  def write_report(names, files: {})
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @dir / "report.html")
+    names.each do |name|
+      path = @dir / "screenshots" / "#{files.fetch(name, name)}.png"
+      path.dirname.mkpath
+      FileUtils.cp(File.expand_path("a.png", TEST_IMAGES_DIR), path)
+      reporter.record([SnapDiff::ScreenshotAssertion.new(name, path: path)])
+    end
+    reporter.finalize.to_s
+  end
+end
diff --git a/test/unit/reporters/html_reporter_test.rb b/test/unit/reporters/html_reporter_test.rb
index bdcbb3e2..ea49f7a8 100644
--- a/test/unit/reporters/html_reporter_test.rb
+++ b/test/unit/reporters/html_reporter_test.rb
@@ -613,8 +613,60 @@ def synchronize
     assert_not (@output_dir / "snap_diff_manifest.json").exist?
   end
 
+  # --- review controls: only in a CI run, only for manifest files ---------
+
+  test "in a CI run the report carries the run id and the files a reviewer may accept" do
+    first = build_failing_assertion("index")
+    report_dir = first.compare.image_path.dirname
+    reporter = SnapDiff::Reporters::HTML.new(output_path: report_dir / "report.html")
+    reporter.record([first])
+    reporter.record([build_failing_assertion("index")])
+    with_run_id("4242") { reporter.finalize }
+
+    file = manifest(report_dir).fetch("entries").sole.fetch("file")
+    html = (report_dir / "report.html").read
+    assert_includes html, "Copy review command"
+    assert_equal({"run" => "4242", "files" => [file]}, report_review(report_dir / "report.html"))
+    assert_equal [file, file], report_data(report_dir / "report.html").map { |e| e["file"] }
+  end
+
+  test "outside a CI run the report has no review controls" do
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    reporter.record([build_failing_assertion("index")])
+    with_run_id(nil) { reporter.finalize }
+
+    html = @output_path.read
+    assert_not_includes html, "Copy review command"
+    assert_not_includes html, "var REVIEW"
+    assert_not_includes report_data.sole.keys, "file"
+  end
+
+  test "a re-recorded entry and a capture outside the report directory get no review controls" do
+    git_init_output_dir
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_dir / "report/report.html")
+    reporter.record([build_rerecorded_assertion("accepted")])
+    capture_new_screenshot(reporter, "outside")
+    with_run_id("7") { reporter.finalize }
+
+    path = @output_dir / "report/report.html"
+    assert_equal({"run" => "7", "files" => []}, report_review(path))
+    assert_equal [nil, nil], report_data(path).map { |e| e["file"] }
+  end
+
   private
 
+  def with_run_id(id)
+    original = ENV["GITHUB_RUN_ID"]
+    ENV["GITHUB_RUN_ID"] = id
+    yield
+  ensure
+    ENV["GITHUB_RUN_ID"] = original
+  end
+
+  def report_review(path)
+    JSON.parse(path.read[/^\s*var REVIEW = (.*);$/, 1])
+  end
+
   def git_init_output_dir
     system("git", "-C", @output_dir.to_s, "init", "-q", exception: true)
   end
@@ -637,8 +689,8 @@ def capture_new_screenshot(reporter, name, dir: "screenshots", root: @output_dir
     path
   end
 
-  def report_data
-    json = @output_path.read[/^\s*var DATA = (.*);$/, 1]
+  def report_data(path = @output_path)
+    json = path.read[/^\s*var DATA = (.*);$/, 1]
     JSON.parse(json.gsub("<\\/", "</"))
   end
 

From 6f770edbfbd9298dd4dd62d9ce41596398f39546 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 12:45:07 +0200
Subject: [PATCH 13/16] feat: accept screenshots by PR comment, carried out
 with the repository's token

/snap-diff accept run=<id> <file>@<sha16>... (copied from the report)
makes an issue_comment workflow commit those captures from that run's
report artifact to the PR branch, reply, and re-run CI. No personal
token: GITHUB_TOKEN does the write.

It runs no PR code (read-tree, hooks and config off), requires write
permission via the API, binds the run to the PR head and each file to
the reviewed SHA-256, writes only PNG/WebP bytes under screenshots-path,
refuses Git LFS paths, stages without filters and pushes with a lease
on the reviewed commit. Replies carry fixed text only.

In the report, only the last capture of a file gets Accept/Reject;
superseded or uncaptured entries say why.
---
 .../accept-screenshots/accept_screenshots.rb  | 409 +++++++++++++++++
 .github/actions/accept-screenshots/action.yml |  32 ++
 .github/workflows/snap-diff-accept.yml        |  37 ++
 lib/snap_diff/reporters/html.rb               |  42 +-
 .../reporters/templates/report.html.erb       |  28 +-
 test/integration/review_controls_test.rb      |  59 ++-
 test/unit/accept_screenshots_test.rb          | 410 ++++++++++++++++++
 test/unit/reporters/html_reporter_test.rb     |  49 ++-
 8 files changed, 1034 insertions(+), 32 deletions(-)
 create mode 100644 .github/actions/accept-screenshots/accept_screenshots.rb
 create mode 100644 .github/actions/accept-screenshots/action.yml
 create mode 100644 .github/workflows/snap-diff-accept.yml
 create mode 100644 test/unit/accept_screenshots_test.rb

diff --git a/.github/actions/accept-screenshots/accept_screenshots.rb b/.github/actions/accept-screenshots/accept_screenshots.rb
new file mode 100644
index 00000000..1797d516
--- /dev/null
+++ b/.github/actions/accept-screenshots/accept_screenshots.rb
@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+# Accept screenshot baselines from a PR comment:
+#
+#   /snap-diff accept run=<run_id> <file>@<sha16> <file>@<sha16> ...
+#   /snap-diff reject <file> ...            (optional, informational)
+#
+# <file> is a `file` from the report's snap_diff_manifest.json; <sha16> is the
+# first 16 hex digits of the SHA-256 of its bytes, as the report showed them.
+# The bytes come from that run's `*-report-full` artifact and are committed to
+# the PR branch at the manifest `path`. Nothing from the repository is
+# executed: git only fetches, reads the tree into an index, stages blobs,
+# commits and pushes; there is no working tree.
+# Stdlib only; shells out to `gh` and `git`.
+#
+# Environment (all required unless noted):
+#   GH_TOKEN             token for gh and git (contents/pull-requests/actions)
+#   GITHUB_REPOSITORY    owner/name
+#   GITHUB_SERVER_URL    optional, default https://github.com
+#   COMMENT_BODY         the PR comment
+#   COMMENT_AUTHOR       commenter login
+#   AUTHOR_ASSOCIATION   pre-filter: OWNER, MEMBER or COLLABORATOR
+#   PR_NUMBER            the pull request number
+#   SCREENSHOTS_PATH     optional, default doc/screenshots: every target must be under it
+#   CI_WORKFLOW          optional: workflow file to dispatch on the branch after the push
+#   RUNNER_TEMP          optional: scratch dir, default a fresh Dir.mktmpdir
+#
+# Every refusal is a reply comment on the PR plus exit status 1. Replies and
+# logs carry only validated strings or fixed text, never raw input.
+
+require "json"
+require "open3"
+require "base64"
+require "digest"
+require "fileutils"
+require "tmpdir"
+
+module AcceptScreenshots
+  class Refusal < StandardError; end
+
+  MAX_FILES = 200
+  MAX_BODY = 20_000
+  MAX_BYTES = 20 * 1024 * 1024
+  MAX_TOTAL_BYTES = 200 * 1024 * 1024
+  MAX_ARTIFACT_BYTES = 100 * 1024 * 1024
+  MAX_MANIFEST_BYTES = 1024 * 1024
+  MAX_CANDIDATES = 10
+  ALLOWED_ASSOCIATIONS = %w[OWNER MEMBER COLLABORATOR].freeze
+  ALLOWED_CHARS = "only A-Z a-z 0-9 . _ - /, no spaces, no `..`"
+  # No spaces: the command is whitespace-split, so a name with one cannot be written.
+  SAFE_PATH = %r{\A[A-Za-z0-9._/-]+\z}
+  LOGIN = /\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\z/
+  ACCEPT_LINE = %r{\A/snap-diff accept(?: |\z)}
+  ACCEPT = %r{\A/snap-diff accept run=(\d+)((?: +\S+)*)\z}
+  REJECT = %r{\A/snap-diff reject((?: +\S+)*)\z}
+  HASHED = /\A([^@]+)@([0-9a-f]{16})\z/
+  MAGIC = {".png" => ["PNG", /\A\x89PNG\r\n\x1A\n/n], ".webp" => ["WebP", /\ARIFF....WEBP/mn]}.freeze
+  BOT = ["github-actions[bot]", "41898282+github-actions[bot]@users.noreply.github.com"].freeze
+
+  module_function
+
+  # {run:, accept: {file => sha16}, reject: [file]}
+  def parse(body)
+    raise Refusal, "Comment too long (over #{MAX_BODY} characters)." if body.length > MAX_BODY
+
+    lines = body.lines.map(&:strip).reject(&:empty?)
+    raise Refusal, "The first line must be `/snap-diff accept run=<run id> <file>@<hash> ...`." unless lines.first&.match?(ACCEPT_LINE)
+
+    accept = lines.first.match(ACCEPT) or raise Refusal, "Missing or invalid `run=<run id>` (digits only)."
+    reject = []
+    lines.drop(1).each do |line|
+      match = line.match(REJECT) or raise Refusal, "Unexpected line after the accept line; only `/snap-diff reject <file> ...` may follow."
+      reject.concat(match[1].split)
+    end
+    tokens = accept[2].split.uniq
+    raise Refusal, "Accept needs at least one file." if tokens.empty?
+    raise Refusal, "Too many files (#{tokens.size}, max #{MAX_FILES})." if tokens.size > MAX_FILES
+
+    files = tokens.each_with_index.with_object({}) do |(token, i), acc|
+      match = token.match(HASHED) or raise Refusal, "Accepted file ##{i + 1} lacks its @<hash> (16 lowercase hex); copy the command from the report again."
+      file, sha16 = match.captures
+      raise Refusal, "Accepted file ##{i + 1} is not allowed (#{ALLOWED_CHARS})." unless safe_path?(file)
+      raise Refusal, "`#{file}` is accepted twice with different hashes." if acc.key?(file)
+
+      acc[file] = sha16
+    end
+    reject.each_with_index { |file, i| raise Refusal, "Rejected file ##{i + 1} is not allowed (#{ALLOWED_CHARS})." unless safe_path?(file) }
+    {run: accept[1], accept: files, reject: reject.uniq}
+  end
+
+  # Relative, no empty / `.` / `..` segments, conservative characters.
+  def safe_path?(path)
+    return false unless path.is_a?(String) && path.match?(SAFE_PATH)
+
+    path.split("/", -1).none? { |segment| segment.empty? || segment == "." || segment == ".." }
+  end
+
+  # `permission` is the base role: maintain reads as write, custom roles as their base.
+  def writer?(permission_json) = %w[admin write].include?(permission_json["permission"])
+
+  def manifest_entries(manifest)
+    entries = manifest.is_a?(Hash) && manifest["entries"]
+    (entries.is_a?(Array) && entries.all?(Hash)) ? entries : nil
+  end
+
+  # { requested file => target path }, validated.
+  def entries_for(manifest, files, screenshots_path)
+    entries = manifest_entries(manifest) or raise Refusal, "The report manifest is malformed."
+
+    targets = files.to_h do |file|
+      matches = entries.select { |entry| entry["file"] == file }
+      raise Refusal, "`#{file}` is not in the report manifest." if matches.empty?
+      raise Refusal, "`#{file}` is listed more than once in the report manifest." if matches.size > 1
+      raise Refusal, "`#{file}`: only changed or new screenshots can be accepted." unless %w[changed new].include?(matches.first["status"])
+
+      [file, check_target!(file, matches.first["path"], screenshots_path)]
+    end
+    duplicate = targets.values.tally.find { |_, count| count > 1 }
+    raise Refusal, "Two accepted files share the same target `#{duplicate.first}`." if duplicate
+
+    targets
+  end
+
+  def check_target!(file, path, screenshots_path)
+    allowed = safe_path?(path) && path.start_with?("#{screenshots_path}/") &&
+      path.split("/").none? { |segment| segment.downcase.start_with?(".git") }
+    raise Refusal, "Target path for `#{file}` is not allowed (under `#{screenshots_path}/`, #{ALLOWED_CHARS}, no `.git*` segment)." unless allowed
+
+    ext = File.extname(path).downcase
+    raise Refusal, "`#{file}`: extension must be .png or .webp and match its target." unless MAGIC.key?(ext) && File.extname(file).downcase == ext
+
+    path
+  end
+
+  def check_image!(file, bytes)
+    kind, magic = MAGIC.fetch(File.extname(file).downcase)
+    raise Refusal, "`#{file}` is not a #{kind} image." unless bytes.b.match?(magic)
+
+    nil
+  end
+
+  def check_hash!(file, bytes, sha16)
+    raise Refusal, "`#{file}` does not match the reviewed hash #{sha16}; review the report again." unless Digest::SHA256.hexdigest(bytes).start_with?(sha16)
+
+    nil
+  end
+
+  # Sizes are checked before any byte is read.
+  def read_images(dir, files, max_file: MAX_BYTES, max_total: MAX_TOTAL_BYTES)
+    root = File.realpath(dir)
+    total = 0
+    paths = files.to_h do |file|
+      path = File.join(dir, file)
+      raise Refusal, "`#{file}` is missing from the artifact." unless File.exist?(path) || File.symlink?(path)
+      raise Refusal, "`#{file}` in the artifact is not a regular file." unless File.lstat(path).file?
+      raise Refusal, "`#{file}` in the artifact is not a regular file." unless File.realpath(path).start_with?("#{root}/")
+
+      size = File.size(path)
+      raise Refusal, "`#{file}` is larger than #{max_file} bytes." if size > max_file
+      total += size
+      raise Refusal, "The accepted files together are larger than #{max_total} bytes." if total > max_total
+
+      [file, path]
+    end
+    paths.transform_values { |path| File.binread(path) }
+  end
+
+  # Report artifact names, sorted; expired and oversized ones left out.
+  def report_artifacts(artifacts_json)
+    artifacts_json.fetch("artifacts")
+      .select { |a| !a["expired"] && a["name"].to_s.end_with?("-report-full") && a["size_in_bytes"].to_i <= MAX_ARTIFACT_BYTES }
+      .map { |a| a["name"] }.sort
+  end
+
+  # The first of at most MAX_CANDIDATES artifacts whose manifest lists every
+  # file with the command's hash: [index, manifest]. The block loads one
+  # manifest (index, name), so later artifacts are never downloaded. The
+  # manifest is only a pointer; the gate is check_hash! on the picked bytes.
+  def pick_artifact(names, accept)
+    names.first(MAX_CANDIDATES).each_with_index do |name, i|
+      manifest = yield(name, i)
+      entries = manifest_entries(manifest) or next
+      covered = accept.all? { |file, sha16| entries.any? { |e| e["file"] == file && e["sha256"].to_s.start_with?(sha16) } }
+      return [i, manifest] if covered
+    end
+    raise Refusal, "No report artifact of this run lists all of #{accept.keys.join(", ")} with those hashes."
+  end
+
+  def load_manifest(dir)
+    path = File.join(dir, "snap_diff_manifest.json")
+    return unless File.file?(path) && !File.symlink?(path) && File.size(path) <= MAX_MANIFEST_BYTES
+
+    JSON.parse(File.read(path))
+  rescue JSON::ParserError
+    nil
+  end
+
+  # The run must come from this repository (no forks) and from this PR: a run
+  # of another PR or event on the same commit carries another report. A
+  # workflow_dispatch run (this bot's CI re-dispatch) lists no PRs, so it
+  # counts when it ran on the PR's branch. head_sha equality is checked apart.
+  def check_run!(run, repo, pr, run_id, head_ref)
+    raise Refusal, "Run #{run_id} was not built from this repository." unless run.dig("head_repository", "full_name") == repo
+
+    of_pr = Array(run["pull_requests"]).any? { |p| p["number"].to_s == pr }
+    dispatched_on_branch = run["event"] == "workflow_dispatch" && run["head_branch"] == head_ref
+    raise Refusal, "Run #{run_id} is not a run of this pull request." unless of_pr || dispatched_on_branch
+
+    nil
+  end
+
+  # Paths whose `git check-attr filter` output says lfs.
+  def lfs_paths(check_attr_output)
+    check_attr_output.lines.filter_map do |line|
+      path, value = line.chomp.split(": filter: ", 2)
+      path if value == "lfs"
+    end
+  end
+
+  def summary(command, targets, sha, ci_line)
+    lines = [sha ? "Accepted #{targets.size} screenshot(s) from run #{command[:run]} in #{sha}:" :
+      "Nothing to commit: these screenshots from run #{command[:run]} already match the PR branch:"]
+    targets.each { |file, path| lines << "- `#{file}` -> `#{path}`" }
+    unless command[:reject].empty?
+      lines << "" << "Rejected (not committed):"
+      command[:reject].each { |file| lines << "- `#{file}`" }
+    end
+    lines << "" << ci_line if sha
+    lines.join("\n")
+  end
+
+  def commit_message(targets, run_id, login, pr)
+    bullets = targets.map { |file, path| "- #{file} -> #{path}" }.join("\n")
+    "Accept screenshot baselines\n\nAccepted by @#{login} in PR ##{pr} from run #{run_id}:\n#{bullets}\n"
+  end
+
+  # Workflow commands start a line with `::`; nothing logged may.
+  # A lone \r ends a line for the runner too.
+  def log_text(text) = text.to_s[0, 4000].gsub(/\r\n?/, "\n").gsub(/^(\s*)::/, '\1: :')
+
+  def log(text) = warn(log_text(text))
+
+  # ---- side effects ---------------------------------------------------------
+
+  def env(name) = ENV.fetch(name) { abort "#{name} is not set" }
+
+  def sh(*cmd, stdin: nil, env: {}, chdir: nil)
+    opts = {stdin_data: stdin, binmode: true}
+    opts[:chdir] = chdir if chdir
+    out, err, status = Open3.capture3(env, *cmd, **opts)
+    log(err) unless err.empty?
+    [out, status.success?]
+  end
+
+  def sh!(*cmd, **opts)
+    out, ok = sh(*cmd, **opts)
+    raise "#{cmd.first(2).join(" ")} failed" unless ok
+
+    out
+  end
+
+  def gh_json(path) = JSON.parse(sh!("gh", "api", path))
+
+  def reply(repo, pr, text)
+    sh!("gh", "api", "-X", "POST", "repos/#{repo}/issues/#{pr}/comments", "--input", "-", stdin: JSON.generate(body: text))
+  end
+
+  # A fresh, isolated git: no global or system config, no hooks, no LFS
+  # downloads, the bot as author. `auth` adds the token as an HTTP header via
+  # GIT_CONFIG_* env -- never argv, a remote URL or .git/config.
+  def git_env(auth = nil)
+    config = [["core.hooksPath", "/dev/null"]]
+    config << ["http.#{ENV.fetch("GITHUB_SERVER_URL", "https://github.com")}/.extraheader", "AUTHORIZATION: basic #{auth}"] if auth
+    vars = {
+      "GIT_CONFIG_GLOBAL" => "/dev/null", "GIT_CONFIG_NOSYSTEM" => "1",
+      "GIT_LFS_SKIP_SMUDGE" => "1", "GIT_TERMINAL_PROMPT" => "0",
+      "GIT_AUTHOR_NAME" => BOT[0], "GIT_AUTHOR_EMAIL" => BOT[1],
+      "GIT_COMMITTER_NAME" => BOT[0], "GIT_COMMITTER_EMAIL" => BOT[1],
+      "GIT_CONFIG_COUNT" => config.size.to_s
+    }
+    config.each_with_index { |(key, value), i| vars.merge!("GIT_CONFIG_KEY_#{i}" => key, "GIT_CONFIG_VALUE_#{i}" => value) }
+    vars
+  end
+
+  def run!
+    repo = env("GITHUB_REPOSITORY")
+    pr = env("PR_NUMBER")
+    raise "PR_NUMBER is not a number" unless pr.match?(/\A\d+\z/)
+
+    exit 1 unless accept!(repo, pr)
+  rescue Refusal => e
+    log(e.message)
+    reply(repo, pr, "Screenshot accept refused: #{e.message}")
+    exit 1
+  rescue => e
+    log("#{e.class}: #{e.message}")
+    reply(repo, pr, "Screenshot accept failed; see the workflow log.") if repo && pr
+    exit 1
+  end
+
+  # True unless the commit landed but the CI dispatch failed.
+  def accept!(repo, pr)
+    raise Refusal, "Only owners, members and collaborators can accept screenshots." unless ALLOWED_ASSOCIATIONS.include?(env("AUTHOR_ASSOCIATION"))
+
+    login = env("COMMENT_AUTHOR")
+    raise Refusal, "Only people with write access can accept screenshots." unless login.match?(LOGIN)
+    # MEMBER/COLLABORATOR includes read-only people; the permission API does not.
+    raise Refusal, "Only people with write access can accept screenshots." unless writer?(gh_json("repos/#{repo}/collaborators/#{login}/permission"))
+
+    screenshots_path = ENV.fetch("SCREENSHOTS_PATH", "doc/screenshots").delete_suffix("/")
+    raise "SCREENSHOTS_PATH must be a safe relative path" unless safe_path?(screenshots_path)
+    workflow = ENV["CI_WORKFLOW"].to_s
+    raise "CI_WORKFLOW must be a workflow file name" unless workflow.empty? || workflow.match?(/\A[\w.-]+\.ya?ml\z/)
+
+    command = parse(env("COMMENT_BODY"))
+    run_id = command[:run]
+    files = command[:accept].keys
+
+    run = gh_json("repos/#{repo}/actions/runs/#{run_id}")
+    pull = gh_json("repos/#{repo}/pulls/#{pr}")
+    branch = pull.dig("head", "ref")
+    check_run!(run, repo, pr, run_id, branch)
+    raise Refusal, "The pull request is not open." unless pull["state"] == "open"
+    raise Refusal, "The pull request comes from a fork." unless pull.dig("head", "repo", "full_name") == repo
+    raise Refusal, "PR has new commits since run #{run_id} — review the new report." unless pull.dig("head", "sha") == run["head_sha"]
+    raise "unexpected head_sha" unless run["head_sha"].to_s.match?(/\A\h{40}\z/)
+    raise Refusal, "Refusing to push to the base or default branch." if [pull.dig("base", "ref"), pull.dig("base", "repo", "default_branch")].include?(branch)
+
+    work = Dir.mktmpdir("snap-diff-accept-", ENV["RUNNER_TEMP"] || Dir.mktmpdir)
+    names = report_artifacts(gh_json("repos/#{repo}/actions/runs/#{run_id}/artifacts?per_page=100"))
+    picked, manifest = pick_artifact(names, command[:accept]) do |name, i|
+      dir = File.join(work, "artifact-#{i}")
+      sh!("gh", "run", "download", run_id, "-R", repo, "-n", name, "-D", dir)
+      load_manifest(dir)
+    end
+    targets = entries_for(manifest, files, screenshots_path)
+    images = read_images(File.join(work, "artifact-#{picked}"), files)
+    images.each do |file, bytes|
+      check_image!(file, bytes)
+      check_hash!(file, bytes, command[:accept].fetch(file))
+    end
+
+    auth = Base64.strict_encode64("x-access-token:#{env("GH_TOKEN")}")
+    puts "::add-mask::#{auth}" if ENV["GITHUB_ACTIONS"] == "true"
+    sha = commit_and_push(remote: "#{ENV.fetch("GITHUB_SERVER_URL", "https://github.com")}/#{repo}.git", head_sha: run["head_sha"],
+      branch: branch, targets: targets, images: images, dir: File.join(work, "repo"),
+      message: commit_message(targets, run_id, login, pr), git_env: git_env(auth))
+
+    ci_line = workflow.empty? ? "Re-run CI to verify." : "Dispatching `#{workflow}` on the PR branch to verify."
+    reply(repo, pr, summary(command, targets, sha, ci_line))
+    puts "accepted #{targets.size} file(s): #{sha || "no change"}"
+    return true unless sha && !workflow.empty?
+
+    dispatch_ci(repo, pr, workflow, branch)
+  ensure
+    FileUtils.rm_rf(work) if work # nothing of this run outlives it on a persistent runner
+  end
+
+  # Best effort, after the reply: a failure must not hide the pushed commit.
+  # A push made with GITHUB_TOKEN does not start workflows; a
+  # workflow_dispatch made with it does.
+  def dispatch_ci(repo, pr, workflow, branch)
+    _, ok = sh("gh", "workflow", "run", workflow, "-R", repo, "--ref", branch)
+    return true if ok
+
+    log("CI dispatch failed; the commit is pushed.")
+    reply(repo, pr, "The commit is pushed, but dispatching `#{workflow}` failed. Re-run CI to verify.")
+    false
+  end
+
+  # A scratch repository holding only the reviewed commit, read into the
+  # index; no working tree. Blobs are written from the verified bytes with
+  # --no-filters and staged by id, so the PR's .gitattributes cannot rewrite
+  # them.
+  # Returns the pushed commit, or nil when the bytes are already committed.
+  def commit_and_push(remote:, head_sha:, branch:, targets:, images:, dir:, message:, git_env:)
+    git = ->(*args, stdin: nil) { sh!("git", *args, stdin: stdin, env: git_env, chdir: dir) }
+
+    FileUtils.mkdir_p(dir)
+    git.call("init", "-q")
+    git.call("remote", "add", "origin", remote)
+    git.call("fetch", "-q", "--depth=1", "origin", head_sha)
+    git.call("read-tree", head_sha)
+
+    lfs = lfs_paths(git.call("check-attr", "--cached", "filter", "--", *targets.values))
+    raise Refusal, lfs.map { |path| "`#{path}` is tracked by Git LFS; accept it locally." }.join(" ") unless lfs.empty?
+
+    targets.each do |file, path|
+      bytes = images.fetch(file)
+      blob = git.call("hash-object", "-w", "--no-filters", "--stdin", stdin: bytes).strip
+      raise "staged blob differs from the verified bytes" unless blob == Digest::SHA1.hexdigest("blob #{bytes.bytesize}\0".b + bytes.b)
+
+      git.call("update-index", "--add", "--cacheinfo", "100644,#{blob},#{path}")
+    end
+    _, unchanged = sh("git", "diff-index", "--cached", "--quiet", head_sha, env: git_env, chdir: dir)
+    return nil if unchanged
+
+    commit = git.call("commit-tree", git.call("write-tree").strip, "-p", head_sha, "-F", "-", stdin: message).strip
+    # A lease, not a force: the push lands only while the branch is exactly the
+    # reviewed head_sha. A plain push would still fast-forward a branch reset
+    # to an ancestor of head_sha and bring the removed commits back.
+    _, pushed = sh("git", "push", "-q", "--force-with-lease=refs/heads/#{branch}:#{head_sha}", "origin", "#{commit}:refs/heads/#{branch}", env: git_env, chdir: dir)
+    raise Refusal, "Push rejected: the branch moved or is protected. Review the new report." unless pushed
+
+    commit
+  end
+end
+
+AcceptScreenshots.run! if $PROGRAM_NAME == __FILE__
diff --git a/.github/actions/accept-screenshots/action.yml b/.github/actions/accept-screenshots/action.yml
new file mode 100644
index 00000000..2f5a7128
--- /dev/null
+++ b/.github/actions/accept-screenshots/action.yml
@@ -0,0 +1,32 @@
+---
+name: 'Accept SnapDiff screenshots'
+description: >-
+  Commit screenshot baselines accepted in a PR comment
+  (`/snap-diff accept run=<run id> <file> ...`) from that run's report artifact.
+  Run it from an issue_comment workflow gated to OWNER/MEMBER/COLLABORATOR.
+inputs:
+  token:
+    description: 'Token with contents: write, pull-requests: write, actions: read (actions: write to dispatch ci-workflow); reads the commenter''s permission'
+    default: ${{ github.token }}
+  screenshots-path:
+    description: 'Every accepted file must be committed under this directory (relative to the repository root)'
+    default: 'doc/screenshots'
+  ci-workflow:
+    description: >-
+      Optional workflow file name (with workflow_dispatch) to run on the PR branch after the commit.
+      A push made with GITHUB_TOKEN does not start workflows; a workflow_dispatch does.
+    default: ''
+runs:
+  using: 'composite'
+  steps:
+    - name: Accept screenshots
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        CI_WORKFLOW: ${{ inputs.ci-workflow }}
+        SCREENSHOTS_PATH: ${{ inputs.screenshots-path }}
+        COMMENT_BODY: ${{ github.event.comment.body }}
+        COMMENT_AUTHOR: ${{ github.event.comment.user.login }}
+        AUTHOR_ASSOCIATION: ${{ github.event.comment.author_association }}
+        PR_NUMBER: ${{ github.event.issue.number }}
+      run: ruby "$GITHUB_ACTION_PATH/accept_screenshots.rb"
diff --git a/.github/workflows/snap-diff-accept.yml b/.github/workflows/snap-diff-accept.yml
new file mode 100644
index 00000000..1e1e96d4
--- /dev/null
+++ b/.github/workflows/snap-diff-accept.yml
@@ -0,0 +1,37 @@
+---
+name: Accept screenshots
+
+# A maintainer pastes the report's review command as a PR comment:
+#   /snap-diff accept run=<run id> <file> ...
+# The action commits those files from that run's report artifact to the PR branch.
+
+on:
+  issue_comment:
+    types: [ created ]
+
+jobs:
+  accept:
+    if: >-
+      github.event.issue.pull_request &&
+      startsWith(github.event.comment.body, '/snap-diff accept') &&
+      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: write
+    concurrency:
+      group: snap-diff-accept-${{ github.event.issue.number }}
+      cancel-in-progress: false
+    steps:
+      # The default branch (issue_comment's ref): this repository's trusted
+      # code, needed for the local action. The PR's code is never checked out here.
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: ./.github/actions/accept-screenshots
+        with:
+          screenshots-path: test/fixtures/app/doc/screenshots
+          ci-workflow: test.yml
diff --git a/lib/snap_diff/reporters/html.rb b/lib/snap_diff/reporters/html.rb
index e0412d73..3eda86ac 100644
--- a/lib/snap_diff/reporters/html.rb
+++ b/lib/snap_diff/reporters/html.rb
@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "base64"
+require "digest"
 require "erb"
 require "fileutils"
 require "pathname"
@@ -136,15 +137,30 @@ def review
         run = ENV["GITHUB_RUN_ID"].to_s
         return if run.empty?
 
-        {run: run, files: manifest_entries.map { |entry| entry[:accept]["file"] }}
+        files = manifest_entries.map { |entry| entry[:accept]["file"] }
+        {run: run, files: files, sha16: files.to_h { |file| [file, file_sha256(file)[0, 16]] }}
       end
 
-      # The entries the page shows. In a CI run those a reviewer may accept
-      # carry their manifest `file`; the rest of :accept stays internal.
+      # The entries the page shows. In a CI run the manifest's entry for a
+      # file (its last capture) carries that `file`; an earlier capture of the
+      # same file points at it (`superseded_by`, an index); any other entry
+      # says why it has no controls (`review_reason`). The rest of :accept
+      # stays internal.
       def report_data
+        in_review = review
+        chosen = in_review ? manifest_entries : []
         entries.map do |entry|
           data = entry.except(:accept)
-          data[:file] = entry[:accept]["file"] if review && manifest_entry?(entry)
+          next data unless in_review
+
+          if chosen.any? { |m| m.equal?(entry) }
+            data[:file] = entry[:accept]["file"]
+          elsif manifest_entry?(entry)
+            later = chosen.find { |m| m[:accept]["path"] == entry[:accept]["path"] }
+            data[:superseded_by] = entries.index { |e| e.equal?(later) }
+          else
+            data[:review_reason] = (entry[:status] == "rerecorded") ? "rerecorded" : "no_capture"
+          end
           data
         end
       end
@@ -292,13 +308,25 @@ def data_uri(pathname)
         "data:#{mime};base64,#{Base64.strict_encode64(pathname.binread)}"
       end
 
+      # One digest per file for the page and the manifest alike.
       def write_report
         FileUtils.mkdir_p(output_path.dirname)
+        @digests = {}
         File.write(output_path, render)
         write_manifest
+      ensure
+        @digests = nil
       end
 
-      def manifest_entry?(entry) = %w[changed new].include?(entry[:status]) && entry[:accept]
+      def manifest_entry?(entry) = %w[changed new].include?(entry[:status]) && entry[:accept] && (output_path.dirname / entry[:accept]["file"]).file?
+
+      # Of the bytes on disk when the report is written -- what the artifact
+      # uploads. The accept command carries its first 16 hex digits, and the
+      # bot refuses a file whose bytes no longer match.
+      def file_sha256(file)
+        digest = -> { Digest::SHA256.file(output_path.dirname / file).hexdigest }
+        @digests ? (@digests[file] ||= digest.call) : digest.call
+      end
 
       # One file, one entry: the last capture.
       def manifest_entries
@@ -307,7 +335,9 @@ def manifest_entries
 
       # What a reviewer page may accept: the captures that differ or are new.
       def write_manifest
-        manifest = manifest_entries.map { |entry| {"name" => entry[:name], "status" => entry[:status]}.merge(entry[:accept]) }
+        manifest = manifest_entries.map do |entry|
+          {"name" => entry[:name], "status" => entry[:status]}.merge(entry[:accept], "sha256" => file_sha256(entry[:accept]["file"]))
+        end
         File.write(output_path.dirname / "snap_diff_manifest.json", JSON.pretty_generate("version" => 1, "entries" => manifest))
       end
     end
diff --git a/lib/snap_diff/reporters/templates/report.html.erb b/lib/snap_diff/reporters/templates/report.html.erb
index da519c91..f160834f 100644
--- a/lib/snap_diff/reporters/templates/report.html.erb
+++ b/lib/snap_diff/reporters/templates/report.html.erb
@@ -161,7 +161,7 @@
     .review-btn.reject.active { background: var(--red-dim); color: var(--red); border-color: var(--red); }
     #review-panel { display: flex; align-items: flex-start; gap: .5rem; padding: .375rem .75rem; background: var(--bg2); border-top: 1px solid var(--border); flex-shrink: 0; }
     #review-side { display: flex; flex-direction: column; gap: .25rem; align-items: flex-start; }
-    #review-count, #review-hint { font-size: .625rem; color: var(--text2); }
+    #review-count, #review-hint, #review-note { font-size: .625rem; color: var(--text2); }
     #review-command { flex: 1; min-width: 0; height: 2.75rem; resize: none; font-family: var(--font-mono); font-size: .625rem; background: var(--surface); color: var(--text); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: .25rem .4rem; }
 <% end %>
 
@@ -241,6 +241,8 @@
       <span class="toolbar-label">Review</span>
       <button class="review-btn accept" id="review-accept" title="Accept (Y)" hidden>Accept</button>
       <button class="review-btn reject" id="review-reject" title="Reject (N)" hidden>Reject</button>
+      <span id="review-note" hidden></span>
+      <button class="review-btn" id="review-jump" hidden>Show it</button>
 <% end %>
     </div>
 
@@ -498,16 +500,36 @@
     var accepted = REVIEW.files.filter(function(f) { return decisions[f] === 'accept'; });
     var rejected = REVIEW.files.filter(function(f) { return decisions[f] === 'reject'; });
     var lines = [];
-    if (accepted.length) lines.push('/snap-diff accept run=' + REVIEW.run + ' ' + accepted.join(' '));
+    var hashed = accepted.map(function(f) { return f + '@' + REVIEW.sha16[f]; });
+    if (accepted.length) lines.push('/snap-diff accept run=' + REVIEW.run + ' ' + hashed.join(' '));
     if (rejected.length) lines.push('/snap-diff reject ' + rejected.join(' '));
     return { text: lines.join('\n'), accepted: accepted.length, rejected: rejected.length };
   }
+  /* An entry without controls says why: an earlier capture of a file whose
+     last capture is the one on disk, or no final capture at all. */
+  var REASONS = {
+    superseded: 'Superseded by a later capture of this file.',
+    rerecorded: 'Re-recorded in this run, so there is nothing to accept.',
+    no_capture: 'No final capture in this report, so it cannot be accepted here.'
+  };
+  var reviewNote = $('review-note'), reviewJump = $('review-jump');
+  reviewJump.addEventListener('click', function() {
+    var item = DATA[state.current];
+    if (item && item.superseded_by != null) selectItem(item.superseded_by);
+  });
+
   function syncReview() {
-    var file = DATA[state.current] && DATA[state.current].file;
+    var item = DATA[state.current];
+    var file = item && item.file;
     [[reviewAccept, 'accept'], [reviewReject, 'reject']].forEach(function(pair) {
       pair[0].hidden = !file;
       pair[0].classList.toggle('active', !!file && decisions[file] === pair[1]);
     });
+    var superseded = !!item && item.superseded_by != null;
+    var reason = !item || file ? '' : REASONS[superseded ? 'superseded' : item.review_reason] || '';
+    reviewNote.textContent = reason;
+    reviewNote.hidden = !reason;
+    reviewJump.hidden = !superseded;
     var r = reviewText();
     reviewCount.textContent = r.accepted + ' accepted \u00b7 ' + r.rejected + ' rejected';
     reviewCommand.value = r.text;
diff --git a/test/integration/review_controls_test.rb b/test/integration/review_controls_test.rb
index aae468e0..e5979716 100644
--- a/test/integration/review_controls_test.rb
+++ b/test/integration/review_controls_test.rb
@@ -25,28 +25,48 @@ class ReviewControlsTest < ActiveSupport::TestCase
   end
 
   test "Accept and Reject build the exact PR comment command" do
-    # "one" and "one again" are two entries of the same file.
-    report = write_report(%w[one one_again two], files: {"one_again" => "one"})
-    @session.visit "file://#{report}"
+    @session.visit "file://#{write_report(%w[one two three])}"
 
     assert_equal "", command, "nothing is decided yet"
-    @session.click_button "Accept"
-    assert_equal "/snap-diff accept run=99 screenshots/one.png", command
-    assert_equal "1 accepted · 0 rejected", @session.find("#review-count").text
+    @session.find("body").send_keys(:right, :right, "y") # the user's flow: 3rd Y, 2nd N, 1st Y
+    @session.find("body").send_keys(:left, "n")
+    @session.find("body").send_keys(:left, "y")
+
+    assert_equal "/snap-diff accept run=99 screenshots/one.png@#{sha16} screenshots/three.png@#{sha16}\n" \
+      "/snap-diff reject screenshots/two.png", command
+    assert_equal "2 accepted · 1 rejected", @session.find("#review-count").text
+
+    @session.click_button "Reject" # one: accept -> reject
+    assert_equal "/snap-diff accept run=99 screenshots/three.png@#{sha16}\n" \
+      "/snap-diff reject screenshots/one.png screenshots/two.png", command
 
-    @session.find("body").send_keys(:right) # one_again: shares the decision
-    assert @session.has_css?("#review-accept.active")
+    @session.click_button "Reject" # one: reject -> undecided
+    assert_equal "/snap-diff accept run=99 screenshots/three.png@#{sha16}\n/snap-diff reject screenshots/two.png", command
+  end
 
-    @session.find("body").send_keys(:right)
-    @session.click_button "Reject"
-    assert_equal "/snap-diff accept run=99 screenshots/one.png\n/snap-diff reject screenshots/two.png", command
-    assert_equal "1 accepted · 1 rejected", @session.find("#review-count").text
+  test "an earlier capture of a file points at the last one, which alone has the buttons" do
+    # "one" and "one_again" capture the same file; only the last is on disk.
+    @session.visit "file://#{write_report(%w[one one_again], files: {"one_again" => "one"})}"
 
-    @session.click_button "Accept" # two: reject -> accept
-    assert_equal "/snap-diff accept run=99 screenshots/one.png screenshots/two.png", command
+    assert @session.has_no_button?("Accept")
+    assert @session.has_css?("#review-note", text: "Superseded by a later capture of this file.")
+    @session.find("body").send_keys("y")
+    assert_equal "", command, "Y does nothing on a superseded entry"
 
-    @session.find("body").send_keys("n")
-    assert_equal "/snap-diff accept run=99 screenshots/one.png\n/snap-diff reject screenshots/two.png", command
+    @session.click_button "Show it"
+    assert @session.has_css?("#topbar-title", text: "one_again")
+    assert @session.has_no_css?("#review-note")
+    @session.click_button "Accept"
+    assert_equal "/snap-diff accept run=99 screenshots/one.png@#{sha16}", command
+  end
+
+  test "an entry with no final capture says why it cannot be accepted" do
+    @session.visit "file://#{write_report(%w[gone], missing: %w[gone])}"
+
+    assert @session.has_css?("#review-note", text: "No final capture in this report, so it cannot be accepted here.")
+    assert @session.has_no_button?("Accept")
+    @session.find("body").send_keys("y")
+    assert_equal "", command
   end
 
   test "a local report has no review controls" do
@@ -62,12 +82,15 @@ class ReviewControlsTest < ActiveSupport::TestCase
 
   def command = @session.find("#review-command").value
 
-  def write_report(names, files: {})
+  # The same bytes (a.png) for every capture, so one hash.
+  def sha16 = Digest::SHA256.file(File.expand_path("a.png", TEST_IMAGES_DIR)).hexdigest[0, 16]
+
+  def write_report(names, files: {}, missing: [])
     reporter = SnapDiff::Reporters::HTML.new(output_path: @dir / "report.html")
     names.each do |name|
       path = @dir / "screenshots" / "#{files.fetch(name, name)}.png"
       path.dirname.mkpath
-      FileUtils.cp(File.expand_path("a.png", TEST_IMAGES_DIR), path)
+      FileUtils.cp(File.expand_path("a.png", TEST_IMAGES_DIR), path) unless missing.include?(name)
       reporter.record([SnapDiff::ScreenshotAssertion.new(name, path: path)])
     end
     reporter.finalize.to_s
diff --git a/test/unit/accept_screenshots_test.rb b/test/unit/accept_screenshots_test.rb
new file mode 100644
index 00000000..a42a8c5b
--- /dev/null
+++ b/test/unit/accept_screenshots_test.rb
@@ -0,0 +1,410 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "tmpdir"
+require_relative "../../.github/actions/accept-screenshots/accept_screenshots"
+
+class AcceptScreenshotsTest < Minitest::Test
+  A = AcceptScreenshots
+  PNG = "\x89PNG\r\n\x1A\n".b + "rest\r\n".b
+  WEBP = "RIFF\x10\x00\x00\x00WEBPVP8 ".b
+  HOSTILE = "x\n::add-mask::s @someone [a](http://e)"
+
+  def refusal(&block) = assert_raises(A::Refusal, &block).message
+
+  def sha16(bytes) = Digest::SHA256.hexdigest(bytes)[0, 16]
+
+  def assert_not_echoed(text)
+    %w[add-mask @someone http:// [a]].each { |bit| refute_includes text, bit }
+  end
+
+  # -- parse --------------------------------------------------------------
+
+  def test_parse_accept_and_reject
+    body = "/snap-diff accept run=123 linux/a.png@0123abcd0123abcd linux/b.webp@ffffffffffffffff\r\n/snap-diff reject linux/c.png\n"
+
+    assert_equal({run: "123", accept: {"linux/a.png" => "0123abcd0123abcd", "linux/b.webp" => "ffffffffffffffff"}, reject: %w[linux/c.png]}, A.parse(body))
+  end
+
+  def test_parse_without_reject_line
+    assert_equal({run: "7", accept: {"a.png" => "0123abcd0123abcd"}, reject: []}, A.parse("/snap-diff accept run=7 a.png@0123abcd0123abcd"))
+  end
+
+  def test_parse_drops_duplicate_files
+    assert_equal({"a.png" => "0123abcd0123abcd"}, A.parse("/snap-diff accept run=7 a.png@0123abcd0123abcd a.png@0123abcd0123abcd")[:accept])
+  end
+
+  def test_parse_refuses_one_file_with_two_hashes
+    assert_match(/twice/, refusal { A.parse("/snap-diff accept run=7 a.png@0123abcd0123abcd a.png@0000000000000000") })
+  end
+
+  def test_parse_requires_the_hash
+    ["a.png", "a.png@0123abcd", "a.png@0123abcd0123abc", "a.png@0123ABCD0123ABCD", "a.png@0123abcd0123abcd0", "a.png@"].each do |token|
+      assert_match(/@<hash>/, refusal { A.parse("/snap-diff accept run=7 #{token}") }, token)
+    end
+  end
+
+  def test_parse_refuses_missing_run
+    assert_match(/run=/, refusal { A.parse("/snap-diff accept a.png@0123abcd0123abcd") })
+    assert_match(/run=/, refusal { A.parse("/snap-diff accept run=12x a.png@0123abcd0123abcd") })
+  end
+
+  def test_parse_refuses_no_files
+    assert_match(/at least one file/, refusal { A.parse("/snap-diff accept run=7") })
+  end
+
+  def test_parse_refuses_other_lines
+    assert_match(/unexpected line/i, refusal { A.parse("/snap-diff accept run=7 a.png@0123abcd0123abcd\nplease merge") })
+    assert_match(/first line/, refusal { A.parse("hi\n/snap-diff accept run=7 a.png@0123abcd0123abcd") })
+  end
+
+  def test_parse_refuses_bad_chars_without_echoing_them
+    assert_match(/not allowed/, refusal { A.parse("/snap-diff accept run=7 a$(id).png@0123abcd0123abcd") })
+    assert_match(/not allowed/, refusal { A.parse("/snap-diff accept run=7 a.png@0123abcd0123abcd\n/snap-diff reject b;c.png") })
+    assert_not_echoed refusal { A.parse("/snap-diff accept run=7 a.png@0123abcd0123abcd\n/snap-diff reject [a](http://e)@someone") }
+  end
+
+  def test_parse_refuses_dot_dot_and_absolute
+    ["../a.png", "x/../../a.png", "/etc/a.png"].each do |file|
+      assert_match(/not allowed/, refusal { A.parse("/snap-diff accept run=7 #{file}@0123abcd0123abcd") }, file)
+    end
+  end
+
+  def test_parse_refuses_too_many_files
+    files = (1..A::MAX_FILES + 1).map { |i| "f#{i}.png@0123abcd0123abcd" }.join(" ")
+
+    assert_match(/too many/i, refusal { A.parse("/snap-diff accept run=7 #{files}") })
+  end
+
+  def test_parse_refuses_long_comment
+    assert_match(/too long/, refusal { A.parse("/snap-diff accept run=7 a.png@0123abcd0123abcd" + " " * A::MAX_BODY) })
+  end
+
+  # -- safe_path? -----------------------------------------------------------
+
+  def test_safe_path
+    assert A.safe_path?("test/fixtures/app/doc/screenshots/linux/index.png")
+    refute A.safe_path?("with space/x.png")
+    refute A.safe_path?("")
+    refute A.safe_path?("a/./b.png")
+    refute A.safe_path?("a//b.png")
+    refute A.safe_path?("a\nb.png")
+    refute A.safe_path?("a@b.png")
+  end
+
+  # -- writer? ----------------------------------------------------------------
+
+  def test_writer
+    assert A.writer?({"permission" => "admin", "role_name" => "admin"})
+    assert A.writer?({"permission" => "write", "role_name" => "maintain"})
+    assert A.writer?({"permission" => "write", "role_name" => "write"})
+    assert A.writer?({"permission" => "write", "role_name" => "custom-writer"})
+    refute A.writer?({"permission" => "read", "role_name" => "write"}), "the base permission decides"
+    refute A.writer?({"permission" => "read", "role_name" => "triage"})
+    refute A.writer?({"permission" => "read", "role_name" => "read"})
+    refute A.writer?({"permission" => "none"})
+  end
+
+  # -- entries_for: manifest lookup ----------------------------------------
+
+  def manifest(*entries) = {"version" => 1, "entries" => entries}
+
+  def entry(file, path: "shots/#{file}", status: "changed", sha256: "0" * 64)
+    {"name" => file, "status" => status, "path" => path, "file" => file, "sha256" => sha256}
+  end
+
+  def test_entries_for_maps_file_to_path
+    m = manifest(entry("a.png"), entry("b.webp", status: "new"), entry("c.png"))
+
+    assert_equal({"a.png" => "shots/a.png", "b.webp" => "shots/b.webp"}, A.entries_for(m, %w[a.png b.webp], "shots"))
+  end
+
+  def test_entries_for_refuses_unlisted_file
+    assert_match(/not in the report/, refusal { A.entries_for(manifest(entry("a.png")), %w[b.png], "shots") })
+  end
+
+  def test_entries_for_refuses_status_without_echoing_it
+    message = refusal { A.entries_for(manifest(entry("a.png", status: HOSTILE)), %w[a.png], "shots") }
+
+    assert_match(/only changed or new/, message)
+    assert_not_echoed message
+  end
+
+  def test_entries_for_refuses_target_outside_screenshots_path
+    ["other/a.png", "shotsy/a.png", "shots.png"].each do |path|
+      assert_match(/not allowed/, refusal { A.entries_for(manifest(entry("a.png", path: path)), %w[a.png], "shots") }, path)
+    end
+  end
+
+  def test_entries_for_refuses_git_segments
+    ["shots/.git/x.png", "shots/.GIT/x.png", "shots/.github/x.png", "shots/.gitattributes/x.png"].each do |path|
+      assert_match(/not allowed/, refusal { A.entries_for(manifest(entry("a.png", path: path)), %w[a.png], "shots") }, path)
+    end
+  end
+
+  def test_entries_for_refuses_unsafe_target_without_echoing_it
+    ["shots/../a.png", "/shots/a.png", "shots/a;b.png", "shots/with space.png", HOSTILE].each do |path|
+      message = refusal { A.entries_for(manifest(entry("a.png", path: path)), %w[a.png], "shots") }
+      assert_match(/not allowed/, message, path)
+      assert_not_echoed message
+    end
+  end
+
+  def test_entries_for_refuses_extension_mismatch
+    assert_match(/extension/, refusal { A.entries_for(manifest(entry("a.png", path: "shots/a.webp")), %w[a.png], "shots") })
+    assert_match(/extension/, refusal { A.entries_for(manifest(entry("a.txt")), %w[a.txt], "shots") })
+  end
+
+  def test_entries_for_refuses_two_files_one_target
+    m = manifest(entry("a.png", path: "shots/x.png"), entry("b.png", path: "shots/x.png"))
+
+    assert_match(/same target/, refusal { A.entries_for(m, %w[a.png b.png], "shots") })
+  end
+
+  def test_entries_for_refuses_duplicate_manifest_file
+    assert_match(/more than once/, refusal { A.entries_for(manifest(entry("a.png"), entry("a.png")), %w[a.png], "shots") })
+  end
+
+  def test_entries_for_refuses_malformed_manifest
+    assert_match(/manifest/, refusal { A.entries_for({"entries" => "x"}, %w[a.png], "shots") })
+    assert_match(/manifest/, refusal { A.entries_for(nil, %w[a.png], "shots") })
+  end
+
+  # -- check_image! / check_hash! -----------------------------------------------
+
+  def test_check_image_accepts_png_and_webp
+    assert_nil A.check_image!("a.png", PNG)
+    assert_nil A.check_image!("a.webp", WEBP)
+  end
+
+  def test_check_image_refuses_wrong_magic
+    assert_match(/not a PNG/, refusal { A.check_image!("a.png", WEBP) })
+    assert_match(/not a WebP/, refusal { A.check_image!("a.webp", PNG) })
+    assert_match(/not a PNG/, refusal { A.check_image!("a.png", "#!/bin/sh") })
+  end
+
+  def test_check_hash
+    assert_nil A.check_hash!("a.png", PNG, sha16(PNG))
+    assert_match(/does not match/, refusal { A.check_hash!("a.png", PNG + "x", sha16(PNG)) })
+  end
+
+  # -- read_images: sizes before reading ----------------------------------------
+
+  def test_read_images_checks_sizes_before_reading
+    Dir.mktmpdir do |dir|
+      File.binwrite(File.join(dir, "a.png"), PNG)
+      File.binwrite(File.join(dir, "b.png"), PNG)
+
+      assert_equal({"a.png" => PNG}, A.read_images(dir, %w[a.png]))
+      assert_match(/larger/, refusal { A.read_images(dir, %w[a.png], max_file: PNG.bytesize - 1) })
+      assert_match(/together/, refusal { A.read_images(dir, %w[a.png b.png], max_total: PNG.bytesize * 2 - 1) })
+    end
+  end
+
+  def test_read_images_refuses_symlinks_and_missing_files
+    Dir.mktmpdir do |dir|
+      File.symlink("/etc/hosts", File.join(dir, "a.png"))
+
+      assert_match(/not a regular file/, refusal { A.read_images(dir, %w[a.png]) })
+      assert_match(/missing/, refusal { A.read_images(dir, %w[b.png]) })
+    end
+  end
+
+  # -- artifacts ------------------------------------------------------------------
+
+  def test_report_artifacts_keeps_unexpired_report_artifacts_under_the_cap
+    artifacts = {"artifacts" => [
+      {"name" => "z-report-full", "expired" => false, "size_in_bytes" => 10},
+      {"name" => "a-report-full", "expired" => false, "size_in_bytes" => 10},
+      {"name" => "huge-report-full", "expired" => false, "size_in_bytes" => A::MAX_ARTIFACT_BYTES + 1},
+      {"name" => "a-diffs", "expired" => false, "size_in_bytes" => 10},
+      {"name" => "old-report-full", "expired" => true, "size_in_bytes" => 10}
+    ]}
+
+    assert_equal %w[a-report-full z-report-full], A.report_artifacts(artifacts)
+  end
+
+  def accept(*files) = files.to_h { |file| [file, "0" * 16] }
+
+  def test_pick_artifact_takes_the_first_manifest_listing_every_file_with_its_hash_and_stops_there
+    manifests = [
+      manifest(entry("x.png")),
+      manifest(entry("x.png"), entry("y.png", sha256: "f" * 64)), # y.png: another hash
+      manifest(entry("x.png"), entry("y.png")),
+      manifest(entry("x.png"), entry("y.png"))
+    ]
+    loaded = []
+
+    picked = A.pick_artifact(%w[a b c d], accept("x.png", "y.png")) do |name, i|
+      loaded << name
+      manifests[i]
+    end
+
+    assert_equal [2, manifests[2]], picked
+    assert_equal %w[a b c], loaded, "stops downloading once one covers"
+  end
+
+  def test_pick_artifact_refuses_when_none_covers
+    assert_match(/No report artifact/, refusal { A.pick_artifact(%w[a b], accept("x.png")) { |_, i| [manifest(entry("y.png")), nil][i] } })
+    assert_match(/No report artifact/, refusal { A.pick_artifact([], accept("x.png")) { flunk } })
+  end
+
+  def test_pick_artifact_tries_at_most_ten_candidates
+    loaded = []
+    names = (1..12).map(&:to_s)
+
+    refusal { A.pick_artifact(names, accept("x.png")) { |name| (loaded << name) && nil } }
+
+    assert_equal names.first(A::MAX_CANDIDATES), loaded
+  end
+
+  def test_load_manifest_refuses_oversized_or_missing_files
+    Dir.mktmpdir do |dir|
+      assert_nil A.load_manifest(dir)
+      File.write(File.join(dir, "snap_diff_manifest.json"), JSON.generate(manifest(entry("x.png"))))
+      assert_equal manifest(entry("x.png")), A.load_manifest(dir)
+      File.write(File.join(dir, "snap_diff_manifest.json"), " " * (A::MAX_MANIFEST_BYTES + 1))
+      assert_nil A.load_manifest(dir)
+    end
+  end
+
+  # -- check_run! -----------------------------------------------------------
+
+  def run_json(repo: "o/r", prs: [5], event: "pull_request", branch: "feat")
+    {"head_repository" => {"full_name" => repo}, "pull_requests" => prs.map { |n| {"number" => n} },
+     "event" => event, "head_branch" => branch}
+  end
+
+  def test_check_run_accepts_this_repo_and_pr
+    assert_nil A.check_run!(run_json, "o/r", "5", "9", "feat")
+  end
+
+  def test_check_run_accepts_dispatch_on_the_pr_branch
+    assert_nil A.check_run!(run_json(prs: [], event: "workflow_dispatch"), "o/r", "5", "9", "feat")
+  end
+
+  def test_check_run_refuses_fork
+    assert_match(/not built from this repository/, refusal { A.check_run!(run_json(repo: "fork/r"), "o/r", "5", "9", "feat") })
+  end
+
+  def test_check_run_refuses_run_of_another_pr
+    assert_match(/not a run of this pull request/, refusal { A.check_run!(run_json(prs: [6]), "o/r", "5", "9", "feat") })
+    assert_match(/not a run of this pull request/, refusal { A.check_run!(run_json(prs: []), "o/r", "5", "9", "feat") })
+  end
+
+  def test_check_run_refuses_dispatch_on_another_branch
+    run = run_json(prs: [], event: "workflow_dispatch", branch: "other")
+
+    assert_match(/not a run of this pull request/, refusal { A.check_run!(run, "o/r", "5", "9", "feat") })
+  end
+
+  def test_check_run_refuses_push_run_of_another_branch_same_sha
+    run = run_json(prs: [], event: "push", branch: "other")
+
+    assert_match(/not a run of this pull request/, refusal { A.check_run!(run, "o/r", "5", "9", "feat") })
+  end
+
+  # -- text that reaches replies and logs -------------------------------------
+
+  def test_lfs_paths
+    out = "a/x.png: filter: lfs\nc.png: filter: unspecified\nd.webp: filter: other\n"
+
+    assert_equal ["a/x.png"], A.lfs_paths(out)
+  end
+
+  def test_log_text_neutralises_workflow_commands
+    text = A.log_text("ok\n::add-mask::secret\n  ::error::x\r::warning::y")
+
+    refute_match(/(\A|[\r\n])\s*::/, text) # a lone \r starts a line for the runner too
+    assert_includes text, "ok"
+  end
+
+  def test_summary_names_only_validated_strings
+    command = {run: "7", accept: {"a.png" => "0123abcd0123abcd"}, reject: %w[b.png]}
+    text = A.summary(command, {"a.png" => "shots/a.png"}, "f" * 40, "Re-run CI to verify.")
+
+    assert_includes text, "`a.png` -> `shots/a.png`"
+    assert_includes text, "`b.png`"
+    assert_includes text, "f" * 40
+  end
+
+  def test_commit_message_credits_the_commenter_in_the_body
+    message = A.commit_message({"a.png" => "shots/a.png"}, "7", "octo-cat", "5")
+
+    assert_equal "Accept screenshot baselines", message.lines.first.chomp
+    assert_includes message, "Accepted by @octo-cat in PR #5"
+    refute_includes message, "Co-authored-by"
+  end
+
+  # -- commit_and_push against a local bare repository --------------------------
+
+  def git(dir, *args, env: A.git_env) = A.sh!("git", *args, env: env, chdir: dir).strip
+
+  # A bare remote whose feat branch has two commits; the second is the reviewed head.
+  def with_remote(attributes: "")
+    Dir.mktmpdir do |root|
+      remote = File.join(root, "remote.git")
+      seed = File.join(root, "seed")
+      git(root, "init", "-q", "--bare", remote)
+      git(remote, "config", "receive.shallowUpdate", "true") # as GitHub: a push from the shallow clone lands
+      git(root, "init", "-q", seed)
+      File.write(File.join(seed, ".gitattributes"), attributes)
+      FileUtils.mkdir_p(File.join(seed, "shots"))
+      File.binwrite(File.join(seed, "shots/a.png"), "old")
+      git(seed, "add", ".")
+      git(seed, "commit", "-q", "-m", "one")
+      ancestor = git(seed, "rev-parse", "HEAD")
+      git(seed, "commit", "-q", "--allow-empty", "-m", "two")
+      head = git(seed, "rev-parse", "HEAD")
+      git(seed, "push", "-q", remote, "HEAD:refs/heads/feat")
+      yield remote, head, ancestor, File.join(root, "work")
+    end
+  end
+
+  def push(remote, head, dir, targets: {"a.png" => "shots/a.png"}, images: {"a.png" => PNG})
+    A.commit_and_push(remote: remote, head_sha: head, branch: "feat", targets: targets, images: images,
+      dir: dir, message: "Accept screenshot baselines\n", git_env: A.git_env)
+  end
+
+  def test_committed_bytes_equal_the_artifact_bytes_despite_text_attributes
+    with_remote(attributes: "*.png text eol=lf\n") do |remote, head, _, dir|
+      sha = push(remote, head, dir)
+
+      assert_equal sha, git(remote, "rev-parse", "feat")
+      assert_equal PNG, A.sh!("git", "cat-file", "blob", "feat:shots/a.png", env: A.git_env, chdir: remote).b
+    end
+  end
+
+  def test_nothing_to_commit_when_bytes_already_match
+    with_remote do |remote, head, _, dir|
+      assert_nil push(remote, head, dir, images: {"a.png" => "old".b})
+      assert_equal head, git(remote, "rev-parse", "feat")
+    end
+  end
+
+  def test_a_moved_branch_rejects_the_push
+    with_remote do |remote, head, ancestor, dir|
+      git(remote, "update-ref", "refs/heads/feat", ancestor) # reset to an ancestor: a plain push would fast-forward
+
+      assert_match(/Push rejected: the branch moved or is protected/, refusal { push(remote, head, dir) })
+      assert_equal ancestor, git(remote, "rev-parse", "feat")
+    end
+  end
+
+  # The shallow clone alone already refuses the ancestor case above ("fetch
+  # first"); only the lease refuses recreating a branch deleted after review.
+  def test_a_deleted_branch_is_not_recreated
+    with_remote do |remote, head, _, dir|
+      git(remote, "update-ref", "-d", "refs/heads/feat")
+
+      assert_match(/Push rejected/, refusal { push(remote, head, dir) })
+      refute_includes git(remote, "branch", "--list"), "feat"
+    end
+  end
+
+  def test_lfs_tracked_target_is_refused
+    with_remote(attributes: "*.png filter=lfs\n") do |remote, head, _, dir|
+      assert_match(/Git LFS/, refusal { push(remote, head, dir) })
+    end
+  end
+end
diff --git a/test/unit/reporters/html_reporter_test.rb b/test/unit/reporters/html_reporter_test.rb
index ea49f7a8..013440f8 100644
--- a/test/unit/reporters/html_reporter_test.rb
+++ b/test/unit/reporters/html_reporter_test.rb
@@ -506,7 +506,8 @@ def synchronize
     capture_new_screenshot(reporter, "signup")
     reporter.finalize
 
-    assert_equal [{"name" => "signup", "status" => "new", "path" => "screenshots/signup.png", "file" => "screenshots/signup.png"}],
+    sha256 = Digest::SHA256.file(@output_dir / "screenshots/signup.png").hexdigest
+    assert_equal [{"name" => "signup", "status" => "new", "path" => "screenshots/signup.png", "file" => "screenshots/signup.png", "sha256" => sha256}],
       manifest.fetch("entries")
     assert_predicate @output_dir / "screenshots/signup.png", :exist?
   end
@@ -623,11 +624,48 @@ def synchronize
     reporter.record([build_failing_assertion("index")])
     with_run_id("4242") { reporter.finalize }
 
-    file = manifest(report_dir).fetch("entries").sole.fetch("file")
+    entry = manifest(report_dir).fetch("entries").sole
+    file = entry.fetch("file")
     html = (report_dir / "report.html").read
     assert_includes html, "Copy review command"
-    assert_equal({"run" => "4242", "files" => [file]}, report_review(report_dir / "report.html"))
-    assert_equal [file, file], report_data(report_dir / "report.html").map { |e| e["file"] }
+    # The hash binds the command to the bytes the artifact holds: the file on disk, the last capture.
+    assert_equal Digest::SHA256.file(report_dir / file).hexdigest, entry.fetch("sha256")
+    assert_equal({"run" => "4242", "files" => [file], "sha16" => {file => entry["sha256"][0, 16]}}, report_review(report_dir / "report.html"))
+    # Only the last capture of a file is on disk and in the manifest: the
+    # earlier entry points at it instead of offering its own controls.
+    data = report_data(report_dir / "report.html")
+    assert_equal [nil, file], data.map { |e| e["file"] }
+    assert_equal [1, nil], data.map { |e| e["superseded_by"] }
+  end
+
+  test "in a CI run an entry with no final capture says why it cannot be accepted" do
+    git_init_output_dir
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    reporter.record([SnapDiff::ScreenshotAssertion.new("gone", path: @output_dir / "screenshots/gone.png")])
+    reporter.record([build_rerecorded_assertion("accepted")])
+    capture_new_screenshot(reporter, "kept")
+    with_run_id("7") { reporter.finalize }
+
+    data = report_data
+    assert_equal ["no_capture", "rerecorded", nil], data.map { |e| e["review_reason"] }
+    assert_equal [nil, nil, "screenshots/kept.png"], data.map { |e| e["file"] }
+  end
+
+  # The template asks for the review data several times and every entry
+  # looks at it; each file is still read and hashed once per report.
+  test "in a CI run each manifest file is hashed once" do
+    git_init_output_dir
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    %w[a b c].each { |name| capture_new_screenshot(reporter, name) }
+    hashed = []
+    real = Digest::SHA256.method(:file)
+
+    Digest::SHA256.stub(:file, ->(path) { hashed << path.to_s and real.call(path) }) do
+      with_run_id("7") { reporter.finalize }
+    end
+
+    assert_equal %w[a b c].map { |n| (@output_dir / "screenshots/#{n}.png").to_s }, hashed
+    assert_equal 3, manifest.fetch("entries").size
   end
 
   test "outside a CI run the report has no review controls" do
@@ -649,8 +687,9 @@ def synchronize
     with_run_id("7") { reporter.finalize }
 
     path = @output_dir / "report/report.html"
-    assert_equal({"run" => "7", "files" => []}, report_review(path))
+    assert_equal({"run" => "7", "files" => [], "sha16" => {}}, report_review(path))
     assert_equal [nil, nil], report_data(path).map { |e| e["file"] }
+    assert_equal %w[rerecorded no_capture], report_data(path).map { |e| e["review_reason"] }
   end
 
   private

From c9a3aafa31b543be4eac49161d629594b43ccf36 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 13:03:32 +0200
Subject: [PATCH 14/16] fix: the manifest drops a file re-recorded later; clean
 removes it; aria-pressed

The last capture per path decides first, so an earlier changed capture
re-recorded later in the run is not offered for acceptance.
snap_diff:clean deletes snap_diff_manifest.json with the report, and
the report's Accept/Reject buttons expose their state as aria-pressed.
---
 Rakefile                                        |  2 +-
 lib/snap_diff/reporters/html.rb                 | 17 +++++++++++------
 .../reporters/templates/report.html.erb         |  4 +++-
 test/integration/review_controls_test.rb        |  7 +++++++
 test/unit/reporters/html_reporter_test.rb       | 17 +++++++++++++++++
 5 files changed, 39 insertions(+), 8 deletions(-)

diff --git a/Rakefile b/Rakefile
index 3562df55..ad1be8c0 100644
--- a/Rakefile
+++ b/Rakefile
@@ -69,7 +69,7 @@ desc "Remove screenshot diff artifacts (keeps baselines)"
 task "snap_diff:clean" do
   patterns = ["**/*.diff.png", "**/*.base.png", "**/*.base.diff.png", "**/*.heatmap.diff.png",
     "**/*.diff.webp", "**/*.base.webp", "**/*.base.diff.webp", "**/*.heatmap.diff.webp",
-    "**/snap_diff_report.html"]
+    "**/snap_diff_report.html", "**/snap_diff_manifest.json"]
   removed = patterns.flat_map { |p| Dir.glob("tmp/#{p}") + Dir.glob("doc/screenshots/#{p}") }.uniq
   removed.each { |f| FileUtils.rm_f(f) }
   puts "Removed #{removed.size} diff artifacts"
diff --git a/lib/snap_diff/reporters/html.rb b/lib/snap_diff/reporters/html.rb
index 3eda86ac..ab0fef79 100644
--- a/lib/snap_diff/reporters/html.rb
+++ b/lib/snap_diff/reporters/html.rb
@@ -155,8 +155,8 @@ def report_data
 
           if chosen.any? { |m| m.equal?(entry) }
             data[:file] = entry[:accept]["file"]
-          elsif manifest_entry?(entry)
-            later = chosen.find { |m| m[:accept]["path"] == entry[:accept]["path"] }
+          elsif reviewable_status?(entry) && captured?(entry)
+            later = last_captures.find { |m| m[:accept]["path"] == entry[:accept]["path"] }
             data[:superseded_by] = entries.index { |e| e.equal?(later) }
           else
             data[:review_reason] = (entry[:status] == "rerecorded") ? "rerecorded" : "no_capture"
@@ -318,7 +318,9 @@ def write_report
         @digests = nil
       end
 
-      def manifest_entry?(entry) = %w[changed new].include?(entry[:status]) && entry[:accept] && (output_path.dirname / entry[:accept]["file"]).file?
+      def reviewable_status?(entry) = %w[changed new].include?(entry[:status])
+
+      def captured?(entry) = entry[:accept] && (output_path.dirname / entry[:accept]["file"]).file?
 
       # Of the bytes on disk when the report is written -- what the artifact
       # uploads. The accept command carries its first 16 hex digits, and the
@@ -328,11 +330,14 @@ def file_sha256(file)
         @digests ? (@digests[file] ||= digest.call) : digest.call
       end
 
-      # One file, one entry: the last capture.
-      def manifest_entries
-        entries.select { |entry| manifest_entry?(entry) }.reverse.uniq { |entry| entry[:accept]["path"] }.reverse
+      # One file, one entry: the last capture, whatever its status -- a changed
+      # one re-recorded afterwards is already accepted.
+      def last_captures
+        entries.select { |entry| captured?(entry) }.reverse.uniq { |entry| entry[:accept]["path"] }.reverse
       end
 
+      def manifest_entries = last_captures.select { |entry| reviewable_status?(entry) }
+
       # What a reviewer page may accept: the captures that differ or are new.
       def write_manifest
         manifest = manifest_entries.map do |entry|
diff --git a/lib/snap_diff/reporters/templates/report.html.erb b/lib/snap_diff/reporters/templates/report.html.erb
index f160834f..117a24b8 100644
--- a/lib/snap_diff/reporters/templates/report.html.erb
+++ b/lib/snap_diff/reporters/templates/report.html.erb
@@ -523,7 +523,9 @@
     var file = item && item.file;
     [[reviewAccept, 'accept'], [reviewReject, 'reject']].forEach(function(pair) {
       pair[0].hidden = !file;
-      pair[0].classList.toggle('active', !!file && decisions[file] === pair[1]);
+      var on = !!file && decisions[file] === pair[1];
+      pair[0].classList.toggle('active', on);
+      pair[0].setAttribute('aria-pressed', on);
     });
     var superseded = !!item && item.superseded_by != null;
     var reason = !item || file ? '' : REASONS[superseded ? 'superseded' : item.review_reason] || '';
diff --git a/test/integration/review_controls_test.rb b/test/integration/review_controls_test.rb
index e5979716..31cdfc57 100644
--- a/test/integration/review_controls_test.rb
+++ b/test/integration/review_controls_test.rb
@@ -28,6 +28,7 @@ class ReviewControlsTest < ActiveSupport::TestCase
     @session.visit "file://#{write_report(%w[one two three])}"
 
     assert_equal "", command, "nothing is decided yet"
+    assert_equal %w[false false], pressed
     @session.find("body").send_keys(:right, :right, "y") # the user's flow: 3rd Y, 2nd N, 1st Y
     @session.find("body").send_keys(:left, "n")
     @session.find("body").send_keys(:left, "y")
@@ -35,12 +36,15 @@ class ReviewControlsTest < ActiveSupport::TestCase
     assert_equal "/snap-diff accept run=99 screenshots/one.png@#{sha16} screenshots/three.png@#{sha16}\n" \
       "/snap-diff reject screenshots/two.png", command
     assert_equal "2 accepted · 1 rejected", @session.find("#review-count").text
+    assert_equal %w[true false], pressed, "one is accepted"
 
     @session.click_button "Reject" # one: accept -> reject
+    assert_equal %w[false true], pressed
     assert_equal "/snap-diff accept run=99 screenshots/three.png@#{sha16}\n" \
       "/snap-diff reject screenshots/one.png screenshots/two.png", command
 
     @session.click_button "Reject" # one: reject -> undecided
+    assert_equal %w[false false], pressed
     assert_equal "/snap-diff accept run=99 screenshots/three.png@#{sha16}\n/snap-diff reject screenshots/two.png", command
   end
 
@@ -82,6 +86,9 @@ class ReviewControlsTest < ActiveSupport::TestCase
 
   def command = @session.find("#review-command").value
 
+  # aria-pressed of [Accept, Reject], which must follow the visual state.
+  def pressed = %w[#review-accept #review-reject].map { |id| @session.find(id)["aria-pressed"] }
+
   # The same bytes (a.png) for every capture, so one hash.
   def sha16 = Digest::SHA256.file(File.expand_path("a.png", TEST_IMAGES_DIR)).hexdigest[0, 16]
 
diff --git a/test/unit/reporters/html_reporter_test.rb b/test/unit/reporters/html_reporter_test.rb
index 013440f8..1645a76e 100644
--- a/test/unit/reporters/html_reporter_test.rb
+++ b/test/unit/reporters/html_reporter_test.rb
@@ -558,6 +558,23 @@ def synchronize
     assert_empty JSON.parse((@output_dir / "report/snap_diff_manifest.json").read).fetch("entries")
   end
 
+  # The file on disk is the last capture: a changed one that was re-recorded
+  # afterwards is already accepted, so it must not be offered again.
+  test "the manifest does not list a changed capture that a later re-recorded one replaced" do
+    changed = build_failing_assertion("index")
+    compare = make_comparison(:a, :b, destination: "fail_index")
+    compare.processed
+    rerecorded = SnapDiff::ScreenshotAssertion.new("index_again", record_mode: :all).tap { |a| a.compare = compare }
+    report_dir = changed.compare.image_path.dirname
+    reporter = SnapDiff::Reporters::HTML.new(output_path: report_dir / "report.html")
+    reporter.record([changed])
+    reporter.record([rerecorded])
+    reporter.finalize
+
+    assert_equal %w[changed rerecorded], reporter.entries.map { |e| e[:status] }
+    assert_empty manifest(report_dir).fetch("entries")
+  end
+
   test "the manifest carries file paths when images are embedded" do
     git_init_output_dir
     reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path, embed_images: true)

From 15ad84b70c1397f901a829c13e43f808309e0767 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 13:17:28 +0200
Subject: [PATCH 15/16] docs: accept screenshots from the pull request

The PR comment and job summary tell same-repository reviewers how to
accept. ci-integration.md covers the flow, the workflow to copy, who
can use it, its limits and the security model; reporters.md says what
snap_diff_manifest.json is for.
---
 .github/actions/upload-screenshots/action.yml |  8 +++
 CHANGELOG.md                                  |  7 ++
 README.md                                     |  2 +-
 docs/ci-integration.md                        | 68 +++++++++++++++++++
 docs/reporters.md                             |  7 +-
 5 files changed, 87 insertions(+), 5 deletions(-)

diff --git a/.github/actions/upload-screenshots/action.yml b/.github/actions/upload-screenshots/action.yml
index 7a937a8e..cb3e0641 100644
--- a/.github/actions/upload-screenshots/action.yml
+++ b/.github/actions/upload-screenshots/action.yml
@@ -77,6 +77,9 @@ runs:
     - name: Job summary
       if: steps.check-report.outputs.exists == 'true'
       shell: bash
+      env:
+        HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+        REPO: ${{ github.repository }}
       run: |
         cat >> "$GITHUB_STEP_SUMMARY" <<EOF
         ### SnapDiff Report
@@ -86,6 +89,9 @@ runs:
         | HTML report (inline) | ${{ steps.upload-report.outputs.artifact-url || 'N/A' }} |
         | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
         EOF
+        if [ "$HEAD_REPO" = "$REPO" ]; then
+          printf '\nTo accept: open the HTML report, mark screenshots Accept/Reject, Copy review command, and paste it as a comment on the pull request.\n' >> "$GITHUB_STEP_SUMMARY"
+        fi
 
     - name: Find existing PR comment
       if: inputs.pr-comment == 'true' && github.event_name == 'pull_request'
@@ -111,3 +117,5 @@ runs:
           | HTML report (inline) | ${{ steps.upload-report.outputs.artifact-url || 'N/A' }} |
           | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
           | [All artifacts](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}#artifacts) | Browse all |
+
+          ${{ steps.check-report.outputs.exists == 'true' && github.event.pull_request.head.repo.full_name == github.repository && 'To accept: open the HTML report, mark screenshots Accept/Reject, Copy review command, and paste it as a comment here.' || '' }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 64b0677e..b9536e11 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,13 @@ kept as history. This entry is the one to read if you are coming from **1.15.1**
 
 ### Added
 
+- **Accept screenshots from a pull request comment.** On GitHub Actions, the HTML report gets
+  Accept/Reject buttons and a "Copy review command" button. Pasting the command as a PR comment runs
+  the new `accept-screenshots` action, which commits the exact CI pixels to the PR branch with the
+  repository's `GITHUB_TOKEN`. The report also writes `snap_diff_manifest.json`, and
+  `upload-screenshots` adds a how-to-accept line to its PR comment and job summary. See
+  [CI integration](docs/ci-integration.md#accept-screenshots-from-the-pull-request).
+
 - **`SNAP_DIFF_ACCEPT_SCREENSHOTS=1` re-records changed baselines for one run.** The variable
   selects `record = :all` for the run that sees it, outranking `record =` and `fail_if_new`; a
   `record:` on the screenshot still outranks it. `1` and `true` turn it on; any other value is the
diff --git a/README.md b/README.md
index 389a3798..1a022be7 100644
--- a/README.md
+++ b/README.md
@@ -233,7 +233,7 @@ After tests run, open `doc/screenshots/snap_diff_report.html`:
 
 ![SnapDiff Web UI — annotated diff showing changed regions highlighted in red](docs/images/snap_diff_annotated.png)
 
-See [Web UI & Custom Reporters](docs/reporters.md) for full feature details and [CI Integration](docs/ci-integration.md) for GitHub Actions setup.
+See [Web UI & Custom Reporters](docs/reporters.md) for full feature details and [CI Integration](docs/ci-integration.md) for GitHub Actions setup, including [accepting screenshots from a PR comment](docs/ci-integration.md#accept-screenshots-from-the-pull-request).
 
 ## AI-Assisted Triage (optional)
 
diff --git a/docs/ci-integration.md b/docs/ci-integration.md
index c4e11e1e..80338ccb 100644
--- a/docs/ci-integration.md
+++ b/docs/ci-integration.md
@@ -283,4 +283,72 @@ Two things this minimal recipe does not do:
 2. Enter the branch name (e.g. your PR branch)
 3. The workflow records new and changed baselines, commits, and pushes
 
+## Accept screenshots from the pull request
+
+When a CI run fails on screenshot diffs, a reviewer can accept the new pixels without checking out the
+branch. In the HTML report (the inline link in the PR comment), each changed or new screenshot has
+Accept and Reject buttons (keys `Y` and `N`). The "Copy review command" button copies a line like
+`/snap-diff accept run=123 linux/cuprite/index.png@0123456789abcdef`. Pasting it as a PR comment starts
+a workflow that commits those exact files from that run's report artifact to the PR branch with the
+repository's own `GITHUB_TOKEN`, replies with the commit, and re-runs CI. The buttons appear only in
+reports built on GitHub Actions.
+
+To install it, copy this workflow. Set `screenshots-path` to your `save_path`. `ci-workflow` is
+optional: it names your test workflow, which needs an `on: workflow_dispatch` trigger. Without it the
+reply asks you to re-run CI by hand, because a push made with `GITHUB_TOKEN` does not start workflows.
+
+```yaml
+# .github/workflows/snap-diff-accept.yml
+name: Accept screenshots
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  accept:
+    if: >-
+      github.event.issue.pull_request &&
+      startsWith(github.event.comment.body, '/snap-diff accept') &&
+      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: write   # read is enough if you leave out ci-workflow
+    concurrency:
+      group: snap-diff-accept-${{ github.event.issue.number }}
+      cancel-in-progress: false
+    steps:
+      - uses: snap-diff/snap_diff-capybara/.github/actions/accept-screenshots@master
+        with:
+          screenshots-path: doc/screenshots
+          ci-workflow: test.yml
+```
+
+`issue_comment` workflows run only from the default branch, so merge this file first. Until then the
+comment does nothing.
+
+Commenters need write access to the repository. The workflow checks the permission API as well as the
+comment's `author_association`, so read-only collaborators are refused.
+
+Limits:
+
+- Pull requests from the same repository only. A fork PR is refused.
+- Git LFS paths are refused. Accept those locally.
+- Screenshot paths may use only `A-Z a-z 0-9 . _ - /` (no spaces) and must sit under `screenshots-path`.
+- The report artifact must still exist. `upload-screenshots` keeps it `retention-days` days (default 2).
+- Only the PR's current head can be accepted. After a new push, review the new run's report.
+- Only the last capture of a file can be accepted. Earlier captures of it show a note instead of the buttons.
+
+Security: the workflow never checks out or runs the PR's code. It downloads the report artifact, takes
+the paths from the report's manifest, and commits a file only if its SHA-256 matches the hash in the
+reviewer's command and its bytes are a PNG or WebP. It pushes only to the PR branch, and only while
+that branch is still at the commit the run tested. The design does rely on trust you already extend:
+whoever opens a same-repository PR can already push to the repository, and their CI run produces the
+artifact. Beyond that, the permission check and your branch protection limit the damage. Do not enable
+this for forks, and do not give the bot a ruleset bypass: with branch protection in place, a push the
+rules reject fails instead of landing.
+
 [← Back to README](../README.md)
diff --git a/docs/reporters.md b/docs/reporters.md
index e1479c75..153239c8 100644
--- a/docs/reporters.md
+++ b/docs/reporters.md
@@ -24,10 +24,9 @@ committing it is what accepts it). Their count in the report is the summary line
 
 **Note:** The report is not written when every screenshot matched and none is new.
 
-Beside the report it writes `snap_diff_manifest.json`: one entry per changed or new screenshot with
-its `name`, `status`, repo-relative baseline `path` and the capture `file`. The
-[browser review page](ci-integration.md#accept-or-reject-screenshots-in-the-browser) reads it; add
-it to your `.gitignore` next to `snap_diff_report.html`.
+It also writes `snap_diff_manifest.json`, one entry per changed or new screenshot. The
+[accept workflow](ci-integration.md#accept-screenshots-from-the-pull-request) reads it to find where
+each accepted file goes. Add it to your `.gitignore` next to `snap_diff_report.html`.
 
 ## The end-of-run summary
 

From 5d38a7e24934b5f9e263fa557df58c5161169535 Mon Sep 17 00:00:00 2001
From: Paul Keen <125715+pftg@users.noreply.github.com>
Date: Thu, 22 Oct 2026 14:50:05 +0200
Subject: [PATCH 16/16] feat: one Commit decisions button in the report,
 through a prefilled GitHub issue

Copying a command into a PR comment was too many steps. The report's
Commit decisions button opens GitHub's new-issue page with the
decisions as its body; submitting it runs the same accept workflow,
which now also handles issues: it commits, posts the summary on the PR,
links it from the issue and closes the issue. The command carries the
PR number, reject-only reviews are recorded, and the PR comment still
works as a fallback for selections too long for one link.
---
 .../accept-screenshots/accept_screenshots.rb  | 120 +++++++++++++-----
 .github/actions/accept-screenshots/action.yml |  18 +--
 .github/actions/upload-screenshots/action.yml |   4 +-
 .github/workflows/snap-diff-accept.yml        |  21 ++-
 CHANGELOG.md                                  |   8 +-
 docs/ci-integration.md                        |  33 +++--
 lib/snap_diff/reporters/html.rb               |  17 ++-
 .../reporters/templates/report.html.erb       |  42 +++++-
 test/integration/review_controls_test.rb      |  68 +++++++++-
 test/unit/accept_screenshots_test.rb          |  49 ++++++-
 test/unit/reporters/html_reporter_test.rb     |  40 +++++-
 11 files changed, 337 insertions(+), 83 deletions(-)

diff --git a/.github/actions/accept-screenshots/accept_screenshots.rb b/.github/actions/accept-screenshots/accept_screenshots.rb
index 1797d516..2a4a1178 100644
--- a/.github/actions/accept-screenshots/accept_screenshots.rb
+++ b/.github/actions/accept-screenshots/accept_screenshots.rb
@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
-# Accept screenshot baselines from a PR comment:
+# Accept screenshot baselines from a PR comment or a new issue (the report's
+# "Commit decisions" button opens one prefilled):
 #
-#   /snap-diff accept run=<run_id> <file>@<sha16> <file>@<sha16> ...
+#   /snap-diff accept run=<run_id> [pr=<n>] <file>@<sha16> <file>@<sha16> ...
 #   /snap-diff reject <file> ...            (optional, informational)
 #
+# or, rejecting only (nothing is committed; the list goes on the PR):
+#
+#   /snap-diff reject run=<run_id> [pr=<n>] <file> ...
+#
 # <file> is a `file` from the report's snap_diff_manifest.json; <sha16> is the
 # first 16 hex digits of the SHA-256 of its bytes, as the report showed them.
 # The bytes come from that run's `*-report-full` artifact and are committed to
@@ -17,15 +22,19 @@
 #   GH_TOKEN             token for gh and git (contents/pull-requests/actions)
 #   GITHUB_REPOSITORY    owner/name
 #   GITHUB_SERVER_URL    optional, default https://github.com
-#   COMMENT_BODY         the PR comment
-#   COMMENT_AUTHOR       commenter login
+#   EVENT_NAME           issue_comment (a PR comment) or issues (a new issue)
+#   ISSUE_NUMBER         the commented PR, or the new issue
+#   BODY                 the comment or issue body: the command
+#   AUTHOR               its author's login
 #   AUTHOR_ASSOCIATION   pre-filter: OWNER, MEMBER or COLLABORATOR
-#   PR_NUMBER            the pull request number
 #   SCREENSHOTS_PATH     optional, default doc/screenshots: every target must be under it
 #   CI_WORKFLOW          optional: workflow file to dispatch on the branch after the push
 #   RUNNER_TEMP          optional: scratch dir, default a fresh Dir.mktmpdir
 #
-# Every refusal is a reply comment on the PR plus exit status 1. Replies and
+# The PR is the commented one, or in an issue `pr=`, or else the single open
+# same-repository PR on the run's branch. Every refusal is a reply on the
+# comment's PR or the issue (then closed as not planned) plus exit status 1;
+# a done issue gets a link to the PR and is closed as completed. Replies and
 # logs carry only validated strings or fixed text, never raw input.
 
 require "json"
@@ -50,8 +59,8 @@ class Refusal < StandardError; end
   # No spaces: the command is whitespace-split, so a name with one cannot be written.
   SAFE_PATH = %r{\A[A-Za-z0-9._/-]+\z}
   LOGIN = /\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\z/
-  ACCEPT_LINE = %r{\A/snap-diff accept(?: |\z)}
-  ACCEPT = %r{\A/snap-diff accept run=(\d+)((?: +\S+)*)\z}
+  FIRST_LINE = %r{\A/snap-diff (?:accept|reject)(?: |\z)}
+  HEAD_LINE = %r{\A/snap-diff (accept|reject) run=(\d+)(?: pr=(\d+))?((?: +\S+)*)\z}
   REJECT = %r{\A/snap-diff reject((?: +\S+)*)\z}
   HASHED = /\A([^@]+)@([0-9a-f]{16})\z/
   MAGIC = {".png" => ["PNG", /\A\x89PNG\r\n\x1A\n/n], ".webp" => ["WebP", /\ARIFF....WEBP/mn]}.freeze
@@ -59,22 +68,29 @@ class Refusal < StandardError; end
 
   module_function
 
-  # {run:, accept: {file => sha16}, reject: [file]}
+  # {run:, pr: nil | digits, accept: {file => sha16}, reject: [file]}
   def parse(body)
     raise Refusal, "Comment too long (over #{MAX_BODY} characters)." if body.length > MAX_BODY
 
     lines = body.lines.map(&:strip).reject(&:empty?)
-    raise Refusal, "The first line must be `/snap-diff accept run=<run id> <file>@<hash> ...`." unless lines.first&.match?(ACCEPT_LINE)
+    unless lines.first&.match?(FIRST_LINE)
+      raise Refusal, "The first line must be `/snap-diff accept run=<run id> <file>@<hash> ...` or `/snap-diff reject run=<run id> <file> ...`."
+    end
 
-    accept = lines.first.match(ACCEPT) or raise Refusal, "Missing or invalid `run=<run id>` (digits only)."
-    reject = []
+    head = lines.first.match(HEAD_LINE) or raise Refusal, "Missing or invalid `run=<run id>` (digits only)."
+    kind, run, pr, rest = head.captures
+    tokens = rest.split.uniq
+    raise Refusal, "Invalid `pr=<number>` (digits only, right after `run=`)." if tokens.any? { |t| t.start_with?("pr=", "run=") }
+    raise Refusal, "The command needs at least one file." if tokens.empty?
+    raise Refusal, "Too many files (#{tokens.size}, max #{MAX_FILES})." if tokens.size > MAX_FILES
+
+    reject = (kind == "reject") ? tokens : []
     lines.drop(1).each do |line|
-      match = line.match(REJECT) or raise Refusal, "Unexpected line after the accept line; only `/snap-diff reject <file> ...` may follow."
+      match = (kind == "accept") && line.match(REJECT) or raise Refusal, "Unexpected line after the first line; only `/snap-diff reject <file> ...` may follow an accept line."
       reject.concat(match[1].split)
     end
-    tokens = accept[2].split.uniq
-    raise Refusal, "Accept needs at least one file." if tokens.empty?
-    raise Refusal, "Too many files (#{tokens.size}, max #{MAX_FILES})." if tokens.size > MAX_FILES
+    reject.each_with_index { |file, i| raise Refusal, "Rejected file ##{i + 1} is not allowed (#{ALLOWED_CHARS})." unless safe_path?(file) }
+    return {run: run, pr: pr, accept: {}, reject: reject.uniq} if kind == "reject"
 
     files = tokens.each_with_index.with_object({}) do |(token, i), acc|
       match = token.match(HASHED) or raise Refusal, "Accepted file ##{i + 1} lacks its @<hash> (16 lowercase hex); copy the command from the report again."
@@ -84,8 +100,23 @@ def parse(body)
 
       acc[file] = sha16
     end
-    reject.each_with_index { |file, i| raise Refusal, "Rejected file ##{i + 1} is not allowed (#{ALLOWED_CHARS})." unless safe_path?(file) }
-    {run: accept[1], accept: files, reject: reject.uniq}
+    {run: run, pr: pr, accept: files, reject: reject.uniq}
+  end
+
+  # A comment acts on the PR it is posted on; a `pr=` in it must agree.
+  def comment_pr(command, issue_number)
+    raise Refusal, "The command names PR ##{command[:pr]} but was posted on PR ##{issue_number}." if command[:pr] && command[:pr] != issue_number
+
+    issue_number
+  end
+
+  # An issue without `pr=`: the single open same-repository PR on the run's branch.
+  def resolve_pr(pulls, repo, head_branch)
+    matches = pulls.select { |p| p.dig("head", "repo", "full_name") == repo && p.dig("head", "ref") == head_branch }
+    raise Refusal, "No open pull request of this repository is on the run's branch." if matches.empty?
+    raise Refusal, "More than one open pull request is on the run's branch; add `pr=<number>`." if matches.size > 1
+
+    matches.first["number"].to_s
   end
 
   # Relative, no empty / `.` / `..` segments, conservative characters.
@@ -229,6 +260,10 @@ def summary(command, targets, sha, ci_line)
     lines.join("\n")
   end
 
+  def reject_summary(command)
+    (["Rejected in run #{command[:run]} (not committed):"] + command[:reject].map { |file| "- `#{file}`" }).join("\n")
+  end
+
   def commit_message(targets, run_id, login, pr)
     bullets = targets.map { |file, path| "- #{file} -> #{path}" }.join("\n")
     "Accept screenshot baselines\n\nAccepted by @#{login} in PR ##{pr} from run #{run_id}:\n#{bullets}\n"
@@ -261,8 +296,12 @@ def sh!(*cmd, **opts)
 
   def gh_json(path) = JSON.parse(sh!("gh", "api", path))
 
-  def reply(repo, pr, text)
-    sh!("gh", "api", "-X", "POST", "repos/#{repo}/issues/#{pr}/comments", "--input", "-", stdin: JSON.generate(body: text))
+  def reply(repo, number, text)
+    sh!("gh", "api", "-X", "POST", "repos/#{repo}/issues/#{number}/comments", "--input", "-", stdin: JSON.generate(body: text))
+  end
+
+  def close_issue(repo, number, reason)
+    sh!("gh", "api", "-X", "PATCH", "repos/#{repo}/issues/#{number}", "--input", "-", stdin: JSON.generate(state: "closed", state_reason: reason))
   end
 
   # A fresh, isolated git: no global or system config, no hooks, no LFS
@@ -284,25 +323,27 @@ def git_env(auth = nil)
 
   def run!
     repo = env("GITHUB_REPOSITORY")
-    pr = env("PR_NUMBER")
-    raise "PR_NUMBER is not a number" unless pr.match?(/\A\d+\z/)
+    issue = env("ISSUE_NUMBER")
+    raise "ISSUE_NUMBER is not a number" unless issue.match?(/\A\d+\z/)
+    issue_mode = {"issues" => true, "issue_comment" => false}.fetch(env("EVENT_NAME"))
 
-    exit 1 unless accept!(repo, pr)
+    exit 1 unless accept!(repo, issue, issue_mode)
   rescue Refusal => e
     log(e.message)
-    reply(repo, pr, "Screenshot accept refused: #{e.message}")
+    reply(repo, issue, "Screenshot accept refused: #{e.message}")
+    close_issue(repo, issue, "not_planned") if issue_mode
     exit 1
   rescue => e
     log("#{e.class}: #{e.message}")
-    reply(repo, pr, "Screenshot accept failed; see the workflow log.") if repo && pr
+    reply(repo, issue, "Screenshot accept failed; see the workflow log.") if repo && issue
     exit 1
   end
 
   # True unless the commit landed but the CI dispatch failed.
-  def accept!(repo, pr)
+  def accept!(repo, issue, issue_mode)
     raise Refusal, "Only owners, members and collaborators can accept screenshots." unless ALLOWED_ASSOCIATIONS.include?(env("AUTHOR_ASSOCIATION"))
 
-    login = env("COMMENT_AUTHOR")
+    login = env("AUTHOR")
     raise Refusal, "Only people with write access can accept screenshots." unless login.match?(LOGIN)
     # MEMBER/COLLABORATOR includes read-only people; the permission API does not.
     raise Refusal, "Only people with write access can accept screenshots." unless writer?(gh_json("repos/#{repo}/collaborators/#{login}/permission"))
@@ -312,15 +353,26 @@ def accept!(repo, pr)
     workflow = ENV["CI_WORKFLOW"].to_s
     raise "CI_WORKFLOW must be a workflow file name" unless workflow.empty? || workflow.match?(/\A[\w.-]+\.ya?ml\z/)
 
-    command = parse(env("COMMENT_BODY"))
+    command = parse(env("BODY"))
     run_id = command[:run]
     files = command[:accept].keys
 
     run = gh_json("repos/#{repo}/actions/runs/#{run_id}")
+    pr = if !issue_mode then comment_pr(command, issue)
+    elsif command[:pr] then command[:pr]
+    else
+      raise Refusal, "Run #{run_id} has no branch; add `pr=<number>`." unless run["head_branch"].is_a?(String)
+
+      pulls = sh!("gh", "api", "-X", "GET", "repos/#{repo}/pulls", "-f", "state=open", "-f", "per_page=100",
+        "-f", "head=#{repo.split("/").first}:#{run["head_branch"]}")
+      resolve_pr(JSON.parse(pulls), repo, run["head_branch"])
+    end
     pull = gh_json("repos/#{repo}/pulls/#{pr}")
     branch = pull.dig("head", "ref")
     check_run!(run, repo, pr, run_id, branch)
     raise Refusal, "The pull request is not open." unless pull["state"] == "open"
+    return finish(repo, issue, issue_mode, pr, reject_summary(command), "Recorded on PR ##{pr}.") if files.empty?
+
     raise Refusal, "The pull request comes from a fork." unless pull.dig("head", "repo", "full_name") == repo
     raise Refusal, "PR has new commits since run #{run_id} — review the new report." unless pull.dig("head", "sha") == run["head_sha"]
     raise "unexpected head_sha" unless run["head_sha"].to_s.match?(/\A\h{40}\z/)
@@ -347,7 +399,7 @@ def accept!(repo, pr)
       message: commit_message(targets, run_id, login, pr), git_env: git_env(auth))
 
     ci_line = workflow.empty? ? "Re-run CI to verify." : "Dispatching `#{workflow}` on the PR branch to verify."
-    reply(repo, pr, summary(command, targets, sha, ci_line))
+    finish(repo, issue, issue_mode, pr, summary(command, targets, sha, ci_line), "Applied to PR ##{pr}: #{sha || "nothing to commit"}.")
     puts "accepted #{targets.size} file(s): #{sha || "no change"}"
     return true unless sha && !workflow.empty?
 
@@ -356,6 +408,16 @@ def accept!(repo, pr)
     FileUtils.rm_rf(work) if work # nothing of this run outlives it on a persistent runner
   end
 
+  # The outcome goes on the PR; an issue also gets a link to it and is closed.
+  def finish(repo, issue, issue_mode, pr, pr_text, issue_text)
+    reply(repo, pr, pr_text)
+    return true unless issue_mode
+
+    reply(repo, issue, issue_text)
+    close_issue(repo, issue, "completed")
+    true
+  end
+
   # Best effort, after the reply: a failure must not hide the pushed commit.
   # A push made with GITHUB_TOKEN does not start workflows; a
   # workflow_dispatch made with it does.
diff --git a/.github/actions/accept-screenshots/action.yml b/.github/actions/accept-screenshots/action.yml
index 2f5a7128..56e4f429 100644
--- a/.github/actions/accept-screenshots/action.yml
+++ b/.github/actions/accept-screenshots/action.yml
@@ -1,12 +1,12 @@
 ---
 name: 'Accept SnapDiff screenshots'
 description: >-
-  Commit screenshot baselines accepted in a PR comment
-  (`/snap-diff accept run=<run id> <file> ...`) from that run's report artifact.
-  Run it from an issue_comment workflow gated to OWNER/MEMBER/COLLABORATOR.
+  Commit screenshot baselines accepted in a PR comment or a new issue
+  (`/snap-diff accept run=<run id> [pr=<n>] <file>@<hash> ...`) from that run's report artifact.
+  Run it from an issue_comment + issues workflow gated to OWNER/MEMBER/COLLABORATOR.
 inputs:
   token:
-    description: 'Token with contents: write, pull-requests: write, actions: read (actions: write to dispatch ci-workflow); reads the commenter''s permission'
+    description: 'Token with contents: write, pull-requests: write, issues: write, actions: read (actions: write to dispatch ci-workflow); reads the author''s permission'
     default: ${{ github.token }}
   screenshots-path:
     description: 'Every accepted file must be committed under this directory (relative to the repository root)'
@@ -25,8 +25,10 @@ runs:
         GH_TOKEN: ${{ inputs.token }}
         CI_WORKFLOW: ${{ inputs.ci-workflow }}
         SCREENSHOTS_PATH: ${{ inputs.screenshots-path }}
-        COMMENT_BODY: ${{ github.event.comment.body }}
-        COMMENT_AUTHOR: ${{ github.event.comment.user.login }}
-        AUTHOR_ASSOCIATION: ${{ github.event.comment.author_association }}
-        PR_NUMBER: ${{ github.event.issue.number }}
+        EVENT_NAME: ${{ github.event_name }}
+        ISSUE_NUMBER: ${{ github.event.issue.number }}
+        # issue_comment: the comment on the PR; issues: the new issue itself.
+        BODY: ${{ github.event_name == 'issues' && github.event.issue.body || github.event.comment.body }}
+        AUTHOR: ${{ github.event_name == 'issues' && github.event.issue.user.login || github.event.comment.user.login }}
+        AUTHOR_ASSOCIATION: ${{ github.event_name == 'issues' && github.event.issue.author_association || github.event.comment.author_association }}
       run: ruby "$GITHUB_ACTION_PATH/accept_screenshots.rb"
diff --git a/.github/actions/upload-screenshots/action.yml b/.github/actions/upload-screenshots/action.yml
index cb3e0641..6e32323f 100644
--- a/.github/actions/upload-screenshots/action.yml
+++ b/.github/actions/upload-screenshots/action.yml
@@ -90,7 +90,7 @@ runs:
         | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
         EOF
         if [ "$HEAD_REPO" = "$REPO" ]; then
-          printf '\nTo accept: open the HTML report, mark screenshots Accept/Reject, Copy review command, and paste it as a comment on the pull request.\n' >> "$GITHUB_STEP_SUMMARY"
+          printf '\nTo accept: open the HTML report, mark Accept/Reject, then Commit decisions.\n' >> "$GITHUB_STEP_SUMMARY"
         fi
 
     - name: Find existing PR comment
@@ -118,4 +118,4 @@ runs:
           | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
           | [All artifacts](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}#artifacts) | Browse all |
 
-          ${{ steps.check-report.outputs.exists == 'true' && github.event.pull_request.head.repo.full_name == github.repository && 'To accept: open the HTML report, mark screenshots Accept/Reject, Copy review command, and paste it as a comment here.' || '' }}
+          ${{ steps.check-report.outputs.exists == 'true' && github.event.pull_request.head.repo.full_name == github.repository && 'To accept: open the HTML report, mark Accept/Reject, then Commit decisions.' || '' }}
diff --git a/.github/workflows/snap-diff-accept.yml b/.github/workflows/snap-diff-accept.yml
index 1e1e96d4..d368d5ba 100644
--- a/.github/workflows/snap-diff-accept.yml
+++ b/.github/workflows/snap-diff-accept.yml
@@ -1,31 +1,40 @@
 ---
 name: Accept screenshots
 
-# A maintainer pastes the report's review command as a PR comment:
-#   /snap-diff accept run=<run id> <file> ...
+# The report's "Commit decisions" button opens a new issue whose body is the
+# review command (or a maintainer pastes it as a PR comment):
+#   /snap-diff accept run=<run id> [pr=<n>] <file>@<hash> ...
 # The action commits those files from that run's report artifact to the PR branch.
 
 on:
   issue_comment:
     types: [ created ]
+  issues:
+    types: [ opened ]
 
 jobs:
   accept:
     if: >-
-      github.event.issue.pull_request &&
-      startsWith(github.event.comment.body, '/snap-diff accept') &&
-      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request &&
+       startsWith(github.event.comment.body, '/snap-diff ') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
+      (github.event_name == 'issues' &&
+       startsWith(github.event.issue.body, '/snap-diff ') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.issue.author_association))
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
       contents: write
       pull-requests: write
+      issues: write
       actions: write
+    # Per PR for comments, per issue for issues (the PR is not known yet);
+    # two issues for one PR may run at once, and the push lease lets only one land.
     concurrency:
       group: snap-diff-accept-${{ github.event.issue.number }}
       cancel-in-progress: false
     steps:
-      # The default branch (issue_comment's ref): this repository's trusted
+      # The default branch (the ref of both events): this repository's trusted
       # code, needed for the local action. The PR's code is never checked out here.
       - uses: actions/checkout@v7
         with:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b9536e11..fb9437cd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,10 +20,10 @@ kept as history. This entry is the one to read if you are coming from **1.15.1**
 
 ### Added
 
-- **Accept screenshots from a pull request comment.** On GitHub Actions, the HTML report gets
-  Accept/Reject buttons and a "Copy review command" button. Pasting the command as a PR comment runs
-  the new `accept-screenshots` action, which commits the exact CI pixels to the PR branch with the
-  repository's `GITHUB_TOKEN`. The report also writes `snap_diff_manifest.json`, and
+- **Accept screenshots from the CI report.** On GitHub Actions, the HTML report gets Accept/Reject
+  buttons and a "Commit decisions" button that opens a prefilled GitHub issue. Submitting it (or pasting
+  the copied command as a PR comment) runs the new `accept-screenshots` action, which commits the exact
+  CI pixels to the PR branch with the repository's `GITHUB_TOKEN`. The report also writes `snap_diff_manifest.json`, and
   `upload-screenshots` adds a how-to-accept line to its PR comment and job summary. See
   [CI integration](docs/ci-integration.md#accept-screenshots-from-the-pull-request).
 
diff --git a/docs/ci-integration.md b/docs/ci-integration.md
index 80338ccb..25f815df 100644
--- a/docs/ci-integration.md
+++ b/docs/ci-integration.md
@@ -287,11 +287,14 @@ Two things this minimal recipe does not do:
 
 When a CI run fails on screenshot diffs, a reviewer can accept the new pixels without checking out the
 branch. In the HTML report (the inline link in the PR comment), each changed or new screenshot has
-Accept and Reject buttons (keys `Y` and `N`). The "Copy review command" button copies a line like
-`/snap-diff accept run=123 linux/cuprite/index.png@0123456789abcdef`. Pasting it as a PR comment starts
-a workflow that commits those exact files from that run's report artifact to the PR branch with the
-repository's own `GITHUB_TOKEN`, replies with the commit, and re-runs CI. The buttons appear only in
-reports built on GitHub Actions.
+Accept and Reject buttons (keys `Y` and `N`). "Commit decisions" opens a new GitHub issue already
+filled in with a command like `/snap-diff accept run=123 pr=45 linux/cuprite/index.png@0123456789abcdef`.
+Click Submit. A workflow commits those exact files from that run's report artifact to the PR branch
+with the repository's own `GITHUB_TOKEN`, posts the result on the PR, closes the issue and re-runs CI.
+The buttons appear only in reports built on GitHub Actions.
+
+If the link would be too long for GitHub, the button is disabled. Use "Copy review command" and paste
+the command as a comment on the pull request instead; it does the same thing.
 
 To install it, copy this workflow. Set `screenshots-path` to your `save_path`. `ci-workflow` is
 optional: it names your test workflow, which needs an `on: workflow_dispatch` trigger. Without it the
@@ -304,18 +307,24 @@ name: Accept screenshots
 on:
   issue_comment:
     types: [created]
+  issues:
+    types: [opened]
 
 jobs:
   accept:
     if: >-
-      github.event.issue.pull_request &&
-      startsWith(github.event.comment.body, '/snap-diff accept') &&
-      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request &&
+       startsWith(github.event.comment.body, '/snap-diff ') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
+      (github.event_name == 'issues' &&
+       startsWith(github.event.issue.body, '/snap-diff ') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.issue.author_association))
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
       contents: write
       pull-requests: write
+      issues: write
       actions: write   # read is enough if you leave out ci-workflow
     concurrency:
       group: snap-diff-accept-${{ github.event.issue.number }}
@@ -327,11 +336,11 @@ jobs:
           ci-workflow: test.yml
 ```
 
-`issue_comment` workflows run only from the default branch, so merge this file first. Until then the
-comment does nothing.
+`issue_comment` and `issues` workflows run only from the default branch, so merge this file first.
+Until then the issue or comment does nothing.
 
-Commenters need write access to the repository. The workflow checks the permission API as well as the
-comment's `author_association`, so read-only collaborators are refused.
+Reviewers need write access to the repository. The workflow checks the permission API as well as the
+`author_association`, so read-only collaborators are refused, and their issue is closed with the reason.
 
 Limits:
 
diff --git a/lib/snap_diff/reporters/html.rb b/lib/snap_diff/reporters/html.rb
index ab0fef79..0e0d9bc4 100644
--- a/lib/snap_diff/reporters/html.rb
+++ b/lib/snap_diff/reporters/html.rb
@@ -131,14 +131,25 @@ def render
         ERB.new(File.read(self.class.template_path)).result(binding)
       end
 
-      # Review controls (Accept/Reject, the PR comment command) exist only in
-      # a CI run, where the run id names the artifact the bot reads.
+      # Review controls (Accept/Reject, the review command) exist only in a
+      # CI run, where the run id names the artifact the bot reads. A
+      # pull_request run's merge ref names the PR; the repository gives the
+      # new-issue page that "Commit decisions" opens.
       def review
         run = ENV["GITHUB_RUN_ID"].to_s
         return if run.empty?
 
         files = manifest_entries.map { |entry| entry[:accept]["file"] }
-        {run: run, files: files, sha16: files.to_h { |file| [file, file_sha256(file)[0, 16]] }}
+        {run: run, pr: ENV["GITHUB_REF"].to_s[%r{\Arefs/pull/(\d+)/merge\z}, 1], issue_url: new_issue_url,
+         files: files, sha16: files.to_h { |file| [file, file_sha256(file)[0, 16]] }}
+      end
+
+      def new_issue_url
+        repo = ENV["GITHUB_REPOSITORY"].to_s
+        server = ENV.fetch("GITHUB_SERVER_URL", "https://github.com").to_s
+        return unless repo.match?(%r{\A[\w.-]+/[\w.-]+\z}) && server.match?(%r{\Ahttps://[\w.-]+(?::\d+)?\z})
+
+        "#{server}/#{repo}/issues/new"
       end
 
       # The entries the page shows. In a CI run the manifest's entry for a
diff --git a/lib/snap_diff/reporters/templates/report.html.erb b/lib/snap_diff/reporters/templates/report.html.erb
index 117a24b8..0770f9a0 100644
--- a/lib/snap_diff/reporters/templates/report.html.erb
+++ b/lib/snap_diff/reporters/templates/report.html.erb
@@ -161,7 +161,9 @@
     .review-btn.reject.active { background: var(--red-dim); color: var(--red); border-color: var(--red); }
     #review-panel { display: flex; align-items: flex-start; gap: .5rem; padding: .375rem .75rem; background: var(--bg2); border-top: 1px solid var(--border); flex-shrink: 0; }
     #review-side { display: flex; flex-direction: column; gap: .25rem; align-items: flex-start; }
-    #review-count, #review-hint, #review-note { font-size: .625rem; color: var(--text2); }
+    #review-count, #review-hint, #review-note, #review-commit-note { font-size: .625rem; color: var(--text2); }
+    .review-btn.primary { background: var(--green-dim); color: var(--green); border-color: var(--green); }
+    .review-btn:disabled { opacity: .5; cursor: not-allowed; }
     #review-command { flex: 1; min-width: 0; height: 2.75rem; resize: none; font-family: var(--font-mono); font-size: .625rem; background: var(--surface); color: var(--text); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: .25rem .4rem; }
 <% end %>
 
@@ -256,8 +258,10 @@
     <div id="review-panel">
       <div id="review-side">
         <span id="review-count"></span>
+        <button class="review-btn primary" id="review-commit" disabled>Commit decisions</button>
+        <span id="review-hint">Opens a GitHub issue with your decisions; submit it to commit.</span>
+        <span id="review-commit-note" hidden></span>
         <button class="review-btn" id="review-copy">Copy review command</button>
-        <span id="review-hint">Paste this as a comment on the pull request.</span>
       </div>
       <textarea id="review-command" readonly aria-label="Review command"></textarea>
     </div>
@@ -489,9 +493,10 @@
   }
 
 <% if review %>
-  /* ── Review (CI runs): build the PR comment command ───────────────────
-     Decisions are keyed by manifest file, so entries sharing a file share
-     the decision. */
+  /* ── Review (CI runs): build the review command ──────────────────────
+     Decisions are keyed by manifest file. "Commit decisions" opens a new
+     GitHub issue prefilled with the command; the bot acts on it once the
+     reviewer submits it. The command field and Copy stay as the fallback. */
   var decisions = {};
   var reviewAccept = $('review-accept'), reviewReject = $('review-reject');
   var reviewCommand = $('review-command'), reviewCount = $('review-count');
@@ -500,11 +505,23 @@
     var accepted = REVIEW.files.filter(function(f) { return decisions[f] === 'accept'; });
     var rejected = REVIEW.files.filter(function(f) { return decisions[f] === 'reject'; });
     var lines = [];
+    var head = 'run=' + REVIEW.run + (REVIEW.pr ? ' pr=' + REVIEW.pr : '');
     var hashed = accepted.map(function(f) { return f + '@' + REVIEW.sha16[f]; });
-    if (accepted.length) lines.push('/snap-diff accept run=' + REVIEW.run + ' ' + hashed.join(' '));
-    if (rejected.length) lines.push('/snap-diff reject ' + rejected.join(' '));
+    if (accepted.length) {
+      lines.push('/snap-diff accept ' + head + ' ' + hashed.join(' '));
+      if (rejected.length) lines.push('/snap-diff reject ' + rejected.join(' '));
+    } else if (rejected.length) {
+      lines.push('/snap-diff reject ' + head + ' ' + rejected.join(' '));
+    }
     return { text: lines.join('\n'), accepted: accepted.length, rejected: rejected.length };
   }
+  /* GitHub refuses very long URLs; past this the copy fallback is the way. */
+  var MAX_URL = 7000;
+  function issueUrl(text) {
+    if (!REVIEW.issue_url || !text) return '';
+    var title = 'snap-diff review: ' + (REVIEW.pr ? 'PR #' + REVIEW.pr + ' ' : '') + '(run ' + REVIEW.run + ')';
+    return REVIEW.issue_url + '?title=' + encodeURIComponent(title) + '&body=' + encodeURIComponent(text);
+  }
   /* An entry without controls says why: an earlier capture of a file whose
      last capture is the one on disk, or no final capture at all. */
   var REASONS = {
@@ -535,7 +552,18 @@
     var r = reviewText();
     reviewCount.textContent = r.accepted + ' accepted \u00b7 ' + r.rejected + ' rejected';
     reviewCommand.value = r.text;
+    var url = issueUrl(r.text);
+    var why = !r.text ? '' : !REVIEW.issue_url ? 'No repository known for this run: copy the command and paste it as a PR comment.'
+      : url.length > MAX_URL ? 'Too many files for one link: copy the command and paste it as a PR comment.' : '';
+    reviewCommit.disabled = !url || !!why;
+    reviewCommitNote.textContent = why;
+    reviewCommitNote.hidden = !why;
   }
+  var reviewCommit = $('review-commit'), reviewCommitNote = $('review-commit-note');
+  reviewCommit.addEventListener('click', function() {
+    var url = issueUrl(reviewCommand.value);
+    if (url && url.length <= MAX_URL) window.open(url, '_blank', 'noopener');
+  });
   function decide(choice) {
     var file = DATA[state.current] && DATA[state.current].file;
     if (!file) return;
diff --git a/test/integration/review_controls_test.rb b/test/integration/review_controls_test.rb
index 31cdfc57..02669973 100644
--- a/test/integration/review_controls_test.rb
+++ b/test/integration/review_controls_test.rb
@@ -7,19 +7,22 @@
 # The report's review controls, driven in a real browser: a reviewer clicks
 # Accept and Reject and the read-only field shows the PR comment command.
 class ReviewControlsTest < ActiveSupport::TestCase
+  # Pinned: CI sets these for real. No GITHUB_REF unless a test sets one.
+  CI_ENV = {"GITHUB_RUN_ID" => "99", "GITHUB_REF" => nil, "GITHUB_REPOSITORY" => "o/r", "GITHUB_SERVER_URL" => "https://github.com"}.freeze
+
   setup do
     @dir = Pathname.new(Dir.mktmpdir).realpath
     system("git", "-C", @dir.to_s, "init", "-q", exception: true)
     @original_root = SnapDiff.config.root
     SnapDiff.config.root = @dir
-    @original_run_id = ENV["GITHUB_RUN_ID"]
-    ENV["GITHUB_RUN_ID"] = "99"
+    @original_env = CI_ENV.keys.to_h { |k| [k, ENV[k]] }
+    CI_ENV.each { |k, v| ENV[k] = v }
     @session = Capybara::Session.new(Capybara.javascript_driver)
   end
 
   teardown do
     @session.quit
-    ENV["GITHUB_RUN_ID"] = @original_run_id
+    @original_env.each { |k, v| ENV[k] = v }
     SnapDiff.config.root = @original_root
     FileUtils.remove_entry(@dir)
   end
@@ -73,6 +76,56 @@ class ReviewControlsTest < ActiveSupport::TestCase
     assert_equal "", command
   end
 
+  test "Commit decisions opens the prefilled new-issue page in a new tab" do
+    ENV["GITHUB_REF"] = "refs/pull/313/merge"
+    visit_with_window_open_spy(write_report(%w[one two three]))
+    assert @session.has_button?("Commit decisions", disabled: true), "nothing to commit yet"
+
+    @session.find("body").send_keys("y", :right, "n", :right, "y")
+    @session.click_button "Commit decisions"
+
+    url, target, features = opened
+    assert_equal ["_blank", "noopener"], [target, features]
+    assert_equal "https://github.com/o/r/issues/new", url[/\A[^?]*/]
+    assert_equal({"title" => "snap-diff review: PR #313 (run 99)",
+                  "body" => "/snap-diff accept run=99 pr=313 screenshots/one.png@#{sha16} screenshots/three.png@#{sha16}\n" \
+                            "/snap-diff reject screenshots/two.png"}, query(url))
+    assert @session.has_css?("#review-hint", text: "Opens a GitHub issue with your decisions; submit it to commit.")
+  end
+
+  test "a reject-only review names the run and PR on its reject line" do
+    ENV["GITHUB_REF"] = "refs/pull/313/merge"
+    visit_with_window_open_spy(write_report(%w[one two]))
+
+    @session.find("body").send_keys("n")
+    @session.click_button "Commit decisions"
+
+    assert_equal "/snap-diff reject run=99 pr=313 screenshots/one.png", query(opened.first)["body"]
+    assert_equal "/snap-diff reject run=99 pr=313 screenshots/one.png", command
+  end
+
+  test "without a PR in the run the command and title leave it out" do
+    ENV["GITHUB_REF"] = "refs/heads/main"
+    visit_with_window_open_spy(write_report(%w[one]))
+
+    @session.find("body").send_keys("y")
+    @session.click_button "Commit decisions"
+
+    assert_equal({"title" => "snap-diff review: (run 99)", "body" => "/snap-diff accept run=99 screenshots/one.png@#{sha16}"}, query(opened.first))
+  end
+
+  test "a link too long for GitHub leaves only the copy fallback" do
+    names = (1..40).map { |i| "#{"long" * 45}#{i}" } # ~190-char names: 40 accepts pass 7000 chars
+    visit_with_window_open_spy(write_report(names))
+
+    @session.find("body").send_keys(*names.flat_map { ["y", :right] })
+
+    assert @session.has_button?("Commit decisions", disabled: true)
+    assert @session.has_css?("#review-commit-note", text: "Too many files for one link: copy the command and paste it as a PR comment.")
+    assert_equal 40, command.scan("@#{sha16}").size, "the command itself is complete"
+    assert @session.has_button?("Copy review command")
+  end
+
   test "a local report has no review controls" do
     ENV["GITHUB_RUN_ID"] = nil
     @session.visit "file://#{write_report(%w[one])}"
@@ -86,6 +139,15 @@ class ReviewControlsTest < ActiveSupport::TestCase
 
   def command = @session.find("#review-command").value
 
+  def visit_with_window_open_spy(report)
+    @session.visit "file://#{report}"
+    @session.execute_script("window.open = function(u, t, f) { window.__opened = [u, t, f]; return null; }")
+  end
+
+  def opened = @session.evaluate_script("window.__opened")
+
+  def query(url) = URI.decode_www_form(URI(url).query).to_h
+
   # aria-pressed of [Accept, Reject], which must follow the visual state.
   def pressed = %w[#review-accept #review-reject].map { |id| @session.find(id)["aria-pressed"] }
 
diff --git a/test/unit/accept_screenshots_test.rb b/test/unit/accept_screenshots_test.rb
index a42a8c5b..ff3f49f3 100644
--- a/test/unit/accept_screenshots_test.rb
+++ b/test/unit/accept_screenshots_test.rb
@@ -23,11 +23,28 @@ def assert_not_echoed(text)
   def test_parse_accept_and_reject
     body = "/snap-diff accept run=123 linux/a.png@0123abcd0123abcd linux/b.webp@ffffffffffffffff\r\n/snap-diff reject linux/c.png\n"
 
-    assert_equal({run: "123", accept: {"linux/a.png" => "0123abcd0123abcd", "linux/b.webp" => "ffffffffffffffff"}, reject: %w[linux/c.png]}, A.parse(body))
+    assert_equal({run: "123", pr: nil, accept: {"linux/a.png" => "0123abcd0123abcd", "linux/b.webp" => "ffffffffffffffff"}, reject: %w[linux/c.png]}, A.parse(body))
   end
 
   def test_parse_without_reject_line
-    assert_equal({run: "7", accept: {"a.png" => "0123abcd0123abcd"}, reject: []}, A.parse("/snap-diff accept run=7 a.png@0123abcd0123abcd"))
+    assert_equal({run: "7", pr: nil, accept: {"a.png" => "0123abcd0123abcd"}, reject: []}, A.parse("/snap-diff accept run=7 a.png@0123abcd0123abcd"))
+  end
+
+  def test_parse_pr
+    assert_equal({run: "7", pr: "12", accept: {"a.png" => "0123abcd0123abcd"}, reject: %w[b.png]},
+      A.parse("/snap-diff accept run=7 pr=12 a.png@0123abcd0123abcd\n/snap-diff reject b.png"))
+    assert_match(/pr=/, refusal { A.parse("/snap-diff accept run=7 pr=x a.png@0123abcd0123abcd") })
+  end
+
+  def test_parse_reject_only
+    assert_equal({run: "7", pr: "12", accept: {}, reject: %w[a.png b.png]}, A.parse("/snap-diff reject run=7 pr=12 a.png b.png"))
+    assert_equal({run: "7", pr: nil, accept: {}, reject: %w[a.png]}, A.parse("/snap-diff reject run=7 a.png"))
+  end
+
+  def test_parse_refuses_reject_only_without_run_or_files
+    assert_match(/run=/, refusal { A.parse("/snap-diff reject a.png") })
+    assert_match(/at least one file/, refusal { A.parse("/snap-diff reject run=7") })
+    assert_match(/unexpected line/i, refusal { A.parse("/snap-diff reject run=7 a.png\n/snap-diff reject b.png") })
   end
 
   def test_parse_drops_duplicate_files
@@ -304,8 +321,36 @@ def test_check_run_refuses_push_run_of_another_branch_same_sha
     assert_match(/not a run of this pull request/, refusal { A.check_run!(run, "o/r", "5", "9", "feat") })
   end
 
+  # -- which pull request ------------------------------------------------------
+
+  def pull(number, repo: "o/r", ref: "feat") = {"number" => number, "head" => {"ref" => ref, "repo" => {"full_name" => repo}}}
+
+  def test_resolve_pr_takes_the_single_open_same_repo_pr_on_the_branch
+    pulls = [pull(3), pull(4, repo: "fork/r"), pull(5, ref: "other")]
+
+    assert_equal "3", A.resolve_pr(pulls, "o/r", "feat")
+  end
+
+  def test_resolve_pr_refuses_none_or_several
+    assert_match(/No open pull request/, refusal { A.resolve_pr([pull(4, repo: "fork/r")], "o/r", "feat") })
+    assert_match(/More than one/, refusal { A.resolve_pr([pull(3), pull(6)], "o/r", "feat") })
+  end
+
+  def test_comment_pr_is_the_commented_pr
+    assert_equal "5", A.comment_pr({pr: nil}, "5")
+    assert_equal "5", A.comment_pr({pr: "5"}, "5")
+    assert_match(/names PR #6 but was posted on PR #5/, refusal { A.comment_pr({pr: "6"}, "5") })
+  end
+
   # -- text that reaches replies and logs -------------------------------------
 
+  def test_reject_summary
+    text = A.reject_summary({run: "7", accept: {}, reject: %w[a.png b.png]})
+
+    assert_includes text, "run 7"
+    assert_includes text, "- `a.png`\n- `b.png`"
+  end
+
   def test_lfs_paths
     out = "a/x.png: filter: lfs\nc.png: filter: unspecified\nd.webp: filter: other\n"
 
diff --git a/test/unit/reporters/html_reporter_test.rb b/test/unit/reporters/html_reporter_test.rb
index 1645a76e..9e1ea8cf 100644
--- a/test/unit/reporters/html_reporter_test.rb
+++ b/test/unit/reporters/html_reporter_test.rb
@@ -647,7 +647,7 @@ def synchronize
     assert_includes html, "Copy review command"
     # The hash binds the command to the bytes the artifact holds: the file on disk, the last capture.
     assert_equal Digest::SHA256.file(report_dir / file).hexdigest, entry.fetch("sha256")
-    assert_equal({"run" => "4242", "files" => [file], "sha16" => {file => entry["sha256"][0, 16]}}, report_review(report_dir / "report.html"))
+    assert_equal({"run" => "4242", "pr" => nil, "issue_url" => nil, "files" => [file], "sha16" => {file => entry["sha256"][0, 16]}}, report_review(report_dir / "report.html"))
     # Only the last capture of a file is on disk and in the manifest: the
     # earlier entry points at it instead of offering its own controls.
     data = report_data(report_dir / "report.html")
@@ -685,6 +685,30 @@ def synchronize
     assert_equal 3, manifest.fetch("entries").size
   end
 
+  # The "Commit decisions" button opens <server>/<repo>/issues/new; the PR
+  # number comes from a pull_request run's merge ref.
+  test "in a pull_request run the review data names the PR and the new-issue page" do
+    reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+    reporter.record([build_failing_assertion("index")])
+    with_run_id("7", ref: "refs/pull/313/merge", repo: "o/r", server: "https://ghe.example.com") { reporter.finalize }
+
+    assert_equal({"pr" => "313", "issue_url" => "https://ghe.example.com/o/r/issues/new"}, report_review.slice("pr", "issue_url"))
+  end
+
+  test "outside a pull_request run, or without a usable repository, those are left out" do
+    {
+      {ref: "refs/heads/main", repo: "o/r"} => {"pr" => nil, "issue_url" => "https://github.com/o/r/issues/new"},
+      {ref: "refs/pull/313/head", repo: "o/r\"><x"} => {"pr" => nil, "issue_url" => nil},
+      {ref: "refs/pull/313/merge", repo: "o/r", server: "javascript:alert(1)//"} => {"pr" => "313", "issue_url" => nil}
+    }.each do |env, expected|
+      reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
+      reporter.record([build_failing_assertion("index")])
+      with_run_id("7", **env) { reporter.finalize }
+
+      assert_equal expected, report_review.slice("pr", "issue_url"), env.inspect
+    end
+  end
+
   test "outside a CI run the report has no review controls" do
     reporter = SnapDiff::Reporters::HTML.new(output_path: @output_path)
     reporter.record([build_failing_assertion("index")])
@@ -704,22 +728,24 @@ def synchronize
     with_run_id("7") { reporter.finalize }
 
     path = @output_dir / "report/report.html"
-    assert_equal({"run" => "7", "files" => [], "sha16" => {}}, report_review(path))
+    assert_equal({"run" => "7", "pr" => nil, "issue_url" => nil, "files" => [], "sha16" => {}}, report_review(path))
     assert_equal [nil, nil], report_data(path).map { |e| e["file"] }
     assert_equal %w[rerecorded no_capture], report_data(path).map { |e| e["review_reason"] }
   end
 
   private
 
-  def with_run_id(id)
-    original = ENV["GITHUB_RUN_ID"]
-    ENV["GITHUB_RUN_ID"] = id
+  # The review controls read these; pin all of them, since CI sets them too.
+  def with_run_id(id, ref: nil, repo: nil, server: nil)
+    vars = {"GITHUB_RUN_ID" => id, "GITHUB_REF" => ref, "GITHUB_REPOSITORY" => repo, "GITHUB_SERVER_URL" => server}
+    original = vars.keys.to_h { |k| [k, ENV[k]] }
+    vars.each { |k, v| ENV[k] = v }
     yield
   ensure
-    ENV["GITHUB_RUN_ID"] = original
+    original.each { |k, v| ENV[k] = v }
   end
 
-  def report_review(path)
+  def report_review(path = @output_path)
     JSON.parse(path.read[/^\s*var REVIEW = (.*);$/, 1])
   end