patchright-cli 0.10.0__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.10.0"
+__version__ = "0.11.0"

patchright_cli/_skills/patchright-cli/SKILL.md

@@ -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
 
@@ -149,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
@@ -165,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.
@@ -176,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`.
@@ -200,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
@@ -300,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`
@@ -312,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,6 +392,15 @@ clear-media
 `--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`
@@ -361,24 +410,25 @@ 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]  # Open browser (starts daemon if needed)
+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]      # Click element
+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>                             # Hover over element
+hover <ref> [--scroll]                  # Hover over element
 select <ref> <value>                    # Select dropdown option
-check <ref>                             # Check checkbox/radio
+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]  # Search the snapshot for matching elements
+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>                        # Drag element to target
-drop <ref> [--path] [--data]            # Drop file/data onto element
+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)
 
@@ -455,6 +505,14 @@ 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
 
@@ -472,7 +530,7 @@ tracing-start                           # Start Playwright tracing
 tracing-stop                            # Stop tracing and save
 
 # Video
-video-start                             # Start video recording
+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
@@ -482,12 +540,23 @@ video-hide-actions                      # Stop annotating actions
 pdf [--filename]                        # Save page as PDF
 
 # DevTools
-console [level] [--clear]               # Show console messages
+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
-highlight <ref> [--style] [--hide]      # Show overlay on element
+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

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