@jterrazz/test 16.0.0 → 16.1.1

package/dist/substring-warning.js

@@ -0,0 +1,282 @@
+//#region src/model/elements/ambiguity.ts
+/**
+* The ambiguity refusal — CONVENTIONS W3.
+*
+* A visit descriptor must designate exactly one element. Acting on "the
+* first match" is the failure mode this module exists to prevent: the spec
+* keeps passing while the visitor clicks something else, and nothing ever
+* reports it. So when a descriptor matches several elements the framework
+* refuses, and the refusal has to carry everything needed to fix it without
+* opening a browser — the descriptor in the caller's own vocabulary, every
+* candidate, and the concrete rewrites that would resolve it.
+*
+* Pure string building: it takes captured data and returns a message, so the
+* wording is unit-testable and the browser integration stays a thin adapter.
+*/
+/** `kind` → the constructor that builds it, so errors echo the caller's source. */
+const CONSTRUCTORS = {
+	banner: "banner",
+	button: "button",
+	complementary: "complementary",
+	contentinfo: "contentinfo",
+	dialog: "dialog",
+	field: "field",
+	form: "form",
+	heading: "heading",
+	link: "link",
+	listitem: "listitem",
+	main: "main",
+	navigation: "navigation",
+	option: "option",
+	region: "region",
+	row: "row",
+	search: "search",
+	status: "status",
+	table: "table",
+	testId: "testId",
+	text: "content"
+};
+/** The landmark a context string maps back to, for a copy-pasteable suggestion. */
+const CONTEXT_LANDMARKS = {
+	aside: "complementary()",
+	banner: "banner()",
+	complementary: "complementary()",
+	contentinfo: "contentinfo()",
+	footer: "contentinfo()",
+	form: "form()",
+	header: "banner()",
+	main: "main()",
+	nav: "navigation()",
+	navigation: "navigation()",
+	search: "search()"
+};
+/**
+* Render a descriptor as the source that would build it — `link('Articles')`,
+* `within(navigation(), link('Articles', { exact: false }))`. The error speaks
+* the vocabulary the author wrote, never playwright's — so the option appears
+* only when the AUTHOR stated one, whichever way.
+*/
+function formatElement(element) {
+	const bare = formatBare(element);
+	return element.scope ? `within(${formatElement(element.scope)}, ${bare})` : bare;
+}
+function formatBare(element) {
+	const args = [];
+	if (element.name !== void 0) args.push(JSON.stringify(element.name));
+	if (element.exact !== void 0) args.push(`{ exact: ${String(element.exact)} }`);
+	return `${CONSTRUCTORS[element.kind]}(${args.join(", ")})`;
+}
+/** `1. <a href="/articles">Articles</a>  in <nav>` — one evidence line per candidate. */
+function formatMatch(match, index) {
+	const attribute = match.detail ? ` ${quoteDetail(match)}` : "";
+	const named = match.accessibleName ? `  named ${JSON.stringify(match.accessibleName)}` : "";
+	const context = match.context ? `  in <${match.context}>` : "";
+	return `  ${index + 1}. <${match.tag}${attribute}>${match.text}</${match.tag}>${named}${context}`;
+}
+function quoteDetail(match) {
+	return `${match.tag === "a" ? "href" : "name"}=${JSON.stringify(match.detail)}`;
+}
+/** Each landmark the candidates sit in, and how many of them it holds. */
+function landmarkCounts(matches) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const match of matches) {
+		const landmark = match.context === void 0 ? void 0 : CONTEXT_LANDMARKS[match.context];
+		if (landmark !== void 0) counts.set(landmark, (counts.get(landmark) ?? 0) + 1);
+	}
+	return [...counts].toSorted(([, a], [, b]) => a - b);
+}
+/**
+* The rewrites worth offering, in the order they should be tried. Scoping is
+* always available; `exact` only when it would actually narrow the set, and
+* the count it would leave is stated so a still-ambiguous suggestion never
+* reads as a fix.
+*/
+function formatFixes(element, matches) {
+	const fixes = [];
+	const narrowing = landmarkCounts(matches).filter(([, count]) => count < matches.length);
+	if (!element.scope) {
+		const [first, ...rest] = narrowing;
+		const alsoHere = rest.length > 0 ? `   [also here: ${rest.map(([name]) => name).join(", ")}]` : "";
+		fixes.push(first === void 0 ? `scope it       within(<a container holding only this one>, ${formatBare(element)})` : `scope it       within(${first[0]}, ${formatBare(element)})   [leaves ${first[1]} of ${matches.length}]${alsoHere}`);
+	}
+	if (element.exact === false && element.name !== void 0) {
+		const remaining = matches.filter((match) => match.text === element.name).length;
+		if (remaining > 0 && remaining < matches.length) fixes.push(`exact name     ${formatBare({
+			...element,
+			exact: true
+		})}   [leaves ${remaining} of ${matches.length}]`);
+	}
+	fixes.push("other element  a heading(), button() or field() may name one thing where this does not");
+	return fixes;
+}
+/**
+* The W3 refusal. A distinct class so the visit wrapper can recognize an
+* already-complete message and let it through instead of nesting it inside
+* `visit scenario failed: …`, which would print the whole thing twice.
+*/
+var AmbiguousElementError = class extends Error {
+	name = "AmbiguousElementError";
+};
+/**
+* Build the refusal thrown when a descriptor matches more than one element.
+*
+* @param options.element The descriptor as the caller wrote it.
+* @param options.matches Every candidate, in DOM order (already truncated).
+* @param options.url The page the visitor was on when it happened.
+*/
+function describeAmbiguity(options) {
+	const { element, matches, url } = options;
+	const fixes = formatFixes(element, matches).map((fix) => `  • ${fix}`);
+	return [
+		`Ambiguous element: ${formatElement(element)} matched ${matches.length} elements on ${url}.`,
+		"",
+		"A spec must designate exactly one element. Acting on the first match would let",
+		"this test keep passing while the visitor interacts with something else.",
+		"",
+		"Matched:",
+		...matches.map((match, index) => formatMatch(match, index)),
+		"",
+		"Disambiguate with one of:",
+		...fixes,
+		"",
+		"Docs: docs/13-elements.md#designating-exactly-one-element (CONVENTIONS W3)"
+	].join("\n");
+}
+//#endregion
+//#region src/model/elements/substring-warning.ts
+/**
+* The transitional warning for a name that matches only as a SUBSTRING.
+*
+* Until 16.0 a descriptor's name matched any element whose accessible name
+* CONTAINED it, so `link('Articles')` also designated "Read Articles" — and a
+* test could pass for years against the wrong element without anyone noticing,
+* because the wrong element was usually next to the right one. Exact is the
+* default now.
+*
+* A lint rule cannot carry this: whether a name matched whole or in part is a
+* fact about a RUN, and a verdict fed by a previous run's artefact is not
+* deterministic. So it is a runtime warning, printed by the adapter that did
+* the looking, at the moment it has both answers in hand — nothing found under
+* exact, something found under substring.
+*
+* It is printed ONCE per descriptor per process: a scenario that clicks the
+* same link in ten tests has one thing to fix, not ten lines to read.
+*/
+/** How long the window lasts, stated in the message itself. */
+const WINDOW = "through 16.x";
+/** The node side's printer — the default every adapter but the page's uses. */
+function toStandardError(line) {
+	if (typeof process === "undefined") {
+		console.warn(line);
+		return;
+	}
+	process.stderr.write(`${line}\n`);
+}
+/** Descriptors already reported in this process. */
+const reported = /* @__PURE__ */ new Set();
+/** The identity a descriptor is deduplicated by — kind, name, and its scope chain. */
+function identityOf(element) {
+	const own = `${element.kind}:${element.name ?? ""}`;
+	return element.scope === void 0 ? own : `${identityOf(element.scope)}>${own}`;
+}
+/**
+* Report that `element` designated nothing as a whole name, but would have
+* designated something as a substring. Returns whether a line was printed,
+* which is what the adapters' own tests assert on.
+*/
+async function warnSubstringOnly(element, where, found, print = toStandardError) {
+	const identity = identityOf(element);
+	if (reported.has(identity)) return false;
+	reported.add(identity);
+	const spelling = found === void 0 ? "" : ` The name to write is '${found.replaceAll(/\s+/gu, " ").trim()}'.`;
+	await print(`@jterrazz/test: ${element.kind}('${element.name ?? ""}') matched nothing as a whole accessible name, and matched only as a SUBSTRING of a longer one (${where}).${spelling} Names are exact from 16.0: write the name in full, scope it with \`within(…)\`, or state \`{ exact: false }\` to keep the old behaviour. The substring is still resolved, with this warning, ${WINDOW}; gone in 17.0, where the same descriptor is simply not found.`);
+	return true;
+}
+/**
+* How long a descriptor is given to ARRIVE before the window concludes it is
+* absent — the budget `settles` spends and no more.
+*
+* A count is one observation, and a verb called right after a navigating
+* `click()` takes it on the page being LEFT. The window may not decide
+* "nothing matches this whole name" on that reading: the destination has not
+* been parsed yet. Long enough for a navigation to commit, far short of the
+* verb's own 30 s, and paid only when there is a substring to widen to.
+*/
+const WINDOW_SETTLE_MS = 5e3;
+/**
+* The descriptor to retry with, LEVEL by level, or `undefined` when nothing
+* would change.
+*
+* Every level of the chain is asked the same question the target is asked —
+* `within(button('Proof of authorship'), content('Verified'))` against a
+* button named "Proof of authorship Verified" failed on the SCOPE, and a
+* warning that only ever widened the target printed nothing at all. The chain
+* is walked outside-in and rebuilt as it goes, since an inner level's answer
+* is meaningless under a scope that designates nothing.
+*
+* A level that states an `exact` of its own is left alone: an author who wrote
+* `{ exact: false }` chose the substring, and one who wrote `{ exact: true }`
+* was already exact.
+*
+* Asked BEFORE the action, not after it fails: a verb waits its whole
+* actionability budget, which is the test's own budget, so a retry afterwards
+* never runs — the test is already over. The common case (the name matches
+* whole) costs one count per level, which waits for nothing.
+*/
+async function widenedForWindow(element, where, probe) {
+	const chain = [];
+	for (let level = element; level; level = level.scope) chain.unshift(level);
+	let rebuilt;
+	let widened = false;
+	for (const level of chain) {
+		const candidate = {
+			...level,
+			...rebuilt === void 0 ? {} : { scope: rebuilt }
+		};
+		const loose = await widenedLevel(candidate, where, probe);
+		widened ||= loose !== void 0;
+		rebuilt = loose ?? candidate;
+	}
+	return widened ? rebuilt : void 0;
+}
+/**
+* The one level, widened and warned about, or `undefined` when it designates
+* something already, states its own `exact`, carries no name, would designate
+* nothing either way, or turns out to be exact on the surface that ARRIVES.
+*
+* The last is the navigation case, and it is the reason the verdict is not two
+* counts: a `see()` fired right after a navigating `click()` counts the page
+* being left, so a descriptor that is perfectly exact on the DESTINATION read
+* as substring-only — non-deterministically, since which page each count
+* landed on was a race. A widening is therefore only decided once the exact
+* descriptor has been given the settle budget and still designates nothing.
+* The tell of the old fault was the printed name equalling the name written.
+*/
+async function widenedLevel(candidate, where, probe) {
+	if (candidate.exact !== void 0 || candidate.name === void 0) return;
+	try {
+		if (await probe.count(candidate) > 0) return;
+		const loose = {
+			...candidate,
+			exact: false
+		};
+		if (await probe.count(loose) !== 1) return;
+		if (!alreadyJudged(candidate) && await probe.settles(candidate)) return;
+		await warnSubstringOnly(candidate, where, await probe.nameOf(loose), probe.print);
+		return loose;
+	} catch {
+		return;
+	}
+}
+/**
+* Has this descriptor already been judged substring-only in this run?
+*
+* The verdict is made once: a scenario that clicks the same link in ten tests
+* pays the settle budget on the first of them and is widened straight away on
+* the nine after it.
+*/
+function alreadyJudged(element) {
+	return reported.has(identityOf(element));
+}
+//#endregion
+export { describeAmbiguity as a, AmbiguousElementError as i, warnSubstringOnly as n, formatElement as o, widenedForWindow as r, WINDOW_SETTLE_MS as t };

package/dist/vitest.js

@@ -214,6 +214,60 @@ function rootDefaults() {
 		}
 	};
 }
+/** 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.
+*/
+function statedOnce(test) {
+	const exclude = eachOnce(test.exclude);
+	const include = eachOnce(test.include);
+	return {
+		...test,
+		...exclude === void 0 ? {} : { exclude },
+		...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 : {
+		...merged,
+		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.
@@ -222,19 +276,26 @@ function rootDefaults() {
 */
 function withProjectDefaults(project) {
 	if (typeof project !== "object" || project === null || "then" in project) return project;
-	return mergeConfig(projectDefaults(), 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 projects = merged.test?.projects;
-	if (!projects) return merged;
+	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);
 	return {
 		...merged,
 		test: {
-			...merged.test,
-			projects: projects.map(withProjectDefaults)
+			...root,
+			...root.exclude === void 0 ? {} : { exclude: rootExcludeBeside(inline, root.exclude) },
+			projects: inline
 		}
 	};
 }
@@ -242,7 +303,7 @@ function defineSpecConfig(config = {}) {
 //#region src/runner/facet-project.ts
 /** The globs a node facet collects, and the ones a caller stated instead. */
 function facetProject(facet, options) {
-	return mergeConfig(projectDefaults(), { test: {
+	return onProjectDefaults({ test: {
 		...options.exclude === void 0 ? {} : { exclude: options.exclude },
 		include: options.include ?? [`specs/${facet}/**/*.spec.ts`],
 		...options.serial === true ? { fileParallelism: false } : {},
@@ -289,6 +350,23 @@ function goldenPath(testPath, name) {
 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);
@@ -306,9 +384,11 @@ const goldenWrite = (context, name, content) => {
 * page calls and the names the project registers cannot drift.
 */
 const COMPONENT_COMMANDS = {
+	ariaNode,
 	ariaTree,
 	goldenRead,
-	goldenWrite
+	goldenWrite,
+	notify
 };
 //#endregion
 //#region src/facets/component/component.project.ts
@@ -578,7 +658,7 @@ async function component(options = {}) {
 	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 = {
+	return onProjectDefaults({
 		...pipeline,
 		...jsxPipeline(pipeline),
 		optimizeDeps: { include: SEAM_DEPENDENCIES.filter(resolves) },
@@ -605,8 +685,7 @@ async function component(options = {}) {
 			sequence: { groupOrder: 2 },
 			...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
 		}
-	};
-	return mergeConfig(projectDefaults(), project);
+	});
 }
 //#endregion
 //#region src/facets/integration/integration.project.ts
@@ -638,7 +717,7 @@ function mobile(options = {}) {
 * a 2-vCPU runner.
 */
 function website(options = {}) {
-	return mergeConfig(projectDefaults(), { test: {
+	return onProjectDefaults({ test: {
 		...options.exclude === void 0 ? {} : { exclude: options.exclude },
 		...options.serial === true ? { fileParallelism: false } : {},
 		include: options.include ?? ["specs/website/**/*.spec.ts"],
@@ -660,7 +739,7 @@ function website(options = {}) {
 */
 function unit(options = {}) {
 	const fromRoots = options.roots?.map((root) => `${root.replace(/\/+$/u, "")}/**/*.test.ts`);
-	return mergeConfig(projectDefaults(), { test: {
+	return onProjectDefaults({ test: {
 		exclude: options.exclude ?? ["specs/**", "**/*.test.tsx"],
 		include: options.include ?? fromRoots ?? ["**/*.test.ts"],
 		...options.serial === true ? { fileParallelism: false } : {},

package/docs/01-architecture.md

@@ -0,0 +1,95 @@
+# 01 — Architecture
+
+What this package IS: one runner model behind six constructors, one chain that needs none, five source trees with declared edges, and seven channels through which its conventions are enforced — each row of the catalogue naming exactly one. The chapters that follow explain how to USE each facet; this one draws the lines they sit inside.
+
+| The shape                  | Held below                                                                       |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| The runner model           | [The runner model](#the-runner-model) — constructor, handle, chain, result       |
+| The source trees           | [The five trees](#the-five-trees) — `model`, `facets`, `seams`, `runner`, `lint` |
+| How a convention is held   | [The seven enforcement channels](#the-seven-enforcement-channels)                |
+| What ships out of the tree | [What the tree publishes](#what-the-tree-publishes)                              |
+
+The rules themselves — what each family says, what a reviewer must judge — are the constitution, [18 — Conventions](18-conventions.md); their normative sentences are the generated catalogue, [19 — Linting](19-linting.md).
+
+## The runner model
+
+Every facet is the same four steps. A **constructor** takes options and returns a **handle**; the handle opens a **chain** of zero or more setups closed by exactly one terminal action; the action executes and resolves to a **typed result**; the result is asserted through vitest's `expect()`. Nothing else is public — there is no imperative escape hatch, because a spec that can do anything proves nothing in particular.
+
+Six constructors exist and the list is closed (`src/facets/specification.ts`):
+
+| Constructor                   | Handle destructures to             | Subject under test                               |
+| ----------------------------- | ---------------------------------- | ------------------------------------------------ |
+| `specification.api()`         | `{ api, cleanup, docker }`         | An HTTP API, built and served in this process    |
+| `specification.jobs()`        | `{ jobs, cleanup }`                | A background pipeline, triggered by name         |
+| `specification.cli()`         | `{ cli, cleanup, docker }`         | A command binary in a fresh temp directory       |
+| `specification.integration()` | `{ integration, cleanup, docker }` | A module against real services, or a golden      |
+| `specification.website()`     | `{ website, cleanup, url }`        | A rendered page — fetched, or driven in chromium |
+| `specification.mobile()`      | `{ mobile, cleanup, udid }`        | A native screen on an iOS simulator              |
+
+The asymmetry in that column is the model, not an oversight: `jobs` never spawns a container, so it is handed no `docker`; `website` and `mobile` drive a browser and a simulator rather than an orchestrated stack, so they carry neither.
+
+**One facet has no constructor**, and the same reason explains it: a rendered component starts nothing. `component` ([07 — Component specs](07-component.md)) is a chain the package exports directly — `component.intercept(…).render(<X />)` — so there is no handle to destructure and no `cleanup` to pass to `afterAll`. What every render of a project shares (the providers, the Vite pipeline, the viewport) is the PROJECT's, stated once by `component()` in `vitest.config.ts`.
+
+A runner is created **once per suite**, in a `*.specification.ts` file, and imported by the test files beside it. That split is what makes the container lifecycle affordable — one Postgres per suite, not one per test — and it is why `afterAll(cleanup)` belongs in the specification file and nowhere else.
+
+### The seam under the chain
+
+`SpecificationBuilder` (`src/model/chain/builder.ts`) holds the chain for every facet; each facet contributes its own setups and its own terminal actions on top. The infrastructure a chain needs is reached through **ports** — `src/model/ports/` declares eight of them (`browser`, `cli`, `container`, `database`, `device`, `isolation`, `server`, `service`) — and an integration implements one. So the chain knows "a database exists"; it never knows Postgres.
+
+Every seam is opened lazily rather than imported, and each one is an optional peer loaded by the one module that owns it: `playwright` for `.visit()`, `appium`/`webdriverio` for `.open()`, `@vitest/browser-playwright` + `vitest-browser-react` + `react` for `component.render()`, and — since 16.0 — `better-sqlite3`, `pg`, `redis` and `testcontainers` for the services a record declares. A project that tests no page, no component and no database installs none of them; `src/seams/peer.ts` owns the one message a missing peer produces, which names the facet that asked, the command, and under pnpm the `onlyBuiltDependencies` line a native binding needs.
+
+## The five trees
+
+The source tree is five trees with declared, one-directional edges. The map is not the linter's to assume — `i1-layer-boundaries` ships inert — so this package declares its own as `FRAMEWORK_LAYERS` in `oxlint.config.ts`, and that declaration is the enforced statement of what follows.
+
+| Tree      | May import                                                                                                                              | Holds                                                                                                                                                                                                                         |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model/`  | itself, the docker/process/yaml seams, the msw seam through two named lazy imports, `runner/update`, and each facet's `*.result` module | What every facet is made of: the chain and the orchestrator, the results and their accessors, the element vocabulary, the contracts and `intercept()`, the `{{token}}` engine, the goldens, the clock, the doubles, the ports |
+| `facets/` | `model/`, itself, the runner's project shape, and the one seam each constructor opens                                                   | Seven folders, the SAME four files in each: `<facet>.specification.ts` (the constructor), `<facet>.chain.ts`, `<facet>.result.ts`, `<facet>.project.ts` (the vitest helper), plus what is unique to the facet                 |
+| `seams/`  | its OWN external dependency, plus `model/` and the facet vocabulary an adapter projects into                                            | One folder per dependency: `postgres`, `redis`, `sqlite`, `testcontainers`, `docker`, `hono`, `playwright`, `vitest-browser`, `appium`, `msw`, `openai`, `anthropic`, `yaml`, `process`                                       |
+| `runner/` | `vitest`, `vite`, `@vitest/browser-playwright`, `model/`, `facets/`                                                                     | The CONFIG side of the runner coupling: the preset, update mode, the `literate()` plugin, the shape a node facet's project takes, and the project index                                                                       |
+| `lint/`   | itself, plus a short list of PURE `model/` modules                                                                                      | The tool-facing channel: the oxlint plugin, the conventions checker, the catalogue manifest and generator                                                                                                                     |
+
+**Every facet folder carries the same four files, whether or not it owns all four.** The setups and terminal actions of the six node facets are ONE builder, because a second copy of "declare a contract, seed a table, run the thing" is how two facets drift — so `api.chain.ts` and its five siblings are a named re-export of that builder rather than an implementation, and `jobs.result.ts` re-exports the shape the builder states. The shape is uniform so that a reader who has opened one facet has opened all seven; the re-export says, in the folder itself, which of the four a facet does not own.
+
+Three of those edges carry their reason in the declaration itself. `model/` reaches `seams/docker`, `seams/process` and the yaml parser because none of the three has a dependency of its own to leak, and it reaches each facet's `*.result` module because the ONE builder constructs all seven results — a value edge, stated rather than hidden. `lint/` reaches exactly the pure modules the runner also uses — the token list, the ground names, the root walk, the `<case>.spec.yaml` parser — so that the file the lint accepts is the file the runner runs, from ONE parser. And the runner is named in exactly TWO places outside a test, one per side of it: `runner/` for the config side — the preset, the project shape, the plugin — and `seams/vitest-browser/` for the page side, where the locators, the visitor, the golden commands and the page's own `vitest` primitives live. Swapping the runner would be a rewrite of those two folders and of nothing else; `model/` states what a render IS and never which runner performs it, which is why the layer map exempts that seam from the prod-import ban (F2) by name.
+
+The table's May-import column is a reading of `FRAMEWORK_LAYERS`, never a second statement of it: the declaration in `oxlint.config.ts` is what the linter enforces and what a change edits.
+
+There are TWO composition roots and neither names a layer. `src/index.ts` is node's: it wires the container integrations into the registry seam and re-exports the public surface. `src/browser/index.ts` is the page's, and `src/surface.ts` is what they agree on — see [What the tree publishes](#what-the-tree-publishes).
+
+## The seven enforcement channels
+
+A convention this package states is held by a **channel**, and every row of the catalogue names exactly one of seven. The guiding aim is that most enforcement is programmatic, not review-borne.
+
+- **statique** — the `jterrazz/*` oxlint plugin: one file per rule under `src/lint/rules/model/` or `src/lint/rules/<facet>/` — the tree the rule reaches, which is also the `facet` field of its manifest row — AST analysis, one diagnostic per file.
+- **upstream** — a convention an oxlint vitest-plugin rule already holds, set as an OPTION from the `testing` fragment rather than duplicated as a rule of ours ([ADR-005](decisions/005-the-doubles-ladder-is-closed.md)).
+- **checker** — passes of the `jterrazz-test-check` binary reading what an AST cannot: the `{{token}}` grammar of `_requests/` and `_expected/` fixtures, the `<case>.spec.yaml` document family, cross-file analyses that cross a `*.specification.ts` with its tests, and the member pass that judges a package rather than a tree.
+- **runtime** — the framework refuses incorrect usage as it executes, where static analysis abstains (a non-literal argument) or cannot reach (the network, a container lifecycle).
+- **type** — what the compiler refuses with no rule at all, proven by `src/type-channel.test-d.ts`.
+- **meta** — what the framework's own suite holds about itself: the catalogue's freshness, its completeness, the reach of its rules — [03 — Testing](03-testing.md) owns the channel.
+- **process** — the judgement no single channel settles: asset-driven grouping, golden-file discipline, retro-propagation.
+
+The channel a rule sits on is not prose here: it is a field of `src/lint/manifest.ts`, the single source of truth from which the catalogue in [19 — Linting](19-linting.md) is generated. A rule and its normative sentence live together in the code, so the two cannot drift.
+
+## What the tree publishes
+
+The bundle is built by `tsdown` into `dist/` and its shape follows how each entry is consumed. `index` and `vitest`, plus the `checker`/`catalog` CLIs, are ESM-only — vitest is ESM-only and the CLIs are invoked as `node dist/*.js`. The `oxlint` plugin ships dual, because oxlint loads it from a consumer project that may itself be CommonJS.
+
+**There are FOUR entries and no more**: `@jterrazz/test` for everything a spec uses, `@jterrazz/test/vitest` for what `vitest.config.ts` needs, `@jterrazz/test/oxlint` for the lint plugin, `@jterrazz/test/schema` for an editor validating a `<case>.spec.yaml`. That is rule F1 rather than a convention of taste, and the exemption is derived from the manifest's own `exports` map (`src/lint/package-exports.ts`), so a subpath is exempt the moment it is published and stops being exempt the moment it is withdrawn.
+
+**The root entry has two runtimes.** A component test renders in a real browser, and the node entry cannot load there: it wires `pg`, `better-sqlite3`, `testcontainers` and `node:fs` at import. So `exports["."]` carries a `browser` condition resolving to `dist/browser/index.js` — the same public surface, built for a page, where every node-only name (the six constructors, the services, the docker accessors, the results that walk a disk) is a stub that throws where it was called, naming the facet and saying it runs under node. The split is the RUNTIME's and never the facets': one specifier, so no spec has to remember which entry it may import.
+
+`types` is stated once, and it is the node build's — so the two runtimes are ONE type surface and a name cannot exist on one side only. What both agree on lives in `src/surface.ts`, and the `package-exports` meta-test compares the two builds' exported names on every run.
+
+Two committed projections leave the code and land in the corpus: the API reference under `docs/reference/` (typedoc, through `typescript docs`) and the rule catalogue spliced into [19 — Linting](19-linting.md) and `skills/jterrazz-test/references/rules.md`. A third, `schema/spec.schema.json`, is generated from the document grammar's own constants. Both `docs/` and `schema/` ship in the tarball — the reference included, since the corpus links into it — so a consumer reads the manual where the messages send them, inside the install ([04 — Operating](04-operating.md#what-leaves-the-tree)). All three are regenerated by one gesture and sync-checked — see [02 — Developing](02-developing.md).
+
+## Pitfalls
+
+- **Reaching for a dependency from `model/`.** A new external package belongs in a folder of `seams/` that imports it and nothing else; `model/` importing it directly is the one boundary this package cannot afford to blur, and `i1-layer-boundaries` refuses it.
+- **Adding a seventh constructor.** The six are the closed vocabulary the conventions, the linter and the documentation are all shaped around. A new SUBJECT to specify is a design decision, and it earns a record in [`decisions/`](decisions/) before it earns a constructor — as `integration` did in [ADR-004](decisions/004-a-module-against-real-services-or-a-golden-is-the-integration-facet.md).
+- **Writing a rule's normative sentence into a chapter.** It belongs in `src/lint/manifest.ts` beside the implementation; a chapter that restates it is the second copy the whole design exists to prevent.
+
+## Related
+
+[02 — Developing](02-developing.md) · [03 — Testing](03-testing.md) · [18 — Conventions](18-conventions.md) · [19 — Linting](19-linting.md)