sentience-ts 0.10.3

package/dist/inspector.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * Inspector tool - helps developers see what the agent "sees"
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Inspector = void 0;
+exports.inspect = inspect;
+class Inspector {
+    constructor(browser) {
+        this.browser = browser;
+        this.active = false;
+    }
+    async start() {
+        const page = this.browser.getPage();
+        this.active = true;
+        // Inject inspector script into page
+        await page.evaluate(() => {
+            // Remove existing inspector if any
+            if (window.__sentience_inspector_active) {
+                return;
+            }
+            window.__sentience_inspector_active = true;
+            window.__sentience_last_element_id = null;
+            // Get element at point
+            function getElementAtPoint(x, y) {
+                const el = document.elementFromPoint(x, y);
+                if (!el)
+                    return null;
+                // Find element in registry
+                const registry = window.sentience_registry;
+                if (registry) {
+                    for (let i = 0; i < registry.length; i++) {
+                        if (registry[i] === el) {
+                            return i;
+                        }
+                    }
+                }
+                return null;
+            }
+            // Mouse move handler
+            function handleMouseMove(e) {
+                if (!window.__sentience_inspector_active)
+                    return;
+                const elementId = getElementAtPoint(e.clientX, e.clientY);
+                if (elementId === null || elementId === window.__sentience_last_element_id) {
+                    return;
+                }
+                window.__sentience_last_element_id = elementId;
+                // Get element info from snapshot if available
+                const sentience = window.sentience;
+                const registry = window.sentience_registry;
+                if (sentience && registry) {
+                    const el = registry[elementId];
+                    if (el) {
+                        const rect = el.getBoundingClientRect();
+                        const text = el.getAttribute('aria-label') ||
+                            el.value ||
+                            el.placeholder ||
+                            el.alt ||
+                            (el.innerText || '').substring(0, 50);
+                        const role = el.getAttribute('role') || el.tagName.toLowerCase();
+                        console.log(`[Sentience Inspector] Element #${elementId}: role=${role}, text="${text}", bbox=(${Math.round(rect.x)}, ${Math.round(rect.y)}, ${Math.round(rect.width)}, ${Math.round(rect.height)})`);
+                    }
+                }
+            }
+            // Click handler
+            function handleClick(e) {
+                if (!window.__sentience_inspector_active)
+                    return;
+                e.preventDefault();
+                e.stopPropagation();
+                const elementId = getElementAtPoint(e.clientX, e.clientY);
+                if (elementId === null)
+                    return;
+                // Get full element info
+                const sentience = window.sentience;
+                const registry = window.sentience_registry;
+                if (sentience && registry) {
+                    const el = registry[elementId];
+                    if (el) {
+                        const rect = el.getBoundingClientRect();
+                        const info = {
+                            id: elementId,
+                            tag: el.tagName.toLowerCase(),
+                            role: el.getAttribute('role') || 'generic',
+                            text: el.getAttribute('aria-label') ||
+                                el.value ||
+                                el.placeholder ||
+                                el.alt ||
+                                (el.innerText || '').substring(0, 100),
+                            bbox: {
+                                x: Math.round(rect.x),
+                                y: Math.round(rect.y),
+                                width: Math.round(rect.width),
+                                height: Math.round(rect.height),
+                            },
+                            attributes: {
+                                id: el.id || null,
+                                class: el.className || null,
+                                name: el.name || null,
+                                type: el.type || null,
+                            },
+                        };
+                        console.log('[Sentience Inspector] Clicked element:', JSON.stringify(info, null, 2));
+                        // Also try to get from snapshot if available
+                        if (sentience && sentience.snapshot) {
+                            sentience
+                                .snapshot({ limit: 100 })
+                                .then((snap) => {
+                                const element = snap.elements.find((el) => el.id === elementId);
+                                if (element) {
+                                    console.log('[Sentience Inspector] Snapshot element:', JSON.stringify(element, null, 2));
+                                }
+                            })
+                                .catch(() => { });
+                        }
+                    }
+                }
+            }
+            // Add event listeners
+            document.addEventListener('mousemove', handleMouseMove, true);
+            document.addEventListener('click', handleClick, true);
+            // Store cleanup function
+            window.__sentience_inspector_cleanup = () => {
+                document.removeEventListener('mousemove', handleMouseMove, true);
+                document.removeEventListener('click', handleClick, true);
+                window.__sentience_inspector_active = false;
+            };
+            console.log('[Sentience Inspector] ✅ Inspection mode active. Hover elements to see info, click to see full details.');
+        });
+    }
+    async stop() {
+        const page = this.browser.getPage();
+        this.active = false;
+        // Cleanup inspector
+        await page.evaluate(() => {
+            if (window.__sentience_inspector_cleanup) {
+                window.__sentience_inspector_cleanup();
+            }
+        });
+    }
+}
+exports.Inspector = Inspector;
+function inspect(browser) {
+    return new Inspector(browser);
+}
+//# sourceMappingURL=inspector.js.map

package/dist/inspector.js.map

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

package/dist/query.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Query engine v1 - semantic selector matching
+ */
+import { Snapshot, Element, QuerySelector, QuerySelectorObject } from './types';
+export declare function parseSelector(selector: string): QuerySelectorObject;
+export declare function query(snapshot: Snapshot, selector: QuerySelector): Element[];
+export declare function find(snapshot: Snapshot, selector: QuerySelector): Element | null;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEhF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAsJnE;AAiMD,wBAAgB,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,EAAE,CAW5E;AAED,wBAAgB,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI,CAGhF"}

package/dist/query.js

@@ -0,0 +1,337 @@
+"use strict";
+/**
+ * Query engine v1 - semantic selector matching
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSelector = parseSelector;
+exports.query = query;
+exports.find = find;
+function parseSelector(selector) {
+    const query = {};
+    // Match patterns like: key=value, key~'value', key!="value", key>123, key^='prefix', key$='suffix'
+    // Updated regex to support: =, !=, ~, ^=, $=, >, >=, <, <=
+    // Supports dot notation: attr.id, css.color
+    // Note: Handle ^= and $= first (before single char operators) to avoid regex conflicts
+    const pattern = /([\w.]+)(\^=|\$=|>=|<=|!=|[=~<>])((?:'[^']+'|"[^"]+"|[^\s]+))/g;
+    let match;
+    while ((match = pattern.exec(selector)) !== null) {
+        const key = match[1];
+        const op = match[2];
+        let value = match[3];
+        // Remove quotes from value
+        value = value.replace(/^["']|["']$/g, '');
+        // Handle numeric comparisons
+        let isNumeric = false;
+        let numericValue = 0;
+        const parsedNum = parseFloat(value);
+        if (!isNaN(parsedNum) && isFinite(parsedNum)) {
+            isNumeric = true;
+            numericValue = parsedNum;
+        }
+        if (op === '!=') {
+            if (key === 'role') {
+                query.role_exclude = value;
+            }
+            else if (key === 'clickable') {
+                query.clickable = false;
+            }
+            else if (key === 'visible') {
+                query.visible = false;
+            }
+        }
+        else if (op === '~') {
+            // Substring match (case-insensitive)
+            if (key === 'text' || key === 'name') {
+                query.text_contains = value;
+            }
+        }
+        else if (op === '^=') {
+            // Prefix match
+            if (key === 'text' || key === 'name') {
+                query.text_prefix = value;
+            }
+        }
+        else if (op === '$=') {
+            // Suffix match
+            if (key === 'text' || key === 'name') {
+                query.text_suffix = value;
+            }
+        }
+        else if (op === '>') {
+            // Greater than
+            if (isNumeric) {
+                if (key === 'importance') {
+                    query.importance_min = numericValue + 0.0001; // Exclusive
+                }
+                else if (key.startsWith('bbox.')) {
+                    query[`${key}_min`] = numericValue + 0.0001;
+                }
+                else if (key === 'z_index') {
+                    query.z_index_min = numericValue + 0.0001;
+                }
+            }
+            else if (key.startsWith('attr.') || key.startsWith('css.')) {
+                query[`${key}_gt`] = value;
+            }
+        }
+        else if (op === '>=') {
+            // Greater than or equal
+            if (isNumeric) {
+                if (key === 'importance') {
+                    query.importance_min = numericValue;
+                }
+                else if (key.startsWith('bbox.')) {
+                    query[`${key}_min`] = numericValue;
+                }
+                else if (key === 'z_index') {
+                    query.z_index_min = numericValue;
+                }
+            }
+            else if (key.startsWith('attr.') || key.startsWith('css.')) {
+                query[`${key}_gte`] = value;
+            }
+        }
+        else if (op === '<') {
+            // Less than
+            if (isNumeric) {
+                if (key === 'importance') {
+                    query.importance_max = numericValue - 0.0001; // Exclusive
+                }
+                else if (key.startsWith('bbox.')) {
+                    query[`${key}_max`] = numericValue - 0.0001;
+                }
+                else if (key === 'z_index') {
+                    query.z_index_max = numericValue - 0.0001;
+                }
+            }
+            else if (key.startsWith('attr.') || key.startsWith('css.')) {
+                query[`${key}_lt`] = value;
+            }
+        }
+        else if (op === '<=') {
+            // Less than or equal
+            if (isNumeric) {
+                if (key === 'importance') {
+                    query.importance_max = numericValue;
+                }
+                else if (key.startsWith('bbox.')) {
+                    query[`${key}_max`] = numericValue;
+                }
+                else if (key === 'z_index') {
+                    query.z_index_max = numericValue;
+                }
+            }
+            else if (key.startsWith('attr.') || key.startsWith('css.')) {
+                query[`${key}_lte`] = value;
+            }
+        }
+        else if (op === '=') {
+            // Exact match
+            if (key === 'role') {
+                query.role = value;
+            }
+            else if (key === 'clickable') {
+                query.clickable = value.toLowerCase() === 'true';
+            }
+            else if (key === 'visible') {
+                query.visible = value.toLowerCase() === 'true';
+            }
+            else if (key === 'tag') {
+                query.tag = value;
+            }
+            else if (key === 'name' || key === 'text') {
+                query.text = value;
+            }
+            else if (key === 'importance' && isNumeric) {
+                query.importance = numericValue;
+            }
+            else if (key.startsWith('attr.')) {
+                // Dot notation for attributes: attr.id="submit-btn"
+                const attrKey = key.substring(5); // Remove "attr." prefix
+                if (!query.attr) {
+                    query.attr = {};
+                }
+                query.attr[attrKey] = value;
+            }
+            else if (key.startsWith('css.')) {
+                // Dot notation for CSS: css.color="red"
+                const cssKey = key.substring(4); // Remove "css." prefix
+                if (!query.css) {
+                    query.css = {};
+                }
+                query.css[cssKey] = value;
+            }
+        }
+    }
+    return query;
+}
+function matchElement(element, query) {
+    // Role exact match
+    if (query.role !== undefined) {
+        if (element.role !== query.role) {
+            return false;
+        }
+    }
+    // Role exclusion
+    if (query.role_exclude !== undefined) {
+        if (element.role === query.role_exclude) {
+            return false;
+        }
+    }
+    // Clickable
+    if (query.clickable !== undefined) {
+        if (element.visual_cues.is_clickable !== query.clickable) {
+            return false;
+        }
+    }
+    // Visible (using in_viewport and !is_occluded)
+    if (query.visible !== undefined) {
+        const isVisible = element.in_viewport && !element.is_occluded;
+        if (isVisible !== query.visible) {
+            return false;
+        }
+    }
+    // Tag (not yet in Element model, but prepare for future)
+    if (query.tag !== undefined) {
+        // For now, this will always fail since tag is not in Element model
+        // This is a placeholder for future implementation
+    }
+    // Text exact match
+    if (query.text !== undefined) {
+        if (!element.text || element.text !== query.text) {
+            return false;
+        }
+    }
+    // Text contains (case-insensitive)
+    if (query.text_contains !== undefined) {
+        if (!element.text) {
+            return false;
+        }
+        if (!element.text.toLowerCase().includes(query.text_contains.toLowerCase())) {
+            return false;
+        }
+    }
+    // Text prefix match
+    if (query.text_prefix !== undefined) {
+        if (!element.text) {
+            return false;
+        }
+        if (!element.text.toLowerCase().startsWith(query.text_prefix.toLowerCase())) {
+            return false;
+        }
+    }
+    // Text suffix match
+    if (query.text_suffix !== undefined) {
+        if (!element.text) {
+            return false;
+        }
+        if (!element.text.toLowerCase().endsWith(query.text_suffix.toLowerCase())) {
+            return false;
+        }
+    }
+    // Importance filtering
+    if (query.importance !== undefined) {
+        if (element.importance !== query.importance) {
+            return false;
+        }
+    }
+    if (query.importance_min !== undefined) {
+        if (element.importance < query.importance_min) {
+            return false;
+        }
+    }
+    if (query.importance_max !== undefined) {
+        if (element.importance > query.importance_max) {
+            return false;
+        }
+    }
+    // BBox filtering (spatial)
+    if (query['bbox.x_min'] !== undefined) {
+        if (element.bbox.x < query['bbox.x_min']) {
+            return false;
+        }
+    }
+    if (query['bbox.x_max'] !== undefined) {
+        if (element.bbox.x > query['bbox.x_max']) {
+            return false;
+        }
+    }
+    if (query['bbox.y_min'] !== undefined) {
+        if (element.bbox.y < query['bbox.y_min']) {
+            return false;
+        }
+    }
+    if (query['bbox.y_max'] !== undefined) {
+        if (element.bbox.y > query['bbox.y_max']) {
+            return false;
+        }
+    }
+    if (query['bbox.width_min'] !== undefined) {
+        if (element.bbox.width < query['bbox.width_min']) {
+            return false;
+        }
+    }
+    if (query['bbox.width_max'] !== undefined) {
+        if (element.bbox.width > query['bbox.width_max']) {
+            return false;
+        }
+    }
+    if (query['bbox.height_min'] !== undefined) {
+        if (element.bbox.height < query['bbox.height_min']) {
+            return false;
+        }
+    }
+    if (query['bbox.height_max'] !== undefined) {
+        if (element.bbox.height > query['bbox.height_max']) {
+            return false;
+        }
+    }
+    // Z-index filtering
+    if (query.z_index_min !== undefined) {
+        if (element.z_index < query.z_index_min) {
+            return false;
+        }
+    }
+    if (query.z_index_max !== undefined) {
+        if (element.z_index > query.z_index_max) {
+            return false;
+        }
+    }
+    // In viewport filtering
+    if (query.in_viewport !== undefined) {
+        if (element.in_viewport !== query.in_viewport) {
+            return false;
+        }
+    }
+    // Occlusion filtering
+    if (query.is_occluded !== undefined) {
+        if (element.is_occluded !== query.is_occluded) {
+            return false;
+        }
+    }
+    // Attribute filtering (dot notation: attr.id="submit-btn")
+    if (query.attr !== undefined) {
+        // This requires DOM access, which is not available in the Element model
+        // This is a placeholder for future implementation when we add DOM access
+    }
+    // CSS property filtering (dot notation: css.color="red")
+    if (query.css !== undefined) {
+        // This requires DOM access, which is not available in the Element model
+        // This is a placeholder for future implementation when we add DOM access
+    }
+    return true;
+}
+function query(snapshot, selector) {
+    // Parse selector if string
+    const queryObj = typeof selector === 'string' ? parseSelector(selector) : selector;
+    // Filter elements
+    const matches = snapshot.elements.filter((el) => matchElement(el, queryObj));
+    // Sort by importance (descending)
+    matches.sort((a, b) => b.importance - a.importance);
+    return matches;
+}
+function find(snapshot, selector) {
+    const results = query(snapshot, selector);
+    return results[0] || null;
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

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

package/dist/read.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Read page content - supports raw HTML, text, and markdown formats
+ */
+import { SentienceBrowser } from './browser';
+export interface ReadOptions {
+    format?: 'raw' | 'text' | 'markdown';
+    enhanceMarkdown?: boolean;
+}
+export interface ReadResult {
+    status: 'success' | 'error';
+    url: string;
+    format: 'raw' | 'text' | 'markdown';
+    content: string;
+    length: number;
+    error?: string;
+}
+/**
+ * Read page content as raw HTML, text, or markdown
+ *
+ * @param browser - SentienceBrowser instance
+ * @param options - Read options
+ * @returns ReadResult with page content
+ *
+ * @example
+ * // Get raw HTML (default)
+ * const result = await read(browser);
+ * const htmlContent = result.content;
+ *
+ * @example
+ * // Get high-quality markdown (uses Turndown internally)
+ * const result = await read(browser, { format: 'markdown' });
+ * const markdown = result.content;
+ *
+ * @example
+ * // Get plain text
+ * const result = await read(browser, { format: 'text' });
+ * const text = result.content;
+ */
+export declare function read(browser: SentienceBrowser, options?: ReadOptions): Promise<ReadResult>;
+//# sourceMappingURL=read.d.ts.map

package/dist/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../src/read.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAG7C,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;IACrC,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,IAAI,CACxB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CA+DrB"}

package/dist/read.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Read page content - supports raw HTML, text, and markdown formats
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.read = read;
+const turndown_1 = __importDefault(require("turndown"));
+/**
+ * Read page content as raw HTML, text, or markdown
+ *
+ * @param browser - SentienceBrowser instance
+ * @param options - Read options
+ * @returns ReadResult with page content
+ *
+ * @example
+ * // Get raw HTML (default)
+ * const result = await read(browser);
+ * const htmlContent = result.content;
+ *
+ * @example
+ * // Get high-quality markdown (uses Turndown internally)
+ * const result = await read(browser, { format: 'markdown' });
+ * const markdown = result.content;
+ *
+ * @example
+ * // Get plain text
+ * const result = await read(browser, { format: 'text' });
+ * const text = result.content;
+ */
+async function read(browser, options = {}) {
+    const page = browser.getPage();
+    const format = options.format || 'raw'; // Default to 'raw' for Turndown compatibility
+    const enhanceMarkdown = options.enhanceMarkdown !== false; // Default to true
+    if (format === 'markdown' && enhanceMarkdown) {
+        // Get raw HTML from the extension first
+        const rawHtmlResult = (await page.evaluate((opts) => {
+            return window.sentience.read(opts);
+        }, { format: 'raw' }));
+        if (rawHtmlResult.status === 'success') {
+            const htmlContent = rawHtmlResult.content;
+            try {
+                const turndownService = new turndown_1.default({
+                    headingStyle: 'atx',
+                    hr: '---',
+                    bulletListMarker: '-',
+                    codeBlockStyle: 'fenced',
+                    emDelimiter: '*',
+                });
+                // Add custom rules for better markdown
+                turndownService.addRule('strikethrough', {
+                    filter: (node) => ['s', 'del', 'strike'].includes(node.nodeName.toLowerCase()),
+                    replacement: function (content) {
+                        return '~~' + content + '~~';
+                    },
+                });
+                // Optionally strip certain tags entirely
+                turndownService.remove(['script', 'style', 'noscript', 'iframe']);
+                const markdownContent = turndownService.turndown(htmlContent);
+                return {
+                    status: 'success',
+                    url: rawHtmlResult.url,
+                    format: 'markdown',
+                    content: markdownContent,
+                    length: markdownContent.length,
+                };
+            }
+            catch (e) {
+                console.warn(`Turndown conversion failed: ${e.message}, falling back to extension's markdown.`);
+                // Fallback to extension's markdown if Turndown fails
+            }
+        }
+        else {
+            console.warn(`Failed to get raw HTML from extension: ${rawHtmlResult.error}, falling back to extension's markdown.`);
+            // Fallback to extension's markdown if getting raw HTML fails
+        }
+    }
+    // If not enhanced markdown, or fallback, call extension with requested format
+    const result = (await page.evaluate((opts) => {
+        return window.sentience.read(opts);
+    }, { format }));
+    return result;
+}
+//# sourceMappingURL=read.js.map

package/dist/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../src/read.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;AAyCH,oBAkEC;AAxGD,wDAAuC;AAgBvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACI,KAAK,UAAU,IAAI,CACxB,OAAyB,EACzB,UAAuB,EAAE;IAEzB,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,8CAA8C;IACtF,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,KAAK,KAAK,CAAC,CAAC,kBAAkB;IAE7E,IAAI,MAAM,KAAK,UAAU,IAAI,eAAe,EAAE,CAAC;QAC7C,wCAAwC;QACxC,MAAM,aAAa,GAAG,CAAC,MAAM,IAAI,CAAC,QAAQ,CACxC,CAAC,IAAI,EAAE,EAAE;YACP,OAAQ,MAAc,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC,EACD,EAAE,MAAM,EAAE,KAAK,EAAE,CAClB,CAAe,CAAC;QAEjB,IAAI,aAAa,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACvC,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC;YAC1C,IAAI,CAAC;gBACH,MAAM,eAAe,GAAG,IAAI,kBAAe,CAAC;oBAC1C,YAAY,EAAE,KAAK;oBACnB,EAAE,EAAE,KAAK;oBACT,gBAAgB,EAAE,GAAG;oBACrB,cAAc,EAAE,QAAQ;oBACxB,WAAW,EAAE,GAAG;iBACjB,CAAC,CAAC;gBAEH,uCAAuC;gBACvC,eAAe,CAAC,OAAO,CAAC,eAAe,EAAE;oBACvC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;oBAC9E,WAAW,EAAE,UAAU,OAAO;wBAC5B,OAAO,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC;oBAC/B,CAAC;iBACF,CAAC,CAAC;gBAEH,yCAAyC;gBACzC,eAAe,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAQ,CAAC,CAAC;gBAEzE,MAAM,eAAe,GAAG,eAAe,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;gBAC9D,OAAO;oBACL,MAAM,EAAE,SAAS;oBACjB,GAAG,EAAE,aAAa,CAAC,GAAG;oBACtB,MAAM,EAAE,UAAU;oBAClB,OAAO,EAAE,eAAe;oBACxB,MAAM,EAAE,eAAe,CAAC,MAAM;iBAC/B,CAAC;YACJ,CAAC;YAAC,OAAO,CAAM,EAAE,CAAC;gBAChB,OAAO,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC,OAAO,yCAAyC,CAAC,CAAC;gBAChG,qDAAqD;YACvD,CAAC;QACH,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,0CAA0C,aAAa,CAAC,KAAK,yCAAyC,CAAC,CAAC;YACrH,6DAA6D;QAC/D,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,QAAQ,CACjC,CAAC,IAAI,EAAE,EAAE;QACP,OAAQ,MAAc,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9C,CAAC,EACD,EAAE,MAAM,EAAE,CACX,CAAe,CAAC;IAEjB,OAAO,MAAM,CAAC;AAChB,CAAC"}