@stablyai/playwright-base 0.1.0

package/dist/ai/extract.d.ts

@@ -0,0 +1,15 @@
+import type { Locator, Page } from 'playwright';
+import * as z4 from 'zod/v4/core';
+export type ExtractSchema = z4.$ZodType;
+export type SchemaOutput<T extends ExtractSchema> = z4.output<T>;
+type ExtractSubject = Page | Locator;
+type BaseExtractArgs = {
+    prompt: string;
+    pageOrLocator: ExtractSubject;
+};
+type ExtractArgsWithSchema<T extends ExtractSchema> = BaseExtractArgs & {
+    schema: T;
+};
+export declare function extract(args: BaseExtractArgs): Promise<string>;
+export declare function extract<T extends ExtractSchema>(args: ExtractArgsWithSchema<T>): Promise<SchemaOutput<T>>;
+export {};

package/dist/ai/extract.js

@@ -0,0 +1,85 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extract = extract;
+const z4 = __importStar(require("zod/v4/core"));
+const zod_1 = require("zod");
+const runtime_1 = require("../runtime");
+const EXTRACT_ENDPOINT = 'https://api.stably.ai/internal/v1/extract';
+const zSuccess = zod_1.z.object({ value: zod_1.z.unknown() });
+const zError = zod_1.z.object({ error: zod_1.z.string() });
+class ExtractValidationError extends Error {
+    constructor(message, issues) {
+        super(message);
+        this.issues = issues;
+        this.name = 'ExtractValidationError';
+    }
+}
+async function validateWithSchema(schema, value) {
+    const result = await z4.safeParseAsync(schema, value);
+    if (!result.success) {
+        throw new ExtractValidationError('Validation failed', result.error.issues);
+    }
+    return result.data;
+}
+async function extract({ prompt, pageOrLocator, schema, }) {
+    const jsonSchema = schema ? z4.toJSONSchema(schema) : undefined;
+    const apiKey = (0, runtime_1.requireApiKey)();
+    const form = new FormData();
+    form.append('prompt', prompt);
+    if (jsonSchema) {
+        form.append('jsonSchema', JSON.stringify(jsonSchema));
+    }
+    const pngBuffer = await pageOrLocator.screenshot({ type: 'png' }); // Buffer
+    const u8 = Uint8Array.from(pngBuffer); // strips Buffer type → plain Uint8Array
+    const blob = new Blob([u8], { type: 'image/png' });
+    form.append('image', blob, 'screenshot.png');
+    const response = await fetch(EXTRACT_ENDPOINT, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: form,
+    });
+    const parsed = await response.json().catch(() => undefined);
+    if (response.ok) {
+        const { value } = zSuccess.parse(parsed);
+        return (schema ? await validateWithSchema(schema, value)
+            : typeof value === 'string' ? value
+                : JSON.stringify(value));
+    }
+    const err = zError.safeParse(parsed);
+    throw new Error(`Extract failed (${response.status})${err.success ? `: ${err.data.error}` : ''}`);
+}

package/dist/ai/verify-prompt.d.ts

@@ -0,0 +1,7 @@
+export declare function verifyPrompt({ prompt, screenshot, }: {
+    prompt: string;
+    screenshot: Uint8Array;
+}): Promise<{
+    pass: boolean;
+    reason?: string;
+}>;

package/dist/ai/verify-prompt.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyPrompt = verifyPrompt;
+const PROMPT_ASSERTION_ENDPOINT = 'https://api.stably.ai/internal/v1/assert';
+const zod_1 = require("zod");
+const runtime_1 = require("../runtime");
+const zSuccess = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    reason: zod_1.z.string().optional(),
+});
+const zError = zod_1.z.object({
+    error: zod_1.z.string(),
+});
+async function verifyPrompt({ prompt, screenshot, }) {
+    const apiKey = (0, runtime_1.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: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: form,
+    });
+    const parsed = await response.json().catch(() => undefined);
+    if (response.ok) {
+        const { success, reason } = zSuccess.parse(parsed);
+        return {
+            pass: success,
+            reason,
+        };
+    }
+    const err = zError.safeParse(parsed);
+    throw new Error(`Verify prompt failed (${response.status})${err.success ? `: ${err.data.error}` : ''}`);
+}

package/dist/expect.d.ts

@@ -0,0 +1,13 @@
+import type { Locator, Page } from 'playwright';
+import type { ScreenshotPromptOptions } from './index';
+type MatcherContext = {
+    isNot: boolean;
+    message?: () => string;
+};
+export declare const stablyPlaywrightMatchers: {
+    readonly toMatchScreenshotPrompt: (this: MatcherContext, received: Page | Locator, condition: string, options?: ScreenshotPromptOptions) => Promise<{
+        pass: boolean;
+        message: () => string;
+    }>;
+};
+export {};

package/dist/expect.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stablyPlaywrightMatchers = void 0;
+const playwright_type_predicates_1 = require("./playwright-type-predicates");
+const verify_prompt_1 = require("./ai/verify-prompt");
+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 += `\n\nReason: ${reason}`;
+    }
+    return message;
+}
+function areScreenshotsEqual(a, b) {
+    if (a.byteLength !== b.byteLength) {
+        return false;
+    }
+    for (let index = 0; index < a.byteLength; index += 1) {
+        if (a[index] !== b[index]) {
+            return false;
+        }
+    }
+    return true;
+}
+async function takeStableScreenshot(target, options) {
+    var _a;
+    const page = (0, playwright_type_predicates_1.isPage)(target) ? target : target.page();
+    // Use a small budget for stabilization within the overall assertion timeout.
+    // We allocate up to 25% of the total timeout (bounded between 300ms and 2000ms).
+    const totalTimeout = (_a = options === null || options === void 0 ? void 0 : options.timeout) !== null && _a !== void 0 ? _a : 5000;
+    // Budget is 25% of the total timeout
+    const stabilizationBudgetMs = Math.floor(totalTimeout * 0.25);
+    const stabilityBudgetMs = Math.min(2000, 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() : 1000;
+        if (delay) {
+            await page.waitForTimeout(delay);
+        }
+        previous = actual;
+        const rawScreenshot = await target.screenshot(options);
+        actual = Uint8Array.from(rawScreenshot);
+        if (!isFirstIteration &&
+            actual &&
+            previous &&
+            areScreenshotsEqual(actual, previous)) {
+            return actual;
+        }
+        isFirstIteration = false;
+    }
+    return actual !== null && actual !== void 0 ? actual : Uint8Array.from(await target.screenshot(options));
+}
+exports.stablyPlaywrightMatchers = {
+    async toMatchScreenshotPrompt(received, condition, options) {
+        const target = (0, playwright_type_predicates_1.isPage)(received) ? received
+            : (0, playwright_type_predicates_1.isLocator)(received) ? received
+                : undefined;
+        if (!target) {
+            // Should never happen
+            throw new Error('toMatchScreenshotPrompt only supports Playwright Page and Locator instances.');
+        }
+        const targetType = (0, playwright_type_predicates_1.isPage)(target) ? 'page' : 'locator';
+        // Wait for two consecutive identical screenshots before sending to AI
+        const screenshot = await takeStableScreenshot(target, options);
+        const verifyResult = await (0, verify_prompt_1.verifyPrompt)({ prompt: condition, screenshot });
+        return {
+            pass: verifyResult.pass,
+            message: () => createFailureMessage({
+                targetType,
+                condition,
+                didPass: verifyResult.pass,
+                reason: verifyResult.reason,
+                isNot: this.isNot,
+            }),
+        };
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import type { Page } from 'playwright';
+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('@playwright/test').PageAssertionsToHaveScreenshotOptions;
+export { augmentBrowser, augmentBrowserContext, augmentBrowserType, augmentLocator, augmentPage, stablyPlaywrightMatchers, requireApiKey, };
+export interface Expect<T = Page> {
+    toMatchScreenshotPrompt(condition: string, options?: ScreenshotPromptOptions): Promise<void>;
+}
+declare module 'playwright' {
+    interface Locator {
+        extract(prompt: string): Promise<string>;
+        extract<T extends ExtractSchema>(prompt: string, options: {
+            schema: T;
+        }): Promise<SchemaOutput<T>>;
+        describe(description: string, options?: LocatorDescribeOptions): Locator;
+    }
+    interface Page {
+        extract(prompt: string): Promise<string>;
+        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;
+        }>;
+    }
+}

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireApiKey = exports.stablyPlaywrightMatchers = exports.augmentPage = exports.augmentLocator = exports.augmentBrowserType = exports.augmentBrowserContext = exports.augmentBrowser = exports.setApiKey = void 0;
+const augment_1 = require("./playwright-augment/augment");
+Object.defineProperty(exports, "augmentBrowser", { enumerable: true, get: function () { return augment_1.augmentBrowser; } });
+Object.defineProperty(exports, "augmentBrowserContext", { enumerable: true, get: function () { return augment_1.augmentBrowserContext; } });
+Object.defineProperty(exports, "augmentBrowserType", { enumerable: true, get: function () { return augment_1.augmentBrowserType; } });
+Object.defineProperty(exports, "augmentLocator", { enumerable: true, get: function () { return augment_1.augmentLocator; } });
+Object.defineProperty(exports, "augmentPage", { enumerable: true, get: function () { return augment_1.augmentPage; } });
+const expect_1 = require("./expect");
+Object.defineProperty(exports, "stablyPlaywrightMatchers", { enumerable: true, get: function () { return expect_1.stablyPlaywrightMatchers; } });
+const runtime_1 = require("./runtime");
+Object.defineProperty(exports, "requireApiKey", { enumerable: true, get: function () { return runtime_1.requireApiKey; } });
+var runtime_2 = require("./runtime");
+Object.defineProperty(exports, "setApiKey", { enumerable: true, get: function () { return runtime_2.setApiKey; } });

package/dist/playwright-augment/augment.d.ts

@@ -0,0 +1,9 @@
+import type { Browser, BrowserContext, BrowserType, Locator, Page } from 'playwright';
+export interface LocatorDescribeOptions {
+    autoHeal?: boolean;
+}
+export declare function augmentLocator<T extends Locator>(locator: T): T;
+export declare function augmentPage<T extends Page>(page: T): T;
+export declare function augmentBrowserContext<T extends BrowserContext>(context: T): T;
+export declare function augmentBrowser<T extends Browser>(browser: T): T;
+export declare function augmentBrowserType<TBrowser extends Browser>(browserType: BrowserType<TBrowser>): BrowserType<TBrowser>;

package/dist/playwright-augment/augment.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.augmentLocator = augmentLocator;
+exports.augmentPage = augmentPage;
+exports.augmentBrowserContext = augmentBrowserContext;
+exports.augmentBrowser = augmentBrowser;
+exports.augmentBrowserType = augmentBrowserType;
+const extract_1 = require("./methods/extract");
+const agent_1 = require("./methods/agent");
+const LOCATOR_PATCHED = Symbol.for('stably.playwright.locatorPatched');
+const LOCATOR_DESCRIBE_WRAPPED = Symbol.for('stably.playwright.locatorDescribeWrapped');
+const PAGE_PATCHED = Symbol.for('stably.playwright.pagePatched');
+const CONTEXT_PATCHED = Symbol.for('stably.playwright.contextPatched');
+const BROWSER_PATCHED = Symbol.for('stably.playwright.browserPatched');
+const 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', (0, extract_1.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', (0, extract_1.createPageExtract)(page));
+    defineHiddenProperty(page, PAGE_PATCHED, true);
+    return page;
+}
+function augmentBrowserContext(context) {
+    var _a;
+    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 = (_a = context.pages) === null || _a === void 0 ? void 0 : _a.bind(context);
+    if (originalPages) {
+        context.pages = (() => originalPages().map((page) => augmentPage(page)));
+    }
+    if (!context.agent) {
+        defineHiddenProperty(context, 'agent', (0, agent_1.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', (0, agent_1.createAgentStub)());
+    }
+    defineHiddenProperty(browser, BROWSER_PATCHED, true);
+    return browser;
+}
+function augmentBrowserType(browserType) {
+    var _a, _b, _c;
+    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 = (_a = browserType.connect) === null || _a === void 0 ? void 0 : _a.bind(browserType);
+    if (originalConnect) {
+        browserType.connect = (async (...args) => {
+            const browser = await originalConnect(...args);
+            return augmentBrowser(browser);
+        });
+    }
+    const originalConnectOverCDP = (_b = browserType.connectOverCDP) === null || _b === void 0 ? void 0 : _b.bind(browserType);
+    if (originalConnectOverCDP) {
+        browserType.connectOverCDP = (async (...args) => {
+            const browser = await originalConnectOverCDP(...args);
+            return augmentBrowser(browser);
+        });
+    }
+    const originalLaunchPersistentContext = (_c = browserType.launchPersistentContext) === null || _c === void 0 ? void 0 : _c.bind(browserType);
+    if (originalLaunchPersistentContext) {
+        browserType.launchPersistentContext = (async (...args) => {
+            const context = await originalLaunchPersistentContext(...args);
+            return augmentBrowserContext(context);
+        });
+    }
+    defineHiddenProperty(browserType, BROWSER_TYPE_PATCHED, true);
+    return browserType;
+}

package/dist/playwright-augment/methods/agent.d.ts

@@ -0,0 +1,9 @@
+import type { Page } from 'playwright';
+type AgentOptions = {
+    page: Page;
+    maxCycles?: number;
+};
+export declare function createAgentStub(): (prompt: string, options: AgentOptions) => Promise<{
+    success: boolean;
+}>;
+export {};

package/dist/playwright-augment/methods/agent.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentStub = createAgentStub;
+const runtime_1 = require("../../runtime");
+function createAgentStub() {
+    return async (prompt, options) => {
+        (0, runtime_1.requireApiKey)();
+        void prompt;
+        void options;
+        return { success: true };
+    };
+}

package/dist/playwright-augment/methods/extract.d.ts

@@ -0,0 +1,14 @@
+import type { Locator, Page } from 'playwright';
+import { type ExtractSchema, type SchemaOutput } from '../../ai/extract';
+type ExtractOptions<T extends ExtractSchema> = {
+    schema: T;
+};
+type ExtractMethod = {
+    (prompt: string): Promise<string>;
+    <T extends ExtractSchema>(prompt: string, options: ExtractOptions<T>): Promise<SchemaOutput<T>>;
+};
+type LocatorExtract = ExtractMethod;
+type PageExtract = ExtractMethod;
+export declare const createLocatorExtract: (locator: Locator) => LocatorExtract;
+export declare const createPageExtract: (page: Page) => PageExtract;
+export {};

package/dist/playwright-augment/methods/extract.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPageExtract = exports.createLocatorExtract = void 0;
+const extract_1 = require("../../ai/extract");
+function createExtract(pageOrLocator) {
+    const impl = (async (prompt, options) => {
+        if (options === null || options === void 0 ? void 0 : options.schema) {
+            return (0, extract_1.extract)({
+                prompt,
+                schema: options.schema,
+                pageOrLocator,
+            });
+        }
+        return (0, extract_1.extract)({ prompt, pageOrLocator });
+    });
+    return impl;
+}
+const createLocatorExtract = (locator) => createExtract(locator);
+exports.createLocatorExtract = createLocatorExtract;
+const createPageExtract = (page) => createExtract(page);
+exports.createPageExtract = createPageExtract;

package/dist/playwright-type-predicates.d.ts

@@ -0,0 +1,3 @@
+import { Page, Locator } from 'playwright';
+export declare function isPage(candidate: unknown): candidate is Page;
+export declare function isLocator(candidate: unknown): candidate is Locator;

package/dist/playwright-type-predicates.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPage = isPage;
+exports.isLocator = isLocator;
+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');
+}

package/dist/runtime.d.ts

@@ -0,0 +1,3 @@
+export declare function setApiKey(apiKey: string): void;
+export declare function getApiKey(): string | undefined;
+export declare function requireApiKey(): string;

package/dist/runtime.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setApiKey = setApiKey;
+exports.getApiKey = getApiKey;
+exports.requireApiKey = requireApiKey;
+let 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;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@stablyai/playwright-base",
+  "version": "0.1.0",
+  "description": "Shared augmentation runtime for Stably Playwright wrappers",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@playwright/test": "^1.44.0",
+    "playwright": "^1.44.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "zod": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}

package/src/ai/extract.ts

@@ -0,0 +1,97 @@
+import type { Locator, Page } from 'playwright';
+import * as z4 from 'zod/v4/core';
+import { z } from 'zod';
+import { requireApiKey } from '../runtime';
+
+export type ExtractSchema = z4.$ZodType;
+
+export type SchemaOutput<T extends ExtractSchema> = z4.output<T>;
+
+type ExtractIssue = z4.$ZodIssue;
+
+const EXTRACT_ENDPOINT = 'https://api.stably.ai/internal/v1/extract';
+
+const zSuccess = z.object({ value: z.unknown() });
+const zError = z.object({ error: z.string() });
+
+class ExtractValidationError extends Error {
+  constructor(
+    message: string,
+    readonly issues: ReadonlyArray<ExtractIssue>,
+  ) {
+    super(message);
+    this.name = 'ExtractValidationError';
+  }
+}
+
+async function validateWithSchema<T extends ExtractSchema>(
+  schema: T,
+  value: unknown,
+): Promise<SchemaOutput<T>> {
+  const result = await z4.safeParseAsync(schema, value);
+  if (!result.success) {
+    throw new ExtractValidationError('Validation failed', result.error.issues);
+  }
+
+  return result.data;
+}
+
+type ExtractSubject = Page | Locator;
+
+type BaseExtractArgs = {
+  prompt: string;
+  pageOrLocator: ExtractSubject;
+};
+
+type ExtractArgsWithSchema<T extends ExtractSchema> = BaseExtractArgs & {
+  schema: T;
+};
+
+export async function extract(args: BaseExtractArgs): Promise<string>;
+export async function extract<T extends ExtractSchema>(
+  args: ExtractArgsWithSchema<T>,
+): Promise<SchemaOutput<T>>;
+export async function extract<T extends ExtractSchema>({
+  prompt,
+  pageOrLocator,
+  schema,
+}: BaseExtractArgs & { schema?: T }): Promise<string | SchemaOutput<T>> {
+  const jsonSchema = schema ? z4.toJSONSchema(schema) : undefined;
+
+  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' }); // Buffer
+  const u8 = Uint8Array.from(pngBuffer); // strips Buffer type → plain Uint8Array
+  const blob = new Blob([u8], { type: 'image/png' });
+  form.append('image', blob, 'screenshot.png');
+
+  const response = await fetch(EXTRACT_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: form,
+  });
+
+  const parsed = await response.json().catch(() => undefined as unknown);
+
+  if (response.ok) {
+    const { value } = zSuccess.parse(parsed);
+    return (
+      schema ? await validateWithSchema(schema, value)
+      : typeof value === 'string' ? value
+      : JSON.stringify(value)
+    );
+  }
+
+  const err = zError.safeParse(parsed);
+  throw new Error(
+    `Extract failed (${response.status})${err.success ? `: ${err.data.error}` : ''}`,
+  );
+}

package/src/ai/verify-prompt.ts

@@ -0,0 +1,57 @@
+const PROMPT_ASSERTION_ENDPOINT = 'https://api.stably.ai/internal/v1/assert';
+
+import { z } from 'zod';
+import { requireApiKey } from '../runtime';
+
+const zSuccess = z.object({
+  success: z.boolean(),
+  reason: z.string().optional(),
+});
+
+const zError = z.object({
+  error: z.string(),
+});
+
+export async function verifyPrompt({
+  prompt,
+  screenshot,
+}: {
+  prompt: string;
+  screenshot: Uint8Array;
+}): Promise<{
+  pass: boolean;
+  reason?: string;
+}> {
+  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: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: form,
+  });
+
+  const parsed = await response.json().catch(() => undefined as unknown);
+
+  if (response.ok) {
+    const { success, reason } = zSuccess.parse(parsed);
+    return {
+      pass: success,
+      reason,
+    };
+  }
+
+  const err = zError.safeParse(parsed);
+  throw new Error(
+    `Verify prompt failed (${response.status})${
+      err.success ? `: ${err.data.error}` : ''
+    }`,
+  );
+}

package/src/expect.ts

@@ -0,0 +1,134 @@
+import type { Locator, Page } from 'playwright';
+import type { ScreenshotPromptOptions } from './index';
+
+import { isLocator, isPage } from './playwright-type-predicates';
+
+import { verifyPrompt } from './ai/verify-prompt';
+
+type VerifyTargetType = 'page' | 'locator';
+
+type MatcherContext = {
+  isNot: boolean;
+  message?: () => string;
+};
+
+function createFailureMessage({
+  targetType,
+  condition,
+  didPass,
+  isNot,
+  reason,
+}: {
+  targetType: VerifyTargetType;
+  condition: string;
+  didPass: boolean;
+  isNot: boolean;
+  reason?: string;
+}): string {
+  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 += `\n\nReason: ${reason}`;
+  }
+
+  return message;
+}
+
+function areScreenshotsEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.byteLength !== b.byteLength) {
+    return false;
+  }
+
+  for (let index = 0; index < a.byteLength; index += 1) {
+    if (a[index] !== b[index]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+async function takeStableScreenshot(
+  target: Page | Locator,
+  options?: ScreenshotPromptOptions,
+): Promise<Uint8Array> {
+  const page = isPage(target) ? target : target.page();
+
+  // Use a small budget for stabilization within the overall assertion timeout.
+  // We allocate up to 25% of the total timeout (bounded between 300ms and 2000ms).
+  const totalTimeout =
+    (options as { timeout?: number } | undefined)?.timeout ?? 5000;
+  // Budget is 25% of the total timeout
+  const stabilizationBudgetMs = Math.floor(totalTimeout * 0.25);
+  const stabilityBudgetMs = Math.min(
+    2000,
+    Math.max(300, stabilizationBudgetMs),
+  );
+  const deadline = Date.now() + stabilityBudgetMs;
+
+  let actual: Uint8Array | undefined;
+  let previous: Uint8Array | undefined;
+  const pollIntervals = [0, 100, 250, 500];
+  let isFirstIteration = true;
+
+  while (true) {
+    if (Date.now() >= deadline) break;
+    const delay = pollIntervals.length ? pollIntervals.shift()! : 1000;
+    if (delay) {
+      await page.waitForTimeout(delay);
+    }
+    previous = actual;
+    const rawScreenshot = await target.screenshot(options);
+    actual = Uint8Array.from(rawScreenshot);
+    if (
+      !isFirstIteration &&
+      actual &&
+      previous &&
+      areScreenshotsEqual(actual, previous)
+    ) {
+      return actual;
+    }
+    isFirstIteration = false;
+  }
+  return actual ?? Uint8Array.from(await target.screenshot(options));
+}
+
+export const stablyPlaywrightMatchers = {
+  async toMatchScreenshotPrompt(
+    this: MatcherContext,
+    received: Page | Locator,
+    condition: string,
+    options?: ScreenshotPromptOptions,
+  ) {
+    const target =
+      isPage(received) ? received
+      : isLocator(received) ? received
+      : undefined;
+    if (!target) {
+      // Should never happen
+      throw new Error(
+        'toMatchScreenshotPrompt only supports Playwright Page and Locator instances.',
+      );
+    }
+    const targetType: VerifyTargetType = isPage(target) ? 'page' : 'locator';
+
+    // Wait for two consecutive identical screenshots before sending to AI
+    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,
+        }),
+    };
+  },
+} as const;

package/src/index.ts

@@ -0,0 +1,69 @@
+import type { Page } from 'playwright';
+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('@playwright/test').PageAssertionsToHaveScreenshotOptions;
+export {
+  augmentBrowser,
+  augmentBrowserContext,
+  augmentBrowserType,
+  augmentLocator,
+  augmentPage,
+  stablyPlaywrightMatchers,
+  requireApiKey,
+};
+
+export interface Expect<T = Page> {
+  toMatchScreenshotPrompt(
+    condition: string,
+    options?: ScreenshotPromptOptions,
+  ): Promise<void>;
+}
+
+declare module 'playwright' {
+  interface Locator {
+    extract(prompt: string): Promise<string>;
+    extract<T extends ExtractSchema>(
+      prompt: string,
+      options: { schema: T },
+    ): Promise<SchemaOutput<T>>;
+    describe(description: string, options?: LocatorDescribeOptions): Locator;
+  }
+
+  interface Page {
+    extract(prompt: string): Promise<string>;
+    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 }>;
+  }
+}

package/src/playwright-augment/augment.ts

@@ -0,0 +1,207 @@
+import type {
+  Browser,
+  BrowserContext,
+  BrowserType,
+  Locator,
+  Page,
+} from 'playwright';
+
+import { createLocatorExtract, createPageExtract } from './methods/extract';
+import { createAgentStub } from './methods/agent';
+
+export interface LocatorDescribeOptions {
+  autoHeal?: boolean;
+}
+
+const LOCATOR_PATCHED = Symbol.for('stably.playwright.locatorPatched');
+const LOCATOR_DESCRIBE_WRAPPED = Symbol.for(
+  'stably.playwright.locatorDescribeWrapped',
+);
+const PAGE_PATCHED = Symbol.for('stably.playwright.pagePatched');
+const CONTEXT_PATCHED = Symbol.for('stably.playwright.contextPatched');
+const BROWSER_PATCHED = Symbol.for('stably.playwright.browserPatched');
+const BROWSER_TYPE_PATCHED = Symbol.for('stably.playwright.browserTypePatched');
+
+function defineHiddenProperty<T, K extends PropertyKey>(
+  target: T,
+  key: K,
+  value: unknown,
+): void {
+  Object.defineProperty(target as unknown as object, key, {
+    value,
+    enumerable: false,
+    configurable: true,
+    writable: true,
+  });
+}
+
+export function augmentLocator<T extends Locator>(locator: T): T {
+  if (
+    (locator as unknown as { [LOCATOR_PATCHED]?: boolean })[LOCATOR_PATCHED]
+  ) {
+    return locator;
+  }
+
+  defineHiddenProperty(locator, 'extract', createLocatorExtract(locator));
+
+  const markerTarget = locator as unknown as Record<PropertyKey, unknown>;
+
+  if (
+    typeof locator.describe === 'function' &&
+    !markerTarget[LOCATOR_DESCRIBE_WRAPPED]
+  ) {
+    const originalDescribe = locator.describe.bind(locator);
+    locator.describe = ((
+      description: string,
+      options?: LocatorDescribeOptions,
+    ) => {
+      void options;
+      const result = originalDescribe(description);
+      return result ? augmentLocator(result as Locator) : result;
+    }) as Locator['describe'];
+
+    defineHiddenProperty(locator, LOCATOR_DESCRIBE_WRAPPED, true);
+  }
+
+  defineHiddenProperty(locator, LOCATOR_PATCHED, true);
+
+  return locator;
+}
+
+export function augmentPage<T extends Page>(page: T): T {
+  if ((page as unknown as { [PAGE_PATCHED]?: boolean })[PAGE_PATCHED]) {
+    return page;
+  }
+
+  const originalLocator = page.locator.bind(page);
+  page.locator = ((...args: Parameters<Page['locator']>) => {
+    const locator = originalLocator(...args);
+    return augmentLocator(locator);
+  }) as Page['locator'];
+
+  defineHiddenProperty(page, 'extract', createPageExtract(page));
+  defineHiddenProperty(page, PAGE_PATCHED, true);
+
+  return page;
+}
+
+export function augmentBrowserContext<T extends BrowserContext>(context: T): T {
+  if (
+    (context as unknown as { [CONTEXT_PATCHED]?: boolean })[CONTEXT_PATCHED]
+  ) {
+    return context;
+  }
+
+  const originalNewPage = context.newPage.bind(context);
+  context.newPage = (async (...args: Parameters<BrowserContext['newPage']>) => {
+    const page = await originalNewPage(...args);
+    return augmentPage(page);
+  }) as BrowserContext['newPage'];
+
+  const originalPages = context.pages?.bind(context);
+  if (originalPages) {
+    context.pages = (() =>
+      originalPages().map((page) =>
+        augmentPage(page),
+      )) as BrowserContext['pages'];
+  }
+
+  if (!(context as unknown as { agent?: unknown }).agent) {
+    defineHiddenProperty(context, 'agent', createAgentStub());
+  }
+
+  defineHiddenProperty(context, CONTEXT_PATCHED, true);
+
+  return context;
+}
+
+export function augmentBrowser<T extends Browser>(browser: T): T {
+  if (
+    (browser as unknown as { [BROWSER_PATCHED]?: boolean })[BROWSER_PATCHED]
+  ) {
+    return browser;
+  }
+
+  const originalNewContext = browser.newContext.bind(browser);
+  browser.newContext = (async (...args: Parameters<Browser['newContext']>) => {
+    const context = await originalNewContext(...args);
+    return augmentBrowserContext(context);
+  }) as Browser['newContext'];
+
+  const originalNewPage = browser.newPage.bind(browser);
+  browser.newPage = (async (...args: Parameters<Browser['newPage']>) => {
+    const page = await originalNewPage(...args);
+    return augmentPage(page);
+  }) as Browser['newPage'];
+
+  const originalContexts = browser.contexts.bind(browser);
+  browser.contexts = (() =>
+    originalContexts().map((context) =>
+      augmentBrowserContext(context),
+    )) as Browser['contexts'];
+
+  if (!(browser as unknown as { agent?: unknown }).agent) {
+    defineHiddenProperty(browser, 'agent', createAgentStub());
+  }
+
+  defineHiddenProperty(browser, BROWSER_PATCHED, true);
+
+  return browser;
+}
+
+export function augmentBrowserType<TBrowser extends Browser>(
+  browserType: BrowserType<TBrowser>,
+): BrowserType<TBrowser> {
+  if (
+    (browserType as unknown as { [BROWSER_TYPE_PATCHED]?: boolean })[
+      BROWSER_TYPE_PATCHED
+    ]
+  ) {
+    return browserType;
+  }
+
+  const originalLaunch = browserType.launch.bind(browserType);
+  browserType.launch = (async (
+    ...args: Parameters<BrowserType<TBrowser>['launch']>
+  ) => {
+    const browser = await originalLaunch(...args);
+    return augmentBrowser(browser);
+  }) as BrowserType<TBrowser>['launch'];
+
+  const originalConnect = browserType.connect?.bind(browserType);
+  if (originalConnect) {
+    browserType.connect = (async (
+      ...args: Parameters<NonNullable<BrowserType<TBrowser>['connect']>>
+    ) => {
+      const browser = await originalConnect(...args);
+      return augmentBrowser(browser);
+    }) as NonNullable<BrowserType<TBrowser>['connect']>;
+  }
+
+  const originalConnectOverCDP = browserType.connectOverCDP?.bind(browserType);
+  if (originalConnectOverCDP) {
+    browserType.connectOverCDP = (async (
+      ...args: Parameters<NonNullable<BrowserType<TBrowser>['connectOverCDP']>>
+    ) => {
+      const browser = await originalConnectOverCDP(...args);
+      return augmentBrowser(browser);
+    }) as NonNullable<BrowserType<TBrowser>['connectOverCDP']>;
+  }
+
+  const originalLaunchPersistentContext =
+    browserType.launchPersistentContext?.bind(browserType);
+  if (originalLaunchPersistentContext) {
+    browserType.launchPersistentContext = (async (
+      ...args: Parameters<
+        NonNullable<BrowserType<TBrowser>['launchPersistentContext']>
+      >
+    ) => {
+      const context = await originalLaunchPersistentContext(...args);
+      return augmentBrowserContext(context);
+    }) as NonNullable<BrowserType<TBrowser>['launchPersistentContext']>;
+  }
+
+  defineHiddenProperty(browserType, BROWSER_TYPE_PATCHED, true);
+
+  return browserType;
+}

package/src/playwright-augment/methods/agent.ts

@@ -0,0 +1,19 @@
+import type { Page } from 'playwright';
+import { requireApiKey } from '../../runtime';
+
+type AgentOptions = {
+  page: Page;
+  maxCycles?: number;
+};
+
+export function createAgentStub(): (
+  prompt: string,
+  options: AgentOptions,
+) => Promise<{ success: boolean }> {
+  return async (prompt: string, options: AgentOptions) => {
+    requireApiKey();
+    void prompt;
+    void options;
+    return { success: true };
+  };
+}

package/src/playwright-augment/methods/extract.ts

@@ -0,0 +1,48 @@
+import type { Locator, Page } from 'playwright';
+import {
+  type ExtractSchema,
+  type SchemaOutput,
+  extract,
+} from '../../ai/extract';
+
+type ExtractOptions<T extends ExtractSchema> = {
+  schema: T;
+};
+
+type ExtractMethod = {
+  (prompt: string): Promise<string>;
+  <T extends ExtractSchema>(
+    prompt: string,
+    options: ExtractOptions<T>,
+  ): Promise<SchemaOutput<T>>;
+};
+
+type LocatorExtract = ExtractMethod;
+type PageExtract = ExtractMethod;
+
+type ExtractSubject = Locator | Page;
+
+function createExtract(pageOrLocator: ExtractSubject): ExtractMethod {
+  const impl = (async (
+    prompt: string,
+    options?: ExtractOptions<ExtractSchema>,
+  ) => {
+    if (options?.schema) {
+      return extract({
+        prompt,
+        schema: options.schema,
+        pageOrLocator,
+      });
+    }
+
+    return extract({ prompt, pageOrLocator });
+  }) as ExtractMethod;
+
+  return impl;
+}
+
+export const createLocatorExtract = (locator: Locator): LocatorExtract =>
+  createExtract(locator);
+
+export const createPageExtract = (page: Page): PageExtract =>
+  createExtract(page);

package/src/playwright-type-predicates.ts

@@ -0,0 +1,19 @@
+import { Page, Locator } from 'playwright';
+
+export function isPage(candidate: unknown): candidate is Page {
+  return (
+    typeof candidate === 'object' &&
+    candidate !== null &&
+    typeof (candidate as Page).screenshot === 'function' &&
+    typeof (candidate as Page).goto === 'function'
+  );
+}
+
+export function isLocator(candidate: unknown): candidate is Locator {
+  return (
+    typeof candidate === 'object' &&
+    candidate !== null &&
+    typeof (candidate as Locator).screenshot === 'function' &&
+    typeof (candidate as Locator).nth === 'function'
+  );
+}

package/src/runtime.ts

@@ -0,0 +1,19 @@
+let configuredApiKey: string | undefined = process.env.STABLY_API_KEY;
+
+export function setApiKey(apiKey: string): void {
+  configuredApiKey = apiKey;
+}
+
+export function getApiKey(): string | undefined {
+  return configuredApiKey;
+}
+
+export function requireApiKey(): string {
+  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;
+}

package/tsconfig.build.json

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["dist", "node_modules"]
+}