import {
  AccessibleRoleLocator,
  assertValidClickCount,
  BlurOption,
  BoundingRect,
  ClickOption,
  CssProperty,
  dateUtil,
  defaultWaitForOption,
  ElementNotFoundError,
  EnterTextOption,
  FocusOption,
  HoverOption,
  Interactor,
  interactorUtil,
  locatorUtil,
  MouseDownOption,
  MouseEnterOption,
  MouseLeaveOption,
  MouseMoveOption,
  MouseOutOption,
  MouseUpOption,
  Optional,
  PartLocator,
  Point,
  PressKeyOption,
  timingUtil,
  elementStateUtil,
  visibilityUtil,
  WaitForOption,
  WaitUntilOption,
} from '@atomic-testing/core';
import { fireEvent, queryAllByRole } from '@testing-library/dom';
import defaultUserEvent from '@testing-library/user-event';

import { FakeDataTransfer, FakeMouseEvent } from './fakeEvents';
import { DOMInteractorOption, UserEventDispatcher } from './types';

/**
 * Derive a `KeyboardEvent.code` from a `KeyboardEvent.key`, approximating what
 * a real browser reports for a standard US layout: letters map to `KeyX`,
 * digits to `DigitX`, space to `Space`, and named keys (`ArrowRight`, `Enter`,
 * `Home`, …) carry their own name as the code. jsdom leaves `code` empty
 * unless supplied, but real keyboard events always populate it — and component
 * libraries legitimately switch on `code` (PrimeVue's Slider does), so the
 * jsdom leg must match. Left/right-variant modifiers (`Shift` → `ShiftLeft`)
 * are not disambiguated; a bare modifier press is not a supported gesture here.
 */
function deriveKeyCode(key: string): string {
  if (key === ' ') {
    return 'Space';
  }
  if (/^[a-zA-Z]$/.test(key)) {
    return `Key${key.toUpperCase()}`;
  }
  if (/^[0-9]$/.test(key)) {
    return `Digit${key}`;
  }
  return key;
}

/**
 * Whether a key press on this element needs `beforeinput`/`input` fidelity — true
 * only for a `contenteditable` host. Such a host commits edits from input events
 * that a bare `keydown`/`keyup` never produces (the MUI X picker section field
 * clears on `Backspace` this way, see #903), so it must go through
 * `userEvent.keyboard`.
 *
 * Everything else — including `<input>`/`<textarea>` — keeps the direct
 * `fireEvent.keyDown` dispatch on the element, which is what keyboard-driven
 * drivers rely on and matches the pre-existing behavior. `userEvent.keyboard`
 * delivers to `document.activeElement` and regressed command-key contracts on
 * both non-editable and editable targets: Angular Material `MatSelect`
 * (open on `Enter`) and `MatAutocomplete` (close on `Escape`, whose target is a
 * text `<input>`). Text fields do their actual editing through
 * {@link DOMInteractor.enterText}/{@link DOMInteractor.typeText}, not `pressKey`,
 * so excluding them here loses nothing. jsdom leaves `isContentEditable`
 * `undefined`, so the attribute is consulted directly rather than the property.
 */
function needsInputEventFidelity(el: Element): boolean {
  if ((el as HTMLElement).isContentEditable === true) {
    return true;
  }
  const contentEditable = el.getAttribute('contenteditable');
  return contentEditable === '' || contentEditable === 'true';
}

/**
 * The jsdom-backed {@link Interactor} implementation — dispatches events and
 * reads the DOM via `@testing-library/dom`'s `fireEvent` and `user-event`. The
 * blessed base for every framework adapter that runs against jsdom (ADR-002,
 * ADR-007): `ReactInteractor` and `VueInteractor` extend it and layer their
 * reactivity flush onto the {@link runInteraction} seam rather than
 * reimplementing the primitives. `PlaywrightInteractor` does not extend this
 * class — its browser backing shares no implementation with jsdom.
 */
export class DOMInteractor implements Interactor {
  protected readonly userEvent: UserEventDispatcher;

  constructor(
    protected readonly rootEl: HTMLElement = document.documentElement,
    option?: DOMInteractorOption
  ) {
    this.userEvent = option?.userEvent ?? defaultUserEvent;
  }

  /**
   * Template-method seam every mutating primitive (and both wait conditions)
   * routes through. The base runs the interaction verbatim; framework adapters
   * override it to flush their reactivity around the whole interaction —
   * `ReactInteractor` wraps it in `act(...)`, `VueInteractor` awaits
   * `nextTick()`. Because every mutation funnels through this one method, a new
   * mutating primitive added to this base is flushed by every adapter
   * automatically — closing the silent gap that the previous per-method
   * overrides left open, where an un-mirrored primitive was inherited unwrapped
   * (#1052).
   *
   * Reads (`getText`, `getAttribute`, `exists`, …) deliberately do NOT route
   * through here: they observe state without mutating it, so there is nothing to
   * flush.
   */
  protected runInteraction<T>(fn: () => Promise<T>): Promise<T> {
    return fn();
  }

  async getAttribute(locator: PartLocator, name: string, isMultiple: true): Promise<readonly string[]>;
  async getAttribute(locator: PartLocator, name: string, isMultiple: false): Promise<Optional<string>>;
  async getAttribute(locator: PartLocator, name: string): Promise<Optional<string>>;
  async getAttribute(
    locator: PartLocator,
    name: string,
    isMultiple?: boolean
  ): Promise<Optional<string> | readonly string[]> {
    if (isMultiple) {
      const elements = await this.getElement(locator, true);
      return Promise.resolve(elements.map(el => el.getAttribute(name)!));
    } else {
      const el = await this.getElement(locator);
      if (el != null) {
        return Promise.resolve(el.getAttribute(name) ?? undefined);
      }
      return undefined;
    }
  }

  async getStyleValue(locator: PartLocator, propertyName: CssProperty): Promise<Optional<string>> {
    const el = await this.getElement(locator);
    if (el != null) {
      const computedStyle = window.getComputedStyle(el as HTMLElement);
      const val = computedStyle[propertyName] as string;
      return Promise.resolve(val ?? undefined);
    }
    return undefined;
  }

  protected calculateMousePosition(el: Element, preferredPoint?: Point) {
    const rect = el.getBoundingClientRect();
    const mouseLocation: Point = {
      x: preferredPoint?.x != null ? rect.left + preferredPoint?.x : rect.left + rect.width / 2,
      y: preferredPoint?.y != null ? rect.top + preferredPoint?.y : rect.top + rect.height / 2,
    };
    return mouseLocation;
  }

  /**
   * Dispatch a click event on the element that matches the locator.
   *
   * @param locator - Locator used to find the target element
   * @param option - Optional click configuration such as the click position
   * @returns A promise that resolves after the event is triggered
   * @throws {ElementNotFoundError} If the element is not found
   */
  async click(locator: PartLocator, option?: ClickOption): Promise<void> {
    assertValidClickCount(option?.clickCount);
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'click');
      }

      const isDoubleClick = option?.clickCount === 2;
      const isSimpleEvent = option?.position == null;
      if (isSimpleEvent) {
        // Some MUI component does not work with fireEvent('click', ...)
        await (isDoubleClick ? this.userEvent.dblClick(el) : this.userEvent.click(el));
      } else {
        const clickLocation = this.calculateMousePosition(el, option?.position);
        const dispatch = (type: string) =>
          fireEvent(
            el,
            new FakeMouseEvent(type, {
              bubbles: true,
              clientX: clickLocation.x,
              clientY: clickLocation.y,
            })
          );
        // A real double-click gesture is two full clicks followed by the
        // `dblclick` event — firing `dblclick` alone would skip `onClick`
        // handlers a component also relies on.
        if (isDoubleClick) {
          dispatch('click');
          dispatch('click');
          dispatch('dblclick');
        } else {
          dispatch('click');
        }
      }
    });
  }

  /**
   * Move the mouse over the element.
   *
   * @param locator - Locator used to find the target element
   * @param _option - Reserved for future use
   * @returns A promise that resolves after the hover event
   * @throws {ElementNotFoundError} If the element is not found
   */
  async hover(locator: PartLocator, _option?: HoverOption): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'hover');
      }
      await this.userEvent.hover(el);
    });
  }

  /**
   * Dispatch a `mousemove` event on the target element.
   *
   * @param locator - Locator used to find the target element
   * @param option - Allows specifying the mouse position relative to the element
   * @returns A promise that resolves once the event has been dispatched
   * @throws {ElementNotFoundError} If the element is not found
   */
  async mouseMove(locator: PartLocator, option?: Partial<MouseMoveOption>): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'mouseMove');
      }

      const moveLocation = this.calculateMousePosition(el, option?.position);
      const evt = new FakeMouseEvent('mousemove', {
        bubbles: true,
        clientX: moveLocation.x,
        clientY: moveLocation.y,
      });

      fireEvent(el, evt);
    });
  }

  /**
   * Dispatch a `mousedown` event on the target element.
   *
   * @param locator - Locator used to find the target element
   * @param option - Allows specifying the mouse position relative to the element
   * @returns Promise resolved when the event is dispatched
   * @throws {ElementNotFoundError} If the element is not found
   */
  async mouseDown(locator: PartLocator, option?: Partial<MouseDownOption>): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'mouseDown');
      }

      const mouseLocation = this.calculateMousePosition(el, option?.position);
      const evt = new FakeMouseEvent('mousedown', {
        bubbles: true,
        clientX: mouseLocation.x,
        clientY: mouseLocation.y,
      });

      fireEvent(el, evt);
    });
  }

  /**
   * Dispatch a `mouseup` event on the target element.
   *
   * @param locator - Locator used to find the target element
   * @param option - Allows specifying the mouse position relative to the element
   * @returns Promise resolved when the event is dispatched
   * @throws {ElementNotFoundError} If the element is not found
   */
  async mouseUp(locator: PartLocator, option?: Partial<MouseUpOption>): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'mouseUp');
      }

      const mouseLocation = this.calculateMousePosition(el, option?.position);
      const evt = new FakeMouseEvent('mouseup', {
        bubbles: true,
        clientX: mouseLocation.x,
        clientY: mouseLocation.y,
      });

      fireEvent(el, evt);
    });
  }

  /**
   * Dispatch a `mouseover` event on the target element.
   *
   * @param locator - Locator used to find the target element
   * @param option - Optional mouse position relative to the element
   * @returns Promise resolved once the event is dispatched
   * @throws {ElementNotFoundError} If the element is not found
   */
  async mouseOver(locator: PartLocator, option?: Partial<HoverOption>): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'mouseOver');
      }

      const moveLocation = this.calculateMousePosition(el, option?.position);
      const evt = new FakeMouseEvent('mouseover', {
        bubbles: true,
        clientX: moveLocation.x,
        clientY: moveLocation.y,
      });

      fireEvent(el, evt);
    });
  }

  /**
   * Dispatch a `mouseout` event on the target element.
   *
   * @param locator - Locator used to find the target element
   * @param _option - Reserved for future use
   * @returns Promise resolved once the event is dispatched
   * @throws {ElementNotFoundError} If the element is not found
   */
  async mouseOut(locator: PartLocator, _option?: Partial<MouseOutOption>): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'mouseOut');
      }

      fireEvent.mouseOut(el);
    });
  }

  /**
   * Dispatch a `mouseenter` event on the target element.
   *
   * @param locator - Locator used to find the target element
   * @param _option - Reserved for future use
   * @returns Promise resolved after the event dispatches
   * @throws {ElementNotFoundError} If the element is not found
   */
  async mouseEnter(locator: PartLocator, _option?: Partial<MouseEnterOption>): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'mouseEnter');
      }

      // mouseOver would trigger mouseEnter event
      // hover fireEvent.mouseEnter does not
      fireEvent.mouseOver(el);
    });
  }

  /**
   * Dispatch a `mouseleave` event on the target element.
   *
   * @param locator - Locator used to find the target element
   * @param _option - Reserved for future use
   * @returns Promise resolved once the event is dispatched
   * @throws {ElementNotFoundError} If the element is not found
   */
  async mouseLeave(locator: PartLocator, _option?: Partial<MouseLeaveOption>): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'mouseLeave');
      }

      fireEvent.mouseOut(el);
    });
  }

  /**
   * Move focus to the element found by the locator.
   *
   * @param locator - Locator used to find the target element
   * @param _option - Reserved for future use
   * @returns Promise resolved when focus has been applied
   * @throws {ElementNotFoundError} If the element is not found
   */
  async focus(locator: PartLocator, _option?: Partial<FocusOption>): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'focus');
      }
      if ('focus' in el === false) {
        return;
      }
      (el as HTMLInputElement).focus();
    });
  }

  /**
   * Remove focus from the element found by the locator.
   *
   * @param locator - Locator used to find the target element
   * @param _option - Reserved for future use
   * @returns Promise resolved when blur has been applied
   * @throws {ElementNotFoundError} If the element is not found
   */
  async blur(locator: PartLocator, _option?: Partial<BlurOption>): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'blur');
      }
      if ('blur' in el === false) {
        return;
      }
      (el as HTMLInputElement).blur();
    });
  }

  /**
   * Legacy numeric key codes for the named keys drivers press. Synthetic
   * `KeyboardEvent`s carry `keyCode: 0` unless told otherwise, and several
   * component libraries (Angular Material/CDK among them) still dispatch on
   * `event.keyCode` rather than `event.key` — without this a synthetic
   * `Escape`/`Enter` is silently ignored. Real browser input (Playwright)
   * carries the code natively; this map restores parity for the DOM path.
   */
  private static readonly legacyKeyCodes: Readonly<Record<string, number>> = {
    Backspace: 8,
    Tab: 9,
    Enter: 13,
    Escape: 27,
    ' ': 32,
    PageUp: 33,
    PageDown: 34,
    End: 35,
    Home: 36,
    ArrowLeft: 37,
    ArrowUp: 38,
    ArrowRight: 39,
    ArrowDown: 40,
    Delete: 46,
  };

  private static legacyKeyCodeOf(key: string): number | undefined {
    const named = DOMInteractor.legacyKeyCodes[key];
    if (named != null) {
      return named;
    }
    // Letters and digits: the legacy code is the uppercase character code.
    return /^[a-zA-Z0-9]$/.test(key) ? key.toUpperCase().charCodeAt(0) : undefined;
  }

  /**
   * Dispatch a key press (`keydown` + `keyup`) on the element matched by the locator.
   *
   * The element is focused first so the key originates from the active element,
   * matching a real key press. `fireEvent` is used over `userEvent.keyboard` for
   * determinism and because MUI handlers read `event.key` directly. The physical
   * `code` is derived from `key` (see {@link deriveKeyCode}) so handlers that
   * switch on `event.code` — e.g. PrimeVue's Slider — behave as they do under a
   * real browser event, where `code` is always populated.
   *
   * `key` is dispatched verbatim — a `shift` modifier is NOT used to derive a
   * shifted character (`{ key: 'a', shift: true }` stays `key: 'a'`, never
   * folded to `'A'`), matching `PlaywrightInteractor`'s behavior (see
   * {@link KeyboardActions.pressKey} for the cross-engine verification, #924).
   *
   * @param locator - Locator used to find the target element
   * @param key - A `KeyboardEvent.key` value, e.g. `'Escape'`, `'Backspace'`
   * @param option - Modifier flags folded into the event init as
   * `ctrlKey`/`shiftKey`/`altKey`/`metaKey`, so a handler reading
   * `event.ctrlKey` (etc.) sees the chord — see {@link PressKeyOption}
   * @returns Promise resolved once the events have been dispatched
   * @throws {ElementNotFoundError} If the element is not found
   */
  async pressKey(locator: PartLocator, key: string, option?: Partial<PressKeyOption>): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'pressKey');
      }
      if ('focus' in el) {
        (el as HTMLElement).focus();
      }

      // For a focused text-editing target, dispatch through `userEvent.keyboard`
      // so the press carries full editing fidelity — keydown → beforeinput/input →
      // keyup — matching Playwright's `locator.press()`. A bare keydown/keyup pair
      // reaches `KeyboardEvent.key` handlers but is invisible to components that
      // commit edits from input events (e.g. the MUI X picker section field
      // clearing on Backspace, see #903). This is gated to editing targets
      // ({@link needsInputEventFidelity}): command targets (combobox, dialog,
      // chip) must keep the direct `fireEvent` dispatch their keyboard handlers
      // rely on — `userEvent.keyboard` delivers to `document.activeElement`, which
      // broke the Angular Material `MatSelect` open-on-Enter path.
      const activeElement = el.ownerDocument?.activeElement;
      const holdsFocus = el === activeElement || (activeElement != null && el.contains(activeElement));
      if (holdsFocus && needsInputEventFidelity(el)) {
        // Printable keys are typed as-is (doubling `{`/`[` so user-event's
        // descriptor syntax never engages); named keys become `{Key}` descriptors.
        // The global flag is defensive — `key.length === 1` means at most one char
        // here — and keeps the escape consistent with `typeText`'s.
        const descriptor = key.length === 1 ? key.replace(/[{[]/g, '$&$&') : `{${key}}`;
        let chord = descriptor;
        if (option?.shift) {
          chord = `{Shift>}${chord}{/Shift}`;
        }
        if (option?.alt) {
          chord = `{Alt>}${chord}{/Alt}`;
        }
        if (option?.ctrl) {
          chord = `{Control>}${chord}{/Control}`;
        }
        if (option?.meta) {
          chord = `{Meta>}${chord}{/Meta}`;
        }
        try {
          await this.userEvent.keyboard(chord);
          return;
        } catch {
          // user-event rejects keys outside its keyboard map while parsing,
          // before dispatching anything — fall through to the bare key events so
          // exotic keys still reach KeyboardEvent.key handlers as before.
        }
      }

      // Non-focusable target (or a key user-event cannot type): dispatch the key
      // events directly on the element, as a real key press cannot originate
      // from it anyway.
      // `keyCode`/`which` mirror `key` for handlers that still read the legacy
      // numeric code (see legacyKeyCodes above).
      const keyCode = DOMInteractor.legacyKeyCodeOf(key);
      const eventInit = {
        key,
        code: deriveKeyCode(key),
        ...(keyCode != null ? { keyCode, which: keyCode } : {}),
        ctrlKey: !!option?.ctrl,
        shiftKey: !!option?.shift,
        altKey: !!option?.alt,
        metaKey: !!option?.meta,
      };
      fireEvent.keyDown(el, eventInit);
      fireEvent.keyUp(el, eventInit);
    });
  }

  /**
   * Dispatch a `contextmenu` (right-click) event on the element matched by the locator.
   *
   * The element is focused first if focusable, mirroring {@link pressKey}, so the
   * event originates from the active element as a real right-click would. A
   * context menu has no `aria-expanded`/controlled-open path, so this dispatched
   * event is the only way to exercise the menu-opening behavior.
   *
   * @param locator - Locator used to find the target element
   * @returns Promise resolved once the event has been dispatched
   * @throws {ElementNotFoundError} If the element is not found
   */
  async contextMenu(locator: PartLocator): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'contextMenu');
      }
      if ('focus' in el) {
        (el as HTMLElement).focus();
      }
      fireEvent.contextMenu(el);
    });
  }

  /**
   * Activate the element matched by the locator without pointer geometry.
   *
   * Uses `userEvent.click`, which ignores layout and coordinates, so it reaches a
   * visually-hidden or covered input that a positional click would miss (e.g. MUI
   * Rating's hidden `<input type="radio">`).
   *
   * @param locator - Locator used to find the target element
   * @returns Promise resolved once the element has been activated
   * @throws {ElementNotFoundError} If the element is not found
   */
  async activate(locator: PartLocator): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'activate');
      }
      await this.userEvent.click(el);
    });
  }

  /**
   * Type text into the element matched by the locator.
   *
   * @param locator - Locator used to find the target element
   * @param text - The string to type
   * @param option - Options such as appending or replacing existing value
   * @returns Promise resolved when typing has completed
   * @throws {ElementNotFoundError} If the element is not found
   */
  async enterText(locator: PartLocator, text: string, option?: Partial<EnterTextOption> | undefined): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'enterText');
      }

      if (!option?.append) {
        await this.userEvent.clear(el);
      }

      // An empty value is a pure clear: `userEvent.clear()` above already emptied
      // the field and `userEvent.type` rejects `''` ("Expected key descriptor"),
      // so there is nothing left to type. Return early on the mechanism grounds
      // that `userEvent.type` cannot take `''`; the shared date-format policy
      // (`dateUtil.assertValidHtmlDateInputValue`) likewise treats `''` as a valid
      // clear, keeping this in lockstep with PlaywrightInteractor's `clear()` +
      // `fill('')`.
      if (text === '') {
        return;
      }

      // Enforce the shared date/time/datetime-local format policy (#1053).
      if (el.tagName === 'INPUT') {
        dateUtil.assertValidHtmlDateInputValue(el.getAttribute('type') ?? '', text);
      }

      await this.userEvent.type(el, text);
    });
  }

  /**
   * Type text into the element as real per-character keystrokes.
   *
   * Focuses the element, then dispatches the characters through
   * `userEvent.keyboard`, which fires the full key event sequence
   * (keydown → beforeinput → input → keyup) against the active element —
   * matching `PlaywrightInteractor`'s `pressSequentially` (focus + keys, no
   * pointer event, no clearing). `{`/`[` are doubled so user-event's
   * descriptor syntax never engages and the text is typed literally.
   *
   * @param locator - Locator used to find the target element
   * @param text - The literal text to type, one keystroke per character
   * @returns Promise resolved once every keystroke has been dispatched
   * @throws {ElementNotFoundError} If the element is not found
   */
  async typeText(locator: PartLocator, text: string): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'typeText');
      }
      if ('focus' in el) {
        (el as HTMLElement).focus();
      }
      // A real browser places a caret inside a contenteditable host on focus;
      // jsdom does not, and userEvent.keyboard inserts at the document selection
      // — so without a caret the keystrokes would land nowhere. Collapse a
      // selection to the end of the host's content (matching userEvent.type's
      // append behavior) unless the caret is already inside it.
      if (el.hasAttribute('contenteditable')) {
        const selection = el.ownerDocument.getSelection();
        if (selection != null && (selection.anchorNode == null || !el.contains(selection.anchorNode))) {
          const range = el.ownerDocument.createRange();
          range.selectNodeContents(el);
          range.collapse(false);
          selection.removeAllRanges();
          selection.addRange(range);
        }
      }
      // userEvent.keyboard('') throws ("Expected key descriptor"), so an empty
      // text is focus-only — the same outcome pressSequentially('') produces.
      if (text === '') {
        return;
      }
      const literalText = text.replace(/[{[]/g, '$&$&');
      await this.userEvent.keyboard(literalText);
    });
  }

  /**
   * Set the value of a range input and fire its change event.
   *
   * `fireEvent.change` assigns the value through the element's native value
   * setter (which both sanitizes it to the input's step and lets React's value
   * tracker observe the change) and dispatches the event so a controlled
   * component re-renders. Typing (`enterText`) does not apply to a range input.
   *
   * @param locator - Locator used to find the range input element
   * @param value - The numeric value to set
   * @returns Promise resolved once the change event has fired
   * @throws {ElementNotFoundError} If the element is not found
   */
  async setRangeValue(locator: PartLocator, value: number): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'setRangeValue');
      }
      fireEvent.change(el, { target: { value: String(value) } });
    });
  }

  /**
   * Select one or more option values in a `<select>` element.
   *
   * @param locator - Locator used to find the select element
   * @param values - Values of the options to select
   * @returns Promise resolved when the options have been selected
   * @throws {ElementNotFoundError} If the element is not found
   */
  async selectOptionValue(locator: PartLocator, values: string[]): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'selectOptionValue');
      }
      await this.userEvent.selectOptions(el, values);
    });
  }

  /**
   * Set the selected files on an `<input type="file">` element.
   *
   * The interactor contract passes filesystem paths, but a file input's value
   * cannot be assigned programmatically — the browser blocks it — so the
   * `FileList` must be populated through `userEvent.upload`, which also fires the
   * `change` event. jsdom has no filesystem and never reads file bytes; only
   * `File.name` is observable, so each path is wrapped in an empty `File` named
   * by its basename. The real bytes matter only to the Playwright layer, which
   * reads the paths natively — keeping `dom-core` free of any `node` dependency.
   *
   * @param locator - Locator used to find the file input element
   * @param files - One or more filesystem paths to upload
   * @returns Promise resolved once the upload change event has fired
   * @throws {ElementNotFoundError} If the element is not found
   */
  async setInputFiles(locator: PartLocator, files: string | string[]): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'setInputFiles');
      }
      const paths = Array.isArray(files) ? files : [files];
      const fileObjects = paths.map(filePath => {
        // `||` (not `??`): split().pop() yields '' (not undefined) for a
        // trailing-separator path, and an empty File name is useless — fall back
        // to the full path in that case.
        const name = filePath.split(/[\\/]/).pop() || filePath;
        return new File([], name);
      });
      await this.userEvent.upload(el as HTMLElement, fileObjects);
    });
  }

  /**
   * Scroll the located element into view.
   *
   * jsdom has no layout engine, so this never produces an observable scroll —
   * geometry stays zeroed and nothing becomes "visible". Worse, jsdom does not
   * implement `Element.prototype.scrollIntoView` as a function in every version,
   * so calling it unguarded would throw a `TypeError`. The `typeof` guard keeps
   * this a safe no-op that resolves; real scrolling behavior is E2E-only.
   *
   * @param locator - Locator used to find the element
   * @throws {ElementNotFoundError} If the element is not found
   */
  async scrollIntoView(locator: PartLocator): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'scrollIntoView');
      }
      if (typeof (el as HTMLElement).scrollIntoView === 'function') {
        (el as HTMLElement).scrollIntoView();
      }
    });
  }

  /**
   * Scroll the located element by the given pixel delta.
   *
   * jsdom has no layout engine, so the scroll offset never changes — this is a
   * no-op behaviorally. As with {@link scrollIntoView}, jsdom may not implement
   * `Element.prototype.scrollBy` as a function, so the `typeof` guard prevents a
   * `TypeError` and keeps the call a safe no-op that resolves; real scroll
   * behavior is E2E-only.
   *
   * @param locator - Locator used to find the scrollable element
   * @param delta - Pixel offset to scroll by
   * @throws {ElementNotFoundError} If the element is not found
   */
  async scrollBy(locator: PartLocator, delta: Point): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'scrollBy');
      }
      if (typeof (el as HTMLElement).scrollBy === 'function') {
        (el as HTMLElement).scrollBy(delta.x, delta.y);
      }
    });
  }

  /**
   * Dispatch a single bubbling mouse event at `point` using the shared
   * {@link FakeMouseEvent}. Centralizes the drag gesture's event shape so
   * {@link drag} and {@link dragTo} cannot drift apart.
   */
  private dispatchMouse(el: Element, type: string, point: Point): void {
    fireEvent(el, new FakeMouseEvent(type, { bubbles: true, clientX: point.x, clientY: point.y }));
  }

  /**
   * Fire the native HTML5 drag-and-drop event sequence — `dragstart` on
   * `sourceEl` → `dragenter`/`dragover`/`drop` on `targetEl` → `dragend` on
   * `sourceEl` — sharing one {@link FakeDataTransfer} across every event, so a
   * `dragstart` handler's `setData` is readable from `drop`'s `getData`.
   * `sourceEl === targetEl` is valid: {@link drag}'s single-element delta
   * gesture has no separate drop target, so it drags and drops onto itself.
   *
   * Fired unconditionally: unlike a real browser — which fires `drop` only
   * when the `dragover` listener calls `preventDefault()` to accept the drop —
   * jsdom has no native drag-recognition machinery to gate on, so this always
   * runs the full sequence. This is NOT identical to {@link
   * PlaywrightInteractor}, whose `drag`/`dragTo` drive a REAL pointer gesture
   * that the real browser's own native DnD recognition processes — including
   * the real `preventDefault()` gate — see #922. A target that opts in the
   * way any real HTML5-DnD target must (calling `preventDefault()` in its
   * `dragover`/`dragenter` handler, as the shared `.suite.ts` fixture does)
   * sees `drop` fire in both engines regardless of this difference; a target
   * that never opts in would still see `drop` here but not in a real browser
   * — an accepted simplification for a synthetic environment with no native
   * gesture recognition to simulate faithfully.
   *
   * jsdom implements neither `DragEvent` nor `DataTransfer` (only
   * `MouseEvent`), so `@testing-library/dom`'s `fireEvent.drag*` dispatch a
   * plain `Event` with `dataTransfer` attached as a property rather than a
   * real `DragEvent` — its own documented recipe for jsdom HTML5 DnD (see
   * https://github.com/jsdom/jsdom/issues/1568). Coordinates are not carried on
   * these events for the same reason {@link dispatchMouse}'s are E2E-only:
   * jsdom has no layout.
   */
  private dispatchHtml5DragSequence(sourceEl: Element, targetEl: Element): void {
    const dataTransfer = new FakeDataTransfer();
    fireEvent.dragStart(sourceEl, { dataTransfer });
    fireEvent.dragEnter(targetEl, { dataTransfer });
    fireEvent.dragOver(targetEl, { dataTransfer });
    fireEvent.drop(targetEl, { dataTransfer });
    fireEvent.dragEnd(sourceEl, { dataTransfer });
  }

  /**
   * Drag the source element and drop it onto the target element.
   *
   * The pointer sequence (`mousedown` on source → `mousemove` on target →
   * `mouseup` on target) is synthesized with the shared {@link dispatchMouse} +
   * {@link calculateMousePosition} pattern. jsdom has no layout, so those
   * coordinates are all zeros — the event wiring (and any drop handler the
   * sequence triggers) is exercised, but the positional outcome is E2E-only.
   *
   * The native HTML5 drag-and-drop sequence
   * (`dragstart`/`dragenter`/`dragover`/`drop`/`dragend` + `dataTransfer`) is
   * ALSO synthesized via {@link dispatchHtml5DragSequence}, so both DnD
   * models — pointer/mouse-based (dnd-kit, react-beautiful-dnd) and native
   * HTML5 (`draggable` + `ondragstart`/`ondragover`/`ondrop`) — are driven by
   * this one primitive (#922).
   *
   * @param source - Locator used to find the element to drag
   * @param target - Locator used to find the drop target
   * @throws {ElementNotFoundError} If either element is not found
   */
  async dragTo(source: PartLocator, target: PartLocator): Promise<void> {
    return this.runInteraction(async () => {
      const sourceEl = await this.getElement(source);
      if (sourceEl == null) {
        throw new ElementNotFoundError(source, 'dragTo');
      }
      const targetEl = await this.getElement(target);
      if (targetEl == null) {
        throw new ElementNotFoundError(target, 'dragTo');
      }

      const sourcePoint = this.calculateMousePosition(sourceEl);
      const targetPoint = this.calculateMousePosition(targetEl);

      this.dispatchMouse(sourceEl, 'mousedown', sourcePoint);
      this.dispatchMouse(targetEl, 'mousemove', targetPoint);
      this.dispatchMouse(targetEl, 'mouseup', targetPoint);
      this.dispatchHtml5DragSequence(sourceEl, targetEl);
    });
  }

  /**
   * Drag the located element by the given pixel delta from its center.
   *
   * The sequence (`mousedown` at center → `mousemove` at center + delta →
   * `mouseup` at center + delta) is synthesized with the shared
   * {@link dispatchMouse} + {@link calculateMousePosition} pattern, using the
   * caller-supplied delta for the move/up coordinates. jsdom has no layout, so the
   * center resolves to zeros and only the event wiring is exercised — the
   * behavioral outcome of the drag is E2E-only.
   *
   * The native HTML5 drag-and-drop sequence is ALSO synthesized (on the same
   * element, as its own drop target — see {@link dispatchHtml5DragSequence}),
   * so a `draggable` element driven by this primitive sees `dragstart` and
   * `dragend` regardless of DnD model (#922).
   *
   * @param locator - Locator used to find the element to drag
   * @param delta - Pixel offset to drag by
   * @throws {ElementNotFoundError} If the element is not found
   */
  async drag(locator: PartLocator, delta: Point): Promise<void> {
    return this.runInteraction(async () => {
      const el = await this.getElement(locator);
      if (el == null) {
        throw new ElementNotFoundError(locator, 'drag');
      }

      const start = this.calculateMousePosition(el);
      const end: Point = { x: start.x + delta.x, y: start.y + delta.y };

      this.dispatchMouse(el, 'mousedown', start);
      this.dispatchMouse(el, 'mousemove', end);
      this.dispatchMouse(el, 'mouseup', end);
      this.dispatchHtml5DragSequence(el, el);
    });
  }

  //#region wait conditions
  async waitUntilComponentState(
    locator: PartLocator,
    option: Partial<Readonly<WaitForOption>> = defaultWaitForOption
  ): Promise<void> {
    // Routed through the seam so a framework adapter's flush wraps the ENTIRE
    // probe loop in one pass (React's single surrounding `act`), not each probe.
    return this.runInteraction(() => interactorUtil.interactorWaitUtil(locator, this, option));
  }

  waitUntil<T>(option: WaitUntilOption<T>): Promise<T> {
    return this.runInteraction(() => timingUtil.waitUntil(option));
  }
  //#endregion

  async exists(locator: PartLocator): Promise<boolean> {
    const el = await this.getElement(locator);
    return Promise.resolve(el != null);
  }

  /**
   * Count every element matching the locator — the length of the multi-match
   * query. Reuses the {@link getElement} multiple-overload rather than a second
   * `querySelectorAll` path, so the document-root (`:root`) escape is honored in
   * exactly one place. A read: it does NOT route through {@link runInteraction}.
   */
  async getElementCount(locator: PartLocator): Promise<number> {
    const elements = await this.getElement(locator, true);
    return elements.length;
  }

  async getElement<T extends Element = Element>(locator: PartLocator, isMultiple: true): Promise<readonly T[]>;
  async getElement<T extends Element = Element>(locator: PartLocator, isMultiple: false): Promise<Optional<T>>;
  async getElement<T extends Element = Element>(locator: PartLocator): Promise<Optional<T>>;
  async getElement<T extends Element = Element>(locator: PartLocator, isMultiple = false) {
    const accessibleRoleSplit = locatorUtil.splitAtAccessibleRoleLocator(locator);
    if (accessibleRoleSplit != null) {
      return this.getElementByAccessibleRole<T>(accessibleRoleSplit, isMultiple);
    }

    const cssLocator = await locatorUtil.toCssSelector(locator, this);
    // The engine-root locator (`[]`) resolves to `:root`, which matches `<html>` —
    // an ancestor of `rootEl`, so `rootEl.querySelector(':root')` finds nothing.
    // Query from the document in that case, matching `document.querySelector(':root')`
    // and Playwright's `page.locator(':root')`. See #1048.
    const escapesToDocumentRoot =
      cssLocator === locatorUtil.documentRootSelector || this.escapesToDocumentRoot(locator);
    const queryRoot = escapesToDocumentRoot ? this.rootEl.ownerDocument : this.rootEl;
    if (isMultiple) {
      const elList = queryRoot.querySelectorAll<T>(cssLocator);
      const result: T[] = [];
      elList.forEach(el => result.push(el));
      return result;
    }
    return queryRoot.querySelector<T>(cssLocator) ?? undefined;
  }

  /**
   * Resolve a locator chain split at its {@link AccessibleRoleLocator}
   * segment (`findByRole`) — the second resolution channel, bypassing CSS
   * entirely (#923). Three cases for the scope the accname search runs
   * within, mirroring how an ordinary CSS chain resolves:
   *
   * - `roleLocator.relative === 'Root'` — escapes to the document root
   *   (via {@link getElement}'s existing `[]` → `:root` handling), mirroring
   *   how a trailing `'Root'` locator in an ordinary chain slices away
   *   everything before it (see `escapesToDocumentRoot`).
   * - `before` is non-empty — resolves normally (recursing back into
   *   {@link getElement}, so it fully supports nested `LinkedCssLocator`s
   *   etc.) to a single scope element.
   * - `before` is empty and NOT a `'Root'` escape — scopes to `this.rootEl`
   *   directly, NOT the document root. An unscoped `findByRole(...)` must
   *   still respect the interactor's own scoping (e.g. a Storybook canvas),
   *   exactly like a bare CSS locator does; routing this case through
   *   `getElement([])` would incorrectly escape to the document regardless
   *   of `rootEl`, since an empty chain always reduces to `:root`.
   *
   * Within that scope, `@testing-library/dom`'s `queryAllByRole` resolves by
   * the accname algorithm — the same engine `dom-core` already depends on for
   * this exact purpose (see the `findByRole` design in ADR 0001, Decision B).
   * `hidden: true` matches this codebase's other locators, which resolve
   * structurally regardless of visibility (`isVisible` is the dedicated
   * visibility check, not baked into resolution).
   */
  private async getElementByAccessibleRole<T extends Element>(
    split: { before: PartLocator; roleLocator: AccessibleRoleLocator },
    isMultiple: boolean
  ): Promise<T[] | Optional<T>> {
    const scopeEl =
      split.roleLocator.relative === 'Root'
        ? await this.getElement([])
        : split.before.length === 0
          ? this.rootEl
          : await this.getElement(split.before);
    if (scopeEl == null) {
      return isMultiple ? [] : undefined;
    }
    const matches = queryAllByRole(scopeEl as HTMLElement, split.roleLocator.role, {
      hidden: true,
      ...(split.roleLocator.name != null ? { name: split.roleLocator.name } : {}),
    }) as unknown as T[];
    return isMultiple ? matches : matches[0];
  }

  /**
   * A `'Root'`-relative locator (the portal escape — see the portals guide) is
   * documented to search from the document, not from this interactor's root, so
   * portalled content (dialogs, dropdowns rendered at `<body>`) stays reachable
   * even when the interactor is scoped to a sub-tree such as a Storybook canvas.
   * Mirrors `locatorUtil.getEffectiveLocator`'s slicing rule: the last `'Root'`
   * locator wins unless it is `'linked'`, whose CSS still needs the scoped
   * context.
   */
  private escapesToDocumentRoot(locator: PartLocator): boolean {
    for (let i = locator.length - 1; i >= 0; i--) {
      if (locator[i].relative === 'Root') {
        return locator[i].complexity !== 'linked';
      }
    }
    return false;
  }

  async getInputValue(locator: PartLocator): Promise<Optional<string>> {
    const el = await this.getElement(locator);
    if (el != null) {
      if (el.nodeName === 'INPUT') {
        return Promise.resolve((el as HTMLInputElement).value ?? undefined);
      } else if (el.nodeName === 'TEXTAREA') {
        return Promise.resolve((el as HTMLTextAreaElement).value ?? undefined);
      }
    }
    return undefined;
  }

  async getSelectValues(locator: PartLocator): Promise<Optional<readonly string[]>> {
    const el = await this.getElement(locator);
    if (el != null && el.nodeName === 'SELECT') {
      const options = el.querySelectorAll<HTMLOptionElement>('option:checked');
      const values = Array.from(options).map(o => o.value);
      return Promise.resolve(values);
    }
    return Promise.resolve(undefined);
  }

  async getSelectLabels(locator: PartLocator): Promise<Optional<readonly string[]>> {
    const el = await this.getElement(locator);
    if (el != null && el.nodeName === 'SELECT') {
      const options = el.querySelectorAll<HTMLOptionElement>('option:checked');
      const values = Array.from(options).map(o => o.text);
      return Promise.resolve(values);
    }
    return Promise.resolve(undefined);
  }

  async getText(locator: PartLocator): Promise<Optional<string>> {
    const el = await this.getElement(locator);
    if (el != null) {
      return Promise.resolve(el.textContent ?? undefined);
    }
    return undefined;
  }

  /**
   * Get the located element's bounding rectangle.
   *
   * jsdom has no layout engine, so `getBoundingClientRect` returns all zeros: the
   * rect is structurally valid but behaviorally meaningless. Real geometry is
   * E2E-only.
   *
   * @param locator - Locator used to find the element to measure
   * @returns The element's bounding rectangle (a zero-rect under jsdom)
   * @throws {ElementNotFoundError} If the element is not found
   */
  async getBoundingRect(locator: PartLocator): Promise<BoundingRect> {
    const el = await this.getElement(locator);
    if (el == null) {
      throw new ElementNotFoundError(locator, 'getBoundingRect');
    }
    const r = el.getBoundingClientRect();
    return { x: r.x, y: r.y, width: r.width, height: r.height };
  }

  async isChecked(locator: PartLocator): Promise<boolean> {
    const el = await this.getElement(locator);
    if (el == null) {
      return false;
    }
    // Shared with PlaywrightInteractor so both engines answer identically.
    return elementStateUtil.isElementChecked(el);
  }

  async isDisabled(locator: PartLocator): Promise<boolean> {
    const el = await this.getElement(locator);
    if (el == null) {
      return false;
    }
    // Shared with PlaywrightInteractor so both engines answer identically.
    return elementStateUtil.isElementDisabled(el);
  }

  async isReadonly(locator: PartLocator): Promise<boolean> {
    // Honor `aria-readonly` for symmetry with `isRequired`'s `aria-required`
    // check (#1053): the native `readonly` attribute only exists on native form
    // controls, whereas composite/custom widgets (comboboxes, grids,
    // contenteditable regions) expose read-only state through ARIA. The two
    // capability probes now read both the native and ARIA signals.
    if (await this.hasAttribute(locator, 'readonly')) {
      return true;
    }
    return (await this.getAttribute(locator, 'aria-readonly')) === 'true';
  }

  async isRequired(locator: PartLocator): Promise<boolean> {
    const el = await this.getElement(locator);
    if (el != null) {
      if ('required' in el && Boolean((el as { required?: boolean }).required)) {
        return true;
      }
      return el.getAttribute('aria-required') === 'true';
    }
    return false;
  }

  async isError(locator: PartLocator): Promise<boolean> {
    const el = await this.getElement(locator);
    return el != null && el.getAttribute('aria-invalid') === 'true';
  }

  async isVisible(locator: PartLocator): Promise<boolean> {
    const el = await this.getElement(locator);
    if (el == null) {
      return false;
    }
    // Apply the shared visibility policy (#1053): walk the ancestor chain so a
    // child of a `display: none` / `opacity: 0` ancestor is reported hidden, not
    // visible. `visibility` is inherited and handled on the element alone inside
    // the predicate.
    return visibilityUtil.isElementVisibleByStyle(el, target => window.getComputedStyle(target as HTMLElement));
  }

  async hasCssClass(locator: PartLocator, className: string): Promise<boolean> {
    const el = await this.getElement(locator);
    if (el != null) {
      return Promise.resolve(el.classList.contains(className));
    }
    return Promise.resolve(false);
  }

  async hasAttribute(locator: PartLocator, name: string): Promise<boolean> {
    const el = await this.getElement(locator);
    if (el != null) {
      return Promise.resolve(el.hasAttribute(name));
    }
    return Promise.resolve(false);
  }

  //#region
  async innerHTML(locator: PartLocator): Promise<string> {
    const el = await this.getElement(locator);
    return el?.innerHTML ?? '';
  }
  //#endregion
}