agent-web-interface 4.0.0

package/dist/src/server/session-store.js

@@ -0,0 +1,224 @@
+/**
+ * Session Store
+ *
+ * Tracks active sessions per MCP client (tenant isolation).
+ * Supports optional TTL-based auto-cleanup of expired sessions.
+ */
+import { randomUUID } from 'crypto';
+/** Default TTL in milliseconds (30 minutes) */
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+/** Cleanup interval in milliseconds (5 minutes) */
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+/**
+ * In-memory session store for tenant isolation
+ */
+export class SessionStore {
+    sessions = new Map();
+    ttlMs;
+    maxSessions;
+    cleanupInterval = null;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxSessions = options.maxSessions ?? Infinity;
+        if (options.autoCleanup && this.ttlMs > 0) {
+            this.startAutoCleanup();
+        }
+    }
+    /**
+     * Create a new session for a tenant
+     *
+     * @param tenant_id - The tenant/client identifier
+     * @returns The new session_id
+     * @throws Error if max sessions limit reached
+     */
+    createSession(tenant_id) {
+        // Check max sessions limit
+        if (this.sessions.size >= this.maxSessions) {
+            throw new Error(`Maximum sessions limit reached: ${this.maxSessions}`);
+        }
+        const session_id = `session-${randomUUID()}`;
+        const now = new Date();
+        const session = {
+            session_id,
+            tenant_id,
+            page_ids: new Set(),
+            created_at: now,
+            last_accessed_at: now,
+            expires_at: this.ttlMs > 0 ? new Date(now.getTime() + this.ttlMs) : null,
+        };
+        this.sessions.set(session_id, session);
+        return session_id;
+    }
+    /**
+     * Get a session by its ID.
+     * Automatically refreshes TTL and checks for expiration.
+     *
+     * @param session_id - The session identifier
+     * @returns TenantSession if found and not expired, undefined otherwise
+     */
+    getSession(session_id) {
+        const session = this.sessions.get(session_id);
+        if (!session)
+            return undefined;
+        // Check if expired
+        if (this.isExpired(session)) {
+            this.sessions.delete(session_id);
+            return undefined;
+        }
+        // Touch session to refresh TTL
+        this.touchSession(session);
+        return session;
+    }
+    /**
+     * Add a page to a session
+     *
+     * @param session_id - The session identifier
+     * @param page_id - The page identifier to add
+     */
+    addPage(session_id, page_id) {
+        const session = this.sessions.get(session_id);
+        if (session) {
+            session.page_ids.add(page_id);
+        }
+    }
+    /**
+     * Remove a page from a session
+     *
+     * @param session_id - The session identifier
+     * @param page_id - The page identifier to remove
+     */
+    removePage(session_id, page_id) {
+        const session = this.sessions.get(session_id);
+        if (session) {
+            session.page_ids.delete(page_id);
+        }
+    }
+    /**
+     * Get all pages for a session
+     *
+     * @param session_id - The session identifier
+     * @returns Array of page_ids (empty if session not found)
+     */
+    getPages(session_id) {
+        const session = this.sessions.get(session_id);
+        if (!session) {
+            return [];
+        }
+        return Array.from(session.page_ids);
+    }
+    /**
+     * Destroy a session completely
+     *
+     * @param session_id - The session identifier
+     */
+    destroySession(session_id) {
+        this.sessions.delete(session_id);
+    }
+    /**
+     * List all active sessions
+     *
+     * @returns Array of all TenantSession objects
+     */
+    listSessions() {
+        return Array.from(this.sessions.values());
+    }
+    /**
+     * Get sessions for a specific tenant
+     *
+     * @param tenant_id - The tenant identifier
+     * @returns Array of sessions for this tenant
+     */
+    getSessionsByTenant(tenant_id) {
+        return this.listSessions().filter((s) => s.tenant_id === tenant_id);
+    }
+    /**
+     * Get the total number of sessions
+     *
+     * @returns Session count
+     */
+    sessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Check if a session exists
+     *
+     * @param session_id - The session identifier
+     * @returns true if session exists
+     */
+    hasSession(session_id) {
+        return this.sessions.has(session_id);
+    }
+    /**
+     * Clear all sessions (for testing or shutdown)
+     */
+    clear() {
+        this.sessions.clear();
+    }
+    /**
+     * Stop automatic cleanup timer
+     */
+    stopAutoCleanup() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
+    /**
+     * Start automatic cleanup of expired sessions
+     */
+    startAutoCleanup() {
+        this.stopAutoCleanup();
+        this.cleanupInterval = setInterval(() => {
+            this.cleanupExpired();
+        }, CLEANUP_INTERVAL_MS);
+        // Don't keep the process alive just for cleanup
+        this.cleanupInterval.unref();
+    }
+    /**
+     * Manually clean up all expired sessions
+     *
+     * @returns Number of sessions removed
+     */
+    cleanupExpired() {
+        let removed = 0;
+        const now = new Date();
+        for (const [session_id, session] of this.sessions) {
+            if (session.expires_at && session.expires_at <= now) {
+                this.sessions.delete(session_id);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Check if a session is expired
+     */
+    isExpired(session) {
+        if (!session.expires_at)
+            return false;
+        return session.expires_at <= new Date();
+    }
+    /**
+     * Touch a session to refresh its TTL
+     */
+    touchSession(session) {
+        const now = new Date();
+        session.last_accessed_at = now;
+        if (this.ttlMs > 0) {
+            session.expires_at = new Date(now.getTime() + this.ttlMs);
+        }
+    }
+    /**
+     * Get the configured TTL in milliseconds
+     */
+    getTtlMs() {
+        return this.ttlMs;
+    }
+    /**
+     * Get the configured max sessions limit
+     */
+    getMaxSessions() {
+        return this.maxSessions;
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/src/server/session-store.js.map

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

package/dist/src/shared/errors/browser-session.error.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Browser Session Error
+ *
+ * Standardized error classification for browser session operations.
+ * Provides error codes for programmatic handling and detailed messages for debugging.
+ */
+/**
+ * Error codes for browser session operations
+ */
+export type BrowserErrorCode = 'NOT_CONNECTED' | 'ALREADY_CONNECTED' | 'CONNECTION_FAILED' | 'CONNECTION_TIMEOUT' | 'INVALID_URL' | 'PAGE_NOT_FOUND' | 'PAGE_CLOSED' | 'CDP_ERROR' | 'CDP_TIMEOUT' | 'CDP_SESSION_CLOSED' | 'BROWSER_DISCONNECTED' | 'INVALID_STATE' | 'OPERATION_FAILED';
+/**
+ * Standardized error for browser session operations.
+ *
+ * @example
+ * ```typescript
+ * throw new BrowserSessionError(
+ *   'Browser disconnected unexpectedly',
+ *   'BROWSER_DISCONNECTED',
+ *   originalError
+ * );
+ *
+ * // Catching and handling by code
+ * try {
+ *   await session.connect();
+ * } catch (error) {
+ *   if (error instanceof BrowserSessionError) {
+ *     switch (error.code) {
+ *       case 'CONNECTION_TIMEOUT':
+ *         console.log('Connection timed out, retrying...');
+ *         break;
+ *       case 'INVALID_URL':
+ *         console.log('Invalid endpoint URL');
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class BrowserSessionError extends Error {
+    /**
+     * Error code for programmatic handling
+     */
+    readonly code: BrowserErrorCode;
+    /**
+     * Original error that caused this error (if any)
+     */
+    readonly cause?: Error;
+    /**
+     * Additional context for debugging
+     */
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, code: BrowserErrorCode, cause?: Error, context?: Record<string, unknown>);
+    /**
+     * Create a JSON-serializable representation of the error
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Type guard to check if an error is a BrowserSessionError
+     */
+    static isBrowserSessionError(error: unknown): error is BrowserSessionError;
+    /**
+     * Create error for not connected state
+     */
+    static notConnected(context?: Record<string, unknown>): BrowserSessionError;
+    /**
+     * Create error for already connected state
+     */
+    static alreadyConnected(context?: Record<string, unknown>): BrowserSessionError;
+    /**
+     * Create error for connection failure
+     */
+    static connectionFailed(cause: Error, context?: Record<string, unknown>): BrowserSessionError;
+    /**
+     * Create error for connection timeout
+     */
+    static connectionTimeout(endpointUrl: string, timeoutMs: number, context?: Record<string, unknown>): BrowserSessionError;
+    /**
+     * Create error for invalid URL
+     */
+    static invalidUrl(url: string, context?: Record<string, unknown>): BrowserSessionError;
+    /**
+     * Create error for page not found
+     */
+    static pageNotFound(pageId: string, context?: Record<string, unknown>): BrowserSessionError;
+    /**
+     * Create error for CDP operation failure
+     */
+    static cdpError(method: string, cause: Error, context?: Record<string, unknown>): BrowserSessionError;
+    /**
+     * Create error for CDP timeout
+     */
+    static cdpTimeout(method: string, timeoutMs: number, context?: Record<string, unknown>): BrowserSessionError;
+    /**
+     * Create error for browser disconnect
+     */
+    static browserDisconnected(context?: Record<string, unknown>): BrowserSessionError;
+    /**
+     * Create error for invalid state transition
+     */
+    static invalidState(currentState: string, attemptedOperation: string, context?: Record<string, unknown>): BrowserSessionError;
+}
+//# sourceMappingURL=browser-session.error.d.ts.map

package/dist/src/shared/errors/browser-session.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session.error.d.ts","sourceRoot":"","sources":["../../../../src/shared/errors/browser-session.error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,mBAAmB,GACnB,mBAAmB,GACnB,oBAAoB,GACpB,aAAa,GACb,gBAAgB,GAChB,aAAa,GACb,WAAW,GACX,aAAa,GACb,oBAAoB,GACpB,sBAAsB,GACtB,eAAe,GACf,kBAAkB,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,gBAAgB,EACtB,KAAK,CAAC,EAAE,KAAK,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAcnC;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAgBjC;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB;IAI1E;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB;IAI3E;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB;IAS/E;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB;IAS7F;;OAEG;IACH,MAAM,CAAC,iBAAiB,CACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,mBAAmB;IAStB;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB;IAOtF;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB;IAO3F;;OAEG;IACH,MAAM,CAAC,QAAQ,CACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,mBAAmB;IAOtB;;OAEG;IACH,MAAM,CAAC,UAAU,CACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,mBAAmB;IAStB;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB;IASlF;;OAEG;IACH,MAAM,CAAC,YAAY,CACjB,YAAY,EAAE,MAAM,EACpB,kBAAkB,EAAE,MAAM,EAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,mBAAmB;CAQvB"}

package/dist/src/shared/errors/browser-session.error.js

@@ -0,0 +1,153 @@
+/**
+ * Browser Session Error
+ *
+ * Standardized error classification for browser session operations.
+ * Provides error codes for programmatic handling and detailed messages for debugging.
+ */
+/**
+ * Standardized error for browser session operations.
+ *
+ * @example
+ * ```typescript
+ * throw new BrowserSessionError(
+ *   'Browser disconnected unexpectedly',
+ *   'BROWSER_DISCONNECTED',
+ *   originalError
+ * );
+ *
+ * // Catching and handling by code
+ * try {
+ *   await session.connect();
+ * } catch (error) {
+ *   if (error instanceof BrowserSessionError) {
+ *     switch (error.code) {
+ *       case 'CONNECTION_TIMEOUT':
+ *         console.log('Connection timed out, retrying...');
+ *         break;
+ *       case 'INVALID_URL':
+ *         console.log('Invalid endpoint URL');
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class BrowserSessionError extends Error {
+    /**
+     * Error code for programmatic handling
+     */
+    code;
+    /**
+     * Original error that caused this error (if any)
+     */
+    cause;
+    /**
+     * Additional context for debugging
+     */
+    context;
+    constructor(message, code, cause, context) {
+        super(message);
+        this.name = 'BrowserSessionError';
+        this.code = code;
+        this.cause = cause;
+        this.context = context;
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, BrowserSessionError);
+        }
+    }
+    /**
+     * Create a JSON-serializable representation of the error
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            context: this.context,
+            cause: this.cause
+                ? {
+                    name: this.cause.name,
+                    message: this.cause.message,
+                }
+                : undefined,
+            stack: this.stack,
+        };
+    }
+    /**
+     * Type guard to check if an error is a BrowserSessionError
+     */
+    static isBrowserSessionError(error) {
+        return error instanceof BrowserSessionError;
+    }
+    /**
+     * Create error for not connected state
+     */
+    static notConnected(context) {
+        return new BrowserSessionError('Browser not connected', 'NOT_CONNECTED', undefined, context);
+    }
+    /**
+     * Create error for already connected state
+     */
+    static alreadyConnected(context) {
+        return new BrowserSessionError('Browser already connected or connection in progress', 'ALREADY_CONNECTED', undefined, context);
+    }
+    /**
+     * Create error for connection failure
+     */
+    static connectionFailed(cause, context) {
+        return new BrowserSessionError(`Failed to connect to browser: ${cause.message}`, 'CONNECTION_FAILED', cause, context);
+    }
+    /**
+     * Create error for connection timeout
+     */
+    static connectionTimeout(endpointUrl, timeoutMs, context) {
+        return new BrowserSessionError(`Connection timeout after ${timeoutMs}ms: ${endpointUrl}`, 'CONNECTION_TIMEOUT', undefined, { endpointUrl, timeoutMs, ...context });
+    }
+    /**
+     * Create error for invalid URL
+     */
+    static invalidUrl(url, context) {
+        return new BrowserSessionError(`Invalid endpoint URL: ${url}`, 'INVALID_URL', undefined, {
+            url,
+            ...context,
+        });
+    }
+    /**
+     * Create error for page not found
+     */
+    static pageNotFound(pageId, context) {
+        return new BrowserSessionError(`Page not found: ${pageId}`, 'PAGE_NOT_FOUND', undefined, {
+            pageId,
+            ...context,
+        });
+    }
+    /**
+     * Create error for CDP operation failure
+     */
+    static cdpError(method, cause, context) {
+        return new BrowserSessionError(`CDP command failed: ${method}`, 'CDP_ERROR', cause, {
+            method,
+            ...context,
+        });
+    }
+    /**
+     * Create error for CDP timeout
+     */
+    static cdpTimeout(method, timeoutMs, context) {
+        return new BrowserSessionError(`CDP command timed out after ${timeoutMs}ms: ${method}`, 'CDP_TIMEOUT', undefined, { method, timeoutMs, ...context });
+    }
+    /**
+     * Create error for browser disconnect
+     */
+    static browserDisconnected(context) {
+        return new BrowserSessionError('Browser disconnected unexpectedly', 'BROWSER_DISCONNECTED', undefined, context);
+    }
+    /**
+     * Create error for invalid state transition
+     */
+    static invalidState(currentState, attemptedOperation, context) {
+        return new BrowserSessionError(`Invalid operation "${attemptedOperation}" in state "${currentState}"`, 'INVALID_STATE', undefined, { currentState, attemptedOperation, ...context });
+    }
+}
+//# sourceMappingURL=browser-session.error.js.map

package/dist/src/shared/errors/browser-session.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session.error.js","sourceRoot":"","sources":["../../../../src/shared/errors/browser-session.error.ts"],"names":[],"mappings":"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"}

package/dist/src/shared/errors/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Error module exports
+ */
+export { BrowserSessionError, type BrowserErrorCode } from './browser-session.error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/shared/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/shared/errors/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/src/shared/errors/index.js

@@ -0,0 +1,5 @@
+/**
+ * Error module exports
+ */
+export { BrowserSessionError } from './browser-session.error.js';
+//# sourceMappingURL=index.js.map

package/dist/src/shared/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/shared/errors/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAyB,MAAM,4BAA4B,CAAC"}

package/dist/src/shared/services/dom-transformer.service.d.ts

@@ -0,0 +1,71 @@
+/**
+ * DOM Transformer Service
+ *
+ * Transforms CDP DOM.getDocument responses into our DomTreeNode format
+ *
+ * FIXES: The stub implementation in browser-automation-mcp-server.ts:731-736
+ * that returned { nodes: [] } without transforming the CDP response
+ */
+import type { DomTreeNode } from '../types/index.js';
+/**
+ * CDP DOM Node structure
+ */
+interface CdpDomNode {
+    nodeId: number;
+    nodeType: number;
+    nodeName: string;
+    localName: string;
+    nodeValue: string;
+    childNodeCount?: number;
+    children?: CdpDomNode[];
+    attributes?: string[];
+    documentURL?: string;
+    baseURL?: string;
+}
+interface CdpDomTreeResponse {
+    root: CdpDomNode;
+}
+export interface DomGetTreeParams {
+    frameId?: string;
+    depth?: number;
+    visibleOnly?: boolean;
+}
+export interface DomGetTreeResponse {
+    nodes: DomTreeNode[];
+}
+export declare class DomTransformerService {
+    /**
+     * Transform CDP DOM.getDocument response into our DomTreeNode format
+     */
+    transform(cdpResponse: CdpDomTreeResponse, params: DomGetTreeParams): DomGetTreeResponse;
+    /**
+     * Recursively transform a CDP node and its children
+     */
+    private transformNode;
+    /**
+     * Parse CDP attributes array [key1, value1, key2, value2, ...] to object
+     */
+    private parseAttributes;
+    /**
+     * Check if element is hidden by inline style
+     */
+    private isHiddenByStyle;
+    /**
+     * Extract text content from immediate text children
+     */
+    private extractTextContent;
+    /**
+     * Flatten tree structure into array (breadth-first traversal)
+     */
+    flattenTree(nodes: DomTreeNode[]): DomTreeNode[];
+    /**
+     * Filter nodes by tag name
+     */
+    filterByTag(nodes: DomTreeNode[], tag: string): DomTreeNode[];
+    /**
+     * Find nodes by attribute
+     */
+    findByAttribute(nodes: DomTreeNode[], attrName: string, attrValue?: string): DomTreeNode[];
+}
+export {};
+//# sourceMappingURL=dom-transformer.service.d.ts.map

package/dist/src/shared/services/dom-transformer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-transformer.service.d.ts","sourceRoot":"","sources":["../../../../src/shared/services/dom-transformer.service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;GAEG;AACH,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,kBAAkB;IAC1B,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,qBAAa,qBAAqB;IAChC;;OAEG;IACH,SAAS,CAAC,WAAW,EAAE,kBAAkB,EAAE,MAAM,EAAE,gBAAgB,GAAG,kBAAkB;IASxF;;OAEG;IACH,OAAO,CAAC,aAAa;IAoFrB;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAUvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAuB1B;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE;IAgBhD;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE;IAe7D;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE;CA2B3F"}