@testspectra/matchers 1.1.0 → 1.1.8-rc.2

package/src/types.ts

@@ -1,1521 +1,1648 @@
-/**
- * Canonical action keys supported across TestSpectra runner and database models.
- * @see backend/src/models/test_step.rs
- */
-export type ActionKey =
-  | 'navigate'
-  | 'click'
-  | 'type'
-  | 'clear'
-  | 'select'
-  | 'scroll'
-  | 'swipe'
-  | 'wait'
-  | 'waitForElement'
-  | 'pressKey'
-  | 'longPress'
-  | 'doubleClick'
-  | 'hover'
-  | 'dragDrop'
-  | 'back'
-  | 'refresh';
-
-/**
- * Canonical assertion keys supported across TestSpectra runner and database models.
- * @see backend/src/models/test_step.rs
- */
-export type AssertionKey =
-  | 'elementDisplayed'
-  | 'elementNotDisplayed'
-  | 'elementExists'
-  | 'elementNotExists'
-  | 'elementClickable'
-  | 'elementNotClickable'
-  | 'elementEnabled'
-  | 'elementDisabled'
-  | 'elementChecked'
-  | 'elementNotChecked'
-  | 'elementFocused'
-  | 'elementNotFocused'
-  | 'textEquals'
-  | 'textNotEquals'
-  | 'textContains'
-  | 'textNotContains'
-  | 'valueEquals'
-  | 'valueNotEquals'
-  | 'valueContains'
-  | 'valueNotContains'
-  | 'attributeEquals'
-  | 'attributeNotEquals'
-  | 'hasClass'
-  | 'notHasClass'
-  | 'hasCss'
-  | 'notHasCss'
-  | 'collectionLengthEquals'
-  | 'collectionLengthNotEquals'
-  | 'collectionLengthGreaterThan'
-  | 'collectionLengthLessThan'
-  | 'collectionEmpty'
-  | 'collectionNotEmpty'
-  | 'urlEquals'
-  | 'urlContains'
-  | 'titleEquals'
-  | 'titleContains'
-  | 'pageLoaded'
-  | 'noConsoleErrors';
-
-/**
- * Supported keyboard key names for `Spectra.pressKey(key)`.
- *
- * @example
- * ```ts
- * await Spectra.pressKey("Enter");
- * await Spectra.pressKey("Tab");
- * ```
- */
-export type KeyOption =
-  | 'Enter'
-  | 'Tab'
-  | 'Escape'
-  | 'Backspace'
-  | 'Delete'
-  | 'ArrowUp'
-  | 'ArrowDown'
-  | 'ArrowLeft'
-  | 'ArrowRight'
-  | 'Space';
-
-/**
- * Cardinal directions for gestures such as swipe and scroll.
- */
-export type Direction = 'up' | 'down' | 'left' | 'right';
-
-/**
- * Target reference for locating an element.
- * Can be a CSS/XPath selector string, a resolved `SpectraElement` proxy,
- * or a chainable element promise `Promise<SpectraElement>`.
- *
- * @example
- * ```ts
- * // Selector string
- * Spectra.get("#submit-btn");
- *
- * // Page Object property
- * Spectra.get(LoginPage.submitButton);
- * ```
- */
-export type ElementTarget = string | SingleElementProxy | Promise<SingleElementProxy>;
-
-/**
- * Configuration options for scroll actions.
- *
- * @example
- * ```ts
- * await Spectra.scroll({ direction: "down", pixels: 300 });
- * await Spectra.scroll({ selector: "#footer" });
- * ```
- */
-export interface ScrollOptions {
-  /** Direction to scroll (default: "down") */
-  direction?: Direction;
-  /** Distance in pixels to scroll (default: 500) */
-  pixels?: number;
-  /** Optional target element selector to scroll directly into view */
-  selector?: ElementTarget;
-}
-
-/**
- * Configuration options for touch swipe gestures (mobile & web).
- *
- * @example
- * ```ts
- * await Spectra.swipe({ direction: "left", distance: 400 });
- * ```
- */
-export interface SwipeOptions {
-  /** Direction of the swipe gesture */
-  direction: Direction;
-  /** Distance in pixels to swipe (default: 300) */
-  distance?: number;
-  /** Optional element target to anchor the swipe gesture */
-  selector?: ElementTarget;
-}
-
-/**
- * Configuration options for long-press gestures.
- *
- * @example
- * ```ts
- * await Spectra.longPress("#draggable-card", { duration: 1500 });
- * ```
- */
-export interface LongPressOptions {
-  /** Optional label or text associated with the element */
-  text?: string;
-  /** Duration in milliseconds to hold the press (default: 1000) */
-  duration?: number;
-}
-
-/**
- * Configuration options for click interactions.
- */
-export interface ClickOptions {
-  /** Optional inner text filter */
-  text?: string;
-  /** Click type: standard single click or double click */
-  clickType?: 'single' | 'double';
-}
-
-/**
- * Configuration options for typing input into form elements.
- *
- * @example
- * ```ts
- * await Spectra.type("#username", "john_doe", { clearFirst: true });
- * ```
- */
-export interface TypeOptions {
-  /** Whether to clear existing input value before typing new text (default: false) */
-  clearFirst?: boolean;
-}
-
-/**
- * Canonical assertion matcher keys for single element verification.
- * Dispatched internally by semantic receiver methods (`.shouldBeVisible()`, `.shouldHaveText()`, etc.).
- */
-export type SingleElementMatcher =
-  | 'be.visible'
-  | 'not.be.visible'
-  | 'exist'
-  | 'not.exist'
-  | 'be.clickable'
-  | 'not.be.clickable'
-  | 'be.enabled'
-  | 'be.disabled'
-  | 'be.checked'
-  | 'not.be.checked'
-  | 'be.selected'
-  | 'not.be.selected'
-  | 'be.focused'
-  | 'not.be.focused'
-  | 'have.value'
-  | 'not.have.value'
-  | 'contain.value'
-  | 'not.contain.value'
-  | 'have.text'
-  | 'not.have.text'
-  | 'contain.text'
-  | 'not.contain.text'
-  | 'have.class'
-  | 'not.have.class'
-  | 'have.attr'
-  | 'not.have.attr'
-  | 'have.css'
-  | 'not.have.css'
-  | 'have.url'
-  | 'contain.url'
-  | 'have.title'
-  | 'contain.title';
-
-/**
- * Canonical assertion matcher keys for multi-element collections.
- * Dispatched internally by semantic collection methods (`.shouldHaveLength()`, `.shouldBeEmpty()`, etc.).
- */
-export type MultiElementMatcher =
-  | 'have.length'
-  | 'not.have.length'
-  | 'have.length.greaterThan'
-  | 'have.length.lessThan'
-  | 'be.empty'
-  | 'not.be.empty'
-  | 'exist';
-
-/**
- * Receiver-oriented element assertion methods.
- * Attached directly to SingleElementProxy instances.
- */
-export interface ElementReceiverAssertions<TReturn = Promise<void>> {
-  /**
-   * Asserts that the target element is visible and displayed on the page.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#submit-btn').shouldBeVisible();
-   * await LoginPage.submitButton.shouldBeVisible();
-   * ```
-   */
-  shouldBeVisible(): TReturn;
-
-  /**
-   * Asserts that the target element is hidden, detached, or not displayed on the page.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('.loading-spinner').shouldNotBeVisible();
-   * ```
-   */
-  shouldNotBeVisible(): TReturn;
-
-  /**
-   * Asserts that the target element exists in the DOM.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#cookie-consent-modal').shouldExist();
-   * ```
-   */
-  shouldExist(): TReturn;
-
-  /**
-   * Asserts that the target element does not exist in the DOM.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#deleted-record-row').shouldNotExist();
-   * ```
-   */
-  shouldNotExist(): TReturn;
-
-  /**
-   * Asserts that the target element is visible, enabled, and clickable.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('button[type="submit"]').shouldBeClickable();
-   * ```
-   */
-  shouldBeClickable(): TReturn;
-
-  /**
-   * Asserts that the target element is disabled, covered, or not clickable.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('button.disabled-action').shouldNotBeClickable();
-   * ```
-   */
-  shouldNotBeClickable(): TReturn;
-
-  /**
-   * Asserts that the target form input/button is enabled (not disabled).
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#username-field').shouldBeEnabled();
-   * ```
-   */
-  shouldBeEnabled(): TReturn;
-
-  /**
-   * Asserts that the target form input/button has the disabled state/attribute.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#submit-order-btn').shouldBeDisabled();
-   * ```
-   */
-  shouldBeDisabled(): TReturn;
-
-  /**
-   * Asserts that the target checkbox or radio input is checked/selected.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#terms-checkbox').shouldBeChecked();
-   * ```
-   */
-  shouldBeChecked(): TReturn;
-
-  /**
-   * Asserts that the target checkbox or radio input is unchecked/deselected.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#subscribe-newsletter').shouldNotBeChecked();
-   * ```
-   */
-  shouldNotBeChecked(): TReturn;
-
-  /**
-   * Asserts that the target element currently holds active document focus.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#search-input').shouldBeFocused();
-   * ```
-   */
-  shouldBeFocused(): TReturn;
-
-  /**
-   * Asserts that the target element does not hold active document focus.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#blur-input').shouldNotBeFocused();
-   * ```
-   */
-  shouldNotBeFocused(): TReturn;
-
-  /**
-   * Asserts that the target element's text content matches the expected string or regular expression.
-   *
-   * @param expected Exact string or RegExp pattern to match against element text.
-   * @example
-   * ```ts
-   * await Spectra.get('h1.page-title').shouldHaveText('Dashboard Overview');
-   * await Spectra.get('.badge').shouldHaveText(/Active|Pending/);
-   * ```
-   */
-  shouldHaveText(expected: string | RegExp): TReturn;
-
-  /**
-   * Asserts that the target element's text content does not match the expected string or regular expression.
-   *
-   * @param expected String or RegExp pattern that the element text must NOT match.
-   * @example
-   * ```ts
-   * await Spectra.get('.status-label').shouldNotHaveText('Error');
-   * ```
-   */
-  shouldNotHaveText(expected: string | RegExp): TReturn;
-
-  /**
-   * Asserts that the target element's text content contains the specified substring.
-   *
-   * @param substring Substring expected to be present within the element text.
-   * @example
-   * ```ts
-   * await Spectra.get('.toast-message').shouldContainText('Successfully saved');
-   * ```
-   */
-  shouldContainText(substring: string): TReturn;
-
-  /**
-   * Asserts that the target element's text content does not contain the specified substring.
-   *
-   * @param substring Substring that must NOT be present within the element text.
-   * @example
-   * ```ts
-   * await Spectra.get('.log-output').shouldNotContainText('Fatal Exception');
-   * ```
-   */
-  shouldNotContainText(substring: string): TReturn;
-
-  /**
-   * Asserts that the form input or textarea element's value exactly equals the specified string.
-   *
-   * @param value Expected input field value.
-   * @example
-   * ```ts
-   * await Spectra.get('input[name="email"]').shouldHaveValue('admin@testspectra.dev');
-   * ```
-   */
-  shouldHaveValue(value: string): TReturn;
-
-  /**
-   * Asserts that the form input or textarea element's value does not equal the specified string.
-   *
-   * @param value Value that the input field must NOT equal.
-   * @example
-   * ```ts
-   * await Spectra.get('input[name="role"]').shouldNotHaveValue('guest');
-   * ```
-   */
-  shouldNotHaveValue(value: string): TReturn;
-
-  /**
-   * Asserts that the form input or textarea element's value contains the specified substring.
-   *
-   * @param substring Substring expected to be contained within the input value.
-   * @example
-   * ```ts
-   * await Spectra.get('input[name="email"]').shouldContainValue('@testspectra.dev');
-   * ```
-   */
-  shouldContainValue(substring: string): TReturn;
-
-  /**
-   * Asserts that the form input or textarea element's value does not contain the specified substring.
-   *
-   * @param substring Substring that must NOT be contained within the input value.
-   * @example
-   * ```ts
-   * await Spectra.get('input[name="url"]').shouldNotContainValue('http://');
-   * ```
-   */
-  shouldNotContainValue(substring: string): TReturn;
-
-  /**
-   * Asserts that the element has the specified attribute, and optionally that its value matches.
-   *
-   * @param name Attribute name to inspect.
-   * @param value Optional expected attribute value string.
-   * @example
-   * ```ts
-   * await Spectra.get('a.external-link').shouldHaveAttribute('target', '_blank');
-   * await Spectra.get('input.required-field').shouldHaveAttribute('required');
-   * ```
-   */
-  shouldHaveAttribute(name: string, value?: string): TReturn;
-
-  /**
-   * Asserts that the element does not have the specified attribute.
-   *
-   * @param name Attribute name that must NOT exist on the element.
-   * @example
-   * ```ts
-   * await Spectra.get('button#action-btn').shouldNotHaveAttribute('disabled');
-   * ```
-   */
-  shouldNotHaveAttribute(name: string): TReturn;
-
-  /**
-   * Asserts that the element contains the specified CSS class name.
-   *
-   * @param className CSS class name expected in the element's classList.
-   * @example
-   * ```ts
-   * await Spectra.get('.nav-tab').shouldHaveClass('active');
-   * ```
-   */
-  shouldHaveClass(className: string): TReturn;
-
-  /**
-   * Asserts that the element does not contain the specified CSS class name.
-   *
-   * @param className CSS class name that must NOT be in the element's classList.
-   * @example
-   * ```ts
-   * await Spectra.get('.modal-backdrop').shouldNotHaveClass('hidden');
-   * ```
-   */
-  shouldNotHaveClass(className: string): TReturn;
-
-  /**
-   * Asserts that the computed CSS style property of the element equals the specified value.
-   *
-   * @param property CSS style property name (e.g. 'color', 'display', 'opacity').
-   * @param value Expected computed CSS property value.
-   * @example
-   * ```ts
-   * await Spectra.get('.badge-success').shouldHaveCss('color', 'rgb(0, 128, 0)');
-   * ```
-   */
-  shouldHaveCss(property: string, value: string): TReturn;
-
-  /**
-   * Asserts that the computed CSS style property of the element does not equal the specified value.
-   *
-   * @param property CSS style property name.
-   * @param value Value that the computed CSS property must NOT equal.
-   * @example
-   * ```ts
-   * await Spectra.get('.main-content').shouldNotHaveCss('display', 'none');
-   * ```
-   */
-  shouldNotHaveCss(property: string, value: string): TReturn;
-}
-
-/**
- * Receiver-oriented collection assertion methods.
- * Attached directly to CollectionProxy and collection prototypes.
- */
-export interface CollectionReceiverAssertions<TReturn = Promise<void>> {
-  /**
-   * Asserts that the collection contains exactly the specified number of matching elements.
-   *
-   * @param count Expected exact count of elements.
-   * @example
-   * ```ts
-   * await Spectra.getAll('.user-table-row').shouldHaveLength(10);
-   * ```
-   */
-  shouldHaveLength(count: number): TReturn;
-
-  /**
-   * Asserts that the collection does not contain the specified number of matching elements.
-   *
-   * @param count Count that the element collection must NOT equal.
-   * @example
-   * ```ts
-   * await Spectra.getAll('.error-item').shouldNotHaveLength(0);
-   * ```
-   */
-  shouldNotHaveLength(count: number): TReturn;
-
-  /**
-   * Asserts that the collection contains strictly more than `min` matching elements.
-   *
-   * @param min Minimum threshold (exclusive).
-   * @example
-   * ```ts
-   * await Spectra.getAll('.search-result-card').shouldHaveLengthGreaterThan(0);
-   * ```
-   */
-  shouldHaveLengthGreaterThan(min: number): TReturn;
-
-  /**
-   * Asserts that the collection contains strictly fewer than `max` matching elements.
-   *
-   * @param max Maximum threshold (exclusive).
-   * @example
-   * ```ts
-   * await Spectra.getAll('.warning-banner').shouldHaveLengthLessThan(5);
-   * ```
-   */
-  shouldHaveLengthLessThan(max: number): TReturn;
-
-  /**
-   * Asserts that the collection contains zero matching elements.
-   *
-   * @example
-   * ```ts
-   * await Spectra.getAll('.unread-notification-badge').shouldBeEmpty();
-   * ```
-   */
-  shouldBeEmpty(): TReturn;
-
-  /**
-   * Asserts that the collection contains at least one matching element.
-   *
-   * @example
-   * ```ts
-   * await Spectra.getAll('.product-card').shouldNotBeEmpty();
-   * ```
-   */
-  shouldNotBeEmpty(): TReturn;
-}
-
-/**
- * Browser-level context assertion methods.
- * Hosted on Spectra.browser and the global browser object.
- */
-export interface BrowserReceiverAssertions {
-  /**
-   * Asserts that current browser URL exactly matches the expected URL.
-   *
-   * @param expectedUrl Full expected URL string.
-   * @example
-   * ```ts
-   * await Spectra.browser.shouldHaveUrl('https://app.testspectra.dev/dashboard');
-   * ```
-   */
-  shouldHaveUrl(expectedUrl: string): Promise<void>;
-
-  /**
-   * Asserts that current browser URL contains the specified substring.
-   *
-   * @param expectedSubstr Substring expected in browser URL.
-   * @example
-   * ```ts
-   * await Spectra.browser.shouldContainUrl('/dashboard');
-   * ```
-   */
-  shouldContainUrl(expectedSubstr: string): Promise<void>;
-
-  /**
-   * Asserts that current page title exactly matches the expected title.
-   *
-   * @param expectedTitle Full expected page title string.
-   * @example
-   * ```ts
-   * await Spectra.browser.shouldHaveTitle('Dashboard - TestSpectra');
-   * ```
-   */
-  shouldHaveTitle(expectedTitle: string): Promise<void>;
-
-  /**
-   * Asserts that current page title contains the specified substring.
-   *
-   * @param expectedSubstr Substring expected in page title.
-   * @example
-   * ```ts
-   * await Spectra.browser.shouldContainTitle('Dashboard');
-   * ```
-   */
-  shouldContainTitle(expectedSubstr: string): Promise<void>;
-
-  /**
-   * Asserts that the browser document `readyState` is 'complete' or 'interactive'.
-   *
-   * @example
-   * ```ts
-   * await Spectra.browser.shouldBeLoaded();
-   * ```
-   */
-  shouldBeLoaded(): Promise<void>;
-
-  /**
-   * Asserts that no severe or unhandled JavaScript errors occurred in the browser console.
-   *
-   * @example
-   * ```ts
-   * await Spectra.browser.shouldHaveNoConsoleErrors();
-   * ```
-   */
-  shouldHaveNoConsoleErrors(): Promise<void>;
-
-  /**
-   * Clears all browser cookies for the active domain.
-   *
-   * @example
-   * ```ts
-   * await Spectra.browser.clearCookies();
-   * ```
-   */
-  clearCookies(): Promise<void>;
-
-  /**
-   * Clears all key-value entries in browser `localStorage`.
-   *
-   * @example
-   * ```ts
-   * await Spectra.browser.clearLocalStorage();
-   * ```
-   */
-  clearLocalStorage(): Promise<void>;
-}
-
-/**
- * Native proxy interface for interacting with a single DOM / UI element.
- */
-export interface SingleElementProxy extends ElementReceiverAssertions<Promise<void>> {
-  /** Target CSS or XPath selector string for this element. */
-  selector: string;
-
-  /** Positional index when matched from a collection (or null for standalone selectors). */
-  index: number | null;
-
-  /**
-   * Waits until the element exists in the DOM within the specified timeout.
-   *
-   * @param timeoutMs Timeout in milliseconds (default: 5000ms).
-   */
-  waitForElement(timeoutMs?: number): Promise<boolean>;
-
-  /**
-   * Clicks on the element.
-   *
-   * @param options Optional click interaction options.
-   * @example
-   * ```ts
-   * await Spectra.get('#submit-btn').click();
-   * ```
-   */
-  click(options?: ClickOptions): Promise<void>;
-
-  /**
-   * Performs a double-click interaction on the element.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('.editable-cell').doubleClick();
-   * ```
-   */
-  doubleClick(): Promise<void>;
-
-  /**
-   * Performs a context-click (right-click) on the element.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('.file-item').rightClick();
-   * ```
-   */
-  rightClick(): Promise<void>;
-
-  /**
-   * Sets or replaces the value of a form input element.
-   *
-   * @param value Text value to set.
-   * @example
-   * ```ts
-   * await Spectra.get('#username').setValue('admin');
-   * ```
-   */
-  setValue(value: unknown): Promise<void>;
-
-  /**
-   * Types text keystrokes into the element, optionally clearing existing content first.
-   *
-   * @param value Text string to type.
-   * @param options Optional type options (e.g. `{ clearFirst: true }`).
-   * @example
-   * ```ts
-   * await LoginPage.emailInput.type('admin@testspectra.dev', { clearFirst: true });
-   * ```
-   */
-  type(value: unknown, options?: TypeOptions): Promise<void>;
-
-  /**
-   * Clears the current text value from an input or textarea element.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#search-bar').clearValue();
-   * ```
-   */
-  clearValue(): Promise<void>;
-
-  /**
-   * Clears the current text value from an input or textarea element (alias to `clearValue()`).
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#search-bar').clear();
-   * ```
-   */
-  clear(): Promise<void>;
-
-  /**
-   * Selects an option in a `<select>` element by its visible text or value.
-   *
-   * @param option Visible text or value of the option to select.
-   * @example
-   * ```ts
-   * await Spectra.get('#country-dropdown').select('Indonesia');
-   * ```
-   */
-  select(option: string): Promise<void>;
-
-  /**
-   * Selects an option in a `<select>` dropdown by its visible text.
-   *
-   * @param text Visible text label of the option.
-   */
-  selectByVisibleText(text: string): Promise<void>;
-
-  /**
-   * Hovers the mouse cursor over the center of the element.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('.dropdown-trigger').hover();
-   * ```
-   */
-  hover(): Promise<void>;
-
-  /**
-   * Focuses the target element (triggers focus event and active document focus).
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#email-input').focus();
-   * ```
-   */
-  focus(): Promise<void>;
-
-  /**
-   * Moves the mouse cursor to the element (alias to `hover()`).
-   */
-  moveTo(): Promise<void>;
-
-  /**
-   * Drags this element and drops it onto the target element destination.
-   *
-   * @param target Destination element target selector or proxy.
-   * @example
-   * ```ts
-   * await Spectra.get('#drag-source').dragDrop('#drop-zone');
-   * ```
-   */
-  dragDrop(target: ElementTarget): Promise<void>;
-
-  /**
-   * Drags this element and drops it onto the target element destination (alias to `dragDrop()`).
-   */
-  dragAndDrop(target: ElementTarget): Promise<void>;
-
-  /**
-   * Scrolls the page until this element is aligned into the visible viewport.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get('#footer-links').scrollIntoView();
-   * ```
-   */
-  scrollIntoView(): Promise<void>;
-
-  /**
-   * Long-presses on the element for touch/mobile gestures.
-   *
-   * @param options Long-press duration in milliseconds or configuration object.
-   * @example
-   * ```ts
-   * await Spectra.get('.draggable-card').longPress({ duration: 1500 });
-   * ```
-   */
-  longPress(options?: number | LongPressOptions): Promise<void>;
-
-  /**
-   * Waits until the element is displayed and visible in the viewport.
-   *
-   * @param opts Optional timeout configuration object.
-   */
-  waitForDisplayed(opts?: { timeout?: number }): Promise<boolean>;
-
-  /**
-   * Returns the inner text content of the element.
-   *
-   * @example
-   * ```ts
-   * const headingText = await Spectra.get('h1').getText();
-   * ```
-   */
-  getText(): Promise<string>;
-
-  /**
-   * Returns the current `value` property of an input or textarea element.
-   *
-   * @example
-   * ```ts
-   * const query = await Spectra.get('input#search').getValue();
-   * ```
-   */
-  getValue(): Promise<string>;
-
-  /**
-   * Returns true if the element is currently visible and rendered in the DOM.
-   */
-  isDisplayed(): Promise<boolean>;
-
-  /**
-   * Returns true if the element is currently visible (alias to `isDisplayed()`).
-   */
-  isVisible(): Promise<boolean>;
-
-  /**
-   * Returns true if the element exists in the DOM.
-   */
-  isExisting(): Promise<boolean>;
-
-  /**
-   * Returns true if the element is enabled (not disabled).
-   */
-  isEnabled(): Promise<boolean>;
-
-  /**
-   * Returns true if the checkbox, radio, or `<option>` is selected.
-   */
-  isSelected(): Promise<boolean>;
-
-  /**
-   * Returns true if the checkbox or radio button is checked.
-   */
-  isChecked(): Promise<boolean>;
-
-  /**
-   * Returns true if the element is the active focused element in document.
-   */
-  isFocused(): Promise<boolean>;
-
-  /**
-   * Retrieves the value of a specified HTML attribute from the element.
-   *
-   * @param name Attribute name (e.g. 'href', 'src', 'data-id').
-   * @example
-   * ```ts
-   * const linkUrl = await Spectra.get('a#download').getAttribute('href');
-   * ```
-   */
-  getAttribute(name: string): Promise<string | null>;
-
-  /**
-   * Retrieves the computed CSS property value of the element.
-   *
-   * @param name CSS property name (e.g. 'background-color', 'font-size').
-   * @example
-   * ```ts
-   * const color = await Spectra.get('.btn-primary').getCSSProperty('background-color');
-   * ```
-   */
-  getCSSProperty(name: string): Promise<{ value: string }>;
-}
-
-/**
- * TestSpectra native element interface alias.
- */
-export type SpectraElement = SingleElementProxy;
-
-/**
- * Native proxy interface for interacting with multiple matching elements in a collection.
- */
-export interface CollectionProxy extends CollectionReceiverAssertions<Promise<void>> {
-  /** Target CSS or XPath selector string for this collection. */
-  selector: string;
-
-  /**
-   * Returns the total count of elements matching this collection selector.
-   *
-   * @example
-   * ```ts
-   * const totalRows = await Spectra.getAll('.table-row').count();
-   * ```
-   */
-  count(): Promise<number>;
-
-  /**
-   * Total count of elements matching this collection selector (Promise).
-   */
-  readonly length: Promise<number>;
-
-  /**
-   * Returns a `SingleElementProxy` pointing to the first matching element in the collection (index 0).
-   *
-   * @example
-   * ```ts
-   * await Spectra.getAll('.list-item').first().click();
-   * ```
-   */
-  first(): SingleElementProxy;
-
-  /**
-   * Returns a `SingleElementProxy` pointing to the last matching element in the collection.
-   *
-   * @example
-   * ```ts
-   * await Spectra.getAll('.list-item').last().click();
-   * ```
-   */
-  last(): SingleElementProxy;
-
-  /**
-   * Returns a `SingleElementProxy` pointing to the matching element at the specified zero-based index.
-   *
-   * @param index Zero-based index of the target element.
-   * @example
-   * ```ts
-   * await Spectra.getAll('.list-item').nth(2).click();
-   * ```
-   */
-  nth(index: number): SingleElementProxy;
-}
-
-/**
- * TestSpectra native collection interface alias.
- */
-export type SpectraCollection = CollectionProxy;
-
-/**
- * Native browser bridge interface for page navigation, execution, and network interception.
- */
-export interface SpectraBrowserBridge extends BrowserReceiverAssertions {
-  /**
-   * Navigates the browser to the specified absolute or relative URL.
-   *
-   * @param targetUrl Target destination URL.
-   * @example
-   * ```ts
-   * await Spectra.browser.url('/auth/login');
-   * ```
-   */
-  url(targetUrl: string): Promise<void>;
-
-  /**
-   * Retrieves the current browser URL.
-   *
-   * @example
-   * ```ts
-   * const currentUrl = await Spectra.browser.getUrl();
-   * ```
-   */
-  getUrl(): Promise<string>;
-
-  /**
-   * Retrieves the current page title.
-   *
-   * @example
-   * ```ts
-   * const title = await Spectra.browser.getTitle();
-   * ```
-   */
-  getTitle(): Promise<string>;
-
-  /**
-   * Navigates one step back in the browser history.
-   *
-   * @example
-   * ```ts
-   * await Spectra.browser.back();
-   * ```
-   */
-  back(): Promise<void>;
-
-  /**
-   * Navigates one step forward in the browser history.
-   *
-   * @example
-   * ```ts
-   * await Spectra.browser.forward();
-   * ```
-   */
-  forward(): Promise<void>;
-
-  /**
-   * Reloads / refreshes the current active page.
-   *
-   * @example
-   * ```ts
-   * await Spectra.browser.refresh();
-   * ```
-   */
-  refresh(): Promise<void>;
-
-  /**
-   * Pauses test execution for the specified number of milliseconds.
-   *
-   * @param ms Duration in milliseconds to pause.
-   * @example
-   * ```ts
-   * await Spectra.browser.pause(1000);
-   * ```
-   */
-  pause(ms: number): Promise<void>;
-
-  /**
-   * Sets the browser viewport dimensions (width and height in pixels).
-   *
-   * @param width Viewport width in pixels.
-   * @param height Viewport height in pixels.
-   * @example
-   * ```ts
-   * await Spectra.browser.setViewport(1920, 1080);
-   * ```
-   */
-  setViewport(width: number, height: number): Promise<void>;
-
-  /**
-   * Executes a JavaScript function or script snippet in the browser context and returns the result.
-   *
-   * @param fn Function or script string to execute.
-   * @param args Arguments to pass into the function.
-   * @example
-   * ```ts
-   * const docWidth = await Spectra.browser.execute(() => document.body.clientWidth);
-   * ```
-   */
-  execute<R = unknown>(fn: ((...args: unknown[]) => R) | string, ...args: unknown[]): Promise<R>;
-
-  /**
-   * Evaluates a JavaScript expression string in the browser context.
-   *
-   * @param expr JavaScript expression string.
-   * @example
-   * ```ts
-   * const isReady = await Spectra.browser.evaluate('document.readyState === "complete"');
-   * ```
-   */
-  evaluate<R = unknown>(expr: string): Promise<R>;
-
-  /**
-   * Repeatedly polls a condition function until it returns true or times out.
-   *
-   * @param fn Condition function returning a boolean or boolean promise.
-   * @param opts Optional timeout and message options.
-   * @example
-   * ```ts
-   * await Spectra.browser.waitUntil(async () => (await Spectra.get('#status').getText()) === 'Ready', {
-   *   timeout: 5000,
-   *   timeoutMsg: 'Status never reached Ready',
-   * });
-   * ```
-   */
-  waitUntil(fn: () => Promise<boolean> | boolean, opts?: { timeout?: number; timeoutMsg?: string }): Promise<boolean>;
-
-  /**
-   * Retrieves captured browser console log entries.
-   *
-   * @param type Optional log type filter (e.g. 'browser', 'error').
-   */
-  getLogs(type?: string): Promise<Array<{ level: string; message: string }>>;
-
-  /**
-   * Intercepts and mocks HTTP network requests matching the specified URL pattern.
-   *
-   * @param pattern URL substring or glob pattern to intercept.
-   * @param method HTTP method (GET, POST, PUT, DELETE, etc.).
-   * @param fixture Mock response payload object or string.
-   * @param options Mock response options (status code, custom headers).
-   * @example
-   * ```ts
-   * const mock = await Spectra.browser.intercept('/api/v1/users', 'GET', [{ id: 1, name: 'Alice' }], {
-   *   statusCode: 200,
-   * });
-   * ```
-   */
-  intercept(
-    pattern: string,
-    method?: string,
-    fixture?: unknown,
-    options?: { statusCode?: number; headers?: Record<string, string> },
-  ): Promise<MockInterceptHandle>;
-}
-
-/**
- * Mock rule configuration for CDP network request interception.
- */
-export interface MockRule {
-  /** URL pattern or substring to match. */
-  pattern: string;
-  /** HTTP method (e.g. GET, POST). */
-  method: string;
-  /** Mock response payload. */
-  response: unknown;
-  /** HTTP status code (e.g. 200, 404). */
-  statusCode: number;
-  /** Custom HTTP response headers. */
-  headers?: Record<string, string>;
-  /** Total times this mock rule matched and intercepted requests. */
-  callCount: number;
-}
-
-/**
- * Handle returned by `Spectra.intercept()` to dynamically inspect and update mock responses.
- */
-export interface MockInterceptHandle {
-  /**
-   * Dynamically updates the response payload for this active mock rule.
-   *
-   * @param newFixture New response payload object or string.
-   * @param newOptions Optional status code and header overrides.
-   */
-  respondWith: (
-    newFixture: unknown,
-    newOptions?: { statusCode?: number; headers?: Record<string, string> },
-  ) => Promise<void>;
-
-  /**
-   * Returns the number of times this mock intercepted network requests.
-   */
-  callCount: () => number;
-}
-
-/**
- * Audit log entry for captured CDP network requests.
- */
-export interface CDPNetworkEntry {
-  /** Unique CDP request ID. */
-  requestId: string;
-  /** Target request URL. */
-  url: string;
-  /** HTTP request method. */
-  method: string;
-  /** Resource type (e.g. 'Fetch', 'XHR', 'Document', 'Stylesheet'). */
-  type: string;
-  /** HTTP response status code. */
-  status: number;
-  /** HTTP response status message. */
-  statusText: string;
-  /** Host domain name. */
-  domain: string;
-  /** Protocol name (e.g. 'h2', 'http/1.1'). */
-  protocol: string;
-  /** Request timing metrics in milliseconds. */
-  timing: { waiting: number; download: number };
-  /** Content body size in bytes. */
-  size: number;
-  /** Wire transfer size in bytes. */
-  transferSize: number;
-  /** Start timestamp epoch. */
-  startTime: number;
-}
-
-/**
- * Main TestSpectra cross-platform automation and assertion interface contract.
- */
-export interface SpectraStatic {
-  /**
-   * Locates a single DOM / UI element proxy by selector or target reference.
-   *
-   * @param target CSS selector string, XPath string, or element proxy.
-   * @example
-   * ```ts
-   * const submitBtn = Spectra.get('#btn-submit');
-   * await submitBtn.click();
-   * ```
-   */
-  get(target: ElementTarget): SingleElementProxy;
-
-  /**
-   * Locates a collection proxy of multiple matching DOM / UI elements by selector.
-   *
-   * @param selector CSS or XPath selector matching multiple elements.
-   * @example
-   * ```ts
-   * const rows = Spectra.getAll('table tr');
-   * await rows.shouldHaveLength(5);
-   * ```
-   */
-  getAll(selector: string): CollectionProxy;
-
-  /**
-   * Navigates the active browser window or mobile webview to the specified URL.
-   *
-   * @param url Absolute or relative URL destination.
-   * @example
-   * ```ts
-   * await Spectra.navigate('/dashboard');
-   * ```
-   */
-  navigate(url: string): Promise<void>;
-
-  /**
-   * Navigates one step backward in browser history.
-   *
-   * @example
-   * ```ts
-   * await Spectra.back();
-   * ```
-   */
-  back(): Promise<void>;
-
-  /**
-   * Navigates one step forward in browser history.
-   *
-   * @example
-   * ```ts
-   * await Spectra.forward();
-   * ```
-   */
-  forward(): Promise<void>;
-
-  /**
-   * Reloads / refreshes the current active page.
-   *
-   * @example
-   * ```ts
-   * await Spectra.refresh();
-   * ```
-   */
-  refresh(): Promise<void>;
-
-  /**
-   * Sets the browser viewport dimensions (width and height in pixels).
-   *
-   * @param width Viewport width in pixels.
-   * @param height Viewport height in pixels.
-   * @example
-   * ```ts
-   * await Spectra.setViewport(1920, 1080);
-   * ```
-   */
-  setViewport(width: number, height: number): Promise<void>;
-
-  /**
-   * Clicks on the specified element target.
-   *
-   * @param target Element selector string, Page Object element, or proxy.
-   * @param textOrOptions Optional text filter or click options.
-   * @example
-   * ```ts
-   * await Spectra.click('#submit-btn');
-   * await Spectra.click(LoginPage.submitButton);
-   * ```
-   */
-  click(target: ElementTarget, textOrOptions?: string | ClickOptions): Promise<void>;
-
-  /**
-   * Performs a double-click interaction on the specified element target.
-   *
-   * @param target Target element selector or proxy.
-   * @example
-   * ```ts
-   * await Spectra.doubleClick('.grid-cell');
-   * ```
-   */
-  doubleClick(target: ElementTarget): Promise<void>;
-
-  /**
-   * Performs a context-click (right-click) interaction on the specified element target.
-   *
-   * @param target Target element selector or proxy.
-   * @example
-   * ```ts
-   * await Spectra.rightClick('#context-menu-area');
-   * ```
-   */
-  rightClick(target: ElementTarget): Promise<void>;
-
-  /**
-   * Types text keystrokes into the specified element target.
-   *
-   * @param target Target input or textarea element selector or proxy.
-   * @param text String content to type.
-   * @param options Optional typing configuration (e.g. `{ clearFirst: true }`).
-   * @example
-   * ```ts
-   * await Spectra.type('#username', 'john_doe', { clearFirst: true });
-   * ```
-   */
-  type(target: ElementTarget, text: string, options?: TypeOptions): Promise<void>;
-
-  /**
-   * Clears the current text value from an input or textarea element.
-   *
-   * @param target Target element selector or proxy.
-   * @example
-   * ```ts
-   * await Spectra.clear('#search-input');
-   * ```
-   */
-  clear(target: ElementTarget): Promise<void>;
-
-  /**
-   * Selects an option in a `<select>` dropdown by its visible text or value.
-   *
-   * @param target Target select element selector or proxy.
-   * @param option Visible text label or value of the option.
-   * @example
-   * ```ts
-   * await Spectra.select('#country-dropdown', 'United States');
-   * ```
-   */
-  select(target: ElementTarget, option: string): Promise<void>;
-
-  /**
-   * Hovers the mouse cursor over the specified element target.
-   *
-   * @param target Target element selector or proxy.
-   * @example
-   * ```ts
-   * await Spectra.hover('.profile-menu-trigger');
-   * ```
-   */
-  hover(target: ElementTarget): Promise<void>;
-
-  /**
-   * Focuses the target element (triggers focus event and active document focus).
-   *
-   * @param target Target element selector or proxy.
-   * @example
-   * ```ts
-   * await Spectra.focus('#email-input');
-   * ```
-   */
-  focus(target: ElementTarget): Promise<void>;
-
-  /**
-   * Drags a source element and drops it onto a destination element target.
-   *
-   * @param source Draggable source element selector or proxy.
-   * @param destination Drop zone destination element selector or proxy.
-   * @example
-   * ```ts
-   * await Spectra.dragDrop('#item-1', '#kanban-column-done');
-   * ```
-   */
-  dragDrop(source: ElementTarget, destination: ElementTarget): Promise<void>;
-
-  /**
-   * Scrolls the page until the specified element is aligned into the visible viewport.
-   *
-   * @param target Target element selector or proxy.
-   * @example
-   * ```ts
-   * await Spectra.scrollIntoView('#footer-contact');
-   * ```
-   */
-  scrollIntoView(target: ElementTarget): Promise<void>;
-
-  /**
-   * Performs a directional scroll on the page.
-   *
-   * @param options Scroll options (direction, pixel distance, or target selector).
-   * @example
-   * ```ts
-   * await Spectra.scroll({ direction: 'down', pixels: 400 });
-   * ```
-   */
-  scroll(options?: ScrollOptions): Promise<void>;
-
-  /**
-   * Performs a directional touch swipe gesture (mobile & web).
-   *
-   * @param options Swipe options (direction, distance in pixels, anchor selector).
-   * @example
-   * ```ts
-   * await Spectra.swipe({ direction: 'left', distance: 300 });
-   * ```
-   */
-  swipe(options: SwipeOptions): Promise<void>;
-
-  /**
-   * Performs a long-press touch gesture on the target element.
-   *
-   * @param target Target element selector or proxy.
-   * @param options Long-press duration in milliseconds or configuration object.
-   * @example
-   * ```ts
-   * await Spectra.longPress('#sortable-item', { duration: 1500 });
-   * ```
-   */
-  longPress(target: ElementTarget, options?: LongPressOptions | number): Promise<void>;
-
-  /**
-   * Presses a specific keyboard key into the active document element.
-   *
-   * @param key Key name to press (e.g. 'Enter', 'Tab', 'Escape', 'Backspace').
-   * @example
-   * ```ts
-   * await Spectra.pressKey('Enter');
-   * ```
-   */
-  pressKey(key: KeyOption | string): Promise<void>;
-
-  /**
-   * Pauses test execution for the specified number of milliseconds.
-   *
-   * @param ms Milliseconds to wait.
-   * @example
-   * ```ts
-   * await Spectra.wait(1000);
-   * ```
-   */
-  wait(ms: number): Promise<void>;
-
-  /**
-   * Waits for the specified element to appear and exist in the DOM.
-   *
-   * @param target Target element selector or proxy.
-   * @param timeoutMs Maximum time to wait in milliseconds (default: 5000ms).
-   * @example
-   * ```ts
-   * await Spectra.waitForElement('#dynamic-content', 10000);
-   * ```
-   */
-  waitForElement(target: ElementTarget, timeoutMs?: number): Promise<void>;
-
-  /**
-   * Direct access to browser context commands and page assertions.
-   */
-  browser: SpectraBrowserBridge;
-
-  /**
-   * Intercepts and mocks HTTP network requests matching the specified pattern or options.
-   *
-   * @param patternOrOptions URL pattern string or structured intercept configuration object.
-   * @param method HTTP method (GET, POST, etc.) when pattern string is used.
-   * @param fixture Mock response payload.
-   * @param options Additional response options (status code, custom headers).
-   * @example
-   * ```ts
-   * const mock = await Spectra.intercept('/api/v1/profile', 'GET', { name: 'Admin', role: 'root' });
-   * ```
-   */
-  intercept(
-    patternOrOptions: string | { url: string; method?: string; response?: unknown },
-    method?: string,
-    fixture?: unknown,
-    options?: { statusCode?: number; headers?: Record<string, string> },
-  ): Promise<MockInterceptHandle>;
-
-  /**
-   * Clears and resets all active CDP network interception rules.
-   *
-   * @example
-   * ```ts
-   * Spectra.clearMocks();
-   * ```
-   */
-  clearMocks(): void;
-}
+/**
+ * Canonical action keys supported across TestSpectra runner and database models.
+ * @see backend/src/models/test_step.rs
+ */
+export type ActionKey =
+  | 'navigate'
+  | 'click'
+  | 'type'
+  | 'clear'
+  | 'select'
+  | 'scroll'
+  | 'swipe'
+  | 'wait'
+  | 'waitForElement'
+  | 'pressKey'
+  | 'longPress'
+  | 'doubleClick'
+  | 'hover'
+  | 'dragDrop'
+  | 'back'
+  | 'refresh';
+
+/**
+ * Canonical assertion keys supported across TestSpectra runner and database models.
+ * @see backend/src/models/test_step.rs
+ */
+export type AssertionKey =
+  | 'elementDisplayed'
+  | 'elementNotDisplayed'
+  | 'elementExists'
+  | 'elementNotExists'
+  | 'elementClickable'
+  | 'elementNotClickable'
+  | 'elementEnabled'
+  | 'elementDisabled'
+  | 'elementChecked'
+  | 'elementNotChecked'
+  | 'elementFocused'
+  | 'elementNotFocused'
+  | 'textEquals'
+  | 'textNotEquals'
+  | 'textContains'
+  | 'textNotContains'
+  | 'valueEquals'
+  | 'valueNotEquals'
+  | 'valueContains'
+  | 'valueNotContains'
+  | 'attributeEquals'
+  | 'attributeNotEquals'
+  | 'hasClass'
+  | 'notHasClass'
+  | 'hasCss'
+  | 'notHasCss'
+  | 'collectionLengthEquals'
+  | 'collectionLengthNotEquals'
+  | 'collectionLengthGreaterThan'
+  | 'collectionLengthLessThan'
+  | 'collectionEmpty'
+  | 'collectionNotEmpty'
+  | 'urlEquals'
+  | 'urlContains'
+  | 'titleEquals'
+  | 'titleContains'
+  | 'pageLoaded'
+  | 'noConsoleErrors';
+
+/**
+ * Supported keyboard key names for `Spectra.pressKey(key)`.
+ *
+ * @example
+ * ```ts
+ * await Spectra.pressKey("Enter");
+ * await Spectra.pressKey("Tab");
+ * ```
+ */
+export type KeyOption =
+  | 'Enter'
+  | 'Tab'
+  | 'Escape'
+  | 'Backspace'
+  | 'Delete'
+  | 'ArrowUp'
+  | 'ArrowDown'
+  | 'ArrowLeft'
+  | 'ArrowRight'
+  | 'Space';
+
+/**
+ * Cardinal directions for gestures such as swipe and scroll.
+ */
+export type Direction = 'up' | 'down' | 'left' | 'right';
+
+/**
+ * Target reference for locating an element.
+ * Can be a CSS/XPath selector string, a resolved `SpectraElement` proxy,
+ * or a chainable element promise `Promise<SpectraElement>`.
+ *
+ * @example
+ * ```ts
+ * // Selector string
+ * Spectra.get("#submit-btn");
+ *
+ * // Page Object property
+ * Spectra.get(LoginPage.submitButton);
+ * ```
+ */
+export type ElementTarget = string | SingleElementProxy | Promise<SingleElementProxy>;
+
+/**
+ * Internal descriptor for a selector resolved relative to a parent element, produced by
+ * `element.get()` / `element.getAll()` chaining (see `SingleElementProxy.get`). Recursive so
+ * arbitrarily deep chains (e.g. `Spectra.getAll('.card').nth(2).get('.buy-btn')`) carry their
+ * full ancestry down to the driver.
+ *
+ * Resolution differs per platform: web (CDP) nests real DOM `.querySelector()` calls against the
+ * resolved parent; Android has no ancestor/descendant API, so the parent's bounds rectangle is
+ * used to filter candidates via containment (a child is "within" the parent if its bounds sit
+ * inside the parent's).
+ */
+export interface ScopedSelector {
+  /** This level's own selector string (`~`/`#` shorthand or raw CSS/xpath), not the full chain. */
+  selector: string;
+  /** Positional index at this level, or null. */
+  index: number | null;
+  /** The element this selector is scoped within, or undefined for a root-level selector. */
+  parent?: ScopedSelector;
+}
+
+/**
+ * Configuration options for scroll actions.
+ *
+ * @example
+ * ```ts
+ * await Spectra.scroll({ direction: "down", pixels: 300 });
+ * await Spectra.scroll({ selector: "#footer" });
+ * ```
+ */
+export interface ScrollOptions {
+  /** Direction to scroll (default: "down") */
+  direction?: Direction;
+  /** Distance in pixels to scroll (default: 500) */
+  pixels?: number;
+  /** Optional target element selector to scroll directly into view */
+  selector?: ElementTarget;
+}
+
+/**
+ * Configuration options for touch swipe gestures (mobile & web).
+ *
+ * @example
+ * ```ts
+ * await Spectra.swipe({ direction: "left", distance: 400 });
+ * ```
+ */
+export interface SwipeOptions {
+  /** Direction of the swipe gesture */
+  direction: Direction;
+  /** Distance in pixels to swipe (default: 300) */
+  distance?: number;
+  /** Optional element target to anchor the swipe gesture */
+  selector?: ElementTarget;
+}
+
+/**
+ * Configuration options for long-press gestures.
+ *
+ * @example
+ * ```ts
+ * await Spectra.longPress("#draggable-card", { duration: 1500 });
+ * ```
+ */
+export interface LongPressOptions {
+  /** Optional label or text associated with the element */
+  text?: string;
+  /** Duration in milliseconds to hold the press (default: 1000) */
+  duration?: number;
+}
+
+/**
+ * Configuration options for click interactions.
+ */
+export interface ClickOptions {
+  /** Optional inner text filter */
+  text?: string;
+  /** Click type: standard single click or double click */
+  clickType?: 'single' | 'double';
+}
+
+/**
+ * Configuration options for typing input into form elements.
+ *
+ * @example
+ * ```ts
+ * await Spectra.type("#username", "john_doe", { clearFirst: true });
+ * ```
+ */
+export interface TypeOptions {
+  /** Whether to clear existing input value before typing new text (default: false) */
+  clearFirst?: boolean;
+}
+
+/**
+ * Per-call override for how long an assertion polls before failing, mirroring Playwright's
+ * `{ timeout }` option on web-first assertions (`expect(locator).toHaveText(x, { timeout })`).
+ *
+ * Defaults to the adaptive assertion timeout (`Spectra`'s fail-fast cap, distinct from
+ * `implicitWait`) when omitted — pass this when a specific assertion is known to need longer,
+ * e.g. right after a deliberately delayed `Spectra.intercept(..., { delayMs })` mock, without
+ * raising the timeout for every other assertion in the test.
+ *
+ * @example
+ * ```ts
+ * const mock = await Spectra.intercept('/api/report', { response: { delayMs: 4000, body } });
+ * await ReportPage.statusBadge.shouldHaveText('Ready', { timeoutMs: 5000 });
+ * ```
+ */
+export interface AssertionOptions {
+  /** Maximum time (in milliseconds) to keep polling before the assertion fails. */
+  timeoutMs?: number;
+}
+
+/**
+ * Canonical assertion matcher keys for single element verification.
+ * Dispatched internally by semantic receiver methods (`.shouldBeVisible()`, `.shouldHaveText()`, etc.).
+ */
+export type SingleElementMatcher =
+  | 'be.visible'
+  | 'not.be.visible'
+  | 'exist'
+  | 'not.exist'
+  | 'be.clickable'
+  | 'not.be.clickable'
+  | 'be.enabled'
+  | 'be.disabled'
+  | 'be.checked'
+  | 'not.be.checked'
+  | 'be.selected'
+  | 'not.be.selected'
+  | 'be.focused'
+  | 'not.be.focused'
+  | 'have.value'
+  | 'not.have.value'
+  | 'contain.value'
+  | 'not.contain.value'
+  | 'have.text'
+  | 'not.have.text'
+  | 'contain.text'
+  | 'not.contain.text'
+  | 'have.class'
+  | 'not.have.class'
+  | 'have.attr'
+  | 'not.have.attr'
+  | 'have.css'
+  | 'not.have.css'
+  | 'have.url'
+  | 'contain.url'
+  | 'have.title'
+  | 'contain.title';
+
+/**
+ * Canonical assertion matcher keys for multi-element collections.
+ * Dispatched internally by semantic collection methods (`.shouldHaveLength()`, `.shouldBeEmpty()`, etc.).
+ */
+export type MultiElementMatcher =
+  | 'have.length'
+  | 'not.have.length'
+  | 'have.length.greaterThan'
+  | 'have.length.lessThan'
+  | 'be.empty'
+  | 'not.be.empty'
+  | 'exist';
+
+/**
+ * Receiver-oriented element assertion methods.
+ * Attached directly to SingleElementProxy instances.
+ */
+export interface ElementReceiverAssertions<TReturn = Promise<void>> {
+  /**
+   * Asserts that the target element is visible and displayed on the page.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#submit-btn').shouldBeVisible();
+   * await LoginPage.submitButton.shouldBeVisible();
+   * ```
+   */
+  shouldBeVisible(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element is hidden, detached, or not displayed on the page.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('.loading-spinner').shouldNotBeVisible();
+   * ```
+   */
+  shouldNotBeVisible(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element exists in the DOM.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#cookie-consent-modal').shouldExist();
+   * ```
+   */
+  shouldExist(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element does not exist in the DOM.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#deleted-record-row').shouldNotExist();
+   * ```
+   */
+  shouldNotExist(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element is visible, enabled, and clickable.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('button[type="submit"]').shouldBeClickable();
+   * ```
+   */
+  shouldBeClickable(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element is disabled, covered, or not clickable.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('button.disabled-action').shouldNotBeClickable();
+   * ```
+   */
+  shouldNotBeClickable(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target form input/button is enabled (not disabled).
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#username-field').shouldBeEnabled();
+   * ```
+   */
+  shouldBeEnabled(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target form input/button has the disabled state/attribute.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#submit-order-btn').shouldBeDisabled();
+   * ```
+   */
+  shouldBeDisabled(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target checkbox or radio input is checked/selected.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#terms-checkbox').shouldBeChecked();
+   * ```
+   */
+  shouldBeChecked(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target checkbox or radio input is unchecked/deselected.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#subscribe-newsletter').shouldNotBeChecked();
+   * ```
+   */
+  shouldNotBeChecked(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element currently holds active document focus.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#search-input').shouldBeFocused();
+   * ```
+   */
+  shouldBeFocused(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element does not hold active document focus.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#blur-input').shouldNotBeFocused();
+   * ```
+   */
+  shouldNotBeFocused(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element's text content matches the expected string or regular expression.
+   *
+   * @param expected Exact string or RegExp pattern to match against element text.
+   * @example
+   * ```ts
+   * await Spectra.get('h1.page-title').shouldHaveText('Dashboard Overview');
+   * await Spectra.get('.badge').shouldHaveText(/Active|Pending/);
+   * ```
+   */
+  shouldHaveText(expected: string | RegExp, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element's text content does not match the expected string or regular expression.
+   *
+   * @param expected String or RegExp pattern that the element text must NOT match.
+   * @example
+   * ```ts
+   * await Spectra.get('.status-label').shouldNotHaveText('Error');
+   * ```
+   */
+  shouldNotHaveText(expected: string | RegExp, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element's text content contains the specified substring.
+   *
+   * @param substring Substring expected to be present within the element text.
+   * @example
+   * ```ts
+   * await Spectra.get('.toast-message').shouldContainText('Successfully saved');
+   * ```
+   */
+  shouldContainText(substring: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the target element's text content does not contain the specified substring.
+   *
+   * @param substring Substring that must NOT be present within the element text.
+   * @example
+   * ```ts
+   * await Spectra.get('.log-output').shouldNotContainText('Fatal Exception');
+   * ```
+   */
+  shouldNotContainText(substring: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the form input or textarea element's value exactly equals the specified string.
+   *
+   * @param value Expected input field value.
+   * @example
+   * ```ts
+   * await Spectra.get('input[name="email"]').shouldHaveValue('admin@testspectra.dev');
+   * ```
+   */
+  shouldHaveValue(value: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the form input or textarea element's value does not equal the specified string.
+   *
+   * @param value Value that the input field must NOT equal.
+   * @example
+   * ```ts
+   * await Spectra.get('input[name="role"]').shouldNotHaveValue('guest');
+   * ```
+   */
+  shouldNotHaveValue(value: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the form input or textarea element's value contains the specified substring.
+   *
+   * @param substring Substring expected to be contained within the input value.
+   * @example
+   * ```ts
+   * await Spectra.get('input[name="email"]').shouldContainValue('@testspectra.dev');
+   * ```
+   */
+  shouldContainValue(substring: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the form input or textarea element's value does not contain the specified substring.
+   *
+   * @param substring Substring that must NOT be contained within the input value.
+   * @example
+   * ```ts
+   * await Spectra.get('input[name="url"]').shouldNotContainValue('http://');
+   * ```
+   */
+  shouldNotContainValue(substring: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the element has the specified attribute, and optionally that its value matches.
+   *
+   * @param name Attribute name to inspect.
+   * @param value Optional expected attribute value string.
+   * @example
+   * ```ts
+   * await Spectra.get('a.external-link').shouldHaveAttribute('target', '_blank');
+   * await Spectra.get('input.required-field').shouldHaveAttribute('required');
+   * ```
+   */
+  shouldHaveAttribute(name: string, value?: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the element does not have the specified attribute.
+   *
+   * @param name Attribute name that must NOT exist on the element.
+   * @example
+   * ```ts
+   * await Spectra.get('button#action-btn').shouldNotHaveAttribute('disabled');
+   * ```
+   */
+  shouldNotHaveAttribute(name: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the element contains the specified CSS class name.
+   *
+   * @param className CSS class name expected in the element's classList.
+   * @example
+   * ```ts
+   * await Spectra.get('.nav-tab').shouldHaveClass('active');
+   * ```
+   */
+  shouldHaveClass(className: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the element does not contain the specified CSS class name.
+   *
+   * @param className CSS class name that must NOT be in the element's classList.
+   * @example
+   * ```ts
+   * await Spectra.get('.modal-backdrop').shouldNotHaveClass('hidden');
+   * ```
+   */
+  shouldNotHaveClass(className: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the computed CSS style property of the element equals the specified value.
+   *
+   * @param property CSS style property name (e.g. 'color', 'display', 'opacity').
+   * @param value Expected computed CSS property value.
+   * @example
+   * ```ts
+   * await Spectra.get('.badge-success').shouldHaveCss('color', 'rgb(0, 128, 0)');
+   * ```
+   */
+  shouldHaveCss(property: string, value: string, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the computed CSS style property of the element does not equal the specified value.
+   *
+   * @param property CSS style property name.
+   * @param value Value that the computed CSS property must NOT equal.
+   * @example
+   * ```ts
+   * await Spectra.get('.main-content').shouldNotHaveCss('display', 'none');
+   * ```
+   */
+  shouldNotHaveCss(property: string, value: string, options?: AssertionOptions): TReturn;
+}
+
+/**
+ * Receiver-oriented collection assertion methods.
+ * Attached directly to CollectionProxy and collection prototypes.
+ */
+export interface CollectionReceiverAssertions<TReturn = Promise<void>> {
+  /**
+   * Asserts that the collection contains exactly the specified number of matching elements.
+   *
+   * @param count Expected exact count of elements.
+   * @example
+   * ```ts
+   * await Spectra.getAll('.user-table-row').shouldHaveLength(10);
+   * ```
+   */
+  shouldHaveLength(count: number, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the collection does not contain the specified number of matching elements.
+   *
+   * @param count Count that the element collection must NOT equal.
+   * @example
+   * ```ts
+   * await Spectra.getAll('.error-item').shouldNotHaveLength(0);
+   * ```
+   */
+  shouldNotHaveLength(count: number, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the collection contains strictly more than `min` matching elements.
+   *
+   * @param min Minimum threshold (exclusive).
+   * @example
+   * ```ts
+   * await Spectra.getAll('.search-result-card').shouldHaveLengthGreaterThan(0);
+   * ```
+   */
+  shouldHaveLengthGreaterThan(min: number, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the collection contains strictly fewer than `max` matching elements.
+   *
+   * @param max Maximum threshold (exclusive).
+   * @example
+   * ```ts
+   * await Spectra.getAll('.warning-banner').shouldHaveLengthLessThan(5);
+   * ```
+   */
+  shouldHaveLengthLessThan(max: number, options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the collection contains zero matching elements.
+   *
+   * @example
+   * ```ts
+   * await Spectra.getAll('.unread-notification-badge').shouldBeEmpty();
+   * ```
+   */
+  shouldBeEmpty(options?: AssertionOptions): TReturn;
+
+  /**
+   * Asserts that the collection contains at least one matching element.
+   *
+   * @example
+   * ```ts
+   * await Spectra.getAll('.product-card').shouldNotBeEmpty();
+   * ```
+   */
+  shouldNotBeEmpty(options?: AssertionOptions): TReturn;
+}
+
+/**
+ * Browser-level context assertion methods.
+ * Hosted on Spectra.browser and the global browser object.
+ */
+export interface BrowserReceiverAssertions {
+  /**
+   * Asserts that current browser URL exactly matches the expected URL.
+   *
+   * @param expectedUrl Full expected URL string.
+   * @example
+   * ```ts
+   * await Spectra.browser.shouldHaveUrl('https://app.testspectra.dev/dashboard');
+   * ```
+   */
+  shouldHaveUrl(expectedUrl: string, options?: AssertionOptions): Promise<void>;
+
+  /**
+   * Asserts that current browser URL contains the specified substring.
+   *
+   * @param expectedSubstr Substring expected in browser URL.
+   * @example
+   * ```ts
+   * await Spectra.browser.shouldContainUrl('/dashboard');
+   * ```
+   */
+  shouldContainUrl(expectedSubstr: string, options?: AssertionOptions): Promise<void>;
+
+  /**
+   * Asserts that current page title exactly matches the expected title.
+   *
+   * @param expectedTitle Full expected page title string.
+   * @example
+   * ```ts
+   * await Spectra.browser.shouldHaveTitle('Dashboard - TestSpectra');
+   * ```
+   */
+  shouldHaveTitle(expectedTitle: string, options?: AssertionOptions): Promise<void>;
+
+  /**
+   * Asserts that current page title contains the specified substring.
+   *
+   * @param expectedSubstr Substring expected in page title.
+   * @example
+   * ```ts
+   * await Spectra.browser.shouldContainTitle('Dashboard');
+   * ```
+   */
+  shouldContainTitle(expectedSubstr: string, options?: AssertionOptions): Promise<void>;
+
+  /**
+   * Asserts that the browser document `readyState` is 'complete' or 'interactive'.
+   *
+   * @example
+   * ```ts
+   * await Spectra.browser.shouldBeLoaded();
+   * ```
+   */
+  shouldBeLoaded(options?: AssertionOptions): Promise<void>;
+
+  /**
+   * Asserts that no severe or unhandled JavaScript errors occurred in the browser console.
+   *
+   * @example
+   * ```ts
+   * await Spectra.browser.shouldHaveNoConsoleErrors();
+   * ```
+   */
+  shouldHaveNoConsoleErrors(options?: AssertionOptions): Promise<void>;
+
+  /**
+   * Clears all browser cookies for the active domain.
+   *
+   * @example
+   * ```ts
+   * await Spectra.browser.clearCookies();
+   * ```
+   */
+  clearCookies(): Promise<void>;
+
+  /**
+   * Applies one or more raw `Set-Cookie` header values — exactly as received from a `fetch()`
+   * response, e.g. `response.headers.getSetCookie()` — to the browser's cookie jar. Operates at
+   * the CDP `Network` domain level rather than through `document.cookie`, so `HttpOnly` cookies
+   * are fully supported (set, not just read-blocked). Useful for seeding an authenticated session
+   * by logging in via a direct API call instead of driving the real login UI — see
+   * `docs/v2/features/authentication-and-session-seeding.md`.
+   *
+   * `url` is required to resolve `Domain`/`Path`/`Secure` defaults for any `Set-Cookie` value that
+   * doesn't specify them explicitly (an omitted `Domain` defaults to the issuing request's own
+   * host, per RFC 6265) — pass the URL the response actually came from.
+   *
+   * Web only — Android has no browser/cookie-jar concept; see the docs above for the mobile
+   * equivalent (deep-link-triggered, Keystore-backed session seeding).
+   *
+   * @example
+   * ```ts
+   * const res = await fetch('https://api.example.com/auth/login', { method: 'POST', body: ... });
+   * await Spectra.browser.setCookies(res.headers.getSetCookie(), res.url);
+   * ```
+   */
+  setCookies(setCookieHeaders: string | string[], url: string): Promise<void>;
+
+  /**
+   * Clears all key-value entries in browser `localStorage`.
+   *
+   * @example
+   * ```ts
+   * await Spectra.browser.clearLocalStorage();
+   * ```
+   */
+  clearLocalStorage(): Promise<void>;
+}
+
+/**
+ * Native proxy interface for interacting with a single DOM / UI element.
+ */
+export interface SingleElementProxy extends ElementReceiverAssertions<Promise<void>> {
+  /** Target CSS or XPath selector string for this element. */
+  selector: string;
+
+  /** Positional index when matched from a collection (or null for standalone selectors). */
+  index: number | null;
+
+  /**
+   * Finds `childSelector` scoped to this element's subtree, mirroring Playwright's locator
+   * chaining (`parent.locator(child)`) instead of a separate `within()`/`findWithin()` verb.
+   * Resolution is a real DOM descendant query on web; on Android (no ancestor API) it's a
+   * bounds-containment heuristic over the flat accessibility-tree dump.
+   *
+   * @example
+   * ```ts
+   * const modal = Spectra.get('#modal');
+   * await modal.get('#save-btn').click();
+   * ```
+   */
+  get(childSelector: string, index?: number | null): SingleElementProxy;
+
+  /**
+   * Finds all elements matching `childSelector` scoped to this element's subtree — the
+   * collection equivalent of `get()`.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#modal').getAll('.list-item').shouldHaveLength(3);
+   * ```
+   */
+  getAll(childSelector: string): CollectionProxy;
+
+  /**
+   * Waits until the element exists in the DOM within the specified timeout.
+   *
+   * @param timeoutMs Timeout in milliseconds (default: 5000ms).
+   */
+  waitForElement(timeoutMs?: number): Promise<boolean>;
+
+  /**
+   * Clicks on the element.
+   *
+   * @param options Optional click interaction options.
+   * @example
+   * ```ts
+   * await Spectra.get('#submit-btn').click();
+   * ```
+   */
+  click(options?: ClickOptions): Promise<void>;
+
+  /**
+   * Performs a double-click interaction on the element.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('.editable-cell').doubleClick();
+   * ```
+   */
+  doubleClick(): Promise<void>;
+
+  /**
+   * Performs a context-click (right-click) on the element.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('.file-item').rightClick();
+   * ```
+   */
+  rightClick(): Promise<void>;
+
+  /**
+   * Sets or replaces the value of a form input element.
+   *
+   * @param value Text value to set.
+   * @example
+   * ```ts
+   * await Spectra.get('#username').setValue('admin');
+   * ```
+   */
+  setValue(value: unknown): Promise<void>;
+
+  /**
+   * Types text keystrokes into the element, optionally clearing existing content first.
+   *
+   * @param value Text string to type.
+   * @param options Optional type options (e.g. `{ clearFirst: true }`).
+   * @example
+   * ```ts
+   * await LoginPage.emailInput.type('admin@testspectra.dev', { clearFirst: true });
+   * ```
+   */
+  type(value: unknown, options?: TypeOptions): Promise<void>;
+
+  /**
+   * Clears the current text value from an input or textarea element.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#search-bar').clearValue();
+   * ```
+   */
+  clearValue(): Promise<void>;
+
+  /**
+   * Clears the current text value from an input or textarea element (alias to `clearValue()`).
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#search-bar').clear();
+   * ```
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Selects an option in a `<select>` element by its visible text or value.
+   *
+   * @param option Visible text or value of the option to select.
+   * @example
+   * ```ts
+   * await Spectra.get('#country-dropdown').select('Indonesia');
+   * ```
+   */
+  select(option: string): Promise<void>;
+
+  /**
+   * Selects an option in a `<select>` dropdown by its visible text.
+   *
+   * @param text Visible text label of the option.
+   */
+  selectByVisibleText(text: string): Promise<void>;
+
+  /**
+   * Hovers the mouse cursor over the center of the element.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('.dropdown-trigger').hover();
+   * ```
+   */
+  hover(): Promise<void>;
+
+  /**
+   * Focuses the target element (triggers focus event and active document focus).
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#email-input').focus();
+   * ```
+   */
+  focus(): Promise<void>;
+
+  /**
+   * Moves the mouse cursor to the element (alias to `hover()`).
+   */
+  moveTo(): Promise<void>;
+
+  /**
+   * Drags this element and drops it onto the target element destination.
+   *
+   * @param target Destination element target selector or proxy.
+   * @example
+   * ```ts
+   * await Spectra.get('#drag-source').dragDrop('#drop-zone');
+   * ```
+   */
+  dragDrop(target: ElementTarget): Promise<void>;
+
+  /**
+   * Drags this element and drops it onto the target element destination (alias to `dragDrop()`).
+   */
+  dragAndDrop(target: ElementTarget): Promise<void>;
+
+  /**
+   * Scrolls the page until this element is aligned into the visible viewport.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('#footer-links').scrollIntoView();
+   * ```
+   */
+  scrollIntoView(): Promise<void>;
+
+  /**
+   * Long-presses on the element for touch/mobile gestures.
+   *
+   * @param options Long-press duration in milliseconds or configuration object.
+   * @example
+   * ```ts
+   * await Spectra.get('.draggable-card').longPress({ duration: 1500 });
+   * ```
+   */
+  longPress(options?: number | LongPressOptions): Promise<void>;
+
+  /**
+   * Waits until the element is displayed and visible in the viewport.
+   *
+   * @param opts Optional timeout configuration object.
+   */
+  waitForDisplayed(opts?: { timeout?: number }): Promise<boolean>;
+
+  /**
+   * Returns the inner text content of the element.
+   *
+   * @example
+   * ```ts
+   * const headingText = await Spectra.get('h1').getText();
+   * ```
+   */
+  getText(): Promise<string>;
+
+  /**
+   * Returns the current `value` property of an input or textarea element.
+   *
+   * @example
+   * ```ts
+   * const query = await Spectra.get('input#search').getValue();
+   * ```
+   */
+  getValue(): Promise<string>;
+
+  /**
+   * Returns true if the element is currently visible and rendered in the DOM.
+   */
+  isDisplayed(): Promise<boolean>;
+
+  /**
+   * Returns true if the element is currently visible (alias to `isDisplayed()`).
+   */
+  isVisible(): Promise<boolean>;
+
+  /**
+   * Returns true if the element exists in the DOM.
+   */
+  isExisting(): Promise<boolean>;
+
+  /**
+   * Returns true if the element is enabled (not disabled).
+   */
+  isEnabled(): Promise<boolean>;
+
+  /**
+   * Returns true if the checkbox, radio, or `<option>` is selected.
+   */
+  isSelected(): Promise<boolean>;
+
+  /**
+   * Returns true if the checkbox or radio button is checked.
+   */
+  isChecked(): Promise<boolean>;
+
+  /**
+   * Returns true if the element is the active focused element in document.
+   */
+  isFocused(): Promise<boolean>;
+
+  /**
+   * Retrieves the value of a specified HTML attribute from the element.
+   *
+   * @param name Attribute name (e.g. 'href', 'src', 'data-id').
+   * @example
+   * ```ts
+   * const linkUrl = await Spectra.get('a#download').getAttribute('href');
+   * ```
+   */
+  getAttribute(name: string): Promise<string | null>;
+
+  /**
+   * Retrieves the computed CSS property value of the element.
+   *
+   * @param name CSS property name (e.g. 'background-color', 'font-size').
+   * @example
+   * ```ts
+   * const color = await Spectra.get('.btn-primary').getCSSProperty('background-color');
+   * ```
+   */
+  getCSSProperty(name: string): Promise<{ value: string }>;
+}
+
+/**
+ * TestSpectra native element interface alias.
+ */
+export type SpectraElement = SingleElementProxy;
+
+/**
+ * Native proxy interface for interacting with multiple matching elements in a collection.
+ */
+export interface CollectionProxy extends CollectionReceiverAssertions<Promise<void>> {
+  /** Target CSS or XPath selector string for this collection. */
+  selector: string;
+
+  /**
+   * Returns the total count of elements matching this collection selector.
+   *
+   * @example
+   * ```ts
+   * const totalRows = await Spectra.getAll('.table-row').count();
+   * ```
+   */
+  count(): Promise<number>;
+
+  /**
+   * Total count of elements matching this collection selector (Promise).
+   */
+  readonly length: Promise<number>;
+
+  /**
+   * Returns a `SingleElementProxy` pointing to the first matching element in the collection (index 0).
+   *
+   * @example
+   * ```ts
+   * await Spectra.getAll('.list-item').first().click();
+   * ```
+   */
+  first(): SingleElementProxy;
+
+  /**
+   * Returns a `SingleElementProxy` pointing to the last matching element in the collection.
+   *
+   * @example
+   * ```ts
+   * await Spectra.getAll('.list-item').last().click();
+   * ```
+   */
+  last(): SingleElementProxy;
+
+  /**
+   * Returns a `SingleElementProxy` pointing to the matching element at the specified zero-based index.
+   *
+   * When this collection itself came from a `.getAll()` chain, `first()`/`last()`/`nth()` carry
+   * that scope forward instead of reverting to an unscoped lookup — e.g. the button below is
+   * resolved within the 3rd `.card`, not just anywhere on the page:
+   *
+   * @param index Zero-based index of the target element.
+   * @example
+   * ```ts
+   * await Spectra.getAll('.list-item').nth(2).click();
+   * await Spectra.getAll('.card').nth(2).get('.buy-btn').click();
+   * ```
+   */
+  nth(index: number): SingleElementProxy;
+}
+
+/**
+ * TestSpectra native collection interface alias.
+ */
+export type SpectraCollection = CollectionProxy;
+
+/**
+ * Native browser bridge interface for page navigation, execution, and network interception.
+ */
+export interface SpectraBrowserBridge extends BrowserReceiverAssertions {
+  /**
+   * All network requests recorded so far this session — both genuine (non-intercepted) traffic
+   * and requests an active `intercept()` mock fulfilled. Recording is always on; nothing needs
+   * to be explicitly enabled first. On Android, only requests routed through the worker's local
+   * mock proxy are recorded (see `Spectra.intercept`'s docs on why mobile needs an absolute URL
+   * rather than a relative path) — a request the app makes that never reaches the proxy at all
+   * won't appear here.
+   *
+   * @example
+   * ```ts
+   * await Spectra.get('~fetch-api-btn').click();
+   * const entry = Spectra.browser.recordedNetwork.find((e) => e.url.includes('/posts'));
+   * ```
+   */
+  recordedNetwork: CDPNetworkEntry[];
+
+  /**
+   * Retrieves the current browser URL.
+   *
+   * @example
+   * ```ts
+   * const currentUrl = await Spectra.browser.getUrl();
+   * ```
+   */
+  getUrl(): Promise<string>;
+
+  /**
+   * Retrieves the current page title.
+   *
+   * @example
+   * ```ts
+   * const title = await Spectra.browser.getTitle();
+   * ```
+   */
+  getTitle(): Promise<string>;
+
+  /**
+   * Executes a JavaScript function or script snippet in the browser context and returns the result.
+   *
+   * @param fn Function or script string to execute.
+   * @param args Arguments to pass into the function.
+   * @example
+   * ```ts
+   * const docWidth = await Spectra.browser.execute(() => document.body.clientWidth);
+   * ```
+   */
+  execute<R = unknown>(fn: ((...args: unknown[]) => R) | string, ...args: unknown[]): Promise<R>;
+
+  /**
+   * Evaluates a JavaScript expression string in the browser context.
+   *
+   * @param expr JavaScript expression string.
+   * @example
+   * ```ts
+   * const isReady = await Spectra.browser.evaluate('document.readyState === "complete"');
+   * ```
+   */
+  evaluate<R = unknown>(expr: string): Promise<R>;
+
+  /**
+   * Repeatedly polls a condition function until it returns true or times out.
+   *
+   * @param fn Condition function returning a boolean or boolean promise.
+   * @param opts Optional timeout and message options.
+   * @example
+   * ```ts
+   * await Spectra.browser.waitUntil(async () => (await Spectra.get('#status').getText()) === 'Ready', {
+   *   timeout: 5000,
+   *   timeoutMsg: 'Status never reached Ready',
+   * });
+   * ```
+   */
+  waitUntil(fn: () => Promise<boolean> | boolean, opts?: { timeout?: number; timeoutMsg?: string }): Promise<boolean>;
+
+  /**
+   * Retrieves captured browser console log entries.
+   *
+   * @param type Optional log type filter (e.g. 'browser', 'error').
+   */
+  getLogs(type?: string): Promise<Array<{ level: string; message: string }>>;
+}
+
+/**
+ * Intercepted HTTP request metadata captured during test execution.
+ */
+export interface InterceptedRequest {
+  /** Optional unique identifier for the request */
+  id?: string;
+  /** Target request URL */
+  url: string;
+  /** HTTP method */
+  method: string;
+  /** Request headers */
+  headers?: Record<string, string>;
+  /** Request body / payload if available */
+  postData?: string;
+  /** Timestamp when intercepted */
+  timestamp: number;
+}
+
+/**
+ * Queued one-time mock response item for FIFO polling and retry flows.
+ */
+export interface QueuedMockResponse {
+  response: unknown;
+  statusCode: number;
+  headers?: Record<string, string>;
+  /** Milliseconds to wait before fulfilling this response — simulates a late/slow network reply. */
+  delayMs?: number;
+}
+
+/**
+ * Mock rule configuration for CDP & Mobile network request interception.
+ */
+export interface MockRule {
+  /** URL pattern or substring to match. */
+  pattern: string;
+  /** HTTP method (e.g. GET, POST, ALL). */
+  method: string;
+  /** Mock response payload. */
+  response: unknown;
+  /** HTTP status code (e.g. 200, 404). */
+  statusCode: number;
+  /** Custom HTTP response headers. */
+  headers?: Record<string, string>;
+  /** Milliseconds to wait before fulfilling the default response — simulates a late/slow reply. */
+  delayMs?: number;
+  /** Total times this mock rule matched and intercepted requests. */
+  callCount: number;
+  /** FIFO queue of one-time responses (respondOnce) */
+  respondOnceQueue: QueuedMockResponse[];
+  /** Whether requests matching this rule should be aborted / failed */
+  aborted?: boolean;
+  /** Specific error code for network abort simulation */
+  abortReason?: 'Failed' | 'Aborted' | 'TimedOut' | 'ConnectionReset';
+  /** Recorded list of intercepted requests matching this rule */
+  calls: InterceptedRequest[];
+  /** Internal pending waitForCall resolvers (keyed by expected call count). */
+  waitResolvers: Array<{ count: number; resolve: (req: InterceptedRequest) => void }>;
+}
+
+/**
+ * Handle returned by `Spectra.intercept()` to dynamically inspect and update mock responses.
+ */
+export interface MockInterceptHandle {
+  /**
+   * Dynamically updates the default response payload for this active mock rule.
+   *
+   * @param newFixture New response payload object or string.
+   * @param newOptions Optional status code and header overrides.
+   */
+  respondWith: (
+    newFixture: unknown,
+    newOptions?: { statusCode?: number; headers?: Record<string, string>; delayMs?: number },
+  ) => Promise<void>;
+
+  /**
+   * Queues a one-time mock response for the next matching request (FIFO queue for polling/retries).
+   *
+   * @param newFixture One-time response payload object or string.
+   * @param newOptions Optional status code and header overrides.
+   */
+  respondOnce: (
+    newFixture: unknown,
+    newOptions?: { statusCode?: number; headers?: Record<string, string>; delayMs?: number },
+  ) => Promise<void>;
+
+  /**
+   * Simulates a network failure or connection abort for matching requests.
+   *
+   * @param errorCode Network failure reason (default: 'Failed').
+   */
+  abort: (errorCode?: 'Failed' | 'Aborted' | 'TimedOut' | 'ConnectionReset') => Promise<void>;
+
+  /**
+   * Awaits until the mock rule has intercepted at least `count` matching requests.
+   *
+   * @param options Timeout and expected request count.
+   */
+  waitForCall: (options?: { timeout?: number; count?: number }) => Promise<InterceptedRequest>;
+
+  /**
+   * Returns the number of times this mock intercepted network requests.
+   */
+  callCount: (() => number) & number;
+
+  /**
+   * Historical array of all intercepted requests matching this rule.
+   */
+  calls: InterceptedRequest[];
+}
+
+/**
+ * Audit log entry for captured CDP network requests.
+ */
+export interface CDPNetworkEntry {
+  /** Unique CDP request ID. */
+  requestId: string;
+  /** Target request URL. */
+  url: string;
+  /** HTTP request method. */
+  method: string;
+  /** Resource type (e.g. 'Fetch', 'XHR', 'Document', 'Stylesheet'). */
+  type: string;
+  /** HTTP response status code. */
+  status: number;
+  /** HTTP response status message. */
+  statusText: string;
+  /** Host domain name. */
+  domain: string;
+  /** Protocol name (e.g. 'h2', 'http/1.1'). */
+  protocol: string;
+  /** Request timing metrics in milliseconds. */
+  timing: { waiting: number; download: number };
+  /** Content body size in bytes. */
+  size: number;
+  /** Wire transfer size in bytes. */
+  transferSize: number;
+  /** Start timestamp epoch. */
+  startTime: number;
+}
+
+/**
+ * Main TestSpectra cross-platform automation and assertion interface contract.
+ */
+export interface SpectraStatic {
+  /**
+   * Locates a single DOM / UI element proxy by selector or target reference.
+   *
+   * @param target CSS selector string, XPath string, or element proxy.
+   * @example
+   * ```ts
+   * const submitBtn = Spectra.get('#btn-submit');
+   * await submitBtn.click();
+   * ```
+   */
+  get(target: ElementTarget): SingleElementProxy;
+
+  /**
+   * Locates a collection proxy of multiple matching DOM / UI elements by selector.
+   *
+   * @param selector CSS or XPath selector matching multiple elements.
+   * @example
+   * ```ts
+   * const rows = Spectra.getAll('table tr');
+   * await rows.shouldHaveLength(5);
+   * ```
+   */
+  getAll(selector: string): CollectionProxy;
+
+  /**
+   * Navigates the active browser window to the specified URL. On Android, deep-links directly
+   * into the app via `adb shell am start` instead — pass a full URI matching a scheme the app
+   * registers (e.g. `expo-router`'s `scheme` in `app.json`), not a bare path, since there's no
+   * configured base scheme to combine one against.
+   *
+   * @param url Absolute or relative URL on web; a full deep-link URI on Android.
+   * @example
+   * ```ts
+   * await Spectra.navigate('/dashboard'); // web
+   * await Spectra.navigate('testspectra-demo://permission-rationale'); // Android
+   * ```
+   */
+  navigate(url: string): Promise<void>;
+
+  /**
+   * Navigates one step backward in browser history.
+   *
+   * @example
+   * ```ts
+   * await Spectra.back();
+   * ```
+   */
+  back(): Promise<void>;
+
+  /**
+   * Navigates one step forward in browser history.
+   *
+   * @example
+   * ```ts
+   * await Spectra.forward();
+   * ```
+   */
+  forward(): Promise<void>;
+
+  /**
+   * Reloads / refreshes the current active page.
+   *
+   * @example
+   * ```ts
+   * await Spectra.refresh();
+   * ```
+   */
+  refresh(): Promise<void>;
+
+  /**
+   * Sets the browser viewport dimensions (width and height in pixels).
+   *
+   * @param width Viewport width in pixels.
+   * @param height Viewport height in pixels.
+   * @example
+   * ```ts
+   * await Spectra.setViewport(1920, 1080);
+   * ```
+   */
+  setViewport(width: number, height: number): Promise<void>;
+
+  /**
+   * Clicks on the specified element target.
+   *
+   * @param target Element selector string, Page Object element, or proxy.
+   * @param textOrOptions Optional text filter or click options.
+   * @example
+   * ```ts
+   * await Spectra.click('#submit-btn');
+   * await Spectra.click(LoginPage.submitButton);
+   * ```
+   */
+  click(target: ElementTarget, textOrOptions?: string | ClickOptions): Promise<void>;
+
+  /**
+   * Performs a double-click interaction on the specified element target.
+   *
+   * @param target Target element selector or proxy.
+   * @example
+   * ```ts
+   * await Spectra.doubleClick('.grid-cell');
+   * ```
+   */
+  doubleClick(target: ElementTarget): Promise<void>;
+
+  /**
+   * Performs a context-click (right-click) interaction on the specified element target.
+   *
+   * @param target Target element selector or proxy.
+   * @example
+   * ```ts
+   * await Spectra.rightClick('#context-menu-area');
+   * ```
+   */
+  rightClick(target: ElementTarget): Promise<void>;
+
+  /**
+   * Types text keystrokes into the specified element target.
+   *
+   * @param target Target input or textarea element selector or proxy.
+   * @param text String content to type.
+   * @param options Optional typing configuration (e.g. `{ clearFirst: true }`).
+   * @example
+   * ```ts
+   * await Spectra.type('#username', 'john_doe', { clearFirst: true });
+   * ```
+   */
+  type(target: ElementTarget, text: string, options?: TypeOptions): Promise<void>;
+
+  /**
+   * Clears the current text value from an input or textarea element.
+   *
+   * @param target Target element selector or proxy.
+   * @example
+   * ```ts
+   * await Spectra.clear('#search-input');
+   * ```
+   */
+  clear(target: ElementTarget): Promise<void>;
+
+  /**
+   * Selects an option in a `<select>` dropdown by its visible text or value.
+   *
+   * @param target Target select element selector or proxy.
+   * @param option Visible text label or value of the option.
+   * @example
+   * ```ts
+   * await Spectra.select('#country-dropdown', 'United States');
+   * ```
+   */
+  select(target: ElementTarget, option: string): Promise<void>;
+
+  /**
+   * Hovers the mouse cursor over the specified element target.
+   *
+   * @param target Target element selector or proxy.
+   * @example
+   * ```ts
+   * await Spectra.hover('.profile-menu-trigger');
+   * ```
+   */
+  hover(target: ElementTarget): Promise<void>;
+
+  /**
+   * Focuses the target element (triggers focus event and active document focus).
+   *
+   * @param target Target element selector or proxy.
+   * @example
+   * ```ts
+   * await Spectra.focus('#email-input');
+   * ```
+   */
+  focus(target: ElementTarget): Promise<void>;
+
+  /**
+   * Drags a source element and drops it onto a destination element target.
+   *
+   * @param source Draggable source element selector or proxy.
+   * @param destination Drop zone destination element selector or proxy.
+   * @example
+   * ```ts
+   * await Spectra.dragDrop('#item-1', '#kanban-column-done');
+   * ```
+   */
+  dragDrop(source: ElementTarget, destination: ElementTarget): Promise<void>;
+
+  /**
+   * Scrolls the page until the specified element is aligned into the visible viewport.
+   *
+   * @param target Target element selector or proxy.
+   * @example
+   * ```ts
+   * await Spectra.scrollIntoView('#footer-contact');
+   * ```
+   */
+  scrollIntoView(target: ElementTarget): Promise<void>;
+
+  /**
+   * Performs a directional scroll on the page.
+   *
+   * @param options Scroll options (direction, pixel distance, or target selector).
+   * @example
+   * ```ts
+   * await Spectra.scroll({ direction: 'down', pixels: 400 });
+   * ```
+   */
+  scroll(options?: ScrollOptions): Promise<void>;
+
+  /**
+   * Performs a directional touch swipe gesture (mobile & web).
+   *
+   * @param options Swipe options (direction, distance in pixels, anchor selector).
+   * @example
+   * ```ts
+   * await Spectra.swipe({ direction: 'left', distance: 300 });
+   * ```
+   */
+  swipe(options: SwipeOptions): Promise<void>;
+
+  /**
+   * Performs a long-press touch gesture on the target element.
+   *
+   * @param target Target element selector or proxy.
+   * @param options Long-press duration in milliseconds or configuration object.
+   * @example
+   * ```ts
+   * await Spectra.longPress('#sortable-item', { duration: 1500 });
+   * ```
+   */
+  longPress(target: ElementTarget, options?: LongPressOptions | number): Promise<void>;
+
+  /**
+   * Presses a specific keyboard key into the active document element.
+   *
+   * @param key Key name to press (e.g. 'Enter', 'Tab', 'Escape', 'Backspace').
+   * @example
+   * ```ts
+   * await Spectra.pressKey('Enter');
+   * ```
+   */
+  pressKey(key: KeyOption | string): Promise<void>;
+
+  /**
+   * Grants an Android runtime permission on demand — typically called right after confirming an
+   * in-app rationale dialog, so a test can exercise its own permission-request UX instead of
+   * having every permission pre-granted before the app even launches. No-op on platforms without
+   * an OS-level runtime permission model (e.g. web).
+   *
+   * @param name Fully-qualified Android permission name (e.g. 'android.permission.CAMERA').
+   * @example
+   * ```ts
+   * await Spectra.get('~rationale-allow-btn').click();
+   * await Spectra.grantPermission('android.permission.CAMERA');
+   * ```
+   */
+  grantPermission(name: string): Promise<void>;
+
+  /**
+   * Pauses test execution for the specified number of milliseconds.
+   *
+   * @param ms Milliseconds to wait.
+   * @example
+   * ```ts
+   * await Spectra.wait(1000);
+   * ```
+   */
+  wait(ms: number): Promise<void>;
+
+  /**
+   * Waits for the specified element to appear and exist in the DOM.
+   *
+   * @param target Target element selector or proxy.
+   * @param timeoutMs Maximum time to wait in milliseconds (default: 5000ms).
+   * @example
+   * ```ts
+   * await Spectra.waitForElement('#dynamic-content', 10000);
+   * ```
+   */
+  waitForElement(target: ElementTarget, timeoutMs?: number): Promise<void>;
+
+  /**
+   * Direct access to browser context commands and page assertions.
+   */
+  browser: SpectraBrowserBridge;
+
+  /**
+   * Typed environment variables from `spectra.config.ts`'s `executionConfig.environmentVariables`.
+   * Each configured key is generated into `.testspectra/types/env.d.ts` as a `SpectraEnv` member
+   * (TypeScript interface merging), so `Spectra.env.MY_KEY` resolves to `string` — never
+   * `string | undefined` like raw `process.env.MY_KEY` would.
+   *
+   * @example
+   * ```ts
+   * const mode = Spectra.env.API_MODE;
+   * ```
+   */
+  env: SpectraEnv;
+
+  /**
+   * Intercepts and mocks HTTP network requests matching the specified pattern or options.
+   *
+   * @param patternOrOptions URL pattern string or structured intercept configuration object.
+   * @param method HTTP method (GET, POST, etc.) when pattern string is used.
+   * @param fixture Mock response payload.
+   * @param options Additional response options (status code, custom headers).
+   * @example
+   * ```ts
+   * const mock = await Spectra.intercept('/api/v1/profile', 'GET', { name: 'Admin', role: 'root' });
+   * ```
+   */
+  intercept(
+    patternOrOptions: string | { url: string; method?: string; response?: unknown },
+    method?: string,
+    fixture?: unknown,
+    options?: { statusCode?: number; headers?: Record<string, string>; delayMs?: number },
+  ): Promise<MockInterceptHandle>;
+
+  /**
+   * Clears and resets all active CDP network interception rules.
+   *
+   * @example
+   * ```ts
+   * Spectra.clearMocks();
+   * ```
+   */
+  clearMocks(): void;
+}