explorbot 0.3.4 → 0.4.0

package/src/commands/plans-command.ts

@@ -79,15 +79,15 @@ export class PlansCommand extends BaseCommand {
       return file;
     }
 
-    const resolved = this.explorBot.resolvePlanPath(target);
-    if (!existsSync(resolved)) {
-      throw new Error(`Plan file not found: ${resolved}`);
+    const plan = Plan.loadFromFile(target, this.explorBot.getPlansDir());
+    if (!plan?.filePath) {
+      throw new Error(`Plan file not found: ${target}`);
     }
 
     return {
-      name: path.basename(resolved),
-      path: resolved,
-      modifiedAt: statSync(resolved).mtimeMs,
+      name: path.basename(plan.filePath),
+      path: plan.filePath,
+      modifiedAt: statSync(plan.filePath).mtimeMs,
     };
   }
 }

package/src/config.ts

@@ -273,6 +273,7 @@ export const EXPLORBOT_ENV_VARS: EnvVar[] = [
   { name: 'EXPLORBOT_KNOWLEDGE_FILE', description: 'Path to a knowledge markdown file' },
   { name: 'EXPLORBOT_API_SPEC', description: 'OpenAPI spec path for the API boat' },
   { name: 'EXPLORBOT_NO_BANNER', description: 'Suppress the startup banner, for machine-readable output' },
+  { name: 'EXPLORBOT_MAX_DURATION', description: 'Wall-clock budget in minutes for an explore run; same as --max-duration' },
 ];
 
 export type {

package/src/experience-tracker.ts

@@ -123,10 +123,14 @@ export class ExperienceTracker {
     const filePath = this.getExperienceFilePath(stateHash);
 
     if (!existsSync(filePath)) {
-      const frontmatter = {
+      const frontmatter: Record<string, unknown> = {
         url: state.url ? extractStatePath(state.url) : '',
         title: state.title,
       };
+      if (state.overlay.present && state.overlay.name) {
+        frontmatter.region = state.overlay.name;
+        if (state.overlay.root) frontmatter.root = state.overlay.root;
+      }
       this.writeExperienceFile(stateHash, '', frontmatter);
     }
 

package/src/explorbot.ts

@@ -346,14 +346,22 @@ export class ExplorBot {
         }
       };
 
-      const cookieProvider = async (): Promise<Record<string, string>> => {
-        const cookies = await this.explorer.withPage((page) => page.context().cookies()).catch(() => []);
-        if (!cookies.length) return {};
-        return { Cookie: cookies.map((c: any) => `${c.name}=${c.value}`).join('; ') };
+      const browserHeaderProvider = async (): Promise<Record<string, string>> => {
+        const session = await this.explorer
+          .withPage(async (page) => ({
+            cookies: await page.context().cookies(baseEndpoint),
+            csrf: await page.evaluate(() => document.querySelector('meta[name="csrf-token"]')?.getAttribute('content') || '').catch(() => ''),
+          }))
+          .catch(() => ({ cookies: [] as any[], csrf: '' }));
+
+        const headers: Record<string, string> = {};
+        if (session.cookies.length) headers.Cookie = session.cookies.map((c: any) => `${c.name}=${c.value}`).join('; ');
+        if (session.csrf) headers['x-csrf-token'] = session.csrf;
+        return headers;
       };
 
       this.agents.fisherman = this.createAgent(({ ai }) => {
-        return new Fisherman(ai, apiClient, requestStore, specLoader, baseEndpoint, cookieProvider, configHeaders, hasApiConfig);
+        return new Fisherman(ai, apiClient, requestStore, specLoader, baseEndpoint, browserHeaderProvider, configHeaders, hasApiConfig);
       });
     }
     return this.agents.fisherman;
@@ -449,41 +457,17 @@ export class ExplorBot {
     return urlPart + featurePart.slice(0, maxFeatureLen) + suffix;
   }
 
-  resolvePlanPath(filename: string): string {
-    let planPath = filename;
-
-    if (path.isAbsolute(filename)) {
-      if (!existsSync(planPath) && !filename.endsWith('.md')) {
-        planPath = `${filename}.md`;
-      }
-    } else if (existsSync(filename) || existsSync(`${filename}.md`)) {
-      planPath = existsSync(filename) ? filename : `${filename}.md`;
-    } else {
-      const plansDir = this.getPlansDir();
-      planPath = path.join(plansDir, filename);
-      if (!existsSync(planPath) && !filename.endsWith('.md')) {
-        planPath = path.join(plansDir, `${filename}.md`);
-      }
-    }
-
-    return planPath;
-  }
-
   loadPlan(filename: string): Plan {
-    const planPath = this.resolvePlanPath(filename);
-    if (!existsSync(planPath)) {
-      throw new Error(`Plan file not found: ${planPath}`);
-    }
-    this.setCurrentPlan(Plan.fromMarkdown(planPath));
-    return this.currentPlan!;
+    const plan = Plan.loadFromFile(filename, this.getPlansDir());
+    if (!plan) throw new Error(`Plan file not found: ${filename}`);
+    this.setCurrentPlan(plan);
+    return plan;
   }
 
   loadPlans(filename: string): Plan[] {
-    const planPath = this.resolvePlanPath(filename);
-    if (!existsSync(planPath)) {
-      throw new Error(`Plan file not found: ${planPath}`);
-    }
-    return parsePlansFromMarkdown(planPath);
+    const plan = Plan.loadFromFile(filename, this.getPlansDir());
+    if (!plan?.filePath) throw new Error(`Plan file not found: ${filename}`);
+    return parsePlansFromMarkdown(plan.filePath);
   }
 
   setCurrentPlan(plan?: Plan): void {

package/src/state-manager.ts

@@ -50,6 +50,10 @@ export interface WebPageState {
   links?: Link[];
   verifications?: Record<string, boolean>;
   overlay?: Overlay;
+  /** Region name, the persisted scalar form of overlay.name used in experience frontmatter */
+  region?: string;
+  /** Region root selector, the persisted scalar form of overlay.root used in experience frontmatter */
+  root?: string;
 }
 
 export interface StateTransition {
@@ -119,7 +123,9 @@ export class StateManager {
    */
   private emitStateChange(event: StateTransition): void {
     const state = event.toState;
-    tag('data').log('state', { url: state.fullUrl || state.url, path: state.url, title: state.title, h1: state.h1 });
+    const payload: Record<string, unknown> = { url: state.fullUrl || state.url, path: state.url, title: state.title, h1: state.h1 };
+    if (state.overlay?.present) payload.region = state.overlay.name || state.overlay.type;
+    tag('data').log('state', payload);
 
     this.stateChangeListeners.forEach((listener) => {
       try {
@@ -143,9 +149,9 @@ export class StateManager {
     if (newState.url) this.allVisitedUrls.add(normalizeUrl(newState.url));
 
     const hashChanged = actionResult.hash !== previousHash;
-    const dialogOpened = !hashChanged && this.hasDialogAppeared(previousState, newState);
+    const regionAppeared = !hashChanged && this.hasRegionAppeared(previousState, newState);
 
-    if (hashChanged || dialogOpened) {
+    if (hashChanged || regionAppeared) {
       const transition: StateTransition = {
         fromState: previousState,
         toState: newState,
@@ -156,8 +162,8 @@ export class StateManager {
       this.stateHistory.push(transition);
       this.emitStateChange(transition);
 
-      if (dialogOpened) {
-        debugLog('State change detected: modal dialog appeared');
+      if (regionAppeared) {
+        debugLog('State change detected: region of interest appeared');
       }
     }
 
@@ -206,10 +212,10 @@ export class StateManager {
     return newState;
   }
 
-  private hasDialogAppeared(previousState: WebPageState | null, newState: WebPageState): boolean {
+  private hasRegionAppeared(previousState: WebPageState | null, newState: WebPageState): boolean {
     const prevFocus = previousState?.overlay ?? Overlay.fromAria(previousState?.ariaSnapshot ?? null);
     const newFocus = newState.overlay ?? Overlay.fromAria(newState.ariaSnapshot ?? null);
-    return !prevFocus.detected && newFocus.detected;
+    return !prevFocus.present && newFocus.present;
   }
 
   /**

package/src/test-plan.ts

@@ -1,6 +1,9 @@
 import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
 import figures from 'figures';
 import type { ActionResult } from './action-result.ts';
+import { listSites } from './global-config.ts';
 import { WebPageState } from './state-manager.ts';
 import { tag } from './utils/logger.ts';
 import { parsePlanFromMarkdown, planToAiContext, savePlanToMarkdown, savePlansToMarkdown } from './utils/test-plan-markdown.ts';
@@ -388,12 +391,15 @@ export class Test extends Task {
   }
 }
 
+const SITE_PLANS_DIR = ['output', 'plans'];
+
 type PlanChangeListener = (tests: Test[]) => void;
 
 export class Plan {
   title: string;
   tests: Test[] = [];
   url?: string;
+  filePath?: string;
   iteration = 0;
   parentPlan?: Plan;
   private changeListeners: PlanChangeListener[] = [];
@@ -455,6 +461,10 @@ export class Plan {
     return this.tests.filter((test) => test.status === 'pending' && test.enabled);
   }
 
+  get startUrl(): string | undefined {
+    return this.url || this.tests[0]?.startUrl;
+  }
+
   get isComplete(): boolean {
     return this.tests.length > 0 && this.tests.every((test) => test.hasFinished);
   }
@@ -469,6 +479,25 @@ export class Plan {
 
   updateStatus(): void {}
 
+  static loadFromFile(file: string, plansDir?: string): Plan | null {
+    const names = [file];
+    if (!file.endsWith('.md')) names.push(`${file}.md`);
+
+    const dirs = [process.cwd()];
+    if (plansDir) dirs.push(plansDir);
+    if (!plansDir) dirs.push(...listSites().map((site) => path.join(site.dir, ...SITE_PLANS_DIR)));
+
+    for (const dir of dirs) {
+      const filePath = names.map((name) => path.resolve(dir, name)).find(existsSync);
+      if (!filePath) continue;
+      const loaded = parsePlanFromMarkdown(filePath);
+      loaded.filePath = filePath;
+      return loaded;
+    }
+
+    return null;
+  }
+
   static fromMarkdown(filePath: string): Plan {
     return parsePlanFromMarkdown(filePath);
   }

package/src/utils/aria.ts

@@ -470,51 +470,20 @@ const formatDiff = (added: string[], removed: string[], toggled: string[], typed
 
 export interface FocusAreaResult {
   detected: boolean;
-  type: 'dialog' | 'modal' | null;
+  type: 'modal' | null;
   name: string | null;
 }
 
-const CLOSE_OVERLAY_BUTTON_RE = /^close\s+(modal|dialog|popup|drawer|panel|sheet)\b/i;
-
-const findOverlayByCloseButton = (nodeList: AriaNode[]): FocusAreaResult | null => {
-  const closeIdx = nodeList.findIndex((n) => n.role === 'button' && CLOSE_OVERLAY_BUTTON_RE.test(n.name || ''));
-  if (closeIdx !== -1) {
-    let heading: AriaNode | undefined;
-    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: AriaNode[]): FocusAreaResult | null => {
+  let topmost: FocusAreaResult | null = 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;
+    if (child) topmost = child;
   }
-  return null;
+  return topmost;
 };
 
 // ─────────────────────────────────────────────────────────────────
@@ -561,13 +530,7 @@ export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {
   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: string | null): Array<Record<string, unknown>> => {

package/src/utils/html-diff.ts

@@ -7,8 +7,10 @@ import { isDynamicId, isGenericClass } from './xpath.ts';
 export interface HtmlDiffPart {
   container: string;
   subtree: string;
+  rawSize: number;
   added: string[];
   removed: string[];
+  appearedSelector?: string;
 }
 
 export interface HtmlDiffResult {
@@ -16,6 +18,7 @@ export interface HtmlDiffResult {
   added: string[];
   removed: string[];
   similarity: number;
+  pageSize: number;
   summary: string;
   messages: string[];
 }
@@ -30,6 +33,9 @@ interface HtmlNode {
 
 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;
@@ -211,7 +217,12 @@ export async function htmlDiff(originalHtml: string, modifiedHtml: string, htmlC
 
   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];
@@ -223,11 +234,16 @@ export async function htmlDiff(originalHtml: string, modifiedHtml: string, htmlC
     added: allAdded,
     removed,
     similarity,
+    pageSize,
     summary,
     messages: collectMessages(originalMap, modifiedMap, allAdded),
   };
 }
 
+function serializeNode(node: parse5TreeAdapter.Node): string {
+  return serialize({ childNodes: [node], nodeName: '#document-fragment' } as any);
+}
+
 /**
  * Text the app announced while the page stayed the same: live region content first, then any other text that appeared.
  */
@@ -492,14 +508,14 @@ function buildContainerSelector(element: ElementNode, allElements: NodeMap): str
   return matchCount === 1 ? selector : null;
 }
 
-function pathToXPath(treePath: string): string {
+export function pathToXPath(treePath: string): string {
   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: string, originalMap: NodeMap, modifiedMap: NodeMap): { path: string; selector: string } {
+function findStableContainer(topLevelPath: string, originalMap: NodeMap, modifiedMap: NodeMap, pageSize: number): { path: string; selector: string } {
   const segments = topLevelPath.split('/');
 
   for (let i = segments.length - 2; i >= 1; i--) {
@@ -508,6 +524,7 @@ function findStableContainer(topLevelPath: string, originalMap: NodeMap, modifie
     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 };
     return { path: candidatePath, selector: pathToXPath(candidatePath) };
@@ -516,7 +533,29 @@ function findStableContainer(topLevelPath: string, originalMap: NodeMap, modifie
   return { path: 'html[1]/body[1]', selector: 'body' };
 }
 
-async function buildDiffParts(originalMap: NodeMap, modifiedMap: NodeMap): Promise<HtmlDiffPart[]> {
+function dominantChild(element: ElementNode): ElementNode | null {
+  const children = (element.childNodes ?? []).filter((child): child is ElementNode => '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: ElementNode, allElements: NodeMap): string | undefined {
+  let current: ElementNode | null = element;
+  while (current) {
+    const selector = buildContainerSelector(current, allElements);
+    if (selector) return selector;
+    current = dominantChild(current);
+  }
+  return undefined;
+}
+
+async function buildDiffParts(originalMap: NodeMap, modifiedMap: NodeMap, pageSize: number): Promise<HtmlDiffPart[]> {
   const addedPaths: string[] = [];
   const changedPaths: string[] = [];
 
@@ -546,7 +585,7 @@ async function buildDiffParts(originalMap: NodeMap, modifiedMap: NodeMap): Promi
   const grouped = new Map<string, { selector: string; paths: string[] }>();
 
   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);
@@ -592,10 +631,26 @@ async function buildDiffParts(originalMap: NodeMap, modifiedMap: NodeMap): Promi
     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: string) => {
+      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: string[] = [];
 
-    parts.push({ container: selector, subtree, added: addedLines, removed: removedLines });
+    const part: HtmlDiffPart = { 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/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)))