visual-ai-assertions 0.2.0

package/dist/index.js

@@ -0,0 +1,1349 @@
+// src/constants.ts
+var Provider = {
+  ANTHROPIC: "anthropic",
+  OPENAI: "openai",
+  GOOGLE: "google"
+};
+var Model = {
+  Anthropic: {
+    OPUS_4_6: "claude-opus-4-6",
+    SONNET_4_6: "claude-sonnet-4-6",
+    HAIKU_4_5: "claude-haiku-4-5"
+  },
+  OpenAI: {
+    GPT_5_4: "gpt-5.4",
+    GPT_5_4_PRO: "gpt-5.4-pro",
+    GPT_5_2: "gpt-5.2",
+    GPT_5_MINI: "gpt-5-mini"
+  },
+  Google: {
+    GEMINI_3_1_PRO_PREVIEW: "gemini-3.1-pro-preview",
+    GEMINI_3_FLASH_PREVIEW: "gemini-3-flash-preview"
+  }
+};
+var DEFAULT_MODELS = {
+  [Provider.ANTHROPIC]: Model.Anthropic.SONNET_4_6,
+  [Provider.OPENAI]: Model.OpenAI.GPT_5_MINI,
+  [Provider.GOOGLE]: Model.Google.GEMINI_3_FLASH_PREVIEW
+};
+var DEFAULT_MAX_TOKENS = 4096;
+var MODEL_TO_PROVIDER = new Map([
+  ...Object.values(Model.Anthropic).map((m) => [m, Provider.ANTHROPIC]),
+  ...Object.values(Model.OpenAI).map((m) => [m, Provider.OPENAI]),
+  ...Object.values(Model.Google).map((m) => [m, Provider.GOOGLE])
+]);
+var VALID_PROVIDERS = Object.values(Provider);
+var Content = {
+  /** Detects Lorem ipsum, TODO, TBD, and similar placeholder text */
+  PLACEHOLDER_TEXT: "placeholder-text",
+  /** Detects error messages, banners, stack traces, or error codes */
+  ERROR_MESSAGES: "error-messages",
+  /** Detects broken image icons or failed-to-load image indicators */
+  BROKEN_IMAGES: "broken-images",
+  /** Detects UI elements that unintentionally overlap and obscure content */
+  OVERLAPPING_ELEMENTS: "overlapping-elements"
+};
+var Layout = {
+  /** Detects elements that unintentionally overlap each other */
+  OVERLAP: "overlap",
+  /** Detects content cut off or extending beyond container boundaries */
+  OVERFLOW: "overflow",
+  /** Detects inconsistent alignment of text, images, and UI components */
+  ALIGNMENT: "alignment"
+};
+var Accessibility = {
+  /** Detects insufficient color contrast between text and backgrounds */
+  CONTRAST: "contrast",
+  /** Detects text that is cut off, overlapping, too small, or obscured */
+  READABILITY: "readability",
+  /** Detects interactive elements that are not visually distinct */
+  INTERACTIVE_VISIBILITY: "interactive-visibility"
+};
+
+// src/errors.ts
+var VisualAIError = class extends Error {
+  code;
+  constructor(message, code = "VISUAL_AI_ERROR") {
+    super(message);
+    this.code = code;
+    this.name = "VisualAIError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var VisualAIAuthError = class extends VisualAIError {
+  constructor(message) {
+    super(message, "AUTH_FAILED");
+    this.name = "VisualAIAuthError";
+  }
+};
+var VisualAIRateLimitError = class extends VisualAIError {
+  retryAfter;
+  constructor(message, retryAfter) {
+    super(message, "RATE_LIMITED");
+    this.name = "VisualAIRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var VisualAIProviderError = class extends VisualAIError {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message, "PROVIDER_ERROR");
+    this.name = "VisualAIProviderError";
+    this.statusCode = statusCode;
+  }
+};
+var VisualAIImageError = class extends VisualAIError {
+  constructor(message) {
+    super(message, "IMAGE_INVALID");
+    this.name = "VisualAIImageError";
+  }
+};
+var VisualAIResponseParseError = class extends VisualAIError {
+  rawResponse;
+  constructor(message, rawResponse) {
+    super(message, "RESPONSE_PARSE_FAILED");
+    this.name = "VisualAIResponseParseError";
+    this.rawResponse = rawResponse;
+  }
+};
+var VisualAIConfigError = class extends VisualAIError {
+  constructor(message) {
+    super(message, "CONFIG_INVALID");
+    this.name = "VisualAIConfigError";
+  }
+};
+var VisualAIAssertionError = class extends VisualAIError {
+  result;
+  constructor(message, result) {
+    super(message, "ASSERTION_FAILED");
+    this.name = "VisualAIAssertionError";
+    this.result = result;
+  }
+};
+function isVisualAIKnownError(error) {
+  return error instanceof VisualAIAuthError || error instanceof VisualAIRateLimitError || error instanceof VisualAIProviderError || error instanceof VisualAIImageError || error instanceof VisualAIResponseParseError || error instanceof VisualAIConfigError || error instanceof VisualAIAssertionError;
+}
+
+// src/core/prompt.ts
+var JSON_INSTRUCTIONS = `
+IMPORTANT: You MUST respond with valid JSON only. No markdown, no code blocks, no extra text.
+`;
+var ISSUE_SCHEMA_INSTRUCTIONS = `
+Each issue must have:
+- "priority": "critical" | "major" | "minor"
+- "category": "accessibility" | "missing-element" | "layout" | "content" | "styling" | "functionality" | "performance" | "other"
+- "description": what the issue is
+- "suggestion": how to fix or improve it
+`;
+var CHECK_OUTPUT_SCHEMA = `Respond with a JSON object matching this exact structure:
+{
+  "pass": boolean,          // true ONLY if ALL statements are true
+  "reasoning": string,      // brief overall summary (e.g. "3 of 4 checks passed...")
+  "issues": [...],          // list of issues found (empty if all pass)
+  "statements": [           // one entry per statement, in order
+    {
+      "statement": string,  // the original statement text
+      "pass": boolean,      // whether this statement is true
+      "reasoning": string,  // explanation for this statement
+      "confidence": "high" | "medium" | "low"
+        // high = clearly visible/absent with no ambiguity
+        // medium = present but partially obscured, small, or borderline
+        // low = cannot determine with certainty from the screenshot
+    }
+  ]
+}
+${ISSUE_SCHEMA_INSTRUCTIONS}
+
+Only include issues for statements that fail. If all statements pass, issues should be an empty array.
+
+Example for a failing check:
+{
+  "pass": false,
+  "reasoning": "1 of 2 checks failed. The submit button is not visible.",
+  "issues": [
+    { "priority": "major", "category": "missing-element", "description": "Submit button is not visible on the page", "suggestion": "Verify the submit button component is rendered and not hidden by CSS" }
+  ],
+  "statements": [
+    { "statement": "The page header is visible", "pass": true, "reasoning": "Header with logo is clearly visible at the top", "confidence": "high" },
+    { "statement": "The submit button is visible", "pass": false, "reasoning": "No submit button found in the visible area of the page", "confidence": "high" }
+  ]
+}
+${JSON_INSTRUCTIONS}`;
+var ASK_OUTPUT_SCHEMA = `Respond with a JSON object matching this exact structure:
+{
+  "summary": string,        // high-level analysis summary
+  "issues": [...]           // list of issues/findings, can be empty
+}
+${ISSUE_SCHEMA_INSTRUCTIONS}
+
+Prioritize issues by severity:
+- "critical": blocks functionality, breaks accessibility, data loss risk
+- "major": significant usability or visual problem
+- "minor": cosmetic issue, minor improvement suggestion
+
+Example:
+{
+  "summary": "Found 2 issues: a critical accessibility problem and a minor cosmetic issue.",
+  "issues": [
+    { "priority": "critical", "category": "accessibility", "description": "Submit button has insufficient color contrast", "suggestion": "Increase contrast so text is clearly readable against the background" },
+    { "priority": "minor", "category": "content", "description": "Placeholder text 'Lorem ipsum' visible in sidebar", "suggestion": "Replace with actual content or remove the placeholder section" }
+  ]
+}
+${JSON_INSTRUCTIONS}`;
+var COMPARE_OUTPUT_SCHEMA = `Respond with a JSON object matching this exact structure:
+{
+  "pass": boolean,          // true if no critical or major changes found
+  "reasoning": string,      // overall summary of changes detected
+  "changes": [              // list of all visual differences detected (empty if images are identical)
+    {
+      "description": string,  // what changed between the images
+      "severity": "critical" | "major" | "minor"
+        // critical = element removed, layout broken, functionality lost
+        // major = significant visual change that may be unintentional
+        // minor = small stylistic difference (color, spacing, font)
+    }
+  ]
+}
+
+If the images appear identical, set pass to true, explain in reasoning, and return an empty changes array.
+${JSON_INSTRUCTIONS}`;
+var DEFAULT_CHECK_ROLE = "You are a visual QA assistant. Evaluate the provided image precisely and objectively.";
+var DEFAULT_ASK_ROLE = "You are a visual QA assistant. Analyze the provided image based on the user's request.";
+var COMPARE_ROLE = "You are performing a visual regression test. Compare the BEFORE image (baseline) to the AFTER image (current) and identify all visual differences. Flag changes that appear unintentional or problematic.";
+var COMPARE_EDGE_RULES = [
+  "The BEFORE image is the baseline/expected state.",
+  "Flag removals and layout changes as higher severity. Color and spacing changes are lower severity unless they break readability.",
+  "If the images appear identical, report no changes and pass."
+];
+function buildInstructionsSection(instructions) {
+  return "Additional instructions:\n" + instructions.map((instruction) => `- ${instruction}`).join("\n");
+}
+function buildCheckPrompt(statements, options) {
+  const stmts = Array.isArray(statements) ? statements : [statements];
+  const statementsBlock = stmts.map((s, i) => `${i + 1}. "${s}"`).join("\n");
+  const sections = [options?.role ?? DEFAULT_CHECK_ROLE];
+  if (options?.instructions && options.instructions.length > 0) {
+    sections.push(buildInstructionsSection(options.instructions));
+  }
+  sections.push(`Statements to evaluate:
+${statementsBlock}`);
+  sections.push(CHECK_OUTPUT_SCHEMA);
+  return sections.join("\n\n");
+}
+function buildAskPrompt(userPrompt, options) {
+  const sections = [DEFAULT_ASK_ROLE];
+  if (options?.instructions && options.instructions.length > 0) {
+    sections.push(buildInstructionsSection(options.instructions));
+  }
+  sections.push(`User request: ${userPrompt}`);
+  sections.push(ASK_OUTPUT_SCHEMA);
+  return sections.join("\n\n");
+}
+function buildAiDiffPrompt() {
+  return `You are given two screenshots of the same page or component.
+Generate a single annotated image that clearly highlights the visual differences between the first and second images.
+- Overlay semi-transparent red rectangles or outlines on areas that changed
+- Keep unchanged areas visible but slightly dimmed
+- The output image should match the dimensions of the input images
+- Focus on meaningful visual differences: layout shifts, missing elements, color changes, text differences`;
+}
+function buildAiDiffCodeExecutionPrompt() {
+  return `${buildAiDiffPrompt()}
+
+Write Python code using PIL/Pillow for image processing and matplotlib for rendering to accomplish the above.
+Your code MUST load both input images and display the result using matplotlib.`;
+}
+function buildComparePrompt(options) {
+  const evaluation = options?.userPrompt ? `User request: ${options.userPrompt}` : "Identify all visual differences between the baseline and current screenshot. Flag any changes that appear unintentional or problematic.";
+  const instructions = options?.instructions ? [...COMPARE_EDGE_RULES, ...options.instructions] : COMPARE_EDGE_RULES;
+  const sections = [
+    COMPARE_ROLE,
+    buildInstructionsSection(instructions),
+    evaluation,
+    COMPARE_OUTPUT_SCHEMA
+  ];
+  return sections.join("\n\n");
+}
+
+// src/templates/elements-visibility.ts
+var ELEMENTS_VISIBLE_ROLE = "Check whether specific UI elements are present and fully visible in this screenshot.";
+var ELEMENTS_HIDDEN_ROLE = "Check whether specific UI elements are absent or hidden in this screenshot.";
+var ELEMENTS_VISIBLE_EDGE_RULES = [
+  "If an element is partially visible (cut off by screenshot boundary), it is NOT considered fully visible \u2014 the check for that element should fail. Note the partial visibility in your reasoning."
+];
+var ELEMENTS_HIDDEN_EDGE_RULES = [
+  "If an element is partially visible (cut off by screenshot boundary), it is NOT considered hidden \u2014 the check for that element should fail. Note the partial visibility in your reasoning."
+];
+function buildElementsVisibilityPrompt(elements, visible, options) {
+  const statements = visible ? elements.map((el) => `The element "${el}" is fully visible on the page`) : elements.map((el) => `The element "${el}" is NOT visible on the page`);
+  const defaultRules = visible ? ELEMENTS_VISIBLE_EDGE_RULES : ELEMENTS_HIDDEN_EDGE_RULES;
+  const instructions = options?.instructions ? [...defaultRules, ...options.instructions] : defaultRules;
+  return buildCheckPrompt(statements, {
+    role: visible ? ELEMENTS_VISIBLE_ROLE : ELEMENTS_HIDDEN_ROLE,
+    instructions
+  });
+}
+
+// src/templates/accessibility.ts
+var ALL_CHECKS = Object.values(Accessibility);
+var ACCESSIBILITY_ROLE = "Evaluate this screenshot for visual accessibility. Focus on what you can actually perceive \u2014 apparent contrast levels, text legibility, and visual distinctiveness of interactive elements.";
+var ACCESSIBILITY_EDGE_RULES = [
+  "Do not state specific contrast ratios. Describe contrast as 'appears sufficient' or 'appears low'.",
+  "Dark mode and light mode themes are both valid. Do not flag a valid dark theme as a contrast issue."
+];
+var CHECK_STATEMENTS = {
+  [Accessibility.CONTRAST]: "All text and interactive elements appear to have sufficient color contrast \u2014 text is clearly readable against its background",
+  [Accessibility.READABILITY]: "All text is readable \u2014 no text is cut off, overlapping, too small to read, or obscured by background images",
+  [Accessibility.INTERACTIVE_VISIBILITY]: "All interactive elements (buttons, links, inputs) are clearly identifiable and visually distinct from non-interactive content"
+};
+function buildAccessibilityPrompt(options) {
+  const checks = options?.checks ?? [...ALL_CHECKS];
+  const statements = checks.map((c) => CHECK_STATEMENTS[c]);
+  const instructions = options?.instructions ? [...ACCESSIBILITY_EDGE_RULES, ...options.instructions] : ACCESSIBILITY_EDGE_RULES;
+  return buildCheckPrompt(statements, {
+    role: ACCESSIBILITY_ROLE,
+    instructions
+  });
+}
+
+// src/templates/layout.ts
+var ALL_CHECKS2 = Object.values(Layout);
+var LAYOUT_ROLE = "Evaluate this screenshot for visual layout problems \u2014 overlapping elements, content that appears cut off or overflowing, and inconsistent alignment patterns.";
+var LAYOUT_EDGE_RULES = [
+  "Intentional overlaps (stacked avatars, dropdown menus, overlapping cards) are acceptable. Flag only overlaps that obscure content or appear broken.",
+  "Scrollable containers with partially visible content are not overflow issues."
+];
+var CHECK_STATEMENTS2 = {
+  [Layout.OVERLAP]: "No elements overlap each other unintentionally \u2014 all content is clearly separated and readable",
+  [Layout.OVERFLOW]: "No content appears to be unintentionally cut off or extending beyond its container boundaries",
+  [Layout.ALIGNMENT]: "Elements are properly aligned \u2014 text, images, and UI components follow a consistent grid or alignment pattern"
+};
+function buildLayoutPrompt(options) {
+  const checks = options?.checks ?? [...ALL_CHECKS2];
+  const statements = checks.map((c) => CHECK_STATEMENTS2[c]);
+  const instructions = options?.instructions ? [...LAYOUT_EDGE_RULES, ...options.instructions] : LAYOUT_EDGE_RULES;
+  return buildCheckPrompt(statements, { role: LAYOUT_ROLE, instructions });
+}
+
+// src/templates/page-load.ts
+var PAGE_LOAD_ROLE = "Evaluate whether this page has finished loading. Look for loading indicators, empty content areas, and missing resources.";
+function buildPageLoadPrompt(options) {
+  const expectLoaded = options?.expectLoaded ?? true;
+  const statements = expectLoaded ? [
+    "The page content has finished loading \u2014 no spinning indicators, skeleton placeholders, or progress bars are visible",
+    "The main content area has actual content displayed (not blank or empty)",
+    "No broken image icons or missing resource indicators are visible"
+  ] : [
+    "The page shows a loading state \u2014 loading spinners, skeleton screens, or progress indicators are visible"
+  ];
+  return buildCheckPrompt(statements, {
+    role: PAGE_LOAD_ROLE,
+    instructions: options?.instructions
+  });
+}
+
+// src/templates/content.ts
+var ALL_CHECKS3 = Object.values(Content);
+var CONTENT_ROLE = "Evaluate this screenshot for content quality problems \u2014 placeholder or dummy content, error states, and broken resources that should not appear in a production UI.";
+var CHECK_STATEMENTS3 = {
+  [Content.PLACEHOLDER_TEXT]: "No placeholder text like 'Lorem ipsum', 'TODO', 'TBD', 'placeholder', or similar dummy content is visible on the page",
+  [Content.ERROR_MESSAGES]: "No error messages, error banners, stack traces, or error codes are visible on the page",
+  [Content.BROKEN_IMAGES]: "No broken image icons, missing image placeholders, or failed-to-load image indicators are visible",
+  [Content.OVERLAPPING_ELEMENTS]: "No UI elements are unintentionally overlapping each other, obscuring text, buttons, or other interactive content"
+};
+function buildContentPrompt(options) {
+  const checks = options?.checks ?? [...ALL_CHECKS3];
+  const statements = checks.map((c) => CHECK_STATEMENTS3[c]);
+  return buildCheckPrompt(statements, {
+    role: CONTENT_ROLE,
+    instructions: options?.instructions
+  });
+}
+
+// src/providers/error-mapper.ts
+function mapProviderError(err) {
+  if (!(err instanceof Error)) {
+    return new VisualAIProviderError(String(err));
+  }
+  const status = err.status;
+  if (status === 401 || status === 403) {
+    return new VisualAIAuthError(err.message);
+  }
+  if (status === 429) {
+    const headers = err.headers;
+    const retryAfter = parseRetryAfter(headers?.["retry-after"]);
+    return new VisualAIRateLimitError(err.message, retryAfter);
+  }
+  if (status !== void 0) {
+    return new VisualAIProviderError(err.message, status);
+  }
+  return new VisualAIProviderError(err.message);
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  return Number.isFinite(seconds) ? seconds : void 0;
+}
+
+// src/providers/anthropic.ts
+var AnthropicDriver = class {
+  client;
+  model;
+  maxTokens;
+  apiKeyOrEnv;
+  reasoningEffort;
+  constructor(config) {
+    this.model = config.model;
+    this.maxTokens = config.maxTokens;
+    this.client = null;
+    this.apiKeyOrEnv = config.apiKey;
+    this.reasoningEffort = config.reasoningEffort;
+  }
+  async getClient() {
+    if (this.client) return this.client;
+    let Anthropic;
+    try {
+      const mod = await import("@anthropic-ai/sdk");
+      Anthropic = mod.default;
+    } catch {
+      throw new VisualAIConfigError(
+        "Anthropic SDK not installed. Run: npm install @anthropic-ai/sdk"
+      );
+    }
+    const apiKey = this.apiKeyOrEnv ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new VisualAIAuthError(
+        "Anthropic API key not found. Set ANTHROPIC_API_KEY or pass apiKey in config."
+      );
+    }
+    this.client = new Anthropic({ apiKey });
+    return this.client;
+  }
+  async sendMessage(images, prompt) {
+    const client = await this.getClient();
+    const imageBlocks = images.map((img) => ({
+      type: "image",
+      source: {
+        type: "base64",
+        media_type: img.mimeType,
+        data: img.base64
+      }
+    }));
+    try {
+      const requestParams = {
+        model: this.model,
+        max_tokens: this.maxTokens,
+        messages: [
+          {
+            role: "user",
+            content: [...imageBlocks, { type: "text", text: prompt }]
+          }
+        ]
+      };
+      if (this.reasoningEffort) {
+        requestParams.thinking = { type: "adaptive" };
+        requestParams.output_config = {
+          effort: this.reasoningEffort === "xhigh" ? "max" : this.reasoningEffort
+        };
+      }
+      const message = await client.messages.create(requestParams);
+      const textBlock = message.content.find((block) => block.type === "text");
+      const text = textBlock?.text ?? "";
+      return {
+        text,
+        usage: {
+          inputTokens: message.usage.input_tokens,
+          outputTokens: message.usage.output_tokens
+        }
+      };
+    } catch (err) {
+      throw mapProviderError(err);
+    }
+  }
+};
+
+// src/providers/google.ts
+var DEFAULT_IMAGE_GEN_MODEL = "gemini-2.5-flash-image";
+function needsCodeExecution(model) {
+  const match = model.match(/^gemini-(\d+)/);
+  return match !== null && match[1] !== void 0 && parseInt(match[1], 10) >= 3;
+}
+var GOOGLE_THINKING_BUDGET = {
+  low: 1024,
+  medium: 8192,
+  high: 24576,
+  xhigh: 24576
+};
+var GoogleDriver = class {
+  client;
+  model;
+  maxTokens;
+  apiKeyOrEnv;
+  reasoningEffort;
+  constructor(config) {
+    this.model = config.model;
+    this.maxTokens = config.maxTokens;
+    this.client = null;
+    this.apiKeyOrEnv = config.apiKey;
+    this.reasoningEffort = config.reasoningEffort;
+  }
+  toGeminiParts(images) {
+    return images.map((img) => ({
+      inlineData: { data: img.base64, mimeType: img.mimeType }
+    }));
+  }
+  async getClient() {
+    if (this.client) return this.client;
+    let GoogleGenAI;
+    try {
+      const mod = await import("@google/genai");
+      GoogleGenAI = mod.GoogleGenAI;
+    } catch {
+      throw new VisualAIConfigError(
+        "Google GenAI SDK not installed. Run: npm install @google/genai"
+      );
+    }
+    const apiKey = this.apiKeyOrEnv ?? process.env.GOOGLE_API_KEY;
+    if (!apiKey) {
+      throw new VisualAIAuthError(
+        "Google API key not found. Set GOOGLE_API_KEY or pass apiKey in config."
+      );
+    }
+    this.client = new GoogleGenAI({ apiKey });
+    return this.client;
+  }
+  async sendMessage(images, prompt) {
+    const client = await this.getClient();
+    try {
+      const response = await client.models.generateContent({
+        model: this.model,
+        contents: [...this.toGeminiParts(images), prompt],
+        config: {
+          responseMimeType: "application/json",
+          maxOutputTokens: this.maxTokens,
+          ...this.reasoningEffort && {
+            thinkingConfig: {
+              thinkingBudget: GOOGLE_THINKING_BUDGET[this.reasoningEffort]
+            }
+          }
+        }
+      });
+      const text = response.text ?? "";
+      return {
+        text,
+        usage: response.usageMetadata ? {
+          inputTokens: response.usageMetadata.promptTokenCount ?? 0,
+          outputTokens: response.usageMetadata.candidatesTokenCount ?? 0
+        } : void 0
+      };
+    } catch (err) {
+      throw mapProviderError(err);
+    }
+  }
+  async generateImage(images, prompt, options) {
+    const client = await this.getClient();
+    const imageModel = options?.model ?? DEFAULT_IMAGE_GEN_MODEL;
+    const resolvedPrompt = options?.promptKind === "ai-diff" && needsCodeExecution(imageModel) ? buildAiDiffCodeExecutionPrompt() : prompt;
+    const config = needsCodeExecution(imageModel) ? { tools: [{ codeExecution: {} }] } : { responseModalities: ["TEXT", "IMAGE"] };
+    try {
+      const response = await client.models.generateContent({
+        model: imageModel,
+        contents: [...this.toGeminiParts(images), resolvedPrompt],
+        config
+      });
+      const parts = response.candidates?.[0]?.content?.parts;
+      if (!parts) {
+        throw new VisualAIProviderError("Gemini image generation returned no response parts");
+      }
+      const imagePart = parts.find((p) => p.inlineData?.data);
+      if (!imagePart?.inlineData) {
+        throw new VisualAIProviderError(
+          "Gemini image generation returned no image data. Ensure the model supports image output."
+        );
+      }
+      return {
+        imageData: Buffer.from(imagePart.inlineData.data, "base64"),
+        mimeType: imagePart.inlineData.mimeType,
+        usage: response.usageMetadata ? {
+          inputTokens: response.usageMetadata.promptTokenCount ?? 0,
+          outputTokens: response.usageMetadata.candidatesTokenCount ?? 0
+        } : void 0
+      };
+    } catch (err) {
+      if (err instanceof VisualAIProviderError) throw err;
+      throw mapProviderError(err);
+    }
+  }
+};
+
+// src/providers/openai.ts
+var OpenAIDriver = class {
+  client;
+  model;
+  maxTokens;
+  apiKeyOrEnv;
+  reasoningEffort;
+  constructor(config) {
+    this.model = config.model;
+    this.maxTokens = config.maxTokens;
+    this.client = null;
+    this.apiKeyOrEnv = config.apiKey;
+    this.reasoningEffort = config.reasoningEffort;
+  }
+  async getClient() {
+    if (this.client) return this.client;
+    let OpenAI;
+    try {
+      const mod = await import("openai");
+      OpenAI = mod.default;
+    } catch {
+      throw new VisualAIConfigError("OpenAI SDK not installed. Run: npm install openai");
+    }
+    const apiKey = this.apiKeyOrEnv ?? process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new VisualAIAuthError(
+        "OpenAI API key not found. Set OPENAI_API_KEY or pass apiKey in config."
+      );
+    }
+    this.client = new OpenAI({ apiKey });
+    return this.client;
+  }
+  async sendMessage(images, prompt) {
+    const client = await this.getClient();
+    const imageBlocks = images.map((img) => ({
+      type: "input_image",
+      image_url: `data:${img.mimeType};base64,${img.base64}`
+    }));
+    try {
+      const requestParams = {
+        model: this.model,
+        max_output_tokens: this.maxTokens,
+        text: { format: { type: "json_object" } },
+        input: [
+          {
+            role: "user",
+            content: [...imageBlocks, { type: "input_text", text: prompt }]
+          }
+        ]
+      };
+      if (this.reasoningEffort) {
+        requestParams.reasoning = { effort: this.reasoningEffort };
+      }
+      const response = await client.responses.create(requestParams);
+      const text = response.output_text ?? "";
+      return {
+        text,
+        usage: response.usage ? {
+          inputTokens: response.usage.input_tokens,
+          outputTokens: response.usage.output_tokens
+        } : void 0
+      };
+    } catch (err) {
+      throw mapProviderError(err);
+    }
+  }
+};
+
+// src/core/config.ts
+var MODEL_PREFIX_TO_PROVIDER = [
+  ["claude-", "anthropic"],
+  ["gpt-", "openai"],
+  ["o1-", "openai"],
+  ["o3-", "openai"],
+  ["o4-", "openai"],
+  ["gemini-", "google"]
+];
+function inferProviderFromModel(model) {
+  const known = MODEL_TO_PROVIDER.get(model);
+  if (known) return known;
+  const prefixMatch = MODEL_PREFIX_TO_PROVIDER.find(([prefix]) => model.startsWith(prefix));
+  return prefixMatch?.[1];
+}
+function resolveProvider(config) {
+  if (config.provider) {
+    if (!VALID_PROVIDERS.includes(config.provider)) {
+      throw new VisualAIConfigError(
+        `Unknown provider: "${config.provider}". Supported: ${VALID_PROVIDERS.join(", ")}`
+      );
+    }
+    return config.provider;
+  }
+  const envProvider = process.env.VISUAL_AI_PROVIDER;
+  if (envProvider) {
+    if (VALID_PROVIDERS.includes(envProvider)) {
+      return envProvider;
+    }
+    throw new VisualAIConfigError(
+      `Invalid VISUAL_AI_PROVIDER: "${envProvider}". Supported: ${VALID_PROVIDERS.join(", ")}`
+    );
+  }
+  const model = config.model ?? process.env.VISUAL_AI_MODEL;
+  if (model) {
+    const inferred = inferProviderFromModel(model);
+    if (inferred) return inferred;
+  }
+  const apiKeyProviderMap = [
+    ["ANTHROPIC_API_KEY", "anthropic"],
+    ["OPENAI_API_KEY", "openai"],
+    ["GOOGLE_API_KEY", "google"]
+  ];
+  const detected = apiKeyProviderMap.find(([key]) => process.env[key]);
+  if (detected) return detected[1];
+  throw new VisualAIConfigError(
+    "No provider specified. Set `provider` in config, `VISUAL_AI_PROVIDER` env variable, or an API key env variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY)."
+  );
+}
+function parseBooleanEnv(envName, value) {
+  if (value === void 0 || value === "") return void 0;
+  const lower = value.toLowerCase();
+  if (lower === "true" || lower === "1") return true;
+  if (lower === "false" || lower === "0") return false;
+  throw new VisualAIConfigError(
+    `Invalid ${envName} value: "${value}". Use "true", "1", "false", or "0".`
+  );
+}
+function resolveConfig(config) {
+  const provider = resolveProvider(config);
+  const model = config.model ?? process.env.VISUAL_AI_MODEL ?? DEFAULT_MODELS[provider];
+  const modelProvider = inferProviderFromModel(model);
+  if (modelProvider && modelProvider !== provider) {
+    throw new VisualAIConfigError(
+      `Model "${model}" appears to be a ${modelProvider} model, but provider is "${provider}". Either change the provider or use a ${provider}-compatible model.`
+    );
+  }
+  return {
+    provider,
+    apiKey: config.apiKey,
+    model,
+    maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
+    reasoningEffort: config.reasoningEffort,
+    debug: config.debug ?? parseBooleanEnv("VISUAL_AI_DEBUG", process.env.VISUAL_AI_DEBUG) ?? false,
+    trackUsage: config.trackUsage ?? parseBooleanEnv("VISUAL_AI_TRACK_USAGE", process.env.VISUAL_AI_TRACK_USAGE) ?? false
+  };
+}
+
+// src/core/pricing.ts
+var PER_MILLION = 1e6;
+var PRICING_TABLE = {
+  [`${Provider.ANTHROPIC}:${Model.Anthropic.OPUS_4_6}`]: {
+    inputPricePerToken: 5 / PER_MILLION,
+    outputPricePerToken: 25 / PER_MILLION
+  },
+  [`${Provider.ANTHROPIC}:${Model.Anthropic.SONNET_4_6}`]: {
+    inputPricePerToken: 3 / PER_MILLION,
+    outputPricePerToken: 15 / PER_MILLION
+  },
+  [`${Provider.ANTHROPIC}:${Model.Anthropic.HAIKU_4_5}`]: {
+    inputPricePerToken: 1 / PER_MILLION,
+    outputPricePerToken: 5 / PER_MILLION
+  },
+  [`${Provider.OPENAI}:${Model.OpenAI.GPT_5_4}`]: {
+    inputPricePerToken: 2.5 / PER_MILLION,
+    outputPricePerToken: 15 / PER_MILLION
+  },
+  [`${Provider.OPENAI}:${Model.OpenAI.GPT_5_4_PRO}`]: {
+    inputPricePerToken: 30 / PER_MILLION,
+    outputPricePerToken: 180 / PER_MILLION
+  },
+  [`${Provider.OPENAI}:${Model.OpenAI.GPT_5_2}`]: {
+    inputPricePerToken: 1.75 / PER_MILLION,
+    outputPricePerToken: 14 / PER_MILLION
+  },
+  [`${Provider.OPENAI}:${Model.OpenAI.GPT_5_MINI}`]: {
+    inputPricePerToken: 0.25 / PER_MILLION,
+    outputPricePerToken: 2 / PER_MILLION
+  },
+  [`${Provider.GOOGLE}:${Model.Google.GEMINI_3_1_PRO_PREVIEW}`]: {
+    inputPricePerToken: 2 / PER_MILLION,
+    outputPricePerToken: 12 / PER_MILLION
+  },
+  [`${Provider.GOOGLE}:${Model.Google.GEMINI_3_FLASH_PREVIEW}`]: {
+    inputPricePerToken: 0.5 / PER_MILLION,
+    outputPricePerToken: 3 / PER_MILLION
+  }
+};
+function calculateCost(provider, model, inputTokens, outputTokens) {
+  const key = `${provider}:${model}`;
+  const pricing = PRICING_TABLE[key];
+  if (!pricing) return void 0;
+  return inputTokens * pricing.inputPricePerToken + outputTokens * pricing.outputPricePerToken;
+}
+
+// src/core/debug.ts
+function debugLog(config, label, data) {
+  if (config.debug) {
+    process.stderr.write(`[visual-ai-assertions] ${label}: ${data}
+`);
+  }
+}
+function usageLog(config, method, usage) {
+  if (!config.trackUsage) return;
+  const costStr = usage.estimatedCost !== void 0 ? `$${usage.estimatedCost.toFixed(6)}` : "unknown";
+  process.stderr.write(
+    `[visual-ai-assertions] ${method} usage: ${usage.inputTokens} input + ${usage.outputTokens} output tokens (${costStr}) in ${usage.durationSeconds?.toFixed(3) ?? "0.000"}s [${config.model}]
+`
+  );
+}
+function processUsage(method, rawUsage, durationSeconds, config) {
+  const inputTokens = rawUsage?.inputTokens ?? 0;
+  const outputTokens = rawUsage?.outputTokens ?? 0;
+  const usage = {
+    inputTokens,
+    outputTokens,
+    estimatedCost: calculateCost(config.provider, config.model, inputTokens, outputTokens),
+    durationSeconds
+  };
+  usageLog(config, method, usage);
+  return usage;
+}
+async function timedSendMessage(driver, images, prompt) {
+  const start = performance.now();
+  const response = await driver.sendMessage(images, prompt);
+  const durationSeconds = (performance.now() - start) / 1e3;
+  return { ...response, durationSeconds };
+}
+
+// src/core/diff.ts
+import sharp from "sharp";
+async function generateAiDiff(imgA, imgB, model, driver) {
+  if (!driver.generateImage) {
+    throw new VisualAIConfigError(
+      "AI-generated diff images require a provider that supports image generation. Currently only the Google (Gemini) provider supports this."
+    );
+  }
+  if (model !== Model.Google.GEMINI_3_FLASH_PREVIEW) {
+    throw new VisualAIConfigError(
+      "Annotated diff images are only supported when visualAI is configured with the Google model gemini-3-flash-preview."
+    );
+  }
+  const response = await driver.generateImage([imgA, imgB], buildAiDiffPrompt(), {
+    model,
+    promptKind: "ai-diff"
+  });
+  const img = sharp(response.imageData);
+  const meta = await img.metadata();
+  const pngData = await img.png().toBuffer();
+  return {
+    data: pngData,
+    width: meta.width ?? 0,
+    height: meta.height ?? 0,
+    mimeType: "image/png"
+  };
+}
+
+// src/core/image.ts
+import { readFile } from "fs/promises";
+import { extname } from "path";
+import sharp2 from "sharp";
+var SUPPORTED_FORMATS = /* @__PURE__ */ new Set([
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "image/gif"
+]);
+var EXTENSION_TO_MIME = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".gif": "image/gif"
+};
+var MAX_DIMENSION = 1568;
+var URL_FETCH_TIMEOUT_MS = 1e4;
+function isSupportedMimeType(value) {
+  return SUPPORTED_FORMATS.has(value);
+}
+function getMimeFromExtension(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  return EXTENSION_TO_MIME[ext];
+}
+function isFilePath(input) {
+  return input.startsWith("/") || input.startsWith("./") || input.startsWith("../") || input.includes("\\");
+}
+function isUrl(input) {
+  return input.startsWith("http://") || input.startsWith("https://");
+}
+function isBase64Image(input) {
+  return input.startsWith("iVBOR") || // PNG  (0x89 0x50 0x4E 0x47)
+  input.startsWith("/9j/") || // JPEG (0xFF 0xD8 0xFF)
+  input.startsWith("R0lGOD") || // GIF  (0x47 0x49 0x46)
+  input.startsWith("UklGR");
+}
+function detectMimeType(data) {
+  if (data[0] === 255 && data[1] === 216 && data[2] === 255) {
+    return "image/jpeg";
+  }
+  if (data[0] === 137 && data[1] === 80 && data[2] === 78 && data[3] === 71) {
+    return "image/png";
+  }
+  if (data[0] === 82 && data[1] === 73 && data[2] === 70 && data[3] === 70 && data[8] === 87 && data[9] === 69 && data[10] === 66 && data[11] === 80) {
+    return "image/webp";
+  }
+  if (data[0] === 71 && data[1] === 73 && data[2] === 70) {
+    return "image/gif";
+  }
+  throw new VisualAIImageError("Unable to detect image format from file content");
+}
+async function resizeIfNeeded(data, mimeType) {
+  if (mimeType === "image/gif") {
+    return data;
+  }
+  if (mimeType === "image/png" && data.length >= 24) {
+    const width2 = data.readUInt32BE(16);
+    const height2 = data.readUInt32BE(20);
+    if (width2 <= MAX_DIMENSION && height2 <= MAX_DIMENSION) {
+      return data;
+    }
+  }
+  const pipeline = sharp2(data);
+  const metadata = await pipeline.metadata();
+  const width = metadata.width ?? 0;
+  const height = metadata.height ?? 0;
+  if (width <= MAX_DIMENSION && height <= MAX_DIMENSION) {
+    return data;
+  }
+  return pipeline.resize({
+    width: MAX_DIMENSION,
+    height: MAX_DIMENSION,
+    fit: "inside",
+    withoutEnlargement: true
+  }).toBuffer();
+}
+async function loadFromFilePath(filePath) {
+  let fileData;
+  try {
+    fileData = await readFile(filePath);
+  } catch (err) {
+    throw new VisualAIImageError(
+      `Failed to read image file: ${filePath} \u2014 ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const mimeType = getMimeFromExtension(filePath) ?? detectMimeType(fileData);
+  return { data: fileData, mimeType };
+}
+async function loadFromUrl(url) {
+  let response;
+  try {
+    response = await fetch(url, {
+      signal: AbortSignal.timeout(URL_FETCH_TIMEOUT_MS)
+    });
+  } catch (err) {
+    throw new VisualAIImageError(
+      `Failed to fetch image from URL: ${url} \u2014 ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!response.ok) {
+    throw new VisualAIImageError(
+      `Failed to fetch image from URL: ${url} \u2014 HTTP ${response.status}`
+    );
+  }
+  const arrayBuffer = await response.arrayBuffer();
+  const data = Buffer.from(arrayBuffer);
+  const contentType = response.headers.get("content-type")?.split(";")[0]?.trim() ?? null;
+  const mimeType = contentType && isSupportedMimeType(contentType) ? contentType : detectMimeType(data);
+  return { data, mimeType };
+}
+function loadFromBase64(input) {
+  let base64Data = input;
+  let mimeType;
+  if (input.startsWith("data:")) {
+    const match = /^data:(image\/[^;]+);base64,(.+)$/.exec(input);
+    if (!match?.[1] || !match[2]) {
+      throw new VisualAIImageError("Invalid data URL format");
+    }
+    if (!isSupportedMimeType(match[1])) {
+      throw new VisualAIImageError(`Unsupported image format: ${match[1]}`);
+    }
+    mimeType = match[1];
+    base64Data = match[2];
+  }
+  if (!/^[A-Za-z0-9+/\n\r]+=*$/.test(base64Data)) {
+    throw new VisualAIImageError("Invalid base64 string");
+  }
+  const data = Buffer.from(base64Data, "base64");
+  if (data.length === 0) {
+    throw new VisualAIImageError("Empty image data after base64 decode");
+  }
+  return { data, mimeType: mimeType ?? detectMimeType(data) };
+}
+async function normalizeImage(input) {
+  let data;
+  let mimeType;
+  if (Buffer.isBuffer(input)) {
+    mimeType = detectMimeType(input);
+    data = input;
+  } else if (input instanceof Uint8Array) {
+    const buf = Buffer.from(input);
+    mimeType = detectMimeType(buf);
+    data = buf;
+  } else if (typeof input === "string") {
+    if (isUrl(input)) {
+      ({ data, mimeType } = await loadFromUrl(input));
+    } else if (input.startsWith("data:")) {
+      ({ data, mimeType } = loadFromBase64(input));
+    } else if (isBase64Image(input)) {
+      ({ data, mimeType } = loadFromBase64(input));
+    } else if (isFilePath(input)) {
+      ({ data, mimeType } = await loadFromFilePath(input));
+    } else {
+      throw new VisualAIImageError(
+        `Unrecognized image input: "${input.slice(0, 80)}". Expected a file path, URL, data URL, or base64-encoded image string.`
+      );
+    }
+  } else {
+    throw new VisualAIImageError(
+      "Invalid image input: expected Buffer, Uint8Array, file path, URL, or base64 string"
+    );
+  }
+  data = await resizeIfNeeded(data, mimeType);
+  let cachedBase64;
+  return {
+    data,
+    mimeType,
+    get base64() {
+      if (cachedBase64 === void 0) {
+        cachedBase64 = data.toString("base64");
+      }
+      return cachedBase64;
+    }
+  };
+}
+
+// src/types.ts
+import { z } from "zod";
+var IssuePrioritySchema = z.enum(["critical", "major", "minor"]);
+var IssueCategorySchema = z.enum([
+  "accessibility",
+  "missing-element",
+  "layout",
+  "content",
+  "styling",
+  "functionality",
+  "performance",
+  "other"
+]);
+var IssueSchema = z.object({
+  priority: IssuePrioritySchema,
+  category: IssueCategorySchema,
+  description: z.string(),
+  suggestion: z.string()
+});
+var ConfidenceSchema = z.enum(["high", "medium", "low"]);
+var StatementResultSchema = z.object({
+  statement: z.string(),
+  pass: z.boolean(),
+  reasoning: z.string(),
+  confidence: ConfidenceSchema.optional()
+});
+var UsageInfoSchema = z.object({
+  inputTokens: z.number(),
+  outputTokens: z.number(),
+  estimatedCost: z.number().optional(),
+  durationSeconds: z.number().nonnegative().optional()
+});
+var BaseResultSchema = z.object({
+  pass: z.boolean(),
+  reasoning: z.string(),
+  usage: UsageInfoSchema.optional()
+});
+var CheckResultSchema = BaseResultSchema.extend({
+  issues: z.array(IssueSchema),
+  statements: z.array(StatementResultSchema)
+});
+var ChangeEntrySchema = z.object({
+  description: z.string(),
+  severity: IssuePrioritySchema
+});
+var CompareResultSchema = BaseResultSchema.extend({
+  changes: z.array(ChangeEntrySchema).max(50)
+});
+var AskResultSchema = z.object({
+  summary: z.string(),
+  issues: z.array(IssueSchema),
+  usage: UsageInfoSchema.optional()
+});
+
+// src/core/response.ts
+function stripCodeFences(text) {
+  const trimmed = text.trim();
+  const match = /^```(?:json)?\s*\n?([\s\S]*?)\n?\s*```$/s.exec(trimmed);
+  return match?.[1] ?? trimmed;
+}
+var CheckResponseSchema = CheckResultSchema.omit({ usage: true });
+var AskResponseSchema = AskResultSchema.omit({ usage: true });
+var CompareResponseSchema = CompareResultSchema.omit({ usage: true });
+function parseResponse(raw, schema) {
+  let parsed;
+  try {
+    parsed = JSON.parse(stripCodeFences(raw));
+  } catch {
+    throw new VisualAIResponseParseError(
+      `Failed to parse AI response as JSON: ${raw.slice(0, 200)}`,
+      raw
+    );
+  }
+  const result = schema.safeParse(parsed);
+  if (!result.success) {
+    throw new VisualAIResponseParseError(
+      `AI response does not match expected schema: ${result.error.message}`,
+      raw
+    );
+  }
+  return result.data;
+}
+function parseCheckResponse(raw) {
+  return parseResponse(raw, CheckResponseSchema);
+}
+function parseAskResponse(raw) {
+  return parseResponse(raw, AskResponseSchema);
+}
+function parseCompareResponse(raw) {
+  return parseResponse(raw, CompareResponseSchema);
+}
+
+// src/core/client.ts
+var PROVIDER_REGISTRY = {
+  anthropic: (config) => new AnthropicDriver(config),
+  openai: (config) => new OpenAIDriver(config),
+  google: (config) => new GoogleDriver(config)
+};
+function createDriver(provider, config) {
+  return PROVIDER_REGISTRY[provider](config);
+}
+function visualAI(config = {}) {
+  const resolvedConfig = resolveConfig(config);
+  const driverConfig = {
+    apiKey: resolvedConfig.apiKey,
+    model: resolvedConfig.model,
+    maxTokens: resolvedConfig.maxTokens,
+    reasoningEffort: resolvedConfig.reasoningEffort
+  };
+  const driver = createDriver(resolvedConfig.provider, driverConfig);
+  async function checkElementsVisibility(image, elements, visible, options) {
+    const methodName = visible ? "elementsVisible" : "elementsHidden";
+    if (elements.length === 0) {
+      throw new VisualAIConfigError(`At least one element is required for ${methodName}()`);
+    }
+    const img = await normalizeImage(image);
+    const prompt = buildElementsVisibilityPrompt(elements, visible, options);
+    debugLog(resolvedConfig, `${methodName} prompt`, prompt);
+    const response = await timedSendMessage(driver, [img], prompt);
+    debugLog(resolvedConfig, `${methodName} response`, response.text);
+    const result = parseCheckResponse(response.text);
+    return {
+      ...result,
+      usage: processUsage(methodName, response.usage, response.durationSeconds, resolvedConfig)
+    };
+  }
+  return {
+    async check(image, statements, options) {
+      const stmts = Array.isArray(statements) ? statements : [statements];
+      if (stmts.length === 0) {
+        throw new VisualAIConfigError("At least one statement is required for check()");
+      }
+      const img = await normalizeImage(image);
+      const prompt = buildCheckPrompt(stmts, { instructions: options?.instructions });
+      debugLog(resolvedConfig, "check prompt", prompt);
+      const response = await timedSendMessage(driver, [img], prompt);
+      debugLog(resolvedConfig, "check response", response.text);
+      const result = parseCheckResponse(response.text);
+      return {
+        ...result,
+        usage: processUsage("check", response.usage, response.durationSeconds, resolvedConfig)
+      };
+    },
+    async ask(image, userPrompt, options) {
+      const img = await normalizeImage(image);
+      const prompt = buildAskPrompt(userPrompt, { instructions: options?.instructions });
+      debugLog(resolvedConfig, "ask prompt", prompt);
+      const response = await timedSendMessage(driver, [img], prompt);
+      debugLog(resolvedConfig, "ask response", response.text);
+      const result = parseAskResponse(response.text);
+      return {
+        ...result,
+        usage: processUsage("ask", response.usage, response.durationSeconds, resolvedConfig)
+      };
+    },
+    async compare(imageA, imageB, options) {
+      const [imgA, imgB] = await Promise.all([normalizeImage(imageA), normalizeImage(imageB)]);
+      const prompt = buildComparePrompt({
+        userPrompt: options?.prompt,
+        instructions: options?.instructions
+      });
+      debugLog(resolvedConfig, "compare prompt", prompt);
+      const response = await timedSendMessage(driver, [imgA, imgB], prompt);
+      debugLog(resolvedConfig, "compare response", response.text);
+      const supportsAnnotatedDiff = resolvedConfig.provider === "google" && resolvedConfig.model === Model.Google.GEMINI_3_FLASH_PREVIEW;
+      const effectiveDiffImage = options?.diffImage ?? (supportsAnnotatedDiff ? true : false);
+      let diffImage;
+      if (effectiveDiffImage) {
+        try {
+          diffImage = await generateAiDiff(imgA, imgB, resolvedConfig.model, driver);
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          debugLog(resolvedConfig, "ai diff error", msg);
+          if (!resolvedConfig.debug) {
+            process.stderr.write(
+              `[visual-ai-assertions] warning: diff generation failed: ${msg}
+`
+            );
+          }
+        }
+      }
+      const result = parseCompareResponse(response.text);
+      return {
+        ...result,
+        ...diffImage ? { diffImage } : {},
+        usage: processUsage("compare", response.usage, response.durationSeconds, resolvedConfig)
+      };
+    },
+    elementsVisible(image, elements, options) {
+      return checkElementsVisibility(image, elements, true, options);
+    },
+    elementsHidden(image, elements, options) {
+      return checkElementsVisibility(image, elements, false, options);
+    },
+    async accessibility(image, options) {
+      const img = await normalizeImage(image);
+      const prompt = buildAccessibilityPrompt(options);
+      debugLog(resolvedConfig, "accessibility prompt", prompt);
+      const response = await timedSendMessage(driver, [img], prompt);
+      debugLog(resolvedConfig, "accessibility response", response.text);
+      const result = parseCheckResponse(response.text);
+      return {
+        ...result,
+        usage: processUsage(
+          "accessibility",
+          response.usage,
+          response.durationSeconds,
+          resolvedConfig
+        )
+      };
+    },
+    async layout(image, options) {
+      const img = await normalizeImage(image);
+      const prompt = buildLayoutPrompt(options);
+      debugLog(resolvedConfig, "layout prompt", prompt);
+      const response = await timedSendMessage(driver, [img], prompt);
+      debugLog(resolvedConfig, "layout response", response.text);
+      const result = parseCheckResponse(response.text);
+      return {
+        ...result,
+        usage: processUsage("layout", response.usage, response.durationSeconds, resolvedConfig)
+      };
+    },
+    async pageLoad(image, options) {
+      const img = await normalizeImage(image);
+      const prompt = buildPageLoadPrompt(options);
+      debugLog(resolvedConfig, "pageLoad prompt", prompt);
+      const response = await timedSendMessage(driver, [img], prompt);
+      debugLog(resolvedConfig, "pageLoad response", response.text);
+      const result = parseCheckResponse(response.text);
+      return {
+        ...result,
+        usage: processUsage("pageLoad", response.usage, response.durationSeconds, resolvedConfig)
+      };
+    },
+    async content(image, options) {
+      const img = await normalizeImage(image);
+      const prompt = buildContentPrompt(options);
+      debugLog(resolvedConfig, "content prompt", prompt);
+      const response = await timedSendMessage(driver, [img], prompt);
+      debugLog(resolvedConfig, "content response", response.text);
+      const result = parseCheckResponse(response.text);
+      return {
+        ...result,
+        usage: processUsage("content", response.usage, response.durationSeconds, resolvedConfig)
+      };
+    }
+  };
+}
+
+// src/format.ts
+function formatCheckResult(result, label) {
+  if (result.pass) {
+    const header2 = label ? `Visual AI Check Passed (${label})` : "Visual AI Check Passed";
+    return `${header2}
+${"=".repeat(header2.length)}
+${result.reasoning}`;
+  }
+  const header = label ? `Visual AI Check Failed (${label})` : "Visual AI Check Failed";
+  const lines = [header, "=".repeat(header.length), result.reasoning];
+  if (result.statements.length > 0) {
+    lines.push("", "Statements:");
+    for (const s of result.statements) {
+      const status = s.pass ? "PASS" : "FAIL";
+      const confidence = s.confidence ? ` (${s.confidence})` : "";
+      lines.push(`  ${status}  "${s.statement}"`);
+      lines.push(`        ${s.reasoning}${confidence}`);
+    }
+  }
+  if (result.issues.length > 0) {
+    lines.push("", "Issues:");
+    for (const issue of result.issues) {
+      lines.push(`  [${issue.priority}/${issue.category}] ${issue.description}`);
+      lines.push(`    \u2192 ${issue.suggestion}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatCompareResult(result, label) {
+  const status = result.pass ? "Passed" : "Failed";
+  const header = label ? `Visual AI Compare ${status} (${label})` : `Visual AI Compare ${status}`;
+  const lines = [header, "=".repeat(header.length), result.reasoning];
+  if (result.changes.length > 0) {
+    lines.push("", "Changes:");
+    for (const change of result.changes) {
+      lines.push(`  [${change.severity}] ${change.description}`);
+    }
+  }
+  if (result.diffImage) {
+    const { width, height } = result.diffImage;
+    lines.push("", `Diff image: ${width}x${height} (AI-generated)`);
+  }
+  return lines.join("\n");
+}
+function assertVisualResult(result, label) {
+  if (!result.pass) {
+    throw new VisualAIAssertionError(formatCheckResult(result, label), result);
+  }
+}
+function assertVisualCompareResult(result, label) {
+  if (!result.pass) {
+    throw new VisualAIAssertionError(formatCompareResult(result, label), result);
+  }
+}
+export {
+  Accessibility,
+  AskResultSchema,
+  ChangeEntrySchema,
+  CheckResultSchema,
+  CompareResultSchema,
+  ConfidenceSchema,
+  Content,
+  DEFAULT_MODELS,
+  IssueCategorySchema,
+  IssuePrioritySchema,
+  IssueSchema,
+  Layout,
+  Model,
+  Provider,
+  StatementResultSchema,
+  UsageInfoSchema,
+  VALID_PROVIDERS,
+  VisualAIAssertionError,
+  VisualAIAuthError,
+  VisualAIConfigError,
+  VisualAIError,
+  VisualAIImageError,
+  VisualAIProviderError,
+  VisualAIRateLimitError,
+  VisualAIResponseParseError,
+  assertVisualCompareResult,
+  assertVisualResult,
+  formatCheckResult,
+  formatCompareResult,
+  isVisualAIKnownError,
+  visualAI
+};
+//# sourceMappingURL=index.js.map