@blazediff/core-native 4.0.0 → 4.1.0

package/dist/index.d.ts

@@ -9,9 +9,14 @@ interface BlazeDiffOptions {
     compression?: number;
     /** JPEG quality (1-100). Default: 90 */
     quality?: number;
+    /** Run structured interpretation after raw pixel diff */
+    interpret?: boolean;
+    /** Output format for diff: "png" (default) or "html" (interpret report) */
+    outputFormat?: "png" | "html";
 }
 type BlazeDiffResult = {
     match: true;
+    interpretation?: InterpretResult;
 } | {
     match: false;
     reason: "layout-diff";
@@ -20,11 +25,66 @@ type BlazeDiffResult = {
     reason: "pixel-diff";
     diffCount: number;
     diffPercentage: number;
+    interpretation?: InterpretResult;
 } | {
     match: false;
     reason: "file-not-exists";
     file: string;
 };
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ShapeStats {
+    fillRatio: number;
+    borderRatio: number;
+    innerFillRatio: number;
+    centerDensity: number;
+    rowOccupancy: number;
+    colOccupancy: number;
+}
+interface ColorDeltaStats {
+    meanDelta: number;
+    maxDelta: number;
+}
+interface GradientStats {
+    edgeScore: number;
+}
+interface ClassificationSignals {
+    blendsWithBgInImg1: boolean;
+    blendsWithBgInImg2: boolean;
+    lowColorDelta: boolean;
+    lowEdgeChange: boolean;
+    denseFill: boolean;
+    sparseFill: boolean;
+    tinyRegion: boolean;
+    confidence: number;
+}
+interface ChangeRegion {
+    bbox: BoundingBox;
+    pixelCount: number;
+    percentage: number;
+    position: string;
+    shape: string;
+    shapeStats: ShapeStats;
+    changeType: string;
+    signals: ClassificationSignals;
+    confidence: number;
+    colorDelta: ColorDeltaStats;
+    gradient: GradientStats;
+}
+interface InterpretResult {
+    summary: string;
+    diffCount: number;
+    totalRegions: number;
+    regions: ChangeRegion[];
+    severity: string;
+    diffPercentage: number;
+    width: number;
+    height: number;
+}
 /**
  * Compare two images (PNG or JPEG) and optionally generate a diff image.
  *
@@ -55,5 +115,21 @@ declare function getBinaryPath(): string;
  * Returns true if the native module loaded successfully.
  */
 declare function hasNativeBinding(): boolean;
+/**
+ * Interpret the diff between two images, returning structured analysis results.
+ *
+ * Uses native N-API bindings when available for better performance.
+ * Falls back to execFile if native bindings are unavailable.
+ *
+ * @example
+ * ```ts
+ * const result = await interpret('expected.png', 'actual.png');
+ * console.log(result.summary);
+ * for (const region of result.regions) {
+ *   console.log(`${region.position}: ${region.changeType} (${region.percentage.toFixed(2)}%)`);
+ * }
+ * ```
+ */
+declare function interpret(image1Path: string, image2Path: string, options?: Pick<BlazeDiffOptions, "threshold" | "antialiasing">): Promise<InterpretResult>;
 
-export { type BlazeDiffOptions, type BlazeDiffResult, compare, getBinaryPath, hasNativeBinding };
+export { type BlazeDiffOptions, type BlazeDiffResult, type BoundingBox, type ChangeRegion, type ClassificationSignals, type ColorDeltaStats, type GradientStats, type InterpretResult, type ShapeStats, compare, getBinaryPath, hasNativeBinding, interpret };

package/dist/index.js

@@ -32,7 +32,8 @@ var index_exports = {};
 __export(index_exports, {
   compare: () => compare,
   getBinaryPath: () => getBinaryPath,
-  hasNativeBinding: () => hasNativeBinding
+  hasNativeBinding: () => hasNativeBinding,
+  interpret: () => interpret
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -119,25 +120,19 @@ function tryLoadNativeBinding() {
   return null;
 }
 function convertNapiResult(result) {
+  const interpretation = result.interpretation ?? void 0;
   if (result.matchResult) {
-    return { match: true };
+    return { match: true, interpretation };
   }
   if (result.reason === "layout-diff") {
     return { match: false, reason: "layout-diff" };
   }
-  if (result.reason === "pixel-diff") {
-    return {
-      match: false,
-      reason: "pixel-diff",
-      diffCount: result.diffCount ?? 0,
-      diffPercentage: result.diffPercentage ?? 0
-    };
-  }
   return {
     match: false,
     reason: "pixel-diff",
     diffCount: result.diffCount ?? 0,
-    diffPercentage: result.diffPercentage ?? 0
+    diffPercentage: result.diffPercentage ?? 0,
+    interpretation
   };
 }
 function convertToNapiOptions(options) {
@@ -146,7 +141,9 @@ function convertToNapiOptions(options) {
     antialiasing: options?.antialiasing,
     diffMask: options?.diffMask,
     compression: options?.compression,
-    quality: options?.quality
+    quality: options?.quality,
+    interpret: options?.interpret,
+    outputFormat: options?.outputFormat
   };
 }
 function resolveBinaryPath() {
@@ -195,16 +192,21 @@ function getBinaryPathInternal() {
 }
 function buildArgs(diffOutput, options) {
   const args = [];
+  const useInterpret = options?.interpret || options?.outputFormat === "html";
   if (diffOutput) args.push(diffOutput);
+  if (useInterpret) args.push("--interpret");
   args.push("--output-format=json");
   if (!options) return args;
   if (options.threshold !== void 0)
     args.push(`--threshold=${options.threshold}`);
   if (options.antialiasing) args.push("--antialiasing");
-  if (options.diffMask) args.push("--diff-mask");
-  if (options.compression !== void 0)
-    args.push(`--compression=${options.compression}`);
-  if (options.quality !== void 0) args.push(`--quality=${options.quality}`);
+  if (!useInterpret) {
+    if (options.diffMask) args.push("--diff-mask");
+    if (options.compression !== void 0)
+      args.push(`--compression=${options.compression}`);
+    if (options.quality !== void 0)
+      args.push(`--quality=${options.quality}`);
+  }
   return args;
 }
 function parseJsonOutput(text) {
@@ -225,6 +227,9 @@ function detectMissingFile(error, basePath, comparePath) {
 async function execFileCompare(basePath, comparePath, diffOutput, options) {
   const binaryPath = getBinaryPathInternal();
   const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
+  if (options?.interpret || options?.outputFormat === "html") {
+    return execFileInterpretCompare(binaryPath, args, basePath, comparePath);
+  }
   try {
     await execFileAsync(binaryPath, args);
     return { match: true };
@@ -257,6 +262,35 @@ async function execFileCompare(basePath, comparePath, diffOutput, options) {
     throw new Error(output || `blazediff exited with code ${code}`);
   }
 }
+async function execFileInterpretCompare(binaryPath, args, basePath, comparePath) {
+  try {
+    const { stdout } = await execFileAsync(binaryPath, args);
+    const interpretation = JSON.parse(stdout);
+    return { match: true, interpretation };
+  } catch (err) {
+    const { code, stdout, stderr } = err;
+    if (code === 1 && stdout) {
+      const interpretation = JSON.parse(stdout);
+      return {
+        match: false,
+        reason: "pixel-diff",
+        diffCount: interpretation.diffCount,
+        diffPercentage: interpretation.diffPercentage,
+        interpretation
+      };
+    }
+    const errorOutput = stderr || stdout || "";
+    if (code === 2) {
+      const missingFile = detectMissingFile(errorOutput, basePath, comparePath);
+      if (missingFile) {
+        return { match: false, reason: "file-not-exists", file: missingFile };
+      }
+    }
+    throw new Error(
+      errorOutput || `blazediff --interpret exited with code ${code}`
+    );
+  }
+}
 async function compare(basePath, comparePath, diffOutput, options) {
   const binding = tryLoadNativeBinding();
   if (binding) {
@@ -285,9 +319,27 @@ function getBinaryPath() {
 function hasNativeBinding() {
   return tryLoadNativeBinding() !== null;
 }
+async function interpret(image1Path, image2Path, options) {
+  const binding = tryLoadNativeBinding();
+  if (binding) {
+    return binding.interpretImages(image1Path, image2Path, {
+      threshold: options?.threshold,
+      antialiasing: options?.antialiasing
+    });
+  }
+  const result = await compare(image1Path, image2Path, void 0, {
+    ...options,
+    interpret: true
+  });
+  if ("interpretation" in result && result.interpretation) {
+    return result.interpretation;
+  }
+  throw new Error("Interpretation result missing from compare");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   compare,
   getBinaryPath,
-  hasNativeBinding
+  hasNativeBinding,
+  interpret
 });

package/dist/index.mjs

@@ -77,25 +77,19 @@ function tryLoadNativeBinding() {
   return null;
 }
 function convertNapiResult(result) {
+  const interpretation = result.interpretation ?? void 0;
   if (result.matchResult) {
-    return { match: true };
+    return { match: true, interpretation };
   }
   if (result.reason === "layout-diff") {
     return { match: false, reason: "layout-diff" };
   }
-  if (result.reason === "pixel-diff") {
-    return {
-      match: false,
-      reason: "pixel-diff",
-      diffCount: result.diffCount ?? 0,
-      diffPercentage: result.diffPercentage ?? 0
-    };
-  }
   return {
     match: false,
     reason: "pixel-diff",
     diffCount: result.diffCount ?? 0,
-    diffPercentage: result.diffPercentage ?? 0
+    diffPercentage: result.diffPercentage ?? 0,
+    interpretation
   };
 }
 function convertToNapiOptions(options) {
@@ -104,7 +98,9 @@ function convertToNapiOptions(options) {
     antialiasing: options?.antialiasing,
     diffMask: options?.diffMask,
     compression: options?.compression,
-    quality: options?.quality
+    quality: options?.quality,
+    interpret: options?.interpret,
+    outputFormat: options?.outputFormat
   };
 }
 function resolveBinaryPath() {
@@ -153,16 +149,21 @@ function getBinaryPathInternal() {
 }
 function buildArgs(diffOutput, options) {
   const args = [];
+  const useInterpret = options?.interpret || options?.outputFormat === "html";
   if (diffOutput) args.push(diffOutput);
+  if (useInterpret) args.push("--interpret");
   args.push("--output-format=json");
   if (!options) return args;
   if (options.threshold !== void 0)
     args.push(`--threshold=${options.threshold}`);
   if (options.antialiasing) args.push("--antialiasing");
-  if (options.diffMask) args.push("--diff-mask");
-  if (options.compression !== void 0)
-    args.push(`--compression=${options.compression}`);
-  if (options.quality !== void 0) args.push(`--quality=${options.quality}`);
+  if (!useInterpret) {
+    if (options.diffMask) args.push("--diff-mask");
+    if (options.compression !== void 0)
+      args.push(`--compression=${options.compression}`);
+    if (options.quality !== void 0)
+      args.push(`--quality=${options.quality}`);
+  }
   return args;
 }
 function parseJsonOutput(text) {
@@ -183,6 +184,9 @@ function detectMissingFile(error, basePath, comparePath) {
 async function execFileCompare(basePath, comparePath, diffOutput, options) {
   const binaryPath = getBinaryPathInternal();
   const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
+  if (options?.interpret || options?.outputFormat === "html") {
+    return execFileInterpretCompare(binaryPath, args, basePath, comparePath);
+  }
   try {
     await execFileAsync(binaryPath, args);
     return { match: true };
@@ -215,6 +219,35 @@ async function execFileCompare(basePath, comparePath, diffOutput, options) {
     throw new Error(output || `blazediff exited with code ${code}`);
   }
 }
+async function execFileInterpretCompare(binaryPath, args, basePath, comparePath) {
+  try {
+    const { stdout } = await execFileAsync(binaryPath, args);
+    const interpretation = JSON.parse(stdout);
+    return { match: true, interpretation };
+  } catch (err) {
+    const { code, stdout, stderr } = err;
+    if (code === 1 && stdout) {
+      const interpretation = JSON.parse(stdout);
+      return {
+        match: false,
+        reason: "pixel-diff",
+        diffCount: interpretation.diffCount,
+        diffPercentage: interpretation.diffPercentage,
+        interpretation
+      };
+    }
+    const errorOutput = stderr || stdout || "";
+    if (code === 2) {
+      const missingFile = detectMissingFile(errorOutput, basePath, comparePath);
+      if (missingFile) {
+        return { match: false, reason: "file-not-exists", file: missingFile };
+      }
+    }
+    throw new Error(
+      errorOutput || `blazediff --interpret exited with code ${code}`
+    );
+  }
+}
 async function compare(basePath, comparePath, diffOutput, options) {
   const binding = tryLoadNativeBinding();
   if (binding) {
@@ -243,8 +276,26 @@ function getBinaryPath() {
 function hasNativeBinding() {
   return tryLoadNativeBinding() !== null;
 }
+async function interpret(image1Path, image2Path, options) {
+  const binding = tryLoadNativeBinding();
+  if (binding) {
+    return binding.interpretImages(image1Path, image2Path, {
+      threshold: options?.threshold,
+      antialiasing: options?.antialiasing
+    });
+  }
+  const result = await compare(image1Path, image2Path, void 0, {
+    ...options,
+    interpret: true
+  });
+  if ("interpretation" in result && result.interpretation) {
+    return result.interpretation;
+  }
+  throw new Error("Interpretation result missing from compare");
+}
 export {
   compare,
   getBinaryPath,
-  hasNativeBinding
+  hasNativeBinding,
+  interpret
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blazediff/core-native",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Native Rust binaries for blazediff - the fastest image diff in the world",
   "private": false,
   "publishConfig": {
@@ -20,12 +20,12 @@
     "dist"
   ],
   "optionalDependencies": {
-    "@blazediff/core-native-darwin-arm64": "4.0.0",
-    "@blazediff/core-native-darwin-x64": "4.0.0",
-    "@blazediff/core-native-linux-arm64": "4.0.0",
-    "@blazediff/core-native-linux-x64": "4.0.0",
-    "@blazediff/core-native-win32-arm64": "4.0.0",
-    "@blazediff/core-native-win32-x64": "4.0.0"
+    "@blazediff/core-native-darwin-arm64": "4.1.0",
+    "@blazediff/core-native-darwin-x64": "4.1.0",
+    "@blazediff/core-native-linux-arm64": "4.1.0",
+    "@blazediff/core-native-linux-x64": "4.1.0",
+    "@blazediff/core-native-win32-arm64": "4.1.0",
+    "@blazediff/core-native-win32-x64": "4.1.0"
   },
   "keywords": [
     "image",