tamash-playwright 0.10.0-beta.5 → 0.10.0

package/CHANGELOG.md

@@ -3,9 +3,9 @@
 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.10.0] - 2026-08-26
+## [0.10.0] - 2026-08-27
 
-### Fixed (continued)
+### 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
@@ -18,6 +18,21 @@ All notable changes to this project are documented here. Format loosely follows
   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
 
@@ -32,27 +47,17 @@ All notable changes to this project are documented here. Format loosely follows
   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.
-
-### Fixed
-
-- **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 all of today's
-  `nearbyRef`/`adjacent`-strategy widening logic) 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).
-- **`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 (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.
-
-### Added
-
+- **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
@@ -66,17 +71,6 @@ All notable changes to this project are documented here. Format loosely follows
 - **`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.
-- **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.
 
 ## [0.9.0] - 2026-08-26
 

package/README.md

@@ -267,7 +267,7 @@ Beyond a single broken `click`/`fill`/`getByRole` on the main page, all of this
 
 - **Popups and extra tabs.** A page opened via `context.newPage()`, `window.open`, or a `target="_blank"` link is just as healing-aware as your main `page` — no manual wrapping needed.
 - **Elements inside `<iframe>`s.** `page.frameLocator('#my-iframe')` and anything chained off it heals the same way, scoped correctly to the iframe's own document.
-- **Most of the Playwright API surface**, not just clicks and fills — `check`, `selectOption`, `dragTo`, `dispatchEvent`, read methods like `textContent`/`getAttribute`/`isChecked`, `screenshot`, and more. Methods that can't be safely healed by guessing a replacement element (`dragTo`, `drop`) are still reported honestly on failure, they're just never silently retried with a different element.
+- **Most of the Playwright API surface**, not just clicks and fills — `check`, `selectOption`, `dragTo`, `dispatchEvent`, read methods like `textContent`/`getAttribute`/`isChecked`, `screenshot`, and more. A few are deliberately excluded, but still reported honestly on failure rather than silently retried: `dragTo`/`drop` can't be safely healed by guessing a replacement element for just one side of a two-sided drag, and `waitFor` is a state check rather than an action — a timeout on it can mean a genuinely broken selector, or that the element correctly never reached the expected state (verifying something does *not* appear, say), which can't be told apart from the error alone. (`expect(locator).toBeVisible()` and similar assertions are excluded for the same reason, but never even reach this mechanism — they're Playwright's own matcher, not a method this wraps.)
 
 ## When there's no name to match: finding elements by structure
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamash-playwright",
-  "version": "0.10.0-beta.5",
+  "version": "0.10.0",
   "description": "Plug and Play Self-healing for Playwright and automatically recovers broken selectors using an AI model (Ollama, OpenAI, Anthropic, Gemini, or a Claude/GitHub Copilot subscription).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/usage.md

@@ -161,7 +161,7 @@ Everything below applies identically in both places — same package, same behav
 
 - **Popups and extra tabs.** A page opened via `context.newPage()`, `window.open`, or a `target="_blank"` link is just as healing-aware as your main `page`.
 - **Elements inside `<iframe>`s.** `page.frameLocator('#my-iframe')` and anything chained off it heals the same way, correctly scoped to the iframe's own document.
-- **Most of the Playwright API surface**, not just clicks and fills — `check`, `selectOption`, `dragTo`, `dispatchEvent`, read methods like `textContent`/`getAttribute`/`isChecked`, `screenshot`, and more. `dragTo` and `drop` are reported honestly on failure rather than guessed at.
+- **Most of the Playwright API surface**, not just clicks and fills — `check`, `selectOption`, `dragTo`, `dispatchEvent`, read methods like `textContent`/`getAttribute`/`isChecked`, `screenshot`, and more. `dragTo`, `drop`, and `waitFor` are reported honestly on failure rather than guessed at — the first two because a two-sided drag can't be safely fixed by guessing one side, `waitFor` because a timeout on it can be a correct test outcome (e.g. verifying an absence), not a broken selector. `expect(locator).toBeVisible()` and similar assertions are excluded the same way, but never reach this mechanism at all — they're Playwright's own matcher, not a method this wraps.
 
 ## When there's no name to match: finding elements by structure