@stablyai/playwright-base 0.1.7 → 0.1.8-next.2

package/dist/index.cjs

@@ -67,7 +67,7 @@ var isObject = (value) => {
 // src/ai/metadata.ts
 var SDK_METADATA_HEADERS = {
   "X-Client-Name": "stably-playwright-sdk-js",
-  "X-Client-Version": "0.1.7"
+  "X-Client-Version": "0.1.8-next.2"
 };
 
 // src/ai/extract.ts
@@ -167,143 +167,6 @@ function createExtract(pageOrLocator) {
 var createLocatorExtract = (locator) => createExtract(locator);
 var createPageExtract = (page) => createExtract(page);
 
-// src/playwright-augment/methods/agent.ts
-function createAgentStub() {
-  return async (prompt, options) => {
-    requireApiKey();
-    void prompt;
-    void options;
-    return { success: true };
-  };
-}
-
-// src/playwright-augment/augment.ts
-var LOCATOR_PATCHED = Symbol.for("stably.playwright.locatorPatched");
-var LOCATOR_DESCRIBE_WRAPPED = Symbol.for(
-  "stably.playwright.locatorDescribeWrapped"
-);
-var PAGE_PATCHED = Symbol.for("stably.playwright.pagePatched");
-var CONTEXT_PATCHED = Symbol.for("stably.playwright.contextPatched");
-var BROWSER_PATCHED = Symbol.for("stably.playwright.browserPatched");
-var BROWSER_TYPE_PATCHED = Symbol.for("stably.playwright.browserTypePatched");
-function defineHiddenProperty(target, key, value) {
-  Object.defineProperty(target, key, {
-    value,
-    enumerable: false,
-    configurable: true,
-    writable: true
-  });
-}
-function augmentLocator(locator) {
-  if (locator[LOCATOR_PATCHED]) {
-    return locator;
-  }
-  defineHiddenProperty(locator, "extract", createLocatorExtract(locator));
-  const markerTarget = locator;
-  if (typeof locator.describe === "function" && !markerTarget[LOCATOR_DESCRIBE_WRAPPED]) {
-    const originalDescribe = locator.describe.bind(locator);
-    locator.describe = (description, options) => {
-      void options;
-      const result = originalDescribe(description);
-      return result ? augmentLocator(result) : result;
-    };
-    defineHiddenProperty(locator, LOCATOR_DESCRIBE_WRAPPED, true);
-  }
-  defineHiddenProperty(locator, LOCATOR_PATCHED, true);
-  return locator;
-}
-function augmentPage(page) {
-  if (page[PAGE_PATCHED]) {
-    return page;
-  }
-  const originalLocator = page.locator.bind(page);
-  page.locator = (...args) => {
-    const locator = originalLocator(...args);
-    return augmentLocator(locator);
-  };
-  defineHiddenProperty(page, "extract", createPageExtract(page));
-  defineHiddenProperty(page, PAGE_PATCHED, true);
-  return page;
-}
-function augmentBrowserContext(context) {
-  if (context[CONTEXT_PATCHED]) {
-    return context;
-  }
-  const originalNewPage = context.newPage.bind(context);
-  context.newPage = async (...args) => {
-    const page = await originalNewPage(...args);
-    return augmentPage(page);
-  };
-  const originalPages = context.pages?.bind(context);
-  if (originalPages) {
-    context.pages = () => originalPages().map(
-      (page) => augmentPage(page)
-    );
-  }
-  if (!context.agent) {
-    defineHiddenProperty(context, "agent", createAgentStub());
-  }
-  defineHiddenProperty(context, CONTEXT_PATCHED, true);
-  return context;
-}
-function augmentBrowser(browser) {
-  if (browser[BROWSER_PATCHED]) {
-    return browser;
-  }
-  const originalNewContext = browser.newContext.bind(browser);
-  browser.newContext = async (...args) => {
-    const context = await originalNewContext(...args);
-    return augmentBrowserContext(context);
-  };
-  const originalNewPage = browser.newPage.bind(browser);
-  browser.newPage = async (...args) => {
-    const page = await originalNewPage(...args);
-    return augmentPage(page);
-  };
-  const originalContexts = browser.contexts.bind(browser);
-  browser.contexts = () => originalContexts().map(
-    (context) => augmentBrowserContext(context)
-  );
-  if (!browser.agent) {
-    defineHiddenProperty(browser, "agent", createAgentStub());
-  }
-  defineHiddenProperty(browser, BROWSER_PATCHED, true);
-  return browser;
-}
-function augmentBrowserType(browserType) {
-  if (browserType[BROWSER_TYPE_PATCHED]) {
-    return browserType;
-  }
-  const originalLaunch = browserType.launch.bind(browserType);
-  browserType.launch = async (...args) => {
-    const browser = await originalLaunch(...args);
-    return augmentBrowser(browser);
-  };
-  const originalConnect = browserType.connect?.bind(browserType);
-  if (originalConnect) {
-    browserType.connect = async (...args) => {
-      const browser = await originalConnect(...args);
-      return augmentBrowser(browser);
-    };
-  }
-  const originalConnectOverCDP = browserType.connectOverCDP?.bind(browserType);
-  if (originalConnectOverCDP) {
-    browserType.connectOverCDP = async (...args) => {
-      const browser = await originalConnectOverCDP(...args);
-      return augmentBrowser(browser);
-    };
-  }
-  const originalLaunchPersistentContext = browserType.launchPersistentContext?.bind(browserType);
-  if (originalLaunchPersistentContext) {
-    browserType.launchPersistentContext = async (...args) => {
-      const context = await originalLaunchPersistentContext(...args);
-      return augmentBrowserContext(context);
-    };
-  }
-  defineHiddenProperty(browserType, BROWSER_TYPE_PATCHED, true);
-  return browserType;
-}
-
 // src/playwright-type-predicates.ts
 function isPage(candidate) {
   return typeof candidate === "object" && candidate !== null && typeof candidate.screenshot === "function" && typeof candidate.goto === "function";
@@ -312,63 +175,6 @@ function isLocator(candidate) {
   return typeof candidate === "object" && candidate !== null && typeof candidate.screenshot === "function" && typeof candidate.nth === "function";
 }
 
-// src/ai/verify-prompt.ts
-var PROMPT_ASSERTION_ENDPOINT = "https://api.stably.ai/internal/v1/assert";
-var parseSuccessResponse = (value) => {
-  if (!isObject(value)) {
-    throw new Error("Verify prompt returned unexpected response shape");
-  }
-  const { success, reason } = value;
-  if (typeof success !== "boolean") {
-    throw new Error("Verify prompt returned unexpected response shape");
-  }
-  if (reason !== void 0 && typeof reason !== "string") {
-    throw new Error("Verify prompt returned unexpected response shape");
-  }
-  return {
-    success,
-    reason
-  };
-};
-var parseErrorResponse = (value) => {
-  if (!isObject(value)) {
-    return void 0;
-  }
-  const { error } = value;
-  return typeof error !== "string" ? void 0 : { error };
-};
-async function verifyPrompt({
-  prompt,
-  screenshot
-}) {
-  const apiKey = requireApiKey();
-  const form = new FormData();
-  form.append("prompt", prompt);
-  const u8 = Uint8Array.from(screenshot);
-  const blob = new Blob([u8], { type: "image/png" });
-  form.append("image", blob, "screenshot.png");
-  const response = await fetch(PROMPT_ASSERTION_ENDPOINT, {
-    method: "POST",
-    headers: {
-      ...SDK_METADATA_HEADERS,
-      Authorization: `Bearer ${apiKey}`
-    },
-    body: form
-  });
-  const parsed = await response.json().catch(() => void 0);
-  if (response.ok) {
-    const { success, reason } = parseSuccessResponse(parsed);
-    return {
-      pass: success,
-      reason
-    };
-  }
-  const err = parseErrorResponse(parsed);
-  throw new Error(
-    `Verify prompt failed (${response.status})${err ? `: ${err.error}` : ""}`
-  );
-}
-
 // ../../node_modules/.pnpm/pixelmatch@7.1.0/node_modules/pixelmatch/index.js
 function pixelmatch(img1, img2, output, width, height, options = {}) {
   const {
@@ -584,6 +390,17 @@ async function takeStableScreenshot(target, options) {
   let previous;
   const pollIntervals = [0, 100, 250, 500];
   let isFirstIteration = true;
+  const safeScreenshot = async () => {
+    for (let i = 0; i < 3; i++) {
+      try {
+        return await target.screenshot(options);
+      } catch {
+        await page.waitForTimeout(250);
+        continue;
+      }
+    }
+    return await target.screenshot(options);
+  };
   while (true) {
     if (Date.now() >= deadline) break;
     const delay = pollIntervals.length ? pollIntervals.shift() : 1e3;
@@ -591,7 +408,7 @@ async function takeStableScreenshot(target, options) {
       await page.waitForTimeout(delay);
     }
     previous = actual;
-    actual = await target.screenshot(options);
+    actual = await safeScreenshot();
     if (!isFirstIteration && actual && previous && imagesAreSimilar({
       image1: previous,
       image2: actual,
@@ -601,11 +418,475 @@ async function takeStableScreenshot(target, options) {
     }
     isFirstIteration = false;
   }
-  return actual ?? await target.screenshot(options);
+  return actual ?? await safeScreenshot();
+}
+
+// src/playwright-augment/methods/agent/construct-payload.ts
+function constructAgentPayload({
+  sessionId,
+  message,
+  isError,
+  screenshot,
+  tabManager,
+  activePage,
+  additionalContext
+}) {
+  const form = new FormData();
+  form.append("session_id", sessionId);
+  form.append("message", message);
+  if (isError) {
+    form.append("is_error", JSON.stringify(isError));
+  }
+  if (additionalContext) {
+    form.append("additional_context", JSON.stringify(additionalContext));
+  }
+  const viewportSize = activePage.viewportSize();
+  if (viewportSize) {
+    form.append("page_dimensions", JSON.stringify(viewportSize));
+  }
+  const screenshotBytes = Uint8Array.from(screenshot);
+  const screenshotBlob = new Blob([screenshotBytes], { type: "image/png" });
+  form.append("screenshot", screenshotBlob, "screenshot.png");
+  const tabs = Array.from(tabManager.entries()).map(([page, alias]) => ({
+    alias,
+    url: page.url()
+  }));
+  form.append("all_pages", JSON.stringify(tabs));
+  const activePageAlias = tabManager.get(activePage);
+  if (activePageAlias) {
+    form.append("active_page_alias", activePageAlias);
+  }
+  return form;
+}
+
+// src/playwright-augment/methods/agent.ts
+var AGENT_PATH = "internal/v1/agent";
+var STABLY_API_URL = process.env.STABLY_API_URL || "https://api.stably.ai";
+var AGENT_ENDPOINT = new URL(AGENT_PATH, STABLY_API_URL).toString();
+function createAgentStub() {
+  return async (prompt, options) => {
+    const apiKey = requireApiKey();
+    const maxCycles = options.maxCycles ?? 30;
+    const browserContext = options.page.context();
+    const tabManager = /* @__PURE__ */ new Map();
+    browserContext.pages().forEach((page, index) => {
+      tabManager.set(page, `page${index + 1}`);
+    });
+    let activePage = options.page;
+    let agentMessage = {
+      message: prompt,
+      isError: false,
+      shouldTerminate: false
+    };
+    let finalSuccess;
+    let newPageOpenedMsg;
+    const sessionId = crypto.randomUUID();
+    const onNewPage = async (page) => {
+      await page.waitForLoadState("domcontentloaded");
+      if (!tabManager.has(page)) {
+        const alias2 = `page${tabManager.size + 1}`;
+        tabManager.set(page, alias2);
+      }
+      await page.bringToFront();
+      activePage = page;
+      const alias = tabManager.get(page);
+      newPageOpenedMsg = `opened new tab ${alias} (${page.url()})`;
+    };
+    browserContext.on("page", onNewPage);
+    try {
+      for (let i = 0; i < maxCycles; i++) {
+        if (agentMessage.shouldTerminate) {
+          break;
+        }
+        const screenshot = await takeStableScreenshot(activePage);
+        const response = await fetch(AGENT_ENDPOINT, {
+          method: "POST",
+          headers: {
+            ...SDK_METADATA_HEADERS,
+            Authorization: `Bearer ${apiKey}`
+          },
+          body: constructAgentPayload({
+            sessionId,
+            message: agentMessage.message,
+            isError: agentMessage.isError,
+            screenshot,
+            tabManager,
+            activePage,
+            additionalContext: newPageOpenedMsg ? { newPageMessage: newPageOpenedMsg } : void 0
+          })
+        });
+        newPageOpenedMsg = void 0;
+        const responseJson = await response.json();
+        if (!response.ok) {
+          throw new Error(`Agent call failed: ${JSON.stringify(responseJson)}`);
+        }
+        const agentResponse = responseJson;
+        agentMessage = await (async () => {
+          try {
+            switch (agentResponse.action) {
+              case "key": {
+                const { text } = agentResponse;
+                if (text) {
+                  await activePage.keyboard.press(text);
+                  return { message: `pressed "${text}"` };
+                }
+                return { message: "pressed key" };
+              }
+              case "type": {
+                const { text } = agentResponse;
+                await activePage.keyboard.type(text);
+                return { message: `typed "${text}"` };
+              }
+              case "mouse_move": {
+                const [x, y] = agentResponse.coordinate;
+                await activePage.mouse.move(x, y);
+                return { message: `mouse moved to [${x}, ${y}]` };
+              }
+              case "left_click": {
+                const [x, y] = agentResponse.coordinate;
+                await activePage.mouse.click(x, y);
+                return { message: `left click at [${x}, ${y}]` };
+              }
+              case "right_click": {
+                const [x, y] = agentResponse.coordinate;
+                await activePage.mouse.click(x, y, { button: "right" });
+                return { message: `right click at [${x}, ${y}]` };
+              }
+              case "double_click": {
+                const [x, y] = agentResponse.coordinate;
+                await activePage.mouse.dblclick(x, y);
+                return { message: `double click at [${x}, ${y}]` };
+              }
+              case "triple_click": {
+                const [x, y] = agentResponse.coordinate;
+                await activePage.mouse.click(x, y, { clickCount: 3 });
+                return { message: `triple click at [${x}, ${y}]` };
+              }
+              case "left_click_drag": {
+                const [startX, startY] = agentResponse.start_coordinate;
+                const [endX, endY] = agentResponse.coordinate;
+                await activePage.mouse.move(startX, startY);
+                await activePage.mouse.down();
+                await activePage.mouse.move(endX, endY);
+                await activePage.mouse.up();
+                return {
+                  message: `dragged from [${startX}, ${startY}] to [${endX}, ${endY}]`
+                };
+              }
+              case "screenshot": {
+                await takeStableScreenshot(activePage);
+                return { message: "captured screenshot" };
+              }
+              case "wait": {
+                const waitMs = agentResponse.milliseconds ?? 3e3;
+                await activePage.waitForTimeout(waitMs);
+                return { message: `waited ${waitMs}ms` };
+              }
+              case "navigate_to_url": {
+                await activePage.goto(agentResponse.url);
+                return { message: `navigated to "${agentResponse.url}"` };
+              }
+              case "new_tab_url": {
+                const newPage = await browserContext.newPage();
+                await newPage.goto(agentResponse.url);
+                await newPage.waitForLoadState("domcontentloaded");
+                return { message: "opened new tab" };
+              }
+              case "switch_tab": {
+                const entry = Array.from(tabManager.entries()).find(
+                  ([, alias]) => alias === agentResponse.tab_alias
+                );
+                const page = entry?.[0];
+                if (!page) {
+                  throw new Error(
+                    `Tab with alias ${agentResponse.tab_alias} not found`
+                  );
+                }
+                await page.bringToFront();
+                activePage = page;
+                return { message: `switched to "${agentResponse.tab_alias}"` };
+              }
+              case "scroll": {
+                const [x, y] = agentResponse.coordinate;
+                await activePage.mouse.move(x, y);
+                let deltaX = 0;
+                let deltaY = 0;
+                switch (agentResponse.scroll_direction) {
+                  case "up":
+                    deltaY = -agentResponse.scroll_amount;
+                    break;
+                  case "down":
+                    deltaY = agentResponse.scroll_amount;
+                    break;
+                  case "left":
+                    deltaX = -agentResponse.scroll_amount;
+                    break;
+                  case "right":
+                    deltaX = agentResponse.scroll_amount;
+                    break;
+                }
+                await activePage.mouse.wheel(deltaX, deltaY);
+                return {
+                  message: `scrolled ${agentResponse.scroll_direction}`
+                };
+              }
+              case "navigate_back": {
+                const res = await activePage.goBack();
+                if (!res)
+                  throw new Error("navigate_back failed: no history entry");
+                return { message: "navigated back" };
+              }
+              case "terminate_test": {
+                const { success, reason } = agentResponse;
+                finalSuccess = success;
+                return { message: reason, shouldTerminate: true };
+              }
+            }
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { message, isError: true };
+          }
+        })();
+      }
+    } finally {
+      browserContext.off("page", onNewPage);
+    }
+    return { success: finalSuccess ?? false };
+  };
+}
+
+// src/playwright-augment/augment.ts
+var LOCATOR_PATCHED = Symbol.for("stably.playwright.locatorPatched");
+var LOCATOR_DESCRIBE_WRAPPED = Symbol.for(
+  "stably.playwright.locatorDescribeWrapped"
+);
+var PAGE_PATCHED = Symbol.for("stably.playwright.pagePatched");
+var CONTEXT_PATCHED = Symbol.for("stably.playwright.contextPatched");
+var BROWSER_PATCHED = Symbol.for("stably.playwright.browserPatched");
+var BROWSER_TYPE_PATCHED = Symbol.for("stably.playwright.browserTypePatched");
+function defineHiddenProperty(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: false,
+    configurable: true,
+    writable: true
+  });
+}
+function augmentLocator(locator) {
+  if (locator[LOCATOR_PATCHED]) {
+    return locator;
+  }
+  defineHiddenProperty(locator, "extract", createLocatorExtract(locator));
+  const markerTarget = locator;
+  if (typeof locator.describe === "function" && !markerTarget[LOCATOR_DESCRIBE_WRAPPED]) {
+    const originalDescribe = locator.describe.bind(locator);
+    locator.describe = (description, options) => {
+      void options;
+      const result = originalDescribe(description);
+      return result ? augmentLocator(result) : result;
+    };
+    defineHiddenProperty(locator, LOCATOR_DESCRIBE_WRAPPED, true);
+  }
+  defineHiddenProperty(locator, LOCATOR_PATCHED, true);
+  return locator;
+}
+function augmentPage(page) {
+  if (page[PAGE_PATCHED]) {
+    return page;
+  }
+  const originalLocator = page.locator.bind(page);
+  page.locator = (...args) => {
+    const locator = originalLocator(...args);
+    return augmentLocator(locator);
+  };
+  defineHiddenProperty(page, "extract", createPageExtract(page));
+  defineHiddenProperty(page, PAGE_PATCHED, true);
+  return page;
+}
+function augmentBrowserContext(context) {
+  if (context[CONTEXT_PATCHED]) {
+    return context;
+  }
+  const originalNewPage = context.newPage.bind(context);
+  context.newPage = async (...args) => {
+    const page = await originalNewPage(...args);
+    return augmentPage(page);
+  };
+  const originalPages = context.pages?.bind(context);
+  if (originalPages) {
+    context.pages = () => originalPages().map(
+      (page) => augmentPage(page)
+    );
+  }
+  if (!context.agent) {
+    defineHiddenProperty(context, "agent", createAgentStub());
+  }
+  defineHiddenProperty(context, CONTEXT_PATCHED, true);
+  return context;
+}
+function augmentBrowser(browser) {
+  if (browser[BROWSER_PATCHED]) {
+    return browser;
+  }
+  const originalNewContext = browser.newContext.bind(browser);
+  browser.newContext = async (...args) => {
+    const context = await originalNewContext(...args);
+    return augmentBrowserContext(context);
+  };
+  const originalNewPage = browser.newPage.bind(browser);
+  browser.newPage = async (...args) => {
+    const page = await originalNewPage(...args);
+    return augmentPage(page);
+  };
+  const originalContexts = browser.contexts.bind(browser);
+  browser.contexts = () => originalContexts().map(
+    (context) => augmentBrowserContext(context)
+  );
+  if (!browser.agent) {
+    defineHiddenProperty(browser, "agent", createAgentStub());
+  }
+  defineHiddenProperty(browser, BROWSER_PATCHED, true);
+  return browser;
+}
+function augmentBrowserType(browserType) {
+  if (browserType[BROWSER_TYPE_PATCHED]) {
+    return browserType;
+  }
+  const originalLaunch = browserType.launch.bind(browserType);
+  browserType.launch = async (...args) => {
+    const browser = await originalLaunch(...args);
+    return augmentBrowser(browser);
+  };
+  const originalConnect = browserType.connect?.bind(browserType);
+  if (originalConnect) {
+    browserType.connect = async (...args) => {
+      const browser = await originalConnect(...args);
+      return augmentBrowser(browser);
+    };
+  }
+  const originalConnectOverCDP = browserType.connectOverCDP?.bind(browserType);
+  if (originalConnectOverCDP) {
+    browserType.connectOverCDP = async (...args) => {
+      const browser = await originalConnectOverCDP(...args);
+      return augmentBrowser(browser);
+    };
+  }
+  const originalLaunchPersistentContext = browserType.launchPersistentContext?.bind(browserType);
+  if (originalLaunchPersistentContext) {
+    browserType.launchPersistentContext = async (...args) => {
+      const context = await originalLaunchPersistentContext(...args);
+      return augmentBrowserContext(context);
+    };
+  }
+  defineHiddenProperty(browserType, BROWSER_TYPE_PATCHED, true);
+  return browserType;
 }
 
-// src/expect.ts
-function createFailureMessage({
+// src/ai/verify-prompt.ts
+var PROMPT_ASSERTION_ENDPOINT = "https://api.stably.ai/internal/v1/assert";
+var parseSuccessResponse = (value) => {
+  if (!isObject(value)) {
+    throw new Error("Verify prompt returned unexpected response shape");
+  }
+  const { success, reason } = value;
+  if (typeof success !== "boolean") {
+    throw new Error("Verify prompt returned unexpected response shape");
+  }
+  if (reason !== void 0 && typeof reason !== "string") {
+    throw new Error("Verify prompt returned unexpected response shape");
+  }
+  return {
+    success,
+    reason
+  };
+};
+var parseErrorResponse = (value) => {
+  if (!isObject(value)) {
+    return void 0;
+  }
+  const { error } = value;
+  return typeof error !== "string" ? void 0 : { error };
+};
+async function verifyPrompt({
+  prompt,
+  screenshot
+}) {
+  const apiKey = requireApiKey();
+  const form = new FormData();
+  form.append("prompt", prompt);
+  const u8 = Uint8Array.from(screenshot);
+  const blob = new Blob([u8], { type: "image/png" });
+  form.append("image", blob, "screenshot.png");
+  const response = await fetch(PROMPT_ASSERTION_ENDPOINT, {
+    method: "POST",
+    headers: {
+      ...SDK_METADATA_HEADERS,
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: form
+  });
+  const parsed = await response.json().catch(() => void 0);
+  if (response.ok) {
+    const { success, reason } = parseSuccessResponse(parsed);
+    return {
+      pass: success,
+      reason
+    };
+  }
+  const err = parseErrorResponse(parsed);
+  throw new Error(
+    `Verify prompt failed (${response.status})${err ? `: ${err.error}` : ""}`
+  );
+}
+
+// src/expect/snapshotCache.ts
+var import_path = __toESM(require("path"));
+var import_promises = require("fs/promises");
+var import_path2 = require("path");
+var import_fs = require("fs");
+var import_internal_playwright_test = require("@stablyai/internal-playwright-test");
+async function getCacheEntryPath(snapshotKey) {
+  const testDir = import_path.default.dirname(import_internal_playwright_test.test.info().file);
+  return import_path.default.join(testDir, snapshotKey);
+}
+async function tryUseCachedSnapshot({
+  currentSnapshot,
+  cachedSnapshotKey,
+  snapshotSimilarityThreshold
+}) {
+  const cacheEntryPath = await getCacheEntryPath(cachedSnapshotKey);
+  try {
+    await (0, import_promises.access)(cacheEntryPath, import_fs.constants.F_OK);
+  } catch {
+    return { success: false, usedCachedSnapshot: false };
+  }
+  const cacheEntry = await (0, import_promises.readFile)(cacheEntryPath);
+  return {
+    success: imagesAreSimilar({
+      image1: cacheEntry,
+      image2: currentSnapshot,
+      threshold: snapshotSimilarityThreshold
+    }),
+    usedCachedSnapshot: true
+  };
+}
+async function updateCachedSnapshot({
+  snapshotKey,
+  snapshot
+}) {
+  const cacheEntryPath = await getCacheEntryPath(snapshotKey);
+  try {
+    await (0, import_promises.mkdir)((0, import_path2.dirname)(cacheEntryPath), { recursive: true });
+    await (0, import_promises.writeFile)(cacheEntryPath, snapshot);
+  } catch (err) {
+    console.error("Error writing snapshot", err);
+    throw err;
+  }
+}
+
+// src/expect/expect.ts
+var DEFAULT_SNAPSHOT_SIMILARITY_THRESHOLD = 0.02;
+function createResultMessage({
   targetType,
   condition,
   didPass,
@@ -632,14 +913,38 @@ var stablyPlaywrightMatchers = {
     }
     const targetType = isPage(target) ? "page" : "locator";
     const screenshot = await takeStableScreenshot(target, options);
+    const useCachedSnapshotResult = options?.cache ? await tryUseCachedSnapshot({
+      currentSnapshot: screenshot,
+      cachedSnapshotKey: options.cache.snapshotKey,
+      snapshotSimilarityThreshold: options?.threshold ?? DEFAULT_SNAPSHOT_SIMILARITY_THRESHOLD
+    }) : void 0;
+    if (useCachedSnapshotResult?.success) {
+      return {
+        pass: true,
+        message: () => createResultMessage({
+          targetType,
+          condition,
+          didPass: true,
+          reason: "Used cached snapshot to verify condition",
+          isNot: this.isNot
+        })
+      };
+    }
     const verifyResult = await verifyPrompt({ prompt: condition, screenshot });
+    if (options?.cache && verifyResult.pass) {
+      await updateCachedSnapshot({
+        snapshotKey: options.cache.snapshotKey,
+        snapshot: screenshot
+      });
+    }
+    const snapshotUsageMessage = useCachedSnapshotResult ? `Attempted to use the cached snapshot to verify the condition, but ${useCachedSnapshotResult.usedCachedSnapshot ? "the snapshot did not match the current snapshot" : "no snapshot was found"}.` : void 0;
     return {
       pass: verifyResult.pass,
-      message: () => createFailureMessage({
+      message: () => createResultMessage({
         targetType,
         condition,
         didPass: verifyResult.pass,
-        reason: verifyResult.reason,
+        reason: snapshotUsageMessage ? `${snapshotUsageMessage} ${verifyResult.reason}` : verifyResult.reason,
         isNot: this.isNot
       })
     };