donobu 2.15.0 → 2.16.0

package/dist/managers/InteractionVisualizer.d.ts

@@ -1,28 +1,25 @@
 import { Page, Locator } from 'playwright';
 /**
  * Class for visualizing interactions in a webpage with a virtual mouse and messages.
- *
- * This class assumes that the /donobu.css route exists and defines the
- * `.donobu-message` and `.donobu-virtual-mouse` CSS classes (e.g. being served up by
- * a virtual route registered with the browser context).
  */
 export declare class InteractionVisualizer {
     readonly defaultMessageDurationMillis: number;
+    private static readonly VIRTUAL_MOUSE_SVG;
+    private static readonly CSS;
     private static readonly MESSAGE_CONTAINER_ID;
     private static readonly VIRTUAL_MOUSE_ID;
+    private static readonly registeredContexts;
     private currentMousePosition;
-    private isMouseVisible;
     /**
      * Creates an instance of InteractionVisualizer.
      * @param defaultMessageDurationMillis - Default duration for displaying messages in milliseconds.
      */
     constructor(defaultMessageDurationMillis: number);
     /**
-     * Show the given message text visually adjacent to the given element for the given duration.
-     * Moves the virtual mouse to the element with a smooth animation.
-     * Blocks execution for the duration.
+     * Moves the virtual mouse to the element with a smooth animation and
+     * optionally displays a message at element.
      */
-    pointAt(page: Page, element: Locator, message: string, durationMillis?: number): Promise<void>;
+    pointAt(page: Page, element: Locator, message?: string, durationMillis?: number): Promise<void>;
     /**
      * Moves the virtual mouse to the target position with a smooth animation.
      */
@@ -32,12 +29,9 @@ export declare class InteractionVisualizer {
      */
     private displayMessageNearElement;
     /**
-     * Hide the virtual mouse.
+     * Ensures routes are registered for the given browser context.
+     * @param browserContext - The browser context to register routes on.
      */
-    hideVirtualMouse(page: Page): Promise<void>;
-    /**
-     * Clean up all messages and the virtual mouse.
-     */
-    cleanUp(page: Page): Promise<void>;
+    private static ensureRoutesRegistered;
 }
 //# sourceMappingURL=InteractionVisualizer.d.ts.map

package/dist/managers/InteractionVisualizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InteractionVisualizer.d.ts","sourceRoot":"","sources":["../../src/managers/InteractionVisualizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAI3C;;;;;;GAMG;AACH,qBAAa,qBAAqB;aAWG,4BAA4B,EAAE,MAAM;IAVvE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CACR;IACpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IAC3D,OAAO,CAAC,oBAAoB,CAAkB;IAC9C,OAAO,CAAC,cAAc,CAAS;IAE/B;;;OAGG;gBACgC,4BAA4B,EAAE,MAAM;IAEvE;;;;OAIG;IACU,OAAO,CAClB,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,MAA0C,GACzD,OAAO,CAAC,IAAI,CAAC;IA4DhB;;OAEG;YACW,gBAAgB;IA8F9B;;OAEG;YACW,yBAAyB;IAgDvC;;OAEG;IACU,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBxD;;OAEG;IACU,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAahD"}
+{"version":3,"file":"InteractionVisualizer.d.ts","sourceRoot":"","sources":["../../src/managers/InteractionVisualizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,OAAO,EAAkB,MAAM,YAAY,CAAC;AAK3D;;GAEG;AACH,qBAAa,qBAAqB;aAeG,4BAA4B,EAAE,MAAM;IAdvE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAEvC;IACF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAmD;IAC9E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CACR;IACpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IAC3D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAiC;IAC3E,OAAO,CAAC,oBAAoB,CAAkB;IAE9C;;;OAGG;gBACgC,4BAA4B,EAAE,MAAM;IAEvE;;;OAGG;IACU,OAAO,CAClB,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,cAAc,GAAE,MAA0C,GACzD,OAAO,CAAC,IAAI,CAAC;IA4DhB;;OAEG;YACW,gBAAgB;IA8F9B;;OAEG;YACW,yBAAyB;IAgDvC;;;OAGG;mBACkB,sBAAsB;CAkC5C"}

package/dist/managers/InteractionVisualizer.js

@@ -3,12 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.InteractionVisualizer = void 0;
 const Logger_1 = require("../utils/Logger");
 const PlaywrightUtils_1 = require("../utils/PlaywrightUtils");
+const MiscUtils_1 = require("../utils/MiscUtils");
 /**
  * Class for visualizing interactions in a webpage with a virtual mouse and messages.
- *
- * This class assumes that the /donobu.css route exists and defines the
- * `.donobu-message` and `.donobu-virtual-mouse` CSS classes (e.g. being served up by
- * a virtual route registered with the browser context).
  */
 class InteractionVisualizer {
     /**
@@ -18,17 +15,16 @@ class InteractionVisualizer {
     constructor(defaultMessageDurationMillis) {
         this.defaultMessageDurationMillis = defaultMessageDurationMillis;
         this.currentMousePosition = { x: 0, y: 0 };
-        this.isMouseVisible = false;
     }
     /**
-     * Show the given message text visually adjacent to the given element for the given duration.
-     * Moves the virtual mouse to the element with a smooth animation.
-     * Blocks execution for the duration.
+     * Moves the virtual mouse to the element with a smooth animation and
+     * optionally displays a message at element.
      */
     async pointAt(page, element, message, durationMillis = this.defaultMessageDurationMillis) {
-        if (!message.trim() || !durationMillis || durationMillis <= 0) {
+        if (!durationMillis || durationMillis <= 0) {
             return;
         }
+        await InteractionVisualizer.ensureRoutesRegistered(page.context());
         try {
             // Get element position for mouse movement
             const boundingBox = await element.boundingBox();
@@ -39,14 +35,17 @@ class InteractionVisualizer {
             // Calculate target position (center of the element)
             const targetX = boundingBox.x + boundingBox.width / 2;
             const targetY = boundingBox.y + boundingBox.height / 2;
+            const promises = [];
             // Start mouse movement and message display in parallel
-            const mouseMovementPromise = this.moveVirtualMouse(page, targetX, targetY, durationMillis / 2);
-            // Display the message for the element
-            await this.displayMessageNearElement(element, message);
-            // Create a promise for the message duration
-            const messageDurationPromise = page.waitForTimeout(durationMillis);
+            promises.push(this.moveVirtualMouse(page, targetX, targetY, durationMillis / 2));
+            if (message && !message.trim()) {
+                // Display the message for the element
+                await this.displayMessageNearElement(element, message);
+                // Create a promise for the message duration
+                promises.push(page.waitForTimeout(durationMillis));
+            }
             // Wait for both mouse movement and message duration to complete
-            await Promise.all([mouseMovementPromise, messageDurationPromise]);
+            await Promise.all(promises);
             // Remove only the message after the duration (keep the mouse)
             await element.evaluate((_, [messageContainerId]) => {
                 const container = document.getElementById(messageContainerId);
@@ -73,6 +72,7 @@ class InteractionVisualizer {
      * Moves the virtual mouse to the target position with a smooth animation.
      */
     async moveVirtualMouse(page, targetX, targetY, durationMillis) {
+        await InteractionVisualizer.ensureRoutesRegistered(page.context());
         await page.evaluate(([containerId, mouseId, startX, startY, endX, endY, duration]) => {
             return new Promise((resolve) => {
                 // 1) Find or create the container
@@ -144,7 +144,6 @@ class InteractionVisualizer {
         ]);
         // Update current mouse position
         this.currentMousePosition = { x: targetX, y: targetY };
-        this.isMouseVisible = true;
     }
     /**
      * Creates a message adjacent to the element, inside a shadow root to avoid CSS collisions.
@@ -184,40 +183,41 @@ class InteractionVisualizer {
         }, [InteractionVisualizer.MESSAGE_CONTAINER_ID, message]);
     }
     /**
-     * Hide the virtual mouse.
+     * Ensures routes are registered for the given browser context.
+     * @param browserContext - The browser context to register routes on.
      */
-    async hideVirtualMouse(page) {
-        if (!this.isMouseVisible) {
+    static async ensureRoutesRegistered(browserContext) {
+        if (this.registeredContexts.has(browserContext)) {
             return;
         }
-        await page.evaluate(([containerId, mouseId]) => {
-            const container = document.getElementById(containerId);
-            if (container && container.shadowRoot) {
-                const mouse = container.shadowRoot.getElementById(mouseId);
-                if (mouse) {
-                    mouse.remove();
-                }
-            }
-        }, [
-            InteractionVisualizer.MESSAGE_CONTAINER_ID,
-            InteractionVisualizer.VIRTUAL_MOUSE_ID,
-        ]);
-        this.isMouseVisible = false;
-    }
-    /**
-     * Clean up all messages and the virtual mouse.
-     */
-    async cleanUp(page) {
-        await page.evaluate(([containerId]) => {
-            const container = document.getElementById(containerId);
-            if (container) {
-                container.remove();
-            }
-        }, [InteractionVisualizer.MESSAGE_CONTAINER_ID]);
-        this.isMouseVisible = false;
+        try {
+            await browserContext.route('**/donobu-virtual-mouse.svg', async (route) => {
+                await route.fulfill({
+                    status: 200,
+                    contentType: 'image/svg+xml',
+                    body: InteractionVisualizer.VIRTUAL_MOUSE_SVG,
+                });
+            });
+            await browserContext.route('**/donobu.css', async (route) => {
+                await route.fulfill({
+                    status: 200,
+                    contentType: 'text/css',
+                    body: InteractionVisualizer.CSS,
+                });
+            });
+            this.registeredContexts.add(browserContext);
+            Logger_1.appLogger.debug('Routes registered for InteractionVisualizer');
+        }
+        catch (e) {
+            Logger_1.appLogger.error('Failed to register routes for InteractionVisualizer', e);
+            throw e;
+        }
     }
 }
 exports.InteractionVisualizer = InteractionVisualizer;
+InteractionVisualizer.VIRTUAL_MOUSE_SVG = MiscUtils_1.MiscUtils.getResourceFileAsString('donobu-virtual-mouse.svg');
+InteractionVisualizer.CSS = MiscUtils_1.MiscUtils.getResourceFileAsString('donobu.css');
 InteractionVisualizer.MESSAGE_CONTAINER_ID = 'donobu-message-shadow-container';
 InteractionVisualizer.VIRTUAL_MOUSE_ID = 'virtual-mouse';
+InteractionVisualizer.registeredContexts = new WeakSet();
 //# sourceMappingURL=InteractionVisualizer.js.map

package/dist/managers/InteractionVisualizer.js.map

@@ -1 +1 @@
-{"version":3,"file":"InteractionVisualizer.js","sourceRoot":"","sources":["../../src/managers/InteractionVisualizer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"InteractionVisualizer.js","sourceRoot":"","sources":["../../src/managers/InteractionVisualizer.ts"],"names":[],"mappings":"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"}

package/dist/managers/PageInspector.d.ts

@@ -0,0 +1,242 @@
+import { Page } from 'playwright';
+import { InteractableElement } from '../models/InteractableElement';
+/**
+ * A class for identifying, attributing, and annotating interactable elements on web pages.
+ *
+ * The PageInspector provides functionality to:
+ * - Find and attribute interactable elements with unique identifiers
+ * - Retrieve information about attributed elements
+ * - Add visual annotations (numbered indicators) to interactable elements
+ * - Clean up both attributes and annotations
+ *
+ * Interactable elements are determined using comprehensive heuristics including:
+ * - Standard HTML interactive elements (buttons, inputs, links, etc.)
+ * - Elements with ARIA roles indicating interactivity
+ * - Elements with event handlers or CSS classes suggesting interactivity
+ * - Elements that are visible, enabled, and accessible at their coordinates
+ *
+ * This class is designed to work with Playwright's Page and Frame objects
+ * and handles cross-frame navigation, shadow DOM, and various edge cases.
+ *
+ * WARNING: It is REQUIRED that the {@link PageInspector.INIT_SCRIPT} has been
+ *          run in the browser context before calling this class's methods.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * await browserContext.addInitScript(PageInspector.INIT_SCRIPT);
+ * const inspector = new PageInspector();
+ *
+ * const page = await browserContext.newPage();
+ * await page.goto("https://google.com");
+ *
+ * // Find and attribute interactable elements
+ * await inspector.attributeInteractableElements(page);
+ *
+ * // Get information about interactable elements
+ * const elements = await inspector.getAttributedInteractableElements(page);
+ *
+ * // Add visual annotations to the page
+ * await inspector.annotateInteractableElements(page);
+ *
+ * // Clean up when done
+ * await inspector.removeDonobuAnnotations(page);
+ * await inspector.deattributeVisibleInteractableElements(page);
+ * ```
+ *
+ * @remarks
+ * This class uses custom HTML attributes (`data-donobu-interactable` by default)
+ * to mark elements, and creates a shadow DOM container for annotations to avoid
+ * style conflicts with the target page.
+ *
+ * All methods will throw a {@link PageClosedException} if the page is closed
+ * during operation.
+ */
+export declare class PageInspector {
+    readonly interactableElementAttribute: string;
+    readonly interactableAnnotationAttribute: string;
+    /**
+     * A JavaScript code snippet intended to run as an initialization
+     * script for `DonobuFlow` flows. This script helps other scripts to know
+     * non-traditional interactive elements via calling the
+     * {@link window.__donobu.getInteractiveElements} function.
+     */
+    static readonly INIT_SCRIPT: string;
+    constructor(interactableElementAttribute?: string, interactableAnnotationAttribute?: string);
+    /**
+     * Assigns a globally unique attribute to all visible and interactable elements in the page.
+     *
+     * This method performs the following steps:
+     * 1. Removes any pre-existing interactable element attributes from the page
+     * 2. Assigns sequential numeric values as attributes to interactable elements in the main frame
+     * 3. Processes child frames that are visible in the viewport and assigns attributes to their interactable elements
+     *
+     * The method identifies "interactable" elements based on tag names, ARIA roles, CSS classes, and other heuristics.
+     * Only elements that are:
+     * - Visible (non-zero dimensions and not hidden via CSS)
+     * - More than 50% in the viewport
+     * - Not disabled or inert
+     * - Actually reachable at their coordinates (topmost in z-index)
+     * will receive the attribute.
+     *
+     * @param page - The Playwright Page object to process
+     * @throws {PageClosedException} If the page is closed during processing
+     * @returns {Promise<void>} A promise that resolves when all elements have been attributed
+     */
+    attributeInteractableElements(page: Page): Promise<void>;
+    /**
+     * Retrieves all elements that have been previously attributed with the interactable element attribute.
+     *
+     * This method:
+     * 1. Searches all frames in the page (including the main frame and child frames)
+     * 2. Collects elements with the {@link interactableElementAttribute} attribute
+     * 3. Creates an {@link InteractableElement} object for each attributed element
+     *
+     * For each interactable element, it extracts:
+     * - The attribute value (serving as a unique identifier)
+     * - A simplified HTML snippet representation of the element
+     *   * For 'select' elements, the complete HTML (including options) is preserved
+     *   * For all other elements, only the opening tag without children is captured
+     *
+     * Note: This method only finds elements that have been previously attributed using
+     * the {@link attributeInteractableElements} method.
+     *
+     * @param page - The Playwright Page object to process
+     * @returns {Promise<InteractableElement[]>} A promise that resolves to an array of
+     *         interactable elements with their attribute values and HTML snippets
+     * @throws {PageClosedException} If the page is closed during processing
+     *
+     * @example
+     * const inspector = new PageInspector();
+     * await inspector.attributeInteractableElements(page);
+     * const elements = await inspector.getAttributedInteractableElements(page);
+     * // elements = [{ donobuAttributeValue: "0", htmlSnippet: "<button id=\"submit\">"}]
+     */
+    getAttributedInteractableElements(page: Page): Promise<InteractableElement[]>;
+    /**
+     * Visually annotates all interactable elements with numbered indicators on the page.
+     *
+     * This method:
+     * 1. Processes all accessible frames in the page
+     * 2. Creates (or reuses) a shadow DOM container to isolate annotation styling
+     * 3. Places circular numbered indicators over each element that has the
+     *    {@link interactableElementAttribute} attribute
+     *
+     * The annotations:
+     * - Are positioned at the center of each interactable element
+     * - Have the same numeric value as the element's attribute
+     * - Are styled as black circles with red borders and white text
+     * - Are placed in a shadow DOM to avoid style conflicts with the page
+     * - Have the {@link interactableAnnotationAttribute} for identification
+     * - Are non-interactive (pointer-events: none)
+     *
+     * Note: This method requires elements to be previously attributed using the
+     * {@link attributeInteractableElements} method to find the elements to annotate.
+     *
+     * @param page - The Playwright Page object to process
+     * @returns {Promise<void>} A promise that resolves when all elements have been annotated
+     * @throws {PageClosedException} If the page is closed during processing
+     *
+     * @example
+     * const inspector = new PageInspector();
+     * await inspector.attributeInteractableElements(page);
+     * await inspector.annotateInteractableElements(page);
+     * // Visible numbered annotations now appear over all interactable elements
+     */
+    annotateInteractableElements(page: Page): Promise<void>;
+    /**
+     * Removes all visual annotations from the page that were created by
+     * the {@link annotateInteractableElements} method.
+     *
+     * This method:
+     * 1. Processes all accessible frames in the page
+     * 2. Finds and removes the shadow DOM container with ID 'annotation-shadow-container'
+     *    that contains all the annotations
+     *
+     * This effectively removes all numbered indicators that were previously placed
+     * over interactable elements, leaving the page in its original visual state.
+     * Note that this only removes the visual annotations, not the
+     * {@link interactableElementAttribute} attributes on the elements themselves.
+     *
+     * @param page - The Playwright Page object to process
+     * @returns {Promise<void>} A promise that resolves when all annotations have been removed
+     * @throws {PageClosedException} If the page is closed during processing
+     *
+     * @example
+     * const inspector = new PageInspector();
+     * await inspector.attributeInteractableElements(page);
+     * await inspector.annotateInteractableElements(page);
+     * // ... do some operations with the annotations visible ...
+     * await inspector.removeDonobuAnnotations(page);
+     * // All visual annotations are now removed from the page
+     */
+    removeDonobuAnnotations(page: Page): Promise<void>;
+    /**
+     * Removes all interactable element attributes that were previously added to elements in the page.
+     *
+     * This method:
+     * 1. Processes all accessible frames in the page
+     * 2. Finds all elements with the {@link interactableElementAttribute} attribute
+     * 3. Removes this attribute from each element
+     *
+     * This effectively undoes the changes made by the {@link attributeInteractableElements} method,
+     * returning the page's DOM to its original state without the custom attributes.
+     * Note that this does not affect any visual annotations - to remove those, use
+     * the {@link removeDonobuAnnotations} method separately.
+     *
+     * This method is automatically called at the beginning of {@link attributeInteractableElements}
+     * to ensure a clean state before adding new attributes, but can also be called
+     * independently to clean up the DOM.
+     *
+     * @param page - The Playwright Page object to process
+     * @returns {Promise<void>} A promise that resolves when all attributes have been removed
+     * @throws {PageClosedException} If the page is closed during processing
+     *
+     * @example
+     * const inspector = new PageInspector();
+     * await inspector.attributeInteractableElements(page);
+     * // ... perform operations with attributed elements ...
+     * await inspector.deattributeInteractableElements(page);
+     * // All interactable element attributes are now removed from the page
+     */
+    deattributeInteractableElements(page: Page): Promise<void>;
+    /**
+     * Converts an HTML attribute to a JavaScript attribute. For example,
+     * "data-foo-bar" is turned into "fooBar". Notice the dropping of the "data-"
+     * prefix, and the conversion from kebab-case to camelCase.
+     */
+    static convertToJsAttribute(htmlAttribute: string): string;
+    /**
+     * An internal method that is injected into page/frame contexts to find and attribute interactable elements.
+     *
+     * This method:
+     * 1. Identifies potentially interactable elements using a comprehensive selector
+     * 2. Filters elements based on visibility, position in viewport, and interactability
+     * 3. Assigns unique sequential numeric values to the interactable attribute
+     *
+     * The method uses several criteria to determine if an element is truly interactable:
+     * - Element must be visible (non-zero dimensions, not hidden via CSS)
+     * - Element must have at least 50% of its area within the viewport
+     * - Element must not be disabled, inert, or have pointer-events:none
+     * - Element must be the topmost element at its coordinates (using point sampling)
+     *
+     * Special handling is provided for label elements, which will attribute their
+     * associated form controls as well.
+     *
+     * This method can process both standard DOM elements and elements within shadow roots,
+     * ensuring thorough coverage of modern web applications.
+     *
+     * @param arg - A tuple containing [offset: number, interactableAttribute: string]
+     *              where offset is the starting value for sequential numbering and
+     *              interactableAttribute is the attribute name to assign
+     * @returns The updated offset after assigning attributes (for sequential numbering across frames)
+     * @private
+     *
+     * @remarks
+     * This method is designed to be injected into the page context using page.evaluate()
+     * and should not be called directly from Node.js code.
+     */
+    private static attributeElementsInContext;
+    private static frameFilter;
+}
+//# sourceMappingURL=PageInspector.d.ts.map

package/dist/managers/PageInspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PageInspector.d.ts","sourceRoot":"","sources":["../../src/managers/PageInspector.ts"],"names":[],"mappings":"AACA,OAAO,EAAS,IAAI,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAMpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,aAAa;aAYN,4BAA4B,EAAE,MAAM;aACpC,+BAA+B,EAAE,MAAM;IAZzD;;;;;OAKG;IACH,gBAAuB,WAAW,SAEhC;gBAGgB,4BAA4B,GAAE,MAAmC,EACjE,+BAA+B,GAAE,MAAiC;IAGpF;;;;;;;;;;;;;;;;;;;OAmBG;IACU,6BAA6B,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAoErE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACU,iCAAiC,CAC5C,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,mBAAmB,EAAE,CAAC;IA4DjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACU,4BAA4B,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAmJpE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB/D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACU,+BAA+B,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBvE;;;;OAIG;WACW,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM;IAkBjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,OAAO,CAAC,MAAM,CAAC,0BAA0B;IAgVzC,OAAO,CAAC,MAAM,CAAC,WAAW;CAQ3B"}