explorbot 0.3.5 → 0.4.1

package/dist/src/utils/aria.js

@@ -469,47 +469,17 @@ const formatDiff = (added, removed, toggled, typed = []) => {
     sections.push(...formatDiffSection('added', added), ...formatDiffSection('removed', removed));
     return sections.join('\n');
 };
-const CLOSE_OVERLAY_BUTTON_RE = /^close\s+(modal|dialog|popup|drawer|panel|sheet)\b/i;
-const findOverlayByCloseButton = (nodeList) => {
-    const closeIdx = nodeList.findIndex((n) => n.role === 'button' && CLOSE_OVERLAY_BUTTON_RE.test(n.name || ''));
-    if (closeIdx !== -1) {
-        let heading;
-        for (let i = closeIdx - 1; i >= 0; i--) {
-            if (nodeList[i].role === 'heading' && nodeList[i].name) {
-                heading = nodeList[i];
-                break;
-            }
-        }
-        if (!heading) {
-            for (let i = closeIdx + 1; i < nodeList.length; i++) {
-                if (nodeList[i].role === 'heading' && nodeList[i].name) {
-                    heading = nodeList[i];
-                    break;
-                }
-            }
-        }
-        return { detected: true, type: 'dialog', name: heading?.name || null };
-    }
-    for (const node of nodeList) {
-        const inner = findOverlayByCloseButton(node.children);
-        if (inner)
-            return inner;
-    }
-    return null;
-};
 const findDialogOrModal = (nodes) => {
+    let topmost = null;
     for (const node of nodes) {
-        if (node.role === 'dialog' || node.role === 'alertdialog') {
-            return { detected: true, type: 'dialog', name: node.name || null };
-        }
-        if (node.attributes.modal === true || node.attributes.modal === 'true') {
-            return { detected: true, type: 'modal', name: node.name || null };
+        if (node.role === 'dialog' || node.role === 'alertdialog' || node.attributes.modal === true || node.attributes.modal === 'true') {
+            topmost = { detected: true, type: 'modal', name: node.name || null };
         }
         const child = findDialogOrModal(node.children);
         if (child)
-            return child;
+            topmost = child;
     }
-    return null;
+    return topmost;
 };
 export const compactAriaSnapshot = (snapshot, keepNamed = false, offload) => {
     if (!snapshot)
@@ -547,13 +517,7 @@ export const detectFocusArea = (snapshot) => {
     let tree = parseSnapshot(snapshot);
     tree = unwrapIgnored(tree);
     tree = dropEmpty(tree, { keepNamed: true });
-    const direct = findDialogOrModal(tree);
-    if (direct)
-        return direct;
-    const fallback = findOverlayByCloseButton(tree);
-    if (fallback?.name)
-        return fallback;
-    return { detected: false, type: null, name: null };
+    return findDialogOrModal(tree) ?? { detected: false, type: null, name: null };
 };
 export const collectInteractiveNodes = (snapshot) => {
     let tree = parseSnapshot(snapshot);

package/dist/src/utils/html-diff.d.ts

@@ -2,14 +2,17 @@ import type { HtmlConfig } from '../config.js';
 export interface HtmlDiffPart {
     container: string;
     subtree: string;
+    rawSize: number;
     added: string[];
     removed: string[];
+    appearedSelector?: string;
 }
 export interface HtmlDiffResult {
     parts: HtmlDiffPart[];
     added: string[];
     removed: string[];
     similarity: number;
+    pageSize: number;
     summary: string;
     messages: string[];
 }
@@ -22,3 +25,4 @@ export declare function htmlDiff(originalHtml: string, modifiedHtml: string, htm
  * Text the app announced across a navigation. Only live regions: everything else on a new page is its content, not a message.
  */
 export declare function liveRegionMessages(originalHtml: string, modifiedHtml: string): string[];
+export declare function pathToXPath(treePath: string): string;

package/dist/src/utils/html-diff.js

@@ -2,6 +2,8 @@ import { parse, serialize } from 'parse5';
 import { TAILWIND_CLASS_PATTERNS, TRASH_HTML_CLASSES, minifyHtml } from "./html.js";
 import { isDynamicId, isGenericClass } from "./xpath.js";
 const IGNORED_PATHS = new Set(['html[1]', 'html[1]/head[1]', 'html[1]/body[1]']);
+const SHELL_RATIO = 0.8;
+const ROOT_CONTENT_RATIO = 0.8;
 const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log']);
 const TEXT_LINE_PREFIX = 'TEXT:';
 const MESSAGE_MAX_LENGTH = 200;
@@ -147,7 +149,11 @@ export async function htmlDiff(originalHtml, modifiedHtml, htmlConfig) {
     const { added, removed } = findDifferences(originalLines, modifiedLines);
     const originalMap = collectElementMap(originalDocument);
     const modifiedMap = collectElementMap(modifiedDocument);
-    const parts = await buildDiffParts(originalMap, modifiedMap);
+    const modifiedBody = findBodyElement(modifiedDocument);
+    let pageSize = modifiedHtml.length;
+    if (modifiedBody)
+        pageSize = serializeNode(modifiedBody).length;
+    const parts = await buildDiffParts(originalMap, modifiedMap, pageSize);
     const structuralAdditions = parts.flatMap((p) => p.added.filter((a) => a.startsWith('ELEMENT:')));
     const allAdded = [...added, ...structuralAdditions];
     const totalChanges = allAdded.length + removed.length;
@@ -157,10 +163,14 @@ export async function htmlDiff(originalHtml, modifiedHtml, htmlConfig) {
         added: allAdded,
         removed,
         similarity,
+        pageSize,
         summary,
         messages: collectMessages(originalMap, modifiedMap, allAdded),
     };
 }
+function serializeNode(node) {
+    return serialize({ childNodes: [node], nodeName: '#document-fragment' });
+}
 /**
  * Text the app announced while the page stayed the same: live region content first, then any other text that appeared.
  */
@@ -392,14 +402,14 @@ function buildContainerSelector(element, allElements) {
     }
     return matchCount === 1 ? selector : null;
 }
-function pathToXPath(treePath) {
+export function pathToXPath(treePath) {
     const parts = treePath.split('/');
     const bodyIdx = parts.findIndex((p) => p.startsWith('body'));
     if (bodyIdx === -1)
         return `//${parts.join('/')}`;
     return `//body/${parts.slice(bodyIdx + 1).join('/')}`;
 }
-function findStableContainer(topLevelPath, originalMap, modifiedMap) {
+function findStableContainer(topLevelPath, originalMap, modifiedMap, pageSize) {
     const segments = topLevelPath.split('/');
     for (let i = segments.length - 2; i >= 1; i--) {
         const candidatePath = segments.slice(0, i + 1).join('/');
@@ -408,6 +418,8 @@ function findStableContainer(topLevelPath, originalMap, modifiedMap) {
         if (!originalMap.has(candidatePath) || !modifiedMap.has(candidatePath))
             continue;
         const element = modifiedMap.get(candidatePath);
+        if (pageSize > 0 && serializeNode(element).length >= SHELL_RATIO * pageSize)
+            break;
         const css = buildContainerSelector(element, modifiedMap);
         if (css)
             return { path: candidatePath, selector: css };
@@ -415,7 +427,32 @@ function findStableContainer(topLevelPath, originalMap, modifiedMap) {
     }
     return { path: 'html[1]/body[1]', selector: 'body' };
 }
-async function buildDiffParts(originalMap, modifiedMap) {
+function dominantChild(element) {
+    const children = (element.childNodes ?? []).filter((child) => 'tagName' in child && !!child.tagName);
+    if (children.length === 0)
+        return null;
+    if (children.length === 1)
+        return children[0];
+    const parentSize = serializeNode(element).length;
+    if (!parentSize)
+        return null;
+    for (const child of children) {
+        if (serializeNode(child).length >= ROOT_CONTENT_RATIO * parentSize)
+            return child;
+    }
+    return null;
+}
+function semanticSelectorFor(element, allElements) {
+    let current = element;
+    while (current) {
+        const selector = buildContainerSelector(current, allElements);
+        if (selector)
+            return selector;
+        current = dominantChild(current);
+    }
+    return undefined;
+}
+async function buildDiffParts(originalMap, modifiedMap, pageSize) {
     const addedPaths = [];
     const changedPaths = [];
     for (const [path, element] of modifiedMap.entries()) {
@@ -438,7 +475,7 @@ async function buildDiffParts(originalMap, modifiedMap) {
     const allTopLevel = [...addedTopLevel, ...changedTopLevel];
     const grouped = new Map();
     for (const path of allTopLevel) {
-        const { path: containerPath, selector } = findStableContainer(path, originalMap, modifiedMap);
+        const { path: containerPath, selector } = findStableContainer(path, originalMap, modifiedMap, pageSize);
         const existing = grouped.get(containerPath);
         if (existing) {
             existing.paths.push(path);
@@ -482,9 +519,27 @@ async function buildDiffParts(originalMap, modifiedMap) {
         const subtree = serialized ? await minifyHtml(serialized) : '';
         if (!subtree)
             continue;
-        const addedLines = paths.filter((p) => addedTopLevel.includes(p)).map((p) => `ELEMENT:${p}`);
+        const appearedPaths = paths.filter((p) => addedTopLevel.includes(p));
+        const sizeOf = (p) => {
+            const node = modifiedMap.get(p);
+            if (!node)
+                return 0;
+            return serializeNode(node).length;
+        };
+        appearedPaths.sort((a, b) => sizeOf(b) - sizeOf(a));
+        const addedLines = appearedPaths.map((p) => `ELEMENT:${p}`);
         const removedLines = [];
-        parts.push({ container: selector, subtree, added: addedLines, removed: removedLines });
+        const part = { container: selector, subtree, rawSize: serialized.length, added: addedLines, removed: removedLines };
+        const appearedPath = appearedPaths[0];
+        if (appearedPath) {
+            const appearedElement = modifiedMap.get(appearedPath);
+            if (appearedElement) {
+                const appearedSelector = semanticSelectorFor(appearedElement, modifiedMap);
+                if (appearedSelector)
+                    part.appearedSelector = appearedSelector;
+            }
+        }
+        parts.push(part);
     }
     return parts;
 }

package/dist/src/utils/html.d.ts

@@ -16,16 +16,11 @@ export declare const HTML_SELECTORS: {
     readonly semanticContextContainer: "section, article, form, fieldset, li, tr, td, th, [role=\"group\"], [role=\"tabpanel\"], [role=\"region\"], [class*=\"card\"], [class*=\"panel\"], [class*=\"item\"], [class*=\"usage\"], [class*=\"group\"]";
 };
 export declare const HTML_VISIBILITY_LIMITS: {
-    readonly maxViewportOverlayRatio: 0.95;
     readonly minOpacity: 0.1;
-    readonly minOverlayHeight: 40;
-    readonly minOverlayWidth: 80;
 };
 export declare const HTML_EXTRACTION_LIMITS: {
     readonly componentScopeHtmlLength: 8000;
-    readonly maxOverlayCount: 3;
     readonly maxScopeInteractiveCount: 16;
-    readonly overlayHtmlLength: 6000;
 };
 export declare const CODE_EDITOR_MARKERS: readonly ["monaco", "codemirror", "ace", "ace_editor", "code"];
 export declare const HTML_INTERACTIVE_ROLES: Set<string>;
@@ -62,14 +57,6 @@ export declare const ELEMENT_EXTRACTION_CONFIG: {
 };
 export type ElementExtractionConfig = typeof ELEMENT_EXTRACTION_CONFIG;
 export type RawElementData = NonNullable<ReturnType<typeof extractElementData>>;
-export type VisibleOverlayExtractionConfig = {
-    interactiveContentSelector: string;
-    limits: typeof HTML_EXTRACTION_LIMITS;
-    overlaySelectors: readonly string[];
-    overlaySemanticSelector: string;
-    visibilityLimits: typeof HTML_VISIBILITY_LIMITS;
-    geometryFallback?: boolean;
-};
 export type ComponentScopeExtractionConfig = {
     eidxAttr: string;
     interactiveControlSelector: string;
@@ -85,9 +72,7 @@ export declare function extractElementData(el: Element, config?: ElementExtracti
     y: number;
 };
 export declare function getElementDataExtractorSource(): string;
-export declare function extractVisibleOverlayHtml(config: VisibleOverlayExtractionConfig): string;
 export declare function extractComponentScopeHtml(eidx: string, config: ComponentScopeExtractionConfig): string;
-export declare function getVisibleOverlayHtmlExtractorSource(): string;
 export declare function getComponentScopeHtmlExtractorSource(): string;
 export declare const TRASH_HTML_CLASSES: RegExp;
 export declare const TAILWIND_CLASS_PATTERNS: RegExp[];
@@ -106,6 +91,11 @@ export declare function minifyHtml(html: string): Promise<string>;
 export declare function htmlCombinedSnapshot(html: string, htmlConfig?: HtmlConfig['combined'], opts?: {
     keepPositions?: boolean;
 }): string;
+/**
+ * Cleans a small HTML snippet for AI consumption: keeps structure and text,
+ * drops noisy attributes and generated class names
+ */
+export declare function cleanHtmlSnippet(html: string): string;
 /**
  * Creates text-only snapshot with markdown formatting
  */

package/dist/src/utils/html.js

@@ -81,16 +81,11 @@ export const HTML_SELECTORS = {
     semanticContextContainer: 'section, article, form, fieldset, li, tr, td, th, [role="group"], [role="tabpanel"], [role="region"], [class*="card"], [class*="panel"], [class*="item"], [class*="usage"], [class*="group"]',
 };
 export const HTML_VISIBILITY_LIMITS = {
-    maxViewportOverlayRatio: 0.95,
     minOpacity: 0.1,
-    minOverlayHeight: 40,
-    minOverlayWidth: 80,
 };
 export const HTML_EXTRACTION_LIMITS = {
     componentScopeHtmlLength: 8000,
-    maxOverlayCount: 3,
     maxScopeInteractiveCount: 16,
-    overlayHtmlLength: 6000,
 };
 export const CODE_EDITOR_MARKERS = ['monaco', 'codemirror', 'ace', 'ace_editor', 'code'];
 export const HTML_INTERACTIVE_ROLES = new Set(['button', 'link', 'checkbox', 'radio', 'switch', 'tab', 'combobox', 'iframe', 'code-editor', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'slider', 'spinbutton', 'textbox', 'searchbox', 'treeitem']);
@@ -411,83 +406,6 @@ export function extractElementData(el, config) {
 export function getElementDataExtractorSource() {
     return extractElementData.toString();
 }
-export function extractVisibleOverlayHtml(config) {
-    function isVisible(element) {
-        const html = element;
-        const style = window.getComputedStyle(html);
-        const rect = html.getBoundingClientRect();
-        if (rect.width === 0 && rect.height === 0)
-            return false;
-        if (style.display === 'none' || style.visibility === 'hidden')
-            return false;
-        if (Number.parseFloat(style.opacity || '1') < config.visibilityLimits.minOpacity)
-            return false;
-        return true;
-    }
-    function getUsefulContent(element) {
-        const text = (element.textContent || '').replace(/\s+/g, ' ').trim();
-        const interactiveCount = element.querySelectorAll(config.interactiveContentSelector).length;
-        return { interactiveCount, text };
-    }
-    function isLikelyFloatingOverlay(element) {
-        const html = element;
-        const style = window.getComputedStyle(html);
-        const rect = html.getBoundingClientRect();
-        const zIndex = Number.parseInt(style.zIndex || '0', 10);
-        const isFloating = style.position === 'fixed' || style.position === 'absolute' || style.position === 'sticky' || zIndex > 0;
-        if (!isFloating)
-            return false;
-        if (rect.width < config.visibilityLimits.minOverlayWidth || rect.height < config.visibilityLimits.minOverlayHeight)
-            return false;
-        if (rect.bottom < 0 || rect.right < 0 || rect.top > window.innerHeight || rect.left > window.innerWidth)
-            return false;
-        if (rect.width >= window.innerWidth * config.visibilityLimits.maxViewportOverlayRatio && rect.height >= window.innerHeight * config.visibilityLimits.maxViewportOverlayRatio)
-            return false;
-        const { interactiveCount, text } = getUsefulContent(element);
-        return interactiveCount > 0 || text.length > 0;
-    }
-    function isFloatingOverlay(element) {
-        const style = window.getComputedStyle(element);
-        return style.position === 'fixed' || style.position === 'absolute' || Number.parseInt(style.zIndex || '0', 10) > 0;
-    }
-    const seen = new Set();
-    const collected = [];
-    for (const selector of config.overlaySelectors) {
-        for (const element of Array.from(document.querySelectorAll(selector))) {
-            if (seen.has(element))
-                continue;
-            seen.add(element);
-            if (!isVisible(element))
-                continue;
-            if (!element.matches(config.overlaySemanticSelector) && !isFloatingOverlay(element))
-                continue;
-            const { interactiveCount, text } = getUsefulContent(element);
-            if (interactiveCount === 0 && text.length === 0)
-                continue;
-            collected.push(element);
-        }
-    }
-    const overlays = collected.filter((element) => !collected.some((other) => other !== element && element.contains(other))).map((element) => element.outerHTML.slice(0, config.limits.overlayHtmlLength));
-    if (overlays.length === 0 && config.geometryFallback !== false) {
-        const floatingCandidates = Array.from(document.body.querySelectorAll('*'))
-            .filter((element) => !seen.has(element) && isVisible(element) && isLikelyFloatingOverlay(element))
-            .sort((left, right) => {
-            const leftStyle = window.getComputedStyle(left);
-            const rightStyle = window.getComputedStyle(right);
-            const leftZ = Number.parseInt(leftStyle.zIndex || '0', 10) || 0;
-            const rightZ = Number.parseInt(rightStyle.zIndex || '0', 10) || 0;
-            if (leftZ !== rightZ)
-                return rightZ - leftZ;
-            const leftRect = left.getBoundingClientRect();
-            const rightRect = right.getBoundingClientRect();
-            return leftRect.width * leftRect.height - rightRect.width * rightRect.height;
-        });
-        for (const element of floatingCandidates.slice(0, config.limits.maxOverlayCount)) {
-            overlays.push(element.outerHTML.slice(0, config.limits.overlayHtmlLength));
-        }
-    }
-    return overlays.slice(0, config.limits.maxOverlayCount).join('\n\n--- overlay ---\n\n');
-}
 export function extractComponentScopeHtml(eidx, config) {
     const element = document.querySelector(`[${config.eidxAttr}="${eidx}"]`);
     if (!element)
@@ -507,9 +425,6 @@ export function extractComponentScopeHtml(eidx, config) {
         return element.outerHTML.slice(0, config.limits.componentScopeHtmlLength);
     return '';
 }
-export function getVisibleOverlayHtmlExtractorSource() {
-    return extractVisibleOverlayHtml.toString();
-}
 export function getComponentScopeHtmlExtractorSource() {
     return extractComponentScopeHtml.toString();
 }
@@ -927,6 +842,19 @@ export function htmlCombinedSnapshot(html, htmlConfig, opts) {
     cleanAllElements(body);
     return serialize(document);
 }
+/**
+ * Cleans a small HTML snippet for AI consumption: keeps structure and text,
+ * drops noisy attributes and generated class names
+ */
+export function cleanHtmlSnippet(html) {
+    const fragment = parseFragment(html);
+    for (const node of fragment.childNodes) {
+        if (!('tagName' in node))
+            continue;
+        cleanAllElements(node);
+    }
+    return serialize(fragment);
+}
 /**
  * Creates text-only snapshot with markdown formatting
  */
@@ -1381,6 +1309,7 @@ function cleanElement(element) {
         if (attr.name === 'class') {
             attr.value = attr.value
                 .split(/\s+/)
+                .filter(Boolean)
                 .filter((className) => !/\d/.test(className))
                 .filter((className) => !className.includes(':'))
                 .filter((className) => !TAILWIND_CLASS_PATTERNS.some((pattern) => pattern.test(className)))

package/dist/src/utils/overlay.d.ts

@@ -1,24 +1,69 @@
-import { type VisibleOverlayExtractionConfig } from './html.js';
-export declare const OVERLAY_SELECTORS: {
-    readonly semanticOverlays: readonly ["[role=\"dialog\"]", "[role=\"listbox\"]", "[role=\"menu\"]", "[role=\"tooltip\"]:not([style*=\"display: none\"]):not([style*=\"visibility: hidden\"])", "[class*=\"modal\"]", "[class*=\"dialog\"]", "[class*=\"overlay\"]", "[class*=\"popup\"]", "[class*=\"drawer\"]", "[class*=\"lightbox\"]"];
-    readonly modalOverlays: readonly ["[role=\"dialog\"]", "[role=\"alertdialog\"]", "[aria-modal=\"true\"]", "[class*=\"modal\"]", "[class*=\"dialog\"]", "[class*=\"overlay\"]", "[class*=\"popup\"]", "[class*=\"drawer\"]", "[class*=\"lightbox\"]"];
-    readonly overlaySemanticSelector: "[role=\"dialog\"], [role=\"alertdialog\"], [aria-modal=\"true\"], [role=\"listbox\"], [role=\"menu\"], [role=\"tooltip\"]";
-};
+import type { HtmlDiffPart } from './html-diff.js';
+export type OverlayType = 'modal' | 'region';
 export type OverlayData = {
-    type?: 'dialog' | 'modal' | null;
+    type?: OverlayType | null;
     name?: string | null;
+    root?: string | null;
+    html?: string | null;
+    xpath?: string | null;
+    parent?: OverlayData | null;
 };
 export declare class Overlay {
-    readonly type: 'dialog' | 'modal' | null;
+    readonly type: OverlayType | null;
     readonly name: string | null;
+    readonly root: string | null;
+    readonly html: string | null;
+    readonly xpath: string | null;
+    readonly parent: OverlayData | null;
     constructor(data?: OverlayData);
     get detected(): boolean;
-    static fromHtml(html: string): Overlay;
+    get present(): boolean;
+    describe(): string;
+    withGeometry(geometry: Overlay): Overlay;
+    withParent(parent: Overlay): Overlay;
     static fromAria(snapshot: string | null): Overlay;
     static resolve(data: {
-        overlayHtml?: string;
         overlay?: OverlayData | null;
         ariaSnapshot?: string | null;
     }): Overlay;
-    static captureConfig(): VisibleOverlayExtractionConfig;
 }
+export declare class OverlayPage {
+    page: {
+        evaluate(fn: any, arg: any): Promise<any>;
+    } | null;
+    constructor(page: {
+        evaluate(fn: any, arg: any): Promise<any>;
+    } | null);
+    detectRegion(diff: RegionDiff): Promise<Overlay | null>;
+    isStillOpen(overlay: Overlay): Promise<boolean>;
+    appearedSubRoots(diff: RegionDiff): AppearedSubRoot[];
+    probe(xpath: string): Promise<RegionProbe | null>;
+    toOverlay(subRoot: AppearedSubRoot, probe: RegionProbe | null, previousHtml: string): Overlay;
+    nameFrom(html: string, previousHtml: string): string | null;
+    freshHeading(html: string, previousHtml: string): string | null;
+    headingsOf(html: string): string[];
+}
+export interface RegionDiff {
+    parts: HtmlDiffPart[];
+    pageSize: number;
+    similarity: number;
+    sameUrl: boolean;
+    previousHtml: string;
+}
+interface AppearedSubRoot {
+    container: string;
+    elementXPath: string;
+    subtree: string;
+    size: number;
+    rawSize: number;
+    appearedSelector?: string;
+    fresh: boolean;
+}
+interface RegionProbe {
+    found: boolean;
+    onScreen: boolean;
+    floating: boolean;
+    centerBelongs: boolean;
+    coveredByFloating: boolean;
+}
+export {};