visual-ai-assertions 0.16.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +17 -6
  2. package/dist/index.cjs +165 -52
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +101 -1
  5. package/dist/index.d.ts +101 -1
  6. package/dist/index.js +164 -52
  7. package/dist/index.js.map +1 -1
  8. package/package.json +6 -2
package/dist/index.d.cts CHANGED
@@ -9,6 +9,19 @@ declare const ReasoningEffort: {
9
9
  };
10
10
  /** Union of valid reasoning effort values, derived from the ReasoningEffort constant. */
11
11
  type ReasoningEffortLevel = (typeof ReasoningEffort)[keyof typeof ReasoningEffort];
12
+ /**
13
+ * Abstract image-detail hint. Each provider driver maps it to its native
14
+ * mechanism (OpenAI/OpenRouter `detail`, Google `mediaResolution`); Anthropic
15
+ * has no equivalent (Claude auto-downscales to ~1568px / 1.15MP regardless).
16
+ * `"auto"` sends no detail field, preserving each provider's default.
17
+ */
18
+ declare const ImageDetail: {
19
+ readonly AUTO: "auto";
20
+ readonly LOW: "low";
21
+ readonly HIGH: "high";
22
+ };
23
+ /** Union of valid image-detail values, derived from the ImageDetail constant. */
24
+ type ImageDetailLevel = (typeof ImageDetail)[keyof typeof ImageDetail];
12
25
  /** Supported provider identifiers used internally for pricing and provider selection. */
13
26
  declare const Provider: {
14
27
  readonly ANTHROPIC: "anthropic";
@@ -20,6 +33,7 @@ declare const Provider: {
20
33
  declare const Model: {
21
34
  readonly Anthropic: {
22
35
  readonly FABLE_5: "claude-fable-5";
36
+ readonly OPUS_5: "claude-opus-5";
23
37
  readonly OPUS_4_8: "claude-opus-4-8";
24
38
  readonly OPUS_4_7: "claude-opus-4-7";
25
39
  readonly OPUS_4_6: "claude-opus-4-6";
@@ -40,6 +54,8 @@ declare const Model: {
40
54
  readonly GPT_5_MINI: "gpt-5-mini";
41
55
  };
42
56
  readonly Google: {
57
+ readonly GEMINI_3_8_FLASH: "gemini-3.8-flash";
58
+ readonly GEMINI_3_7_FLASH: "gemini-3.7-flash";
43
59
  readonly GEMINI_3_6_FLASH: "gemini-3.6-flash";
44
60
  readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
45
61
  readonly GEMINI_3_5_FLASH_LITE: "gemini-3.5-flash-lite";
@@ -53,9 +69,12 @@ declare const Model: {
53
69
  * recognizes them. All listed models accept image input.
54
70
  */
55
71
  readonly OpenRouter: {
72
+ readonly MUSE_SPARK_1_3: "meta/muse-spark-1.3";
73
+ readonly GROK_4_6: "x-ai/grok-4.6";
56
74
  readonly GROK_4_5: "x-ai/grok-4.5";
57
75
  readonly KIMI_K3: "moonshotai/kimi-k3";
58
76
  readonly KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code";
77
+ readonly QWEN_3_8_MAX: "qwen/qwen3.8-max";
59
78
  readonly QWEN_3_7_PLUS: "qwen/qwen3.7-plus";
60
79
  readonly QWEN_3_6_FLASH: "qwen/qwen3.6-flash";
61
80
  };
@@ -173,19 +192,33 @@ declare const UsageInfoSchema: z.ZodObject<{
173
192
  outputTokens: z.ZodNumber;
174
193
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
175
194
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
195
+ /**
196
+ * Prompt tokens served from the provider's cache, when reported. Informational
197
+ * only — `estimatedCost` does not apply a cache discount, because providers
198
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
199
+ * Google) or billed as a separate bucket alongside it (Anthropic).
200
+ */
201
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
202
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
176
203
  estimatedCost: z.ZodOptional<z.ZodNumber>;
204
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
205
+ reportedCost: z.ZodOptional<z.ZodNumber>;
177
206
  durationSeconds: z.ZodOptional<z.ZodNumber>;
178
207
  }, "strip", z.ZodTypeAny, {
179
208
  inputTokens: number;
180
209
  outputTokens: number;
181
210
  reasoningTokens?: number | undefined;
211
+ cachedInputTokens?: number | undefined;
182
212
  estimatedCost?: number | undefined;
213
+ reportedCost?: number | undefined;
183
214
  durationSeconds?: number | undefined;
184
215
  }, {
185
216
  inputTokens: number;
186
217
  outputTokens: number;
187
218
  reasoningTokens?: number | undefined;
219
+ cachedInputTokens?: number | undefined;
188
220
  estimatedCost?: number | undefined;
221
+ reportedCost?: number | undefined;
189
222
  durationSeconds?: number | undefined;
190
223
  }>;
191
224
  /** Token usage and optional cost/latency metadata for a provider call. */
@@ -206,19 +239,33 @@ declare const CheckResultSchema: z.ZodObject<{
206
239
  outputTokens: z.ZodNumber;
207
240
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
208
241
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
242
+ /**
243
+ * Prompt tokens served from the provider's cache, when reported. Informational
244
+ * only — `estimatedCost` does not apply a cache discount, because providers
245
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
246
+ * Google) or billed as a separate bucket alongside it (Anthropic).
247
+ */
248
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
249
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
209
250
  estimatedCost: z.ZodOptional<z.ZodNumber>;
251
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
252
+ reportedCost: z.ZodOptional<z.ZodNumber>;
210
253
  durationSeconds: z.ZodOptional<z.ZodNumber>;
211
254
  }, "strip", z.ZodTypeAny, {
212
255
  inputTokens: number;
213
256
  outputTokens: number;
214
257
  reasoningTokens?: number | undefined;
258
+ cachedInputTokens?: number | undefined;
215
259
  estimatedCost?: number | undefined;
260
+ reportedCost?: number | undefined;
216
261
  durationSeconds?: number | undefined;
217
262
  }, {
218
263
  inputTokens: number;
219
264
  outputTokens: number;
220
265
  reasoningTokens?: number | undefined;
266
+ cachedInputTokens?: number | undefined;
221
267
  estimatedCost?: number | undefined;
268
+ reportedCost?: number | undefined;
222
269
  durationSeconds?: number | undefined;
223
270
  }>>;
224
271
  } & {
@@ -282,7 +329,9 @@ declare const CheckResultSchema: z.ZodObject<{
282
329
  inputTokens: number;
283
330
  outputTokens: number;
284
331
  reasoningTokens?: number | undefined;
332
+ cachedInputTokens?: number | undefined;
285
333
  estimatedCost?: number | undefined;
334
+ reportedCost?: number | undefined;
286
335
  durationSeconds?: number | undefined;
287
336
  } | undefined;
288
337
  }, {
@@ -305,7 +354,9 @@ declare const CheckResultSchema: z.ZodObject<{
305
354
  inputTokens: number;
306
355
  outputTokens: number;
307
356
  reasoningTokens?: number | undefined;
357
+ cachedInputTokens?: number | undefined;
308
358
  estimatedCost?: number | undefined;
359
+ reportedCost?: number | undefined;
309
360
  durationSeconds?: number | undefined;
310
361
  } | undefined;
311
362
  }>;
@@ -348,19 +399,33 @@ declare const CompareResultSchema: z.ZodObject<{
348
399
  outputTokens: z.ZodNumber;
349
400
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
350
401
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
402
+ /**
403
+ * Prompt tokens served from the provider's cache, when reported. Informational
404
+ * only — `estimatedCost` does not apply a cache discount, because providers
405
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
406
+ * Google) or billed as a separate bucket alongside it (Anthropic).
407
+ */
408
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
409
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
351
410
  estimatedCost: z.ZodOptional<z.ZodNumber>;
411
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
412
+ reportedCost: z.ZodOptional<z.ZodNumber>;
352
413
  durationSeconds: z.ZodOptional<z.ZodNumber>;
353
414
  }, "strip", z.ZodTypeAny, {
354
415
  inputTokens: number;
355
416
  outputTokens: number;
356
417
  reasoningTokens?: number | undefined;
418
+ cachedInputTokens?: number | undefined;
357
419
  estimatedCost?: number | undefined;
420
+ reportedCost?: number | undefined;
358
421
  durationSeconds?: number | undefined;
359
422
  }, {
360
423
  inputTokens: number;
361
424
  outputTokens: number;
362
425
  reasoningTokens?: number | undefined;
426
+ cachedInputTokens?: number | undefined;
363
427
  estimatedCost?: number | undefined;
428
+ reportedCost?: number | undefined;
364
429
  durationSeconds?: number | undefined;
365
430
  }>>;
366
431
  } & {
@@ -385,7 +450,9 @@ declare const CompareResultSchema: z.ZodObject<{
385
450
  inputTokens: number;
386
451
  outputTokens: number;
387
452
  reasoningTokens?: number | undefined;
453
+ cachedInputTokens?: number | undefined;
388
454
  estimatedCost?: number | undefined;
455
+ reportedCost?: number | undefined;
389
456
  durationSeconds?: number | undefined;
390
457
  } | undefined;
391
458
  }, {
@@ -399,7 +466,9 @@ declare const CompareResultSchema: z.ZodObject<{
399
466
  inputTokens: number;
400
467
  outputTokens: number;
401
468
  reasoningTokens?: number | undefined;
469
+ cachedInputTokens?: number | undefined;
402
470
  estimatedCost?: number | undefined;
471
+ reportedCost?: number | undefined;
403
472
  durationSeconds?: number | undefined;
404
473
  } | undefined;
405
474
  }>;
@@ -447,19 +516,33 @@ declare const AskResultSchema: z.ZodObject<{
447
516
  outputTokens: z.ZodNumber;
448
517
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
449
518
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
519
+ /**
520
+ * Prompt tokens served from the provider's cache, when reported. Informational
521
+ * only — `estimatedCost` does not apply a cache discount, because providers
522
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
523
+ * Google) or billed as a separate bucket alongside it (Anthropic).
524
+ */
525
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
526
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
450
527
  estimatedCost: z.ZodOptional<z.ZodNumber>;
528
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
529
+ reportedCost: z.ZodOptional<z.ZodNumber>;
451
530
  durationSeconds: z.ZodOptional<z.ZodNumber>;
452
531
  }, "strip", z.ZodTypeAny, {
453
532
  inputTokens: number;
454
533
  outputTokens: number;
455
534
  reasoningTokens?: number | undefined;
535
+ cachedInputTokens?: number | undefined;
456
536
  estimatedCost?: number | undefined;
537
+ reportedCost?: number | undefined;
457
538
  durationSeconds?: number | undefined;
458
539
  }, {
459
540
  inputTokens: number;
460
541
  outputTokens: number;
461
542
  reasoningTokens?: number | undefined;
543
+ cachedInputTokens?: number | undefined;
462
544
  estimatedCost?: number | undefined;
545
+ reportedCost?: number | undefined;
463
546
  durationSeconds?: number | undefined;
464
547
  }>>;
465
548
  }, "strip", z.ZodTypeAny, {
@@ -474,7 +557,9 @@ declare const AskResultSchema: z.ZodObject<{
474
557
  inputTokens: number;
475
558
  outputTokens: number;
476
559
  reasoningTokens?: number | undefined;
560
+ cachedInputTokens?: number | undefined;
477
561
  estimatedCost?: number | undefined;
562
+ reportedCost?: number | undefined;
478
563
  durationSeconds?: number | undefined;
479
564
  } | undefined;
480
565
  frameReferences?: number[] | null | undefined;
@@ -490,7 +575,9 @@ declare const AskResultSchema: z.ZodObject<{
490
575
  inputTokens: number;
491
576
  outputTokens: number;
492
577
  reasoningTokens?: number | undefined;
578
+ cachedInputTokens?: number | undefined;
493
579
  estimatedCost?: number | undefined;
580
+ reportedCost?: number | undefined;
494
581
  durationSeconds?: number | undefined;
495
582
  } | undefined;
496
583
  frameReferences?: number[] | null | undefined;
@@ -567,6 +654,19 @@ interface VisualAIConfig {
567
654
  debugResponse?: boolean;
568
655
  maxTokens?: number;
569
656
  reasoningEffort?: ReasoningEffortLevel;
657
+ /**
658
+ * Longest-edge pixel cap for image inputs before they are sent to the
659
+ * provider. Defaults to 1568. Raising it only helps providers that accept
660
+ * higher-resolution requests (OpenAI with `imageDetail: "high"` scales into a
661
+ * 2048px box); Anthropic re-downscales to ~1568px regardless.
662
+ */
663
+ maxImageDimension?: number;
664
+ /**
665
+ * Image-detail hint mapped per provider: OpenAI/OpenRouter `detail`, Google
666
+ * `mediaResolution`. `"auto"` (default) sends no detail field. No effect on
667
+ * Anthropic (Claude auto-downscales images).
668
+ */
669
+ imageDetail?: ImageDetailLevel;
570
670
  trackUsage?: boolean;
571
671
  }
572
672
  /** Optional instructions for `check()`. */
@@ -1105,4 +1205,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
1105
1205
  */
1106
1206
  declare function assertVisualCompareResult(result: CompareResult, label?: string): void;
1107
1207
 
1108
- 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 };
1208
+ 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, ImageDetail, type ImageDetailLevel, 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 CHANGED
@@ -9,6 +9,19 @@ declare const ReasoningEffort: {
9
9
  };
10
10
  /** Union of valid reasoning effort values, derived from the ReasoningEffort constant. */
11
11
  type ReasoningEffortLevel = (typeof ReasoningEffort)[keyof typeof ReasoningEffort];
12
+ /**
13
+ * Abstract image-detail hint. Each provider driver maps it to its native
14
+ * mechanism (OpenAI/OpenRouter `detail`, Google `mediaResolution`); Anthropic
15
+ * has no equivalent (Claude auto-downscales to ~1568px / 1.15MP regardless).
16
+ * `"auto"` sends no detail field, preserving each provider's default.
17
+ */
18
+ declare const ImageDetail: {
19
+ readonly AUTO: "auto";
20
+ readonly LOW: "low";
21
+ readonly HIGH: "high";
22
+ };
23
+ /** Union of valid image-detail values, derived from the ImageDetail constant. */
24
+ type ImageDetailLevel = (typeof ImageDetail)[keyof typeof ImageDetail];
12
25
  /** Supported provider identifiers used internally for pricing and provider selection. */
13
26
  declare const Provider: {
14
27
  readonly ANTHROPIC: "anthropic";
@@ -20,6 +33,7 @@ declare const Provider: {
20
33
  declare const Model: {
21
34
  readonly Anthropic: {
22
35
  readonly FABLE_5: "claude-fable-5";
36
+ readonly OPUS_5: "claude-opus-5";
23
37
  readonly OPUS_4_8: "claude-opus-4-8";
24
38
  readonly OPUS_4_7: "claude-opus-4-7";
25
39
  readonly OPUS_4_6: "claude-opus-4-6";
@@ -40,6 +54,8 @@ declare const Model: {
40
54
  readonly GPT_5_MINI: "gpt-5-mini";
41
55
  };
42
56
  readonly Google: {
57
+ readonly GEMINI_3_8_FLASH: "gemini-3.8-flash";
58
+ readonly GEMINI_3_7_FLASH: "gemini-3.7-flash";
43
59
  readonly GEMINI_3_6_FLASH: "gemini-3.6-flash";
44
60
  readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
45
61
  readonly GEMINI_3_5_FLASH_LITE: "gemini-3.5-flash-lite";
@@ -53,9 +69,12 @@ declare const Model: {
53
69
  * recognizes them. All listed models accept image input.
54
70
  */
55
71
  readonly OpenRouter: {
72
+ readonly MUSE_SPARK_1_3: "meta/muse-spark-1.3";
73
+ readonly GROK_4_6: "x-ai/grok-4.6";
56
74
  readonly GROK_4_5: "x-ai/grok-4.5";
57
75
  readonly KIMI_K3: "moonshotai/kimi-k3";
58
76
  readonly KIMI_K2_7_CODE: "moonshotai/kimi-k2.7-code";
77
+ readonly QWEN_3_8_MAX: "qwen/qwen3.8-max";
59
78
  readonly QWEN_3_7_PLUS: "qwen/qwen3.7-plus";
60
79
  readonly QWEN_3_6_FLASH: "qwen/qwen3.6-flash";
61
80
  };
@@ -173,19 +192,33 @@ declare const UsageInfoSchema: z.ZodObject<{
173
192
  outputTokens: z.ZodNumber;
174
193
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
175
194
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
195
+ /**
196
+ * Prompt tokens served from the provider's cache, when reported. Informational
197
+ * only — `estimatedCost` does not apply a cache discount, because providers
198
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
199
+ * Google) or billed as a separate bucket alongside it (Anthropic).
200
+ */
201
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
202
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
176
203
  estimatedCost: z.ZodOptional<z.ZodNumber>;
204
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
205
+ reportedCost: z.ZodOptional<z.ZodNumber>;
177
206
  durationSeconds: z.ZodOptional<z.ZodNumber>;
178
207
  }, "strip", z.ZodTypeAny, {
179
208
  inputTokens: number;
180
209
  outputTokens: number;
181
210
  reasoningTokens?: number | undefined;
211
+ cachedInputTokens?: number | undefined;
182
212
  estimatedCost?: number | undefined;
213
+ reportedCost?: number | undefined;
183
214
  durationSeconds?: number | undefined;
184
215
  }, {
185
216
  inputTokens: number;
186
217
  outputTokens: number;
187
218
  reasoningTokens?: number | undefined;
219
+ cachedInputTokens?: number | undefined;
188
220
  estimatedCost?: number | undefined;
221
+ reportedCost?: number | undefined;
189
222
  durationSeconds?: number | undefined;
190
223
  }>;
191
224
  /** Token usage and optional cost/latency metadata for a provider call. */
@@ -206,19 +239,33 @@ declare const CheckResultSchema: z.ZodObject<{
206
239
  outputTokens: z.ZodNumber;
207
240
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
208
241
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
242
+ /**
243
+ * Prompt tokens served from the provider's cache, when reported. Informational
244
+ * only — `estimatedCost` does not apply a cache discount, because providers
245
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
246
+ * Google) or billed as a separate bucket alongside it (Anthropic).
247
+ */
248
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
249
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
209
250
  estimatedCost: z.ZodOptional<z.ZodNumber>;
251
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
252
+ reportedCost: z.ZodOptional<z.ZodNumber>;
210
253
  durationSeconds: z.ZodOptional<z.ZodNumber>;
211
254
  }, "strip", z.ZodTypeAny, {
212
255
  inputTokens: number;
213
256
  outputTokens: number;
214
257
  reasoningTokens?: number | undefined;
258
+ cachedInputTokens?: number | undefined;
215
259
  estimatedCost?: number | undefined;
260
+ reportedCost?: number | undefined;
216
261
  durationSeconds?: number | undefined;
217
262
  }, {
218
263
  inputTokens: number;
219
264
  outputTokens: number;
220
265
  reasoningTokens?: number | undefined;
266
+ cachedInputTokens?: number | undefined;
221
267
  estimatedCost?: number | undefined;
268
+ reportedCost?: number | undefined;
222
269
  durationSeconds?: number | undefined;
223
270
  }>>;
224
271
  } & {
@@ -282,7 +329,9 @@ declare const CheckResultSchema: z.ZodObject<{
282
329
  inputTokens: number;
283
330
  outputTokens: number;
284
331
  reasoningTokens?: number | undefined;
332
+ cachedInputTokens?: number | undefined;
285
333
  estimatedCost?: number | undefined;
334
+ reportedCost?: number | undefined;
286
335
  durationSeconds?: number | undefined;
287
336
  } | undefined;
288
337
  }, {
@@ -305,7 +354,9 @@ declare const CheckResultSchema: z.ZodObject<{
305
354
  inputTokens: number;
306
355
  outputTokens: number;
307
356
  reasoningTokens?: number | undefined;
357
+ cachedInputTokens?: number | undefined;
308
358
  estimatedCost?: number | undefined;
359
+ reportedCost?: number | undefined;
309
360
  durationSeconds?: number | undefined;
310
361
  } | undefined;
311
362
  }>;
@@ -348,19 +399,33 @@ declare const CompareResultSchema: z.ZodObject<{
348
399
  outputTokens: z.ZodNumber;
349
400
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
350
401
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
402
+ /**
403
+ * Prompt tokens served from the provider's cache, when reported. Informational
404
+ * only — `estimatedCost` does not apply a cache discount, because providers
405
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
406
+ * Google) or billed as a separate bucket alongside it (Anthropic).
407
+ */
408
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
409
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
351
410
  estimatedCost: z.ZodOptional<z.ZodNumber>;
411
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
412
+ reportedCost: z.ZodOptional<z.ZodNumber>;
352
413
  durationSeconds: z.ZodOptional<z.ZodNumber>;
353
414
  }, "strip", z.ZodTypeAny, {
354
415
  inputTokens: number;
355
416
  outputTokens: number;
356
417
  reasoningTokens?: number | undefined;
418
+ cachedInputTokens?: number | undefined;
357
419
  estimatedCost?: number | undefined;
420
+ reportedCost?: number | undefined;
358
421
  durationSeconds?: number | undefined;
359
422
  }, {
360
423
  inputTokens: number;
361
424
  outputTokens: number;
362
425
  reasoningTokens?: number | undefined;
426
+ cachedInputTokens?: number | undefined;
363
427
  estimatedCost?: number | undefined;
428
+ reportedCost?: number | undefined;
364
429
  durationSeconds?: number | undefined;
365
430
  }>>;
366
431
  } & {
@@ -385,7 +450,9 @@ declare const CompareResultSchema: z.ZodObject<{
385
450
  inputTokens: number;
386
451
  outputTokens: number;
387
452
  reasoningTokens?: number | undefined;
453
+ cachedInputTokens?: number | undefined;
388
454
  estimatedCost?: number | undefined;
455
+ reportedCost?: number | undefined;
389
456
  durationSeconds?: number | undefined;
390
457
  } | undefined;
391
458
  }, {
@@ -399,7 +466,9 @@ declare const CompareResultSchema: z.ZodObject<{
399
466
  inputTokens: number;
400
467
  outputTokens: number;
401
468
  reasoningTokens?: number | undefined;
469
+ cachedInputTokens?: number | undefined;
402
470
  estimatedCost?: number | undefined;
471
+ reportedCost?: number | undefined;
403
472
  durationSeconds?: number | undefined;
404
473
  } | undefined;
405
474
  }>;
@@ -447,19 +516,33 @@ declare const AskResultSchema: z.ZodObject<{
447
516
  outputTokens: z.ZodNumber;
448
517
  /** Reasoning/thinking tokens consumed by the model (informational, typically included within outputTokens). */
449
518
  reasoningTokens: z.ZodOptional<z.ZodNumber>;
519
+ /**
520
+ * Prompt tokens served from the provider's cache, when reported. Informational
521
+ * only — `estimatedCost` does not apply a cache discount, because providers
522
+ * differ on whether these are counted inside `inputTokens` (OpenAI, OpenRouter,
523
+ * Google) or billed as a separate bucket alongside it (Anthropic).
524
+ */
525
+ cachedInputTokens: z.ZodOptional<z.ZodNumber>;
526
+ /** Cost in USD from the library's local pricing table (inputTokens/outputTokens × per-model rates). */
450
527
  estimatedCost: z.ZodOptional<z.ZodNumber>;
528
+ /** Actual cost in USD reported by the provider itself, when available (OpenRouter). Authoritative over `estimatedCost`. */
529
+ reportedCost: z.ZodOptional<z.ZodNumber>;
451
530
  durationSeconds: z.ZodOptional<z.ZodNumber>;
452
531
  }, "strip", z.ZodTypeAny, {
453
532
  inputTokens: number;
454
533
  outputTokens: number;
455
534
  reasoningTokens?: number | undefined;
535
+ cachedInputTokens?: number | undefined;
456
536
  estimatedCost?: number | undefined;
537
+ reportedCost?: number | undefined;
457
538
  durationSeconds?: number | undefined;
458
539
  }, {
459
540
  inputTokens: number;
460
541
  outputTokens: number;
461
542
  reasoningTokens?: number | undefined;
543
+ cachedInputTokens?: number | undefined;
462
544
  estimatedCost?: number | undefined;
545
+ reportedCost?: number | undefined;
463
546
  durationSeconds?: number | undefined;
464
547
  }>>;
465
548
  }, "strip", z.ZodTypeAny, {
@@ -474,7 +557,9 @@ declare const AskResultSchema: z.ZodObject<{
474
557
  inputTokens: number;
475
558
  outputTokens: number;
476
559
  reasoningTokens?: number | undefined;
560
+ cachedInputTokens?: number | undefined;
477
561
  estimatedCost?: number | undefined;
562
+ reportedCost?: number | undefined;
478
563
  durationSeconds?: number | undefined;
479
564
  } | undefined;
480
565
  frameReferences?: number[] | null | undefined;
@@ -490,7 +575,9 @@ declare const AskResultSchema: z.ZodObject<{
490
575
  inputTokens: number;
491
576
  outputTokens: number;
492
577
  reasoningTokens?: number | undefined;
578
+ cachedInputTokens?: number | undefined;
493
579
  estimatedCost?: number | undefined;
580
+ reportedCost?: number | undefined;
494
581
  durationSeconds?: number | undefined;
495
582
  } | undefined;
496
583
  frameReferences?: number[] | null | undefined;
@@ -567,6 +654,19 @@ interface VisualAIConfig {
567
654
  debugResponse?: boolean;
568
655
  maxTokens?: number;
569
656
  reasoningEffort?: ReasoningEffortLevel;
657
+ /**
658
+ * Longest-edge pixel cap for image inputs before they are sent to the
659
+ * provider. Defaults to 1568. Raising it only helps providers that accept
660
+ * higher-resolution requests (OpenAI with `imageDetail: "high"` scales into a
661
+ * 2048px box); Anthropic re-downscales to ~1568px regardless.
662
+ */
663
+ maxImageDimension?: number;
664
+ /**
665
+ * Image-detail hint mapped per provider: OpenAI/OpenRouter `detail`, Google
666
+ * `mediaResolution`. `"auto"` (default) sends no detail field. No effect on
667
+ * Anthropic (Claude auto-downscales images).
668
+ */
669
+ imageDetail?: ImageDetailLevel;
570
670
  trackUsage?: boolean;
571
671
  }
572
672
  /** Optional instructions for `check()`. */
@@ -1105,4 +1205,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
1105
1205
  */
1106
1206
  declare function assertVisualCompareResult(result: CompareResult, label?: string): void;
1107
1207
 
1108
- 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 };
1208
+ 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, ImageDetail, type ImageDetailLevel, 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 };