@orkestrel/test 0.0.14 → 0.0.16

package/README.md

@@ -9,7 +9,8 @@ enough packages had already written their own; the guide's [Limits](guides/test.
 states that rule, what it excluded, and the one door the journey layer came through instead. Nothing
 here runs in production code. Part of the `@orkestrel` line.
 
-It has **zero runtime dependencies**, and no exported signature names an `@orkestrel/*` type. Both
+This package runtime-depends on `@orkestrel/contract` for the outcome type `retryUntil` reads
+internally. That type is not re-exported. No exported signature names an `@orkestrel/*` type. Both
 rules exist for one reason: a test helper hands its types straight into the consumer's assertions,
 and a second copy of a package inside its own repository makes the compiler read one type as two.
 

package/dist/src/browser/index.d.ts

@@ -1250,6 +1250,65 @@ export declare function readFocus(): string | undefined;
  */
 export declare function readFrame(path: string): Promise<FrameReading>;
 
+/**
+ * Reads the topmost element at one element's bounding-box centre.
+ *
+ * @param element - The element whose bounding-box centre is the point to read.
+ * @returns The element the owner document's hit test names at that point, or `undefined` where the
+ * point lies outside that viewport or reaches nothing.
+ *
+ * @remarks
+ * This reads one point and nothing else: the centre of the element's own bounding box, hit-tested
+ * against `element.ownerDocument`. That point is where a thumb aimed at the middle of what it sees
+ * lands, and the arrangements that take it away are the ones {@link isReachable} cannot see: a
+ * sticky masthead covering a control that was scrolled to, and a wrapped inline target, whose
+ * per-line rectangles leave a gap the single bounding box spans and whose centre falls in that gap
+ * on the ancestor. `isReachable` reads `checkVisibility`, geometry, and the focus order, and each
+ * arrangement passes all three while a click at that point misses.
+ *
+ * It does not predict where the installed driver clicks. `playwright-core@1.63.0` clips each
+ * content quad to the viewport, drops every quad left without area, and takes the midpoint of the
+ * first quad that survives — `_clickablePoint` at `playwright-core/lib/coreBundle.js:20084`,
+ * reached from the locator `click` the Vitest provider delegates to. For the wrapped target the
+ * first surviving quad is the first line box, so the driver aims inside the link while this centre
+ * sits in the gap. Read a result as the answer for the point this names, and for no other.
+ *
+ * It returns the node rather than a verdict, because the node is the diagnosis: a caller narrows
+ * the result, rules on `link.contains(hit)`, and names what came back — the list item rather than
+ * the link, the masthead rather than the control.
+ *
+ * Pass {@link isRendered} and {@link isReachable} before reading, because neither answer means
+ * anything on an element that failed them. An element the document does not render measures a zero
+ * rectangle at the origin, and a zero-area element measures a point on its own edge; each is
+ * hit-tested like any other point and names whatever paints there — the surrounding container for
+ * a control clipped inside one, and the document body for a rectangle collapsed at the origin.
+ * `contains` is then false, and a caller that skipped the gates reports a cover that is not there.
+ *
+ * A returned node carries silences of its own. A cover painted with `pointer-events: none` is
+ * absent from the hit test, so the reading names the element underneath it and the caller reads
+ * reachable for a cover a person can see. An element inside a shadow tree retargets, in an open
+ * root and a closed one alike: the document-level hit test names the host, the inner element does
+ * not contain the host, and the caller reads the element's own host as a cover. Ask
+ * `element.getRootNode()` for its own `elementFromPoint` where the subject sits in a shadow tree.
+ *
+ * `undefined` carries one silence: a centre outside the viewport reads the same as a centre that
+ * reaches nothing. {@link isOutsideViewport} does not separate them, because it asks whether the
+ * whole rectangle misses the viewport while this asks where one point lands — a rectangle at
+ * `left: -80` with `width: 100` has its right edge at 20, so that predicate reports false while the
+ * centre at -30 reads `undefined` here. The two also measure different windows: the predicate reads
+ * the global `window`, and this reads `element.ownerDocument`. Compare the centre against that
+ * document's own viewport where the distinction is the subject.
+ *
+ * @example
+ * ```ts
+ * const link = requireValue(container.querySelector('a'))
+ * const hit = readHit(link)
+ * // False for a wrapped link whose centre sits between its line boxes.
+ * hit !== undefined && link.contains(hit)
+ * ```
+ */
+export declare function readHit(element: Element): Element | undefined;
+
 /**
  * Collects the painted layers standing between one element and the surface it sits on.
  *

package/dist/src/browser/index.js

@@ -269,6 +269,67 @@ function isRendered(element) {
 	return getComputedStyle(element).visibility !== "hidden";
 }
 /**
+* Reads the topmost element at one element's bounding-box centre.
+*
+* @param element - The element whose bounding-box centre is the point to read.
+* @returns The element the owner document's hit test names at that point, or `undefined` where the
+* point lies outside that viewport or reaches nothing.
+*
+* @remarks
+* This reads one point and nothing else: the centre of the element's own bounding box, hit-tested
+* against `element.ownerDocument`. That point is where a thumb aimed at the middle of what it sees
+* lands, and the arrangements that take it away are the ones {@link isReachable} cannot see: a
+* sticky masthead covering a control that was scrolled to, and a wrapped inline target, whose
+* per-line rectangles leave a gap the single bounding box spans and whose centre falls in that gap
+* on the ancestor. `isReachable` reads `checkVisibility`, geometry, and the focus order, and each
+* arrangement passes all three while a click at that point misses.
+*
+* It does not predict where the installed driver clicks. `playwright-core@1.63.0` clips each
+* content quad to the viewport, drops every quad left without area, and takes the midpoint of the
+* first quad that survives — `_clickablePoint` at `playwright-core/lib/coreBundle.js:20084`,
+* reached from the locator `click` the Vitest provider delegates to. For the wrapped target the
+* first surviving quad is the first line box, so the driver aims inside the link while this centre
+* sits in the gap. Read a result as the answer for the point this names, and for no other.
+*
+* It returns the node rather than a verdict, because the node is the diagnosis: a caller narrows
+* the result, rules on `link.contains(hit)`, and names what came back — the list item rather than
+* the link, the masthead rather than the control.
+*
+* Pass {@link isRendered} and {@link isReachable} before reading, because neither answer means
+* anything on an element that failed them. An element the document does not render measures a zero
+* rectangle at the origin, and a zero-area element measures a point on its own edge; each is
+* hit-tested like any other point and names whatever paints there — the surrounding container for
+* a control clipped inside one, and the document body for a rectangle collapsed at the origin.
+* `contains` is then false, and a caller that skipped the gates reports a cover that is not there.
+*
+* A returned node carries silences of its own. A cover painted with `pointer-events: none` is
+* absent from the hit test, so the reading names the element underneath it and the caller reads
+* reachable for a cover a person can see. An element inside a shadow tree retargets, in an open
+* root and a closed one alike: the document-level hit test names the host, the inner element does
+* not contain the host, and the caller reads the element's own host as a cover. Ask
+* `element.getRootNode()` for its own `elementFromPoint` where the subject sits in a shadow tree.
+*
+* `undefined` carries one silence: a centre outside the viewport reads the same as a centre that
+* reaches nothing. {@link isOutsideViewport} does not separate them, because it asks whether the
+* whole rectangle misses the viewport while this asks where one point lands — a rectangle at
+* `left: -80` with `width: 100` has its right edge at 20, so that predicate reports false while the
+* centre at -30 reads `undefined` here. The two also measure different windows: the predicate reads
+* the global `window`, and this reads `element.ownerDocument`. Compare the centre against that
+* document's own viewport where the distinction is the subject.
+*
+* @example
+* ```ts
+* const link = requireValue(container.querySelector('a'))
+* const hit = readHit(link)
+* // False for a wrapped link whose centre sits between its line boxes.
+* hit !== undefined && link.contains(hit)
+* ```
+*/
+function readHit(element) {
+	const rectangle = element.getBoundingClientRect();
+	return element.ownerDocument.elementFromPoint(rectangle.left + rectangle.width / 2, rectangle.top + rectangle.height / 2) ?? void 0;
+}
+/**
 * Computes the pattern that matches one accessible name a decorative glyph may sit beside.
 *
 * @param name - The exact accessible name a person reads, whitespace runs collapsed on the way in.
@@ -2246,6 +2307,6 @@ function createJournal() {
 	};
 }
 //#endregion
-export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, blendColor, build, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, createChannel, createDragEvent, createJournal, createPointerEvent, createPortfolio, describeFocus, describeTree, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, readBackdrop, readCascade, readClasses, readContrast, readFocus, readFrame, readLayers, readName, readPage, readPerception, readPixels, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releasePane, removeDatabase, render, resolveAccessible, resolveRendered, stagePane, traverseAccessible, typeAccessible, typeInput, waitForFrame };
+export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, blendColor, build, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, createChannel, createDragEvent, createJournal, createPointerEvent, createPortfolio, describeFocus, describeTree, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, readBackdrop, readCascade, readClasses, readContrast, readFocus, readFrame, readHit, readLayers, readName, readPage, readPerception, readPixels, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releasePane, removeDatabase, render, resolveAccessible, resolveRendered, stagePane, traverseAccessible, typeAccessible, typeInput, waitForFrame };
 
 //# sourceMappingURL=index.js.map