visual-ai-assertions 0.23.0 → 0.26.0

package/dist/index.js

@@ -1,132 +1,3 @@
-// src/constants.ts
-var ReasoningEffort = {
-  LOW: "low",
-  MEDIUM: "medium",
-  HIGH: "high",
-  XHIGH: "xhigh"
-};
-var ImageDetail = {
-  AUTO: "auto",
-  LOW: "low",
-  HIGH: "high"
-};
-var DEFAULT_IMAGE_DETAIL = ImageDetail.AUTO;
-var DEFAULT_MAX_IMAGE_DIMENSION = 1568;
-var Provider = {
-  ANTHROPIC: "anthropic",
-  OPENAI: "openai",
-  GOOGLE: "google",
-  OPENROUTER: "openrouter"
-};
-var Model = {
-  Anthropic: {
-    FABLE_5_1: "claude-fable-5-1",
-    FABLE_5: "claude-fable-5",
-    OPUS_5: "claude-opus-5",
-    OPUS_4_8: "claude-opus-4-8",
-    OPUS_4_7: "claude-opus-4-7",
-    OPUS_4_6: "claude-opus-4-6",
-    SONNET_5: "claude-sonnet-5",
-    SONNET_4_6: "claude-sonnet-4-6",
-    HAIKU_4_5: "claude-haiku-4-5"
-  },
-  OpenAI: {
-    GPT_6_ASTRA: "gpt-6-astra",
-    GPT_5_6_SOL: "gpt-5.6-sol",
-    GPT_5_6_TERRA: "gpt-5.6-terra",
-    GPT_5_6_LUNA: "gpt-5.6-luna",
-    GPT_5_5: "gpt-5.5",
-    GPT_5_4: "gpt-5.4",
-    GPT_5_4_PRO: "gpt-5.4-pro",
-    GPT_5_4_MINI: "gpt-5.4-mini",
-    GPT_5_4_NANO: "gpt-5.4-nano",
-    GPT_5_2: "gpt-5.2",
-    GPT_5_MINI: "gpt-5-mini"
-  },
-  Google: {
-    GEMINI_3_8_FLASH: "gemini-3.8-flash",
-    GEMINI_3_7_FLASH: "gemini-3.7-flash",
-    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: {
-    MUSE_SPARK_1_3: "meta/muse-spark-1.3",
-    GROK_4_6: "x-ai/grok-4.6",
-    GROK_4_5: "x-ai/grok-4.5",
-    KIMI_K3: "moonshotai/kimi-k3",
-    KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code",
-    QWEN_3_8_MAX: "qwen/qwen3.8-max",
-    QWEN_3_7_PLUS: "qwen/qwen3.7-plus",
-    QWEN_3_6_FLASH: "qwen/qwen3.6-flash",
-    GLM_5_3_FLASH: "z-ai/glm-5.3-flash"
-  }
-};
-var DEFAULT_MODELS = {
-  [Provider.ANTHROPIC]: Model.Anthropic.SONNET_4_6,
-  [Provider.OPENAI]: Model.OpenAI.GPT_5_6_LUNA,
-  [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 OPENAI_HEAVY_REASONING_MAX_TOKENS = 32768;
-var MODELS_REQUIRING_LARGE_OUTPUT_BUDGET = /* @__PURE__ */ new Set([
-  Model.OpenAI.GPT_6_ASTRA
-]);
-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.OpenRouter).map((m) => [m, Provider.OPENROUTER])
-]);
-var VALID_PROVIDERS = Object.values(Provider);
-var PROVIDER_DEFAULT_REASONING = {
-  openai: "medium",
-  anthropic: "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 */
-  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",
-  /** Detects color choices likely to be indistinguishable to viewers with common color vision deficiencies */
-  COLOR_BLINDNESS: "color-blindness",
-  /** Detects information conveyed by color alone, without a non-color cue (icon, text, pattern, position) */
-  COLOR_ALONE: "color-alone"
-};
-
 // src/errors.ts
 var VisualAIError = class extends Error {
   code;
@@ -258,10 +129,15 @@ Example for a failing check:
   ]
 }
 ${JSON_INSTRUCTIONS}`;
-var CHECK_OUTPUT_SCHEMA_VIDEO = `IMPORTANT: Follow this evaluation order:
+function buildCheckOutputSchemaVideo(unit) {
+  const anyPoint = unit === "frame" ? "ANY frame of the timeline" : "ANY moment of the video";
+  const bestPoint = unit === "frame" ? "the timestamp of the frame that most clearly demonstrates it" : "the timestamp of the moment that most clearly demonstrates it";
+  const citing = unit === "frame" ? "citing frame timestamps" : "citing timestamps";
+  const exampleWhere = unit === "frame" ? "at the 3.5s frame" : "at 3.5s";
+  return `IMPORTANT: Follow this evaluation order:
 1. First, evaluate EACH statement independently across the entire timeline and populate the "statements" array
-2. A statement passes if it is true at ANY frame of the timeline, unless the wording explicitly says otherwise (e.g. "throughout", "at all times")
-3. For each statement that passes, set "timestampSeconds" to the timestamp of the frame that most clearly demonstrates it (or where it first becomes true). Use null when the statement fails or applies across the whole clip.
+2. A statement passes if it is true at ${anyPoint}, unless the wording explicitly says otherwise (e.g. "throughout", "at all times")
+3. For each statement that passes, set "timestampSeconds" to ${bestPoint} (or where it first becomes true). Use null when the statement fails or applies across the whole clip.
 4. Then, set "pass" to true ONLY if every statement passed (logical AND of all statement results)
 5. Write "reasoning" as a brief overall summary of the evaluation
 6. Include "issues" only for statements that failed
@@ -275,7 +151,7 @@ Respond with a JSON object matching this exact structure:
     {
       "statement": string,  // the original statement text
       "pass": boolean,      // whether this statement is true at any point in the timeline
-      "reasoning": string,  // explanation for this statement, citing frame timestamps where relevant
+      "reasoning": string,  // explanation for this statement, ${citing} where relevant
       "confidence": "high" | "medium" | "low",
       "timestampSeconds": number | null
         // seconds from the start of the clip where the statement is most clearly true,
@@ -293,10 +169,13 @@ Example for a passing video check:
   "reasoning": "The success toast appeared briefly around 3.5s.",
   "issues": [],
   "statements": [
-    { "statement": "A success toast with text 'Saved' appears", "pass": true, "reasoning": "A green toast labeled 'Saved' is visible in the bottom-right at the 3.5s frame", "confidence": "high", "timestampSeconds": 3.5 }
+    { "statement": "A success toast with text 'Saved' appears", "pass": true, "reasoning": "A green toast labeled 'Saved' is visible in the bottom-right ${exampleWhere}", "confidence": "high", "timestampSeconds": 3.5 }
   ]
 }
 ${JSON_INSTRUCTIONS}`;
+}
+var CHECK_OUTPUT_SCHEMA_VIDEO = buildCheckOutputSchemaVideo("frame");
+var CHECK_OUTPUT_SCHEMA_NATIVE_VIDEO = buildCheckOutputSchemaVideo("moment");
 var ASK_OUTPUT_SCHEMA_IMAGE = `Respond with a JSON object matching this exact structure:
 {
   "summary": string,        // high-level analysis summary
@@ -329,6 +208,17 @@ ${ISSUE_SCHEMA_INSTRUCTIONS}
 Prioritize issues by severity (critical / major / minor) as for image input.
 Cite frame indices in "frameReferences" so the user can locate the moments you describe.
 ${JSON_INSTRUCTIONS}`;
+var ASK_OUTPUT_SCHEMA_NATIVE_VIDEO = `Respond with a JSON object matching this exact structure:
+{
+  "summary": string,                // high-level summary of what happens across the video
+  "issues": [...],                  // list of issues/findings, can be empty
+  "timestampReferences": number[]   // seconds from the start of the clip of the moments the answer relies on (in order)
+}
+${ISSUE_SCHEMA_INSTRUCTIONS}
+
+Prioritize issues by severity (critical / major / minor) as for image input.
+Cite timestamps in "timestampReferences" so the user can locate the moments you describe.
+${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
@@ -350,15 +240,26 @@ var DEFAULT_CHECK_ROLE = "You are a visual QA assistant. Evaluate the provided i
 var DEFAULT_CHECK_ROLE_VIDEO = "You are a visual QA assistant. Evaluate the provided sequence of video frames precisely and objectively, treating them as a chronological timeline.";
 var DEFAULT_ASK_ROLE = "You are a visual QA assistant. Analyze the provided image based on the user's request.";
 var DEFAULT_ASK_ROLE_VIDEO = "You are a visual QA assistant. Analyze the provided sequence of video frames as a chronological timeline based on the user's request.";
-function buildVideoTimelineSection(frameTimestamps, durationSeconds) {
+var DEFAULT_CHECK_ROLE_NATIVE_VIDEO = "You are a visual QA assistant. Evaluate the provided video recording precisely and objectively, treating it as a chronological timeline.";
+var DEFAULT_ASK_ROLE_NATIVE_VIDEO = "You are a visual QA assistant. Analyze the provided video recording as a chronological timeline based on the user's request.";
+function buildNativeVideoSection(durationSeconds) {
+  return `Video recording:
+- Total duration: ${durationSeconds.toFixed(2)}s
+
+The attached file is the complete video recording. Treat it as a chronological timeline and refer to moments by timestamp (seconds from the start of the clip) where helpful.`;
+}
+function buildVideoTimelineSection(frameTimestamps, durationSeconds, droppedUnchanged = 0) {
   const formatted = frameTimestamps.map((t, i) => `  ${i}: ${t.toFixed(2)}s`).join("\n");
+  const attached = frameTimestamps.length;
+  const sampledLine = droppedUnchanged > 0 ? `- ${attached + droppedUnchanged} frames sampled (in chronological order); ${droppedUnchanged} ${droppedUnchanged === 1 ? "was" : "were"} dropped because ${droppedUnchanged === 1 ? "it" : "they"} did not visibly change from the preceding kept frame, so ${attached} ${attached === 1 ? "image is" : "images are"} attached` : `- ${attached} frames sampled (in chronological order)`;
+  const droppedGuidance = droppedUnchanged > 0 ? ` Frames sampled between two consecutive listed timestamps looked the same as the earlier listed frame, and frames sampled after the last listed timestamp looked the same as the last attached image until the clip ended at ${durationSeconds.toFixed(2)}s.` : "";
   return `Video timeline:
 - Total duration: ${durationSeconds.toFixed(2)}s
-- ${frameTimestamps.length} frames sampled (in chronological order)
+${sampledLine}
 - Frame index \u2192 timestamp:
 ${formatted}
 
-Treat the attached images as a chronological timeline. The first image is the earliest frame, the last is the latest. Refer to frames by timestamp where helpful.`;
+Treat the attached images as a chronological timeline. The first image is the earliest frame, the last is the latest. Refer to frames by timestamp where helpful.${droppedGuidance}`;
 }
 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 = [
@@ -373,30 +274,52 @@ function buildCheckPrompt(statements, options) {
   const stmts = Array.isArray(statements) ? statements : [statements];
   const statementsBlock = stmts.map((s, i) => `${i + 1}. "${s}"`).join("\n");
   const media = options?.media;
-  const defaultRole = media?.kind === "video" ? DEFAULT_CHECK_ROLE_VIDEO : DEFAULT_CHECK_ROLE;
+  const defaultRole = media?.kind === "video" ? DEFAULT_CHECK_ROLE_VIDEO : media?.kind === "native-video" ? DEFAULT_CHECK_ROLE_NATIVE_VIDEO : DEFAULT_CHECK_ROLE;
   const sections = [options?.role ?? defaultRole];
   if (media?.kind === "video") {
-    sections.push(buildVideoTimelineSection(media.frameTimestamps, media.durationSeconds));
+    sections.push(
+      buildVideoTimelineSection(
+        media.frameTimestamps,
+        media.durationSeconds,
+        media.droppedUnchanged
+      )
+    );
+  } else if (media?.kind === "native-video") {
+    sections.push(buildNativeVideoSection(media.durationSeconds));
   }
   if (options?.instructions && options.instructions.length > 0) {
     sections.push(buildInstructionsSection(options.instructions));
   }
   sections.push(`Statements to evaluate:
 ${statementsBlock}`);
-  sections.push(media?.kind === "video" ? CHECK_OUTPUT_SCHEMA_VIDEO : CHECK_OUTPUT_SCHEMA_IMAGE);
+  sections.push(
+    media?.kind === "video" ? CHECK_OUTPUT_SCHEMA_VIDEO : media?.kind === "native-video" ? CHECK_OUTPUT_SCHEMA_NATIVE_VIDEO : CHECK_OUTPUT_SCHEMA_IMAGE
+  );
   return sections.join("\n\n");
 }
 function buildAskPrompt(userPrompt, options) {
   const media = options?.media;
-  const sections = [media?.kind === "video" ? DEFAULT_ASK_ROLE_VIDEO : DEFAULT_ASK_ROLE];
+  const sections = [
+    media?.kind === "video" ? DEFAULT_ASK_ROLE_VIDEO : media?.kind === "native-video" ? DEFAULT_ASK_ROLE_NATIVE_VIDEO : DEFAULT_ASK_ROLE
+  ];
   if (media?.kind === "video") {
-    sections.push(buildVideoTimelineSection(media.frameTimestamps, media.durationSeconds));
+    sections.push(
+      buildVideoTimelineSection(
+        media.frameTimestamps,
+        media.durationSeconds,
+        media.droppedUnchanged
+      )
+    );
+  } else if (media?.kind === "native-video") {
+    sections.push(buildNativeVideoSection(media.durationSeconds));
   }
   if (options?.instructions && options.instructions.length > 0) {
     sections.push(buildInstructionsSection(options.instructions));
   }
   sections.push(`User request: ${userPrompt}`);
-  sections.push(media?.kind === "video" ? ASK_OUTPUT_SCHEMA_VIDEO : ASK_OUTPUT_SCHEMA_IMAGE);
+  sections.push(
+    media?.kind === "video" ? ASK_OUTPUT_SCHEMA_VIDEO : media?.kind === "native-video" ? ASK_OUTPUT_SCHEMA_NATIVE_VIDEO : ASK_OUTPUT_SCHEMA_IMAGE
+  );
   return sections.join("\n\n");
 }
 function buildAiDiffPrompt() {
@@ -441,7 +364,7 @@ function visibleRole(finalState, requireCorrectRendering) {
 var ELEMENTS_VISIBLE_CLIPPING_RULES = [
   "When an element is partly rendered but cut off at an edge, decide whether ordinary scrolling would bring it fully into view. For example, a card peeking past the end of a horizontal carousel, a filter chip in a row that continues past the screen edge, or a list item partly below the bottom of a scrolling feed is reachable that way, so the check for that element PASSES. Say in your reasoning that it is reached by scrolling.",
   "An element that scrolling cannot bring into view is NOT properly visible: one sliced by the screen edge itself, or cut off or overlapped by fixed chrome such as the status bar, a notch, a home indicator, a sticky header, or a fixed bottom navigation bar. That is a layout fault, so the check for that element FAILS. Describe the clipping in your reasoning.",
-  "An element you cannot see at all is not visible, even if the page might reveal it after scrolling. Judge only what this screenshot actually shows."
+  "The scrolling allowance above applies only to elements that are at least partly rendered. If no part of an element is on screen, the check for that element FAILS: do not infer that it exists below the fold. Judge only what this screenshot actually shows."
 ];
 var ELEMENTS_VISIBLE_FINAL_STATE_RULE = "Judge each element in its finished, presented state. Things a design draws on top of an element \u2014 a badge, a favourite icon, a duration or price pill, a gradient scrim \u2014 coexist with finished content and leave it visible. An overlay that says the element is NOT ready \u2014 a loading spinner, a skeleton placeholder, a shimmer, a progress bar, an error or retry overlay \u2014 means the element is not properly visible even when you can still make out what sits underneath, so the check for that element FAILS. Name which of the two you are seeing in your reasoning.";
 var ELEMENTS_VISIBLE_CORRECT_RENDERING_RULE = "An element that is present but clearly defective in how it is rendered is NOT properly visible: text at contrast too low to read, elements overlapping or colliding with one another, an element visibly out of alignment with the siblings it should line up with, or text cut off mid-word inside its own container. The check for that element FAILS. In your reasoning, say that the element is present and then name the defect. Only clear, unambiguous defects count: do not fail an element for tight spacing, stylistic choices, or anything you would have to argue for.";
@@ -472,6 +395,144 @@ function buildElementsVisibilityPrompt(elements, visible, options) {
   return buildCheckPrompt(statements, { role, instructions });
 }
 
+// src/constants.ts
+var ReasoningEffort = {
+  MINIMAL: "minimal",
+  LOW: "low",
+  MEDIUM: "medium",
+  HIGH: "high",
+  XHIGH: "xhigh"
+};
+var ImageDetail = {
+  AUTO: "auto",
+  LOW: "low",
+  HIGH: "high"
+};
+var DEFAULT_IMAGE_DETAIL = ImageDetail.AUTO;
+var DEFAULT_MAX_IMAGE_DIMENSION = 1568;
+var Provider = {
+  ANTHROPIC: "anthropic",
+  OPENAI: "openai",
+  GOOGLE: "google",
+  OPENROUTER: "openrouter"
+};
+var Model = {
+  Anthropic: {
+    FABLE_5_1: "claude-fable-5-1",
+    FABLE_5: "claude-fable-5",
+    OPUS_5_5: "claude-opus-5-5",
+    OPUS_5: "claude-opus-5",
+    OPUS_4_8: "claude-opus-4-8",
+    OPUS_4_7: "claude-opus-4-7",
+    OPUS_4_6: "claude-opus-4-6",
+    SONNET_5_5: "claude-sonnet-5-5",
+    SONNET_5: "claude-sonnet-5",
+    SONNET_4_6: "claude-sonnet-4-6",
+    HAIKU_4_5: "claude-haiku-4-5"
+  },
+  OpenAI: {
+    GPT_6_ASTRA: "gpt-6-astra",
+    GPT_6_1_SOL: "gpt-6.1-sol",
+    GPT_6_SOL: "gpt-6-sol",
+    GPT_6_LUNA: "gpt-6-luna",
+    GPT_5_6_SOL: "gpt-5.6-sol",
+    GPT_5_6_TERRA: "gpt-5.6-terra",
+    GPT_5_6_LUNA: "gpt-5.6-luna",
+    GPT_5_5: "gpt-5.5",
+    GPT_5_4: "gpt-5.4",
+    GPT_5_4_PRO: "gpt-5.4-pro",
+    GPT_5_4_MINI: "gpt-5.4-mini",
+    GPT_5_4_NANO: "gpt-5.4-nano",
+    GPT_5_2: "gpt-5.2",
+    GPT_5_MINI: "gpt-5-mini"
+  },
+  Google: {
+    GEMINI_3_8_FLASH: "gemini-3.8-flash",
+    GEMINI_3_7_FLASH: "gemini-3.7-flash",
+    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: {
+    MUSE_SPARK_1_3: "meta/muse-spark-1.3",
+    GROK_4_7: "x-ai/grok-4.7",
+    GROK_4_6: "x-ai/grok-4.6",
+    GROK_4_5: "x-ai/grok-4.5",
+    KIMI_K3: "moonshotai/kimi-k3",
+    KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code",
+    QWEN_3_8_MAX: "qwen/qwen3.8-max",
+    QWEN_3_7_PLUS: "qwen/qwen3.7-plus",
+    QWEN_3_6_FLASH: "qwen/qwen3.6-flash",
+    GLM_5_3_FLASH: "z-ai/glm-5.3-flash",
+    MIMO_V2_6_PRO: "xiaomi/mimo-v2.6-pro"
+  }
+};
+var DEFAULT_MODELS = {
+  [Provider.ANTHROPIC]: Model.Anthropic.SONNET_5_5,
+  [Provider.OPENAI]: Model.OpenAI.GPT_6_1_SOL,
+  [Provider.GOOGLE]: Model.Google.GEMINI_3_8_FLASH,
+  [Provider.OPENROUTER]: Model.OpenRouter.MUSE_SPARK_1_3
+};
+var DEFAULT_MAX_TOKENS = 4096;
+var OPENAI_REASONING_MAX_TOKENS = 16384;
+var OPENAI_HEAVY_REASONING_MAX_TOKENS = 32768;
+var MODELS_REQUIRING_LARGE_OUTPUT_BUDGET = /* @__PURE__ */ new Set([
+  Model.OpenRouter.QWEN_3_8_MAX,
+  Model.OpenRouter.QWEN_3_7_PLUS
+]);
+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.OpenRouter).map((m) => [m, Provider.OPENROUTER])
+]);
+var VALID_PROVIDERS = Object.values(Provider);
+var PROVIDER_DEFAULT_REASONING = {
+  openai: "medium",
+  anthropic: "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 */
+  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",
+  /** Detects color choices likely to be indistinguishable to viewers with common color vision deficiencies */
+  COLOR_BLINDNESS: "color-blindness",
+  /** Detects information conveyed by color alone, without a non-color cue (icon, text, pattern, position) */
+  COLOR_ALONE: "color-alone"
+};
+
 // 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.";
@@ -581,17 +642,22 @@ function parseRetryAfter(value) {
 var XHIGH_CAPABLE_MODELS = /* @__PURE__ */ new Set([
   Model.Anthropic.FABLE_5_1,
   Model.Anthropic.FABLE_5,
+  Model.Anthropic.OPUS_5_5,
   Model.Anthropic.OPUS_5,
   Model.Anthropic.OPUS_4_8,
   Model.Anthropic.OPUS_4_7,
+  Model.Anthropic.SONNET_5_5,
   Model.Anthropic.SONNET_5
 ]);
 function mapEffort(level, model) {
+  if (level === "minimal") return "low";
   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 = {
+  // 1024 is Anthropic's minimum thinking budget, so minimal and low coincide.
+  minimal: 1024,
   low: 1024,
   medium: 4096,
   high: 8192,
@@ -697,11 +763,20 @@ var AnthropicDriver = class {
 
 // src/providers/google.ts
 var DEFAULT_IMAGE_GEN_MODEL = "gemini-2.5-flash-image";
+var GEMINI_INLINE_VIDEO_LIMIT_BYTES = 19 * 1024 * 1024;
+var GEMINI_FILE_POLL_INTERVAL_MS = 2e3;
+var GEMINI_FILE_POLL_TIMEOUT_MS = 5 * 6e4;
 function needsCodeExecution(model) {
   const match = model.match(/^gemini-(\d+)/);
   return match !== null && match[1] !== void 0 && parseInt(match[1], 10) >= 3;
 }
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
 var GOOGLE_THINKING_LEVEL = {
+  // Gemini does define a "minimal" thinking level, but some models reject it
+  // (e.g. Gemini 3.1 Pro), so "minimal" clamps to "low" here as well.
+  minimal: "low",
   low: "low",
   medium: "medium",
   high: "high",
@@ -768,24 +843,28 @@ var GoogleDriver = class {
     });
     return this.client;
   }
-  async sendMessage(images, prompt, _options) {
-    const client = await this.getClient();
+  /** Request config shared by image and video messages. */
+  generationConfig() {
+    return {
+      responseMimeType: "application/json",
+      maxOutputTokens: this.maxTokens,
+      ...this.reasoningEffort && {
+        thinkingConfig: {
+          thinkingLevel: GOOGLE_THINKING_LEVEL[this.reasoningEffort]
+        }
+      },
+      ...this.imageDetail && GOOGLE_MEDIA_RESOLUTION[this.imageDetail] && {
+        mediaResolution: GOOGLE_MEDIA_RESOLUTION[this.imageDetail]
+      }
+    };
+  }
+  /** Runs one generateContent call and normalizes finish reasons, text, and usage. */
+  async generate(client, contents) {
     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: {
-              thinkingLevel: GOOGLE_THINKING_LEVEL[this.reasoningEffort]
-            }
-          },
-          ...this.imageDetail && GOOGLE_MEDIA_RESOLUTION[this.imageDetail] && {
-            mediaResolution: GOOGLE_MEDIA_RESOLUTION[this.imageDetail]
-          }
-        }
+        contents,
+        config: this.generationConfig()
       });
       const finishReason = response.candidates?.[0]?.finishReason;
       if (finishReason === "MAX_TOKENS") {
@@ -800,9 +879,8 @@ var GoogleDriver = class {
           `Response blocked: Google returned finishReason "${finishReason}".`
         );
       }
-      const text = response.text ?? "";
       return {
-        text,
+        text: response.text ?? "",
         usage: toGeminiUsage(response.usageMetadata)
       };
     } catch (err) {
@@ -810,6 +888,80 @@ var GoogleDriver = class {
       throw mapProviderError(err);
     }
   }
+  async sendMessage(images, prompt, _options) {
+    const client = await this.getClient();
+    return this.generate(client, [...this.toGeminiParts(images), prompt]);
+  }
+  /**
+   * Uploads a video through the Files API and waits until Gemini has finished
+   * processing it. Returns the ACTIVE file record.
+   */
+  async uploadVideo(client, video) {
+    try {
+      const uploaded = await client.files.upload({
+        file: new Blob([new Uint8Array(video.data)], { type: video.mimeType }),
+        config: { mimeType: video.mimeType }
+      });
+      const name = uploaded.name;
+      if (!name) {
+        throw new VisualAIProviderError("Gemini Files API returned a file without a name.");
+      }
+      const deadline = Date.now() + GEMINI_FILE_POLL_TIMEOUT_MS;
+      let current = uploaded;
+      while (current.state === "PROCESSING") {
+        if (Date.now() > deadline) {
+          throw new VisualAIProviderError(
+            `Gemini file ${name} was still processing after ${GEMINI_FILE_POLL_TIMEOUT_MS}ms.`
+          );
+        }
+        await sleep(GEMINI_FILE_POLL_INTERVAL_MS);
+        current = await client.files.get({ name });
+      }
+      if (current.state !== "ACTIVE") {
+        throw new VisualAIProviderError(
+          `Gemini file ${name} ended in state ${current.state ?? "unknown"}: ${current.error?.message ?? "no error message"}`
+        );
+      }
+      if (!current.uri) {
+        throw new VisualAIProviderError("Gemini Files API returned an ACTIVE file without a URI.");
+      }
+      return current;
+    } catch (err) {
+      if (err instanceof VisualAIProviderError) throw err;
+      throw mapProviderError(err);
+    }
+  }
+  /**
+   * Sends the video bytes themselves. Gemini samples the clip server-side at
+   * `video.fps` and, unlike sampled frames, also hears the audio track. Small
+   * videos go inline; larger ones are uploaded via the Files API and deleted
+   * again afterwards (they would expire on their own after 48 h).
+   */
+  async sendVideoMessage(video, prompt, _options) {
+    const client = await this.getClient();
+    const videoMetadata = { fps: video.fps };
+    if (video.data.byteLength <= GEMINI_INLINE_VIDEO_LIMIT_BYTES) {
+      const part = {
+        inlineData: { data: video.data.toString("base64"), mimeType: video.mimeType },
+        videoMetadata
+      };
+      const response = await this.generate(client, [part, prompt]);
+      return { ...response, delivery: "inline" };
+    }
+    const file = await this.uploadVideo(client, video);
+    try {
+      const part = {
+        fileData: { fileUri: file.uri, mimeType: file.mimeType ?? video.mimeType },
+        videoMetadata
+      };
+      const response = await this.generate(client, [part, prompt]);
+      return { ...response, delivery: "file" };
+    } finally {
+      if (file.name) {
+        await client.files.delete({ name: file.name }).catch(() => void 0);
+      }
+    }
+  }
   async generateImage(images, prompt, options) {
     const client = await this.getClient();
     const imageModel = options?.model ?? DEFAULT_IMAGE_GEN_MODEL;
@@ -942,6 +1094,9 @@ var OpenAIDriver = class {
 // src/providers/openrouter.ts
 var OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
 var OPENROUTER_REASONING_EFFORT = {
+  // OpenRouter normalizes upstream vendors to low/medium/high only, so
+  // "minimal" has no native equivalent and clamps to the floor.
+  minimal: "low",
   low: "low",
   medium: "medium",
   high: "high",
@@ -1101,10 +1256,20 @@ function parseBooleanEnv(envName, value) {
     `Invalid ${envName} value: "${value}". Use "true", "1", "false", or "0".`
   );
 }
+function parseReasoningEffortEnv(envName, value) {
+  if (value === void 0 || value === "") return void 0;
+  const levels = Object.values(ReasoningEffort);
+  const lower = value.toLowerCase();
+  if (levels.includes(lower)) return lower;
+  throw new VisualAIConfigError(
+    `Invalid ${envName} value: "${value}". Use one of: ${levels.join(", ")}.`
+  );
+}
 var debugDeprecationWarned = false;
 function resolveConfig(config) {
   const provider = resolveProvider(config);
   const model = config.model ?? process.env.VISUAL_AI_MODEL ?? DEFAULT_MODELS[provider];
+  const reasoningEffort = config.reasoningEffort ?? parseReasoningEffortEnv("VISUAL_AI_REASONING_EFFORT", process.env.VISUAL_AI_REASONING_EFFORT);
   const debug = config.debug ?? parseBooleanEnv("VISUAL_AI_DEBUG", process.env.VISUAL_AI_DEBUG) ?? false;
   const debugPrompt = config.debugPrompt ?? parseBooleanEnv("VISUAL_AI_DEBUG_PROMPT", process.env.VISUAL_AI_DEBUG_PROMPT) ?? false;
   const debugResponse = config.debugResponse ?? parseBooleanEnv("VISUAL_AI_DEBUG_RESPONSE", process.env.VISUAL_AI_DEBUG_RESPONSE) ?? false;
@@ -1122,12 +1287,12 @@ function resolveConfig(config) {
   }
   const userSetMaxTokens = config.maxTokens !== void 0;
   let maxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
-  const effortNeedsLargeBudget = config.reasoningEffort === "high" || config.reasoningEffort === "xhigh";
+  const effortNeedsLargeBudget = reasoningEffort === "high" || reasoningEffort === "xhigh";
   const modelNeedsLargeBudget = MODELS_REQUIRING_LARGE_OUTPUT_BUDGET.has(model);
   if (!userSetMaxTokens && (provider === "openai" || provider === "openrouter") && (effortNeedsLargeBudget || modelNeedsLargeBudget)) {
     maxTokens = modelNeedsLargeBudget ? OPENAI_HEAVY_REASONING_MAX_TOKENS : OPENAI_REASONING_MAX_TOKENS;
     if (debug) {
-      const reason = modelNeedsLargeBudget ? `model "${model}", which exhausts smaller budgets on reasoning at any effort` : `provider "${provider}" with reasoningEffort "${config.reasoningEffort}"`;
+      const reason = modelNeedsLargeBudget ? `model "${model}", which exhausts smaller budgets on reasoning at any effort` : `provider "${provider}" with reasoningEffort "${reasoningEffort}"`;
       process.stderr.write(
         `[visual-ai-assertions] Auto-increased maxTokens from ${DEFAULT_MAX_TOKENS} to ${maxTokens} for ${reason}.
 `
@@ -1139,7 +1304,7 @@ function resolveConfig(config) {
     apiKey: config.apiKey,
     model,
     maxTokens,
-    reasoningEffort: config.reasoningEffort,
+    reasoningEffort,
     maxImageDimension: config.maxImageDimension ?? DEFAULT_MAX_IMAGE_DIMENSION,
     imageDetail: config.imageDetail ?? DEFAULT_IMAGE_DETAIL,
     timeout: config.timeout,
@@ -1162,6 +1327,10 @@ var PRICING_TABLE = {
     inputPricePerToken: 10 / PER_MILLION,
     outputPricePerToken: 50 / PER_MILLION
   },
+  [`${Provider.ANTHROPIC}:${Model.Anthropic.OPUS_5_5}`]: {
+    inputPricePerToken: 4 / PER_MILLION,
+    outputPricePerToken: 20 / PER_MILLION
+  },
   [`${Provider.ANTHROPIC}:${Model.Anthropic.OPUS_5}`]: {
     inputPricePerToken: 5 / PER_MILLION,
     outputPricePerToken: 25 / PER_MILLION
@@ -1170,6 +1339,10 @@ var PRICING_TABLE = {
     inputPricePerToken: 5 / PER_MILLION,
     outputPricePerToken: 25 / PER_MILLION
   },
+  [`${Provider.ANTHROPIC}:${Model.Anthropic.SONNET_5_5}`]: {
+    inputPricePerToken: 2 / PER_MILLION,
+    outputPricePerToken: 10 / PER_MILLION
+  },
   [`${Provider.ANTHROPIC}:${Model.Anthropic.SONNET_5}`]: {
     inputPricePerToken: 3 / PER_MILLION,
     outputPricePerToken: 15 / PER_MILLION
@@ -1196,6 +1369,22 @@ var PRICING_TABLE = {
     inputPricePerToken: 10 / PER_MILLION,
     outputPricePerToken: 50 / PER_MILLION
   },
+  // Cached input is $0.10/MTok (not modelled), half GPT-6 Sol's cached rate.
+  [`${Provider.OPENAI}:${Model.OpenAI.GPT_6_1_SOL}`]: {
+    inputPricePerToken: 2 / PER_MILLION,
+    outputPricePerToken: 10 / PER_MILLION
+  },
+  // Cached input is $0.20/MTok (not modelled). Prompts above 272K input tokens
+  // bill at 2x input / 1.5x output, which is far beyond screenshot-sized calls.
+  [`${Provider.OPENAI}:${Model.OpenAI.GPT_6_SOL}`]: {
+    inputPricePerToken: 2 / PER_MILLION,
+    outputPricePerToken: 10 / PER_MILLION
+  },
+  // Cached input is $0.01/MTok and cache writes $0.125/MTok; neither is modelled.
+  [`${Provider.OPENAI}:${Model.OpenAI.GPT_6_LUNA}`]: {
+    inputPricePerToken: 0.1 / PER_MILLION,
+    outputPricePerToken: 0.5 / PER_MILLION
+  },
   [`${Provider.OPENAI}:${Model.OpenAI.GPT_5_6_SOL}`]: {
     inputPricePerToken: 5 / PER_MILLION,
     outputPricePerToken: 30 / PER_MILLION
@@ -1292,6 +1481,10 @@ var PRICING_TABLE = {
     inputPricePerToken: 0.1 / PER_MILLION,
     outputPricePerToken: 0.2 / PER_MILLION
   },
+  [`${Provider.OPENROUTER}:${Model.OpenRouter.GROK_4_7}`]: {
+    inputPricePerToken: 1.6 / PER_MILLION,
+    outputPricePerToken: 4.8 / PER_MILLION
+  },
   [`${Provider.OPENROUTER}:${Model.OpenRouter.GROK_4_6}`]: {
     inputPricePerToken: 2 / PER_MILLION,
     outputPricePerToken: 6 / PER_MILLION
@@ -1325,6 +1518,13 @@ var PRICING_TABLE = {
   [`${Provider.OPENROUTER}:${Model.OpenRouter.GLM_5_3_FLASH}`]: {
     inputPricePerToken: 0.15 / PER_MILLION,
     outputPricePerToken: 0.5 / PER_MILLION
+  },
+  // Verified 2026-09-23 against https://openrouter.ai/api/v1/models; both
+  // upstream endpoints (Xiaomi, DeepInfra) charge the same rate. Cached input
+  // is $0.0036/MTok, not modelled (no provider gets a cache discount here).
+  [`${Provider.OPENROUTER}:${Model.OpenRouter.MIMO_V2_6_PRO}`]: {
+    inputPricePerToken: 0.435 / PER_MILLION,
+    outputPricePerToken: 0.87 / PER_MILLION
   }
 };
 function calculateCost(provider, model, inputTokens, outputTokens) {
@@ -1402,6 +1602,15 @@ async function timedSendMessage(driver, images, prompt, options) {
   const durationSeconds = (performance.now() - start) / 1e3;
   return { ...response, durationSeconds };
 }
+async function timedSendVideoMessage(driver, video, prompt, options) {
+  if (!driver.sendVideoMessage) {
+    throw new VisualAIError("Provider driver does not support native video delivery");
+  }
+  const start = performance.now();
+  const response = await driver.sendVideoMessage(video, prompt, options);
+  const durationSeconds = (performance.now() - start) / 1e3;
+  return { ...response, durationSeconds };
+}
 
 // src/core/diff.ts
 import sharp from "sharp";
@@ -1641,6 +1850,9 @@ async function normalizeImage(input, maxDimension = DEFAULT_MAX_IMAGE_DIMENSION)
   };
 }
 
+// src/core/media.ts
+import { readFile as readFile3 } from "fs/promises";
+
 // src/core/debug-frames.ts
 import { randomBytes } from "crypto";
 import { mkdir, writeFile } from "fs/promises";
@@ -1696,6 +1908,92 @@ async function saveDebugFrames(frames, env = process.env) {
   return runDir;
 }
 
+// src/core/frame-dedupe.ts
+import sharp3 from "sharp";
+var DEDUPE_THUMBNAIL_EDGE = 256;
+var DEDUPE_PIXEL_TOLERANCE = 24;
+var DEFAULT_DEDUPE_THRESHOLD = 1e-3;
+function resolveDedupeOptions(raw) {
+  if (raw === void 0 || raw === true) {
+    return { enabled: true, threshold: DEFAULT_DEDUPE_THRESHOLD };
+  }
+  if (raw === false) {
+    return { enabled: false, threshold: DEFAULT_DEDUPE_THRESHOLD };
+  }
+  const threshold = raw.threshold ?? DEFAULT_DEDUPE_THRESHOLD;
+  if (!Number.isFinite(threshold) || threshold <= 0 || threshold > 1) {
+    throw new VisualAIVideoError(
+      `Invalid dedupe threshold: ${String(threshold)}. Must be a finite number in (0, 1].`
+    );
+  }
+  return { enabled: true, threshold };
+}
+async function frameSignature(frame) {
+  try {
+    const { data, info } = await sharp3(frame.data).flatten({ background: { r: 255, g: 255, b: 255 } }).greyscale().resize(DEDUPE_THUMBNAIL_EDGE, DEDUPE_THUMBNAIL_EDGE, {
+      fit: "inside",
+      withoutEnlargement: true
+    }).raw().toBuffer({ resolveWithObject: true });
+    return { width: info.width, height: info.height, pixels: data };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new VisualAIVideoError(
+      `Failed to decode frame ${frame.index} (${frame.timestampSeconds.toFixed(2)}s) for change detection: ${reason}`
+    );
+  }
+}
+function changedFraction(a, b) {
+  if (a.width !== b.width || a.height !== b.height) {
+    return 1;
+  }
+  let changed = 0;
+  for (let i = 0; i < a.pixels.length; i++) {
+    if (Math.abs((a.pixels[i] ?? 0) - (b.pixels[i] ?? 0)) > DEDUPE_PIXEL_TOLERANCE) {
+      changed++;
+    }
+  }
+  return changed / a.pixels.length;
+}
+function reindex(frame, index) {
+  if (frame.index === index) {
+    return frame;
+  }
+  return {
+    data: frame.data,
+    mimeType: frame.mimeType,
+    get base64() {
+      return frame.base64;
+    },
+    timestampSeconds: frame.timestampSeconds,
+    index
+  };
+}
+async function dedupeFrames(frames, options) {
+  const { enabled, threshold } = resolveDedupeOptions(options);
+  if (!enabled || frames.length < 2) {
+    return { frames: [...frames], dropped: 0 };
+  }
+  const signed = await Promise.all(
+    frames.map(async (frame) => ({ frame, signature: await frameSignature(frame) }))
+  );
+  const [first, ...rest] = signed;
+  if (first === void 0) {
+    return { frames: [], dropped: 0 };
+  }
+  const kept = [first.frame];
+  let lastKept = first.signature;
+  for (const { frame, signature } of rest) {
+    if (changedFraction(lastKept, signature) >= threshold) {
+      kept.push(frame);
+      lastKept = signature;
+    }
+  }
+  return {
+    frames: kept.map((frame, index) => reindex(frame, index)),
+    dropped: frames.length - kept.length
+  };
+}
+
 // src/core/video.ts
 import { mkdtemp, readFile as readFile2, readdir, rm, writeFile as writeFile2 } from "fs/promises";
 import { tmpdir } from "os";
@@ -1931,7 +2229,7 @@ async function probeDurationSeconds(videoPath) {
     });
   });
 }
-async function extractFrames(videoPath, options = {}, maxDimension = FRAME_MAX_DIMENSION) {
+function resolveVideoSamplingOptions(options = {}) {
   const fps = options.fps ?? DEFAULT_FPS;
   const maxFrames = options.maxFrames ?? DEFAULT_MAX_FRAMES;
   const maxDurationSeconds = options.maxDurationSeconds ?? DEFAULT_MAX_DURATION_SECONDS;
@@ -1951,13 +2249,20 @@ async function extractFrames(videoPath, options = {}, maxDimension = FRAME_MAX_D
       `Invalid maxDurationSeconds: ${maxDurationSeconds}. Must be a finite number > 0.`
     );
   }
-  const ffmpeg = await loadFfmpegFactory();
-  const durationSeconds = await probeDurationSeconds(videoPath);
+  return { fps, maxFrames, maxDurationSeconds };
+}
+function assertDurationWithinLimit(durationSeconds, maxDurationSeconds) {
   if (durationSeconds > maxDurationSeconds) {
     throw new VisualAIVideoError(
       `Video duration ${durationSeconds.toFixed(2)}s exceeds limit of ${maxDurationSeconds}s. Pass { maxDurationSeconds: N } to override, or trim the source video.`
     );
   }
+}
+async function extractFrames(videoPath, options = {}, maxDimension = FRAME_MAX_DIMENSION) {
+  const { fps, maxFrames, maxDurationSeconds } = resolveVideoSamplingOptions(options);
+  const ffmpeg = await loadFfmpegFactory();
+  const durationSeconds = await probeDurationSeconds(videoPath);
+  assertDurationWithinLimit(durationSeconds, maxDurationSeconds);
   const outputDir = await mkdtemp(join2(tmpdir(), "visual-ai-frames-"));
   try {
     const filter = `fps=${fps},scale='if(gt(iw,ih),min(${maxDimension},iw),-2)':'if(gt(iw,ih),-2,min(${maxDimension},ih))':flags=area`;
@@ -2061,6 +2366,7 @@ function isTimestampedFrameInput(frame) {
 async function normalizeFrames(input, maxDimension = DEFAULT_MAX_IMAGE_DIMENSION) {
   const rawFrames = input.frames;
   const fps = input.fps ?? DEFAULT_FPS;
+  resolveDedupeOptions(input.dedupe);
   if (rawFrames.length === 0) {
     throw new VisualAIVideoError("frames must be a non-empty array of image inputs");
   }
@@ -2072,7 +2378,7 @@ async function normalizeFrames(input, maxDimension = DEFAULT_MAX_IMAGE_DIMENSION
   if (!Number.isFinite(fps) || fps <= 0) {
     throw new VisualAIVideoError(`Invalid fps: ${fps}. Must be a finite number > 0.`);
   }
-  const frames = await Promise.all(
+  const sampled = await Promise.all(
     rawFrames.map(async (raw, index) => {
       const timestamped = isTimestampedFrameInput(raw);
       const imageInput = timestamped ? raw.image : raw;
@@ -2095,20 +2401,45 @@ async function normalizeFrames(input, maxDimension = DEFAULT_MAX_IMAGE_DIMENSION
       };
     })
   );
-  const durationSeconds = frames.reduce((max, f) => Math.max(max, f.timestampSeconds), 0);
+  const durationSeconds = sampled.reduce((max, f) => Math.max(max, f.timestampSeconds), 0);
+  const { frames, dropped } = await dedupeFrames(sampled, input.dedupe);
   await saveDebugFrames(frames);
-  return { kind: "video", frames, durationSeconds };
+  return { kind: "video", frames, durationSeconds, droppedUnchanged: dropped };
+}
+async function normalizeNativeVideo(input, videoOptions) {
+  const { fps, maxDurationSeconds } = resolveVideoSamplingOptions(videoOptions);
+  const { path, mimeType, cleanup } = await resolveVideoToPath(input);
+  try {
+    const durationSeconds = await probeDurationSeconds(path);
+    assertDurationWithinLimit(durationSeconds, maxDurationSeconds);
+    const data = await readFile3(path);
+    return { kind: "native-video", video: { data, mimeType, durationSeconds, fps } };
+  } finally {
+    try {
+      await cleanup();
+    } catch {
+    }
+  }
 }
-async function normalizeMedia(input, videoOptions, maxDimension = DEFAULT_MAX_IMAGE_DIMENSION) {
+async function normalizeMedia(input, videoOptions, maxDimension = DEFAULT_MAX_IMAGE_DIMENSION, nativeVideo = false) {
   if (isFramesInput(input)) {
     return normalizeFrames(input, maxDimension);
   }
   if (isVideoInput(input)) {
+    if (nativeVideo) {
+      return normalizeNativeVideo(input, videoOptions);
+    }
+    resolveDedupeOptions(videoOptions?.dedupe);
     const { path, cleanup } = await resolveVideoToPath(input);
     try {
-      const { frames, durationSeconds } = await extractFrames(path, videoOptions, maxDimension);
+      const { frames: sampled, durationSeconds } = await extractFrames(
+        path,
+        videoOptions,
+        maxDimension
+      );
+      const { frames, dropped } = await dedupeFrames(sampled, videoOptions?.dedupe);
       await saveDebugFrames(frames);
-      return { kind: "video", frames, durationSeconds };
+      return { kind: "video", frames, durationSeconds, droppedUnchanged: dropped };
     } finally {
       try {
         await cleanup();
@@ -2198,6 +2529,12 @@ var AskResultSchema = z.object({
    * omitting the key, even for image inputs that were never asked to populate it.
    */
   frameReferences: z.array(z.number().int().nonnegative()).nullable().optional(),
+  /**
+   * For natively delivered video, the timestamps (seconds from the start of
+   * the clip) the model relied on to answer. The native counterpart of
+   * `frameReferences`. Nullable for the same strict-schema reason.
+   */
+  timestampReferences: z.array(z.number().nonnegative()).nullable().optional(),
   usage: UsageInfoSchema.optional()
 });
 
@@ -2209,6 +2546,12 @@ function stripCodeFences(text) {
 }
 var CheckResponseSchema = CheckResultSchema.omit({ usage: true });
 var AskResponseSchema = AskResultSchema.omit({ usage: true });
+var AskImageResponseSchema = AskResponseSchema.omit({
+  frameReferences: true,
+  timestampReferences: true
+});
+var AskFramesResponseSchema = AskResponseSchema.omit({ timestampReferences: true });
+var AskNativeVideoResponseSchema = AskResponseSchema.omit({ frameReferences: true });
 var CompareResponseSchema = CompareResultSchema.omit({ usage: true });
 var STRAY_CONTROL_CHARS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
 function parseJson(text) {
@@ -2276,7 +2619,8 @@ function parseAskResponse(raw) {
   const result = parseResponse(raw, AskResponseSchema);
   return {
     ...result,
-    frameReferences: result.frameReferences ?? void 0
+    frameReferences: result.frameReferences ?? void 0,
+    timestampReferences: result.timestampReferences ?? void 0
   };
 }
 function parseCompareResponse(raw) {
@@ -2300,31 +2644,75 @@ function createDriver(provider, config) {
   return PROVIDER_REGISTRY[provider](config);
 }
 var checkSchemaOptions = toSchemaOptions(CheckResponseSchema);
-var askSchemaOptions = toSchemaOptions(AskResponseSchema);
+var askSchemaOptionsByMedia = {
+  image: toSchemaOptions(AskImageResponseSchema),
+  video: toSchemaOptions(AskFramesResponseSchema),
+  "native-video": toSchemaOptions(AskNativeVideoResponseSchema)
+};
 var compareSchemaOptions = toSchemaOptions(CompareResponseSchema);
 function mediaToProviderInputs(media) {
   if (media.kind === "image") {
     return {
+      kind: "images",
       images: [media.image],
       mediaContext: { kind: "image" },
-      framesMetadata: void 0
+      frames: void 0
+    };
+  }
+  if (media.kind === "native-video") {
+    return {
+      kind: "native-video",
+      video: media.video,
+      mediaContext: { kind: "native-video", durationSeconds: media.video.durationSeconds }
     };
   }
   const timestamps = media.frames.map((f) => f.timestampSeconds);
   return {
+    kind: "images",
     images: media.frames,
     mediaContext: {
       kind: "video",
       frameTimestamps: timestamps,
-      durationSeconds: media.durationSeconds
+      durationSeconds: media.durationSeconds,
+      droppedUnchanged: media.droppedUnchanged
     },
-    framesMetadata: {
+    frames: {
       count: media.frames.length,
       timestampsSeconds: timestamps,
-      durationSeconds: media.durationSeconds
+      durationSeconds: media.durationSeconds,
+      droppedUnchanged: media.droppedUnchanged
     }
   };
 }
+async function sendMedia(driver, dispatch, prompt, options) {
+  if (dispatch.kind === "native-video") {
+    const response2 = await timedSendVideoMessage(driver, dispatch.video, prompt, options);
+    const { durationSeconds, fps, mimeType } = dispatch.video;
+    return {
+      response: response2,
+      metadata: { video: { durationSeconds, fps, mimeType, delivery: response2.delivery } }
+    };
+  }
+  const response = await timedSendMessage(driver, dispatch.images, prompt, options);
+  return { response, metadata: dispatch.frames ? { frames: dispatch.frames } : {} };
+}
+function resolveNativeVideo(input, videoOptions, driver, provider) {
+  const mode = videoOptions?.mode ?? "auto";
+  if (mode !== "auto" && mode !== "native" && mode !== "frames") {
+    throw new VisualAIConfigError(
+      `Invalid video mode: ${mode}. Expected "auto", "native", or "frames".`
+    );
+  }
+  const supported = typeof driver.sendVideoMessage === "function";
+  if (mode === "frames") return false;
+  if (mode === "auto") return supported;
+  if (!supported && !isFramesInput(input) && isVideoInput(input)) {
+    throw new VisualAIConfigError(
+      `Native video delivery is not supported by the "${provider}" provider. Use a Google model, or set video: { mode: "frames" } to sample frames instead.`
+    );
+  }
+  return true;
+}
 function visualAI(config = {}) {
   const resolvedConfig = resolveConfig(config);
   const driverConfig = {
@@ -2362,38 +2750,60 @@ function visualAI(config = {}) {
         throw new VisualAIConfigError("At least one statement is required for check()");
       }
       return withErrorDebug(resolvedConfig, "check", async () => {
-        const media = await normalizeMedia(input, options?.video, maxImageDimension);
-        const { images, mediaContext, framesMetadata } = mediaToProviderInputs(media);
+        const nativeVideo = resolveNativeVideo(
+          input,
+          options?.video,
+          driver,
+          resolvedConfig.provider
+        );
+        const media = await normalizeMedia(input, options?.video, maxImageDimension, nativeVideo);
+        const dispatch = mediaToProviderInputs(media);
         const prompt = buildCheckPrompt(stmts, {
           instructions: options?.instructions,
-          media: mediaContext
+          media: dispatch.mediaContext
         });
         debugLog(resolvedConfig, "check prompt", prompt, "prompt");
-        const response = await timedSendMessage(driver, images, prompt, checkSchemaOptions);
+        const { response, metadata } = await sendMedia(
+          driver,
+          dispatch,
+          prompt,
+          checkSchemaOptions
+        );
         debugLog(resolvedConfig, "check response", response.text, "response");
         const result = parseCheckResponse(response.text);
         return {
           ...result,
-          ...framesMetadata ? { frames: framesMetadata } : {},
+          ...metadata,
           usage: processUsage("check", response.usage, response.durationSeconds, resolvedConfig)
         };
       });
     },
     async ask(input, userPrompt, options) {
       return withErrorDebug(resolvedConfig, "ask", async () => {
-        const media = await normalizeMedia(input, options?.video, maxImageDimension);
-        const { images, mediaContext, framesMetadata } = mediaToProviderInputs(media);
+        const nativeVideo = resolveNativeVideo(
+          input,
+          options?.video,
+          driver,
+          resolvedConfig.provider
+        );
+        const media = await normalizeMedia(input, options?.video, maxImageDimension, nativeVideo);
+        const dispatch = mediaToProviderInputs(media);
         const prompt = buildAskPrompt(userPrompt, {
           instructions: options?.instructions,
-          media: mediaContext
+          media: dispatch.mediaContext
         });
         debugLog(resolvedConfig, "ask prompt", prompt, "prompt");
-        const response = await timedSendMessage(driver, images, prompt, askSchemaOptions);
+        const { response, metadata } = await sendMedia(
+          driver,
+          dispatch,
+          prompt,
+          askSchemaOptionsByMedia[dispatch.mediaContext.kind]
+        );
         debugLog(resolvedConfig, "ask response", response.text, "response");
         const result = parseAskResponse(response.text);
         return {
           ...result,
-          ...framesMetadata ? { frames: framesMetadata } : {},
+          ...metadata,
           usage: processUsage("ask", response.usage, response.durationSeconds, resolvedConfig)
         };
       });
@@ -2411,7 +2821,7 @@ function visualAI(config = {}) {
         debugLog(resolvedConfig, "compare prompt", prompt, "prompt");
         const response = await timedSendMessage(driver, [imgA, imgB], prompt, compareSchemaOptions);
         debugLog(resolvedConfig, "compare response", response.text, "response");
-        const supportsAnnotatedDiff = resolvedConfig.provider === "google" && resolvedConfig.model === Model.Google.GEMINI_3_FLASH_PREVIEW;
+        const supportsAnnotatedDiff = resolvedConfig.provider === "google" && DIFF_ALLOWED_MODELS.has(resolvedConfig.model);
         const effectiveDiffImage = options?.diffImage ?? (supportsAnnotatedDiff ? true : false);
         let diffImage;
         if (effectiveDiffImage) {