visual-ai-assertions 0.21.0 → 0.23.0

package/README.md

@@ -1,6 +1,6 @@
 # visual-ai-assertions
 
-AI-powered visual assertions for E2E tests. Send screenshots — or short video recordings — to Claude, GPT, Gemini — or Grok, Kimi, and Qwen via OpenRouter — and get structured, typed results.
+AI-powered visual assertions for E2E tests. Send screenshots — or short video recordings — to Claude, GPT, Gemini — or Grok, Kimi, Qwen, and GLM via OpenRouter — and get structured, typed results.
 
 ## Installation
 
@@ -11,7 +11,7 @@ npm install visual-ai-assertions
 # Optional: install additional provider SDKs
 npm install @anthropic-ai/sdk    # for Claude
 npm install @google/genai        # for Gemini
-# OpenRouter (Grok, Kimi, Qwen, ...) uses the OpenAI SDK — no extra install
+# OpenRouter (Grok, Kimi, Qwen, GLM, ...) uses the OpenAI SDK — no extra install
 
 # Zod is a peer dependency
 npm install zod
@@ -104,6 +104,7 @@ const ai = visualAI({
   debug: true, // optional, logs prompts/responses to stderr
   maxTokens: 4096, // optional, default 4096
   reasoningEffort: "high", // optional, "low" | "medium" | "high" | "xhigh"
+  timeout: 120_000, // optional, ms — defaults to the provider SDK's own timeout
   trackUsage: false, // optional, defaults to false — usage stats to stderr
 });
 
@@ -255,6 +256,33 @@ await ai.elementsVisible(screenshot, ["Submit button", "Nav bar", "Footer"]);
 // Check that UI elements are hidden
 await ai.elementsHidden(screenshot, ["Loading spinner", "Error modal"]);
 
+// Clipping is judged the way a tester would. An element cut off at the trailing
+// edge of a scrollable row or feed passes, because scrolling reaches it. One
+// sliced by the screen edge or by fixed chrome such as the status bar or a
+// sticky nav fails, because scrolling cannot. An element you cannot see at all
+// fails: only what the screenshot shows is judged.
+//
+// Overlays are judged by what they say about the element's state, not by how
+// much they cover. A badge, favourite icon or price pill coexists with finished
+// content and leaves the element visible. A loading spinner, skeleton, progress
+// bar or error overlay says it is not ready, so the check fails even though you
+// can still see what is underneath. A modal, dialog or cookie banner that a user
+// could not read or use past also fails.
+//
+// Pass finalState: false when the screenshot was deliberately captured mid-load,
+// so loading chrome is expected rather than a defect. The finished-state rules
+// are left out; presence, clipping and blocking overlays are still judged.
+await ai.elementsVisible(screenshot, ["Product image"], { finalState: false });
+
+// By default this is a presence check: an element counts as visible if it is
+// there at all, whatever it looks like. Pass requireCorrectRendering: true to
+// also fail an element that is present but clearly badly rendered — unreadable
+// contrast, overlapping or misaligned elements, text cut off mid-word — with
+// the model saying the element is present before naming the defect. Opt in per
+// assertion: measured on the bench, it catches exactly that case and makes
+// models flakier on plain presence questions.
+await ai.elementsVisible(screenshot, ["Promo banner"], { requireCorrectRendering: true });
+
 // Accessibility checks (contrast, readability, interactive visibility, color blindness, color-alone meaning)
 await ai.accessibility(screenshot);
 await ai.accessibility(screenshot, {
@@ -463,16 +491,17 @@ The `VisualAIKnownError` union and `isVisualAIKnownError()` helper are useful wh
 
 ## Configuration
 
-| Option            | Type    | Default          | Description                                                                   |
-| ----------------- | ------- | ---------------- | ----------------------------------------------------------------------------- |
-| `apiKey`          | string  | env var          | API key for the provider                                                      |
-| `model`           | string  | provider default | Model to use                                                                  |
-| `debug`           | boolean | `false`          | Enable error diagnostic logging to stderr                                     |
-| `debugPrompt`     | boolean | `false`          | Log prompts to stderr                                                         |
-| `debugResponse`   | boolean | `false`          | Log responses to stderr                                                       |
-| `maxTokens`       | number  | `4096`           | Max tokens for AI response                                                    |
-| `reasoningEffort` | string  | `undefined`      | `"low"` `"medium"` `"high"` `"xhigh"` — controls how deeply the model reasons |
-| `trackUsage`      | boolean | `false`          | Log token usage and estimated cost to stderr                                  |
+| Option            | Type    | Default          | Description                                                                                                                                                                 |
+| ----------------- | ------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiKey`          | string  | env var          | API key for the provider                                                                                                                                                    |
+| `model`           | string  | provider default | Model to use                                                                                                                                                                |
+| `debug`           | boolean | `false`          | Enable error diagnostic logging to stderr                                                                                                                                   |
+| `debugPrompt`     | boolean | `false`          | Log prompts to stderr                                                                                                                                                       |
+| `debugResponse`   | boolean | `false`          | Log responses to stderr                                                                                                                                                     |
+| `maxTokens`       | number  | `4096`           | Max tokens for AI response                                                                                                                                                  |
+| `reasoningEffort` | string  | `undefined`      | `"low"` `"medium"` `"high"` `"xhigh"` — controls how deeply the model reasons                                                                                               |
+| `timeout`         | number  | SDK default      | Per-request timeout in ms. Unset leaves each SDK's own default (OpenAI/OpenRouter 10 min, Google 1 min). SDKs retry timeouts, so total wall time can be a multiple of this. |
+| `trackUsage`      | boolean | `false`          | Log token usage and estimated cost to stderr                                                                                                                                |
 
 ## Exported Types
 
@@ -535,7 +564,8 @@ All listed models support image/vision input. Pass any model ID to the `model` c
 
 | Model             | Model ID            | Input $/MTok | Output $/MTok | Notes                                       |
 | ----------------- | ------------------- | ------------ | ------------- | ------------------------------------------- |
-| Claude Fable 5    | `claude-fable-5`    | $10          | $50           | Most capable; long-horizon agentic work     |
+| Claude Fable 5.1  | `claude-fable-5-1`  | $10          | $50           | Most capable; long-horizon agentic work     |
+| Claude Fable 5    | `claude-fable-5`    | $10          | $50           | Predecessor to Fable 5.1, same price        |
 | Claude Opus 4.8   | `claude-opus-4-8`   | $5           | $25           | Most capable Opus tier; supports `xhigh`    |
 | Claude Opus 4.7   | `claude-opus-4-7`   | $5           | $25           | Previous Opus; supports `xhigh` effort tier |
 | Claude Opus 4.6   | `claude-opus-4-6`   | $5           | $25           | Previous flagship, 128K max output          |
@@ -547,6 +577,7 @@ All listed models support image/vision input. Pass any model ID to the `model` c
 
 | Model         | Model ID        | Input $/MTok | Output $/MTok | Notes                                  |
 | ------------- | --------------- | ------------ | ------------- | -------------------------------------- |
+| GPT-6 Astra   | `gpt-6-astra`   | $10          | $50           | Most capable; restricted access¹       |
 | GPT-5.6 Sol   | `gpt-5.6-sol`   | $5           | $30           | Newest flagship, frontier tier         |
 | GPT-5.6 Terra | `gpt-5.6-terra` | $2           | $12           | Newest balanced, everyday tier         |
 | GPT-5.6 Luna  | `gpt-5.6-luna`  | $0.20        | $1.20         | **Default** — newest, fastest/cheapest |
@@ -558,6 +589,10 @@ All listed models support image/vision input. Pass any model ID to the `model` c
 | GPT-5.4 nano  | `gpt-5.4-nano`  | $0.20        | $1.25         | Cheapest older-generation option       |
 | GPT-5 mini    | `gpt-5-mini`    | $0.25        | $2            | Fast and cheap                         |
 
+¹ GPT-6 Astra is rolling out through OpenAI's Trusted Access Program, so many API keys cannot reach it yet — expect a `VisualAIProviderError` naming the model until your account is enabled.
+
+Astra reasons heavily enough to spend the entire 4096-token default output budget before emitting an answer, so **it is given a 32768-token budget automatically**, at every reasoning effort rather than only at `high`/`xhigh` like other OpenAI models. That follows OpenAI's guidance to reserve at least 25,000 tokens for reasoning and output. Its output length is erratic — identical calls have used anywhere from 0 to 16384+ reasoning tokens — so a large budget reduces truncation without eliminating it; a call that exhausts the budget still bills for the tokens it burned. Passing `maxTokens` explicitly still wins. It also accepts a fifth reasoning level, `max`, above `xhigh`; this library's `reasoningEffort` stops at `xhigh`, which is passed through unchanged, so `max` is not currently reachable.
+
 ### Google
 
 | Model                 | Model ID                 | Input $/MTok | Output $/MTok | Notes                             |
@@ -587,9 +622,12 @@ Any [OpenRouter](https://openrouter.ai/models) model slug (always `vendor/model`
 | Qwen3.8 Max    | `qwen/qwen3.8-max`          | $2           | $6            | First Max tier with image input       |
 | Qwen3.7 Plus   | `qwen/qwen3.7-plus`         | $0.32        | $1.28         | Cost-effective, GUI/screen-reading    |
 | Qwen3.6 Flash  | `qwen/qwen3.6-flash`        | $0.19        | $1.13         | **Default** — cheap flash vision tier |
+| GLM 5.3 Flash  | `z-ai/glm-5.3-flash`        | $0.15        | $0.50         | Z.ai flash tier, 1.3M context²        |
 
 ¹ Muse Spark 1.3 is age-gated by OpenRouter: calls return HTTP 403 (`VisualAIAuthError`) until the account completes the 18+ confirmation at [openrouter.ai/settings/preferences](https://openrouter.ai/settings/preferences). It also reasons by default — expect several hundred reasoning tokens per call even with no `reasoningEffort` set.
 
+² GLM 5.3 Flash reasons by default — expect one to two hundred reasoning tokens per call even with no `reasoningEffort` set, billed at the output rate. OpenRouter's own context cap for it is 1,048,576 tokens (Z.ai lists 1,310,720) and its output ceiling is 131,072.
+
 Meta also publishes `meta/muse-spark-1.3-contributor`, the same model at $0.10 / $0.20 per MTok — about 12x cheaper — because Meta uses everything submitted through it for product improvement. It has **no named constant** (`Model.OpenRouter` does not expose it) and never appears by default anywhere in this library, so using it takes a deliberate, explicit choice: pass the slug directly as a plain string, `visualAI({ model: "meta/muse-spark-1.3-contributor" })`. Any OpenRouter slug works this way — see the note above the table — and cost tracking works correctly once you opt in. OpenRouter itself blocks it with HTTP 404 (`paid-model-training-violation-by-account`) until the account's privacy settings allow training endpoints, at [openrouter.ai/settings/privacy](https://openrouter.ai/settings/privacy). Only use it if sending your screenshots to Meta for training is a trade you've deliberately made.
 
 `qwen/qwen3.7-max` and the DeepSeek V4 family (`deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, and dated variants such as `deepseek/deepseek-v4-pro-0813`) are not listed because they accept no image input on OpenRouter.

package/dist/index.cjs

@@ -89,6 +89,7 @@ var Provider = {
 };
 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",
@@ -99,6 +100,7 @@ var Model = {
     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",
@@ -133,7 +135,8 @@ var Model = {
     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"
+    QWEN_3_6_FLASH: "qwen/qwen3.6-flash",
+    GLM_5_3_FLASH: "z-ai/glm-5.3-flash"
   }
 };
 var DEFAULT_MODELS = {
@@ -144,6 +147,10 @@ var DEFAULT_MODELS = {
 };
 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]),
@@ -488,22 +495,50 @@ function buildComparePrompt(options) {
 }
 
 // src/templates/elements-visibility.ts
-var ELEMENTS_VISIBLE_ROLE = "Check whether specific UI elements are present and fully visible in this screenshot.";
 var ELEMENTS_HIDDEN_ROLE = "Check whether specific UI elements are absent or hidden in this screenshot.";
-var ELEMENTS_VISIBLE_EDGE_RULES = [
-  "If an element is partially visible (cut off by screenshot boundary), it is NOT considered fully visible \u2014 the check for that element should fail. Note the partial visibility in your reasoning."
+function joinClauses(clauses) {
+  if (clauses.length <= 1) return clauses[0] ?? "";
+  if (clauses.length === 2) return `${clauses[0]} and ${clauses[1]}`;
+  return `${clauses.slice(0, -1).join(", ")}, and ${clauses[clauses.length - 1]}`;
+}
+function visibleRole(finalState, requireCorrectRendering) {
+  const clauses = ["present", "properly visible"];
+  if (requireCorrectRendering) clauses.push("correctly rendered");
+  if (finalState) clauses.push("in their finished state");
+  return `Check whether specific UI elements are ${joinClauses(clauses)} in this screenshot.`;
+}
+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."
 ];
-var ELEMENTS_HIDDEN_EDGE_RULES = [
-  "If an element is partially visible (cut off by screenshot boundary), it is NOT considered hidden \u2014 the check for that element should fail. Note the partial visibility in your reasoning."
+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.";
+var ELEMENTS_VISIBLE_OCCLUSION_RULE = "An element a user could not read or use because a modal, dialog, cookie banner, toast or similar overlay covers it is NOT visible: the check for that element FAILS.";
+function visibleRules(finalState, requireCorrectRendering) {
+  return [
+    ...ELEMENTS_VISIBLE_CLIPPING_RULES,
+    ...finalState ? [ELEMENTS_VISIBLE_FINAL_STATE_RULE] : [],
+    ...requireCorrectRendering ? [ELEMENTS_VISIBLE_CORRECT_RENDERING_RULE] : [],
+    ELEMENTS_VISIBLE_OCCLUSION_RULE
+  ];
+}
+var ELEMENTS_HIDDEN_BASE_RULES = [
+  "An element that is rendered at all, even partly, is not hidden, so the check for that element FAILS. This includes one peeking past the edge of a scrollable row or feed, which the user reaches by scrolling normally. Note the partial visibility in your reasoning.",
+  "An element that appears nowhere in this screenshot counts as hidden, even if the page might reveal it after scrolling. Judge only what this screenshot actually shows."
 ];
+var ELEMENTS_HIDDEN_FINAL_STATE_RULE = "An element sitting under a loading spinner, skeleton, progress bar or error overlay is still rendered, so it is not hidden and the check for that element FAILS. It is not properly visible either; that is what the visible check is for.";
+function hiddenRules(finalState) {
+  return finalState ? [...ELEMENTS_HIDDEN_BASE_RULES, ELEMENTS_HIDDEN_FINAL_STATE_RULE] : ELEMENTS_HIDDEN_BASE_RULES;
+}
 function buildElementsVisibilityPrompt(elements, visible, options) {
-  const statements = visible ? elements.map((el) => `The element "${el}" is fully visible on the page`) : elements.map((el) => `The element "${el}" is NOT visible on the page`);
-  const defaultRules = visible ? ELEMENTS_VISIBLE_EDGE_RULES : ELEMENTS_HIDDEN_EDGE_RULES;
+  const statements = visible ? elements.map((el) => `The element "${el}" is visible on the page`) : elements.map((el) => `The element "${el}" is NOT visible on the page`);
+  const finalState = options?.finalState ?? true;
+  const correctRendering = visible && (options?.requireCorrectRendering ?? false);
+  const defaultRules = visible ? visibleRules(finalState, correctRendering) : hiddenRules(finalState);
   const instructions = options?.instructions ? [...defaultRules, ...options.instructions] : defaultRules;
-  return buildCheckPrompt(statements, {
-    role: visible ? ELEMENTS_VISIBLE_ROLE : ELEMENTS_HIDDEN_ROLE,
-    instructions
-  });
+  const role = visible ? visibleRole(finalState, correctRendering) : ELEMENTS_HIDDEN_ROLE;
+  return buildCheckPrompt(statements, { role, instructions });
 }
 
 // src/templates/accessibility.ts
@@ -613,6 +648,7 @@ function parseRetryAfter(value) {
 
 // src/providers/anthropic.ts
 var XHIGH_CAPABLE_MODELS = /* @__PURE__ */ new Set([
+  Model.Anthropic.FABLE_5_1,
   Model.Anthropic.FABLE_5,
   Model.Anthropic.OPUS_5,
   Model.Anthropic.OPUS_4_8,
@@ -636,12 +672,14 @@ var AnthropicDriver = class {
   maxTokens;
   apiKeyOrEnv;
   reasoningEffort;
+  timeout;
   constructor(config) {
     this.model = config.model;
     this.maxTokens = config.maxTokens;
     this.client = null;
     this.apiKeyOrEnv = config.apiKey;
     this.reasoningEffort = config.reasoningEffort;
+    this.timeout = config.timeout;
   }
   async getClient() {
     if (this.client) return this.client;
@@ -660,7 +698,10 @@ var AnthropicDriver = class {
         "Anthropic API key not found. Set ANTHROPIC_API_KEY or pass apiKey in config."
       );
     }
-    this.client = new Anthropic({ apiKey });
+    this.client = new Anthropic({
+      apiKey,
+      ...this.timeout !== void 0 && { timeout: this.timeout }
+    });
     return this.client;
   }
   async sendMessage(images, prompt, _options) {
@@ -758,6 +799,7 @@ var GoogleDriver = class {
   apiKeyOrEnv;
   reasoningEffort;
   imageDetail;
+  timeout;
   constructor(config) {
     this.model = config.model;
     this.maxTokens = config.maxTokens;
@@ -765,6 +807,7 @@ var GoogleDriver = class {
     this.apiKeyOrEnv = config.apiKey;
     this.reasoningEffort = config.reasoningEffort;
     this.imageDetail = config.imageDetail;
+    this.timeout = config.timeout;
   }
   toGeminiParts(images) {
     return images.map((img) => ({
@@ -788,7 +831,10 @@ var GoogleDriver = class {
         "Google API key not found. Set GOOGLE_API_KEY or pass apiKey in config."
       );
     }
-    this.client = new GoogleGenAI({ apiKey });
+    this.client = new GoogleGenAI({
+      apiKey,
+      ...this.timeout !== void 0 && { httpOptions: { timeout: this.timeout } }
+    });
     return this.client;
   }
   async sendMessage(images, prompt, _options) {
@@ -874,6 +920,7 @@ var OpenAIDriver = class {
   apiKeyOrEnv;
   reasoningEffort;
   imageDetail;
+  timeout;
   constructor(config) {
     this.model = config.model;
     this.maxTokens = config.maxTokens;
@@ -881,6 +928,7 @@ var OpenAIDriver = class {
     this.apiKeyOrEnv = config.apiKey;
     this.reasoningEffort = config.reasoningEffort;
     this.imageDetail = config.imageDetail;
+    this.timeout = config.timeout;
   }
   async getClient() {
     if (this.client) return this.client;
@@ -897,7 +945,10 @@ var OpenAIDriver = class {
         "OpenAI API key not found. Set OPENAI_API_KEY or pass apiKey in config."
       );
     }
-    this.client = new OpenAI({ apiKey });
+    this.client = new OpenAI({
+      apiKey,
+      ...this.timeout !== void 0 && { timeout: this.timeout }
+    });
     return this.client;
   }
   async sendMessage(images, prompt, options) {
@@ -972,6 +1023,7 @@ var OpenRouterDriver = class {
   apiKeyOrEnv;
   reasoningEffort;
   imageDetail;
+  timeout;
   constructor(config) {
     this.model = config.model;
     this.maxTokens = config.maxTokens;
@@ -979,6 +1031,7 @@ var OpenRouterDriver = class {
     this.apiKeyOrEnv = config.apiKey;
     this.reasoningEffort = config.reasoningEffort;
     this.imageDetail = config.imageDetail;
+    this.timeout = config.timeout;
   }
   async getClient() {
     if (this.client) return this.client;
@@ -997,7 +1050,11 @@ var OpenRouterDriver = class {
         "OpenRouter API key not found. Set OPENROUTER_API_KEY or pass apiKey in config."
       );
     }
-    this.client = new OpenAI({ apiKey, baseURL: OPENROUTER_BASE_URL });
+    this.client = new OpenAI({
+      apiKey,
+      baseURL: OPENROUTER_BASE_URL,
+      ...this.timeout !== void 0 && { timeout: this.timeout }
+    });
     return this.client;
   }
   async sendMessage(images, prompt, options) {
@@ -1127,13 +1184,21 @@ function resolveConfig(config) {
 `
     );
   }
+  if (config.timeout !== void 0 && (!Number.isFinite(config.timeout) || config.timeout <= 0)) {
+    throw new VisualAIConfigError(
+      `Invalid timeout: ${config.timeout}. Must be a positive number of milliseconds.`
+    );
+  }
   const userSetMaxTokens = config.maxTokens !== void 0;
   let maxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
-  if (!userSetMaxTokens && (provider === "openai" || provider === "openrouter") && (config.reasoningEffort === "high" || config.reasoningEffort === "xhigh")) {
-    maxTokens = OPENAI_REASONING_MAX_TOKENS;
+  const effortNeedsLargeBudget = config.reasoningEffort === "high" || config.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}"`;
       process.stderr.write(
-        `[visual-ai-assertions] Auto-increased maxTokens from ${DEFAULT_MAX_TOKENS} to ${OPENAI_REASONING_MAX_TOKENS} for provider "${provider}" with reasoningEffort "${config.reasoningEffort}".
+        `[visual-ai-assertions] Auto-increased maxTokens from ${DEFAULT_MAX_TOKENS} to ${maxTokens} for ${reason}.
 `
       );
     }
@@ -1146,6 +1211,7 @@ function resolveConfig(config) {
     reasoningEffort: config.reasoningEffort,
     maxImageDimension: config.maxImageDimension ?? DEFAULT_MAX_IMAGE_DIMENSION,
     imageDetail: config.imageDetail ?? DEFAULT_IMAGE_DETAIL,
+    timeout: config.timeout,
     debug,
     debugPrompt,
     debugResponse,
@@ -1156,6 +1222,11 @@ function resolveConfig(config) {
 // src/core/pricing.ts
 var PER_MILLION = 1e6;
 var PRICING_TABLE = {
+  // Fable 5.1 is priced identically to Fable 5, the tier it succeeds.
+  [`${Provider.ANTHROPIC}:${Model.Anthropic.FABLE_5_1}`]: {
+    inputPricePerToken: 10 / PER_MILLION,
+    outputPricePerToken: 50 / PER_MILLION
+  },
   [`${Provider.ANTHROPIC}:${Model.Anthropic.FABLE_5}`]: {
     inputPricePerToken: 10 / PER_MILLION,
     outputPricePerToken: 50 / PER_MILLION
@@ -1188,6 +1259,12 @@ var PRICING_TABLE = {
     inputPricePerToken: 1 / PER_MILLION,
     outputPricePerToken: 5 / PER_MILLION
   },
+  // Cached input is $1/MTok and cache writes $12.50/MTok; neither is modelled
+  // here, since `calculateCost` applies no cache discount on any provider.
+  [`${Provider.OPENAI}:${Model.OpenAI.GPT_6_ASTRA}`]: {
+    inputPricePerToken: 10 / PER_MILLION,
+    outputPricePerToken: 50 / PER_MILLION
+  },
   [`${Provider.OPENAI}:${Model.OpenAI.GPT_5_6_SOL}`]: {
     inputPricePerToken: 5 / PER_MILLION,
     outputPricePerToken: 30 / PER_MILLION
@@ -1311,6 +1388,12 @@ var PRICING_TABLE = {
   [`${Provider.OPENROUTER}:${Model.OpenRouter.QWEN_3_6_FLASH}`]: {
     inputPricePerToken: 0.1875 / PER_MILLION,
     outputPricePerToken: 1.125 / PER_MILLION
+  },
+  // Verified 2026-09-10 against https://openrouter.ai/api/v1/models. Cached
+  // input is $0.03/MTok, not modelled (no provider gets a cache discount here).
+  [`${Provider.OPENROUTER}:${Model.OpenRouter.GLM_5_3_FLASH}`]: {
+    inputPricePerToken: 0.15 / PER_MILLION,
+    outputPricePerToken: 0.5 / PER_MILLION
   }
 };
 function calculateCost(provider, model, inputTokens, outputTokens) {
@@ -2196,10 +2279,34 @@ function stripCodeFences(text) {
 var CheckResponseSchema = CheckResultSchema.omit({ usage: true });
 var AskResponseSchema = AskResultSchema.omit({ usage: true });
 var CompareResponseSchema = CompareResultSchema.omit({ usage: true });
+var STRAY_CONTROL_CHARS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch (first) {
+    try {
+      return JSON.parse(text.replace(/[\u0000-\u001f]/g, " "));
+    } catch {
+      throw first;
+    }
+  }
+}
+function stripControlCharacters(value) {
+  if (typeof value === "string") return value.replace(STRAY_CONTROL_CHARS, "");
+  if (Array.isArray(value)) return value.map((item) => stripControlCharacters(item));
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = stripControlCharacters(item);
+    }
+    return out;
+  }
+  return value;
+}
 function parseResponse(raw, schema) {
   let parsed;
   try {
-    parsed = JSON.parse(stripCodeFences(raw));
+    parsed = stripControlCharacters(parseJson(stripCodeFences(raw)));
   } catch {
     throw new VisualAIResponseParseError(
       `Failed to parse AI response as JSON: ${raw.slice(0, 200)}`,
@@ -2294,7 +2401,8 @@ function visualAI(config = {}) {
     model: resolvedConfig.model,
     maxTokens: resolvedConfig.maxTokens,
     reasoningEffort: resolvedConfig.reasoningEffort,
-    imageDetail: resolvedConfig.imageDetail
+    imageDetail: resolvedConfig.imageDetail,
+    timeout: resolvedConfig.timeout
   };
   const driver = createDriver(resolvedConfig.provider, driverConfig);
   const maxImageDimension = resolvedConfig.maxImageDimension;