From 61ac675f578808e93024162a86d4ae32ff5d7640 Mon Sep 17 00:00:00 2001
From: Pierre Le Fevre <hello@pierrelf.com>
Date: Fri, 22 May 2026 15:43:59 +0200
Subject: [PATCH] Tighten real-web expectation to Chromium parity +
 interactivity (isu issue 271)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Phase 23 real-web soak previously asserted each scenario against a
frozen capture of we's own historical render — that's a regression
guard, not a correctness bar. Tighten the documented expectation so the
golden is a Chromium-captured reference at the same viewport, and so
each scenario must exercise at least one user-driven interaction (not
just first paint).

This commit ships the policy + tooling; the actual per-scenario
migration is filed as isu issues 273-279 and lands one merge per
follow-up.

- PLAN.md Phase 23: new "Golden screenshot policy" and "Interactivity
  policy" paragraphs; matching exit-criteria lines.
- crates/e2e/real-web/README.md: new directory-layout entry for
  `<domain>.<viewport>.chromium.expected.png`, new "Golden screenshot
  policy" and "Interactivity policy" sections, refreshed soak iteration
  workflow, refreshed exit-criteria checklist.
- crates/e2e/scenarios/real-web/.gitignore: keep `*.chromium.png` /
  `*.firefox.png` throwaway captures gitignored; commit the canonical
  `*.chromium.expected.png` golden.
- tests/popular-sites/compare.py: new `--write-golden` flag that writes
  the canonical golden (`<scenario>.<viewport>.chromium.expected.png`)
  rather than the throwaway reference. Only `--browser chromium` is
  accepted with it (Chromium is the parity bar).
- tests/popular-sites/test_compare.py: cover the new naming.
- tests/popular-sites/README.md: document `--write-golden`.

The legacy `<domain>.<viewport>.expected.png` files are left in place
for now; they will be deleted in each per-scenario migration commit
(isu issues 274-278).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .isu/issues.json                         |  95 +++++++++++++++++++-
 PLAN.md                                  |   5 +-
 crates/e2e/real-web/README.md            | 107 ++++++++++++++++++-----
 crates/e2e/scenarios/real-web/.gitignore |  12 ++-
 tests/popular-sites/README.md            |  27 +++---
 tests/popular-sites/compare.py           |  52 +++++++++--
 tests/popular-sites/test_compare.py      |  15 ++++
 7 files changed, 266 insertions(+), 47 deletions(-)

diff --git a/.isu/issues.json b/.isu/issues.json
index da88c82..a394a5d 100644
--- a/.isu/issues.json
+++ b/.isu/issues.json
@@ -1,5 +1,5 @@
 {
-  "next_id": 273,
+  "next_id": 280,
   "issues": [
     {
       "id": 1,
@@ -3266,7 +3266,7 @@
       "labels": [],
       "assigned": [],
       "author": "piefev",
-      "state": "open",
+      "state": "closed",
       "created_at": "2026-05-22T13:19:21Z"
     },
     {
@@ -3279,6 +3279,97 @@
       "author": "piefev",
       "state": "open",
       "created_at": "2026-05-22T13:19:54Z"
+    },
+    {
+      "id": 273,
+      "repo": "we",
+      "title": "Add click/type/wait interactivity commands to e2e scenario DSL",
+      "body": "Phase 23 / isu 271 follow-up.\n\nThe tightened real-web standard (see PLAN.md Phase 23 'Methodology → Interactivity policy') requires each scenario to include at least one user-driven interaction. The e2e harness today only loads, screenshots, and dumps — it has no way to express \"click the search button\" or \"type into the input\".\n\nScope:\n\n- Refactor the scenario runner so the JS VM is kept alive across commands within a single page session (today `RenderOutput.doc` is detached after `goto`; introduce a `Session` that owns the VM + Document and is re-painted after each interaction).\n- Add DSL commands:\n  - `click <css-selector>` — find the element via `querySelector`, dispatch a synthetic `mousedown`/`mouseup`/`click` event sequence with bubbling, then re-style/re-layout/re-paint.\n  - `type <css-selector> <text>` — focus the element, dispatch `keydown`/`beforeinput`/`input`/`keyup` events per character; update the element's value for `<input>`/`<textarea>`.\n  - `wait_for_console <substring> [--timeout-ms N]` — pump the event loop until the substring appears (useful for async work kicked off by a click).\n- Per-command panic catching must continue to work.\n- Unit tests for the parser; smoke-scenario coverage for each new command using `crates/e2e/pages/`.\n- Update `CLAUDE.md` 'E2E Harness' section + `crates/e2e/src/scenario.rs` module doc.\n\nAcceptance: the smoke suite passes, and one new scenario under `crates/e2e/scenarios/` demonstrates click + type + wait_for_console driving a tiny interactive page.",
+      "labels": [
+        "real-web"
+      ],
+      "assigned": [],
+      "author": "piefev",
+      "state": "open",
+      "created_at": "2026-05-22T13:41:36Z"
+    },
+    {
+      "id": 274,
+      "repo": "we",
+      "title": "Migrate bing.com scenario to Chromium-reference golden",
+      "body": "Phase 23 / isu 271 follow-up.\n\nThe current `crates/e2e/scenarios/real-web/bing.com.we` asserts against `bing.com.{desktop,mobile}.expected.png` — a frozen capture of we's own historical render. The tightened standard (PLAN.md Phase 23 'Methodology → Golden screenshot policy') requires the golden to be a Chromium-captured reference at the same viewport.\n\nScope:\n\n1. Capture the golden: `python3 tests/popular-sites/compare.py --write-golden --browser chromium crates/e2e/scenarios/real-web/bing.com.we`. Commit the resulting `bing.com.desktop.chromium.expected.png` and `bing.com.mobile.chromium.expected.png`.\n2. Update the scenario to assert against the new golden:\n   `assert_screenshot_matches real-web/bing.com/desktop.png bing.com.desktop.chromium.expected.png`.\n3. Delete the legacy `bing.com.{desktop,mobile}.expected.png` files.\n4. If `we`'s render does not match Chromium (it will not, on day one), mark the scenario `# xfail: see isu issue <new>` and file a fresh `real-web` defect issue capturing the visual gap (include diff image paths from the harness output).\n\nAcceptance: scenario is committed with Chromium golden + assertion. Either it passes (great), or it is `xfail`'d with a tracking issue.",
+      "labels": [
+        "real-web"
+      ],
+      "assigned": [],
+      "author": "piefev",
+      "state": "open",
+      "created_at": "2026-05-22T13:41:45Z"
+    },
+    {
+      "id": 275,
+      "repo": "we",
+      "title": "Migrate opera.com scenario to Chromium-reference golden",
+      "body": "Phase 23 / isu 271 follow-up. Same scope as isu issue 274, but for `crates/e2e/scenarios/real-web/opera.com.we`. See isu issue 271 and PLAN.md Phase 23 'Methodology → Golden screenshot policy' for the standard.",
+      "labels": [
+        "real-web"
+      ],
+      "assigned": [],
+      "author": "piefev",
+      "state": "open",
+      "created_at": "2026-05-22T13:41:51Z"
+    },
+    {
+      "id": 276,
+      "repo": "we",
+      "title": "Migrate palmplaystore.com scenario to Chromium-reference golden",
+      "body": "Phase 23 / isu 271 follow-up. Same scope as isu issue 274, but for `crates/e2e/scenarios/real-web/palmplaystore.com.we`. See isu issue 271 and PLAN.md Phase 23 'Methodology → Golden screenshot policy' for the standard.",
+      "labels": [
+        "real-web"
+      ],
+      "assigned": [],
+      "author": "piefev",
+      "state": "open",
+      "created_at": "2026-05-22T13:41:51Z"
+    },
+    {
+      "id": 277,
+      "repo": "we",
+      "title": "Migrate roblox.com scenario to Chromium-reference golden",
+      "body": "Phase 23 / isu 271 follow-up. Same scope as isu issue 274, but for `crates/e2e/scenarios/real-web/roblox.com.we`. See isu issue 271 and PLAN.md Phase 23 'Methodology → Golden screenshot policy' for the standard.",
+      "labels": [
+        "real-web"
+      ],
+      "assigned": [],
+      "author": "piefev",
+      "state": "open",
+      "created_at": "2026-05-22T13:41:51Z"
+    },
+    {
+      "id": 278,
+      "repo": "we",
+      "title": "Migrate tiktok.com scenario to Chromium-reference golden",
+      "body": "Phase 23 / isu 271 follow-up. Same scope as isu issue 274, but for `crates/e2e/scenarios/real-web/tiktok.com.we`. See isu issue 271 and PLAN.md Phase 23 'Methodology → Golden screenshot policy' for the standard.",
+      "labels": [
+        "real-web"
+      ],
+      "assigned": [],
+      "author": "piefev",
+      "state": "open",
+      "created_at": "2026-05-22T13:41:51Z"
+    },
+    {
+      "id": 279,
+      "repo": "we",
+      "title": "Update existing real-web scenarios to include interactivity assertions",
+      "body": "Phase 23 / isu 271 follow-up. Once the interactivity DSL commands land (isu issue 273), every committed real-web scenario must include at least one user-driven interaction (PLAN.md Phase 23 'Methodology → Interactivity policy').\n\nPer-scenario work:\n- Identify the page's primary affordance (search input, login button, menu, …).\n- Add a `click` and/or `type` step that exercises it.\n- Add an `assert_dom_contains` / `assert_console_contains` (or `assert_screenshot_matches` against a second golden) capturing the expected response.\n- If our implementation does not yet make the affordance work, mark the scenario `# xfail` with a tracking issue for the underlying defect.\n\nAcceptance: every `.we` file in `crates/e2e/scenarios/real-web/` contains at least one `click` or `type` command. The exit-criteria checklist line in `crates/e2e/real-web/README.md` can be checked off.",
+      "labels": [
+        "real-web"
+      ],
+      "assigned": [],
+      "author": "piefev",
+      "state": "open",
+      "created_at": "2026-05-22T13:41:59Z"
     }
   ]
 }
diff --git a/PLAN.md b/PLAN.md
index e688336..a6093d6 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -465,7 +465,8 @@ If `pick.py` happens to return a domain that already has a committed scenario, r
 
 - One scenario per site, named after the domain. Each scenario does at minimum: `goto_as <url> <snapshot-html>`, `cache_put` for subresources, `screenshot`, `dump_dom`, `dump_console`, plus targeted `assert_dom_contains` / `assert_console_contains` for the page's key content.
 - Snapshots are committed so the scenario suite is offline-runnable and deterministic. Re-snapshot only when intentionally bumping a baseline, in its own commit.
-- Golden screenshots live next to each scenario as `<domain>.expected.png`. Diff against the rendered output with a per-pixel tolerance helper added to the e2e harness; any diff over threshold fails the scenario.
+- **Golden screenshot policy.** The committed golden for each scenario is a Chromium-captured reference at the same viewport: `<domain>.<viewport>.chromium.expected.png`. The bar is "we renders this page indistinguishably from Chromium," not "we renders this page the way it did last week." A scenario asserts against the Chromium golden via `assert_screenshot_matches`; the diff threshold is intentionally tight. A scenario whose `we` render does not yet match Chromium is marked `# xfail: see isu issue <id>` and the gap is tracked as its own defect issue. The legacy self-referential `<domain>.<viewport>.expected.png` files are deprecated and scheduled for migration; new scenarios use the Chromium golden from day one. Generate the golden with `python3 tests/popular-sites/compare.py --write-golden --browser chromium <scenario>`.
+- **Interactivity policy.** Each committed scenario must include at least one *interactivity* assertion — a `click`, `type`, focus change, or equivalent user-driven action — that demonstrates the page does what a user would expect it to do, not just that it paints the right pixels on first load. The DSL commands required to express this are tracked under their own `real-web` issues; until they land, scenarios are explicitly marked as not yet meeting the interactivity bar.
 - Each fix lands in its own merge to `main`, references the `isu` issue, and includes (a) the scenario asserting the bug is gone and (b) any narrower unit test that catches the regression at a lower layer.
 
 ### Bug intake & triage
@@ -485,6 +486,8 @@ If `pick.py` happens to return a domain that already has a committed scenario, r
 
 - Coverage: at least the top 100 filtered popular sites have committed `passing` scenarios under `crates/e2e/scenarios/real-web/`.
 - Stability: a sustained streak (e.g. 25 consecutive random picks) of new sites that pass on first scenario run with no `sev-crash` or `sev-broken` defects.
+- **Chromium parity.** Every committed scenario asserts against a Chromium-captured golden (`<domain>.<viewport>.chromium.expected.png`), not against `we`'s own prior output. No `# xfail`'d Chromium-parity gaps remain.
+- **Interactivity.** Every committed scenario exercises at least one user-driven interaction (click, type, focus, …) and asserts the page responds correctly. No scenario is purely a first-paint screenshot.
 - Every `real-web`-labelled `isu` issue is either closed by a fix or explicitly re-categorised as a feature request scheduled for a later phase.
 - `cargo run -p we-e2e -- --real-web` is green in CI and runs as part of the standard pre-merge checklist for any change to parsing, styling, layout, rendering, scripting, networking, or the UA stylesheet.
 - A short retrospective in `crates/e2e/real-web/README.md` lists the bugs found, the fixes that landed, and any features the soak motivated promoting to a future phase.
diff --git a/crates/e2e/real-web/README.md b/crates/e2e/real-web/README.md
index 5659034..3d57832 100644
--- a/crates/e2e/real-web/README.md
+++ b/crates/e2e/real-web/README.md
@@ -14,17 +14,62 @@ re-baselining) live in [`CLAUDE.md`](../../../CLAUDE.md) under
 ```
 crates/e2e/
 ├── scenarios/real-web/
-│   ├── <domain>.we                        # scenario, one per site
-│   └── <domain>.<viewport>.expected.png   # golden screenshot per viewport
+│   ├── <domain>.we                                  # scenario, one per site
+│   ├── <domain>.<viewport>.chromium.expected.png    # canonical golden (Chromium reference)
+│   └── <domain>.<viewport>.expected.png             # legacy self-referential golden (deprecated)
 └── real-web/
-    ├── README.md                          # this file
-    └── snapshots/<domain>/                # committed offline page bodies
+    ├── README.md                                    # this file
+    └── snapshots/<domain>/                          # committed offline page bodies
 ```
 
 `tests/popular-sites/pick.py` produces candidate URLs at soak time but is
 **not** part of the committed scenario tree — see
 [`tests/popular-sites/README.md`](../../../tests/popular-sites/README.md).
 
+## Golden screenshot policy
+
+The bar is **parity with Chromium**, not parity with `we`'s own historical
+output. Every new scenario asserts against a Chromium-captured reference
+PNG; the older `<domain>.<viewport>.expected.png` files are deprecated and
+scheduled for migration on a per-scenario basis (tracked in `isu`).
+
+### Capturing or refreshing a Chromium golden
+
+```sh
+# One-time per machine.
+npx playwright install chromium
+
+# Write the canonical golden PNG for one scenario.
+python3 tests/popular-sites/compare.py --write-golden --browser chromium \
+    crates/e2e/scenarios/real-web/<domain>.we
+```
+
+The capture lands at
+`crates/e2e/scenarios/real-web/<domain>.<viewport>.chromium.expected.png`
+and is committed. Asserting in the scenario uses the standard helper:
+
+```text
+assert_screenshot_matches real-web/<domain>/desktop.png \
+    <domain>.desktop.chromium.expected.png
+```
+
+A scenario whose `we` render does not yet match its Chromium golden must
+be marked `# xfail: see isu issue <id>` and the visual gap tracked as its
+own `real-web` defect issue.
+
+Without `--write-golden`, `compare.py` writes a throwaway
+`<domain>.<viewport>.chromium.png` next to the scenario — gitignored, for
+human eyeballing only.
+
+## Interactivity policy
+
+Each committed scenario must include at least one interactivity
+assertion: a click, keystroke, focus, or other user-driven action that
+demonstrates the page does what a user would expect. The DSL commands
+that express interactivity are tracked under their own `real-web`
+issues; until they land, new scenarios should note in their comment
+header that the interactivity check is pending the harness work.
+
 ## Soak iteration workflow
 
 When the issue queue is empty during Phase 23, run one iteration:
@@ -35,33 +80,46 @@ When the issue queue is empty during Phase 23, run one iteration:
 3. Write `crates/e2e/scenarios/real-web/<domain>.we`: force
    `network offline`, `goto_as <url> <snapshot>`, `screenshot`, `dump_dom`,
    `dump_console`, and at least one `assert_dom_contains` for the page's
-   primary content. Capture a golden PNG and assert with
-   `assert_screenshot_matches`.
-4. Run the scenario. For each defect (panic, layout glitch, missing glyph,
-   JS exception, perf cliff), file an `isu` issue with the `real-web` label,
-   the scenario path, and pointers to the captured artifacts in
-   `crates/e2e/artifacts/real-web/runs/<domain>/`.
-5. Commit the scenario, snapshot, and golden screenshot — even if open
-   defects remain — so the next iteration picks the defect issues up via the
-   normal Priority 1 path.
-6. Exit. Subsequent iterations close defects one by one; when all defects
-   for the site are closed, the scenario becomes `pass` and the soak moves on.
+   primary content.
+4. Capture the Chromium golden:
+   `python3 tests/popular-sites/compare.py --write-golden --browser chromium <scenario>`.
+   Assert in the scenario with
+   `assert_screenshot_matches <captured.png> <domain>.<viewport>.chromium.expected.png`.
+5. Add at least one interactivity assertion (or, if the DSL doesn't yet
+   support the interaction the page requires, mark the scenario `# xfail`
+   with a pointer to the tracking issue).
+6. Run the scenario. For each defect (panic, layout glitch, missing glyph,
+   JS exception, perf cliff, Chromium-parity gap), file an `isu` issue with
+   the `real-web` label, the scenario path, and pointers to the captured
+   artifacts in `crates/e2e/artifacts/real-web/runs/<domain>/`.
+7. Commit the scenario, snapshot, and Chromium golden — even if open
+   defects remain — so the next iteration picks the defect issues up via
+   the normal Priority 1 path.
+8. Exit. Subsequent iterations close defects one by one; when all defects
+   for the site are closed, the scenario becomes `pass` and the soak moves
+   on.
 
 If the picker returns a domain that already has a committed scenario,
 re-snapshot it against the live site (`--real-web-online`) and treat any
 divergence either as a real-web regression (file an issue) or as upstream
-drift (update snapshot + golden in its own commit).
+drift (update snapshot + Chromium golden in its own commit).
 
 ## Comparing against Chrome and Firefox
 
 `tests/popular-sites/compare.py` drives Playwright to capture Chromium
-and Firefox screenshots for any committed `.we` scenario, alongside
-`<domain>.<viewport>.expected.png`. The reference images are for human
-inspection only — the harness still asserts only against
-`.expected.png` — and are gitignored so they never accidentally land
-in a commit. See
+and Firefox screenshots for any committed `.we` scenario. Two output
+modes:
+
+* Default: writes throwaway `<domain>.<viewport>.<browser>.png` PNGs
+  next to the scenario for human inspection. Gitignored so they never
+  accidentally land in a commit.
+* `--write-golden --browser chromium`: writes
+  `<domain>.<viewport>.chromium.expected.png`, the **canonical golden**
+  the harness asserts `we` against.
+
+See
 [`tests/popular-sites/README.md`](../../../tests/popular-sites/README.md)
-for the install + invocation steps.
+for install + invocation steps.
 
 ## Running the suite
 
@@ -137,6 +195,11 @@ Tracked against [`PLAN.md`](../../../PLAN.md) Phase 23:
       scenarios under `crates/e2e/scenarios/real-web/`.
 - [ ] A streak of 25 consecutive random picks with no `sev-crash` or
       `sev-broken` defects.
+- [ ] Every committed scenario asserts against a Chromium-captured golden
+      (`<domain>.<viewport>.chromium.expected.png`). No legacy
+      self-referential `.expected.png` remains in the suite.
+- [ ] Every committed scenario exercises at least one user-driven
+      interaction (click, keystroke, focus, …).
 - [ ] Every `real-web`-labelled `isu` issue is either closed or
       re-categorised as a feature for a later phase.
 - [ ] `cargo run -p we-e2e -- --real-web` runs green in CI and is part of the
diff --git a/crates/e2e/scenarios/real-web/.gitignore b/crates/e2e/scenarios/real-web/.gitignore
index 2673923..6f6770c 100644
--- a/crates/e2e/scenarios/real-web/.gitignore
+++ b/crates/e2e/scenarios/real-web/.gitignore
@@ -1,6 +1,12 @@
 # Comparison screenshots generated by tests/popular-sites/compare.py via
-# Playwright. They are reference images for human inspection only — not
-# consumed by the e2e harness, and they go stale quickly as live sites
-# and browser versions change. Regenerate on demand instead of committing.
+# Playwright. They are throwaway reference images for human inspection
+# only — not consumed by the e2e harness, and they go stale quickly as
+# live sites and browser versions change. Regenerate on demand instead
+# of committing.
+#
+# The canonical Chromium golden (`*.chromium.expected.png`, written by
+# `compare.py --write-golden`) is the assertion target and IS committed;
+# the negated pattern below keeps it out of these ignore rules.
 *.chromium.png
 *.firefox.png
+!*.chromium.expected.png
diff --git a/tests/popular-sites/README.md b/tests/popular-sites/README.md
index 55d5083..e97104f 100644
--- a/tests/popular-sites/README.md
+++ b/tests/popular-sites/README.md
@@ -106,22 +106,25 @@ screenshots — see below.
 `compare.py` walks one or more `.we` scenarios, tracks the current
 `viewport` / `goto_as` / `screenshot` state, and shells out to
 `npx playwright screenshot` so the same page can be re-rendered in
-Chromium and Firefox at the same viewport. The PNGs land next to the
-existing golden under `crates/e2e/scenarios/real-web/`:
+Chromium and Firefox at the same viewport. PNGs land under
+`crates/e2e/scenarios/real-web/`. Two output naming modes:
 
 ```
 crates/e2e/scenarios/real-web/
 ├── bing.com.we
-├── bing.com.desktop.expected.png    # we's render — asserted by harness
-├── bing.com.desktop.chromium.png    # Playwright Chromium — reference
-└── bing.com.desktop.firefox.png     # Playwright Firefox — reference
+├── bing.com.desktop.chromium.expected.png  # canonical golden (--write-golden)
+├── bing.com.desktop.chromium.png           # throwaway reference (default)
+└── bing.com.desktop.firefox.png            # throwaway reference (default)
 ```
 
-The reference images are for human inspection only — the e2e harness
-still asserts `we` against the committed `.expected.png`. They are
-listed in
-`crates/e2e/scenarios/real-web/.gitignore` so a captured set never
-accidentally lands in a commit; regenerate on demand.
+* **Default mode** writes `<scenario>.<viewport>.<browser>.png`. These
+  are gitignored reference images for human inspection only.
+* **`--write-golden --browser chromium`** writes
+  `<scenario>.<viewport>.chromium.expected.png`. *This is the canonical
+  golden the e2e harness asserts against* — see
+  [`crates/e2e/real-web/README.md`](../../crates/e2e/real-web/README.md)
+  for the policy. Only `--browser chromium` is accepted with
+  `--write-golden`; Chromium is the parity bar.
 
 ### Setup
 
@@ -140,6 +143,10 @@ python3 tests/popular-sites/compare.py --all
 python3 tests/popular-sites/compare.py --browser chromium \
     crates/e2e/scenarios/real-web/bing.com.we
 
+# Write the canonical Chromium golden the harness asserts against.
+python3 tests/popular-sites/compare.py --write-golden --browser chromium \
+    crates/e2e/scenarios/real-web/bing.com.we
+
 # Apples-to-apples with the offline snapshot we feed `we` (mostly blank
 # for client-side rendered sites, but useful when our render diverges
 # from what other engines do on the same exact bytes).
diff --git a/tests/popular-sites/compare.py b/tests/popular-sites/compare.py
index 93202d8..29d8424 100755
--- a/tests/popular-sites/compare.py
+++ b/tests/popular-sites/compare.py
@@ -4,8 +4,10 @@
 For each ``screenshot <path>`` line in a ``.we`` scenario, this script
 re-renders the same page in Chromium and Firefox (via Playwright) at the
 same viewport and writes the resulting PNGs next to the existing golden
-under
-``crates/e2e/scenarios/real-web/<scenario>.<viewport>.<browser>.png``.
+under ``crates/e2e/scenarios/real-web/<scenario>.<viewport>.<browser>.png``
+(throwaway, gitignored) or
+``crates/e2e/scenarios/real-web/<scenario>.<viewport>.<browser>.expected.png``
+with ``--write-golden`` (committed, asserted against by the e2e harness).
 
 Two source modes are supported:
 
@@ -19,10 +21,10 @@ Two source modes are supported:
   scenario sees, but for sites whose UI is rendered client-side, the
   output is essentially blank.
 
-The Playwright outputs are reference images for human inspection (do we
-look like Chrome at all?). They are not consumed by the e2e harness;
-``assert_screenshot_matches`` still compares ``we``'s render against the
-committed ``.expected.png``.
+Without ``--write-golden`` the captures are reference images for human
+inspection only. With ``--write-golden --browser chromium`` the capture
+*is* the canonical golden the e2e harness asserts ``we`` against — see
+``crates/e2e/real-web/README.md`` for the policy.
 
 Playwright is not a ``we`` dependency. The script shells out to
 ``npx playwright`` so the only runtime requirements are Node.js + npx on
@@ -43,6 +45,10 @@ Usage::
     # Restrict to a single browser.
     python3 tests/popular-sites/compare.py --browser chromium <scenario>
 
+    # Write the canonical Chromium golden the harness asserts against.
+    python3 tests/popular-sites/compare.py --write-golden \
+        --browser chromium <scenario>
+
     # Skip files that already have output committed.
     python3 tests/popular-sites/compare.py --skip-existing --all
 """
@@ -148,8 +154,17 @@ def parse_capture_plan(scenario_path: Path) -> list[dict]:
     return plan
 
 
-def _output_path(plan_item: dict, browser: str) -> Path:
-    name = f"{plan_item['scenario_stem']}.{plan_item['viewport_name']}.{browser}.png"
+def _output_path(plan_item: dict, browser: str, write_golden: bool = False) -> Path:
+    """Path the captured PNG should be written to.
+
+    With ``write_golden=True`` the file is the canonical Chromium-reference
+    golden the e2e harness asserts against
+    (``<scenario>.<viewport>.<browser>.expected.png``). Without it, the
+    file is a throwaway reference for human inspection
+    (``<scenario>.<viewport>.<browser>.png``, gitignored).
+    """
+    suffix = "expected.png" if write_golden else "png"
+    name = f"{plan_item['scenario_stem']}.{plan_item['viewport_name']}.{browser}.{suffix}"
     return plan_item["scenario_dir"] / name
 
 
@@ -258,6 +273,17 @@ def main() -> int:
         action="store_true",
         help="Skip captures whose output file already exists.",
     )
+    parser.add_argument(
+        "--write-golden",
+        action="store_true",
+        help=(
+            "Write captures as the canonical e2e golden file "
+            "(<scenario>.<viewport>.<browser>.expected.png) rather than as "
+            "a throwaway reference. The e2e harness asserts against these "
+            "files via `assert_screenshot_matches`. Only `--browser chromium` "
+            "is accepted with this flag, since Chromium is the parity bar."
+        ),
+    )
     parser.add_argument(
         "--dry-run",
         action="store_true",
@@ -271,6 +297,14 @@ def main() -> int:
         parser.error("provide one or more scenario paths or pass --all")
 
     browsers = args.browser or list(SUPPORTED_BROWSERS)
+    if args.write_golden:
+        # Chromium is the parity bar (PLAN.md Phase 23). Refuse to write a
+        # Firefox-captured PNG as the canonical golden so an accidental
+        # `--browser firefox --write-golden` never silently overrides it.
+        if browsers != ["chromium"]:
+            parser.error(
+                "--write-golden requires --browser chromium (and only chromium)"
+            )
     wait_ms = args.wait_ms
     if wait_ms is None:
         wait_ms = 5000 if args.source == "url" else 500
@@ -323,7 +357,7 @@ def main() -> int:
                 target = _file_url(item["snapshot"])
             for browser in browsers:
                 total += 1
-                out = _output_path(item, browser)
+                out = _output_path(item, browser, write_golden=args.write_golden)
                 rel = out.relative_to(REPO_ROOT)
                 print(
                     f"{scenario.name}: {item['viewport_name']} "
diff --git a/tests/popular-sites/test_compare.py b/tests/popular-sites/test_compare.py
index 7b98b52..53cb931 100644
--- a/tests/popular-sites/test_compare.py
+++ b/tests/popular-sites/test_compare.py
@@ -141,6 +141,21 @@ class OutputPathTests(unittest.TestCase):
                 "bing.com.desktop.firefox.png",
             )
 
+    def test_output_path_golden_format(self):
+        with tempfile.TemporaryDirectory() as td:
+            tmp = Path(td)
+            scenario_dir = tmp / "scenarios"
+            scenario_dir.mkdir()
+            item = {
+                "scenario_stem": "bing.com",
+                "viewport_name": "desktop",
+                "scenario_dir": scenario_dir,
+            }
+            self.assertEqual(
+                compare._output_path(item, "chromium", write_golden=True).name,
+                "bing.com.desktop.chromium.expected.png",
+            )
+
 
 if __name__ == "__main__":
     unittest.main()
-- 
2.51.2