visual-ai-assertions 0.9.0 → 0.11.0

package/README.md

@@ -12,9 +12,6 @@ npm install visual-ai-assertions
 npm install @anthropic-ai/sdk    # for Claude
 npm install @google/genai        # for Gemini
 
-# Optional: install ffmpeg deps to enable video input
-npm install --save-dev fluent-ffmpeg @ffmpeg-installer/ffmpeg @ffprobe-installer/ffprobe
-
 # Zod is a peer dependency
 npm install zod
 ```
@@ -256,10 +253,10 @@ await ai.elementsVisible(screenshot, ["Submit button", "Nav bar", "Footer"]);
 // Check that UI elements are hidden
 await ai.elementsHidden(screenshot, ["Loading spinner", "Error modal"]);
 
-// Accessibility checks (contrast, readability, interactive visibility)
+// Accessibility checks (contrast, readability, interactive visibility, color blindness, color-alone meaning)
 await ai.accessibility(screenshot);
 await ai.accessibility(screenshot, {
-  checks: [Accessibility.CONTRAST, Accessibility.READABILITY],
+  checks: [Accessibility.CONTRAST, Accessibility.COLOR_BLINDNESS, Accessibility.COLOR_ALONE],
 });
 
 // Layout checks (overlap, overflow, alignment)
@@ -346,13 +343,7 @@ await ai.check("./long-clip.mp4", ["Loader disappears"], {
 
 How it works: the library samples frames with ffmpeg and sends them to the provider as an ordered timeline. A statement passes when it is true at any sampled frame, unless its wording specifies otherwise (e.g. "throughout"). Template helpers (`accessibility`, `layout`, `pageLoad`, `content`, `elementsVisible`, `elementsHidden`) are image-only — pass video to `check()` or `ask()` instead.
 
-**ffmpeg setup.** Video support is gated on three optional peer deps:
-
-```bash
-npm install --save-dev fluent-ffmpeg @ffmpeg-installer/ffmpeg @ffprobe-installer/ffprobe
-```
-
-Calling `check()` or `ask()` with a video input throws `VisualAIVideoError` (import from `visual-ai-assertions` to `instanceof`-narrow it) if these packages aren't installed. If you already have `ffmpeg`/`ffprobe` on `PATH`, only `fluent-ffmpeg` is required.
+**ffmpeg setup.** Video support works out of the box — `fluent-ffmpeg`, `@ffmpeg-installer/ffmpeg`, and `@ffprobe-installer/ffprobe` ship as regular dependencies and bundle platform-specific ffmpeg/ffprobe binaries. If you ran `npm install` you already have everything you need. On platforms where the prebuilt binary is unavailable (or if you've pruned dependencies), `check()` and `ask()` throw `VisualAIVideoError` (import from `visual-ai-assertions` to `instanceof`-narrow it) when called with video input.
 
 ### Formatting & Assertion Helpers
 
@@ -432,13 +423,15 @@ The `VisualAIKnownError` union and `isVisualAIKnownError()` helper are useful wh
 
 ### Optional Configuration
 
-| Variable                   | Description                                                                                                    |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `VISUAL_AI_MODEL`          | Default model when `model` is not set in config. Overrides the provider's default model.                       |
-| `VISUAL_AI_DEBUG`          | Enable error diagnostic logging to stderr. Does **not** enable prompt/response logging. Use `"true"` or `"1"`. |
-| `VISUAL_AI_DEBUG_PROMPT`   | Enable prompt-only debug logging to stderr. Use `"true"` or `"1"`.                                             |
-| `VISUAL_AI_DEBUG_RESPONSE` | Enable response-only debug logging to stderr. Use `"true"` or `"1"`.                                           |
-| `VISUAL_AI_TRACK_USAGE`    | Enable usage tracking (token counts and cost) to stderr. Use `"true"` or `"1"`.                                |
+| Variable                     | Description                                                                                                                                                                                                                        |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VISUAL_AI_MODEL`            | Default model when `model` is not set in config. Overrides the provider's default model.                                                                                                                                           |
+| `VISUAL_AI_DEBUG`            | Enable error diagnostic logging to stderr. Does **not** enable prompt/response logging. Use `"true"` or `"1"`.                                                                                                                     |
+| `VISUAL_AI_DEBUG_PROMPT`     | Enable prompt-only debug logging to stderr. Use `"true"` or `"1"`.                                                                                                                                                                 |
+| `VISUAL_AI_DEBUG_RESPONSE`   | Enable response-only debug logging to stderr. Use `"true"` or `"1"`.                                                                                                                                                               |
+| `VISUAL_AI_DEBUG_FRAMES`     | Persist sampled video frames to disk for offline inspection. Use `"true"` or `"1"`. Frames are written to `./visual-ai-debug-frames/<timestamp>-<id>/` (override path with the next variable). Has no effect on image-only inputs. |
+| `VISUAL_AI_DEBUG_FRAMES_DIR` | Override the base directory for `VISUAL_AI_DEBUG_FRAMES`. Each call still gets its own timestamped subdirectory inside it.                                                                                                         |
+| `VISUAL_AI_TRACK_USAGE`      | Enable usage tracking (token counts and cost) to stderr. Use `"true"` or `"1"`.                                                                                                                                                    |
 
 ## Configuration
 

package/dist/index.cjs

@@ -142,7 +142,11 @@ var Accessibility = {
   /** 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"
+  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
@@ -467,12 +471,16 @@ var ALL_CHECKS = Object.values(Accessibility);
 var ACCESSIBILITY_ROLE = "Evaluate this screenshot for visual accessibility. Focus on what you can actually perceive \u2014 apparent contrast levels, text legibility, and visual distinctiveness of interactive elements.";
 var ACCESSIBILITY_EDGE_RULES = [
   "Do not state specific contrast ratios. Describe contrast as 'appears sufficient' or 'appears low'.",
-  "Dark mode and light mode themes are both valid. Do not flag a valid dark theme as a contrast issue."
+  "Dark mode and light mode themes are both valid. Do not flag a valid dark theme as a contrast issue.",
+  "Purely decorative color (branding, backgrounds, gradients) is not a color-blindness or color-alone issue \u2014 only flag color usage that carries meaning a user must perceive to use the interface.",
+  "Only evaluate color cues that are visible in the screenshot. Do not assume hover/focus state colors exist if they are not shown."
 ];
 var CHECK_STATEMENTS = {
   [Accessibility.CONTRAST]: "All text and interactive elements appear to have sufficient color contrast \u2014 text is clearly readable against its background",
   [Accessibility.READABILITY]: "All text is readable \u2014 no text is cut off, overlapping, too small to read, or obscured by background images",
-  [Accessibility.INTERACTIVE_VISIBILITY]: "All interactive elements (buttons, links, inputs) are clearly identifiable and visually distinct from non-interactive content"
+  [Accessibility.INTERACTIVE_VISIBILITY]: "All interactive elements (buttons, links, inputs) are clearly identifiable and visually distinct from non-interactive content",
+  [Accessibility.COLOR_BLINDNESS]: "Information conveyed by color remains distinguishable to viewers with common color vision deficiencies \u2014 status indicators, chart series, and other meaningful color pairings do not rely on hue combinations that are commonly confused (e.g., red/green, blue/purple)",
+  [Accessibility.COLOR_ALONE]: "Information conveyed by color is also conveyed through at least one non-color cue \u2014 text labels, icons, shapes, patterns, underlines, or position accompany any color-based meaning (e.g., required fields, error states, chart legends, link styling)"
 };
 function buildAccessibilityPrompt(options) {
   const checks = options?.checks ?? [...ALL_CHECKS];
@@ -1309,10 +1317,65 @@ async function normalizeImage(input) {
   };
 }
 
-// src/core/video.ts
+// src/core/debug-frames.ts
+var import_node_crypto = require("crypto");
 var import_promises2 = require("fs/promises");
-var import_node_os = require("os");
 var import_node_path2 = require("path");
+var DEBUG_FRAMES_ENV = "VISUAL_AI_DEBUG_FRAMES";
+var DEBUG_FRAMES_DIR_ENV = "VISUAL_AI_DEBUG_FRAMES_DIR";
+var DEFAULT_DIR_NAME = "visual-ai-debug-frames";
+function isEnabled(env) {
+  const raw = env[DEBUG_FRAMES_ENV];
+  if (raw === void 0 || raw === "") return false;
+  const lower = raw.toLowerCase();
+  return lower === "true" || lower === "1";
+}
+function timestampSlug(date) {
+  return date.toISOString().replace(/[:.]/g, "-");
+}
+function paddedIndex(value, total) {
+  const width = Math.max(2, String(total - 1).length);
+  return String(value).padStart(width, "0");
+}
+function extensionFromMimeType(mimeType) {
+  if (mimeType === "image/png") return ".png";
+  if (mimeType === "image/webp") return ".webp";
+  return ".jpg";
+}
+async function saveDebugFrames(frames, env = process.env) {
+  if (!isEnabled(env)) return void 0;
+  if (frames.length === 0) return void 0;
+  const baseDir = env[DEBUG_FRAMES_DIR_ENV]?.trim() || DEFAULT_DIR_NAME;
+  const runDir = (0, import_node_path2.resolve)(baseDir, `${timestampSlug(/* @__PURE__ */ new Date())}-${(0, import_node_crypto.randomBytes)(3).toString("hex")}`);
+  try {
+    await (0, import_promises2.mkdir)(runDir, { recursive: true });
+    await Promise.all(
+      frames.map((frame) => {
+        const idx = paddedIndex(frame.index, frames.length);
+        const ts = frame.timestampSeconds.toFixed(2);
+        const ext = extensionFromMimeType(frame.mimeType);
+        const filename = `frame-${idx}-t${ts}s${ext}`;
+        return (0, import_promises2.writeFile)((0, import_node_path2.join)(runDir, filename), frame.data);
+      })
+    );
+  } catch (err) {
+    process.stderr.write(
+      `[visual-ai-assertions] warning: failed to save debug frames to ${runDir}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return void 0;
+  }
+  process.stderr.write(
+    `[visual-ai-assertions] Saved ${frames.length} debug frame(s) to ${runDir}
+`
+  );
+  return runDir;
+}
+
+// src/core/video.ts
+var import_promises3 = require("fs/promises");
+var import_node_os = require("os");
+var import_node_path3 = require("path");
 var FRAME_MAX_DIMENSION = 1568;
 var DEFAULT_FPS = 1;
 var DEFAULT_MAX_FRAMES = 10;
@@ -1338,7 +1401,7 @@ function isSupportedVideoMimeType(value) {
   return VIDEO_MIME_TYPES.has(value);
 }
 function getVideoMimeFromExtension(filePath) {
-  const ext = (0, import_node_path2.extname)(filePath).toLowerCase();
+  const ext = (0, import_node_path3.extname)(filePath).toLowerCase();
   return VIDEO_EXTENSIONS[ext];
 }
 function detectVideoMimeType(data) {
@@ -1411,24 +1474,24 @@ async function resolveVideoToPath(input) {
   return writeBufferToTemp(buf, mimeType);
 }
 async function writeBufferToTemp(data, mimeType) {
-  const dir = await (0, import_promises2.mkdtemp)((0, import_node_path2.join)((0, import_node_os.tmpdir)(), "visual-ai-video-"));
+  const dir = await (0, import_promises3.mkdtemp)((0, import_node_path3.join)((0, import_node_os.tmpdir)(), "visual-ai-video-"));
   try {
     const ext = extensionFor(mimeType);
-    const path = (0, import_node_path2.join)(dir, `input${ext}`);
-    await (0, import_promises2.writeFile)(path, data);
+    const path = (0, import_node_path3.join)(dir, `input${ext}`);
+    await (0, import_promises3.writeFile)(path, data);
     return {
       path,
       mimeType,
       cleanup: async () => {
         try {
-          await (0, import_promises2.rm)(dir, { recursive: true, force: true });
+          await (0, import_promises3.rm)(dir, { recursive: true, force: true });
         } catch {
         }
       }
     };
   } catch (err) {
     try {
-      await (0, import_promises2.rm)(dir, { recursive: true, force: true });
+      await (0, import_promises3.rm)(dir, { recursive: true, force: true });
     } catch {
     }
     throw err;
@@ -1457,7 +1520,7 @@ async function loadFfmpegFactory() {
       const code = err?.code;
       if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
         throw new VisualAIVideoError(
-          "Video support requires fluent-ffmpeg. Install it with: pnpm add -D fluent-ffmpeg @ffmpeg-installer/ffmpeg @ffprobe-installer/ffprobe @types/fluent-ffmpeg"
+          "Could not load fluent-ffmpeg. It ships as a dependency of visual-ai-assertions, so this usually means the install was pruned or the platform-specific binary is unavailable. Reinstall the package or run: pnpm add fluent-ffmpeg @ffmpeg-installer/ffmpeg @ffprobe-installer/ffprobe"
         );
       }
       throw new VisualAIVideoError(
@@ -1502,7 +1565,7 @@ async function loadFfmpegFactory() {
 }
 async function probeDurationSeconds(videoPath) {
   const ffmpeg = await loadFfmpegFactory();
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let settled = false;
     const finish = (fn) => {
       if (settled) return;
@@ -1539,7 +1602,7 @@ async function probeDurationSeconds(videoPath) {
         return;
       }
       finish(() => {
-        resolve(duration);
+        resolve2(duration);
       });
     });
   });
@@ -1571,10 +1634,10 @@ async function extractFrames(videoPath, options = {}) {
       `Video duration ${durationSeconds.toFixed(2)}s exceeds limit of ${maxDurationSeconds}s. Pass { maxDurationSeconds: N } to override, or trim the source video.`
     );
   }
-  const outputDir = await (0, import_promises2.mkdtemp)((0, import_node_path2.join)((0, import_node_os.tmpdir)(), "visual-ai-frames-"));
+  const outputDir = await (0, import_promises3.mkdtemp)((0, import_node_path3.join)((0, import_node_os.tmpdir)(), "visual-ai-frames-"));
   try {
     const filter = `fps=${fps},scale='if(gt(iw,ih),min(${FRAME_MAX_DIMENSION},iw),-2)':'if(gt(iw,ih),-2,min(${FRAME_MAX_DIMENSION},ih))':flags=area`;
-    await new Promise((resolve, reject) => {
+    await new Promise((resolve2, reject) => {
       let settled = false;
       const cmd = ffmpeg(videoPath);
       const finish = (fn) => {
@@ -1596,9 +1659,9 @@ async function extractFrames(videoPath, options = {}) {
           );
         });
       }, FFMPEG_RUN_TIMEOUT_MS);
-      cmd.outputOptions(["-vf", filter, "-vframes", String(maxFrames), "-q:v", "3"]).output((0, import_node_path2.join)(outputDir, "frame-%04d.jpg")).on("end", () => {
+      cmd.outputOptions(["-vf", filter, "-vframes", String(maxFrames), "-q:v", "3"]).output((0, import_node_path3.join)(outputDir, "frame-%04d.jpg")).on("end", () => {
         finish(() => {
-          resolve();
+          resolve2();
         });
       }).on("error", (err) => {
         finish(() => {
@@ -1606,7 +1669,7 @@ async function extractFrames(videoPath, options = {}) {
         });
       }).run();
     });
-    const files = (await (0, import_promises2.readdir)(outputDir)).filter((name) => name.endsWith(".jpg")).sort();
+    const files = (await (0, import_promises3.readdir)(outputDir)).filter((name) => name.endsWith(".jpg")).sort();
     if (files.length === 0) {
       throw new VisualAIVideoError(
         "No frames could be extracted from the video. The source may be corrupt or empty."
@@ -1614,7 +1677,7 @@ async function extractFrames(videoPath, options = {}) {
     }
     const frames = await Promise.all(
       files.map(async (name, index) => {
-        const data = await (0, import_promises2.readFile)((0, import_node_path2.join)(outputDir, name));
+        const data = await (0, import_promises3.readFile)((0, import_node_path3.join)(outputDir, name));
         const timestampSeconds = Math.min(durationSeconds, (index + 0.5) / fps);
         let cachedBase64;
         return {
@@ -1634,7 +1697,7 @@ async function extractFrames(videoPath, options = {}) {
     return { frames, durationSeconds };
   } finally {
     try {
-      await (0, import_promises2.rm)(outputDir, { recursive: true, force: true });
+      await (0, import_promises3.rm)(outputDir, { recursive: true, force: true });
     } catch {
     }
   }
@@ -1670,6 +1733,7 @@ async function normalizeMedia(input, videoOptions) {
     const { path, cleanup } = await resolveVideoToPath(input);
     try {
       const { frames, durationSeconds } = await extractFrames(path, videoOptions);
+      await saveDebugFrames(frames);
       return { kind: "video", frames, durationSeconds };
     } finally {
       try {