tamash-playwright 0.3.0 → 0.5.0

package/dist/healer/providers/types.d.ts

@@ -36,8 +36,44 @@ export type ProviderResult = {
     suggestion: SelectorSuggestion;
     usage?: TokenUsage;
 };
+export type VisionPoint = {
+    found: true;
+    x: number;
+    y: number;
+} | {
+    found: false;
+};
+export type SuggestElementFromImageInput = {
+    action: string;
+    description?: string;
+    /** Raw PNG bytes, base64-encoded, no `data:` URI prefix. */
+    imageBase64: string;
+    timeoutMs?: number;
+};
+export type VisionProviderResult = {
+    point: VisionPoint;
+    usage?: TokenUsage;
+};
+export type ActionTactic = 'scroll' | 'force' | 'wait' | 'dispatch' | 'none';
+export type SuggestActionTacticInput = {
+    action: string;
+    /** The error message from the failed replay attempt (not a selector problem). */
+    errorMessage: string;
+    timeoutMs?: number;
+};
+export type ActionTacticResult = {
+    tactic: ActionTactic;
+    usage?: TokenUsage;
+};
 export type HealProvider = {
     name: string;
     suggestSelector(input: SuggestSelectorInput): Promise<ProviderResult | null>;
+    /** True when this provider's configured model is expected to accept image input; gates whether
+     * suggestSelectorFromImage is actually called — the method itself is always implemented (all
+     * four providers implement every method unconditionally), so callers should key off this flag,
+     * not the method's presence. */
+    supportsVision: boolean;
+    suggestSelectorFromImage(input: SuggestElementFromImageInput): Promise<VisionProviderResult | null>;
+    suggestActionTactic(input: SuggestActionTacticInput): Promise<ActionTacticResult | null>;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/healer/providers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/healer/providers/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAC9E,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/healer/providers/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB,CAAC;AAOF,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEnF,MAAM,MAAM,4BAA4B,GAAG;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB,CAAC;AAMF,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAE7E,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC7E;;;oCAGgC;IAChC,cAAc,EAAE,OAAO,CAAC;IACxB,wBAAwB,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAGpG,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;CAC1F,CAAC"}

package/dist/healer/providers/vision-models.d.ts

@@ -0,0 +1,3 @@
+export type VisionVendor = 'openai' | 'anthropic' | 'gemini' | 'ollama';
+export declare function isVisionCapableModel(vendor: VisionVendor, model: string): boolean;
+//# sourceMappingURL=vision-models.d.ts.map

package/dist/healer/providers/vision-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-models.d.ts","sourceRoot":"","sources":["../../../src/healer/providers/vision-models.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAgCxE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAMjF"}

package/dist/healer/providers/vision-models.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isVisionCapableModel = isVisionCapableModel;
+// New models ship constantly, so this will go stale — it's a best-effort heuristic, not an
+// authoritative capability registry. Getting it wrong is cheap either way: a false positive just
+// means the vision fallback is attempted and the provider call fails/degrades (see each
+// provider's suggestSelectorFromImage error handling); a false negative just means the vision
+// fallback never gets attempted, same as today.
+const VISION_PATTERNS = {
+    openai: {
+        include: [/gpt-4o/i, /gpt-4\.1/i, /gpt-4\.5/i, /gpt-5/i, /\bo1\b/i, /\bo3\b/i, /\bo4\b/i, /vision/i],
+        exclude: [/gpt-3\.5/i, /embedding/i, /whisper/i, /\btts\b/i, /moderation/i],
+    },
+    anthropic: {
+        // All current Claude 3+ models are multimodal; Claude 2.x and Instant predate vision support.
+        include: [/claude-(3|4|5)/i, /claude-(opus|sonnet|haiku)-(3|4|5)/i],
+        exclude: [/claude-2/i, /claude-instant/i],
+    },
+    gemini: {
+        // Every Gemini chat model from 1.5 onward is multimodal by default.
+        include: [/gemini/i],
+        exclude: [/embedding/i, /\baqa\b/i],
+    },
+    ollama: {
+        include: [/llava/i, /bakllava/i, /moondream/i, /llama3\.2-vision/i, /qwen2(\.5)?-vl/i, /minicpm-v/i, /pixtral/i, /granite3\.2-vision/i, /gemma-?[3-9]/i, /vision/i],
+        exclude: [],
+    },
+};
+// The gemma pattern above matches at the family level (gemma3, gemma4, ...) even though each
+// family's smallest variant (e.g. gemma3:1b) is text-only — the tag naming isn't consistent enough
+// to reliably split by parameter size, so this is a documented false-positive risk for those
+// specific small tags rather than something solved here.
+function isVisionCapableModel(vendor, model) {
+    const { include, exclude } = VISION_PATTERNS[vendor];
+    if (exclude.some((pattern) => pattern.test(model))) {
+        return false;
+    }
+    return include.some((pattern) => pattern.test(model));
+}
+//# sourceMappingURL=vision-models.js.map

package/dist/healer/providers/vision-models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-models.js","sourceRoot":"","sources":["../../../src/healer/providers/vision-models.ts"],"names":[],"mappings":";;;AAEA,2FAA2F;AAC3F,iGAAiG;AACjG,wFAAwF;AACxF,8FAA8F;AAC9F,gDAAgD;AAChD,MAAM,eAAe,GAAmE;IACtF,MAAM,EAAE;QACN,OAAO,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC;QACpG,OAAO,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,CAAC;KAC5E;IACD,SAAS,EAAE;QACT,8FAA8F;QAC9F,OAAO,EAAE,CAAC,iBAAiB,EAAE,qCAAqC,CAAC;QACnE,OAAO,EAAE,CAAC,WAAW,EAAE,iBAAiB,CAAC;KAC1C;IACD,MAAM,EAAE;QACN,oEAAoE;QACpE,OAAO,EAAE,CAAC,SAAS,CAAC;QACpB,OAAO,EAAE,CAAC,YAAY,EAAE,UAAU,CAAC;KACpC;IACD,MAAM,EAAE;QACN,OAAO,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,eAAe,EAAE,SAAS,CAAC;QACnK,OAAO,EAAE,EAAE;KACZ;CACF,CAAC;AAEF,6FAA6F;AAC7F,mGAAmG;AACnG,6FAA6F;AAC7F,yDAAyD;AACzD,8BAAqC,MAAoB,EAAE,KAAa;IACtE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACnD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;AACxD,CAAC"}

package/dist/healer/replay-action.d.ts

@@ -0,0 +1,3 @@
+import type { Locator } from '@playwright/test';
+export declare function replayAction(locator: Locator, action: string, callArgs?: unknown[]): Promise<unknown>;
+//# sourceMappingURL=replay-action.d.ts.map

package/dist/healer/replay-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-action.d.ts","sourceRoot":"","sources":["../../src/healer/replay-action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAQhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAyE/G"}

package/dist/healer/replay-action.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replayAction = replayAction;
+// `dragTo`/`drop` (and anything else outside this list) can't be safely "healed" by guessing a
+// substitute locator and clicking it — that would silently perform the wrong action and report
+// a false recovery, so those actions are excluded rather than defaulted to `.click()`.
+//
+// Kept in its own leaf module (rather than healer/index.ts, where it originally lived) so both
+// index.ts and action-recovery.ts can import it without either needing to import the other.
+async function replayAction(locator, action, callArgs = []) {
+    const [firstArg] = callArgs;
+    switch (action) {
+        case 'click':
+            return locator.click();
+        case 'dblclick':
+            return locator.dblclick();
+        case 'tap':
+            return locator.tap();
+        case 'hover':
+            return locator.hover();
+        case 'fill':
+            return locator.fill(String(firstArg ?? ''));
+        case 'clear':
+            return locator.clear();
+        case 'press':
+            return locator.press(String(firstArg ?? ''));
+        case 'check':
+            return locator.check();
+        case 'uncheck':
+            return locator.uncheck();
+        case 'selectOption':
+            return locator.selectOption(firstArg);
+        case 'setInputFiles':
+            return locator.setInputFiles(firstArg);
+        case 'focus':
+            return locator.focus();
+        case 'blur':
+            return locator.blur();
+        case 'type':
+            return locator.type(String(firstArg ?? ''));
+        case 'pressSequentially':
+            return locator.pressSequentially(String(firstArg ?? ''));
+        case 'setChecked':
+            return locator.setChecked(Boolean(firstArg));
+        case 'scrollIntoViewIfNeeded':
+            return locator.scrollIntoViewIfNeeded();
+        case 'dispatchEvent':
+            return locator.dispatchEvent(String(firstArg ?? ''), callArgs[1]);
+        case 'waitFor':
+            return locator.waitFor(firstArg);
+        case 'textContent':
+            return locator.textContent();
+        case 'innerText':
+            return locator.innerText();
+        case 'getAttribute':
+            return locator.getAttribute(String(firstArg ?? ''));
+        case 'inputValue':
+            return locator.inputValue();
+        case 'isChecked':
+            return locator.isChecked();
+        case 'isEnabled':
+            return locator.isEnabled();
+        case 'isDisabled':
+            return locator.isDisabled();
+        case 'isEditable':
+            return locator.isEditable();
+        case 'innerHTML':
+            return locator.innerHTML();
+        case 'selectText':
+            return locator.selectText();
+        case 'screenshot':
+            return locator.screenshot();
+        case 'boundingBox':
+            return locator.boundingBox();
+        case 'elementHandle':
+            return locator.elementHandle();
+        case 'ariaSnapshot':
+            return locator.ariaSnapshot();
+        default:
+            throw new Error(`Action "${action}" cannot be safely replayed by the self-healer.`);
+    }
+}
+//# sourceMappingURL=replay-action.js.map

package/dist/healer/replay-action.js.map

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

package/dist/healer/vision.d.ts

@@ -0,0 +1,25 @@
+import type { Frame, FrameLocator, Page } from '@playwright/test';
+import type { VisionPoint } from './providers/types';
+export type PageContext = Page | Frame | FrameLocator;
+export type ViewportBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type ScrollOffset = {
+    x: number;
+    y: number;
+};
+export type VisionCapture = {
+    imageBase64: string;
+    box: ViewportBox;
+    scroll: ScrollOffset;
+};
+export declare function captureElementForVision(pageContext: PageContext, timeoutMs: number): Promise<VisionCapture | undefined>;
+export declare function resolveElementAtVisionPoint(pageContext: PageContext, point: Extract<VisionPoint, {
+    found: true;
+}>, box: ViewportBox, scroll: ScrollOffset, timeoutMs: number): Promise<string | undefined>;
+export declare function visionTagSelector(id: string): string;
+export declare function cleanupVisionTag(pageContext: PageContext, id: string): Promise<void>;
+//# sourceMappingURL=vision.d.ts.map

package/dist/healer/vision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../../src/healer/vision.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOrD,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,KAAK,GAAG,YAAY,CAAC;AAEtD,MAAM,MAAM,WAAW,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAClF,MAAM,MAAM,YAAY,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,aAAa,GAAG;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,WAAW,CAAC;IACjB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAOF,wBAAsB,uBAAuB,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAkB7H;AAUD,wBAAsB,2BAA2B,CAC/C,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,CAAC,EAC5C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA0B7B;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEpD;AAID,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU1F"}

package/dist/healer/vision.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureElementForVision = captureElementForVision;
+exports.resolveElementAtVisionPoint = resolveElementAtVisionPoint;
+exports.visionTagSelector = visionTagSelector;
+exports.cleanupVisionTag = cleanupVisionTag;
+// Verified empirically (real Chromium run, not assumed): `:root`'s screenshot captures the FULL
+// document height, not just the current viewport — a 2000px-tall document produces a 2000px-tall
+// PNG regardless of scroll position. So a normalized point the vision model returns is a
+// *document*-relative position; resolveElementAtVisionPoint() below is what converts that back to
+// something elementFromPoint() can actually use.
+async function captureElementForVision(pageContext, timeoutMs) {
+    const root = pageContext.locator(':root');
+    try {
+        const box = await root.boundingBox({ timeout: timeoutMs });
+        if (!box) {
+            return undefined;
+        }
+        const [screenshot, scroll] = await Promise.all([
+            root.screenshot({ timeout: timeoutMs }),
+            root.evaluate(() => ({ x: window.scrollX, y: window.scrollY })),
+        ]);
+        return { imageBase64: screenshot.toString('base64'), box, scroll };
+    }
+    catch {
+        return undefined;
+    }
+}
+const HEAL_ATTRIBUTE = 'data-tamash-heal-id';
+// Verified empirically: boundingBox() on `:root` is viewport-relative (its `y` goes negative as
+// the page scrolls down), so `box.{x,y} + scroll.{x,y}` recovers true document coordinates
+// regardless of scroll state at capture time. elementFromPoint() itself only accepts
+// viewport-relative coordinates and returns null for anything currently scrolled out of view, so
+// resolution has to scroll first — done in a single evaluate() call so the scroll and the lookup
+// happen atomically, with no round trip in between for the page to move again.
+async function resolveElementAtVisionPoint(pageContext, point, box, scroll, timeoutMs) {
+    const docX = box.x + scroll.x + (point.x / 1000) * box.width;
+    const docY = box.y + scroll.y + (point.y / 1000) * box.height;
+    try {
+        const id = await pageContext.locator(':root').evaluate((_rootEl, [dx, dy]) => {
+            window.scrollTo({ left: Math.max(0, dx - window.innerWidth / 2), top: Math.max(0, dy - window.innerHeight / 2) });
+            const vx = dx - window.scrollX;
+            const vy = dy - window.scrollY;
+            const el = document.elementFromPoint(vx, vy);
+            if (!el || el === document.documentElement || el === document.body) {
+                return null;
+            }
+            const generatedId = `tamash-heal-${Math.random().toString(36).slice(2)}`;
+            el.setAttribute('data-tamash-heal-id', generatedId);
+            return generatedId;
+        }, [docX, docY], { timeout: timeoutMs });
+        return id ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function visionTagSelector(id) {
+    return `[${HEAL_ATTRIBUTE}="${id}"]`;
+}
+// Best-effort: the healed action itself may have removed/replaced the tagged element (e.g. it
+// was a "dismiss" button), so a failure here is expected sometimes and not worth surfacing.
+async function cleanupVisionTag(pageContext, id) {
+    try {
+        // `HEAL_ATTRIBUTE` must be passed as an explicit evaluate() argument, not closed over — the
+        // callback is serialized and runs standalone in the page, with no access to this module's
+        // Node-side scope (confirmed the hard way: closing over it threw "HEAL_ATTRIBUTE is not
+        // defined" inside the browser context).
+        await pageContext.locator(visionTagSelector(id)).evaluate((el, attr) => el.removeAttribute(attr), HEAL_ATTRIBUTE);
+    }
+    catch {
+        // Ignore — see above.
+    }
+}
+//# sourceMappingURL=vision.js.map

package/dist/healer/vision.js.map

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

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { test, expect } from './bindings';
 export type { BindingFixtures } from './bindings';
-export { bindPageActions, bindFrameActions, bindLocatorActions, bindTargetActions } from './bindings/locator.binding';
+export { bindPageActions, bindFrameActions, bindLocatorActions, bindTargetActions, bindContext } from './bindings/locator.binding';
 export { healActionFailure, getHealingReports } from './healer';
 export type { SelfHealingReport } from './healer';
-export type { HealProvider, SelectorSuggestion, SuggestSelectorInput, TokenUsage, ProviderResult } from './healer/providers/types';
+export type { HealProvider, SelectorSuggestion, SuggestSelectorInput, TokenUsage, ProviderResult, VisionPoint, SuggestElementFromImageInput, VisionProviderResult, ActionTactic, SuggestActionTacticInput, ActionTacticResult } from './healer/providers/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEtH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAChE,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEnI,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAChE,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,YAAY,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getHealingReports = exports.healActionFailure = exports.bindTargetActions = exports.bindLocatorActions = exports.bindFrameActions = exports.bindPageActions = exports.expect = exports.test = void 0;
+exports.getHealingReports = exports.healActionFailure = exports.bindContext = exports.bindTargetActions = exports.bindLocatorActions = exports.bindFrameActions = exports.bindPageActions = exports.expect = exports.test = void 0;
 var bindings_1 = require("./bindings");
 Object.defineProperty(exports, "test", { enumerable: true, get: function () { return bindings_1.test; } });
 Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return bindings_1.expect; } });
@@ -9,6 +9,7 @@ Object.defineProperty(exports, "bindPageActions", { enumerable: true, get: funct
 Object.defineProperty(exports, "bindFrameActions", { enumerable: true, get: function () { return locator_binding_1.bindFrameActions; } });
 Object.defineProperty(exports, "bindLocatorActions", { enumerable: true, get: function () { return locator_binding_1.bindLocatorActions; } });
 Object.defineProperty(exports, "bindTargetActions", { enumerable: true, get: function () { return locator_binding_1.bindTargetActions; } });
+Object.defineProperty(exports, "bindContext", { enumerable: true, get: function () { return locator_binding_1.bindContext; } });
 var healer_1 = require("./healer");
 Object.defineProperty(exports, "healActionFailure", { enumerable: true, get: function () { return healer_1.healActionFailure; } });
 Object.defineProperty(exports, "getHealingReports", { enumerable: true, get: function () { return healer_1.getHealingReports; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uCAA0C;AAAjC,gGAAA,IAAI,OAAA;AAAE,kGAAA,MAAM,OAAA;AAErB,8DAAsH;AAA7G,kHAAA,eAAe,OAAA;AAAE,mHAAA,gBAAgB,OAAA;AAAE,qHAAA,kBAAkB,OAAA;AAAE,oHAAA,iBAAiB,OAAA;AAEjF,mCAAgE;AAAvD,2GAAA,iBAAiB,OAAA;AAAE,2GAAA,iBAAiB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uCAA0C;AAAjC,gGAAA,IAAI,OAAA;AAAE,kGAAA,MAAM,OAAA;AAErB,8DAAmI;AAA1H,kHAAA,eAAe,OAAA;AAAE,mHAAA,gBAAgB,OAAA;AAAE,qHAAA,kBAAkB,OAAA;AAAE,oHAAA,iBAAiB,OAAA;AAAE,8GAAA,WAAW,OAAA;AAE9F,mCAAgE;AAAvD,2GAAA,iBAAiB,OAAA;AAAE,2GAAA,iBAAiB,OAAA"}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "tamash-playwright",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Plug and Play Self-healing for Playwright and automatically recovers broken selectors using an AI model (Ollama, OpenAI, Anthropic, or Gemini).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "tamash-playwright": "dist/cli/index.js"
+  },
   "files": [
     "dist",
     "README.md",