playwright-locator-healer 0.1.3

package/dist/healing/validator.js

@@ -0,0 +1,286 @@
+import { z } from 'zod';
+import { HealingError } from './errors.js';
+/**
+ * Capture a stable fingerprint of a DOM element for cache-drift detection.
+ * Recomputed on cache hit; entries whose fingerprint has drifted are
+ * treated as stale and re-healed instead of trusted blindly.
+ *
+ * @param handle - Element handle, usually the operator's picked node.
+ * @returns Fingerprint (tag + role + name + text + key attrs).
+ */
+export async function captureFingerprint(handle) {
+    return handle.evaluate((el) => {
+        const e = el;
+        const attrs = {};
+        for (const k of ['id', 'name', 'data-testid', 'data-test', 'data-qa', 'data-cy', 'aria-label']) {
+            const v = e.getAttribute(k);
+            if (v)
+                attrs[k] = v;
+        }
+        const tag = e.tagName.toLowerCase();
+        const role = e.getAttribute('role') ?? '';
+        const accessibleName = e.ariaLabel ?? e.getAttribute('aria-label') ?? (e.textContent ?? '').trim().slice(0, 80);
+        const text = (e.textContent ?? '').trim().slice(0, 80);
+        return {
+            tag,
+            ...(role ? { role } : {}),
+            ...(accessibleName ? { accessibleName } : {}),
+            ...(text ? { text } : {}),
+            ...(Object.keys(attrs).length ? { attrs } : {}),
+        };
+    });
+}
+/**
+ * Compare two fingerprints. Returns true if they match within a tolerance
+ * suitable for "same logical element after a minor DOM change".
+ *
+ * - tag must match exactly
+ * - role, accessibleName, text compared via Levenshtein distance ≤ 30%
+ * - any matching stable attr (id, testid, aria-label) short-circuits to match
+ *
+ * @param a - Cached fingerprint.
+ * @param b - Live recomputed fingerprint.
+ */
+export function fingerprintMatches(a, b) {
+    if (a.tag !== b.tag)
+        return false;
+    // Stable-attr short-circuit: if any of id/testid/aria-label matches, accept.
+    if (a.attrs && b.attrs) {
+        for (const k of ['id', 'data-testid', 'data-test', 'data-qa', 'data-cy', 'aria-label']) {
+            if (a.attrs[k] && a.attrs[k] === b.attrs[k])
+                return true;
+        }
+    }
+    const within = (s1, s2) => {
+        if (!s1 && !s2)
+            return true;
+        if (!s1 || !s2)
+            return false;
+        if (s1 === s2)
+            return true;
+        const max = Math.max(s1.length, s2.length);
+        if (max === 0)
+            return true;
+        const dist = levenshtein(s1, s2);
+        return dist / max <= 0.3;
+    };
+    return within(a.role, b.role) && within(a.accessibleName, b.accessibleName) && within(a.text, b.text);
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    const prev = new Array(b.length + 1).fill(0).map((_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let curr = i;
+        let topLeft = i - 1;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const next = Math.min(curr + 1, prev[j] + 1, topLeft + cost);
+            topLeft = prev[j];
+            prev[j] = curr;
+            curr = next;
+        }
+        prev[b.length] = curr;
+    }
+    return prev[b.length];
+}
+// Filter-chain shape: root + optional filters + optional target. Strict
+// rejects any unknown key — enforcing max depth=2 (no nested chain/deeper).
+const FilterChainSpecSchema = z.object({
+    root: z.string().min(1),
+    filters: z.array(z.record(z.unknown())).optional().default([]),
+    target: z.string().optional(),
+}).strict();
+/**
+ * If a role suggestion's exact `name="X"` returns no matches, produce a
+ * relaxed variant using a case-insensitive regex match. Accessible names
+ * commonly carry leading/trailing whitespace introduced by adjacent icons
+ * (`<button><i>icon</i> Login</button>` → accessibleName=` Login`), and
+ * exact-string matches fail in that case.
+ *
+ * Returns the relaxed suggestion (new selector string) or null if the input
+ * isn't a role+name selector.
+ *
+ * @param suggestion - Original LLM suggestion.
+ * @returns Relaxed suggestion with regex name, or null.
+ */
+export function relaxRoleNameMatch(suggestion) {
+    if (suggestion.selectorType !== 'role')
+        return null;
+    const m = suggestion.selector.match(/^([^\[]+)\[name="([^"]+)"\](.*)$/);
+    if (!m)
+        return null;
+    const [, rolePart, name, rest] = m;
+    const escaped = name.trim().replace(/[\\/]/g, (s) => `\\${s}`);
+    const relaxedSelector = `${rolePart}[name=/${escaped}/i]${rest}`;
+    return { ...suggestion, selector: relaxedSelector };
+}
+export function buildLocator(page, suggestion) {
+    switch (suggestion.selectorType) {
+        case 'role': {
+            // LLM sometimes generates aria-label= instead of name=; the role= selector
+            // engine only recognizes name=, checked=, disabled= etc. — not aria-label=.
+            const normalized = suggestion.selector.replace(/\baria-label=/gi, 'name=');
+            return page.locator(`role=${normalized}`);
+        }
+        case 'text':
+            return page.getByText(suggestion.selector, { exact: false });
+        case 'label':
+            return page.getByLabel(suggestion.selector);
+        case 'testid':
+            return page.getByTestId(suggestion.selector);
+        case 'filter-chain': {
+            let raw;
+            try {
+                raw = JSON.parse(suggestion.selector);
+            }
+            catch (e) {
+                throw new HealingError(`filter-chain JSON parse failed: ${e.message}`, 'invalid-filter-chain');
+            }
+            const parsed = FilterChainSpecSchema.safeParse(raw);
+            if (!parsed.success) {
+                throw new HealingError(`filter-chain rejected (depth or shape): ${parsed.error.message}`, 'invalid-filter-chain');
+            }
+            const spec = parsed.data;
+            let loc = page.locator(spec.root);
+            for (const f of spec.filters)
+                loc = loc.filter(f);
+            if (spec.target)
+                loc = loc.locator(spec.target);
+            return loc;
+        }
+        case 'js':
+            // js tier is validated via direct evaluate path; buildLocator can't build it.
+            // Return a never-matching locator so any downstream attempt fails-closed.
+            return page.locator('__heal_never_match__');
+        case 'css':
+        case 'xpath':
+        default:
+            return page.locator(suggestion.selector);
+    }
+}
+export async function validateLocator(page, suggestion, timeoutMs = 5000) {
+    try {
+        const locator = buildLocator(page, suggestion);
+        // Wait for at least one match to be visible (handles JS-rendered content),
+        // then require exactly one match so we never cache an ambiguous locator.
+        await locator.first().waitFor({ state: 'visible', timeout: timeoutMs });
+        const count = await locator.count();
+        return count === 1;
+    }
+    catch {
+        return false;
+    }
+}
+export async function validateProposedSelector(page, selector, picked) {
+    let count;
+    try {
+        count = await page.locator(selector).count();
+    }
+    catch (err) {
+        return { ok: false, count: 0, reason: `invalid selector: ${err.message}` };
+    }
+    if (count !== 1) {
+        return { ok: false, count, reason: `matched ${count}, expected 1` };
+    }
+    const matched = await page.locator(selector).elementHandle();
+    const same = matched && (await matched.evaluate((a, b) => a === b, picked));
+    if (!same)
+        return { ok: false, count, reason: 'matched a different node than picked' };
+    return { ok: true, count };
+}
+export async function validateProposedLocator(locator, picked) {
+    let count = 0;
+    try {
+        count = await locator.count();
+    }
+    catch (err) {
+        const msg = String(err?.message ?? err);
+        if (msg.includes('strict mode violation'))
+            return { ok: false, count: -1, reason: 'strict-mode-violation' };
+        return { ok: false, count: 0, reason: `invalid locator: ${msg}` };
+    }
+    if (count !== 1)
+        return { ok: false, count, reason: `matched ${count}, expected 1` };
+    try {
+        const visible = await locator.isVisible();
+        if (!visible)
+            return { ok: false, count, reason: 'not visible' };
+    }
+    catch (err) {
+        return { ok: false, count, reason: `visibility check failed: ${err?.message ?? err}` };
+    }
+    // P0-4 identity check: when the operator picked a specific DOM node in the
+    // overlay, the LLM's proposed selector must resolve to that same node. A
+    // uniquely-resolving sibling that passes count===1 + visible would
+    // otherwise be cached and poison every subsequent run.
+    if (picked) {
+        try {
+            const resolvedHandle = await locator.elementHandle();
+            if (!resolvedHandle)
+                return { ok: false, count, reason: 'identity-drift: resolved no handle' };
+            const same = await resolvedHandle.evaluate((a, b) => a === b, picked);
+            if (!same)
+                return { ok: false, count, reason: 'identity-drift: resolved a different node' };
+        }
+        catch (err) {
+            return { ok: false, count, reason: `identity check failed: ${err?.message ?? err}` };
+        }
+    }
+    return { ok: true, count };
+}
+/**
+ * Verify a candidate locator is actionable for the requested action BEFORE
+ * writing it to cache. Without this check the healer can cache a selector
+ * that resolves count===1 + visible but isn't actually clickable (overlay,
+ * pointer-events:none, disabled). Cache then poisons every subsequent run.
+ *
+ * Uses Playwright's trial mode for mutating actions: the action is fully
+ * simulated (visibility, stability, enabledness, no overlap) but not
+ * performed. For read-only actions a lighter check suffices.
+ *
+ * @param locator - Built locator under validation.
+ * @param action - Method name the test will invoke on success (`click`, `fill`...).
+ * @param timeoutMs - Budget per probe.
+ * @returns `{ ok }` plus a `reason` describing the first failing check.
+ */
+export async function verifyActionable(locator, action, timeoutMs = 1500) {
+    const TRIAL_ACTIONS = new Set(['click', 'dblclick', 'tap', 'hover', 'check', 'uncheck']);
+    const EDIT_ACTIONS = new Set(['fill', 'type', 'press', 'pressSequentially', 'clear', 'setInputFiles', 'selectText', 'selectOption']);
+    try {
+        if (TRIAL_ACTIONS.has(action)) {
+            // Playwright's `trial: true` runs the full actionability waiter
+            // (visible, stable, enabled, receives events) without performing.
+            await locator[action]({ trial: true, timeout: timeoutMs });
+            return { ok: true, count: 1 };
+        }
+        if (EDIT_ACTIONS.has(action)) {
+            const visible = await locator.isVisible();
+            if (!visible)
+                return { ok: false, count: 1, reason: 'edit target not visible' };
+            const enabled = await locator.isEnabled();
+            if (!enabled)
+                return { ok: false, count: 1, reason: 'edit target not enabled' };
+            if (action === 'fill' || action === 'type' || action === 'clear' || action === 'pressSequentially') {
+                const editable = await locator.isEditable().catch(() => true);
+                if (!editable)
+                    return { ok: false, count: 1, reason: 'edit target not editable' };
+            }
+            return { ok: true, count: 1 };
+        }
+        // assertions, queries, focus, scrollIntoViewIfNeeded — visibility is enough
+        const visible = await locator.isVisible();
+        if (!visible)
+            return { ok: false, count: 1, reason: 'not visible' };
+        return { ok: true, count: 1 };
+    }
+    catch (err) {
+        const msg = String(err?.message ?? err);
+        return { ok: false, count: 1, reason: `actionability failed: ${msg.split('\n')[0].slice(0, 200)}` };
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/healing/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../healing/validator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAqB;IAC5D,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAO,EAAE,EAAE;QACjC,MAAM,CAAC,GAAG,EAAa,CAAC;QACxB,MAAM,KAAK,GAA2B,EAAE,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,CAAC,EAAE,CAAC;YAC/F,MAAM,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,CAAC;gBAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;QACD,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC1C,MAAM,cAAc,GAAI,CAAS,CAAC,SAAS,IAAI,CAAC,CAAC,YAAY,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzH,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvD,OAAO;YACL,GAAG;YACH,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzB,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAuB,EAAE,CAAuB;IACjF,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IAClC,6EAA6E;IAC7E,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,CAAC,EAAE,CAAC;YACvF,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,EAAW,EAAE,EAAW,EAAW,EAAE;QACnD,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAC5B,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC;QAC7B,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,GAAG,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3B,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACjC,OAAO,IAAI,GAAG,GAAG,IAAI,GAAG,CAAC;IAC3B,CAAC,CAAC;IACF,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,cAAc,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AACxG,CAAC;AAED,SAAS,WAAW,CAAC,CAAS,EAAE,CAAS;IACvC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtB,IAAI,CAAC,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IAC/B,IAAI,CAAC,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,IAAI,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;QACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,CAAC;YAC7D,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;YACf,IAAI,GAAG,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC;AAID,wEAAwE;AACxE,4EAA4E;AAC5E,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IAC9D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAA6B;IAC9D,IAAI,UAAU,CAAC,YAAY,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACpD,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACxE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC/D,MAAM,eAAe,GAAG,GAAG,QAAQ,UAAU,OAAO,MAAM,IAAI,EAAE,CAAC;IACjE,OAAO,EAAE,GAAG,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAU,EAAE,UAA6B;IACpE,QAAQ,UAAU,CAAC,YAAY,EAAE,CAAC;QAChC,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,2EAA2E;YAC3E,4EAA4E;YAC5E,MAAM,UAAU,GAAG,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;YAC3E,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,UAAU,EAAE,CAAC,CAAC;QAC5C,CAAC;QACD,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/D,KAAK,OAAO;YACV,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC9C,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC/C,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,IAAI,GAAY,CAAC;YACjB,IAAI,CAAC;gBAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAAC,CAAC;YAC9C,OAAO,CAAC,EAAE,CAAC;gBACT,MAAM,IAAI,YAAY,CACpB,mCAAoC,CAAW,CAAC,OAAO,EAAE,EACzD,sBAAsB,CACvB,CAAC;YACJ,CAAC;YACD,MAAM,MAAM,GAAG,qBAAqB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YACpD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,MAAM,IAAI,YAAY,CACpB,2CAA2C,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,EACjE,sBAAsB,CACvB,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;YACzB,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO;gBAAE,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAQ,CAAC,CAAC;YACzD,IAAI,IAAI,CAAC,MAAM;gBAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAChD,OAAO,GAAG,CAAC;QACb,CAAC;QACD,KAAK,IAAI;YACP,8EAA8E;YAC9E,0EAA0E;YAC1E,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC;QAC9C,KAAK,KAAK,CAAC;QACX,KAAK,OAAO,CAAC;QACb;YACE,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAU,EACV,UAA6B,EAC7B,SAAS,GAAG,IAAI;IAEhB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC/C,2EAA2E;QAC3E,yEAAyE;QACzE,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QACxE,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACpC,OAAO,KAAK,KAAK,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAQD,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,IAAU,EAAE,QAAgB,EAAE,MAAqB;IAEnD,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,qBAAsB,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC;IACxF,CAAC;IACD,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,KAAK,cAAc,EAAE,CAAC;IACtE,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,aAAa,EAAE,CAAC;IAC7D,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5E,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,sCAAsC,EAAE,CAAC;IACvF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAgB,EAAE,MAA4B;IAE9C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IAChC,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC;QACxC,IAAI,GAAG,CAAC,QAAQ,CAAC,uBAAuB,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;QAC5G,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,oBAAoB,GAAG,EAAE,EAAE,CAAC;IACpE,CAAC;IACD,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,KAAK,cAAc,EAAE,CAAC;IACrF,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC;QAC1C,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IACnE,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,4BAA4B,GAAG,EAAE,OAAO,IAAI,GAAG,EAAE,EAAE,CAAC;IACzF,CAAC;IACD,2EAA2E;IAC3E,yEAAyE;IACzE,mEAAmE;IACnE,uDAAuD;IACvD,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,aAAa,EAAE,CAAC;YACrD,IAAI,CAAC,cAAc;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,EAAE,CAAC;YAC/F,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;YACtE,IAAI,CAAC,IAAI;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,2CAA2C,EAAE,CAAC;QAC9F,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,GAAG,EAAE,OAAO,IAAI,GAAG,EAAE,EAAE,CAAC;QACvF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgB,EAChB,MAAc,EACd,SAAS,GAAG,IAAI;IAEhB,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IACzF,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,CAAC,CAAC,CAAC;IACrI,IAAI,CAAC;QACH,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,gEAAgE;YAChE,kEAAkE;YAClE,MAAO,OAAe,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;YACpE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAChC,CAAC;QACD,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC;YAC1C,IAAI,CAAC,OAAO;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;YAChF,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC;YAC1C,IAAI,CAAC,OAAO;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;YAChF,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,mBAAmB,EAAE,CAAC;gBACnG,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;gBAC9D,IAAI,CAAC,QAAQ;oBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;YACpF,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAChC,CAAC;QACD,4EAA4E;QAC5E,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC;QAC1C,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QACpE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAChC,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC;QACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,yBAAyB,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;IACtG,CAAC;AACH,CAAC"}

package/dist/scripts/heal-report.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * scripts/heal-report.ts
+ *
+ * Reads `.healed-locators/cost.daily.json` and prints a markdown table:
+ *
+ *   | date | calls | cost (USD) | cache hit rate | cumulative cost (USD) |
+ *
+ * Sorted newest day first. Cumulative is computed by accumulating cost from
+ * the oldest day forward, then displayed against each row. Cache hit rate is
+ * `cachedCalls / calls`; displayed as `n/a` for rows missing `cachedCalls`
+ * (pre-cache-tracking historical data).
+ *
+ * Usage:
+ *   npx tsx scripts/heal-report.ts
+ *   npx tsx scripts/heal-report.ts --file path/to/cost.daily.json
+ *
+ * Exit codes:
+ *   0  ok (table or "no data" notice printed)
+ *   1  file read/parse error
+ */
+export {};
+//# sourceMappingURL=heal-report.d.ts.map

package/dist/scripts/heal-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heal-report.d.ts","sourceRoot":"","sources":["../../scripts/heal-report.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/scripts/heal-report.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * scripts/heal-report.ts
+ *
+ * Reads `.healed-locators/cost.daily.json` and prints a markdown table:
+ *
+ *   | date | calls | cost (USD) | cache hit rate | cumulative cost (USD) |
+ *
+ * Sorted newest day first. Cumulative is computed by accumulating cost from
+ * the oldest day forward, then displayed against each row. Cache hit rate is
+ * `cachedCalls / calls`; displayed as `n/a` for rows missing `cachedCalls`
+ * (pre-cache-tracking historical data).
+ *
+ * Usage:
+ *   npx tsx scripts/heal-report.ts
+ *   npx tsx scripts/heal-report.ts --file path/to/cost.daily.json
+ *
+ * Exit codes:
+ *   0  ok (table or "no data" notice printed)
+ *   1  file read/parse error
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+function parseArgs(argv) {
+    let file = join(process.cwd(), '.healed-locators', 'cost.daily.json');
+    for (let i = 0; i < argv.length; i++) {
+        if ((argv[i] === '--file' || argv[i] === '-f') && argv[i + 1]) {
+            file = resolve(argv[i + 1]);
+            i++;
+        }
+    }
+    return { file };
+}
+function fmtCost(n) {
+    return `$${n.toFixed(4)}`;
+}
+function fmtRate(hits, calls) {
+    if (hits === undefined || calls === 0)
+        return 'n/a';
+    return `${((hits / calls) * 100).toFixed(1)}%`;
+}
+function buildTable(data) {
+    const entries = Object.entries(data.byDay);
+    if (entries.length === 0) {
+        return '_(no recorded LLM calls — `.healed-locators/cost.daily.json` is empty)_';
+    }
+    // Sort oldest → newest to compute cumulative, then reverse for display.
+    entries.sort(([a], [b]) => a.localeCompare(b));
+    let running = 0;
+    const rows = entries.map(([date, row]) => {
+        running += row.cost;
+        return {
+            date,
+            calls: row.calls,
+            cost: row.cost,
+            cumulative: running,
+            hitRate: fmtRate(row.cachedCalls, row.calls),
+        };
+    });
+    rows.reverse();
+    const lines = [];
+    lines.push('| date | calls | cost | cache hit rate | cumulative |');
+    lines.push('|------|------:|-----:|---------------:|-----------:|');
+    for (const r of rows) {
+        lines.push(`| ${r.date} | ${r.calls} | ${fmtCost(r.cost)} | ${r.hitRate} | ${fmtCost(r.cumulative)} |`);
+    }
+    const all = data.allTime;
+    lines.push(`| **all-time** | **${all.calls}** | **${fmtCost(all.cost)}** | **${fmtRate(all.cachedCalls, all.calls)}** | **${fmtCost(all.cost)}** |`);
+    return lines.join('\n');
+}
+function main() {
+    const { file } = parseArgs(process.argv.slice(2));
+    if (!existsSync(file)) {
+        process.stdout.write(`# Heal cost report\n\n_(no data — ${file} does not exist)_\n`);
+        return 0;
+    }
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf-8');
+    }
+    catch (err) {
+        process.stderr.write(`error: cannot read ${file}: ${err.message}\n`);
+        return 1;
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        process.stderr.write(`error: cannot parse ${file} as JSON: ${err.message}\n`);
+        return 1;
+    }
+    // Defensive: tolerate partial shapes.
+    if (!data || typeof data !== 'object' || !data.byDay) {
+        data = { byDay: {}, allTime: { cost: 0, calls: 0 } };
+    }
+    if (!data.allTime)
+        data.allTime = { cost: 0, calls: 0 };
+    process.stdout.write('# Heal cost report\n\n');
+    process.stdout.write(`Source: \`${file}\`\n\n`);
+    process.stdout.write(buildTable(data));
+    process.stdout.write('\n');
+    return 0;
+}
+process.exit(main());
+//# sourceMappingURL=heal-report.js.map

package/dist/scripts/heal-report.js.map

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

package/dist/scripts/init.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/scripts/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../scripts/init.ts"],"names":[],"mappings":""}

package/dist/scripts/init.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * scripts/init.ts
+ *
+ * `npx playwright-locator-healer init` — one-command setup for a consumer
+ * project. Idempotent: re-running is safe.
+ *
+ * Steps performed (each is a no-op if already done):
+ *   1. Verify peer dep — @playwright/test ≥ 1.59
+ *   2. Verify OPENAI_API_KEY presence (env or .env)
+ *   3. Write .env.example if missing
+ *   4. Create .healed-locators/.gitkeep (cache dir tracked, contents kept)
+ *   5. Append safe entries to .gitignore (cache screenshots + logs only)
+ *   6. Print next-steps banner
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+const ENV_EXAMPLE_TEMPLATE = `# OpenAI key — required when a heal fires (cache hits do not need it)
+OPENAI_API_KEY=
+
+# Optional — see healing/models.ts for full registry
+# HEAL_MODEL=gpt-4o-mini
+
+# Optional — debug|info|warn|error (default warn)
+# HEAL_LOG_LEVEL=warn
+
+# Optional — defaults to .healed-locators relative to cwd
+# HEAL_CACHE_DIR=.healed-locators
+`;
+const GITIGNORE_ENTRIES = [
+    '# playwright-heal — screenshot evidence + logs (cache JSON stays tracked)',
+    '.healed-locators/screenshots/',
+    '.healed-locators/*.log',
+];
+function log(prefix, msg) {
+    process.stdout.write(`${prefix} ${msg}\n`);
+}
+function checkPlaywright(cwd) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return { step: 'peer-dep', ok: false, message: 'no package.json in cwd — run from your project root' };
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    }
+    catch (e) {
+        return { step: 'peer-dep', ok: false, message: `package.json invalid: ${e.message}` };
+    }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (!deps['@playwright/test']) {
+        return { step: 'peer-dep', ok: false, message: '@playwright/test not installed — run `npm install --save-dev @playwright/test`' };
+    }
+    return { step: 'peer-dep', ok: true, message: `@playwright/test ${deps['@playwright/test']} detected` };
+}
+function checkOpenAIKey(cwd) {
+    if (process.env.OPENAI_API_KEY) {
+        return { step: 'api-key', ok: true, message: 'OPENAI_API_KEY set in shell env' };
+    }
+    const envPath = join(cwd, '.env');
+    if (existsSync(envPath)) {
+        const txt = readFileSync(envPath, 'utf-8');
+        const match = txt.match(/^OPENAI_API_KEY=(.+)$/m);
+        if (match && match[1].trim().length > 0) {
+            return { step: 'api-key', ok: true, message: 'OPENAI_API_KEY found in .env' };
+        }
+    }
+    return { step: 'api-key', ok: false, message: 'OPENAI_API_KEY not set — see .env.example for placeholder, then add to .env or shell' };
+}
+function ensureEnvExample(cwd) {
+    const path = join(cwd, '.env.example');
+    if (existsSync(path))
+        return { step: 'env-example', ok: true, message: '.env.example already present (unchanged)' };
+    writeFileSync(path, ENV_EXAMPLE_TEMPLATE);
+    return { step: 'env-example', ok: true, message: 'wrote .env.example' };
+}
+function ensureCacheDir(cwd) {
+    const dir = join(cwd, '.healed-locators');
+    const keep = join(dir, '.gitkeep');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    if (!existsSync(keep))
+        writeFileSync(keep, '');
+    return { step: 'cache-dir', ok: true, message: `${dir} ready (.gitkeep present, commit the directory to share heals)` };
+}
+function ensureGitignore(cwd) {
+    const path = join(cwd, '.gitignore');
+    const current = existsSync(path) ? readFileSync(path, 'utf-8') : '';
+    const missing = GITIGNORE_ENTRIES.filter((e) => !e.startsWith('#') && !current.includes(e));
+    if (missing.length === 0) {
+        return { step: 'gitignore', ok: true, message: '.gitignore already covers heal artifacts (unchanged)' };
+    }
+    const sep = current.length === 0 || current.endsWith('\n') ? '' : '\n';
+    const block = `${sep}\n${GITIGNORE_ENTRIES.join('\n')}\n`;
+    appendFileSync(path, block);
+    return { step: 'gitignore', ok: true, message: `added ${missing.length} entries to .gitignore` };
+}
+function printNextSteps(allOk) {
+    process.stdout.write('\n');
+    log('[heal]', '────────── next steps ──────────');
+    log('[heal]', '1. Change your spec import:');
+    log('[heal]', `     import { test, expect } from 'playwright-locator-healer/auto';`);
+    log('[heal]', '2. Run your tests:');
+    log('[heal]', '     npx playwright test --headed');
+    log('[heal]', '3. When a locator breaks, an overlay opens — pick the element, accept, done.');
+    log('[heal]', '4. Cost report any time:');
+    log('[heal]', '     npx heal-report');
+    if (!allOk) {
+        log('[heal]', '');
+        log('[heal]', 'Some checks above need your attention before tests will heal cleanly.');
+    }
+    process.stdout.write('\n');
+}
+function main() {
+    const cwd = resolve(process.cwd());
+    log('[heal]', `init in ${cwd}`);
+    const steps = [
+        checkPlaywright(cwd),
+        ensureEnvExample(cwd),
+        checkOpenAIKey(cwd),
+        ensureCacheDir(cwd),
+        ensureGitignore(cwd),
+    ];
+    for (const s of steps) {
+        log(s.ok ? '[heal] ✓' : '[heal] ✗', `${s.step.padEnd(14)} ${s.message}`);
+    }
+    const allOk = steps.every((s) => s.ok);
+    printNextSteps(allOk);
+    process.exit(allOk ? 0 : 1);
+}
+main();
+//# sourceMappingURL=init.js.map

package/dist/scripts/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../scripts/init.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,oBAAoB,GAAG;;;;;;;;;;;CAW5B,CAAC;AAEF,MAAM,iBAAiB,GAAG;IACxB,2EAA2E;IAC3E,+BAA+B;IAC/B,wBAAwB;CACzB,CAAC;AAQF,SAAS,GAAG,CAAC,MAAc,EAAE,GAAW;IACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAC1C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,qDAAqD,EAAE,CAAC;IACzG,CAAC;IACD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAAC,CAAC;IACzD,OAAO,CAAM,EAAE,CAAC;QAAC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,yBAAyB,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;IAAC,CAAC;IACzG,MAAM,IAAI,GAAG,EAAE,GAAG,GAAG,CAAC,YAAY,EAAE,GAAG,GAAG,CAAC,eAAe,EAAE,CAAC;IAC7D,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,gFAAgF,EAAE,CAAC;IACpI,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,oBAAoB,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,CAAC;AAC1G,CAAC;AAED,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;QAC/B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC;IACnF,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAClD,IAAI,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC;QAChF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,sFAAsF,EAAE,CAAC;AACzI,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IACvC,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,0CAA0C,EAAE,CAAC;IACpH,aAAa,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAC1C,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAC1E,CAAC;AAED,SAAS,cAAc,CAAC,GAAW;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACnC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,GAAG,gEAAgE,EAAE,CAAC;AAC1H,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpE,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5F,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,sDAAsD,EAAE,CAAC;IAC1G,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACvE,MAAM,KAAK,GAAG,GAAG,GAAG,KAAK,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IAC1D,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC5B,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,OAAO,CAAC,MAAM,wBAAwB,EAAE,CAAC;AACnG,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,GAAG,CAAC,QAAQ,EAAE,kCAAkC,CAAC,CAAC;IAClD,GAAG,CAAC,QAAQ,EAAE,6BAA6B,CAAC,CAAC;IAC7C,GAAG,CAAC,QAAQ,EAAE,qEAAqE,CAAC,CAAC;IACrF,GAAG,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;IACpC,GAAG,CAAC,QAAQ,EAAE,mCAAmC,CAAC,CAAC;IACnD,GAAG,CAAC,QAAQ,EAAE,8EAA8E,CAAC,CAAC;IAC9F,GAAG,CAAC,QAAQ,EAAE,0BAA0B,CAAC,CAAC;IAC1C,GAAG,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAClB,GAAG,CAAC,QAAQ,EAAE,uEAAuE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,IAAI;IACX,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACnC,GAAG,CAAC,QAAQ,EAAE,WAAW,GAAG,EAAE,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG;QACZ,eAAe,CAAC,GAAG,CAAC;QACpB,gBAAgB,CAAC,GAAG,CAAC;QACrB,cAAc,CAAC,GAAG,CAAC;QACnB,cAAc,CAAC,GAAG,CAAC;QACnB,eAAe,CAAC,GAAG,CAAC;KACrB,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACvC,cAAc,CAAC,KAAK,CAAC,CAAC;IACtB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,IAAI,EAAE,CAAC"}