[tmashara]

A route's own before or beforeShot still replaces the top-level one; that stays the default. It can now run the hook it replaced through ctx.topLevel:

export default {
  before: async (page) => {
    const accept = page.getByRole("button", { name: "Accept" });
    if (await accept.isVisible()) await accept.click();
  },
  routes: [
    {
      left: "/docs",
      before: async (page, { topLevel }) => {
        await topLevel?.();
        await page.click("[aria-label=Menu]");
      },
    },
  ],
};

topLevel is set only on a route's own hook when a different top-level hook of that kind exists. Otherwise it is undefined, hence the ?.(). It runs with the same page and { side, route, width }, inside the calling hook's step. A throw or a hang there is reported as that hook's error or timeout, the same as before.

Notes

• shotId includes the top-level hooks' sources, so a --cache-right recording isn't replayed after only the top-level hook changes.
• configHash changes for every config, because routes carry the new field. That's harmless: version() already invalidates reruns on every release. Accepted entries aren't keyed on it, so they're unaffected.
• Docs: the Hook jsdoc, renderdiff.config.example.ts, docs/scoping.md and skills/renderdiff/reference.md.

Testing

• typecheck, lint, format:check and npm test (362/362) pass.
• Visual: the "before hooks" suite in tests/visual/guardrails.test.ts passes, including the new test "a route's own hook can run the top-level one as ctx.topLevel".
• Unit: one shotId assertion checks that a different top-level hook gives a different key.

Refs #59

🤖 Generated with Claude Code