From c4b19d1998144fc8e245a850653496e1429cb6c8 Mon Sep 17 00:00:00 2001
From: Timur Mashara <62305878+tmashara@users.noreply.github.com>
Date: Mon, 2 Nov 2026 13:55:14 +0100
Subject: [PATCH] Docs: config/flag parity fixes The example config and README
 now cover beforeShot, the "flags can't" list drops hide selectors (--hide
 exists), and the precedence notes say --mask and --hide add to the config's
 lists. The action's routes input warns that it splits on spaces, so '/route
 @sel' belongs in the config.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                    |  5 +++--
 action.yml                   |  2 +-
 renderdiff.config.example.ts | 14 +++++++++++---
 3 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 25a23e0..ce1affa 100644
--- a/README.md
+++ b/README.md
@@ -166,7 +166,7 @@ screenshots and text) out of git too. Details: [docs/scoping.md](https://github.
 
 Flags cover a one-off run. A `renderdiff.config.{ts,mts,js,mjs}` in the working directory
 covers a repo you diff repeatedly, and expresses what flags can't: **per-route masks** for content
-that legitimately drifts, extra selectors to hide, extra URLs to block, `before` hooks.
+that legitimately drifts, extra URLs to block, `before` and `beforeShot` hooks.
 
 ```ts
 export default {
@@ -181,7 +181,8 @@ export default {
 };
 ```
 
-**Precedence: CLI flag > config file > built-in default.** Every field is annotated in
+**Precedence: CLI flag > config file > built-in default; `--mask` and `--hide` add to the
+config's instead.** Every field is annotated in
 [`renderdiff.config.example.ts`](./renderdiff.config.example.ts). `export default { … }`
 needs no import; `import type { RenderdiffConfig } from "renderdiff"` is for editor types
 only.
diff --git a/action.yml b/action.yml
index 9c3e602..85d472e 100644
--- a/action.yml
+++ b/action.yml
@@ -13,7 +13,7 @@ inputs:
     description: The reference, e.g. https://example.com.
     required: true
   routes:
-    description: Routes separated by spaces or newlines, e.g. "/ /about /pricing::/plans". Optional when the config lists them.
+    description: Routes separated by spaces or newlines, e.g. "/ /about /pricing::/plans". Split on spaces, so a per-route selector ('/route @sel') doesn't work here; put it in the config. Optional when the config lists them.
     default: ""
   config:
     description: Path to a renderdiff config file. Default renderdiff.config.{ts,mts,js,mjs} in the workspace.
diff --git a/renderdiff.config.example.ts b/renderdiff.config.example.ts
index d85b900..03633fe 100644
--- a/renderdiff.config.example.ts
+++ b/renderdiff.config.example.ts
@@ -1,8 +1,8 @@
 // Copy to `renderdiff.config.ts` in the directory you run `renderdiff` from.
 //
-// Everything here is optional, and CLI flags always win over it. The type import and
-// `satisfies` are for editor types only: Node erases both, so this loads without
-// renderdiff installed in the project.
+// Everything here is optional; a CLI flag for the same setting wins over it (`--mask`
+// and `--hide` add to it instead). The type import and `satisfies` are for editor types
+// only: Node erases both, so this loads without renderdiff installed in the project.
 import type { RenderdiffConfig } from "renderdiff";
 
 export default {
@@ -46,6 +46,14 @@ export default {
     if (await accept.isVisible()) await accept.click();
   },
 
+  // Like `before`, but after the settle, right before masks and the shot: for state the
+  // settle's scroll pass would undo. Nothing settles after it, so await what it changes.
+  // For every route without its own `beforeShot` (which can run this one with
+  // `await topLevel?.()`), CLI routes included.
+  // beforeShot: async (page) => {
+  //   await page.click("[data-tab=intro]");
+  // },
+
   // Playwright storage state (cookies, localStorage) each side starts with, e.g. signed
   // in: `npx playwright codegen --save-storage=auth.json <url>`. One file, or
   // `{ left, right }`. Relative to this file. It holds live session tokens: never commit