From 3b9c8f1c501efea919e116b3e9f69d2d313d66e1 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Mon, 10 Aug 2026 04:48:27 +0000
Subject: [PATCH] docs(runner): name the pinned Chromium when Phase 7G shots
 drift

The 24 committed Phase 7G PNGs are pinned to one Chromium build, so running
check:phase7:ui against Playwright's bundled browser mismatches all 24 at once
and reads like a UI regression. The drift report now prints the Chromium version
it recorded with and points at PAPERCLIP_RUNNER_CHROMIUM_PATH, and the UI doc
states that the check needs the recording browser rather than framing that
variable as a missing-system-libraries workaround.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 .../docs/phase-07-issue-thread-ui.md            |  6 ++++++
 .../scripts/record-phase7-ui-evidence.mjs       | 17 ++++++++++++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/packages/paperclip-runner/docs/phase-07-issue-thread-ui.md b/packages/paperclip-runner/docs/phase-07-issue-thread-ui.md
index e3a7e8b0124..87798b57a04 100644
--- a/packages/paperclip-runner/docs/phase-07-issue-thread-ui.md
+++ b/packages/paperclip-runner/docs/phase-07-issue-thread-ui.md
@@ -106,6 +106,12 @@ Hosts without the Playwright chromium system libraries can either run
 `pnpm --filter @paperclipai/paperclip-runner verify:rootless` or set
 `PAPERCLIP_RUNNER_CHROMIUM_PATH` to a preinstalled Chromium.
 
+The committed PNGs are pinned to the Chromium build listed in the Phase 7G
+verification evidence, so `check:phase7:ui` needs that same browser. Point
+`PAPERCLIP_RUNNER_CHROMIUM_PATH` at it before comparing; a different build makes
+every shot mismatch at once, which reads like a regression but is not one. The
+check prints the Chromium version it recorded with whenever it reports drift.
+
 ## Accessibility
 
 The suite enforces the contract's blocking gate: axe reports zero serious or
diff --git a/packages/paperclip-runner/scripts/record-phase7-ui-evidence.mjs b/packages/paperclip-runner/scripts/record-phase7-ui-evidence.mjs
index 8bda18bf580..a0a4c67ccaa 100644
--- a/packages/paperclip-runner/scripts/record-phase7-ui-evidence.mjs
+++ b/packages/paperclip-runner/scripts/record-phase7-ui-evidence.mjs
@@ -79,6 +79,9 @@ async function startPreview() {
   };
 }
 
+// Set by `record` so a drift report can name the Chromium build that produced it.
+let browserVersion = "unknown";
+
 async function record(targetDir) {
   await mkdir(targetDir, { recursive: true });
   const browser = await chromium.launch({
@@ -86,6 +89,7 @@ async function record(targetDir) {
       ? {}
       : { executablePath: process.env.PAPERCLIP_RUNNER_CHROMIUM_PATH }),
   });
+  browserVersion = browser.version();
   const recorded = [];
   try {
     for (const viewport of VIEWPORTS) {
@@ -174,7 +178,18 @@ async function main() {
         );
       }
       if (drift.length > 0) {
-        process.stderr.write(`Phase 7 UI evidence is not byte-stable:\n${drift.join("\n")}\n`);
+        process.stderr.write(
+          [
+            "Phase 7 UI evidence is not byte-stable:",
+            ...drift,
+            "",
+            `Recorded with Chromium ${browserVersion}.`,
+            "Committed PNGs are pinned to one Chromium build. A wholesale mismatch",
+            "usually means a different browser, not a UI regression: set",
+            "PAPERCLIP_RUNNER_CHROMIUM_PATH to the Chromium that recorded them.",
+            "",
+          ].join("\n"),
+        );
         process.exitCode = 1;
         return;
       }