playwright-locator-healer 0.1.3

package/dist/healing/heal/orchestrator.js

@@ -0,0 +1,644 @@
+import { join } from 'node:path';
+import { parseSourceTrace, readSnippet } from './source-trace.js';
+import { appendReport, appendAuditV2 } from './report.js';
+import { cacheV2Get, cacheV2Set } from '../cache.js';
+import { buildLocator, validateProposedLocator, verifyActionable, relaxRoleNameMatch, captureFingerprint, fingerprintMatches } from '../validator.js';
+import { injectOverlay } from '../overlay/inject.js';
+import { HealCancelledError, HealExhaustedError, HealLLMError, HealingError } from '../errors.js';
+import { requestHealedLocator } from '../llm-client.js';
+import { tryPreflight } from './preflight.js';
+import { extractScopedCandidates } from '../dom-extractor.js';
+import { isBudgetExceeded, getSessionCost, getCallCount, getDailyTotals, MODEL_NAME } from '../cost-tracker.js';
+import { warn as logWarn } from '../logger.js';
+import { toPlaywrightCode } from './playwright-code.js';
+import { safeCount, validateJs, tierOfType, extractStructured, tryForegroundUpgrade, } from './orchestrator-helpers.js';
+/** Maximum number of progressive LLM rounds attempted before giving up. */
+const MAX_ROUNDS = 4;
+function statusFields(extra) {
+    const daily = getDailyTotals();
+    return {
+        sessionCostUsd: getSessionCost(),
+        llmCallCount: getCallCount(),
+        todayCostUsd: daily.cost,
+        todayCallCount: daily.calls,
+        modelName: MODEL_NAME,
+        statusLabel: extra?.statusLabel,
+        llmStartedAt: extra?.llmStartedAt,
+    };
+}
+/**
+ * Top-level heal entry point. Five-stage flow:
+ *   0. live re-check — maybe the page changed and the original works now
+ *   1. cache lookup — return a previously-healed selector if it still resolves
+ *   2. overlay + pick — developer clicks the right element
+ *   3. preflight — try cheap deterministic locators (testid, role+name, …)
+ *   4. progressive LLM rounds — 4 rounds with increasing tier permissions
+ *
+ * Returns the persisted `HealEntryV2` so the caller (auto-fixture or
+ * manual code) can build a Playwright `Locator` from the result and retry.
+ *
+ * @param input - See `HealActionInput`.
+ * @returns The healed entry (selector + selectorType + tier + trace).
+ * @throws HealCancelledError, HealExhaustedError, HealLLMError on the
+ *   respective failure modes; HealingError(circuit-open) when the LLM
+ *   circuit breaker is open.
+ */
+export async function healAction(input) {
+    const cacheDir = input.cacheDir ?? (process.env.HEAL_CACHE_DIR ?? join(process.cwd(), '.healed-locators'));
+    const { page, originalSelector, action, description, testFile, callerStack } = input;
+    // P2-2: prefer the caller-captured stack (taken synchronously at the
+    // proxy entry) over the local stack, which has already crossed multiple
+    // async boundaries and shows <anonymous> Proxy frames.
+    const trace = parseSourceTrace(callerStack ?? new Error().stack);
+    const ctx = { originalSelector, action, callSite: trace.callSite };
+    // Stage 0 — live re-check
+    if ((await safeCount(page, originalSelector)) === 1) {
+        return synthEntry(originalSelector, 'css', originalSelector, description ?? '', action, trace, 1);
+    }
+    // Stage 1 — cache
+    let cached = null;
+    try {
+        cached = await cacheV2Get(cacheDir, testFile, originalSelector, action);
+    }
+    catch (e) {
+        if (e instanceof HealingError && e.code === 'invalid-cache') {
+            process.stderr.write(`[HEAL] ${e.message} — treating as cache miss\n`);
+        }
+        else {
+            throw e;
+        }
+    }
+    if (cached) {
+        const loc = buildLocator(page, {
+            selectorType: cached.selectorType, selector: cached.healedSelector, rationale: '',
+            tier: cached.tier ?? 6,
+        });
+        // intentionally swallowed: count() throws on invalid selector → treat as 0 matches and fall through
+        if ((await loc.count().catch(() => 0)) === 1) {
+            // P0-1b: drift gate parity with auto-fixture. When the cached entry
+            // carries a fingerprint, recompute on the live resolved element. If
+            // tag/role/attrs/text have drifted past tolerance, treat the entry
+            // as stale and re-heal rather than trust a `count===1` collision
+            // (e.g. cache poisoned by manual edit pointing at `<body>`).
+            if (cached.fingerprint) {
+                // intentionally swallowed: fingerprint extraction failure → assume drift, re-heal
+                const live = await loc.elementHandle().then((h) => h ? captureFingerprint(h) : null).catch(() => null);
+                if (!live || !fingerprintMatches(cached.fingerprint, live)) {
+                    await appendAuditV2(cacheDir, { event: 'cache-stale', ...ctx });
+                    // fall through to overlay heal
+                }
+                else {
+                    await appendAuditV2(cacheDir, { event: 'cache-hit', ...ctx, healedSelector: cached.healedSelector, tier: cached.tier ?? 6 });
+                    if ((cached.tier ?? 4) >= 5) {
+                        const upgraded = await tryForegroundUpgrade();
+                        if (upgraded)
+                            return upgraded;
+                    }
+                    return cached;
+                }
+            }
+            else {
+                await appendAuditV2(cacheDir, { event: 'cache-hit', ...ctx, healedSelector: cached.healedSelector, tier: cached.tier ?? 6 });
+                if ((cached.tier ?? 4) >= 5) {
+                    const upgraded = await tryForegroundUpgrade();
+                    if (upgraded)
+                        return upgraded;
+                }
+                return cached;
+            }
+        }
+        else {
+            await appendAuditV2(cacheDir, { event: 'cache-stale', ...ctx });
+        }
+    }
+    // Stage 2 + 3 + 4 — overlay + pick + preflight + LLM rounds
+    return openOverlayAndHeal(input, trace, ctx, []);
+}
+async function openOverlayAndHeal(input, trace, ctx, seedAttempts) {
+    const { page, originalSelector, action, description, testFile } = input;
+    const cacheDir = input.cacheDir ?? (process.env.HEAL_CACHE_DIR ?? join(process.cwd(), '.healed-locators'));
+    const snippet = readSnippet(trace.callSite);
+    const overlay = await injectOverlay(page);
+    try {
+        await overlay.setState({
+            stage: 'pick', originalSelector, action, description,
+            callSite: trace.callSite, pomFrame: trace.pomFrame,
+            sourceSnippet: snippet, ...statusFields({ statusLabel: 'PICK' }),
+        });
+        await overlay.enablePickMode();
+        let pickedHandle = null;
+        let pickedXpath = '';
+        let pickedHtml = '';
+        let intentText = description ?? '';
+        let intentSubmitted = false;
+        let forceSkipPreflight = false;
+        // Loop until BOTH a pick happened AND user explicitly submitted intent.
+        // Auto-derived description pre-fills the textarea but never auto-fires.
+        while (!pickedHandle || !intentSubmitted) {
+            const msg = await overlay.waitForMessage();
+            if (msg.type === 'cancel') {
+                await appendAuditV2(cacheDir, { event: 'cancel', ...ctx });
+                throw new HealCancelledError('user cancelled heal', ctx);
+            }
+            if (msg.type === 'pick-error') {
+                await appendAuditV2(cacheDir, { event: 'pick-error', ...ctx, reason: msg.reason });
+                throw new HealingError(`[heal] ${msg.reason}: cannot reach element inside closed shadow DOM at ${msg.xpath}. ` +
+                    `Closed shadow roots are not supported.`, 'shadow-unsupported');
+            }
+            if (msg.type === 'pick') {
+                pickedXpath = msg.xpath;
+                pickedHtml = msg.html;
+                pickedHandle = await page.locator(`xpath=${pickedXpath}`).elementHandle();
+                await overlay.disablePickMode();
+                // Compute pick-preview info and show the PICK-PREVIEW stage.
+                const pickPreview = pickedHandle
+                    ? await computePickPreview(pickedHandle)
+                    : undefined;
+                await overlay.setState({
+                    stage: 'pick-preview', originalSelector, action, description,
+                    callSite: trace.callSite, pomFrame: trace.pomFrame,
+                    sourceSnippet: snippet, pickPreview,
+                    ...statusFields({ statusLabel: 'PICK · PREVIEW' }),
+                });
+                continue;
+            }
+            if (msg.type === 'pick-preview-repick') {
+                // Return to pick stage and re-enable pick mode.
+                pickedHandle = null;
+                pickedXpath = '';
+                pickedHtml = '';
+                await overlay.setState({
+                    stage: 'pick', originalSelector, action, description,
+                    callSite: trace.callSite, pomFrame: trace.pomFrame, sourceSnippet: snippet,
+                    ...statusFields({ statusLabel: 'PICK' }),
+                });
+                await overlay.enablePickMode();
+                continue;
+            }
+            if (msg.type === 'pick-preview-continue') {
+                // Advance to intent stage with the picked info preserved.
+                if (!pickedHandle)
+                    continue; // no pick yet — ignore stale message
+                await overlay.setState({
+                    stage: 'intent', originalSelector, action, description,
+                    callSite: trace.callSite, pomFrame: trace.pomFrame,
+                    pickedHtml, intentText, sourceSnippet: snippet,
+                    ...statusFields({ statusLabel: 'INTENT' }),
+                });
+                continue;
+            }
+            if (msg.type === 'force-llm') {
+                // Require a pick first — ignore otherwise.
+                if (!pickedHandle)
+                    continue;
+                forceSkipPreflight = true;
+                await appendAuditV2(cacheDir, { event: 'force-llm', ...ctx });
+                // Re-render intent stage so user types context, then presses propose.
+                await overlay.setState({
+                    stage: 'intent', originalSelector, action, description,
+                    callSite: trace.callSite, pomFrame: trace.pomFrame,
+                    pickedHtml, intentText, sourceSnippet: snippet,
+                    ...statusFields({ statusLabel: 'INTENT · FORCE LLM' }),
+                });
+                continue;
+            }
+            if (msg.type === 'intent') {
+                intentText = msg.text || description || '';
+                intentSubmitted = true;
+                continue;
+            }
+            if (msg.type === 'reject') {
+                pickedHandle = null;
+                pickedXpath = '';
+                pickedHtml = '';
+                forceSkipPreflight = false;
+                await overlay.setState({
+                    stage: 'pick', originalSelector, action, description,
+                    callSite: trace.callSite, pomFrame: trace.pomFrame, sourceSnippet: snippet,
+                    ...statusFields({ statusLabel: 'PICK' }),
+                });
+                await overlay.enablePickMode();
+                continue;
+            }
+        }
+        // Stage 3 — preflight (skipped if user pressed force-LLM)
+        const pre = !forceSkipPreflight
+            ? await (async () => {
+                await overlay.setState({
+                    stage: 'intent', originalSelector, action, description,
+                    callSite: trace.callSite, pomFrame: trace.pomFrame,
+                    pickedHtml, intentText, sourceSnippet: snippet, loading: true,
+                    loadingLabel: 'PREFLIGHT',
+                    ...statusFields({ statusLabel: 'PREFLIGHT' }),
+                });
+                return tryPreflight(page, pickedHandle);
+            })()
+            : null;
+        if (pre) {
+            // P0-4: preflight semantic guard. Preflight derives a selector from
+            // the picked element's own attrs — it cannot detect a wrong-element
+            // pick (operator picks the username input but intent says "login
+            // button"). Refuse to cache obvious mismatches between the picked
+            // element's tag/role and the action verb / intent keywords.
+            const preflightMismatch = await detectPreflightMismatch(pickedHandle, action, intentText);
+            if (preflightMismatch) {
+                await appendAuditV2(cacheDir, {
+                    event: 'preflight-rejected', ...ctx,
+                    healedSelector: pre.selector, reason: preflightMismatch,
+                });
+                // fall through to LLM round — operator may have picked wrong, give them another chance
+            }
+            else {
+                // P0-1a: capture fingerprint of the picked element so future cache
+                // hits can detect drift (DOM rolled forward, page rewritten, etc).
+                const fingerprint = await captureFingerprint(pickedHandle).catch(() => undefined);
+                const entry = synthEntry(originalSelector, pre.selectorType, pre.selector, intentText, action, trace, 1, fingerprint);
+                await cacheV2Set(cacheDir, testFile, entry);
+                await appendReport(cacheDir, entry);
+                await appendAuditV2(cacheDir, { event: 'preflight-hit', ...ctx, healedSelector: pre.selector, tier: 1 });
+                return entry;
+            }
+        }
+        // Stage 4 — progressive rounds
+        const attempts = [...seedAttempts];
+        for (let round = 1; round <= MAX_ROUNDS; round++) {
+            if (isBudgetExceeded()) {
+                await appendAuditV2(cacheDir, { event: 'budget-exceeded', ...ctx, round });
+                throw new HealExhaustedError('budget exceeded', { ...ctx, attempts: round });
+            }
+            const candidates = await extractScopedCandidates(page, pickedHandle, round);
+            const { ancestorsHtml, structured } = await pickedHandle.evaluate(extractStructured);
+            // Wire abort: any cancel-llm message from overlay aborts the in-flight call.
+            const controller = new AbortController();
+            let abortKind = null;
+            overlay.setAbortHandler((m) => {
+                if (m.type === 'cancel-llm') {
+                    abortKind = 'cancel-llm';
+                    controller.abort();
+                    return true;
+                }
+                if (m.type === 'cancel') {
+                    abortKind = 'cancel';
+                    controller.abort();
+                    return true;
+                }
+                return false;
+            });
+            overlay.setCancelInFlight(() => controller.abort());
+            const llmStartedAt = Date.now();
+            await overlay.setState({
+                stage: 'intent', originalSelector, action, description,
+                callSite: trace.callSite, pomFrame: trace.pomFrame,
+                pickedHtml, intentText, loading: true, loadingLabel: `LLM R${round}`,
+                sourceSnippet: snippet, round,
+                ...statusFields({ statusLabel: `LLM R${round}`, llmStartedAt }),
+            });
+            let suggestions;
+            try {
+                suggestions = await requestHealedLocator({
+                    picked: structured, ancestorsHtml, intent: intentText, action,
+                    originalSelector, pageUrl: page.url(),
+                    candidates, previousAttempts: attempts, round: round,
+                    signal: controller.signal,
+                });
+            }
+            catch (e) {
+                overlay.setCancelInFlight(null);
+                overlay.setAbortHandler(null);
+                const aborted = abortKind !== null || (e instanceof HealingError && e.code === 'aborted');
+                if (aborted) {
+                    await appendAuditV2(cacheDir, { event: 'llm-aborted', ...ctx, round });
+                    if (abortKind === 'cancel') {
+                        await appendAuditV2(cacheDir, { event: 'cancel', ...ctx });
+                        throw new HealCancelledError('user cancelled heal', ctx);
+                    }
+                    await overlay.setState({
+                        stage: 'intent', originalSelector, action, description,
+                        callSite: trace.callSite, pomFrame: trace.pomFrame,
+                        pickedHtml, intentText, sourceSnippet: snippet,
+                        ...statusFields({ statusLabel: 'INTENT (LLM cancelled · edit & retry)' }),
+                    });
+                    while (true) {
+                        const m = await overlay.waitForMessage();
+                        if (m.type === 'cancel') {
+                            await appendAuditV2(cacheDir, { event: 'cancel', ...ctx });
+                            throw new HealCancelledError('user cancelled heal', ctx);
+                        }
+                        if (m.type === 'intent') {
+                            intentText = m.text || intentText;
+                            break;
+                        }
+                    }
+                    round--;
+                    continue;
+                }
+                await appendAuditV2(cacheDir, { event: 'llm-error', ...ctx, error: String(e), round });
+                throw new HealLLMError('llm call failed', ctx, e);
+            }
+            overlay.setCancelInFlight(null);
+            overlay.setAbortHandler(null);
+            await appendAuditV2(cacheDir, {
+                event: 'llm-suggestions', ...ctx, round,
+                suggestions: suggestions.map(s => ({
+                    selectorType: s.selectorType, selector: s.selector, tier: s.tier ?? 6,
+                })),
+            });
+            const result = await tryValidateAndConfirm(page, overlay, suggestions, ctx, trace, cacheDir, testFile, intentText, action, attempts, round, pickedHtml, pickedHandle);
+            if (result.kind === 'accepted')
+                return result.entry;
+            if (result.kind === 'cancel')
+                throw new HealCancelledError('user cancelled at confirm', ctx);
+            if (result.kind === 'edit-intent') {
+                // User rejected a suggestion → return to intent stage, preserve text,
+                // wait for them to revise and explicitly send again. LLM does NOT
+                // auto-fire — user must press ↵ propose.
+                await overlay.setState({
+                    stage: 'intent',
+                    originalSelector: ctx.originalSelector, action,
+                    callSite: trace.callSite, pomFrame: trace.pomFrame,
+                    pickedHtml, intentText,
+                    ...statusFields({ statusLabel: 'INTENT — revise & send' }),
+                });
+                while (true) {
+                    const m = await overlay.waitForMessage();
+                    if (m.type === 'cancel') {
+                        await appendAuditV2(cacheDir, { event: 'cancel', ...ctx });
+                        throw new HealCancelledError('user cancelled at edit-intent', ctx);
+                    }
+                    if (m.type === 'intent') {
+                        intentText = m.text || intentText;
+                        break;
+                    }
+                }
+                // Loop will re-enter the round with same number — fresh LLM call w/ new intent.
+                round--;
+                continue;
+            }
+            // result.kind === 'retry' — all suggestions invalid → ask broaden.
+            if (round < MAX_ROUNDS) {
+                const ok = await askBroaden(overlay, round);
+                if (!ok)
+                    throw new HealCancelledError('user declined broaden', ctx);
+            }
+        }
+        await appendAuditV2(cacheDir, { event: 'exhausted', ...ctx, attempts: attempts.length });
+        throw new HealExhaustedError(`exhausted ${MAX_ROUNDS} rounds`, { ...ctx, attempts: MAX_ROUNDS });
+    }
+    finally {
+        await overlay.destroy().catch((err) => {
+            logWarn('best-effort overlay teardown failed:', err.message);
+        });
+    }
+}
+async function askBroaden(overlay, round) {
+    await overlay.setState({
+        stage: 'broaden', round,
+        message: `Round ${round} found no unique match. Broaden scope and retry?`,
+        ...statusFields({ statusLabel: 'BROADEN?' }),
+    });
+    const msg = await overlay.waitForMessage();
+    return msg.type === 'broaden';
+}
+async function tryValidateAndConfirm(page, overlay, suggestions, ctx, trace, cacheDir, testFile, intentText, action, attempts, round, pickedHtml, pickedHandle) {
+    for (const sug of suggestions) {
+        const tier = sug.tier ?? tierOfType(sug.selectorType);
+        // js tier — validate via evaluate, not locator
+        if (sug.selectorType === 'js') {
+            const ok = await validateJs(page, sug.selector);
+            if (!ok) {
+                attempts.push({ selectorType: sug.selectorType, selector: sug.selector, tier, reason: 'js-eval-error' });
+                continue;
+            }
+            const decision = await confirmWith(overlay, sug, ctx, trace, intentText, pickedHtml);
+            if (decision === 'accept') {
+                await appendAuditV2(cacheDir, { event: 'js-accepted', ...ctx, round, selector: sug.selector });
+                // audit-only, NOT cached
+                return { kind: 'accepted', entry: synthEntry(ctx.originalSelector, 'css', sug.selector, intentText, action, trace, 9) };
+            }
+            if (decision === 'cancel')
+                return { kind: 'cancel' };
+            attempts.push({ selectorType: sug.selectorType, selector: sug.selector, tier, reason: 'js-eval-error' });
+            continue;
+        }
+        let activeSug = sug;
+        let loc = buildLocator(page, activeSug);
+        let v = await validateProposedLocator(loc, pickedHandle);
+        // P0-5: when an exact role+name match returns count===0, retry with a
+        // case-insensitive regex variant. Accessible names commonly carry
+        // whitespace from adjacent icons (` Login` vs `Login`); the relaxed
+        // form heals those without bothering the operator with another round.
+        if (!v.ok && v.count === 0) {
+            const relaxed = relaxRoleNameMatch(activeSug);
+            if (relaxed) {
+                const relaxedLoc = buildLocator(page, relaxed);
+                const v2 = await validateProposedLocator(relaxedLoc, pickedHandle);
+                if (v2.ok) {
+                    activeSug = relaxed;
+                    loc = relaxedLoc;
+                    v = v2;
+                }
+            }
+        }
+        if (!v.ok) {
+            const reason = v.reason === 'strict-mode-violation' ? 'strict-mode-violation'
+                : v.count > 1 ? 'count-many'
+                    : v.count === 0 ? 'count-zero'
+                        : 'invalid-selector';
+            attempts.push({ selectorType: activeSug.selectorType, selector: activeSug.selector, tier, reason, matchedCount: v.count });
+            await appendAuditV2(cacheDir, {
+                event: 'validate', ...ctx, round,
+                selectorType: activeSug.selectorType, selector: activeSug.selector, ok: false, reason: v.reason ?? '',
+            });
+            continue;
+        }
+        // Pre-cache actionability gate: count===1+visible isn't sufficient — the
+        // element must actually accept the requested action (not overlaid,
+        // disabled, or otherwise unactionable). Without this, cached selectors
+        // poison subsequent runs.
+        const act = await verifyActionable(loc, action);
+        if (!act.ok) {
+            attempts.push({ selectorType: activeSug.selectorType, selector: activeSug.selector, tier, reason: 'count-zero', matchedCount: v.count });
+            await appendAuditV2(cacheDir, {
+                event: 'validate', ...ctx, round,
+                selectorType: activeSug.selectorType, selector: activeSug.selector, ok: false, reason: `actionability: ${act.reason ?? 'unknown'}`,
+            });
+            continue;
+        }
+        const decision = await confirmWith(overlay, activeSug, ctx, trace, intentText, pickedHtml);
+        if (decision === 'accept') {
+            const fingerprint = pickedHandle ? await captureFingerprint(pickedHandle).catch(() => undefined) : undefined;
+            const entry = {
+                originalSelector: ctx.originalSelector, action,
+                healedSelector: activeSug.selector,
+                selectorType: activeSug.selectorType,
+                tier,
+                intent: intentText,
+                callSite: trace.callSite, pomFrame: trace.pomFrame,
+                healedAt: new Date().toISOString(),
+                ...(fingerprint ? { fingerprint } : {}),
+            };
+            await cacheV2Set(cacheDir, testFile, entry);
+            await appendReport(cacheDir, entry);
+            await appendAuditV2(cacheDir, { event: 'accept', ...ctx, round, tier, healedSelector: activeSug.selector });
+            return { kind: 'accepted', entry };
+        }
+        if (decision === 'cancel')
+            return { kind: 'cancel' };
+        // rejected → user wants to revise intent and re-fire LLM.
+        // Drop remaining suggestions in this batch and bubble back up.
+        attempts.push({ selectorType: activeSug.selectorType, selector: activeSug.selector, tier, reason: 'count-zero', matchedCount: 1 });
+        return { kind: 'edit-intent' };
+    }
+    return { kind: 'retry' };
+}
+async function confirmWith(overlay, sug, ctx, trace, intentText, pickedHtml) {
+    await overlay.setState({
+        stage: 'confirm', originalSelector: ctx.originalSelector, action: ctx.action,
+        callSite: trace.callSite, pomFrame: trace.pomFrame,
+        intentText,
+        pickedHtml: pickedHtml ?? '',
+        proposedSelector: `${sug.selectorType}=${sug.selector}`,
+        proposedCode: toPlaywrightCode(sug.selectorType, sug.selector, ctx.action),
+        matchCount: 1,
+        ...statusFields({ statusLabel: 'CONFIRM' }),
+    });
+    const msg = await overlay.waitForMessage();
+    if (msg.type === 'accept')
+        return 'accept';
+    if (msg.type === 'cancel')
+        return 'cancel';
+    return 'reject';
+}
+// Helpers (safeCount, validateJs, tierOfType, extractStructured,
+// tryForegroundUpgrade) moved to ./orchestrator-helpers.ts.
+// toPlaywrightCode lives in ./playwright-code.ts; re-exported for the
+// stable public import path:
+export { toPlaywrightCode } from './playwright-code.js';
+/**
+ * Compute a `PickPreviewInfo` from an `ElementHandle`. Runs entirely
+ * client-side via `evaluate` — no LLM involved.
+ *
+ * Stable-handle priority: `#id` → `[data-testid]` → `[data-test]` →
+ * `[data-cy]` → `[data-qa]` → `[aria-label]` → `role+name`.
+ */
+async function computePickPreview(handle) {
+    return handle.evaluate((el) => {
+        const tag = el.tagName.toLowerCase();
+        // Role: explicit role attr first, then implicit from tag.
+        const explicitRole = el.getAttribute('role') ?? '';
+        const implicitRoleMap = {
+            button: 'button', a: 'link', input: 'textbox', textarea: 'textbox',
+            select: 'combobox', img: 'img', nav: 'navigation', main: 'main',
+            header: 'banner', footer: 'contentinfo', form: 'form', table: 'table',
+            ul: 'list', ol: 'list', li: 'listitem', h1: 'heading', h2: 'heading',
+            h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading',
+        };
+        const role = explicitRole || implicitRoleMap[tag] || tag;
+        // Accessible name: aria-label → aria-labelledby text → visible text trimmed to 80.
+        const ariaLabel = (el.getAttribute('aria-label') ?? '').trim();
+        let accessibleName = ariaLabel;
+        if (!accessibleName) {
+            const labelledById = el.getAttribute('aria-labelledby');
+            if (labelledById) {
+                const ref = document.getElementById(labelledById);
+                accessibleName = (ref?.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 80);
+            }
+        }
+        if (!accessibleName) {
+            accessibleName = (el.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 80);
+        }
+        accessibleName = accessibleName || '(no accessible name)';
+        // Text: first 60 chars textContent single-line.
+        const text = (el.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 60);
+        // Stable handle: prefer most-stable attribute.
+        let stableHandle = '';
+        const id = el.id ? el.id.trim() : '';
+        if (id) {
+            stableHandle = `#${id}`;
+        }
+        else {
+            const testid = el.getAttribute('data-testid') ?? el.getAttribute('data-test') ??
+                el.getAttribute('data-cy') ?? el.getAttribute('data-qa') ?? '';
+            if (testid) {
+                const attr = el.getAttribute('data-testid') !== null ? 'data-testid'
+                    : el.getAttribute('data-test') !== null ? 'data-test'
+                        : el.getAttribute('data-cy') !== null ? 'data-cy'
+                            : 'data-qa';
+                stableHandle = `[${attr}="${testid}"]`;
+            }
+            else if (ariaLabel) {
+                stableHandle = `[aria-label="${ariaLabel}"]`;
+            }
+            else if (role && accessibleName && accessibleName !== '(no accessible name)') {
+                const nameSlice = accessibleName.slice(0, 40);
+                stableHandle = `${role}[name="${nameSlice}"]`;
+            }
+        }
+        return { tag, role, accessibleName, text, stableHandle };
+    });
+}
+/**
+ * Construct a `HealEntryV2` record. Used both for cache writes and for
+ * the live re-check / preflight paths that never round-trip the LLM.
+ *
+ * @param original - Original (broken) selector string.
+ * @param type - Healed selector kind (`css`, `role`, `testid`, ...).
+ * @param healed - Healed selector body (no `kind=` prefix).
+ * @param intent - Natural-language intent string captured from the user.
+ * @param action - Playwright action verb (`click`, `fill`, ...).
+ * @param trace - Parsed source-trace `{ callSite, pomFrame }`.
+ * @param tier - Selector tier 1-7 (default 6 = xpath fallback).
+ * @returns A fully populated `HealEntryV2` with `healedAt` set to now.
+ */
+/**
+ * Cheap deterministic guard against the "operator picked the wrong element"
+ * failure mode. Inspects tag + intent text + action verb. Returns a reason
+ * string if the picked element is incompatible with the action, else null.
+ *
+ * Examples caught:
+ *   - intent="login button", action="click", picked=`<input type="text">` → "input-for-button-intent"
+ *   - action="fill", picked=`<button>` → "button-for-fill"
+ *
+ * Not a perfect semantic check; just blocks the most common adversarial picks
+ * the QA suite found. The overlay PICK-PREVIEW pane (Batch D) is the primary
+ * defense — this is belt-and-suspenders.
+ */
+async function detectPreflightMismatch(handle, action, intentText) {
+    try {
+        const tag = await handle.evaluate((el) => el.tagName.toLowerCase());
+        const typeAttr = await handle.evaluate((el) => el.getAttribute('type') || '');
+        const intent = intentText.toLowerCase();
+        const BUTTON_HINTS = ['button', 'submit', 'click', 'login', 'signin', 'sign in', 'go ', 'continue', 'confirm'];
+        const FILL_HINTS = ['fill', 'enter', 'type', 'input', 'textbox', 'password', 'email', 'username'];
+        const looksLikeButtonIntent = BUTTON_HINTS.some((kw) => intent.includes(kw));
+        const looksLikeFillIntent = FILL_HINTS.some((kw) => intent.includes(kw));
+        const isClickAction = action === 'click' || action === 'tap' || action === 'dblclick';
+        const isFillAction = action === 'fill' || action === 'type' || action === 'pressSequentially' || action === 'clear';
+        const isTextInput = tag === 'textarea' || (tag === 'input' && !['button', 'submit', 'reset', 'image', 'checkbox', 'radio'].includes(typeAttr.toLowerCase()));
+        const isButton = tag === 'button' || (tag === 'input' && ['button', 'submit', 'reset', 'image'].includes(typeAttr.toLowerCase()));
+        if (isClickAction && isTextInput && looksLikeButtonIntent) {
+            return `input-for-button-intent: picked <${tag}${typeAttr ? ` type="${typeAttr}"` : ''}> but action=click + intent mentions button/submit`;
+        }
+        if (isFillAction && isButton) {
+            return `button-for-fill: picked <${tag}> but action=${action} expects a fillable field`;
+        }
+        if (isClickAction && looksLikeFillIntent && isTextInput) {
+            return `input-for-fill-intent-but-click-action: intent looks like fill but action is click`;
+        }
+        return null;
+    }
+    catch {
+        // intentionally swallowed: pick handle could be detached → can't guard, let it through
+        return null;
+    }
+}
+export function synthEntry(original, type, healed, intent, action, trace, tier = 6, fingerprint) {
+    return {
+        originalSelector: original, action, healedSelector: healed,
+        selectorType: type, tier, intent,
+        callSite: trace.callSite, pomFrame: trace.pomFrame,
+        healedAt: new Date().toISOString(),
+        ...(fingerprint ? { fingerprint } : {}),
+    };
+}
+//# sourceMappingURL=orchestrator.js.map