explorbot 0.1.32-beta.1 → 0.2.1

package/src/knowledge-tracker.ts

@@ -1,15 +1,19 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import dedent from 'dedent';
 import matter from 'gray-matter';
 import { ActionResult } from './action-result.js';
 import { ConfigParser } from './config.js';
 import { getCliName } from './utils/cli-name.ts';
-import { createDebug } from './utils/logger.js';
+import { createDebug, pluralize, tag } from './utils/logger.js';
+import { loadMarkdownFiles } from './utils/markdown-files.js';
+import { mdq } from './utils/markdown-query.js';
 import { isSecretName, registerSecret } from './utils/secrets.js';
+import { slugify } from './utils/strings.js';
 
 const debugLog = createDebug('explorbot:knowledge-tracker');
 
-interface Knowledge {
+export interface Knowledge {
   filePath: string;
   url: string;
   content: string;
@@ -24,14 +28,7 @@ export class KnowledgeTracker {
   constructor() {
     const configParser = ConfigParser.getInstance();
     const config = configParser.getConfig();
-    const configPath = configParser.getConfigPath();
-
-    if (configPath) {
-      const projectRoot = dirname(configPath);
-      this.knowledgeDir = join(projectRoot, config.dirs?.knowledge || 'knowledge');
-    } else {
-      this.knowledgeDir = config.dirs?.knowledge || 'knowledge';
-    }
+    this.knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
 
     if (!existsSync(this.knowledgeDir)) {
       mkdirSync(this.knowledgeDir, { recursive: true });
@@ -43,29 +40,13 @@ export class KnowledgeTracker {
 
     this.knowledgeFiles = [];
 
-    if (!existsSync(this.knowledgeDir)) {
-      return;
-    }
-
-    const files = readdirSync(this.knowledgeDir)
-      .filter((file) => file.endsWith('.md'))
-      .map((file) => join(this.knowledgeDir, file));
-
-    for (const filePath of files) {
-      try {
-        const fileContent = readFileSync(filePath, 'utf8');
-        const parsed = matter(fileContent);
-        const urlPattern = parsed.data.url || parsed.data.path || '*';
-
-        this.knowledgeFiles.push({
-          filePath,
-          url: urlPattern,
-          content: this.interpolateVars(parsed.content),
-          ...parsed.data,
-        });
-      } catch (error) {
-        // Skip invalid files
-      }
+    for (const entry of loadMarkdownFiles(this.knowledgeDir, { recursive: true })) {
+      this.knowledgeFiles.push({
+        filePath: entry.filePath,
+        url: entry.data.url || entry.data.path || '*',
+        content: this.interpolateVars(entry.content),
+        ...entry.data,
+      });
     }
 
     this.isLoaded = true;
@@ -79,25 +60,40 @@ export class KnowledgeTracker {
     });
   }
 
+  renderRelevantKnowledge(state: ActionResult): string {
+    const knowledgeFiles = this.getRelevantKnowledge(state);
+    if (knowledgeFiles.length === 0) return '';
+
+    const knowledgeContent = knowledgeFiles
+      .map((k) => k.content)
+      .filter((k) => !!k)
+      .join('\n\n');
+
+    tag('operation').log(`Found ${knowledgeFiles.length} relevant knowledge ${pluralize(knowledgeFiles.length, 'file')}`);
+    return dedent`
+      <knowledge>
+      Here is relevant knowledge for this page:
+
+      ${knowledgeContent}
+      </knowledge>
+    `;
+  }
+
   addKnowledge(urlPattern: string, description: string): { filename: string; filePath: string; isNewFile: boolean } {
     const configParser = ConfigParser.getInstance();
-    const config = configParser.getConfig();
     const configPath = configParser.getConfigPath();
 
     if (!configPath) {
       throw new Error(`No explorbot configuration found. Please run "${getCliName()} init" first.`);
     }
 
-    const projectRoot = dirname(configPath);
-    const knowledgeDir = join(projectRoot, config.dirs?.knowledge || 'knowledge');
-
-    if (!existsSync(knowledgeDir)) {
-      mkdirSync(knowledgeDir, { recursive: true });
+    if (!existsSync(this.knowledgeDir)) {
+      mkdirSync(this.knowledgeDir, { recursive: true });
     }
 
     const normalizedUrl = this.normalizeUrl(urlPattern);
     const filename = this.generateFilename(normalizedUrl);
-    const filePath = join(knowledgeDir, filename);
+    const filePath = join(this.knowledgeDir, filename);
 
     const isNewFile = !existsSync(filePath);
 
@@ -128,6 +124,8 @@ export class KnowledgeTracker {
       writeFileSync(filePath, fileContent, 'utf8');
     }
 
+    this.isLoaded = false;
+
     return { filename, filePath, isNewFile };
   }
 
@@ -158,12 +156,7 @@ export class KnowledgeTracker {
   }
 
   private generateFilename(url: string): string {
-    let filename = url
-      .replace(/https?:\/\//g, '')
-      .replace(/[^a-zA-Z0-9_]/g, '_')
-      .replace(/_+/g, '_')
-      .replace(/^_|_$/g, '')
-      .toLowerCase();
+    let filename = slugify(url.replace(/https?:\/\//g, ''));
 
     if (!filename || filename === '*') {
       filename = 'general';
@@ -194,7 +187,7 @@ export class KnowledgeTracker {
 
     return this.knowledgeFiles.map((knowledge) => {
       const content = knowledge.content.trim();
-      const firstLine = content.split('\n')[0]?.trim() || '';
+      const firstLine = mdq(content).meta()[0]?.text.split('\n')[0]?.trim() || '';
       return {
         url: knowledge.url,
         firstLine,

package/src/state-manager.ts

@@ -1,11 +1,9 @@
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import matter from 'gray-matter';
 import { ActionResult } from './action-result.js';
-import { ConfigParser, outputPath } from './config.js';
-import { ExperienceTracker } from './experience-tracker.js';
+import type { ExperienceTracker } from './experience-tracker.js';
+import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
 import { detectFocusArea } from './utils/aria.js';
-import { createDebug, tag } from './utils/logger.js';
+import { createDebug } from './utils/logger.js';
+import { slugify } from './utils/strings.js';
 import { extractStatePath } from './utils/url-matcher.js';
 
 const debugLog = createDebug('explorbot:state');
@@ -69,43 +67,36 @@ export interface StateTransition {
 
 export type StateChangeListener = (event: StateTransition) => void;
 
-export interface Knowledge extends WebPageState {
-  /** File path */
-  filePath: string;
-  /** Markdown content */
-  content: string;
+export interface TabInfo {
+  url: string;
+  title: string;
 }
 
+export type { Knowledge };
+
 export class StateManager {
+  otherTabs: TabInfo[] = [];
   private currentState: WebPageState | null = null;
   private stateHistory: StateTransition[] = [];
   private allVisitedUrls: Set<string> = new Set();
-  private knowledgeCache: Knowledge[] = [];
-  private lastKnowledgeScan: Date | null = null;
   private stateChangeListeners: StateChangeListener[] = [];
   private experienceTracker!: ExperienceTracker;
-  private knowledgeDir: string;
+  private knowledgeTracker: KnowledgeTracker;
   private nextStateId = 1;
 
-  constructor() {
-    this.experienceTracker = new ExperienceTracker();
-    const configParser = ConfigParser.getInstance();
-    const config = configParser.getConfig();
-    const configPath = configParser.getConfigPath();
-
-    // Resolve knowledge directory relative to the config file location (project root)
-    if (configPath) {
-      const projectRoot = dirname(configPath);
-      this.knowledgeDir = join(projectRoot, config.dirs?.knowledge || 'knowledge');
-    } else {
-      this.knowledgeDir = config.dirs?.knowledge || 'knowledge';
-    }
+  constructor(experienceTracker: ExperienceTracker, knowledgeTracker: KnowledgeTracker) {
+    this.experienceTracker = experienceTracker;
+    this.knowledgeTracker = knowledgeTracker;
   }
 
   getExperienceTracker(): ExperienceTracker {
     return this.experienceTracker;
   }
 
+  getKnowledgeTracker(): KnowledgeTracker {
+    return this.knowledgeTracker;
+  }
+
   /**
    * Subscribe to state change events
    */
@@ -134,11 +125,6 @@ export class StateManager {
     });
   }
 
-  /**
-   * Extract state path from full URL
-   * Removes domain, port, protocol
-   * Keeps path, query, and hash: /path/to/page?tab=users#section
-   */
   /**
    * Update current state from ActionResult and record transition if state changed
    */
@@ -230,13 +216,7 @@ export class StateManager {
       parts.push(`title_${title}`);
     }
 
-    return parts
-      .join('_')
-      .replace(/[^a-zA-Z0-9_]/g, '_')
-      .replace(/_+/g, '_')
-      .replace(/^_|_$/g, '')
-      .toLowerCase()
-      .substring(0, 200);
+    return slugify(parts.join('_')).substring(0, 200);
   }
 
   /**
@@ -327,65 +307,14 @@ export class StateManager {
     return this.stateHistory.slice(-count);
   }
 
-  /**
-   * Scan knowledge directory for .md files and cache them
-   */
-  private scanKnowledgeFiles(): void {
-    const now = new Date();
-
-    // Only rescan every 30 seconds to avoid excessive file I/O
-    if (this.lastKnowledgeScan && now.getTime() - this.lastKnowledgeScan.getTime() < 30000) {
-      return;
-    }
-
-    this.knowledgeCache = [];
-
-    if (!existsSync(this.knowledgeDir)) {
-      debugLog(`Knowledge directory not found: ${this.knowledgeDir}`);
-      return;
-    }
-
-    try {
-      const files = readdirSync(this.knowledgeDir, { recursive: true })
-        .filter((file) => typeof file === 'string' && file.endsWith('.md'))
-        .map((file) => join(this.knowledgeDir, file as string));
-
-      for (const filePath of files) {
-        try {
-          const fileContent = readFileSync(filePath, 'utf8');
-          const parsed = matter(fileContent);
-
-          const urlPattern = parsed.data.url || parsed.data.path || '*';
-
-          this.knowledgeCache.push({
-            filePath,
-            url: urlPattern,
-            ...parsed.data,
-            content: parsed.content,
-          });
-
-          debugLog(`Loaded knowledge file: ${filePath} (pattern: ${urlPattern})`);
-        } catch (error) {
-          debugLog(`Failed to load knowledge file ${filePath}:`, error);
-        }
-      }
-
-      this.lastKnowledgeScan = now;
-      debugLog(`Scanned ${this.knowledgeCache.length} knowledge files`);
-    } catch (error) {
-      debugLog('Failed to scan knowledge directory:', error);
-    }
-  }
   /**
    * Get relevant knowledge files for current state
    */
   getRelevantKnowledge(): Knowledge[] {
     if (!this.currentState) return [];
 
-    this.scanKnowledgeFiles();
-
     const actionResult = ActionResult.fromState(this.currentState);
-    return this.knowledgeCache.filter((knowledge) => actionResult.isMatchedBy(knowledge));
+    return this.knowledgeTracker.getRelevantKnowledge(actionResult);
   }
 
   /**
@@ -402,24 +331,6 @@ export class StateManager {
   /**
    * Get all context for current state (knowledge + experience)
    */
-  getCurrentContext(): {
-    state: WebPageState;
-    knowledge: Knowledge[];
-    experience: string[];
-    recentTransitions: StateTransition[];
-  } {
-    if (!this.currentState) {
-      throw new Error('No current state available');
-    }
-
-    return {
-      state: this.currentState,
-      knowledge: this.getRelevantKnowledge(),
-      experience: this.getRelevantExperience(),
-      recentTransitions: this.getRecentTransitions(),
-    };
-  }
-
   /**
    * Check if we've been in this state before
    */
@@ -455,45 +366,6 @@ export class StateManager {
    * If the last transition changed URL, returns the fromState (for URL change detection).
    * Otherwise returns the most recent toState with content (for diffing).
    */
-  getPreviousState(): WebPageState | null {
-    if (this.stateHistory.length === 0) return null;
-
-    const lastTransition = this.stateHistory[this.stateHistory.length - 1];
-
-    if (lastTransition.fromState?.url !== lastTransition.toState?.url) {
-      return lastTransition.fromState;
-    }
-
-    for (let i = this.stateHistory.length - 1; i >= 0; i--) {
-      const toState = this.stateHistory[i].toState;
-
-      if (!toState) continue;
-      if (toState.id === this.currentState?.id) continue;
-
-      if (toState.html || toState.ariaSnapshot) {
-        return toState;
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Load HTML content from file
-   */
-  loadHtmlFromFile(htmlFile: string): string | null {
-    try {
-      const filePath = outputPath('states', htmlFile);
-      if (existsSync(filePath)) {
-        return readFileSync(filePath, 'utf8');
-      }
-      return null;
-    } catch (error) {
-      debugLog('Failed to load HTML from file:', error);
-      return null;
-    }
-  }
-
   /**
    * Clear state history (useful for testing or reset)
    * Note: This preserves the current state, only clears navigation history
@@ -527,15 +399,8 @@ export class StateManager {
     this.stateHistory = [];
     this.allVisitedUrls.clear();
     this.stateChangeListeners = [];
-    this.knowledgeCache = [];
-    this.lastKnowledgeScan = null;
     this.nextStateId = 1;
 
-    // Clean up experience tracker if it has cleanup method
-    if (this.experienceTracker && typeof this.experienceTracker.cleanup === 'function') {
-      this.experienceTracker.cleanup();
-    }
-
     debugLog('StateManager cleanup completed');
   }
 }

package/src/utils/aria.ts

@@ -483,7 +483,7 @@ export const compactAriaSnapshot = (snapshot: string | null, keepNamed = false):
   return renderTree(tree);
 };
 
-export const diffAriaSnapshots = (previous: string | null, current: string | null): string | null => {
+export const diffAriaSnapshots = (previous: string | null, current: string | null): AriaDiff => {
   const flat = (snap: string | null): FlatEntry[] => {
     let tree = parseSnapshot(snap);
     tree = unwrapIgnored(tree);
@@ -500,7 +500,9 @@ export const diffAriaSnapshots = (previous: string | null, current: string | nul
   const currTotals = countBy(curr.map((e) => e.summary));
   const byCount = diffByCount(prevTotals, currTotals);
   const renames = detectRenames(prev, curr, prevTotals, currTotals);
-  return formatDiff([...byCount.added, ...renames.added], [...byCount.removed, ...renames.removed], toggled);
+  const added = [...byCount.added, ...renames.added];
+  const removed = [...byCount.removed, ...renames.removed];
+  return { text: formatDiff(added, removed, toggled), count: added.length + removed.length + toggled.length };
 };
 
 export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {
@@ -570,10 +572,17 @@ export function parseAriaLocator(ariaStr: string): { role: string; text: string
   return { role: match[1], text: match[2] };
 }
 
+export const LARGE_ARIA_CHANGE_THRESHOLD = 50;
+
 // ─────────────────────────────────────────────────────────────────
 // Types
 // ─────────────────────────────────────────────────────────────────
 
+export interface AriaDiff {
+  text: string | null;
+  count: number;
+}
+
 type AriaNode = {
   role: string;
   name?: string;

package/src/utils/cache.ts

@@ -0,0 +1,40 @@
+export class TTLCache<T> {
+  private store = new Map<string, CacheEntry<T>>();
+  private ttlMs: number;
+
+  constructor(ttlMs = Number.POSITIVE_INFINITY) {
+    this.ttlMs = ttlMs;
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (Date.now() - entry.at > this.ttlMs) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  set(key: string, value: T): void {
+    this.store.set(key, { value, at: Date.now() });
+  }
+
+  async fetch(key: string, compute: () => Promise<T>): Promise<T> {
+    const cached = this.get(key);
+    if (cached !== undefined) return cached;
+    const value = await compute();
+    this.set(key, value);
+    return value;
+  }
+
+  delete(key: string): void {
+    this.store.delete(key);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}
+
+type CacheEntry<T> = { value: T; at: number };

package/src/utils/context-formatter.ts

@@ -29,6 +29,15 @@ function indent(text: string): string {
     .join('\n');
 }
 
+export function formatHeadings(headings: { h1?: string; h2?: string; h3?: string; h4?: string }): string[] {
+  const lines: string[] = [];
+  if (headings.h1) lines.push(`H1: ${headings.h1}`);
+  if (headings.h2) lines.push(`H2: ${headings.h2}`);
+  if (headings.h3) lines.push(`H3: ${headings.h3}`);
+  if (headings.h4) lines.push(`H4: ${headings.h4}`);
+  return lines;
+}
+
 export type ContextMode = 'attached' | 'compact' | 'full';
 
 export function formatContextSummary(data: ContextData, mode: ContextMode = 'compact'): string {
@@ -51,11 +60,7 @@ function formatContextAttached(data: ContextData): string {
   }
   lines.push('');
 
-  const headingLines: string[] = [];
-  if (data.headings.h1) headingLines.push(`H1: ${data.headings.h1}`);
-  if (data.headings.h2) headingLines.push(`H2: ${data.headings.h2}`);
-  if (data.headings.h3) headingLines.push(`H3: ${data.headings.h3}`);
-  if (data.headings.h4) headingLines.push(`H4: ${data.headings.h4}`);
+  const headingLines = formatHeadings(data.headings);
 
   if (headingLines.length > 0) {
     lines.push(section('HEADINGS') + chalk.gray(' (Auto-attached)'));
@@ -116,11 +121,7 @@ function formatContextCompact(data: ContextData): string {
   }
   lines.push('');
 
-  const headingLines: string[] = [];
-  if (data.headings.h1) headingLines.push(`H1: ${data.headings.h1}`);
-  if (data.headings.h2) headingLines.push(`H2: ${data.headings.h2}`);
-  if (data.headings.h3) headingLines.push(`H3: ${data.headings.h3}`);
-  if (data.headings.h4) headingLines.push(`H4: ${data.headings.h4}`);
+  const headingLines = formatHeadings(data.headings);
 
   if (headingLines.length > 0) {
     lines.push(section('HEADINGS') + chalk.gray(' (Auto-attached)'));
@@ -177,11 +178,7 @@ function formatContextFull(data: ContextData): string {
   }
   lines.push('');
 
-  const headingLines: string[] = [];
-  if (data.headings.h1) headingLines.push(`H1: ${data.headings.h1}`);
-  if (data.headings.h2) headingLines.push(`H2: ${data.headings.h2}`);
-  if (data.headings.h3) headingLines.push(`H3: ${data.headings.h3}`);
-  if (data.headings.h4) headingLines.push(`H4: ${data.headings.h4}`);
+  const headingLines = formatHeadings(data.headings);
 
   if (headingLines.length > 0) {
     lines.push(section('HEADINGS') + chalk.gray(' (Auto-attached)'));

package/src/utils/hooks-runner.ts

@@ -54,11 +54,9 @@ export class HooksRunner {
   private async executeHook(hook: Hook, url: string): Promise<void> {
     try {
       if (hook.type === 'playwright') {
-        const page = this.explorer.playwrightHelper.page;
-        await hook.hook({ page, url });
+        await this.explorer.withPage(async (page) => hook.hook({ page, url }));
       } else {
-        const I = this.explorer.actor;
-        await hook.hook({ I, url });
+        await hook.hook({ I: this.explorer.actor, url });
       }
     } catch (error) {
       debugLog(`Hook error: ${error}`);

package/src/utils/html.ts

@@ -85,8 +85,10 @@ const HIDDEN_CLASSES = new Set(['hidden', 'invisible', 'd-none', 'hide', 'dn', '
 
 export const EXPLORBOT_ATTRS = {
   area: 'data-explorbot-area',
+  coveredBy: 'data-explorbot-covered-by',
   context: 'data-explorbot-context',
   eidx: 'data-explorbot-eidx',
+  hit: 'data-explorbot-hit',
   variant: 'data-explorbot-variant',
 } as const;
 
@@ -169,14 +171,49 @@ export type ComponentScopeExtractionConfig = {
   limits: typeof HTML_EXTRACTION_LIMITS;
 };
 
+export function captureHtmlForSnapshot(): string {
+  const clone = document.documentElement.cloneNode(true) as HTMLElement;
+  const liveControls = Array.from(document.querySelectorAll('input, textarea, select')) as Array<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>;
+  const clonedControls = Array.from(clone.querySelectorAll('input, textarea, select')) as HTMLElement[];
+
+  for (let i = 0; i < liveControls.length; i++) {
+    const source = liveControls[i];
+    const target = clonedControls[i];
+    if (!target) continue;
+
+    if (source instanceof HTMLInputElement || source instanceof HTMLTextAreaElement) {
+      target.setAttribute('data-explorbot-value', source.value);
+    }
+
+    if (source instanceof HTMLInputElement && (source.type === 'checkbox' || source.type === 'radio')) {
+      let checked = 'false';
+      if (source.checked) checked = 'true';
+      target.setAttribute('data-explorbot-checked', checked);
+    }
+
+    if (source instanceof HTMLSelectElement) {
+      target.setAttribute(
+        'data-explorbot-value',
+        Array.from(source.selectedOptions)
+          .map((option) => option.value)
+          .join(',')
+      );
+    }
+  }
+
+  return clone.outerHTML;
+}
+
 export function extractElementData(el: Element, config?: ElementExtractionConfig) {
   const cfg =
     config ||
     ({
       attrs: {
         area: 'data-explorbot-area',
+        coveredBy: 'data-explorbot-covered-by',
         context: 'data-explorbot-context',
         eidx: 'data-explorbot-eidx',
+        hit: 'data-explorbot-hit',
         variant: 'data-explorbot-variant',
       },
       codeEditorMarkers: ['monaco', 'codemirror', 'ace', 'ace_editor', 'code'],
@@ -246,6 +283,45 @@ export function extractElementData(el: Element, config?: ElementExtractionConfig
     return Array.from(tokens).slice(0, 8);
   }
 
+  function describeOverlappingElement(target: Element): string {
+    const parts = [target.tagName.toLowerCase()];
+    const role = target.getAttribute('role');
+    const ariaLabel = target.getAttribute('aria-label');
+    const id = target.getAttribute('id');
+    const className = (target.getAttribute('class') || '').split(/\s+/).filter(Boolean).slice(0, 3).join('.');
+
+    if (id) parts.push(`#${id.slice(0, 40)}`);
+    if (className) parts.push(`.${className.slice(0, 80)}`);
+    if (role) parts.push(`[role="${role.slice(0, 40)}"]`);
+    if (ariaLabel) parts.push(`[aria-label="${ariaLabel.slice(0, 80)}"]`);
+
+    return parts.join('');
+  }
+
+  function inspectHitTarget(target: Element, rect: DOMRect): { hit: string; coveredBy?: string } {
+    const viewportPoints = [
+      { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 },
+      { x: rect.left + Math.min(rect.width - 1, Math.max(1, rect.width * 0.25)), y: rect.top + Math.min(rect.height - 1, Math.max(1, rect.height * 0.25)) },
+      { x: rect.left + Math.min(rect.width - 1, Math.max(1, rect.width * 0.75)), y: rect.top + Math.min(rect.height - 1, Math.max(1, rect.height * 0.75)) },
+    ].filter((point) => point.x >= 0 && point.y >= 0 && point.x <= window.innerWidth && point.y <= window.innerHeight);
+
+    if (viewportPoints.length === 0) {
+      return { hit: 'offscreen' };
+    }
+
+    for (const point of viewportPoints) {
+      const top = document.elementFromPoint(point.x, point.y);
+      if (!top) continue;
+      if (top === target || target.contains(top)) {
+        return { hit: 'target' };
+      }
+    }
+
+    const centerPoint = viewportPoints[0];
+    const top = document.elementFromPoint(centerPoint.x, centerPoint.y);
+    return { hit: 'covered', coveredBy: top ? describeOverlappingElement(top) : undefined };
+  }
+
   function isEmbeddedCodeEditorFrame(target: Element): boolean {
     const src = (target.getAttribute('src') || '').toLowerCase();
     const markerSelector = cfg.codeEditorMarkers.map((marker) => `[class*="${marker}"]`).join(', ');
@@ -354,6 +430,9 @@ export function extractElementData(el: Element, config?: ElementExtractionConfig
   allAttrs[cfg.attrs.area] = areaHints.join('|');
   allAttrs[cfg.attrs.context] = findContextLabel(el);
   allAttrs[cfg.attrs.variant] = collectVariantHints(el).join('|');
+  const hitTarget = inspectHitTarget(el, rect);
+  allAttrs[cfg.attrs.hit] = hitTarget.hit;
+  if (hitTarget.coveredBy) allAttrs[cfg.attrs.coveredBy] = hitTarget.coveredBy;
 
   return {
     tag: el.tagName.toLowerCase(),