@blazediff/core-native 4.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Teimur Gasanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# @blazediff/core-native
+
+<div align="center">
+
+[![npm bundle size](https://img.shields.io/bundlephobia/min/%40blazediff%2Fbin)](https://www.npmjs.com/package/@blazediff/core-native)
+[![NPM Downloads](https://img.shields.io/npm/dy/%40blazediff%2Fbin)](https://www.npmjs.com/package/@blazediff/core-native)
+[![Crates.io](https://img.shields.io/crates/v/blazediff.svg)](https://crates.io/crates/blazediff)
+
+</div>
+
+The fastest single-threaded image diff in the world. Native Rust implementation with SIMD optimization, **3-4x faster** and **3x smaller** than [odiff](https://github.com/dmtrKovalenko/odiff).
+
+**Features:**
+- **PNG, JPEG & QOI support** - auto-detected by file extension
+- SIMD-accelerated (NEON on ARM, SSE4.1 on x86)
+- Block-based two-pass optimization
+- YIQ perceptual color difference
+- Anti-aliasing detection
+- Cross-platform pre-built binaries (~700KB-900KB, no compilation required)
+
+**Vendored Libraries:**
+- [libspng](https://libspng.org/) - Fast PNG decoding/encoding with SIMD
+- [libjpeg-turbo](https://libjpeg-turbo.org/) - High-performance JPEG codec with SIMD
+- [qoi](https://github.com/aldanor/qoi-rust) - QOI (Quite OK Image) format for fast lossless compression
+
+> **Note:** This package was previously published as [`@blazediff/bin`](https://www.npmjs.com/package/@blazediff/bin), which is now deprecated. Please use `@blazediff/core-native` instead.
+
+## Installation
+
+```bash
+npm install @blazediff/core-native
+```
+
+Also available as a Rust crate: [`cargo install blazediff`](https://crates.io/crates/blazediff)
+
+Pre-built binaries are included via platform-specific packages:
+- [`@blazediff/core-native-darwin-arm64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native-darwin-arm64) - macOS ARM64 (Apple Silicon)
+- [`@blazediff/core-native-darwin-x64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native-darwin-x64) - macOS x64 (Intel)
+- [`@blazediff/core-native-linux-arm64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native-linux-arm64) - Linux ARM64
+- [`@blazediff/core-native-linux-x64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native-linux-x64) - Linux x64
+- [`@blazediff/core-native-win32-arm64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native-win32-arm64) - Windows ARM64
+- [`@blazediff/core-native-win32-x64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native-win32-x64) - Windows x64
+
+## API
+
+### compare(basePath, comparePath, diffOutput, options?)
+
+Compare two images (PNG or JPEG) and generate a diff image. Format is auto-detected from file extension.
+
+<table>
+  <tr>
+    <th width="500">Parameter</th>
+    <th width="500">Type</th>
+    <th width="500">Description</th>
+  </tr>
+  <tr>
+    <td><code>basePath</code></td>
+    <td>string</td>
+    <td>Path to the base/expected image</td>
+  </tr>
+  <tr>
+    <td><code>comparePath</code></td>
+    <td>string</td>
+    <td>Path to the comparison/actual image</td>
+  </tr>
+  <tr>
+    <td><code>diffOutput</code></td>
+    <td>string</td>
+    <td>Path where the diff image will be saved</td>
+  </tr>
+  <tr>
+    <td><code>options</code></td>
+    <td>BlazeDiffOptions</td>
+    <td>Comparison options (optional)</td>
+  </tr>
+</table>
+
+<strong>Returns:</strong> `Promise<BlazeDiffResult>`
+
+<table>
+  <tr>
+    <th width="500">Option</th>
+    <th width="500">Type</th>
+    <th width="500">Default</th>
+    <th width="500">Description</th>
+  </tr>
+  <tr>
+    <td><code>threshold</code></td>
+    <td>number</td>
+    <td>0.1</td>
+    <td>Color difference threshold (0.0-1.0). Lower = more strict</td>
+  </tr>
+  <tr>
+    <td><code>antialiasing</code></td>
+    <td>boolean</td>
+    <td>false</td>
+    <td>Enable anti-aliasing detection to exclude AA pixels from diff count</td>
+  </tr>
+  <tr>
+    <td><code>diffMask</code></td>
+    <td>boolean</td>
+    <td>false</td>
+    <td>Output only differences with transparent background</td>
+  </tr>
+</table>
+
+### Result Types
+
+```typescript
+type BlazeDiffResult =
+  | { match: true }
+  | { match: false; reason: "layout-diff" }
+  | { match: false; reason: "pixel-diff"; diffCount: number; diffPercentage: number }
+  | { match: false; reason: "file-not-exists"; file: string };
+```
+
+## Usage
+
+### Programmatic API
+
+```typescript
+import { compare } from '@blazediff/core-native';
+
+const result = await compare('expected.png', 'actual.png', 'diff.png', {
+  threshold: 0.1,
+  antialiasing: true,
+});
+
+if (result.match) {
+  console.log('Images are identical!');
+} else if (result.reason === 'pixel-diff') {
+  console.log(`${result.diffCount} pixels differ (${result.diffPercentage.toFixed(2)}%)`);
+} else if (result.reason === 'layout-diff') {
+  console.log('Images have different dimensions');
+}
+```
+
+### CLI Usage
+
+```bash
+# Compare two PNG images
+npx blazediff expected.png actual.png diff.png
+
+# Compare two JPEG images
+npx blazediff expected.jpg actual.jpg diff.jpg
+
+# Compare two QOI images
+npx blazediff expected.qoi actual.qoi diff.qoi
+
+# Mixed formats (PNG input, QOI output - recommended for smallest diff files)
+npx blazediff expected.png actual.png diff.qoi
+
+# With options
+npx blazediff expected.png actual.png diff.png --threshold 0.05 --antialiasing
+
+# With higher PNG compression (smaller output file, slower)
+npx blazediff expected.png actual.png diff.png -c 6
+
+# With JPEG quality setting
+npx blazediff expected.jpg actual.jpg diff.jpg -q 85
+
+# Output as JSON
+npx blazediff expected.png actual.png diff.png --output-format json
+```
+
+### CLI Options
+
+```
+Usage: blazediff [OPTIONS] <IMAGE1> <IMAGE2> [OUTPUT]
+
+Arguments:
+  <IMAGE1>  First image path (PNG, JPEG, or QOI)
+  <IMAGE2>  Second image path (PNG, JPEG, or QOI)
+  [OUTPUT]  Output diff image path (optional, format detected from extension)
+
+Options:
+  -t, --threshold <THRESHOLD>  Color difference threshold (0.0-1.0) [default: 0.1]
+  -a, --antialiasing           Enable anti-aliasing detection
+      --diff-mask              Output only differences (transparent background)
+  -c, --compression <LEVEL>    PNG compression level (0-9, 0=fastest, 9=smallest) [default: 0]
+  -q, --quality <QUALITY>      JPEG quality (1-100) [default: 90]
+      --output-format <FORMAT> Output format (json or text) [default: json]
+  -h, --help                   Print help
+  -V, --version                Print version
+```
+
+### Supported Formats
+
+| Format | Extensions | Notes |
+|--------|------------|-------|
+| PNG | `.png` | Lossless, supports transparency |
+| JPEG | `.jpg`, `.jpeg` | Lossy, smaller file sizes |
+| QOI | `.qoi` | Fast lossless, ideal for diff outputs (12x smaller than uncompressed PNG) |
+
+Input images can be mixed formats (e.g., compare PNG to JPEG). Output format is determined by the output file extension.
+
+**QOI for diff outputs:** QOI excels at encoding diff images with large uniform areas, producing files 12x smaller than PNG (level 0) while being faster to encode.
+
+### Exit Codes
+
+- `0` - Images are identical
+- `1` - Images differ (includes layout/size mismatch)
+- `2` - Error (file not found, invalid format, etc.)
+
+## Performance
+
+Benchmarked on Apple M1 Pro with 5600x3200 4K PNG images:
+
+| Tool | Benchmark Time | vs blazediff |
+|------|------|--------------|
+| **blazediff** | ~327ms | - |
+| odiff | ~1215ms | 3.4x slower |
+
+Binary sizes (stripped, LTO optimized) - **~3x smaller than odiff**:
+
+| Platform | blazediff | odiff |
+|----------|-----------|-------|
+| macOS ARM64 | 702 KB | 2.2 MB |
+| macOS x64 | 773 KB | 2.6 MB |
+| Linux ARM64 | 753 KB | 2.3 MB |
+| Linux x64 | 869 KB | 2.9 MB |
+| Windows ARM64 | 580 KB | 2.4 MB |
+| Windows x64 | 915 KB | 3.0 MB |
+
+## Algorithm
+
+BlazeDiff uses a two-pass block-based approach with SIMD acceleration:
+
+1. **Cold Pass**: Scans image in 8x8 blocks using 32-bit integer comparison to identify changed regions
+2. **Hot Pass**: Only processes blocks marked as changed, applying YIQ perceptual color difference
+3. **SIMD**: Uses NEON (ARM) or SSE4.1 (x86) for parallel pixel processing
+4. **Anti-aliasing**: Implements Vysniauskas (2009) algorithm to detect AA artifacts
+
+## References
+
+- **YIQ Color Space**: [Kotsarenko & Ramos (2009)](https://doaj.org/article/b2e3b5088ba943eebd9af2927fef08ad) - "Measuring perceived color difference using YIQ NTSC transmission color space"
+- **Anti-Aliasing Detection**: [Vysniauskas (2009)](https://www.researchgate.net/publication/234073157_Anti-aliased_Pixel_and_Intensity_Slope_Detector) - "Anti-aliased Pixel and Intensity Slope Detector"
+- **Inspiration**: [odiff](https://github.com/dmtrKovalenko/odiff) - Fast image comparison tool written in Zig

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+interface BlazeDiffOptions {
+    /** Color difference threshold (0.0-1.0). Lower = more strict. Default: 0.1 */
+    threshold?: number;
+    /** Enable anti-aliasing detection to exclude AA pixels from diff count */
+    antialiasing?: boolean;
+    /** Output only differences with transparent background */
+    diffMask?: boolean;
+    /** PNG compression level (0-9, 0=fastest/largest, 9=slowest/smallest) */
+    compression?: number;
+    /** JPEG quality (1-100). Default: 90 */
+    quality?: number;
+}
+type BlazeDiffResult = {
+    match: true;
+} | {
+    match: false;
+    reason: "layout-diff";
+} | {
+    match: false;
+    reason: "pixel-diff";
+    diffCount: number;
+    diffPercentage: number;
+} | {
+    match: false;
+    reason: "file-not-exists";
+    file: string;
+};
+/**
+ * Compare two images (PNG or JPEG) and optionally generate a diff image.
+ *
+ * Uses native N-API bindings when available for ~10-100x better performance
+ * on small images (no process spawn overhead). Falls back to execFile if
+ * native bindings are unavailable.
+ *
+ * @example
+ * ```ts
+ * // With diff output
+ * const result = await compare('expected.png', 'actual.png', 'diff.png');
+ *
+ * // Without diff output (faster, just returns comparison result)
+ * const result = await compare('expected.png', 'actual.png');
+ *
+ * if (result.match) {
+ *   console.log('Images identical');
+ * } else if (result.reason === 'pixel-diff') {
+ *   console.log(`${result.diffCount} pixels differ`);
+ * }
+ * ```
+ */
+declare function compare(basePath: string, comparePath: string, diffOutput?: string, options?: BlazeDiffOptions): Promise<BlazeDiffResult>;
+/** Get the path to the blazediff binary for direct CLI usage. */
+declare function getBinaryPath(): string;
+/**
+ * Check if native N-API bindings are available.
+ * Returns true if the native module loaded successfully.
+ */
+declare function hasNativeBinding(): boolean;
+
+export { type BlazeDiffOptions, type BlazeDiffResult, compare, getBinaryPath, hasNativeBinding };

package/dist/index.js

@@ -0,0 +1,293 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  compare: () => compare,
+  getBinaryPath: () => getBinaryPath,
+  hasNativeBinding: () => hasNativeBinding
+});
+module.exports = __toCommonJS(index_exports);
+
+// ../../node_modules/.pnpm/tsup@8.5.0_jiti@2.6.0_postcss@8.5.6_tsx@4.20.6_typescript@5.9.2_yaml@2.8.1/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.src || new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/index.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_module = require("module");
+var import_node_os = __toESM(require("os"));
+var import_node_path = __toESM(require("path"));
+var import_node_url = require("url");
+var import_node_util = require("util");
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var PLATFORM_PACKAGES = {
+  "darwin-arm64": {
+    packageName: "@blazediff/core-native-darwin-arm64",
+    packageDir: "core-native-darwin-arm64"
+  },
+  "darwin-x64": {
+    packageName: "@blazediff/core-native-darwin-x64",
+    packageDir: "core-native-darwin-x64"
+  },
+  "linux-arm64": {
+    packageName: "@blazediff/core-native-linux-arm64",
+    packageDir: "core-native-linux-arm64"
+  },
+  "linux-x64": {
+    packageName: "@blazediff/core-native-linux-x64",
+    packageDir: "core-native-linux-x64"
+  },
+  "win32-arm64": {
+    packageName: "@blazediff/core-native-win32-arm64",
+    packageDir: "core-native-win32-arm64"
+  },
+  "win32-x64": {
+    packageName: "@blazediff/core-native-win32-x64",
+    packageDir: "core-native-win32-x64"
+  }
+};
+var nativeBinding = null;
+var nativeBindingAttempted = false;
+function tryLoadNativeBinding() {
+  if (nativeBindingAttempted) {
+    return nativeBinding;
+  }
+  nativeBindingAttempted = true;
+  const platform = import_node_os.default.platform();
+  const arch = import_node_os.default.arch();
+  const key = `${platform}-${arch}`;
+  const platformInfo = PLATFORM_PACKAGES[key];
+  if (!platformInfo) {
+    return null;
+  }
+  try {
+    const require2 = (0, import_node_module.createRequire)(importMetaUrl);
+    const binding = require2(platformInfo.packageName);
+    if (typeof binding?.compare === "function") {
+      nativeBinding = binding;
+      return binding;
+    }
+  } catch {
+  }
+  try {
+    const currentDir = import_node_path.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
+    const packagesDir = import_node_path.default.resolve(currentDir, "..", "..");
+    const nodePath = import_node_path.default.join(
+      packagesDir,
+      platformInfo.packageDir,
+      "blazediff.node"
+    );
+    if ((0, import_node_fs.existsSync)(nodePath)) {
+      const require2 = (0, import_node_module.createRequire)(importMetaUrl);
+      const binding = require2(nodePath);
+      if (typeof binding?.compare === "function") {
+        nativeBinding = binding;
+        return binding;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function convertNapiResult(result) {
+  if (result.matchResult) {
+    return { match: true };
+  }
+  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
+  };
+}
+function convertToNapiOptions(options) {
+  return {
+    threshold: options?.threshold,
+    antialiasing: options?.antialiasing,
+    diffMask: options?.diffMask,
+    compression: options?.compression,
+    quality: options?.quality
+  };
+}
+function resolveBinaryPath() {
+  const platform = import_node_os.default.platform();
+  const arch = import_node_os.default.arch();
+  const key = `${platform}-${arch}`;
+  const platformInfo = PLATFORM_PACKAGES[key];
+  if (!platformInfo) {
+    throw new Error(
+      `Unsupported platform: ${key}. Supported: ${Object.keys(PLATFORM_PACKAGES).join(", ")}`
+    );
+  }
+  const binaryName = platform === "win32" ? "blazediff.exe" : "blazediff";
+  try {
+    const require2 = (0, import_node_module.createRequire)(importMetaUrl);
+    const packagePath = require2.resolve(
+      `${platformInfo.packageName}/package.json`
+    );
+    const packageDir = import_node_path.default.dirname(packagePath);
+    const binaryPath = import_node_path.default.join(packageDir, binaryName);
+    if ((0, import_node_fs.existsSync)(binaryPath)) {
+      return binaryPath;
+    }
+  } catch {
+  }
+  const currentDir = import_node_path.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
+  const packagesDir = import_node_path.default.resolve(currentDir, "..", "..");
+  const siblingPath = import_node_path.default.join(
+    packagesDir,
+    platformInfo.packageDir,
+    binaryName
+  );
+  if ((0, import_node_fs.existsSync)(siblingPath)) {
+    return siblingPath;
+  }
+  throw new Error(
+    `Platform package ${platformInfo.packageName} is not installed. This usually means the optional dependency wasn't installed for your platform. Try reinstalling with: npm install @blazediff/core-native`
+  );
+}
+var cachedBinaryPath = null;
+function getBinaryPathInternal() {
+  if (!cachedBinaryPath) {
+    cachedBinaryPath = resolveBinaryPath();
+  }
+  return cachedBinaryPath;
+}
+function buildArgs(diffOutput, options) {
+  const args = [];
+  if (diffOutput) args.push(diffOutput);
+  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}`);
+  return args;
+}
+function parseJsonOutput(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function detectMissingFile(error, basePath, comparePath) {
+  if (!/Failed to load images:.*(?:No such file|not found)/i.test(error)) {
+    return null;
+  }
+  if (error.includes(basePath)) return basePath;
+  if (error.includes(comparePath)) return comparePath;
+  return basePath;
+}
+async function execFileCompare(basePath, comparePath, diffOutput, options) {
+  const binaryPath = getBinaryPathInternal();
+  const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
+  try {
+    await execFileAsync(binaryPath, args);
+    return { match: true };
+  } catch (err) {
+    const { code, stdout, stderr } = err;
+    const output = stdout || stderr || "";
+    if (code === 1) {
+      const json = parseJsonOutput(output);
+      if (json?.error?.includes("Layout differs")) {
+        return { match: false, reason: "layout-diff" };
+      }
+      if (json) {
+        return {
+          match: false,
+          reason: "pixel-diff",
+          diffCount: json.diffCount,
+          diffPercentage: json.diffPercentage
+        };
+      }
+      if (output.includes("Layout differs")) {
+        return { match: false, reason: "layout-diff" };
+      }
+    }
+    if (code === 2) {
+      const missingFile = detectMissingFile(output, basePath, comparePath);
+      if (missingFile) {
+        return { match: false, reason: "file-not-exists", file: missingFile };
+      }
+    }
+    throw new Error(output || `blazediff exited with code ${code}`);
+  }
+}
+async function compare(basePath, comparePath, diffOutput, options) {
+  const binding = tryLoadNativeBinding();
+  if (binding) {
+    try {
+      const result = binding.compare(
+        basePath,
+        comparePath,
+        diffOutput ?? null,
+        convertToNapiOptions(options)
+      );
+      return convertNapiResult(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const missingFile = detectMissingFile(message, basePath, comparePath);
+      if (missingFile) {
+        return { match: false, reason: "file-not-exists", file: missingFile };
+      }
+      throw err;
+    }
+  }
+  return execFileCompare(basePath, comparePath, diffOutput, options);
+}
+function getBinaryPath() {
+  return getBinaryPathInternal();
+}
+function hasNativeBinding() {
+  return tryLoadNativeBinding() !== null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compare,
+  getBinaryPath,
+  hasNativeBinding
+});

package/dist/index.mjs

@@ -0,0 +1,250 @@
+// src/index.ts
+import { execFile } from "child_process";
+import { existsSync } from "fs";
+import { createRequire } from "module";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var PLATFORM_PACKAGES = {
+  "darwin-arm64": {
+    packageName: "@blazediff/core-native-darwin-arm64",
+    packageDir: "core-native-darwin-arm64"
+  },
+  "darwin-x64": {
+    packageName: "@blazediff/core-native-darwin-x64",
+    packageDir: "core-native-darwin-x64"
+  },
+  "linux-arm64": {
+    packageName: "@blazediff/core-native-linux-arm64",
+    packageDir: "core-native-linux-arm64"
+  },
+  "linux-x64": {
+    packageName: "@blazediff/core-native-linux-x64",
+    packageDir: "core-native-linux-x64"
+  },
+  "win32-arm64": {
+    packageName: "@blazediff/core-native-win32-arm64",
+    packageDir: "core-native-win32-arm64"
+  },
+  "win32-x64": {
+    packageName: "@blazediff/core-native-win32-x64",
+    packageDir: "core-native-win32-x64"
+  }
+};
+var nativeBinding = null;
+var nativeBindingAttempted = false;
+function tryLoadNativeBinding() {
+  if (nativeBindingAttempted) {
+    return nativeBinding;
+  }
+  nativeBindingAttempted = true;
+  const platform = os.platform();
+  const arch = os.arch();
+  const key = `${platform}-${arch}`;
+  const platformInfo = PLATFORM_PACKAGES[key];
+  if (!platformInfo) {
+    return null;
+  }
+  try {
+    const require2 = createRequire(import.meta.url);
+    const binding = require2(platformInfo.packageName);
+    if (typeof binding?.compare === "function") {
+      nativeBinding = binding;
+      return binding;
+    }
+  } catch {
+  }
+  try {
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const packagesDir = path.resolve(currentDir, "..", "..");
+    const nodePath = path.join(
+      packagesDir,
+      platformInfo.packageDir,
+      "blazediff.node"
+    );
+    if (existsSync(nodePath)) {
+      const require2 = createRequire(import.meta.url);
+      const binding = require2(nodePath);
+      if (typeof binding?.compare === "function") {
+        nativeBinding = binding;
+        return binding;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function convertNapiResult(result) {
+  if (result.matchResult) {
+    return { match: true };
+  }
+  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
+  };
+}
+function convertToNapiOptions(options) {
+  return {
+    threshold: options?.threshold,
+    antialiasing: options?.antialiasing,
+    diffMask: options?.diffMask,
+    compression: options?.compression,
+    quality: options?.quality
+  };
+}
+function resolveBinaryPath() {
+  const platform = os.platform();
+  const arch = os.arch();
+  const key = `${platform}-${arch}`;
+  const platformInfo = PLATFORM_PACKAGES[key];
+  if (!platformInfo) {
+    throw new Error(
+      `Unsupported platform: ${key}. Supported: ${Object.keys(PLATFORM_PACKAGES).join(", ")}`
+    );
+  }
+  const binaryName = platform === "win32" ? "blazediff.exe" : "blazediff";
+  try {
+    const require2 = createRequire(import.meta.url);
+    const packagePath = require2.resolve(
+      `${platformInfo.packageName}/package.json`
+    );
+    const packageDir = path.dirname(packagePath);
+    const binaryPath = path.join(packageDir, binaryName);
+    if (existsSync(binaryPath)) {
+      return binaryPath;
+    }
+  } catch {
+  }
+  const currentDir = path.dirname(fileURLToPath(import.meta.url));
+  const packagesDir = path.resolve(currentDir, "..", "..");
+  const siblingPath = path.join(
+    packagesDir,
+    platformInfo.packageDir,
+    binaryName
+  );
+  if (existsSync(siblingPath)) {
+    return siblingPath;
+  }
+  throw new Error(
+    `Platform package ${platformInfo.packageName} is not installed. This usually means the optional dependency wasn't installed for your platform. Try reinstalling with: npm install @blazediff/core-native`
+  );
+}
+var cachedBinaryPath = null;
+function getBinaryPathInternal() {
+  if (!cachedBinaryPath) {
+    cachedBinaryPath = resolveBinaryPath();
+  }
+  return cachedBinaryPath;
+}
+function buildArgs(diffOutput, options) {
+  const args = [];
+  if (diffOutput) args.push(diffOutput);
+  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}`);
+  return args;
+}
+function parseJsonOutput(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function detectMissingFile(error, basePath, comparePath) {
+  if (!/Failed to load images:.*(?:No such file|not found)/i.test(error)) {
+    return null;
+  }
+  if (error.includes(basePath)) return basePath;
+  if (error.includes(comparePath)) return comparePath;
+  return basePath;
+}
+async function execFileCompare(basePath, comparePath, diffOutput, options) {
+  const binaryPath = getBinaryPathInternal();
+  const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
+  try {
+    await execFileAsync(binaryPath, args);
+    return { match: true };
+  } catch (err) {
+    const { code, stdout, stderr } = err;
+    const output = stdout || stderr || "";
+    if (code === 1) {
+      const json = parseJsonOutput(output);
+      if (json?.error?.includes("Layout differs")) {
+        return { match: false, reason: "layout-diff" };
+      }
+      if (json) {
+        return {
+          match: false,
+          reason: "pixel-diff",
+          diffCount: json.diffCount,
+          diffPercentage: json.diffPercentage
+        };
+      }
+      if (output.includes("Layout differs")) {
+        return { match: false, reason: "layout-diff" };
+      }
+    }
+    if (code === 2) {
+      const missingFile = detectMissingFile(output, basePath, comparePath);
+      if (missingFile) {
+        return { match: false, reason: "file-not-exists", file: missingFile };
+      }
+    }
+    throw new Error(output || `blazediff exited with code ${code}`);
+  }
+}
+async function compare(basePath, comparePath, diffOutput, options) {
+  const binding = tryLoadNativeBinding();
+  if (binding) {
+    try {
+      const result = binding.compare(
+        basePath,
+        comparePath,
+        diffOutput ?? null,
+        convertToNapiOptions(options)
+      );
+      return convertNapiResult(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const missingFile = detectMissingFile(message, basePath, comparePath);
+      if (missingFile) {
+        return { match: false, reason: "file-not-exists", file: missingFile };
+      }
+      throw err;
+    }
+  }
+  return execFileCompare(basePath, comparePath, diffOutput, options);
+}
+function getBinaryPath() {
+  return getBinaryPathInternal();
+}
+function hasNativeBinding() {
+  return tryLoadNativeBinding() !== null;
+}
+export {
+  compare,
+  getBinaryPath,
+  hasNativeBinding
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@blazediff/core-native",
+  "version": "4.0.0",
+  "description": "Native Rust binaries for blazediff - the fastest image diff in the world",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "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"
+  },
+  "keywords": [
+    "image",
+    "comparison",
+    "diff",
+    "pixel",
+    "visual-testing",
+    "visual-regression",
+    "screenshot",
+    "native",
+    "rust",
+    "simd",
+    "fast"
+  ],
+  "author": "Teimur Gasanov <me@teimurjan.dev> (https://github.com/teimurjan)",
+  "repository": "https://github.com/teimurjan/blazediff",
+  "homepage": "https://blazediff.dev",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsup": "8.5.0",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}