@jterrazz/test 16.1.1 → 17.0.0

package/dist/vitest.js

@@ -1,232 +1,55 @@
-import { i as GROUND_EXPECTED } from "./fixtures.js";
-import { i as SCREENSHOTS_DIR, n as COVERAGE_DIR, o as VITEST_ARTIFACTS_DIR, r as REPORTER_OUTPUT_FILES, t as ATTACHMENTS_DIR } from "./artifacts.js";
-import { n as specDescription } from "./literate.js";
+import { a as callerFrames, r as writeInPlace } from "./shared-in-place.js";
+import { t as isRecord } from "./shared-json-shape.js";
+import { n as refusal$1, t as invariant } from "./shared-refusal.js";
+import { i as renderText, n as literate, o as resolveSpecPath } from "./shared-literate-plugin.js";
+import { u as shouldUpdateSnapshots } from "./shared-ledger.js";
+import { i as COVERAGE_DIR, l as VITEST_ARTIFACTS_DIR, n as ATTACHMENTS_DIR, o as REPORTER_OUTPUT_FILES, r as BLOB_DIR, s as SCREENSHOTS_DIR, t as ARTIFACTS_DIR } from "./shared-artifacts.js";
+import { t as derivedProjects } from "./shared-derived-projects.js";
+import { t as TEST_SECTION } from "./shared-test-section.js";
+import { r as servicesSetup } from "./shared-services.global-setup.js";
+import { r as tempRootSetup } from "./shared-temp-root.global-setup.js";
+import { inPlaceSetup } from "./in-place.global-setup.js";
+import { t as routeCoverageSetup } from "./shared-route-coverage.global-setup.js";
+import { mobileSessionSetup } from "./mobile-session.global-setup.js";
 import { createRequire } from "node:module";
+import { GROUND_GLOB, readSettings } from "@jterrazz/typescript/rules";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { configDefaults, mergeConfig } from "vitest/config";
-//#region src/runner/literate-plugin.ts
-/**
-* The `literate()` vite plugin — door one of the spec-document format.
-*
-* It makes a `<case>.spec.yaml` file a TEST FILE: the glob joins the project's
-* test include, and each document is transformed into a one-test module that
-* runs the file through the registered `cli` runner. The runner shows the
-* document's path as the file and its `description:` as the title, so a failing
-* scenario is opened where it is written — not in a `.test.ts` that merely
-* points at it.
-*
-* ```typescript
-* // vitest.config.ts
-* import { defineConfig } from 'vitest/config';
-* import { literate } from '@jterrazz/test/vitest';
-*
-* export default defineConfig({
-*     plugins: [literate({ specification: './specs/cli/cli.specification.ts' })],
-* });
-* ```
-*/
-/** The `.spec.yaml` extension, matched on the id vite hands the plugin. */
-const SPEC_FILE = /\.spec\.yaml(?:\?.*)?$/u;
-/**
-* The module a `<case>.spec.yaml` becomes: one `test()` whose title is the
-* document's `description:` and whose body runs the whole file — its ground,
-* its servers, every run asserted.
-*
-* @internal Exported for unit tests.
-*/
-function literateModule(content, filePath, specificationPath) {
-	const title = specDescription(content, filePath);
-	return [
-		"import { test } from 'vitest';",
-		`import { cli } from ${JSON.stringify(specificationPath)};`,
-		"",
-		`test(${JSON.stringify(title)}, async () => {`,
-		`    await cli.run(${JSON.stringify(filePath)});`,
-		"});",
-		""
-	].join("\n");
-}
-/** Strip vite's query suffix (`?v=…`) from a module id. */
-function cleanId(id) {
-	return id.split("?")[0] ?? id;
-}
-function literate(options) {
-	const include = options.include ?? ["**/*.spec.yaml"];
-	let root = process.cwd();
-	return {
-		config: () => ({ test: { include } }),
-		configResolved: (resolved) => {
-			root = resolved.root;
-		},
-		enforce: "pre",
-		load: (id) => {
-			if (!SPEC_FILE.test(id)) return null;
-			const filePath = cleanId(id);
-			const specificationPath = isAbsolute(options.specification) ? options.specification : resolve(root, options.specification);
-			return literateModule(readFileSync(filePath, "utf8"), filePath, specificationPath);
-		},
-		name: "jterrazz-test:literate"
-	};
-}
-//#endregion
-//#region src/runner/preset.ts
-/**
-* `defineSpecConfig()` — the shared vitest config every repository of the
-* ecosystem starts from.
-*
-* Fourteen hand-rolled `vitest.config.ts` files had converged on the same
-* handful of settings and disagreed on the rest by accident; the preset is
-* their common ground, stated once. A consumer writes ONE call and keeps
-* everything vitest offers: what it passes is a plain vite/vitest config,
-* merged OVER the defaults, so any of them is overridable in place.
-*
-* ```typescript
-* // vitest.config.ts
-* import { defineSpecConfig } from '@jterrazz/test/vitest';
-*
-* export default defineSpecConfig({
-*     literate: { specification: './specs/cli/cli.specification.ts' },
-*     test: {
-*         projects: [
-*             { test: { include: ['src/**\/*.test.ts'], name: 'unit' } },
-*             { test: { include: ['specs/api/**\/*.test.ts'], name: 'api' } },
-*         ],
-*     },
-* });
-* ```
-*/
-/**
-* A run's budget. Vitest's own 5s test / 10s hook defaults were raised by every
-* repository that starts real infrastructure, and none of them meant 5s — a
-* container boot, a `prisma db push` or a `next build` all outlive it. 30s is
-* the value the ecosystem's configs already converged on; a suite that needs
-* more (a simulator cold boot, a real image build) states its own per project.
-*/
+//#region src/vitest/project.ts
 const TEST_TIMEOUT_MS = 3e4;
 const HOOK_TIMEOUT_MS = 3e4;
-/**
-* What a spec STANDS ON is never itself a test: `_fixtures/` holds inputs —
-* deliberately-wrong twins, fixture projects a spec lints — and collecting them
-* runs a repository's own counter-examples as if they were its suite. Every
-* config that ever hit it added the same line by hand.
-*
-* Merged, not replaced: vite concatenates arrays, so a consumer's `exclude`
-* ADDS to this list and never has to spread `configDefaults.exclude` again.
-*/
-const EXCLUDE = [...configDefaults.exclude, "**/_fixtures/**"];
-/**
-* What a test may never carry into the next one, and the one policy the
-* framework states rather than lints.
-*
-* `retry: 0` is the policy: a flaky test is fixed or deleted, never re-rolled
-* until it passes. A retry turns a real defect into a slow one and hides the
-* day it becomes permanent.
-*
-* The three restores are the other half of the same idea. `vi.spyOn`,
-* `vi.stubGlobal` and `vi.stubEnv` each own a teardown, and a test that forgets
-* one leaks into whatever runs next — a failure that appears in a FILE that did
-* nothing wrong and disappears when that file is run alone. Turning them on
-* here is what lets `clock.at()` and `vi.stubEnv()` be written without an
-* `afterEach`, which is the shape rule J6w asks for.
-*/
+/** Ground folders hold inputs and deliberately-wrong twins, never tests, and `.artifacts/` copies of the project (a mutation sandbox); vite concatenates, so a consumer's `exclude` adds to this. */
+const EXCLUDE = [
+	...configDefaults.exclude,
+	`${ARTIFACTS_DIR}/**`,
+	GROUND_GLOB
+];
 const HYGIENE = {
 	restoreMocks: true,
 	retry: 0,
 	unstubEnvs: true,
 	unstubGlobals: true
 };
-/**
-* Defaults a vitest PROJECT accepts. `coverage` and `reporters` are root-only
-* options (vitest omits them from a project's config), so they are absent here
-* on purpose — setting them would be silently dropped.
-*
-* Exported for the project helpers, which build their canonical project ON
-* these rather than beside them: a helper's project must carry the same
-* budgets and the same artefact directory as a hand-written one.
-*
-* @internal
-*/
+/** `coverage` and `reporters` are root-only: vitest drops them from a project. */
 function projectDefaults() {
 	return {
 		cacheDir: VITEST_ARTIFACTS_DIR,
 		test: {
 			attachmentsDir: ATTACHMENTS_DIR,
 			exclude: EXCLUDE,
+			globalSetup: [inPlaceSetup(), tempRootSetup()],
 			hookTimeout: HOOK_TIMEOUT_MS,
 			...HYGIENE,
 			testTimeout: TEST_TIMEOUT_MS
 		}
 	};
 }
-/**
-* Coverage, when `--coverage` asks for it.
-*
-* `v8` because it is the runtime's own counter: no instrumentation pass, no
-* second transform of every file, and the numbers do not move when the bundler
-* does. The provider is an OPTIONAL peer (`@vitest/coverage-v8`), so a project
-* that never asks for coverage never installs it.
-*
-* `json-summary` is not a taste: it is the machine-readable report the ratchet
-* reads. `text` is for the human running the command, and `html` for the one
-* chasing a line. All three land under `.artifacts/vitest/coverage/`, the one
-* directory the toolchain's page owns.
-*
-* What is EXCLUDED is the shape of the answer, not a way to raise the number:
-* a type-only module has nothing to execute (v8 reports it as 0/0 or, worse,
-* as uncovered lines that cannot be covered), and the CLI entries are proven
-* by running the binary, not by importing it.
-*/
-const COVERAGE = {
-	exclude: [
-		"**/node_modules/**",
-		"specs/**",
-		"**/_fixtures/**",
-		"**/*.d.ts",
-		"**/*.test-d.ts",
-		"**/*.fixtures.ts",
-		"dist/**",
-		".artifacts/**",
-		"**/*.config.ts",
-		"**/*.config.mts"
-	],
-	provider: "v8",
-	reporter: [
-		"text",
-		"html",
-		"json-summary"
-	],
-	reportsDirectory: COVERAGE_DIR
-};
-/** Defaults for the root config — the project ones, plus what only a root carries. */
-function rootDefaults() {
-	return {
-		cacheDir: VITEST_ARTIFACTS_DIR,
-		test: {
-			attachmentsDir: ATTACHMENTS_DIR,
-			coverage: COVERAGE,
-			exclude: EXCLUDE,
-			hookTimeout: HOOK_TIMEOUT_MS,
-			...HYGIENE,
-			outputFile: REPORTER_OUTPUT_FILES,
-			testTimeout: TEST_TIMEOUT_MS
-		}
-	};
-}
-/** A glob list with its repeats taken out, or nothing where there is no list. */
 function eachOnce(globs) {
 	return globs === void 0 ? void 0 : [...new Set(globs)];
 }
-/**
-* The glob lists vite CONCATENATES rather than overrides, each glob kept once.
-*
-* A project built ON the defaults and then merged INTO them by
-* `defineSpecConfig` carried every default twice. Glob matching is idempotent,
-* so nothing collected differently — but the no-tests banner is the one place a
-* consumer ever reads that list, and it read as three merges of the same three
-* globs.
-*/
+/** Vite concatenates these lists: each glob is kept once. */
 function statedOnce(test) {
 	const exclude = eachOnce(test.exclude);
 	const include = eachOnce(test.include);
@@ -236,11 +59,6 @@ function statedOnce(test) {
 		...include === void 0 ? {} : { include }
 	};
 }
-/**
-* Build a project ON the defaults — the ONE way a project is built here.
-*
-* @internal
-*/
 function onProjectDefaults(stated) {
 	const merged = mergeConfig(projectDefaults(), stated);
 	return merged.test === void 0 ? merged : {
@@ -248,151 +66,139 @@ function onProjectDefaults(stated) {
 		test: statedOnce(merged.test)
 	};
 }
-/**
-* Is every project an inline object — one this preset merged its defaults into?
-* A project named by a glob or handed as a promise carries a config this call
-* never saw, and the root's exclusions are the only ones it gets from here.
-*/
-function allInline(projects) {
-	return projects.every((project) => typeof project === "object" && project !== null && !("then" in project));
-}
-/**
-* The root's exclusions, beside projects that already carry them.
-*
-* With `projects`, the root collects nothing itself: its `exclude` only travels
-* INTO each project, where vitest CONCATENATES it with the project's own — so
-* every preset glob reached the banner twice. The preset's own are dropped
-* here, since each inline project states them in full; what the CONSUMER stated
-* at the root stays, because no project holds a copy of that.
-*/
-function rootExcludeBeside(projects, exclude) {
-	return allInline(projects) ? exclude.filter((glob) => !EXCLUDE.includes(glob)) : exclude;
-}
-/**
-* A project inherits NOTHING from the root `test` block — vitest resolves each
-* project as its own config — so the defaults are merged into every inline one.
-* A project declared as a glob string, a promise or a function is handed back
-* untouched: there is no object to merge into.
-*/
-function withProjectDefaults(project) {
-	if (typeof project !== "object" || project === null || "then" in project) return project;
-	return onProjectDefaults(project);
-}
-function defineSpecConfig(config = {}) {
-	const { literate: literateOptions, ...userConfig } = config;
-	const stated = literateOptions ? mergeConfig({ plugins: [literate(literateOptions)] }, userConfig) : userConfig;
-	const merged = mergeConfig(rootDefaults(), stated);
-	const root = merged.test === void 0 ? void 0 : statedOnce(merged.test);
-	if (root === void 0) return merged;
-	const { projects } = root;
-	if (projects === void 0) return {
-		...merged,
-		test: root
-	};
-	const inline = projects.map(withProjectDefaults);
+/** A stated `include` or `exclude` replaces the canonical one; the group is 0 until a specification states its own. */
+function projectTest(name, options, canonical) {
+	const exclude = options.exclude ?? canonical.exclude;
 	return {
-		...merged,
-		test: {
-			...root,
-			...root.exclude === void 0 ? {} : { exclude: rootExcludeBeside(inline, root.exclude) },
-			projects: inline
+		...exclude === void 0 ? {} : { exclude },
+		include: options.include ?? canonical.include,
+		...options.serial === true ? { fileParallelism: false } : {},
+		name,
+		sequence: { groupOrder: 0 },
+		...options.timeout === void 0 ? {} : {
+			hookTimeout: options.timeout,
+			testTimeout: options.timeout
 		}
 	};
 }
-//#endregion
-//#region src/runner/facet-project.ts
-/** The globs a node facet collects, and the ones a caller stated instead. */
-function facetProject(facet, options) {
-	return onProjectDefaults({ test: {
-		...options.exclude === void 0 ? {} : { exclude: options.exclude },
-		include: options.include ?? [`specs/${facet}/**/*.spec.ts`],
-		...options.serial === true ? { fileParallelism: false } : {},
-		name: facet,
-		sequence: { groupOrder: 0 },
-		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+function specificationProject(specification, options) {
+	return onProjectDefaults({ test: projectTest(specification, options, { include: [`specs/${specification}/**/*.spec.ts`] }) });
+}
+function inProcessProject(specification, options) {
+	const project = specificationProject(specification, options);
+	return options.runner === void 0 ? project : mergeConfig(project, { test: {
+		isolate: false,
+		setupFiles: [options.runner]
 	} });
 }
 //#endregion
-//#region src/facets/api/api.project.ts
-/** `api()` — the app met through HTTP. */
+//#region src/specifications/api/api.project.ts
 function api(options = {}) {
-	return facetProject("api", options);
+	return mergeConfig(inProcessProject("api", options), { test: { globalSetup: [servicesSetup(), routeCoverageSetup()] } });
 }
 //#endregion
-//#region src/facets/cli/cli.project.ts
-/** The literate defaults — the path convention `cli()` assumes when nothing says otherwise. */
-const CLI_SPECIFICATION = "./specs/cli/cli.specification.ts";
-const CLI_DOCUMENTS = ["specs/cli/**/*.spec.yaml"];
-/**
-* A cli project collects the facet's `.test.ts` files AND its documents: a
-* `<case>.spec.yaml` is a test file of its own (docs/07 § the literate door),
-* so the plugin's glob has to join the include of the project that collects
-* them — which is this one, never the root config.
-*/
+//#region src/specifications/cli/cli.project.ts
+/** A cli project: the specification's `.spec.ts` files and its documents (docs/guides/spec-documents.md); the plugin's glob joins this project's include, never the root config. */
 function cli(options = {}) {
-	const { literate: literateOptions, ...common } = options;
-	const project = facetProject("cli", common);
-	if (literateOptions === false) return project;
-	const documents = literateOptions?.include ?? CLI_DOCUMENTS;
+	const { literate: door, ...common } = options;
+	const project = specificationProject("cli", common);
+	if (door === false) return project;
 	return mergeConfig(project, { plugins: [literate({
-		include: documents,
-		specification: literateOptions?.specification ?? CLI_SPECIFICATION
+		include: door?.include ?? ["specs/cli/**/*.spec.yaml"],
+		runner: door?.runner ?? "./specs/cli/cli.specification.ts"
 	})] });
 }
 //#endregion
-//#region src/seams/vitest-browser/commands.ts
-/** Where a golden sits: `_expected/<name>` beside the test that asked for it. */
+//#region src/stubs/delivery/browser-page/worker-script.ts
+/** From this package's own install: `@vitest/browser` resolves it only where the installer hoists, and a consumer declaring `msw` is what `no-redundant-test-dependency` forbids. */
+function mswWorkerScript() {
+	return createRequire(import.meta.url).resolve("msw/mockServiceWorker.js");
+}
+//#endregion
+//#region src/specifications/component/golden/commands.ts
+function testFile(testPath) {
+	if (testPath === void 0) throw invariant("a golden command reached the server with no test path");
+	return testPath;
+}
 function goldenPath(testPath, name) {
-	if (testPath === void 0) throw new Error("golden: the command carries no test path — a golden is read from a test file.");
-	return resolve(dirname(testPath), GROUND_EXPECTED, name);
+	return resolveSpecPath("toMatch", name, dirname(testFile(testPath)));
 }
-/** The ARIA snapshot of the rendered `<body>`, as YAML. */
 const ariaTree = async (context) => {
 	return await (await context.frame()).locator("body").ariaSnapshot();
 };
-/**
-* The ARIA snapshot of ONE node, named by the selector the page's locator
-* carries — the accessible name, as the browser computed it, for a page that
-* cannot compute one itself.
-*/
-const ariaNode = async (context, selector) => {
-	return await (await context.frame()).locator(selector).ariaSnapshot();
-};
-/**
-* A line the page has for whoever is running the suite, written on the node
-* side's stderr — the one channel vitest's default reporter passes through.
-* The console is captured and dropped, so a page that printed to it printed to
-* nobody.
-*/
-const notify = (_context, line) => {
-	process.stderr.write(`${line}\n`);
-};
-/** The golden's current content, or `null` when it does not exist yet. */
 const goldenRead = (context, name) => {
 	const path = goldenPath(context.testPath, name);
 	return existsSync(path) ? readFileSync(path, "utf8") : null;
 };
-/** Write the golden — update mode's half, and the path it wrote, for the message. */
 const goldenWrite = (context, name, content) => {
 	const path = goldenPath(context.testPath, name);
 	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, content, "utf8");
+	writeFileSync(path, content);
 	return path;
 };
-/**
-* The commands, as `component()` registers them — one list, so the names the
-* page calls and the names the project registers cannot drift.
-*/
+const inPlaceWrite = (context, stack, text) => {
+	const file = testFile(context.testPath);
+	const frame = context.project.browser?.parseStacktrace(stack).find((candidate) => candidate.file === file);
+	if (frame === void 0) throw new Error(refusal$1({
+		fix: "call toMatch() from the test file itself, or compare to a golden file: toMatch(file(...))",
+		found: "update mode: no frame of this toMatch call is the test file, so the value in place has nowhere to be written",
+		read: "docs/reference/tokens.md#a-value-written-in-place-is-rewritten-in-the-test",
+		why: "A value written in place is rewritten in the test that states it."
+	}));
+	writeInPlace({
+		column: frame.column,
+		file,
+		line: frame.line
+	}, (indent) => renderText(text, indent), context.project.getProvidedContext().inPlaceRewrites);
+	return `${file}:${frame.line}`;
+};
+/** One list, so the names the page calls and the names the project registers cannot drift. */
 const COMPONENT_COMMANDS = {
-	ariaNode,
 	ariaTree,
 	goldenRead,
 	goldenWrite,
-	notify
+	inPlaceWrite
 };
 //#endregion
-//#region src/facets/component/component.project.ts
-/** The pipeline keys a consumer's Vite config contributes, and nothing else. */
+//#region src/specifications/component/peers/peer-versions.ts
+const requireFrom$1 = createRequire(import.meta.url);
+function versionOf(specifier) {
+	const path = requireFrom$1.resolve(`${specifier}/package.json`);
+	const manifest = JSON.parse(String(readFileSync(path)));
+	if (typeof manifest === "object" && manifest !== null && "version" in manifest) return String(manifest.version);
+	throw new Error(refusal$1({
+		fix: `reinstall ${specifier}: \`npm install ${specifier}\``,
+		found: `the installed ${specifier} manifest carries no version`,
+		read: "docs/start/set-up-a-project.md#what-to-install",
+		why: "The component project reads the version of the peers it configures from their installed manifests."
+	}));
+}
+/** Vite 8 transforms with oxc and warns on every `esbuild` option; Vite 6 and 7 have no `oxc` key. */
+function transformKey() {
+	return Number.parseInt(versionOf("vite").split(".")[0] ?? "", 10) >= 8 ? "oxc" : "esbuild";
+}
+/** `@vitest/browser-playwright` peers vitest on an exact version; a mismatch fails deep in the tester naming neither. */
+function assertProviderPin(runner, provider) {
+	if (provider === null) throw new Error(refusal$1("seam-is-an-optional-peer", {
+		fix: `npm i -D @vitest/browser-playwright@${runner} playwright`,
+		found: "component() requires `@vitest/browser-playwright`, and it is not installed"
+	}));
+	if (runner !== provider) throw new Error(refusal$1({
+		fix: `bump both to the same version in one change: npm i -D vitest@${provider} @vitest/browser-playwright@${provider}`,
+		found: `component(): @vitest/browser-playwright is ${provider}, and vitest is ${runner}`,
+		read: "docs/start/set-up-a-project.md#what-to-install",
+		why: "`@vitest/browser-playwright` peers vitest on an exact version."
+	}));
+}
+function installedVersion(specifier) {
+	try {
+		return versionOf(specifier);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/specifications/component/component.project.ts
 const PIPELINE_KEYS = [
 	"assetsInclude",
 	"css",
@@ -400,44 +206,25 @@ const PIPELINE_KEYS = [
 	"envPrefix",
 	"esbuild",
 	"json",
+	"optimizeDeps",
 	"oxc",
 	"plugins",
 	"resolve"
 ];
-/**
-* The seam's own runtime, pre-bundled so a cold cache never reloads mid-run.
-*
-* `msw` and `msw/browser` are NOT here: `@vitest/browser` already puts both in
-* `optimizeDeps.exclude`, and Vite's esbuild optimizer (6 and 7) treats an
-* entry that is both included and excluded as fatal — dependency optimisation
-* throws before a single test runs.
-*/
-const SEAM_DEPENDENCIES = [
+const PAGE_DEPENDENCIES = [
 	"react",
 	"react-dom/client",
 	"react/jsx-dev-runtime",
 	"react/jsx-runtime",
-	"vitest-browser-react"
+	"vitest-browser-react",
+	"vitest-mock-extended"
 ];
 const requireFrom = createRequire(import.meta.url);
-/** This module's own file — the frames the caller search walks past. */
 const HELPERS_FILE = import.meta.filename;
-/** A stack frame's file, in either of the two shapes V8 prints it in. */
-const STACK_FRAME = /(?:\((?<wrapped>[^()]+):\d+:\d+\)|at (?<bare>[^()\s]+):\d+:\d+)$/u;
-/** A config vite bundled before importing it — `<its name>.timestamp-<hash>.mjs`. */
 const BUNDLED_CONFIG = /^(?<name>.+)\.timestamp-[^.]+\.mjs$/u;
-/** The file of the first frame below this module — who called the helper. */
 function callerFile() {
-	const { stack } = /* @__PURE__ */ new Error("@jterrazz/test: reading the call site of a project helper");
-	for (const frame of stack?.split("\n").slice(1) ?? []) {
-		const groups = STACK_FRAME.exec(frame.trim())?.groups;
-		const location = groups?.wrapped ?? groups?.bare;
-		if (location === void 0 || location.startsWith("node:")) continue;
-		const file = location.startsWith("file:") ? fileURLToPath(location) : location;
-		if (file !== HELPERS_FILE) return file;
-	}
+	return callerFrames().find(({ file }) => file !== HELPERS_FILE)?.file;
 }
-/** The nearest directory at or above the cwd holding a file of this name. */
 function nearestHolding(name) {
 	let directory = process.cwd();
 	for (;;) {
@@ -447,27 +234,6 @@ function nearestHolding(name) {
 		directory = parent;
 	}
 }
-/**
-* The directory of the CONFIG that called a helper — what the relative paths
-* it was handed mean.
-*
-* Not `process.cwd()`: a `vitest.config.ts` is read by more tools than the
-* runner, and knip and `typescript check` load every config of a repository
-* from the repository ROOT — `component({ vite: './web/vite.config.ts' })`
-* written beside an app resolved against the wrong tree and threw before a
-* single test ran. `import.meta` cannot answer either: it describes THIS
-* module. And vitest hands a project neither its root nor its config file — a
-* project function is called with `{ command, mode, isPreview, isSsrBuild }`
-* and nothing else.
-*
-* So the call site is read off the stack, where a loader that keeps a config's
-* identity (node, tsx, jiti — what those tools use) names the file itself.
-* Vite's own loader does not: it BUNDLES the config into
-* `node_modules/.vite-temp/` and only the config's NAME survives the move. The
-* name is what is then looked for upward from the cwd, because that loader is
-* the runner's and a runner is started in the tree it tests. A config loaded
-* by the runner from another tree entirely states `root` itself.
-*/
 function callerDirectory() {
 	const file = callerFile();
 	if (file === void 0) return process.cwd();
@@ -475,7 +241,6 @@ function callerDirectory() {
 	if (bundled === void 0 || basename(dirname(file)) !== ".vite-temp") return dirname(file);
 	return nearestHolding(bundled) ?? process.cwd();
 }
-/** Is this specifier installed here? An absent optional peer is simply not pre-bundled. */
 function resolves(specifier) {
 	try {
 		requireFrom.resolve(specifier);
@@ -484,20 +249,10 @@ function resolves(specifier) {
 		return false;
 	}
 }
-/**
-* Serve msw's worker script from the package's OWN install, at the path the
-* worker asks for, with the scope header a worker registered at `/` needs.
-*
-* `@vitest/browser` resolves `/mockServiceWorker.js` too, but from ITS own
-* directory — and it does not depend on `msw`, so that resolution only lands
-* where the installer hoists. The package that OWNS the dependency is the one
-* that can always find it, and it is this one. Without either, a consumer runs
-* `msw init` and declares `msw`, which F8 forbids.
-*/
 function mswWorkerPlugin() {
 	return {
 		configureServer(server) {
-			const script = requireFrom.resolve("msw/mockServiceWorker.js");
+			const script = mswWorkerScript();
 			server.middlewares.use("/mockServiceWorker.js", (_request, response) => {
 				response.setHeader("content-type", "text/javascript");
 				response.setHeader("service-worker-allowed", "/");
@@ -507,16 +262,7 @@ function mswWorkerPlugin() {
 		name: "@jterrazz/test:msw-worker"
 	};
 }
-/**
-* Keep an app's Vite PIPELINE and drop everything that says where the app
-* lives.
-*
-* An allow-list, not a drop-list: a consumer's config carries keys the
-* framework has never heard of — `environments`, `ssr`, `appType`, `publicDir`
-* — and one of them re-roots the run and the project collects nothing. Naming
-* what the pipeline IS keeps an unknown key from leaking in. The consumer's
-* `plugins` are CONCATENATED after the seam's, never assigned over them.
-*/
+const isPluginList = (plugins) => Array.isArray(plugins);
 async function reroot(source, root) {
 	const environment = {
 		command: "serve",
@@ -524,144 +270,90 @@ async function reroot(source, root) {
 		mode: "test"
 	};
 	let loaded;
-	let from = "the value it was given";
+	let found;
+	let fix;
 	if (typeof source === "string") {
 		const { loadConfigFromFile } = await import("vite");
-		from = isAbsolute(source) ? source : resolve(root, source);
+		const from = isAbsolute(source) ? source : resolve(root, source);
 		loaded = (await loadConfigFromFile(environment, from))?.config;
-	} else if (typeof source === "function") loaded = await source(environment);
-	else loaded = await source;
-	if (loaded === void 0) throw new Error(`component({ vite }): no config at ${from}`);
+		found = `${from} exports no config`;
+		fix = "point `vite` at the app's own vite.config.ts";
+	} else if (typeof source === "function") {
+		loaded = await source(environment);
+		if (typeof loaded === "function") {
+			found = "the config function returned a function, not a config";
+			fix = "call the framework's factory and pass what it returns (for Astro, `getViteConfig({}, { root: import.meta.dirname })`, never `getViteConfig`)";
+		} else {
+			found = "the config function returned no config";
+			fix = "return the framework's config from the function (for Astro, `getViteConfig({}, { root: import.meta.dirname })`)";
+		}
+	} else {
+		loaded = await source;
+		found = "the config promise resolved to no config";
+		fix = "resolve the promise to the framework's config object";
+	}
+	if (typeof loaded !== "object" || loaded === null) throw new Error(refusal$1({
+		fix,
+		found: `component({ vite }): ${found}`,
+		read: "docs/guides/component-specs.md#the-constructor-there-is-none",
+		why: "A component renders through the Vite pipeline the app builds with, read from its config."
+	}));
 	const inactive = transformKey() === "oxc" ? "esbuild" : "oxc";
 	const kept = {};
 	const config = { ...loaded };
-	for (const key of PIPELINE_KEYS) if (config[key] !== void 0 && key !== inactive) kept[key] = config[key];
+	for (const key of PIPELINE_KEYS) if (key !== inactive) kept[key] = config[key];
 	return kept;
 }
-/** What a missing optional peer costs, said once rather than as a resolver stack. */
-const PROVIDER_MISSING = "component(): @vitest/browser-playwright is an optional peer — install it beside the runner it pins (npm i -D @vitest/browser-playwright@<the installed vitest version> playwright).";
-/** The installed version of a package, read from its own manifest. */
-function versionOf(specifier) {
-	const manifest = JSON.parse(readFileSync(requireFrom.resolve(`${specifier}/package.json`), "utf8"));
-	if (typeof manifest === "object" && manifest !== null && "version" in manifest) return String(manifest.version);
-	throw new Error(`component(): ${specifier} is installed without a version.`);
-}
-/**
-* Which of the two transformer keys the INSTALLED Vite actually reads.
-*
-* Vite 8 transforms with oxc and prints a warning for every `esbuild` option it
-* is handed; Vite 6 and 7 transform with esbuild and have no `oxc` key at all.
-* The inactive one is dropped rather than carried as a second, ignored
-* statement — a config that says the same thing twice is a config that will one
-* day say two different things.
-*/
-function transformKey() {
-	return Number.parseInt(versionOf("vite").split(".")[0] ?? "", 10) >= 8 ? "oxc" : "esbuild";
+function optimizeDepsOf(declared) {
+	const own = isRecord(declared) ? { ...declared } : {};
+	const listed = "include" in own && Array.isArray(own.include) ? own.include : [];
+	return {
+		...own,
+		include: [.../* @__PURE__ */ new Set([...PAGE_DEPENDENCIES.filter(resolves), ...listed.filter((entry) => typeof entry === "string")])]
+	};
 }
-/**
-* The JSX default, on the key the running Vite reads, yielding to the
-* consumer's own: a `jsxImportSource` or a classic runtime is the app's
-* statement, not the seam's to overwrite.
-*/
 function jsxPipeline(pipeline) {
 	const key = transformKey();
 	const stated = pipeline[key];
 	if (key === "oxc") return { oxc: stated ?? { jsx: { runtime: "automatic" } } };
 	return { esbuild: stated ?? { jsx: "automatic" } };
 }
-/**
-* `@vitest/browser-playwright` peers vitest on an EXACT version: 4.1.10 wants
-* 4.1.10, not `^4.1`. A mismatch fails deep inside the tester with a message
-* about a missing runner, so the pair is checked where the project is built
-* and both versions are named.
-*/
-function assertProviderPin() {
-	const runner = versionOf("vitest");
-	let provider;
-	try {
-		provider = versionOf("@vitest/browser-playwright");
-	} catch {
-		throw new Error(PROVIDER_MISSING);
-	}
-	if (runner !== provider) throw new Error(`component(): @vitest/browser-playwright@${provider} peers vitest on an exact version, and vitest is ${runner}. Bump both to the same version in one change (npm i -D vitest@${provider} @vitest/browser-playwright@${provider}).`);
-}
-/** The framework's own update flag, read where `process` exists. */
-function updating() {
-	return process.env.TEST_UPDATE === "1" || process.argv.includes("-u") || process.argv.includes("--update");
-}
-/**
-* Hand the project's `wrap` to the page as a STATIC import.
-*
-* The page could fetch the module by URL when the first render needs it, and
-* that is what breaks: a dependency Vite never scanned is discovered mid-run,
-* the optimizer rewrites its cache, and every module the page is holding —
-* the test's own included — 404s behind a stale `?v=` hash. A setup file is in
-* the graph before the first test runs, so the wrap and everything it imports
-* are scanned, pre-bundled, and never re-optimised under the run.
-*
-* It is written into `.artifacts/` rather than served from memory because
-* vitest resolves `setupFiles` as paths on disk; it is generated, so it belongs
-* with everything else a tool generates, and never on the row.
-*
-* The wrapper lands on `globalThis` under a shared symbol rather than an
-* export: the setup module and the package's browser build are separate graphs
-* in the page and share no module instance.
-*/
 function writeSetupFile(wrap, root) {
 	const absolute = resolve(root, wrap);
 	const path = resolve(root, VITEST_ARTIFACTS_DIR, "component-setup.mjs");
 	mkdirSync(dirname(path), { recursive: true });
 	writeFileSync(path, [
-		"// Generated by `component({ wrap })` — @jterrazz/test. Do not edit.",
+		"// Generated by `component({ wrap })` of @jterrazz/test. Do not edit.",
 		`import wrap from ${JSON.stringify(absolute)};`,
 		"globalThis[Symbol.for('@jterrazz/test:component-wrap')] = wrap;",
 		""
 	].join("\n"), "utf8");
 	return path;
 }
-/**
-* What the page cannot read for itself: update mode is a `process.env`/`argv`
-* read, and the project's clock is stated where `process` exists.
-*/
 function providedToPage(options) {
 	return {
 		...options.clock === void 0 ? {} : { componentClock: options.clock },
 		componentViewport: viewportOf(options),
-		update: updating()
+		update: shouldUpdateSnapshots()
 	};
 }
-/** The page size every render of the project starts at. */
 function viewportOf(options) {
 	return options.viewport ?? {
 		height: 720,
 		width: 1280
 	};
 }
-/** The globs a component project collects, and the ones it stays out of. */
-function componentGlobs(options) {
-	return {
-		exclude: options.exclude ?? (options.include === void 0 ? ["specs/**"] : []),
-		include: options.include ?? ["**/*.test.tsx"]
-	};
-}
-/**
-* A component test renders in a real Chromium — the browser the website facet
-* already drives through the same `playwright` peer.
-*
-* The default `include` reaches the whole project, so the default `exclude`
-* keeps it out of `specs/`, where the assembled product is specified. State
-* your own `include` and the exclusion is yours to state too.
-*/
+/** A component project: renders in a real Chromium; the default `exclude` keeps it out of `specs/`. */
 async function component(options = {}) {
 	const root = options.root ?? callerDirectory();
-	assertProviderPin();
+	assertProviderPin(versionOf("vitest"), installedVersion("@vitest/browser-playwright"));
 	const { playwright } = await import("@vitest/browser-playwright");
 	const pipeline = options.vite === void 0 ? {} : await reroot(options.vite, root);
-	const consumerPlugins = Array.isArray(pipeline.plugins) ? pipeline.plugins : [];
+	const consumerPlugins = isPluginList(pipeline.plugins) ? pipeline.plugins : [];
 	return onProjectDefaults({
 		...pipeline,
 		...jsxPipeline(pipeline),
-		optimizeDeps: { include: SEAM_DEPENDENCIES.filter(resolves) },
+		optimizeDeps: optimizeDepsOf(pipeline.optimizeDeps),
 		plugins: [mswWorkerPlugin(), ...consumerPlugins],
 		test: {
 			browser: {
@@ -677,76 +369,232 @@ async function component(options = {}) {
 				screenshotDirectory: SCREENSHOTS_DIR,
 				viewport: viewportOf(options)
 			},
-			...componentGlobs(options),
-			...options.serial === true ? { fileParallelism: false } : {},
-			name: "component",
+			...projectTest("component", options, {
+				exclude: options.include === void 0 ? ["specs/**"] : [],
+				include: ["**/*.test.tsx"]
+			}),
 			provide: providedToPage(options),
 			...options.wrap === void 0 ? {} : { setupFiles: [writeSetupFile(options.wrap, root)] },
-			sequence: { groupOrder: 2 },
-			...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+			sequence: { groupOrder: 2 }
 		}
 	});
 }
 //#endregion
-//#region src/facets/integration/integration.project.ts
-/** `integration()` — a module against real services, or against a golden. */
+//#region src/specifications/integration/integration.project.ts
 function integration(options = {}) {
-	return facetProject("integration", options);
+	return mergeConfig(inProcessProject("integration", options), { test: { globalSetup: [servicesSetup()] } });
+}
+//#endregion
+//#region src/specifications/job/job.project.ts
+function job(options = {}) {
+	return mergeConfig(inProcessProject("job", options), { test: { globalSetup: [servicesSetup()] } });
 }
 //#endregion
-//#region src/facets/jobs/jobs.project.ts
-/** `jobs()` — what a name triggers in-process. */
-function jobs(options = {}) {
-	return facetProject("jobs", options);
+//#region src/specifications/lint/lint.project.ts
+function lint(options = {}) {
+	return specificationProject("lint", options);
 }
 //#endregion
-//#region src/facets/mobile/mobile.project.ts
-/**
-* `mobile()` — the app on a simulator. A simulator is the one thing that
-* cannot share a machine with itself, so it runs last and alone (group 3).
-*/
+//#region src/specifications/mobile/mobile.project.ts
+/** A simulator cannot share a machine with itself: serial. A global setup holds one driver session for the run. */
 function mobile(options = {}) {
-	return mergeConfig(facetProject("mobile", options), { test: { sequence: { groupOrder: 3 } } });
+	const { device, root, ...common } = options;
+	return mergeConfig(specificationProject("mobile", common), { test: {
+		fileParallelism: false,
+		globalSetup: [mobileSessionSetup()],
+		...device === void 0 ? {} : { provide: { mobileAppium: {
+			device,
+			root: root ?? "."
+		} } },
+		sequence: { groupOrder: 3 }
+	} });
 }
 //#endregion
-//#region src/facets/website/website.project.ts
-/**
-* A website spec meets the assembled product through a served page, in the
-* Chromium playwright drives. It opens a browser, so it is scheduled before the
-* component project and never beside it: two Chromiums must not share a slot on
-* a 2-vCPU runner.
-*/
+//#region src/specifications/website/website.project.ts
 function website(options = {}) {
-	return onProjectDefaults({ test: {
-		...options.exclude === void 0 ? {} : { exclude: options.exclude },
-		...options.serial === true ? { fileParallelism: false } : {},
-		include: options.include ?? ["specs/website/**/*.spec.ts"],
-		name: "website",
-		sequence: { groupOrder: 1 },
-		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+	return mergeConfig(specificationProject("website", options), { test: { sequence: { groupOrder: 1 } } });
+}
+//#endregion
+//#region src/vitest/preset.ts
+const COVERAGE = {
+	exclude: [
+		"**/node_modules/**",
+		"specs/**",
+		GROUND_GLOB,
+		"**/*.d.ts",
+		"**/*.test-d.ts",
+		"**/*.fixtures.ts",
+		".artifacts/**",
+		"**/*.config.ts",
+		"**/*.config.mts"
+	],
+	autoAttachSubprocess: true,
+	excludeAfterRemap: true,
+	provider: "v8",
+	reporter: [
+		"text",
+		"html",
+		"json-summary"
+	],
+	reportsDirectory: COVERAGE_DIR
+};
+function shardOf(argv) {
+	for (const [index, argument] of argv.entries()) {
+		if (argument.startsWith("--shard=")) return argument.slice(8);
+		if (argument === "--shard") return argv[index + 1];
+	}
+}
+function reporterOutputFiles(argv) {
+	const shard = shardOf(argv);
+	return shard === void 0 ? REPORTER_OUTPUT_FILES : {
+		...REPORTER_OUTPUT_FILES,
+		blob: `${BLOB_DIR}/blob-${shard.replace("/", "-")}.json`
+	};
+}
+function rootDefaults() {
+	return mergeConfig(projectDefaults(), { test: {
+		coverage: COVERAGE,
+		outputFile: reporterOutputFiles(process.argv)
 	} });
 }
+function isInline(project) {
+	return isRecord(project) && !("then" in project);
+}
+function rootExcludeBeside(projects, exclude) {
+	return projects.every(isInline) ? exclude.filter((glob) => !EXCLUDE.includes(glob)) : exclude;
+}
+function withProjectDefaults(project) {
+	return isInline(project) ? onProjectDefaults(project) : project;
+}
+function presetConfig(stated = {}) {
+	const merged = mergeConfig(rootDefaults(), stated);
+	const root = statedOnce(merged.test ?? {});
+	const { projects } = root;
+	if (projects === void 0) return {
+		...merged,
+		test: root
+	};
+	const inline = projects.map(withProjectDefaults);
+	return {
+		...merged,
+		test: {
+			...root,
+			...root.exclude === void 0 ? {} : { exclude: rootExcludeBeside(inline, root.exclude) },
+			projects: inline
+		}
+	};
+}
 //#endregion
-//#region src/runner/projects.ts
-/**
-* A module test runs beside the module it covers: no DOM, no browser, no
-* pipeline. Its suffix is `.test.ts` and its place is OUTSIDE `specs/`, where
-* the assembled product is specified in `.spec.ts` — the two exclusions say
-* exactly that. `.test.tsx` is the third exclusion because a rendered thing is
-* a component test: a project's dependency scan reads every file its globs
-* match, and a `.tsx` collected here would be optimised for a page that never
-* opens.
-*/
+//#region src/vitest/unit.project.ts
+/** `.test.tsx` is excluded: a rendered thing is a component test, and the dependency scan would optimise it for a page that never opens. */
 function unit(options = {}) {
 	const fromRoots = options.roots?.map((root) => `${root.replace(/\/+$/u, "")}/**/*.test.ts`);
 	return onProjectDefaults({ test: {
-		exclude: options.exclude ?? ["specs/**", "**/*.test.tsx"],
-		include: options.include ?? fromRoots ?? ["**/*.test.ts"],
-		...options.serial === true ? { fileParallelism: false } : {},
-		name: "unit",
-		sequence: { groupOrder: 0 },
-		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+		...projectTest("unit", options, {
+			exclude: fromRoots === void 0 ? ["specs/**", "**/*.test.tsx"] : ["**/*.test.tsx"],
+			include: fromRoots ?? ["**/*.test.ts"]
+		}),
+		...options.isolate === void 0 ? {} : { isolate: options.isolate }
 	} });
 }
 //#endregion
-export { api, cli, component, defineSpecConfig, integration, jobs, literate, mobile, unit, website };
+//#region src/index.vitest.ts
+/** The shared vitest config: what you pass is merged over the defaults. */
+function defineSpecConfig(config = {}) {
+	const { literate: literateOptions, ...userConfig } = config;
+	return presetConfig(literateOptions ? mergeConfig({ plugins: [literate(literateOptions)] }, userConfig) : userConfig);
+}
+const BUILDERS = /* @__PURE__ */ new Map([
+	["unit", unit],
+	["lint", lint],
+	["cli", cli],
+	["api", api],
+	["job", job],
+	["integration", integration],
+	["website", website],
+	["mobile", mobile],
+	["component", component]
+]);
+const anchored = (root, path) => isAbsolute(path) ? path : resolve(root, path);
+const anchoredTarget = (root, target) => typeof target === "string" && target.startsWith(".") ? anchored(root, target) : target;
+function aliasesFrom(root, vite) {
+	if (!isRecord(vite) || !isRecord(vite.resolve)) return vite;
+	const stated = vite.resolve.alias;
+	if (Array.isArray(stated)) {
+		const alias = stated.map((entry) => isRecord(entry) ? {
+			...entry,
+			replacement: anchoredTarget(root, entry.replacement)
+		} : entry);
+		return {
+			...vite,
+			resolve: {
+				...vite.resolve,
+				alias
+			}
+		};
+	}
+	if (!isRecord(stated)) return vite;
+	const alias = Object.fromEntries(Object.entries(stated).map(([name, target]) => [name, anchoredTarget(root, target)]));
+	return {
+		...vite,
+		resolve: {
+			...vite.resolve,
+			alias
+		}
+	};
+}
+function refused(found, fix) {
+	return new Error(refusal$1({
+		fix,
+		found,
+		read: "docs/start/set-up-a-project.md#the-vitest-config",
+		why: "a project is derived from the tree, and a declared one only states how it departs from that, with its reason"
+	}));
+}
+function declaredProjects(declared) {
+	if (declared === void 0) return /* @__PURE__ */ new Map();
+	if (!isRecord(declared)) throw refused("`test.projects` is not a record", "key each project by its specification: `projects: { cli: { timeout: 120_000, reason: ... } }`");
+	const projects = /* @__PURE__ */ new Map();
+	for (const [specification, project] of Object.entries(declared)) {
+		if (!BUILDERS.has(specification)) throw refused(`\`test.projects\` names the specification \`${specification}\``, `key it by one of ${[...BUILDERS.keys()].join(", ")}`);
+		const { reason, ...options } = isRecord(project) ? project : {};
+		if (typeof reason !== "string" || reason.trim() === "") throw refused(`\`test.projects.${specification}\` departs from its derived project with no reason`, `state why under \`test.projects.${specification}.reason\`, or delete what the tree already derives`);
+		projects.set(specification, options);
+	}
+	return projects;
+}
+async function projectOf(root, specification, { setup, ...options }) {
+	const builder = BUILDERS.get(specification);
+	if (builder === void 0) return {};
+	const componentRoot = anchored(root, typeof options.root === "string" ? options.root : ".");
+	const project = await builder({
+		...options,
+		...specification === "component" ? { root: componentRoot } : {},
+		vite: aliasesFrom(root, options.vite)
+	});
+	const setups = Array.isArray(setup) ? setup.filter((path) => typeof path === "string") : [];
+	return mergeConfig({ test: { globalSetup: setups.map((path) => anchored(root, path)) } }, project);
+}
+async function derivedFrom(root) {
+	const { problem, resolved } = await readSettings(root);
+	if (problem !== null) throw new Error(refusal$1({
+		fix: "correct jterrazz.config.ts as the finding says, then run vitest again",
+		found: `jterrazz.config.ts ${problem}`,
+		read: "docs/start/set-up-a-project.md#the-vitest-config",
+		why: "the test projects are declared there, and a config read without them would run none of them"
+	}));
+	const section = resolved.sections[TEST_SECTION];
+	const declared = declaredProjects(isRecord(section) ? section.projects : void 0);
+	const own = resolved.own[TEST_SECTION]?.projects;
+	const derived = derivedProjects(root);
+	const specifications = [...BUILDERS.keys()].filter((specification) => derived.has(specification) || isRecord(own) && own[specification] !== void 0);
+	return presetConfig(specifications.length === 0 ? {} : { test: { projects: await Promise.all(specifications.map(async (specification) => await projectOf(root, specification, {
+		...derived.get(specification),
+		...declared.get(specification)
+	}))) } });
+}
+const vitestConfig = async (configUrl) => await derivedFrom(dirname(fileURLToPath(configUrl)));
+//#endregion
+export { api, cli, component, defineSpecConfig, integration, job, lint, literate, mobile, unit, vitestConfig, website };
+
+//# sourceMappingURL=vitest.js.map