mendwright 0.3.0__tar.gz → 0.4.0__tar.gz

mendwright-0.4.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and version numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While the version starts with 0, a minor release can change the public API.
+
+## [Unreleased]
+
+## [0.4.0] - 2026-10-12
+
+- Heals without a model (see the [guide](https://github.com/saadbuilt/mendwright/blob/main/docs/guide.md#heals-without-a-model)). Each time a key's selector matches, mendwright saves a fingerprint of the element: its tag, the attributes that survive redesigns, its text or label, and its ancestors, never an input's value. When the selector breaks, mendwright scores the page's elements against it first, and heals with no model call when one element scores at least 0.40, no other comes within 0.12, it shares an id, test id, name, link, label or text with the recorded element (the same numbers and words, allowing a typo, a plural or a filler word), and it sits inside the recorded containers that are still on the page. The pick goes through the same checks as a model's. With no provider configured, these heals still happen. It is on by default; `mendwright.open(fingerprint=False)`, `MENDWRIGHT_FINGERPRINT=0` or `MENDWRIGHT_DISABLE=1` turns it off. On the benchmark it healed 20 of 35 broken selectors with no wrong heal, with thresholds tuned on those same cases.
+- No changes per step (see the [guide](https://github.com/saadbuilt/mendwright/blob/main/docs/guide.md#no-changes-per-step)): `page = mendwright.open(page).page` on Playwright, sync or async, and `driver = mendwright.open(driver).driver` on Selenium. `page.locator(selector)`, the page shortcuts that take a selector, and `find_element()` with `By.XPATH`, `By.CSS_SELECTOR`, `By.ID` or `By.NAME` go through `heal.locator()`, with the selector as the key. Reads, `set_input_files`, `focus` and `find_element()` keep Playwright's and Selenium's own answer for a hidden element or several matches, and heal only a selector that matches nothing. Everything else goes to the real object, and `.native` is that object. A `find_element()` that can't find or heal the element raises an `AttentionRequired` that is also Selenium's `NoSuchElementException`.
+- `heal.locator(..., intent="the terms checkbox in the signup form")` describes an element in words (see the [guide](https://github.com/saadbuilt/mendwright/blob/main/docs/guide.md#describing-an-element-with-intent)). It is saved with the key, redacted, and given to the model on one line of the prompt (the reference gateway builds the same line). With `role=` and no selector, a model finds the element on first use, and the saved XPath is used from then on.
+- `mendwright fix` writes confirmed heals back into your code (see the [guide](https://github.com/saadbuilt/mendwright/blob/main/docs/guide.md#mendwright-fix)). It prints a diff of the string literals it would change, and `--apply` writes them, checking that each Python file still parses and changed only in the planned strings. It leaves alone keys marked destructive, heals inside an iframe, unconfirmed heals (unless `--include-unconfirmed`), keys whose old selector is a bare word, a key in `heal.locator(key, ...)` and `role=` or `text=` values, and a selector passed where only CSS runs, such as `By.CSS_SELECTOR`, and lists each with the reason.
+- `mendwright report --format html` writes one self-contained page (no scripts, nothing loaded from the network) with the keys, recent heals, flow events and quarantines, and `--out FILE` writes any format to a file.
+- `mendwright doctor` says whether the fingerprint tier is on, and `--json` has a `fingerprint` entry.
+- `HealEvent` has a `source`: `"fingerprint"`, `"model"` or `"intent"`. The journal's `heal.proposed`, `heal.rejected` and `heal.applied` carry the same `source`, and a fingerprint heal has `"provider": "fingerprint"`.
+- Drivers can have an optional `fingerprint(selector, frame_chain=())`, which the built-in Playwright and Selenium drivers have.
+- The benchmark runs the fingerprint tier first, as `mendwright.open()` does. `--no-fingerprint` measures the provider alone, and the results show which tier made each heal.
+- Flow changes (see the [guide](https://github.com/saadbuilt/mendwright/blob/main/docs/guide.md#flow-changes)):
+  - `heal.interrupt(key, selector, action="click", args=(), role=None)` registers a step that can show up at any point, such as a cookie banner, a newsletter modal or an "are you still there?" dialog. mendwright handles it when it is in the way of a step (the step's element is missing, the page shows it before an action, or an action fails because something covered the element), then goes on with the step. A failed action is retried once, and only after an interruption was handled, never when Playwright's call log says the action was already done. At most 3 are handled per step. An interruption is never healed, and a later `heal.locator()` for its key is skipped when the element isn't there. When an action fails because its element was covered or couldn't be reached and no interruption matched, one WARNING names the ones mendwright looked for, since one whose selector no longer matches is the likeliest cause.
+  - `mendwright.open(page, cookies="reject")` or `cookies="accept"` registers an interruption for the consent banners of OneTrust, Cookiebot, Didomi, TrustArc, Usercentrics, Quantcast Choice, Osano, cookieconsent, CookieYes and Complianz, with a fallback for other banners. The fallback acts only inside a short element that mentions cookies and holds no text field or navigation, so a consent screen that isn't about cookies (an OAuth Allow, a terms step) or a button such as Close account is never clicked. It is off by default.
+  - `heal.locator(..., optional=True)` skips a step whose element isn't there instead of healing it. Proxies have `.present`, which is False for a skipped step, and its actions do nothing.
+  - The prompt tells the model it may answer `{"xpath": null, "reason": "..."}` when no element on the page fits the step, and not to pick an element that is only similar. Providers report that as "the model says no element on this page fits: <reason>", and the reference gateway passes it on. The prompt also names the page path and the path where the key was last found.
+  - All of this works the same in `mendwright.aio`, where actions awaited together look for interruptions one at a time.
+  - New journal events: `flow.interrupt`, `flow.skip` and `flow.page_guard`.
+- `mendwright demo` shows a cookie banner that now opens first and covers the form, handled as a registered interruption. `StandInPage` takes a `url=` and knows an overlay that blocks clicks until it is closed.
+- An accuracy benchmark in `benchmarks/`: 47 cases where a redesign breaks a selector (12 of them where the right answer is no heal, 4 of those a step that moved to another page), a harness that runs them through `mendwright.open()` with any provider or a model-free baseline, and the baseline results. It is not part of the package. See [docs/benchmark.md](https://github.com/saadbuilt/mendwright/blob/main/docs/benchmark.md).
+
+### Changed
+
+- `heal.page` on a Playwright healer is now a stand-in for the page (`HealingPage`, or `AsyncHealingPage` in `mendwright.aio`), and `heal.driver` on a Selenium healer is a stand-in for the WebDriver (`HealingDriver`). They pass `isinstance()` checks, and `.native` is the real page or driver. `heal.driver` on Playwright and `heal.page` on Selenium are as before.
+- With no provider configured, a broken selector heals when its fingerprint finds the element with confidence. The `mendwright.open()` warning, `mendwright doctor` and the pytest header say so.
+- `overrides.json` now stores a `fingerprint` for every key whose selector matched while the tier is on, not only for healed keys, and an `intent` when you pass one. The file is written when a fingerprint changes. [SECURITY.md](https://github.com/saadbuilt/mendwright/blob/main/SECURITY.md) lists what a fingerprint holds.
+- A fingerprint heal doesn't count toward the hourly rate limit, and isn't reported to the provider's `report_outcome()`.
+- A key is no longer healed on a page other than the last few its element was found on. The store saves those pages (`lastPage` and `pages` in `overrides.json`, at most 5; numbers, uuids and other generated ids in a path count as one page), and such a heal is declined before any model call with an error that says the flow looks changed. Pass `heal_across_pages=True` to `mendwright.open()` to heal there anyway, for example after a redesign that only changed the URL. Pages loaded with `page.set_content()` (`about:blank`) are never compared.
+
+## [0.3.0] - 2026-10-11
+
+First public release. Earlier versions were developed privately as selfheal and never published.
+
+- Drivers for Playwright (sync and async, including patchright and camoufox) and Selenium, behind one `mendwright.open(page)`. `heal.locator(key, selector)` takes XPath, CSS or Playwright selectors. A heal is always an XPath.
+- Providers for Anthropic, OpenAI and compatible APIs, Gemini, Bedrock, LiteLLM, Ollama and your own gateway. `auto_provider()` picks one from the environment, and there is no default model. `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` are honoured for proxies and compatible hosts.
+- Local checks before a heal is used: not an index-only path, not quarantined or superseded for the key, one match in the captured HTML, the step's role, and one visible match on the live page that still has the role. A heal whose action fails is quarantined, and the quarantine blocks the same element, not just the same selector string.
+- Keys you mark as destructive are never healed and never sent to a model: `destructive=True` in `heal.locator()`, `mendwright.open(destructive_keys=...)`, or `"destructive": true` in a seed file. mendwright doesn't guess this from the key or the page.
+- Page capture removes scripts, styles, comments and head metadata, and redacts values, URLs and long numbers, including in broken selectors and expected text. Direct providers have an hourly rate limit and an optional spend cap.
+- A pytest plugin: the `heal` fixture, an overridable `mendwright_provider` fixture, and `--mendwright-strict`, which also fails reruns from pytest-rerunfailures. Heals from a passing test are confirmed.
+- The `mendwright` command: `demo` (offline, or `--live` with the model from your environment), `doctor` and `report`.
+- Heals are saved in `.mendwright/overrides.json`, with a journal next to it. A corrupt store raises instead of being overwritten. Each applied heal prints one line to stderr.
+- Python 3.10 to 3.14, with lxml as the only dependency.
+
+### Changed
+
+From the private builds. If you never used them under the name selfheal, you can skip this.
+
+- On Selenium, the handle for a candidate inside an iframe is a `FramedElement`. `driver.execute_script()` and `ActionChains` need `el.in_frame(lambda e: ...)` to get an element that still works in the frame (see the [guide](https://github.com/saadbuilt/mendwright/blob/main/docs/guide.md#selenium)).
+
+[Unreleased]: https://github.com/saadbuilt/mendwright/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/saadbuilt/mendwright/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/saadbuilt/mendwright/releases/tag/v0.3.0

{mendwright-0.3.0 → mendwright-0.4.0}/CONTRIBUTING.md

@@ -129,17 +129,20 @@ The modules:
 
 - `selectors.py`: `classify()` (XPath, CSS or Playwright engine selector), `check_syntax()`, `normalize()` and `InvalidSelector`.
 - `drivers/`: `base.py` holds the `Driver` protocol, the shared describe and inventory scripts, and the fallback helpers. `registry.py` has `wrap()` and `register_driver()`. The built-in drivers are `playwright_sync.py`, `playwright_async.py` (used by `mendwright.aio`) and `selenium.py`, which handles frames, implicit waits and the verb mapping.
+- `fingerprint.py`: the fingerprint tier. `FINGERPRINT_JS` reads an element in one round trip and `from_raw()` normalizes it; `find()` scores the elements of a captured page against a stored fingerprint and returns a unique XPath only for a confident match.
+- `proxies.py`: `heal.page` and `heal.driver`, the page and driver stand-ins that send selector lookups through `heal.locator()` and everything else to the real object.
 - `resolver.py`: `resolve()` and `present()`. Tries the candidates in order and polls until the timeout, then raises `AttentionRequired`, or `InvalidSelector` when no candidate can run.
-- `facade.py`: `mendwright.open()`, `Healer` and `ActionProxy`. Puts the selectors from your code first, reads the role from the page, never acts through a saved heal on a key marked destructive, and runs actions, quarantining a heal whose action fails.
+- `facade.py`: `mendwright.open()`, `Healer` and `ActionProxy`. Puts the selectors from your code first, reads the role from the page, never acts through a saved heal on a key marked destructive, and runs actions, quarantining a heal whose action fails. It also handles interruptions, optional steps and the page guard.
+- `flow.py` and `interruptions.py`: page paths, interception errors and the texts for flow changes; `heal.interrupt()`'s checks and the selectors of the `cookies=` preset.
 - `aio.py`: `mendwright.aio.open()` and `AsyncHealer`. A heal runs the sync coordinator in a worker thread, which reaches the page through `SyncBridge`.
-- `coordinator.py`: `HealCoordinator` and `resolve_with_heal()`. Runs the checks before any model call, builds the bundle, asks the provider (with one re-prompt on rejection), applies, journals, and keeps the reason for `explain()`.
+- `coordinator.py`: `HealCoordinator` and `resolve_with_heal()`. Runs the checks before any heal, tries the fingerprint tier, builds the bundle, asks the provider (with one re-prompt on rejection), applies, journals, and keeps the reason for `explain()`.
 - `validation.py` and `gate.py`: `validate()` checks a proposal against the captured HTML with lxml; `live_match()` checks it against the page through the driver. `client.apply()` runs both.
 - `store.py` and `roles.py`: the seed and override layers, candidate status, per-key metadata, the lock file and the merge; and the role vocabulary.
 - `capture.py`: `build_bundle()`, `redact()` and `clean_html()`.
 - `providers/`: the `HealProvider` protocol (`base.py`), the built-in providers, `auto_provider()` (`detect.py`) and the error text (`_errors.py`). `prompt.py` holds the one prompt every provider uses.
 - `limits.py` and `journal.py`: the rate limit and spend cap for direct providers, and the JSONL journal.
 - `publish.py`: writes a confirmed selector into a seed JSON file.
-- `cli.py` and `demo/`: the `mendwright` command and the demo that ships in the wheel.
+- `cli.py` and `demo/`: the `mendwright` command and the demo that ships in the wheel. `fixback.py` is `mendwright fix`, and `report_html.py` is `mendwright report --format html`.
 - `pytest_plugin.py`: the `heal` fixture, confirmation from test results, strict mode and the summary.
 
 ## Writing a driver
@@ -158,6 +161,7 @@ A driver wraps one live page or session.
 | `outer_html(scope=None)` | expected | The HTML the checks run against. |
 | `act_on(native, verb, *args, **kwargs)` | optional | Run a Playwright-style verb on a `handle()` result. Without it, `driver_act_on()` calls `getattr(native, verb)(*args, **kwargs)`. |
 | `describe(selector, frame_chain=())` | optional | `{'tag', 'role', 'text', 'outer_html'}` for a single match, else `None`. Without it, `driver_describe()` returns `None` and the role is guessed from the selector text. |
+| `fingerprint(selector, frame_chain=())` | optional | The fingerprint (see `mendwright/fingerprint.py`) of the one element the selector matches, else `None`. Run `FINGERPRINT_JS` on the match and pass the result through `from_raw()`. Without it, `driver_fingerprint()` returns `None` and the fingerprint tier never has anything to look for. |
 | `inventory(limit=200)` | optional | Up to `limit` rows of `{'tag', 'role', 'id', 'name', 'text', 'aria_label'}` for buttons, links, inputs, selects, textareas and `[role]` elements. Without it, `driver_inventory()` returns `[]`. |
 
 Rules:

{mendwright-0.3.0 → mendwright-0.4.0}/MANIFEST.in

@@ -1,7 +1,7 @@
 # The sdist carries what it needs to run the offline test suite from the tarball.
 # Explicit patterns rather than graft, so __pycache__ and .pyc files never get in.
 # Each pattern must match at least one file, or the build prints a warning.
-include CHANGELOG.md CONTRIBUTING.md SECURITY.md CODE_OF_CONDUCT.md
+include CHANGELOG.md CONTRIBUTING.md SECURITY.md
 recursive-include tests *.py *.html
 recursive-include examples/demo *.py *.html *.md
 # The reference gateway and its config: tests/test_gateway_worker.py checks the worker

{mendwright-0.3.0 → mendwright-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mendwright
-Version: 0.3.0
+Version: 0.4.0
 Summary: Self-healing selectors for Playwright and Selenium. When a selector breaks, a model suggests a new one, mendwright checks it against the page, and the step is retried.
 Author: saadbuilt
 License-Expression: MIT
@@ -67,15 +67,15 @@ Dynamic: license-file
 Self-healing selectors for Playwright and Selenium.
 
 [![PyPI](https://img.shields.io/pypi/v/mendwright)](https://pypi.org/project/mendwright/)
-[![Python versions](https://img.shields.io/pypi/pyversions/mendwright)](https://pypi.org/project/mendwright/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mendwright?cacheSeconds=3600)](https://pypi.org/project/mendwright/)
 [![CI](https://github.com/saadbuilt/mendwright/actions/workflows/ci.yml/badge.svg)](https://github.com/saadbuilt/mendwright/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/saadbuilt/mendwright/blob/main/LICENSE)
 
 </div>
 
-When a site update breaks a selector, mendwright asks a model for a new XPath, checks it against the live page, saves it, and retries the step. On the next run the saved selector is used and the model isn't called.
+mendwright heals many broken selectors without any API key. Each time a selector matches, it saves a fingerprint of the element: its tag, ids, names, label, text and surroundings. When a site update breaks the selector, mendwright looks for that element first, checks the new XPath against the live page, saves it, and retries the step. It asks a model only when the fingerprint match isn't confident. On the next run the saved selector is used and nothing is asked.
 
-Supports Anthropic, OpenAI and compatible APIs, Gemini, Bedrock, LiteLLM, or a local model through Ollama.
+For the model it supports Anthropic, OpenAI and compatible APIs, Gemini, Bedrock, LiteLLM, or a local model through Ollama.
 
 ## Install
 
@@ -86,28 +86,29 @@ mendwright demo
 
 If the `mendwright` command isn't on your PATH (common on Windows), run `python -m mendwright demo`.
 
-The demo runs offline, with no browser and no API key. A fake page built on lxml stands in for the browser and a canned reply stands in for the model. A redesign breaks two selectors. mendwright heals the checkbox, and refuses to heal the pay button because the demo marks it `destructive=True`.
+The demo runs offline, with no browser and no API key. A fake page built on lxml stands in for the browser and a canned reply stands in for the model. A redesign breaks two selectors, and a cookie banner that used to come later now opens first and covers the form. mendwright clicks the banner away because the demo registered it with `heal.interrupt()`, heals the checkbox, and refuses to heal the pay button because the demo marks it `destructive=True`.
 
-<img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/demo.svg" width="100%" alt="Terminal recording of mendwright demo. On v2 of a checkout page the accept_terms selector misses, the model proposes an XPath anchored on the label text, it passes the checks and the box is checked. The pay selector, marked destructive=True, also misses and is refused without a model call.">
+<img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/demo.svg" width="100%" alt="Terminal recording of mendwright demo. On v2 of a checkout page a cookie banner covers the form and is clicked away as a registered interruption. The accept_terms selector misses, the model proposes an XPath anchored on the label text, it passes the checks and the box is checked. The pay selector, marked destructive=True, also misses and is refused without a model call.">
 
 <details>
 <summary>The same output as text</summary>
 
 ```text
-mendwright demo: a redesign breaks two selectors on a checkout page.
+mendwright demo: a redesign breaks two selectors on a checkout page and adds a cookie banner.
 Offline: a stand-in page (lxml, no browser) and a scripted model reply (no API call).
 
-  v1  accept_terms  #accept-terms  ok     matched, box checked
-  v1  pay           #pay           ok     matched (not clicked)
-      -- v2: a redesign ships and both ids are gone --
-  v2  accept_terms  #accept-terms  MISS   no element matches
+  v1  accept_terms  #accept-terms   ok     matched, box checked
+  v1  pay           #pay            ok     matched (not clicked)
+      -- v2: a redesign ships, both ids are gone, and a cookie banner opens first --
+  v2  cookies       #cookie-accept  ok     banner covered the form, clicked it (heal.interrupt)
+  v2  accept_terms  #accept-terms   MISS   no element matches
       model    proposed //label[contains(normalize-space(.),'accept the terms')]//input[@type='checkbox'] (scripted reply, no API call)
       checks   pass: 1 checkbox in the captured HTML, 1 match on the live page
       retry    ok: box checked with the healed selector, heal confirmed
-  v2  pay           #pay           MISS   no element matches
+  v2  pay           #pay            MISS   no element matches
       refused  'pay' is marked destructive=True. Not healed, no model call.
 
-Done: 1 heal applied and confirmed, 1 refused, 1 model call in total.
+Done: 1 heal applied and confirmed, 1 refused, 1 interruption handled, 1 model call in total.
 ```
 
 </details>
@@ -133,8 +134,9 @@ with sync_playwright() as p:
 `heal.locator()` takes the selector you'd pass to `page.locator()`, plus a key: a name for the element that its heals are saved under.
 
 `role=` is optional. mendwright needs to know what kind of element it is looking for before it can check a heal, and it learns that the first time the selector matches. Pass `role=` when you add mendwright to a suite whose selectors might already be broken.
+`intent=` describes the element in words, such as `intent="the terms checkbox in the signup form"`. The model gets it with the page, and with `role=` and no selector, a model finds the element on first use.
 
-Then tell mendwright which model to ask:
+A selector that never matched has no fingerprint, and some changes are beyond one, so to let mendwright ask a model:
 
 ```bash
 export ANTHROPIC_API_KEY="sk-ant-..."
@@ -145,11 +147,26 @@ $env:ANTHROPIC_API_KEY = "sk-ant-..."
 $env:ANTHROPIC_MODEL = "..."
 ```
 
-There is no default model. `OPENAI_API_KEY` with `OPENAI_MODEL`, `GEMINI_API_KEY` with `GEMINI_MODEL`, and `OLLAMA_MODEL` work the same way.
-For Bedrock, LiteLLM or another OpenAI-compatible host, pass `provider=` to `mendwright.open()`.
-`mendwright doctor` shows which provider it found. Without one, selectors still resolve, and a broken one raises an error that lists the variables to set.
+There is no default model. `OPENAI_API_KEY` with `OPENAI_MODEL`, `GEMINI_API_KEY` with `GEMINI_MODEL`, and `OLLAMA_MODEL` work the same way. For Bedrock, LiteLLM or another OpenAI-compatible host, pass `provider=` to `mendwright.open()`.
+`mendwright doctor` shows which provider it found. Without one, selectors still resolve and fingerprint heals still happen, and a selector the fingerprint can't place raises an error that lists the variables to set.
 
-A selector that stops matching is waited for 10 seconds (`MENDWRIGHT_TIMEOUT_MS`) before mendwright asks the model. Each applied heal prints one line to stderr, and `mendwright report` shows what was saved.
+A selector that stops matching is waited for 10 seconds (`MENDWRIGHT_TIMEOUT_MS`) before mendwright tries to heal it. Each applied heal prints one line to stderr, and `mendwright report` shows what was saved.
+
+## No changes per step
+
+To heal an existing script without touching its steps, change the line that makes the page or the driver:
+
+<!-- readme-test: wrappers -->
+```python
+page = mendwright.open(page).page          # Playwright
+page.fill("#email", "ada@example.com")
+page.check("#terms")
+
+driver = mendwright.open(driver).driver    # Selenium (By from selenium.webdriver.common.by)
+driver.find_element(By.ID, "terms").click()
+```
+
+Each selector is also the key its heals are saved under. Chained locators, `get_by_*` and the other `By` values go to the real page or driver unhealed, and `.native` is the real object. The [guide](https://github.com/saadbuilt/mendwright/blob/main/docs/guide.md#no-changes-per-step) lists what heals.
 
 ## Selenium
 
@@ -166,8 +183,7 @@ heal.locator("accept_terms", "//input[@id='terms']", role="checkbox").check()
 driver.quit()
 ```
 
-Playwright verbs such as `fill()`, `check()` and `select_option()` are mapped to WebElement calls, so step code reads the same on both libraries.
-Selenium runs XPath and CSS, so Playwright selectors such as `text=Save` raise `InvalidSelector` at once.
+Playwright verbs such as `fill()`, `check()` and `select_option()` are mapped to WebElement calls, so step code reads the same on both libraries. Selenium runs XPath and CSS, so Playwright selectors such as `text=Save` raise `InvalidSelector` at once.
 
 ## Async Playwright
 
@@ -209,13 +225,13 @@ To make CI show selector drift instead of quietly healing it, run `pytest --mend
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/how-it-works-dark.svg">
-  <img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/how-it-works-light.svg" width="800" alt="How a heal works: a selector misses; a key marked destructive, an unknown role or a used-up hourly limit stops with AttentionRequired before any model call; otherwise the page is captured and redacted, a model proposes an XPath and local checks run; a failure gives the model the reason and one more try, and a second failure raises AttentionRequired with nothing saved; a pass is saved and the step retried; if the action then fails the healed selector is quarantined.">
+  <img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/how-it-works-light.svg" width="800" alt="How a heal works: a selector misses; a key marked destructive, an unknown role or a page the key was never found on stops with AttentionRequired before anything is tried; otherwise the page is captured, and an XPath comes from the saved fingerprint when one element matches it with confidence, else from the model within the hourly limit; local checks run; a failed fingerprint pick goes to the model, a failed model pick gets the reason and one more try, and a second failure raises AttentionRequired with nothing saved; a pass is saved and the step retried; if the action then fails the healed selector is quarantined.">
 </picture>
 
-A step is refused before any model call when its key is marked destructive, when mendwright doesn't know what kind of element it is (see `role=` above), or when the hourly limit is used up: 3 heal attempts per key and 60 in all by default.
-mendwright doesn't guess which controls are destructive. Mark a pay, submit or delete step with `heal.locator(..., destructive=True)`, or pass its key in `mendwright.open(destructive_keys=...)`.
-A rejected attempt counts, and an attempt makes up to 2 model calls. Going through a gateway skips this limit, because the gateway meters on its side.
-Otherwise mendwright sends a cleaned, redacted copy of the page to the model (at most 60,000 characters of HTML and 60,000 of element inventory per request), and uses the XPath it proposes only if:
+A step is refused before anything is tried when its key is marked destructive, when mendwright doesn't know what kind of element it is (see `role=` above), or when the page isn't one the key was found on. mendwright doesn't guess which controls are destructive. Mark a pay, submit or delete step with `heal.locator(..., destructive=True)`, or pass its key in `mendwright.open(destructive_keys=...)`.
+Next, mendwright scores the page's elements against the key's fingerprint. It takes the best one, with no model call, only when it shares an id, test id, name, link, label or text with the recorded element and no other element comes close.
+Otherwise it sends a cleaned, redacted copy of the page to the model (at most 60,000 characters of HTML and 60,000 of element inventory per request), within an hourly limit of 3 heal attempts per key and 60 in all. A rejected attempt counts, and an attempt makes up to 2 model calls. A gateway meters on its side instead.
+Either way, the XPath is used only if:
 
 - it isn't an index-only path such as `/html[1]/body[1]/div[3]/input[1]`
 - the store doesn't hold it as quarantined or superseded for this key, and it doesn't reach an element the key has quarantined
@@ -223,13 +239,43 @@ Otherwise mendwright sends a cleaned, redacted copy of the page to the model (at
 - that element has the step's role (checkbox, button, link, and so on)
 - it matches exactly one element on the live page, and that element is visible (hidden checkboxes are allowed) and still has the role
 
-If the first proposal fails, the model gets the reason and one more try. Heals are saved in `.mendwright/overrides.json`, and each request, proposal, rejection and outcome goes to `journal.jsonl` next to it.
+If a fingerprint pick fails, the model is asked. If the model's first proposal fails, it gets the reason and one more try. Heals are saved in `.mendwright/overrides.json`, and each request, proposal, rejection and outcome goes to `journal.jsonl` next to it.
 On the next run the selector in your code is tried first and the saved heal right after it, in the same pass. That resolves without a wait or a model call. If the action on a healed element fails in the browser, the heal is quarantined and not used again.
 
+## What it can and can't fix
+
+mendwright repairs a selector on the page your script is on. It handles layout changes within that page:
+
+- ids and classes renamed, or replaced by build-generated ones
+- labels reworded or translated (with a model)
+- elements wrapped in a new container or component
+- elements moved to another part of the page, or form fields put in a different order
+- lookalike elements where the surrounding text decides which one is meant
+
+It also handles some changes in your script's flow:
+
+- A step that can show up at any point, such as a cookie banner, a newsletter modal or an "are you still there?" dialog. Register it once with `heal.interrupt()`. When it is in the way of a step (the step's element is missing, or the page shows the interruption), mendwright handles it first (a click, unless you register another action) and goes on with the step. If your script also has its own step for it, that step is skipped once the interruption was handled, so a cookie banner that now appears before signup instead of after it needs no other change.
+- The consent banners of common consent managers, with `cookies="reject"` or `cookies="accept"`. This is off by default.
+- A step that may not be there, with `heal.locator(..., optional=True)`.
+
+<!-- readme-test: flow -->
+```python
+heal = mendwright.open(page, cookies="reject")      # close common consent banners
+heal.interrupt("newsletter", "#newsletter-close")   # your own modal, wherever it opens
+
+heal.locator("email", "#email").fill("ada@example.com")
+heal.locator("create_account", "#create-account").click()
+```
+
+A step that moved to another page, steps in a new order, or a new required step still need a change to your script.
+mendwright remembers the last few pages each key was found on and doesn't heal a key on another page, so you get an error that says the flow changed, instead of a heal onto a similar element such as a Help button where a Continue button used to be. If a redesign only changed the URL, or the same steps run under language paths such as `/en/` and `/de/`, pass `heal_across_pages=True` to `mendwright.open()`.
+The model is also told it may answer that no element on the page fits, but a step that moved within the same address is still the model's call, so mark irreversible steps with `destructive=True`. The [guide](https://github.com/saadbuilt/mendwright/blob/main/docs/guide.md#flow-changes) has the details.
+
+Anchor selectors on ids, names, labels or text rather than position. A positional selector such as `(//form//input)[1]` that still matches after two fields swap now points at the wrong field, and since nothing broke, mendwright doesn't step in.
+
 ## Errors
 
-When mendwright can't or won't heal a step, it raises `mendwright.AttentionRequired` with the reason and a next step.
-This is the error from `heal.locator("pay", "#pay", destructive=True)` when `#pay` stopped matching:
+When mendwright can't or won't heal a step, it raises `mendwright.AttentionRequired` with the reason and a next step. This is the error from `heal.locator("pay", "#pay", destructive=True)` when `#pay` stopped matching:
 
 <!-- readme-test: attention-pay -->
 ```text
@@ -237,7 +283,8 @@ mendwright.exceptions.AttentionRequired: No matching element for: pay (tried 1 c
   -> 'pay' is marked as a destructive control, and mendwright never auto-heals those, because a validated but wrong selector here could act on a live account. Fix the selector in your code or seed file by hand.
 ```
 
-`mendwright doctor` checks the install, the provider and the store path. `mendwright report` lists each key with its selectors and recent heals; `--format md` prints a Markdown table you can append to `$GITHUB_STEP_SUMMARY`.
+`mendwright doctor` checks the install, the provider and the store path. `mendwright report` lists each key with its selectors and recent heals; `--format md` prints a Markdown table you can append to `$GITHUB_STEP_SUMMARY`, and `--format html --out report.html` writes one self-contained page.
+`mendwright fix` puts confirmed heals back into your code: it prints a diff of the string literals it would change, and `--apply` writes them.
 
 ## Compatibility
 
@@ -249,26 +296,24 @@ mendwright.exceptions.AttentionRequired: No matching element for: pay (tried 1 c
 | Model providers | Anthropic, OpenAI, Azure OpenAI, OpenAI-compatible hosts (Groq, OpenRouter, vLLM, LM Studio), Ollama, Gemini, Bedrock, LiteLLM, or your own gateway |
 | Python | 3.10 and newer, with lxml as the only dependency |
 
-The real-browser suite (`python -m pytest -m browser`) passed locally on Windows 11 with Python 3.12 on Playwright Chromium, Firefox and WebKit, patchright, camoufox, and Selenium with Chrome and Firefox. The async tests passed on all three Playwright browsers.
-CI runs the offline suite on Linux (Python 3.10 to 3.14), Windows and macOS, and the browser suite on Linux.
+The real-browser suite (`python -m pytest -m browser`) passed locally on Windows 11 with Python 3.12 on Playwright Chromium, Firefox and WebKit, patchright, camoufox, and Selenium with Chrome and Firefox. The async tests passed on all three Playwright browsers. CI runs the offline suite on Linux (Python 3.10 to 3.14), Windows and macOS, and the browser suite on Linux.
 
 ## Comparison
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/feature-matrix-dark.svg">
-  <img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/feature-matrix-light.svg" width="800" alt="Feature comparison of mendwright, Healenium, robotframework-heal, Skyvern, Stagehand and auto-playwright across thirteen features, including four where mendwright does not lead. The same data is in docs/comparison.md.">
+  <img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/feature-matrix-light.svg" width="800" alt="Feature comparison of mendwright, Healenium, robotframework-heal, Skyvern, Stagehand and auto-playwright across thirteen features, including two where mendwright does not lead. The same data is in docs/comparison.md.">
 </picture>
 
-Where another tool fits better: Healenium needs no change per step (you wrap the Java driver once, or point a Python, JS or C# Selenium client at its proxy), and its open source edition calls no model, which keeps page content on your machine. Robot Framework suites have robotframework-heal. Agent tools such as Stagehand and Skyvern handle steps that have no selector at all.
-[docs/comparison.md](https://github.com/saadbuilt/mendwright/blob/main/docs/comparison.md) has the full comparison, with a source for every cell and the footprint charts.
+Where another tool fits better: Healenium covers Java, and any Selenium client through its proxy, and its open source edition never calls a model in any setup. Robot Framework suites have robotframework-heal. Agent tools such as Stagehand and Skyvern handle steps written in plain English. [docs/comparison.md](https://github.com/saadbuilt/mendwright/blob/main/docs/comparison.md) has the full comparison, with a source for every cell and the footprint charts.
 
 ## Limitations
 
 - Heals are always XPath, even when your code used CSS or a Playwright selector.
 - An element inside an iframe heals only when you open mendwright on the frame: a `Frame` from `page.frames` on Playwright, or the driver after `switch_to.frame()` on Selenium. On Playwright, a selector that matches only inside a child iframe raises `AttentionRequired` and says so, without a model call.
-- With a hosted provider, page HTML is sent to it. Redaction removes quoted `value` attributes, absolute http(s) URLs and runs of 12 to 19 digits, but visible text and other attributes stay. See [SECURITY.md](https://github.com/saadbuilt/mendwright/blob/main/SECURITY.md). A local model through Ollama keeps the page on your machine.
+- With a hosted provider, page HTML is sent to it whenever a fingerprint match isn't confident. Redaction removes quoted `value` attributes, absolute http(s) URLs and runs of 12 to 19 digits, but visible text and other attributes stay. See [SECURITY.md](https://github.com/saadbuilt/mendwright/blob/main/SECURITY.md). A local model through Ollama keeps the page on your machine.
 - If a page's cleaned HTML is longer than 60,000 characters, the rest is cut before it reaches the model. An element near the end is then visible to it only through the element inventory.
-- How often a model picks the right element hasn't been measured, for any model.
+- Accuracy has been measured only without a model. On the [47-case benchmark](https://github.com/saadbuilt/mendwright/blob/main/docs/benchmark.md), the fingerprint tier alone healed 20 of 35 broken selectors and none onto a wrong element, but its thresholds were tuned on those same cases, so expect it to be wrong now and then on yours. With a model-free similarity baseline behind it, 28 of 35 healed, and 3 of the 47 cases went to the wrong element ([results](https://github.com/saadbuilt/mendwright/blob/main/benchmarks/RESULTS.md)). No model numbers are published yet.
 - `--mendwright-strict` only fails the run that made the heal. Later runs pick up the saved heal and pass, which is why strict CI runs need a fresh store.
 
 ## Links

{mendwright-0.3.0 → mendwright-0.4.0}/README.md

@@ -8,15 +8,15 @@
 Self-healing selectors for Playwright and Selenium.
 
 [![PyPI](https://img.shields.io/pypi/v/mendwright)](https://pypi.org/project/mendwright/)
-[![Python versions](https://img.shields.io/pypi/pyversions/mendwright)](https://pypi.org/project/mendwright/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mendwright?cacheSeconds=3600)](https://pypi.org/project/mendwright/)
 [![CI](https://github.com/saadbuilt/mendwright/actions/workflows/ci.yml/badge.svg)](https://github.com/saadbuilt/mendwright/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/saadbuilt/mendwright/blob/main/LICENSE)
 
 </div>
 
-When a site update breaks a selector, mendwright asks a model for a new XPath, checks it against the live page, saves it, and retries the step. On the next run the saved selector is used and the model isn't called.
+mendwright heals many broken selectors without any API key. Each time a selector matches, it saves a fingerprint of the element: its tag, ids, names, label, text and surroundings. When a site update breaks the selector, mendwright looks for that element first, checks the new XPath against the live page, saves it, and retries the step. It asks a model only when the fingerprint match isn't confident. On the next run the saved selector is used and nothing is asked.
 
-Supports Anthropic, OpenAI and compatible APIs, Gemini, Bedrock, LiteLLM, or a local model through Ollama.
+For the model it supports Anthropic, OpenAI and compatible APIs, Gemini, Bedrock, LiteLLM, or a local model through Ollama.
 
 ## Install
 
@@ -27,28 +27,29 @@ mendwright demo
 
 If the `mendwright` command isn't on your PATH (common on Windows), run `python -m mendwright demo`.
 
-The demo runs offline, with no browser and no API key. A fake page built on lxml stands in for the browser and a canned reply stands in for the model. A redesign breaks two selectors. mendwright heals the checkbox, and refuses to heal the pay button because the demo marks it `destructive=True`.
+The demo runs offline, with no browser and no API key. A fake page built on lxml stands in for the browser and a canned reply stands in for the model. A redesign breaks two selectors, and a cookie banner that used to come later now opens first and covers the form. mendwright clicks the banner away because the demo registered it with `heal.interrupt()`, heals the checkbox, and refuses to heal the pay button because the demo marks it `destructive=True`.
 
-<img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/demo.svg" width="100%" alt="Terminal recording of mendwright demo. On v2 of a checkout page the accept_terms selector misses, the model proposes an XPath anchored on the label text, it passes the checks and the box is checked. The pay selector, marked destructive=True, also misses and is refused without a model call.">
+<img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/demo.svg" width="100%" alt="Terminal recording of mendwright demo. On v2 of a checkout page a cookie banner covers the form and is clicked away as a registered interruption. The accept_terms selector misses, the model proposes an XPath anchored on the label text, it passes the checks and the box is checked. The pay selector, marked destructive=True, also misses and is refused without a model call.">
 
 <details>
 <summary>The same output as text</summary>
 
 ```text
-mendwright demo: a redesign breaks two selectors on a checkout page.
+mendwright demo: a redesign breaks two selectors on a checkout page and adds a cookie banner.
 Offline: a stand-in page (lxml, no browser) and a scripted model reply (no API call).
 
-  v1  accept_terms  #accept-terms  ok     matched, box checked
-  v1  pay           #pay           ok     matched (not clicked)
-      -- v2: a redesign ships and both ids are gone --
-  v2  accept_terms  #accept-terms  MISS   no element matches
+  v1  accept_terms  #accept-terms   ok     matched, box checked
+  v1  pay           #pay            ok     matched (not clicked)
+      -- v2: a redesign ships, both ids are gone, and a cookie banner opens first --
+  v2  cookies       #cookie-accept  ok     banner covered the form, clicked it (heal.interrupt)
+  v2  accept_terms  #accept-terms   MISS   no element matches
       model    proposed //label[contains(normalize-space(.),'accept the terms')]//input[@type='checkbox'] (scripted reply, no API call)
       checks   pass: 1 checkbox in the captured HTML, 1 match on the live page
       retry    ok: box checked with the healed selector, heal confirmed
-  v2  pay           #pay           MISS   no element matches
+  v2  pay           #pay            MISS   no element matches
       refused  'pay' is marked destructive=True. Not healed, no model call.
 
-Done: 1 heal applied and confirmed, 1 refused, 1 model call in total.
+Done: 1 heal applied and confirmed, 1 refused, 1 interruption handled, 1 model call in total.
 ```
 
 </details>
@@ -74,8 +75,9 @@ with sync_playwright() as p:
 `heal.locator()` takes the selector you'd pass to `page.locator()`, plus a key: a name for the element that its heals are saved under.
 
 `role=` is optional. mendwright needs to know what kind of element it is looking for before it can check a heal, and it learns that the first time the selector matches. Pass `role=` when you add mendwright to a suite whose selectors might already be broken.
+`intent=` describes the element in words, such as `intent="the terms checkbox in the signup form"`. The model gets it with the page, and with `role=` and no selector, a model finds the element on first use.
 
-Then tell mendwright which model to ask:
+A selector that never matched has no fingerprint, and some changes are beyond one, so to let mendwright ask a model:
 
 ```bash
 export ANTHROPIC_API_KEY="sk-ant-..."
@@ -86,11 +88,26 @@ $env:ANTHROPIC_API_KEY = "sk-ant-..."
 $env:ANTHROPIC_MODEL = "..."
 ```
 
-There is no default model. `OPENAI_API_KEY` with `OPENAI_MODEL`, `GEMINI_API_KEY` with `GEMINI_MODEL`, and `OLLAMA_MODEL` work the same way.
-For Bedrock, LiteLLM or another OpenAI-compatible host, pass `provider=` to `mendwright.open()`.
-`mendwright doctor` shows which provider it found. Without one, selectors still resolve, and a broken one raises an error that lists the variables to set.
+There is no default model. `OPENAI_API_KEY` with `OPENAI_MODEL`, `GEMINI_API_KEY` with `GEMINI_MODEL`, and `OLLAMA_MODEL` work the same way. For Bedrock, LiteLLM or another OpenAI-compatible host, pass `provider=` to `mendwright.open()`.
+`mendwright doctor` shows which provider it found. Without one, selectors still resolve and fingerprint heals still happen, and a selector the fingerprint can't place raises an error that lists the variables to set.
 
-A selector that stops matching is waited for 10 seconds (`MENDWRIGHT_TIMEOUT_MS`) before mendwright asks the model. Each applied heal prints one line to stderr, and `mendwright report` shows what was saved.
+A selector that stops matching is waited for 10 seconds (`MENDWRIGHT_TIMEOUT_MS`) before mendwright tries to heal it. Each applied heal prints one line to stderr, and `mendwright report` shows what was saved.
+
+## No changes per step
+
+To heal an existing script without touching its steps, change the line that makes the page or the driver:
+
+<!-- readme-test: wrappers -->
+```python
+page = mendwright.open(page).page          # Playwright
+page.fill("#email", "ada@example.com")
+page.check("#terms")
+
+driver = mendwright.open(driver).driver    # Selenium (By from selenium.webdriver.common.by)
+driver.find_element(By.ID, "terms").click()
+```
+
+Each selector is also the key its heals are saved under. Chained locators, `get_by_*` and the other `By` values go to the real page or driver unhealed, and `.native` is the real object. The [guide](https://github.com/saadbuilt/mendwright/blob/main/docs/guide.md#no-changes-per-step) lists what heals.
 
 ## Selenium
 
@@ -107,8 +124,7 @@ heal.locator("accept_terms", "//input[@id='terms']", role="checkbox").check()
 driver.quit()
 ```
 
-Playwright verbs such as `fill()`, `check()` and `select_option()` are mapped to WebElement calls, so step code reads the same on both libraries.
-Selenium runs XPath and CSS, so Playwright selectors such as `text=Save` raise `InvalidSelector` at once.
+Playwright verbs such as `fill()`, `check()` and `select_option()` are mapped to WebElement calls, so step code reads the same on both libraries. Selenium runs XPath and CSS, so Playwright selectors such as `text=Save` raise `InvalidSelector` at once.
 
 ## Async Playwright
 
@@ -150,13 +166,13 @@ To make CI show selector drift instead of quietly healing it, run `pytest --mend
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/how-it-works-dark.svg">
-  <img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/how-it-works-light.svg" width="800" alt="How a heal works: a selector misses; a key marked destructive, an unknown role or a used-up hourly limit stops with AttentionRequired before any model call; otherwise the page is captured and redacted, a model proposes an XPath and local checks run; a failure gives the model the reason and one more try, and a second failure raises AttentionRequired with nothing saved; a pass is saved and the step retried; if the action then fails the healed selector is quarantined.">
+  <img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/how-it-works-light.svg" width="800" alt="How a heal works: a selector misses; a key marked destructive, an unknown role or a page the key was never found on stops with AttentionRequired before anything is tried; otherwise the page is captured, and an XPath comes from the saved fingerprint when one element matches it with confidence, else from the model within the hourly limit; local checks run; a failed fingerprint pick goes to the model, a failed model pick gets the reason and one more try, and a second failure raises AttentionRequired with nothing saved; a pass is saved and the step retried; if the action then fails the healed selector is quarantined.">
 </picture>
 
-A step is refused before any model call when its key is marked destructive, when mendwright doesn't know what kind of element it is (see `role=` above), or when the hourly limit is used up: 3 heal attempts per key and 60 in all by default.
-mendwright doesn't guess which controls are destructive. Mark a pay, submit or delete step with `heal.locator(..., destructive=True)`, or pass its key in `mendwright.open(destructive_keys=...)`.
-A rejected attempt counts, and an attempt makes up to 2 model calls. Going through a gateway skips this limit, because the gateway meters on its side.
-Otherwise mendwright sends a cleaned, redacted copy of the page to the model (at most 60,000 characters of HTML and 60,000 of element inventory per request), and uses the XPath it proposes only if:
+A step is refused before anything is tried when its key is marked destructive, when mendwright doesn't know what kind of element it is (see `role=` above), or when the page isn't one the key was found on. mendwright doesn't guess which controls are destructive. Mark a pay, submit or delete step with `heal.locator(..., destructive=True)`, or pass its key in `mendwright.open(destructive_keys=...)`.
+Next, mendwright scores the page's elements against the key's fingerprint. It takes the best one, with no model call, only when it shares an id, test id, name, link, label or text with the recorded element and no other element comes close.
+Otherwise it sends a cleaned, redacted copy of the page to the model (at most 60,000 characters of HTML and 60,000 of element inventory per request), within an hourly limit of 3 heal attempts per key and 60 in all. A rejected attempt counts, and an attempt makes up to 2 model calls. A gateway meters on its side instead.
+Either way, the XPath is used only if:
 
 - it isn't an index-only path such as `/html[1]/body[1]/div[3]/input[1]`
 - the store doesn't hold it as quarantined or superseded for this key, and it doesn't reach an element the key has quarantined
@@ -164,13 +180,43 @@ Otherwise mendwright sends a cleaned, redacted copy of the page to the model (at
 - that element has the step's role (checkbox, button, link, and so on)
 - it matches exactly one element on the live page, and that element is visible (hidden checkboxes are allowed) and still has the role
 
-If the first proposal fails, the model gets the reason and one more try. Heals are saved in `.mendwright/overrides.json`, and each request, proposal, rejection and outcome goes to `journal.jsonl` next to it.
+If a fingerprint pick fails, the model is asked. If the model's first proposal fails, it gets the reason and one more try. Heals are saved in `.mendwright/overrides.json`, and each request, proposal, rejection and outcome goes to `journal.jsonl` next to it.
 On the next run the selector in your code is tried first and the saved heal right after it, in the same pass. That resolves without a wait or a model call. If the action on a healed element fails in the browser, the heal is quarantined and not used again.
 
+## What it can and can't fix
+
+mendwright repairs a selector on the page your script is on. It handles layout changes within that page:
+
+- ids and classes renamed, or replaced by build-generated ones
+- labels reworded or translated (with a model)
+- elements wrapped in a new container or component
+- elements moved to another part of the page, or form fields put in a different order
+- lookalike elements where the surrounding text decides which one is meant
+
+It also handles some changes in your script's flow:
+
+- A step that can show up at any point, such as a cookie banner, a newsletter modal or an "are you still there?" dialog. Register it once with `heal.interrupt()`. When it is in the way of a step (the step's element is missing, or the page shows the interruption), mendwright handles it first (a click, unless you register another action) and goes on with the step. If your script also has its own step for it, that step is skipped once the interruption was handled, so a cookie banner that now appears before signup instead of after it needs no other change.
+- The consent banners of common consent managers, with `cookies="reject"` or `cookies="accept"`. This is off by default.
+- A step that may not be there, with `heal.locator(..., optional=True)`.
+
+<!-- readme-test: flow -->
+```python
+heal = mendwright.open(page, cookies="reject")      # close common consent banners
+heal.interrupt("newsletter", "#newsletter-close")   # your own modal, wherever it opens
+
+heal.locator("email", "#email").fill("ada@example.com")
+heal.locator("create_account", "#create-account").click()
+```
+
+A step that moved to another page, steps in a new order, or a new required step still need a change to your script.
+mendwright remembers the last few pages each key was found on and doesn't heal a key on another page, so you get an error that says the flow changed, instead of a heal onto a similar element such as a Help button where a Continue button used to be. If a redesign only changed the URL, or the same steps run under language paths such as `/en/` and `/de/`, pass `heal_across_pages=True` to `mendwright.open()`.
+The model is also told it may answer that no element on the page fits, but a step that moved within the same address is still the model's call, so mark irreversible steps with `destructive=True`. The [guide](https://github.com/saadbuilt/mendwright/blob/main/docs/guide.md#flow-changes) has the details.
+
+Anchor selectors on ids, names, labels or text rather than position. A positional selector such as `(//form//input)[1]` that still matches after two fields swap now points at the wrong field, and since nothing broke, mendwright doesn't step in.
+
 ## Errors
 
-When mendwright can't or won't heal a step, it raises `mendwright.AttentionRequired` with the reason and a next step.
-This is the error from `heal.locator("pay", "#pay", destructive=True)` when `#pay` stopped matching:
+When mendwright can't or won't heal a step, it raises `mendwright.AttentionRequired` with the reason and a next step. This is the error from `heal.locator("pay", "#pay", destructive=True)` when `#pay` stopped matching:
 
 <!-- readme-test: attention-pay -->
 ```text
@@ -178,7 +224,8 @@ mendwright.exceptions.AttentionRequired: No matching element for: pay (tried 1 c
   -> 'pay' is marked as a destructive control, and mendwright never auto-heals those, because a validated but wrong selector here could act on a live account. Fix the selector in your code or seed file by hand.
 ```
 
-`mendwright doctor` checks the install, the provider and the store path. `mendwright report` lists each key with its selectors and recent heals; `--format md` prints a Markdown table you can append to `$GITHUB_STEP_SUMMARY`.
+`mendwright doctor` checks the install, the provider and the store path. `mendwright report` lists each key with its selectors and recent heals; `--format md` prints a Markdown table you can append to `$GITHUB_STEP_SUMMARY`, and `--format html --out report.html` writes one self-contained page.
+`mendwright fix` puts confirmed heals back into your code: it prints a diff of the string literals it would change, and `--apply` writes them.
 
 ## Compatibility
 
@@ -190,26 +237,24 @@ mendwright.exceptions.AttentionRequired: No matching element for: pay (tried 1 c
 | Model providers | Anthropic, OpenAI, Azure OpenAI, OpenAI-compatible hosts (Groq, OpenRouter, vLLM, LM Studio), Ollama, Gemini, Bedrock, LiteLLM, or your own gateway |
 | Python | 3.10 and newer, with lxml as the only dependency |
 
-The real-browser suite (`python -m pytest -m browser`) passed locally on Windows 11 with Python 3.12 on Playwright Chromium, Firefox and WebKit, patchright, camoufox, and Selenium with Chrome and Firefox. The async tests passed on all three Playwright browsers.
-CI runs the offline suite on Linux (Python 3.10 to 3.14), Windows and macOS, and the browser suite on Linux.
+The real-browser suite (`python -m pytest -m browser`) passed locally on Windows 11 with Python 3.12 on Playwright Chromium, Firefox and WebKit, patchright, camoufox, and Selenium with Chrome and Firefox. The async tests passed on all three Playwright browsers. CI runs the offline suite on Linux (Python 3.10 to 3.14), Windows and macOS, and the browser suite on Linux.
 
 ## Comparison
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/feature-matrix-dark.svg">
-  <img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/feature-matrix-light.svg" width="800" alt="Feature comparison of mendwright, Healenium, robotframework-heal, Skyvern, Stagehand and auto-playwright across thirteen features, including four where mendwright does not lead. The same data is in docs/comparison.md.">
+  <img src="https://raw.githubusercontent.com/saadbuilt/mendwright/main/docs/assets/feature-matrix-light.svg" width="800" alt="Feature comparison of mendwright, Healenium, robotframework-heal, Skyvern, Stagehand and auto-playwright across thirteen features, including two where mendwright does not lead. The same data is in docs/comparison.md.">
 </picture>
 
-Where another tool fits better: Healenium needs no change per step (you wrap the Java driver once, or point a Python, JS or C# Selenium client at its proxy), and its open source edition calls no model, which keeps page content on your machine. Robot Framework suites have robotframework-heal. Agent tools such as Stagehand and Skyvern handle steps that have no selector at all.
-[docs/comparison.md](https://github.com/saadbuilt/mendwright/blob/main/docs/comparison.md) has the full comparison, with a source for every cell and the footprint charts.
+Where another tool fits better: Healenium covers Java, and any Selenium client through its proxy, and its open source edition never calls a model in any setup. Robot Framework suites have robotframework-heal. Agent tools such as Stagehand and Skyvern handle steps written in plain English. [docs/comparison.md](https://github.com/saadbuilt/mendwright/blob/main/docs/comparison.md) has the full comparison, with a source for every cell and the footprint charts.
 
 ## Limitations
 
 - Heals are always XPath, even when your code used CSS or a Playwright selector.
 - An element inside an iframe heals only when you open mendwright on the frame: a `Frame` from `page.frames` on Playwright, or the driver after `switch_to.frame()` on Selenium. On Playwright, a selector that matches only inside a child iframe raises `AttentionRequired` and says so, without a model call.
-- With a hosted provider, page HTML is sent to it. Redaction removes quoted `value` attributes, absolute http(s) URLs and runs of 12 to 19 digits, but visible text and other attributes stay. See [SECURITY.md](https://github.com/saadbuilt/mendwright/blob/main/SECURITY.md). A local model through Ollama keeps the page on your machine.
+- With a hosted provider, page HTML is sent to it whenever a fingerprint match isn't confident. Redaction removes quoted `value` attributes, absolute http(s) URLs and runs of 12 to 19 digits, but visible text and other attributes stay. See [SECURITY.md](https://github.com/saadbuilt/mendwright/blob/main/SECURITY.md). A local model through Ollama keeps the page on your machine.
 - If a page's cleaned HTML is longer than 60,000 characters, the rest is cut before it reaches the model. An element near the end is then visible to it only through the element inventory.
-- How often a model picks the right element hasn't been measured, for any model.
+- Accuracy has been measured only without a model. On the [47-case benchmark](https://github.com/saadbuilt/mendwright/blob/main/docs/benchmark.md), the fingerprint tier alone healed 20 of 35 broken selectors and none onto a wrong element, but its thresholds were tuned on those same cases, so expect it to be wrong now and then on yours. With a model-free similarity baseline behind it, 28 of 35 healed, and 3 of the 47 cases went to the wrong element ([results](https://github.com/saadbuilt/mendwright/blob/main/benchmarks/RESULTS.md)). No model numbers are published yet.
 - `--mendwright-strict` only fails the run that made the heal. Later runs pick up the saved heal and pass, which is why strict CI runs need a fresh store.
 
 ## Links