explorbot 0.3.5 → 0.4.0

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