askui 0.18.0 → 0.19.0

package/dist/esm/execution/dsl.js

@@ -28,7 +28,11 @@ class FluentBase {
         if (this instanceof FluentCommand) {
             const fluentCommand = this;
             const customElements = newParamsList.has('customElement') ? newParamsList.get('customElement') : [];
-            return fluentCommand.fluentCommandExecutor(newCurrentInstruction.trim(), customElements);
+            const aiElementNames = newParamsList.has('aiElementName') ? newParamsList.get('aiElementName') : [];
+            return fluentCommand.fluentCommandExecutor(newCurrentInstruction.trim(), {
+                customElementsJson: customElements,
+                aiElementNames,
+            });
         }
         if (!this.prev) {
             throw new Error('Prev element not defined');
@@ -41,7 +45,11 @@ class FluentBase {
         if (this instanceof Getter) {
             const getter = this;
             const customElements = newParamsList.has('customElement') ? newParamsList.get('customElement') : [];
-            return getter.getterExecutor(newCurrentInstruction.trim(), customElements);
+            const aiElementNames = newParamsList.has('aiElementName') ? newParamsList.get('aiElementName') : [];
+            return getter.getterExecutor(newCurrentInstruction.trim(), {
+                customElementsJson: customElements,
+                aiElementNames,
+            });
         }
         if (!this.prev) {
             throw new Error('Prev element not defined');
@@ -143,9 +151,11 @@ export class FluentFilters extends FluentBase {
      *
      * **Examples:**
      * ```typescript
-     * await aui.moveMouseTo().button().exec()
+     * await aui.click().button().contains().text().withText('Google Search').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/button.gif)
+     *
      * @return {FluentFiltersOrRelations}
      */
     button() {
@@ -205,13 +215,20 @@ export class FluentFilters extends FluentBase {
     /**
      * Filters for an UI element 'text'.
      *
-     * Often combined with the filter `withText()` as shown in the below examples.
+     * Takes an optional parameter to filter for a specific text.
+     * See the examples below.
+     *
      * See also the filters `withTextRegex()` and `withExactText()`
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().text().withText('Password').exec();
+     * await aui.click().text().exec();
+     * await aui.click().text('Username').exec();
+     *
+     * // Matching with an exact text
      * await aui.click().text().withExactText('Username').exec();
+     *
+     * // Matching with a regex
      * await aui.click().text().withTextRegex('\b[Ss]\w+').exec();
      * ```
      *
@@ -235,6 +252,8 @@ export class FluentFilters extends FluentBase {
      * icon().withText('plus')
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/icon.gif)
+     *
      * **Note:** This is an alpha feature. The prediction of the icon name is sometimes unstable. Use custom elements as an alternative.
      *
      * @return {FluentFiltersOrRelations}
@@ -245,7 +264,9 @@ export class FluentFilters extends FluentBase {
         return new FluentFiltersOrRelations(this);
     }
     /**
-     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element that is not recognized by our machine learning models by default. It can also be used for pixel assertions of elements using classical [template matching](https://en.wikipedia.org/wiki/Template_matching).
+     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element based on an image instead of using text or element descriptions like `button().withText('Submit')` in `await aui.click().button().withText('Submit').exec()`.
+     *
+     * See the tutorial - [Custom Element](https://docs.askui.com/docs/general/Tutorials/custom-element) for more detail.
      *
      * **Example**
      * ```typescript
@@ -255,6 +276,7 @@ export class FluentFilters extends FluentBase {
      *         customImage: './logo.png', // required
      *         name: 'myLogo', // optional
      *         threshold: 0.9, // optional, defaults to 0.9
+     *         stopThreshold: 0.9, // optional, defaults to 0.9
      *         rotationDegreePerStep: 0, // optional, defaults to 0
      *         imageCompareFormat: 'grayscale', // optional, defaults to 'grayscale'
      *         // mask:{x:0, y:0}[] // optional, a polygon to match only a certain area of the custom element
@@ -269,12 +291,13 @@ export class FluentFilters extends FluentBase {
      * - **name** (*`string`, optional*):
      *     - A unique name that can be used for filtering for the custom element. If not given, any text inside the custom image will be detected via OCR.
      * - **threshold** (*`number`, optional*):
-     *     - A threshold for how much a UI element needs to be similar to the custom element as defined. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     *     - A threshold for how much a UI element needs to be similar to the custom element as defined by the image. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     * - **stopThreshold** (*`number`, optional*):
+     *     - A threshold for when to stop searching for UI elements similar to the custom element. As soon as UI elements have been found that are at least as similar as the `stopThreshold`, the search is going to stop. After that elements are filtered using the `threshold`. Because of that the `stopThreshold` should be greater than or equal to `threshold`. It is primarily to be used as a speed improvement (by lowering the value). Takes values between `0.0` and `1.0`. Defaults to `0.9`.
      * - **rotationDegreePerStep** (*`number`, optional*):
      *     - Step size in rotation degree. Rotates the custom image by this step size until 360° is exceeded. The range is from `0` to `360`. Defaults to `0`.
-     * - **imageCompareFormat** (*`'RGB' | 'grayscale'`, optional*):
-     *     - The color compare style. 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three color. Defaults to 'grayscale'.
-     * of the given custom image.
+     * - **imageCompareFormat** (*`'RGB' | 'grayscale' | 'edges'`, optional*):
+     *     - The color compare style. 'edges' compares only edges, 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three colors (red, green, blue). Defaults to 'grayscale'.
      *
      *
      * @param {CustomElementJson} customElement - The custom element to filter for.
@@ -288,6 +311,23 @@ export class FluentFilters extends FluentBase {
         this._params.set('customElement', customElement);
         return new FluentFiltersOrRelations(this);
     }
+    /**
+     * Detects an AI Element created with the workflow creator.
+     *
+     * @param {string} aiElementName - Name of the AI Element.
+     *
+     * @return {FluentFiltersOrRelations}
+     */
+    aiElement(aiElementName) {
+        this._textStr = '';
+        this._textStr += 'ai';
+        this._textStr += ' element';
+        this._textStr += ' with';
+        this._textStr += ' name';
+        this._textStr += ` ${Separators.STRING}${aiElementName}${Separators.STRING}`;
+        this._params.set('aiElementName', aiElementName);
+        return new FluentFiltersOrRelations(this);
+    }
     /**
      * Filters for a UI element 'image'.
      *
@@ -297,10 +337,14 @@ export class FluentFilters extends FluentBase {
      * await aui.click().image().exec();
      *
      * // Works if you have an image with
-     * // a caption text below
-     * await aui.click().image().above().text().withText('The caption').exec();
+     * // a text below
+     * await aui.click().image().above().text().withText('Automating WebGL').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/image.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelations}
      */
     image() {
@@ -321,6 +365,10 @@ export class FluentFilters extends FluentBase {
      * await aui.typeIn('Oh yeah').textfield().below().text().withText('E-Mail Address').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/textfield.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelations}
      */
     textfield() {
@@ -329,7 +377,13 @@ export class FluentFilters extends FluentBase {
         return new FluentFiltersOrRelations(this);
     }
     /**
-     * Filters for similar (doesn't need to be a 100% equal) text.
+     * Filters for similar -- meaning >70% similar -- text.
+     *
+     * Takes an optional parameter to specify the similarity. Usually you need the optional parameter for long texts you want to match precisely.
+     *
+     * _We use [RapidFuzz](https://maxbachmann.github.io/RapidFuzz/Usage/fuzz.html#ratio) which calculates the similarity like this:_
+     *
+     * `1 - (distance / (lengthString1 + lengthString2))`
      *
      * **Examples:**
      * ```typescript
@@ -344,6 +398,11 @@ export class FluentFilters extends FluentBase {
      * // usually false
      * 'atebxtc' === withText('text') => false
      * 'other' === withText('text') => false
+     *
+     * // optional parameter: similarity_score
+     * '978-0-201-00650-6' == withText('978-0-201-00') => true with 82.76 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => false with 82.76 < 90 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => true with 93.75 < 90 similarity
      * ```
      * ![](https://docs.askui.com/img/gif/withText.gif)
      *
@@ -374,6 +433,10 @@ export class FluentFilters extends FluentBase {
      * await aui.get().text().withTextRegex('\b[Ss]\w+').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withtextregex.gif)
+     *
+     *
+     *
      * @param {string} regex_pattern - A regex pattern
      *
      * @return {FluentFiltersOrRelations}
@@ -402,6 +465,10 @@ export class FluentFilters extends FluentBase {
      * await aui.moveMouseTo().text().withExactText('Password').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withexacttext.gif)
+     *
+     *
+     *
      * @param {string} text - A text to be matched.
      *
      * @return {FluentFiltersOrRelations}
@@ -438,17 +505,28 @@ export class FluentFilters extends FluentBase {
     /**
      * Filters elements based on a textual description.
      *
-     * ## What Should I Write as Matching Text
+     * **What Should I Write as Matching Text**
+     *
      * The text description inside the `matching()` should describe the element visually.
      * It understands color, some famous company/product names, general descriptions.
      *
-     * It sometimes requires a bit of playing to find a matching description:
-     * E.g. `puzzle piece` can fail here while `an icon showing a puzzle piece` might work.
+     * It sometimes requires a bit of playing around to find a matching description:
+     * E.g. `puzzle piece` can fail while `an icon showing a puzzle piece` might work.
      * Generally the more detail the better.
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().matching('a mask on purple background and a firefox logo').exec()
+     * // Select the black sneaker from a bunch of sneakers
+     * await aui.click().element().matching('a black sneaker shoe').exec();
+     *
+     * // Select an image that has text in it
+     * await aui.click().element().matching('has Burger King in it').exec();
+     * await aui.click().element().matching('has adidas in it').exec();
+     *
+     * // Target a logo/image by describing it
+     * await aui.click().element().matching('a mask on purple background and a firefox logo').exec();
+     * await aui.click().element().matching('logo looking like an apple with one bite bitten off').exec();
+     * await aui.click().element().matching('logo looking like a seashell').exec();
      * ```
      *
      * @param {string} text - A description of the target element.
@@ -606,14 +684,19 @@ export class FluentFiltersOrRelations extends FluentFilters {
     /**
      * Filters for an element right of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl    |  |  rightEl0  |  |  rightEl1  |
+     * --------------  --------------  --------------
      *
-     * // Returns rightEl because rightEl is right of leftEl
+     * // Returns rightEl0 because rightEl0 is the first element right of leftEl
      * ...rightEl().rightOf().leftEl()
+     * ...rightEl().rightOf(0).leftEl()
+     * // Returns rightEl1 because rightEl1 is the second element right of leftEl
+     * ...rightEl().rightOf(1).leftEl()
      * // Returns no element because leftEl is left of rightEl
      * ...leftEl().rightOf().rightEl()
      * ```
@@ -633,14 +716,19 @@ export class FluentFiltersOrRelations extends FluentFilters {
     /**
      * Filters for an element left of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl1   |  |  leftEl0   |  |  rightEl   |
+     * --------------  --------------  --------------
      *
-     * // Returns leftEl because leftEl is left of rightEl
+     * // Returns leftEl0 because leftEl0 is the first element left of rightEl
      * ...leftEl().leftOf().rightEl()
+     * ...leftEl().leftOf(0).rightEl()
+     * // Returns leftEl1 because leftEl1 is the second element left of rightEl
+     * ...leftEl().leftOf(1).rightEl()
      * // Returns no element because rightEl is left of leftEl
      * ...rightEl().leftOf().leftEl()
      * ```
@@ -660,17 +748,25 @@ export class FluentFiltersOrRelations extends FluentFilters {
     /**
      * Filters for an element below another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
      * |    text    |
      * --------------
      * --------------
-     * |   button   |
+     * |   button0  |
+     * --------------
+     * --------------
+     * |   button1  |
      * --------------
      *
-     * // Returns button because button is below text
+     * // Returns button0 because button0 is the first button below text
      * ...button().below().text()
+     * ...button().below(0).text()
+     * // Returns button1 because button1  is the second button below text
+     * ...button().below(1).text()
      * // Returns no element because text is above button
      * ...text().below().button()
      * ```
@@ -689,17 +785,25 @@ export class FluentFiltersOrRelations extends FluentFilters {
     /**
      * Filters for an element above another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
-     * |    text    |
+     * |   text1    |
+     * --------------
+     * --------------
+     * |   text0    |
      * --------------
      * --------------
      * |   button   |
      * --------------
      *
-     * // Returns text because text is above button
+     * // Returns text0 because text0 is the first element above button
      * ...text().above().button()
+     * ...text().above(0).button()
+     * // Returns text1 because text1 is the second element above button
+     * ...text().above(1).button()
      * // Returns no element because button is below text
      * ...button().above().text()
      * ```
@@ -864,9 +968,11 @@ export class FluentFiltersCondition extends FluentBase {
      *
      * **Examples:**
      * ```typescript
-     * await aui.moveMouseTo().button().exec()
+     * await aui.click().button().contains().text().withText('Google Search').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/button.gif)
+     *
      * @return {FluentFiltersOrRelationsCondition}
      */
     button() {
@@ -926,13 +1032,20 @@ export class FluentFiltersCondition extends FluentBase {
     /**
      * Filters for an UI element 'text'.
      *
-     * Often combined with the filter `withText()` as shown in the below examples.
+     * Takes an optional parameter to filter for a specific text.
+     * See the examples below.
+     *
      * See also the filters `withTextRegex()` and `withExactText()`
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().text().withText('Password').exec();
+     * await aui.click().text().exec();
+     * await aui.click().text('Username').exec();
+     *
+     * // Matching with an exact text
      * await aui.click().text().withExactText('Username').exec();
+     *
+     * // Matching with a regex
      * await aui.click().text().withTextRegex('\b[Ss]\w+').exec();
      * ```
      *
@@ -956,6 +1069,8 @@ export class FluentFiltersCondition extends FluentBase {
      * icon().withText('plus')
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/icon.gif)
+     *
      * **Note:** This is an alpha feature. The prediction of the icon name is sometimes unstable. Use custom elements as an alternative.
      *
      * @return {FluentFiltersOrRelationsCondition}
@@ -966,7 +1081,9 @@ export class FluentFiltersCondition extends FluentBase {
         return new FluentFiltersOrRelationsCondition(this);
     }
     /**
-     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element that is not recognized by our machine learning models by default. It can also be used for pixel assertions of elements using classical [template matching](https://en.wikipedia.org/wiki/Template_matching).
+     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element based on an image instead of using text or element descriptions like `button().withText('Submit')` in `await aui.click().button().withText('Submit').exec()`.
+     *
+     * See the tutorial - [Custom Element](https://docs.askui.com/docs/general/Tutorials/custom-element) for more detail.
      *
      * **Example**
      * ```typescript
@@ -976,6 +1093,7 @@ export class FluentFiltersCondition extends FluentBase {
      *         customImage: './logo.png', // required
      *         name: 'myLogo', // optional
      *         threshold: 0.9, // optional, defaults to 0.9
+     *         stopThreshold: 0.9, // optional, defaults to 0.9
      *         rotationDegreePerStep: 0, // optional, defaults to 0
      *         imageCompareFormat: 'grayscale', // optional, defaults to 'grayscale'
      *         // mask:{x:0, y:0}[] // optional, a polygon to match only a certain area of the custom element
@@ -990,12 +1108,13 @@ export class FluentFiltersCondition extends FluentBase {
      * - **name** (*`string`, optional*):
      *     - A unique name that can be used for filtering for the custom element. If not given, any text inside the custom image will be detected via OCR.
      * - **threshold** (*`number`, optional*):
-     *     - A threshold for how much a UI element needs to be similar to the custom element as defined. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     *     - A threshold for how much a UI element needs to be similar to the custom element as defined by the image. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     * - **stopThreshold** (*`number`, optional*):
+     *     - A threshold for when to stop searching for UI elements similar to the custom element. As soon as UI elements have been found that are at least as similar as the `stopThreshold`, the search is going to stop. After that elements are filtered using the `threshold`. Because of that the `stopThreshold` should be greater than or equal to `threshold`. It is primarily to be used as a speed improvement (by lowering the value). Takes values between `0.0` and `1.0`. Defaults to `0.9`.
      * - **rotationDegreePerStep** (*`number`, optional*):
      *     - Step size in rotation degree. Rotates the custom image by this step size until 360° is exceeded. The range is from `0` to `360`. Defaults to `0`.
-     * - **imageCompareFormat** (*`'RGB' | 'grayscale'`, optional*):
-     *     - The color compare style. 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three color. Defaults to 'grayscale'.
-     * of the given custom image.
+     * - **imageCompareFormat** (*`'RGB' | 'grayscale' | 'edges'`, optional*):
+     *     - The color compare style. 'edges' compares only edges, 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three colors (red, green, blue). Defaults to 'grayscale'.
      *
      *
      * @param {CustomElementJson} customElement - The custom element to filter for.
@@ -1009,6 +1128,23 @@ export class FluentFiltersCondition extends FluentBase {
         this._params.set('customElement', customElement);
         return new FluentFiltersOrRelationsCondition(this);
     }
+    /**
+     * Detects an AI Element created with the workflow creator.
+     *
+     * @param {string} aiElementName - Name of the AI Element.
+     *
+     * @return {FluentFiltersOrRelationsCondition}
+     */
+    aiElement(aiElementName) {
+        this._textStr = '';
+        this._textStr += 'ai';
+        this._textStr += ' element';
+        this._textStr += ' with';
+        this._textStr += ' name';
+        this._textStr += ` ${Separators.STRING}${aiElementName}${Separators.STRING}`;
+        this._params.set('aiElementName', aiElementName);
+        return new FluentFiltersOrRelationsCondition(this);
+    }
     /**
      * Filters for a UI element 'image'.
      *
@@ -1018,10 +1154,14 @@ export class FluentFiltersCondition extends FluentBase {
      * await aui.click().image().exec();
      *
      * // Works if you have an image with
-     * // a caption text below
-     * await aui.click().image().above().text().withText('The caption').exec();
+     * // a text below
+     * await aui.click().image().above().text().withText('Automating WebGL').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/image.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelationsCondition}
      */
     image() {
@@ -1042,6 +1182,10 @@ export class FluentFiltersCondition extends FluentBase {
      * await aui.typeIn('Oh yeah').textfield().below().text().withText('E-Mail Address').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/textfield.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelationsCondition}
      */
     textfield() {
@@ -1050,7 +1194,13 @@ export class FluentFiltersCondition extends FluentBase {
         return new FluentFiltersOrRelationsCondition(this);
     }
     /**
-     * Filters for similar (doesn't need to be a 100% equal) text.
+     * Filters for similar -- meaning >70% similar -- text.
+     *
+     * Takes an optional parameter to specify the similarity. Usually you need the optional parameter for long texts you want to match precisely.
+     *
+     * _We use [RapidFuzz](https://maxbachmann.github.io/RapidFuzz/Usage/fuzz.html#ratio) which calculates the similarity like this:_
+     *
+     * `1 - (distance / (lengthString1 + lengthString2))`
      *
      * **Examples:**
      * ```typescript
@@ -1065,6 +1215,11 @@ export class FluentFiltersCondition extends FluentBase {
      * // usually false
      * 'atebxtc' === withText('text') => false
      * 'other' === withText('text') => false
+     *
+     * // optional parameter: similarity_score
+     * '978-0-201-00650-6' == withText('978-0-201-00') => true with 82.76 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => false with 82.76 < 90 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => true with 93.75 < 90 similarity
      * ```
      * ![](https://docs.askui.com/img/gif/withText.gif)
      *
@@ -1095,6 +1250,10 @@ export class FluentFiltersCondition extends FluentBase {
      * await aui.get().text().withTextRegex('\b[Ss]\w+').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withtextregex.gif)
+     *
+     *
+     *
      * @param {string} regex_pattern - A regex pattern
      *
      * @return {FluentFiltersOrRelationsCondition}
@@ -1123,6 +1282,10 @@ export class FluentFiltersCondition extends FluentBase {
      * await aui.moveMouseTo().text().withExactText('Password').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withexacttext.gif)
+     *
+     *
+     *
      * @param {string} text - A text to be matched.
      *
      * @return {FluentFiltersOrRelationsCondition}
@@ -1159,17 +1322,28 @@ export class FluentFiltersCondition extends FluentBase {
     /**
      * Filters elements based on a textual description.
      *
-     * ## What Should I Write as Matching Text
+     * **What Should I Write as Matching Text**
+     *
      * The text description inside the `matching()` should describe the element visually.
      * It understands color, some famous company/product names, general descriptions.
      *
-     * It sometimes requires a bit of playing to find a matching description:
-     * E.g. `puzzle piece` can fail here while `an icon showing a puzzle piece` might work.
+     * It sometimes requires a bit of playing around to find a matching description:
+     * E.g. `puzzle piece` can fail while `an icon showing a puzzle piece` might work.
      * Generally the more detail the better.
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().matching('a mask on purple background and a firefox logo').exec()
+     * // Select the black sneaker from a bunch of sneakers
+     * await aui.click().element().matching('a black sneaker shoe').exec();
+     *
+     * // Select an image that has text in it
+     * await aui.click().element().matching('has Burger King in it').exec();
+     * await aui.click().element().matching('has adidas in it').exec();
+     *
+     * // Target a logo/image by describing it
+     * await aui.click().element().matching('a mask on purple background and a firefox logo').exec();
+     * await aui.click().element().matching('logo looking like an apple with one bite bitten off').exec();
+     * await aui.click().element().matching('logo looking like a seashell').exec();
      * ```
      *
      * @param {string} text - A description of the target element.
@@ -1327,14 +1501,19 @@ export class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
     /**
      * Filters for an element right of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl    |  |  rightEl0  |  |  rightEl1  |
+     * --------------  --------------  --------------
      *
-     * // Returns rightEl because rightEl is right of leftEl
+     * // Returns rightEl0 because rightEl0 is the first element right of leftEl
      * ...rightEl().rightOf().leftEl()
+     * ...rightEl().rightOf(0).leftEl()
+     * // Returns rightEl1 because rightEl1 is the second element right of leftEl
+     * ...rightEl().rightOf(1).leftEl()
      * // Returns no element because leftEl is left of rightEl
      * ...leftEl().rightOf().rightEl()
      * ```
@@ -1354,14 +1533,19 @@ export class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
     /**
      * Filters for an element left of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl1   |  |  leftEl0   |  |  rightEl   |
+     * --------------  --------------  --------------
      *
-     * // Returns leftEl because leftEl is left of rightEl
+     * // Returns leftEl0 because leftEl0 is the first element left of rightEl
      * ...leftEl().leftOf().rightEl()
+     * ...leftEl().leftOf(0).rightEl()
+     * // Returns leftEl1 because leftEl1 is the second element left of rightEl
+     * ...leftEl().leftOf(1).rightEl()
      * // Returns no element because rightEl is left of leftEl
      * ...rightEl().leftOf().leftEl()
      * ```
@@ -1381,17 +1565,25 @@ export class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
     /**
      * Filters for an element below another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
      * |    text    |
      * --------------
      * --------------
-     * |   button   |
+     * |   button0  |
+     * --------------
+     * --------------
+     * |   button1  |
      * --------------
      *
-     * // Returns button because button is below text
+     * // Returns button0 because button0 is the first button below text
      * ...button().below().text()
+     * ...button().below(0).text()
+     * // Returns button1 because button1  is the second button below text
+     * ...button().below(1).text()
      * // Returns no element because text is above button
      * ...text().below().button()
      * ```
@@ -1410,17 +1602,25 @@ export class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
     /**
      * Filters for an element above another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
-     * |    text    |
+     * |   text1    |
+     * --------------
+     * --------------
+     * |   text0    |
      * --------------
      * --------------
      * |   button   |
      * --------------
      *
-     * // Returns text because text is above button
+     * // Returns text0 because text0 is the first element above button
      * ...text().above().button()
+     * ...text().above(0).button()
+     * // Returns text1 because text1 is the second element above button
+     * ...text().above(1).button()
      * // Returns no element because button is below text
      * ...button().above().text()
      * ```
@@ -1504,12 +1704,12 @@ export class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
      * **Examples:**
      * ```typescript
      * // Stops execution at this point when the element does not exist.
-     * await aui.expect().text().withText('Login').exists().exec()
+     * await aui.expect().text('Login').exists().exec()
      *
      * // This will catch the error and log a message
      * // But the execution will continue afterwards
      * try {
-     *     await aui.expect().text().withText('Login').exists().exec()
+     *     await aui.expect().text('Login').exists().exec()
      * } catch (error) {
      *     console.log('Too bad we could not find the element!');
      * }
@@ -1532,12 +1732,12 @@ export class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
      * **Examples:**
      * ```typescript
      * // Stops execution at this point when the element does exist.
-     * await aui.expect().text().withText('Login').notExists().exec()
+     * await aui.expect().text('Login').notExists().exec()
      *
      * // This will catch the error and log a message
      * // But the execution will continue afterwards
      * try {
-     *     await aui.expect().text().withText('Login').notExists().exec()
+     *     await aui.expect().text('Login').notExists().exec()
      * } catch (error) {
      *     console.log('Too bad we could find the element!');
      * }
@@ -1566,8 +1766,8 @@ export class FluentCommand extends FluentBase {
      *
      * **Examples:**
      * ```typescript
-     * await aui.expect().text().withText('Login').exists().exec()
-     * await aui.expect().text().withText('Login').notExists().exec()
+     * await aui.expect().text('Login').exists().exec()
+     * await aui.expect().text('Login').notExists().exec()
      * ```
      *
      * @return {FluentFiltersCondition}
@@ -1584,9 +1784,13 @@ export class FluentCommand extends FluentBase {
      *
      * **Example:**
      * ```typescript
-     * await aui.click().button().withText('Submit').exec()
+     * await aui.click().button().withText('Google Search').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/click.gif)
+     *
+     *
+     *
      * @return {FluentFilters}
      */
     click() {
@@ -1600,9 +1804,13 @@ export class FluentCommand extends FluentBase {
      *
      * **Example:**
      * ```typescript
-     * await aui.moveMouseTo().button().withText('Submit').exec()
+     * await aui.moveMouseTo().text().withText('Grinning_Face').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/movemouseto.gif)
+     *
+     *
+     *
      * @return {FluentFilters}
      */
     moveMouseTo() {
@@ -1644,9 +1852,11 @@ export class FluentCommand extends FluentBase {
      *
      * **Example:**
      * ```typescript
-     * await aui.scroll(0, 10).textarea().exec()
+     * await aui.scrollInside(0,-500).text().withText('Bottom sheet').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/scrollinside.gif)
+     *
      * @param {number} x_offset - A (positive/negative) x direction.
      * @param {number} y_offset - A (positive/negative) y direction.
      *
@@ -1723,12 +1933,14 @@ export class FluentCommand extends FluentBase {
      *
      * **Examples:**
      * ```typescript
-     * await aui.type('Type some text').exec()
+     * await aui.type('askui@askui.com').exec()
      *
      * // mask the text so it is not send to the askui-inference server
      * await aui.type('Type some text', { isSecret: true, secretMask: '**' }).exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/type.gif)
+     *
      * @param {string} text - A text to type
      *
      * @return {Exec}
@@ -1744,9 +1956,11 @@ export class FluentCommand extends FluentBase {
      *
      * **Example:**
      * ```typescript
-     * await aui.moveMouseRelatively(20, 20).exec();
+     * await aui.moveMouseRelatively(0, 50).exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/movemouserelatively.gif)
+     *
      * @param {number} x_offset - A (positive/negative) x direction.
      * @param {number} y_offset - A (positive/negative) y direction.
      *
@@ -1776,6 +1990,8 @@ export class FluentCommand extends FluentBase {
      * await aui.moveMouse(500, 500).exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/moveMouse.gif)
+     *
      * @param {number} x_coordinate - A (positive/negative) x coordinate.
      * @param {number} y_coordinate - A (positive/negative) y coordinate.
      *
@@ -1801,10 +2017,12 @@ export class FluentCommand extends FluentBase {
      *
      * **Example:**
      * ```typescript
-     * // Scroll 10 up in y direction
-     * await aui.scroll(0, 10).exec()
+     * // Scroll 500 pixels down in y direction
+     * await aui.scroll(0, -500).exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/scroll.gif)
+     *
      * @param {number} x_offset - A (positive/negative) x direction.
      * @param {number} y_offset - A (positive/negative) y direction.
      *
@@ -1922,6 +2140,8 @@ export class FluentCommand extends FluentBase {
      * await aui.mouseDoubleLeftClick().exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/mousedoubleleftclick.gif)
+     *
      * @return {Exec}
      */
     mouseDoubleLeftClick() {
@@ -1972,11 +2192,17 @@ export class FluentCommand extends FluentBase {
     /**
      * Toggles mouse down (Left mouse key/tap).
      *
+     *  This is the equivalent to **mouse-left-press-and-hold**. It holds the mouse button until the `mouseToogleUp()` is called. Often combined with `mouseToggleUP` to automate **drag-and-drop**.
+     *
      * **Example:**
      * ```typescript
      * await aui.mouseToggleDown().exec();
+     * await aui.moveMouseRelatively(-400,0).exec();
+     * await aui.mouseToggleUp().exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/mouseToggleDownUp.gif)
+     *
      * @return {Exec}
      */
     mouseToggleDown() {
@@ -1987,11 +2213,17 @@ export class FluentCommand extends FluentBase {
     /**
      * Toggles mouse up (Left mouse key/tap).
      *
+     * This is the equivalent to releasing the pressing mouse left button. Often combined with `mouseToggleDown()` to automate **drag-and-drop**.
+     *
      * **Example:**
      * ```typescript
+     * await aui.mouseToggleDown().exec();
+     * await aui.moveMouseRelatively(-400,0).exec();
      * await aui.mouseToggleUp().exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/mouseToggleDownUp.gif)
+     *
      * @return {Exec}
      */
     mouseToggleUp() {
@@ -2004,8 +2236,13 @@ export class FluentCommand extends FluentBase {
      *
      * **Operating system specific mappings:**
      * 1. Windows: `command`-key maps to `windows`-key
-     * ---
      *
+     * **Examples:**
+     * ```typescript
+     * await aui.pressThreeKeys('control', 'command' 'space').exec();
+     * ```
+     *
+     * ![](https://docs.askui.com/img/gif/pressThreeKeys.gif)
      *
      * @param {MODIFIER_KEY} first_key - A modifier key
      * @param {MODIFIER_KEY} second_key - A modifier key
@@ -2048,8 +2285,13 @@ export class FluentCommand extends FluentBase {
      *
      * **Operating system specific mappings:**
      * 1. Windows: `command`-key maps to `windows`-key
-     * ---
      *
+     * **Examples:**
+     * ```typescript
+     * await aui.pressKey('tab').exec();
+     * ```
+     *
+     * ![](https://docs.askui.com/img/gif/pressKey.gif)
      *
      * @param {PC_AND_MODIFIER_KEY} key - A key
      *
@@ -2082,7 +2324,15 @@ export class FluentCommand extends FluentBase {
         return new Exec(this);
     }
     /**
-     * Press two Android keys like `ALT+F4`
+     * Press two Android keys like `volume_down+power`
+     * See [API docs](https://docs.askui.com/docs/api/Actions/pressandroidtwokey) for available keys.
+     *
+     * **Examples:**
+     * ```typescript
+     * await aui.pressAndroidTwoKey('volume_down', 'power').exec();
+     * ```
+     *
+     * ![](https://docs.askui.com/img/gif/pressAndroidTwoKey.gif)
      *
      * @param {ANDROID_KEY} first_key - A Android key
      * @param {ANDROID_KEY} second_key - A Android key
@@ -2099,7 +2349,15 @@ export class FluentCommand extends FluentBase {
         return new Exec(this);
     }
     /**
-     * Press one Android key like `DEL`
+     * Press one Android key like `del`
+     * See [API docs](https://docs.askui.com/docs/api/Actions/pressandroidtwokey) for available keys.
+     *
+     * **Examples:**
+     * ```typescript
+     * await aui.pressAndroidKey('notification').exec();
+     * ```
+     *
+     * ![](https://docs.askui.com/img/gif/pressAndroidKey.gif)
      *
      * @param {ANDROID_KEY} key - A Android key
      *
@@ -2206,9 +2464,11 @@ export class FluentFiltersGetter extends FluentBase {
      *
      * **Examples:**
      * ```typescript
-     * await aui.moveMouseTo().button().exec()
+     * await aui.click().button().contains().text().withText('Google Search').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/button.gif)
+     *
      * @return {FluentFiltersOrRelationsGetter}
      */
     button() {
@@ -2268,13 +2528,20 @@ export class FluentFiltersGetter extends FluentBase {
     /**
      * Filters for an UI element 'text'.
      *
-     * Often combined with the filter `withText()` as shown in the below examples.
+     * Takes an optional parameter to filter for a specific text.
+     * See the examples below.
+     *
      * See also the filters `withTextRegex()` and `withExactText()`
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().text().withText('Password').exec();
+     * await aui.click().text().exec();
+     * await aui.click().text('Username').exec();
+     *
+     * // Matching with an exact text
      * await aui.click().text().withExactText('Username').exec();
+     *
+     * // Matching with a regex
      * await aui.click().text().withTextRegex('\b[Ss]\w+').exec();
      * ```
      *
@@ -2298,6 +2565,8 @@ export class FluentFiltersGetter extends FluentBase {
      * icon().withText('plus')
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/icon.gif)
+     *
      * **Note:** This is an alpha feature. The prediction of the icon name is sometimes unstable. Use custom elements as an alternative.
      *
      * @return {FluentFiltersOrRelationsGetter}
@@ -2308,7 +2577,9 @@ export class FluentFiltersGetter extends FluentBase {
         return new FluentFiltersOrRelationsGetter(this);
     }
     /**
-     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element that is not recognized by our machine learning models by default. It can also be used for pixel assertions of elements using classical [template matching](https://en.wikipedia.org/wiki/Template_matching).
+     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element based on an image instead of using text or element descriptions like `button().withText('Submit')` in `await aui.click().button().withText('Submit').exec()`.
+     *
+     * See the tutorial - [Custom Element](https://docs.askui.com/docs/general/Tutorials/custom-element) for more detail.
      *
      * **Example**
      * ```typescript
@@ -2318,6 +2589,7 @@ export class FluentFiltersGetter extends FluentBase {
      *         customImage: './logo.png', // required
      *         name: 'myLogo', // optional
      *         threshold: 0.9, // optional, defaults to 0.9
+     *         stopThreshold: 0.9, // optional, defaults to 0.9
      *         rotationDegreePerStep: 0, // optional, defaults to 0
      *         imageCompareFormat: 'grayscale', // optional, defaults to 'grayscale'
      *         // mask:{x:0, y:0}[] // optional, a polygon to match only a certain area of the custom element
@@ -2332,12 +2604,13 @@ export class FluentFiltersGetter extends FluentBase {
      * - **name** (*`string`, optional*):
      *     - A unique name that can be used for filtering for the custom element. If not given, any text inside the custom image will be detected via OCR.
      * - **threshold** (*`number`, optional*):
-     *     - A threshold for how much a UI element needs to be similar to the custom element as defined. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     *     - A threshold for how much a UI element needs to be similar to the custom element as defined by the image. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     * - **stopThreshold** (*`number`, optional*):
+     *     - A threshold for when to stop searching for UI elements similar to the custom element. As soon as UI elements have been found that are at least as similar as the `stopThreshold`, the search is going to stop. After that elements are filtered using the `threshold`. Because of that the `stopThreshold` should be greater than or equal to `threshold`. It is primarily to be used as a speed improvement (by lowering the value). Takes values between `0.0` and `1.0`. Defaults to `0.9`.
      * - **rotationDegreePerStep** (*`number`, optional*):
      *     - Step size in rotation degree. Rotates the custom image by this step size until 360° is exceeded. The range is from `0` to `360`. Defaults to `0`.
-     * - **imageCompareFormat** (*`'RGB' | 'grayscale'`, optional*):
-     *     - The color compare style. 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three color. Defaults to 'grayscale'.
-     * of the given custom image.
+     * - **imageCompareFormat** (*`'RGB' | 'grayscale' | 'edges'`, optional*):
+     *     - The color compare style. 'edges' compares only edges, 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three colors (red, green, blue). Defaults to 'grayscale'.
      *
      *
      * @param {CustomElementJson} customElement - The custom element to filter for.
@@ -2351,6 +2624,23 @@ export class FluentFiltersGetter extends FluentBase {
         this._params.set('customElement', customElement);
         return new FluentFiltersOrRelationsGetter(this);
     }
+    /**
+     * Detects an AI Element created with the workflow creator.
+     *
+     * @param {string} aiElementName - Name of the AI Element.
+     *
+     * @return {FluentFiltersOrRelationsGetter}
+     */
+    aiElement(aiElementName) {
+        this._textStr = '';
+        this._textStr += 'ai';
+        this._textStr += ' element';
+        this._textStr += ' with';
+        this._textStr += ' name';
+        this._textStr += ` ${Separators.STRING}${aiElementName}${Separators.STRING}`;
+        this._params.set('aiElementName', aiElementName);
+        return new FluentFiltersOrRelationsGetter(this);
+    }
     /**
      * Filters for a UI element 'image'.
      *
@@ -2360,10 +2650,14 @@ export class FluentFiltersGetter extends FluentBase {
      * await aui.click().image().exec();
      *
      * // Works if you have an image with
-     * // a caption text below
-     * await aui.click().image().above().text().withText('The caption').exec();
+     * // a text below
+     * await aui.click().image().above().text().withText('Automating WebGL').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/image.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelationsGetter}
      */
     image() {
@@ -2384,6 +2678,10 @@ export class FluentFiltersGetter extends FluentBase {
      * await aui.typeIn('Oh yeah').textfield().below().text().withText('E-Mail Address').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/textfield.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelationsGetter}
      */
     textfield() {
@@ -2392,7 +2690,13 @@ export class FluentFiltersGetter extends FluentBase {
         return new FluentFiltersOrRelationsGetter(this);
     }
     /**
-     * Filters for similar (doesn't need to be a 100% equal) text.
+     * Filters for similar -- meaning >70% similar -- text.
+     *
+     * Takes an optional parameter to specify the similarity. Usually you need the optional parameter for long texts you want to match precisely.
+     *
+     * _We use [RapidFuzz](https://maxbachmann.github.io/RapidFuzz/Usage/fuzz.html#ratio) which calculates the similarity like this:_
+     *
+     * `1 - (distance / (lengthString1 + lengthString2))`
      *
      * **Examples:**
      * ```typescript
@@ -2407,6 +2711,11 @@ export class FluentFiltersGetter extends FluentBase {
      * // usually false
      * 'atebxtc' === withText('text') => false
      * 'other' === withText('text') => false
+     *
+     * // optional parameter: similarity_score
+     * '978-0-201-00650-6' == withText('978-0-201-00') => true with 82.76 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => false with 82.76 < 90 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => true with 93.75 < 90 similarity
      * ```
      * ![](https://docs.askui.com/img/gif/withText.gif)
      *
@@ -2437,6 +2746,10 @@ export class FluentFiltersGetter extends FluentBase {
      * await aui.get().text().withTextRegex('\b[Ss]\w+').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withtextregex.gif)
+     *
+     *
+     *
      * @param {string} regex_pattern - A regex pattern
      *
      * @return {FluentFiltersOrRelationsGetter}
@@ -2465,6 +2778,10 @@ export class FluentFiltersGetter extends FluentBase {
      * await aui.moveMouseTo().text().withExactText('Password').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withexacttext.gif)
+     *
+     *
+     *
      * @param {string} text - A text to be matched.
      *
      * @return {FluentFiltersOrRelationsGetter}
@@ -2501,17 +2818,28 @@ export class FluentFiltersGetter extends FluentBase {
     /**
      * Filters elements based on a textual description.
      *
-     * ## What Should I Write as Matching Text
+     * **What Should I Write as Matching Text**
+     *
      * The text description inside the `matching()` should describe the element visually.
      * It understands color, some famous company/product names, general descriptions.
      *
-     * It sometimes requires a bit of playing to find a matching description:
-     * E.g. `puzzle piece` can fail here while `an icon showing a puzzle piece` might work.
+     * It sometimes requires a bit of playing around to find a matching description:
+     * E.g. `puzzle piece` can fail while `an icon showing a puzzle piece` might work.
      * Generally the more detail the better.
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().matching('a mask on purple background and a firefox logo').exec()
+     * // Select the black sneaker from a bunch of sneakers
+     * await aui.click().element().matching('a black sneaker shoe').exec();
+     *
+     * // Select an image that has text in it
+     * await aui.click().element().matching('has Burger King in it').exec();
+     * await aui.click().element().matching('has adidas in it').exec();
+     *
+     * // Target a logo/image by describing it
+     * await aui.click().element().matching('a mask on purple background and a firefox logo').exec();
+     * await aui.click().element().matching('logo looking like an apple with one bite bitten off').exec();
+     * await aui.click().element().matching('logo looking like a seashell').exec();
      * ```
      *
      * @param {string} text - A description of the target element.
@@ -2669,14 +2997,19 @@ export class FluentFiltersOrRelationsGetter extends FluentFiltersGetter {
     /**
      * Filters for an element right of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl    |  |  rightEl0  |  |  rightEl1  |
+     * --------------  --------------  --------------
      *
-     * // Returns rightEl because rightEl is right of leftEl
+     * // Returns rightEl0 because rightEl0 is the first element right of leftEl
      * ...rightEl().rightOf().leftEl()
+     * ...rightEl().rightOf(0).leftEl()
+     * // Returns rightEl1 because rightEl1 is the second element right of leftEl
+     * ...rightEl().rightOf(1).leftEl()
      * // Returns no element because leftEl is left of rightEl
      * ...leftEl().rightOf().rightEl()
      * ```
@@ -2696,14 +3029,19 @@ export class FluentFiltersOrRelationsGetter extends FluentFiltersGetter {
     /**
      * Filters for an element left of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl1   |  |  leftEl0   |  |  rightEl   |
+     * --------------  --------------  --------------
      *
-     * // Returns leftEl because leftEl is left of rightEl
+     * // Returns leftEl0 because leftEl0 is the first element left of rightEl
      * ...leftEl().leftOf().rightEl()
+     * ...leftEl().leftOf(0).rightEl()
+     * // Returns leftEl1 because leftEl1 is the second element left of rightEl
+     * ...leftEl().leftOf(1).rightEl()
      * // Returns no element because rightEl is left of leftEl
      * ...rightEl().leftOf().leftEl()
      * ```
@@ -2723,17 +3061,25 @@ export class FluentFiltersOrRelationsGetter extends FluentFiltersGetter {
     /**
      * Filters for an element below another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
      * |    text    |
      * --------------
      * --------------
-     * |   button   |
+     * |   button0  |
+     * --------------
+     * --------------
+     * |   button1  |
      * --------------
      *
-     * // Returns button because button is below text
+     * // Returns button0 because button0 is the first button below text
      * ...button().below().text()
+     * ...button().below(0).text()
+     * // Returns button1 because button1  is the second button below text
+     * ...button().below(1).text()
      * // Returns no element because text is above button
      * ...text().below().button()
      * ```
@@ -2752,17 +3098,25 @@ export class FluentFiltersOrRelationsGetter extends FluentFiltersGetter {
     /**
      * Filters for an element above another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
-     * |    text    |
+     * |   text1    |
+     * --------------
+     * --------------
+     * |   text0    |
      * --------------
      * --------------
      * |   button   |
      * --------------
      *
-     * // Returns text because text is above button
+     * // Returns text0 because text0 is the first element above button
      * ...text().above().button()
+     * ...text().above(0).button()
+     * // Returns text1 because text1 is the second element above button
+     * ...text().above(1).button()
      * // Returns no element because button is below text
      * ...button().above().text()
      * ```
@@ -2856,22 +3210,74 @@ export class Getter extends FluentCommand {
      *
      * **Examples:**
      * ```typescript
-     * const text = await aui.get().text().withText('Sign').exec();
+     * const text = await aui.get().text('Sign').exec();
      * console.log(text);
+     *
+     * // Console output
+     * [
+     *   DetectedElement {
+     *     name: 'TEXT',
+     *     text: 'Sign In',
+     *     bndbox: BoundingBox {
+     *       xmin: 1128.2720982142857,
+     *       ymin: 160.21332310267857,
+     *       xmax: 1178.8204241071428,
+     *       ymax: 180.83512834821428
+     *     }
+     *   }
+     * ]
      * ```
-     * ```text
-     *  console output: [
+     *
+     * // *************************************************** //
+     * // Examples on how to work with the returned elements  //
+     * // *************************************************** //
+     * const texts = await aui.get().text().below().textfield().exec();
+     *
+     * // We can get a lot of elements this way
+     * console.log(texts);
+     *
+     * // Console output
+     * [
      *   DetectedElement {
-     *      name: 'TEXT',
-     *      text: 'Sign In',
-     *      bndbox: BoundingBox {
-     *         xmin: 1128.2720982142857,
-     *         ymin: 160.21332310267857,
-     *         xmax: 1178.8204241071428,
-     *         ymax: 180.83512834821428
-     *      }
-     *    }
-     *  ]
+     *     name: 'TEXT',
+     *     text: 'Sign In',
+     *     bndbox: BoundingBox {
+     *       xmin: 1128.2720982142857,
+     *       ymin: 160.21332310267857,
+     *       xmax: 1178.8204241071428,
+     *       ymax: 180.83512834821428
+     *     },
+     *   },
+     *   DetectedElement {
+     *     name: 'TEXT',
+     *     text: 'Login',
+     *     bndbox: BoundingBox {
+     *       xmin: 250.8204241071428,
+     *       ymin: 300.21332310267857,
+     *       xmax: 450.6304241071428,
+     *       ymax: 950.47812834821428
+     *     },
+     *   },
+     *   ... 10 more items
+     * ]
+     *
+     * // Extract the FIRST element
+     * // Arrays start with index 0!
+     * const firstTextElement = texts[0];
+     * const textOfFirstElement = firstElement.text;
+     *
+     * console.log(textOfFirstElement);
+     *
+     * // Console output
+     * Sign In
+     *
+     * // Log the text of the SECOND element
+     * // with shorter code
+     * const texts = await aui.get().text().below().textfield().exec();
+     * console.log(texts[1].text)
+     *
+     * // Console output
+     * Login
      * ```
      *
      * @return {FluentFiltersGetter}