patchright-cli 0.9.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

patchright_cli/__init__.py

@@ -1,3 +1,3 @@
 """patchright-cli — Undetected browser automation CLI using Patchright."""
 
-__version__ = "0.9.1"
+__version__ = "0.11.0"

patchright_cli/__main__.py

@@ -1,6 +1,6 @@
 """Allow running as `python -m patchright_cli`."""
 
-from patchright_cli.cli import main
+from patchright_cli._entry import main
 
 if __name__ == "__main__":
     main()

patchright_cli/_entry.py

@@ -0,0 +1,26 @@
+"""Console-script entry point with a `--version` fast path.
+
+Agents probe `--version` constantly, so a bare version flag is answered here
+from the leaf `patchright_cli/__init__.py`, before cli.py pulls in click and
+the daemon (and with it Patchright). Everything else goes to cli.main().
+"""
+
+import sys
+
+_VERSION_FLAGS = ("-v", "-V", "--version")
+
+
+def main() -> None:
+    if len(sys.argv) == 2 and sys.argv[1] in _VERSION_FLAGS:
+        from patchright_cli import __version__
+
+        sys.stdout.write(__version__ + "\n")
+        return
+
+    from patchright_cli.cli import main as cli_main
+
+    cli_main()
+
+
+if __name__ == "__main__":
+    main()

patchright_cli/_skills/patchright-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: patchright-cli
-description: Anti-detect browser automation using Patchright (undetected Playwright fork). Use when you need to interact with websites that block regular Playwright/Chrome DevTools, such as Akamai/Cloudflare-protected sites. Provides the same command interface as playwright-cli but bypasses bot detection. Use this skill whenever the user asks to automate a browser, scrape a website, fill forms, log into sites, take screenshots, or do anything involving Chrome automation — especially if the target site has bot protection like Cloudflare or Akamai.
+description: Anti-detect browser automation using Patchright (undetected Playwright fork). Use when you need to interact with websites that block regular Playwright/Chrome DevTools, such as Akamai/Cloudflare-protected sites. Uses playwright-cli style commands (not a drop-in replacement) but bypasses bot detection. Use this skill whenever the user asks to automate a browser, scrape a website, fill forms, log into sites, take screenshots, or do anything involving Chrome automation — especially if the target site has bot protection like Cloudflare or Akamai.
 ---
 
 # Anti-Detect Browser Automation with patchright-cli
@@ -28,7 +28,7 @@ patchright-cli screenshot                    # capture the page
 patchright-cli close                         # done
 ```
 
-Every interaction follows: **open -> snapshot -> read refs -> interact -> snapshot again -> repeat**. Refs are ephemeral -- they change on every page update. If a ref fails, re-snapshot.
+Every interaction follows: **open -> snapshot -> read refs -> interact -> snapshot again -> repeat**. A ref (`e5`, or `f3e5` inside an iframe and after a navigation) names one element until it leaves the page; a ref whose element is gone fails fast with `no longer matches an element` -- re-snapshot then. Refs are per tab: after `tab-select`, use the snapshot it prints. A click that opens a popup makes the popup current, and the popup's first-document refs (`e1`, `e2`, ...) can reuse numbers from the opener, so use the snapshot printed after the click.
 
 ## Command chaining
 
@@ -101,6 +101,8 @@ These go before the command:
 --show-port=9322        # Dashboard port (default: 9322)
 --raw                   # Strip page/snapshot decorations from output
 --json                  # Wrap full response as JSON ({success, output, ...})
+--toon                  # TOON for results with structured data (list, tab-list, cookie-list,
+                        # find, console, network, url, title, ...); others print as usual
 ```
 
 These go *after* the command instead:
@@ -147,9 +149,9 @@ snapshot <ref>                # Subtree of a specific element
 snapshot --selector="#main"   # Subtree of a CSS selector -- must match exactly
                               # one element. No ref needed, so
                               # this works before the first snapshot
-snapshot --depth=N            # Limit depth
-snapshot -i                   # Interactive elements only
-snapshot --boxes              # Append [box=x,y,w,h] to each [ref=eN] line
+snapshot --depth=N            # Levels 0..N; a cut node ends in `# +N refs`
+snapshot -i                   # Interactive elements (and named landmarks around them)
+snapshot --boxes              # Append [box=x,y,w,h] (page coordinates, iframes too)
 ```
 
 ### Searching instead of snapshotting
@@ -163,8 +165,14 @@ patchright-cli find --regex "sign (in|up)" # regex, case-insensitive
 patchright-cli find --regex "/Sign In/"    # slash form carries flags (i, m, s)
 patchright-cli find "price" --all          # include text/paragraph nodes
 patchright-cli find "hide" --limit=50      # default limit is 20
+patchright-cli find --role=button --description="Deletes"  # role + accessible description
 ```
 
+The snapshot never shows accessible descriptions (`aria-describedby`,
+`aria-description`, a `title` that is not the name). To target an element by
+one, use `find --role=<role>` with `--name` and/or `--description`: substring
+and case-insensitive, `/regex/i`, or whole with `--exact`. It returns refs.
+
 `find` searches links, buttons, inputs and headings by default — the things
 you can act on. Use `--all` when you are looking for page *content* rather
 than a control.
@@ -174,13 +182,13 @@ controls stay distinguishable:
 
 ```
   # table > rowgroup > cell "407 points by pluc 4 hours ago | hide | 321 ..."
-- link "hide": [ref=e49]
+- link "hide" [ref=e49]:
   - /url: hide?id=49489982
 ```
 
-Refs from `find` are numbered across the whole page and are immediately
-usable with `click`, `fill`, and the rest. They stay valid until the next
-`snapshot` or `find`.
+Refs from `find` are the same refs `snapshot` prints and are immediately
+usable with `click`, `fill`, and the rest. A hit with no ref of its own (a
+`text:` line or an `option`) names the element to act on as `[in=e12]`.
 
 When output says `Found 20 of 340 matches`, narrow the query rather than
 raising `--limit`.
@@ -198,6 +206,8 @@ drop <ref> --path=./file.png  # Drop file onto element (HTML5 drop from outside)
 drop <ref> --data="text/plain=hello"  # Drop arbitrary MIME data
 ```
 
+`drop` fails (exit 1) when the target does not accept drops, meaning its `dragover` handler does not call `preventDefault()`. Before, it reported success without anything being dropped. Drop onto the element that handles the drop, not onto a wrapper around it.
+
 ### Form input
 
 ```bash
@@ -235,14 +245,6 @@ press <key>                   # Keypress (Enter, ArrowDown, etc.)
 keydown <key> / keyup <key>   # Hold/release key
 ```
 
-### Mouse
-
-```bash
-mousemove <x> <y>             # Move to coordinates
-mousedown / mouseup           # Button down/up
-mousewheel <dx> <dy>          # Scroll wheel
-```
-
 ### Tabs
 
 ```bash
@@ -306,7 +308,7 @@ dialog-dismiss                # Dismiss next dialog
 ### DevTools
 
 ```bash
-console                       # Show console messages
+console                       # Start capture / show captured console messages
 console warning               # Filter by level
 network                       # Show network requests (each line is `#<id> METHOD STATUS URL`)
 requests                      # Alias for `network`
@@ -318,6 +320,38 @@ highlight <ref>               # Persistent overlay on element [--style=CSS]
 highlight <ref> --hide        # Remove overlay; `highlight --hide` clears all
 ```
 
+The first `console` call starts CDP Runtime capture across this session's existing
+and future pages, including popups. Earlier messages are unavailable: call it
+before reproducing an issue, then again to read messages. Capture makes CDP
+detectable until the session closes; `console --clear` only clears the buffer.
+
+A highlight is page-visible while shown (an `<x-pw-glass>` element under `<html>`);
+`--hide` removes the element once no highlight is left. `pick-locator` refuses to
+run without `--detectable`: Playwright's recorder then stays in every page of the
+session (`window.playwright`, `__pw_*` globals, an `<x-pw-glass>` element it
+re-adds) until the session closes, so use a throwaway session for it.
+
+### Debugger (step through a command's browser calls)
+
+```bash
+debugger-pause                # Arm: the next page action, navigation or eval pauses
+click e3                      # Replies at once: "Paused before: Evaluate (held: `click e3`)"
+snapshot                      # Other commands still run while paused, actions included
+debugger-step                 # Run that call, pause before the next ("Click ...")
+debugger-resume               # Let the held command finish, turn the debugger off
+debugger-status               # off | armed | paused + call title and held command
+```
+
+This is Playwright's action debugger, not a JavaScript debugger: it holds
+patchright-cli's own calls in the driver, sends nothing to Chrome, and page
+scripts keep running, so pages cannot detect it. Only page actions, navigation,
+`eval` and element getters pause; `snapshot`, `title`, cookies, `state-save`,
+`tab-new` and `highlight` run straight through (the reply says so) and leave it
+armed. While one call is held, other commands, actions included, run at once,
+so their side effects can land before the held one's. After `debugger-step` the
+debugger stays armed until `debugger-resume`, which also cancels an armed pause
+nothing has hit. `close` while paused resumes and closes.
+
 ### Recording and capture
 
 ```bash
@@ -352,36 +386,201 @@ set-media print               # screen | print
 clear-media
 ```
 
-### Storage
-
-```bash
-cookie-list / cookie-get / cookie-set / cookie-delete / cookie-clear
-cookie-export / cookie-import
-localstorage-list / localstorage-get / localstorage-set / localstorage-delete / localstorage-clear
-sessionstorage-list / sessionstorage-get / sessionstorage-set / sessionstorage-delete / sessionstorage-clear
-state-save <file> / state-load <file>
-```
-
-### Network
-
-```bash
-route "<pattern>" [options]   # Mock requests (--status, --body, --content-type, --header)
-route-list / unroute          # Manage routes
-network-state-set offline     # Simulate offline
-network-state-set online      # Restore connectivity
-```
-
-### Sessions
-
-```bash
-list                          # List active sessions
-close-all                     # Close all sessions
-kill-all                      # Force-kill all + stop daemon
-delete-data                   # Delete session profile data
-profile-list                  # List profiles, size, and which session uses each
-profile-delete <name>         # Delete an idle named profile
-grant-permissions <perms>     # Grant browser permissions
-```
+### Network mocking
+
+`route "<pattern>"` mocks matching requests (`--status`, `--body`,
+`--content-type`, `--header`); `route-list` and `unroute` manage them, and
+`network-state-set offline|online` simulates connectivity.
+
+### Passkeys (WebAuthn)
+
+Run a `passkey-*` command, such as `passkey-list`, BEFORE the page calls
+`navigator.credentials.create()` or `.get()`. The first one installs a virtual
+authenticator in the session; until then the page gets Chrome's native OS
+passkey dialog and the ceremony hangs. Then `passkey-list` shows what the page
+registered, `passkey-add <rp-id>` seeds one, and `passkey-export` /
+`passkey-import` keep passkeys across sessions (the export holds private keys).
+
+## Command reference
+
+Every command, its flags and what it does. `patchright-cli <command> --help`
+shows one command's flag defaults and examples; `patchright-cli` with no
+arguments shows whether the daemon is up and which sessions are open.
+
+<!-- BEGIN GENERATED: commands (scripts/gen_skill.py from COMMAND_SPECS; do not edit by hand) -->
+```bash
+# Core
+open [url] [--block-networks] [--headed] [--webmcp]  # Open browser (starts daemon if needed)
+attach --cdp=<url> [--cdp-headers] [--cdp-timeout] [--block-networks]  # Attach to running Chrome via CDP
+goto <url>                              # Navigate to URL
+click <ref> [button] [--modifiers] [--scroll]  # Click element
+dblclick <ref> [button] [--modifiers]   # Double-click element
+fill <ref> <value> [--submit]           # Fill text into element
+type <text> [--submit]                  # Type text via keyboard
+hover <ref> [--scroll]                  # Hover over element
+select <ref> <value>                    # Select dropdown option
+check <ref> [--scroll]                  # Check checkbox/radio
+uncheck <ref>                           # Uncheck checkbox/radio
+snapshot [ref] [--selector] [--filename] [--depth] [--interactive] [--boxes]  # Take accessibility snapshot
+find <text> [--regex] [--all] [--limit] [--role] [--name] [--description] [--exact]  # Search the snapshot for matching elements
+eval <expr> [ref] [--file]              # Evaluate JavaScript (expression, --file or stdin)
+text <ref|selector>                     # Get text content of element
+html [ref] [--selector] [--include-shadow] [--filename] [--max-chars]  # Print page HTML, or one element's outerHTML
+screenshot [ref] [--full-page] [--hires] [--filename]  # Save screenshot
+drag <from> <to> [--scroll]             # Drag element to target
+drop <ref> [--path] [--data]            # Drop file/data onto element (fails if it does not accept drops)
+close                                   # Close browser session (or the --tab it is addressed to)
+detach                                  # Detach attached session (keep external browser running)
+
+# Navigation
+go-back                                 # Go back
+go-forward                              # Go forward
+reload                                  # Reload page
+url                                     # Print current URL
+title                                   # Print page title
+
+# Keyboard
+press <key>                             # Press key
+keydown <key>                           # Key down
+keyup <key>                             # Key up
+
+# Mouse
+mousemove <x> <y>                       # Move mouse
+mousedown [button]                      # Mouse button down
+mouseup [button]                        # Mouse button up
+mousewheel <dx> <dy>                    # Scroll mouse wheel
+
+# Scroll & Wait
+scroll <dx> <dy>                        # Scroll by pixel offset
+scroll-to <ref>                         # Scroll element into view
+wait [ms] [--url]                       # Wait for milliseconds, or for a URL
+wait-for <ref> [--state]                # Wait for element to reach a state
+
+# Tabs
+tab-list                                # List tabs
+tab-new [url]                           # Open new tab
+tab-close [index]                       # Close tab
+tab-select <index>                      # Switch to tab (default tab only)
+
+# Dialog
+dialog-accept [text]                    # Accept next dialog
+dialog-dismiss                          # Dismiss next dialog
+
+# Upload/Resize
+upload <file> [ref]                     # Upload file to input
+resize <w> <h>                          # Resize viewport
+
+# Emulation
+set-color-scheme <dark|light|no-preference>  # Emulate prefers-color-scheme
+clear-color-scheme                      # Stop emulating prefers-color-scheme
+set-reduced-motion <reduce|no-preference>  # Emulate prefers-reduced-motion
+clear-reduced-motion                    # Stop emulating prefers-reduced-motion
+set-forced-colors <active|none>         # Emulate forced-colors
+clear-forced-colors                     # Stop emulating forced-colors
+set-contrast <more|no-preference>       # Emulate prefers-contrast
+clear-contrast                          # Stop emulating prefers-contrast
+set-media <screen|print>                # Emulate CSS media type
+clear-media                             # Stop emulating the CSS media type
+
+# State
+state-save [file]                       # Save cookies+storage to JSON
+state-load <file>                       # Load saved state
+
+# Storage
+cookie-list [--domain] [--path]         # List cookies
+cookie-get <name>                       # Get cookie
+cookie-set <name> <value> [--domain] [--path] [--expires] [--httpOnly] [--secure] [--sameSite]  # Set cookie
+cookie-delete <name>                    # Delete cookie
+cookie-clear                            # Clear all cookies
+cookie-import <file>                    # Import cookies from JSON
+cookie-export [file]                    # Export cookies to JSON
+localstorage-list                       # List localStorage
+localstorage-get <key>                  # Get localStorage item
+localstorage-set <key> <value>          # Set localStorage item
+localstorage-delete <key>               # Delete localStorage item
+localstorage-clear                      # Clear localStorage
+sessionstorage-list                     # List sessionStorage
+sessionstorage-get <key>                # Get sessionStorage item
+sessionstorage-set <key> <value>        # Set sessionStorage item
+sessionstorage-delete <key>             # Delete sessionStorage item
+sessionstorage-clear                    # Clear sessionStorage
+
+# Passkeys
+passkey-list [--rp-id] [--id]           # List virtual passkeys; run before the page uses WebAuthn
+passkey-add <rp-id> [--id] [--user-handle] [--private-key] [--public-key] [--sign-count]  # Seed a virtual passkey
+passkey-delete <id>                     # Delete a virtual passkey by credential id
+passkey-clear [--rp-id]                 # Delete all virtual passkeys
+passkey-export [file] [--rp-id]         # Export virtual passkeys with private keys to an owner-only JSON
+passkey-import <file>                   # Seed virtual passkeys from a passkey-export file
+
+# Permissions
+grant-permissions <perms> [--origin]    # Grant comma-separated permissions
+
+# Route
+route <pattern> [--status] [--body] [--content-type] [--header] [--remove-header]  # Mock requests matching a URL pattern
+route-list                              # List active routes
+unroute [pattern]                       # Remove route(s)
+network-state-set <online|offline>      # Set online/offline
+
+# Code
+run-code <code> [--file]                # Run raw JS in page context (code, --file or stdin)
+
+# Tracing
+tracing-start                           # Start Playwright tracing
+tracing-stop                            # Stop tracing and save
+
+# Video
+video-start [--fps]                     # Start video recording
+video-stop [--filename]                 # Stop recording and save
+video-chapter <title>                   # Add chapter marker to video
+video-show-actions [--duration] [--position]  # Annotate actions in the recording
+video-hide-actions                      # Stop annotating actions
+
+# PDF
+pdf [--filename]                        # Save page as PDF
+
+# DevTools
+console [level] [--clear]               # Start session-wide CDP capture and show messages; earlier messages are unavailable (detectable)
+network [--static] [--clear]            # Show network requests
+requests [--static] [--clear]           # Alias for `network`
+request <id> [--body]                   # Show full detail for a network request
+generate-locator <ref>                  # Emit Playwright locator expression for a ref
+pick-locator [--detectable] [--wait] [--cancel]  # Wait for a person to click an element; print its locator (page-detectable: needs --detectable)
+highlight <ref> [--style] [--hide]      # Show overlay on element (page-detectable while shown; removed on --hide)
+
+# Debugger
+debugger-pause                          # Pause before the next page action, navigation or eval; that command replies at once, held
+debugger-step                           # Run the paused call and pause before the next one; prints the held command's result
+debugger-resume                         # Let the held command finish and print its result (or cancel an unhit pause)
+debugger-status                         # Show the debugger state: off, armed, or the paused call and held command
+
+# WebMCP
+webmcp-list                             # List the WebMCP tools the page registers
+webmcp-call <name> [json] [--params]    # Call a WebMCP tool the page registers
+
+# Session
+list                                    # List sessions
+close-all                               # Close all sessions
+kill-all [--force]                      # Kill all sessions and stop the daemon
+delete-data                             # Delete this session's profile
+
+# Profiles
+profile-list                            # List profiles, their size and which session uses them
+profile-delete <name>                   # Delete a named profile
+
+# Dashboard
+show [--annotate] [--wait] [--no-open]  # Open session dashboard
+
+# Codegen
+codegen [file]                          # Start recording interactions
+codegen-stop [file]                     # Stop recording and save script
+
+# Setup
+install --skills | --hooks [--uninstall]  # Install agent skill files, or session-start hooks
+mcp [--http] [--host=HOST] [--port=N]   # Start MCP server (stdio by default)
+daemon-info --json                      # Show daemon client protocol and token path without starting it
+```
+<!-- END GENERATED -->
 
 ---
 

patchright_cli/_skills/patchright-cli/references/snapshot-refs.md

@@ -2,97 +2,108 @@
 
 ## How the snapshot system works
 
-patchright-cli uses Playwright's accessibility tree to build a YAML snapshot of all interactive elements on the page. Each element gets a short ref like `e1`, `e5`, `e12`. You use these refs to target elements in commands like `click`, `fill`, `hover`, etc.
+patchright-cli takes Playwright's AI-mode accessibility snapshot of the whole
+page, iframes included, and saves it as YAML. Elements carry Playwright's own
+refs, like `e5` or `f3e5`. You use these refs to target elements in commands
+like `click`, `fill`, `hover`, etc.
 
 ```
 open browser -> snapshot -> read refs -> interact -> snapshot again -> repeat
 ```
 
-Refs are **ephemeral** -- they change every time the page updates. After navigation, form submission, or any dynamic content change, you must re-snapshot to get fresh refs.
+## What a ref is
+
+- A ref names **one element** for as long as that element stays on the page.
+  Taking another snapshot, or acting, does not renumber it; new elements get
+  new numbers.
+- `e5` is an element of the tab's first page. After a navigation (`goto`, a
+  link, `reload`) the page's refs gain a frame prefix, `f3e5`, and refs inside
+  an iframe always have one. Copy refs exactly as printed.
+- A ref whose element was removed or replaced fails at once:
+  `Ref e7 no longer matches an element (removed or changed since the snapshot). Run snapshot.`
+  A ref from a page the tab has left fails with `is from a page this tab has left`.
+  Nothing falls back to "an element with the same role and name", so a stale
+  ref never clicks the wrong element.
+- Refs are **per tab**. A ref that is not in this tab's last snapshot is refused:
+  `e2 is not from a snapshot of this tab; run snapshot (...)`. An element whose role
+  or name changes (a button relabelled "Saved") gets a new ref, so the old one is refused too.
+  After `tab-select`, use the snapshot it prints. A click that opens a popup makes
+  the popup current, and the popup's first-document refs (`e1`, `e2`, ...) can reuse
+  numbers from the opener, so use the snapshot printed after the click.
+- `e5`, `@e5`, `ref=e5` and `[ref=e5]` all work. Anything else is a usage error (exit 2).
 
 ## Snapshot commands
 
 ```bash
 patchright-cli snapshot                        # Full page snapshot
 patchright-cli snapshot e3                     # Subtree rooted at ref e3
-patchright-cli snapshot --depth=2              # Limit tree depth (reduces noise)
+patchright-cli snapshot --selector="#main"     # Subtree under a CSS selector (exactly one match)
+patchright-cli snapshot --depth=2              # Levels 0..2 only
+patchright-cli snapshot -i                     # Interactive elements only
+patchright-cli snapshot --boxes                # [box=x,y,w,h] on each element
 patchright-cli snapshot --filename=snap.yml    # Save to custom filename
-patchright-cli snapshot -i                     # Interactive-only elements
-patchright-cli snapshot --interactive          # Same as -i
 ```
 
-### Options
-
 | Flag | Effect |
 |------|--------|
 | `[ref]` | Show only the subtree rooted at the given ref |
-| `--selector=<css>` | Show only the subtree under a CSS selector. Must match exactly one element |
-| `--depth=N` | Limit depth of the tree (useful for complex pages) |
-| `-i` / `--interactive` | Show only interactive elements (buttons, links, inputs) |
+| `--selector=<css>` | Show only the subtree under a CSS selector. Must match exactly one element that is in the accessibility tree |
+| `--depth=N` | Show levels 0..N. A node whose children were cut ends in `# +N refs` (or `# +more`) |
+| `-i` / `--interactive` | Interactive elements, clickable `generic [cursor=pointer]` nodes, a combobox's options, and the named landmarks and iframes around them. `text:` and `/url:` lines are dropped |
+| `--boxes` | Append `[box=x,y,w,h]`: viewport coordinates in CSS pixels, converted to page coordinates inside iframes |
 | `--filename=F` | Save snapshot to a custom file path |
 
-## When to re-snapshot
-
-Re-snapshot whenever the page state has changed and you need to interact with elements:
+Every view is cut from one full-page snapshot, so the refs it shows are the
+page's refs: a ref from `snapshot e3`, `--depth` or `-i` works with every
+command, and refs outside the printed part keep working too.
 
-- After `goto`, `go-back`, `go-forward`, `reload`
-- After `click` that triggers navigation or DOM changes
-- After form submission
-- After `wait` / `wait-for` for dynamic content
-- After `eval` / `run-code` that modifies the DOM
+## When to re-snapshot
 
-Most state-changing commands (click, fill, goto, etc.) **auto-snapshot** and return the new snapshot. You only need to manually run `snapshot` when the page changes asynchronously or you need a subtree/filtered view.
+Most state-changing commands (click, fill, goto, etc.) **auto-snapshot** and
+return the new snapshot. Re-snapshot yourself when the page changes on its own
+(timers, AJAX), after `eval` / `run-code` that changes the DOM, or when a ref
+reports `no longer matches an element`.
 
 ## Reading the snapshot
 
-The snapshot is a YAML tree. Each element shows:
-- Its **ref** (e.g., `e5`)
-- Its **role** (button, link, textbox, heading, etc.)
-- Its **name** or text content
-- Child elements nested underneath
-
-Example output:
 ```yaml
-- heading "Welcome" [e1]
-  - link "Sign in" [e2]
-- navigation [e3]
-  - link "Home" [e4]
-  - link "About" [e5]
-- main [e6]
-  - textbox "Search" [e7]
-  - button "Go" [e8]
+- heading "Welcome" [level=1] [ref=e2]
+- navigation "Main" [ref=e3]:
+  - link "Home" [ref=e4]:
+    - /url: /
+- main [ref=e6]:
+  - textbox "Search" [ref=e7]
+  - button "Go" [ref=e8]
+  - generic [ref=e9] [cursor=pointer]: Open card
+  - combobox "Size" [ref=e10]:
+    - option "Small" [selected]
+    - option "Large"
+  - iframe [ref=e11]:
+    - button "Pay" [ref=f2e4]
 ```
 
-## Troubleshooting
+- `[active]` marks the focused element, `[cursor=pointer]` a node that looks
+  clickable though its role does not say so.
+- Wrapper `generic` nodes with nothing of their own are not printed; their
+  children move up a level.
+- `text:` lines and `option`s have no ref. Select an option by its label:
+  `select e10 Large`.
 
-### "Could not locate element for ref"
-The page has changed since the last snapshot. Run `snapshot` to get fresh refs and retry.
+## Troubleshooting
 
 ### Element not visible or not interactive
-Some elements are hidden or overlapped. Try:
 - `scroll-to <ref>` to bring the element into view
-- `wait-for <ref>` to wait until the element appears
-- `snapshot -i` to see only interactive elements
-- `snapshot <ref>` to inspect a subtree for nested elements
-- `snapshot --selector="#main"` to scope by CSS when you have no ref yet
-
-### Refs from a scoped snapshot
-
-A scoped snapshot -- `snapshot <ref>` or `snapshot --selector=<css>` -- numbers
-its refs from `e1` within that subtree, and those refs resolve inside the same
-subtree. They are not the numbers a full-page `snapshot` would give, so do not
-mix refs from a scoped snapshot with refs from a full one: take a fresh
-snapshot at the scope you intend to work in.
+- `wait-for <ref>` to wait until it is visible (`--state=hidden` to wait until it goes)
+- `snapshot <ref>` to inspect a subtree
 
 ### Too many elements in snapshot
-Use `--depth=N` to limit tree depth, or snapshot a specific subtree with `snapshot <ref>`. The `-i` flag also helps by filtering to interactive elements only.
+Use `find`, `--depth=N`, `-i`, or `snapshot <ref>`.
 
-### Stale refs after dynamic content
-SPAs and pages with AJAX calls update the DOM without navigation. After triggering dynamic content (e.g., clicking a "Load more" button), wait briefly and re-snapshot:
+### Elements that appear later
 ```bash
-patchright-cli click e5          # Triggers dynamic load
+patchright-cli click e5          # Triggers a dynamic load
 patchright-cli wait 1000         # Wait for content
-patchright-cli snapshot          # Get fresh refs
+patchright-cli snapshot          # Refs for the new elements
 ```
 
 ## `find` — searching the snapshot
@@ -103,14 +114,15 @@ find --regex <pattern>   Regex match; bare patterns are case-insensitive
 find --regex "/p/ims"    Slash form; supported flags are i, m, s
 find --all               Search every node, not just interactive roles + heading
 find --limit=N           Cap rendered hits (default 20)
+find --role=<role>       Elements get_by_role matches (--name, --description, --exact)
 ```
 
 ### What gets searched
 
-By default, roles in `SEARCHABLE_ROLES` — every interactive role plus
-`heading`. This is deliberate: role filtering is the single biggest lever on
-output size. Measured across 13 queries on four real pages it cut hits 4.3x
-(729 to 168); on one Wikipedia query, 442 hits became 53.
+By default, every interactive role plus `heading`. This is deliberate: role
+filtering is the single biggest lever on output size. Measured across 13
+queries on four real pages it cut hits 4.3x (729 to 168); on one Wikipedia
+query, 442 hits became 53.
 
 Matching runs against a node's accessible name. For unnamed nodes such as
 `- text: Star 95.3k`, the value after the colon is used instead. Property
@@ -120,7 +132,8 @@ lines like `- /url: ...` are not nodes and never match.
 
 Per hit: a `  # ancestor > ancestor > parent` breadcrumb (3 deep, names cut at
 45 characters, repeated names collapsed), then the matched node with its ref,
-then its subtree.
+then its subtree. A hit without a ref of its own (an `option`, or a `text:`
+line under `--all`) shows the nearest element you can act on as `[in=e12]`.
 
 `find` prints inline and writes no `.yml` file. `snapshot` still writes one.
 

patchright_cli/_skills/patchright-cli/references/storage-state.md

@@ -80,7 +80,7 @@ patchright-cli state-save auth.json                     # Save cookies + localSt
 patchright-cli state-load auth.json                     # Restore state
 ```
 
-When loading state, navigate to the matching origin first so localStorage can be applied correctly.
+`state-load` replaces the session's state: it first clears the existing cookies, localStorage, IndexedDB and OPFS data, then applies the file. localStorage is applied to every origin in the file; you do not need to visit an origin first.
 
 ## Cookie persistence login pattern