vitest-image-snapshot 0.6.49 → 0.6.51

package/README.md

@@ -246,7 +246,7 @@ test("canvas output matches snapshot", async () => {
 
 ## Build Version
 **vitest-image-snapshot** is currently 
-part of the [wesl-js](https://github.com/wgsl-tooling-wg/wesl-js/) monorepo. 
+part of the [wesl-js](https://github.com/webgpu-tools/wesl-js/) monorepo. 
 (It'll eventually move to it's own repo).
 
 ## Contributions

package/dist/{ImageSnapshotReporter-D7WPlzM3.js → ImageSnapshotReporter-B3evIi81.js}

@@ -5,7 +5,13 @@ import { fileURLToPath } from "node:url";
 import * as http from "node:http";
 import isCI from "is-ci";
 //#region src/DiffReport.ts
-const templatesDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "templates");
+const autoOpenValues = [
+	"always",
+	"failures",
+	"never"
+];
+const thisDir = path.dirname(fileURLToPath(import.meta.url));
+const templatesDir = path.join(thisDir, "templates");
 /** Clear the diff report directory if it exists. */
 async function clearDiffReport(reportDir) {
 	if (fs.existsSync(reportDir)) await fs.promises.rm(reportDir, { recursive: true });
@@ -25,7 +31,7 @@ async function generateDiffReport(failures, config) {
 	const outputPath = path.join(reportDir, "index.html");
 	await fs.promises.writeFile(outputPath, html, "utf-8");
 	if (failures.length > 0 && !liveReload) console.log(`\n Image diff report: ${outputPath}`);
-	if (autoOpen === "never" || autoOpen === "failures" && failures.length === 0) return;
+	if (!(autoOpen === "always" || autoOpen === "failures" && failures.length > 0)) return;
 	try {
 		exec(`${{
 			darwin: "open",
@@ -82,7 +88,7 @@ function createReportHTML(failures, liveReload) {
 		timestamp: escapeHtml(timestamp),
 		script
 	});
-	const rows = failures.map((failure) => createRowHTML(failure)).join("\n");
+	const rows = failures.map(createRowHTML).join("\n");
 	return renderTemplate(loadTemplate("report-failure.hbs"), {
 		totalFailures: String(totalFailures),
 		testPlural: totalFailures === 1 ? "test" : "tests",
@@ -133,11 +139,6 @@ function diffCellHTML(diffPath) {
 }
 //#endregion
 //#region src/ImageSnapshotReporter.ts
-const autoOpenValues = [
-	"always",
-	"failures",
-	"never"
-];
 /** Vitest reporter that generates HTML diff reports for image snapshot failures */
 var ImageSnapshotReporter = class {
 	failuresByFile = /* @__PURE__ */ new Map();
@@ -171,7 +172,7 @@ var ImageSnapshotReporter = class {
 	startServer() {
 		const reportDir = this.resolveReportDir();
 		const server = http.createServer((req, res) => {
-			const url = req.url === "/" ? "/index.html" : req.url || "/index.html";
+			const url = !req.url || req.url === "/" ? "/index.html" : req.url;
 			const filePath = path.join(reportDir, url);
 			fs.stat(filePath, (statErr, stats) => {
 				if (statErr) {
@@ -180,7 +181,12 @@ var ImageSnapshotReporter = class {
 					return;
 				}
 				const ext = path.extname(filePath);
-				const contentType = ext === ".html" ? "text/html" : ext === ".css" ? "text/css" : ext === ".png" ? "image/png" : "application/octet-stream";
+				const contentType = {
+					".html": "text/html",
+					".css": "text/css",
+					".png": "image/png",
+					".js": "text/javascript"
+				}[ext] ?? "application/octet-stream";
 				const headers = {
 					"Content-Type": contentType,
 					"Last-Modified": stats.mtime.toUTCString()
@@ -213,11 +219,10 @@ var ImageSnapshotReporter = class {
 	onTestCaseResult(testCase) {
 		const result = testCase.result();
 		if (result?.state !== "failed") return;
-		const meta = testCase.meta();
-		if (!meta.imageSnapshotFailure) return;
-		const error = result.errors?.[0];
-		const failure = captureFailure(testCase, meta.imageSnapshotFailure, error?.message || "");
-		const moduleId = testCase.module.moduleId;
+		const { imageSnapshotFailure } = testCase.meta();
+		if (!imageSnapshotFailure) return;
+		const failure = captureFailure(testCase, imageSnapshotFailure, result.errors?.[0]?.message || "");
+		const { moduleId } = testCase.module;
 		const existing = this.failuresByFile.get(moduleId) || [];
 		this.failuresByFile.set(moduleId, [...existing, failure]);
 	}
@@ -235,16 +240,18 @@ var ImageSnapshotReporter = class {
 		return path.isAbsolute(this.reportPath) ? this.reportPath : path.join(configRoot, this.reportPath);
 	}
 };
+/** Build a failure record from test metadata for the diff report. */
 function captureFailure(testCase, data, message) {
 	const snapshotName = data.actualPath.match(/([^/]+)\.png$/)?.[1] || "unknown";
+	const { mismatchedPixels, mismatchedPixelRatio } = data;
 	return {
 		testName: testCase.fullName || testCase.name,
 		snapshotName,
 		comparison: {
 			pass: false,
 			message,
-			mismatchedPixels: data.mismatchedPixels,
-			mismatchedPixelRatio: data.mismatchedPixelRatio
+			mismatchedPixels,
+			mismatchedPixelRatio
 		},
 		paths: {
 			reference: data.expectedPath,
@@ -254,4 +261,4 @@ function captureFailure(testCase, data, message) {
 	};
 }
 //#endregion
-export { clearDiffReport as n, generateDiffReport as r, ImageSnapshotReporter as t };
+export { generateDiffReport as i, autoOpenValues as n, clearDiffReport as r, ImageSnapshotReporter as t };

package/dist/ImageSnapshotReporter-D6HJydo6.d.ts

@@ -0,0 +1,91 @@
+import { Reporter, TestCase, TestSpecification, Vitest } from "vitest/node";
+
+//#region src/ImageComparison.d.ts
+/** nodejs compatible interface to DOM ImageData */
+interface ImageData {
+  readonly data: Uint8ClampedArray;
+  readonly width: number;
+  readonly height: number;
+  readonly colorSpace: "srgb" | "display-p3";
+}
+/** Options controlling image comparison thresholds and behavior. */
+interface ComparisonOptions {
+  /** Color difference threshold (0-1). Default: 0.1 */
+  threshold?: number;
+  /** Max ratio of pixels allowed to differ (0-1). Default: 0 */
+  allowedPixelRatio?: number;
+  /** Max absolute number of pixels allowed to differ. Default: 0 */
+  allowedPixels?: number;
+  /** If true, disables detecting and ignoring anti-aliased pixels. Default: true */
+  includeAA?: boolean;
+}
+interface ComparisonResult {
+  pass: boolean;
+  diffBuffer?: Buffer;
+  message: string;
+  mismatchedPixels: number;
+  mismatchedPixelRatio: number;
+}
+declare function compareImages(reference: ImageData | Buffer, actual: ImageData | Buffer, options?: ComparisonOptions): Promise<ComparisonResult>;
+//#endregion
+//#region src/DiffReport.d.ts
+declare const autoOpenValues: readonly ["always", "failures", "never"];
+type AutoOpen = (typeof autoOpenValues)[number];
+/** Failed image snapshot with comparison results and file paths. */
+interface ImageSnapshotFailure {
+  testName: string;
+  snapshotName: string;
+  comparison: ComparisonResult;
+  paths: {
+    reference: string;
+    actual: string;
+    diff: string;
+  };
+}
+/** Configuration for HTML diff report generation. */
+interface DiffReportConfig {
+  /** Auto-open report in browser. Default: "failures" or "never" in CI */
+  autoOpen: AutoOpen;
+  /** Directory path for generated HTML report (absolute or relative). */
+  reportDir: string;
+  /** Vitest config root for calculating relative paths when copying images */
+  configRoot: string;
+  /** Enable live reload script in HTML. Default: false */
+  liveReload?: boolean;
+}
+/** Clear the diff report directory if it exists. */
+declare function clearDiffReport(reportDir: string): Promise<void>;
+/** Generate HTML diff report for image snapshot results. */
+declare function generateDiffReport(failures: ImageSnapshotFailure[], config: DiffReportConfig): Promise<void>;
+//#endregion
+//#region src/ImageSnapshotReporter.d.ts
+interface ImageSnapshotReporterOptions {
+  /** Auto-open report in browser. Default: "failures" or "never" in CI */
+  autoOpen?: AutoOpen;
+  /** Report directory (relative to config.root or absolute) */
+  reportPath?: string;
+  /** Port for live-reload server. Set to 0 to disable. Default: 4343 */
+  port?: number;
+}
+/** Vitest reporter that generates HTML diff reports for image snapshot failures */
+declare class ImageSnapshotReporter implements Reporter {
+  private failuresByFile;
+  private vitest;
+  private reportPath?;
+  private autoOpen;
+  private port;
+  private serverStarted;
+  constructor(options?: ImageSnapshotReporterOptions);
+  /** Resolve autoOpen setting with priority: CI override > env var > config option > default */
+  private resolveAutoOpen;
+  /** Parse and validate IMAGE_DIFF_AUTO_OPEN environment variable */
+  private envAutoOpen;
+  onInit(vitest: Vitest): void;
+  private startServer;
+  onTestRunStart(specifications: ReadonlyArray<TestSpecification>): void;
+  onTestCaseResult(testCase: TestCase): void;
+  onTestRunEnd(): Promise<void>;
+  private resolveReportDir;
+}
+//#endregion
+export { ImageSnapshotFailure as a, generateDiffReport as c, ImageData as d, compareImages as f, DiffReportConfig as i, ComparisonOptions as l, ImageSnapshotReporterOptions as n, autoOpenValues as o, AutoOpen as r, clearDiffReport as s, ImageSnapshotReporter as t, ComparisonResult as u };

package/dist/index.d.ts

@@ -1,61 +1,5 @@
-import { n as ImageSnapshotReporter, r as ImageSnapshotReporterOptions, t as AutoOpen } from "./ImageSnapshotReporter-D3jHkOX3.js";
+import { a as ImageSnapshotFailure, c as generateDiffReport, d as ImageData, f as compareImages, i as DiffReportConfig, l as ComparisonOptions, n as ImageSnapshotReporterOptions, o as autoOpenValues, r as AutoOpen, s as clearDiffReport, t as ImageSnapshotReporter, u as ComparisonResult } from "./ImageSnapshotReporter-D6HJydo6.js";
 
-//#region src/ImageComparison.d.ts
-/** nodejs compatible interface to DOM ImageData */
-interface ImageData {
-  readonly data: Uint8ClampedArray;
-  readonly width: number;
-  readonly height: number;
-  readonly colorSpace: "srgb" | "display-p3";
-}
-/** Options controlling image comparison thresholds and behavior. */
-interface ComparisonOptions {
-  /** Color difference threshold (0-1). Default: 0.1 */
-  threshold?: number;
-  /** Max ratio of pixels allowed to differ (0-1). Default: 0 */
-  allowedPixelRatio?: number;
-  /** Max absolute number of pixels allowed to differ. Default: 0 */
-  allowedPixels?: number;
-  /** If true, disables detecting and ignoring anti-aliased pixels. Default: true */
-  includeAA?: boolean;
-}
-interface ComparisonResult {
-  pass: boolean;
-  diffBuffer?: Buffer;
-  message: string;
-  mismatchedPixels: number;
-  mismatchedPixelRatio: number;
-}
-declare function compareImages(reference: ImageData | Buffer, actual: ImageData | Buffer, options?: ComparisonOptions): Promise<ComparisonResult>;
-//#endregion
-//#region src/DiffReport.d.ts
-/** Failed image snapshot with comparison results and file paths. */
-interface ImageSnapshotFailure {
-  testName: string;
-  snapshotName: string;
-  comparison: ComparisonResult;
-  paths: {
-    reference: string;
-    actual: string;
-    diff: string;
-  };
-}
-/** Configuration for HTML diff report generation. */
-interface DiffReportConfig {
-  /** Auto-open report in browser. Default: "failures" or "never" in CI */
-  autoOpen: AutoOpen;
-  /** Directory path for generated HTML report (absolute or relative). */
-  reportDir: string;
-  /** Vitest config root for calculating relative paths when copying images */
-  configRoot: string;
-  /** Enable live reload script in HTML. Default: false */
-  liveReload?: boolean;
-}
-/** Clear the diff report directory if it exists. */
-declare function clearDiffReport(reportDir: string): Promise<void>;
-/** Generate HTML diff report for image snapshot results. */
-declare function generateDiffReport(failures: ImageSnapshotFailure[], config: DiffReportConfig): Promise<void>;
-//#endregion
 //#region src/ImageSnapshotMatcher.d.ts
 interface MatchImageOptions extends ComparisonOptions {
   name?: string;
@@ -101,4 +45,4 @@ declare module "vitest" {
   }
 }
 //#endregion
-export { AutoOpen, ComparisonOptions, ComparisonResult, DiffReportConfig, ImageData, ImageSnapshotFailure, ImageSnapshotManager, ImageSnapshotReporter, ImageSnapshotReporterOptions, MatchImageOptions, SnapshotConfig, clearDiffReport, compareImages, generateDiffReport, imageMatcher, pngBuffer };
+export { AutoOpen, ComparisonOptions, ComparisonResult, DiffReportConfig, ImageData, ImageSnapshotFailure, ImageSnapshotManager, ImageSnapshotReporter, ImageSnapshotReporterOptions, MatchImageOptions, SnapshotConfig, autoOpenValues, clearDiffReport, compareImages, generateDiffReport, imageMatcher, pngBuffer };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as clearDiffReport, r as generateDiffReport, t as ImageSnapshotReporter } from "./ImageSnapshotReporter-D7WPlzM3.js";
+import { i as generateDiffReport, n as autoOpenValues, r as clearDiffReport, t as ImageSnapshotReporter } from "./ImageSnapshotReporter-B3evIi81.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import pixelmatch from "pixelmatch";
@@ -72,6 +72,8 @@ function pngBuffer(imageData) {
 }
 //#endregion
 //#region src/SnapshotManager.ts
+const replaceableChars = /[<>:"/\\|?*]/g;
+const unreplaceableChars = /\p{Control}+/gu;
 /** Manage reference/actual/diff snapshot files. */
 var ImageSnapshotManager = class {
 	config;
@@ -87,13 +89,13 @@ var ImageSnapshotManager = class {
 		};
 	}
 	referencePath(snapshotName) {
-		return path.join(this.testDir, this.config.snapshotDir, `${snapshotName}.png`);
+		return path.join(this.testDir, this.config.snapshotDir, `${sanitizeName(snapshotName)}.png`);
 	}
 	actualPath(snapshotName) {
-		return path.join(this.testDir, this.config.actualDir, `${snapshotName}.png`);
+		return path.join(this.testDir, this.config.actualDir, `${sanitizeName(snapshotName)}.png`);
 	}
 	diffPath(snapshotName) {
-		return path.join(this.testDir, this.config.diffDir, `${snapshotName}.png`);
+		return path.join(this.testDir, this.config.diffDir, `${sanitizeName(snapshotName)}.png`);
 	}
 	/** Update failing snapshots (only in "all" mode with vitest -u) */
 	shouldUpdate() {
@@ -123,6 +125,10 @@ var ImageSnapshotManager = class {
 		await fs.promises.writeFile(filepath, buffer);
 	}
 };
+/** Replace chars that are invalid in Windows filenames. */
+function sanitizeName(input) {
+	return input.replace(replaceableChars, "_").replace(unreplaceableChars, "").trim();
+}
 //#endregion
 //#region src/ImageSnapshotMatcher.ts
 /** Register toMatchImage() matcher with Vitest */
@@ -193,4 +199,4 @@ async function missingSnapshot(manager, actualBuffer, snapshotName) {
 	};
 }
 //#endregion
-export { ImageSnapshotManager, ImageSnapshotReporter, clearDiffReport, compareImages, generateDiffReport, imageMatcher, pngBuffer };
+export { ImageSnapshotManager, ImageSnapshotReporter, autoOpenValues, clearDiffReport, compareImages, generateDiffReport, imageMatcher, pngBuffer };

package/dist/reporter.d.ts

@@ -1,2 +1,2 @@
-import { n as ImageSnapshotReporter } from "./ImageSnapshotReporter-D3jHkOX3.js";
+import { t as ImageSnapshotReporter } from "./ImageSnapshotReporter-D6HJydo6.js";
 export { ImageSnapshotReporter as default };

package/dist/reporter.js

@@ -1,4 +1,4 @@
-import { t as ImageSnapshotReporter } from "./ImageSnapshotReporter-D7WPlzM3.js";
+import { t as ImageSnapshotReporter } from "./ImageSnapshotReporter-B3evIi81.js";
 //#region src/reporter.ts
 var reporter_default = ImageSnapshotReporter;
 //#endregion

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "vitest-image-snapshot",
-  "version": "0.6.49",
+  "version": "0.6.51",
   "type": "module",
   "files": [
     "dist",
     "src"
   ],
-  "repository": "github:wgsl-tooling-wg/wesl-js",
+  "repository": "github:webgpu-tools/wesl-js",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
     "./reporter": {
       "types": "./dist/reporter.d.ts",
       "import": "./dist/reporter.js"

package/src/DiffReport.ts

@@ -3,12 +3,12 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ComparisonResult } from "./ImageComparison.ts";
-import type { AutoOpen } from "./ImageSnapshotReporter.ts";
 
-const templatesDir = path.join(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "templates",
-);
+export const autoOpenValues = ["always", "failures", "never"] as const;
+export type AutoOpen = (typeof autoOpenValues)[number];
+
+const thisDir = path.dirname(fileURLToPath(import.meta.url));
+const templatesDir = path.join(thisDir, "templates");
 
 /** Failed image snapshot with comparison results and file paths. */
 export interface ImageSnapshotFailure {
@@ -64,11 +64,11 @@ export async function generateDiffReport(
     );
   }
 
-  const withCopiedImages =
+  const copied =
     failures.length > 0
       ? await copyImagesToReport(failures, reportDir, configRoot)
       : [];
-  const html = createReportHTML(withCopiedImages, liveReload);
+  const html = createReportHTML(copied, liveReload);
   const outputPath = path.join(reportDir, "index.html");
 
   await fs.promises.writeFile(outputPath, html, "utf-8");
@@ -78,14 +78,10 @@ export async function generateDiffReport(
     console.log(`\n Image diff report: ${outputPath}`);
   }
 
-  if (
-    autoOpen === "never" ||
-    (autoOpen === "failures" && failures.length === 0)
-  ) {
-    return;
-  }
+  const shouldOpen =
+    autoOpen === "always" || (autoOpen === "failures" && failures.length > 0);
+  if (!shouldOpen) return;
 
-  // open the browser to view the report
   try {
     const commands: Record<string, string> = { darwin: "open", win32: "start" };
     const cmd = commands[process.platform] ?? "xdg-open";
@@ -145,7 +141,6 @@ function renderTemplate(
     result = result.replaceAll(`{{${key}}}`, value);
   }
 
-  // Check for any unreplaced placeholders
   const unreplaced = result.match(/\{\{(\w+)\}\}/g);
   if (unreplaced) {
     const keys = unreplaced.map(m => m.slice(2, -2)).join(", ");
@@ -170,7 +165,7 @@ function createReportHTML(
     });
   }
 
-  const rows = failures.map(failure => createRowHTML(failure)).join("\n");
+  const rows = failures.map(createRowHTML).join("\n");
 
   return renderTemplate(loadTemplate("report-failure.hbs"), {
     totalFailures: String(totalFailures),

package/src/ImageSnapshotReporter.ts

@@ -8,10 +8,12 @@ import type {
   TestSpecification,
   Vitest,
 } from "vitest/node";
-import { generateDiffReport, type ImageSnapshotFailure } from "./DiffReport.ts";
-
-const autoOpenValues = ["always", "failures", "never"] as const;
-export type AutoOpen = (typeof autoOpenValues)[number];
+import {
+  type AutoOpen,
+  autoOpenValues,
+  generateDiffReport,
+  type ImageSnapshotFailure,
+} from "./DiffReport.ts";
 
 /** Metadata captured when image snapshot test fails, used to generate HTML report. */
 interface ImageSnapshotFailureData {
@@ -78,7 +80,7 @@ export class ImageSnapshotReporter implements Reporter {
   private startServer() {
     const reportDir = this.resolveReportDir();
     const server = http.createServer((req, res) => {
-      const url = req.url === "/" ? "/index.html" : req.url || "/index.html";
+      const url = !req.url || req.url === "/" ? "/index.html" : req.url;
       const filePath = path.join(reportDir, url);
 
       fs.stat(filePath, (statErr, stats) => {
@@ -89,14 +91,13 @@ export class ImageSnapshotReporter implements Reporter {
         }
 
         const ext = path.extname(filePath);
-        const contentType =
-          ext === ".html"
-            ? "text/html"
-            : ext === ".css"
-              ? "text/css"
-              : ext === ".png"
-                ? "image/png"
-                : "application/octet-stream";
+        const mimeTypes: Record<string, string> = {
+          ".html": "text/html",
+          ".css": "text/css",
+          ".png": "image/png",
+          ".js": "text/javascript",
+        };
+        const contentType = mimeTypes[ext] ?? "application/octet-stream";
         const headers = {
           "Content-Type": contentType,
           "Last-Modified": stats.mtime.toUTCString(),
@@ -140,18 +141,13 @@ export class ImageSnapshotReporter implements Reporter {
     const result = testCase.result();
     if (result?.state !== "failed") return;
 
-    const meta = testCase.meta() as {
-      imageSnapshotFailure?: ImageSnapshotFailureData;
-    };
-    if (!meta.imageSnapshotFailure) return;
-
-    const error = result.errors?.[0];
-    const failure = captureFailure(
-      testCase,
-      meta.imageSnapshotFailure,
-      error?.message || "",
-    );
-    const moduleId = testCase.module.moduleId;
+    type Meta = { imageSnapshotFailure?: ImageSnapshotFailureData };
+    const { imageSnapshotFailure } = testCase.meta() as Meta;
+    if (!imageSnapshotFailure) return;
+
+    const message = result.errors?.[0]?.message || "";
+    const failure = captureFailure(testCase, imageSnapshotFailure, message);
+    const { moduleId } = testCase.module;
     const existing = this.failuresByFile.get(moduleId) || [];
     this.failuresByFile.set(moduleId, [...existing, failure]);
   }
@@ -177,21 +173,22 @@ export class ImageSnapshotReporter implements Reporter {
   }
 }
 
+/** Build a failure record from test metadata for the diff report. */
 function captureFailure(
   testCase: TestCase,
   data: ImageSnapshotFailureData,
   message: string,
 ): ImageSnapshotFailure {
   const snapshotName = data.actualPath.match(/([^/]+)\.png$/)?.[1] || "unknown";
-
+  const { mismatchedPixels, mismatchedPixelRatio } = data;
   return {
     testName: testCase.fullName || testCase.name,
     snapshotName,
     comparison: {
       pass: false,
       message,
-      mismatchedPixels: data.mismatchedPixels,
-      mismatchedPixelRatio: data.mismatchedPixelRatio,
+      mismatchedPixels,
+      mismatchedPixelRatio,
     },
     paths: {
       reference: data.expectedPath,

package/src/SnapshotManager.ts

@@ -1,6 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+const replaceableChars = /[<>:"/\\|?*]/g;
+const unreplaceableChars = /\p{Control}+/gu;
+
 export interface SnapshotConfig {
   snapshotDir?: string;
   diffDir?: string;
@@ -29,7 +32,7 @@ export class ImageSnapshotManager {
     return path.join(
       this.testDir,
       this.config.snapshotDir,
-      `${snapshotName}.png`,
+      `${sanitizeName(snapshotName)}.png`,
     );
   }
 
@@ -37,12 +40,16 @@ export class ImageSnapshotManager {
     return path.join(
       this.testDir,
       this.config.actualDir,
-      `${snapshotName}.png`,
+      `${sanitizeName(snapshotName)}.png`,
     );
   }
 
   diffPath(snapshotName: string): string {
-    return path.join(this.testDir, this.config.diffDir, `${snapshotName}.png`);
+    return path.join(
+      this.testDir,
+      this.config.diffDir,
+      `${sanitizeName(snapshotName)}.png`,
+    );
   }
 
   /** Update failing snapshots (only in "all" mode with vitest -u) */
@@ -88,3 +95,11 @@ export class ImageSnapshotManager {
     await fs.promises.writeFile(filepath, buffer);
   }
 }
+
+/** Replace chars that are invalid in Windows filenames. */
+function sanitizeName(input: string): string {
+  return input
+    .replace(replaceableChars, "_")
+    .replace(unreplaceableChars, "")
+    .trim();
+}

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export * from "../DiffReport.ts";
+export * from "../ImageComparison.ts";
+export * from "../PNGUtil.ts";
+export * from "../SnapshotManager.ts";

package/src/test/SnapshotManager.test.ts

@@ -17,6 +17,30 @@ test("generates correct file paths", () => {
   );
 });
 
+test("sanitizes invalid filename characters", () => {
+  const manager = new ImageSnapshotManager(path.join("/path/to/test.ts"));
+  const snap = (name: string) => manager.referencePath(name);
+  const snapDir = path.join("/path/to", "__image_snapshots__");
+
+  // filesystem-invalid chars replaced with underscores
+  expect(snap("Category > test")).toBe(
+    path.join(snapDir, "Category _ test.png"),
+  );
+  expect(snap('a<>:"/\\|?*b')).toBe(path.join(snapDir, "a_________b.png"));
+
+  // control chars removed, outer whitespace trimmed
+  expect(snap("word1\x02word2")).toBe(path.join(snapDir, "word1word2.png"));
+  expect(snap(" spaced ")).toBe(path.join(snapDir, "spaced.png"));
+
+  // sanitization applied to all path types
+  expect(manager.actualPath("a > b")).toBe(
+    path.join("/path/to", "__image_actual__", "a _ b.png"),
+  );
+  expect(manager.diffPath("a > b")).toBe(
+    path.join("/path/to", "__image_diffs__", "a _ b.png"),
+  );
+});
+
 test("supports custom directory names", () => {
   const testPath = path.join("/path/to/test.ts");
   const manager = new ImageSnapshotManager(testPath, {

package/dist/ImageSnapshotReporter-D3jHkOX3.d.ts

@@ -1,35 +0,0 @@
-import { Reporter, TestCase, TestSpecification, Vitest } from "vitest/node";
-
-//#region src/ImageSnapshotReporter.d.ts
-declare const autoOpenValues: readonly ["always", "failures", "never"];
-type AutoOpen = (typeof autoOpenValues)[number];
-interface ImageSnapshotReporterOptions {
-  /** Auto-open report in browser. Default: "failures" or "never" in CI */
-  autoOpen?: AutoOpen;
-  /** Report directory (relative to config.root or absolute) */
-  reportPath?: string;
-  /** Port for live-reload server. Set to 0 to disable. Default: 4343 */
-  port?: number;
-}
-/** Vitest reporter that generates HTML diff reports for image snapshot failures */
-declare class ImageSnapshotReporter implements Reporter {
-  private failuresByFile;
-  private vitest;
-  private reportPath?;
-  private autoOpen;
-  private port;
-  private serverStarted;
-  constructor(options?: ImageSnapshotReporterOptions);
-  /** Resolve autoOpen setting with priority: CI override > env var > config option > default */
-  private resolveAutoOpen;
-  /** Parse and validate IMAGE_DIFF_AUTO_OPEN environment variable */
-  private envAutoOpen;
-  onInit(vitest: Vitest): void;
-  private startServer;
-  onTestRunStart(specifications: ReadonlyArray<TestSpecification>): void;
-  onTestCaseResult(testCase: TestCase): void;
-  onTestRunEnd(): Promise<void>;
-  private resolveReportDir;
-}
-//#endregion
-export { ImageSnapshotReporter as n, ImageSnapshotReporterOptions as r, AutoOpen as t };