visual-ai-assertions 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -74,6 +74,10 @@ declare const Accessibility: {
     readonly READABILITY: "readability";
     /** Detects interactive elements that are not visually distinct */
     readonly INTERACTIVE_VISIBILITY: "interactive-visibility";
+    /** Detects color choices likely to be indistinguishable to viewers with common color vision deficiencies */
+    readonly COLOR_BLINDNESS: "color-blindness";
+    /** Detects information conveyed by color alone, without a non-color cue (icon, text, pattern, position) */
+    readonly COLOR_ALONE: "color-alone";
 };
 /** Union of all built-in content check names. */
 type ContentCheckName = (typeof Content)[keyof typeof Content];

package/dist/index.d.ts

@@ -74,6 +74,10 @@ declare const Accessibility: {
     readonly READABILITY: "readability";
     /** Detects interactive elements that are not visually distinct */
     readonly INTERACTIVE_VISIBILITY: "interactive-visibility";
+    /** Detects color choices likely to be indistinguishable to viewers with common color vision deficiencies */
+    readonly COLOR_BLINDNESS: "color-blindness";
+    /** Detects information conveyed by color alone, without a non-color cue (icon, text, pattern, position) */
+    readonly COLOR_ALONE: "color-alone";
 };
 /** Union of all built-in content check names. */
 type ContentCheckName = (typeof Content)[keyof typeof Content];

package/dist/index.js

@@ -74,7 +74,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
@@ -399,12 +403,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];
@@ -1241,10 +1249,65 @@ async function normalizeImage(input) {
   };
 }
 
+// src/core/debug-frames.ts
+import { randomBytes } from "crypto";
+import { mkdir, writeFile } from "fs/promises";
+import { join, resolve } from "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 = resolve(baseDir, `${timestampSlug(/* @__PURE__ */ new Date())}-${randomBytes(3).toString("hex")}`);
+  try {
+    await 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 writeFile(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
-import { mkdtemp, readFile as readFile2, readdir, rm, writeFile } from "fs/promises";
+import { mkdtemp, readFile as readFile2, readdir, rm, writeFile as writeFile2 } from "fs/promises";
 import { tmpdir } from "os";
-import { extname as extname2, join } from "path";
+import { extname as extname2, join as join2 } from "path";
 var FRAME_MAX_DIMENSION = 1568;
 var DEFAULT_FPS = 1;
 var DEFAULT_MAX_FRAMES = 10;
@@ -1343,11 +1406,11 @@ async function resolveVideoToPath(input) {
   return writeBufferToTemp(buf, mimeType);
 }
 async function writeBufferToTemp(data, mimeType) {
-  const dir = await mkdtemp(join(tmpdir(), "visual-ai-video-"));
+  const dir = await mkdtemp(join2(tmpdir(), "visual-ai-video-"));
   try {
     const ext = extensionFor(mimeType);
-    const path = join(dir, `input${ext}`);
-    await writeFile(path, data);
+    const path = join2(dir, `input${ext}`);
+    await writeFile2(path, data);
     return {
       path,
       mimeType,
@@ -1389,7 +1452,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(
@@ -1434,7 +1497,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;
@@ -1471,7 +1534,7 @@ async function probeDurationSeconds(videoPath) {
         return;
       }
       finish(() => {
-        resolve(duration);
+        resolve2(duration);
       });
     });
   });
@@ -1503,10 +1566,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 mkdtemp(join(tmpdir(), "visual-ai-frames-"));
+  const outputDir = await mkdtemp(join2(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) => {
@@ -1528,9 +1591,9 @@ async function extractFrames(videoPath, options = {}) {
           );
         });
       }, FFMPEG_RUN_TIMEOUT_MS);
-      cmd.outputOptions(["-vf", filter, "-vframes", String(maxFrames), "-q:v", "3"]).output(join(outputDir, "frame-%04d.jpg")).on("end", () => {
+      cmd.outputOptions(["-vf", filter, "-vframes", String(maxFrames), "-q:v", "3"]).output(join2(outputDir, "frame-%04d.jpg")).on("end", () => {
         finish(() => {
-          resolve();
+          resolve2();
         });
       }).on("error", (err) => {
         finish(() => {
@@ -1546,7 +1609,7 @@ async function extractFrames(videoPath, options = {}) {
     }
     const frames = await Promise.all(
       files.map(async (name, index) => {
-        const data = await readFile2(join(outputDir, name));
+        const data = await readFile2(join2(outputDir, name));
         const timestampSeconds = Math.min(durationSeconds, (index + 0.5) / fps);
         let cachedBase64;
         return {
@@ -1602,6 +1665,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 {