visual-ai-assertions 0.9.0 → 0.10.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
 ```
@@ -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

@@ -1309,10 +1309,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 +1393,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 +1466,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 +1512,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 +1557,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 +1594,7 @@ async function probeDurationSeconds(videoPath) {
         return;
       }
       finish(() => {
-        resolve(duration);
+        resolve2(duration);
       });
     });
   });
@@ -1571,10 +1626,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 +1651,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 +1661,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 +1669,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 +1689,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 +1725,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 {