diff --git a/README.md b/README.md index f1836fcb2..98cfc258b 100644 --- a/README.md +++ b/README.md @@ -297,6 +297,33 @@ agent-browser tab close [n] # Close tab agent-browser window new # New window ``` +### SPA Detail Pages + +On SPAs with dynamic result lists, refs from `snapshot` often become stale if +you click into a detail page and then navigate back. A more reliable pattern is +to keep the source tab on the list page and open detail pages in a temporary +tab: + +```bash +# 1. Snapshot the result list +agent-browser snapshot -i -c + +# 2. Open one result in a new tab instead of leaving the list page +agent-browser click @e12 --new-tab +agent-browser tab 1 + +# 3. Inspect the detail page, then close it +agent-browser snapshot -i -c +agent-browser tab close + +# 4. Return to the source tab and re-snapshot before the next item +agent-browser tab 0 +agent-browser snapshot -i -c +``` + +This avoids invalidating refs on the source page and is especially useful for +search results, infinite-scroll feeds, and modal-heavy applications. + ### Frames ```bash diff --git a/docs/src/app/snapshots/page.mdx b/docs/src/app/snapshots/page.mdx index 6c7ff6912..021697eb9 100644 --- a/docs/src/app/snapshots/page.mdx +++ b/docs/src/app/snapshots/page.mdx @@ -61,6 +61,28 @@ agent-browser snapshot -i # Get fresh refs agent-browser click @e1 # Use new refs ``` +On dynamic SPAs, `back()` can also trigger a full re-render of the source list, +which means previously captured refs may no longer point at the same items. In +those flows, keep the source tab stable and open detail pages in a temporary +tab: + +```bash +agent-browser snapshot -i -c +agent-browser click @e12 --new-tab +agent-browser tab 1 + +# Inspect the detail page +agent-browser snapshot -i -c + +# Close it and return to the original list +agent-browser tab close +agent-browser tab 0 +agent-browser snapshot -i -c +``` + +This pattern is more reliable for result feeds, search pages, and other UIs +that reassign refs whenever the list re-renders. + ## Annotated screenshots For visual context alongside text snapshots, use `screenshot --annotate` to overlay numbered labels on interactive elements. Each label `[N]` maps to ref `@eN`: