playwright-locator-healer 0.1.3

package/dist/healing/prompts/heal-v21.js

@@ -0,0 +1,204 @@
+// healing/prompts/heal-v21.ts
+//
+// Static system prompt for the heal v2.1 LLM call. Byte-identical across all
+// calls and intentionally ≥1024 tokens so OpenAI's prompt cache (75% discount
+// on cached input tokens for gpt-4.1-mini) reliably hits.
+//
+// Keep this in its own module so the long string does not bloat llm-client.ts
+// and so prompt iteration can ship without re-reading the OpenAI wrapper.
+/**
+ * Senior-SDET persona + strict tier rubric used for every
+ * `requestHealedLocator` call. Mutating this string invalidates OpenAI's
+ * prompt-cache hash and momentarily increases per-call cost until the new
+ * prefix re-warms.
+ */
+export const HEAL_V21_SYSTEM_PROMPT = `# WHO YOU ARE
+You are a senior SDET architect with 8+ years writing Playwright and
+Selenium tests at production scale. You have been burned by every UI
+framework footgun — React reconciliation ids, Emotion / styled-
+components hashed class names, MUI \`css-1k4n5\`, Vue \`data-v-{hash}\`,
+Angular \`_ngcontent-c12\`, Ember UUIDs, React 18 \`:r0:\` useId,
+Salesforce LWC scoped classes. You instinctively distrust anything that
+looks generated and instinctively trust ARIA roles, accessible names,
+and test ids. You write the locator a careful human would write by
+hand — not the locator a tool would auto-export.
+
+# WHAT YOU DO (scope of work)
+ONE thing only: take the developer's picked element + their intent
+description, and produce exactly 3 ranked Playwright locators in JSON.
+That is all. You do not refactor tests. You do not suggest test design
+changes. You do not explain your reasoning at length. You do not output
+anything that is not strict JSON matching the required schema.
+
+# WHAT IS IN SCOPE
+- Generating ARIA-role, test-id, label, text, attribute-CSS, xpath, or
+  Playwright filter-chain locators that uniquely match the picked
+  element on the current page.
+- Drilling DOWN when the picked element is a container — your locator
+  must resolve to the inner element matching the user's intent verb.
+- Drilling UP when the picked element is a non-interactive descendant
+  (a \`<span>\` / \`<svg>\` / \`<i>\` inside a \`<button>\` / \`<a>\`) AND the
+  developer's intent describes the interactive ancestor — target the
+  clickable ancestor.
+
+# WHAT IS OUT OF SCOPE (do not do these)
+- Inventing role names, attribute values, or text that does not appear
+  in the picked element or candidate list. NO HALLUCINATION.
+- Proposing any locator with auto-generated tokens. If a token has the
+  shape \`<prefix>-<digits/hex>\` with 5+ alphanumeric chars after a
+  hyphen or underscore, it is auto-generated. Reject it.
+- Producing positional xpath (\`//div[3]/section[2]/button[1]\`) or deep
+  descendant CSS chains (\`body > div > main > div > section > button\`)
+  before round 3.
+- Producing \`page.evaluate(...)\` or JavaScript expressions unless round
+  is exactly 4.
+- Returning more or fewer than 3 suggestions.
+- Returning prose, commentary, markdown fences, or anything outside the
+  JSON object.
+
+# HOW YOU THINK (silent 3-step internal monologue — do NOT emit)
+
+  Step 1. UNDERSTAND
+    Restate the developer's intent in one sentence. What element are
+    they acting on? What is the verb (click, fill, expect)? If the
+    intent words and the picked element disagree (intent says "submit"
+    but pick is a Cancel button), THE PICK WINS. Note the disagreement
+    in your rationale.
+
+  Step 2. ANCHOR
+    Walk the picked element's properties in this priority order. Stop
+    at the FIRST strong stable anchor:
+      a. dataTestId present and not auto-generated → use it.
+      b. accessibleName non-empty AND (explicit role OR implicit role
+         from the table below) → use role + name.
+      c. associated <label> text for form fields → use label.
+      d. unique visible text (siblingsSameTag === 1 AND no other
+         candidate has the same accessibleName) → use text.
+      e. stable id (does not match auto-gen pattern) → use #id.
+      f. stable attribute (name, type, data-action / data-event /
+         data-name — NOT data-v / data-reactid / data-emotion).
+    If NONE hold, you are in fragile territory: announce in rationale
+    and fall back to tier 4–6.
+
+  Step 3. SCOPE
+    Ask: does my chosen anchor uniquely identify THE picked element on
+    the current page? Check siblingsSameTag and candidate count.
+      → If YES, emit the bare semantic locator (tier 1 or 2).
+      → If NO, wrap it in a filter-chain (tier 3). Pick a parent
+        landmark visible in parentRole (form, navigation, dialog,
+        region, main, listitem, table). Add \`filter({hasText: 'X'})\`
+        using a phrase that comes from the intent or visible sibling
+        text — never invented.
+
+# WHAT YOU KNOW (skill)
+
+## Implicit ARIA roles (use when no explicit role attribute)
+  <button>              → button
+  <a href>              → link
+  <input type=text>     → textbox
+  <input type=submit>   → button
+  <input type=checkbox> → checkbox
+  <input type=radio>    → radio
+  <select>              → combobox
+  <textarea>            → textbox
+  <h1>..<h6>            → heading
+  <nav>                 → navigation
+  <main>                → main
+  <header>              → banner
+  <footer>              → contentinfo
+  <aside>               → complementary
+  <ul>/<ol>             → list
+  <li>                  → listitem
+  <table>               → table
+  <tr>                  → row
+  <td>                  → cell
+  <form>                → form
+
+## Accessible name computation (use this order)
+  1. aria-labelledby (referenced element's text)
+  2. aria-label attribute
+  3. <label for=id> for inputs (or wrapping <label>)
+  4. element's visible textContent
+  5. placeholder (inputs only, weak fallback)
+  6. title attribute (weakest)
+
+## Edge-case recognition (apply these rules without being asked)
+  - Pick is <span>/<svg>/<i> inside a <button>/<a> →
+    target the interactive ancestor. Use parentRole + nearest
+    accessibleName.
+  - Pick is a container <section>/<div>/<form> and intent verb is
+    click/fill/select/expect-visible → drill down to the inner
+    interactive element matching the intent noun.
+  - accessibleName empty (icon-only button) → look for aria-label or
+    title. If neither, the element is a11y-broken; fall to data-*
+    or stable id.
+  - Multiple elements share the same accessibleName (5 "Edit" buttons
+    in a table) → tier 3 filter-chain by row text from neighborText.
+  - Form input has no <label for=> but has placeholder → use
+    role=textbox + accessibleName from associatedLabel, OR scope to
+    enclosing form.
+  - Generic visible text ("Submit", "Save", "Close") appears in many
+    components on the page → NEVER bare text=; always scope via
+    filter-chain.
+
+# OUTPUT CONTRACT
+Return strict JSON: { "suggestions": [3 entries] }. Each entry:
+  - selectorType: "role" | "text" | "label" | "testid" | "css" |
+                  "xpath" | "filter-chain" | "js"
+  - selector: the bare selector value (forms below)
+  - tier: integer 1-7 matching the tier table
+  - rationale: ONE sentence stating the tier and what disambiguates.
+
+## Selector forms by type
+  role         → \`button[name="Submit"]\` (NO \`role=\` prefix in the value)
+  text         → \`Sign in\` (visible text only)
+  label        → \`Email address\` (label text only)
+  testid       → \`submit-btn\` (the testid value only)
+  css          → \`#stable-id\`, \`[name="email"]\`, \`[data-action="save"]\`
+  xpath        → \`//button[@data-x="y"]\` (attribute-anchored only)
+  filter-chain → JSON: {"root":"role=...","filters":[{"hasText":"..."}],"target":"role=..."}
+  js           → JS expression returning ONE Element (round 4 only, never cached)
+
+## Tier rubric (the tier you emit is a CONSEQUENCE of ANCHOR + SCOPE)
+  1 = clean semantic (role+name / label / text) — anchor unique
+  2 = testid — dataTestId present and clean
+  3 = filter-chain — semantic anchor exists but multi-matches → scope
+  4 = attribute CSS / stable id
+  5 = class chain CSS (brittle — last CSS resort)
+  6 = attr-anchored xpath
+  7 = js evaluate (round 4 escape hatch, never cached)
+
+## Round semantics
+  Round 1: best single-shot. Allowed tiers: 1-4.
+  Round 2: previous attempts failed — read previousAttempts, avoid
+           repeats. Allowed tiers: 1-5. Strongly prefer chained scope.
+  Round 3: allow tier 6 (attribute-anchored xpath).
+  Round 4: allow tier 7 (js evaluate).
+
+## Quoting (multi-word names break without quotes)
+  CORRECT: role=region[name="Login form"]
+  CORRECT: button[name="Sign in"]
+  WRONG:   role=region[name=Login form]    ← will not parse
+
+# WORKED EXAMPLE (shows ANCHOR + SCOPE producing tier 1)
+Picked: <button class="x_a82">Sign in</button> inside <form aria-label="Login form">
+siblingsSameTag: 1, accessibleName: "Sign in", parentRole: "form"
+Intent: "sign-in button in the login form"
+Round: 1
+Previous: []
+Silent reasoning: UNDERSTAND → click the sign-in button.
+                  ANCHOR → no testid, but accessibleName "Sign in" +
+                           implicit role button.
+                  SCOPE → siblingsSameTag=1, only one Sign in on page →
+                          tier 1.
+Output:
+{"suggestions":[
+  {"selectorType":"role","selector":"button[name=\\"Sign in\\"]","rationale":"Tier 1: unique role+accessibleName.","tier":1},
+  {"selectorType":"filter-chain","selector":"{\\"root\\":\\"role=region[name=\\\\\\"Login form\\\\\\"]\\",\\"filters\\":[],\\"target\\":\\"role=button[name=\\\\\\"Sign in\\\\\\"]\\"}","rationale":"Tier 3: scoped via login-form landmark for extra robustness.","tier":3},
+  {"selectorType":"text","selector":"Sign in","rationale":"Tier 1 text variant.","tier":1}
+]}
+
+# REMEMBER
+Think silently. Output strict JSON only. No markdown fences. No
+commentary outside JSON. No invented values.`;
+//# sourceMappingURL=heal-v21.js.map

package/dist/healing/prompts/heal-v21.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heal-v21.js","sourceRoot":"","sources":["../../../healing/prompts/heal-v21.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,0DAA0D;AAC1D,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAE1E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CA4LO,CAAC"}

package/dist/healing/retry-policy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * healing/retry-policy.ts
+ *
+ * Exponential-backoff retry schedule for OpenAI calls. Centralised so unit
+ * tests can spy on the schedule and so future reliability work has one place
+ * to tune retry behaviour.
+ *
+ * - `BACKOFF_DELAYS_MS`: base delays (ms) for attempts 0, 1, 2. Overridable
+ *   via the `HEALING_BACKOFF_MS` env var (`"10,20,40"`) for fast tests.
+ * - `backoffWithJitter(attempt)`: returns the base delay for the given
+ *   attempt index plus ±20% random jitter, clamped at ≥0.
+ * - `sleep(ms)`: thin promise wrapper around `setTimeout`.
+ */
+/**
+ * Base delays in milliseconds for each retry attempt (index 0, 1, 2 ...).
+ * Reads `HEALING_BACKOFF_MS` env at module load — comma-separated integers,
+ * e.g. `HEALING_BACKOFF_MS=10,20,40` for unit tests that exercise the retry
+ * path without slowing the suite.
+ */
+export declare const BACKOFF_DELAYS_MS: number[];
+/**
+ * Exponential backoff with ±20% jitter. Attempt indices ≥ schedule length
+ * clamp to the last entry (i.e. attempts past attempt 2 use the 4 s delay).
+ *
+ * @param attempt - Zero-based attempt index (0 = first retry).
+ * @returns Delay in milliseconds (≥0, rounded).
+ */
+export declare function backoffWithJitter(attempt: number): number;
+/**
+ * Promise-based `setTimeout`. Resolves after the given number of
+ * milliseconds elapse.
+ *
+ * @param ms - Wait duration in milliseconds.
+ * @returns Promise that resolves with `undefined`.
+ */
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=retry-policy.d.ts.map

package/dist/healing/retry-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.d.ts","sourceRoot":"","sources":["../../healing/retry-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAEhB,CAAC;AAEvB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/healing/retry-policy.js

@@ -0,0 +1,46 @@
+/**
+ * healing/retry-policy.ts
+ *
+ * Exponential-backoff retry schedule for OpenAI calls. Centralised so unit
+ * tests can spy on the schedule and so future reliability work has one place
+ * to tune retry behaviour.
+ *
+ * - `BACKOFF_DELAYS_MS`: base delays (ms) for attempts 0, 1, 2. Overridable
+ *   via the `HEALING_BACKOFF_MS` env var (`"10,20,40"`) for fast tests.
+ * - `backoffWithJitter(attempt)`: returns the base delay for the given
+ *   attempt index plus ±20% random jitter, clamped at ≥0.
+ * - `sleep(ms)`: thin promise wrapper around `setTimeout`.
+ */
+/**
+ * Base delays in milliseconds for each retry attempt (index 0, 1, 2 ...).
+ * Reads `HEALING_BACKOFF_MS` env at module load — comma-separated integers,
+ * e.g. `HEALING_BACKOFF_MS=10,20,40` for unit tests that exercise the retry
+ * path without slowing the suite.
+ */
+export const BACKOFF_DELAYS_MS = process.env.HEALING_BACKOFF_MS
+    ? process.env.HEALING_BACKOFF_MS.split(',').map(Number)
+    : [1000, 2000, 4000];
+/**
+ * Exponential backoff with ±20% jitter. Attempt indices ≥ schedule length
+ * clamp to the last entry (i.e. attempts past attempt 2 use the 4 s delay).
+ *
+ * @param attempt - Zero-based attempt index (0 = first retry).
+ * @returns Delay in milliseconds (≥0, rounded).
+ */
+export function backoffWithJitter(attempt) {
+    const idx = Math.min(Math.max(0, attempt), BACKOFF_DELAYS_MS.length - 1);
+    const base = BACKOFF_DELAYS_MS[idx] ?? 1000;
+    const jitter = (Math.random() * 0.4 - 0.2) * base; // ±20%
+    return Math.max(0, Math.round(base + jitter));
+}
+/**
+ * Promise-based `setTimeout`. Resolves after the given number of
+ * milliseconds elapse.
+ *
+ * @param ms - Wait duration in milliseconds.
+ * @returns Promise that resolves with `undefined`.
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retry-policy.js.map

package/dist/healing/retry-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.js","sourceRoot":"","sources":["../../healing/retry-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAa,OAAO,CAAC,GAAG,CAAC,kBAAkB;IACvE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;IACvD,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAEvB;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzE,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IAC5C,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO;IAC1D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/healing/session-cost.d.ts

@@ -0,0 +1,44 @@
+/** Active OpenAI model id resolved from `HEAL_MODEL`. */
+export declare const ACTIVE_MODEL_ID: string;
+/** USD per million fresh input tokens for the active model. */
+export declare const PRICE_INPUT_FRESH_PER_M: number;
+/** USD per million cached input tokens for the active model (prompt cache discount). */
+export declare const PRICE_INPUT_CACHED_PER_M: number;
+/** USD per million output tokens for the active model. */
+export declare const PRICE_OUTPUT_PER_M: number;
+/**
+ * Accumulate token usage from a completed OpenAI call into the session
+ * totals, returning the USD cost of *this* call.
+ *
+ * @param usage - The `completion.usage` object from the OpenAI SDK. The
+ *   nested `prompt_tokens_details.cached_tokens` is used to bill cached
+ *   tokens at the discounted rate.
+ * @returns USD cost contributed by this call (already added to session total).
+ */
+export declare function accumulateSessionCost(usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    } | null;
+}): number;
+/**
+ * Snapshot of accumulated session usage. Numbers are cumulative across
+ * every successful OpenAI call since process start (or last `resetSessionCost`).
+ *
+ * @returns Token counts, USD cost, and total call count.
+ */
+export declare function getSessionCost(): {
+    prompt_tokens: number;
+    cached_tokens: number;
+    completion_tokens: number;
+    cost_usd: number;
+    call_count: number;
+};
+/**
+ * Reset every session counter to zero. Test-only — production code should
+ * never call this since cost ledgers must accumulate for the lifetime of
+ * the process.
+ */
+export declare function resetSessionCost(): void;
+//# sourceMappingURL=session-cost.d.ts.map

package/dist/healing/session-cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-cost.d.ts","sourceRoot":"","sources":["../../healing/session-cost.ts"],"names":[],"mappings":"AAiBA,yDAAyD;AACzD,eAAO,MAAM,eAAe,QAAkB,CAAC;AAE/C,+DAA+D;AAC/D,eAAO,MAAM,uBAAuB,QAAqB,CAAC;AAE1D,wFAAwF;AACxF,eAAO,MAAM,wBAAwB,QAAsB,CAAC;AAE5D,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAQtD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC3D,GAAG,MAAM,CAaT;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,CAQA;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAMvC"}

package/dist/healing/session-cost.js

@@ -0,0 +1,95 @@
+/**
+ * healing/session-cost.ts
+ *
+ * Process-wide accumulator for OpenAI token usage and USD cost. Pricing is
+ * resolved once at module load from the active model (see `models.ts`); the
+ * `HEAL_MODEL` env can swap models before import.
+ *
+ * A `process.on('exit')` hook prints a session summary to stderr when at
+ * least one call ran — handy when a Playwright suite finishes and the
+ * developer wants a one-line bill.
+ *
+ * Reset via `resetSessionCost()` between test runs.
+ */
+import { resolveModel } from './models.js';
+const _activeModel = resolveModel();
+/** Active OpenAI model id resolved from `HEAL_MODEL`. */
+export const ACTIVE_MODEL_ID = _activeModel.id;
+/** USD per million fresh input tokens for the active model. */
+export const PRICE_INPUT_FRESH_PER_M = _activeModel.input;
+/** USD per million cached input tokens for the active model (prompt cache discount). */
+export const PRICE_INPUT_CACHED_PER_M = _activeModel.cached;
+/** USD per million output tokens for the active model. */
+export const PRICE_OUTPUT_PER_M = _activeModel.output;
+let _sessionPromptTokens = 0;
+let _sessionCachedTokens = 0;
+let _sessionCompletionTokens = 0;
+let _sessionCostUsd = 0;
+let _sessionCallCount = 0;
+/**
+ * Accumulate token usage from a completed OpenAI call into the session
+ * totals, returning the USD cost of *this* call.
+ *
+ * @param usage - The `completion.usage` object from the OpenAI SDK. The
+ *   nested `prompt_tokens_details.cached_tokens` is used to bill cached
+ *   tokens at the discounted rate.
+ * @returns USD cost contributed by this call (already added to session total).
+ */
+export function accumulateSessionCost(usage) {
+    const cached = usage.prompt_tokens_details?.cached_tokens ?? 0;
+    const fresh = Math.max(0, usage.prompt_tokens - cached);
+    const callCost = (fresh / 1e6) * PRICE_INPUT_FRESH_PER_M +
+        (cached / 1e6) * PRICE_INPUT_CACHED_PER_M +
+        (usage.completion_tokens / 1e6) * PRICE_OUTPUT_PER_M;
+    _sessionPromptTokens += usage.prompt_tokens;
+    _sessionCachedTokens += cached;
+    _sessionCompletionTokens += usage.completion_tokens;
+    _sessionCostUsd += callCost;
+    _sessionCallCount++;
+    return callCost;
+}
+/**
+ * Snapshot of accumulated session usage. Numbers are cumulative across
+ * every successful OpenAI call since process start (or last `resetSessionCost`).
+ *
+ * @returns Token counts, USD cost, and total call count.
+ */
+export function getSessionCost() {
+    return {
+        prompt_tokens: _sessionPromptTokens,
+        cached_tokens: _sessionCachedTokens,
+        completion_tokens: _sessionCompletionTokens,
+        cost_usd: _sessionCostUsd,
+        call_count: _sessionCallCount,
+    };
+}
+/**
+ * Reset every session counter to zero. Test-only — production code should
+ * never call this since cost ledgers must accumulate for the lifetime of
+ * the process.
+ */
+export function resetSessionCost() {
+    _sessionPromptTokens = 0;
+    _sessionCachedTokens = 0;
+    _sessionCompletionTokens = 0;
+    _sessionCostUsd = 0;
+    _sessionCallCount = 0;
+}
+process.on('exit', () => {
+    if (_sessionCostUsd === 0)
+        return;
+    const cachedPct = _sessionPromptTokens > 0
+        ? ((_sessionCachedTokens / _sessionPromptTokens) * 100).toFixed(0)
+        : '0';
+    const wouldBeCost = (_sessionPromptTokens / 1e6) * PRICE_INPUT_FRESH_PER_M +
+        (_sessionCompletionTokens / 1e6) * PRICE_OUTPUT_PER_M;
+    process.stderr.write(`[HEAL] ─────────────────────────────────────────────────────\n` +
+        `[HEAL] SESSION LLM COST SUMMARY\n` +
+        `[HEAL]   calls:  ${_sessionCallCount}\n` +
+        `[HEAL]   tokens: ${_sessionPromptTokens.toLocaleString()}in (${_sessionCachedTokens.toLocaleString()} cached, ${cachedPct}%) + ${_sessionCompletionTokens.toLocaleString()}out\n` +
+        `[HEAL]   cost:   $${_sessionCostUsd.toFixed(6)} USD\n` +
+        `[HEAL]   would-be cost without cache: $${wouldBeCost.toFixed(6)} USD\n` +
+        `[HEAL]   savings from prompt cache:   $${(wouldBeCost - _sessionCostUsd).toFixed(6)} USD\n` +
+        `[HEAL] ─────────────────────────────────────────────────────\n`);
+});
+//# sourceMappingURL=session-cost.js.map

package/dist/healing/session-cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-cost.js","sourceRoot":"","sources":["../../healing/session-cost.ts"],"names":[],"mappings":"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"}

package/dist/healing/test-fixture.d.ts

@@ -0,0 +1,9 @@
+import { expect } from '@playwright/test';
+import { type HealActionInput } from './heal/orchestrator.js';
+import type { HealEntryV2 } from './types.js';
+type HealFn = (args: Omit<HealActionInput, 'page' | 'testFile'>) => Promise<HealEntryV2>;
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    heal: HealFn;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect };
+//# sourceMappingURL=test-fixture.d.ts.map

package/dist/healing/test-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-fixture.d.ts","sourceRoot":"","sources":["../../healing/test-fixture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,KAAK,MAAM,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,UAAU,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAEzF,eAAO,MAAM,IAAI;UAAuB,MAAM;wGA+B5C,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/healing/test-fixture.js

@@ -0,0 +1,37 @@
+import { test as base, expect } from '@playwright/test';
+import { join, basename } from 'node:path';
+import { healAction } from './heal/orchestrator.js';
+import { cacheV2Get } from './cache.js';
+import { buildLocator } from './validator.js';
+export const test = base.extend({
+    heal: async ({ page }, use, testInfo) => {
+        const testFile = basename(testInfo.file);
+        // Explicit opt-in only. Generic `CI` env is too easy to set by accident
+        // (VS Code, IDE tasks, shell rc). Heal short-circuits ONLY when the
+        // caller sets HEAL_HEADLESS=1.
+        const isHeadlessMode = process.env.HEAL_HEADLESS === '1';
+        const fn = async (args) => {
+            if (isHeadlessMode) {
+                // HEAL_HEADLESS=1: cache-hit-or-fail. No overlay, no LLM.
+                const cacheDir = args.cacheDir ?? join(process.cwd(), '.healed-locators');
+                const cached = await cacheV2Get(cacheDir, testFile, args.originalSelector, args.action);
+                if (cached) {
+                    const loc = buildLocator(page, {
+                        selectorType: cached.selectorType,
+                        selector: cached.healedSelector,
+                        rationale: '',
+                        tier: cached.tier ?? 6,
+                    });
+                    if ((await loc.count().catch(() => 0)) === 1)
+                        return cached;
+                }
+                throw new Error(`[heal] HEAL_HEADLESS=1: no cached entry for "${args.originalSelector}" (action=${args.action}). ` +
+                    `Cannot prompt user. Unset HEAL_HEADLESS to interact, or pre-seed the cache.`);
+            }
+            return healAction({ page, testFile, ...args });
+        };
+        await use(fn);
+    },
+});
+export { expect };
+//# sourceMappingURL=test-fixture.js.map

package/dist/healing/test-fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-fixture.js","sourceRoot":"","sources":["../../healing/test-fixture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAwB,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAK9C,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAmB;IAChD,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE;QACtC,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzC,wEAAwE;QACxE,oEAAoE;QACpE,+BAA+B;QAC/B,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,GAAG,CAAC;QAEzD,MAAM,EAAE,GAAW,KAAK,EAAE,IAAI,EAAE,EAAE;YAChC,IAAI,cAAc,EAAE,CAAC;gBACnB,0DAA0D;gBAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,kBAAkB,CAAC,CAAC;gBAC1E,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;gBACxF,IAAI,MAAM,EAAE,CAAC;oBACX,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE;wBAC7B,YAAY,EAAE,MAAM,CAAC,YAAY;wBACjC,QAAQ,EAAE,MAAM,CAAC,cAAc;wBAC/B,SAAS,EAAE,EAAE;wBACb,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC;qBACvB,CAAC,CAAC;oBACH,IAAI,CAAC,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;wBAAE,OAAO,MAAM,CAAC;gBAC9D,CAAC;gBACD,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,CAAC,gBAAgB,aAAa,IAAI,CAAC,MAAM,KAAK;oBAClG,6EAA6E,CAC9E,CAAC;YACJ,CAAC;YACD,OAAO,UAAU,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC,CAAC;QACF,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,CAAC;CACF,CAAC,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC"}