@weave-apps/sdk 0.9.0 → 0.11.0

package/dist/app-sdk/src/WeaveDOMAPI.js

@@ -0,0 +1,774 @@
+/**
+ * Weave DOM API
+ *
+ * Client-side API for iframe apps to interact with the parent page DOM
+ * through the secure DOM Bridge in the content script.
+ */
+/**
+ * DOM operation types (must match content script)
+ */
+var DOMOperation;
+(function (DOMOperation) {
+    // Read operations
+    DOMOperation["QUERY"] = "QUERY";
+    DOMOperation["QUERY_ALL"] = "QUERY_ALL";
+    DOMOperation["GET_TEXT"] = "GET_TEXT";
+    DOMOperation["GET_ATTRIBUTE"] = "GET_ATTRIBUTE";
+    DOMOperation["GET_VALUE"] = "GET_VALUE";
+    DOMOperation["IS_CHECKED"] = "IS_CHECKED";
+    DOMOperation["HAS_CLASS"] = "HAS_CLASS";
+    DOMOperation["GET_PAGE_URL"] = "GET_PAGE_URL";
+    // Write operations
+    DOMOperation["SET_TEXT"] = "SET_TEXT";
+    DOMOperation["SET_ATTRIBUTE"] = "SET_ATTRIBUTE";
+    DOMOperation["SET_VALUE"] = "SET_VALUE";
+    DOMOperation["ADD_CLASS"] = "ADD_CLASS";
+    DOMOperation["REMOVE_CLASS"] = "REMOVE_CLASS";
+    DOMOperation["TOGGLE_CLASS"] = "TOGGLE_CLASS";
+    DOMOperation["SET_STYLE"] = "SET_STYLE";
+    // DOM manipulation
+    DOMOperation["INSERT_HTML"] = "INSERT_HTML";
+    DOMOperation["REMOVE_ELEMENT"] = "REMOVE_ELEMENT";
+    // Element injection with event listeners
+    DOMOperation["INJECT_ELEMENT"] = "INJECT_ELEMENT";
+    DOMOperation["REMOVE_INJECTED_ELEMENT"] = "REMOVE_INJECTED_ELEMENT";
+    // Form operations
+    DOMOperation["GET_FORM_DATA"] = "GET_FORM_DATA";
+    DOMOperation["START_FORM_CLICK_LISTENER"] = "START_FORM_CLICK_LISTENER";
+    DOMOperation["STOP_FORM_CLICK_LISTENER"] = "STOP_FORM_CLICK_LISTENER";
+    DOMOperation["SET_FORM_FIELD_VALUE"] = "SET_FORM_FIELD_VALUE";
+    // Element click listener operations
+    DOMOperation["START_ELEMENT_CLICK_LISTENER"] = "START_ELEMENT_CLICK_LISTENER";
+    DOMOperation["STOP_ELEMENT_CLICK_LISTENER"] = "STOP_ELEMENT_CLICK_LISTENER";
+    // Element hover listener operations
+    DOMOperation["START_ELEMENT_HOVER_LISTENER"] = "START_ELEMENT_HOVER_LISTENER";
+    DOMOperation["STOP_ELEMENT_HOVER_LISTENER"] = "STOP_ELEMENT_HOVER_LISTENER";
+    // Click operation
+    DOMOperation["CLICK_ELEMENT"] = "CLICK_ELEMENT";
+    // Element watching operations
+    DOMOperation["WATCH_ELEMENT"] = "WATCH_ELEMENT";
+    DOMOperation["UNWATCH_ELEMENT"] = "UNWATCH_ELEMENT";
+    // Navigation operations
+    DOMOperation["RELOAD_PAGE"] = "RELOAD_PAGE";
+    // Scroll operations
+    DOMOperation["SCROLL_INTO_VIEW"] = "SCROLL_INTO_VIEW";
+    // Dialog operations
+    DOMOperation["SHOW_ALERT"] = "SHOW_ALERT";
+    DOMOperation["SHOW_CONFIRM"] = "SHOW_CONFIRM";
+})(DOMOperation || (DOMOperation = {}));
+/**
+ * Weave DOM API
+ * Provides methods for iframe apps to interact with parent page DOM
+ */
+export class WeaveDOMAPI {
+    constructor() {
+        this.pendingRequests = new Map();
+        this.messageListener = null;
+        this.requestCounter = 0;
+        this.timeout = 5000; // 5 second timeout
+        this.formClickCallback = null;
+        this.workflowSavedCallback = null;
+        this.triggerSavedCallback = null;
+        this.elementClickCallbacks = new Map();
+        this.elementSelectorClickCallbacks = new Map();
+        this.elementSelectorHoverCallbacks = new Map();
+        this.elementChangeCallbacks = new Map();
+        this.elementIdCounter = 0;
+        this.watcherIdCounter = 0;
+        this.initialize();
+    }
+    /**
+     * Initialize the API and start listening for responses
+     */
+    initialize() {
+        this.messageListener = (event) => {
+            this.handleResponse(event);
+        };
+        window.addEventListener('message', this.messageListener);
+    }
+    /**
+     * Cleanup
+     */
+    destroy() {
+        if (this.messageListener) {
+            window.removeEventListener('message', this.messageListener);
+            this.messageListener = null;
+        }
+        this.pendingRequests.clear();
+    }
+    /**
+     * Handle response from content script
+     */
+    handleResponse(event) {
+        const data = event.data;
+        // Only accept messages from parent (content script)
+        if (event.source !== window.parent) {
+            return;
+        }
+        // Handle form click events
+        if (data?.type === 'WEAVE_FORM_CLICKED') {
+            if (this.formClickCallback) {
+                this.formClickCallback({
+                    formData: data.formData,
+                    clickedElement: data.clickedElement,
+                });
+            }
+            return;
+        }
+        // Handle workflow saved events
+        if (data?.type === 'WORKFLOW_SAVED') {
+            if (this.workflowSavedCallback) {
+                this.workflowSavedCallback(data.payload);
+            }
+            return;
+        }
+        // Handle trigger saved events
+        if (data?.type === 'TRIGGER_SAVED') {
+            if (this.triggerSavedCallback) {
+                this.triggerSavedCallback(data.payload);
+            }
+            return;
+        }
+        // Handle element click events (for injected elements)
+        if (data?.type === 'WEAVE_ELEMENT_CLICKED') {
+            const callback = this.elementClickCallbacks.get(data.elementId);
+            if (callback) {
+                callback({
+                    elementId: data.elementId,
+                    event: data.event,
+                });
+            }
+            return;
+        }
+        // Handle element selector click events (for element click listeners)
+        if (data?.type === 'WEAVE_ELEMENT_SELECTOR_CLICKED') {
+            const callback = this.elementSelectorClickCallbacks.get(data.listenerId);
+            if (callback) {
+                callback({
+                    element: data.element,
+                    event: data.event,
+                });
+            }
+            return;
+        }
+        // Handle element selector hover events (for element hover listeners)
+        if (data?.type === 'WEAVE_ELEMENT_SELECTOR_HOVERED') {
+            const callback = this.elementSelectorHoverCallbacks.get(data.listenerId);
+            if (callback) {
+                callback({
+                    element: data.element,
+                    event: data.event,
+                });
+            }
+            return;
+        }
+        // Handle element change events (for element watchers)
+        if (data?.type === 'WEAVE_ELEMENT_CHANGED') {
+            const callback = this.elementChangeCallbacks.get(data.watcherId);
+            if (callback) {
+                callback({
+                    changeType: data.changeType,
+                    element: data.element,
+                    attributeName: data.attributeName,
+                    attributeValue: data.attributeValue,
+                });
+            }
+            return;
+        }
+        // Handle normal DOM operation responses
+        if (data?.type !== 'WEAVE_DOM_RESPONSE') {
+            return;
+        }
+        const response = data;
+        const pending = this.pendingRequests.get(response.id);
+        if (!pending) {
+            return;
+        }
+        this.pendingRequests.delete(response.id);
+        if (response.success) {
+            pending.resolve(response.data);
+        }
+        else {
+            pending.reject(new Error(response.error || 'Unknown error'));
+        }
+    }
+    /**
+     * Send request to content script
+     */
+    sendRequest(operation, payload) {
+        return new Promise((resolve, reject) => {
+            const id = `dom-request-${++this.requestCounter}`;
+            const request = {
+                type: 'WEAVE_DOM_REQUEST',
+                id,
+                operation,
+                payload,
+            };
+            // Store pending request
+            this.pendingRequests.set(id, { resolve, reject });
+            // Set timeout
+            const timeoutId = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Request timeout: ${operation}`));
+            }, this.timeout);
+            // Clear timeout on resolve/reject
+            const originalResolve = resolve;
+            const originalReject = reject;
+            this.pendingRequests.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timeoutId);
+                    originalResolve(value);
+                },
+                reject: (error) => {
+                    clearTimeout(timeoutId);
+                    originalReject(error);
+                },
+            });
+            // Send to parent window (content script will intercept)
+            window.parent.postMessage(request, '*');
+        });
+    }
+    // ============================================================================
+    // Read Operations
+    // ============================================================================
+    /**
+     * Query a single element from parent page
+     */
+    async query(selector) {
+        return this.sendRequest(DOMOperation.QUERY, { selector });
+    }
+    /**
+     * Query all matching elements from parent page
+     */
+    async queryAll(selector) {
+        return this.sendRequest(DOMOperation.QUERY_ALL, { selector });
+    }
+    /**
+     * Get text content of an element
+     */
+    async getText(selector) {
+        return this.sendRequest(DOMOperation.GET_TEXT, { selector });
+    }
+    /**
+     * Get attribute value of an element
+     */
+    async getAttribute(selector, attribute) {
+        return this.sendRequest(DOMOperation.GET_ATTRIBUTE, {
+            selector,
+            attribute
+        });
+    }
+    /**
+     * Get value of an input element
+     */
+    async getValue(selector) {
+        return this.sendRequest(DOMOperation.GET_VALUE, { selector });
+    }
+    /**
+     * Check if a checkbox or radio button is checked
+     * @param selector - CSS selector for the checkbox/radio element
+     * @returns Promise with true if checked, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const isChecked = await weaveDOM.isChecked('#my-checkbox');
+     * if (isChecked) {
+     *   console.log('Checkbox is checked');
+     * }
+     * ```
+     */
+    async isChecked(selector) {
+        return this.sendRequest(DOMOperation.IS_CHECKED, { selector });
+    }
+    /**
+     * Check if element has a class
+     */
+    async hasClass(selector, className) {
+        return this.sendRequest(DOMOperation.HAS_CLASS, {
+            selector,
+            className
+        });
+    }
+    /**
+     * Get the current page URL
+     * Returns the parent page URL (not the iframe URL)
+     * @returns Promise with the current page URL
+     */
+    async getPageUrl() {
+        return this.sendRequest(DOMOperation.GET_PAGE_URL, {});
+    }
+    /**
+     * Reload the current page
+     * Triggers a full page reload of the parent page
+     */
+    async reloadPage() {
+        return this.sendRequest(DOMOperation.RELOAD_PAGE, {});
+    }
+    // ============================================================================
+    // Write Operations
+    // ============================================================================
+    /**
+     * Set text content of an element
+     */
+    async setText(selector, text) {
+        return this.sendRequest(DOMOperation.SET_TEXT, { selector, text });
+    }
+    /**
+     * Set attribute value of an element
+     */
+    async setAttribute(selector, attribute, value) {
+        return this.sendRequest(DOMOperation.SET_ATTRIBUTE, {
+            selector,
+            attribute,
+            value
+        });
+    }
+    /**
+     * Set value of an input element
+     */
+    async setValue(selector, value) {
+        return this.sendRequest(DOMOperation.SET_VALUE, { selector, value });
+    }
+    /**
+     * Add a class to an element
+     */
+    async addClass(selector, className) {
+        return this.sendRequest(DOMOperation.ADD_CLASS, { selector, className });
+    }
+    /**
+     * Remove a class from an element
+     */
+    async removeClass(selector, className) {
+        return this.sendRequest(DOMOperation.REMOVE_CLASS, { selector, className });
+    }
+    /**
+     * Toggle a class on an element
+     */
+    async toggleClass(selector, className) {
+        return this.sendRequest(DOMOperation.TOGGLE_CLASS, { selector, className });
+    }
+    /**
+     * Set a CSS style property on an element
+     */
+    async setStyle(selector, property, value) {
+        return this.sendRequest(DOMOperation.SET_STYLE, {
+            selector,
+            property,
+            value
+        });
+    }
+    /**
+     * Insert HTML relative to an element
+     */
+    async insertHTML(selector, position, html) {
+        return this.sendRequest(DOMOperation.INSERT_HTML, {
+            selector,
+            position,
+            html
+        });
+    }
+    /**
+     * Remove an element from the DOM
+     */
+    async removeElement(selector) {
+        return this.sendRequest(DOMOperation.REMOVE_ELEMENT, { selector });
+    }
+    /**
+     * Click an element on the parent page
+     *
+     * @param selector - CSS selector for the element to click
+     * @returns Promise that resolves when the click is complete
+     *
+     * @example
+     * // Click a button
+     * await weaveDOM.clickElement('button#submit');
+     *
+     * // Click a link
+     * await weaveDOM.clickElement('a.nav-item[href="/dashboard"]');
+     */
+    async clickElement(selector) {
+        return this.sendRequest(DOMOperation.CLICK_ELEMENT, { selector });
+    }
+    // ============================================================================
+    // Form Operations
+    // ============================================================================
+    /**
+     * Get form data from a form or an element inside a form
+     * @param selector - CSS selector for the form or an element inside the form
+     * @returns Promise with complete form data including all fields
+     */
+    async getFormData(selector) {
+        return this.sendRequest(DOMOperation.GET_FORM_DATA, { selector });
+    }
+    /**
+     * Start listening for clicks on form elements
+     * When a form element is clicked, the callback will be invoked with the form data
+     * @param callback - Function to call when a form element is clicked
+     */
+    async startFormClickListener(callback) {
+        this.formClickCallback = callback;
+        return this.sendRequest(DOMOperation.START_FORM_CLICK_LISTENER, {});
+    }
+    /**
+     * Stop listening for clicks on form elements
+     */
+    async stopFormClickListener() {
+        this.formClickCallback = null;
+        return this.sendRequest(DOMOperation.STOP_FORM_CLICK_LISTENER, {});
+    }
+    /**
+     * Start listening for clicks on elements matching a CSS selector
+     * When an element is clicked, the callback will be invoked with element data
+     *
+     * @param selector - CSS selector for elements to listen to (e.g., 'div.sortable-item[role="button"]')
+     * @param callback - Function to call when a matching element is clicked
+     * @param options - Optional configuration
+     * @param options.listenerId - Unique ID for this listener (auto-generated if not provided)
+     * @returns Promise<string> - The listener ID (for cleanup with stopElementClickListener)
+     *
+     * @example
+     * // Listen to tab buttons
+     * const listenerId = await weaveDOM.startElementClickListener(
+     *   'div.sortable-item[role="button"]',
+     *   (data) => {
+     *     console.log('Tab clicked:', data.element.textContent);
+     *     console.log('Element:', data.element);
+     *   }
+     * );
+     *
+     * // Later, stop listening
+     * await weaveDOM.stopElementClickListener(listenerId);
+     */
+    async startElementClickListener(selector, callback, options) {
+        const listenerId = options?.listenerId || `listener-${Date.now()}-${Math.random()}`;
+        // Store callback
+        this.elementSelectorClickCallbacks.set(listenerId, callback);
+        // Send request to content script
+        await this.sendRequest(DOMOperation.START_ELEMENT_CLICK_LISTENER, {
+            selector,
+            listenerId,
+        });
+        return listenerId;
+    }
+    /**
+     * Stop listening for clicks on elements
+     *
+     * @param listenerId - The ID of the listener to stop (returned from startElementClickListener)
+     *
+     * @example
+     * const listenerId = await weaveDOM.startElementClickListener('button', callback);
+     * // ... later ...
+     * await weaveDOM.stopElementClickListener(listenerId);
+     */
+    async stopElementClickListener(listenerId) {
+        // Remove callback
+        this.elementSelectorClickCallbacks.delete(listenerId);
+        // Send request to content script
+        return this.sendRequest(DOMOperation.STOP_ELEMENT_CLICK_LISTENER, {
+            listenerId,
+        });
+    }
+    /**
+     * Start listening for hover on elements matching a CSS selector
+     * When an element is hovered for the configured delay, the callback will be invoked with element data
+     *
+     * @param selector - CSS selector for elements to listen to
+     * @param callback - Function to call when a matching element is hovered
+     * @param options - Optional configuration
+     * @param options.listenerId - Unique ID for this listener (auto-generated if not provided)
+     * @param options.hoverDelayMs - Delay in milliseconds before hover callback fires (default: 1000)
+     * @returns Promise<string> - The listener ID (for cleanup with stopElementHoverListener)
+     */
+    async startElementHoverListener(selector, callback, options) {
+        const listenerId = options?.listenerId || `hover-listener-${Date.now()}-${Math.random()}`;
+        // Store callback
+        this.elementSelectorHoverCallbacks.set(listenerId, callback);
+        // Send request to content script
+        await this.sendRequest(DOMOperation.START_ELEMENT_HOVER_LISTENER, {
+            selector,
+            listenerId,
+            hoverDelayMs: options?.hoverDelayMs,
+        });
+        return listenerId;
+    }
+    /**
+     * Stop listening for hover on elements
+     *
+     * @param listenerId - The ID of the listener to stop (returned from startElementHoverListener)
+     */
+    async stopElementHoverListener(listenerId) {
+        // Remove callback
+        this.elementSelectorHoverCallbacks.delete(listenerId);
+        // Send request to content script
+        return this.sendRequest(DOMOperation.STOP_ELEMENT_HOVER_LISTENER, {
+            listenerId,
+        });
+    }
+    /**
+     * Set the value of a form field
+     * Handles all input types (text, checkbox, radio, select, textarea, etc.)
+     * Automatically triggers validation events
+     *
+     * @param selector - CSS selector for the form field
+     * @param value - Value to set (string for text inputs, boolean for checkboxes, array for multi-selects)
+     * @param scrollIntoView - Optional: if true, scrolls element to center of viewport before setting value (default: false)
+     *
+     * @example
+     * // Text input
+     * await weaveDOM.setFormFieldValue('input[name="email"]', 'user@example.com');
+     *
+     * // Checkbox with scroll
+     * await weaveDOM.setFormFieldValue('input[name="terms"]', true, true);
+     *
+     * // Radio button (set to the value of the radio to select)
+     * await weaveDOM.setFormFieldValue('input[name="gender"][value="female"]', 'female');
+     *
+     * // Select
+     * await weaveDOM.setFormFieldValue('select[name="country"]', 'US');
+     *
+     * // Multi-select with scroll to make it visible
+     * await weaveDOM.setFormFieldValue('select[name="interests"]', ['sports', 'music'], true);
+     */
+    async setFormFieldValue(selector, value, scrollIntoView = false) {
+        return this.sendRequest(DOMOperation.SET_FORM_FIELD_VALUE, {
+            selector,
+            value,
+            scrollIntoView
+        });
+    }
+    // ============================================================================
+    // Event Listeners
+    // ============================================================================
+    /**
+     * Register a callback for when a workflow is saved
+     * @param callback - Function to call when a workflow is saved from the content script
+     */
+    onWorkflowSaved(callback) {
+        this.workflowSavedCallback = callback;
+    }
+    /**
+     * Remove the workflow saved callback
+     */
+    offWorkflowSaved() {
+        this.workflowSavedCallback = null;
+    }
+    /**
+     * Register a callback for when a trigger is saved
+     * @param callback - Function to call when a trigger is saved from the content script
+     */
+    onTriggerSaved(callback) {
+        this.triggerSavedCallback = callback;
+    }
+    /**
+     * Remove the trigger saved callback
+     */
+    offTriggerSaved() {
+        this.triggerSavedCallback = null;
+    }
+    // ============================================================================
+    // Element Injection Operations
+    // ============================================================================
+    /**
+     * Inject an element onto the parent page with optional click event listener
+     *
+     * @param targetSelector - CSS selector for the element to inject relative to
+     * @param position - Position relative to target ('beforebegin', 'afterbegin', 'beforeend', 'afterend')
+     * @param html - HTML string to inject (will be sanitized)
+     * @param options - Optional configuration
+     * @param options.onClick - Callback function to invoke when element is clicked
+     * @param options.elementId - Custom element ID (auto-generated if not provided)
+     * @returns Promise with the element ID
+     *
+     * @example
+     * // Inject a button with click handler
+     * const elementId = await weaveDOM.injectElement(
+     *   'body',
+     *   'beforeend',
+     *   '<button class="my-button">Click Me</button>',
+     *   {
+     *     onClick: (data) => {
+     *       console.log('Button clicked!', data);
+     *     }
+     *   }
+     * );
+     *
+     * // Later, remove the element
+     * await weaveDOM.removeInjectedElement(elementId);
+     */
+    async injectElement(targetSelector, position, html, options) {
+        // Generate element ID if not provided
+        const elementId = options?.elementId || `weave-injected-${++this.elementIdCounter}`;
+        // Store click callback if provided
+        if (options?.onClick) {
+            this.elementClickCallbacks.set(elementId, options.onClick);
+        }
+        // Send injection request
+        const result = await this.sendRequest(DOMOperation.INJECT_ELEMENT, {
+            targetSelector,
+            position,
+            html,
+            elementId,
+            onClick: !!options?.onClick,
+        });
+        return result.elementId;
+    }
+    /**
+     * Remove an injected element from the parent page
+     *
+     * @param elementId - ID of the element to remove (returned from injectElement)
+     *
+     * @example
+     * await weaveDOM.removeInjectedElement('weave-injected-1');
+     */
+    async removeInjectedElement(elementId) {
+        // Remove click callback if it exists
+        this.elementClickCallbacks.delete(elementId);
+        // Send removal request
+        return this.sendRequest(DOMOperation.REMOVE_INJECTED_ELEMENT, {
+            elementId,
+        });
+    }
+    // ============================================================================
+    // Element Watching Operations
+    // ============================================================================
+    /**
+     * Watch an element for changes (attributes, removal, children)
+     *
+     * Sets up MutationObservers to monitor:
+     * - Attribute changes on the element
+     * - Element removal from DOM
+     * - Child node changes (optional)
+     *
+     * @param selector - CSS selector for the element to watch
+     * @param callback - Function to call when element changes
+     * @param options - Optional configuration
+     * @param options.watchAttributes - Watch for attribute changes (default: true)
+     * @param options.watchChildren - Watch for child node changes (default: false)
+     * @param options.attributeFilter - Optional array of specific attributes to watch
+     * @returns Promise with the watcher ID (use to stop watching)
+     *
+     * @example
+     * // Watch for attribute changes
+     * const watcherId = await weaveDOM.watchElement(
+     *   '#my-element',
+     *   (data) => {
+     *     if (data.changeType === 'attribute') {
+     *       console.log(`Attribute ${data.attributeName} changed to: ${data.attributeValue}`);
+     *     } else if (data.changeType === 'removed') {
+     *       console.log('Element was removed from DOM');
+     *     }
+     *   },
+     *   {
+     *     watchAttributes: true,
+     *     attributeFilter: ['class', 'data-status'] // Only watch specific attributes
+     *   }
+     * );
+     *
+     * // Later, stop watching
+     * await weaveDOM.unwatchElement(watcherId);
+     */
+    async watchElement(selector, callback, options) {
+        // Generate watcher ID
+        const watcherId = `weave-watcher-${++this.watcherIdCounter}`;
+        // Store callback
+        this.elementChangeCallbacks.set(watcherId, callback);
+        // Send watch request
+        await this.sendRequest(DOMOperation.WATCH_ELEMENT, {
+            selector,
+            watcherId,
+            watchAttributes: options?.watchAttributes,
+            watchChildren: options?.watchChildren,
+            attributeFilter: options?.attributeFilter,
+        });
+        return watcherId;
+    }
+    /**
+     * Stop watching an element
+     *
+     * @param watcherId - ID of the watcher to stop (returned from watchElement)
+     *
+     * @example
+     * await weaveDOM.unwatchElement('weave-watcher-1');
+     */
+    async unwatchElement(watcherId) {
+        // Remove callback
+        this.elementChangeCallbacks.delete(watcherId);
+        // Send unwatch request
+        return this.sendRequest(DOMOperation.UNWATCH_ELEMENT, {
+            watcherId,
+        });
+    }
+    // ============================================================================
+    // Scroll Operations
+    // ============================================================================
+    /**
+     * Scroll an element into view on the parent page
+     *
+     * Abstraction over Element.scrollIntoView(). Accepts either a boolean
+     * `alignToTop` parameter or a `ScrollIntoViewOptions` object.
+     *
+     * @param selector - CSS selector for the element to scroll into view
+     * @param arg - Optional. A boolean (alignToTop) or a ScrollIntoViewOptions object.
+     *   - `true` (default): aligns the element to the top of the scrollable ancestor
+     *   - `false`: aligns the element to the bottom
+     *   - `ScrollIntoViewOptions`: e.g. `{ behavior: 'smooth', block: 'center' }`
+     *
+     * @example
+     * // Scroll element to top (default)
+     * await weaveDOM.scrollIntoView('#my-element');
+     *
+     * // Scroll element to bottom
+     * await weaveDOM.scrollIntoView('#my-element', false);
+     *
+     * // Scroll with smooth animation to center
+     * await weaveDOM.scrollIntoView('#my-element', { behavior: 'smooth', block: 'center' });
+     */
+    async scrollIntoView(selector, arg) {
+        const payload = { selector };
+        if (typeof arg === 'boolean') {
+            payload.alignToTop = arg;
+        }
+        else if (typeof arg === 'object' && arg !== null) {
+            payload.options = arg;
+        }
+        return this.sendRequest(DOMOperation.SCROLL_INTO_VIEW, payload);
+    }
+    // ============================================================================
+    // Dialog Operations
+    // ============================================================================
+    /**
+     * Show an alert dialog on the parent page
+     *
+     * This displays a native browser alert dialog with the specified message.
+     * The dialog blocks until the user clicks OK.
+     *
+     * @param message - Message to display in the alert
+     *
+     * @example
+     * await weaveDOM.alert('Please log in to continue.');
+     */
+    async alert(message) {
+        return this.sendRequest(DOMOperation.SHOW_ALERT, { message });
+    }
+    /**
+     * Show a confirm dialog on the parent page
+     *
+     * This displays a native browser confirm dialog with the specified message.
+     * Returns true if user clicked OK, false if user clicked Cancel.
+     *
+     * @param message - Message to display in the confirm dialog
+     * @returns Promise<boolean> - true if confirmed, false if cancelled
+     *
+     * @example
+     * const confirmed = await weaveDOM.confirm('Are you sure you want to proceed?');
+     * if (confirmed) {
+     *   // User clicked OK
+     * } else {
+     *   // User clicked Cancel
+     * }
+     */
+    async confirm(message) {
+        return this.sendRequest(DOMOperation.SHOW_CONFIRM, { message });
+    }
+}
+export default new WeaveDOMAPI();