@jterrazz/test 9.2.1 → 10.1.0

package/dist/oxlint.cjs

@@ -166,7 +166,7 @@ const RULE_DOCS = {
 	},
 	"a2-known-constructors": {
 		channel: "statique",
-		convention: "Quatre constructeurs et seulement quatre : `specification.api()`, `specification.jobs()`, `specification.cli(bin)`, `specification.website()` ; tout autre membre (`.app`, `.http`, `.stack`…) est une erreur.",
+		convention: "Cinq constructeurs et seulement cinq : `specification.api()`, `specification.jobs()`, `specification.cli(bin)`, `specification.website()`, `specification.mobile()` ; tout autre membre (`.app`, `.http`, `.stack`…) est une erreur.",
 		family: "A",
 		id: "A2",
 		rationale: "Une surface fermée empêche l’invention de constructeurs parallèles et garde l’API mémorisable."
@@ -439,16 +439,16 @@ const RULE_DOCS = {
 	},
 	"w1-scenario-pure": {
 		channel: "statique",
-		convention: "Un scénario de visite est le When : le visiteur agit, la capture reflète l’état final ; aucun `expect()` dans le callback — les assertions vivent dans le Then, sur le résultat retourné.",
-		facet: "website",
+		convention: "Un scénario (`.visit()` website, `.open()` mobile) est le When : le visiteur agit, la capture reflète l’état final ; aucun `expect()` dans le callback — les assertions vivent dans le Then, sur le résultat retourné.",
+		facet: "shared",
 		family: "W",
 		id: "W1",
 		rationale: "Séparer l’interaction de l’assertion garde la grammaire setup → action → résultat intacte et les scénarios rejouables."
 	},
 	"w2w-user-facing-elements": {
 		channel: "statique",
-		convention: "Les éléments d’un scénario sont user-facing (`button`, `link`, `field`, `heading`, `content`) ; `testId()` est l’unique échappatoire et déclenche un avertissement.",
-		facet: "website",
+		convention: "Les éléments d’un scénario sont user-facing (`button`, `link`, `field`, `heading`, `content` ; côté mobile `button`, `field`, `content`) ; `testId()` est l’unique échappatoire et déclenche un avertissement.",
+		facet: "shared",
 		family: "W",
 		id: "W2",
 		rationale: "Tester ce que l’utilisateur voit (rôles, labels) rend les specs robustes aux refontes DOM ; un test-id contourne cette garantie."
@@ -571,6 +571,24 @@ const RUNTIME_RULES = [
 		name: "d14-tomatch-fixture-name",
 		rationale: "L’instinct hérité de vitest (`toMatch(/re/)`) tomberait sinon sur l’erreur d’extension ou coercerait la regex en `\"/re/\"`. L’argument accesseur n’est jamais littéral côté valeur, et une heuristique statique confondrait le `expect(chaîne).toMatch(/re/)` légitime (D3/D8) — seul le canal runtime refuse proprement, sans faux positifs."
 	},
+	{
+		channel: "runtime",
+		convention: "Un descripteur d’élément doit désigner exactement UN élément quand un verbe AGIT dessus (`click`/`tap`/`fill`) : si plusieurs correspondent, l’action est refusée avec une erreur qui énumère les candidats et propose les réécritures (`within(...)`, `{ exact: true }`). Le framework n’agit jamais sur « le premier ». Vaut pour les deux facettes à scénario : website et mobile ; sur mobile, `see()` — qui n’agit sur rien — est satisfait par n’importe quel match visible (l’arbre XCUITest duplique légitimement un label entre conteneur et enfant).",
+		facet: "shared",
+		family: "W",
+		id: "W3",
+		name: "w3-unambiguous-element",
+		rationale: "Agir sur le premier match rend le spec vert alors que le visiteur clique autre chose, et rien ne le signale jamais — une ambiguïté est une faute d’écriture, pas un cas à arbitrer par l’ordre du DOM. Le comptage n’existe qu’à l’exécution : aucune analyse statique ne peut le faire, d’où le canal runtime."
+	},
+	{
+		channel: "runtime",
+		convention: "Le vocabulaire d’éléments est UNIQUE entre les facettes website et mobile ; un landmark ARIA (`main()`, `navigation()`…) passé à un verbe mobile est refusé à l’exécution — un écran iOS n’a pas de régions ARIA ; scoper avec `within(testId(…), …)`.",
+		facet: "mobile",
+		family: "W",
+		id: "W4",
+		name: "w4-no-landmarks-on-mobile",
+		rationale: "Un seul vocabulaire garde l’API mémorisable ; refuser explicitement la partie sans équivalent iOS évite une approximation silencieuse."
+	},
 	{
 		channel: "runtime",
 		convention: "`.intercept()` n’existe que sur `api`/`jobs` et lève immédiatement en mode compose (MSW est in-process).",
@@ -756,18 +774,19 @@ const a10DuplicateBinding = {
 };
 //#endregion
 //#region src/lint/rules/a2-known-constructors.ts
-/** The four constructors, and only four (A2 — see docs/10-linting.md). */
+/** The five constructors, and only five (A2 — see docs/10-linting.md). */
 const KNOWN_CONSTRUCTORS = /* @__PURE__ */ new Set([
 	"api",
 	"cli",
 	"jobs",
+	"mobile",
 	"website"
 ]);
 /**
 * CONVENTIONS A2 — `specification.api()`, `specification.jobs()`,
-* `specification.cli()` and `specification.website()` are the only members.
-* Any other access (`specification.app`, `.http`, `.stack`, …) is flagged at
-* the member site.
+* `specification.cli()`, `specification.website()` and
+* `specification.mobile()` are the only members. Any other access
+* (`specification.app`, `.http`, `.stack`, …) is flagged at the member site.
 */
 const a2KnownConstructors = {
 	create(context) {
@@ -784,7 +803,7 @@ const a2KnownConstructors = {
 	},
 	meta: {
 		docs: RULE_DOCS["a2-known-constructors"],
-		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs(), specification.cli() and specification.website() (A2 — see docs/10-linting.md)." },
+		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs(), specification.cli(), specification.website() and specification.mobile() (A2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2421,6 +2440,7 @@ const f5FixturesOnlyFromTests = {
 */
 const INTEGRATION_DEPS = {
 	anthropic: ["@anthropic-ai/sdk"],
+	appium: ["webdriverio"],
 	compose: ["yaml"],
 	docker: [],
 	hono: ["hono", "@hono/node-server"],
@@ -2498,6 +2518,7 @@ const i1LayerBoundaries = {
 				if (target.startsWith("core/") || target.startsWith("integrations/docker/") || target.startsWith("integrations/hono/") || withoutExtension(target) === "vitest/matchers") return null;
 				if (target.startsWith("integrations/msw/") && inside === "core/specification/shared/builder.ts") return null;
 				if (target.startsWith("integrations/playwright/") && inside === "core/specification/website/start-website.ts") return null;
+				if (target.startsWith("integrations/appium/") && inside === "core/specification/mobile/start-mobile.ts") return null;
 				return "crossLayer";
 			}
 			if (layer === "integrations") return target.startsWith("core/") || target.startsWith(`integrations/${integrationFolder}/`) ? null : "crossLayer";
@@ -2823,6 +2844,82 @@ const TITLED = /* @__PURE__ */ new Set([
 * `HTTP`, `DI`. Such a word names a symbol verbatim — lowercasing it would
 * misspell it — so it is exempt. A prose word (`Rejects`, `Builds`) is not. */
 const ALL_CAPS_IDENTIFIER = /^[A-Z][A-Z0-9_]*$/u;
+/**
+* CONVENTIONS J5 — the first character of a `test('…')` / `describe('…')` title
+* literal must be lowercase.
+*
+* The test name is the sole description of behaviour (B3): a sentence fragment,
+* lowercase-led like prose (`'rejects an unknown job'`). Exempt are titles
+* whose first WORD is an identifier-shaped all-caps/underscored token
+* (`'VALID_CATEGORIES is rejected'`, `'HTTP is upgraded'`, `'DI wires …'`) —
+* lowercasing a named symbol would misspell it — and titles opening on a
+* non-letter (a `$`, a `{`, a `%s` placeholder). Only lowercase-able prose
+* first words are enforced. Covers the modifier and parametrized forms
+* (`test.only`, `describe.each(...)(...)`) via the chain root.
+*/
+const j5LowercaseTitle = {
+	create(context) {
+		return { CallExpression(node) {
+			const callee = node.callee;
+			const root = chainRootName(callee);
+			if (root === void 0 || !TITLED.has(root)) return;
+			const title = stringValue(node.arguments?.[0]);
+			if (title === void 0) return;
+			const first = [...title][0];
+			if (first === void 0 || !/\p{L}/u.test(first)) return;
+			const firstWord = title.split(/\s+/u)[0];
+			if (ALL_CAPS_IDENTIFIER.test(firstWord)) return;
+			if (first !== first.toLocaleLowerCase()) context.report({
+				data: { runner: root },
+				messageId: "uppercase",
+				node
+			});
+		} };
+	},
+	meta: {
+		docs: RULE_DOCS["j5-lowercase-title"],
+		messages: { uppercase: "A {{runner}}() title must start lowercase — the test name is a prose fragment, not a sentence (J5 — see docs/10-linting.md)." },
+		type: "problem"
+	}
+};
+//#endregion
+//#region src/lint/rules/w1-scenario-pure.ts
+/** The scenario-carrying terminal actions: `.visit()` (website) and `.open()` (mobile). */
+const SCENARIO_ACTIONS$1 = /* @__PURE__ */ new Set(["open", "visit"]);
+/**
+* CONVENTIONS W1 — a visit (or mobile open) scenario is the When: the
+* visitor interacts, the capture reflects the final state, and assertions
+* live in the Then on the returned result. An `expect()` inside the scenario
+* callback is flagged.
+*/
+const w1ScenarioPure = {
+	create(context) {
+		return { CallExpression(node) {
+			const callee = node.callee;
+			const member = callee ? memberPropertyName(callee) : void 0;
+			if (member === void 0 || !SCENARIO_ACTIONS$1.has(member)) return;
+			const scenario = node.arguments?.[1];
+			if (scenario?.type !== "ArrowFunctionExpression" && scenario?.type !== "FunctionExpression") return;
+			walk(scenario, (inner) => {
+				if (inner.type !== "CallExpression") return;
+				const innerCallee = inner.callee;
+				if (innerCallee?.type === "Identifier" && innerCallee.name === "expect") context.report({
+					messageId: "expectInScenario",
+					node: inner
+				});
+			});
+		} };
+	},
+	meta: {
+		docs: RULE_DOCS["w1-scenario-pure"],
+		messages: { expectInScenario: "No expect() inside a scenario — the scenario is the When; assert the final state on the returned result in the Then (W1 — see docs/10-linting.md)." },
+		type: "problem"
+	}
+};
+//#endregion
+//#region src/lint/rules/w2w-user-facing-elements.ts
+/** The scenario-carrying terminal actions: `.visit()` (website) and `.open()` (mobile). */
+const SCENARIO_ACTIONS = /* @__PURE__ */ new Set(["open", "visit"]);
 //#endregion
 //#region src/lint/plugin.ts
 /**
@@ -2882,59 +2979,14 @@ const plugin = {
 		"j2-no-sleep-in-specs": j2NoSleepInSpecs,
 		"j3-no-expectless-test": j3NoExpectlessTest,
 		"j4-unique-test-names": j4UniqueTestNames,
-		"j5-lowercase-title": {
-			create(context) {
-				return { CallExpression(node) {
-					const callee = node.callee;
-					const root = chainRootName(callee);
-					if (root === void 0 || !TITLED.has(root)) return;
-					const title = stringValue(node.arguments?.[0]);
-					if (title === void 0) return;
-					const first = [...title][0];
-					if (first === void 0 || !/\p{L}/u.test(first)) return;
-					const firstWord = title.split(/\s+/u)[0];
-					if (ALL_CAPS_IDENTIFIER.test(firstWord)) return;
-					if (first !== first.toLocaleLowerCase()) context.report({
-						data: { runner: root },
-						messageId: "uppercase",
-						node
-					});
-				} };
-			},
-			meta: {
-				docs: RULE_DOCS["j5-lowercase-title"],
-				messages: { uppercase: "A {{runner}}() title must start lowercase — the test name is a prose fragment, not a sentence (J5 — see docs/10-linting.md)." },
-				type: "problem"
-			}
-		},
-		"w1-scenario-pure": {
-			create(context) {
-				return { CallExpression(node) {
-					const callee = node.callee;
-					if (!callee || memberPropertyName(callee) !== "visit") return;
-					const scenario = node.arguments?.[1];
-					if (scenario?.type !== "ArrowFunctionExpression" && scenario?.type !== "FunctionExpression") return;
-					walk(scenario, (inner) => {
-						if (inner.type !== "CallExpression") return;
-						const innerCallee = inner.callee;
-						if (innerCallee?.type === "Identifier" && innerCallee.name === "expect") context.report({
-							messageId: "expectInScenario",
-							node: inner
-						});
-					});
-				} };
-			},
-			meta: {
-				docs: RULE_DOCS["w1-scenario-pure"],
-				messages: { expectInScenario: "No expect() inside a visit scenario — the scenario is the When; assert the final state on the returned result in the Then (W1 — see docs/10-linting.md)." },
-				type: "problem"
-			}
-		},
+		"j5-lowercase-title": j5LowercaseTitle,
+		"w1-scenario-pure": w1ScenarioPure,
 		"w2w-user-facing-elements": {
 			create(context) {
 				return { CallExpression(node) {
 					const callee = node.callee;
-					if (!callee || memberPropertyName(callee) !== "visit") return;
+					const member = callee ? memberPropertyName(callee) : void 0;
+					if (member === void 0 || !SCENARIO_ACTIONS.has(member)) return;
 					const scenario = node.arguments?.[1];
 					if (scenario?.type !== "ArrowFunctionExpression" && scenario?.type !== "FunctionExpression") return;
 					walk(scenario, (inner) => {

package/dist/oxlint.d.cts

@@ -65,7 +65,7 @@ type RuleDoc = {
    * The specification facet the rule guards — segments the catalogue like
    * the constructors segment the API. `'shared'` for cross-facet rules.
    */
-  facet?: 'api' | 'cli' | 'jobs' | 'shared' | 'website';
+  facet?: 'api' | 'cli' | 'jobs' | 'mobile' | 'shared' | 'website';
   /** Convention family letter, e.g. `'A'`. */
   family: string;
   /** Convention code, e.g. `'A1'`. */

package/dist/oxlint.d.ts

@@ -65,7 +65,7 @@ type RuleDoc = {
    * The specification facet the rule guards — segments the catalogue like
    * the constructors segment the API. `'shared'` for cross-facet rules.
    */
-  facet?: 'api' | 'cli' | 'jobs' | 'shared' | 'website';
+  facet?: 'api' | 'cli' | 'jobs' | 'mobile' | 'shared' | 'website';
   /** Convention family letter, e.g. `'A'`. */
   family: string;
   /** Convention code, e.g. `'A1'`. */

package/dist/oxlint.js

@@ -162,7 +162,7 @@ const RULE_DOCS = {
 	},
 	"a2-known-constructors": {
 		channel: "statique",
-		convention: "Quatre constructeurs et seulement quatre : `specification.api()`, `specification.jobs()`, `specification.cli(bin)`, `specification.website()` ; tout autre membre (`.app`, `.http`, `.stack`…) est une erreur.",
+		convention: "Cinq constructeurs et seulement cinq : `specification.api()`, `specification.jobs()`, `specification.cli(bin)`, `specification.website()`, `specification.mobile()` ; tout autre membre (`.app`, `.http`, `.stack`…) est une erreur.",
 		family: "A",
 		id: "A2",
 		rationale: "Une surface fermée empêche l’invention de constructeurs parallèles et garde l’API mémorisable."
@@ -435,16 +435,16 @@ const RULE_DOCS = {
 	},
 	"w1-scenario-pure": {
 		channel: "statique",
-		convention: "Un scénario de visite est le When : le visiteur agit, la capture reflète l’état final ; aucun `expect()` dans le callback — les assertions vivent dans le Then, sur le résultat retourné.",
-		facet: "website",
+		convention: "Un scénario (`.visit()` website, `.open()` mobile) est le When : le visiteur agit, la capture reflète l’état final ; aucun `expect()` dans le callback — les assertions vivent dans le Then, sur le résultat retourné.",
+		facet: "shared",
 		family: "W",
 		id: "W1",
 		rationale: "Séparer l’interaction de l’assertion garde la grammaire setup → action → résultat intacte et les scénarios rejouables."
 	},
 	"w2w-user-facing-elements": {
 		channel: "statique",
-		convention: "Les éléments d’un scénario sont user-facing (`button`, `link`, `field`, `heading`, `content`) ; `testId()` est l’unique échappatoire et déclenche un avertissement.",
-		facet: "website",
+		convention: "Les éléments d’un scénario sont user-facing (`button`, `link`, `field`, `heading`, `content` ; côté mobile `button`, `field`, `content`) ; `testId()` est l’unique échappatoire et déclenche un avertissement.",
+		facet: "shared",
 		family: "W",
 		id: "W2",
 		rationale: "Tester ce que l’utilisateur voit (rôles, labels) rend les specs robustes aux refontes DOM ; un test-id contourne cette garantie."
@@ -567,6 +567,24 @@ const RUNTIME_RULES = [
 		name: "d14-tomatch-fixture-name",
 		rationale: "L’instinct hérité de vitest (`toMatch(/re/)`) tomberait sinon sur l’erreur d’extension ou coercerait la regex en `\"/re/\"`. L’argument accesseur n’est jamais littéral côté valeur, et une heuristique statique confondrait le `expect(chaîne).toMatch(/re/)` légitime (D3/D8) — seul le canal runtime refuse proprement, sans faux positifs."
 	},
+	{
+		channel: "runtime",
+		convention: "Un descripteur d’élément doit désigner exactement UN élément quand un verbe AGIT dessus (`click`/`tap`/`fill`) : si plusieurs correspondent, l’action est refusée avec une erreur qui énumère les candidats et propose les réécritures (`within(...)`, `{ exact: true }`). Le framework n’agit jamais sur « le premier ». Vaut pour les deux facettes à scénario : website et mobile ; sur mobile, `see()` — qui n’agit sur rien — est satisfait par n’importe quel match visible (l’arbre XCUITest duplique légitimement un label entre conteneur et enfant).",
+		facet: "shared",
+		family: "W",
+		id: "W3",
+		name: "w3-unambiguous-element",
+		rationale: "Agir sur le premier match rend le spec vert alors que le visiteur clique autre chose, et rien ne le signale jamais — une ambiguïté est une faute d’écriture, pas un cas à arbitrer par l’ordre du DOM. Le comptage n’existe qu’à l’exécution : aucune analyse statique ne peut le faire, d’où le canal runtime."
+	},
+	{
+		channel: "runtime",
+		convention: "Le vocabulaire d’éléments est UNIQUE entre les facettes website et mobile ; un landmark ARIA (`main()`, `navigation()`…) passé à un verbe mobile est refusé à l’exécution — un écran iOS n’a pas de régions ARIA ; scoper avec `within(testId(…), …)`.",
+		facet: "mobile",
+		family: "W",
+		id: "W4",
+		name: "w4-no-landmarks-on-mobile",
+		rationale: "Un seul vocabulaire garde l’API mémorisable ; refuser explicitement la partie sans équivalent iOS évite une approximation silencieuse."
+	},
 	{
 		channel: "runtime",
 		convention: "`.intercept()` n’existe que sur `api`/`jobs` et lève immédiatement en mode compose (MSW est in-process).",
@@ -752,18 +770,19 @@ const a10DuplicateBinding = {
 };
 //#endregion
 //#region src/lint/rules/a2-known-constructors.ts
-/** The four constructors, and only four (A2 — see docs/10-linting.md). */
+/** The five constructors, and only five (A2 — see docs/10-linting.md). */
 const KNOWN_CONSTRUCTORS = /* @__PURE__ */ new Set([
 	"api",
 	"cli",
 	"jobs",
+	"mobile",
 	"website"
 ]);
 /**
 * CONVENTIONS A2 — `specification.api()`, `specification.jobs()`,
-* `specification.cli()` and `specification.website()` are the only members.
-* Any other access (`specification.app`, `.http`, `.stack`, …) is flagged at
-* the member site.
+* `specification.cli()`, `specification.website()` and
+* `specification.mobile()` are the only members. Any other access
+* (`specification.app`, `.http`, `.stack`, …) is flagged at the member site.
 */
 const a2KnownConstructors = {
 	create(context) {
@@ -780,7 +799,7 @@ const a2KnownConstructors = {
 	},
 	meta: {
 		docs: RULE_DOCS["a2-known-constructors"],
-		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs(), specification.cli() and specification.website() (A2 — see docs/10-linting.md)." },
+		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs(), specification.cli(), specification.website() and specification.mobile() (A2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2417,6 +2436,7 @@ const f5FixturesOnlyFromTests = {
 */
 const INTEGRATION_DEPS = {
 	anthropic: ["@anthropic-ai/sdk"],
+	appium: ["webdriverio"],
 	compose: ["yaml"],
 	docker: [],
 	hono: ["hono", "@hono/node-server"],
@@ -2494,6 +2514,7 @@ const i1LayerBoundaries = {
 				if (target.startsWith("core/") || target.startsWith("integrations/docker/") || target.startsWith("integrations/hono/") || withoutExtension(target) === "vitest/matchers") return null;
 				if (target.startsWith("integrations/msw/") && inside === "core/specification/shared/builder.ts") return null;
 				if (target.startsWith("integrations/playwright/") && inside === "core/specification/website/start-website.ts") return null;
+				if (target.startsWith("integrations/appium/") && inside === "core/specification/mobile/start-mobile.ts") return null;
 				return "crossLayer";
 			}
 			if (layer === "integrations") return target.startsWith("core/") || target.startsWith(`integrations/${integrationFolder}/`) ? null : "crossLayer";
@@ -2819,6 +2840,82 @@ const TITLED = /* @__PURE__ */ new Set([
 * `HTTP`, `DI`. Such a word names a symbol verbatim — lowercasing it would
 * misspell it — so it is exempt. A prose word (`Rejects`, `Builds`) is not. */
 const ALL_CAPS_IDENTIFIER = /^[A-Z][A-Z0-9_]*$/u;
+/**
+* CONVENTIONS J5 — the first character of a `test('…')` / `describe('…')` title
+* literal must be lowercase.
+*
+* The test name is the sole description of behaviour (B3): a sentence fragment,
+* lowercase-led like prose (`'rejects an unknown job'`). Exempt are titles
+* whose first WORD is an identifier-shaped all-caps/underscored token
+* (`'VALID_CATEGORIES is rejected'`, `'HTTP is upgraded'`, `'DI wires …'`) —
+* lowercasing a named symbol would misspell it — and titles opening on a
+* non-letter (a `$`, a `{`, a `%s` placeholder). Only lowercase-able prose
+* first words are enforced. Covers the modifier and parametrized forms
+* (`test.only`, `describe.each(...)(...)`) via the chain root.
+*/
+const j5LowercaseTitle = {
+	create(context) {
+		return { CallExpression(node) {
+			const callee = node.callee;
+			const root = chainRootName(callee);
+			if (root === void 0 || !TITLED.has(root)) return;
+			const title = stringValue(node.arguments?.[0]);
+			if (title === void 0) return;
+			const first = [...title][0];
+			if (first === void 0 || !/\p{L}/u.test(first)) return;
+			const firstWord = title.split(/\s+/u)[0];
+			if (ALL_CAPS_IDENTIFIER.test(firstWord)) return;
+			if (first !== first.toLocaleLowerCase()) context.report({
+				data: { runner: root },
+				messageId: "uppercase",
+				node
+			});
+		} };
+	},
+	meta: {
+		docs: RULE_DOCS["j5-lowercase-title"],
+		messages: { uppercase: "A {{runner}}() title must start lowercase — the test name is a prose fragment, not a sentence (J5 — see docs/10-linting.md)." },
+		type: "problem"
+	}
+};
+//#endregion
+//#region src/lint/rules/w1-scenario-pure.ts
+/** The scenario-carrying terminal actions: `.visit()` (website) and `.open()` (mobile). */
+const SCENARIO_ACTIONS$1 = /* @__PURE__ */ new Set(["open", "visit"]);
+/**
+* CONVENTIONS W1 — a visit (or mobile open) scenario is the When: the
+* visitor interacts, the capture reflects the final state, and assertions
+* live in the Then on the returned result. An `expect()` inside the scenario
+* callback is flagged.
+*/
+const w1ScenarioPure = {
+	create(context) {
+		return { CallExpression(node) {
+			const callee = node.callee;
+			const member = callee ? memberPropertyName(callee) : void 0;
+			if (member === void 0 || !SCENARIO_ACTIONS$1.has(member)) return;
+			const scenario = node.arguments?.[1];
+			if (scenario?.type !== "ArrowFunctionExpression" && scenario?.type !== "FunctionExpression") return;
+			walk(scenario, (inner) => {
+				if (inner.type !== "CallExpression") return;
+				const innerCallee = inner.callee;
+				if (innerCallee?.type === "Identifier" && innerCallee.name === "expect") context.report({
+					messageId: "expectInScenario",
+					node: inner
+				});
+			});
+		} };
+	},
+	meta: {
+		docs: RULE_DOCS["w1-scenario-pure"],
+		messages: { expectInScenario: "No expect() inside a scenario — the scenario is the When; assert the final state on the returned result in the Then (W1 — see docs/10-linting.md)." },
+		type: "problem"
+	}
+};
+//#endregion
+//#region src/lint/rules/w2w-user-facing-elements.ts
+/** The scenario-carrying terminal actions: `.visit()` (website) and `.open()` (mobile). */
+const SCENARIO_ACTIONS = /* @__PURE__ */ new Set(["open", "visit"]);
 //#endregion
 //#region src/lint/plugin.ts
 /**
@@ -2878,59 +2975,14 @@ const plugin = {
 		"j2-no-sleep-in-specs": j2NoSleepInSpecs,
 		"j3-no-expectless-test": j3NoExpectlessTest,
 		"j4-unique-test-names": j4UniqueTestNames,
-		"j5-lowercase-title": {
-			create(context) {
-				return { CallExpression(node) {
-					const callee = node.callee;
-					const root = chainRootName(callee);
-					if (root === void 0 || !TITLED.has(root)) return;
-					const title = stringValue(node.arguments?.[0]);
-					if (title === void 0) return;
-					const first = [...title][0];
-					if (first === void 0 || !/\p{L}/u.test(first)) return;
-					const firstWord = title.split(/\s+/u)[0];
-					if (ALL_CAPS_IDENTIFIER.test(firstWord)) return;
-					if (first !== first.toLocaleLowerCase()) context.report({
-						data: { runner: root },
-						messageId: "uppercase",
-						node
-					});
-				} };
-			},
-			meta: {
-				docs: RULE_DOCS["j5-lowercase-title"],
-				messages: { uppercase: "A {{runner}}() title must start lowercase — the test name is a prose fragment, not a sentence (J5 — see docs/10-linting.md)." },
-				type: "problem"
-			}
-		},
-		"w1-scenario-pure": {
-			create(context) {
-				return { CallExpression(node) {
-					const callee = node.callee;
-					if (!callee || memberPropertyName(callee) !== "visit") return;
-					const scenario = node.arguments?.[1];
-					if (scenario?.type !== "ArrowFunctionExpression" && scenario?.type !== "FunctionExpression") return;
-					walk(scenario, (inner) => {
-						if (inner.type !== "CallExpression") return;
-						const innerCallee = inner.callee;
-						if (innerCallee?.type === "Identifier" && innerCallee.name === "expect") context.report({
-							messageId: "expectInScenario",
-							node: inner
-						});
-					});
-				} };
-			},
-			meta: {
-				docs: RULE_DOCS["w1-scenario-pure"],
-				messages: { expectInScenario: "No expect() inside a visit scenario — the scenario is the When; assert the final state on the returned result in the Then (W1 — see docs/10-linting.md)." },
-				type: "problem"
-			}
-		},
+		"j5-lowercase-title": j5LowercaseTitle,
+		"w1-scenario-pure": w1ScenarioPure,
 		"w2w-user-facing-elements": {
 			create(context) {
 				return { CallExpression(node) {
 					const callee = node.callee;
-					if (!callee || memberPropertyName(callee) !== "visit") return;
+					const member = callee ? memberPropertyName(callee) : void 0;
+					if (member === void 0 || !SCENARIO_ACTIONS.has(member)) return;
 					const scenario = node.arguments?.[1];
 					if (scenario?.type !== "ArrowFunctionExpression" && scenario?.type !== "FunctionExpression") return;
 					walk(scenario, (inner) => {

package/dist/playwright.adapter.js

@@ -1,32 +1,102 @@
+import { n as describeAmbiguity, t as AmbiguousElementError } from "./ambiguity.js";
 import { mkdtempSync } from "node:fs";
 import { resolve } from "node:path";
 import { tmpdir } from "node:os";
 //#region src/integrations/playwright/playwright.adapter.ts
-/** Translate a user-facing element descriptor into a playwright locator. */
-function locate(page, element) {
+/** How many candidates the ambiguity error enumerates before truncating. */
+const MAX_REPORTED_MATCHES = 10;
+/**
+* Translate a user-facing descriptor into a playwright locator, resolving
+* `scope` outside-in so `within(navigation(), link('X'))` searches the nav
+* subtree. No `.first()` anywhere: playwright's strict mode is the mechanism
+* behind CONVENTIONS W3, and swallowing it would reintroduce the silent
+* wrong-element bug the rule exists to prevent.
+*/
+function locate(root, element) {
+	const scope = element.scope ? locate(root, element.scope) : root;
+	const options = {
+		exact: element.exact,
+		name: element.name
+	};
 	switch (element.kind) {
-		case "button": return page.getByRole("button", { name: element.name });
-		case "field": return page.getByLabel(element.name);
-		case "heading": return page.getByRole("heading", { name: element.name });
-		case "link": return page.getByRole("link", { name: element.name });
-		case "testId": return page.getByTestId(element.name);
-		case "text": return page.getByText(element.name);
+		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 });
+		case "testId": return scope.getByTestId(element.name ?? "");
+		case "text": return scope.getByText(element.name ?? "", { exact: element.exact });
+	}
+}
+/** Playwright signals "more than one match" through this error text. */
+function isStrictViolation(error) {
+	return error instanceof Error && error.message.includes("strict mode violation");
+}
+/** Capture the candidates in-page — the evidence the refusal enumerates. */
+async function captureMatches(locator) {
+	return locator.evaluateAll((nodes, limit) => {
+		const LANDMARKS = "nav, header, footer, main, aside, section, form, [role]";
+		return nodes.slice(0, limit).map((node) => {
+			const element = node;
+			const landmark = element.parentElement?.closest(LANDMARKS);
+			const context = landmark ? landmark.getAttribute("role") ?? landmark.tagName.toLowerCase() : null;
+			const detail = element.getAttribute("href") ?? element.getAttribute("name");
+			return {
+				context: context ?? void 0,
+				detail: detail ?? void 0,
+				tag: element.tagName.toLowerCase(),
+				text: (element.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 80)
+			};
+		});
+	}, MAX_REPORTED_MATCHES);
+}
+/**
+* Run one visitor action, converting a strict-mode violation into the W3
+* refusal. The ambiguous level is identified before reporting: a scope that
+* matches several landmarks is the real fault, and naming the target instead
+* would send the author to fix the wrong descriptor.
+*/
+async function act(page, element, action) {
+	try {
+		return await action(locate(page, element));
+	} catch (error) {
+		if (!isStrictViolation(error)) throw error;
+		const culprit = await findAmbiguousLevel(page, element);
+		throw new AmbiguousElementError(describeAmbiguity({
+			element: culprit,
+			matches: await captureMatches(locate(page, culprit)),
+			url: page.url()
+		}));
 	}
 }
+/** Walk the scope chain outside-in; the outermost ambiguous level is the fault. */
+async function findAmbiguousLevel(page, element) {
+	const chain = [];
+	for (let current = element; current; current = current.scope) chain.unshift(current);
+	for (const level of chain.slice(0, -1)) if (await locate(page, level).count() > 1) return level;
+	return element;
+}
 /** The visitor implementation — every action auto-waits via playwright actionability. */
 function createVisitor(page, baseUrl) {
 	return {
-		check: (element) => locate(page, element).first().check(),
-		click: (element) => locate(page, element).first().click(),
-		fill: (element, value) => locate(page, element).first().fill(value),
+		check: (element) => act(page, element, (locator) => locator.check()),
+		click: (element) => act(page, element, (locator) => locator.click()),
+		fill: (element, value) => act(page, element, (locator) => locator.fill(value)),
 		goto: async (path) => {
 			await page.goto(`${baseUrl}${path}`, { waitUntil: "load" });
 		},
-		hover: (element) => locate(page, element).first().hover(),
+		hover: (element) => act(page, element, (locator) => locator.hover()),
 		press: (key) => page.keyboard.press(key),
-		see: (element) => locate(page, element).first().waitFor({ state: "visible" }),
+		see: (element) => act(page, element, (locator) => locator.waitFor({ state: "visible" })),
 		select: async (element, option) => {
-			await locate(page, element).first().selectOption(option);
+			await act(page, element, (locator) => locator.selectOption(option));
 		}
 	};
 }
@@ -51,9 +121,9 @@ var PlaywrightAdapter = class {
 	async open(url, options) {
 		const context = await (await this.launch()).newContext({ extraHTTPHeaders: options.headers });
 		if (options.external === "block") {
-			const origin = new URL(options.baseUrl).origin;
+			const allowed = /* @__PURE__ */ new Set([new URL(options.baseUrl).origin, ...options.allowedOrigins ?? []]);
 			await context.route("**/*", (route) => {
-				if (new URL(route.request().url()).origin === origin) route.continue();
+				if (allowed.has(new URL(route.request().url()).origin)) route.continue();
 				else route.abort();
 			});
 		}
@@ -71,7 +141,12 @@ var PlaywrightAdapter = class {
 				await options.scenario(createVisitor(page, options.baseUrl));
 			} catch (error) {
 				const evidence = await this.captureEvidence(page);
-				throw new Error(`visit scenario failed: ${error instanceof Error ? error.message : String(error)}${evidence ? `\nEvidence: ${evidence}` : ""}`, { cause: error });
+				const suffix = evidence ? `\nEvidence: ${evidence}` : "";
+				if (error instanceof AmbiguousElementError) {
+					error.message += suffix;
+					throw error;
+				}
+				throw new Error(`visit scenario failed: ${error instanceof Error ? error.message : String(error)}${suffix}`, { cause: error });
 			}
 			const extraction = await page.evaluate(() => {
 				const links = [...document.querySelectorAll("link")].map((link) => ({