vitest-plugin-vis 4.2.2 → 5.1.0

package/dist/shared/types.d.mts

@@ -79,6 +79,15 @@ type ToMatchImageSnapshotOptions<M extends ComparisonMethod = 'pixel'> = ImageSn
    * If it passes, it will throw an error with details.
    */
   expectToFail?: boolean | undefined;
+  /**
+   * Create a baseline image when none exists on disk.
+   *
+   * If `true`, the captured image is written to the baseline path and the assertion succeeds,
+   * without Vitest `-u` / `updateSnapshot: 'all'`.
+   *
+   * @default false
+   */
+  createMissingBaseline?: boolean | undefined;
 };
 interface PageImageSnapshotOptions {
   fullPage?: boolean | undefined;
@@ -120,9 +129,20 @@ type ImageSnapshotComparisonInfo = {
    */
   diff?: string | undefined;
 } & ImageSnapshotTimeoutOptions & FailureThresholdOptions & (SsimComparisonOptions | PixelComparisonOptions);
-type MatchImageSnapshotOptions = ImageSnapshotTimeoutOptions & ImageSnapshotCompareOptions<any> & ImageSnapshotKeyOptions;
+type MatchImageSnapshotOptions = ImageSnapshotTimeoutOptions & ImageSnapshotCompareOptions<any> & ImageSnapshotKeyOptions & {
+  /**
+   * When `true`, write a missing baseline on first run (see {@link ToMatchImageSnapshotOptions} `createMissingBaseline`).
+   */
+  createMissingBaseline?: boolean | undefined;
+};
 type SetupVisOptions<GM extends Record<string, any> | unknown = unknown> = {
   auto?: boolean | (<C extends ComparisonMethod, M extends Record<string, any> | unknown = unknown>(options: SnapshotMeta<C> & M & GM) => Promise<boolean> | Promise<void> | boolean | void) | Record<string, boolean | (<C extends ComparisonMethod, M extends Record<string, any> | unknown = unknown>(options: SnapshotMeta<C> & M & GM) => Promise<boolean> | Promise<void> | boolean | void)>;
+  /**
+   * Default {@link ToMatchImageSnapshotOptions#createMissingBaseline} for auto snapshots.
+   *
+   * @default false
+   */
+  createMissingBaseline?: boolean | undefined;
 };
 //#endregion
 export { Awaitable, ComparisonMethod, FailureThresholdOptions, ImageSnapshotCompareOptions, ImageSnapshotComparisonInfo, ImageSnapshotKeyOptions, ImageSnapshotSubjectOptions, ImageSnapshotTimeoutOptions, MatchImageSnapshotOptions, PageImageSnapshotOptions, PixelComparisonOptions, PixelDiffOptions, SetupVisOptions, SnapshotTestMeta, SsimComparisonOptions, type SsimDiffOptions, ToMatchImageSnapshotOptions, ToMatchPageImageSnapshotOptions };

package/dist/shared/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/shared/types.ts"],"sourcesContent":[],"mappings":";;;;;;KAKY,eAAe,IAAI,YAAY;UAE1B,2BAAA;EAFL;;;;;EAEK,OAAA,CAAA,EAAA,MAAA,GAAA,SAAA;AASjB;AAOY,UAPK,uBAAA,CAOW;EAEhB;AA6BZ;;EAKuB,WAAA,CAAA,EAAA,MAAA,GAAA,SAAA;;AAAD,KApCV,gBAAA,GAoCU,OAAA,GAAA,MAAA;AAKV,KAvCA,uBAAA,GAuCsB;EAQtB;AAEZ;;;;EACG,oBAAA,CAAA,EAAA,OAAA,GAAA,SAAA,GAAA,SAAA;EACuB;;;;AAG1B;AASA;;;;;;;AAUA;AAIA;;;;;;EAGY,gBAAA,CAAA,EAAgB,MAAA,GAAA,SAAA;CAEJ;AAAb,KArDC,qBAqDD,CAAA,IAAA,MAAA,CAAA,GAAA;EAAR,gBAAA,EApDgB,CAoDhB;EAAI;AAIP;;EA+BC,WAAA,CAAA,EAnFc,OAmFd,CAnFsB,eAmFtB,CAAA,GAAA,SAAA;CACC;AAA8C,KA/EpC,sBA+EoC,CAAA,IAAA,OAAA,CAAA,GAAA;EAEpC,gBAAA,CAAA,EAhFQ,CAgFR,GAAA,SAAyB;EAAG;;;EAEhB,WAAA,CAAA,EA9ET,gBA8ES,GAAA,SAAA;AAExB,CAAA;AAAuC,KA7E3B,gBAAA,GAAmB,UA6EQ,CAAA,OA7EU,UA6EV,CAAA,CAAA,CAAA,CAAA;AAGvB,KA9EJ,2BA8EI,CAAA,UA9EkC,gBA8ElC,GAAA,OAAA,CAAA,GAAA,CA9EiE,CA8EjE,SAAA,MAAA,GA7Eb,qBA6Ea,CA7ES,CA6ET,CAAA,GA5Eb,sBA4Ea,CA5EU,CA4EV,CAAA,CAAA,GA3Ef,uBA2Ee;AAA4B,KAzEhC,2BAAA,GAyEgC;EAClB;;;;;;EAKR,OAAA,CAAA,EAAA,MAAA,GAAA,SAAA;CAA4B;AAClB,KAvEhB,2BAuEgB,CAAA,UAvEsB,gBAuEtB,GAAA,OAAA,CAAA,GAvEoD,2BAuEpD,GAtE3B,uBAsE2B,GArE3B,2BAqE2B,CArEC,CAqED,CAAA,GAAA;EAAb;;;;EACe,YAAA,CAAA,EAAA,OAAA,GAAA,SAAA;CAL1B;AAAM,UAzDO,wBAAA,CAyDP;;;KArDE,0CAA0C,8BAA8B,4BAA4B,KAC/G;KAEW,gBAAA;;KAET,IAAA,IAAQ,aAAa;;;KAIZ,2BAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA8BR,8BACH,2BACC,wBAAwB;KAEd,yBAAA,GAA4B,8BACvC,mCACA;KAEW,2BAA2B;+BAGvB,4BAA4B,kDAC/B,aAAa,KAAK,IAAI,OAC1B,mBAAmB,kCACxB,qCAGc,4BAA4B,kDAC/B,aAAa,KAAK,IAAI,OAC1B,mBAAmB"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/shared/types.ts"],"sourcesContent":[],"mappings":";;;;;;KAKY,eAAe,IAAI,YAAY;UAE1B,2BAAA;EAFL;;;;;EAEK,OAAA,CAAA,EAAA,MAAA,GAAA,SAAA;AASjB;AAOY,UAPK,uBAAA,CAOW;EAEhB;AA6BZ;;EAKuB,WAAA,CAAA,EAAA,MAAA,GAAA,SAAA;;AAAD,KApCV,gBAAA,GAoCU,OAAA,GAAA,MAAA;AAKV,KAvCA,uBAAA,GAuCsB;EAQtB;AAEZ;;;;EACG,oBAAA,CAAA,EAAA,OAAA,GAAA,SAAA,GAAA,SAAA;EACuB;;;;AAG1B;AASA;;;;;;;AAmBA;AAIA;;;;;;EAGY,gBAAA,CAAA,EAAgB,MAAA,GAAA,SAAA;CAEJ;AAAb,KA9DC,qBA8DD,CAAA,IAAA,MAAA,CAAA,GAAA;EAAR,gBAAA,EA7DgB,CA6DhB;EAAI;AAIP;;EA+BC,WAAA,CAAA,EA5Fc,OA4Fd,CA5FsB,eA4FtB,CAAA,GAAA,SAAA;CACC;AAA8C,KAxFpC,sBAwFoC,CAAA,IAAA,OAAA,CAAA,GAAA;EAEpC,gBAAA,CAAA,EAzFQ,CAyFR,GAAA,SAAyB;EAAG;;;EAEhB,WAAA,CAAA,EAvFT,gBAuFS,GAAA,SAAA;AAOxB,CAAA;AAAuC,KA3F3B,gBAAA,GAAmB,UA2FQ,CAAA,OA3FU,UA2FV,CAAA,CAAA,CAAA,CAAA;AAGvB,KA5FJ,2BA4FI,CAAA,UA5FkC,gBA4FlC,GAAA,OAAA,CAAA,GAAA,CA5FiE,CA4FjE,SAAA,MAAA,GA3Fb,qBA2Fa,CA3FS,CA2FT,CAAA,GA1Fb,sBA0Fa,CA1FU,CA0FV,CAAA,CAAA,GAzFf,uBAyFe;AAA4B,KAvFhC,2BAAA,GAuFgC;EAClB;;;;;;EAKR,OAAA,CAAA,EAAA,MAAA,GAAA,SAAA;CAA4B;AAClB,KArFhB,2BAqFgB,CAAA,UArFsB,gBAqFtB,GAAA,OAAA,CAAA,GArFoD,2BAqFpD,GApF3B,uBAoF2B,GAnF3B,2BAmF2B,CAnFC,CAmFD,CAAA,GAAA;EAAb;;;;EACe,YAAA,CAAA,EAAA,OAAA,GAAA,SAAA;EAL1B;;;;;;;;;;UA9Da,wBAAA;;;KAIL,0CAA0C,8BAA8B,4BAA4B,KAC/G;KAEW,gBAAA;;KAET,IAAA,IAAQ,aAAa;;;KAIZ,2BAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA8BR,8BACH,2BACC,wBAAwB;KAEd,yBAAA,GAA4B,8BACvC,mCACA;;;;;;KAOW,2BAA2B;+BAGvB,4BAA4B,kDAC/B,aAAa,KAAK,IAAI,OAC1B,mBAAmB,kCACxB,qCAGc,4BAA4B,kDAC/B,aAAa,KAAK,IAAI,OAC1B,mBAAmB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-plugin-vis",
-  "version": "4.2.2",
+  "version": "5.1.0",
   "description": "Vitest visual testing plugin",
   "keywords": [
     "image-snapshot",
@@ -21,50 +21,23 @@
   "type": "module",
   "imports": {
     "#vitest-plugin-vis": "./src/index.ts",
-    "#vitest-plugin-vis/client-api": "./src/client-api.ts",
-    "#vitest-plugin-vis/config": "./src/config.ts",
-    "#vitest-plugin-vis/setup": "./src/setup.ts"
+    "#vitest-plugin-vis/client-api": "./src/exports/client-api.ts",
+    "#vitest-plugin-vis/config": "./src/exports/config.ts",
+    "#vitest-plugin-vis/setup": "./src/exports/setup.ts",
+    "#vitest-plugin-vis/setup-api": "./src/exports/setup-api.ts",
+    "#vitest-plugin-vis/testing": "./src/exports/testing.ts",
+    "#vitest-plugin-vis/testing/node": "./src/exports/testing/node.ts"
   },
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
     },
-    "./config": {
-      "types": "./dist/config.d.mts",
-      "default": "./dist/config.mjs"
-    },
-    "./client-api": {
-      "types": "./dist/client-api.d.mts",
-      "default": "./dist/client-api.mjs"
-    },
-    "./presets/auto": {
-      "types": "./dist/presets/auto.d.mts",
-      "default": "./dist/presets/auto.mjs"
-    },
-    "./presets/enable": {
-      "types": "./dist/presets/enable.d.mts",
-      "default": "./dist/presets/enable.mjs"
-    },
-    "./presets/manual": {
-      "types": "./dist/presets/manual.d.mts",
-      "default": "./dist/presets/manual.mjs"
-    },
-    "./server-utils": {
-      "types": "./dist/server-utils.d.mts",
-      "default": "./dist/server-utils.mjs"
-    },
-    "./setup": {
-      "types": "./dist/setup.d.mts",
-      "default": "./dist/setup.mjs"
-    },
-    "./setup-api": {
-      "types": "./dist/setup-api.d.mts",
-      "default": "./dist/setup-api.mjs"
-    },
-    "./testing": {
-      "types": "./dist/testing.d.mts",
-      "default": "./dist/testing.mjs"
+    "./*": {
+      "source": "./src/exports/*.ts",
+      "types": "./dist/exports/*.d.mts",
+      "default": "./dist/exports/*.mjs"
     },
     "./package.json": "./package.json"
   },
@@ -97,13 +70,13 @@
     "@types/is-ci": "^3.0.4",
     "@types/pngjs": "^6.0.5",
     "@types/react": "^19.2.2",
-    "@vitest/browser": "^4.0.16",
-    "@vitest/browser-playwright": "^4.0.16",
-    "@vitest/browser-webdriverio": "^4.0.16",
-    "@vitest/coverage-istanbul": "^4.0.16",
-    "@vitest/coverage-v8": "^4.0.16",
-    "@vitest/expect": "^4.0.16",
-    "@vitest/ui": "^4.0.16",
+    "@vitest/browser": "^4.1.4",
+    "@vitest/browser-playwright": "^4.1.4",
+    "@vitest/browser-webdriverio": "^4.1.4",
+    "@vitest/coverage-istanbul": "^4.1.4",
+    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/expect": "^4.1.4",
+    "@vitest/ui": "^4.1.4",
     "cross-env": "^10.0.0",
     "never-fail": "^1.1.4",
     "npm-run-all2": "^8.0.0",
@@ -113,9 +86,9 @@
     "storybook-addon-tag-badges": "^3.1.0",
     "tailwindcss": "^4.1.14",
     "tsdown": "^0.19.0",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.0",
-    "vitest": "^4.0.16",
+    "typescript": "^6.0.0",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.4",
     "vitest-browser-react": "^2.0.2"
   },
   "peerDependencies": {

package/readme.md

@@ -79,7 +79,7 @@ import { vis } from 'vitest-plugin-vis/config'
 export default defineConfig({
 	plugins: [
 		vis({
-			preset: 'auto' // or 'manual' or 'none'
+			preset: 'auto' // or 'manual' or 'custom'
 		})
 	],
 })
@@ -87,14 +87,14 @@ export default defineConfig({
 
 - `auto` (default): Automatically take a snapshot at the end of each rendering test.
 - `manual`: You control which test(s) should take a snapshot automatically with the `setAutoSnapshotOptions()` function.
-- `none`: Without preset. Set up your visual testing strategy in `vitest.setup.ts`.
+- `custom`: No preset setup file from the plugin. Set up your visual testing strategy in `vitest.setup.ts`.
 
 When using the `auto` or `manual` preset,
 manual snapshots are enabled. You can take manual snapshot using the `expect().toMatchImageSnapshot()` matcher,
 or the `page.toMatchImageSnapshot()` for full page snapshot.
 
 If you want to customize the snapshot behavior,
-you can set the `preset` to `none` and configure your own snapshot strategy in `vitest.setup.ts`:
+you can set the `preset` to `custom` and configure your own snapshot strategy in `vitest.setup.ts`:
 
 ```ts
 // vitest.config.ts
@@ -103,7 +103,7 @@ import { vis } from 'vitest-plugin-vis/config'
 
 export default defineConfig({
 	plugins: [
-		vis({ preset: 'none' })
+		vis({ preset: 'custom' })
 	],
 	test: {
 		browser: {/* ... */},
@@ -261,6 +261,10 @@ export default defineConfig({
 })
 ```
 
+#### `shortenLongSnapshotPaths` (long absolute paths)
+
+Defaults to `false`. When `true`, the plugin keeps legacy snapshot files as `taskId-key.png` and only adjusts the **`snapshotSubpath` segment** when needed: it builds **absolute** paths under `__baselines__` (after `snapshotRootDir` and your `snapshotSubpath`) plus representative snapshot filenames; if those would exceed typical Windows limits (length at least **250**, below classic `MAX_PATH` **260** with margin, or a path component longer than **255**), **directory segments stay as-is** and only the **final path component** (the file name derived from your test/story path) is shortened to `{firstToken}-{hash12}{ext}` — the first token is the substring before the first `.` in the basename (similar in spirit to [tersify](https://github.com/unional/tersify) terse labels). The same resolved subpath is used for **baselines**, **results**, and **diffs**. Your `snapshotRootDir` is not rewritten.
+
 #### Multiple browser instances
 
 When using multiple browser instances (e.g., different viewports or browsers),
@@ -451,6 +455,8 @@ setAutoSnapshotOptions({
 })
 ```
 
+`createMissingBaseline` (on the matcher or on `vis.setup`) writes a missing baseline on the first run without `-u`. For auto snapshots, `vis.setup({ createMissingBaseline: true, auto: true })` applies a default; a test can override with `setAutoSnapshotOptions({ createMissingBaseline: false })` or equivalent meta.
+
 You can also enable/disable auto snapshot by passing boolean:
 
 ```ts

package/src/auto_snapshots/_extract_auto_snapshot_options.ts

@@ -1,4 +1,4 @@
-import { NAME } from '../client-api.ts'
+import { NAME } from '../exports/client-api.ts'
 import type { MetaTask } from './auto_snapshot_options.ts'
 import type { SnapshotMeta } from './snapshot_meta.ts'
 

package/src/client/expect/to_match_image_snapshot.mdx

@@ -72,6 +72,26 @@ it('should use custom snapshot key', async ({ expect }) => {
 })
 ```
 
+#### `createMissingBaseline`
+
+When `true`, if there is **no baseline image yet**,
+the matcher writes the captured image to the baseline path and the assertion succeeds—without using Vitest's `-u` / `updateSnapshot` mode.
+If a baseline already exists, `createMissingBaseline` does not change comparison behavior.
+
+You can also set a default for **auto** snapshots with `vis.setup({ createMissingBaseline: true, auto: ... })`.
+Per-test options from `setAutoSnapshotOptions` / test meta override that default when they set `createMissingBaseline` explicitly.
+
+```ts
+it('creates baseline on first run with createMissingBaseline', async ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).toMatchImageSnapshot({
+		snapshotKey: 'first_run',
+		createMissingBaseline: true
+	})
+})
+```
+
 ### Failure Threshold
 
 #### `failureThreshold` and `failureThresholdType`
@@ -258,7 +278,10 @@ it('should demonstrate all options', async ({ expect }) => {
 		timeout: 45000,
 
 		// Testing utility
-		expectToFail: false
+		expectToFail: false,
+
+		// First-run baseline (optional)
+		createMissingBaseline: false
 	})
 })
 ```

package/src/client/external/vitest/vitest_browser_context_proxy.ts

@@ -1,5 +1,5 @@
 import type { SerializedConfig } from 'vitest'
-import type { BrowserCommands, Platform } from 'vitest/browser'
+import type { BrowserCommands } from 'vitest/browser'
 
 let ctx: Awaited<typeof import('vitest/browser')>
 
@@ -14,7 +14,7 @@ export const server = new Proxy<{
 	 * Platform the Vitest server is running on.
 	 * The same as calling `process.platform` on the server.
 	 */
-	platform: Platform
+	platform: string
 	/**
 	 * Runtime version of the Vitest server.
 	 * The same as calling `process.version` on the server.

package/src/client/external/vitest/vitest_suite_proxy.ts

@@ -1,14 +1,14 @@
 import type { SnapshotTestMeta } from '../../../shared/types.ts'
 
-let vitestSuite: Awaited<typeof import('vitest/suite')>
+let vitest: Awaited<typeof import('vitest')>
 
 if ((globalThis as any).__vitest_browser__) {
-	import('vitest/suite').then((m) => {
-		vitestSuite = m
+	import('vitest').then((m) => {
+		vitest = m
 	})
 }
 
-export type CurrentTest = ReturnType<typeof vitestSuite.getCurrentTest> & SnapshotTestMeta
+export type CurrentTest = ReturnType<typeof vitest.TestRunner.getCurrentTest> & SnapshotTestMeta
 
-export const getCurrentTest = () => vitestSuite?.getCurrentTest() as CurrentTest
-export const getCurrentSuite = () => vitestSuite?.getCurrentSuite()
+export const getCurrentTest = () => vitest?.TestRunner.getCurrentTest() as CurrentTest
+export const getCurrentSuite = () => vitest?.TestRunner.getCurrentSuite()

package/src/client/page/_ctx.ts

@@ -1,10 +1,10 @@
-import { type BrowserPage, commands } from 'vitest/browser'
+import { commands, type BrowserCommands, type BrowserPage } from 'vitest/browser'
 import { getCurrentTest } from '../external/vitest/vitest_suite_proxy.ts'
 
 export type { BrowserPage }
 
 export const ctx = {
-	commands,
+	commands: commands as BrowserCommands,
 	getCurrentTest,
 	__test__reset() {
 		ctx.getCurrentTest = getCurrentTest

package/src/client/page/to_match_image_snapshot.mdx

@@ -68,6 +68,25 @@ it('should use custom snapshot key', async () => {
 })
 ```
 
+#### `createMissingBaseline`
+
+When `true`, if there is **no baseline image yet**,
+the matcher writes the captured image to the baseline path and the assertion succeeds—without using Vitest's `-u` / `updateSnapshot` mode.
+If a baseline already exists, `createMissingBaseline` does not change comparison behavior.
+
+Defaults for **auto** snapshots can come from `vis.setup({ createMissingBaseline: true, auto: ... })`; per-test meta can override with an explicit `createMissingBaseline` value.
+
+```ts
+it('creates page baseline on first run with createMissingBaseline', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		snapshotKey: 'page_first_run',
+		createMissingBaseline: true
+	})
+})
+```
+
 ### Failure Threshold
 
 #### `failureThreshold` and `failureThresholdType`
@@ -256,7 +275,10 @@ it('should demonstrate all page snapshot options', async () => {
 		timeout: 45000,
 
 		// Testing utility
-		expectToFail: false
+		expectToFail: false,
+
+		// First-run baseline (optional)
+		createMissingBaseline: false
 	})
 })
 ```

package/src/client/snapshot/compare_image_snapshot.logic.ts

@@ -8,6 +8,7 @@ export function prettifyOptions(options: ToMatchImageSnapshotOptions<any> | unde
 		options.timeout ? `timeout: ${options.timeout} ms` : '',
 		`comparisonMethod: ${options.comparisonMethod ?? 'pixel'}`,
 		options.diffOptions ? `diffOptions: ${JSON.stringify(options.diffOptions)}` : '',
+		options.createMissingBaseline ? 'createMissingBaseline: true' : '',
 	]
 		.filter(Boolean)
 		.join('\n                ')

package/src/client/snapshot/compare_image_snapshot.ts

@@ -23,7 +23,7 @@ export async function compareImageSnapshot(
 	const resultImage = await toImageData(info.result)
 
 	if (!info.baseline) {
-		if (server.config.snapshotOptions.updateSnapshot === 'all') {
+		if (server.config.snapshotOptions.updateSnapshot === 'all' || options?.createMissingBaseline === true) {
 			await writeSnapshot(commands, resolve(info.projectRoot, info.baselinePath), resultImage)
 			return
 		}
@@ -45,7 +45,7 @@ export async function compareImageSnapshot(
 		diffImage.data,
 		width,
 		height,
-		options,
+		options as ToMatchImageSnapshotOptions<any>,
 	)
 	if (pass) {
 		if (options?.expectToFail) {

package/src/client/suite/auto_snapshot_matcher.ts

@@ -2,7 +2,7 @@ import dedent from 'dedent'
 import { extractAutoSnapshotOptions } from '../../auto_snapshots/_extract_auto_snapshot_options.ts'
 import type { SnapshotMeta } from '../../auto_snapshots/snapshot_meta.ts'
 import type { SetupVisSuiteCommand } from '../../shared/commands.types.ts'
-import type { ComparisonMethod } from '../../shared/types.ts'
+import type { ComparisonMethod, SetupVisOptions } from '../../shared/types.ts'
 import { shouldTakeSnapshot } from '../snapshot/should_take_snapshot.ts'
 import { toTaskId } from '../task/task_id.ts'
 import { ctx } from './_ctx.ts'
@@ -22,6 +22,7 @@ export function autoSnapshotMatcher<GM extends Record<string, any> | unknown = u
 				string,
 				boolean | ((options: SnapshotMeta<C> & M & GM) => Promise<boolean> | Promise<void> | boolean | void)
 			>,
+			suiteDefaults?: Pick<SetupVisOptions<GM>, 'createMissingBaseline'> | undefined,
 		) {
 			return async function matchImageSnapshot() {
 				const test = ctx.getCurrentTest()
@@ -35,9 +36,16 @@ export function autoSnapshotMatcher<GM extends Record<string, any> | unknown = u
 						const theme = themes[themeId]
 						const r = typeof theme === 'function' ? await theme(meta! as any) : theme
 						if (r === false) continue
+						const effectiveCreateMissingBaseline =
+							meta != null && Object.hasOwn(meta as object, 'createMissingBaseline')
+								? (meta as { createMissingBaseline?: boolean }).createMissingBaseline
+								: suiteDefaults?.createMissingBaseline
 						await expect(getSubject(meta?.subject ?? subject)).toMatchImageSnapshot({
 							...meta,
 							snapshotKey: meta?.snapshotKey ?? themeId,
+							...(effectiveCreateMissingBaseline !== undefined
+								? { createMissingBaseline: effectiveCreateMissingBaseline }
+								: {}),
 						})
 					} catch (error) {
 						errors.push([themeId, error as Error])

package/src/config/types.ts

@@ -35,10 +35,8 @@ export type VisOptions<M extends ComparisonMethod = 'pixel'> = (M extends 'ssim'
 		 * Loads the `test.setupFiles` of the specified preset.
 		 *
 		 * @default 'auto'
-		 * @deprecated 'enable' is deprecated. Use `manual` for the same effect.
-		 * @deprecated 'none' is deprecated. Use `custom` for the same effect.
 		 */
-		preset?: 'enable' | 'manual' | 'auto' | 'custom' | 'none' | undefined
+		preset?: 'manual' | 'auto' | 'custom' | undefined
 		/**
 		 * The snapshot folder relative to the root of the project.
 		 *
@@ -74,4 +72,18 @@ export type VisOptions<M extends ComparisonMethod = 'pixel'> = (M extends 'ssim'
 		 * @returns The customized snapshot subpath.
 		 */
 		snapshotSubpath?: ((options: { subpath: string }) => string) | undefined
+		/**
+		 * When `true`, shortenspaths that would exceed Windows-safe limits (full path length at
+		 * least 250, below classic `MAX_PATH` 260, or a final path component longer than 255):
+		 * - After `snapshotRootDir` and `snapshotSubpath`, if the path
+		 *   would exceed that budget, the **final** subpath segment is shortened to
+		 *   `{firstToken}-{hash12}{ext}` (tersify-style).
+		 * - When writing a baseline, if the **actual** absolute path for the legacy `taskId-key.png` file would
+		 *   exceed the budget, only the final segment of that relative path is shortened the same way (nested
+		 *   `describe` directories from `taskId` stay as-is so `taskId-*.png` globs still work).
+		 * `snapshotRootDir` itself is not rewritten.
+		 *
+		 * @default false
+		 */
+		shortenLongSnapshotPaths?: boolean | undefined
 	}

package/src/config/vis.ts

@@ -23,7 +23,7 @@ export function vis<M extends ComparisonMethod = 'pixel'>(options: VisOptions<M>
 						name: undefined,
 						commands: commands as any,
 					},
-					setupFiles: preset && preset !== 'none' && preset !== 'custom' ? [`vitest-plugin-vis/presets/${preset}`] : [],
+					setupFiles: preset && preset !== 'custom' ? [`vitest-plugin-vis/presets/${preset}`] : [],
 				},
 			}
 		},

package/src/exports/client-api.ts

@@ -0,0 +1,13 @@
+import '../server/commands/augment.ts'
+
+export * from '../auto_snapshots/auto_snapshot_options.ts'
+export * from '../client/actions/has_image_snapshot_action.ts'
+export * from '../client/actions/load_image_snapshot_results_action.ts'
+export * from '../client/actions/match_image_snapshot_action.ts'
+export * from '../client/actions/match_page_image_snapshot_action.ts'
+export * from '../client/expect/expectation_result.ts'
+export type * from '../client/expect/to_match_image_snapshot.types.ts'
+export * from '../client/suite/auto_snapshot_matcher.ts'
+export * from '../client/task/task_id.ts'
+export * from '../shared/constants.ts'
+export type * from '../shared/types.ts'

package/src/exports/config.ts

@@ -0,0 +1,3 @@
+export type * from '../config/types.ts'
+export * from '../config/vis.ts'
+export * from '../shared/trim_common_folder.ts'

package/src/exports/presets/auto.ts

@@ -0,0 +1,3 @@
+import { vis } from '../setup.ts'
+
+vis.setup({ auto: true })

package/src/exports/presets/manual.ts

@@ -0,0 +1,3 @@
+import { vis } from '../setup.ts'
+
+vis.setup({ auto: false })

package/src/exports/server-utils.ts

@@ -0,0 +1,7 @@
+export { getSnapshotRootDir } from '../server/snapshot_path.ts'
+export {
+	resolveLegacySnapshotFileRelativePath,
+	resolveSnapshotSubpathWithinLimits,
+} from '../server/snapshot_path_limits.ts'
+export { BASELINE_DIR, DIFF_DIR, SNAPSHOT_ROOT_DIR } from '../shared/constants.ts'
+export { trimCommonFolder } from '../shared/trim_common_folder.ts'

package/src/exports/setup-api.ts

@@ -0,0 +1,5 @@
+// `vitest-plugin-vis/setup` provides code needed in `vitest.setup.ts`.
+import '../client/expect/extend.ts'
+import '../client/page/extend.ts'
+
+export * from '../setup/create_vis.ts'

package/src/exports/setup.ts

@@ -0,0 +1,3 @@
+import './setup-api.ts'
+
+export * from '../setup/vis.ts'

package/src/exports/testing/node.ts

@@ -0,0 +1,4 @@
+/** Node / Vitest project tests only — not safe for browser Vitest. */
+export { stubSuite } from '../../server/testing/stubSuite.ts'
+export { getVisOption } from '../../server/vis_options.ts'
+export * from '../../testing/constants.ts'

package/src/exports/testing.ts

@@ -0,0 +1 @@
+export * from '../testing/constants.ts'

package/src/server/commands/prepare_image_snapshot_comparison.ts

@@ -28,7 +28,7 @@ export const prepareImageSnapshotComparison: ExtendedBrowserCommand<
 			...info,
 			projectRoot,
 			result: subject,
-		}
+		} as ImageSnapshotComparisonInfo
 	}
 
 	const resultBuffer = await takeSnapshot(context, projectRoot, info.resultPath, subject, options)
@@ -37,5 +37,5 @@ export const prepareImageSnapshotComparison: ExtendedBrowserCommand<
 		projectRoot,
 		baseline: baselineBuffer?.toString('base64'),
 		result: resultBuffer.toString('base64'),
-	}
+	} as ImageSnapshotComparisonInfo
 }

package/src/server/commands/prepare_page_image_snapshot_comparison.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'pathe'
 import type { PreparePageImageSnapshotComparisonCommand } from '../../shared/commands.types.ts'
+import type { ImageSnapshotComparisonInfo } from '../../shared/types.ts'
 import { file } from '../externals/file.ts'
 import { getProjectRoot } from '../project.ts'
 import { takePageSnapshot } from '../snapshot.ts'
@@ -24,5 +25,5 @@ export const preparePageImageSnapshotComparison: ExtendedBrowserCommand<
 		projectRoot,
 		baseline: baselineBuffer?.toString('base64'),
 		result: resultBuffer.toString('base64'),
-	}
+	} as ImageSnapshotComparisonInfo
 }