patchright-cli 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

patchright_cli/__init__.py

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

patchright_cli/_skills/patchright-cli/SKILL.md

@@ -9,6 +9,14 @@ patchright-cli drives a real Chrome browser that passes bot detection (Cloudflar
 
 ## Quick start
 
+If `patchright-cli` is not on PATH yet, install it first -- one of:
+
+```bash
+uvx patchright-cli --version                 # run without installing
+pip install patchright-cli                   # or install it
+python -m patchright install chromium        # then fetch the browser, once
+```
+
 ```bash
 patchright-cli open https://example.com     # launch browser + navigate
 patchright-cli snapshot                      # get element refs
@@ -35,33 +43,63 @@ patchright-cli snapshot          # read refs from output
 patchright-cli click e5          # use discovered ref
 ```
 
+## Shell quoting
+
+Quote any URL containing `&`. Unquoted, the shell eats it before patchright-cli
+sees it:
+
+```bash
+# WRONG -- PowerShell 7 treats `&` as the background operator: the command is
+# detached and everything after `&` is run as a separate command.
+# cmd.exe treats it as a command separator. Either way the URL is truncated.
+patchright-cli goto https://example.com/search?q=cats&page=2
+
+# RIGHT -- on any shell
+patchright-cli goto "https://example.com/search?q=cats&page=2"
+```
+
+The same applies to `#` (a bash comment), spaces, and `%` (expanded by
+cmd.exe), and to any argument holding shell metacharacters. Quoting always
+works; leave it on.
+
 ## Global options
 
 These go before the command:
 
 ```bash
 --headless              # Run headless (default: headed -- headed is less detectable)
---persistent            # Use persistent profile (keeps cookies/storage across sessions)
---profile=/path         # Custom profile directory
+--profile=<name>        # Named profile any session can use (default: the session name);
+                        # profiles always persist. A value with / or \ is a directory
 --proxy=<url>           # Proxy server (http, https, socks5) -- supports user:pass@host auth
 -s=mysession            # Named session (default: "default", or PATCHRIGHT_CLI_SESSION env var)
 --port=9322             # Custom daemon port (default: 9321)
 --config=<path>         # Load options from JSON config file
 --cdp=<url>             # Attach to Chrome via CDP endpoint (use with `attach` command)
+--context=new|host      # With `attach`: fresh isolated context (default) or the browser's own
 --device="iPhone 15"    # Emulate a device
+--mobile                # Emulate a generic mobile device (Pixel 7); mobile pages
+                        # are lighter, so snapshots are smaller and cheaper
 --viewport-size=1280x720 # Set viewport size
 --locale=en-US          # Browser locale
 --timezone=America/New_York # Timezone ID
 --geolocation=40.7,-74.0   # Geolocation override (lat,lon)
 --user-agent=<ua>       # Custom user agent string
 --grant-permissions=geolocation,camera  # Grant permissions at launch
---timeout-action=10000  # Default action timeout (ms)
---timeout-navigation=30000 # Default navigation timeout (ms)
 --show-port=9322        # Dashboard port (default: 9322)
 --raw                   # Strip page/snapshot decorations from output
 --json                  # Wrap full response as JSON ({success, output, ...})
 ```
 
+These go *after* the command instead:
+
+```bash
+--timeout=1800          # Daemon idle timeout in seconds before it exits and
+                        # takes the browser (and its login) with it. Default 1800.
+                        # Also settable up front via $PATCHRIGHT_CLI_IDLE_TIMEOUT.
+--timeout-action=10000  # Default action timeout (ms)
+--timeout-navigation=30000 # Default navigation timeout (ms)
+```
+
 ---
 
 ## Core commands
@@ -70,10 +108,11 @@ These go before the command:
 
 ```bash
 open [url]                    # Launch browser (optionally navigate)
-open --persistent             # Keep cookies/storage between runs
+open --profile=work           # Run on a named profile (logins persist; one session at a time)
 open --headless               # Headless mode
-attach --cdp=<url>            # Attach to existing Chrome via CDP
-close                         # Close session (closes the browser)
+attach --cdp=<url>            # Attach to existing Chrome via CDP (fresh, isolated context)
+attach --cdp=<url> --context=host  # Use the Host Context: the browser's own logins, cookies, storage
+close                         # Close session (closes the browser); refused on --context=host -- use detach
 detach                        # Detach an attached session (keeps external browser running)
 ```
 
@@ -92,11 +131,47 @@ title                         # Print page title
 ```bash
 snapshot                      # Full page snapshot
 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
 ```
 
+### Searching instead of snapshotting
+
+On a large page, `find` is the cheaper first move — a full snapshot of a
+Wikipedia article is ~87k tokens; `find` returns a few hundred.
+
+```bash
+patchright-cli find "Sign in"              # substring, case-insensitive
+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
+```
+
+`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.
+
+Each hit prints a `#` breadcrumb showing where it sits, so identical
+controls stay distinguishable:
+
+```
+  # table > rowgroup > cell "407 points by pluc 4 hours ago | hide | 321 ..."
+- 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`.
+
+When output says `Found 20 of 340 matches`, narrow the query rather than
+raising `--limit`.
+
 ### Interaction
 
 ```bash
@@ -138,6 +213,9 @@ screenshot --filename=F       # Custom filename
 scroll <dx> <dy>              # Scroll by pixels
 scroll-to <ref>               # Scroll element into view
 wait <ms>                     # Wait N milliseconds
+wait --url="**/dashboard"     # Wait until the URL matches -- the right tool
+                              # after a login or any redirect. `*` does NOT
+                              # cross a `/`, so use `**`; `/regex/i` also works
 wait-for <ref>                # Wait until element visible
 wait-for <ref> --state=hidden # Wait until hidden
 press <key>                   # Keypress (Enter, ArrowDown, etc.)
@@ -157,10 +235,51 @@ mousewheel <dx> <dy>          # Scroll wheel
 ```bash
 tab-list                      # List open tabs
 tab-new <url>                 # Open new tab
-tab-select <index>            # Switch to tab
-tab-close [index]             # Close tab
+tab-select <index>            # Switch to tab (default tab only; a --tab
+                              # caller is pinned to its own page)
+tab-close [index]             # Close tab (with --context=host, only tabs this session opened)
+```
+
+### Parallel agents: --tab
+
+`--tab <name>` gives a caller its own page, its own refs and its own history
+inside one shared browser -- same fingerprint, same cookies, same login. It is
+the cheap way to parallelise: one Chrome total, not one per agent.
+
+```bash
+patchright-cli --tab inbox-scan open https://app.example.com/inbox
+patchright-cli --tab report-pull open https://app.example.com/reports
+patchright-cli --tab inbox-scan snapshot     # refs belong to this tab only
+patchright-cli tab-list                      # every tab, labelled by owner
+patchright-cli --tab inbox-scan close        # frees this tab; browser stays
+```
+
+**Choose the name once, with a shell-generated suffix.** Nothing enforces
+uniqueness -- two agents on the same name share one page and clobber each
+other. Do not invent the random part yourself; LLM-chosen "random" characters
+collide.
+
+```bash
+TAB="price-scan-$(openssl rand -hex 2)" && echo "$TAB"
+patchright-cli --tab "$TAB" open https://example.com
+# reuse that exact printed name in every later command
 ```
 
+`$PATCHRIGHT_CLI_TAB` sets it for a whole shell, the way `$PATCHRIGHT_CLI_SESSION`
+does for sessions.
+
+Cleanup needs no coordination: every agent runs `close` addressed to its own
+tab, and the browser exits when the last tab goes. On an `attach --context=host`
+session the host's browser never exits: closing tabs leaves it attached, and
+whoever attached runs `detach` at the end.
+
+**`--tab` vs `-s`.** `--tab` shares identity, one browser (~50-150MB per extra
+tab), for agents acting as the same logged-in user. `-s` isolates identity --
+its own profile, cookies and fingerprint, a full Chrome each (~300-500MB) --
+for multi-account work. Tabs share one browser process, so commands from
+different tabs queue behind a slow navigation; separate sessions run fully in
+parallel.
+
 ### Dialogs
 
 Dialogs must be pre-armed *before* the action that triggers them:
@@ -191,11 +310,14 @@ highlight <ref> --hide        # Remove overlay; `highlight --hide` clears all
 ```bash
 screenshot / pdf              # Static capture
 video-start / video-stop      # Video recording
+video-show-actions            # Label each action in the recording [--duration=ms] [--position=P]
+video-hide-actions            # Stop labelling actions
 tracing-start / tracing-stop  # Playwright trace
 codegen / codegen-stop        # Record interactions as script
 resize <w> <h>                # Viewport resize
 upload <file> [ref]           # File upload
 show                          # Live dashboard
+show --annotate               # Ask a human to mark up the page and wait for it
 ```
 
 ### Storage
@@ -224,6 +346,8 @@ 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
 ```
 
@@ -234,13 +358,13 @@ grant-permissions <perms>     # Grant browser permissions
 ### Login flow
 
 ```bash
-patchright-cli open https://example.com/login --persistent
+patchright-cli open --profile=myapp https://example.com/login
 patchright-cli snapshot
 patchright-cli fill e3 "user@example.com"
 patchright-cli fill e5 "password123"
 patchright-cli click e8
 patchright-cli snapshot
-# With --persistent, cookies survive across sessions
+# The login persists in profile "myapp" for any later session that opens it
 ```
 
 ### Extracting data
@@ -278,11 +402,35 @@ patchright-cli click e5                   # This click triggers the dialog
 ```bash
 patchright-cli wait-for e12               # Wait for element
 patchright-cli wait 1000                  # Fixed wait
+patchright-cli wait --url="**/dashboard"  # Wait for a redirect to land
 # For custom conditions, use run-code (see references/running-code.md)
 ```
 
 ---
 
+## Asking a human what to change
+
+`show --annotate` is for design and UI review: it opens a page in the user's
+browser showing a live capture of the current page, they draw on it and write
+what they want changed, and the command returns their drawing plus their notes.
+
+```bash
+patchright-cli show --annotate                  # waits up to 5 minutes
+patchright-cli show --annotate --wait=900       # give them longer
+patchright-cli show --annotate --no-open        # headless box: do not launch a browser
+```
+
+The command **blocks** until they submit, so it opens the review link for them
+rather than printing it. The link is also written to
+`.patchright-cli/annotate-url.txt`, which is how you get it when `--no-open`
+suppressed the browser. You get back the annotated screenshot saved under
+`.patchright-cli/`, their notes, and a fresh snapshot of the page -- enough to
+act on the feedback without asking follow-up questions.
+
+Reach for it when the decision is aesthetic or subjective and you would
+otherwise be guessing: which of two layouts, where an element belongs, whether
+spacing reads right. Do not use it for anything you can check yourself.
+
 ## Anti-detect notes
 
 - Uses real Chrome (not Chromium) -- this is what makes it undetectable
@@ -291,7 +439,8 @@ patchright-cli wait 1000                  # Fixed wait
 - No custom user-agent or headers by default -- preserves Chrome's natural fingerprint
 - Persistent profiles maintain realistic browser history and cookies
 - The daemon architecture means Chrome stays running between commands, behaving like a real user's browser
-- `attach --cdp` lets you connect to an existing Chrome instance
+- `attach --cdp` lets you connect to an existing Chrome instance; add `--context=host` to reuse its logins,
+  cookies and storage (see references/session-management.md)
 
 ## Config files
 
@@ -339,6 +488,16 @@ pip install patchright-cli && patchright-cli install --skills
 # "Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md"
 ```
 
+When an installed copy of this skill drifts from the tool version,
+patchright-cli prints a one-line warning on stderr -- once a day per
+version, so a chained run is not buried in it. Re-run
+`patchright-cli install --skills` to resync, or set
+`PATCHRIGHT_CLI_NO_SKILL_CHECK=1` to silence the check.
+
+`open` also checks PyPI once a day for a newer patchright-cli and prints a
+one-line note when there is one. Set `PATCHRIGHT_CLI_NO_VERSION_CHECK=1` to
+turn that off.
+
 ## Specific tasks
 
 * **Snapshots and element refs** [references/snapshot-refs.md](references/snapshot-refs.md)

patchright_cli/_skills/patchright-cli/references/session-management.md

@@ -21,25 +21,37 @@ patchright-cli open https://example.com    # Uses "myproject" session
 patchright-cli snapshot                    # Same session
 ```
 
-## Persistent profiles
+## Profiles
 
-Use `--persistent` to keep cookies, localStorage, and browser data across sessions:
+Every session you `open` runs on a **profile**: a persistent store of cookies,
+storage, logins and history. (Attached sessions use the browser's own data.) Profiles always persist -- close the session, open it
+again later, and you are still logged in. (`--persistent` is accepted but
+changes nothing.)
 
-```bash
-patchright-cli open https://example.com --persistent
-# ... log in, do work ...
-patchright-cli close
-# Later:
-patchright-cli open https://example.com --persistent
-# Cookies and storage are restored
-```
-
-Profiles are stored at `~/.patchright-cli/profiles/<session-name>`. Use `--profile=/path` to specify a custom profile directory:
+By default the profile is named after the session. `--profile=<name>` picks a
+named profile instead, so any session can use it:
 
 ```bash
-patchright-cli open --persistent --profile=/path/to/my/profile https://example.com
+patchright-cli -s=agent1 open --profile=work https://app.example.com
+# ... log in once, then close ...
+patchright-cli -s=agent1 close
+patchright-cli -s=agent2 open --profile=work https://app.example.com   # still logged in
 ```
 
+- A value containing `/` or `\` is a directory instead of a name:
+  `--profile=/path/to/dir`, `--profile=./browser` (relative to where you run
+  the command). Names use letters, digits, `.`, `_`, `-`.
+- A session name that isn't a valid profile name (e.g. has spaces) needs an
+  explicit `--profile`.
+- One session per profile at a time -- Chrome locks it. A second session asking
+  for a busy profile is refused; run extra agents as `--tab`s on the session that
+  holds it.
+- `profile-list` shows every profile, its size, and which session uses it.
+- `profile-delete <name>` deletes an idle named profile (never a path).
+  `delete-data` deletes only the profile named after the session; for a
+  shared profile use `profile-delete`.
+- Profiles live at `~/.patchright-cli/profiles/<name>`.
+
 ## CDP attach
 
 Connect to an already-running Chrome instance via Chrome DevTools Protocol instead of launching a new one:
@@ -50,6 +62,31 @@ patchright-cli attach --cdp=http://localhost:9222
 
 This is useful for debugging or controlling a browser you launched manually with `--remote-debugging-port`.
 
+By default `attach` opens a fresh Isolated Context inside that browser, so it
+does not see the browser's existing cookies, localStorage or logins. To work in
+the Host Context instead -- the browser's own context, e.g. a Chrome started
+with a persistent `--user-data-dir` -- pass `--context=host`:
+
+```bash
+patchright-cli attach --cdp=http://localhost:9222 --context=host
+```
+
+With `--context=host`:
+
+- Emulation flags (`--device`, `--mobile`, `--viewport-size`, `--locale`,
+  `--timezone`, `--geolocation`, `--user-agent`, `--grant-permissions`) are
+  rejected -- the Host Context's settings are fixed. The same keys in a config
+  file are ignored for this attach.
+- Only one session may use a given Host Context, however its endpoint is
+  spelled. Run extra agents as `--tab`s on that session, or attach them with
+  `--context=new`.
+- The session only closes Pages it opened (`--tab`s, `tab-new`, and popups
+  they spawn). Plain `close` and `delete-data` are refused, and `tab-close`
+  refuses the Host's own tabs: use `detach`. `detach`, `close-all` and
+  `kill-all` close your Pages and leave the Host's tabs and state untouched.
+- If the Host restarts Chrome, re-run the same `attach`: the stale session is
+  replaced automatically and the output says so.
+
 ## Session commands
 
 ```bash
@@ -61,13 +98,39 @@ patchright-cli delete-data                 # Delete default session's profile da
 patchright-cli -s=mysession delete-data    # Delete named session's profile data
 ```
 
+## Concurrent tabs (shared identity)
+
+`--tab <name>` is the cheaper unit of concurrency: one browser, one login, but
+a page, ref registry and navigation history per caller.
+
+```bash
+patchright-cli --tab orders-audit open https://app.example.com/a
+patchright-cli --tab user-export open https://app.example.com/b
+patchright-cli tab-list                      # labelled by owning tab
+patchright-cli --tab orders-audit close      # frees one tab only
+```
+
+`close` releases the tab it is addressed to and the session ends when the last
+tab closes, so concurrent agents clean up without coordinating. A session opened
+only through `--tab` has no default tab in use, so closing the named tabs ends
+it; one opened with a plain `open` keeps its default tab until that is closed
+too. A command
+addressed to a tab that was never opened is an error rather than a silent
+fallback to the default tab -- a typo in a tab name should not quietly drive
+someone else's page.
+
+Named tabs are pinned to their own page, so `tab-select` and popups cannot move
+them; `tab-select` addressed to a named tab is refused rather than silently
+moving somebody else's page. The default tab still follows the index-based
+`tab-select`.
+
 ## Concurrent sessions
 
 You can run multiple sessions simultaneously for parallel workflows:
 
 ```bash
-patchright-cli -s=scrape1 open https://site1.com --persistent
-patchright-cli -s=scrape2 open https://site2.com --persistent
+patchright-cli -s=scrape1 open https://site1.com
+patchright-cli -s=scrape2 open https://site2.com
 # Work with both independently
 patchright-cli -s=scrape1 snapshot
 patchright-cli -s=scrape2 snapshot
@@ -95,7 +158,10 @@ You can also grant permissions at launch with `--grant-permissions=geolocation,c
 
 ## Daemon behavior
 
-The daemon auto-starts on the first command and auto-shuts down after 5 minutes of inactivity. If it ever crashes, the next command will respawn it automatically.
+The daemon auto-starts on the first command and auto-shuts down after 30 minutes of inactivity
+(`--timeout=<seconds>` after the command, or `$PATCHRIGHT_CLI_IDLE_TIMEOUT` up front). A command
+that is still running does not count as inactivity, so a long `show --annotate` will not be cut
+short. If the daemon ever crashes, the next command respawns it automatically.
 
 ## Cleanup best practices
 

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

@@ -26,6 +26,7 @@ patchright-cli snapshot --interactive          # Same as -i
 | 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) |
 | `--filename=F` | Save snapshot to a custom file path |
@@ -73,6 +74,15 @@ Some elements are hidden or overlapped. Try:
 - `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.
 
 ### 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.
@@ -84,3 +94,49 @@ patchright-cli click e5          # Triggers dynamic load
 patchright-cli wait 1000         # Wait for content
 patchright-cli snapshot          # Get fresh refs
 ```
+
+## `find` — searching the snapshot
+
+```
+find <text>              Substring match on the accessible name, case-insensitive
+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)
+```
+
+### 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.
+
+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
+lines like `- /url: ...` are not nodes and never match.
+
+### Output
+
+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.
+
+`find` prints inline and writes no `.yml` file. `snapshot` still writes one.
+
+### Divergence from playwright-cli
+
+playwright-cli's `find` searches all nodes and returns grep-style +/-3 lines of
+context. This one defaults to interactive roles and returns the matched
+subtree with a breadcrumb. Across 13 queries on four real pages, total output
+was 13KB here against 37KB there (a single lookup is a few hundred bytes). `--all` widens the search to every node like
+playwright-cli's does, but each hit still renders as a full subtree rather
+than +/-3 lines of context — on content-heavy pages a matching container can
+print its entire subtree, plus its matching descendants again as their own
+hits (Hacker News `find "comments"` returned 45% of the page this way).
+
+### When hits are truncated
+
+`Found 20 of 340 matches` means the query is too broad. Narrow it — a longer
+substring, or a regex anchored with `\b`. Raising `--limit` just buys more
+tokens for the same ambiguity.

patchright_cli/_skills/patchright-cli/references/video-recording.md

@@ -27,6 +27,30 @@ patchright-cli video-stop
 
 Chapters are saved as a JSON file alongside the video.
 
+### Action callouts
+
+Label each action in the recording as it happens: a badge naming the action
+and the element, plus a ring around the target.
+
+```bash
+patchright-cli video-start
+patchright-cli video-show-actions                      # 600ms, top-right
+patchright-cli video-show-actions --duration=1200 --position=bottom-left
+patchright-cli click e5                                # renders: click button "Sign in"
+patchright-cli video-hide-actions                      # stop annotating
+patchright-cli video-stop
+```
+
+`--position` takes `top-left`, `top-right`, `bottom-left`, or `bottom-right`.
+
+The callout is drawn *before* the action, because a click can navigate away
+or detach the element. It is `pointer-events: none` and `aria-hidden`, so it
+neither blocks the interaction nor shows up in `snapshot`.
+
+Callouts are only drawn while a recording is running -- the flag persists
+across `video-start` / `video-stop`, but outside a recording the page is left
+alone.
+
 ## Codegen (interaction recording)
 
 Record your browser interactions and save them as a replayable bash script:
@@ -47,8 +71,15 @@ patchright-cli screenshot                              # Page screenshot
 patchright-cli screenshot e3                           # Element screenshot by ref
 patchright-cli screenshot --filename=page.png          # Custom filename
 patchright-cli screenshot --full-page                  # Full scrollable page
+patchright-cli screenshot --hires                      # Capture at device pixel ratio
 ```
 
+Screenshots capture one image pixel per CSS pixel. That matches the desktop
+default (device pixel ratio 1), so `--hires` only changes anything under
+`open --mobile` or `open --device=...`, where the ratio is 2-3x and `--hires`
+produces a correspondingly larger file.
+
+
 Screenshots save to `.patchright-cli/` in the current directory.
 
 ## PDF capture