patchright-cli 0.10.0__tar.gz → 0.11.1__tar.gz

{patchright_cli-0.10.0 → patchright_cli-0.11.1}/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Anti-detect browser automation CLI & Skills for AI agents, powered by Patchright",
-    "version": "0.10.0"
+    "version": "0.11.1"
   },
   "plugins": [
     {

{patchright_cli-0.10.0 → patchright_cli-0.11.1}/.github/workflows/ci.yml

@@ -22,10 +22,10 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ["3.10", "3.12"]
+        python-version: ["3.12", "3.13"]
         include:
           - os: macos-latest
-            python-version: "3.12"
+            python-version: "3.13"
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v7

{patchright_cli-0.10.0 → patchright_cli-0.11.1}/CLAUDE.md

@@ -50,11 +50,11 @@ Three-component client-daemon-browser design:
 CLI (cli.py) --TCP:9321--> Daemon (daemon.py) --Patchright--> Chrome
 ```
 
-- **CLI (`src/patchright_cli/cli.py`)**: Stateless thin client. Parses argv manually (not click subcommands), builds a JSON `{command, args, options, cwd}` message, sends it over a length-prefixed TCP socket to the daemon, prints the response, and exits. All commands are defined in the `COMMAND_SPECS` dict (usage, summary, flags, examples; `COMMANDS_HELP` and `ALL_COMMANDS` derive from it) and grouped for the manual in `COMMAND_CATEGORIES`. With no arguments it prints the home view (`_print_home`): live daemon state from an already-running daemon only, never starting one. `--toon` renders a reply's `data` field with `toon.py`.
+- **CLI (`src/patchright_cli/cli.py`)**: Stateless thin client. Parses argv manually (not click subcommands), builds a JSON `{command, args, options, cwd}` message, sends it over a length-prefixed TCP socket to the daemon, prints the response, and exits. All commands are defined in the `COMMAND_SPECS` dict (usage, summary, flags, examples; `COMMANDS_HELP` and `ALL_COMMANDS` derive from it) and grouped for the manual in `COMMAND_CATEGORIES`. With no arguments it prints the home view (`_print_home`): live daemon state from an already-running daemon only, never starting one. `--toon` renders a reply's `data` field with `toon.py`. A failed reply, whatever the daemon's wording, prints through `_failure_lines()`: `error: <message>`, detail lines, then `help: <next step>` lines (exit 1, or 2 when the reply carries `exit_code: 2`); `--json` adds `error`/`help` fields.
 
 - **Daemon (`src/patchright_cli/daemon.py`)**: Long-running async process managing browser sessions. Auto-spawned on `open` via `ensure_daemon_running()` which launches a subprocess. Uses `DaemonState` → multiple `Session` objects, each owning a Patchright persistent browser context. Command dispatch uses `@register()` decorated handlers in `COMMAND_HANDLERS` dict, dispatched by `handle_command()`. Console capture uses CDP sessions (not Playwright's `page.on('console')`) because Patchright suppresses it.
 
-- **Snapshot (`src/patchright_cli/snapshot.py`)**: Uses Playwright's native `aria_snapshot()` to get the accessibility tree. `RefRegistry` annotates each node with sequential refs (`e1`, `e2`, ...). Snapshots are saved as YAML to `.patchright-cli/` in the caller's cwd.
+- **Snapshot (`src/patchright_cli/snapshot.py`, `snapshot_text.py`)**: One full-page `page.aria_snapshot(mode="ai")` per tab (kept as `Tab.last_raw`) gives Playwright's own refs (`e5`, `f3e5` in iframes and after navigation); `page.get_by_ref` resolves them. Any other `aria_snapshot()` call replaces the page's ref map, so `snapshot.py` is the only caller (a unit test greps for it) and scoping, `--depth`, `-i` and `find` are text operations in `snapshot_text.py`. `scripts/ref_sweep/` is the before/after sweep of every ref-taking command; rerun it on a patchright bump. Snapshots are saved as YAML to `.patchright-cli/` in the caller's cwd.
 
 ## Key Design Decisions
 
@@ -63,7 +63,8 @@ CLI (cli.py) --TCP:9321--> Daemon (daemon.py) --Patchright--> Chrome
 - Default daemon port: 9321, profiles stored at `~/.patchright-cli/profiles/<profile-name>`; a session's profile defaults to its session name (`--profile=<name>` overrides, a value with `/` or `\` is a directory). One session per profile at a time
 - CLI-daemon protocol: length-prefixed (4-byte big-endian `!I`) JSON over TCP; every message carries a `token` field read from `~/.patchright-cli/daemon-<port>.token` (written 0600 by the daemon before it listens), and the daemon rejects messages without the right one
 - CLI parses argv manually in `main()` — click is only used for `click.echo()`, not subcommands. New commands need a `COMMAND_SPECS` entry, a place in `COMMAND_CATEGORIES`, and a `@register("<name>")` handler in daemon.py, then `python scripts/gen_skill.py` to refresh the generated command block in `skills/patchright-cli/SKILL.md` (`--check` exits 1 when stale; `tests/test_skill_sync.py` enforces it); only session and lifecycle commands (open, attach, close, kill-all, ...) live in `handle_command()` itself
+- Flag and positional value shapes (numbers, choices, flags that need a value) live in `src/patchright_cli/values.py` (`FLAG_KINDS`, `ARG_KINDS`); the CLI checks them before contacting the daemon (exit 2) and the daemon checks them again for clients that skip the CLI. A new numeric or enum flag needs an entry there (`tests/test_cli_audit.py` enforces it)
 - Version must be updated in `pyproject.toml`, `src/patchright_cli/__init__.py` and `.claude-plugin/marketplace.json` (then run `uv lock` to sync the lock file; `tests/test_packaging.py` checks they match)
 - `python -m patchright_cli` works via `__main__.py`
-- Uses hatchling as build backend, ruff for linting (line-length=120, target py310)
+- Uses hatchling as build backend, ruff for linting (line-length=120, target py312)
 - Ruff rules: E, F, I, W, UP, B, SIM (ignores E501, SIM105, E402)

{patchright_cli-0.10.0 → patchright_cli-0.11.1}/CONTRIBUTING.md

@@ -31,7 +31,7 @@ pre-commit install
 
 ## Code Style
 
-- Python 3.10+
+- Python 3.12+
 - Formatted with [Ruff](https://github.com/astral-sh/ruff) (enforced via pre-commit)
 - Keep the daemon lightweight — avoid heavy dependencies
 

{patchright_cli-0.10.0 → patchright_cli-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchright-cli
-Version: 0.10.0
+Version: 0.11.1
 Summary: Anti-detect browser automation CLI using Patchright (undetected Playwright fork)
 Project-URL: Homepage, https://github.com/AhaiMk01/patchright-cli
 Project-URL: Repository, https://github.com/AhaiMk01/patchright-cli
@@ -14,16 +14,14 @@ Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
 Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: click
-Requires-Dist: patchright
+Requires-Dist: patchright<1.65,>=1.64
 Requires-Dist: pywin32>=306; sys_platform == 'win32'
 Requires-Dist: pyyaml
 Provides-Extra: dev
@@ -85,7 +83,7 @@ curl -s https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/docs/inst
 </details>
 
 > [!IMPORTANT]
-> **Requirements:** Python 3.10+ and Google Chrome
+> **Requirements:** Python 3.12+ and Google Chrome
 
 ```bash
 # Recommended — always runs latest version, no install needed
@@ -235,7 +233,7 @@ graph LR
 |-----------|------|
 | **Daemon** (`daemon.py`) | Long-running process managing browser sessions via Patchright. Auto-starts on first `open`. |
 | **CLI** (`cli.py`) | Thin client — connects, sends command, prints result, disconnects. Browser stays open. |
-| **Snapshot** (`snapshot.py`) | Playwright `aria_snapshot()` accessibility tree, annotated with sequential `[ref=eN]` handles for element targeting. |
+| **Snapshot** (`snapshot.py`) | Playwright's AI-mode `aria_snapshot()` accessibility tree, iframes included, with Playwright's own `[ref=e5]` handles, resolved with `get_by_ref`. |
 
 ### Daemon token
 
@@ -295,6 +293,10 @@ patchright-cli find "text"             # Search snapshot for text
 patchright-cli find --regex "a|b"      # Search by regex
 patchright-cli find "text" --all       # Include text/paragraph nodes
 patchright-cli find "text" --limit=50  # Cap hits (default 20)
+patchright-cli find --role=button --description="Deletes"  # By role + accessible name/description
+patchright-cli html                    # Page HTML (first 8000 chars; --max-chars=0 for all)
+patchright-cli html --include-shadow --filename=page.html  # With open shadow roots, to a file
+patchright-cli html e5                 # One element's outerHTML (or --selector=CSS)
 patchright-cli eval <expr>             # Run JavaScript
 patchright-cli eval --file=script.js   # Run JS from file
 patchright-cli run-code <code>         # Run JS with return value
@@ -400,6 +402,19 @@ patchright-cli sessionstorage-delete <key>
 patchright-cli sessionstorage-clear
 ```
 
+### Passkeys
+A virtual WebAuthn authenticator for testing passkey sign-ups and logins. The first `passkey-*` command installs it in the session, overriding `navigator.credentials.create()` / `.get()` in every page (a page can notice the override, so it stays off until asked for). **Run a `passkey-*` command (e.g. `passkey-list`) before the page calls WebAuthn**: until then the page gets Chrome's native OS passkey dialog and hangs. Passkeys live in the session only; use `passkey-export` / `passkey-import` to keep them (the export holds private keys and is written owner-only; keep it out of version control).
+```bash
+patchright-cli passkey-list                      # Installs the authenticator, lists passkeys (no keys shown)
+patchright-cli passkey-list --rp-id=example.com
+patchright-cli passkey-add example.com           # Seed a new P-256 passkey
+patchright-cli passkey-add example.com --id=<b64url> --user-handle=<b64url> --private-key=<b64url> --public-key=<b64url> --sign-count=5
+patchright-cli passkey-delete <credential-id>
+patchright-cli passkey-clear [--rp-id=example.com]
+patchright-cli passkey-export passkeys.json      # Includes private keys
+patchright-cli passkey-import passkeys.json
+```
+
 ### Request Mocking
 ```bash
 patchright-cli route "**/*.jpg" --status=404
@@ -416,7 +431,8 @@ patchright-cli unroute                 # Remove all routes
 ```bash
 patchright-cli tracing-start
 patchright-cli tracing-stop            # Saves .zip trace file
-patchright-cli video-start             # Start video recording (CDP screencast)
+patchright-cli video-start             # Start real-time video recording at 25 fps (CDP screencast)
+patchright-cli video-start --fps=60    # Another frame rate, 1-60
 patchright-cli video-stop              # Stop and save video (requires ffmpeg for .webm)
 patchright-cli video-stop --filename=recording.webm
 patchright-cli show --annotate          # Ask a human to mark up the page, wait for it
@@ -436,11 +452,24 @@ patchright-cli network-state-set online   # Restore connectivity
 
 ### DevTools
 ```bash
-patchright-cli console                 # All console messages
+patchright-cli console                 # Start capture / show captured console messages
 patchright-cli console warning         # Filter by level
 patchright-cli console --clear         # Clear after printing
 ```
 
+The first `console` call enables CDP Runtime capture for every page in the session,
+including tabs and popups opened later. Messages from before capture starts are
+unavailable: run `console` before reproducing an issue, then call it again to read
+the messages. Capture can make automation detectable and stays enabled until the
+session closes; `--clear` only clears the message buffer. A new session starts
+with capture disabled.
+
+Two DevTools commands leave traces a page can see. `highlight` draws inside an
+`<x-pw-glass>` element under `<html>`; `highlight --hide` removes it once no
+highlight is left. `pick-locator` runs only with `--detectable`: it installs
+Playwright's recorder, which puts `window.playwright`, `__pw_*` globals and an
+`<x-pw-glass>` element into every page of the session until the session closes.
+
 ### Output
 ```bash
 patchright-cli --raw eval --file=s.js  # Raw output (no page/snapshot decoration)

{patchright_cli-0.10.0 → patchright_cli-0.11.1}/README.md

@@ -48,7 +48,7 @@ curl -s https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/docs/inst
 </details>
 
 > [!IMPORTANT]
-> **Requirements:** Python 3.10+ and Google Chrome
+> **Requirements:** Python 3.12+ and Google Chrome
 
 ```bash
 # Recommended — always runs latest version, no install needed
@@ -198,7 +198,7 @@ graph LR
 |-----------|------|
 | **Daemon** (`daemon.py`) | Long-running process managing browser sessions via Patchright. Auto-starts on first `open`. |
 | **CLI** (`cli.py`) | Thin client — connects, sends command, prints result, disconnects. Browser stays open. |
-| **Snapshot** (`snapshot.py`) | Playwright `aria_snapshot()` accessibility tree, annotated with sequential `[ref=eN]` handles for element targeting. |
+| **Snapshot** (`snapshot.py`) | Playwright's AI-mode `aria_snapshot()` accessibility tree, iframes included, with Playwright's own `[ref=e5]` handles, resolved with `get_by_ref`. |
 
 ### Daemon token
 
@@ -258,6 +258,10 @@ patchright-cli find "text"             # Search snapshot for text
 patchright-cli find --regex "a|b"      # Search by regex
 patchright-cli find "text" --all       # Include text/paragraph nodes
 patchright-cli find "text" --limit=50  # Cap hits (default 20)
+patchright-cli find --role=button --description="Deletes"  # By role + accessible name/description
+patchright-cli html                    # Page HTML (first 8000 chars; --max-chars=0 for all)
+patchright-cli html --include-shadow --filename=page.html  # With open shadow roots, to a file
+patchright-cli html e5                 # One element's outerHTML (or --selector=CSS)
 patchright-cli eval <expr>             # Run JavaScript
 patchright-cli eval --file=script.js   # Run JS from file
 patchright-cli run-code <code>         # Run JS with return value
@@ -363,6 +367,19 @@ patchright-cli sessionstorage-delete <key>
 patchright-cli sessionstorage-clear
 ```
 
+### Passkeys
+A virtual WebAuthn authenticator for testing passkey sign-ups and logins. The first `passkey-*` command installs it in the session, overriding `navigator.credentials.create()` / `.get()` in every page (a page can notice the override, so it stays off until asked for). **Run a `passkey-*` command (e.g. `passkey-list`) before the page calls WebAuthn**: until then the page gets Chrome's native OS passkey dialog and hangs. Passkeys live in the session only; use `passkey-export` / `passkey-import` to keep them (the export holds private keys and is written owner-only; keep it out of version control).
+```bash
+patchright-cli passkey-list                      # Installs the authenticator, lists passkeys (no keys shown)
+patchright-cli passkey-list --rp-id=example.com
+patchright-cli passkey-add example.com           # Seed a new P-256 passkey
+patchright-cli passkey-add example.com --id=<b64url> --user-handle=<b64url> --private-key=<b64url> --public-key=<b64url> --sign-count=5
+patchright-cli passkey-delete <credential-id>
+patchright-cli passkey-clear [--rp-id=example.com]
+patchright-cli passkey-export passkeys.json      # Includes private keys
+patchright-cli passkey-import passkeys.json
+```
+
 ### Request Mocking
 ```bash
 patchright-cli route "**/*.jpg" --status=404
@@ -379,7 +396,8 @@ patchright-cli unroute                 # Remove all routes
 ```bash
 patchright-cli tracing-start
 patchright-cli tracing-stop            # Saves .zip trace file
-patchright-cli video-start             # Start video recording (CDP screencast)
+patchright-cli video-start             # Start real-time video recording at 25 fps (CDP screencast)
+patchright-cli video-start --fps=60    # Another frame rate, 1-60
 patchright-cli video-stop              # Stop and save video (requires ffmpeg for .webm)
 patchright-cli video-stop --filename=recording.webm
 patchright-cli show --annotate          # Ask a human to mark up the page, wait for it
@@ -399,11 +417,24 @@ patchright-cli network-state-set online   # Restore connectivity
 
 ### DevTools
 ```bash
-patchright-cli console                 # All console messages
+patchright-cli console                 # Start capture / show captured console messages
 patchright-cli console warning         # Filter by level
 patchright-cli console --clear         # Clear after printing
 ```
 
+The first `console` call enables CDP Runtime capture for every page in the session,
+including tabs and popups opened later. Messages from before capture starts are
+unavailable: run `console` before reproducing an issue, then call it again to read
+the messages. Capture can make automation detectable and stays enabled until the
+session closes; `--clear` only clears the message buffer. A new session starts
+with capture disabled.
+
+Two DevTools commands leave traces a page can see. `highlight` draws inside an
+`<x-pw-glass>` element under `<html>`; `highlight --hide` removes it once no
+highlight is left. `pick-locator` runs only with `--detectable`: it installs
+Playwright's recorder, which puts `window.playwright`, `__pw_*` globals and an
+`<x-pw-glass>` element into every page of the session until the session closes.
+
 ### Output
 ```bash
 patchright-cli --raw eval --file=s.js  # Raw output (no page/snapshot decoration)

{patchright_cli-0.10.0 → patchright_cli-0.11.1}/docs/daemon-protocol.md

@@ -72,9 +72,29 @@ Every reply carries an explicit boolean `success` and a string `output`, on
 both success and failure. `success: false` indicates authentication, command,
 or daemon errors. `output` contains the result or a human-readable error.
 Additional fields, such as `snapshot_path`, are command-specific. Clients must
-ignore unknown fields. No structured error codes are currently provided.
+ignore unknown fields.
 
-Clients can detect these states in failed replies by matching these output
+### Error codes
+
+A failed reply in one of these states carries a string `code`. Branch on it
+rather than on `output`, whose wording can change in any release:
+
+| `code` | State |
+| --- | --- |
+| `session_not_open` | The requested session is absent. |
+| `tab_not_open` | The requested named tab is absent from the session, including one whose page closed or crashed outside the daemon. `open --tab <name>` opens it again. |
+| `target_closed` | The page, context or browser closed under the command. Also the default tab's page closed or crashed outside the daemon (a person, the page, the Host, or a renderer crash): the default tab does not move to another page on its own, so pick one with `tab-select <index>` or open one with `tab-new`. An `open` or `attach` that fails while starting a new session never carries it. A command whose own action closes its page (a popup's "Done" button) succeeds and says the page closed. |
+| `no_page` | The session is open but has no pages left, whether they were closed with `tab-close`, closed outside the daemon, or crashed. The session stays open; `tab-new` opens a page. |
+
+A page closed or crashed outside the daemon leaves the session as soon as Chrome reports it: `tab-list` stops listing it. A crashed page cannot be reloaded, since Patchright fails every later call on it, so the session closes it (in a Host Context, only a page the session opened). While the default tab has no page, `tab-close <index>` still works; `tab-close` without an index is refused rather than closing a neighbour.
+
+Other failures carry no `code`; more codes can be added later, so treat an
+unknown one like a missing one. Successful replies, including the no-ops below,
+never carry `code`. Daemons before 0.11.1 send no codes under the same
+`protocol`, so a client that may meet one keeps the output fragments below as
+its fallback.
+
+Clients can also detect these states in failed replies by matching these output
 fragments. Surrounding context and recovery advice can vary. The fragments in
 this table are part of the protocol:
 
@@ -120,21 +140,28 @@ fewer items than exist, `total` holds the full count.
 | `profile-list` | `[{"name", "size", "session"}]`, where `size` is bytes and `session` is the holding session or `null` |
 | `find` | `[{"ref", "role", "name"}]`, plus `total` when `--limit` cut the hits |
 
+`console` opts the session into CDP Runtime capture on existing and future pages.
+Earlier messages are unavailable; the first response explains this and the CDP
+detection risk. Capture lasts until the session closes; `--clear` only clears the
+buffer. If capture fails on a live page, the response has `success: false` and any
+available messages; another `console` call retries pages that failed.
+
 An empty list is `[]`, and its `output` states the zero explicitly, for example
 `0 cookies in this session`. Commands not listed here send no `data`. More
 fields or commands can gain `data` later, so read only the keys you need.
 
-Best effort, not covered by the compatibility rules below: a command on a page,
-context or browser that has closed usually fails with Playwright's own message
-containing `has been closed`. That text comes from Playwright and can change
-with its version without a protocol increment.
+A command on a page, context or browser that has closed fails with
+`code: "target_closed"`. Its `output` is Playwright's own message, usually
+containing `has been closed`; that text can change with Playwright's version
+without a protocol increment, so match the code instead.
 
 ## Compatibility
 
 `protocol` is independent of the package version. Any incompatible change to
 framing, request limits, request fields (`command`, `args`, `options`, `cwd`,
-`token`), reply fields (`success`, `output`), authentication, or the
-state-detection fragments in the table above requires a protocol increment.
+`token`), reply fields (`success`, `output`), authentication, the error
+codes, or the state-detection fragments in the tables above requires a
+protocol increment. Adding an error code does not.
 Raising a request limit is not incompatible. Optional additive fields and new
 commands do not require an increment. Clients can reject unsupported protocol
 versions before sending requests.

{patchright_cli-0.10.0 → patchright_cli-0.11.1}/docs/installation.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- Python 3.10+
+- Python 3.12+
 - Google Chrome installed on the system
 
 ## Install

{patchright_cli-0.10.0 → patchright_cli-0.11.1}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "patchright-cli"
-version = "0.10.0"
+version = "0.11.1"
 description = "Anti-detect browser automation CLI using Patchright (undetected Playwright fork)"
 license = "Apache-2.0"
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 readme = "README.md"
 authors = [
     { name = "zpahai" },
@@ -15,15 +15,15 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Topic :: Internet :: WWW/HTTP :: Browsers",
     "Topic :: Software Development :: Testing",
 ]
 dependencies = [
-    "patchright",
+    # Refs come from patchright 1.64's aria_snapshot(mode="ai") and get_by_ref; re-run
+    # scripts/ref_sweep before widening this.
+    "patchright>=1.64,<1.65",
     "pyyaml",
     "click",
     "aiohttp>=3.9",
@@ -74,7 +74,7 @@ dev = [
 ]
 
 [tool.ruff]
-target-version = "py310"
+target-version = "py312"
 line-length = 120
 src = ["src"]
 

patchright_cli-0.11.1/scripts/ref_sweep/classify.py

@@ -0,0 +1,207 @@
+"""Classify every step that differs between two sweep results; fail on any step no rule explains.
+
+    python scripts/ref_sweep/classify.py results/before.json results/after.json > results/diff-report.md
+
+Each rule names the steps it covers and why the difference is intended. A step
+the rules do not cover is printed as UNEXPLAINED and the exit code is 1.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+COMPARED = ("exit", "out", "state", "snapshot", "missing_targets")
+
+# (category, reason, predicate over (step id, before, after))
+RULES = [
+    (
+        "snapshot format",
+        "Native AI-mode YAML: Playwright's own refs printed verbatim (`f1e5` after a navigation), bare `generic` "
+        "wrappers hoisted, `[active]`/`[cursor=pointer]` tags, refs after a node's key instead of after its colon, "
+        "iframe content included, options and `text:` lines without refs. `--depth` now cuts lines (with `# +N refs`) "
+        "where it used to only hide tags; `-i` drops non-interactive lines where it used to only hide tags; scoped "
+        "snapshots show page refs instead of renumbering from e1.",
+        lambda sid, b, a: (
+            "snapshot" in b["argv"][:2]
+            and b["exit"] == a["exit"]
+            and b.get("missing_targets") == a.get("missing_targets")
+        ),
+    ),
+    (
+        "find output",
+        "Same search over the new YAML: refs are the page's refs (`f1e28`), ref-less hits show `[in=<ref>]`, and "
+        "iframe content is searchable. find --role maps matches through a depth-0 probe (same matches, native refs).",
+        lambda sid, b, a: b["argv"][0] == "find" and b["exit"] == a["exit"],
+    ),
+    (
+        "--boxes no longer times out",
+        "Old --boxes resolved every ref with a 30 s bounding_box and timed out (controls page > 90 s); native "
+        "boxes=True takes ~0.2 s, iframe boxes shifted to page coordinates (iframe:snapshot-boxes f4e4 "
+        "[box=332,91,58,21] equals the page box measured in iframe:inner-submit-page-box).",
+        lambda sid, b, a: sid == "controls:snapshot-boxes" and b["exit"] == -1 and a["exit"] == 0,
+    ),
+    (
+        "iframe elements are actionable",
+        "The old snapshot had no iframe content, so no ref existed (`missing_targets`); native refs (`f4e3`) reach "
+        "into the same-origin iframe.",
+        lambda sid, b, a: (
+            sid.startswith("iframe:") and b.get("missing_targets") and not a.get("missing_targets") and a["exit"] == 0
+        ),
+    ),
+    (
+        "refs outside a scoped view keep working",
+        "A scoped snapshot used to replace the registry with subtree-local refs, so a page ref then failed; every "
+        "view is now cut from one full snapshot.",
+        lambda sid, b, a: (
+            sid in ("controls:outside-ref-after-selector", "controls:outside-ref-after-ref-scope")
+            and b["exit"] == 1
+            and a["exit"] == 0
+        ),
+    ),
+    (
+        "stale ref refused instead of acting on another element",
+        "Old role/name/nth lookup silently hit a different element after a DOM change or navigation (state log shows "
+        "item-a2 / stay2 / rerender clicked); native refs fail fast with `no longer matches an element`, `is from a "
+        "page this tab has left`, or the tab guard.",
+        lambda sid, b, a: sid.startswith("nav:stale-") and a["exit"] == 1,
+    ),
+    (
+        "new ref error wording",
+        "Unknown/stale ref errors name the cause: tab guard `is not from a snapshot of this tab; run snapshot (...)`, "
+        "`is from a page this tab has left`. Same exit code.",
+        lambda sid, b, a: (
+            b["exit"] == a["exit"] == 1
+            and re.search(r"not found|Re-run", b["out"])
+            and re.search(r"is not from a snapshot of this tab|is from a page this tab has left", a["out"])
+        ),
+    ),
+    (
+        "malformed ref is a usage error",
+        '`click nonsense` exits 2 with `"nonsense" is not a ref (refs look like e5 or f3e5, from snapshot)`.',
+        lambda sid, b, a: sid == "controls:bad-ref-word" and a["exit"] == 2,
+    ),
+    (
+        "ref from the previous document refused",
+        "`@e1` named the first document's root; after the navigations the page's refs are `f1e*`, and the old code "
+        "resolved `e1` by role/name on the new page. The tab guard refuses it.",
+        lambda sid, b, a: sid == "controls:bad-ref-at" and b["exit"] == 0 and a["exit"] == 1,
+    ),
+    (
+        "select names the mistake",
+        "A ref given as the option fails at once with the label hint instead of a 30 s select_option timeout; a "
+        "missing option's timeout lists the combobox's options.",
+        lambda sid, b, a: (
+            sid in ("controls:select-ref-as-option", "controls:select-missing-option") and b["exit"] == a["exit"]
+        ),
+    ),
+    (
+        "ref names in output",
+        "Same result, with the native ref in the message (`Highlighted f1e18.`, pick-locator `### Ref - f1e5`) or "
+        'the locator in Playwright\'s call log (`locator("aria-ref=f8e4")` instead of `get_by_role(...)`).',
+        lambda sid, b, a: (
+            b["exit"] == a["exit"]
+            and (re.search(r"\b(f\d+)?e\d+\b", a["out"]) or "aria-ref=" in a["out"])
+            and a.get("state") == b.get("state")
+        ),
+    ),
+    (
+        "pick-locator now finds the ref",
+        "Old matching only tried role-based picks (an id-based `#save2` pick got no ref) and capped candidates; the "
+        "depth-0 probe maps any picked element, including inside the iframe.",
+        lambda sid, b, a: "pick-" in sid and "### Ref" in a["out"] and b["exit"] == a["exit"] == 0,
+    ),
+    (
+        "cascade: page state from earlier steps",
+        "Same step result; the fixture's click log / field values differ only because earlier steps now succeed "
+        "(iframe fills, refs outside a scoped view) or no longer act on a wrong element.",
+        lambda sid, b, a: (
+            b["exit"] == a["exit"] and _same_shape(b["out"], a["out"]) and b.get("log_delta") == a.get("log_delta")
+        ),
+    ),
+]
+
+
+def _add_log_deltas(steps: list[dict]) -> None:
+    """What each step itself appended to the fixture's click log, so a cascade cannot hide a different action."""
+    prev = ""
+    for step in steps:
+        state = step.get("state")
+        log = state.get("log", "") if isinstance(state, dict) else None
+        if log is None:
+            continue
+        step["log_delta"] = log[len(prev) :] if log.startswith(prev) else log
+        prev = log
+
+
+NOTES = """## Notes
+
+- Known residual, identical before and after: `tabs:a-ref-in-b-same-number`. Two tabs that are both on
+  their first document can print the same ref (`e3`); the tab guard cannot tell them apart, so tab b's
+  `e3` is clicked. Both versions do this; SKILL.md says refs are per tab and to use the snapshot that
+  `tab-select` prints.
+- Ref numbers are Playwright's: the page is on a later document by the time most steps run, so refs read
+  `f1e18` where the old registry printed `e19`. The sweep's argv names targets by role and name, so the
+  steps still line up.
+- Timing (ms, CLI round trip): controls `snapshot --boxes` 90016 (timeout) -> ~210; offscreen `--boxes`
+  ~4250 -> ~215; large `--boxes` ~2700 -> ~250; plain large `snapshot` unchanged (~220).
+"""
+
+
+def _same_shape(x: str, y: str) -> bool:
+    strip = lambda s: re.sub(r"\b(f\d+)?e\d+\b", "<ref>", s)  # noqa: E731
+    return strip(x) == strip(y)
+
+
+def main() -> int:
+    runs = []
+    for path in sys.argv[1:3]:
+        steps = json.loads(Path(path).read_text(encoding="utf-8"))["steps"]
+        _add_log_deltas(steps)
+        keyed: dict[str, dict] = {}
+        for step in steps:  # repeated ids get #2, #3 like sweep.py diff
+            key, n = step["id"], 2
+            while key in keyed:
+                key, n = f"{step['id']}#{n}", n + 1
+            keyed[key] = step
+        runs.append(keyed)
+    before, after = runs
+    by_rule: dict[str, list[str]] = {name: [] for name, _, _ in RULES}
+    unexplained = []
+    for sid, b in before.items():
+        a = after.get(sid)
+        if a is None:
+            unexplained.append(f"{sid} (missing after)")
+            continue
+        if not [f for f in COMPARED if b.get(f) != a.get(f)]:
+            continue
+        for name, _, match in RULES:
+            if match(sid, b, a):
+                by_rule[name].append(f"{sid} (exit {b['exit']} -> {a['exit']})")
+                break
+        else:
+            unexplained.append(sid)
+
+    differing = sum(len(v) for v in by_rule.values()) + len(unexplained)
+    print("# Ref sweep: before (RefRegistry) vs after (native aria refs)\n")
+    print(
+        f"{len(before)} steps; {len(before) - differing} identical; {differing} differ; {len(unexplained)} unexplained.\n"
+    )
+    for name, reason, _ in RULES:
+        if by_rule[name]:
+            print(f"## Intended: {name} ({len(by_rule[name])})\n\n{reason}\n")
+            for line in by_rule[name]:
+                print(f"- {line}")
+            print()
+    print(NOTES)
+    if unexplained:
+        print(f"## UNEXPLAINED ({len(unexplained)})\n")
+        for sid in unexplained:
+            print(f"- {sid}")
+    return 1 if unexplained else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

patchright_cli-0.11.1/scripts/ref_sweep/fixtures/common.js

@@ -0,0 +1,9 @@
+// Sweep harness: fixtures record what happened to them in a data attribute on
+// <html>. `eval` runs in an isolated world that cannot see page globals, but it
+// can read the DOM, so the log lives there (and stays out of the aria tree).
+function log(msg) {
+  const root = document.documentElement;
+  root.dataset.log = (root.dataset.log ? root.dataset.log + ' ' : '') + msg;
+}
+document.addEventListener('click', e => log('click:' + (e.target.id || e.target.tagName)), true);
+document.addEventListener('dblclick', e => log('dblclick:' + (e.target.id || e.target.tagName)), true);

patchright_cli-0.11.1/scripts/ref_sweep/fixtures/controls.html

@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><title>Controls</title><script src="common.js"></script></head>
+<body>
+  <h1>Controls</h1>
+  <section aria-label="Form">
+    <label>Name <input id="name" type="text"></label>
+    <label>Bio <textarea id="bio"></textarea></label>
+    <label><input id="agree" type="checkbox"> I agree</label>
+    <label><input id="r1" type="radio" name="size" value="s"> Small</label>
+    <label><input id="r2" type="radio" name="size" value="l"> Large</label>
+    <label>Color
+      <select id="color"><option value="red">Red</option><option value="green">Green</option><option value="blue">Blue</option></select>
+    </label>
+    <label>Avatar <input id="avatar" type="file"></label>
+    <button id="go" type="button" onclick="log('go')">Go</button>
+    <button id="dbl" type="button" ondblclick="log('dbl')">Double me</button>
+    <button id="hov" type="button" onmouseenter="log('hover')">Hover me</button>
+    <a id="anchor" href="#section-two">Jump to two</a>
+    <button id="star" type="button" aria-label="">&#9733;</button>
+    <button id="say" type="button">Say "hi"</button>
+  </section>
+  <section aria-label="Duplicates">
+    <h2>Duplicates</h2>
+    <ul>
+      <li><button id="save1" type="button">Save</button></li>
+      <li><button id="save2" type="button">Save</button></li>
+      <li><button id="save3" type="button">Save</button></li>
+    </ul>
+    <a id="dup-link-1" href="#a">More</a> <a id="dup-link-2" href="#b">More</a>
+  </section>
+  <section aria-label="Drag">
+    <h2 id="section-two">Drag</h2>
+    <div id="src" draggable="true" role="button" aria-label="Drag source"
+         ondragstart="event.dataTransfer.setData('text/plain','src')">Drag source</div>
+    <div id="dst" role="region" aria-label="Drop target" style="width:200px;height:60px;border:1px solid #888"
+         ondragover="event.preventDefault()"
+         ondrop="event.preventDefault(); log('drop:' + event.dataTransfer.getData('text/plain') + ':' + Array.from(event.dataTransfer.files).map(f => f.name).join(','))">Drop here</div>
+  </section>
+  <section aria-label="Pick">
+    <button type="button">Pick me</button>
+    <button type="button">Pick me</button>
+  </section>
+  <p id="para">Plain paragraph text for find --all.</p>
+</body>
+</html>