explorbot 0.3.5 → 0.4.1

package/src/utils/html.ts

@@ -101,17 +101,12 @@ export const HTML_SELECTORS = {
 } as const;
 
 export const HTML_VISIBILITY_LIMITS = {
-  maxViewportOverlayRatio: 0.95,
   minOpacity: 0.1,
-  minOverlayHeight: 40,
-  minOverlayWidth: 80,
 } as const;
 
 export const HTML_EXTRACTION_LIMITS = {
   componentScopeHtmlLength: 8000,
-  maxOverlayCount: 3,
   maxScopeInteractiveCount: 16,
-  overlayHtmlLength: 6000,
 } as const;
 
 export const CODE_EDITOR_MARKERS = ['monaco', 'codemirror', 'ace', 'ace_editor', 'code'] as const;
@@ -158,14 +153,6 @@ export 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;
@@ -449,80 +436,6 @@ export function getElementDataExtractorSource(): string {
   return extractElementData.toString();
 }
 
-export function extractVisibleOverlayHtml(config: VisibleOverlayExtractionConfig): string {
-  function isVisible(element: Element): boolean {
-    const html = element as HTMLElement;
-    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: Element): { interactiveCount: number; text: string } {
-    const text = (element.textContent || '').replace(/\s+/g, ' ').trim();
-    const interactiveCount = element.querySelectorAll(config.interactiveContentSelector).length;
-    return { interactiveCount, text };
-  }
-
-  function isLikelyFloatingOverlay(element: Element): boolean {
-    const html = element as HTMLElement;
-    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: Element): boolean {
-    const style = window.getComputedStyle(element as HTMLElement);
-    return style.position === 'fixed' || style.position === 'absolute' || Number.parseInt(style.zIndex || '0', 10) > 0;
-  }
-
-  const seen = new Set<Element>();
-  const collected: Element[] = [];
-  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 as HTMLElement).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 as HTMLElement);
-        const rightStyle = window.getComputedStyle(right as HTMLElement);
-        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 as HTMLElement).getBoundingClientRect();
-        const rightRect = (right as HTMLElement).getBoundingClientRect();
-        return leftRect.width * leftRect.height - rightRect.width * rightRect.height;
-      });
-
-    for (const element of floatingCandidates.slice(0, config.limits.maxOverlayCount)) {
-      overlays.push((element as HTMLElement).outerHTML.slice(0, config.limits.overlayHtmlLength));
-    }
-  }
-
-  return overlays.slice(0, config.limits.maxOverlayCount).join('\n\n--- overlay ---\n\n');
-}
-
 export function extractComponentScopeHtml(eidx: string, config: ComponentScopeExtractionConfig): string {
   const element = document.querySelector(`[${config.eidxAttr}="${eidx}"]`);
   if (!element) return '';
@@ -544,10 +457,6 @@ export function extractComponentScopeHtml(eidx: string, config: ComponentScopeEx
   return '';
 }
 
-export function getVisibleOverlayHtmlExtractorSource(): string {
-  return extractVisibleOverlayHtml.toString();
-}
-
 export function getComponentScopeHtmlExtractorSource(): string {
   return extractComponentScopeHtml.toString();
 }
@@ -1020,6 +929,19 @@ export function htmlCombinedSnapshot(html: string, htmlConfig?: HtmlConfig['comb
   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: string): string {
+  const fragment = parseFragment(html);
+  for (const node of fragment.childNodes) {
+    if (!('tagName' in node)) continue;
+    cleanAllElements(node as parse5TreeAdapter.Element);
+  }
+  return serialize(fragment);
+}
+
 /**
  * Creates text-only snapshot with markdown formatting
  */
@@ -1526,6 +1448,7 @@ function cleanElement(element: parse5TreeAdapter.Element): void {
     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/src/utils/overlay.ts

@@ -1,51 +1,254 @@
 import { detectFocusArea } from './aria.js';
-import { HTML_EXTRACTION_LIMITS, HTML_SELECTORS, HTML_VISIBILITY_LIMITS, type VisibleOverlayExtractionConfig, extractHeadings } from './html.js';
+import type { HtmlDiffPart } from './html-diff.js';
+import { pathToXPath } from './html-diff.js';
+import { extractHeadings } from './html.js';
+import { createDebug } from './logger.js';
 
-export const OVERLAY_SELECTORS = {
-  semanticOverlays: ['[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"]'],
-  modalOverlays: ['[role="dialog"]', '[role="alertdialog"]', '[aria-modal="true"]', '[class*="modal"]', '[class*="dialog"]', '[class*="overlay"]', '[class*="popup"]', '[class*="drawer"]', '[class*="lightbox"]'],
-  overlaySemanticSelector: '[role="dialog"], [role="alertdialog"], [aria-modal="true"], [role="listbox"], [role="menu"], [role="tooltip"]',
-} as const;
+const debugLog = createDebug('explorbot:overlay');
 
-export type OverlayData = { type?: 'dialog' | 'modal' | null; name?: string | null };
+export type OverlayType = 'modal' | 'region';
+export type OverlayData = {
+  type?: OverlayType | null;
+  name?: string | null;
+  root?: string | null;
+  html?: string | null;
+  xpath?: string | null;
+  parent?: OverlayData | null;
+};
 
 export 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 = {}) {
     this.type = data.type ?? null;
     this.name = data.name ?? null;
+    this.root = data.root ?? null;
+    this.html = data.html ?? null;
+    this.xpath = data.xpath ?? null;
+    this.parent = data.parent ?? null;
   }
 
   get detected(): boolean {
+    return this.type !== null && this.type !== 'region';
+  }
+
+  get present(): boolean {
     return this.type !== null;
   }
 
-  static fromHtml(html: string): Overlay {
-    const headings = extractHeadings(html);
-    const name = [headings.h1, headings.h2, headings.h3, headings.h4].filter(Boolean).join(' ');
-    return new Overlay({ type: 'modal', name: name || null });
+  describe(): string {
+    if (!this.present) return '';
+    let text = `${this.type} "${this.name || 'unnamed'}" opened`;
+    if (this.root) text += `, scope: ${this.root}`;
+    return text;
+  }
+
+  withGeometry(geometry: Overlay): Overlay {
+    return new Overlay({
+      type: this.type,
+      name: this.name || geometry.name,
+      root: geometry.root,
+      html: geometry.html,
+      xpath: geometry.xpath,
+    });
+  }
+
+  withParent(parent: Overlay): Overlay {
+    return new Overlay({
+      type: this.type,
+      name: this.name,
+      root: this.root,
+      html: this.html,
+      xpath: this.xpath,
+      parent: { type: parent.type, name: parent.name, root: parent.root, xpath: parent.xpath },
+    });
   }
 
   static fromAria(snapshot: string | null): Overlay {
     return new Overlay(detectFocusArea(snapshot));
   }
 
-  static resolve(data: { overlayHtml?: string; overlay?: OverlayData | null; ariaSnapshot?: string | null }): Overlay {
-    if (data.overlayHtml) return Overlay.fromHtml(data.overlayHtml);
+  static resolve(data: { overlay?: OverlayData | null; ariaSnapshot?: string | null }): Overlay {
     if (data.overlay) return new Overlay(data.overlay);
     return Overlay.fromAria(data.ariaSnapshot ?? null);
   }
+}
+
+export class OverlayPage {
+  constructor(private page: { evaluate(fn: any, arg: any): Promise<any> } | null) {}
+
+  async detectRegion(diff: RegionDiff): Promise<Overlay | null> {
+    if (!diff.sameUrl && diff.similarity < SOFT_NAVIGATION_SIMILARITY) return null;
+    for (const subRoot of this.appearedSubRoots(diff)) {
+      const probe = await this.probe(subRoot.elementXPath);
+      if (probe?.found && probe.onScreen && !probe.centerBelongs) {
+        debugLog('Appeared region is hidden or covered, trying the next candidate');
+        continue;
+      }
+      const overlay = this.toOverlay(subRoot, probe, diff.previousHtml);
+      if (!overlay.name && !overlay.root) {
+        debugLog('Appeared region has no name and no semantic root, ignoring it');
+        continue;
+      }
+      debugLog(`Region detected: ${overlay.describe()}`);
+      return overlay;
+    }
+    return null;
+  }
+
+  async isStillOpen(overlay: Overlay): Promise<boolean> {
+    if (!overlay.xpath) return true;
+    const probe = await this.probe(overlay.xpath);
+    if (!probe) return true;
+    if (!probe.found) return false;
+    if (probe.onScreen && !probe.centerBelongs && !probe.coveredByFloating) return false;
+    return true;
+  }
+
+  private appearedSubRoots(diff: RegionDiff): AppearedSubRoot[] {
+    const candidates: AppearedSubRoot[] = [];
+    for (const part of diff.parts) {
+      const appeared = part.added.find((line) => line.startsWith('ELEMENT:'));
+      if (!appeared) continue;
+      if (part.subtree.length < SUBROOT_MIN_HTML) continue;
+      if (diff.pageSize > 0 && part.rawSize > REGION_MAX_RATIO * diff.pageSize) {
+        debugLog(`Appeared subtree spans ${Math.round((part.rawSize / diff.pageSize) * 100)}% of the page — a new state, not a region`);
+        continue;
+      }
+      candidates.push({
+        container: part.container,
+        elementXPath: pathToXPath(appeared.slice('ELEMENT:'.length)),
+        subtree: part.subtree,
+        size: part.subtree.length,
+        rawSize: part.rawSize,
+        appearedSelector: part.appearedSelector,
+        fresh: !!this.freshHeading(part.subtree, diff.previousHtml),
+      });
+    }
+    if (candidates.length === 0) return [];
+    const totalRawSize = candidates.reduce((sum, c) => sum + c.rawSize, 0);
+    const largest = Math.max(...candidates.map((c) => c.rawSize));
+    if (largest < REGION_DOMINANCE * totalRawSize) {
+      debugLog('Changes are scattered across the page, no dominant region');
+      return [];
+    }
+    candidates.sort((a, b) => Number(b.fresh) - Number(a.fresh) || b.size - a.size);
+    return candidates;
+  }
+
+  private async probe(xpath: string): Promise<RegionProbe | null> {
+    if (!this.page) return null;
+    return this.page
+      .evaluate(
+        ({ probeSource, config }: { probeSource: string; config: any }) => {
+          const probe = new Function(`return ${probeSource}`)() as (config: any) => any;
+          return probe(config);
+        },
+        { probeSource: inspectRegion.toString(), config: { xpath } }
+      )
+      .catch((err: Error) => {
+        debugLog('Region probe failed:', err.message);
+        return null;
+      });
+  }
+
+  private toOverlay(subRoot: AppearedSubRoot, probe: RegionProbe | null, previousHtml: string): Overlay {
+    let type: OverlayType = 'region';
+    if (probe?.centerBelongs && probe.floating) type = 'modal';
+    let root: string | null = null;
+    if (subRoot.container !== 'body' && !subRoot.container.startsWith('//')) root = subRoot.container;
+    if (!root && subRoot.appearedSelector) root = subRoot.appearedSelector;
+    return new Overlay({ type, name: this.nameFrom(subRoot.subtree, previousHtml), root, html: subRoot.subtree, xpath: subRoot.elementXPath });
+  }
 
-  static captureConfig(): VisibleOverlayExtractionConfig {
-    return {
-      interactiveContentSelector: HTML_SELECTORS.interactiveContent,
-      limits: HTML_EXTRACTION_LIMITS,
-      overlaySelectors: OVERLAY_SELECTORS.modalOverlays,
-      overlaySemanticSelector: OVERLAY_SELECTORS.overlaySemanticSelector,
-      visibilityLimits: HTML_VISIBILITY_LIMITS,
-      geometryFallback: false,
-    };
+  private nameFrom(html: string, previousHtml: string): string | null {
+    const fresh = this.freshHeading(html, previousHtml);
+    if (fresh) return fresh;
+    const candidates = this.headingsOf(html);
+    if (candidates.length === 0) return null;
+    return candidates.join(' ');
   }
+
+  private freshHeading(html: string, previousHtml: string): string | null {
+    const fresh = this.headingsOf(html).filter((heading) => !previousHtml.includes(heading));
+    return fresh[0] ?? null;
+  }
+
+  private headingsOf(html: string): string[] {
+    const headings = extractHeadings(html);
+    return [headings.h1, headings.h2, headings.h3, headings.h4].filter(Boolean) as string[];
+  }
+}
+
+const SUBROOT_MIN_HTML = 5_000;
+const SOFT_NAVIGATION_SIMILARITY = 50;
+const REGION_MAX_RATIO = 0.6;
+const REGION_DOMINANCE = 0.7;
+
+// Serialized via toString() into page.evaluate — must stay a plain function with no outer-scope references.
+function inspectRegion(config: { xpath: string }): RegionProbe {
+  const probe: RegionProbe = { found: false, onScreen: false, floating: false, centerBelongs: false, coveredByFloating: false };
+
+  const isFloating = (start: HTMLElement | null): boolean => {
+    let node = start;
+    while (node && node !== document.body) {
+      const style = window.getComputedStyle(node);
+      if (style.position === 'fixed' || style.position === 'absolute' || (Number.parseInt(style.zIndex || '0', 10) || 0) > 0) return true;
+      node = node.parentElement;
+    }
+    return false;
+  };
+
+  const result = document.evaluate(config.xpath, document, null, 9, null);
+  const node = result.singleNodeValue;
+  if (!node || node.nodeType !== 1) return probe;
+  const element = node as HTMLElement;
+  const rect = element.getBoundingClientRect();
+  if (rect.width === 0 && rect.height === 0) return probe;
+  probe.found = true;
+
+  probe.floating = isFloating(element);
+
+  const left = Math.max(rect.left, 0);
+  const top = Math.max(rect.top, 0);
+  const right = Math.min(rect.right, window.innerWidth);
+  const bottom = Math.min(rect.bottom, window.innerHeight);
+  if (right <= left || bottom <= top) return probe;
+  probe.onScreen = true;
+
+  const hit = document.elementFromPoint((left + right) / 2, (top + bottom) / 2);
+  probe.centerBelongs = !!hit && (hit === element || element.contains(hit));
+  if (hit && !probe.centerBelongs) probe.coveredByFloating = isFloating(hit as HTMLElement);
+  return probe;
+}
+
+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;
 }

package/src/utils/request-map.ts

@@ -0,0 +1,19 @@
+import type { RequestResult } from '../api/request-result.ts';
+
+export class RequestMap {
+  private requests = new Map<string, RequestResult>();
+
+  constructor(requests: RequestResult[] = []) {
+    for (const request of requests) this.add(request);
+  }
+
+  add(request: RequestResult): void {
+    const { id } = request.extractIdAndTitle();
+    if (id === undefined) return;
+    this.requests.set(String(id), request);
+  }
+
+  get(id: string | number): RequestResult | undefined {
+    return this.requests.get(String(id));
+  }
+}

package/src/utils/url-matcher.ts

@@ -9,14 +9,15 @@ export function isDynamicSegment(segment: string): boolean {
     /* config not loaded yet */
   }
 
+  if (/^v\d+$/i.test(segment)) return false;
   // numeric: /users/123
   if (/^\d+$/.test(segment)) return true;
   // UUID: /items/550e8400-e29b-41d4-a716-446655440000
   if (/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(segment)) return true;
   // ULID: /items/01ARZ3NDEKTSV4RRFFQ69G5FAV
   if (/^[0-9A-HJKMNP-TV-Z]{26}$/.test(segment)) return true;
-  // hex ID (4+ chars): /suite/70dae98a
-  if (/^[a-f0-9]{4,}$/i.test(segment)) return true;
+  // hex ID (4+ chars): /suite/70dae98a — short letters-only hex reads as a word
+  if (/^[a-f0-9]{4,}$/i.test(segment) && (segment.length >= 8 || /\d/.test(segment))) return true;
   // hex-prefixed slug (8+ hex before dash): /suite/95ef0c94-mobile
   if (/^[a-f0-9]{8,}-/i.test(segment)) return true;
   // short mixed alphanumeric (digits + letters, ≤8 chars, no dash): /item/x7f2