From 9cd1e875ea70e7bd25342b519b4c69fa1af66e85 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sun, 16 Aug 2026 09:23:31 -0700 Subject: [PATCH] docs(browse): warn that hover scrolls and the daemon tab persists across sessions Fixes #2445. Both behaviors are by design but produced confidently wrong verification output: hovering a below-the-fold element scrolls the page before a "rest state" screenshot (exit 0, wrong section), and the daemon's tab survives sessions so a bare `reload` can act on whatever earlier work left open. The screenshot-evidence section now names both traps with the concrete guards (assert window.scrollY; always goto before verifying). Co-Authored-By: Claude Fable 5 --- browse/SKILL.md | 12 ++++++++++++ browse/SKILL.md.tmpl | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/browse/SKILL.md b/browse/SKILL.md index 5044f5179..5e06c5b39 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -619,6 +619,18 @@ $B screenshot /tmp/bug.png # plain screenshot $B console # error log ``` +Two behaviors that silently invalidate screenshots (#2445 — designed, but +surprising): +- **`hover` scrolls its target into view.** Hovering anything below the fold + scrolls the page first, so a "rest state" shot taken afterwards captures + the wrong section with exit 0. Before a rest-state screenshot, hover only + something already visible, and assert position when it matters: + `$B js "window.scrollY"` should be `0` (or your intended offset). +- **The tab persists across sessions.** The daemon keeps its tab between your + sessions, so `reload` or `screenshot` without a preceding `goto` can act on + whatever page earlier work left open. Start verification passes with an + explicit `$B goto `, never a bare `reload`. + ### 5. Find all clickable elements (including non-ARIA) ```bash $B snapshot -C # finds divs with cursor:pointer, onclick, tabindex diff --git a/browse/SKILL.md.tmpl b/browse/SKILL.md.tmpl index 1da7698b2..81a91775e 100644 --- a/browse/SKILL.md.tmpl +++ b/browse/SKILL.md.tmpl @@ -65,6 +65,18 @@ $B screenshot /tmp/bug.png # plain screenshot $B console # error log ``` +Two behaviors that silently invalidate screenshots (#2445 — designed, but +surprising): +- **`hover` scrolls its target into view.** Hovering anything below the fold + scrolls the page first, so a "rest state" shot taken afterwards captures + the wrong section with exit 0. Before a rest-state screenshot, hover only + something already visible, and assert position when it matters: + `$B js "window.scrollY"` should be `0` (or your intended offset). +- **The tab persists across sessions.** The daemon keeps its tab between your + sessions, so `reload` or `screenshot` without a preceding `goto` can act on + whatever page earlier work left open. Start verification passes with an + explicit `$B goto `, never a bare `reload`. + ### 5. Find all clickable elements (including non-ARIA) ```bash $B snapshot -C # finds divs with cursor:pointer, onclick, tabindex