@jterrazz/test 15.1.1 → 15.2.0

package/dist/playwright.adapter.js

@@ -1,10 +1,13 @@
-import { n as describeAmbiguity, t as AmbiguousElementError } from "./ambiguity.js";
+import { n as describeAmbiguity, r as formatElement, t as AmbiguousElementError } from "./ambiguity.js";
 import { mkdtempSync } from "node:fs";
 import { resolve } from "node:path";
 import { tmpdir } from "node:os";
+import { setTimeout } from "node:timers/promises";
 //#region src/integrations/playwright/playwright.adapter.ts
 /** How many candidates the ambiguity error enumerates before truncating. */
 const MAX_REPORTED_MATCHES = 10;
+const VALUE_TIMEOUT_MS = 3e4;
+const VALUE_POLL_MS = 100;
 /**
 * Translate a user-facing descriptor into a playwright locator, resolving
 * `scope` outside-in so `within(navigation(), link('X'))` searches the nav
@@ -14,26 +17,15 @@ const MAX_REPORTED_MATCHES = 10;
 */
 function locate(root, element) {
 	const scope = element.scope ? locate(root, element.scope) : root;
-	const options = element.name === void 0 ? { exact: element.exact ?? false } : {
-		exact: element.exact ?? false,
+	const exact = element.exact ?? false;
+	const name = element.name ?? "";
+	if (element.kind === "field") return scope.getByLabel(name, { exact });
+	if (element.kind === "testId") return scope.getByTestId(name);
+	if (element.kind === "text") return scope.getByText(name, { exact });
+	return scope.getByRole(element.kind, element.name === void 0 ? { exact } : {
+		exact,
 		name: element.name
-	};
-	switch (element.kind) {
-		case "banner":
-		case "complementary":
-		case "contentinfo":
-		case "form":
-		case "main":
-		case "navigation":
-		case "region":
-		case "search": return scope.getByRole(element.kind, options);
-		case "button":
-		case "heading":
-		case "link": return scope.getByRole(element.kind, options);
-		case "field": return scope.getByLabel(element.name ?? "", { exact: element.exact ?? false });
-		case "testId": return scope.getByTestId(element.name ?? "");
-		case "text": return scope.getByText(element.name ?? "", { exact: element.exact ?? false });
-	}
+	});
 }
 /** Playwright signals "more than one match" through this error text. */
 function isStrictViolation(error) {
@@ -48,11 +40,14 @@ async function captureMatches(locator) {
 			const landmark = element.parentElement?.closest(LANDMARKS);
 			const context = landmark ? landmark.getAttribute("role") ?? landmark.tagName.toLowerCase() : null;
 			const detail = element.getAttribute("href") ?? element.getAttribute("name");
+			const text = (element.textContent ?? "").replaceAll(/\s+/gu, " ").trim().slice(0, 80);
+			const label = element.getAttribute("aria-label")?.trim();
 			return {
+				accessibleName: label && label !== text ? label : void 0,
 				context: context ?? void 0,
 				detail: detail ?? void 0,
 				tag: element.tagName.toLowerCase(),
-				text: (element.textContent ?? "").replaceAll(/\s+/gu, " ").trim().slice(0, 80)
+				text
 			};
 		});
 	}, MAX_REPORTED_MATCHES);
@@ -83,6 +78,59 @@ async function findAmbiguousLevel(page, element) {
 	for (const level of chain.slice(0, -1)) if (await locate(page, level).count() > 1) return level;
 	return element;
 }
+/**
+* The same element, narrowed by whatever STATE the descriptor carries — focus,
+* or accepting input — or `null` when it carries none.
+*
+* A second condition on the locator rather than a one-shot probe: the locator
+* keeps playwright's own retry, so `see(focused(x))` waits for the keyboard to
+* arrive instead of asking once and failing on a frame of animation. It also
+* needs nothing but `playwright` — `expect(...).toBeFocused()` lives in
+* `@playwright/test`, which this package deliberately does not carry.
+*/
+function stateOnly(page, locator, element) {
+	if (element.focused === true) return locator.and(page.locator(":focus"));
+	if (element.disabled !== void 0) return locator.and(page.locator(element.disabled ? ":disabled" : ":enabled"));
+	if (element.selected !== void 0) return locator.and(page.locator(element.selected ? ":checked" : ":not(:checked)"));
+	return null;
+}
+/**
+* Is this descriptor answered by PRESENCE rather than by visibility? The
+* options of a collapsed `<select>` are in the document and in the tree, and
+* none of them has a box on the screen until a visitor opens it.
+*/
+function byPresence(element) {
+	return element.kind === "option";
+}
+/** The field's live value, or `null` when nothing (unambiguous) is there yet. */
+async function currentValue(locator) {
+	try {
+		return await locator.inputValue({ timeout: VALUE_POLL_MS });
+	} catch (error) {
+		if (isStrictViolation(error)) throw error;
+		return null;
+	}
+}
+/**
+* Wait until the field holds the value the descriptor carries — or, for
+* `gone()`, until it no longer does.
+*
+* A poll rather than a narrowed locator: a value is a PROPERTY of the node,
+* and the CSS a locator narrows with reads ATTRIBUTES — a controlled input
+* whose `value` attribute never moves would answer for a value it no longer
+* holds. The locator is re-read every round, so a re-rendered field is read
+* again rather than held as a stale handle.
+*/
+async function waitForValue(locator, element, wanted) {
+	const value = element.value ?? "";
+	const deadline = Date.now() + VALUE_TIMEOUT_MS;
+	for (;;) {
+		const actual = await currentValue(locator);
+		if (actual === null ? !wanted : actual === value === wanted) return;
+		if (Date.now() >= deadline) throw new Error(`${formatElement(element)} ${wanted ? "never held" : "still holds"} ${JSON.stringify(value)}${actual === null ? " (it is not on the page)" : `, it holds ${JSON.stringify(actual)}`}`);
+		await setTimeout(VALUE_POLL_MS);
+	}
+}
 /** The visitor implementation — every action auto-waits via playwright actionability. */
 function createVisitor(page, baseUrl) {
 	return {
@@ -112,9 +160,32 @@ function createVisitor(page, baseUrl) {
 		press: async (key) => {
 			await page.keyboard.press(key);
 		},
+		gone: async (element) => {
+			await act(page, element, async (locator) => {
+				if (element.value !== void 0) {
+					await waitForValue(locator, element, false);
+					return;
+				}
+				const narrowed = stateOnly(page, locator, element);
+				if (narrowed !== null) {
+					await narrowed.waitFor({ state: "detached" });
+					return;
+				}
+				await locator.waitFor({ state: byPresence(element) ? "detached" : "hidden" });
+			});
+		},
 		see: async (element) => {
 			await act(page, element, async (locator) => {
-				await locator.waitFor({ state: "visible" });
+				if (element.value !== void 0) {
+					await waitForValue(locator, element, true);
+					return;
+				}
+				const narrowed = stateOnly(page, locator, element);
+				if (narrowed !== null) {
+					await narrowed.waitFor({ state: "attached" });
+					return;
+				}
+				await locator.waitFor({ state: byPresence(element) ? "attached" : "visible" });
 			});
 		},
 		select: async (element, option) => {
@@ -192,9 +263,11 @@ var PlaywrightAdapter = class {
 					title: document.title
 				};
 			});
+			const tree = await page.locator("body").ariaSnapshot();
 			return {
 				consoleMessages,
 				status: response?.status() ?? 0,
+				tree,
 				url: page.url(),
 				...extraction
 			};

package/dist/queue.js

@@ -1,5 +1,5 @@
 import { t as CaptureScope } from "./match.js";
-import { A as placeholderPatternSource, D as hasPlaceholders, P as textEquals } from "./artifacts.js";
+import { I as textEquals, M as placeholderPatternSource, k as hasPlaceholders } from "./artifacts.js";
 //#region src/specification/contracts/contract.ts
 /**
 * Declare one contract. Identity function — its value is the enforced shape

package/dist/vitest.d.ts

@@ -1,4 +1,5 @@
-import { ViteUserConfig } from "vitest/config";
+import { TestProjectInlineConfiguration, ViteUserConfig } from "vitest/config";
+import { UserConfig, UserConfigFn } from "vite";
 //#region src/vitest/literate-plugin.d.ts
 type LiterateOptions = {
   /**
@@ -57,4 +58,101 @@ type SpecConfig = {
 } & ViteUserConfig;
 declare function defineSpecConfig(config?: SpecConfig): ViteUserConfig;
 //#endregion
-export { type LiterateOptions, type LiteratePlugin, type SpecConfig, defineSpecConfig, literate };
+//#region src/vitest/projects.d.ts
+/**
+ * The project helpers — one per kind of test, each the canonical project that
+ * kind runs in.
+ *
+ * A project is not a matter of taste: `--project component` has to mean the
+ * same thing in every repository of the ecosystem, and what a browser project
+ * needs (a provider pinned to the runner, a service worker, a Vite pipeline,
+ * an artefact directory that is not the repository root) is the framework's to
+ * know, not the consumer's to rediscover. So the consumer names the kind and
+ * states only what is theirs.
+ */
+/** What every helper accepts on top of its canonical project. */
+type CommonOptions = {
+  /**
+   * Replace the canonical `exclude` globs. A helper whose canonical
+   * `exclude` only guards its canonical `include` drops it when you state
+   * `include` alone, so state both or neither.
+   */
+  exclude?: string[];
+  /** Replace the canonical `include` globs. */
+  include?: string[];
+  /**
+   * Run this project's files ONE AT A TIME (`fileParallelism: false`) — for
+   * the facets whose files share something a second worker would collide
+   * with: one served app, one database file, one browser profile.
+   */
+  serial?: boolean;
+  /** Raise (or lower) the 30s budget for this project alone. */
+  timeout?: number;
+};
+/** `unit()` — module tests, beside the modules they cover (CONVENTIONS I2). */
+type UnitProjectOptions = CommonOptions & {
+  /**
+   * The trees module tests live in, when they do not live in `src/`. Each
+   * root becomes `<root>/**\/*.test.ts`; `include` states the globs outright.
+   */
+  roots?: string[];
+};
+/** `website()` — the assembled product, met through a served page. */
+type WebsiteProjectOptions = CommonOptions;
+/** `component()` — rendered units, beside the components they cover. */
+type ComponentProjectOptions = {
+  /** Freeze the page's `Date` for every render of the project. */
+  clock?: string;
+  /** `Accept-Language` and `Intl` locale of the page. Default `'en-US'`. */
+  locale?: string;
+  /**
+   * The directory `vite` and `wrap` are resolved against. Default: the
+   * directory of the file that CALLED the helper — see
+   * {@link callerDirectory}. State it when the call is not written in the
+   * config it configures (a shared config factory).
+   */
+  root?: string;
+  /** IANA zone the page's `Date` reports in. Default `'UTC'`. */
+  timezone?: string;
+  /**
+   * The app's own Vite pipeline: a config path, the object, or the function
+   * a framework exports. Only the PIPELINE is adopted (see {@link reroot}).
+   */
+  vite?: Promise<UserConfig> | string | UserConfig | UserConfigFn;
+  /** The page size every render gets. Default 1280×720. */
+  viewport?: {
+    height: number;
+    width: number;
+  };
+  /**
+   * A module whose default export is `(ui) => ReactNode` — the providers
+   * every render of this project is dressed in (a theme, a store, an intl
+   * provider). A router belongs on the chain instead: it is a test's Given.
+   */
+  wrap?: string;
+} & CommonOptions;
+/**
+ * A module test runs beside the module it covers: no DOM, no browser, no
+ * pipeline. `.test.tsx` is excluded 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.
+ */
+declare function unit(options?: UnitProjectOptions): TestProjectInlineConfiguration;
+/**
+ * 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.
+ */
+declare function website(options?: WebsiteProjectOptions): TestProjectInlineConfiguration;
+/**
+ * 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.
+ */
+declare function component(options?: ComponentProjectOptions): Promise<TestProjectInlineConfiguration>;
+//#endregion
+export { type ComponentProjectOptions, type LiterateOptions, type LiteratePlugin, type SpecConfig, type UnitProjectOptions, type WebsiteProjectOptions, component, defineSpecConfig, literate, unit, website };

package/dist/vitest.js

@@ -1,6 +1,9 @@
+import { c as GROUND_EXPECTED } from "./match.js";
 import { a as specDescription, r as VITEST_ARTIFACTS_DIR, t as COVERAGE_DIR } from "./artifacts.js";
-import { readFileSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+import { createRequire } from "node:module";
+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/vitest/literate-plugin.ts
 /**
@@ -116,6 +119,12 @@ const EXCLUDE = [...configDefaults.exclude, "**/_fixtures/**"];
 * 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
 */
 function projectDefaults() {
 	return {
@@ -164,4 +173,367 @@ function defineSpecConfig(config = {}) {
 	};
 }
 //#endregion
-export { defineSpecConfig, literate };
+//#region src/integrations/vitest-browser/commands.ts
+/** Where a golden sits: `_expected/<name>` beside the test that asked for it. */
+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);
+}
+/** The ARIA snapshot of the rendered `<body>`, as YAML. */
+const ariaTree = async (context) => {
+	return await (await context.frame()).locator("body").ariaSnapshot();
+};
+/** 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");
+	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 COMPONENT_COMMANDS = {
+	ariaTree,
+	goldenRead,
+	goldenWrite
+};
+//#endregion
+//#region src/vitest/projects.ts
+/** The pipeline keys a consumer's Vite config contributes, and nothing else. */
+const PIPELINE_KEYS = [
+	"assetsInclude",
+	"css",
+	"define",
+	"envPrefix",
+	"esbuild",
+	"json",
+	"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 = [
+	"react",
+	"react-dom/client",
+	"react/jsx-dev-runtime",
+	"react/jsx-runtime",
+	"vitest-browser-react"
+];
+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;
+	}
+}
+/** The nearest directory at or above the cwd holding a file of this name. */
+function nearestHolding(name) {
+	let directory = process.cwd();
+	for (;;) {
+		if (existsSync(resolve(directory, name))) return directory;
+		const parent = dirname(directory);
+		if (parent === directory) return;
+		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();
+	const bundled = BUNDLED_CONFIG.exec(basename(file))?.groups?.name;
+	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);
+		return true;
+	} catch {
+		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");
+			server.middlewares.use("/mockServiceWorker.js", (_request, response) => {
+				response.setHeader("content-type", "text/javascript");
+				response.setHeader("service-worker-allowed", "/");
+				response.end(readFileSync(script, "utf8"));
+			});
+		},
+		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.
+*/
+async function reroot(source, root) {
+	const environment = {
+		command: "serve",
+		isSsrBuild: false,
+		mode: "test"
+	};
+	let loaded;
+	let from = "the value it was given";
+	if (typeof source === "string") {
+		const { loadConfigFromFile } = await import("vite");
+		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}`);
+	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];
+	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";
+}
+/**
+* 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.",
+		`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()
+	};
+}
+/** 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 module test runs beside the module it covers: no DOM, no browser, no
+* pipeline. `.test.tsx` is excluded 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.
+*/
+function unit(options = {}) {
+	const fromRoots = options.roots?.map((root) => `${root.replace(/\/+$/u, "")}/**/*.test.ts`);
+	return mergeConfig(projectDefaults(), { 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 }
+	} });
+}
+/**
+* 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.
+*/
+function website(options = {}) {
+	return mergeConfig(projectDefaults(), { test: {
+		...options.exclude === void 0 ? {} : { exclude: options.exclude },
+		...options.serial === true ? { fileParallelism: false } : {},
+		include: options.include ?? ["specs/website/**/*.test.ts"],
+		name: "website",
+		sequence: { groupOrder: 1 },
+		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+	} });
+}
+/**
+* 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.
+*/
+async function component(options = {}) {
+	const root = options.root ?? callerDirectory();
+	assertProviderPin();
+	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 project = {
+		...pipeline,
+		...jsxPipeline(pipeline),
+		optimizeDeps: { include: SEAM_DEPENDENCIES.filter(resolves) },
+		plugins: [mswWorkerPlugin(), ...consumerPlugins],
+		test: {
+			attachmentsDir: `${VITEST_ARTIFACTS_DIR}/attachments`,
+			browser: {
+				commands: COMPONENT_COMMANDS,
+				enabled: true,
+				headless: true,
+				instances: [{ browser: "chromium" }],
+				provider: playwright({ contextOptions: {
+					locale: options.locale ?? "en-US",
+					timezoneId: options.timezone ?? "UTC"
+				} }),
+				screenshotDirectory: `${VITEST_ARTIFACTS_DIR}/screenshots`,
+				viewport: viewportOf(options)
+			},
+			...componentGlobs(options),
+			...options.serial === true ? { fileParallelism: false } : {},
+			name: "component",
+			provide: providedToPage(options),
+			...options.wrap === void 0 ? {} : { setupFiles: [writeSetupFile(options.wrap, root)] },
+			sequence: { groupOrder: 2 },
+			...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+		}
+	};
+	return mergeConfig(projectDefaults(), project);
+}
+//#endregion
+export { component, defineSpecConfig, literate, unit, website };