tamash-playwright 0.11.0 → 0.12.0-beta.2

package/CHANGELOG.md

@@ -1,426 +1,460 @@
-# Changelog
-
-All notable changes to this project are documented here. Format loosely follows
-[Keep a Changelog](https://keepachangelog.com/); dates are when each version was published.
-
-## [0.11.0] - 2026-08-31
-
-### Fixed
-
-- **`skills/tamash-playwright/references/heal.md` never told the agent the Playwright HTML report exists at the point it matters.** It only pointed at `npx playwright show-report` at the very end (the REPORT step), after the loop was already finished — not right after RUN, where the report's per-attempt annotation and JSON attachment (provider, vision/action-recovery involvement, suggested selector, token cost, failure stage) would actually help decide what to do next. Found by directly auditing the skill against every documented user workflow step, not by running it. Fixed: RUN now explicitly says what the report contains and when it's worth opening.
-
-- **`doctor`'s connectivity check gave false confidence for `claude-subscription`/`copilot-subscription`.**
-  It tested against a fixed, generous 15s timeout, completely decoupled from the project's real
-  configured `actionTimeout` — so a project using the README's own example value (`actionTimeout:
-  8000`) could get `[OK] Connected successfully` from `doctor`, then have its very first real heal
-  in a fresh test run fail with a misleading "not authenticated?" warning, because these two
-  providers spawn the vendor's own CLI as a subprocess and the first call in a process pays a
-  one-time cold-start cost (spawning + authenticating) on top of the actual model call — a cost
-  `doctor`'s own generous timeout never had to absorb. Found via a real, unbriefed agent walkthrough
-  of a from-scratch setup (see the skill entry below): it hit this exact failure, correctly
-  diagnosed the root cause from a source-code comment nothing user-facing ever surfaced, and worked
-  around it by raising `actionTimeout` to 20000ms. Fixed at the actual source: `doctor` now tests
-  connectivity within the project's real `actionTimeout` when one's configured (falling back to the
-  old generous default only when none is set yet), and a `[FAIL]` for either of these two providers
-  now explicitly suggests it may be the cold-start cost rather than a real auth problem. Verified
-  against the real `copilot-subscription` provider — confirmed the check now genuinely uses the
-  configured timeout (not just that it compiles); could not force a deterministic before/after
-  repro of the timeout itself in this environment, since the underlying race is timing/environment-
-  dependent (a warm local CLI session can mask it, exactly as the original cold-start comment
-  already described).
-
-- **The published package was silently carrying stale, orphaned compiled output.** `npm run build`
-  (plain `tsc`, no `--build`/incremental mode) never deletes `dist/` output for a source file that
-  was later removed — found in the `0.11.0-beta.1` publish itself: `dist/healer/providers/
-  claude-cli.js`/`copilot-cli.js` shipped in the tarball with no corresponding source file
-  anywhere in the repo (from an abandoned, never-committed, never-wired-up piece of past work) —
-  dead code nothing actually imports, but real, needless bloat in every install. Fixed by cleaning
-  `dist/` automatically before every build (`prebuild` script), verified by confirming a full
-  rebuild no longer produces those two files.
-
-- **A popup/new tab opened via `context.waitForEvent('page')`, `page.on('popup', ...)`, or
-  `page.waitForEvent('popup')` was never healing-aware.** `bindContext`/`bindPageActions` already
-  made `context.newPage()`/`context.pages()`/`context.on('page', ...)` heal correctly, but these
-  three — including `context.waitForEvent('page')`, the pattern most commonly taught for popup
-  handling — fell through to a raw, unwrapped Playwright page. A broken locator inside the
-  resulting page just threw a plain timeout, with no `[self-healer]` line at all: healing was never
-  attempted, not just unsuccessful. Found while building the first-ever test for popup healing
-  (previously implemented with zero coverage); fixed by extending both bindings to wrap whatever
-  page these three hand back, the same way `newPage()` already did.
-
-- **`tamash` (the rule-based provider) declined on a real, common page pattern it should have
-  resolved.** A floating label rendered as its own text node right next to a field whose accessible
-  name is *also* that same text (confirmed on a real login page: a "Username" label next to a field
-  that's itself named "Username") was miscounted as two competing candidates and declined, even
-  though there's genuinely only one field. `findRuleBasedMatch` now only treats a match as a real
-  competing candidate when it's independently resolvable on its own (has a ref and a plausible
-  role) — a bare text node repeating the same words is decorative, not a second option. Genuine
-  ambiguity (two actually-independent candidates) still declines exactly as before.
-
-- **The HTML report's self-healing attachment was a wall of escape sequences on a failed
-  heal.** Playwright's own error messages embed ANSI colour codes in their "Call log" section;
-  the healer stored those raw in `report.reason` / `report.warning` / `attempts[].error`, and
-  `JSON.stringify` (which builds the `self-healing-<action>` attachment) escapes every ESC byte in the JSON, so a *not-healed* report rendered as unreadable escape soup. A
-  *successful* heal has short or absent error strings, which is why it only showed up on failures.
-  Fixed by stripping ANSI CSI sequences in `normalizeError` — the single point every captured
-  error passes through — so the attachment, the console line, and `heals.jsonl` are all plain
-  text. Verified against a real not-healed run.
-
-- **The three CLI-based subscription providers (`cursor-subscription`, `kiro-subscription`,
-  `codex-subscription`) were verified against their real vendor CLIs for the first time — and none
-  of the three actually worked as shipped.** Four separate bugs, all found by running them, all now
-  fixed:
-  1. **`cursor-subscription` never returned a heal.** `agent -p` refuses to run in any directory
-     without workspace trust — it prints "Workspace Trust Required" and exits without answering.
-     Now passes `--trust --mode ask`; `--mode ask` is Cursor's own read-only Q&A mode ("read-only"
-     per its `--help`), which *removes* the old "has access to all tools, could edit a file"
-     caveat this provider carried — a heal call in `ask` mode cannot write or run anything.
-  2. **`codex-subscription` refused to run outside a Git repository** ("Not inside a trusted
-     directory and --skip-git-repo-check was not specified"). Now passes `--skip-git-repo-check`;
-     this only relaxes the where-may-I-run guard, not the sandbox — `codex exec` still runs
-     `approval: never` + read-only, the property this provider depends on.
-  3. **`codex exec` hung on stdin.** It drains stdin ("Reading additional input from stdin…") and
-     blocks until EOF; `runCliPrompt` left the child's stdin as an open pipe, so every call ran to
-     the timeout and was killed — confirmed: a prompt the CLI answers in ~8s "timed out" at 15s.
-     `runCliPrompt` now gives every child an already-closed stdin (`stdio: ['ignore', …]`),
-     harmless for `agent`/`kiro-cli`, the fix for `codex`.
-  4. **The JSON parsers failed on conversational output.** `parseSuggestion` /
-     `parseVisionSuggestion` / `parseActionTacticSuggestion` extracted JSON from prose with a
-     greedy first-`{`-to-last-`}` slice, which breaks the moment the response contains more than
-     one JSON object — exactly what cursor's `agent` produces (it echoes the system prompt's
-     example objects back before its real answer). Replaced with a balanced-brace-span scan that
-     takes the last valid object (a model states its answer last), old greedy slice kept as a last
-     resort. Improves robustness for every provider, not just the CLI ones.
-
-  Verified live, all authenticated: `doctor` reports `[OK] Connected` for all three; a real
-  `npx playwright test` heal (broken locator, cache cleared) went green with
-  `HEALED [provider=codex-subscription]`, and `kiro-subscription` healed the same spec.
-
-- **`cursor-subscription` reliability note.** Verifying it (see above) showed Cursor's `agent` CLI
-  is an interactive assistant rather than a one-shot completion endpoint — given the heal prompt it
-  often answers conversationally instead of with the required JSON, so the heal is declined more
-  often than with `kiro`/`codex`. It's now invoked in the safest/best-effort form
-  (`agent -p --trust --mode ask --output-format json`, read-only) and is marked **experimental**;
-  the docs point to `kiro`/`codex` as the steadier local-subscription options. Report issues.
-  Also: the full e2e healing suite (12 tests) was run end to end against `copilot-subscription` and
-  `ollama` — **12/12 each** — to confirm the parser rewrite and provider changes don't regress it.
-
-### Added
-
-- **`npx tamash-playwright init-skill` — one command to install the orchestration skill, plus a
-  `doctor` check that flags when it's missing or stale.** The skill this package ships
-  (`skills/tamash-playwright/`) was previously a copy-this-shell-one-liner-per-agent step buried in
-  `SKILL.md`, with nothing verifying it had been done — so a project could `npm install` the
-  package, never copy the skill, and its assistant would silently never load the workflow.
-  `init-skill` copies the skill (`SKILL.md` + `references/`) into **both** standard locations —
-  `.claude/skills/tamash-playwright/` (Claude Code) and `.agents/skills/tamash-playwright/` (the
-  emerging cross-tool standard, read by Cursor, GitHub Copilot, Windsurf, Kiro, Zed, dotnet Aspire,
-  … — the same convention Playwright's own `playwright-cli install --skills` uses). Same content in
-  both; no per-agent format conversion. `--target claude` / `--target agents` installs one; `--user`
-  installs under your home directory; `--force` overwrites a hand-edited copy; `--dry-run` previews.
-  Each install carries a `tamash-playwright-skill-version:` marker; `doctor`'s **Skill** section
-  reads it and reports `[OK]` current / `[WARN]` behind-the-package-version / `[INFO]` not-installed
-  or unmanaged, with the same one-line fix. Covered by unit tests (`skill.test.js`, real installs
-  into a temp dir) and verified live end to end.
-
-  *(0.11.0-beta.7 shipped an earlier `init-skill` that instead auto-detected the agent and wrote a
-  Cursor-specific `.mdc` file / appended blocks to `.github/copilot-instructions.md` and
-  `AGENTS.md`. That approach is gone — `init-skill` and `doctor` now point out any such leftovers
-  from a beta.7 install so you can delete them by hand.)*
-
-- **`doctor`'s AI Provider check now tells you *what kind* of failure it hit and what to do about
-  it, instead of one generic "no valid response".** Every provider gained an optional, diagnostics-
-  only `diagnose()` method (never on the healing hot path) that runs one trivial round trip and
-  reports a structured category — `not-installed`, `not-authenticated`, `timeout`, `bad-model`,
-  `network`, `bad-response` — each of which `doctor` maps to a specific next step: the missing
-  `npm install`/CLI installer for a missing SDK; "run `claude login` / check your API key / confirm
-  your subscription is active and within quota" for a rejected request; "raise `actionTimeout`" (plus
-  the existing subprocess cold-start note) for a timeout; "check `<MODEL>` in your .env" for a
-  rejected model id; a network/proxy/base-URL hint for a connection failure. The raw error line is
-  still printed verbatim beneath the guidance. Previously `doctor` could only distinguish "worked"
-  from "didn't" — a missing SDK, an expired login, a slow network and a wrong model name all
-  produced the same line. Providers that don't implement `diagnose()` fall back to the old
-  `suggestSelector()` probe (worked/didn't, plus a timing-based timeout guess). Verified live:
-  `openai` bad key -> `not-authenticated` (401 body shown), `openai` bad base URL -> `network`,
-  `copilot-subscription` bad model id -> `bad-model`, 1ms `actionTimeout` -> `timeout` with the
-  raise-the-timeout guidance, and all three not-installed shapes by moving the dependency out of
-  resolution and restoring it: `@github/copilot-sdk` (CJS `MODULE_NOT_FOUND`),
-  `@anthropic-ai/claude-agent-sdk` (ESM `ERR_MODULE_NOT_FOUND`), and a missing `kiro-cli` binary
-  (`ENOENT`) -- each surfacing `not-installed` with its exact install command.
-
-- **Three new local-development-only subscription providers: `cursor-subscription`,
-  `kiro-subscription`, `codex-subscription`.** Extends the same "use what you're already paying
-  for" idea `claude-subscription`/`copilot-subscription` already give, to three more real
-  subscriptions — but each is explicitly scoped to local development, never documented or
-  recommended for CI, for two genuinely different reasons found by checking real vendor docs before
-  writing any code. Cursor's and Kiro's own headless-mode docs confirm neither has a way to fully
-  disable tool/file/command access the way `claude-subscription`'s `tools: []`/`copilot-subscription`'s
-  `availableTools: []` do — Cursor's `agent -p` "has access to all tools" by its own docs, and Kiro's
-  headless mode requires `--trust-all-tools`/`--trust-tools` specifically because there's no one to
-  approve a tool call unattended; `kiro-subscription` deliberately never grants that trust, so a
-  tool-requiring response just times out and declines rather than being granted broad access.
-  `codex-subscription` is local-only for a different, simpler reason: `codex exec` (used here, not
-  the interactive REPL) defaults to a read-only sandbox with no approval prompts — already as safe
-  as the two existing subscription providers — but no long-lived, subscription-only token for
-  unattended CI use is confirmed to exist for it yet. None of the three vendors ship a Node SDK, so
-  all three are `child_process` wrappers around the vendor's own CLI binary (`agent`, `kiro-cli`,
-  `codex`) via a new shared `runCliPrompt` helper, rather than the SDK-based design the existing two
-  use — meaning every call pays a fresh process-spawn cost, not just the first the way
-  `copilot-subscription`'s warm shared client does; `doctor` now has a distinct hint explaining this
-  when one of these three fails within a tight `actionTimeout`. Investigated and explicitly ruled
-  out this round: Antigravity — its dedicated `google-antigravity` SDK is Python-only (this is a
-  Node/TypeScript package), has no documented tool-restricted mode at all, and its authentication
-  story isn't published, so it isn't even confirmed to ride on an existing subscription. Verified:
-  real graceful-decline behavior confirmed against genuinely uninstalled CLIs (no fabricated
-  simulation), and the full `doctor` integration (including the new every-call-cost hint) confirmed
-  against a real sample repo. **Not yet verified**: the actual happy path against a real installed
-  and authenticated CLI for any of the three — none were available in the development environment,
-  and all three require a real paid subscription account.
-
-- **A skill for running this package's local workflow inside an AI coding assistant.** Ships at
-  `skills/tamash-playwright/` — a `SKILL.md` entry point that branches on `npx tamash-playwright
-  doctor`'s actual output (never assumed), plus two reference docs: `onboarding.md` (bringing a
-  project up to standard — provider setup, `actionTimeout`, `.describe()` labels, Page Object
-  extraction) and `heal.md` (a gated review/apply/verify/land loop over `apply-heals` and
-  `verify-heals.cjs` — most runs proceed start to finish unattended, pausing only for a genuinely
-  ambiguous fix or anything after a failed verification, and never landing/committing/opening a PR
-  without asking first, no matter how clean the run was). Pure orchestration over commands that
-  already exist — no new healing capability. Ships with adapters for Claude Code, Kiro (identical
-  `SKILL.md` format, confirmed against Kiro's own docs), Cursor (`.mdc` rule), GitHub Copilot
-  (`copilot-instructions.md` section), and an `AGENTS.md` covering the broader cross-tool standard
-  (Antigravity, Gemini CLI, Windsurf, Zed, Aider, and others) — none of which are auto-discovered
-  from `node_modules` by any of these tools, confirmed rather than assumed, so every adapter's
-  install step is one explicit copy command, documented in `SKILL.md` itself.
-- **A new `tamash` heal provider — rule-based healing, no AI at all.** `HEALER_PROVIDER=tamash`
-  needs no API key, no subscription, and makes no network call: it resolves a broken locator by
-  text-matching the same description an AI provider would receive (`.describe()`, or a decoded
-  variable name — see below) against the already-captured accessibility snapshot, then reuses the
-  exact same structural widening (`near`/`adjacent`) the AI-backed path already uses once it finds
-  the right anchor — same output shape, same downstream code, zero duplicated logic. It shares the
-  same non-negotiable discipline as every text-matching step in this package: zero or more than one
-  match, at any point, means it declines rather than guesses — verified with a dedicated permanent
-  e2e suite covering direct matches, widened matches, and every decline path (including the known,
-  accepted limitation that a misleading type hint can't be second-guessed against). Genuinely a
-  different tool than the AI providers, not a free replacement for one: no vision fallback (nothing
-  to reason over a screenshot with) and no action-recovery tactics (those require understanding
-  *why* an action failed, which is inference this provider deliberately doesn't attempt) — a fast,
-  free, fully deterministic first line of defense, best suited to well-`.describe()`d,
-  Page-Object-style suites.
-- **A new `ollama-local` heal provider for self-hosted Ollama servers.** `HEALER_PROVIDER=ollama-local`
-  targets your own `ollama serve` instance or an internal company deployment, instead of Ollama
-  Cloud — a deliberately separate provider from `ollama`, not a flag on it, since the two have
-  genuinely different auth defaults: Ollama Cloud always requires `OLLAMA_API_KEY`, while
-  `OLLAMA_LOCAL_API_KEY` is optional, since a bare `ollama serve` has no authentication at all. Set
-  it only if your internal deployment sits behind a reverse proxy or API gateway that requires a
-  bearer token — verified against a real HTTP server both ways, confirming the `Authorization`
-  header is omitted entirely when no key is set, and sent correctly when one is. Prompted by a real
-  support request from a team wanting to use their own internally-hosted `gpt-oss:120b`.
-- **Undescribed, POM-style locator variables now get a real description automatically.** When
-  `.describe()` was never called, the healer already fell back to the locator's own variable/
-  property name (`txtEmployeeId`) as its best guess at intent — now that raw identifier is decoded
-  into the same kind of human-readable phrase `.describe()` would give: `txtEmployeeId` becomes
-  "Employee Id (textbox)", `submitButton` becomes "Submit (button)", recognizing both prefix-style
-  (`btnSubmit`) and suffix-style (`submitBtn`) naming, camelCase/snake_case/kebab-case, and correct
-  acronym boundaries (`employeeIDNumber` → "Employee ID Number"). Falls back to the raw identifier,
-  exactly as before, whenever nothing meaningful survives decoding (a placeholder name like `el1`,
-  or a bare affix with nothing else) — never a guess dressed up as a real description. Verified
-  live against a real, unpublished build in both sample repos (a real `copilot-subscription` call,
-  and — after finding and fixing a genuinely stale API key along the way — a real `ollama` call),
-  confirming the decoded description actually reaches the configured AI provider unchanged.
-
-## [0.10.0] - 2026-08-27
-
-### Fixed
-
-- **`waitFor()` is never sent to the AI.** It's a state check, not an action — a timeout on it can
-  mean a genuinely broken selector, or it can mean the element correctly never reached the expected
-  state (verifying something does NOT appear, or a real app issue), and there's no way to tell those
-  apart from the error alone. `expect(locator).toBeVisible()` was already permanently excluded from
-  healing for exactly this reason, but never reached this code at all (a separate path from the
-  Proxy-intercepted actions) — `waitFor` just never got the same treatment. Real, reported case: a
-  user's `waitFor` on a locator verifying an absence (where timing out was the *correct* outcome)
-  still burned 8175 tokens across a failed text attempt and a failed vision attempt before giving
-  up, for a heal that could never have succeeded. Now fails fast with a clear `state-wait-not-healed`
-  stage and zero AI calls; a real action (fill/click/...) on the same kind of broken locator is
-  unaffected.
-- **`claude-subscription` was burning a real, unnecessary amount of extra tokens.** The SDK's
-  `effort` option silently defaults to `'high'` ("deep reasoning") when left unset, and this
-  provider never set it — a small prompt-complexity increase (the `nearbyRef`/`nearbyText` addition
-  below) pushed adaptive thinking to reason unpredictably harder for a task that only ever needs to
-  return one line of JSON. Confirmed live via real CI runs: output tokens for the same heal went
-  from a 188-445 baseline up to 422-881, inconsistently, run to run. `thinking: { type: 'disabled' }`
-  + `effort: 'low'` removes the variability entirely — verified repeatedly at a steady 28-30 output
-  tokens, below even the pre-regression baseline, with no change to correctness.
-- **The primary ariaSnapshot capture no longer requests `boxes:true`.** Every node was paying for a
-  `[box=x,y,w,h]` annotation that nothing on the text/`ref` path (including the `nearbyRef`/
-  `adjacent`-strategy widening logic below) ever reads — it's purely topological. The one real
-  consumer (vision's own nearest-candidate lookup) already captures its own separate, fresh
-  snapshot, so this is genuinely free: verified live, input tokens dropped ~23% on a large real
-  page (3794 → 2937) with no loss of accuracy, and no change on small pages (box overhead scales
-  with node count).
-
-### Added
-
-- **Search-scoped snapshots**: before falling back to the full page, the healer now searches the
-  already-captured snapshot for the description's identifying phrase and, only when it matches
-  exactly one node, sends the AI a scoped excerpt (that node's own subtree plus every sibling
-  branch's subtree at each ancestor level up to the root) instead of the whole page — zero extra
-  browser round-trips, since it's pure processing on data already in memory. Falls back to the full
-  snapshot automatically whenever the search is empty or ambiguous, never a guess. Verified live
-  across every real failure mode found this session: 41% token reduction on a deeply-nested field,
-  66% when the target was inside what looked like an unrelated navigation menu (proving it finds
-  wherever the relevant text actually is, not "excludes the nav"), ~29% on a pair of identical
-  sibling fields that still had to be correctly disambiguated, and a clean, correct fallback when
-  the description doesn't match the page's real text at all.
-- **A new `adjacent` selector strategy**, fixing a real ambiguity in the existing `near` strategy:
-  when two fields with no identity of their own share a row/section (two dropdowns side by side,
-  say), `near`'s "climb to a shared ancestor, then search it for any element of this role"
-  approach matches both and gives up rather than risk the wrong one. The AI's `ref` response can
-  now optionally report `nearbyRef`/`nearbyText`/`nearbyRole` for a nameless target it identified;
-  `deriveDurableLocator` uses that hint to find the true common ancestor between the target and
-  its label — via each ref's own full ancestor chain, not by assuming either sits at a matching
-  depth — and, when they're proven to be immediate sibling branches, builds a precise CSS
-  `:text() + *` sibling match (or an xpath climb-then-step, when the label text turns out to be
-  nested below its own branch root). Verified live against a real configured provider, resolving
-  the correct field and never its same-row neighbor in both directions.
-- **Full attempt-history logging**: `SelfHealingReport` now carries an `attempts[]` array — one
-  entry per cache/ref/text/vision/action-recovery attempt actually made, each with its own
-  `succeeded`/`stage`/`error`. Previously only the *last* attempt's stage survived; an earlier
-  attempt's real failure (and the specific error it threw) was silently discarded the moment a
-  later attempt also failed — the exact shape of a real user-reported bug, where a genuine
-  candidate selector was shown next to an unrelated `vision_provider_error` with no way to tell
-  why the candidate itself hadn't worked. The attempt history now also prints directly to
-  console/CI output (not just the JSON attachment) whenever more than one attempt was made, on
-  both pass and fail — since that plain-text output is what most bug reports actually paste, not
-  an attachment nobody opens.
-- **`ariaSnapshot` is attached to the test report on failure** — the exact accessibility tree the
-  AI reasoned over, so a confusing report can be diagnosed against real evidence instead of a
-  separately-captured DevTools screenshot.
-
-## [0.9.0] - 2026-08-26
-
-### Fixed
-
-- **Heal-log visibility**: a heal with no reusable selector (a one-shot `ref` resolution, or a
-  vision-tagged point) was silently dropped from `heals.jsonl` entirely, even though it genuinely
-  fixed that run. Now logged for audit — with a clear `reviewNote` — whenever it has a suggestion
-  *or* a review note, without letting an audit-only entry shadow an older, real cached fix for the
-  same location.
-- **Vision support for `claude-subscription`/`copilot-subscription`**: both providers had
-  `supportsVision` hardcoded to `false` regardless of model. Both SDKs genuinely support image
-  input (Claude Agent SDK via an image content block; Copilot SDK via a `blob` attachment) —
-  implemented for real and verified live with actual screenshots, not just doctor's yes/no label.
-- **Argument forwarding in healed replays**: `replayAction()` only ever forwarded the first call
-  argument. A trailing options object (`click({ modifiers: [...] })`, `fill(value, { timeout })`,
-  `dispatchEvent`'s 3rd argument) was silently dropped on a healed replay — changing the action's
-  real behavior while still reporting a clean `HEALED`.
-- **`ref`-strategy replays now act through the derived durable locator, not the raw ref**:
-  `aria-ref=` locators never resolve for `dispatchEvent` at all (a Playwright-level limitation,
-  confirmed directly via `DEBUG=pw:api`), even though the identical element resolves instantly via
-  a `normalize()`-derived locator for that same action. Fixed by deriving the durable locator
-  *before* replaying and acting through it, falling back to the raw ref only when nothing durable
-  could be found. A related accuracy bug is fixed alongside it: the report/heal-log could
-  previously claim a derived selector "worked" even when its own replay had actually failed and a
-  fallback silently took over — now only the locator that genuinely performed the action is
-  reported or cached.
-- **`copilot-subscription` could hang a non-Playwright test runner indefinitely** — its shared
-  client keeps a connection open across calls for performance, which Playwright's own test runner
-  tolerates by force-exiting regardless, but a runner like Cucumber does not, so the process never
-  returned even after every test had already passed. Found live running a real Cucumber suite in
-  CI. `closeCopilotSubscriptionClient()` is now exported from the package's own entry point so any
-  non-Playwright consumer can call it from their own teardown hook (e.g. Cucumber's `AfterAll`).
-
-### Added
-
-- **`locator.getDurable(action?)`** — resolves any locator (most usefully one built from
-  `aria-ref=...`) to a durable, reusable equivalent (`getByRole`/`getByLabel`/a css selector/…),
-  using the same derivation logic self-healing already uses internally. Throws if nothing durable
-  could be derived, rather than silently handing back something untrusted.
-- **`apply-heals` now previews before writing**: every run — dry or real — shows a styled table of
-  exactly what it found (location, before, after, review status) instead of a plain scrolling log.
-  A real run also asks for confirmation before writing anything, but *only* at a genuine
-  interactive terminal — CI and any non-interactive/piped invocation proceed automatically exactly
-  as before, so no existing unattended CI workflow is affected. `--yes`/`-y` skips the prompt at a
-  real terminal too.
-- **`doctor`'s output is styled** with colors and tables (including a new end-of-run Summary
-  section) instead of a plain scrolling log.
-- **Exact locator code in console lines and reports**: a healed suggestion is now shown as the
-  real, copy-pasteable Playwright call (`getByRole("textbox", { name: "Username" })`) instead of
-  an abbreviated shorthand (`role:textbox:Username`) — the same code `apply-heals` would write to
-  source, so what you see is never a lossier stand-in for what was actually used.
-- A canonical Page Object Model usage example (`tests/pages/` +
-  `tests/example-orangehrm-add-employee.spec.ts`), verified live against a real OrangeHRM demo,
-  including a genuine self-heal via the `near`/widening strategy on a real unlabeled field.
-
-### Changed
-
-- README/usage.md's vision-fallback documentation now correctly lists `claude-subscription`/
-  `copilot-subscription` as vision-capable (with a suitable model), not just the API-key providers.
-
-## [0.8.0] - 2026-08-25
-
-### Added
-
-- `claude-subscription` and `copilot-subscription` heal providers — self-healing backed by a
-  personal Claude or GitHub Copilot subscription instead of a pay-per-token API key, working both
-  locally and unattended in CI (`CLAUDE_CODE_OAUTH_TOKEN` for Claude; the ambient `GITHUB_TOKEN` or
-  a personal-account PAT for Copilot on GitHub Actions).
-
-### Fixed
-
-- Missing CLI install step in setup docs for `claude-subscription`/`copilot-subscription` — the
-  standalone `claude`/`copilot` CLIs are genuinely required for the login step even though the SDKs
-  don't need them installed to function at runtime.
-
-### Documentation
-
-- The org-vs-personal-account Copilot licensing gotcha in CI (a repo owned by an organization
-  without its own Copilot enablement can't use a personal subscription via the ambient token).
-- Action Recovery (`HEALER_ACTION_RECOVERY_ENABLED`) hidden from docs and `doctor` output —
-  disabled by default already; this only reduced its visibility, no behavior change.
-
-## [0.7.0] - 2026-08-21
-
-### Added
-
-- `apply-heals` — turns a runtime heal into a permanent source-code fix, plus an opportunistic
-  cache (`heals.jsonl`) so a previously-confirmed selector is tried before a fresh AI call, and
-  history archival so a run's report/log isn't silently overwritten by the next one.
-- Position/relationship-based locator strategies (`near`, `scoped`, `containing`) for elements with
-  no accessible identity of their own.
-- Self-healing rebuilt around `ariaSnapshot({ mode: 'ai' })` + `aria-ref=` resolution and
-  `Locator.normalize()`, replacing pixel-distance guessing for both the text path and the vision
-  fallback's durability upgrade.
-- A real unit test suite (32 tests at the time, zero new dependencies).
-
-### Fixed
-
-- `doctor`'s `actionTimeout` check being fooled by a commented-out config value.
-- `apply-heals --logs-dir` silently losing raw heal-log archival.
-- `apply-heals` only replacing the first call when re-healing an already-`near`-fixed line.
-- `apply-heals` `ENOENT` on a fresh CI checkout with no `.tamash-playwright/` directory yet — the
-  sharded "apply-heals" CI job checks out fresh and has never run tests itself, so the directory
-  genuinely doesn't exist there the way it always does in every local recipe.
-- File path corruption (and a `require()` crash in the generated verification script) for ESM
-  (`"type": "module"`) consumer projects — `Error.stack` renders as a `file://` URL there, which
-  broke path resolution and a plain `.js` verification script alike.
-- The AI being misled by the broken selector still present in its own prompt context; a failed
-  label guess now auto-upgrades to a structural `near` match instead of giving up.
-
-### Verified
-
-- All four API-key providers (Ollama, OpenAI, Anthropic, Gemini) confirmed working with real API
-  calls, not just documented.
-
-## [0.6.0] - 2026-08-17
-
-### Added
-
-- iframe and popup healing, vision fallback (screenshot-based recovery when text alone isn't
-  enough), AI-driven action recovery (scroll/force/wait/dispatch), and source-location reporting.
-- `doctor`'s `actionTimeout` configuration check.
-
-### Initial release
-
-- Self-healing Playwright bindings: broken locators are recovered at runtime via an AI provider,
-  with `.describe()` for human-readable context.
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); dates are when each version was published.
+
+## [0.12.0-beta.2] - 2026-09-08
+
+### Added
+
+- **Playwright 1.63 support.** Dev/CI now tracks `@playwright/test` 1.63; `peerDependencies`
+  stays `>=1.40.0`. Verified: existing iframe healing (`page.frameLocator('#id')`) still heals,
+  and the full unit + representative e2e suite passes against 1.63.
+
+- **Healing through Playwright 1.63's no-argument `page.frameLocator()`.** 1.63 made
+  `frameLocator()`'s selector optional — with no argument it matches inside *any* frame on the
+  page. As a healing scope that's ambiguous the moment the page has more than one frame (the
+  healer's `locator('body')` snapshot then throws *"frameLocator() matched elements in multiple
+  frames"*, and healing silently no-op'd with `stage=no_snapshot`). Now, when the page has
+  exactly one frame, the healer re-expresses the no-arg `frameLocator()` as an explicit
+  single-frame `FrameLocator` and heals normally — including deriving a **durable, persistable**
+  cross-frame selector (`apply-heals` can write it back to source), identical to what
+  `page.frameLocator('#id')` produces. With zero or several frames it can't know which was meant,
+  so it steps aside cleanly — the original error is re-thrown, never a wrong-frame guess. For
+  healable work on a multi-frame page, pass an explicit selector: `page.frameLocator('#id')`.
+
+  *(`0.12.0-beta.1` collapsed the scope to a raw `page.frames()` `Frame` instead of a
+  `FrameLocator`. `Locator.normalize()` on a `Frame`-rooted locator returns a correct selector
+  string but an object that resolves to nothing, so the heal worked once at runtime but couldn't
+  be persisted — it fell back to a transient one-shot element reference with a `needsReview`
+  note. Fixed here.)*
+
+### Fixed
+
+- **`describeFactoryCall` rendered `iframe "undefined"` for a no-arg `frameLocator()`.** The
+  factory-call label helper assumed a selector argument was always present; with 1.63's optional
+  selector it produced the literal string `iframe "undefined"`. Now renders `any iframe`. (Latent
+  — the label isn't currently surfaced to users or the model, but it would be the moment any
+  "healing inside iframe X" context is added to a report or prompt.)
+
+## [0.11.0] - 2026-08-31
+
+### Fixed
+
+- **`skills/tamash-playwright/references/heal.md` never told the agent the Playwright HTML report exists at the point it matters.** It only pointed at `npx playwright show-report` at the very end (the REPORT step), after the loop was already finished — not right after RUN, where the report's per-attempt annotation and JSON attachment (provider, vision/action-recovery involvement, suggested selector, token cost, failure stage) would actually help decide what to do next. Found by directly auditing the skill against every documented user workflow step, not by running it. Fixed: RUN now explicitly says what the report contains and when it's worth opening.
+
+- **`doctor`'s connectivity check gave false confidence for `claude-subscription`/`copilot-subscription`.**
+  It tested against a fixed, generous 15s timeout, completely decoupled from the project's real
+  configured `actionTimeout` — so a project using the README's own example value (`actionTimeout:
+  8000`) could get `[OK] Connected successfully` from `doctor`, then have its very first real heal
+  in a fresh test run fail with a misleading "not authenticated?" warning, because these two
+  providers spawn the vendor's own CLI as a subprocess and the first call in a process pays a
+  one-time cold-start cost (spawning + authenticating) on top of the actual model call — a cost
+  `doctor`'s own generous timeout never had to absorb. Found via a real, unbriefed agent walkthrough
+  of a from-scratch setup (see the skill entry below): it hit this exact failure, correctly
+  diagnosed the root cause from a source-code comment nothing user-facing ever surfaced, and worked
+  around it by raising `actionTimeout` to 20000ms. Fixed at the actual source: `doctor` now tests
+  connectivity within the project's real `actionTimeout` when one's configured (falling back to the
+  old generous default only when none is set yet), and a `[FAIL]` for either of these two providers
+  now explicitly suggests it may be the cold-start cost rather than a real auth problem. Verified
+  against the real `copilot-subscription` provider — confirmed the check now genuinely uses the
+  configured timeout (not just that it compiles); could not force a deterministic before/after
+  repro of the timeout itself in this environment, since the underlying race is timing/environment-
+  dependent (a warm local CLI session can mask it, exactly as the original cold-start comment
+  already described).
+
+- **The published package was silently carrying stale, orphaned compiled output.** `npm run build`
+  (plain `tsc`, no `--build`/incremental mode) never deletes `dist/` output for a source file that
+  was later removed — found in the `0.11.0-beta.1` publish itself: `dist/healer/providers/
+  claude-cli.js`/`copilot-cli.js` shipped in the tarball with no corresponding source file
+  anywhere in the repo (from an abandoned, never-committed, never-wired-up piece of past work) —
+  dead code nothing actually imports, but real, needless bloat in every install. Fixed by cleaning
+  `dist/` automatically before every build (`prebuild` script), verified by confirming a full
+  rebuild no longer produces those two files.
+
+- **A popup/new tab opened via `context.waitForEvent('page')`, `page.on('popup', ...)`, or
+  `page.waitForEvent('popup')` was never healing-aware.** `bindContext`/`bindPageActions` already
+  made `context.newPage()`/`context.pages()`/`context.on('page', ...)` heal correctly, but these
+  three — including `context.waitForEvent('page')`, the pattern most commonly taught for popup
+  handling — fell through to a raw, unwrapped Playwright page. A broken locator inside the
+  resulting page just threw a plain timeout, with no `[self-healer]` line at all: healing was never
+  attempted, not just unsuccessful. Found while building the first-ever test for popup healing
+  (previously implemented with zero coverage); fixed by extending both bindings to wrap whatever
+  page these three hand back, the same way `newPage()` already did.
+
+- **`tamash` (the rule-based provider) declined on a real, common page pattern it should have
+  resolved.** A floating label rendered as its own text node right next to a field whose accessible
+  name is *also* that same text (confirmed on a real login page: a "Username" label next to a field
+  that's itself named "Username") was miscounted as two competing candidates and declined, even
+  though there's genuinely only one field. `findRuleBasedMatch` now only treats a match as a real
+  competing candidate when it's independently resolvable on its own (has a ref and a plausible
+  role) — a bare text node repeating the same words is decorative, not a second option. Genuine
+  ambiguity (two actually-independent candidates) still declines exactly as before.
+
+- **The HTML report's self-healing attachment was a wall of escape sequences on a failed
+  heal.** Playwright's own error messages embed ANSI colour codes in their "Call log" section;
+  the healer stored those raw in `report.reason` / `report.warning` / `attempts[].error`, and
+  `JSON.stringify` (which builds the `self-healing-<action>` attachment) escapes every ESC byte in the JSON, so a *not-healed* report rendered as unreadable escape soup. A
+  *successful* heal has short or absent error strings, which is why it only showed up on failures.
+  Fixed by stripping ANSI CSI sequences in `normalizeError` — the single point every captured
+  error passes through — so the attachment, the console line, and `heals.jsonl` are all plain
+  text. Verified against a real not-healed run.
+
+- **The three CLI-based subscription providers (`cursor-subscription`, `kiro-subscription`,
+  `codex-subscription`) were verified against their real vendor CLIs for the first time — and none
+  of the three actually worked as shipped.** Four separate bugs, all found by running them, all now
+  fixed:
+  1. **`cursor-subscription` never returned a heal.** `agent -p` refuses to run in any directory
+     without workspace trust — it prints "Workspace Trust Required" and exits without answering.
+     Now passes `--trust --mode ask`; `--mode ask` is Cursor's own read-only Q&A mode ("read-only"
+     per its `--help`), which *removes* the old "has access to all tools, could edit a file"
+     caveat this provider carried — a heal call in `ask` mode cannot write or run anything.
+  2. **`codex-subscription` refused to run outside a Git repository** ("Not inside a trusted
+     directory and --skip-git-repo-check was not specified"). Now passes `--skip-git-repo-check`;
+     this only relaxes the where-may-I-run guard, not the sandbox — `codex exec` still runs
+     `approval: never` + read-only, the property this provider depends on.
+  3. **`codex exec` hung on stdin.** It drains stdin ("Reading additional input from stdin…") and
+     blocks until EOF; `runCliPrompt` left the child's stdin as an open pipe, so every call ran to
+     the timeout and was killed — confirmed: a prompt the CLI answers in ~8s "timed out" at 15s.
+     `runCliPrompt` now gives every child an already-closed stdin (`stdio: ['ignore', …]`),
+     harmless for `agent`/`kiro-cli`, the fix for `codex`.
+  4. **The JSON parsers failed on conversational output.** `parseSuggestion` /
+     `parseVisionSuggestion` / `parseActionTacticSuggestion` extracted JSON from prose with a
+     greedy first-`{`-to-last-`}` slice, which breaks the moment the response contains more than
+     one JSON object — exactly what cursor's `agent` produces (it echoes the system prompt's
+     example objects back before its real answer). Replaced with a balanced-brace-span scan that
+     takes the last valid object (a model states its answer last), old greedy slice kept as a last
+     resort. Improves robustness for every provider, not just the CLI ones.
+
+  Verified live, all authenticated: `doctor` reports `[OK] Connected` for all three; a real
+  `npx playwright test` heal (broken locator, cache cleared) went green with
+  `HEALED [provider=codex-subscription]`, and `kiro-subscription` healed the same spec.
+
+- **`cursor-subscription` reliability note.** Verifying it (see above) showed Cursor's `agent` CLI
+  is an interactive assistant rather than a one-shot completion endpoint — given the heal prompt it
+  often answers conversationally instead of with the required JSON, so the heal is declined more
+  often than with `kiro`/`codex`. It's now invoked in the safest/best-effort form
+  (`agent -p --trust --mode ask --output-format json`, read-only) and is marked **experimental**;
+  the docs point to `kiro`/`codex` as the steadier local-subscription options. Report issues.
+  Also: the full e2e healing suite (12 tests) was run end to end against `copilot-subscription` and
+  `ollama` — **12/12 each** — to confirm the parser rewrite and provider changes don't regress it.
+
+### Added
+
+- **`npx tamash-playwright init-skill` — one command to install the orchestration skill, plus a
+  `doctor` check that flags when it's missing or stale.** The skill this package ships
+  (`skills/tamash-playwright/`) was previously a copy-this-shell-one-liner-per-agent step buried in
+  `SKILL.md`, with nothing verifying it had been done — so a project could `npm install` the
+  package, never copy the skill, and its assistant would silently never load the workflow.
+  `init-skill` copies the skill (`SKILL.md` + `references/`) into **both** standard locations —
+  `.claude/skills/tamash-playwright/` (Claude Code) and `.agents/skills/tamash-playwright/` (the
+  emerging cross-tool standard, read by Cursor, GitHub Copilot, Windsurf, Kiro, Zed, dotnet Aspire,
+  … — the same convention Playwright's own `playwright-cli install --skills` uses). Same content in
+  both; no per-agent format conversion. `--target claude` / `--target agents` installs one; `--user`
+  installs under your home directory; `--force` overwrites a hand-edited copy; `--dry-run` previews.
+  Each install carries a `tamash-playwright-skill-version:` marker; `doctor`'s **Skill** section
+  reads it and reports `[OK]` current / `[WARN]` behind-the-package-version / `[INFO]` not-installed
+  or unmanaged, with the same one-line fix. Covered by unit tests (`skill.test.js`, real installs
+  into a temp dir) and verified live end to end.
+
+  *(0.11.0-beta.7 shipped an earlier `init-skill` that instead auto-detected the agent and wrote a
+  Cursor-specific `.mdc` file / appended blocks to `.github/copilot-instructions.md` and
+  `AGENTS.md`. That approach is gone — `init-skill` and `doctor` now point out any such leftovers
+  from a beta.7 install so you can delete them by hand.)*
+
+- **`doctor`'s AI Provider check now tells you *what kind* of failure it hit and what to do about
+  it, instead of one generic "no valid response".** Every provider gained an optional, diagnostics-
+  only `diagnose()` method (never on the healing hot path) that runs one trivial round trip and
+  reports a structured category — `not-installed`, `not-authenticated`, `timeout`, `bad-model`,
+  `network`, `bad-response` — each of which `doctor` maps to a specific next step: the missing
+  `npm install`/CLI installer for a missing SDK; "run `claude login` / check your API key / confirm
+  your subscription is active and within quota" for a rejected request; "raise `actionTimeout`" (plus
+  the existing subprocess cold-start note) for a timeout; "check `<MODEL>` in your .env" for a
+  rejected model id; a network/proxy/base-URL hint for a connection failure. The raw error line is
+  still printed verbatim beneath the guidance. Previously `doctor` could only distinguish "worked"
+  from "didn't" — a missing SDK, an expired login, a slow network and a wrong model name all
+  produced the same line. Providers that don't implement `diagnose()` fall back to the old
+  `suggestSelector()` probe (worked/didn't, plus a timing-based timeout guess). Verified live:
+  `openai` bad key -> `not-authenticated` (401 body shown), `openai` bad base URL -> `network`,
+  `copilot-subscription` bad model id -> `bad-model`, 1ms `actionTimeout` -> `timeout` with the
+  raise-the-timeout guidance, and all three not-installed shapes by moving the dependency out of
+  resolution and restoring it: `@github/copilot-sdk` (CJS `MODULE_NOT_FOUND`),
+  `@anthropic-ai/claude-agent-sdk` (ESM `ERR_MODULE_NOT_FOUND`), and a missing `kiro-cli` binary
+  (`ENOENT`) -- each surfacing `not-installed` with its exact install command.
+
+- **Three new local-development-only subscription providers: `cursor-subscription`,
+  `kiro-subscription`, `codex-subscription`.** Extends the same "use what you're already paying
+  for" idea `claude-subscription`/`copilot-subscription` already give, to three more real
+  subscriptions — but each is explicitly scoped to local development, never documented or
+  recommended for CI, for two genuinely different reasons found by checking real vendor docs before
+  writing any code. Cursor's and Kiro's own headless-mode docs confirm neither has a way to fully
+  disable tool/file/command access the way `claude-subscription`'s `tools: []`/`copilot-subscription`'s
+  `availableTools: []` do — Cursor's `agent -p` "has access to all tools" by its own docs, and Kiro's
+  headless mode requires `--trust-all-tools`/`--trust-tools` specifically because there's no one to
+  approve a tool call unattended; `kiro-subscription` deliberately never grants that trust, so a
+  tool-requiring response just times out and declines rather than being granted broad access.
+  `codex-subscription` is local-only for a different, simpler reason: `codex exec` (used here, not
+  the interactive REPL) defaults to a read-only sandbox with no approval prompts — already as safe
+  as the two existing subscription providers — but no long-lived, subscription-only token for
+  unattended CI use is confirmed to exist for it yet. None of the three vendors ship a Node SDK, so
+  all three are `child_process` wrappers around the vendor's own CLI binary (`agent`, `kiro-cli`,
+  `codex`) via a new shared `runCliPrompt` helper, rather than the SDK-based design the existing two
+  use — meaning every call pays a fresh process-spawn cost, not just the first the way
+  `copilot-subscription`'s warm shared client does; `doctor` now has a distinct hint explaining this
+  when one of these three fails within a tight `actionTimeout`. Investigated and explicitly ruled
+  out this round: Antigravity — its dedicated `google-antigravity` SDK is Python-only (this is a
+  Node/TypeScript package), has no documented tool-restricted mode at all, and its authentication
+  story isn't published, so it isn't even confirmed to ride on an existing subscription. Verified:
+  real graceful-decline behavior confirmed against genuinely uninstalled CLIs (no fabricated
+  simulation), and the full `doctor` integration (including the new every-call-cost hint) confirmed
+  against a real sample repo. **Not yet verified**: the actual happy path against a real installed
+  and authenticated CLI for any of the three — none were available in the development environment,
+  and all three require a real paid subscription account.
+
+- **A skill for running this package's local workflow inside an AI coding assistant.** Ships at
+  `skills/tamash-playwright/` — a `SKILL.md` entry point that branches on `npx tamash-playwright
+  doctor`'s actual output (never assumed), plus two reference docs: `onboarding.md` (bringing a
+  project up to standard — provider setup, `actionTimeout`, `.describe()` labels, Page Object
+  extraction) and `heal.md` (a gated review/apply/verify/land loop over `apply-heals` and
+  `verify-heals.cjs` — most runs proceed start to finish unattended, pausing only for a genuinely
+  ambiguous fix or anything after a failed verification, and never landing/committing/opening a PR
+  without asking first, no matter how clean the run was). Pure orchestration over commands that
+  already exist — no new healing capability. Ships with adapters for Claude Code, Kiro (identical
+  `SKILL.md` format, confirmed against Kiro's own docs), Cursor (`.mdc` rule), GitHub Copilot
+  (`copilot-instructions.md` section), and an `AGENTS.md` covering the broader cross-tool standard
+  (Antigravity, Gemini CLI, Windsurf, Zed, Aider, and others) — none of which are auto-discovered
+  from `node_modules` by any of these tools, confirmed rather than assumed, so every adapter's
+  install step is one explicit copy command, documented in `SKILL.md` itself.
+- **A new `tamash` heal provider — rule-based healing, no AI at all.** `HEALER_PROVIDER=tamash`
+  needs no API key, no subscription, and makes no network call: it resolves a broken locator by
+  text-matching the same description an AI provider would receive (`.describe()`, or a decoded
+  variable name — see below) against the already-captured accessibility snapshot, then reuses the
+  exact same structural widening (`near`/`adjacent`) the AI-backed path already uses once it finds
+  the right anchor — same output shape, same downstream code, zero duplicated logic. It shares the
+  same non-negotiable discipline as every text-matching step in this package: zero or more than one
+  match, at any point, means it declines rather than guesses — verified with a dedicated permanent
+  e2e suite covering direct matches, widened matches, and every decline path (including the known,
+  accepted limitation that a misleading type hint can't be second-guessed against). Genuinely a
+  different tool than the AI providers, not a free replacement for one: no vision fallback (nothing
+  to reason over a screenshot with) and no action-recovery tactics (those require understanding
+  *why* an action failed, which is inference this provider deliberately doesn't attempt) — a fast,
+  free, fully deterministic first line of defense, best suited to well-`.describe()`d,
+  Page-Object-style suites.
+- **A new `ollama-local` heal provider for self-hosted Ollama servers.** `HEALER_PROVIDER=ollama-local`
+  targets your own `ollama serve` instance or an internal company deployment, instead of Ollama
+  Cloud — a deliberately separate provider from `ollama`, not a flag on it, since the two have
+  genuinely different auth defaults: Ollama Cloud always requires `OLLAMA_API_KEY`, while
+  `OLLAMA_LOCAL_API_KEY` is optional, since a bare `ollama serve` has no authentication at all. Set
+  it only if your internal deployment sits behind a reverse proxy or API gateway that requires a
+  bearer token — verified against a real HTTP server both ways, confirming the `Authorization`
+  header is omitted entirely when no key is set, and sent correctly when one is. Prompted by a real
+  support request from a team wanting to use their own internally-hosted `gpt-oss:120b`.
+- **Undescribed, POM-style locator variables now get a real description automatically.** When
+  `.describe()` was never called, the healer already fell back to the locator's own variable/
+  property name (`txtEmployeeId`) as its best guess at intent — now that raw identifier is decoded
+  into the same kind of human-readable phrase `.describe()` would give: `txtEmployeeId` becomes
+  "Employee Id (textbox)", `submitButton` becomes "Submit (button)", recognizing both prefix-style
+  (`btnSubmit`) and suffix-style (`submitBtn`) naming, camelCase/snake_case/kebab-case, and correct
+  acronym boundaries (`employeeIDNumber` → "Employee ID Number"). Falls back to the raw identifier,
+  exactly as before, whenever nothing meaningful survives decoding (a placeholder name like `el1`,
+  or a bare affix with nothing else) — never a guess dressed up as a real description. Verified
+  live against a real, unpublished build in both sample repos (a real `copilot-subscription` call,
+  and — after finding and fixing a genuinely stale API key along the way — a real `ollama` call),
+  confirming the decoded description actually reaches the configured AI provider unchanged.
+
+## [0.10.0] - 2026-08-27
+
+### Fixed
+
+- **`waitFor()` is never sent to the AI.** It's a state check, not an action — a timeout on it can
+  mean a genuinely broken selector, or it can mean the element correctly never reached the expected
+  state (verifying something does NOT appear, or a real app issue), and there's no way to tell those
+  apart from the error alone. `expect(locator).toBeVisible()` was already permanently excluded from
+  healing for exactly this reason, but never reached this code at all (a separate path from the
+  Proxy-intercepted actions) — `waitFor` just never got the same treatment. Real, reported case: a
+  user's `waitFor` on a locator verifying an absence (where timing out was the *correct* outcome)
+  still burned 8175 tokens across a failed text attempt and a failed vision attempt before giving
+  up, for a heal that could never have succeeded. Now fails fast with a clear `state-wait-not-healed`
+  stage and zero AI calls; a real action (fill/click/...) on the same kind of broken locator is
+  unaffected.
+- **`claude-subscription` was burning a real, unnecessary amount of extra tokens.** The SDK's
+  `effort` option silently defaults to `'high'` ("deep reasoning") when left unset, and this
+  provider never set it — a small prompt-complexity increase (the `nearbyRef`/`nearbyText` addition
+  below) pushed adaptive thinking to reason unpredictably harder for a task that only ever needs to
+  return one line of JSON. Confirmed live via real CI runs: output tokens for the same heal went
+  from a 188-445 baseline up to 422-881, inconsistently, run to run. `thinking: { type: 'disabled' }`
+  + `effort: 'low'` removes the variability entirely — verified repeatedly at a steady 28-30 output
+  tokens, below even the pre-regression baseline, with no change to correctness.
+- **The primary ariaSnapshot capture no longer requests `boxes:true`.** Every node was paying for a
+  `[box=x,y,w,h]` annotation that nothing on the text/`ref` path (including the `nearbyRef`/
+  `adjacent`-strategy widening logic below) ever reads — it's purely topological. The one real
+  consumer (vision's own nearest-candidate lookup) already captures its own separate, fresh
+  snapshot, so this is genuinely free: verified live, input tokens dropped ~23% on a large real
+  page (3794 → 2937) with no loss of accuracy, and no change on small pages (box overhead scales
+  with node count).
+
+### Added
+
+- **Search-scoped snapshots**: before falling back to the full page, the healer now searches the
+  already-captured snapshot for the description's identifying phrase and, only when it matches
+  exactly one node, sends the AI a scoped excerpt (that node's own subtree plus every sibling
+  branch's subtree at each ancestor level up to the root) instead of the whole page — zero extra
+  browser round-trips, since it's pure processing on data already in memory. Falls back to the full
+  snapshot automatically whenever the search is empty or ambiguous, never a guess. Verified live
+  across every real failure mode found this session: 41% token reduction on a deeply-nested field,
+  66% when the target was inside what looked like an unrelated navigation menu (proving it finds
+  wherever the relevant text actually is, not "excludes the nav"), ~29% on a pair of identical
+  sibling fields that still had to be correctly disambiguated, and a clean, correct fallback when
+  the description doesn't match the page's real text at all.
+- **A new `adjacent` selector strategy**, fixing a real ambiguity in the existing `near` strategy:
+  when two fields with no identity of their own share a row/section (two dropdowns side by side,
+  say), `near`'s "climb to a shared ancestor, then search it for any element of this role"
+  approach matches both and gives up rather than risk the wrong one. The AI's `ref` response can
+  now optionally report `nearbyRef`/`nearbyText`/`nearbyRole` for a nameless target it identified;
+  `deriveDurableLocator` uses that hint to find the true common ancestor between the target and
+  its label — via each ref's own full ancestor chain, not by assuming either sits at a matching
+  depth — and, when they're proven to be immediate sibling branches, builds a precise CSS
+  `:text() + *` sibling match (or an xpath climb-then-step, when the label text turns out to be
+  nested below its own branch root). Verified live against a real configured provider, resolving
+  the correct field and never its same-row neighbor in both directions.
+- **Full attempt-history logging**: `SelfHealingReport` now carries an `attempts[]` array — one
+  entry per cache/ref/text/vision/action-recovery attempt actually made, each with its own
+  `succeeded`/`stage`/`error`. Previously only the *last* attempt's stage survived; an earlier
+  attempt's real failure (and the specific error it threw) was silently discarded the moment a
+  later attempt also failed — the exact shape of a real user-reported bug, where a genuine
+  candidate selector was shown next to an unrelated `vision_provider_error` with no way to tell
+  why the candidate itself hadn't worked. The attempt history now also prints directly to
+  console/CI output (not just the JSON attachment) whenever more than one attempt was made, on
+  both pass and fail — since that plain-text output is what most bug reports actually paste, not
+  an attachment nobody opens.
+- **`ariaSnapshot` is attached to the test report on failure** — the exact accessibility tree the
+  AI reasoned over, so a confusing report can be diagnosed against real evidence instead of a
+  separately-captured DevTools screenshot.
+
+## [0.9.0] - 2026-08-26
+
+### Fixed
+
+- **Heal-log visibility**: a heal with no reusable selector (a one-shot `ref` resolution, or a
+  vision-tagged point) was silently dropped from `heals.jsonl` entirely, even though it genuinely
+  fixed that run. Now logged for audit — with a clear `reviewNote` — whenever it has a suggestion
+  *or* a review note, without letting an audit-only entry shadow an older, real cached fix for the
+  same location.
+- **Vision support for `claude-subscription`/`copilot-subscription`**: both providers had
+  `supportsVision` hardcoded to `false` regardless of model. Both SDKs genuinely support image
+  input (Claude Agent SDK via an image content block; Copilot SDK via a `blob` attachment) —
+  implemented for real and verified live with actual screenshots, not just doctor's yes/no label.
+- **Argument forwarding in healed replays**: `replayAction()` only ever forwarded the first call
+  argument. A trailing options object (`click({ modifiers: [...] })`, `fill(value, { timeout })`,
+  `dispatchEvent`'s 3rd argument) was silently dropped on a healed replay — changing the action's
+  real behavior while still reporting a clean `HEALED`.
+- **`ref`-strategy replays now act through the derived durable locator, not the raw ref**:
+  `aria-ref=` locators never resolve for `dispatchEvent` at all (a Playwright-level limitation,
+  confirmed directly via `DEBUG=pw:api`), even though the identical element resolves instantly via
+  a `normalize()`-derived locator for that same action. Fixed by deriving the durable locator
+  *before* replaying and acting through it, falling back to the raw ref only when nothing durable
+  could be found. A related accuracy bug is fixed alongside it: the report/heal-log could
+  previously claim a derived selector "worked" even when its own replay had actually failed and a
+  fallback silently took over — now only the locator that genuinely performed the action is
+  reported or cached.
+- **`copilot-subscription` could hang a non-Playwright test runner indefinitely** — its shared
+  client keeps a connection open across calls for performance, which Playwright's own test runner
+  tolerates by force-exiting regardless, but a runner like Cucumber does not, so the process never
+  returned even after every test had already passed. Found live running a real Cucumber suite in
+  CI. `closeCopilotSubscriptionClient()` is now exported from the package's own entry point so any
+  non-Playwright consumer can call it from their own teardown hook (e.g. Cucumber's `AfterAll`).
+
+### Added
+
+- **`locator.getDurable(action?)`** — resolves any locator (most usefully one built from
+  `aria-ref=...`) to a durable, reusable equivalent (`getByRole`/`getByLabel`/a css selector/…),
+  using the same derivation logic self-healing already uses internally. Throws if nothing durable
+  could be derived, rather than silently handing back something untrusted.
+- **`apply-heals` now previews before writing**: every run — dry or real — shows a styled table of
+  exactly what it found (location, before, after, review status) instead of a plain scrolling log.
+  A real run also asks for confirmation before writing anything, but *only* at a genuine
+  interactive terminal — CI and any non-interactive/piped invocation proceed automatically exactly
+  as before, so no existing unattended CI workflow is affected. `--yes`/`-y` skips the prompt at a
+  real terminal too.
+- **`doctor`'s output is styled** with colors and tables (including a new end-of-run Summary
+  section) instead of a plain scrolling log.
+- **Exact locator code in console lines and reports**: a healed suggestion is now shown as the
+  real, copy-pasteable Playwright call (`getByRole("textbox", { name: "Username" })`) instead of
+  an abbreviated shorthand (`role:textbox:Username`) — the same code `apply-heals` would write to
+  source, so what you see is never a lossier stand-in for what was actually used.
+- A canonical Page Object Model usage example (`tests/pages/` +
+  `tests/example-orangehrm-add-employee.spec.ts`), verified live against a real OrangeHRM demo,
+  including a genuine self-heal via the `near`/widening strategy on a real unlabeled field.
+
+### Changed
+
+- README/usage.md's vision-fallback documentation now correctly lists `claude-subscription`/
+  `copilot-subscription` as vision-capable (with a suitable model), not just the API-key providers.
+
+## [0.8.0] - 2026-08-25
+
+### Added
+
+- `claude-subscription` and `copilot-subscription` heal providers — self-healing backed by a
+  personal Claude or GitHub Copilot subscription instead of a pay-per-token API key, working both
+  locally and unattended in CI (`CLAUDE_CODE_OAUTH_TOKEN` for Claude; the ambient `GITHUB_TOKEN` or
+  a personal-account PAT for Copilot on GitHub Actions).
+
+### Fixed
+
+- Missing CLI install step in setup docs for `claude-subscription`/`copilot-subscription` — the
+  standalone `claude`/`copilot` CLIs are genuinely required for the login step even though the SDKs
+  don't need them installed to function at runtime.
+
+### Documentation
+
+- The org-vs-personal-account Copilot licensing gotcha in CI (a repo owned by an organization
+  without its own Copilot enablement can't use a personal subscription via the ambient token).
+- Action Recovery (`HEALER_ACTION_RECOVERY_ENABLED`) hidden from docs and `doctor` output —
+  disabled by default already; this only reduced its visibility, no behavior change.
+
+## [0.7.0] - 2026-08-21
+
+### Added
+
+- `apply-heals` — turns a runtime heal into a permanent source-code fix, plus an opportunistic
+  cache (`heals.jsonl`) so a previously-confirmed selector is tried before a fresh AI call, and
+  history archival so a run's report/log isn't silently overwritten by the next one.
+- Position/relationship-based locator strategies (`near`, `scoped`, `containing`) for elements with
+  no accessible identity of their own.
+- Self-healing rebuilt around `ariaSnapshot({ mode: 'ai' })` + `aria-ref=` resolution and
+  `Locator.normalize()`, replacing pixel-distance guessing for both the text path and the vision
+  fallback's durability upgrade.
+- A real unit test suite (32 tests at the time, zero new dependencies).
+
+### Fixed
+
+- `doctor`'s `actionTimeout` check being fooled by a commented-out config value.
+- `apply-heals --logs-dir` silently losing raw heal-log archival.
+- `apply-heals` only replacing the first call when re-healing an already-`near`-fixed line.
+- `apply-heals` `ENOENT` on a fresh CI checkout with no `.tamash-playwright/` directory yet — the
+  sharded "apply-heals" CI job checks out fresh and has never run tests itself, so the directory
+  genuinely doesn't exist there the way it always does in every local recipe.
+- File path corruption (and a `require()` crash in the generated verification script) for ESM
+  (`"type": "module"`) consumer projects — `Error.stack` renders as a `file://` URL there, which
+  broke path resolution and a plain `.js` verification script alike.
+- The AI being misled by the broken selector still present in its own prompt context; a failed
+  label guess now auto-upgrades to a structural `near` match instead of giving up.
+
+### Verified
+
+- All four API-key providers (Ollama, OpenAI, Anthropic, Gemini) confirmed working with real API
+  calls, not just documented.
+
+## [0.6.0] - 2026-08-17
+
+### Added
+
+- iframe and popup healing, vision fallback (screenshot-based recovery when text alone isn't
+  enough), AI-driven action recovery (scroll/force/wait/dispatch), and source-location reporting.
+- `doctor`'s `actionTimeout` configuration check.
+
+### Initial release
+
+- Self-healing Playwright bindings: broken locators are recovered at runtime via an AI provider,
+  with `.describe()` for human-readable context.