@stablyai/playwright-base 0.1.10 → 0.2.1

package/dist/index.cjs

@@ -41,6 +41,9 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/expect.ts
+var import_internal_playwright_test = require("@stablyai/internal-playwright-test");
+
 // src/runtime.ts
 var configuredApiKey = process.env.STABLY_API_KEY;
 function setApiKey(apiKey) {
@@ -67,108 +70,65 @@ var isObject = (value) => {
 // src/ai/metadata.ts
 var SDK_METADATA_HEADERS = {
   "X-Client-Name": "stably-playwright-sdk-js",
-  "X-Client-Version": "0.1.10"
+  "X-Client-Version": "0.2.1"
 };
 
-// src/ai/extract.ts
-var EXTRACT_ENDPOINT = "https://api.stably.ai/internal/v2/extract";
-var zodV4 = (() => {
-  try {
-    return require("zod/v4/core");
-  } catch {
-    return void 0;
-  }
-})();
-var isExtractionResponse = (value) => {
+// src/ai/verify-prompt.ts
+var PROMPT_ASSERTION_ENDPOINT = "https://api.stably.ai/internal/v1/assert";
+var parseSuccessResponse = (value) => {
   if (!isObject(value)) {
-    return false;
+    throw new Error("Verify prompt returned unexpected response shape");
   }
-  if (value.success === true) {
-    return "value" in value;
+  const { reason, success } = value;
+  if (typeof success !== "boolean") {
+    throw new Error("Verify prompt returned unexpected response shape");
   }
-  return value.success === false && typeof value.error === "string";
-};
-var isErrorResponse = (value) => {
-  return isObject(value) && typeof value.error === "string";
-};
-var ExtractValidationError = class extends Error {
-  constructor(message, issues) {
-    super(message);
-    this.issues = issues;
-    this.name = "ExtractValidationError";
+  if (reason !== void 0 && typeof reason !== "string") {
+    throw new Error("Verify prompt returned unexpected response shape");
   }
+  return {
+    reason,
+    success
+  };
 };
-async function validateWithSchema(schema, value) {
-  const result = await schema.safeParseAsync(value);
-  if (!result.success) {
-    throw new ExtractValidationError("Validation failed", result.error.issues);
+var parseErrorResponse = (value) => {
+  if (!isObject(value)) {
+    return void 0;
   }
-  return result.data;
-}
-async function extract({
+  const { error } = value;
+  return typeof error !== "string" ? void 0 : { error };
+};
+async function verifyPrompt({
   prompt,
-  pageOrLocator,
-  schema
+  screenshot
 }) {
-  if (schema && !zodV4) {
-    throw new Error(
-      "Schema support requires installing zod@4. Please add it to enable schemas."
-    );
-  }
-  const jsonSchema = schema && zodV4 ? zodV4?.toJSONSchema(
-    schema
-  ) : void 0;
   const apiKey = requireApiKey();
   const form = new FormData();
   form.append("prompt", prompt);
-  if (jsonSchema) {
-    form.append("jsonSchema", JSON.stringify(jsonSchema));
-  }
-  const pngBuffer = await pageOrLocator.screenshot({ type: "png" });
-  const u8 = Uint8Array.from(pngBuffer);
+  const u8 = Uint8Array.from(screenshot);
   const blob = new Blob([u8], { type: "image/png" });
   form.append("image", blob, "screenshot.png");
-  const response = await fetch(EXTRACT_ENDPOINT, {
-    method: "POST",
+  const response = await fetch(PROMPT_ASSERTION_ENDPOINT, {
+    body: form,
     headers: {
       ...SDK_METADATA_HEADERS,
       Authorization: `Bearer ${apiKey}`
     },
-    body: form
+    method: "POST"
   });
-  const raw = await response.json().catch(() => void 0);
+  const parsed = await response.json().catch(() => void 0);
   if (response.ok) {
-    if (!isExtractionResponse(raw)) {
-      throw new Error("Extract returned unexpected response shape");
-    }
-    if (raw.success === false) {
-      return raw.error;
-    }
-    const { value } = raw;
-    return schema ? await validateWithSchema(schema, value) : typeof value === "string" ? value : JSON.stringify(value);
+    const { reason, success } = parseSuccessResponse(parsed);
+    return {
+      pass: success,
+      reason
+    };
   }
-  throw new Error(isErrorResponse(raw) ? raw.error : "Extract failed");
-}
-
-// src/playwright-augment/methods/extract.ts
-function createExtract(pageOrLocator) {
-  const impl = async (prompt, options) => {
-    if (options?.schema) {
-      return extract({
-        prompt,
-        schema: options.schema,
-        pageOrLocator
-      });
-    }
-    return extract({ prompt, pageOrLocator });
-  };
-  return impl;
+  const err = parseErrorResponse(parsed);
+  throw new Error(
+    `Verify prompt failed (${response.status})${err ? `: ${err.error}` : ""}`
+  );
 }
-var createLocatorExtract = (locator) => createExtract(locator);
-var createPageExtract = (page) => createExtract(page);
-
-// src/playwright-augment/methods/agent.ts
-var import_internal_playwright_test = require("@stablyai/internal-playwright-test");
 
 // src/playwright-type-predicates.ts
 function isPage(candidate) {
@@ -178,6 +138,9 @@ function isLocator(candidate) {
   return typeof candidate === "object" && candidate !== null && typeof candidate.screenshot === "function" && typeof candidate.nth === "function";
 }
 
+// src/image-compare.ts
+var jpeg = __toESM(require("jpeg-js"));
+
 // ../../node_modules/.pnpm/pixelmatch@7.1.0/node_modules/pixelmatch/index.js
 function pixelmatch(img1, img2, output, width, height, options = {}) {
   const {
@@ -336,7 +299,6 @@ function drawGrayPixel(img, i, alpha, output) {
 
 // src/image-compare.ts
 var import_pngjs = require("pngjs");
-var jpeg = __toESM(require("jpeg-js"));
 var isPng = (buffer) => {
   return buffer.length >= 8 && buffer[0] === 137 && buffer[1] === 80 && buffer[2] === 78 && buffer[3] === 71 && buffer[4] === 13 && buffer[5] === 10 && buffer[6] === 26 && buffer[7] === 10;
 };
@@ -346,14 +308,14 @@ var isJpeg = (buffer) => {
 var decodeImage = (buffer) => {
   if (isPng(buffer)) {
     const png2 = import_pngjs.PNG.sync.read(buffer);
-    return { data: png2.data, width: png2.width, height: png2.height };
+    return { data: png2.data, height: png2.height, width: png2.width };
   }
   if (isJpeg(buffer)) {
     const img = jpeg.decode(buffer, { maxMemoryUsageInMB: 1024 });
-    return { data: img.data, width: img.width, height: img.height };
+    return { data: img.data, height: img.height, width: img.width };
   }
   const png = import_pngjs.PNG.sync.read(buffer);
-  return { data: png.data, width: png.width, height: png.height };
+  return { data: png.data, height: png.height, width: png.width };
 };
 var imagesAreSimilar = ({
   image1,
@@ -405,7 +367,9 @@ async function takeStableScreenshot(target, options) {
     return await target.screenshot(options);
   };
   while (true) {
-    if (Date.now() >= deadline) break;
+    if (Date.now() >= deadline) {
+      break;
+    }
     const delay = pollIntervals.length ? pollIntervals.shift() : 1e3;
     if (delay) {
       await page.waitForTimeout(delay);
@@ -424,49 +388,279 @@ async function takeStableScreenshot(target, options) {
   return actual ?? await safeScreenshot();
 }
 
+// src/expect.ts
+function createFailureMessage({
+  condition,
+  didPass,
+  isNot,
+  reason,
+  targetType
+}) {
+  const expectation = isNot ? "not to satisfy" : "to satisfy";
+  const result = didPass ? "it did" : "it did not";
+  let message = `Expected ${targetType} ${expectation} ${JSON.stringify(condition)}, but ${result}.`;
+  if (reason) {
+    message += `
+
+Reason: ${reason}`;
+  }
+  return message;
+}
+var stablyPlaywrightMatchers = {
+  async toMatchScreenshotPrompt(received, condition, options) {
+    const target = isPage(received) ? received : isLocator(received) ? received : void 0;
+    if (!target) {
+      throw new Error(
+        "toMatchScreenshotPrompt only supports Playwright Page and Locator instances."
+      );
+    }
+    const targetType = isPage(target) ? "page" : "locator";
+    const screenshot = await takeStableScreenshot(target, options);
+    const verifyResult = await verifyPrompt({ prompt: condition, screenshot });
+    const testInfo = import_internal_playwright_test.test.info();
+    testInfo.attachments.push({
+      body: Buffer.from(
+        JSON.stringify(
+          {
+            pass: verifyResult.pass,
+            prompt: condition,
+            reasoning: verifyResult.reason
+          },
+          null,
+          2
+        ),
+        "utf-8"
+      ),
+      contentType: "application/json",
+      name: "toMatchScreenshotPrompt-reasoning"
+    });
+    return {
+      message: () => createFailureMessage({
+        condition,
+        didPass: verifyResult.pass,
+        isNot: this.isNot,
+        reason: verifyResult.reason,
+        targetType
+      }),
+      name: "toMatchScreenshotPrompt",
+      pass: verifyResult.pass
+    };
+  }
+};
+
+// src/playwright-augment/methods/agent.ts
+var import_internal_playwright_test2 = require("@stablyai/internal-playwright-test");
+
+// src/utils/truncate.ts
+var truncate = (inp, length) => inp.length <= length || inp.length <= 3 ? inp : `${inp.slice(0, length - 3)}...`;
+
 // src/playwright-augment/methods/agent/construct-payload.ts
 function constructAgentPayload({
-  sessionId,
-  message,
+  activePage,
+  additionalContext,
   isError,
+  message,
+  model,
   screenshot,
-  tabManager,
-  activePage,
-  additionalContext
+  sessionId,
+  tabManager
 }) {
   const form = new FormData();
-  form.append("session_id", sessionId);
-  form.append("message", message);
+  const viewportSize = activePage.viewportSize();
+  const tabs = Array.from(tabManager.entries()).map(([page, alias]) => ({
+    alias,
+    url: page.url()
+  }));
+  const activePageAlias = tabManager.get(activePage);
+  const metadata = {
+    allPages: tabs,
+    message,
+    sessionId
+  };
+  if (model) {
+    metadata.model = model;
+  }
   if (isError) {
-    form.append("is_error", JSON.stringify(isError));
+    metadata.isError = isError;
   }
   if (additionalContext) {
-    form.append("additional_context", JSON.stringify(additionalContext));
+    metadata.additionalContext = additionalContext;
   }
-  const viewportSize = activePage.viewportSize();
   if (viewportSize) {
-    form.append("page_dimensions", JSON.stringify(viewportSize));
+    metadata.pageDimensions = viewportSize;
   }
+  if (activePageAlias) {
+    metadata.activePageAlias = activePageAlias;
+  }
+  const metadataBlob = new Blob([JSON.stringify(metadata)], {
+    type: "application/json"
+  });
+  form.append("metadata", metadataBlob, "metadata.json");
   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/exec-response.ts
+var DEFAULT_AGENT_WAIT_MS = 3e3;
+async function execResponse({
+  activePage: initialActivePage,
+  agentResponse,
+  browserContext,
+  tabManager
+}) {
+  let activePage = initialActivePage;
+  try {
+    switch (agentResponse.action) {
+      case "key": {
+        const { text } = agentResponse;
+        if (text) {
+          await activePage.keyboard.press(text);
+          return { activePage, result: { message: `pressed "${text}"` } };
+        }
+        return { activePage, result: { message: "pressed key" } };
+      }
+      case "type": {
+        const { text } = agentResponse;
+        await activePage.keyboard.type(text);
+        return { activePage, result: { message: `typed "${text}"` } };
+      }
+      case "mouse_move": {
+        const [x, y] = agentResponse.coordinate;
+        await activePage.mouse.move(x, y);
+        return { activePage, result: { message: `mouse moved completed` } };
+      }
+      case "left_click": {
+        const [x, y] = agentResponse.coordinate;
+        await activePage.mouse.click(x, y);
+        return { activePage, result: { message: `left click completed` } };
+      }
+      case "right_click": {
+        const [x, y] = agentResponse.coordinate;
+        await activePage.mouse.click(x, y, { button: "right" });
+        return { activePage, result: { message: `right click completed` } };
+      }
+      case "double_click": {
+        const [x, y] = agentResponse.coordinate;
+        await activePage.mouse.dblclick(x, y);
+        return { activePage, result: { message: `double click completed` } };
+      }
+      case "triple_click": {
+        const [x, y] = agentResponse.coordinate;
+        await activePage.mouse.click(x, y, { clickCount: 3 });
+        return { activePage, result: { message: `triple click completed` } };
+      }
+      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 { activePage, result: { message: `drag completed` } };
+      }
+      case "screenshot": {
+        await takeStableScreenshot(activePage);
+        return { activePage, result: { message: "captured screenshot" } };
+      }
+      case "wait": {
+        const waitMs = agentResponse.milliseconds ?? DEFAULT_AGENT_WAIT_MS;
+        await activePage.waitForTimeout(waitMs);
+        return { activePage, result: { message: `waited ${waitMs}ms` } };
+      }
+      case "navigate_to_url": {
+        await activePage.goto(agentResponse.url);
+        return {
+          activePage,
+          result: { message: `navigated to "${agentResponse.url}"` }
+        };
+      }
+      case "new_tab_url": {
+        const newPage = await browserContext.newPage();
+        await newPage.goto(agentResponse.url);
+        await newPage.waitForLoadState("domcontentloaded");
+        activePage = newPage;
+        return { activePage, result: { 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 {
+          activePage,
+          result: { 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 {
+          activePage,
+          result: { 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 { activePage, result: { message: "navigated back" } };
+      }
+      case "aria_snapshot": {
+        const ariaSnapshot = await activePage._snapshotForAI();
+        return {
+          activePage,
+          result: { message: `ARIA Snapshot:
+${ariaSnapshot}` }
+        };
+      }
+      case "terminate_test": {
+        const { reason, success } = agentResponse;
+        return {
+          activePage,
+          finalSuccess: success,
+          result: { message: reason, shouldTerminate: true }
+        };
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { activePage, result: { isError: true, message } };
+  }
+}
+
 // src/playwright-augment/methods/agent.ts
-var AGENT_PATH = "internal/v1/agent";
+var AGENT_PATH = "internal/v3/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() {
+  let thoughtsIndex = 0;
   return async (prompt, options) => {
     const apiKey = requireApiKey();
     const maxCycles = options.maxCycles ?? 30;
@@ -477,8 +671,8 @@ function createAgentStub() {
     });
     let activePage = options.page;
     let agentMessage = {
-      message: prompt,
       isError: false,
+      message: prompt,
       shouldTerminate: false
     };
     let finalSuccess;
@@ -496,165 +690,81 @@ function createAgentStub() {
       newPageOpenedMsg = `opened new tab ${alias} (${page.url()})`;
     };
     browserContext.on("page", onNewPage);
-    return await import_internal_playwright_test.test.step(prompt, async () => {
+    return await import_internal_playwright_test2.test.step(`[Agent] ${prompt}`, async () => {
       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 };
-                }
+          const agentResponses = await import_internal_playwright_test2.test.step(`[Thinking ${thoughtsIndex + 1}]`, async (stepInfo) => {
+            const screenshot = await takeStableScreenshot(activePage);
+            const response = await fetch(AGENT_ENDPOINT, {
+              body: constructAgentPayload({
+                activePage,
+                additionalContext: newPageOpenedMsg ? { newPageMessage: newPageOpenedMsg } : void 0,
+                isError: agentMessage.isError,
+                message: agentMessage.message,
+                model: options.model,
+                screenshot,
+                sessionId,
+                tabManager
+              }),
+              headers: {
+                ...SDK_METADATA_HEADERS,
+                Authorization: `Bearer ${apiKey}`
+              },
+              method: "POST"
+            });
+            newPageOpenedMsg = void 0;
+            const responseJson = await response.json();
+            if (!response.ok) {
+              throw new Error(
+                `Agent call failed: ${JSON.stringify(responseJson)}`
+              );
+            }
+            const reasoningTexts = responseJson.map((r) => r.content).filter((content) => content !== void 0);
+            const reasoningText = reasoningTexts.join("\n\n");
+            const truncatedReasoningText = truncate(reasoningText, 120);
+            await stepInfo.attach(
+              `[Thinking ${thoughtsIndex + 1}] ${truncatedReasoningText}`,
+              {
+                body: reasoningText,
+                contentType: "text/plain"
               }
-            } catch (error) {
-              const message = error instanceof Error ? error.message : String(error);
-              return { message, isError: true };
+            );
+            thoughtsIndex++;
+            return responseJson;
+          });
+          let combinedMessages = [];
+          let aggregatedIsError = false;
+          let aggregatedShouldTerminate = false;
+          for (const agentResponse of agentResponses) {
+            const {
+              activePage: newActivePage,
+              finalSuccess: maybeFinal,
+              result
+            } = await execResponse({
+              activePage,
+              agentResponse,
+              browserContext,
+              tabManager
+            });
+            activePage = newActivePage;
+            combinedMessages.push(result.message);
+            finalSuccess = maybeFinal ?? finalSuccess;
+            if (result.isError) {
+              aggregatedIsError = true;
+            }
+            if (result.shouldTerminate) {
+              aggregatedShouldTerminate = true;
+              break;
             }
-          })();
+          }
+          agentMessage = {
+            isError: aggregatedIsError,
+            message: combinedMessages.join("\n"),
+            shouldTerminate: aggregatedShouldTerminate
+          };
         }
       } finally {
         browserContext.off("page", onNewPage);
@@ -664,6 +774,106 @@ function createAgentStub() {
   };
 }
 
+// src/ai/extract.ts
+var EXTRACT_PATH = "internal/v2/extract";
+var STABLY_API_URL2 = process.env.STABLY_API_URL || "https://api.stably.ai";
+var EXTRACT_ENDPOINT = new URL(EXTRACT_PATH, STABLY_API_URL2).toString();
+var zodV4 = (() => {
+  try {
+    return require("zod/v4/core");
+  } catch {
+    return void 0;
+  }
+})();
+var isExtractionResponse = (value) => {
+  if (!isObject(value)) {
+    return false;
+  }
+  if (value.success === true) {
+    return "value" in value;
+  }
+  return value.success === false && typeof value.error === "string";
+};
+var isErrorResponse = (value) => {
+  return isObject(value) && typeof value.error === "string";
+};
+var ExtractValidationError = class extends Error {
+  constructor(message, issues) {
+    super(message);
+    this.issues = issues;
+    this.name = "ExtractValidationError";
+  }
+};
+async function validateWithSchema(schema, value) {
+  const result = await schema.safeParseAsync(value);
+  if (!result.success) {
+    throw new ExtractValidationError("Validation failed", result.error.issues);
+  }
+  return result.data;
+}
+async function extract({
+  pageOrLocator,
+  prompt,
+  schema
+}) {
+  if (schema && !zodV4) {
+    throw new Error(
+      "Schema support requires installing zod@4. Please add it to enable schemas."
+    );
+  }
+  const jsonSchema = schema && zodV4 ? zodV4?.toJSONSchema(
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    schema
+  ) : void 0;
+  const apiKey = requireApiKey();
+  const form = new FormData();
+  form.append("prompt", prompt);
+  if (jsonSchema) {
+    form.append("jsonSchema", JSON.stringify(jsonSchema));
+  }
+  const pngBuffer = await pageOrLocator.screenshot({ type: "png" });
+  const u8 = Uint8Array.from(pngBuffer);
+  const blob = new Blob([u8], { type: "image/png" });
+  form.append("image", blob, "screenshot.png");
+  const response = await fetch(EXTRACT_ENDPOINT, {
+    body: form,
+    headers: {
+      ...SDK_METADATA_HEADERS,
+      Authorization: `Bearer ${apiKey}`
+    },
+    method: "POST"
+  });
+  const raw = await response.json().catch(() => void 0);
+  if (response.ok) {
+    if (!isExtractionResponse(raw)) {
+      throw new Error("Extract returned unexpected response shape");
+    }
+    if (!raw.success) {
+      throw new Error(`Extract failed: ${raw.error}`);
+    }
+    const { value } = raw;
+    return schema ? await validateWithSchema(schema, value) : typeof value === "string" ? value : JSON.stringify(value);
+  }
+  throw new Error(isErrorResponse(raw) ? raw.error : "Extract failed");
+}
+
+// src/playwright-augment/methods/extract.ts
+function createExtract(pageOrLocator) {
+  const impl = async (prompt, options) => {
+    if (options?.schema) {
+      return extract({
+        pageOrLocator,
+        prompt,
+        schema: options.schema
+      });
+    }
+    return extract({ pageOrLocator, prompt });
+  };
+  return impl;
+}
+var createLocatorExtract = (locator) => createExtract(locator);
+var createPageExtract = (page) => createExtract(page);
+
 // src/playwright-augment/augment.ts
 var LOCATOR_PATCHED = Symbol.for("stably.playwright.locatorPatched");
 var LOCATOR_DESCRIBE_WRAPPED = Symbol.for(
@@ -675,9 +885,9 @@ 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,
+    enumerable: false,
+    value,
     writable: true
   });
 }
@@ -724,6 +934,7 @@ function augmentBrowserContext(context) {
   if (originalPages) {
     context.pages = () => originalPages().map(
       (page) => augmentPage(page)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
     );
   }
   if (!context.agent) {
@@ -749,6 +960,7 @@ function augmentBrowser(browser) {
   const originalContexts = browser.contexts.bind(browser);
   browser.contexts = () => originalContexts().map(
     (context) => augmentBrowserContext(context)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
   );
   if (!browser.agent) {
     defineHiddenProperty(browser, "agent", createAgentStub());
@@ -772,14 +984,19 @@ function augmentBrowserType(browserType) {
       return augmentBrowser(browser);
     };
   }
-  const originalConnectOverCDP = browserType.connectOverCDP?.bind(browserType);
+  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);
+  const originalLaunchPersistentContext = (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    browserType.launchPersistentContext?.bind(browserType)
+  );
   if (originalLaunchPersistentContext) {
     browserType.launchPersistentContext = async (...args) => {
       const context = await originalLaunchPersistentContext(...args);
@@ -789,105 +1006,6 @@ function augmentBrowserType(browserType) {
   defineHiddenProperty(browserType, BROWSER_TYPE_PATCHED, true);
   return browserType;
 }
-
-// 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.ts
-function createFailureMessage({
-  targetType,
-  condition,
-  didPass,
-  isNot,
-  reason
-}) {
-  const expectation = isNot ? "not to satisfy" : "to satisfy";
-  const result = didPass ? "it did" : "it did not";
-  let message = `Expected ${targetType} ${expectation} ${JSON.stringify(condition)}, but ${result}.`;
-  if (reason) {
-    message += `
-
-Reason: ${reason}`;
-  }
-  return message;
-}
-var stablyPlaywrightMatchers = {
-  async toMatchScreenshotPrompt(received, condition, options) {
-    const target = isPage(received) ? received : isLocator(received) ? received : void 0;
-    if (!target) {
-      throw new Error(
-        "toMatchScreenshotPrompt only supports Playwright Page and Locator instances."
-      );
-    }
-    const targetType = isPage(target) ? "page" : "locator";
-    const screenshot = await takeStableScreenshot(target, options);
-    const verifyResult = await verifyPrompt({ prompt: condition, screenshot });
-    return {
-      pass: verifyResult.pass,
-      message: () => createFailureMessage({
-        targetType,
-        condition,
-        didPass: verifyResult.pass,
-        reason: verifyResult.reason,
-        isNot: this.isNot
-      })
-    };
-  }
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   augmentBrowser,