@stablyai/playwright-base 0.1.6 → 0.1.7-next.10

package/dist/index.d.mts

@@ -0,0 +1,112 @@
+import * as _stablyai_internal_playwright_test from '@stablyai/internal-playwright-test';
+import { Browser, BrowserContext, BrowserType, Locator, Page } from '@stablyai/internal-playwright-test';
+import * as z4 from 'zod/v4/core';
+
+interface LocatorDescribeOptions {
+    autoHeal?: boolean;
+}
+declare function augmentLocator<T extends Locator>(locator: T): T;
+declare function augmentPage<T extends Page>(page: T): T;
+declare function augmentBrowserContext<T extends BrowserContext>(context: T): T;
+declare function augmentBrowser<T extends Browser>(browser: T): T;
+declare function augmentBrowserType<TBrowser extends Browser>(browserType: BrowserType<TBrowser>): BrowserType<TBrowser>;
+
+interface ExtractSchema extends z4.$ZodType {
+    safeParseAsync(data: unknown, params?: z4.ParseContext<z4.$ZodIssue>): Promise<z4.util.SafeParseResult<z4.output<this>>>;
+}
+type SchemaOutput<T extends ExtractSchema> = z4.output<T>;
+
+type MatcherContext = {
+    isNot: boolean;
+    message?: () => string;
+};
+declare const stablyPlaywrightMatchers: {
+    readonly toMatchScreenshotPrompt: (this: MatcherContext, received: Page | Locator, condition: string, options?: ScreenshotPromptOptions) => Promise<{
+        pass: boolean;
+        message: () => string;
+    }>;
+};
+
+declare function setApiKey(apiKey: string): void;
+declare function requireApiKey(): string;
+
+type ScreenshotPromptOptions = _stablyai_internal_playwright_test.PageAssertionsToHaveScreenshotOptions;
+
+interface Expect<T = Page> {
+    toMatchScreenshotPrompt(condition: string, options?: ScreenshotPromptOptions): Promise<void>;
+}
+declare module "@stablyai/internal-playwright-test" {
+    interface Locator {
+        /**
+         * Extracts information from this locator using Stably AI.
+         *
+         * Takes a screenshot of the locator and uses AI to extract information based on the
+         * provided prompt. When a schema is provided, the extracted data is validated and
+         * typed according to the schema.
+         *
+         * @param prompt - A natural language description of what information to extract
+         * @returns A string containing the extracted information
+         */
+        extract(prompt: string): Promise<string>;
+        /**
+         * Extracts information from this locator using Stably AI.
+         *
+         * Takes a screenshot of the locator and uses AI to extract information based on the
+         * provided prompt. The extracted data is validated and typed according to the schema.
+         *
+         * @param prompt - A natural language description of what information to extract
+         * @param options - Configuration object containing the Zod schema for validation
+         * @param options.schema - Zod schema to validate and type the extracted data
+         * @returns Typed data matching the provided schema
+         */
+        extract<T extends ExtractSchema>(prompt: string, options: {
+            schema: T;
+        }): Promise<SchemaOutput<T>>;
+        describe(description: string, options?: LocatorDescribeOptions): Locator;
+    }
+    interface Page {
+        /**
+         * Extracts information from this page using Stably AI.
+         *
+         * Takes a screenshot of the page and uses AI to extract information based on the
+         * provided prompt. When a schema is provided, the extracted data is validated and
+         * typed according to the schema.
+         *
+         * @param prompt - A natural language description of what information to extract
+         * @returns A string containing the extracted information
+         */
+        extract(prompt: string): Promise<string>;
+        /**
+         * Extracts information from this page using Stably AI.
+         *
+         * Takes a screenshot of the page and uses AI to extract information based on the
+         * provided prompt. The extracted data is validated and typed according to the schema.
+         *
+         * @param prompt - A natural language description of what information to extract
+         * @param options - Configuration object containing the Zod schema for validation
+         * @param options.schema - Zod schema to validate and type the extracted data
+         * @returns Typed data matching the provided schema
+         */
+        extract<T extends ExtractSchema>(prompt: string, options: {
+            schema: T;
+        }): Promise<SchemaOutput<T>>;
+    }
+    interface BrowserContext {
+        agent(prompt: string, options: {
+            page: Page;
+            maxCycles?: number;
+        }): Promise<{
+            success: boolean;
+        }>;
+    }
+    interface Browser {
+        agent(prompt: string, options: {
+            page: Page;
+            maxCycles?: number;
+        }): Promise<{
+            success: boolean;
+        }>;
+    }
+}
+
+export { type Expect, type ExtractSchema, type LocatorDescribeOptions, type SchemaOutput, type ScreenshotPromptOptions, augmentBrowser, augmentBrowserContext, augmentBrowserType, augmentLocator, augmentPage, requireApiKey, setApiKey, stablyPlaywrightMatchers };

package/dist/index.d.ts

@@ -1,15 +1,38 @@
-import type { Page } from "@stablyai/internal-playwright-test";
-import type { LocatorDescribeOptions } from "./playwright-augment/augment";
-import type { ExtractSchema, SchemaOutput } from "./ai/extract";
-import { augmentBrowser, augmentBrowserContext, augmentBrowserType, augmentLocator, augmentPage } from "./playwright-augment/augment";
-import { stablyPlaywrightMatchers } from "./expect";
-import { requireApiKey } from "./runtime";
-export { setApiKey } from "./runtime";
-export type { LocatorDescribeOptions } from "./playwright-augment/augment";
-export type { ExtractSchema, SchemaOutput } from "./ai/extract";
-export type ScreenshotPromptOptions = import("@stablyai/internal-playwright-test").PageAssertionsToHaveScreenshotOptions;
-export { augmentBrowser, augmentBrowserContext, augmentBrowserType, augmentLocator, augmentPage, stablyPlaywrightMatchers, requireApiKey, };
-export interface Expect<T = Page> {
+import * as _stablyai_internal_playwright_test from '@stablyai/internal-playwright-test';
+import { Browser, BrowserContext, BrowserType, Locator, Page } from '@stablyai/internal-playwright-test';
+import * as z4 from 'zod/v4/core';
+
+interface LocatorDescribeOptions {
+    autoHeal?: boolean;
+}
+declare function augmentLocator<T extends Locator>(locator: T): T;
+declare function augmentPage<T extends Page>(page: T): T;
+declare function augmentBrowserContext<T extends BrowserContext>(context: T): T;
+declare function augmentBrowser<T extends Browser>(browser: T): T;
+declare function augmentBrowserType<TBrowser extends Browser>(browserType: BrowserType<TBrowser>): BrowserType<TBrowser>;
+
+interface ExtractSchema extends z4.$ZodType {
+    safeParseAsync(data: unknown, params?: z4.ParseContext<z4.$ZodIssue>): Promise<z4.util.SafeParseResult<z4.output<this>>>;
+}
+type SchemaOutput<T extends ExtractSchema> = z4.output<T>;
+
+type MatcherContext = {
+    isNot: boolean;
+    message?: () => string;
+};
+declare const stablyPlaywrightMatchers: {
+    readonly toMatchScreenshotPrompt: (this: MatcherContext, received: Page | Locator, condition: string, options?: ScreenshotPromptOptions) => Promise<{
+        pass: boolean;
+        message: () => string;
+    }>;
+};
+
+declare function setApiKey(apiKey: string): void;
+declare function requireApiKey(): string;
+
+type ScreenshotPromptOptions = _stablyai_internal_playwright_test.PageAssertionsToHaveScreenshotOptions;
+
+interface Expect<T = Page> {
     toMatchScreenshotPrompt(condition: string, options?: ScreenshotPromptOptions): Promise<void>;
 }
 declare module "@stablyai/internal-playwright-test" {
@@ -85,3 +108,5 @@ declare module "@stablyai/internal-playwright-test" {
         }>;
     }
 }
+
+export { type Expect, type ExtractSchema, type LocatorDescribeOptions, type SchemaOutput, type ScreenshotPromptOptions, augmentBrowser, augmentBrowserContext, augmentBrowserType, augmentLocator, augmentPage, requireApiKey, setApiKey, stablyPlaywrightMatchers };

package/dist/index.mjs

@@ -0,0 +1,467 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/runtime.ts
+var configuredApiKey = process.env.STABLY_API_KEY;
+function setApiKey(apiKey) {
+  configuredApiKey = apiKey;
+}
+function getApiKey() {
+  return configuredApiKey;
+}
+function requireApiKey() {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw new Error(
+      "Missing Stably API key. Call setApiKey(apiKey) or set the STABLY_API_KEY environment variable."
+    );
+  }
+  return apiKey;
+}
+
+// src/type-predicate/is-object.ts
+var isObject = (value) => {
+  return typeof value === "object" && value !== null;
+};
+
+// src/ai/metadata.ts
+var SDK_METADATA_HEADERS = {
+  "X-Client-Name": "stably-playwright-sdk-js",
+  "X-Client-Version": "0.1.7-next.10"
+};
+
+// 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) => {
+  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({
+  prompt,
+  pageOrLocator,
+  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(
+    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, {
+    method: "POST",
+    headers: {
+      ...SDK_METADATA_HEADERS,
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: form
+  });
+  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 === false) {
+      return 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({
+        prompt,
+        schema: options.schema,
+        pageOrLocator
+      });
+    }
+    return extract({ prompt, pageOrLocator });
+  };
+  return impl;
+}
+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";
+}
+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}` : ""}`
+  );
+}
+
+// src/image-compare.ts
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import * as jpeg from "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;
+};
+var isJpeg = (buffer) => {
+  return buffer.length >= 2 && buffer[0] === 255 && buffer[1] === 216;
+};
+var decodeImage = (buffer) => {
+  if (isPng(buffer)) {
+    const png2 = PNG.sync.read(buffer);
+    return { data: png2.data, width: png2.width, height: png2.height };
+  }
+  if (isJpeg(buffer)) {
+    const img = jpeg.decode(buffer, { maxMemoryUsageInMB: 1024 });
+    return { data: img.data, width: img.width, height: img.height };
+  }
+  const png = PNG.sync.read(buffer);
+  return { data: png.data, width: png.width, height: png.height };
+};
+var imagesAreSimilar = ({
+  image1,
+  image2,
+  threshold
+}) => {
+  const decodedImage1 = decodeImage(image1);
+  const decodedImage2 = decodeImage(image2);
+  if (decodedImage1.width !== decodedImage2.width || decodedImage1.height !== decodedImage2.height) {
+    return false;
+  }
+  const diffRgbaData = new Uint8Array(
+    decodedImage1.width * decodedImage1.height * 4
+  );
+  const numDiffPixels = pixelmatch(
+    decodedImage1.data,
+    decodedImage2.data,
+    diffRgbaData,
+    decodedImage1.width,
+    decodedImage1.height,
+    { threshold }
+  );
+  return numDiffPixels === 0;
+};
+
+// src/screenshot.ts
+async function takeStableScreenshot(target, options) {
+  const page = isPage(target) ? target : target.page();
+  const totalTimeout = options?.timeout ?? 5e3;
+  const stabilizationBudgetMs = Math.floor(totalTimeout * 0.25);
+  const stabilityBudgetMs = Math.min(
+    2e3,
+    Math.max(300, stabilizationBudgetMs)
+  );
+  const deadline = Date.now() + stabilityBudgetMs;
+  let actual;
+  let previous;
+  const pollIntervals = [0, 100, 250, 500];
+  let isFirstIteration = true;
+  while (true) {
+    if (Date.now() >= deadline) break;
+    const delay = pollIntervals.length ? pollIntervals.shift() : 1e3;
+    if (delay) {
+      await page.waitForTimeout(delay);
+    }
+    previous = actual;
+    actual = await target.screenshot(options);
+    if (!isFirstIteration && actual && previous && imagesAreSimilar({
+      image1: previous,
+      image2: actual,
+      threshold: options?.threshold ?? 0.02
+    })) {
+      return actual;
+    }
+    isFirstIteration = false;
+  }
+  return actual ?? await target.screenshot(options);
+}
+
+// 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
+      })
+    };
+  }
+};
+export {
+  augmentBrowser,
+  augmentBrowserContext,
+  augmentBrowserType,
+  augmentLocator,
+  augmentPage,
+  requireApiKey,
+  setApiKey,
+  stablyPlaywrightMatchers
+};
+//# sourceMappingURL=index.mjs.map