visual-ai-assertions 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,839 @@
+import { z } from 'zod';
+
+/** Supported provider identifiers for configuring `visualAI()`. */
+declare const Provider: {
+    readonly ANTHROPIC: "anthropic";
+    readonly OPENAI: "openai";
+    readonly GOOGLE: "google";
+};
+/** Known model names grouped by provider. */
+declare const Model: {
+    readonly Anthropic: {
+        readonly OPUS_4_6: "claude-opus-4-6";
+        readonly SONNET_4_6: "claude-sonnet-4-6";
+        readonly HAIKU_4_5: "claude-haiku-4-5";
+    };
+    readonly OpenAI: {
+        readonly GPT_5_4: "gpt-5.4";
+        readonly GPT_5_4_PRO: "gpt-5.4-pro";
+        readonly GPT_5_2: "gpt-5.2";
+        readonly GPT_5_MINI: "gpt-5-mini";
+    };
+    readonly Google: {
+        readonly GEMINI_3_1_PRO_PREVIEW: "gemini-3.1-pro-preview";
+        readonly GEMINI_3_FLASH_PREVIEW: "gemini-3-flash-preview";
+    };
+};
+/** Union of all built-in model name literals exposed by `Model`. */
+type KnownModelName = (typeof Model.Anthropic)[keyof typeof Model.Anthropic] | (typeof Model.OpenAI)[keyof typeof Model.OpenAI] | (typeof Model.Google)[keyof typeof Model.Google];
+/** Default model selection used when a caller omits `config.model`. */
+declare const DEFAULT_MODELS: {
+    readonly anthropic: "claude-sonnet-4-6";
+    readonly openai: "gpt-5-mini";
+    readonly google: "gemini-3-flash-preview";
+};
+/** List of accepted provider names for validation and public consumption. */
+declare const VALID_PROVIDERS: readonly ProviderName[];
+/** Built-in content checks available through `client.content()`. */
+declare const Content: {
+    /** Detects Lorem ipsum, TODO, TBD, and similar placeholder text */
+    readonly PLACEHOLDER_TEXT: "placeholder-text";
+    /** Detects error messages, banners, stack traces, or error codes */
+    readonly ERROR_MESSAGES: "error-messages";
+    /** Detects broken image icons or failed-to-load image indicators */
+    readonly BROKEN_IMAGES: "broken-images";
+    /** Detects UI elements that unintentionally overlap and obscure content */
+    readonly OVERLAPPING_ELEMENTS: "overlapping-elements";
+};
+/** Built-in layout checks available through `client.layout()`. */
+declare const Layout: {
+    /** Detects elements that unintentionally overlap each other */
+    readonly OVERLAP: "overlap";
+    /** Detects content cut off or extending beyond container boundaries */
+    readonly OVERFLOW: "overflow";
+    /** Detects inconsistent alignment of text, images, and UI components */
+    readonly ALIGNMENT: "alignment";
+};
+/** Built-in accessibility checks available through `client.accessibility()`. */
+declare const Accessibility: {
+    /** Detects insufficient color contrast between text and backgrounds */
+    readonly CONTRAST: "contrast";
+    /** Detects text that is cut off, overlapping, too small, or obscured */
+    readonly READABILITY: "readability";
+    /** Detects interactive elements that are not visually distinct */
+    readonly INTERACTIVE_VISIBILITY: "interactive-visibility";
+};
+/** Union of all built-in content check names. */
+type ContentCheckName = (typeof Content)[keyof typeof Content];
+/** Union of all built-in layout check names. */
+type LayoutCheckName = (typeof Layout)[keyof typeof Layout];
+/** Union of all built-in accessibility check names. */
+type AccessibilityCheckName = (typeof Accessibility)[keyof typeof Accessibility];
+
+/** Zod schema for issue severity levels returned by checks and questions. */
+declare const IssuePrioritySchema: z.ZodEnum<["critical", "major", "minor"]>;
+/** Severity level for a detected visual issue. */
+type IssuePriority = z.infer<typeof IssuePrioritySchema>;
+/** Zod schema for the categories assigned to detected visual issues. */
+declare const IssueCategorySchema: z.ZodEnum<["accessibility", "missing-element", "layout", "content", "styling", "functionality", "performance", "other"]>;
+/** Category assigned to a detected visual issue. */
+type IssueCategory = z.infer<typeof IssueCategorySchema>;
+/** Zod schema for a structured issue reported by the model. */
+declare const IssueSchema: z.ZodObject<{
+    priority: z.ZodEnum<["critical", "major", "minor"]>;
+    category: z.ZodEnum<["accessibility", "missing-element", "layout", "content", "styling", "functionality", "performance", "other"]>;
+    description: z.ZodString;
+    suggestion: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    priority: "critical" | "major" | "minor";
+    category: "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other";
+    description: string;
+    suggestion: string;
+}, {
+    priority: "critical" | "major" | "minor";
+    category: "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other";
+    description: string;
+    suggestion: string;
+}>;
+/** Structured issue reported by a visual check or question. */
+type Issue = z.infer<typeof IssueSchema>;
+/** Zod schema for model confidence labels on statement-level results. */
+declare const ConfidenceSchema: z.ZodEnum<["high", "medium", "low"]>;
+/** Confidence level attached to a statement result. */
+type Confidence = z.infer<typeof ConfidenceSchema>;
+/** Zod schema for an individual statement evaluation within `check()`. */
+declare const StatementResultSchema: z.ZodObject<{
+    statement: z.ZodString;
+    pass: z.ZodBoolean;
+    reasoning: z.ZodString;
+    confidence: z.ZodOptional<z.ZodEnum<["high", "medium", "low"]>>;
+}, "strip", z.ZodTypeAny, {
+    statement: string;
+    pass: boolean;
+    reasoning: string;
+    confidence?: "high" | "medium" | "low" | undefined;
+}, {
+    statement: string;
+    pass: boolean;
+    reasoning: string;
+    confidence?: "high" | "medium" | "low" | undefined;
+}>;
+/** Outcome of a single statement evaluated by `check()`. */
+type StatementResult = z.infer<typeof StatementResultSchema>;
+/** Zod schema for token and latency metadata attached to API calls. */
+declare const UsageInfoSchema: z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    estimatedCost: z.ZodOptional<z.ZodNumber>;
+    durationSeconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    inputTokens: number;
+    outputTokens: number;
+    estimatedCost?: number | undefined;
+    durationSeconds?: number | undefined;
+}, {
+    inputTokens: number;
+    outputTokens: number;
+    estimatedCost?: number | undefined;
+    durationSeconds?: number | undefined;
+}>;
+/** Token usage and optional cost/latency metadata for a provider call. */
+type UsageInfo = z.infer<typeof UsageInfoSchema>;
+/** Zod schema for results returned by `check()` and template helpers. */
+declare const CheckResultSchema: z.ZodObject<{
+    pass: z.ZodBoolean;
+    reasoning: z.ZodString;
+    usage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        estimatedCost: z.ZodOptional<z.ZodNumber>;
+        durationSeconds: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    }, {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    }>>;
+} & {
+    issues: z.ZodArray<z.ZodObject<{
+        priority: z.ZodEnum<["critical", "major", "minor"]>;
+        category: z.ZodEnum<["accessibility", "missing-element", "layout", "content", "styling", "functionality", "performance", "other"]>;
+        description: z.ZodString;
+        suggestion: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        priority: "critical" | "major" | "minor";
+        category: "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other";
+        description: string;
+        suggestion: string;
+    }, {
+        priority: "critical" | "major" | "minor";
+        category: "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other";
+        description: string;
+        suggestion: string;
+    }>, "many">;
+    statements: z.ZodArray<z.ZodObject<{
+        statement: z.ZodString;
+        pass: z.ZodBoolean;
+        reasoning: z.ZodString;
+        confidence: z.ZodOptional<z.ZodEnum<["high", "medium", "low"]>>;
+    }, "strip", z.ZodTypeAny, {
+        statement: string;
+        pass: boolean;
+        reasoning: string;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }, {
+        statement: string;
+        pass: boolean;
+        reasoning: string;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    issues: {
+        priority: "critical" | "major" | "minor";
+        category: "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other";
+        description: string;
+        suggestion: string;
+    }[];
+    pass: boolean;
+    reasoning: string;
+    statements: {
+        statement: string;
+        pass: boolean;
+        reasoning: string;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }[];
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    } | undefined;
+}, {
+    issues: {
+        priority: "critical" | "major" | "minor";
+        category: "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other";
+        description: string;
+        suggestion: string;
+    }[];
+    pass: boolean;
+    reasoning: string;
+    statements: {
+        statement: string;
+        pass: boolean;
+        reasoning: string;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }[];
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    } | undefined;
+}>;
+/** Result returned by `check()` and the template convenience methods. */
+type CheckResult = z.infer<typeof CheckResultSchema>;
+/** Zod schema for an individual visual change reported by `compare()`. */
+declare const ChangeEntrySchema: z.ZodObject<{
+    description: z.ZodString;
+    severity: z.ZodEnum<["critical", "major", "minor"]>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    severity: "critical" | "major" | "minor";
+}, {
+    description: string;
+    severity: "critical" | "major" | "minor";
+}>;
+/** Single visual change reported by `compare()`. */
+type ChangeEntry = z.infer<typeof ChangeEntrySchema>;
+/** Zod schema for the parsed model response returned by `compare()`. */
+declare const CompareResultSchema: z.ZodObject<{
+    pass: z.ZodBoolean;
+    reasoning: z.ZodString;
+    usage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        estimatedCost: z.ZodOptional<z.ZodNumber>;
+        durationSeconds: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    }, {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    }>>;
+} & {
+    changes: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        severity: z.ZodEnum<["critical", "major", "minor"]>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        severity: "critical" | "major" | "minor";
+    }, {
+        description: string;
+        severity: "critical" | "major" | "minor";
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    pass: boolean;
+    reasoning: string;
+    changes: {
+        description: string;
+        severity: "critical" | "major" | "minor";
+    }[];
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    } | undefined;
+}, {
+    pass: boolean;
+    reasoning: string;
+    changes: {
+        description: string;
+        severity: "critical" | "major" | "minor";
+    }[];
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    } | undefined;
+}>;
+/** Result returned by `compare()`, optionally including an AI-generated diff image. */
+type CompareResult = z.infer<typeof CompareResultSchema> & {
+    diffImage?: DiffImageResult;
+};
+/** Zod schema for results returned by `ask()`. */
+declare const AskResultSchema: z.ZodObject<{
+    summary: z.ZodString;
+    issues: z.ZodArray<z.ZodObject<{
+        priority: z.ZodEnum<["critical", "major", "minor"]>;
+        category: z.ZodEnum<["accessibility", "missing-element", "layout", "content", "styling", "functionality", "performance", "other"]>;
+        description: z.ZodString;
+        suggestion: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        priority: "critical" | "major" | "minor";
+        category: "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other";
+        description: string;
+        suggestion: string;
+    }, {
+        priority: "critical" | "major" | "minor";
+        category: "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other";
+        description: string;
+        suggestion: string;
+    }>, "many">;
+    usage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        estimatedCost: z.ZodOptional<z.ZodNumber>;
+        durationSeconds: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    }, {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    issues: {
+        priority: "critical" | "major" | "minor";
+        category: "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other";
+        description: string;
+        suggestion: string;
+    }[];
+    summary: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    } | undefined;
+}, {
+    issues: {
+        priority: "critical" | "major" | "minor";
+        category: "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other";
+        description: string;
+        suggestion: string;
+    }[];
+    summary: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCost?: number | undefined;
+        durationSeconds?: number | undefined;
+    } | undefined;
+}>;
+/** Result returned by `ask()`. */
+type AskResult = z.infer<typeof AskResultSchema>;
+/** Supported input shapes for image arguments accepted by the client. */
+type ImageInput = Buffer | Uint8Array | string;
+/** Supported image MIME types accepted by all providers. */
+type SupportedMimeType = "image/jpeg" | "image/png" | "image/webp" | "image/gif";
+/** Supported provider identifiers. */
+type ProviderName = "anthropic" | "openai" | "google";
+/** Optional reasoning depth requested from providers that support it. */
+type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
+/**
+ * Configuration for creating a visual AI client.
+ *
+ * @example
+ * ```ts
+ * const client = visualAI({
+ *   provider: "openai",
+ *   model: "gpt-5-mini",
+ *   apiKey: process.env.OPENAI_API_KEY,
+ * });
+ * ```
+ */
+interface VisualAIConfig {
+    provider?: ProviderName;
+    apiKey?: string;
+    model?: string;
+    debug?: boolean;
+    maxTokens?: number;
+    reasoningEffort?: ReasoningEffort;
+    trackUsage?: boolean;
+}
+/** Optional instructions for `check()`. */
+interface CheckOptions {
+    instructions?: readonly string[];
+}
+/** Optional instructions for `ask()`. */
+interface AskOptions {
+    instructions?: readonly string[];
+}
+/** Metadata and binary content for an AI-generated diff image. */
+interface DiffImageResult {
+    data: Buffer;
+    width: number;
+    height: number;
+    mimeType: "image/png";
+}
+/** Optional prompt, instructions, and diff configuration for `compare()`. */
+interface CompareOptions {
+    prompt?: string;
+    instructions?: readonly string[];
+    diffImage?: boolean;
+}
+/** Optional instructions for `elementsVisible()` and `elementsHidden()`. */
+interface ElementsVisibilityOptions {
+    instructions?: readonly string[];
+}
+/** Options for the built-in accessibility template. */
+interface AccessibilityOptions {
+    checks?: AccessibilityCheckName[];
+    instructions?: readonly string[];
+}
+/** Options for the built-in layout template. */
+interface LayoutOptions {
+    checks?: LayoutCheckName[];
+    instructions?: readonly string[];
+}
+/** Options for the built-in page-load template. */
+interface PageLoadOptions {
+    expectLoaded?: boolean;
+    instructions?: readonly string[];
+}
+/** Options for the built-in content template. */
+interface ContentOptions {
+    checks?: ContentCheckName[];
+    instructions?: readonly string[];
+}
+
+/**
+ * High-level client for running visual checks against screenshots or other images.
+ *
+ * @example
+ * ```ts
+ * const client = visualAI({ provider: "openai" });
+ * const result = await client.check("./tests/fixtures/small.png", "The button is visible");
+ * ```
+ */
+interface VisualAIClient {
+    /**
+     * Verifies one or more statements against a single image.
+     *
+     * @param image Image source as a buffer, URL, file path, or base64 string.
+     * @param statements One or more statements to validate against the image.
+     * @param options Optional additional instructions appended to the prompt.
+     * @returns A structured result describing pass/fail, issues, and statement reasoning.
+     * @throws {VisualAIConfigError} When no statements are provided.
+     * @throws {VisualAIImageError} When the image cannot be loaded or decoded.
+     * @throws {VisualAIError} When the provider rejects the request or returns invalid output.
+     * @example
+     * ```ts
+     * const result = await client.check(screenshot, [
+     *   "The primary CTA is visible",
+     *   "There is no error banner",
+     * ]);
+     * ```
+     */
+    check(image: ImageInput, statements: string | string[], options?: CheckOptions): Promise<CheckResult>;
+    /**
+     * Asks an open-ended question about an image and returns a structured summary.
+     *
+     * @param image Image source as a buffer, URL, file path, or base64 string.
+     * @param prompt Prompt describing what to inspect in the image.
+     * @param options Optional additional instructions appended to the prompt.
+     * @returns A summary with any detected issues.
+     * @throws {VisualAIImageError} When the image cannot be loaded or decoded.
+     * @throws {VisualAIError} When the provider rejects the request or returns invalid output.
+     * @example
+     * ```ts
+     * const result = await client.ask(screenshot, "What looks visually broken on this page?");
+     * ```
+     */
+    ask(image: ImageInput, prompt: string, options?: AskOptions): Promise<AskResult>;
+    /**
+     * Compares two images and reports meaningful visual differences.
+     *
+     * @param imageA Baseline image source.
+     * @param imageB Candidate image source.
+     * @param options Optional comparison prompt, instructions, and diff-image settings.
+     *   `gemini-3-flash-preview` generates an annotated diff image by default;
+     *   pass `{ diffImage: false }` to opt out.
+     * @returns A structured comparison result with optional diff image metadata.
+     * @throws {VisualAIImageError} When either image cannot be loaded or decoded.
+     * @throws {VisualAIError} When the provider rejects the request or returns invalid output.
+     * @example
+     * ```ts
+     * const result = await client.compare(beforeScreenshot, afterScreenshot, {
+     *   diffImage: true,
+     * });
+     * ```
+     */
+    compare(imageA: ImageInput, imageB: ImageInput, options?: CompareOptions): Promise<CompareResult>;
+    /**
+     * Checks that the listed elements are visible in an image.
+     *
+     * @param image Image source as a buffer, URL, file path, or base64 string.
+     * @param elements Element descriptions that should be present and visible.
+     * @param options Optional additional instructions appended to the prompt.
+     * @returns A structured pass/fail result for the requested elements.
+     * @throws {VisualAIConfigError} When `elements` is empty.
+     * @throws {VisualAIImageError} When the image cannot be loaded or decoded.
+     * @throws {VisualAIError} When the provider rejects the request or returns invalid output.
+     * @example
+     * ```ts
+     * await client.elementsVisible(screenshot, ["Save button", "Profile avatar"]);
+     * ```
+     */
+    elementsVisible(image: ImageInput, elements: string[], options?: ElementsVisibilityOptions): Promise<CheckResult>;
+    /**
+     * Checks that the listed elements are not visible in an image.
+     *
+     * @param image Image source as a buffer, URL, file path, or base64 string.
+     * @param elements Element descriptions that should be absent or hidden.
+     * @param options Optional additional instructions appended to the prompt.
+     * @returns A structured pass/fail result for the requested elements.
+     * @throws {VisualAIConfigError} When `elements` is empty.
+     * @throws {VisualAIImageError} When the image cannot be loaded or decoded.
+     * @throws {VisualAIError} When the provider rejects the request or returns invalid output.
+     * @example
+     * ```ts
+     * await client.elementsHidden(screenshot, ["Cookie banner"]);
+     * ```
+     */
+    elementsHidden(image: ImageInput, elements: string[], options?: ElementsVisibilityOptions): Promise<CheckResult>;
+    /**
+     * Runs the built-in accessibility template against an image.
+     *
+     * @param image Image source as a buffer, URL, file path, or base64 string.
+     * @param options Optional checks and extra instructions for the accessibility prompt.
+     * @returns A structured accessibility-focused check result.
+     * @throws {VisualAIImageError} When the image cannot be loaded or decoded.
+     * @throws {VisualAIError} When the provider rejects the request or returns invalid output.
+     * @example
+     * ```ts
+     * await client.accessibility(screenshot, { checks: ["contrast"] });
+     * ```
+     */
+    accessibility(image: ImageInput, options?: AccessibilityOptions): Promise<CheckResult>;
+    /**
+     * Runs the built-in layout template against an image.
+     *
+     * @param image Image source as a buffer, URL, file path, or base64 string.
+     * @param options Optional checks and extra instructions for the layout prompt.
+     * @returns A structured layout-focused check result.
+     * @throws {VisualAIImageError} When the image cannot be loaded or decoded.
+     * @throws {VisualAIError} When the provider rejects the request or returns invalid output.
+     * @example
+     * ```ts
+     * await client.layout(screenshot, { checks: ["overflow", "alignment"] });
+     * ```
+     */
+    layout(image: ImageInput, options?: LayoutOptions): Promise<CheckResult>;
+    /**
+     * Runs the built-in page-load template against an image.
+     *
+     * @param image Image source as a buffer, URL, file path, or base64 string.
+     * @param options Optional page-load expectations and extra instructions.
+     * @returns A structured page-load check result.
+     * @throws {VisualAIImageError} When the image cannot be loaded or decoded.
+     * @throws {VisualAIError} When the provider rejects the request or returns invalid output.
+     * @example
+     * ```ts
+     * await client.pageLoad(screenshot, { expectLoaded: true });
+     * ```
+     */
+    pageLoad(image: ImageInput, options?: PageLoadOptions): Promise<CheckResult>;
+    /**
+     * Runs the built-in content template against an image.
+     *
+     * @param image Image source as a buffer, URL, file path, or base64 string.
+     * @param options Optional content checks and extra instructions.
+     * @returns A structured content-focused check result.
+     * @throws {VisualAIImageError} When the image cannot be loaded or decoded.
+     * @throws {VisualAIError} When the provider rejects the request or returns invalid output.
+     * @example
+     * ```ts
+     * await client.content(screenshot, { checks: ["placeholder-text"] });
+     * ```
+     */
+    content(image: ImageInput, options?: ContentOptions): Promise<CheckResult>;
+}
+/**
+ * Creates a configured visual AI client.
+ *
+ * @param config Provider selection and runtime options for subsequent requests.
+ * @returns A `VisualAIClient` instance with check, compare, ask, and template helpers.
+ * @throws {VisualAIConfigError} When the provider or model configuration is invalid.
+ * @throws {VisualAIAuthError} When required API credentials are missing.
+ * @example
+ * ```ts
+ * import { expect, test } from "@playwright/test";
+ * import { visualAI } from "visual-ai-assertions";
+ *
+ * test("hero loads correctly", async ({ page }) => {
+ *   const client = visualAI({
+ *     provider: "openai",
+ *     apiKey: process.env.OPENAI_API_KEY,
+ *   });
+ *
+ *   await page.goto("https://example.com");
+ *   const screenshot = await page.screenshot();
+ *   const result = await client.check(screenshot, [
+ *     "The hero heading is visible",
+ *     "There is no loading spinner",
+ *   ]);
+ *
+ *   expect(result.pass).toBe(true);
+ * });
+ * ```
+ */
+declare function visualAI(config?: VisualAIConfig): VisualAIClient;
+
+/**
+ * Discrete error codes exposed by visual-ai-assertions for programmatic handling.
+ */
+type VisualAIErrorCode = "VISUAL_AI_ERROR" | "AUTH_FAILED" | "RATE_LIMITED" | "PROVIDER_ERROR" | "IMAGE_INVALID" | "RESPONSE_PARSE_FAILED" | "CONFIG_INVALID" | "ASSERTION_FAILED";
+/**
+ * Base class for all library errors.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   // ...
+ * } catch (error) {
+ *   if (error instanceof VisualAIError) {
+ *     console.error(error.code, error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class VisualAIError<TCode extends VisualAIErrorCode = VisualAIErrorCode> extends Error {
+    readonly code: TCode;
+    constructor(message: string, code?: TCode);
+}
+/**
+ * Thrown when a provider rejects the configured API credentials.
+ *
+ * @example
+ * ```ts
+ * throw new VisualAIAuthError("Anthropic API key not found");
+ * ```
+ */
+declare class VisualAIAuthError extends VisualAIError<"AUTH_FAILED"> {
+    readonly code: "AUTH_FAILED";
+    constructor(message: string);
+}
+/**
+ * Thrown when a provider enforces a rate limit.
+ *
+ * Carries `retryAfter` when the provider includes retry guidance.
+ *
+ * @example
+ * ```ts
+ * throw new VisualAIRateLimitError("Rate limited", 30);
+ * ```
+ */
+declare class VisualAIRateLimitError extends VisualAIError<"RATE_LIMITED"> {
+    readonly code: "RATE_LIMITED";
+    retryAfter?: number;
+    constructor(message: string, retryAfter?: number);
+}
+/**
+ * Thrown when a provider returns an unexpected non-auth, non-rate-limit failure.
+ *
+ * Carries `statusCode` when the provider exposes an HTTP status.
+ *
+ * @example
+ * ```ts
+ * throw new VisualAIProviderError("Provider returned 500", 500);
+ * ```
+ */
+declare class VisualAIProviderError extends VisualAIError<"PROVIDER_ERROR"> {
+    readonly code: "PROVIDER_ERROR";
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Thrown when an image input cannot be loaded, decoded, or validated.
+ *
+ * @example
+ * ```ts
+ * throw new VisualAIImageError("Unsupported image format: image/bmp");
+ * ```
+ */
+declare class VisualAIImageError extends VisualAIError<"IMAGE_INVALID"> {
+    readonly code: "IMAGE_INVALID";
+    constructor(message: string);
+}
+/**
+ * Thrown when a provider response cannot be parsed into the library result schema.
+ *
+ * Carries `rawResponse` so callers can inspect the original model output.
+ *
+ * @example
+ * ```ts
+ * throw new VisualAIResponseParseError("Invalid JSON", rawText);
+ * ```
+ */
+declare class VisualAIResponseParseError extends VisualAIError<"RESPONSE_PARSE_FAILED"> {
+    readonly code: "RESPONSE_PARSE_FAILED";
+    rawResponse: string;
+    constructor(message: string, rawResponse: string);
+}
+/**
+ * Thrown when library configuration is missing or invalid.
+ *
+ * @example
+ * ```ts
+ * throw new VisualAIConfigError("At least one statement is required for check()");
+ * ```
+ */
+declare class VisualAIConfigError extends VisualAIError<"CONFIG_INVALID"> {
+    readonly code: "CONFIG_INVALID";
+    constructor(message: string);
+}
+/**
+ * Thrown by assertion helpers when a visual check or comparison fails.
+ *
+ * Carries the failed `result` for further inspection.
+ *
+ * @example
+ * ```ts
+ * throw new VisualAIAssertionError("Visual assertion failed", result);
+ * ```
+ */
+declare class VisualAIAssertionError extends VisualAIError<"ASSERTION_FAILED"> {
+    readonly code: "ASSERTION_FAILED";
+    result: CheckResult | CompareResult;
+    constructor(message: string, result: CheckResult | CompareResult);
+}
+/**
+ * Union of all concrete error subclasses exposed by the library.
+ */
+type VisualAIKnownError = VisualAIAuthError | VisualAIRateLimitError | VisualAIProviderError | VisualAIImageError | VisualAIResponseParseError | VisualAIConfigError | VisualAIAssertionError;
+/**
+ * Narrows an unknown thrown value to the concrete visual-ai-assertions error union.
+ *
+ * Use this helper when you want `switch (error.code)` to narrow to subclass-specific fields.
+ *
+ * @param error Unknown thrown value.
+ * @returns `true` when the value is one of the concrete library error subclasses.
+ * @example
+ * ```ts
+ * try {
+ *   // ...
+ * } catch (error) {
+ *   if (isVisualAIKnownError(error)) {
+ *     switch (error.code) {
+ *       case "RATE_LIMITED":
+ *         console.error(error.retryAfter);
+ *         break;
+ *       case "PROVIDER_ERROR":
+ *         console.error(error.statusCode);
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function isVisualAIKnownError(error: unknown): error is VisualAIKnownError;
+
+/**
+ * Formats a check result into a readable multiline string for logs or test failures.
+ *
+ * @param result Structured result returned by `check()` or a template helper.
+ * @param label Optional label appended to the output header.
+ * @returns A human-readable summary of the check result.
+ * @example
+ * ```ts
+ * console.log(formatCheckResult(result, "Checkout page"));
+ * ```
+ */
+declare function formatCheckResult(result: CheckResult, label?: string): string;
+/**
+ * Formats a compare result into a readable multiline string for logs or test failures.
+ *
+ * @param result Structured result returned by `compare()`.
+ * @param label Optional label appended to the output header.
+ * @returns A human-readable summary of the compare result.
+ * @example
+ * ```ts
+ * console.log(formatCompareResult(result, "Before/after deploy"));
+ * ```
+ */
+declare function formatCompareResult(result: CompareResult, label?: string): string;
+/**
+ * Throws a `VisualAIAssertionError` when a check result did not pass.
+ *
+ * @param result Structured result returned by `check()` or a template helper.
+ * @param label Optional label appended to the assertion message.
+ * @returns Nothing when the result passes.
+ * @throws {VisualAIAssertionError} When `result.pass` is `false`.
+ * @example
+ * ```ts
+ * assertVisualResult(result, "Homepage");
+ * ```
+ */
+declare function assertVisualResult(result: CheckResult, label?: string): void;
+/**
+ * Throws a `VisualAIAssertionError` when a compare result did not pass.
+ *
+ * @param result Structured result returned by `compare()`.
+ * @param label Optional label appended to the assertion message.
+ * @returns Nothing when the result passes.
+ * @throws {VisualAIAssertionError} When `result.pass` is `false`.
+ * @example
+ * ```ts
+ * assertVisualCompareResult(result, "Login flow");
+ * ```
+ */
+declare function assertVisualCompareResult(result: CompareResult, label?: string): void;
+
+export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, Model, type PageLoadOptions, Provider, type ProviderName, type ReasoningEffort, type StatementResult, StatementResultSchema, type SupportedMimeType, type UsageInfo, UsageInfoSchema, VALID_PROVIDERS, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };