visual-ai-assertions 0.13.1 → 0.16.0

package/dist/index.d.cts

@@ -14,6 +14,7 @@ declare const Provider: {
     readonly ANTHROPIC: "anthropic";
     readonly OPENAI: "openai";
     readonly GOOGLE: "google";
+    readonly OPENROUTER: "openrouter";
 };
 /** Known model names grouped by provider. */
 declare const Model: {
@@ -39,19 +40,34 @@ declare const Model: {
         readonly GPT_5_MINI: "gpt-5-mini";
     };
     readonly Google: {
+        readonly GEMINI_3_6_FLASH: "gemini-3.6-flash";
         readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
+        readonly GEMINI_3_5_FLASH_LITE: "gemini-3.5-flash-lite";
         readonly GEMINI_3_1_PRO_PREVIEW: "gemini-3.1-pro-preview";
         readonly GEMINI_3_1_FLASH_LITE: "gemini-3.1-flash-lite";
         readonly GEMINI_3_FLASH_PREVIEW: "gemini-3-flash-preview";
     };
+    /**
+     * Models routed through OpenRouter (https://openrouter.ai). Slugs always
+     * carry a vendor prefix (`vendor/model`), which is how provider inference
+     * recognizes them. All listed models accept image input.
+     */
+    readonly OpenRouter: {
+        readonly GROK_4_5: "x-ai/grok-4.5";
+        readonly KIMI_K3: "moonshotai/kimi-k3";
+        readonly KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code";
+        readonly QWEN_3_7_PLUS: "qwen/qwen3.7-plus";
+        readonly QWEN_3_6_FLASH: "qwen/qwen3.6-flash";
+    };
 };
 /** 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];
+type KnownModelName = (typeof Model.Anthropic)[keyof typeof Model.Anthropic] | (typeof Model.OpenAI)[keyof typeof Model.OpenAI] | (typeof Model.Google)[keyof typeof Model.Google] | (typeof Model.OpenRouter)[keyof typeof Model.OpenRouter];
 /** Default model selection used when a caller omits `config.model`. */
 declare const DEFAULT_MODELS: {
     readonly anthropic: "claude-sonnet-4-6";
     readonly openai: "gpt-5.4-mini";
     readonly google: "gemini-3-flash-preview";
+    readonly openrouter: "qwen/qwen3.6-flash";
 };
 /** Built-in content checks available through `client.content()`. */
 declare const Content: {
@@ -493,12 +509,42 @@ type ImageInput = Buffer | Uint8Array | string;
  * an image or a video.
  */
 type MediaInput = ImageInput;
+/**
+ * A single pre-sampled frame with an explicit timestamp. Use this shape when
+ * you want to control the timestamp the model sees; otherwise pass a bare
+ * `ImageInput` and the timestamp is derived from `fps` and the frame's position.
+ */
+interface TimestampedFrameInput {
+    /** Image source for the frame (buffer, data URL, base64, file path, or URL). */
+    image: ImageInput;
+    /** Timestamp in seconds, from the start of the sequence. Derived from `fps` when omitted. */
+    timestampSeconds?: number;
+}
+/**
+ * Pre-sampled frames supplied directly instead of a video file. Useful when you
+ * already have an array of screenshots and cannot (or would rather not) pass a
+ * video — this path never loads ffmpeg. Passed to `check()` / `ask()` in place
+ * of a `MediaInput`; downstream handling is identical to a sampled video.
+ */
+interface FramesInput {
+    /**
+     * Ordered frames, earliest first. Each entry is an image source or a
+     * `{ image, timestampSeconds }` pair. Must be non-empty and is capped at the
+     * same per-request frame limit as video sampling (60).
+     */
+    frames: ReadonlyArray<ImageInput | TimestampedFrameInput>;
+    /**
+     * Frame rate used to derive timestamps for frames that don't carry their own
+     * `timestampSeconds` (frame `i` maps to `i / fps` seconds). Default `1`.
+     */
+    fps?: number;
+}
 /** Supported image MIME types accepted by all providers. */
 type SupportedMimeType = "image/jpeg" | "image/png" | "image/webp" | "image/gif";
 /** Supported video MIME types the client can accept and sample frames from. */
 type SupportedVideoMimeType = "video/mp4" | "video/webm" | "video/quicktime" | "video/x-matroska";
 /** Supported provider identifiers. */
-type ProviderName = "anthropic" | "openai" | "google";
+type ProviderName = "anthropic" | "openai" | "google" | "openrouter";
 /**
  * Configuration for creating a visual AI client.
  *
@@ -633,9 +679,11 @@ interface VisualAIClient {
      * frames automatically; statements pass if they are true at any sampled
      * frame, and each statement result includes the timestamp where it
      * matched. The `frames` metadata on the result reports which timestamps
-     * the model saw.
+     * the model saw. Pass a `FramesInput` (`{ frames, fps? }`) to supply
+     * pre-sampled frames directly — handled identically to a video timeline but
+     * without loading ffmpeg.
      *
-     * @param input Image or video source as a buffer, URL, file path, or base64 string.
+     * @param input Image or video source as a buffer, URL, file path, or base64 string, or a `FramesInput` of pre-sampled frames.
      * @param statements One or more statements to validate against the input.
      * @param options Optional additional instructions and video sampling overrides.
      * @returns A structured result describing pass/fail, issues, and statement reasoning.
@@ -658,15 +706,17 @@ interface VisualAIClient {
      * console.log(result.statements[0].timestampSeconds); // e.g. 3.5
      * ```
      */
-    check(input: MediaInput, statements: string | string[], options?: CheckOptions): Promise<CheckResult>;
+    check(input: MediaInput | FramesInput, statements: string | string[], options?: CheckOptions): Promise<CheckResult>;
     /**
      * Asks an open-ended question about an image or video and returns a structured summary.
      *
      * Video inputs are sampled into frames and analyzed as a chronological
      * timeline. The result's `frameReferences` array surfaces which frames the
-     * model relied on for its answer.
+     * model relied on for its answer. Pass a `FramesInput` (`{ frames, fps? }`)
+     * to supply pre-sampled frames directly — handled identically to a video
+     * timeline but without loading ffmpeg.
      *
-     * @param input Image or video source as a buffer, URL, file path, or base64 string.
+     * @param input Image or video source as a buffer, URL, file path, or base64 string, or a `FramesInput` of pre-sampled frames.
      * @param prompt Prompt describing what to inspect in the input.
      * @param options Optional additional instructions and video sampling overrides.
      * @returns A summary with any detected issues.
@@ -678,7 +728,7 @@ interface VisualAIClient {
      * const result = await client.ask(screenshot, "What looks visually broken on this page?");
      * ```
      */
-    ask(input: MediaInput, prompt: string, options?: AskOptions): Promise<AskResult>;
+    ask(input: MediaInput | FramesInput, prompt: string, options?: AskOptions): Promise<AskResult>;
     /**
      * Compares two images and reports meaningful visual differences.
      *
@@ -1055,4 +1105,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
  */
 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 Frame, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, type MediaInput, Model, type PageLoadOptions, Provider, type ProviderName, ReasoningEffort, type ReasoningEffortLevel, type StatementResult, StatementResultSchema, type SupportedMimeType, type SupportedVideoMimeType, type UsageInfo, UsageInfoSchema, type VideoFramesMetadata, type VideoSamplingOptions, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, VisualAITruncationError, VisualAIVideoError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };
+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 Frame, type FramesInput, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, type MediaInput, Model, type PageLoadOptions, Provider, type ProviderName, ReasoningEffort, type ReasoningEffortLevel, type StatementResult, StatementResultSchema, type SupportedMimeType, type SupportedVideoMimeType, type TimestampedFrameInput, type UsageInfo, UsageInfoSchema, type VideoFramesMetadata, type VideoSamplingOptions, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, VisualAITruncationError, VisualAIVideoError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };

package/dist/index.d.ts

@@ -14,6 +14,7 @@ declare const Provider: {
     readonly ANTHROPIC: "anthropic";
     readonly OPENAI: "openai";
     readonly GOOGLE: "google";
+    readonly OPENROUTER: "openrouter";
 };
 /** Known model names grouped by provider. */
 declare const Model: {
@@ -39,19 +40,34 @@ declare const Model: {
         readonly GPT_5_MINI: "gpt-5-mini";
     };
     readonly Google: {
+        readonly GEMINI_3_6_FLASH: "gemini-3.6-flash";
         readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
+        readonly GEMINI_3_5_FLASH_LITE: "gemini-3.5-flash-lite";
         readonly GEMINI_3_1_PRO_PREVIEW: "gemini-3.1-pro-preview";
         readonly GEMINI_3_1_FLASH_LITE: "gemini-3.1-flash-lite";
         readonly GEMINI_3_FLASH_PREVIEW: "gemini-3-flash-preview";
     };
+    /**
+     * Models routed through OpenRouter (https://openrouter.ai). Slugs always
+     * carry a vendor prefix (`vendor/model`), which is how provider inference
+     * recognizes them. All listed models accept image input.
+     */
+    readonly OpenRouter: {
+        readonly GROK_4_5: "x-ai/grok-4.5";
+        readonly KIMI_K3: "moonshotai/kimi-k3";
+        readonly KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code";
+        readonly QWEN_3_7_PLUS: "qwen/qwen3.7-plus";
+        readonly QWEN_3_6_FLASH: "qwen/qwen3.6-flash";
+    };
 };
 /** 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];
+type KnownModelName = (typeof Model.Anthropic)[keyof typeof Model.Anthropic] | (typeof Model.OpenAI)[keyof typeof Model.OpenAI] | (typeof Model.Google)[keyof typeof Model.Google] | (typeof Model.OpenRouter)[keyof typeof Model.OpenRouter];
 /** Default model selection used when a caller omits `config.model`. */
 declare const DEFAULT_MODELS: {
     readonly anthropic: "claude-sonnet-4-6";
     readonly openai: "gpt-5.4-mini";
     readonly google: "gemini-3-flash-preview";
+    readonly openrouter: "qwen/qwen3.6-flash";
 };
 /** Built-in content checks available through `client.content()`. */
 declare const Content: {
@@ -493,12 +509,42 @@ type ImageInput = Buffer | Uint8Array | string;
  * an image or a video.
  */
 type MediaInput = ImageInput;
+/**
+ * A single pre-sampled frame with an explicit timestamp. Use this shape when
+ * you want to control the timestamp the model sees; otherwise pass a bare
+ * `ImageInput` and the timestamp is derived from `fps` and the frame's position.
+ */
+interface TimestampedFrameInput {
+    /** Image source for the frame (buffer, data URL, base64, file path, or URL). */
+    image: ImageInput;
+    /** Timestamp in seconds, from the start of the sequence. Derived from `fps` when omitted. */
+    timestampSeconds?: number;
+}
+/**
+ * Pre-sampled frames supplied directly instead of a video file. Useful when you
+ * already have an array of screenshots and cannot (or would rather not) pass a
+ * video — this path never loads ffmpeg. Passed to `check()` / `ask()` in place
+ * of a `MediaInput`; downstream handling is identical to a sampled video.
+ */
+interface FramesInput {
+    /**
+     * Ordered frames, earliest first. Each entry is an image source or a
+     * `{ image, timestampSeconds }` pair. Must be non-empty and is capped at the
+     * same per-request frame limit as video sampling (60).
+     */
+    frames: ReadonlyArray<ImageInput | TimestampedFrameInput>;
+    /**
+     * Frame rate used to derive timestamps for frames that don't carry their own
+     * `timestampSeconds` (frame `i` maps to `i / fps` seconds). Default `1`.
+     */
+    fps?: number;
+}
 /** Supported image MIME types accepted by all providers. */
 type SupportedMimeType = "image/jpeg" | "image/png" | "image/webp" | "image/gif";
 /** Supported video MIME types the client can accept and sample frames from. */
 type SupportedVideoMimeType = "video/mp4" | "video/webm" | "video/quicktime" | "video/x-matroska";
 /** Supported provider identifiers. */
-type ProviderName = "anthropic" | "openai" | "google";
+type ProviderName = "anthropic" | "openai" | "google" | "openrouter";
 /**
  * Configuration for creating a visual AI client.
  *
@@ -633,9 +679,11 @@ interface VisualAIClient {
      * frames automatically; statements pass if they are true at any sampled
      * frame, and each statement result includes the timestamp where it
      * matched. The `frames` metadata on the result reports which timestamps
-     * the model saw.
+     * the model saw. Pass a `FramesInput` (`{ frames, fps? }`) to supply
+     * pre-sampled frames directly — handled identically to a video timeline but
+     * without loading ffmpeg.
      *
-     * @param input Image or video source as a buffer, URL, file path, or base64 string.
+     * @param input Image or video source as a buffer, URL, file path, or base64 string, or a `FramesInput` of pre-sampled frames.
      * @param statements One or more statements to validate against the input.
      * @param options Optional additional instructions and video sampling overrides.
      * @returns A structured result describing pass/fail, issues, and statement reasoning.
@@ -658,15 +706,17 @@ interface VisualAIClient {
      * console.log(result.statements[0].timestampSeconds); // e.g. 3.5
      * ```
      */
-    check(input: MediaInput, statements: string | string[], options?: CheckOptions): Promise<CheckResult>;
+    check(input: MediaInput | FramesInput, statements: string | string[], options?: CheckOptions): Promise<CheckResult>;
     /**
      * Asks an open-ended question about an image or video and returns a structured summary.
      *
      * Video inputs are sampled into frames and analyzed as a chronological
      * timeline. The result's `frameReferences` array surfaces which frames the
-     * model relied on for its answer.
+     * model relied on for its answer. Pass a `FramesInput` (`{ frames, fps? }`)
+     * to supply pre-sampled frames directly — handled identically to a video
+     * timeline but without loading ffmpeg.
      *
-     * @param input Image or video source as a buffer, URL, file path, or base64 string.
+     * @param input Image or video source as a buffer, URL, file path, or base64 string, or a `FramesInput` of pre-sampled frames.
      * @param prompt Prompt describing what to inspect in the input.
      * @param options Optional additional instructions and video sampling overrides.
      * @returns A summary with any detected issues.
@@ -678,7 +728,7 @@ interface VisualAIClient {
      * const result = await client.ask(screenshot, "What looks visually broken on this page?");
      * ```
      */
-    ask(input: MediaInput, prompt: string, options?: AskOptions): Promise<AskResult>;
+    ask(input: MediaInput | FramesInput, prompt: string, options?: AskOptions): Promise<AskResult>;
     /**
      * Compares two images and reports meaningful visual differences.
      *
@@ -1055,4 +1105,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
  */
 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 Frame, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, type MediaInput, Model, type PageLoadOptions, Provider, type ProviderName, ReasoningEffort, type ReasoningEffortLevel, type StatementResult, StatementResultSchema, type SupportedMimeType, type SupportedVideoMimeType, type UsageInfo, UsageInfoSchema, type VideoFramesMetadata, type VideoSamplingOptions, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, VisualAITruncationError, VisualAIVideoError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };
+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 Frame, type FramesInput, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, type MediaInput, Model, type PageLoadOptions, Provider, type ProviderName, ReasoningEffort, type ReasoningEffortLevel, type StatementResult, StatementResultSchema, type SupportedMimeType, type SupportedVideoMimeType, type TimestampedFrameInput, type UsageInfo, UsageInfoSchema, type VideoFramesMetadata, type VideoSamplingOptions, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, VisualAITruncationError, VisualAIVideoError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };

package/dist/index.js

@@ -8,7 +8,8 @@ var ReasoningEffort = {
 var Provider = {
   ANTHROPIC: "anthropic",
   OPENAI: "openai",
-  GOOGLE: "google"
+  GOOGLE: "google",
+  OPENROUTER: "openrouter"
 };
 var Model = {
   Anthropic: {
@@ -33,29 +34,47 @@ var Model = {
     GPT_5_MINI: "gpt-5-mini"
   },
   Google: {
+    GEMINI_3_6_FLASH: "gemini-3.6-flash",
     GEMINI_3_5_FLASH: "gemini-3.5-flash",
+    GEMINI_3_5_FLASH_LITE: "gemini-3.5-flash-lite",
     GEMINI_3_1_PRO_PREVIEW: "gemini-3.1-pro-preview",
     GEMINI_3_1_FLASH_LITE: "gemini-3.1-flash-lite",
     GEMINI_3_FLASH_PREVIEW: "gemini-3-flash-preview"
+  },
+  /**
+   * Models routed through OpenRouter (https://openrouter.ai). Slugs always
+   * carry a vendor prefix (`vendor/model`), which is how provider inference
+   * recognizes them. All listed models accept image input.
+   */
+  OpenRouter: {
+    GROK_4_5: "x-ai/grok-4.5",
+    KIMI_K3: "moonshotai/kimi-k3",
+    KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code",
+    QWEN_3_7_PLUS: "qwen/qwen3.7-plus",
+    QWEN_3_6_FLASH: "qwen/qwen3.6-flash"
   }
 };
 var DEFAULT_MODELS = {
   [Provider.ANTHROPIC]: Model.Anthropic.SONNET_4_6,
   [Provider.OPENAI]: Model.OpenAI.GPT_5_4_MINI,
-  [Provider.GOOGLE]: Model.Google.GEMINI_3_FLASH_PREVIEW
+  [Provider.GOOGLE]: Model.Google.GEMINI_3_FLASH_PREVIEW,
+  [Provider.OPENROUTER]: Model.OpenRouter.QWEN_3_6_FLASH
 };
 var DEFAULT_MAX_TOKENS = 4096;
 var OPENAI_REASONING_MAX_TOKENS = 16384;
 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])
+  ...Object.values(Model.Google).map((m) => [m, Provider.GOOGLE]),
+  ...Object.values(Model.OpenRouter).map((m) => [m, Provider.OPENROUTER])
 ]);
 var VALID_PROVIDERS = Object.values(Provider);
 var PROVIDER_DEFAULT_REASONING = {
   openai: "medium",
   anthropic: "off",
-  google: "off"
+  google: "off",
+  // Varies by upstream model; the driver sends no reasoning field unless configured.
+  openrouter: "off"
 };
 var Content = {
   /** Detects Lorem ipsum, TODO, TBD, and similar placeholder text */
@@ -521,6 +540,13 @@ function mapEffort(level, model) {
   if (level !== "xhigh") return level;
   return XHIGH_CAPABLE_MODELS.has(model) ? "xhigh" : "max";
 }
+var BUDGET_THINKING_MODELS = /* @__PURE__ */ new Set([Model.Anthropic.HAIKU_4_5]);
+var EFFORT_TO_BUDGET_TOKENS = {
+  low: 1024,
+  medium: 4096,
+  high: 8192,
+  xhigh: 16384
+};
 var AnthropicDriver = class {
   client;
   model;
@@ -576,10 +602,16 @@ var AnthropicDriver = class {
         ]
       };
       if (this.reasoningEffort) {
-        requestParams.thinking = { type: "adaptive" };
-        requestParams.output_config = {
-          effort: mapEffort(this.reasoningEffort, this.model)
-        };
+        if (BUDGET_THINKING_MODELS.has(this.model)) {
+          const budgetTokens = EFFORT_TO_BUDGET_TOKENS[this.reasoningEffort];
+          requestParams.thinking = { type: "enabled", budget_tokens: budgetTokens };
+          requestParams.max_tokens = Math.max(this.maxTokens, budgetTokens + DEFAULT_MAX_TOKENS);
+        } else {
+          requestParams.thinking = { type: "adaptive" };
+          requestParams.output_config = {
+            effort: mapEffort(this.reasoningEffort, this.model)
+          };
+        }
       }
       const message = await client.messages.create(requestParams);
       const textBlock = message.content.find((block) => block.type === "text");
@@ -820,6 +852,109 @@ var OpenAIDriver = class {
   }
 };
 
+// src/providers/openrouter.ts
+var OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+var OPENROUTER_REASONING_EFFORT = {
+  low: "low",
+  medium: "medium",
+  high: "high",
+  xhigh: "high"
+};
+var OpenRouterDriver = 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 (required for the OpenRouter provider). Run: npm install openai"
+      );
+    }
+    const apiKey = this.apiKeyOrEnv ?? process.env.OPENROUTER_API_KEY;
+    if (!apiKey) {
+      throw new VisualAIAuthError(
+        "OpenRouter API key not found. Set OPENROUTER_API_KEY or pass apiKey in config."
+      );
+    }
+    this.client = new OpenAI({ apiKey, baseURL: OPENROUTER_BASE_URL });
+    return this.client;
+  }
+  async sendMessage(images, prompt, options) {
+    const client = await this.getClient();
+    const imageParts = images.map((img) => ({
+      type: "image_url",
+      image_url: { url: `data:${img.mimeType};base64,${img.base64}` }
+    }));
+    try {
+      const responseFormat = options?.responseSchema ? {
+        type: "json_schema",
+        json_schema: {
+          name: "visual_ai_response",
+          strict: true,
+          schema: options.responseSchema
+        }
+      } : { type: "json_object" };
+      const requestParams = {
+        model: this.model,
+        max_tokens: this.maxTokens,
+        response_format: responseFormat,
+        messages: [
+          {
+            role: "user",
+            content: [...imageParts, { type: "text", text: prompt }]
+          }
+        ],
+        // OpenRouter-specific: include token accounting in the response.
+        usage: { include: true }
+      };
+      if (this.reasoningEffort) {
+        requestParams.reasoning = { effort: OPENROUTER_REASONING_EFFORT[this.reasoningEffort] };
+      }
+      const response = await client.chat.completions.create(requestParams);
+      const choice = response.choices?.[0];
+      if (!choice?.message) {
+        throw new VisualAIProviderError("OpenRouter returned an empty response (no choices).");
+      }
+      const text = choice.message.content ?? "";
+      if (choice.finish_reason === "length") {
+        throw new VisualAITruncationError(
+          `Response truncated: OpenRouter returned finish_reason "length". The model exhausted the output token budget (${this.maxTokens} tokens). This commonly happens with higher reasoning effort levels. Increase maxTokens in your config (e.g., maxTokens: 16384) or lower reasoningEffort.`,
+          text,
+          this.maxTokens
+        );
+      }
+      const reasoningTokens = response.usage?.completion_tokens_details?.reasoning_tokens;
+      return {
+        text,
+        usage: response.usage ? {
+          inputTokens: response.usage.prompt_tokens,
+          outputTokens: response.usage.completion_tokens,
+          ...reasoningTokens !== void 0 && { reasoningTokens }
+        } : void 0
+      };
+    } catch (err) {
+      if (err instanceof VisualAITruncationError || err instanceof VisualAIProviderError) {
+        throw err;
+      }
+      throw mapProviderError(err);
+    }
+  }
+};
+
 // src/core/config.ts
 var MODEL_PREFIX_TO_PROVIDER = [
   ["claude-", "anthropic"],
@@ -832,6 +967,7 @@ var MODEL_PREFIX_TO_PROVIDER = [
 function inferProviderFromModel(model) {
   const known = MODEL_TO_PROVIDER.get(model);
   if (known) return known;
+  if (model.includes("/")) return "openrouter";
   const prefixMatch = MODEL_PREFIX_TO_PROVIDER.find(([prefix]) => model.startsWith(prefix));
   return prefixMatch?.[1];
 }
@@ -844,12 +980,13 @@ function resolveProvider(config) {
   const apiKeyProviderMap = [
     ["ANTHROPIC_API_KEY", "anthropic"],
     ["OPENAI_API_KEY", "openai"],
-    ["GOOGLE_API_KEY", "google"]
+    ["GOOGLE_API_KEY", "google"],
+    ["OPENROUTER_API_KEY", "openrouter"]
   ];
   const detected = apiKeyProviderMap.find(([key]) => process.env[key]);
   if (detected) return detected[1];
   throw new VisualAIConfigError(
-    "Cannot determine provider. Set a model name (config or VISUAL_AI_MODEL) or an API key env variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY)."
+    "Cannot determine provider. Set a model name (config or VISUAL_AI_MODEL) or an API key env variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY)."
   );
 }
 function parseBooleanEnv(envName, value) {
@@ -877,11 +1014,11 @@ function resolveConfig(config) {
   }
   const userSetMaxTokens = config.maxTokens !== void 0;
   let maxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
-  if (!userSetMaxTokens && provider === "openai" && (config.reasoningEffort === "high" || config.reasoningEffort === "xhigh")) {
+  if (!userSetMaxTokens && (provider === "openai" || provider === "openrouter") && (config.reasoningEffort === "high" || config.reasoningEffort === "xhigh")) {
     maxTokens = OPENAI_REASONING_MAX_TOKENS;
     if (debug) {
       process.stderr.write(
-        `[visual-ai-assertions] Auto-increased maxTokens from ${DEFAULT_MAX_TOKENS} to ${OPENAI_REASONING_MAX_TOKENS} for OpenAI with reasoningEffort "${config.reasoningEffort}".
+        `[visual-ai-assertions] Auto-increased maxTokens from ${DEFAULT_MAX_TOKENS} to ${OPENAI_REASONING_MAX_TOKENS} for provider "${provider}" with reasoningEffort "${config.reasoningEffort}".
 `
       );
     }
@@ -970,10 +1107,18 @@ var PRICING_TABLE = {
     inputPricePerToken: 0.25 / PER_MILLION,
     outputPricePerToken: 2 / PER_MILLION
   },
+  [`${Provider.GOOGLE}:${Model.Google.GEMINI_3_6_FLASH}`]: {
+    inputPricePerToken: 1.5 / PER_MILLION,
+    outputPricePerToken: 7.5 / PER_MILLION
+  },
   [`${Provider.GOOGLE}:${Model.Google.GEMINI_3_5_FLASH}`]: {
     inputPricePerToken: 1.5 / PER_MILLION,
     outputPricePerToken: 9 / PER_MILLION
   },
+  [`${Provider.GOOGLE}:${Model.Google.GEMINI_3_5_FLASH_LITE}`]: {
+    inputPricePerToken: 0.3 / PER_MILLION,
+    outputPricePerToken: 2.5 / PER_MILLION
+  },
   [`${Provider.GOOGLE}:${Model.Google.GEMINI_3_1_PRO_PREVIEW}`]: {
     inputPricePerToken: 2 / PER_MILLION,
     outputPricePerToken: 12 / PER_MILLION
@@ -985,6 +1130,28 @@ var PRICING_TABLE = {
   [`${Provider.GOOGLE}:${Model.Google.GEMINI_3_FLASH_PREVIEW}`]: {
     inputPricePerToken: 0.5 / PER_MILLION,
     outputPricePerToken: 3 / PER_MILLION
+  },
+  // OpenRouter passes through upstream per-model pricing (verified 2026-07-22
+  // against https://openrouter.ai/api/v1/models).
+  [`${Provider.OPENROUTER}:${Model.OpenRouter.GROK_4_5}`]: {
+    inputPricePerToken: 2 / PER_MILLION,
+    outputPricePerToken: 6 / PER_MILLION
+  },
+  [`${Provider.OPENROUTER}:${Model.OpenRouter.KIMI_K3}`]: {
+    inputPricePerToken: 3 / PER_MILLION,
+    outputPricePerToken: 15 / PER_MILLION
+  },
+  [`${Provider.OPENROUTER}:${Model.OpenRouter.KIMI_K2_7_CODE}`]: {
+    inputPricePerToken: 0.82 / PER_MILLION,
+    outputPricePerToken: 3.75 / PER_MILLION
+  },
+  [`${Provider.OPENROUTER}:${Model.OpenRouter.QWEN_3_7_PLUS}`]: {
+    inputPricePerToken: 0.32 / PER_MILLION,
+    outputPricePerToken: 1.28 / PER_MILLION
+  },
+  [`${Provider.OPENROUTER}:${Model.OpenRouter.QWEN_3_6_FLASH}`]: {
+    inputPricePerToken: 0.1875 / PER_MILLION,
+    outputPricePerToken: 1.125 / PER_MILLION
   }
 };
 function calculateCost(provider, model, inputTokens, outputTokens) {
@@ -1062,7 +1229,8 @@ async function timedSendMessage(driver, images, prompt, options) {
 import sharp from "sharp";
 var DIFF_ALLOWED_MODELS = /* @__PURE__ */ new Set([
   Model.Google.GEMINI_3_FLASH_PREVIEW,
-  Model.Google.GEMINI_3_5_FLASH
+  Model.Google.GEMINI_3_5_FLASH,
+  Model.Google.GEMINI_3_6_FLASH
 ]);
 async function generateAiDiff(imgA, imgB, model, driver) {
   if (!driver.generateImage) {
@@ -1705,7 +1873,57 @@ function isVideoInput(input) {
   }
   return false;
 }
+function isFramesInput(input) {
+  return typeof input === "object" && input !== null && !Buffer.isBuffer(input) && !(input instanceof Uint8Array) && Array.isArray(input.frames);
+}
+function isTimestampedFrameInput(frame) {
+  return typeof frame === "object" && !Buffer.isBuffer(frame) && !(frame instanceof Uint8Array) && "image" in frame;
+}
+async function normalizeFrames(input) {
+  const rawFrames = input.frames;
+  const fps = input.fps ?? DEFAULT_FPS;
+  if (rawFrames.length === 0) {
+    throw new VisualAIVideoError("frames must be a non-empty array of image inputs");
+  }
+  if (rawFrames.length > MAX_FRAMES_HARD_CAP) {
+    throw new VisualAIVideoError(
+      `frames length ${rawFrames.length} exceeds the hard cap of ${MAX_FRAMES_HARD_CAP}. Pass fewer frames or open an issue if you need a larger limit.`
+    );
+  }
+  if (!Number.isFinite(fps) || fps <= 0) {
+    throw new VisualAIVideoError(`Invalid fps: ${fps}. Must be a finite number > 0.`);
+  }
+  const frames = await Promise.all(
+    rawFrames.map(async (raw, index) => {
+      const timestamped = isTimestampedFrameInput(raw);
+      const imageInput = timestamped ? raw.image : raw;
+      const explicit = timestamped ? raw.timestampSeconds : void 0;
+      const timestampSeconds = explicit ?? index / fps;
+      if (!Number.isFinite(timestampSeconds) || timestampSeconds < 0) {
+        throw new VisualAIVideoError(
+          `Invalid timestampSeconds for frame ${index}: ${String(timestampSeconds)}. Must be a finite number >= 0.`
+        );
+      }
+      const image = await normalizeImage(imageInput);
+      return {
+        data: image.data,
+        mimeType: image.mimeType,
+        get base64() {
+          return image.base64;
+        },
+        timestampSeconds,
+        index
+      };
+    })
+  );
+  const durationSeconds = frames.reduce((max, f) => Math.max(max, f.timestampSeconds), 0);
+  await saveDebugFrames(frames);
+  return { kind: "video", frames, durationSeconds };
+}
 async function normalizeMedia(input, videoOptions) {
+  if (isFramesInput(input)) {
+    return normalizeFrames(input);
+  }
   if (isVideoInput(input)) {
     const { path, cleanup } = await resolveVideoToPath(input);
     try {
@@ -1862,7 +2080,8 @@ function toSchemaOptions(schema) {
 var PROVIDER_REGISTRY = {
   anthropic: (config) => new AnthropicDriver(config),
   openai: (config) => new OpenAIDriver(config),
-  google: (config) => new GoogleDriver(config)
+  google: (config) => new GoogleDriver(config),
+  openrouter: (config) => new OpenRouterDriver(config)
 };
 function createDriver(provider, config) {
   return PROVIDER_REGISTRY[provider](config);