playwright-locator-healer 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to `playwright-locator-healer` are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2026-05-16
+
+First public release. Inaugural npm publish under the `@dhana009` scope.
+
+### Added — heal flow
+
+- Zero-modification **auto-fixture** at `playwright-locator-healer/auto`. Drop-in replacement for `@playwright/test`: any locator action or web-first assertion that times out triggers heal automatically; the action retries against the healed locator in the same run.
+- Explicit **opt-in fixture** at `playwright-locator-healer/test` for incremental Page Object Model migration.
+- Interactive in-browser overlay (Shadow DOM dock) for picking the correct element when a locator breaks. VS Code-style slate palette, draggable, keyboard-driven (A / R / E / B / L / P / Esc).
+- Pre-flight free probe stage: id, data-testid, aria-label, role+name on the picked node. Resolves ~30% of heals at zero LLM cost.
+- Progressive LLM rounds (up to 4): silent auto-accept first valid, then user-gated "broaden?" prompts, then a JS-eval escape hatch.
+- Per-spec selector cache at `.healed-locators/<spec>.json`. Strict-schema reads with malformed entries quarantined and surfaced on stderr.
+- Filter-chain depth enforcement: validator rejects locator chains deeper than 2 levels.
+- Per-page heal serialization so concurrent racing actions queue and second-callers hit the cache.
+
+### Added — reliability (v3 wave 1)
+
+- **Circuit breaker** in `healing/circuit-breaker.ts`. After `HEAL_CIRCUIT_THRESHOLD` (default 3) consecutive LLM failures, the next heal short-circuits with `HealingError` category `circuit-open` instead of paying for another doomed call. Automatically resets on the next successful call.
+- **Strict cache schema** validation on every read. Manual edits, partial writes, or schema drift surface `[HEAL] cache entry rejected for X: <reason>` and the heal proceeds fresh instead of returning garbage.
+- **Filter-chain depth guard** rejects 3+-level chains at validator-build time with `HealingError` category `invalid-filter-chain`.
+- **Jittered exponential backoff** on LLM retries. `HEALING_BACKOFF_MS=1000,2000,4000` becomes `1000±20%, 2000±20%, 4000±20%` to break up thundering-herd retries against OpenAI.
+- **No-silent-swallow** policy enforced in `healing/heal/orchestrator.ts`. Best-effort writes that previously did `.catch(() => {})` now log via `healing/audit-log.ts` and `healing/logger.ts`.
+- New `HealingError` categories: `circuit-open`, `invalid-cache`, `invalid-filter-chain`.
+
+### Added — observability
+
+- **Level-gated logger** in `healing/logger.ts`. `HEAL_LOG_LEVEL` env (default `warn`) controls verbosity (`debug` / `info` / `warn` / `error` / `silent`).
+- **Audit log helper** in `healing/audit-log.ts`. Surfaces append failures instead of swallowing them.
+- **Cache-hit-rate tracking** in `healing/cost-tracker.ts` via `getCacheHitRate()`. Daily `cachedCalls` is now persisted to `.healed-locators/cost.daily.json`.
+- **`heal-report` CLI** (`scripts/heal-report.ts`, exposed as `npx heal-report`). Renders a markdown table of date, calls, cost, cache-hit-rate, cumulative cost across the lifetime of the cost log.
+
+### Added — model + cost
+
+- **Multi-model registry** in `healing/models.ts`. Switch model via `HEAL_MODEL` (`gpt-4.1-mini` default, plus `gpt-4.1`, `gpt-4.1-nano`, `gpt-5.4-mini`, `gpt-5.4-nano`).
+- **Runtime price overrides** via `HEAL_PRICE_INPUT_PER_M`, `HEAL_PRICE_CACHED_PER_M`, `HEAL_PRICE_OUTPUT_PER_M` for surviving OpenAI rate changes without a library release.
+- **Per-call raw usage audit log** at `.healed-locators/llm-calls.ndjson` for independent cross-verification against OpenAI billing.
+- **Prompt-cache aware session summary** at process exit (calls, fresh + cached input tokens, output tokens, cost, savings).
+
+### Added — packaging
+
+- Published as `playwright-locator-healer` with `peerDependencies` on `@playwright/test ^1.59.0`.
+- Exports map: `.`, `./auto`, `./test`.
+- `bin` entry `heal-report` exposing the cost-report CLI.
+- `files` allow-list ensures the published tarball is minimal (`dist/`, `scripts/heal-report.ts`, `README.md`, `USAGE.md`, `CHANGELOG.md`, `LICENSE`).
+- CI workflow at `.github/workflows/ci.yml`: Node 20 + 22 matrix, `tsc --noEmit`, `vitest run`, headless-chromium integration. LLM-dependent tests are gated behind `OPENAI_API_KEY` presence.
+
+### Verified working
+
+- 121 unit tests in `healing/__tests__/`
+- 3 integration flows in `tests/integration/heal-e2e-auto.spec.ts`
+- 3 zero-mod auto-fixture flows in `tests/integration/heal-auto-fixture.spec.ts`
+- `npx tsc --noEmit` zero errors
+- OpenAI prompt cache verified against live billing dashboard (77% input tokens cached on multi-call sessions)
+- Median per-heal cost target: $0 to $0.0007 — achieved
+
+### Known limitations (deferred to v0.2+)
+
+- No keep-alive ping — sporadic users may see frequent prompt-cache cold starts.
+- No diff view before the user accepts a proposed locator.
+- No dock-position memory across sessions.
+- Status-bar elapsed timer renders `0s` (cosmetic).
+- Only OpenAI-compatible models supported; multi-provider abstraction is on the roadmap.
+- Shadow-DOM piercing, cross-origin iframes, CAPTCHA handling, and source-rewrite-into-test-file are explicitly out of scope.
+
+[0.1.0]: https://github.com/Dhana009/playwright-locator-healer/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dhanunjaya Madharapakam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+<div align="center">
+
+# 🩹 playwright-locator-healer
+
+### *Self-healing Playwright locators — pick, confirm, cached forever.*
+
+[![npm version](https://img.shields.io/npm/v/playwright-locator-healer.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/playwright-locator-healer)
+[![npm downloads](https://img.shields.io/npm/dm/playwright-locator-healer.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/playwright-locator-healer)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
+[![node](https://img.shields.io/node/v/playwright-locator-healer.svg?style=flat-square&color=339933)](https://nodejs.org)
+[![Playwright](https://img.shields.io/badge/playwright-≥1.59-2EAD33.svg?style=flat-square)](https://playwright.dev)
+[![CI](https://img.shields.io/github/actions/workflow/status/Dhana009/playwright-locator-healer/ci.yml?branch=main&style=flat-square)](https://github.com/Dhana009/playwright-locator-healer/actions)
+
+**Stop fixing locators by hand. Let your tests fix themselves.**
+
+[Quickstart](#-quickstart) · [How it works](#-how-it-works) · [Cost](#-cost-economics) · [FAQ](#-faq)
+
+</div>
+
+---
+
+## 😖 The problem
+
+```ts
+await page.locator('#login-btn').click();   // ❌ TimeoutError — class changed yesterday
+```
+
+Your test suite breaks **5–20 times a week** — not because the feature is broken, but because a class got renamed, an id grew a hash suffix, or a button moved one level deeper. You sigh. You open DevTools. You hunt for a new selector. You re-run. Repeat tomorrow.
+
+## 🩹 The fix
+
+```diff
+- import { test, expect } from '@playwright/test';
++ import { test, expect } from 'playwright-locator-healer/auto';
+```
+
+Next time a locator fails:
+
+| # | What happens |
+|:-:|---|
+| 1 | 🖼️  An overlay opens in your live browser |
+| 2 | 👆 You click the element the test meant to target |
+| 3 | 🤖 An LLM names a stable selector (`role=button[name="Login"]`, `[data-testid=submit]`, …) |
+| 4 | ✅ You hit Accept. Test continues. |
+| 5 | 🚀 Every subsequent run uses the cached selector — **no overlay, no LLM call, no cost** |
+
+Commit `.healed-locators/` to git. CI runs against cached selectors. Interactive heal happens **only locally**, only when something actually breaks.
+
+---
+
+## ✨ Why it's different
+
+| | Manual fix | Other healers | playwright-locator-healer |
+|---|:-:|:-:|:-:|
+| Zero-mod integration | ❌ | ⚠️ | ✅ |
+| Human-in-the-loop pick | — | ❌ | ✅ |
+| Stable-tier selector ranking | ❌ | ⚠️ | ✅ |
+| Cached drift detection | — | ⚠️ | ✅ |
+| Free in CI (cache-only) | — | ❌ | ✅ |
+| Median cost per heal | ∞ time | $0.005+ | **$0.0007** |
+
+---
+
+## 🎬 See it work
+
+> 📸 Screenshots will live in `docs/screenshots/`. Capture them with `npx playwright test --headed` against a broken selector and drop the PNG/GIF files in. See `docs/screenshots/README.md` for the playbook.
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  🩹 HEAL · pick the element                       _ □ ✕  │
+│  ─────────────────────────────────────────────────────── │
+│  Broken:    #login-btn                                   │
+│  Action:    click                                        │
+│  Intent:    [ type a short description... ]              │
+│  ─────────────────────────────────────────────────────── │
+│  > Hover any element on the page. Click to pick.         │
+└──────────────────────────────────────────────────────────┘
+                          ↓ pick
+┌──────────────────────────────────────────────────────────┐
+│  🩹 HEAL · you picked                                    │
+│  Tag:               <button>                             │
+│  Role:              button                               │
+│  Accessible name:   Login                                │
+│  Stable handle:     #submit                              │
+│  ─────────────────────────────────────────────────────── │
+│  [ ↩ re-pick ]   [ Enter continue ]   [ Esc cancel ]     │
+└──────────────────────────────────────────────────────────┘
+                          ↓ continue
+┌──────────────────────────────────────────────────────────┐
+│  🩹 HEAL · proposed                                      │
+│  role=button[name="Login"]      tier 1 ★★★★★             │
+│  ─────────────────────────────────────────────────────── │
+│  [ ✅ Accept ]  [ ✏️ Reject ]  [ 🛟 Broaden ]  [ Cancel ] │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Quickstart
+
+```bash
+npm install --save-dev playwright-locator-healer
+npx playwright-heal init
+```
+
+`init` is idempotent. It writes `.env.example`, creates `.healed-locators/.gitkeep`, appends safe `.gitignore` entries (logs and screenshots only — cache JSON stays tracked), and prints next steps.
+
+Add your key (only needed when the LLM stage actually runs):
+
+```bash
+echo "OPENAI_API_KEY=sk-..." >> .env
+```
+
+Swap one import line — your tests now self-heal:
+
+```ts
+// Before
+import { test, expect } from '@playwright/test';
+
+// After — no other changes needed
+import { test, expect } from 'playwright-locator-healer/auto';
+```
+
+Run headed:
+
+```bash
+npx playwright test --headed
+```
+
+When a locator fails, an overlay opens in the live browser. Pick the element, type a short intent, accept the proposal. On every subsequent run the cached selector is used — no overlay, no LLM call.
+
+---
+
+## ⚙️ How it works
+
+```
+heal(originalSelector, action)
+  │
+  ├─ Stage 0  Live re-check
+  │           page.locator(orig).count() === 1  →  no heal needed
+  │
+  ├─ Stage 1  Cache hit
+  │           .healed-locators/<spec>.json has entry + live validates  →  return
+  │
+  ├─ Stage 2  Open overlay
+  │           Shadow-DOM dock. User picks element + types intent.
+  │
+  ├─ Stage 3  Pre-flight (free, no LLM)
+  │           id / data-testid / aria-label / role+name on picked node.
+  │           Unique + visible  →  cache + return.  ~30% hit rate, $0.
+  │
+  ├─ Stage 4  Progressive LLM rounds (up to 4)
+  │           R1  silent auto-accept first valid, tiers 1-4
+  │           R2  user-gated "broaden?",         tiers 1-5
+  │           R3  user-gated,                    tiers 1-6 (xpath allowed)
+  │           R4  escape hatch (js eval, never cached, audit-only)
+  │
+  └─ Stage 5  Exhausted  →  audit log + rethrow original error
+```
+
+Every LLM suggestion is validated (`count === 1` and visible) before it reaches the confirm UI. The LLM never auto-applies anything — you accept or reject each candidate.
+
+---
+
+## 🔌 Two integration modes
+
+### Auto-fixture (zero test modifications) — recommended
+
+```ts
+// tests/checkout.spec.ts
+import { test, expect } from 'playwright-locator-healer/auto';
+
+test('checkout flow', async ({ page }) => {
+  await page.goto('https://example.com/cart');
+  await page.locator('#checkout-btn').click();
+  await expect(page.locator('.order-confirm')).toBeVisible();
+});
+```
+
+`page` and `expect` are transparently proxied. Any locator action (`click`, `fill`, `check`, etc.) or web-first assertion (`toBeVisible`, `toHaveText`, etc.) that times out triggers heal. The action is retried against the healed locator in the same run. Existing Playwright tests need only the import swap.
+
+### Opt-in fixture (explicit)
+
+Use when you want full control over when heal fires, or when migrating a Page Object Model incrementally.
+
+```ts
+import { test } from 'playwright-locator-healer/test';
+
+test('signup', async ({ page, heal }) => {
+  await page.goto('/signup');
+
+  const entry = await heal({
+    originalSelector: '#submit-btn',
+    action: 'click',
+    description: 'submit button on signup form',
+  });
+
+  await page.locator(entry.healedSelector).click();
+});
+```
+
+`heal()` returns a `HealEntryV2` with `healedSelector`, `selectorType`, and `tier`. On every future run the call resolves instantly from cache.
+
+---
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `OPENAI_API_KEY` | Yes (LLM stage only) | — | OpenAI API key. Not read until Stage 4 fires. |
+| `HEAL_MODEL` | No | `gpt-4.1-mini` | Model ID. See model table below. |
+| `HEAL_HEADLESS` | No | `0` | `1` enables CI mode: cache hits return, misses rethrow without LLM. |
+| `HEAL_LOG_LEVEL` | No | `warn` | `debug` / `info` / `warn` / `error` / `silent`. |
+| `HEALING_TIMEOUT_LLM` | No | `15000` | Per-call LLM wall-clock timeout (ms). |
+| `HEALING_BACKOFF_MS` | No | `1000,2000,4000` | Comma-separated retry backoff schedule (ms). Each delay is jittered ±20%. |
+| `HEAL_CIRCUIT_THRESHOLD` | No | `3` | Consecutive LLM failures before circuit opens (fast-fail). |
+| `HEAL_PRICE_INPUT_PER_M` | No | model default | Override fresh input token price (USD per 1M tokens). |
+| `HEAL_PRICE_CACHED_PER_M` | No | model default | Override cached input token price. |
+| `HEAL_PRICE_OUTPUT_PER_M` | No | model default | Override output token price. |
+
+---
+
+## Model picker
+
+| `HEAL_MODEL` | Input (fresh) | Input (cached) | Output | Notes |
+|---|---|---|---|---|
+| `gpt-4.1-mini` (default) | $0.40 / 1M | $0.10 / 1M | $1.60 / 1M | Best cost/quality for heal workloads. |
+| `gpt-4.1` | $2.00 / 1M | $0.50 / 1M | $8.00 / 1M | Higher locator quality on complex UIs. |
+| `gpt-4.1-nano` | $0.10 / 1M | $0.025 / 1M | $0.40 / 1M | Cheapest; weaker on ambiguous picks. |
+| `gpt-5.4-mini` | $0.30 / 1M | $0.075 / 1M | $1.20 / 1M | Alternative mini (placeholder pricing). |
+| `gpt-5.4-nano` | $0.075 / 1M | $0.019 / 1M | $0.30 / 1M | Alternative nano (placeholder pricing). |
+
+Switch at any time:
+
+```bash
+HEAL_MODEL=gpt-4.1 npx playwright test --headed
+```
+
+Override pricing when OpenAI rates shift without a library release:
+
+```bash
+HEAL_PRICE_INPUT_PER_M=0.30 HEAL_PRICE_CACHED_PER_M=0.075 npx playwright test --headed
+```
+
+---
+
+## Cost economics
+
+| Path | Cost |
+|---|---|
+| Cache hit (selector already healed in a prior run) | $0 |
+| Pre-flight hit (id / testid / aria-label on picked node) | $0 |
+| LLM Round 1 — first call of session (cold prompt cache) | ~$0.0016 |
+| LLM Round 1 — subsequent call in session (cache warm) | ~$0.0007 |
+| LLM Round 2 — with previous-attempt context | ~$0.0009 |
+| LLM Round 3 | ~$0.0010 |
+
+**Prompt caching.** The system prompt (~1200 tokens) is byte-identical across heal calls. OpenAI caches it server-side after the first call; subsequent calls pay 75% less on the input portion. Cache persists 5–10 min in-memory, up to 24 h on supported models.
+
+**Typical session.** Pre-flight handles ~30% of heals for free. Cache hits cover the rest after the first run. Median per-heal cost: **$0 to $0.0007**.
+
+**Daily budget.** 100 heals across mixed paths: $0.05–$0.10. Annual cost for a daily user: ~$15–$30 after week-1 warm-up. First week may run $1–2 while cache entries accumulate.
+
+A session summary is printed to stderr at process exit:
+
+```
+[HEAL] SESSION LLM COST SUMMARY
+[HEAL]   calls:  4
+[HEAL]   tokens: 6,842in (5,200 cached, 76%) + 948out
+[HEAL]   cost:   $0.003204 USD
+[HEAL]   savings from prompt cache:   $0.001740 USD
+```
+
+For per-day rollups, run the bundled CLI:
+
+```bash
+npx heal-report
+```
+
+Output: a markdown table of date, calls, cost, cache-hit-rate, cumulative cost across the lifetime of `.healed-locators/cost.daily.json`.
+
+---
+
+## Known limitations
+
+- **No iframe support.** The auto-fixture proxies `page.locator` / `page.getBy*` but not `page.frameLocator(...).locator(...)`. Tests that target DOM inside an iframe (third-party widgets, embedded payment forms, TinyMCE editors, etc.) will not heal. Workaround: refactor the iframe locator into a Page Object Method that catches its own timeout, OR add a non-iframe alternative selector in the test source.
+- **No closed-shadow-DOM support.** Closed shadow roots cannot be pierced from outside the host; the pick handler surfaces a clear `HealingError('shadow-unsupported')` instead of opening the overlay against the wrong element. Open shadow roots work fine via `composedPath()`.
+- **OpenAI only (v0.1).** Multi-provider support (Anthropic, Gemini, local) is on the v1.x roadmap.
+- **No auto-rewriting of test source.** The library writes the cache; it never modifies your `.spec.ts` files. After a heal session, `report.md` lists what changed so you can fold the healed selector back into source manually when convenient.
+- **Local-dev tool.** CI cannot run the interactive overlay. Setting `HEAL_HEADLESS=1` (or `CI=1`) puts the library in cache-only mode: hits return, misses fast-fail with a clear `no-operator-in-ci` error. Always commit `.healed-locators/` so CI starts warm.
+
+---
+
+## FAQ
+
+**Q: Does this work in CI?**
+
+Not interactively. The overlay requires a headed browser. In CI, set `HEAL_HEADLESS=1`: cache hits return silently, cache misses rethrow the original error without calling the LLM. Commit `.healed-locators/` to version control so CI always starts with warm cache.
+
+**Q: Where is the cache stored?**
+
+`.healed-locators/<spec-filename>.json` in your project root — one file per test file. Plain JSON, safe to commit, human-readable. Alongside it: `audit.ndjson` (one line per heal event), `llm-calls.ndjson` (raw OpenAI usage for independent cost verification), and `cost.daily.json` (per-day rollup the `heal-report` CLI reads).
+
+**Q: What happens if `OPENAI_API_KEY` is not set?**
+
+Stages 0–3 run normally (live re-check, cache, overlay pick, pre-flight). Stage 4 throws `HealingError` with category `config` and a clear message pointing at the missing env var. Tests that reach Stage 4 without a key fail fast.
+
+**Q: The healed locator is not being applied back to my test source — why?**
+
+By design. The library writes the cache (`.healed-locators/`) and an append-only `report.md`. It does **not** rewrite test source code. After a heal session, open `report.md`: it lists the spec file, line number, broken selector, and healed selector so you can apply the change manually if you wish.
+
+**Q: Can I use a different LLM provider?**
+
+Not in v0.1. Only OpenAI-compatible models via `HEAL_MODEL` are supported. Multi-provider abstraction is on the v1.x roadmap.
+
+**Q: Does it heal locators inside iframes?**
+
+No (see Known limitations). Tests targeting DOM inside `frameLocator(...)` will not heal. Use a non-iframe alternative selector in the test, or wrap the iframe interaction in a try/catch that falls back to a manual locator.
+
+**Q: How big is the install?**
+
+Tarball ~120 kB on disk after npm install. Runtime peer dep: `@playwright/test ^1.59.0`. Runtime deps: `openai`, `zod`, `dotenv`.
+
+**Q: My team is worried about an LLM editing test code.**
+
+It doesn't. The LLM only proposes a selector string; you click "accept" before any cache is written; the test source itself is never touched. The healed selector lives in `.healed-locators/<spec>.json` next to your tests — plain JSON, hand-editable, schema-validated on read.
+
+**Q: What about parallel test runs writing the same cache file?**
+
+Atomic writes (tmpfile + rename) at the cache layer. Per-page heal lock prevents two concurrent heals on the same page from racing the overlay. For full isolation across Playwright projects, set `HEAL_CACHE_DIR=$(pwd)/.healed-locators-${project}`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+For installation patterns, CI recipes, troubleshooting, and advanced configuration, see [USAGE.md](USAGE.md). For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md). For the version history, see [CHANGELOG.md](CHANGELOG.md).

package/USAGE.md

@@ -0,0 +1,217 @@
+# Usage Guide — `playwright-locator-healer`
+
+Drop-in self-healing for an existing Playwright suite. Most projects need a one-line import swap.
+
+---
+
+## 1. Install
+
+```bash
+npm install --save-dev playwright-locator-healer
+```
+
+Requires:
+- Node 20+
+- `@playwright/test` 1.59+ (declared as `peerDependencies`)
+- OpenAI API key — only when the LLM stage runs (cache hits + pre-flight are free)
+
+```bash
+# .env in your project root
+OPENAI_API_KEY=sk-...
+```
+
+---
+
+## 2. Two integration modes — pick one per test file
+
+### Mode A — Auto-fixture (recommended, zero test changes)
+
+Swap the import line; everything else stays the same.
+
+```ts
+// tests/login.spec.ts
+import { test, expect } from 'playwright-locator-healer/auto';
+
+test('login', async ({ page }) => {
+  await page.goto('https://example.com');
+  await page.locator('#submit').click();                     // heals on TimeoutError
+  await expect(page.locator('.welcome')).toBeVisible();      // assertion also heals
+});
+```
+
+The fixture proxies `page` (and chained locators) plus `expect`. Any locator action or web-first assertion that hits `TimeoutError` opens the heal overlay. The action is retried against the healed locator and execution continues from the same step.
+
+Wrapped action methods: `click`, `dblclick`, `fill`, `check`, `uncheck`, `hover`, `type`, `press`, `selectOption`, `tap`, `focus`, `blur`, `clear`, `dragTo`, `setInputFiles`, `pressSequentially`, `scrollIntoViewIfNeeded`.
+
+Wrapped chain methods: `locator`, `getByRole`, `getByText`, `getByLabel`, `getByTestId`, `getByPlaceholder`, `getByTitle`, `getByAltText`, `filter`, `first`, `last`, `nth`, `and`, `or`.
+
+Plus `expect(loc).to*`, `expect.soft(loc).to*`, and `.not.to*` matchers.
+
+### Mode B — Opt-in fixture (legacy / explicit)
+
+Useful for incremental migration of a Page Object Model, or when you want to gate exactly which calls can heal.
+
+```ts
+import { test, expect } from 'playwright-locator-healer/test';
+
+test('signup', async ({ page, heal }) => {
+  await page.goto('/signup');
+
+  try {
+    await page.locator('#submit-btn').click({ timeout: 5_000 });
+  } catch {
+    const { healedSelector } = await heal({
+      originalSelector: '#submit-btn',
+      action: 'click',
+      description: 'submit button on signup form',
+    });
+    await page.locator(healedSelector).click();
+  }
+});
+```
+
+`heal()` returns a `HealEntryV2` with `healedSelector`, `selectorType` (`role` / `testid` / `css` / `xpath` / `text`), and the `tier` the LLM landed on. On subsequent runs the cache makes the call essentially free.
+
+---
+
+## 3. Running tests
+
+```bash
+# Day-to-day — headed so the overlay can open when locators break
+npx playwright test --headed
+
+# CI — cache hits return, misses rethrow without any LLM call
+HEAL_HEADLESS=1 npx playwright test
+
+# Fresh heal (wipe cache)
+rm -rf .healed-locators && npx playwright test --headed
+
+# Switch model for one session
+HEAL_MODEL=gpt-4.1 npx playwright test --headed
+
+# Per-day cost + cache-hit-rate rollup
+npx heal-report
+```
+
+---
+
+## 4. Configuration
+
+See README's "Environment variables" table for the full list. Most-touched:
+
+| Variable | Purpose |
+|---|---|
+| `OPENAI_API_KEY` | Required when an LLM round actually runs. |
+| `HEAL_HEADLESS=1` | CI mode. Cache-hit-or-fail. No overlay, no LLM. |
+| `HEAL_MODEL` | `gpt-4.1-mini` (default), `gpt-4.1`, `gpt-4.1-nano`, `gpt-5.4-mini`, `gpt-5.4-nano`. |
+| `HEAL_LOG_LEVEL` | `debug` / `info` / `warn` (default) / `error` / `silent`. |
+| `HEAL_CIRCUIT_THRESHOLD` | Consecutive LLM failures before fast-fail kicks in (default 3). |
+
+---
+
+## 5. Cache directory layout
+
+```
+.healed-locators/
+  <spec-filename>.json      # selector cache, keyed by original selector + action
+  audit.ndjson              # one JSON line per heal event
+  llm-calls.ndjson          # raw OpenAI usage per call (cost cross-verification)
+  cost.daily.json           # per-day + all-time totals (npx heal-report reads this)
+  report.md                 # human-readable heal log (spec + line + before/after)
+  screenshots/              # failure screenshots when Stage 5 exhausts
+```
+
+**Commit `.healed-locators/` to git.** CI then starts with warm cache and pays $0. Skip it in `.gitignore` and every CI run pays for fresh heals.
+
+Cache entry shape (v2):
+
+```json
+{
+  "version": 2,
+  "entries": {
+    "#submit-btn|click": {
+      "originalSelector": "#submit-btn",
+      "action": "click",
+      "healedSelector": "Submit",
+      "selectorType": "text",
+      "intent": "submit button on signup form",
+      "callSite": "tests/signup.spec.ts:42:18",
+      "healedAt": "2026-05-16T14:22:03Z"
+    }
+  }
+}
+```
+
+---
+
+## 6. Writing good `description` / intent strings
+
+For the opt-in API: pass `description`. For the auto-fixture: type the intent in the overlay. A strong description directly improves locator stability.
+
+Bad — derived from the broken selector:
+
+```ts
+description: `element with selector ${sel}`
+```
+
+Good — purpose + location + region:
+
+```ts
+description: 'the Submit button at the bottom of the login form, below the password input'
+```
+
+Include:
+- **Kind:** button, link, input, dropdown
+- **Purpose:** "submits the form", "opens search modal"
+- **Location:** "top navbar", "left sidebar Getting Started section", "inside the modal"
+
+---
+
+## 7. CI patterns
+
+```bash
+# Pattern A — committed cache (recommended). $0 LLM cost in CI.
+HEAL_HEADLESS=1 npx playwright test
+```
+
+The recommended workflow: dev heals locally headed, commits the updated `.healed-locators/<spec>.json`, CI consumes the warm cache via `HEAL_HEADLESS=1`.
+
+---
+
+## 8. Troubleshooting
+
+| Symptom | Cause + fix |
+|---|---|
+| `HealingError: API key not set` | `.env` not loaded. `import 'dotenv/config'` at the top of `playwright.config.ts`, or pass `OPENAI_API_KEY=...` inline. |
+| `[heal] LLM circuit breaker open` | 3+ consecutive LLM failures (network / 429). Wait; the breaker auto-resets on the next successful call. Bump `HEAL_CIRCUIT_THRESHOLD` for more tolerance. |
+| `[HEAL] cache entry rejected for X` | Malformed entry in `.healed-locators/<spec>.json`. Heal proceeds fresh. Delete the line or the file to silence. |
+| Heal lands on the wrong element | Vague description / intent. Be more specific in the overlay or in the `description` field. |
+| Tests pass locally but fail in CI | CI lacks `OPENAI_API_KEY` and `.healed-locators/` is not committed. Pick one: commit cache (free) or set the CI secret. |
+| `Stage 5 exhausted` on a known-good element | LLM couldn't disambiguate. Inspect `audit.ndjson` last entry — `suggestionsTried` shows what failed. Strengthen the description with a parent landmark. |
+
+---
+
+## 9. Errors
+
+| Class | When | Test outcome |
+|---|---|---|
+| `HealCancelledError` | User pressed Esc in the overlay | Fails |
+| `HealExhaustedError` | All LLM rounds produced no valid locator | Fails |
+| `HealLLMError` | OpenAI API failure (network / auth / 429) | Fails |
+| `HealingError` (category `circuit-open`) | Circuit breaker has tripped | Fast-fail |
+| `HealingError` (category `invalid-cache`) | Malformed cache entry rejected at read | Heal proceeds fresh |
+| `HealingError` (category `invalid-filter-chain`) | LLM emitted a too-deep filter chain | Suggestion skipped |
+| `HealingError` (category `config`) | Missing `OPENAI_API_KEY` etc. | Fails |
+
+All errors carry `context: { originalSelector, action, callSite, attempts? }`.
+
+---
+
+## 10. Minimum drop-in diff
+
+```diff
+- import { test, expect } from '@playwright/test';
++ import { test, expect } from 'playwright-locator-healer/auto';
+```
+
+That's it. Run normally. The next time a selector breaks, the overlay opens; pick it once and every future run is free.

package/dist/healing/audit-log.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Append one JSON line to an audit ndjson file. Failures are logged to
+ * stderr (with the failing entry's keys, never the values) and re-thrown
+ * so callers can decide to swallow or propagate. The previous
+ * `.catch(() => {})` silent-swallow pattern hid I/O issues (disk full,
+ * permission denied, read-only mount, etc.).
+ */
+export declare function appendAuditLine(filePath: string, entry: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=audit-log.d.ts.map

package/dist/healing/audit-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.d.ts","sourceRoot":"","sources":["../../healing/audit-log.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAYf"}