@shivaedev/test-story 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.14.0 - 2026-10-19
+
+### Added
+
+- `screenDriver` actions and text/value readouts accept `ScreenTarget` selectors or `{ role, name }` targets, with exact string or regular-expression accessible names, hidden-element exclusion, candidate diagnostics and role/name narration.
+- `screenDriver.accessible(element)` computes an existing element's accessible name and role without narration; `accessible(selector)` keeps its narrated readout.
+
 ## 0.13.0 - 2026-10-19
 
 ### Added

package/README.md

@@ -581,8 +581,12 @@ verbs: ({ view, requests }, story) => screenDriver({
 
 `text(selector?)` returns rendered text from the selected element or the whole root. `value(selector)` returns the current input or textarea value. Both narrate what they read through `tell` and leave assertions to the spec. Entry narration omits the supplied value.
 
+`click`, `enter`, `submit`, `text` and `value` also accept a `ScreenTarget` object such as `{ role: "button", name: "Save" }` or `{ role: "textbox", name: /email/i }`. The role and computed accessible name must match exactly when strings are used; regular expressions match the name. Like Testing Library's role queries, these targets exclude hidden elements, including `aria-hidden` ancestors. Missing or ambiguous targets fail with the requested role, name and the visible candidates on screen. Narration names the role and name instead of a selector.
+
 `accessible(selector)` returns `{ name, role }` computed by `dom-accessibility-api`, including native roles and label references that take precedence over `aria-label`. It narrates the readout and uses the same single rendered target checks as other readouts. Assert on this result when checking a control's accessible name; reading its raw attributes does not compute that name. This DOM computation does not inspect a browser's accessibility tree or prove speech from a screen reader.
 
+`accessible(element)` uses the same computation on an `Element` the kit already holds and tells no story line.
+
 For React, pass `act: async (action) => { await act(action); }` using React's `act`. The adapter wraps each action and flushes renderer work before checking the pending signal, including while waiting for an asynchronous response. The [React driver stories](https://github.com/ShivaeDev/platform/blob/main/packages/effect-react/src/screenDriver.dom.spec.tsx) cover a native pending atom, a rendered response and a controlled field without React warnings. The driver itself has no renderer dependency.
 
 Settlement has a live-time limit of 3 seconds, configurable with the driver's `timeoutMs` or per call with `settle({ timeoutMs })`, and fails with the current screen text and advice when that limit expires. Use the existing DOM environment and scoped `routeOutbound` routing to reach `fakeHttpService`; the driver does not install another transport. The [screen stories](src/server/screenSignals.dom.spec.ts) hold a real HTTP response across repeated renders and sign in by filling and submitting a form against a fake identity provider. These fixtures prove DOM interactions and loopback HTTP, not a browser or a production authentication system.
@@ -597,7 +601,7 @@ Import each module with the prefix `@shivaedev/test-story/`; there is no root en
 | `domFetch.ts` | `domFetch(baseUrl)` |
 | `seedCookies.ts` | `seedCookies(cookies)`, `DomCookie` |
 | `routeOutbound.ts` | `routeOutbound(routes)` |
-| `screenDriver.ts` | `screenDriver(options)`, `ScreenDriverOptions`, `ScreenDriver` |
+| `screenDriver.ts` | `screenDriver(options)`, `ScreenDriverOptions`, `ScreenDriver`, `ScreenTarget` |
 | `domNavigate.ts` | `domNavigate(url?)` |
 | `genreTags.ts` | `genreTags(...kitNames)`, `GenreTag` |
 | `domEnvironment.config.ts` | Default Vitest environment preserving Node host globals and happy-dom document transport |

package/dist/server/internal/screenAccessibility.d.ts

@@ -0,0 +1,9 @@
+import type { ScreenTarget } from "#screenDriver.ts";
+export declare function accessibility(element: Element): {
+    name: string;
+    role: string | null;
+};
+export declare function targetName(target: ScreenTarget): string;
+export declare function isRendered(found: HTMLElement): boolean;
+export declare function roleElement(root: HTMLElement, target: Exclude<ScreenTarget, string>): HTMLElement;
+//# sourceMappingURL=screenAccessibility.d.ts.map

package/dist/server/internal/screenAccessibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenAccessibility.d.ts","sourceRoot":"","sources":["../../../src/server/internal/screenAccessibility.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO;IACpC,IAAI;IAAkC,IAAI;EACnD;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAIvD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,WAY5C;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,eAsBnF"}

package/dist/server/internal/screenAccessibility.js

@@ -0,0 +1,44 @@
+import { computeAccessibleName, getRole, isInaccessible } from "dom-accessibility-api";
+export function accessibility(element) {
+    return { name: computeAccessibleName(element), role: getRole(element) };
+}
+export function targetName(target) {
+    return typeof target === "string"
+        ? target
+        : `${target.role} named ${typeof target.name === "string" ? JSON.stringify(target.name) : String(target.name)}`;
+}
+export function isRendered(found) {
+    const visibility = getComputedStyle(found).visibility;
+    if (visibility === "hidden" || visibility === "collapse") {
+        return false;
+    }
+    for (let ancestor = found; ancestor; ancestor = ancestor.parentElement) {
+        const style = getComputedStyle(ancestor);
+        if (ancestor.hidden || style.display === "none" || style.contentVisibility === "hidden") {
+            return false;
+        }
+    }
+    return true;
+}
+export function roleElement(root, target) {
+    const candidates = Array.from(root.querySelectorAll("*"))
+        .filter((element) => isRendered(element) && !isInaccessible(element))
+        .map((element) => ({ ...accessibility(element), element }))
+        .filter(({ role }) => role !== null);
+    const matches = candidates.filter(({ role, name }) => {
+        if (role !== target.role) {
+            return false;
+        }
+        if (typeof target.name === "string") {
+            return name === target.name;
+        }
+        return new RegExp(target.name.source, target.name.flags).test(name);
+    });
+    const found = matches[0];
+    if (matches.length === 1 && found) {
+        return found.element;
+    }
+    const listing = candidates.map(({ role, name }) => `  - ${role} named ${JSON.stringify(name)}`).join("\n");
+    throw new Error(`The screen has ${matches.length} matches for ${targetName(target)}.\nhelp: Use a role and name for exactly one visible target.\nCandidates on screen:\n${listing || "  (none)"}`);
+}
+//# sourceMappingURL=screenAccessibility.js.map

package/dist/server/internal/screenAccessibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenAccessibility.js","sourceRoot":"","sources":["../../../src/server/internal/screenAccessibility.ts"],"names":[],"mappings":"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"}

package/dist/server/internal/screenElements.d.ts

@@ -1,9 +1,10 @@
+import type { ScreenTarget } from "#screenDriver.ts";
 export declare function screenElements(root: () => HTMLElement): {
-    element: (selector: string) => HTMLElement;
-    enabled: (found: HTMLElement, selector: string) => void;
-    enter: (selector: string, value: string) => void;
-    form: (selector: string) => HTMLFormElement;
-    input: (selector: string) => HTMLInputElement | HTMLTextAreaElement;
+    element: (selector: ScreenTarget) => HTMLElement;
+    enabled: (found: HTMLElement, selector: ScreenTarget) => void;
+    enter: (selector: ScreenTarget, value: string) => void;
+    form: (selector: ScreenTarget) => HTMLFormElement;
+    input: (selector: ScreenTarget) => HTMLInputElement | HTMLTextAreaElement;
     rendered: (found: HTMLElement, selector: string) => HTMLElement;
 };
 //# sourceMappingURL=screenElements.d.ts.map

package/dist/server/internal/screenElements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenElements.d.ts","sourceRoot":"","sources":["../../../src/server/internal/screenElements.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,WAAW;wBAa1B,MAAM;qBAiBT,WAAW,YAAY,MAAM;sBAQlC,MAAM,SAAS,MAAM;qBAYtB,MAAM;sBA3BC,MAAM;sBAtBN,WAAW,YAAY,MAAM;EA4DtD"}
+{"version":3,"file":"screenElements.d.ts","sourceRoot":"","sources":["../../../src/server/internal/screenElements.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,WAAW;wBAO1B,YAAY;qBAsBf,WAAW,YAAY,YAAY;sBAQxC,YAAY,SAAS,MAAM;qBAY5B,YAAY;sBA7BL,YAAY;sBAnBZ,WAAW,YAAY,MAAM;EA2DtD"}

package/dist/server/internal/screenElements.js

@@ -1,17 +1,15 @@
+import { isRendered, roleElement, targetName } from "#internal/screenAccessibility.ts";
 export function screenElements(root) {
     function rendered(found, selector) {
-        const visibility = getComputedStyle(found).visibility;
-        let hidden = visibility === "hidden" || visibility === "collapse";
-        for (let ancestor = found; ancestor; ancestor = ancestor.parentElement) {
-            const style = getComputedStyle(ancestor);
-            hidden ||= Boolean(ancestor.hidden) || style.display === "none" || style.contentVisibility === "hidden";
-        }
-        if (hidden) {
+        if (!isRendered(found)) {
             throw new Error(`The screen's ${selector} is not rendered.\nhelp: Reveal the target and its ancestors before acting on or reading it.`);
         }
         return found;
     }
     function element(selector) {
+        if (typeof selector !== "string") {
+            return roleElement(root(), selector);
+        }
         const matches = root().querySelectorAll(selector);
         const found = matches[0];
         if (matches.length !== 1 || found === undefined) {
@@ -22,13 +20,13 @@ export function screenElements(root) {
     function input(selector) {
         const found = element(selector);
         if (!(found instanceof HTMLInputElement || found instanceof HTMLTextAreaElement)) {
-            throw new Error(`The screen's ${selector} is not a text field.\nhelp: Select a rendered input or textarea to enter or read a value.`);
+            throw new Error(`The screen's ${targetName(selector)} is not a text field.\nhelp: Select a rendered input or textarea to enter or read a value.`);
         }
         return found;
     }
     function enabled(found, selector) {
         if (found.matches(":disabled") || found.closest("[inert]")) {
-            throw new Error(`The screen's ${selector} is disabled.\nhelp: Wait for the app to enable the control before acting on it.`);
+            throw new Error(`The screen's ${targetName(selector)} is disabled.\nhelp: Wait for the app to enable the control before acting on it.`);
         }
     }
     return {
@@ -38,7 +36,7 @@ export function screenElements(root) {
             const field = input(selector);
             enabled(field, selector);
             if (field.readOnly) {
-                throw new Error(`The screen's ${selector} is read-only.\nhelp: Select an editable input or textarea.`);
+                throw new Error(`The screen's ${targetName(selector)} is read-only.\nhelp: Select an editable input or textarea.`);
             }
             field.focus();
             const prototype = field instanceof HTMLInputElement ? HTMLInputElement.prototype : HTMLTextAreaElement.prototype;
@@ -49,7 +47,7 @@ export function screenElements(root) {
         form: (selector) => {
             const found = element(selector);
             if (!(found instanceof HTMLFormElement)) {
-                throw new Error(`The screen's ${selector} is not a form.\nhelp: Select a rendered form to submit.`);
+                throw new Error(`The screen's ${targetName(selector)} is not a form.\nhelp: Select a rendered form to submit.`);
             }
             enabled(found, selector);
             return found;

package/dist/server/internal/screenElements.js.map

@@ -1 +1 @@
-{"version":3,"file":"screenElements.js","sourceRoot":"","sources":["../../../src/server/internal/screenElements.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"screenElements.js","sourceRoot":"","sources":["../../../src/server/internal/screenElements.ts"],"names":[],"mappings":"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"}

package/dist/server/screenDriver.d.ts

@@ -1,4 +1,8 @@
 import { Effect } from "effect";
+export type ScreenTarget = string | {
+    readonly role: string;
+    readonly name: string | RegExp;
+};
 export interface ScreenDriverOptions {
     readonly act?: (action: () => Promise<void>) => PromiseLike<void>;
     readonly pending: () => boolean;
@@ -8,17 +12,17 @@ export interface ScreenDriverOptions {
 }
 export type ScreenDriver = ReturnType<typeof screenDriver>;
 export declare function screenDriver({ root, pending, tell, act, timeoutMs }: ScreenDriverOptions): {
-    accessible: (selector: string) => {
+    accessible: (selector: string | Element) => {
         name: string;
         role: string | null;
     };
-    click: (selector: string) => Effect.Effect<void, never, never>;
-    enter: (selector: string, value: string) => Effect.Effect<void, never, never>;
+    click: (selector: ScreenTarget) => Effect.Effect<void, never, never>;
+    enter: (selector: ScreenTarget, value: string) => Effect.Effect<void, never, never>;
     settle: (options?: {
         readonly timeoutMs?: number;
     }) => Effect.Effect<void, never, never>;
-    submit: (selector?: string) => Effect.Effect<void, never, never>;
-    text: (selector?: string) => string;
-    value: (selector: string) => string;
+    submit: (selector?: ScreenTarget) => Effect.Effect<void, never, never>;
+    text: (selector?: ScreenTarget) => string;
+    value: (selector: ScreenTarget) => string;
 };
 //# sourceMappingURL=screenDriver.d.ts.map

package/dist/server/screenDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenDriver.d.ts","sourceRoot":"","sources":["../../src/server/screenDriver.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,WAAW,CAAC,IAAI,CAAC,CAAC;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAE3D,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAA0B,EAAE,SAAgB,EAAE,EAAE,mBAAmB;2BAgC9F,MAAM;;;;sBAMX,MAAM;sBAON,MAAM,SAAS,MAAM;uBApCf;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;;sBAuCrC,MAAM;sBAKN,MAAM;EAMzB"}
+{"version":3,"file":"screenDriver.d.ts","sourceRoot":"","sources":["../../src/server/screenDriver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC;AAE9F,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,WAAW,CAAC,IAAI,CAAC,CAAC;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAE3D,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAA0B,EAAE,SAAgB,EAAE,EAAE,mBAAmB;2BAgC9F,MAAM,GAAG,OAAO;;;;sBASrB,YAAY;sBAOZ,YAAY,SAAS,MAAM;uBAvCrB;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;wBAyCpC,YAAY;sBACb,YAAY;sBAKZ,YAAY;EAM/B"}

package/dist/server/screenDriver.js

@@ -1,6 +1,6 @@
-import { computeAccessibleName, getRole } from "dom-accessibility-api";
 import { Effect } from "effect";
 import { withLive } from "@shivaedev/effect-test/withLive.ts";
+import { accessibility, targetName } from "#internal/screenAccessibility.ts";
 import { screenElements } from "#internal/screenElements.ts";
 export function screenDriver({ root, pending, tell, act = (action) => action(), timeoutMs = 3000 }) {
     const currentRoot = typeof root === "function" ? root : () => root;
@@ -31,28 +31,31 @@ export function screenDriver({ root, pending, tell, act = (action) => action(),
     }
     return {
         accessible: (selector) => {
+            if (typeof selector !== "string") {
+                return accessibility(selector);
+            }
             const element = elements.element(selector);
-            const accessible = { name: computeAccessibleName(element), role: getRole(element) };
+            const accessible = accessibility(element);
             tell(`read the accessibility of ${selector}: ${JSON.stringify(accessible)}`);
             return accessible;
         },
-        click: (selector) => perform(`click ${selector}`, () => {
+        click: (selector) => perform(`click ${targetName(selector)}`, () => {
             const element = elements.element(selector);
             elements.enabled(element, selector);
             element.focus();
             element.click();
         }),
-        enter: (selector, value) => perform(`enter a value in ${selector}`, () => elements.enter(selector, value)),
+        enter: (selector, value) => perform(`enter a value in ${targetName(selector)}`, () => elements.enter(selector, value)),
         settle,
-        submit: (selector = "form") => perform(`submit ${selector}`, () => elements.form(selector).requestSubmit()),
+        submit: (selector = "form") => perform(`submit ${targetName(selector)}`, () => elements.form(selector).requestSubmit()),
         text: (selector) => {
             const text = (selector === undefined ? elements.rendered(currentRoot(), "root") : elements.element(selector)).innerText;
-            tell(`read ${selector ?? "the screen"}: ${JSON.stringify(text)}`);
+            tell(`read ${selector === undefined ? "the screen" : targetName(selector)}: ${JSON.stringify(text)}`);
             return text;
         },
         value: (selector) => {
             const value = elements.input(selector).value;
-            tell(`read the value in ${selector}: ${JSON.stringify(value)}`);
+            tell(`read the value in ${targetName(selector)}: ${JSON.stringify(value)}`);
             return value;
         },
     };

package/dist/server/screenDriver.js.map

@@ -1 +1 @@
-{"version":3,"file":"screenDriver.js","sourceRoot":"","sources":["../../src/server/screenDriver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"screenDriver.js","sourceRoot":"","sources":["../../src/server/screenDriver.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/test-story",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Tests that read like stories over the real engine: a story kit per engine with its own it, traits per feature, and a failure that prints the story, where it stopped and the engine's state",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/test-story#readme",
   "bugs": {
@@ -46,7 +46,7 @@
   },
   "devDependencies": {
     "@effect/vitest": "4.0.4",
-    "@shivaedev/quality": "0.28.1",
+    "@shivaedev/quality": "0.29.0",
     "@types/node": "24.19.2",
     "effect": "4.0.4",
     "happy-dom": "20.14.6",

package/src/server/internal/screenAccessibility.ts

@@ -0,0 +1,50 @@
+import { computeAccessibleName, getRole, isInaccessible } from "dom-accessibility-api";
+import type { ScreenTarget } from "#screenDriver.ts";
+
+export function accessibility(element: Element) {
+	return { name: computeAccessibleName(element), role: getRole(element) };
+}
+
+export function targetName(target: ScreenTarget): string {
+	return typeof target === "string"
+		? target
+		: `${target.role} named ${typeof target.name === "string" ? JSON.stringify(target.name) : String(target.name)}`;
+}
+
+export function isRendered(found: HTMLElement) {
+	const visibility = getComputedStyle(found).visibility;
+	if (visibility === "hidden" || visibility === "collapse") {
+		return false;
+	}
+	for (let ancestor: HTMLElement | null = found; ancestor; ancestor = ancestor.parentElement) {
+		const style = getComputedStyle(ancestor);
+		if (ancestor.hidden || style.display === "none" || style.contentVisibility === "hidden") {
+			return false;
+		}
+	}
+	return true;
+}
+
+export function roleElement(root: HTMLElement, target: Exclude<ScreenTarget, string>) {
+	const candidates = Array.from(root.querySelectorAll<HTMLElement>("*"))
+		.filter((element) => isRendered(element) && !isInaccessible(element))
+		.map((element) => ({ ...accessibility(element), element }))
+		.filter(({ role }) => role !== null);
+	const matches = candidates.filter(({ role, name }) => {
+		if (role !== target.role) {
+			return false;
+		}
+		if (typeof target.name === "string") {
+			return name === target.name;
+		}
+		return new RegExp(target.name.source, target.name.flags).test(name);
+	});
+	const found = matches[0];
+	if (matches.length === 1 && found) {
+		return found.element;
+	}
+	const listing = candidates.map(({ role, name }) => `  - ${role} named ${JSON.stringify(name)}`).join("\n");
+	throw new Error(
+		`The screen has ${matches.length} matches for ${targetName(target)}.\nhelp: Use a role and name for exactly one visible target.\nCandidates on screen:\n${listing || "  (none)"}`,
+	);
+}

package/src/server/internal/screenElements.ts

@@ -1,17 +1,17 @@
+import { isRendered, roleElement, targetName } from "#internal/screenAccessibility.ts";
+import type { ScreenTarget } from "#screenDriver.ts";
+
 export function screenElements(root: () => HTMLElement) {
 	function rendered(found: HTMLElement, selector: string) {
-		const visibility = getComputedStyle(found).visibility;
-		let hidden = visibility === "hidden" || visibility === "collapse";
-		for (let ancestor: HTMLElement | null = found; ancestor; ancestor = ancestor.parentElement) {
-			const style = getComputedStyle(ancestor);
-			hidden ||= Boolean(ancestor.hidden) || style.display === "none" || style.contentVisibility === "hidden";
-		}
-		if (hidden) {
+		if (!isRendered(found)) {
 			throw new Error(`The screen's ${selector} is not rendered.\nhelp: Reveal the target and its ancestors before acting on or reading it.`);
 		}
 		return found;
 	}
-	function element(selector: string) {
+	function element(selector: ScreenTarget) {
+		if (typeof selector !== "string") {
+			return roleElement(root(), selector);
+		}
 		const matches = root().querySelectorAll<HTMLElement>(selector);
 		const found = matches[0];
 		if (matches.length !== 1 || found === undefined) {
@@ -21,26 +21,28 @@ export function screenElements(root: () => HTMLElement) {
 		}
 		return rendered(found, selector);
 	}
-	function input(selector: string) {
+	function input(selector: ScreenTarget) {
 		const found = element(selector);
 		if (!(found instanceof HTMLInputElement || found instanceof HTMLTextAreaElement)) {
-			throw new Error(`The screen's ${selector} is not a text field.\nhelp: Select a rendered input or textarea to enter or read a value.`);
+			throw new Error(
+				`The screen's ${targetName(selector)} is not a text field.\nhelp: Select a rendered input or textarea to enter or read a value.`,
+			);
 		}
 		return found;
 	}
-	function enabled(found: HTMLElement, selector: string) {
+	function enabled(found: HTMLElement, selector: ScreenTarget) {
 		if (found.matches(":disabled") || found.closest("[inert]")) {
-			throw new Error(`The screen's ${selector} is disabled.\nhelp: Wait for the app to enable the control before acting on it.`);
+			throw new Error(`The screen's ${targetName(selector)} is disabled.\nhelp: Wait for the app to enable the control before acting on it.`);
 		}
 	}
 	return {
 		element,
 		enabled,
-		enter: (selector: string, value: string) => {
+		enter: (selector: ScreenTarget, value: string) => {
 			const field = input(selector);
 			enabled(field, selector);
 			if (field.readOnly) {
-				throw new Error(`The screen's ${selector} is read-only.\nhelp: Select an editable input or textarea.`);
+				throw new Error(`The screen's ${targetName(selector)} is read-only.\nhelp: Select an editable input or textarea.`);
 			}
 			field.focus();
 			const prototype = field instanceof HTMLInputElement ? HTMLInputElement.prototype : HTMLTextAreaElement.prototype;
@@ -48,10 +50,10 @@ export function screenElements(root: () => HTMLElement) {
 			field.dispatchEvent(new Event("input", { bubbles: true }));
 			field.dispatchEvent(new Event("change", { bubbles: true }));
 		},
-		form: (selector: string) => {
+		form: (selector: ScreenTarget) => {
 			const found = element(selector);
 			if (!(found instanceof HTMLFormElement)) {
-				throw new Error(`The screen's ${selector} is not a form.\nhelp: Select a rendered form to submit.`);
+				throw new Error(`The screen's ${targetName(selector)} is not a form.\nhelp: Select a rendered form to submit.`);
 			}
 			enabled(found, selector);
 			return found;

package/src/server/screenDriver.ts

@@ -1,8 +1,10 @@
-import { computeAccessibleName, getRole } from "dom-accessibility-api";
 import { Effect } from "effect";
 import { withLive } from "@shivaedev/effect-test/withLive.ts";
+import { accessibility, targetName } from "#internal/screenAccessibility.ts";
 import { screenElements } from "#internal/screenElements.ts";
 
+export type ScreenTarget = string | { readonly role: string; readonly name: string | RegExp };
+
 export interface ScreenDriverOptions {
 	readonly act?: (action: () => Promise<void>) => PromiseLike<void>;
 	readonly pending: () => boolean;
@@ -45,30 +47,33 @@ export function screenDriver({ root, pending, tell, act = (action) => action(),
 		return withLive(wait.pipe(Effect.timeoutOrElse({ duration: limit, orElse: timedOut })));
 	}
 	return {
-		accessible: (selector: string) => {
+		accessible: (selector: string | Element) => {
+			if (typeof selector !== "string") {
+				return accessibility(selector);
+			}
 			const element = elements.element(selector);
-			const accessible = { name: computeAccessibleName(element), role: getRole(element) };
+			const accessible = accessibility(element);
 			tell(`read the accessibility of ${selector}: ${JSON.stringify(accessible)}`);
 			return accessible;
 		},
-		click: (selector: string) =>
-			perform(`click ${selector}`, () => {
+		click: (selector: ScreenTarget) =>
+			perform(`click ${targetName(selector)}`, () => {
 				const element = elements.element(selector);
 				elements.enabled(element, selector);
 				element.focus();
 				element.click();
 			}),
-		enter: (selector: string, value: string) => perform(`enter a value in ${selector}`, () => elements.enter(selector, value)),
+		enter: (selector: ScreenTarget, value: string) => perform(`enter a value in ${targetName(selector)}`, () => elements.enter(selector, value)),
 		settle,
-		submit: (selector = "form") => perform(`submit ${selector}`, () => elements.form(selector).requestSubmit()),
-		text: (selector?: string) => {
+		submit: (selector: ScreenTarget = "form") => perform(`submit ${targetName(selector)}`, () => elements.form(selector).requestSubmit()),
+		text: (selector?: ScreenTarget) => {
 			const text = (selector === undefined ? elements.rendered(currentRoot(), "root") : elements.element(selector)).innerText;
-			tell(`read ${selector ?? "the screen"}: ${JSON.stringify(text)}`);
+			tell(`read ${selector === undefined ? "the screen" : targetName(selector)}: ${JSON.stringify(text)}`);
 			return text;
 		},
-		value: (selector: string) => {
+		value: (selector: ScreenTarget) => {
 			const value = elements.input(selector).value;
-			tell(`read the value in ${selector}: ${JSON.stringify(value)}`);
+			tell(`read the value in ${targetName(selector)}: ${JSON.stringify(value)}`);
 			return value;
 		},
 	};