//#endregion
//#region src/dataTypes.d.ts
type Optional<T> = T | undefined;
type Nullable<T> = T | null;
//#endregion
//#region src/geometry/BoundingRect.d.ts
/**
 * An element's axis-aligned bounding box in viewport pixels — `x`/`y` is the
 * top-left corner, matching the shape of `DOMRect`/`getBoundingClientRect()`.
 */
interface BoundingRect {
  x: number;
  y: number;
  width: number;
  height: number;
}
//#endregion
//#region src/geometry/Point.d.ts
/**
 * A 2D coordinate, in pixels, relative to the viewport — the shape used for
 * drag deltas and other point-based interactions (see {@link PointerActions.drag}).
 */
interface Point {
  x: number;
  y: number;
}
//#endregion
//#region src/interactor/CssProperty.d.ts
/**
 * Supported CSS Properties
 */
type CssProperty = Exclude<keyof CSSStyleDeclaration, 'parentRule' | 'length' | 'getPropertyPriority' | 'getPropertyValue' | 'item' | 'removeProperty' | 'setProperty'>;
//#endregion
//#region src/interactor/EnterTextOption.d.ts
interface EnterTextOption {
  /**
   * Append text to the target, default to false
   */
  append: boolean;
}
//#endregion
//#region src/interactor/FocusOption.d.ts
interface BlurOption {}
interface FocusOption {}
//#endregion
//#region src/drivers/WaitForOption.d.ts
type WaitForCondition = 'attached' | 'visible' | 'detached' | 'hidden';
interface WaitForOption {
  /**
   * The condition to wait for the component to reach
   * 'attached' - the component is attached to the DOM
   * 'detached' - the component is not attached to the DOM
   * 'visible' - the component is attached to the DOM and visible
   * 'hidden' - the component is attached to the DOM but not visible
   * @default 'attached'
   */
  condition: WaitForCondition;
  /**
   * The number of milliseconds to wait before timing out
   * @default 30000
   */
  timeoutMs: number;
  /**
   * Whether to log debug information during the wait operation.
   * When enabled, logs each probe's value and whether the condition was met.
   * @default false
   */
  debug: boolean;
}
declare const defaultWaitForOption: Readonly<WaitForOption>;
//#endregion
//#region src/locators/LocatorRelativePosition.d.ts
/**
 * Possible relative positions for a locator in relation to the base element.
 *
 * - `'Root'` — resolve from the document root, ignoring the parent context.
 * - `'Descendant'` — anywhere beneath the parent (CSS descendant combinator,
 *   a space). The default for most builders (`byChecked` is the exception — it
 *   defaults to `'Same'` so it composes onto the input it matches).
 * - `'Same'` — the same element as the parent (compound onto it, no combinator).
 * - `'Child'` — a direct child of the parent (CSS child combinator, `>`), so a
 *   nested descendant with the same selector is not matched. Expressible through
 *   the locator model rather than only via a raw `byCssSelector` escape hatch. The
 *   combinator is emitted for you, so the selector fragment must NOT itself start
 *   with `>` (pass `byCssSelector('.item', 'Child')`, not
 *   `byCssSelector('> .item', 'Child')`, which would double the combinator).
 */
type LocatorRelativePosition = 'Root' | 'Descendant' | 'Same' | 'Child';
//#endregion
//#region src/locators/PartLocator.d.ts
/**
 * How to find an element: always a chain of {@link CssLocator}s, reduced to
 * **one CSS selector** via `locatorUtil.toCssSelector`, which the interactor
 * runs against the DOM. A locator built by a single `by*` builder (e.g.
 * `byDataTestId('submit')`) is simply a one-element chain — there is no
 * separate "bare locator" shape to normalize away. An empty chain (`[]`) is
 * also valid: it is the engine-root locator, and `toCssSelector` reduces it to
 * the portable document-root selector rather than throwing (see #1048).
 *
 * **1.0 boundary — CSS only.** The locator model is deliberately closed to CSS:
 * every builder (`byRole`, `byAriaLabel`, `byAttribute`, `byCssSelector`, …)
 * emits a CSS fragment, same-element matchers compose via {@link
 * locatorUtil.and}, and `byCssSelector` is the raw-CSS escape hatch. XPath,
 * text, and computed-ARIA-name engines are out of scope — see
 * [ADR-008](https://github.com/atomic-testing/atomic-testing/blob/main/agent-docs/adr/008-css-dom-only-locator-boundary.md).
 *
 * **2.0 reshape (#1058).** `PartLocator` used to be `CssLocator | CssLocator[]`,
 * forcing an `isChain`/`toChain` normalization step at every consumer. It is
 * now always `CssLocator[]`, so every builder returns a chain and every
 * consumer can index/slice/concat it directly — see
 * [ADR-017](https://github.com/atomic-testing/atomic-testing/blob/main/agent-docs/adr/017-part-locator-chain-reshape.md).
 *
 * **Readonly.** A driver hands its own locator out by reference, so a mutable
 * array would let a caller's `push` permanently corrupt the driver. Every
 * `locatorUtil` operation is already non-mutating (`concat`/`map`/`slice`), so
 * this costs nothing today — and `readonly T[]` is not assignable to `T[]`, so
 * tightening it after the 1.0 tag would be a major.
 */
type PartLocator = readonly CssLocator[];
//#endregion
//#region src/locators/byAriaLabel.d.ts
type ByAriaLabelSource = {
  _id: 'byAriaLabel';
  value: string;
  relative: LocatorRelativePosition;
};
/**
 * Locate elements by the verbatim value of their `aria-label` attribute.
 *
 * This matches the literal `aria-label` attribute only — it does NOT resolve the
 * computed accessible name (from `aria-labelledby`, an associated `<label>`, or
 * text content), which is not CSS-expressible and is the job of the forthcoming
 * name-aware `findByRole` (deferred — see #923).
 *
 * Most commonly composed with {@link byRole} on the SAME element to tell two
 * same-role siblings apart without relying on unstable (e.g. StyleX-hashed) class
 * names. Use {@link locatorUtil.and} to compound the matchers onto one element:
 *
 * ```ts
 * import { byAriaLabel, byRole, locatorUtil } from '@atomic-testing/core';
 * const openButton = locatorUtil.and(byRole('button'), byAriaLabel('Open'));
 * const closeButton = locatorUtil.and(byRole('button'), byAriaLabel('Close'));
 * ```
 *
 * @param value - Verbatim `aria-label` to match.
 * @param relative - Relative position of the locator. Defaults to `'Descendant'`.
 * @example
 * ```ts
 * const close = byAriaLabel('Close');
 * ```
 */
declare function byAriaLabel(value: string, relative?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/byAttribute.d.ts
type ByAttributeSource = {
  _id: 'byAttribute';
  name: string;
  value: string;
  relativeTo: LocatorRelativePosition;
};
/**
 * Locate an element by a specific attribute and value.
 *
 * @param name - The attribute name.
 * @param value - The attribute value to match.
 * @param relativeTo - Relative position of the locator. Defaults to
 * `'Descendant'`.
 * @example
 * ```ts
 * const dialog = byAttribute('role', 'dialog');
 * ```
 */
declare function byAttribute(name: string, value: string, relativeTo?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/byChecked.d.ts
type ByCheckedSource = {
  _id: 'byChecked';
  checked: boolean;
  relative: LocatorRelativePosition;
};
/**
 * Locate a checkbox or radio input based on its checked state.
 *
 * @param checked - Whether the element should be checked. Defaults to `true`.
 * @param relative - Relative position for the locator. Defaults to
 * `'Same'` so it can be chained with the checkbox locator itself.
 * @example
 * ```ts
 * const unchecked = byChecked(false);
 * ```
 */
declare function byChecked(checked?: boolean, relative?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/byCssClass.d.ts
type ByCssClassSource = {
  _id: 'byCssClass';
  className: string | string[];
  relative: LocatorRelativePosition;
};
/**
 * Locate elements using their CSS class name.
 *
 * Providing multiple class names will result in a selector that matches
 * elements containing all the classes.
 *
 * @param className - One or more class names to match.
 * @param relativeTo - Relative position of the locator. Defaults to
 * `'Descendant'`.
 * @example
 * ```ts
 * const icon = byCssClass('MuiIcon-root');
 * const menuItem = byCssClass(['MuiListItem-root', 'active']);
 * ```
 */
declare function byCssClass(className: string | string[], relativeTo?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/byCssSelector.d.ts
type ByCssSelectorSource = {
  _id: 'byCssSelector';
  selector: string;
  relative: LocatorRelativePosition;
};
/**
 * Locate elements using a raw CSS selector string.
 *
 * This is a low level API and should be used when the other helper
 * locators cannot express the desired selector.
 *
 * @param selector - A CSS selector string.
 * @param relativeTo - Relative position of the locator. Defaults to
 * `'Descendant'`.
 * @example
 * ```ts
 * const activeItem = byCssSelector('.menu .item.active');
 * ```
 */
declare function byCssSelector(selector: string, relativeTo?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/byDataTestId.d.ts
type ByDataTestIdSource = {
  _id: 'byDataTestId';
  id: string | string[];
  relative: LocatorRelativePosition;
};
/**
 * Locate an element by its `data-testid` attribute.
 *
 * When an array of ids is provided, they will be chained as descendant
 * selectors in the resulting locator.
 *
 * @param id - Single id or an array of ids to match against the
 * `data-testid` attribute.
 * @param relativeTo - How the locator is related to the current locator in a
 * locator chain. Defaults to `'Descendant'`.
 * @example
 * ```ts
 * const submitButton = byDataTestId('submit');
 * const itemLabel = byDataTestId(['list', 'item-label']);
 * ```
 */
declare function byDataTestId(id: string | string[], relativeTo?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/byInputType.d.ts
type ByInputTypeSource = {
  _id: 'byInputType';
  type: string;
  relative: LocatorRelativePosition;
};
/**
 * Locate an `<input>` element by its `type` attribute.
 *
 * @param type - The value of the `type` attribute such as `text`, `checkbox`
 * or `radio`.
 * @param relative - Relative position of the locator. Defaults to
 * `'Descendant'`.
 * @example
 * ```ts
 * const passwordField = byInputType('password');
 * ```
 */
declare function byInputType(type: string, relative?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/byName.d.ts
type ByNameSource = {
  _id: 'byName';
  value: string;
  relative: LocatorRelativePosition;
};
/**
 * Locate elements using the value of their `name` attribute.
 *
 * @param value - Value of the `name` attribute to match.
 * @param relative - Relative position of the locator. Defaults to
 * `'Descendant'`.
 * @example
 * ```ts
 * const searchBox = byName('search');
 * ```
 */
declare function byName(value: string, relative?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/byRole.d.ts
type ByRoleSource = {
  _id: 'byRole';
  value: string;
  relative: LocatorRelativePosition;
};
/**
 * Locate elements by their ARIA `role` attribute.
 *
 * To additionally disambiguate two same-role elements by their accessible name,
 * compose with {@link byAriaLabel} (verbatim `aria-label`) on the SAME element
 * via {@link locatorUtil.and}:
 *
 * ```ts
 * import { byAriaLabel, byRole, locatorUtil } from '@atomic-testing/core';
 * const openButton = locatorUtil.and(byRole('button'), byAriaLabel('Open'));
 * ```
 *
 * Computed accessible names (`aria-labelledby` / `<label>` / text content) are
 * not CSS-expressible and are the job of the forthcoming name-aware `findByRole`
 * (deferred — see #923).
 *
 * @param value - The role value to match.
 * @param relative - Relative position of the locator. Defaults to
 * `'Descendant'`.
 * @example
 * ```ts
 * const dialog = byRole('dialog');
 * const root = byRole('presentation', 'Root');
 * ```
 */
declare function byRole(value: string, relative?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/byTagName.d.ts
type ByTagNameSource = {
  _id: 'byTagName';
  tagName: string;
  relative: LocatorRelativePosition;
};
/**
 * Locate elements by their HTML tag name.
 *
 * This locator is generally discouraged in favour of more stable
 * attributes such as `data-testid`.
 *
 * @param tagName - The tag name to match.
 * @param relative - Relative position of the locator. Defaults to
 * `'Descendant'`.
 * @example
 * ```ts
 * const headings = byTagName('h1');
 * ```
 */
declare function byTagName(tagName: string, relative?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/byValue.d.ts
type ByValueSource = {
  _id: 'byValue';
  value: string;
  relative: LocatorRelativePosition;
};
/**
 * Locate elements by the value of their `value` attribute.
 *
 * @param value - The value to match.
 * @param relative - Relative position of the locator. Defaults to
 * `'Descendant'`.
 * @example
 * ```ts
 * const option = byValue('option1');
 * ```
 */
declare function byValue(value: string, relative?: LocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/CssLocatorSource.d.ts
type CssLocatorSource = ByAriaLabelSource | ByAttributeSource | ByCheckedSource | ByCssClassSource | ByCssSelectorSource | ByDataTestIdSource | ByInputTypeSource | ByNameSource | ByRoleSource | ByTagNameSource | ByValueSource;
//#endregion
//#region src/locators/LocatorComplexity.d.ts
/**
 * - `'primitive'` — a single, static CSS fragment (`byRole`, `byAttribute`, …).
 * - `'linked'` — resolves at runtime by reading another element's value
 *   ({@link LinkedCssLocator}); cannot be folded into a static compound.
 * - `'accessibleRole'` — resolves by the ARIA role + COMPUTED accessible name
 *   ({@link AccessibleRoleLocator}, built by `findByRole`); has no CSS
 *   representation at all — see [ADR-008](https://github.com/atomic-testing/atomic-testing/blob/main/agent-docs/adr/008-css-dom-only-locator-boundary.md)
 *   and #923.
 */
type LocatorComplexity = 'primitive' | 'linked' | 'accessibleRole';
//#endregion
//#region src/locators/CssLocator.d.ts
interface CssLocatorInitializer {
  relative: LocatorRelativePosition;
  source: CssLocatorSource;
}
/**
 * The primitive `PartLocator` element: a single CSS selector, optionally
 * carrying its {@link LocatorRelativePosition} (how it composes with an
 * ancestor locator) and descriptive {@link CssLocatorSource}. Every `by*`
 * locator builder (`byDataTestId`, `byRole`, `byCssSelector`, ...) produces one
 * of these; a `PartLocator` chain is an array of them.
 */
declare class CssLocator {
  readonly selector: string;
  private _relativePosition;
  private _source?;
  constructor(selector: string, initializeValue?: Partial<CssLocatorInitializer>);
  get relative(): LocatorRelativePosition;
  get complexity(): LocatorComplexity;
  clone(override?: Partial<CssLocatorInitializer>): CssLocator;
}
//#endregion
//#region src/locators/AccessibleRoleLocator.d.ts
/**
 * The only two {@link LocatorRelativePosition} values `AccessibleRoleLocator`
 * resolution actually honors — `'Root'` escapes to the document root,
 * anything else (the `'Descendant'` default) scopes to the preceding chain
 * (or the interactor's own root when there is none). `'Same'`/`'Child'` have
 * no accname-search equivalent (`'Same'` means "compound onto the same
 * element," which conflicts with "search for a new element by name"; `'Child'`
 * would need result filtering `queryAllByRole`/`getByRole` don't offer) — this
 * narrower type makes passing them a compile error instead of a silent
 * fallback to `'Descendant'` behavior.
 */
type AccessibleRoleLocatorRelativePosition = Extract<LocatorRelativePosition, 'Root' | 'Descendant'>;
interface AccessibleRoleLocatorInitializer {
  name?: string;
  relative?: AccessibleRoleLocatorRelativePosition;
}
/**
 * A locator that resolves by ARIA role plus the COMPUTED accessible name (the
 * accname algorithm: `aria-labelledby` id-refs, an associated `<label>`,
 * wrapping/`title` text, and visible descendant text) — built by `findByRole`,
 * never directly.
 *
 * This is the one locator kind with NO CSS representation: the accessible name
 * is the output of a multi-node graph traversal that no CSS selector can
 * express (see [ADR-008](https://github.com/atomic-testing/atomic-testing/blob/main/agent-docs/adr/008-css-dom-only-locator-boundary.md)
 * and the design in [ADR 0001, Decision B](https://github.com/atomic-testing/atomic-testing/blob/main/docs/adr/0001-interactor-primitives-and-name-aware-role.md)).
 * `selector` (inherited from {@link CssLocator}) is therefore a
 * human-readable DIAGNOSTIC string only — e.g. `role=button name="Save"` — for
 * error messages; it is never run as CSS. Resolution instead happens inside
 * each interactor, backed by an engine that already implements accname:
 * `@testing-library/dom`'s `queryAllByRole` in `DOMInteractor`, Playwright's
 * `Locator.getByRole`/`Page.getByRole` in `PlaywrightInteractor`.
 *
 * `name` matching is always exact and case-sensitive, in BOTH engines — a
 * deliberate simplification, not an oversight. `@testing-library/dom`'s
 * `getByRole` only supports exact string comparison for a string `name` (no
 * substring/fuzzy mode exists in its public API for that case); Playwright's
 * `getByRole` defaults to fuzzy substring matching instead. Rather than expose
 * an `exact` toggle that only ONE engine could honor — a correctness trap for
 * a library whose entire contract is "the same suite runs identically in both
 * environments" — `PlaywrightInteractor` always passes `exact: true`,
 * matching jsdom's only mode.
 *
 * Composition: an `AccessibleRoleLocator` MUST be the last (or only) segment
 * of a {@link PartLocator} chain — everything before it resolves normally (by
 * CSS) to a scope container the accname search runs within; nothing may
 * follow it (see `locatorUtil.splitAtAccessibleRoleLocator`). Its
 * `complexity` is `'accessibleRole'`, distinct from `'primitive'`, so
 * `locatorUtil.and()` — same-element CSS compounding — already rejects it via
 * the same "primitive chains only" guard that rejects a linked locator.
 *
 * @see findByRole
 */
declare class AccessibleRoleLocator extends CssLocator {
  readonly role: string;
  private readonly _name?;
  constructor(role: string, initializeValue: AccessibleRoleLocatorInitializer & Partial<CssLocatorInitializer>);
  get complexity(): LocatorComplexity;
  /**
   * Narrows {@link CssLocator.relative}'s return type: the constructor only
   * ever accepts {@link AccessibleRoleLocatorRelativePosition}, so every
   * instance's underlying value is already within that narrower set — this
   * cast just reflects that guarantee in the type, so `clone()` doesn't need
   * one of its own.
   */
  get relative(): AccessibleRoleLocatorRelativePosition;
  get name(): string | undefined;
  clone(override?: Partial<AccessibleRoleLocatorInitializer> & Partial<CssLocatorInitializer>): AccessibleRoleLocator;
}
//#endregion
//#region src/locators/byLinkedElement.d.ts
/**
 * Experimental locator that matches an element by relating it to another
 * element on the page. It is useful when two elements share related
 * attributes.
 *
 * @param relative - Relative position for the resulting locator. Defaults to
 * `'Descendant'`.
 * @example
 * ```ts
 * const label = byLinkedElement().onLinkedElement(byDataTestId('input'))
 *   .extractAttribute('for')
 *   .toMatchMyAttribute('id');
 * ```
 */
declare function byLinkedElement(relative?: LocatorRelativePosition): {
  onLinkedElement: (locator: PartLocator) => {
    extractAttribute: (attributeName: string) => {
      toMatchMyAttribute: (myAttributeName: string) => PartLocator;
    };
  };
};
//#endregion
//#region src/locators/findByRole.d.ts
/**
 * Locate an element by its ARIA `role` plus its COMPUTED accessible name — the
 * accname algorithm: `aria-labelledby` id-refs, an associated `<label>`,
 * wrapping/`title` text, and (unlike {@link byAriaLabel}) plain visible text
 * content. This is the common case for a design system that labels controls
 * with visible text rather than a literal `aria-label` attribute.
 *
 * Resolution is NOT CSS: the accessible name is computed by a multi-node graph
 * traversal no CSS selector can express (see
 * [ADR-008](https://github.com/atomic-testing/atomic-testing/blob/main/agent-docs/adr/008-css-dom-only-locator-boundary.md)).
 * Each interactor resolves it internally via an engine that already implements
 * accname — `@testing-library/dom`'s `getByRole` in jsdom, Playwright's
 * `Locator.getByRole`/`Page.getByRole` in the browser. `name` matching is
 * always exact and case-sensitive in both engines (see
 * {@link AccessibleRoleLocator} for why there is no `exact` option). Composing
 * this with a preceding locator scopes the search to that ancestor's subtree
 * (e.g. `locatorUtil.append(dialogLocator, findByRole('button', 'Save'))`
 * finds "Save" only within the dialog); it must be the LAST segment of a
 * chain — nothing can be appended after it.
 *
 * Use `findByRole` when the name comes from visible text/`<label>`/
 * `aria-labelledby`; use {@link byAriaLabel} (composed via {@link
 * locatorUtil.and}) when the name is a verbatim `aria-label` attribute — that
 * stays a pure-CSS match with no accname cost.
 *
 * @param role - The ARIA role value to match, e.g. `'button'`, `'link'`.
 * @param name - The computed accessible name to match, exact and
 * case-sensitive. Omit to match by role alone (equivalent to {@link byRole}
 * but accname-resolved).
 * @param relative - Relative position of the locator. Only `'Root'` (escape to
 * the document root) and `'Descendant'` (the default) are accepted: `'Same'`
 * (compound onto the same element) and `'Child'` (restrict to a direct child)
 * have no accname-search equivalent, so the type excludes them rather than
 * silently falling back to `'Descendant'` behavior — see
 * {@link AccessibleRoleLocatorRelativePosition}.
 * @example
 * ```ts
 * const saveButton = findByRole('button', 'Save');
 * const scopedSaveButton = locatorUtil.append(dialogLocator, findByRole('button', 'Save'));
 * ```
 */
declare function findByRole(role: string, name?: string, relative?: AccessibleRoleLocatorRelativePosition): PartLocator;
//#endregion
//#region src/locators/LinkedCssLocator.d.ts
interface LinkedCssLocatorAttributeValueExtract {
  type: 'attribute';
  attributeName: string;
}
type LinkedCssLocatorValueExtract = LinkedCssLocatorAttributeValueExtract;
interface LinkedCssLocatorInitializer {
  valueExtract: LinkedCssLocatorValueExtract;
  matchingTargetLocator: PartLocator;
  matchingTargetValueExtract: LinkedCssLocatorValueExtract;
}
/**
 * A {@link CssLocator} whose match must also satisfy a value comparison against
 * a second, independently-located target element — e.g. an `<option>` whose
 * value equals a `<select>`'s current value. `valueExtract` describes how to
 * read the value off this locator's own match; `matchingTargetLocator` /
 * `matchingTargetValueExtract` describe where to read the value to compare
 * against. Produced by {@link byLinkedElement} (experimental).
 */
declare class LinkedCssLocator extends CssLocator {
  private _valueExtract;
  private _matchingTargetLocator;
  private _matchingTargetValueExtract;
  constructor(selector: string, initializeValue: LinkedCssLocatorInitializer & Partial<CssLocatorInitializer>);
  get complexity(): LocatorComplexity;
  get valueExtract(): LinkedCssLocatorValueExtract;
  get matchingTargetLocator(): PartLocator;
  get matchingTargetValueExtract(): LinkedCssLocatorValueExtract;
  clone(override?: Partial<LinkedCssLocatorInitializer> & Partial<CssLocatorInitializer>): LinkedCssLocator;
}
declare namespace timingUtil_d_exports {
  export { WaitUntilOption, wait, waitUntil };
}
/**
 * Wait a number of milliseconds
 * @param ms A number of milliseconds to wait
 * @returns
 */
declare function wait(ms: number): Promise<void>;
interface WaitUntilOption<T> {
  /**
   * A function that returns a value or promised value to be checked against the terminate condition
   */
  probeFn: () => Promise<T> | T;
  /**
   * A value to check for equality or a function used for custom equality check
   */
  terminateCondition: T | ((currentValue: T) => boolean);
  /**
   * A number of milliseconds to wait before returning the last value
   */
  timeoutMs: number;
  /**
   * Probe on an even grid instead: `probeCount` probes spread across `timeoutMs`,
   * plus a final probe on the timeout boundary. Supply this only when an even
   * cadence is what you want — leaving it unset selects the escalating default
   * described on {@link WaitUntilOption.probeIntervals}, which settles far sooner
   * for the same timeout. Ignored when `probeIntervals` is provided.
   */
  probeCount?: number;
  /**
   * Escalating waits (in milliseconds) between probes; the last entry repeats until
   * timeoutMs elapses. Suits "settle a re-render" waits where the condition usually
   * flips within milliseconds but may occasionally take much longer — probe densely
   * first, then back off. Takes precedence over probeCount, and applies by default
   * when neither is supplied.
   */
  probeIntervals?: readonly number[];
  /**
   * Whether it should log the conditional checks while waiting
   */
  debug?: boolean;
}
/**
 * Keep running a probe function until it returns a value that matches the terminate condition or timeout
 */
declare function waitUntil<T>(option: WaitUntilOption<T>): Promise<T>;
//#endregion
//#region src/interactor/MouseOption.d.ts
interface MouseOption {
  /**
   * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
   * the element.
   * Note that in end to end tests such as Playwright, mouse interaction location is not always pixel perfect.
   */
  position?: Point;
}
interface ClickOption extends MouseOption {
  /**
   * Number of clicks to dispatch as a single gesture, e.g. `2` for a
   * double-click. Only `2` is currently implemented; omit for a single click.
   * Two separate `click()` calls do not reliably register as a real
   * double-click (actionability re-checks between calls can exceed the
   * platform's double-click timing threshold), so a genuine double-click
   * gesture needs this option rather than calling `click()` twice.
   *
   * Every `Interactor.click()` implementation validates this via
   * {@link assertValidClickCount} and throws for anything other than `2`, so
   * an unsupported value fails the same way in every environment instead of
   * silently diverging (e.g. Playwright honoring a `3` while jsdom silently
   * falls back to a single click).
   */
  clickCount?: number;
}
/**
 * Validate a {@link ClickOption.clickCount}. Shared by every `Interactor.click()`
 * implementation so an unsupported value throws identically everywhere,
 * rather than each environment interpreting it differently.
 * @throws {Error} If `clickCount` is set to anything other than `2`.
 */
declare function assertValidClickCount(clickCount: number | undefined): void;
interface MouseMoveOption extends MouseOption {}
interface MouseDownOption extends MouseOption {}
interface MouseUpOption extends MouseOption {}
interface HoverOption extends MouseOption {}
interface MouseOutOption {}
interface MouseEnterOption {}
interface MouseLeaveOption {}
//#endregion
//#region src/interactor/PressKeyOption.d.ts
/**
 * Options for {@link Interactor.pressKey}.
 *
 * Each flag mirrors the corresponding `KeyboardEvent` boolean (`ctrlKey`,
 * `shiftKey`, `altKey`, `metaKey`). They let a single `pressKey` express a
 * modifier chord, so the dispatched key event carries the held modifiers a
 * component reads off the event — e.g. activating a `Ctrl+Enter` "submit"
 * shortcut, or proving the negative case where `Shift+Enter` must NOT fire a
 * plain-`Enter` handler (it should insert a newline instead). Omitting a flag
 * leaves that modifier unpressed.
 */
interface PressKeyOption {
  /** Hold `Control` during the key press (`KeyboardEvent.ctrlKey`). */
  ctrl?: boolean;
  /** Hold `Shift` during the key press (`KeyboardEvent.shiftKey`). */
  shift?: boolean;
  /** Hold `Alt`/`Option` during the key press (`KeyboardEvent.altKey`). */
  alt?: boolean;
  /** Hold `Meta`/`Command`/`Windows` during the key press (`KeyboardEvent.metaKey`). */
  meta?: boolean;
}
//#endregion
//#region src/interactor/Interactor.d.ts
/**
 * Pointer/mouse-driven, potentially DOM-mutating interactions: the pointer
 * gestures a real user performs with a mouse, plus the two dispatch-based
 * escape hatches ({@link PointerActions.contextMenu | contextMenu},
 * {@link PointerActions.activate | activate}) for outcomes ordinary pointer
 * geometry cannot reach, and the drag primitives.
 *
 * Split out of {@link Interactor} as a capability facet (ADR-007) so a driver
 * can depend on just the pointer surface, and a partial-capability environment
 * can declare pointer support independently of the rest. `Interactor`
 * recomposes this facet unchanged.
 */
interface PointerActions {
  /**
   * Click on the desired element
   * @param locator
   * @param option
   */
  click(locator: PartLocator, option?: Partial<ClickOption>): Promise<void>;
  /**
   * Mouse move on the desired element
   * @param locator
   * @param option
   */
  mouseMove(locator: PartLocator, option?: Partial<MouseMoveOption>): Promise<void>;
  mouseDown(locator: PartLocator, option?: Partial<MouseDownOption>): Promise<void>;
  mouseUp(locator: PartLocator, option?: Partial<MouseUpOption>): Promise<void>;
  mouseOver(locator: PartLocator, option?: Partial<HoverOption>): Promise<void>;
  mouseOut(locator: PartLocator, option?: Partial<MouseOutOption>): Promise<void>;
  mouseEnter(locator: PartLocator, option?: Partial<MouseEnterOption>): Promise<void>;
  mouseLeave(locator: PartLocator, option?: Partial<MouseLeaveOption>): Promise<void>;
  /**
   * Dispatch a right-click / `contextmenu` event on the desired element.
   *
   * A `contextmenu` event is the only way to open a context menu: such menus have
   * no `aria-expanded` toggle or controlled-open prop to flip, so the menu is
   * reachable only by the event a right-click produces. This is analogous to
   * {@link KeyboardActions.pressKey | pressKey} for keyboard-only behaviors — a
   * dedicated primitive for an outcome no ordinary {@link PointerActions.click | click}
   * can express. The element is focused first if focusable, mirroring `pressKey`,
   * so the event originates from the active element as in a real right-click.
   *
   * @param locator
   */
  contextMenu(locator: PartLocator): Promise<void>;
  /**
   * Activate the desired element without relying on pointer geometry — a
   * coordinate-free, dispatch-based click.
   *
   * This reaches elements an ordinary {@link PointerActions.click | click} cannot:
   * a visually-hidden or zero-size input covered by another element (e.g. MUI
   * Rating's hidden `<input type="radio">`, where a positional click hit-tests to
   * the covering star label instead). Prefer {@link PointerActions.click | click}
   * for ordinary, visible targets.
   *
   * @param locator
   */
  activate(locator: PartLocator): Promise<void>;
  /**
   * Drag the source element and drop it onto the target element.
   *
   * Drives BOTH DnD models on the same gesture, so either kind of component
   * under test is driven: the pointer sequence
   * (`mousedown`/`mousemove`/`mouseup`, for pointer-based libraries such as
   * dnd-kit or react-beautiful-dnd) and native HTML5 drag-and-drop
   * (`dragstart`/`dragenter`/`dragover`/`drop`/`dragend`, sharing one
   * `dataTransfer`, for components built on `draggable` +
   * `ondragstart`/`ondragover`/`ondrop`) — see #922. The mechanism differs by
   * environment: Playwright drives a real, low-level pointer gesture that the
   * browser's own native drag recognition turns into genuine `drag*` events
   * with a real `DataTransfer` (no synthesis needed); jsdom has no browser
   * layer to recognize a gesture, so `DOMInteractor` explicitly synthesizes
   * both event families.
   *
   * jsdom has no layout engine, so the drag has no positional outcome there:
   * every event is synthesized at zeroed coordinates and only the event wiring
   * (and any handler the sequence triggers, including a `dataTransfer`
   * payload set in `dragstart` and read in `drop`) is exercised. Behavioral
   * assertions about the final position are therefore E2E-only; the jsdom path
   * only guarantees the events fire once both elements are found.
   *
   * @param source Locator of the element to drag
   * @param target Locator of the element to drop onto
   */
  dragTo(source: PartLocator, target: PartLocator): Promise<void>;
  /**
   * Drag the desired element by the given pixel delta from its center.
   *
   * Drives both DnD models, as {@link PointerActions.dragTo | dragTo} does —
   * see #922. There is no separate drop target for a single-element delta
   * drag, so the native HTML5 drag-and-drop sequence
   * (`dragstart`/`dragenter`/`dragover`/`drop`/`dragend`) runs on the element
   * itself, as its own drop target.
   *
   * jsdom has no layout engine, so the drag has no positional outcome there: the
   * pointer sequence is synthesized from the caller-supplied delta and only the
   * event wiring is exercised. Behavioral assertions about the resulting position
   * are therefore E2E-only; the jsdom path only guarantees the events fire once
   * the element is found.
   *
   * @param locator Locator of the element to drag
   * @param delta Pixel offset to drag by, where `x` is horizontal and `y` is vertical
   */
  drag(locator: PartLocator, delta: Point): Promise<void>;
  /**
   * Perform a mouse hover on the desired element
   * @param locator
   */
  hover(locator: PartLocator, option?: HoverOption): Promise<void>;
}
/**
 * Keyboard-driven interactions: dispatch of real key events, distinct from the
 * value-filling {@link FormActions} path. A capability facet of {@link Interactor}
 * (ADR-007).
 */
interface KeyboardActions {
  /**
   * Dispatch a keyboard key press on the desired element.
   *
   * Unlike {@link FormActions.enterText | enterText}, which fills a value, this
   * dispatches an actual key event so components that key off `KeyboardEvent.key`
   * are exercised — e.g. Dialog dismissal on `Escape` or Chip deletion on
   * `Backspace`/`Delete`. The element is focused first so the event originates
   * from the active element, matching a real key press. On a focused
   * `contenteditable` host the press additionally carries `beforeinput`/`input`
   * fidelity, so editing keys such as `Backspace` reach components that commit
   * changes from input events (e.g. the MUI X picker section field, see #903); on
   * every other target — including text `<input>`/`<textarea>` — it stays a plain
   * `keydown`/`keyup` on the element so keyboard handlers fire as they expect (a
   * text field is edited through {@link FormActions.enterText | enterText}/{@link FormActions.typeText | typeText},
   * not this). No pointer event is involved, so behaviours unreachable by
   * {@link PointerActions.click | click} (geometry or not) become testable.
   *
   * Cross-engine note: with `shift` and a PRINTABLE key, `KeyboardEvent.key`
   * is delivered as the literal `key` passed in — NOT case-folded to a
   * shifted variant (`Shift`+`'a'` stays `'a'`, not `'A'`) — with
   * `shiftKey: true` carrying the modifier. This was verified to hold
   * identically in both jsdom (`DOMInteractor`) and Playwright
   * (`PlaywrightInteractor`) against this repo's pinned toolchain; a caller
   * that needs an actual shifted character (e.g. `'A'`, `'!'`) passes it as
   * `key` directly rather than relying on `shift` to transform a lowercase/
   * unshifted one — see #924.
   *
   * @param locator
   * @param key A `KeyboardEvent.key` value, e.g. `'Escape'`, `'Backspace'`, `'Enter'`
   * @param option Modifier flags (`ctrl`/`shift`/`alt`/`meta`) folded into the
   * dispatched key event, so a chord such as `Ctrl+Enter` is delivered with its
   * held modifiers — see {@link PressKeyOption}.
   */
  pressKey(locator: PartLocator, key: string, option?: Partial<PressKeyOption>): Promise<void>;
}
/**
 * Focus management: move focus onto an element or remove it. A capability facet
 * of {@link Interactor} (ADR-007).
 */
interface FocusActions {
  focus(locator: PartLocator, option?: Partial<FocusOption>): Promise<void>;
  /**
   * Remove focus from the desired element
   * @param locator
   * @param option
   */
  blur(locator: PartLocator, option?: Partial<BlurOption>): Promise<void>;
}
/**
 * Form-control value entry: typing into text fields, driving range/select/file
 * inputs. A capability facet of {@link Interactor} (ADR-007); an environment that
 * supports forms but not, say, drag gestures can declare this facet on its own.
 */
interface FormActions {
  /**
   * Type text into the desired element
   * @param locator
   * @param value
   */
  enterText(locator: PartLocator, text: string, option?: Partial<EnterTextOption>): Promise<void>;
  /**
   * Type text into the desired element as a sequence of real per-character
   * keystrokes.
   *
   * Unlike {@link FormActions.enterText | enterText}, which clears the target and
   * fills its value — a path invisible to widgets that ignore programmatic value
   * assignment — this focuses the element and dispatches the full key event
   * sequence per character (`keydown` → `beforeinput` → `input` → `keyup`),
   * inserting at the element's current caret with no clearing. That reaches
   * keystroke-driven editors such as the MUI X picker section field (a
   * `contenteditable` `role="spinbutton"` span that only commits digits arriving
   * as genuine key events) and grid cell editors entered via
   * {@link KeyboardActions.pressKey | pressKey} — see #903/#905.
   *
   * The text is typed literally: characters that carry special meaning in an
   * underlying dispatcher (user-event's `{`/`[` descriptor syntax) are escaped,
   * so `typeText(locator, '{a}')` types the five characters `{a}` verbatim.
   * For non-printable keys or modifier chords use {@link KeyboardActions.pressKey | pressKey};
   * to clear before typing, combine with {@link FormActions.enterText | enterText}
   * or key presses.
   *
   * @param locator Locator of the element to type into
   * @param text The literal text to type, one keystroke per character
   */
  typeText(locator: PartLocator, text: string): Promise<void>;
  /**
   * Set the value of a range input (`<input type="range">`, the element behind a
   * slider) and fire its change so the host framework reacts.
   *
   * A dedicated primitive exists because a range input cannot be driven through
   * {@link FormActions.enterText | enterText} (it accepts no typed text) nor
   * reliably through {@link PointerActions.click | click} (a positional click on
   * the track sets a coordinate-derived, not an exact, value). The value is
   * assigned through the element's native value setter — so the browser sanitizes
   * it to the input's `min`/`max`/`step`, snapping an off-step target to the
   * nearest valid step — and an `input`/`change` event is dispatched so controlled
   * components (e.g. MUI Slider) update their state.
   *
   * jsdom has no range sanitization, so it stores an off-step value verbatim
   * whereas a real browser snaps it; pass a step-aligned `value` for assertions
   * that must hold in both environments. See #73.
   *
   * @param locator Locator of the `<input type="range">` element
   * @param value The numeric value to set; sanitized to the input's step in-browser
   */
  setRangeValue(locator: PartLocator, value: number): Promise<void>;
  /**
   * Select option by value from a select element
   * @param locator
   * @param values
   */
  selectOptionValue(locator: PartLocator, values: string[]): Promise<void>;
  /**
   * Set the selected files on a `<input type="file">` element.
   *
   * A dedicated primitive exists because a file input's `FileList` cannot be
   * populated through {@link FormActions.enterText | enterText} (or any
   * value-typing path): browsers block programmatic assignment to `type=file`
   * value for security, so the `FileList` must be set via the upload-specific
   * channel — `userEvent.upload` in the DOM/jsdom and `locator.setInputFiles` in
   * Playwright — which is the only way a change event with the chosen files fires.
   *
   * @param locator Locator of the `<input type="file">` element
   * @param files One or more filesystem paths to upload. Pass a single path for
   * a non-`multiple` input; pass an array to select several files on a
   * `multiple` input.
   */
  setInputFiles(locator: PartLocator, files: string | string[]): Promise<void>;
}
/**
 * Viewport/scroll interactions. A capability facet of {@link Interactor}
 * (ADR-007). jsdom has no layout engine, so these are no-ops there and behavioral
 * assertions about the resulting scroll state are E2E-only (see each member).
 */
interface ScrollActions {
  /**
   * Scroll the desired element into the viewport.
   *
   * jsdom has no layout engine, so the scrolling effect is a no-op there: the
   * element's geometry never changes and nothing becomes "visible". Behavioral
   * assertions about visibility or offset are therefore E2E-only; the jsdom path
   * only guarantees the call resolves without throwing once the element is found.
   *
   * @param locator Locator of the element to scroll into view
   */
  scrollIntoView(locator: PartLocator): Promise<void>;
  /**
   * Scroll the desired element by the given delta (in pixels).
   *
   * jsdom has no layout engine, so the scrolling effect is a no-op there: the
   * element's scroll offset never changes. Behavioral assertions about the
   * resulting scroll position are therefore E2E-only; the jsdom path only
   * guarantees the call resolves without throwing once the element is found.
   *
   * @param locator Locator of the scrollable element
   * @param delta Pixel offset to scroll by, where `x` is horizontal and `y` is vertical
   */
  scrollBy(locator: PartLocator, delta: Point): Promise<void>;
}
/**
 * Async settling primitives: block until a locator reaches a target state, or
 * until a caller-supplied probe terminates. A capability facet of
 * {@link Interactor} (ADR-007).
 */
interface Waiter {
  /**
   * Wait until the component is in the expected state such as
   * the component's visibility or existence. If the component has
   * not reached the expected state within the timeout, it will throw
   * an error.
   *
   * By default it waits until the component is attached to the DOM
   * within 30 seconds.
   *
   * @param locator The locator of the component to wait for
   * @param option The option to configure the wait behavior
   */
  waitUntilComponentState(locator: PartLocator, option?: Partial<Readonly<WaitForOption>>): Promise<void>;
  /**
   * Keep running a probe function until it returns a value that matches the terminate condition or timeout
   * @returns The last value returned by the probe function
   */
  waitUntil<T>(option: WaitUntilOption<T>): Promise<T>;
}
/**
 * Read-only element queries: values, attributes, geometry, presence/count, and
 * boolean state (checked/disabled/visible/…), plus the {@link ElementQueries.innerHTML | innerHTML}
 * debug read. A capability facet of {@link Interactor} (ADR-007); none of these
 * mutate the DOM.
 */
interface ElementQueries {
  getInputValue(locator: PartLocator): Promise<Optional<string>>;
  /**
   * Get the select element's selected options' values
   * @param locator
   */
  getSelectValues(locator: PartLocator): Promise<Optional<readonly string[]>>;
  /**
   * Get the select element's selected options' labels
   * @param locator
   */
  getSelectLabels(locator: PartLocator): Promise<Optional<readonly string[]>>;
  getAttribute(locator: PartLocator, name: string, isMultiple: true): Promise<readonly string[]>;
  getAttribute(locator: PartLocator, name: string, isMultiple: false): Promise<Optional<string>>;
  getAttribute(locator: PartLocator, name: string): Promise<Optional<string>>;
  /**
   * Get the value of a style property
   * @param locator
   * @param propertyName
   */
  getStyleValue(locator: PartLocator, propertyName: CssProperty): Promise<Optional<string>>;
  getText(locator: PartLocator): Promise<Optional<string>>;
  /**
   * Get the element's bounding rectangle in CSS pixels.
   *
   * jsdom has no layout engine, so every coordinate and dimension is `0` there:
   * the returned rect is structurally valid but behaviorally meaningless.
   * Assertions about real geometry are therefore E2E-only; under jsdom this
   * returns a zero-rect.
   *
   * @param locator Locator of the element to measure
   */
  getBoundingRect(locator: PartLocator): Promise<BoundingRect>;
  exists(locator: PartLocator): Promise<boolean>;
  /**
   * Count every element matching the locator.
   *
   * Where {@link ElementQueries.exists | exists} is a presence check that stops at
   * the first match, this resolves the locator to its full match set and returns
   * the cardinality — the multi-match counterpart the list helpers use to size a
   * collection in one round-trip instead of probing index by index. A locator
   * matching nothing yields `0`.
   *
   * Homogeneous-match semantics: the count is by locator match, not by tag
   * position. A sibling that shares an item's tag but does not satisfy the
   * locator is not counted — the opposite of `:nth-of-type`, which counts by tag
   * among all siblings. This is what lets the count side of a list stay correct
   * when the items are interleaved with a same-tag non-item (a header/divider).
   */
  getElementCount(locator: PartLocator): Promise<number>;
  /**
   * Whether the element is checked, via the native `checked` property of an
   * `<input type="checkbox">`/`<input type="radio">` or `aria-checked="true"` on an
   * element carrying an explicit checkable `role`. `aria-checked="mixed"` and a
   * native `indeterminate` control both report `false` — the contract is two-state.
   * The locator must address the control itself; a `<label>` is not retargeted.
   */
  isChecked(locator: PartLocator): Promise<boolean>;
  /**
   * Whether the element is disabled, via the native disabled state — including the
   * `<fieldset disabled>`/`<optgroup disabled>` cascades — or the nearest
   * `aria-disabled` on the element or an ancestor being `"true"`, so a re-enabled
   * descendant of a disabled container reports `false`. The locator must address the
   * control itself; a `<label>` is not retargeted.
   */
  isDisabled(locator: PartLocator): Promise<boolean>;
  isReadonly(locator: PartLocator): Promise<boolean>;
  /**
   * Whether the element is marked required, via the native `required` property or
   * an `aria-required="true"` attribute.
   */
  isRequired(locator: PartLocator): Promise<boolean>;
  /**
   * Whether the element is in an invalid/error state, signalled by
   * `aria-invalid="true"` (the cross-widget convention; native validity state is
   * not consulted).
   */
  isError(locator: PartLocator): Promise<boolean>;
  isVisible(locator: PartLocator): Promise<boolean>;
  hasCssClass(locator: PartLocator, className: string): Promise<boolean>;
  hasAttribute(locator: PartLocator, name: string): Promise<boolean>;
  /**
   * Get the HTML of an element
   * @param locator
   */
  innerHTML(locator: PartLocator): Promise<string>;
}
/**
 * Environment specific implementation that performs low level actions on the UI.
 *
 * Component drivers delegate every interaction to an instance of this interface
 * so tests can run in different environments by simply providing a different
 * interactor implementation.
 *
 * **Capability facets.** `Interactor` is composed from narrower facets —
 * {@link PointerActions}, {@link KeyboardActions}, {@link FocusActions},
 * {@link FormActions}, {@link ScrollActions}, {@link ElementQueries}, and
 * {@link Waiter} — so a driver can depend on just the surface it uses and a
 * future partial-capability environment can declare exactly the facets it
 * supports (ADR-007). TypeScript is structurally typed, so any value that
 * satisfied `Interactor` before the split still does; recomposing from facets is
 * purely additive and changes no member.
 *
 * **1.0 boundary — DOM and CSS only.** Every method resolves its target by
 * reducing a {@link PartLocator} to a single CSS selector
 * (`locatorUtil.toCssSelector`) and running it against a DOM — jsdom via
 * `@testing-library` in `DOMInteractor`, or a real browser via Playwright. The
 * 1.0 contract is therefore deliberately scoped to **DOM environments addressed
 * by CSS**: there is no seam for a non-DOM target, and a computed ARIA accessible
 * name (`aria-labelledby` / `<label>` / text — not CSS-expressible) is out of
 * scope. See [ADR-008](https://github.com/atomic-testing/atomic-testing/blob/main/agent-docs/adr/008-css-dom-only-locator-boundary.md);
 * the deferred name-aware resolution is tracked in #923. Post-1.0 the interface
 * grows additively per [ADR-007](https://github.com/atomic-testing/atomic-testing/blob/main/agent-docs/adr/007-interactor-evolution-and-composition.md).
 */
interface Interactor extends PointerActions, KeyboardActions, FocusActions, FormActions, ScrollActions, ElementQueries, Waiter {}
//#endregion
//#region src/drivers/ListComponentDriver.d.ts
interface ListComponentDriverSpecificOption<ItemT extends ComponentDriver> {
  itemClass: new (locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) => ItemT;
  itemLocator: PartLocator;
}
interface ListComponentDriverOption<ItemT extends ComponentDriver> extends IComponentDriverOption, ListComponentDriverSpecificOption<ItemT> {}
declare class ListComponentDriver<ItemT extends ComponentDriver> extends ComponentDriver {
  private readonly _option;
  private _itemLocator;
  constructor(locator: PartLocator, interactor: Interactor, option: ListComponentDriverSpecificOption<ItemT>);
  protected getItemLocator(): PartLocator;
  protected getItemClass<ItemClass extends ComponentDriver = ItemT>(itemDriverClass?: ComponentDriverCtor<ItemClass>): ComponentDriverCtor<ItemClass>;
  /**
   * Get the item's driver instance at the given index
   * @param index
   * @param itemDriverClass
   * @returns The item's driver instance at the given index, or `undefined` when the
   * index is out of range. Absence is `undefined` (never `null`) across every core
   * read — see ADR-006 §7.
   */
  getItemByIndex<ItemClass extends ComponentDriver = ItemT>(index: number, itemDriverClass?: ComponentDriverCtor<ItemClass>): Promise<Optional<ItemClass>>;
  /**
   * Get the item's driver instance by the given text
   * @param text
   * @param itemDriverClass
   * @returns The item's driver instance with the given text, or `undefined` when no
   * item matches. Absence is `undefined` (never `null`) across every core read — see
   * ADR-006 §7.
   * @throws {@link ListEnumerationMismatchError} when it searched the whole list
   * without a match but the list is not the homogeneous sibling set positional
   * addressing requires — in that case "no item matches" cannot be distinguished
   * from "enumeration stopped before reaching it", so it is not reported as absence.
   */
  getItemByLabel<ItemClass extends ComponentDriver = ItemT>(text: string, itemDriverClass?: ComponentDriverCtor<ItemClass>): Promise<Optional<ItemClass>>;
  /**
   * Get all the items' driver instances in the list, in DOM order.
   * @param itemDriverClass
   * @returns Every item in the list — never a partial set: see the `@throws` below.
   * @throws {@link ListEnumerationMismatchError} when the list is not the
   * homogeneous sibling set positional addressing requires, so enumeration would
   * otherwise have returned a silently short array.
   */
  getItems<ItemClass extends ComponentDriver = ItemT>(itemDriverClass?: ComponentDriverCtor<ItemClass>): Promise<ItemClass[]>;
  /**
   * Get the number of items in the list, in a single interactor round-trip and
   * without instantiating an item driver — so prefer it to `getItems().length` when
   * only the count is wanted.
   *
   * It is not merely a cheaper `getItems().length`, though: this counts the elements
   * the item locator **matches**, while {@link getItems} walks `:nth-of-type`
   * **positions**. The two agree exactly for the homogeneous sibling set this driver
   * requires, and a list that breaks that requirement makes {@link getItems} throw
   * {@link ListEnumerationMismatchError} rather than let the two answers diverge in
   * silence.
   *
   * @returns The number of elements the item locator matches
   */
  getItemCount(): Promise<number>;
  get driverName(): string;
}
//#endregion
//#region src/partTypes.d.ts
type PartName<T extends ScenePart> = keyof T;
/**
 * Constructor type for a {@link ComponentDriver}, exported publicly so packages
 * can reference it without importing from internal paths. It carries both the
 * construct signature and the static portal hooks every driver class inherits, so
 * concrete driver classes structurally match it.
 *
 * The `any` in the constraint `T extends ComponentDriver<any>` is load-bearing:
 * it lets the type accept any concrete driver regardless of its ScenePart type
 * parameter. The option position, by contrast, is honestly typed to
 * {@link ScenePart} — every driver's parts ultimately satisfy that constraint.
 */
type ComponentDriverCtor<T extends ComponentDriver<any>> = {
  new (locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption<ScenePart>>): T;
  overriddenParentLocator(option?: Partial<IComponentDriverOption<any>>): Optional<PartLocator>;
  overrideLocatorRelativePosition(option?: Partial<IComponentDriverOption<any>>): Optional<LocatorRelativePosition>;
};
interface ComponentPartDefinition<T extends ScenePart> {
  /**
   * The locator of the part
   */
  locator: PartLocator;
  /**
   * The class of driver which is used to interact with the element
   */
  driver: {
    new (locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption<T>>): ComponentDriver<T>;
  };
  option?: Partial<IComponentDriverOption<T>>;
}
/**
 * Definition for a list component part. The `any` in `ItemT extends ComponentDriver<any>`
 * is necessary because ItemT represents the item driver type, and we need to accept
 * any item driver regardless of its ScenePart type parameter.
 */
interface ListComponentPartDefinition<ItemT extends ComponentDriver<any>> {
  /**
   * The locator of the part
   */
  locator: PartLocator;
  /**
   * The class of driver which is used to interact with the element
   */
  driver: typeof ListComponentDriver<ItemT> | (new (locator: PartLocator, interactor: Interactor, option: ListComponentDriverSpecificOption<ItemT> & Partial<IComponentDriverOption<ScenePart>>) => ListComponentDriver<ItemT>);
  /**
   * Option for the driver
   */
  option: ListComponentDriverSpecificOption<ItemT> & Partial<IComponentDriverOption<ScenePart>>;
}
/**
 * The forms a named part in a {@link ScenePart} may take.
 *
 * A component whose interior is caller-supplied is an ordinary
 * {@link ComponentPartDefinition}; its interior is reached at call time through
 * {@link ComponentDriver.within} rather than declared as a second parts channel
 * (ADR-019).
 */
type ScenePartDefinition = ComponentPartDefinition<ScenePart> | ListComponentPartDefinition<ComponentDriver<ScenePart>>;
/**
 * Part name to driver definition map
 */
interface ScenePart extends Record<string, ScenePartDefinition> {}
type ScenePartDriver<T extends ScenePart> = { [partName in keyof T]: InstanceType<T[partName]['driver']>; };
/**
 * The driver-constructor shape a composite driver must present to be placeable in
 * a parent {@link ScenePart}: the `driver` field of {@link ComponentPartDefinition}.
 *
 * Exposed so a package can lock its composite drivers against the contravariant
 * authoring rule documented on {@link ComponentDriver} without copying a full
 * type-test fixture — see {@link AssertScenePlaceableDriver}.
 */
type ScenePlaceableDriverCtor = ComponentPartDefinition<ScenePart>['driver'];
/**
 * Compile-time lock for the composite-driver authoring rule. Resolves to `Ctor`
 * when it satisfies {@link ScenePlaceableDriverCtor} and errors at the type
 * argument otherwise, so a package turns the rule into a build error in one line:
 *
 * ```ts
 * // MyCompositeDriver must stay scene-placeable
 * type _Lock = AssertScenePlaceableDriver<typeof MyCompositeDriver>;
 * ```
 *
 * Because constructor parameters are checked contravariantly, a driver whose
 * option parameter is typed the "natural" `Partial<IComponentDriverOption<typeof
 * parts>>` way fails this assertion — exactly the trap the rule guards against
 * (see {@link ComponentDriver}). This is the reusable form of the type-test that
 * `@atomic-testing/component-driver-html` ships as precedent.
 */
type AssertScenePlaceableDriver<Ctor extends ScenePlaceableDriverCtor> = Ctor;
interface IComponentDriverOption<T extends ScenePart = {}> {
  parts: T;
}
/**
 * The shared, component-agnostic slice of an {@link IComponentDriverOption} that
 * flows unchanged down the driver tree — every field EXCEPT the component-specific
 * `parts`. A parent driver hands this to the constructors of the children it
 * creates dynamically (the list helpers, `ComponentDriver.commutableOption`), so
 * it deliberately carries no `parts`: each child owns its own.
 *
 * Today {@link IComponentDriverOption} has only `parts`, so this resolves to an
 * empty object — which is exactly the honest shape, and why
 * `ComponentDriver.commutableOption` no longer fakes a `parts: {} as T` payload.
 * It is the single home for future universal options (mirroring
 * {@link ITestEngineOption}'s intent), which it will pick up automatically.
 */
type CommutableComponentDriverOption = Omit<IComponentDriverOption, 'parts'>;
/**
 * Shared base option for the framework adapters' `createTestEngine` entry points.
 * Defined once in core so every adapter option type stays in lockstep and future
 * universal bootstrap options have a single home.
 */
interface ITestEngineOption extends IComponentDriverOption {
  /**
   * Element to host the rendered subject. Defaults to `document.body` for the
   * in-DOM adapters (DOM/React/Vue); ignored by out-of-process adapters such as
   * Playwright.
   */
  rootElement?: Element;
}
interface IComponentDriver<T extends ScenePart = {}> {
  /**
   * Return driver instance of all the named parts
   */
  readonly parts: ScenePartDriver<T>;
  /**
   * The locator which helps locate the root of the component
   */
  readonly locator: PartLocator;
  /**
   * Get the combined text content of the component
   * @returns If the component exists and has content, it should return the text or otherwise undefined
   */
  getText(): Promise<Optional<string>>;
  /**
   * Whether the component exists/attached to the DOM
   * @returns true if the component is attached to the DOM, false otherwise
   */
  exists(): Promise<boolean>;
  /**
   * Whether the component is visible.  Visibility is defined
   * that the component does not have the CSS property `display: none`,
   * `visibility: hidden`, or `opacity: 0`.  However this does not
   * check whether the component is within the viewport.
   *
   * @returns true if the component is visible, false otherwise
   */
  isVisible(): Promise<boolean>;
  /**
   * Wait until the component is in the expected state such as
   * the component's visibility or existence. If the component has
   * not reached the expected state within the timeout, it will throw
   * an error.
   *
   * By default it waits until the component is attached to the DOM
   * within 30 seconds.
   *
   * @param option The option to configure the wait behavior
   */
  waitUntilComponentState(option?: Partial<Readonly<WaitForOption>>): Promise<void>;
}
interface ITestEngine<T extends ScenePart = {}> extends IComponentDriver<T> {
  cleanUp(): Promise<void>;
}
//#endregion
//#region src/drivers/ComponentDriver.d.ts
/**
 * Base class for all component drivers.  It provides the basic functionality to interact with the component
 */
declare abstract class ComponentDriver<T extends ScenePart = {}> implements IComponentDriver<T> {
  readonly interactor: Interactor;
  private _locator;
  private readonly _parts;
  /**
   * The component-agnostic slice of the constructor option that is safe to share
   * across the whole driver tree — everything the constructor received EXCEPT the
   * component-specific `parts`, which each driver owns for itself. Parent drivers
   * pass this straight to the constructors of children they create dynamically
   * (see the list helpers). See {@link CommutableComponentDriverOption}.
   */
  readonly commutableOption: CommutableComponentDriverOption;
  /**
   * @param locator Locator for the root of this component.
   * @param interactor Environment adapter used for all interactions.
   * @param option Driver option carrying the shared driver-tree context.
   *
   * Composite-driver authoring rule: a driver that declares non-empty `parts`
   * must type this parameter as `Partial<IComponentDriverOption>` (i.e. the empty
   * `<{}>` default) and hardcode its own `parts` in the body —
   * `super(locator, interactor, { ...option, parts })`. The "natural"
   * `Partial<IComponentDriverOption<typeof parts>>` signature does NOT satisfy
   * `ScenePartDefinition['driver']` (constructor parameters are checked
   * contravariantly), so a driver written that way could not be placed in a
   * parent `ScenePart`. Lock a composite driver against this rule in one line with
   * {@link AssertScenePlaceableDriver}; the rule itself is regression-tested
   * centrally in `core/src/drivers/__type-tests__` and demonstrated in
   * `@atomic-testing/component-driver-html`.
   */
  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption<T>>);
  /**
   * Portal hook: where to re-root this driver's locator when its component renders
   * outside the parent's DOM (a modal, popup, drawer). Return the {@link PartLocator}
   * that locates the component from the document root, or `undefined` (the default)
   * for normal in-tree components whose locator chains from the parent.
   *
   * This is **static** because it is per-class metadata read off the constructor
   * before any instance exists — which makes the "no instance state" constraint
   * structural rather than a documented caution. Override with `static override`.
   *
   * `option` is the fully-merged constructor option the driver is about to receive
   * (the same value passed to the driver's own constructor) — a purely static,
   * per-invocation input, not instance state — so a driver whose portalling is
   * conditional on how its scene configures it (e.g. an overlay that can render
   * teleported OR in-tree, such as PrimeVue's `appendTo="self"`) can branch on a
   * flag there instead of always re-rooting. Ignore it to keep unconditional
   * portal behavior.
   */
  static overriddenParentLocator(_option?: Partial<IComponentDriverOption<any>>): Optional<PartLocator>;
  /**
   * Portal hook: the locator relative position to apply when the component's real
   * DOM is a sibling/elsewhere rather than a descendant (e.g. a MUI dialog rendered
   * at the document root, located by a "Same"-level selector). Return `undefined`
   * (the default) to keep the natural position declared by the ScenePart.
   *
   * Static for the same reason as {@link ComponentDriver.overriddenParentLocator}:
   * it is class-level metadata read before construction. Override with `static override`.
   *
   * See {@link ComponentDriver.overriddenParentLocator} for what `option` carries
   * and why accepting it does not reintroduce instance state.
   */
  static overrideLocatorRelativePosition(_option?: Partial<IComponentDriverOption<any>>): Optional<LocatorRelativePosition>;
  /**
   * Return driver instance of all the named parts
   */
  get parts(): ScenePartDriver<T>;
  /**
   * Return the locator of the component
   */
  get locator(): PartLocator;
  /**
   * The element {@link ComponentDriver.within} resolves an interior scene against —
   * "inside this component", as *this driver* defines inside. Defaults to
   * {@link ComponentDriver.locator}, which is already correct wherever a driver's own
   * locator resolves to the surface holding caller content (Radix/Reka anchor at
   * `Dialog.Content`, Fluent at `DialogSurface`).
   *
   * Override it when the driver's locator resolves to a **wrapper** instead. MUI's
   * Dialog, Drawer and Menu are the shipped cases: their locator is the portal-rendered
   * Modal root, whose children are the backdrop, two focus-trap sentinels and a
   * positioning container. Un-narrowed, an interior there reaches MUI's own chrome,
   * and a `'Child'`-relative interior part resolves to `.MuiBackdrop-root` rather
   * than to anything the scene wrote — silently, since a locator that matches the
   * wrong element raises nothing.
   *
   * An override only helps where that chrome is **ancestral to** the caller's content.
   * Where a design system interleaves chrome *beside* it — Fluent's focus-trap
   * sentinels are siblings of the dialog body — no anchor separates the two, and the
   * default stands (ADR-019's rollout-width audit).
   *
   * An override MUST resolve to an element containing **everything the caller
   * supplied**. For a slotted component that means the surface, never one slot: MUI
   * spreads caller content across `DialogTitle`/`DialogContent`/`DialogActions` as
   * siblings, so narrowing to `.MuiDialogContent-root` would drop the action buttons
   * scenes click. Over-narrowing fails the same silent way it fixes — the part just
   * stops resolving (ADR-019).
   */
  protected get interiorLocator(): PartLocator;
  /**
   * Driver instances for a caller-supplied interior scene, resolved against this
   * component's {@link ComponentDriver.interiorLocator}.
   *
   * The call-time counterpart to {@link ComponentDriver.parts}: `parts` is the
   * chrome the driver author hardcodes, this is the interior the *scene* author
   * owns — a dialog's body, a popover's panel, a toast's action area. A
   * {@link PartLocator} resolves lazily and queries nothing here, so this is
   * synchronous and safe to call before the interior has mounted.
   *
   * This replaced an earlier `ContainerDriver` base whose `content` option
   * required the same scene to be named twice — once as a type argument, once in
   * the driver option — plus a laundering constructor in every subclass (ADR-019).
   * Named `within` rather than `getContent` because leaf drivers already own that
   * name for reading a component's own text (a badge's content, a tooltip's
   * content), and a base-class member cannot collide with them.
   *
   * Interior children are constructed with an empty option, exactly as `content`
   * parts always have been: an interior belongs to the scene, so it inherits no
   * driver-specific configuration from its host. This differs deliberately from
   * {@link ComponentDriver.parts}, whose children do inherit the host's option.
   *
   * @param parts The interior scene to resolve against this component's interior
   * @returns One driver instance per named part
   */
  within<ContentT extends ScenePart>(parts: ContentT): ScenePartDriver<ContentT>;
  /**
   * Check the specified parts' existences, and throw MissingPartError if any of the part is found not existence.
   * Existence is defined by the part's existence in the DOM regardless of its visibility on the screen
   * @param partName Single or array of the names of the parts to be enforced
   */
  protected enforcePartExistence(partName: PartName<T> | ReadonlyArray<PartName<T>>): Promise<void>;
  /**
   * Get the names of parts not in the DOM
   * @param partName Single or array of the names of the parts to be examined
   * @returns
   */
  protected getMissingPartNames(partName: PartName<T> | ReadonlyArray<PartName<T>>): Promise<readonly PartName<T>[]>;
  /**
   * Get the combined text content of the component
   * @returns If the component exists and has content, it should return the text or otherwise undefined
   */
  getText(): Promise<Optional<string>>;
  getAttribute(attributeName: string): Promise<Optional<string>>;
  /**
   * Whether the component exists/attached to the DOM
   * @returns true if the component is attached to the DOM, false otherwise
   */
  exists(): Promise<boolean>;
  click(option?: Partial<ClickOption>): Promise<void>;
  hover(option?: Partial<HoverOption>): Promise<void>;
  protected mouseMove(option?: Partial<MouseMoveOption>): Promise<void>;
  protected mouseDown(option?: Partial<MouseDownOption>): Promise<void>;
  protected mouseUp(option?: Partial<MouseUpOption>): Promise<void>;
  protected mouseOver(option?: Partial<HoverOption>): Promise<void>;
  protected mouseOut(option?: Partial<MouseOutOption>): Promise<void>;
  protected mouseEnter(option?: Partial<MouseEnterOption>): Promise<void>;
  protected mouseLeave(option?: Partial<MouseLeaveOption>): Promise<void>;
  focus(option?: Partial<FocusOption>): Promise<void>;
  /**
   * Dispatch a keyboard key press on the component. See {@link Interactor.pressKey}
   * for the full contract, including modifier-key delivery via {@link PressKeyOption}.
   * @param key A `KeyboardEvent.key` value, e.g. `'Escape'`, `'Backspace'`, `'Enter'`
   * @param option Modifier flags and other per-press options — see {@link PressKeyOption}
   */
  pressKey(key: string, option?: Partial<PressKeyOption>): Promise<void>;
  /**
   * Type text into the component as real per-character keystrokes, inserting at
   * the current caret without clearing. See {@link Interactor.typeText}.
   * @param text The literal text to type, one keystroke per character
   */
  typeText(text: string): Promise<void>;
  /**
   * Dispatch a right-click / `contextmenu` event on the component. See {@link Interactor.contextMenu}.
   */
  protected contextMenu(): Promise<void>;
  /**
   * Activate the component without relying on pointer geometry. See {@link Interactor.activate}.
   */
  protected activate(): Promise<void>;
  /**
   * Scroll the component into the viewport. See {@link Interactor.scrollIntoView}.
   *
   * jsdom has no layout engine, so the scroll is a no-op there and behavioral
   * assertions (visibility, offset) are E2E-only.
   */
  scrollIntoView(): Promise<void>;
  /**
   * Scroll the component by the given pixel delta. See {@link Interactor.scrollBy}.
   *
   * jsdom has no layout engine, so the scroll is a no-op there and behavioral
   * assertions (resulting offset) are E2E-only.
   *
   * @param delta Pixel offset to scroll by
   */
  protected scrollBy(delta: Point): Promise<void>;
  /**
   * Drag this component and drop it onto another component. See {@link Interactor.dragTo}.
   *
   * Prefer a keyboard-driven `setValue` over a true drag in real drivers — these
   * drag primitives exist only for cases keyboard cannot express (e.g. panning a
   * Lightbox, reordering a column). jsdom has no layout engine, so the positional
   * outcome of the drag is E2E-only there.
   *
   * @param target Another driver whose root element is the drop target
   */
  protected dragTo(target: ComponentDriver<any>): Promise<void>;
  /**
   * Drag this component by the given pixel delta from its center. See {@link Interactor.drag}.
   *
   * Prefer a keyboard-driven `setValue` over a true drag in real drivers — these
   * drag primitives exist only for cases keyboard cannot express (e.g. panning a
   * Lightbox, reordering a column). jsdom has no layout engine, so the positional
   * outcome of the drag is E2E-only there.
   *
   * @param delta Pixel offset to drag by
   */
  protected drag(delta: Point): Promise<void>;
  /**
   * Get this component's bounding rectangle. See {@link Interactor.getBoundingRect}.
   *
   * jsdom has no layout engine, so every coordinate and dimension is `0` there;
   * real geometry is E2E-only.
   */
  protected getBoundingRect(): Promise<BoundingRect>;
  /**
   * Whether the component is visible.  Visibility is defined
   * that the component does not have the CSS property `display: none`,
   * `visibility: hidden`, or `opacity: 0`.  However this does not
   * check whether the component is within the viewport.
   *
   * @returns true if the component is visible, false otherwise
   */
  isVisible(): Promise<boolean>;
  /**
   * Wait until the component is attached and becomes visible to the DOM.
   * @param timeoutMs The number of milliseconds to wait before timing out. Defaults
   *   to {@link defaultWaitForOption}.timeoutMs so this wait shares a single
   *   flake-tolerance source with {@link waitUntilComponentState} (#1057).
   */
  waitUntilVisible(timeoutMs?: number): Promise<void>;
  /**
   * Wait until the component is in the expected state such as
   * the component's visibility or existence. If the component has
   * not reached the expected state within the timeout, it will throw
   * an error.
   *
   * By default it waits until the component is attached to the DOM
   * within 30 seconds.
   *
   * @param option The option to configure the wait behavior
   */
  waitUntilComponentState(option?: Partial<Readonly<WaitForOption>>): Promise<void>;
  waitUntil<T>(option: WaitUntilOption<T>): Promise<T>;
  /**
   * Hold an action open until its own postcondition holds, so the action does
   * not resolve while the DOM it promised is still arriving.
   *
   * **Why actions, not reads or assertions.** An interactor settles the
   * framework's scheduler after a write (React `act()`, Vue `nextTick()`,
   * Angular `whenStable()`) and then treats the DOM as final. A component that
   * defers its own DOM work onto a host timer — a `setTimeout` to re-register a
   * select's options, to restore a picker's section spans — lands *after* that
   * settle, so the next single-shot read observes a transient state that is
   * neither the old value nor the new one. Making reads retry cannot fix this
   * (a read does not know what it is waiting for, and negative reads must stay
   * fast); making every mutation drain a fixed extra macrotask is a sleep at
   * framework scale. The action is the only layer that knows what it promised,
   * so the action is where the wait belongs.
   *
   * Probing uses {@link waitUntil}'s escalating intervals, so a postcondition
   * that already holds costs one probe and no delay.
   *
   * @param postcondition Human-readable description of the awaited state, used
   *   verbatim in {@link PostconditionNotMetError}. Phrase it as the state that
   *   must arrive, not the action taken.
   * @param probeFn Returns true once the postcondition holds. Keep it cheap —
   *   it runs repeatedly.
   * @param option.timeoutMs Defaults to {@link defaultWaitForOption}.timeoutMs so
   *   every wait in the library shares one flake-tolerance source (#1057).
   * @throws {PostconditionNotMetError} If the postcondition never holds. Failing
   *   here is deliberate: an action that cannot keep its promise is a real
   *   defect, and reporting it at the action gives a far better diagnostic than
   *   the downstream assertion mismatch it would otherwise become.
   */
  protected awaitPostcondition(postcondition: string, probeFn: () => Promise<boolean> | boolean, option?: {
    readonly timeoutMs?: number;
  }): Promise<void>;
  /**
   * Get the inner HTML of the component
   * @returns The inner HTML of the component
   */
  protected innerHTML(): Promise<string>;
  /**
   * Get the runtime CSS selector of the component. This is useful for debugging and testing purposes.
   *
   * @returns The runtime CSS selector of the component
   */
  runtimeCssSelector(): Promise<string>;
  abstract get driverName(): string;
}
//#endregion
//#region src/TestEngine.d.ts
/**
 * Root driver used for driving a complete scene in a test.
 * It inherits all functionality from {@link ComponentDriver} and
 * adds a clean up hook so that tests can reliably dispose of resources.
 */
declare class TestEngine<T extends ScenePart> extends ComponentDriver<T> {
  readonly interactor: Interactor;
  private readonly _cleanUp;
  /**
   * Construct a {@link TestEngine} instance.
   *
   * @param locator     Root locator for the scene.
   * @param interactor  Low level interactor used by drivers.
   * @param option      Optional driver configuration.
   * @param cleanUp     Hook executed when {@link TestEngine.cleanUp | cleanUp} is called.
   */
  constructor(locator: PartLocator, interactor: Interactor, option?: IComponentDriverOption<T>, cleanUp?: () => Promise<void>);
  /**
   * Run the clean up hook that was provided during construction.
   */
  cleanUp(): Promise<void>;
  /**
   * Identifier for this driver. Used mainly by the debugging utilities.
   */
  get driverName(): string;
}
//#endregion
//#region src/drivers/driverTypes.d.ts
/**
 * A driver whose component holds a readable value — the base capability shared
 * by every form field, regardless of whether that value can also be written.
 */
interface IFormFieldDriver<T> {
  getValue(): Promise<T>;
}
/**
 * A driver whose component's value can be both read and written — a text field,
 * select, or similar input. Extends {@link IFormFieldDriver} with `setValue`.
 */
interface IInputDriver<T> extends IFormFieldDriver<T> {
  setValue(value: T): Promise<boolean>;
}
/**
 * A driver whose component has a binary selected/unselected state that can be
 * toggled — a checkbox, radio, or switch. Distinct from {@link IInputDriver}:
 * the state is a boolean toggle rather than an arbitrary typed value.
 */
interface IToggleDriver {
  isSelected(): Promise<boolean>;
  setSelected(selected: boolean): Promise<void>;
}
/**
 * A driver whose component can be disabled. Implemented uniformly so the obvious
 * assertion `expect(await driver.isDisabled()).toBe(true)` works across components,
 * rather than each consumer reaching into a component-specific attribute or class.
 */
interface IDisableableDriver {
  isDisabled(): Promise<boolean>;
}
/**
 * A driver whose component can be put in a read-only state — its value is shown
 * but not editable. Distinct from {@link IDisableableDriver}: a read-only control
 * is still focusable and is submitted with its form.
 */
interface IReadonlyableDriver {
  isReadonly(): Promise<boolean>;
}
/**
 * A driver whose component can be marked required (a form control).
 */
interface IRequirableDriver {
  isRequired(): Promise<boolean>;
}
/**
 * A driver whose component can be in an invalid/error state (a form control).
 */
interface IValidatableDriver {
  isError(): Promise<boolean>;
}
/**
 * A driver whose component can be clicked. Implemented uniformly so the obvious
 * `await driver.click()` works across components, regardless of what a click
 * means for that component internally.
 */
interface IClickableDriver {
  click(option?: ClickOption): Promise<void>;
}
/**
 * Provide hover functionality to a driver.
 */
interface IMouseInteractableDriver {
  hover(option?: HoverOption): Promise<void>;
}
declare namespace listHelper_d_exports {
  export { collectItemLabels, getListItemByIndex, getListItemCount, getListItemIterator };
}
/**
 * Get list item driver within host by index.  List item is an indefinite number of items under the same host
 * with similar characteristics defined by the itemLocatorBase.
 * @param host The component the list item is under
 * @param itemLocatorBase The locator of the list item without the index, the locator should already compound the host locator if needed
 * @param index The index of the list item
 * @param driverClass The driver class of the list item
 * @returns The item's driver, or `undefined` when the index is out of range.
 */
declare function getListItemByIndex<HostPartT extends ScenePart, ItemT extends ComponentDriver>(host: ComponentDriver<HostPartT>, itemLocatorBase: PartLocator, index: number, driverClass: ComponentDriverCtor<ItemT>): Promise<Optional<ItemT>>;
/**
 * Get an iterator of list item driver.
 * List item is an indefinite number of items under the same host
 *
 * Iteration stops at the first index that does not resolve. For the homogeneous
 * sibling set this addressing requires (see {@link getListItemCount}) that is the
 * end of the list — but any list whose items are not a uniform run of siblings can
 * halt it mid-list instead (a same-tag non-item shifting the reckoning, per-item
 * wrappers making every item `:nth-of-type(1)`; see
 * {@link ListEnumerationMismatchError} for the full set). So on running to
 * completion this cross-checks the number of items it reached against the number the
 * locator actually matches, and throws {@link ListEnumerationMismatchError} when
 * they disagree.
 *
 * Truncation used to be silent, which made it strictly worse than a failure: a
 * header `<li>` ahead of the items yielded an EMPTY list while `getListItemCount`
 * reported 3, and `getItemByLabel` reported "no such item" for an item plainly
 * present. Callers cannot detect this themselves — a short list and a genuinely
 * short list are identical at the call site — so the check belongs here, in the
 * primitive whose addressing creates the hazard, rather than in each of its
 * consumers.
 *
 * Costs one extra {@link Interactor.getElementCount} per completed enumeration,
 * against the n + 1 `exists()` round-trips the walk already spends. A consumer that
 * breaks out early (a label search that finds its match) never reaches the check
 * and never pays for it — and is not making a completeness claim to check.
 *
 * A walk with a non-zero `startIndex` is **not** checked; see the comment at the
 * check for why the two reckonings cannot be reconciled across a tag-position offset.
 *
 * @param host The component the list item is under
 * @param itemLocatorBase The locator of the list item without the index, the locator should already compound the host locator if needed
 * @param driverClass The driver class of the list item
 * @param startIndex The starting index of the list item iterator, default is 0
 * @throws {@link ListEnumerationMismatchError} when enumeration completes having
 * reached fewer items than `itemLocatorBase` matches.
 */
declare function getListItemIterator<HostPartT extends ScenePart, ItemT extends ComponentDriver>(host: ComponentDriver<HostPartT>, itemLocatorBase: PartLocator, driverClass: ComponentDriverCtor<ItemT>, startIndex?: number): AsyncGenerator<ItemT, void, unknown>;
/**
 * Count the items in a list in a single interactor round-trip, without
 * instantiating any item driver.
 *
 * Counts by locator match: {@link Interactor.getElementCount} asks the interactor
 * how many elements `itemLocatorBase` matches. This replaces the former
 * index-by-index `exists()` probing — O(n) round-trips, costly under Playwright
 * where `locator.count()` is one call — and simultaneously fixes the count-side
 * `:nth-of-type` miscount: counting by match (not by tag position) no longer
 * mis-sizes a list interleaved with a same-tag non-item (a header/divider `<li>`).
 *
 * **Homogeneous-siblings requirement.** {@link getListItemByIndex} still ADDRESSES
 * the i-th item by appending `:nth-of-type(i + 1)` to `itemLocatorBase`, so this
 * count and that index access agree only when the items are the homogeneous set
 * the base matches — i.e. no non-item sibling of the same tag shifts the
 * `:nth-of-type` reckoning. For lists that mix item tags or interleave same-tag
 * non-items, use childListHelper's {@link countMatchingChildren} /
 * {@link iterateMatchingChildren} instead, whose `:nth-child` + `childSelector`
 * filter tolerates mixed siblings.
 *
 * @param host The component the list items are under
 * @param itemLocatorBase The locator of the list items without the index; it must
 * match the homogeneous item set only (see the requirement above)
 * @returns The number of items in the list
 */
declare function getListItemCount<HostPartT extends ScenePart>(host: ComponentDriver<HostPartT>, itemLocatorBase: PartLocator): Promise<number>;
/**
 * Collect the non-null visible labels of labelled list items, in DOM order.
 *
 * Shared by the list-family drivers whose item drivers expose `getLabel()`
 * (`ListComponentDriver` subclasses and `PositionalListDriver`), so the
 * "map → filter the absent ones" idiom lives in one place.
 */
declare function collectItemLabels(items: ReadonlyArray<{
  getLabel(): Promise<string | null | undefined>;
}>): Promise<string[]>;
declare namespace childListHelper_d_exports {
  export { countMatchingChildren, getMatchingChildren, iterateMatchingChildren };
}
/**
 * Yield a driver for each descendant of `container` that matches `childSelector`,
 * addressed positionally by `:nth-child`.
 *
 * `:nth-child` is the only element-position pseudo that both jsdom and Playwright
 * resolve identically, and — unlike the `:nth-of-type` used by {@link getListItemByIndex}
 * and friends — it counts across element types. This matters for lists whose items
 * either mix tags (e.g. `<a>`/`<div>` menu items) or are interspersed with
 * non-items (a `role="separator"`, an overflow trigger) sharing a tag with the
 * items: each position is filtered through `childSelector`, so non-matching
 * siblings are skipped without throwing off the index.
 *
 * When `groupSelector` is supplied, a child that is not itself an item but matches
 * `groupSelector` is treated as a wrapper and recursed into — so items nested one
 * (or more) levels deep are still found. Pass a specific selector (e.g. a
 * `role="group"` section) to descend only through those wrappers, or `'*'` to
 * descend through any layout container. Omit it for a flat (direct-children-only)
 * walk.
 *
 * Iteration walks positions until no child exists there, using only
 * {@link Interactor.exists} — portable across interactors (notably,
 * `getAttribute(..., true)` is NOT a reliable element count: Playwright drops
 * null entries, jsdom keeps them). `container` must resolve to a single element so
 * `:nth-child` is unambiguous.
 */
declare function iterateMatchingChildren<ItemT extends ComponentDriver>(host: ComponentDriver, container: PartLocator, childSelector: string, driverClass: ComponentDriverCtor<ItemT>, groupSelector?: string): AsyncGenerator<ItemT>;
/**
 * Count a container's descendants matching `childSelector` (see
 * {@link iterateMatchingChildren} for the `groupSelector` recursion that reaches
 * items nested inside wrappers).
 *
 * The flat case (no `groupSelector`) is a single {@link Interactor.getElementCount}
 * on `> childSelector` — one round-trip instead of the O(children) `exists()`
 * position-walk, and count-equivalent to it: the child-combinator + `childSelector`
 * filter counts exactly the direct children the walk would, still skipping
 * non-matching same-tag siblings. The recursive case must descend into
 * `groupSelector` wrappers, which no single query expresses, so it keeps walking
 * positions via {@link Interactor.exists} (see {@link iterateMatchingChildren} for
 * why a `getAttribute`-based count is not portable).
 */
declare function countMatchingChildren(interactor: Interactor, container: PartLocator, childSelector: string, groupSelector?: string): Promise<number>;
/**
 * Collect a driver for every descendant of `container` matching `childSelector`
 * (see {@link iterateMatchingChildren} for the `groupSelector` recursion).
 */
declare function getMatchingChildren<ItemT extends ComponentDriver>(host: ComponentDriver, container: PartLocator, childSelector: string, driverClass: ComponentDriverCtor<ItemT>, groupSelector?: string): Promise<ItemT[]>;
//#endregion
//#region src/errors/InteractorErrorBase.d.ts
/**
 * Base class for errors thrown at the interactor level, where no
 * `ComponentDriver` is available — only the locator that was being resolved.
 *
 * Carries a **serializable** `locatorDescription` string rather than a live
 * `PartLocator`, so the frozen, catchable error contract stays decoupled from the
 * locator model and callers cannot reach locator internals through a caught
 * error. Subclasses compute the description from the locator via
 * `getLocatorInfoForErrorLog`. See ADR-010.
 */
declare class InteractorErrorBase extends Error {
  readonly locatorDescription: string;
  constructor(message: string, locatorDescription: string);
}
//#endregion
//#region src/errors/ElementNotFoundError.d.ts
declare const ElementNotFoundErrorId = "ElementNotFoundError";
/**
 * Error thrown when an interactor method is called on an element that does not exist.
 * This error is thrown at the interactor level and does not require a ComponentDriver reference.
 */
declare class ElementNotFoundError extends InteractorErrorBase {
  readonly action: string;
  constructor(locator: PartLocator, action: string);
}
//#endregion
//#region src/errors/ErrorBase.d.ts
/**
 * Base class for errors raised from a component driver.
 *
 * Carries only a **serializable** snapshot of where the error occurred —
 * `driverName` — rather than a live `ComponentDriver` reference. This keeps the
 * frozen, catchable error contract decoupled from the evolving driver type (and
 * free of the `any` a `ComponentDriver<any>` field would leak), and stops callers
 * reaching driver/DOM internals through a caught error. The constructor accepts
 * anything name-bearing (a driver satisfies `{ driverName: string }`) and stores
 * only the name. See ADR-010.
 */
declare class ErrorBase extends Error {
  readonly driverName: string;
  constructor(message: string, driver: {
    driverName: string;
  });
}
//#endregion
//#region src/errors/ItemNotFoundError.d.ts
declare const ItemNotFoundErrorId = "ItemNotFoundError";
/**
 * The canonical "an item searched for in a collection was not found" error.
 * Component-specific list-miss errors (e.g. a menu's `MenuItemNotFoundError`)
 * subclass this so callers can catch the family with one `instanceof` check.
 *
 * Per ADR-010 it retains only a serializable {@link locatorDescription} string —
 * never the live locator — keeping the frozen error contract decoupled from the
 * locator model.
 *
 * @param query What was searched for — a {@link PartLocator} or a human-readable
 *   description such as an item label.
 * @param driver Anything name-bearing (a driver satisfies `{ driverName }`); only
 *   its `driverName` is retained.
 * @param message Optional override for the generated message, used by subclasses
 *   that phrase the miss in their own terms.
 */
declare class ItemNotFoundError extends ErrorBase {
  readonly locatorDescription: string;
  constructor(query: PartLocator | string, driver: {
    driverName: string;
  }, message?: string);
}
//#endregion
//#region src/errors/ListEnumerationMismatchError.d.ts
declare const ListEnumerationMismatchErrorId = "ListEnumerationMismatchError";
/**
 * Thrown when a list's two reckonings of "how many items" disagree: positional
 * enumeration walked `:nth-of-type(i + 1)` and stopped, while the locator itself
 * matches a different number of elements. The walk is therefore a lower bound, and
 * the items missing from it are indistinguishable from items that do not exist.
 *
 * `:nth-of-type` counts by **tag**, among **one parent's** children. Any list whose
 * items do not sit as that uniform run of siblings breaks the correspondence, and
 * more than one shape does:
 *
 * - A non-item sibling sharing the items' tag — a header or separator `<li>`, an
 *   `<optgroup>` between `<option>`s — shifts the reckoning, and the walk stops at
 *   the first position the item selector no longer matches.
 * - Items nested under per-item wrappers, where each item is `:nth-of-type(1)` of
 *   its own parent, so the positional sequence never advances past the first.
 * - The list changing between the walk and the count — an async re-render or an
 *   in-flight animation — which no list SHAPE explains and no driver change fixes.
 *
 * For the two structural causes the fix is at the driver, not the call site: address
 * the list with `childListHelper`'s {@link iterateMatchingChildren} /
 * {@link countMatchingChildren}, whose `:nth-child` + child-selector filter skips
 * non-matching siblings without losing its place, and recurses into wrappers when
 * given a `groupSelector`. For the third, settle the list first — see
 * `interactorUtil.interactorWaitUtil`.
 *
 * Per ADR-010 only serializable state is retained — the locator's description, not
 * the live locator.
 */
declare class ListEnumerationMismatchError extends ErrorBase {
  readonly locatorDescription: string;
  /** How many elements the item locator matches. */
  readonly matchedCount: number;
  /** How many items positional enumeration reached before it stopped. */
  readonly enumeratedCount: number;
  constructor(itemLocator: PartLocator, driver: {
    driverName: string;
  }, matchedCount: number, enumeratedCount: number);
}
//#endregion
//#region src/errors/LocatorResolutionError.d.ts
declare const LocatorResolutionErrorId = "LocatorResolutionError";
/**
 * Error thrown when a {@link PartLocator} cannot be reduced to a CSS selector —
 * e.g. a {@link LinkedCssLocator} whose match target is absent, or a
 * `valueExtract` method the resolver does not implement.
 *
 * Lives in the interactor-level error hierarchy (ADR-010): it carries only a
 * serializable {@link locatorDescription} derived via
 * {@link getLocatorInfoForErrorLog}, so consumers that catch on
 * `InteractorErrorBase` see it alongside {@link ElementNotFoundError} rather than
 * a bare `Error` escaping the frozen contract (#1051).
 */
declare class LocatorResolutionError extends InteractorErrorBase {
  constructor(locator: PartLocator, reason: string);
}
//#endregion
//#region src/errors/MissingPartError.d.ts
declare const MissingPartErrorId = "MissingPartError";
/**
 * Thrown when one or more of a driver's declared `ScenePart` parts are not
 * found to exist — e.g. `enforcePartExistence` guards a method that requires
 * an optional part to be present before acting on it. Existence means presence
 * in the DOM, regardless of visibility.
 *
 * Carries the offending {@link missingPartName} (a single part name or, for a
 * multi-part check, the array of every name that was missing) alongside the
 * ADR-010 serializable `driverName` snapshot inherited from {@link ErrorBase}.
 */
declare class MissingPartError<T extends ScenePart> extends ErrorBase {
  readonly missingPartName: keyof T | ReadonlyArray<keyof T>;
  constructor(missingPartName: keyof T | ReadonlyArray<keyof T>, driver: {
    driverName: string;
  });
}
//#endregion
//#region src/errors/PostconditionNotMetError.d.ts
declare const PostconditionNotMetErrorId = "PostconditionNotMetError";
/**
 * Thrown when a driver action's own postcondition did not hold within its
 * timeout — see {@link ComponentDriver.awaitPostcondition}.
 *
 * This error exists to make an unmet postcondition **loud at its cause**. The
 * alternative — letting the action resolve anyway — surfaces later as a
 * baffling read result (`Expected: "Banana" / Received: null`) attributed to
 * the assertion rather than to the action that never finished, which is exactly
 * the diagnosis cost this class removes.
 *
 * Per ADR-010 it retains only the serializable `driverName` inherited from
 * {@link ErrorBase} plus the human-readable {@link postcondition} description —
 * never a live driver, locator, or probe.
 *
 * @param driver Anything name-bearing (a driver satisfies `{ driverName }`);
 *   only its `driverName` is retained.
 * @param postcondition Human-readable description of what was awaited, phrased
 *   as the state that failed to arrive (e.g. `"selectByLabel('Banana'): the
 *   dropdown to close with the selection committed"`).
 * @param timeoutMs How long it was awaited before giving up.
 */
declare class PostconditionNotMetError extends ErrorBase {
  readonly postcondition: string;
  constructor(driver: {
    driverName: string;
  }, postcondition: string, timeoutMs: number);
}
//#endregion
//#region src/errors/WaitForFailureError.d.ts
declare const WaitForFailureErrorId = "WaitForFailureError";
/**
 * Thrown when `waitUntil`/`waitFor`-style polling (see `interactorUtil.interactorWaitUtil`)
 * times out before an element reaches the requested {@link WaitForOption.condition}
 * (`attached`, `detached`, `visible`, or `hidden`) — the element's actual state
 * never matched the expected one within `option.timeoutMs`.
 *
 * Per ADR-010 it carries only the serializable `locatorDescription` string
 * inherited from {@link InteractorErrorBase}, not the live locator.
 */
declare class WaitForFailureError extends InteractorErrorBase {
  constructor(locator: PartLocator, option: WaitForOption);
}
//#endregion
//#region src/example/types.d.ts
/**
 * Shape of a demo/example UI unit used by the monorepo's example harness and
 * `package-tests`. Exported for that internal tooling, not part of the stable
 * 1.0 consumer API.
 *
 * @internal
 */
interface IExampleUIUnit<ExampleT> {
  title: string;
  description?: string;
  ui: ExampleT;
}
/**
 * A demo/example UI unit paired with the `ScenePart` its tests drive. Internal
 * example-harness tooling, not part of the stable 1.0 consumer API.
 *
 * @internal
 */
interface IExampleUnit<T extends ScenePart, ExampleT> extends IExampleUIUnit<ExampleT> {
  scene: T;
}
declare namespace collectionUtil_d_exports {
  export { DifferenceResult, getDifference, toArray };
}
interface DifferenceResult<T> {
  toAdd: ReadonlySet<T>;
  toRemove: ReadonlySet<T>;
}
declare function getDifference<T>(from: Iterable<T>, to: Iterable<T>): DifferenceResult<T>;
declare function toArray<T>(item: T | readonly T[]): T[];
declare namespace dateUtil_d_exports {
  export { DateValidationFailureResult, DateValidationResult, DateValidationSuccessResult, HtmlInputDateType, IDateValidationDescriptor, assertValidHtmlDateInputValue, htmlInputDateTypes, isHtmlDateInputType, isHtmlInputDateFormat, isHtmlInputDateTimeFormat, isHtmlInputTimeFormat, validateHtmlDateInput };
}
declare function isHtmlInputDateFormat(input: string): boolean;
declare function isHtmlInputTimeFormat(input: string): boolean;
/**
 * Whether the input is in the format of an HTML input datetime-local.
 * @param input
 * @returns
 */
declare function isHtmlInputDateTimeFormat(input: string): boolean;
/**
 * Supported html input date types.
 *
 * Deliberately un-annotated: a `readonly string[]` annotation would widen the
 * `as const` tuple back to `string`, and {@link HtmlInputDateType} — a frozen
 * public type — would degrade with it, making {@link isHtmlDateInputType} a
 * no-op guard and {@link dateValidationDescriptors} lose its exhaustiveness
 * check. Narrowing a public type is major-only once 1.0 tags.
 */
declare const htmlInputDateTypes: readonly ["date", "datetime-local", "time"];
type HtmlInputDateType = (typeof htmlInputDateTypes)[number];
interface IDateValidationDescriptor {
  type: HtmlInputDateType;
  validate: (input: string) => boolean;
  format: string;
  example: string;
}
interface DateValidationSuccessResult {
  valid: true;
}
interface DateValidationFailureResult {
  valid: false;
  format: string;
  example: string;
}
type DateValidationResult = DateValidationSuccessResult | DateValidationFailureResult;
declare function isHtmlDateInputType(type: string): type is HtmlInputDateType;
declare function validateHtmlDateInput(type: string, input: string): DateValidationResult;
/**
 * Guard the `enterText` path: throw a descriptive error when `value` is being
 * entered into a date/time/datetime-local input in the wrong format.
 *
 * WHY it lives here (#1053): this is environment-agnostic policy — the SAME rule
 * applies whether text is typed via `userEvent` (jsdom) or `fill` (Playwright).
 * Both `DOMInteractor.enterText` and `PlaywrightInteractor.enterText` used to
 * inline this validate-and-throw block, which had drifted: only the DOM leg
 * short-circuited the empty string, so `enterText('')` on a date input threw
 * "Invalid date format" in Playwright but cleared the field in jsdom. Hoisting
 * the policy here — including the empty-string carve-out — makes both adapters
 * behave identically on the same input.
 *
 * An empty `value` is a pure clear (there is nothing to validate) and a
 * non-date `type` is not our concern, so both are accepted as no-ops.
 *
 * @param type - The input's `type` attribute (e.g. `'date'`, `'text'`).
 * @param value - The text about to be entered.
 * @throws {Error} If `type` is a date input type and `value` is a non-empty,
 *   badly-formatted string.
 */
declare function assertValidHtmlDateInputValue(type: string, value: string): void;
declare namespace escapeUtil_d_exports {
  export { escapeCssClassName, escapeName, escapeValue };
}
declare function escapeName(name: string): string;
/**
 * Escaping based on the CSS spec: https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier
 * @param value
 * @returns
 */
declare function escapeValue(value: string): string;
/**
 * Escapes special characters in CSS class names.
 * This is necessary for class names containing characters like colons (Tailwind's `hover:bg-blue`),
 * dots, brackets, or other CSS selector metacharacters.
 * @param name - The CSS class name to escape
 * @returns The escaped class name safe for use in CSS selectors
 */
declare function escapeCssClassName(name: string): string;
//#endregion
//#region src/utils/getLocatorInfoForErrorLog.d.ts
/**
 * Display a rough description of the locators for error logging
 * this is an estimate, not a precise description with the absence of interactor
 * locators such as LinkedCssLocator would not be interpreted correctly
 *
 * Lives in its own leaf module (imports only the locator model, never the error
 * hierarchy) so the interactor errors that build their `locatorDescription` from
 * it can depend on it without pulling in `locatorUtil` — which throws
 * {@link LocatorResolutionError} and would otherwise close a `locatorUtil ↔
 * error` import cycle.
 *
 * @param locator
 * @returns
 */
declare function getLocatorInfoForErrorLog(locator: PartLocator): string;
declare namespace locatorUtil_d_exports {
  export { OverrideLocatorRelativePositionOption, and, append, defaultOverrideLocatorRelativePositionOption, documentRootSelector, getLinkedCssLocatorMatchingTargetValue, getLocatorInfoForErrorLog, overrideLocatorRelativePosition, splitAtAccessibleRoleLocator, toCssSelector };
}
/**
 * The portable document-root selector an empty locator chain reduces to. `<html>`
 * in the DOM, matched by both `document.querySelector(':root')` (jsdom) and
 * `page.locator(':root')` (Chromium). Used so the engine-root locator (`[]`, in
 * the DOM/Playwright adapters) resolves to a real element instead of `''`, which
 * throws a CSS parse error in every engine. See #1048.
 */
declare const documentRootSelector = ":root";
declare function append(locatorBase: PartLocator, ...locatorsToAppend: PartLocator[]): PartLocator;
/**
 * Compose additional matchers onto the SAME element, producing one compound
 * CSS selector — e.g. `[role="button"]` and `[aria-label="Open"]` together
 * become `[role="button"][aria-label="Open"]`.
 *
 * This is the ergonomic, footgun-free form of same-element composition: it
 * supersedes `append(byRole('button'), byAriaLabel('Open', 'Same'))` — there is
 * no `'Same'` argument to remember (the relationship no longer has to be stored
 * on the appended child) and no wrapper call. The result keeps `base`'s position
 * relative to its parent; the appended matchers contribute only their
 * attribute/selector fragment.
 *
 * Same-element, pure-CSS only:
 * - Put a tag-name matcher ({@link byTagName}) FIRST — a CSS type selector is
 *   only valid at the start of a compound (`input[type="text"]`, never
 *   `[type="text"]input`).
 * - Computed accessible names (`aria-labelledby` / `<label>` / text) are not
 *   CSS-expressible and stay out of scope (see #923); compose a verbatim
 *   `aria-label` via {@link byAriaLabel} instead.
 * - Linked locators ({@link byLinkedElement}) resolve at runtime and cannot be
 *   folded into a static compound; passing one as `base` or as a matcher throws.
 * - `base` and every matcher must each be a one-element, primitive chain — what
 *   a fresh `by*` call produces, and also what `and()` itself returns, so its
 *   result can be composed again. A multi-element chain (`append()`'s typical
 *   output) has no single element left to compound onto and is rejected.
 *
 * @param base - The locator to compound additional matchers onto.
 * @param locators - Additional same-element matchers to compound onto `base`.
 * @example
 * ```ts
 * const openButton = locatorUtil.and(byRole('button'), byAriaLabel('Open'));
 * const activeTab = locatorUtil.and(byRole('tab'), byAttribute('aria-selected', 'true'));
 * ```
 */
declare function and(base: PartLocator, ...locators: PartLocator[]): PartLocator;
/**
 * Split a locator chain at its {@link AccessibleRoleLocator} segment (built by
 * `findByRole`) — the second resolution channel that bypasses
 * {@link toCssSelector} entirely, resolving by computed accessible name
 * instead of CSS (see #923). Returns `undefined` when the chain has no such
 * segment — the common, CSS-only case every existing locator takes.
 *
 * The accessible-role segment must be the chain's LAST element: nothing can
 * be appended after a name-aware resolution result, since there is no CSS
 * expression for "descendant of an accname match." `before` — everything
 * ahead of it — still resolves normally via {@link toCssSelector} and scopes
 * the accname search to that ancestor's subtree.
 *
 * @throws {LocatorResolutionError} If the segment is present but not the last
 * element of the chain (covers both "something follows it" and "more than one
 * such segment" — the first occurrence not being terminal implies either).
 */
declare function splitAtAccessibleRoleLocator(locator: PartLocator): Optional<{
  before: PartLocator;
  roleLocator: AccessibleRoleLocator;
}>;
/**
 * Reduce a {@link PartLocator} to the single CSS selector the interactor runs
 * against the DOM. This is the one locator-resolution seam in the system, and it
 * is **CSS-only by design** for 1.0 — every locator must express itself as CSS
 * here (see [ADR-008](https://github.com/atomic-testing/atomic-testing/blob/main/agent-docs/adr/008-css-dom-only-locator-boundary.md)).
 *
 * An {@link AccessibleRoleLocator} segment (`findByRole`) has no CSS
 * representation at all — see {@link splitAtAccessibleRoleLocator}, which
 * every interactor consults BEFORE reaching this function. Calling this
 * directly with such a locator is a caller error, not a silent fallback.
 */
declare function toCssSelector(locator: PartLocator, interactor: Interactor): Promise<string>;
declare function getLinkedCssLocatorMatchingTargetValue(locator: LinkedCssLocator, context: PartLocator, interactor: Interactor): Promise<Optional<string>>;
interface OverrideLocatorRelativePositionOption {
  shouldOverride: (locator: CssLocator, index: number) => boolean;
}
declare const defaultOverrideLocatorRelativePositionOption: Readonly<OverrideLocatorRelativePositionOption>;
/**
 * Override the supplied locator chain's relative position; by default only the
 * first locator in the chain is overridden.
 * @param locator
 * @param relative
 * @param option
 * @returns
 */
declare function overrideLocatorRelativePosition(locator: PartLocator, relative: LocatorRelativePosition, option?: Partial<Readonly<OverrideLocatorRelativePositionOption>>): PartLocator;
declare namespace interactorUtil_d_exports {
  export { interactorWaitUtil };
}
/**
 * Wait until the element reaches the desired condition.  By default, it waits until the element is attached to the DOM.
 * @param locator The locator of the element to wait for
 * @param interactor The interactor to use to wait for the element
 * @param option Optional parameters to customize the wait behavior
 */
declare function interactorWaitUtil(locator: PartLocator, interactor: Interactor, option?: Partial<Readonly<WaitForOption>>): Promise<void>;
declare namespace visibilityUtil_d_exports {
  export { isElementVisibleByStyle };
}
/**
 * Environment-agnostic visibility policy shared by `DOMInteractor` and
 * `PlaywrightInteractor` so the two cannot drift (#1053). It is the single source
 * of truth for what "visible" means; each interactor supplies only the primitive
 * to read computed style, mirroring the `interactorUtil.interactorWaitUtil`
 * parameterized-by-primitive house pattern.
 *
 * WHY the three properties are treated differently:
 *
 * - `visibility` is an INHERITED property, so an element's own computed
 *   `visibility` already reflects an ancestor's `visibility: hidden` — while a
 *   descendant that overrides back to `visibility: visible` still reads as
 *   `visible`. Checking the element alone is therefore both sufficient and
 *   correct; walking ancestors would wrongly hide a deliberately re-shown
 *   descendant.
 * - `display: none` and `opacity: 0` are NOT inherited: an ancestor with either
 *   removes the whole subtree from view WITHOUT changing a descendant's own
 *   computed value. Inspecting only the target element (the pre-#1053 bug) let a
 *   child of a hidden ancestor report `true`. So these must be walked up the
 *   ancestor chain — element included — to (and including) the document root.
 *
 * The function is passed BY VALUE into Playwright's `page.evaluate`, which
 * serializes it to the browser. It must therefore stay self-contained: it may
 * reference only its parameters and DOM globals (`getComputedStyle`), never an
 * import, a module-scope helper, or a Node object. Keep it synchronous and
 * free of constructs that transpile to injected runtime helpers.
 *
 * @param element - The element whose visibility is being decided.
 * @param getStyle - Accessor returning an element's computed style. Defaults to
 *   the ambient `getComputedStyle` so the serialized function resolves the DOM
 *   global inside the browser; the DOM leg passes jsdom's `window.getComputedStyle`
 *   explicitly.
 * @returns `true` only when the element itself is not `visibility: hidden` and
 *   the element and every ancestor are displayed (`display !== 'none'`) and
 *   non-transparent (`opacity !== '0'`).
 */
declare function isElementVisibleByStyle(element: Element, getStyle?: (el: Element) => CSSStyleDeclaration): boolean;
declare namespace elementStateUtil_d_exports {
  export { isElementChecked, isElementDisabled };
}
/**
 * Environment-agnostic checked/disabled policy shared by `DOMInteractor` and
 * `PlaywrightInteractor` so the two cannot drift, the same way
 * `visibilityUtil.isElementVisibleByStyle` is shared (#1053).
 *
 * Before this existed the two engines answered differently and neither answer was
 * written down: the DOM leg read only native IDL properties, while the Playwright
 * leg delegated to Playwright's own primitives, which follow labels, consult
 * `aria-checked`, honour a disabled `<fieldset>`/`<optgroup>`, and walk ancestors
 * for `aria-disabled`. Any test asserting a design-system control's state got a
 * different answer per runner. Defining the predicate once and running it in both
 * places makes them agree by construction rather than by parallel maintenance.
 *
 * Both functions are passed BY VALUE into Playwright's `page.evaluate`, which
 * serializes them to the browser. They must therefore stay self-contained: they may
 * reference only their parameters and DOM globals, never an import, a module-scope
 * constant, or a Node object — which is why the role list below is inlined rather
 * than hoisted. Keep them synchronous and free of constructs that transpile to
 * injected runtime helpers.
 */
/**
 * Whether the element is checked, via the native `checked` property of an
 * `<input type="checkbox">`/`<input type="radio">`, or `aria-checked="true"` on an
 * element whose explicit `role` is a checkable one.
 *
 * `aria-checked="mixed"` and a native `indeterminate` control both report `false`:
 * this contract is two-state, and "partially checked" is not "checked". An element
 * that cannot be checked at all reports `false` rather than throwing, so the read
 * stays total in both engines.
 *
 * @param element - The element whose checked state is being decided. It must be the
 *   control itself; a `<label>` pointing at one is not retargeted.
 */
declare function isElementChecked(element: Element): boolean;
/**
 * Whether the element is disabled, via the native disabled state — including the
 * `<fieldset disabled>` and `<optgroup disabled>` cascades the HTML spec defines —
 * or the nearest `aria-disabled` on the element or an ancestor being `"true"`.
 *
 * The nearest explicit `aria-disabled` wins, so a re-enabled descendant of a
 * disabled container reports `false`. An element with no disabled semantics at all
 * reports `false` rather than throwing, so the read stays total in both engines.
 *
 * @param element - The element whose disabled state is being decided. It must be the
 *   control itself; a `<label>` pointing at one is not retargeted.
 */
declare function isElementDisabled(element: Element): boolean;
//#endregion
export { AccessibleRoleLocator, type AccessibleRoleLocatorRelativePosition, type AssertScenePlaceableDriver, BlurOption, BoundingRect, ClickOption, type CommutableComponentDriverOption, ComponentDriver, type ComponentDriverCtor, type ComponentPartDefinition, CssLocator, type CssProperty, type DateValidationFailureResult, type DateValidationResult, type DateValidationSuccessResult, ElementNotFoundError, ElementNotFoundErrorId, type ElementQueries, type EnterTextOption, ErrorBase, type FocusActions, FocusOption, type FormActions, HoverOption, type HtmlInputDateType, type IClickableDriver, type IComponentDriver, type IComponentDriverOption, type IDisableableDriver, IExampleUIUnit, IExampleUnit, type IFormFieldDriver, type IInputDriver, type IMouseInteractableDriver, type IReadonlyableDriver, type IRequirableDriver, type ITestEngine, type ITestEngineOption, type IToggleDriver, type IValidatableDriver, type Interactor, InteractorErrorBase, ItemNotFoundError, ItemNotFoundErrorId, type KeyboardActions, LinkedCssLocator, ListComponentDriver, type ListComponentDriverOption, type ListComponentDriverSpecificOption, type ListComponentPartDefinition, ListEnumerationMismatchError, ListEnumerationMismatchErrorId, type LocatorComplexity, type LocatorRelativePosition, LocatorResolutionError, LocatorResolutionErrorId, MissingPartError, MissingPartErrorId, MouseDownOption, MouseEnterOption, MouseLeaveOption, MouseMoveOption, MouseOption, MouseOutOption, MouseUpOption, type Nullable, type Optional, type PartLocator, type PartName, Point, type PointerActions, PostconditionNotMetError, PostconditionNotMetErrorId, type PressKeyOption, type ScenePart, type ScenePartDefinition, type ScenePartDriver, type ScenePlaceableDriverCtor, type ScrollActions, TestEngine, WaitForCondition, WaitForFailureError, WaitForFailureErrorId, WaitForOption, type WaitUntilOption, type Waiter, assertValidClickCount, byAriaLabel, byAttribute, byChecked, byCssClass, byCssSelector, byDataTestId, byInputType, byLinkedElement, byName, byRole, byTagName, byValue, childListHelper_d_exports as childListHelper, collectionUtil_d_exports as collectionUtil, dateUtil_d_exports as dateUtil, defaultWaitForOption, elementStateUtil_d_exports as elementStateUtil, escapeUtil_d_exports as escapeUtil, findByRole, type htmlInputDateTypes, interactorUtil_d_exports as interactorUtil, listHelper_d_exports as listHelper, locatorUtil_d_exports as locatorUtil, timingUtil_d_exports as timingUtil, visibilityUtil_d_exports as visibilityUtil };
//# sourceMappingURL=index.d.cts.map