@mercuryo-ai/agentbrowse 0.2.60 → 0.2.63

package/dist/commands/observe-inventory.js

@@ -14,10 +14,13 @@ export function inferStructuredCellVariantFromEvidence(evidence) {
     const hasSeatMetadata = Boolean(evidence.hasSeatAttribute || evidence.hasSeatRowAttribute || evidence.hasSeatColumnAttribute);
     const seatIdentityLike = /(?:\bseat\s*\d{1,3}[a-z]?\b|место\s*\d{1,3}[a-z]?\b|\b\d{1,3}[a-z]\b|\b[a-z]\d{1,3}\b)/i.test(normalizedLabel);
     const seatClassLike = /seat|cabin|fare|row/.test(className);
-    const compactDateCellLabel = /^(?:\d{1,2}|january|february|march|april|may|june|july|august|september|october|november|december|январ|феврал|март|апрел|ма[йя]|июн|июл|август|сентябр|октябр|ноябр|декабр)$/i.test(normalizedLabel) || /^(?:\d{1,2}[./-]\d{1,2}(?:[./-]\d{2,4})?)$/.test(normalizedLabel);
+    const compactDateCellLabel = /^\d{1,2}$/.test(normalizedLabel) ||
+        /^(?:\d{1,2}[./-]\d{1,2}(?:[./-]\d{2,4})?)$/.test(normalizedLabel);
+    const leadingNumericDayToken = /^\d{1,2}\b/.test(normalizedLabel);
     const dateLike = surfaceKind === 'datepicker' ||
         (hasDateMetadata && role === 'gridcell') ||
-        ((role === 'gridcell' || structuredSurface || hasDateMetadata) && compactDateCellLabel);
+        ((role === 'gridcell' || structuredSurface || hasDateMetadata) &&
+            (compactDateCellLabel || (hasDateMetadata && leadingNumericDayToken)));
     if (dateLike) {
         return 'date-cell';
     }
@@ -62,12 +65,22 @@ export function inferDirectionalControlFallbackFromEvidence(evidence) {
     }
     return undefined;
 }
+export function sanitizeClassNameForStateInference(value) {
+    return (value ?? '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase()
+        .split(' ')
+        .filter(Boolean)
+        .filter((token) => !token.includes(':'))
+        .join(' ');
+}
 export function inferDisabledStateFromSemanticEvidence(evidence) {
     const normalize = (value) => (value ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
     const tagName = normalize(evidence.tagName);
     const role = normalize(evidence.role);
     const inputType = normalize(evidence.inputType);
-    const className = normalize(evidence.className);
+    const className = sanitizeClassNameForStateInference(evidence.className);
     const nonClassBlob = [
         evidence.datasetText,
         evidence.dataState,
@@ -98,6 +111,7 @@ export function inferDisabledStateFromSemanticEvidence(evidence) {
     return disabledLikeRe.test(collectionOrButtonLike ? fullSemanticBlob : nonClassBlob);
 }
 const INFER_STRUCTURED_CELL_VARIANT_HELPER_SCRIPT = `const inferStructuredCellVariantFromEvidence = ${inferStructuredCellVariantFromEvidence.toString()};`;
+const SANITIZE_CLASS_NAME_FOR_STATE_INFERENCE_HELPER_SCRIPT = `const sanitizeClassNameForStateInference = ${sanitizeClassNameForStateInference.toString()};`;
 const INFER_DISABLED_STATE_FROM_SEMANTIC_EVIDENCE_HELPER_SCRIPT = String.raw `
     const inferDisabledStateFromSemanticEvidence = (evidence) => {
       const normalizeDisabledSemanticValue = (value) =>
@@ -106,7 +120,7 @@ const INFER_DISABLED_STATE_FROM_SEMANTIC_EVIDENCE_HELPER_SCRIPT = String.raw `
       const tagName = normalizeDisabledSemanticValue(evidence?.tagName);
       const role = normalizeDisabledSemanticValue(evidence?.role);
       const inputType = normalizeDisabledSemanticValue(evidence?.inputType);
-      const className = normalizeDisabledSemanticValue(evidence?.className);
+      const className = sanitizeClassNameForStateInference(evidence?.className);
       const nonClassBlob = [
         evidence?.datasetText,
         evidence?.dataState,
@@ -404,14 +418,16 @@ export function normalizeStagehandSelector(selector) {
         }
         : { selector };
 }
-async function collectDomTargetsFromDocument(context, options) {
+async function collectDomTargetsFromDocumentRaw(context, options) {
     const includeActivationAffordances = options?.includeActivationAffordances === true;
+    const debugStructuralProfileStats = options?.debugStructuralProfileStats === true;
     const inheritedFramePath = JSON.stringify(options?.framePath ?? []);
     const inheritedFrameUrl = JSON.stringify(options?.frameUrl ?? '');
     const inheritedPageSignature = JSON.stringify(options?.pageSignature ?? '');
     const inheritedPageFormSelector = JSON.stringify(options?.pageFormSelector ?? '');
-    const observedTargets = await context.evaluate(String.raw `(() => {
+    const observedPayload = await context.evaluate(String.raw `(() => {
     const includeActivationAffordances = ${includeActivationAffordances ? 'true' : 'false'};
+    const debugStructuralProfileStats = ${debugStructuralProfileStats ? 'true' : 'false'};
     const inheritedFramePath = ${inheritedFramePath};
     const inheritedFrameUrl = ${inheritedFrameUrl};
     const inheritedPageSignature = ${inheritedPageSignature};
@@ -569,6 +585,7 @@ async function collectDomTargetsFromDocument(context, options) {
     ${TRANSPARENT_ACTIONABLE_CONTROL_HELPER_SCRIPT}
     ${OBSERVE_DOM_LABEL_CONTRACT_HELPER_SCRIPT}
     ${INFER_STRUCTURED_CELL_VARIANT_HELPER_SCRIPT}
+    ${SANITIZE_CLASS_NAME_FOR_STATE_INFERENCE_HELPER_SCRIPT}
     ${INFER_DISABLED_STATE_FROM_SEMANTIC_EVIDENCE_HELPER_SCRIPT}
     ${INFER_DIRECTIONAL_CONTROL_FALLBACK_HELPER_SCRIPT}
 
@@ -1096,7 +1113,26 @@ async function collectDomTargetsFromDocument(context, options) {
       return inferRole(element) || tag;
     };
 
+    const selectorCache = new WeakMap();
+
     const buildSelector = (element) => {
+      if (!isHTMLElementNode(element)) {
+        return undefined;
+      }
+
+      const cachedSelector = selectorCache.get(element);
+      if (typeof cachedSelector === 'string') {
+        return cachedSelector;
+      }
+      if (cachedSelector === null) {
+        return undefined;
+      }
+
+      const finalizeSelector = (value) => {
+        selectorCache.set(element, value ?? null);
+        return value;
+      };
+
       const testIdAttributeOf = (candidate) => {
         if (candidate.hasAttribute('data-testid')) return 'data-testid';
         if (candidate.hasAttribute('data-test-id')) return 'data-test-id';
@@ -1123,7 +1159,7 @@ async function collectDomTargetsFromDocument(context, options) {
       };
 
       if (element.id && isSelectorUniqueFor(element, '#' + cssEscape(element.id))) {
-        return '#' + cssEscape(element.id);
+        return finalizeSelector('#' + cssEscape(element.id));
       }
 
       const testId =
@@ -1131,7 +1167,7 @@ async function collectDomTargetsFromDocument(context, options) {
       if (testId) {
         const selectorValue = testIdSelectorOf(element, testId);
         if (isSelectorUniqueFor(element, selectorValue)) {
-          return selectorValue;
+          return finalizeSelector(selectorValue);
         }
       }
 
@@ -1140,7 +1176,7 @@ async function collectDomTargetsFromDocument(context, options) {
       if (name) {
         const selectorValue = tag + '[name="' + cssEscape(name) + '"]';
         if (isSelectorUniqueFor(element, selectorValue)) {
-          return selectorValue;
+          return finalizeSelector(selectorValue);
         }
       }
 
@@ -1189,10 +1225,14 @@ async function collectDomTargetsFromDocument(context, options) {
         }
         current = current.parentElement;
       }
-      if (path.length === 0) return undefined;
+      if (path.length === 0) return finalizeSelector(undefined);
 
       const structuralSelector = path.join(' > ');
-      return isSelectorUniqueFor(element, structuralSelector) ? structuralSelector : undefined;
+      return finalizeSelector(
+        isSelectorUniqueFor(element, structuralSelector)
+        ? structuralSelector
+        : undefined
+      );
     };
 
     const selectorFromRelation = (element, attribute) => {
@@ -1341,10 +1381,44 @@ async function collectDomTargetsFromDocument(context, options) {
       return false;
     };
 
+    const visibleInteractiveDescendantCountCache = new WeakMap();
+
     const visibleInteractiveDescendantCountOf = (element) => {
-      return Array.from(element.querySelectorAll(selector)).filter((candidate) => {
+      if (!isHTMLElementNode(element)) {
+        return 0;
+      }
+
+      const cachedCount = visibleInteractiveDescendantCountCache.get(element);
+      if (typeof cachedCount === 'number') {
+        return cachedCount;
+      }
+
+      const count = Array.from(element.querySelectorAll(selector)).filter((candidate) => {
         return isHTMLElementNode(candidate) && isVisible(candidate);
       }).length;
+      visibleInteractiveDescendantCountCache.set(element, count);
+      return count;
+    };
+
+    const descendantEditableCountCache = new WeakMap();
+
+    const descendantEditableCountOf = (element) => {
+      if (!isHTMLElementNode(element)) {
+        return 0;
+      }
+
+      const cachedCount = descendantEditableCountCache.get(element);
+      if (typeof cachedCount === 'number') {
+        return cachedCount;
+      }
+
+      const count = Array.from(
+        element.querySelectorAll(
+          'input:not([type="hidden"]), textarea, select, [contenteditable="true"]'
+        )
+      ).filter((candidate) => isHTMLElementNode(candidate) && isVisible(candidate)).length;
+      descendantEditableCountCache.set(element, count);
+      return count;
     };
 
     const clickableSemanticBlobOf = (element) => {
@@ -2139,7 +2213,7 @@ async function collectDomTargetsFromDocument(context, options) {
         states.hasSelection = true;
       }
 
-      const className = (element.getAttribute('class') || '').toLowerCase();
+      const className = sanitizeClassNameForStateInference(element.getAttribute('class') || '');
       const dataset = Object.values(element.dataset || {})
         .join(' ')
         .toLowerCase();
@@ -2218,6 +2292,87 @@ async function collectDomTargetsFromDocument(context, options) {
       return Object.keys(states).length > 0 ? states : undefined;
     };
 
+    const canonicalDateIdentityFromParts = (yearValue, monthValue, dayValue) => {
+      const year = Number.parseInt(String(yearValue || '').trim(), 10);
+      const month = Number.parseInt(String(monthValue || '').trim(), 10);
+      const day = Number.parseInt(String(dayValue || '').trim(), 10);
+      if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) {
+        return undefined;
+      }
+      if (month < 1 || month > 12 || day < 1 || day > 31) {
+        return undefined;
+      }
+
+      const candidate = new Date(Date.UTC(year, month - 1, day));
+      if (
+        candidate.getUTCFullYear() !== year ||
+        candidate.getUTCMonth() !== month - 1 ||
+        candidate.getUTCDate() !== day
+      ) {
+        return undefined;
+      }
+
+      return {
+        dateIso:
+          year.toString().padStart(4, '0') +
+          '-' +
+          month.toString().padStart(2, '0') +
+          '-' +
+          day.toString().padStart(2, '0'),
+        dateYear: year,
+        dateMonth: month,
+        dateDay: day,
+      };
+    };
+
+    const canonicalDateIdentityFromValue = (value) => {
+      const normalized = normalizeDescriptorText(value || '');
+      const match = normalized?.match(/\b(\d{4})-(\d{1,2})-(\d{1,2})\b/);
+      if (!match) {
+        return undefined;
+      }
+
+      return canonicalDateIdentityFromParts(match[1], match[2], match[3]);
+    };
+
+    const canonicalDateIdentityOf = (element, normalizedLabel) => {
+      const metadataValues = [
+        element.getAttribute('data-iso'),
+        element.getAttribute('data-date'),
+        element.getAttribute('data-day'),
+        element.getAttribute('data-testid'),
+        element.getAttribute('data-test-id'),
+        element.getAttribute('id'),
+        element.getAttribute('class'),
+        element.getAttribute('title'),
+        element.getAttribute('aria-label'),
+      ];
+
+      for (const candidateValue of metadataValues) {
+        const directIdentity = canonicalDateIdentityFromValue(candidateValue);
+        if (directIdentity) {
+          return directIdentity;
+        }
+      }
+
+      const leadingDayToken = normalizedLabel.match(/^(\d{1,2})\b/)?.[1];
+      const dayValue = element.getAttribute('data-day')?.trim() || leadingDayToken;
+      const monthValue =
+        element.getAttribute('data-month')?.trim() ||
+        element.getAttribute('data-date-month')?.trim() ||
+        composedClosest(element, '[data-month], [data-date-month]')?.getAttribute?.('data-month')?.trim() ||
+        composedClosest(element, '[data-month], [data-date-month]')?.getAttribute?.('data-date-month')?.trim() ||
+        undefined;
+      const yearValue =
+        element.getAttribute('data-year')?.trim() ||
+        element.getAttribute('data-date-year')?.trim() ||
+        composedClosest(element, '[data-year], [data-date-year]')?.getAttribute?.('data-year')?.trim() ||
+        composedClosest(element, '[data-year], [data-date-year]')?.getAttribute?.('data-date-year')?.trim() ||
+        undefined;
+
+      return canonicalDateIdentityFromParts(yearValue, monthValue, dayValue);
+    };
+
     const inferStructuredCell = (element, surface) => {
       if (!isHTMLElementNode(element)) return undefined;
 
@@ -2231,10 +2386,22 @@ async function collectDomTargetsFromDocument(context, options) {
       const label =
         explicitLabelOf(element) || textOf(element) || seatValueLabel || syntheticLabelOf(element) || '';
       const normalizedLabel = label.replace(/\s+/g, ' ').trim();
+      const dateIdentity = canonicalDateIdentityOf(element, normalizedLabel);
       const explicitDateCellMetadata =
+        Boolean(dateIdentity) ||
         element.hasAttribute('data-day') ||
         element.hasAttribute('data-date') ||
         element.hasAttribute('data-iso') ||
+        /\bdate[-_ ]?cell\b|\bcalendar[-_ ]?day\b|\b\d{4}-\d{2}-\d{2}\b/i.test(
+          [
+            element.getAttribute('data-testid') || '',
+            element.getAttribute('data-test-id') || '',
+            element.getAttribute('id') || '',
+            element.getAttribute('class') || '',
+          ]
+            .join(' ')
+            .trim()
+        ) ||
         element.hasAttribute('aria-rowindex') ||
         element.hasAttribute('aria-colindex') ||
         Boolean(
@@ -2279,6 +2446,7 @@ async function collectDomTargetsFromDocument(context, options) {
       return {
         family: 'structured-grid',
         variant: structuredCellVariant,
+        ...(dateIdentity ?? {}),
         row,
         column,
         zone,
@@ -2357,9 +2525,19 @@ async function collectDomTargetsFromDocument(context, options) {
       return undefined;
     };
 
+    const surfacePositionTraitsCache = new WeakMap();
+
     const surfacePositionTraitsOf = (surface) => {
       if (!isHTMLElementNode(surface) || !isVisible(surface)) return undefined;
 
+      const cachedTraits = surfacePositionTraitsCache.get(surface);
+      if (cachedTraits) {
+        return cachedTraits;
+      }
+      if (cachedTraits === null) {
+        return undefined;
+      }
+
       const style = window.getComputedStyle(surface);
       const position = (style.position || '').toLowerCase();
       const rect = surface.getBoundingClientRect();
@@ -2378,19 +2556,26 @@ async function collectDomTargetsFromDocument(context, options) {
           style.backgroundColor !== 'rgba(0, 0, 0, 0)');
 
       if (rect.width < 180 || rect.height < 72 || interactiveCount < 1 || coverage > 0.45) {
+        surfacePositionTraitsCache.set(surface, null);
         return undefined;
       }
 
       if (position === 'fixed') {
-        return { kind: 'floating-panel', priority: 92 };
+        const traits = { kind: 'floating-panel', priority: 92 };
+        surfacePositionTraitsCache.set(surface, traits);
+        return traits;
       }
 
       if (position === 'sticky') {
-        return { kind: 'sticky-panel', priority: 88 };
+        const traits = { kind: 'sticky-panel', priority: 88 };
+        surfacePositionTraitsCache.set(surface, traits);
+        return traits;
       }
 
       if (position === 'absolute' && hasCardChrome && zIndexValue > 0) {
-        return { kind: 'floating-panel', priority: 82 };
+        const traits = { kind: 'floating-panel', priority: 82 };
+        surfacePositionTraitsCache.set(surface, traits);
+        return traits;
       }
 
       if (
@@ -2399,33 +2584,67 @@ async function collectDomTargetsFromDocument(context, options) {
         interactiveCount >= 1 &&
         (modalBackdropAncestorOf(surface) || siblingModalBackdropOf(surface))
       ) {
-        return { kind: 'floating-panel', priority: 90 };
+        const traits = { kind: 'floating-panel', priority: 90 };
+        surfacePositionTraitsCache.set(surface, traits);
+        return traits;
       }
 
+      surfacePositionTraitsCache.set(surface, null);
       return undefined;
     };
 
+    const inferredSurfaceKindCache = new WeakMap();
+
     const inferSurfaceKind = (surface) => {
       if (!isHTMLElementNode(surface)) return undefined;
+
+      const cachedSurfaceKind = inferredSurfaceKindCache.get(surface);
+      if (typeof cachedSurfaceKind === 'string') {
+        return cachedSurfaceKind;
+      }
+      if (cachedSurfaceKind === null) {
+        return undefined;
+      }
+
       const positionedSurface = surfacePositionTraitsOf(surface);
-      if (positionedSurface?.kind) return positionedSurface.kind;
+      if (positionedSurface?.kind) {
+        inferredSurfaceKindCache.set(surface, positionedSurface.kind);
+        return positionedSurface.kind;
+      }
       const role = surface.getAttribute('role')?.trim();
-      if (role === 'dialog') return 'dialog';
-      if (role === 'listbox') return 'listbox';
-      if (role === 'menu') return 'menu';
-      if (role === 'grid') return 'grid';
-      if (role === 'tabpanel') return 'tabpanel';
-      if (isGenericClickableElement(surface) && isStructuredContainer(surface)) return 'card';
+      if (role === 'dialog') return inferredSurfaceKindCache.set(surface, 'dialog'), 'dialog';
+      if (role === 'listbox') return inferredSurfaceKindCache.set(surface, 'listbox'), 'listbox';
+      if (role === 'menu') return inferredSurfaceKindCache.set(surface, 'menu'), 'menu';
+      if (role === 'grid') return inferredSurfaceKindCache.set(surface, 'grid'), 'grid';
+      if (role === 'tabpanel') return inferredSurfaceKindCache.set(surface, 'tabpanel'), 'tabpanel';
+      if (isGenericClickableElement(surface) && isStructuredContainer(surface)) {
+        inferredSurfaceKindCache.set(surface, 'card');
+        return 'card';
+      }
       const className = (surface.getAttribute('class') || '').toLowerCase();
-      if (className.includes('calendar') || className.includes('datepicker')) return 'datepicker';
-      if (className.includes('popover')) return 'popover';
-      if (className.includes('dropdown')) return 'dropdown';
+      if (className.includes('calendar') || className.includes('datepicker')) {
+        inferredSurfaceKindCache.set(surface, 'datepicker');
+        return 'datepicker';
+      }
+      if (className.includes('popover')) {
+        inferredSurfaceKindCache.set(surface, 'popover');
+        return 'popover';
+      }
+      if (className.includes('dropdown')) {
+        inferredSurfaceKindCache.set(surface, 'dropdown');
+        return 'dropdown';
+      }
       const tag = surface.tagName.toLowerCase();
-      if (tag === 'article') return 'card';
-      if (tag === 'fieldset') return 'group';
-      if (tag === 'li') return 'listitem';
-      if (tag === 'section' || tag === 'form' || tag === 'aside') return tag;
-      return role || surface.tagName.toLowerCase();
+      if (tag === 'article') return inferredSurfaceKindCache.set(surface, 'card'), 'card';
+      if (tag === 'fieldset') return inferredSurfaceKindCache.set(surface, 'group'), 'group';
+      if (tag === 'li') return inferredSurfaceKindCache.set(surface, 'listitem'), 'listitem';
+      if (tag === 'section' || tag === 'form' || tag === 'aside') {
+        inferredSurfaceKindCache.set(surface, tag);
+        return tag;
+      }
+      const resolvedSurfaceKind = role || surface.tagName.toLowerCase();
+      inferredSurfaceKindCache.set(surface, resolvedSurfaceKind || null);
+      return resolvedSurfaceKind;
     };
 
     const labelledByTextOf = (element) => {
@@ -2599,15 +2818,29 @@ async function collectDomTargetsFromDocument(context, options) {
       return text.length <= 140 ? text : text.slice(0, 140);
     };
 
+    const contextNodeCache = new WeakMap();
+
     const contextNodeOf = (element) => {
-      if (!element) return undefined;
+      if (!isHTMLElementNode(element)) return undefined;
+
+      const cachedNode = contextNodeCache.get(element);
+      if (cachedNode) {
+        return cachedNode;
+      }
+      if (cachedNode === null) {
+        return undefined;
+      }
 
-      const kind = element.getAttribute?.('role')?.trim() || element.tagName?.toLowerCase?.();
+      const kind = element.getAttribute('role')?.trim() || element.tagName?.toLowerCase?.();
       const fallbackLabel = contextLabelOf(element);
       const text = contextTextOf(element);
       const selector = buildSelector(element);
-      if (!kind && !fallbackLabel && !text && !selector) return undefined;
-      return {
+      if (!kind && !fallbackLabel && !text && !selector) {
+        contextNodeCache.set(element, null);
+        return undefined;
+      }
+
+      const contextNode = {
         kind: kind || undefined,
         label: fallbackLabel,
         text:
@@ -2617,6 +2850,8 @@ async function collectDomTargetsFromDocument(context, options) {
         selector,
         fallbackLabel,
       };
+      contextNodeCache.set(element, contextNode);
+      return contextNode;
     };
 
     const pageSignature =
@@ -2634,6 +2869,23 @@ async function collectDomTargetsFromDocument(context, options) {
       const seenElements = new Set();
       const overlaySurfaceSelector =
         '[role="dialog"], [aria-modal="true"], [role="listbox"], [role="menu"], [role="grid"], [role="tabpanel"], [class*="popover"], [class*="dropdown"], [class*="listbox"], [class*="calendar"], [class*="datepicker"]';
+      // Keep structural scans bounded without assuming shallow wrapper trees.
+      const structuralAncestorSearchDepth = 16;
+      const structuralProfileDebugStats = debugStructuralProfileStats
+        ? {
+            structuralProfileBuilds: 0,
+            ownerCandidateAncestorVisits: 0,
+            explicitSurfaceAncestorVisits: 0,
+            surfaceSelectorAncestorVisits: 0,
+          }
+        : undefined;
+      const structuralProfileCache = new WeakMap();
+
+      const incrementStructuralProfileDebugStat = (key) => {
+        if (structuralProfileDebugStats) {
+          structuralProfileDebugStats[key] += 1;
+        }
+      };
 
       const compactText = (value) => (value || '').replace(/\s+/g, ' ').trim();
 
@@ -2855,7 +3107,7 @@ async function collectDomTargetsFromDocument(context, options) {
         let preferredFallback = undefined;
         let current = surface;
         let depth = 0;
-        while (current && depth < 8) {
+        while (current && depth < structuralAncestorSearchDepth) {
           if (!isHTMLElementNode(current) || !isVisible(current)) {
             current = current?.parentElement ?? null;
             depth += 1;
@@ -3126,7 +3378,7 @@ async function collectDomTargetsFromDocument(context, options) {
         for (const tokenNode of tokenNodes) {
           let current = composedParentElement(tokenNode);
           let depth = 0;
-          while (current && depth < 8) {
+          while (current && depth < structuralAncestorSearchDepth) {
             if (isPotentialVisualGridSurface(current)) {
               candidateSurfaces.set(
                 current,
@@ -3178,66 +3430,67 @@ async function collectDomTargetsFromDocument(context, options) {
         .filter((element) => isHTMLElementNode(element))
         .filter((element) => isVisible(element));
 
-      const localSurfaceCandidateOf = (element) => {
-        const ranked = [];
-        const pushCandidate = (candidate, depth) => {
-          if (
-            !isHTMLElementNode(candidate) ||
-            candidate === element ||
-            !isVisible(candidate)
-          ) {
-            return;
-          }
+      const explicitSurfaceKindOf = (surface) => {
+        if (!isHTMLElementNode(surface)) {
+          return undefined;
+        }
 
-          const priority = surfacePriorityOf(candidate);
-          if (priority <= 0) {
-            return;
-          }
+        const positionedSurface = surfacePositionTraitsOf(surface);
+        if (positionedSurface?.kind) {
+          return positionedSurface.kind;
+        }
 
-          if (ranked.some((entry) => entry.element === candidate)) {
-            return;
-          }
+        const role = surface.getAttribute('role')?.trim() || '';
+        if (role === 'dialog') return 'dialog';
+        if (role === 'listbox') return 'listbox';
+        if (role === 'menu') return 'menu';
+        if (role === 'grid') return 'grid';
+        if (role === 'tabpanel') return 'tabpanel';
 
-          ranked.push({ element: candidate, priority, depth });
-        };
+        const className = (surface.getAttribute('class') || '').toLowerCase();
+        if (className.includes('calendar') || className.includes('datepicker')) return 'datepicker';
+        if (className.includes('popover')) return 'popover';
+        if (className.includes('dropdown')) return 'dropdown';
 
-        pushCandidate(itemOf(element), 0);
-        pushCandidate(containerOf(element), 1);
+        const tag = surface.tagName.toLowerCase();
+        if (tag === 'form') return 'form';
+        return undefined;
+      };
 
+      const explicitSurfaceOf = (element) => {
         let current = composedParentElement(element);
         let depth = 0;
-        while (current && depth < 16) {
-          pushCandidate(current, depth + 2);
+
+        while (current && depth < structuralAncestorSearchDepth) {
+          incrementStructuralProfileDebugStat('explicitSurfaceAncestorVisits');
+          if (structuralProfileOf(current)?.explicitSurfaceKind) {
+            return current;
+          }
           current = composedParentElement(current);
           depth += 1;
         }
 
-        ranked.sort((left, right) => {
-          if (left.priority !== right.priority) {
-            return right.priority - left.priority;
-          }
-          return left.depth - right.depth;
-        });
-
-        return ranked[0]?.element;
+        return undefined;
       };
 
-      const surfaceSelectorsOf = (element, localSurface) => {
+      const surfaceSelectorsOf = (element, explicitSurface) => {
         const selectors = [];
-        let current = element.parentElement;
+        let current = composedParentElement(element);
 
         while (current) {
-          if (current.matches?.(overlaySurfaceSelector)) {
-            const selector = buildSelector(current);
+          incrementStructuralProfileDebugStat('surfaceSelectorAncestorVisits');
+          const currentProfile = structuralProfileOf(current);
+          if (currentProfile?.explicitSurfaceKind) {
+            const selector = currentProfile.selector;
             if (selector && !selectors.includes(selector)) {
               selectors.push(selector);
             }
           }
-          current = current.parentElement;
+          current = composedParentElement(current);
         }
 
-        if (localSurface) {
-          const selector = buildSelector(localSurface);
+        if (explicitSurface) {
+          const selector = structuralProfileOf(explicitSurface)?.selector;
           if (selector && !selectors.includes(selector)) {
             selectors.push(selector);
           }
@@ -3246,6 +3499,413 @@ async function collectDomTargetsFromDocument(context, options) {
         return selectors.length > 0 ? selectors : undefined;
       };
 
+      const directContextTextProfileCache = new WeakMap();
+
+      const directContextTextProfileOf = (candidate) => {
+        if (!isHTMLElementNode(candidate)) {
+          return undefined;
+        }
+
+        const cachedProfile = directContextTextProfileCache.get(candidate);
+        if (cachedProfile) {
+          return cachedProfile;
+        }
+        if (cachedProfile === null) {
+          return undefined;
+        }
+
+        const children = [];
+        for (const child of Array.from(candidate.children).slice(0, 12)) {
+          if (!isHTMLElementNode(child) || !isVisible(child)) {
+            continue;
+          }
+
+          const tag = child.tagName.toLowerCase();
+          if (
+            ['button', 'input', 'textarea', 'select', 'a', 'svg', 'img'].includes(tag) ||
+            child.matches?.(selector)
+          ) {
+            continue;
+          }
+
+          const normalized = normalizeDescriptorText(textOf(child, { container: true }));
+          if (!normalized) {
+            continue;
+          }
+
+          const semanticText = normalized
+            .replace(observedLooseActionTextRe, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
+          if (!semanticText || semanticText.length < 2) {
+            continue;
+          }
+
+          children.push(child);
+        }
+
+        const profile = {
+          count: children.length,
+          children,
+        };
+        directContextTextProfileCache.set(candidate, profile);
+        return profile;
+      };
+
+      const directContextTextBlockCountOf = (candidate, excludedTarget) => {
+        const profile = directContextTextProfileOf(candidate);
+        if (!profile) {
+          return 0;
+        }
+
+        if (
+          isHTMLElementNode(excludedTarget) &&
+          profile.children.includes(excludedTarget)
+        ) {
+          return Math.max(0, profile.count - 1);
+        }
+
+        return profile.count;
+      };
+
+      const ownerCandidateShapeKeyCache = new WeakMap();
+
+      const ownerCandidateShapeKeyOf = (candidate) => {
+        const cachedShapeKey = ownerCandidateShapeKeyCache.get(candidate);
+        if (typeof cachedShapeKey === 'string') {
+          return cachedShapeKey;
+        }
+
+        const tag = candidate.tagName.toLowerCase();
+        const role = candidate.getAttribute('role')?.trim().toLowerCase() || '';
+        const className = (candidate.getAttribute('class') || '')
+          .trim()
+          .toLowerCase()
+          .split(/\s+/)
+          .filter(Boolean)
+          .sort()
+          .join('.');
+        const shapeKey = tag + '|' + role + '|' + className;
+        ownerCandidateShapeKeyCache.set(candidate, shapeKey);
+        return shapeKey;
+      };
+
+      const ownerCandidatePeerCountOf = (
+        candidate,
+        directTextBlockCount,
+        descendantInteractiveCount
+      ) => {
+        const parent = composedParentElement(candidate);
+        if (!isHTMLElementNode(parent)) {
+          return 0;
+        }
+
+        const candidateShapeKey = ownerCandidateShapeKeyOf(candidate);
+        const candidateChildCount = candidate.children.length;
+        let peerCount = 0;
+
+        for (const sibling of Array.from(parent.children)) {
+          if (!isHTMLElementNode(sibling) || sibling === candidate || !isVisible(sibling)) {
+            continue;
+          }
+          if (ownerCandidateShapeKeyOf(sibling) !== candidateShapeKey) {
+            continue;
+          }
+
+          const siblingInteractiveCount = visibleInteractiveDescendantCountOf(sibling);
+          const siblingTextBlockCount = directContextTextBlockCountOf(sibling);
+          if (Math.abs(siblingInteractiveCount - descendantInteractiveCount) > 1) {
+            continue;
+          }
+          if (Math.abs(siblingTextBlockCount - directTextBlockCount) > 1) {
+            continue;
+          }
+          if (Math.abs(sibling.children.length - candidateChildCount) > 1) {
+            continue;
+          }
+
+          peerCount += 1;
+        }
+
+        return peerCount;
+      };
+
+      const ownerBoundaryMetaOf = (candidate, coverage, descendantInteractiveCount) => {
+        if (!isHTMLElementNode(candidate)) {
+          return undefined;
+        }
+
+        const positionedSurface = surfacePositionTraitsOf(candidate);
+        if (positionedSurface?.kind) {
+          return {
+            kind: positionedSurface.kind,
+            stop: 'hard',
+          };
+        }
+
+        const role = candidate.getAttribute('role')?.trim().toLowerCase() || '';
+        if (role === 'dialog' || candidate.getAttribute('aria-modal') === 'true') {
+          return {
+            kind: 'dialog',
+            stop: 'hard',
+          };
+        }
+        if (['listbox', 'menu', 'grid', 'tabpanel'].includes(role)) {
+          return {
+            kind: role,
+            stop: 'soft',
+          };
+        }
+
+        const tag = candidate.tagName.toLowerCase();
+        if (tag === 'form') {
+          return {
+            kind: 'form',
+            stop: 'hard',
+          };
+        }
+
+        const className = (candidate.getAttribute('class') || '').toLowerCase();
+        if (className.includes('calendar') || className.includes('datepicker')) {
+          return {
+            kind: 'datepicker',
+            stop: 'hard',
+          };
+        }
+        if (className.includes('popover')) {
+          return {
+            kind: 'popover',
+            stop: 'hard',
+          };
+        }
+        if (className.includes('dropdown')) {
+          return {
+            kind: 'dropdown',
+            stop: 'hard',
+          };
+        }
+
+        if (
+          ['main', 'aside', 'section'].includes(tag) &&
+          (coverage >= 0.24 || descendantInteractiveCount > 4)
+        ) {
+          return {
+            kind: tag,
+            stop: 'hard',
+          };
+        }
+
+        return undefined;
+      };
+
+      const structuralProfileOf = (element) => {
+        if (!isHTMLElementNode(element) || !isVisible(element)) {
+          return undefined;
+        }
+
+        const cachedProfile = structuralProfileCache.get(element);
+        if (cachedProfile) {
+          return cachedProfile;
+        }
+        if (cachedProfile === null) {
+          return undefined;
+        }
+
+        const rect = element.getBoundingClientRect();
+        const area = Math.max(rect.width * rect.height, 1);
+        const coverage = area / viewportArea();
+        const descendantInteractiveCount = visibleInteractiveDescendantCountOf(element);
+        const descendantEditableCount = descendantEditableCountOf(element);
+        const boundaryMeta = ownerBoundaryMetaOf(
+          element,
+          coverage,
+          descendantInteractiveCount
+        );
+        const profile = {
+          selector: buildSelector(element),
+          area,
+          coverage,
+          descendantInteractiveCount,
+          descendantEditableCount,
+          directTextBlockCount: directContextTextBlockCountOf(element),
+          boundaryMeta,
+          explicitSurfaceKind: explicitSurfaceKindOf(element),
+          inferredSurfaceKind: inferSurfaceKind(element),
+          contextNode: contextNodeOf(element),
+          surfacePriority: surfacePriorityOf(element),
+          tag: element.tagName.toLowerCase(),
+          role: element.getAttribute('role')?.trim().toLowerCase() || '',
+        };
+        structuralProfileCache.set(element, profile);
+        incrementStructuralProfileDebugStat('structuralProfileBuilds');
+        return profile;
+      };
+
+      const ownerCandidateSurfacePriorityOf = (surfaceKind, fallbackPriority) => {
+        if (typeof fallbackPriority === 'number' && fallbackPriority > 0) {
+          return fallbackPriority;
+        }
+
+        switch ((surfaceKind || '').toLowerCase()) {
+          case 'dialog':
+            return 100;
+          case 'listbox':
+          case 'menu':
+            return 95;
+          case 'floating-panel':
+            return 92;
+          case 'datepicker':
+            return 90;
+          case 'sticky-panel':
+            return 88;
+          case 'popover':
+          case 'dropdown':
+            return 85;
+          case 'grid':
+          case 'tabpanel':
+            return 80;
+          case 'form':
+            return 70;
+          case 'card':
+            return 58;
+          case 'group':
+            return 55;
+          case 'section':
+          case 'aside':
+            return 52;
+          case 'listitem':
+          case 'row':
+            return 48;
+          default:
+            return undefined;
+        }
+      };
+
+      const ownerCandidateSurfaceKindOf = (candidateProfile, metrics) => {
+        if (!candidateProfile) {
+          return undefined;
+        }
+
+        if (metrics.boundaryKind) {
+          return metrics.boundaryKind;
+        }
+
+        const inferredSurfaceKind = candidateProfile.inferredSurfaceKind;
+        if (inferredSurfaceKind && inferredSurfaceKind !== 'div') {
+          return inferredSurfaceKind;
+        }
+
+        const tag = candidateProfile.tag;
+        const role = candidateProfile.role;
+
+        if (tag === 'article') {
+          return 'card';
+        }
+        if (tag === 'fieldset') {
+          return 'group';
+        }
+        if (tag === 'li' || role === 'listitem') {
+          return 'listitem';
+        }
+        if (role === 'row') {
+          return 'row';
+        }
+
+        const itemLikeCard =
+          metrics.directTextBlockCount >= 2 &&
+          metrics.descendantInteractiveCount >= 1 &&
+          metrics.descendantInteractiveCount <= 4 &&
+          metrics.coverage <= 0.45 &&
+          metrics.relativeAreaToTarget >= 2 &&
+          (metrics.peerCount >= 1 || metrics.descendantInteractiveCount === 1);
+        if (itemLikeCard) {
+          return 'card';
+        }
+
+        return inferredSurfaceKind;
+      };
+
+      const ownerCandidatesOf = (target) => {
+        const targetRect = target.getBoundingClientRect();
+        const targetArea = Math.max(targetRect.width * targetRect.height, 1);
+        const candidates = [];
+        let current = composedParentElement(target);
+        let depth = 0;
+
+        while (current && depth < structuralAncestorSearchDepth) {
+          incrementStructuralProfileDebugStat('ownerCandidateAncestorVisits');
+          const candidateProfile = structuralProfileOf(current);
+          if (!candidateProfile) {
+            current = composedParentElement(current);
+            depth += 1;
+            continue;
+          }
+
+          const selectorValue = candidateProfile.selector;
+          if (!selectorValue) {
+            current = composedParentElement(current);
+            depth += 1;
+            continue;
+          }
+
+          const candidateArea = candidateProfile.area;
+          const coverage = candidateProfile.coverage;
+          const descendantInteractiveCount = candidateProfile.descendantInteractiveCount;
+          const descendantEditableCount = candidateProfile.descendantEditableCount;
+          const directTextBlockCount = directContextTextBlockCountOf(current, target);
+          const peerCount = ownerCandidatePeerCountOf(
+            current,
+            directTextBlockCount,
+            descendantInteractiveCount
+          );
+          const boundaryMeta = candidateProfile.boundaryMeta;
+          const boundaryKind = boundaryMeta?.kind;
+          const surfaceKind = ownerCandidateSurfaceKindOf(candidateProfile, {
+            boundaryKind,
+            coverage,
+            directTextBlockCount,
+            descendantInteractiveCount,
+            peerCount,
+            relativeAreaToTarget: candidateArea / targetArea,
+          });
+          const shell =
+            surfaceKind === 'sticky-panel' ||
+            surfaceKind === 'floating-panel' ||
+            (['main', 'aside', 'section'].includes(candidateProfile.tag) &&
+              (coverage >= 0.24 || descendantInteractiveCount > 4));
+          const boundary = Boolean(boundaryKind) || shell;
+          const stopSearch = shell || boundaryMeta?.stop === 'hard';
+          const contextNode = candidateProfile.contextNode;
+          candidates.push({
+            ...contextNode,
+            selector: selectorValue,
+            depth,
+            surfaceKind,
+            surfacePriority: ownerCandidateSurfacePriorityOf(
+              surfaceKind,
+              candidateProfile.surfacePriority
+            ),
+            directTextBlockCount,
+            peerCount,
+            descendantInteractiveCount,
+            descendantEditableCount,
+            viewportCoverage: coverage,
+            relativeAreaToTarget: candidateArea / targetArea,
+            boundary,
+            shell,
+          });
+
+          if (stopSearch) {
+            break;
+          }
+
+          current = composedParentElement(current);
+          depth += 1;
+        }
+
+        return candidates.length > 0 ? candidates : undefined;
+      };
+
       const targets = elements.map((element, ordinal) => {
         const visualSeatGrid = visualSeatGridMeta.get(element);
         const associatedChoiceControl = associatedChoiceControlOf(element);
@@ -3277,16 +3937,9 @@ async function collectDomTargetsFromDocument(context, options) {
         const item =
           (compactClickableAffordance ? compactClickableItemOf(element) : undefined) ||
           itemOf(element);
-        const overlaySurface = composedClosest(element, overlaySurfaceSelector);
-        const localSurface = localSurfaceCandidateOf(element);
-        const selfSurface =
-          genericClickable && !associatedChoiceControl && isStructuredContainer(element)
-            ? element
-            : undefined;
-        const surface =
-          visualSeatGrid?.surface ||
-          (isHTMLElementNode(overlaySurface) ? overlaySurface : localSurface || selfSurface);
-        const surfaceSelectors = surfaceSelectorsOf(element, localSurface || selfSurface);
+        const explicitSurface = explicitSurfaceOf(element);
+        const surface = visualSeatGrid?.surface || explicitSurface;
+        const surfaceSelectors = surfaceSelectorsOf(element, explicitSurface);
         const structure = visualSeatGrid?.structure || inferStructuredCell(element, surface);
         const directFallbackLabel = explicitLabelOf(element) || looseFieldLabelOf(element);
         const directionalFallbackLabel = directionalControlFallbackLabelOf(
@@ -3297,10 +3950,23 @@ async function collectDomTargetsFromDocument(context, options) {
         const currentValue = popupCurrentValueOf(element);
         const selection = selectionOf(element);
         const role = inferRole(element) || inferRole(associatedChoiceControl);
-        const surfaceKind = visualSeatGrid?.surfaceKind || surfaceKindOf(surface);
+        const elementProfile = structuralProfileOf(element);
+        const surfaceProfile = surface ? structuralProfileOf(surface) : undefined;
+        const explicitSurfaceProfile = explicitSurface
+          ? structuralProfileOf(explicitSurface)
+          : undefined;
+        const surfaceKind =
+          visualSeatGrid?.surfaceKind ||
+          surfaceProfile?.inferredSurfaceKind ||
+          surfaceKindOf(surface);
         const fallbackSurfaceLabel =
           (visualSeatGrid?.hintText ? 'Seat map' : undefined) ||
           surfaceFallbackLabelOf(surface, surfaceKind);
+        const explicitSurfaceKind = explicitSurfaceProfile?.explicitSurfaceKind;
+        const explicitFallbackSurfaceLabel =
+          explicitSurface && explicitSurfaceKind
+            ? surfaceFallbackLabelOf(explicitSurface, explicitSurfaceKind)
+            : undefined;
         const form = composedClosest(element, 'form');
         const testIdAttribute = element.hasAttribute('data-testid')
           ? 'data-testid'
@@ -3350,17 +4016,28 @@ async function collectDomTargetsFromDocument(context, options) {
           surfaceKind,
           surfaceLabel: fallbackSurfaceLabel,
           fallbackSurfaceLabel,
-          surfaceSelector: surface ? buildSelector(surface) : undefined,
+          surfaceSelector: surfaceProfile?.selector,
           surfaceSelectors,
-          surfacePriority: surfacePriorityOf(surface),
+          surfacePriority: surfaceProfile?.surfacePriority ?? surfacePriorityOf(surface),
+          explicitSurfaceKind,
+          explicitSurfaceLabel: explicitFallbackSurfaceLabel,
+          explicitFallbackSurfaceLabel,
+          explicitSurfaceSelector: explicitSurfaceProfile?.selector,
+          explicitSurfaceSelectors: surfaceSelectors,
+          explicitSurfacePriority:
+            explicitSurfaceProfile?.surfacePriority ??
+            (explicitSurface ? surfacePriorityOf(explicitSurface) : undefined),
           controlsSurfaceSelector:
             selectorFromRelation(element, 'aria-controls') || selectorFromRelation(element, 'aria-owns'),
           formSelector: form ? buildSelector(form) : undefined,
           pageFormSelector: form ? buildSelector(form) : inheritedPageFormSelector || undefined,
-          descendantInteractiveCount: element.querySelectorAll(selector).length,
-          descendantEditableCount: element.querySelectorAll(
-            'input:not([type="hidden"]), textarea, select, [contenteditable="true"]'
-          ).length,
+          descendantInteractiveCount:
+            elementProfile?.descendantInteractiveCount ?? element.querySelectorAll(selector).length,
+          descendantEditableCount:
+            elementProfile?.descendantEditableCount ??
+            element.querySelectorAll(
+              'input:not([type="hidden"]), textarea, select, [contenteditable="true"]'
+            ).length,
           structure,
           ordinal,
           context: {
@@ -3375,11 +4052,15 @@ async function collectDomTargetsFromDocument(context, options) {
             hintText: describedByTextOf(element),
             fallbackHintText: visualSeatGrid?.hintText,
             visual: visualOf(element),
+            ownerCandidates: ownerCandidatesOf(element),
           },
         };
       });
 
-      return targets;
+      return {
+        targets,
+        debugStats: structuralProfileDebugStats,
+      };
     };
 
     const enrichDisplayLabels = (targets) => {
@@ -3482,8 +4163,9 @@ async function collectDomTargetsFromDocument(context, options) {
       return score;
     };
 
+    const collectionResult = collectTargets(document);
     const seen = new Set();
-    return enrichDisplayLabels(collectTargets(document))
+    const finalTargets = enrichDisplayLabels(collectionResult.targets)
       .filter((candidate) => {
         const frameKey = candidate.framePath ? candidate.framePath.join(' -> ') : 'top';
         const key = frameKey + '|' + (candidate.selector || candidate.domSignature || '');
@@ -3512,18 +4194,55 @@ async function collectDomTargetsFromDocument(context, options) {
         return left.index - right.index;
       })
       .map(({ candidate }) => candidate);
+
+    return debugStructuralProfileStats
+      ? {
+          targets: finalTargets,
+          debugStats: collectionResult.debugStats,
+        }
+      : finalTargets;
   })()`);
-    if (!Array.isArray(observedTargets)) {
-        return [];
+    let observedTargets = [];
+    let debugStats;
+    if (Array.isArray(observedPayload)) {
+        observedTargets = observedPayload;
+    }
+    else if (observedPayload &&
+        typeof observedPayload === 'object' &&
+        Array.isArray(observedPayload.targets)) {
+        observedTargets = observedPayload.targets;
+        const candidateDebugStats = observedPayload.debugStats;
+        if (candidateDebugStats &&
+            typeof candidateDebugStats === 'object' &&
+            typeof candidateDebugStats
+                .structuralProfileBuilds === 'number' &&
+            typeof candidateDebugStats
+                .ownerCandidateAncestorVisits === 'number' &&
+            typeof candidateDebugStats
+                .explicitSurfaceAncestorVisits === 'number' &&
+            typeof candidateDebugStats
+                .surfaceSelectorAncestorVisits === 'number') {
+            debugStats = candidateDebugStats;
+        }
     }
-    return observedTargets
-        .filter((target) => Boolean(target && typeof target === 'object' && typeof target.kind === 'string'))
+    const targets = observedTargets
+        .filter((target) => Boolean(target &&
+        typeof target === 'object' &&
+        typeof target.kind === 'string'))
         .map((target) => enrichObservedTargetSemantics(applyInheritedDomTargetMetadata(target, {
         framePath: options?.framePath,
         frameUrl: options?.frameUrl,
         pageSignature: options?.pageSignature,
         pageFormSelector: options?.pageFormSelector,
     })));
+    return {
+        targets,
+        debugStats,
+    };
+}
+async function collectDomTargetsFromDocument(context, options) {
+    const { targets } = await collectDomTargetsFromDocumentRaw(context, options);
+    return targets;
 }
 const FRAME_HOST_DESCRIPTOR_SCRIPT = String.raw `
   const ownerWindowOf = (node) => node?.ownerDocument?.defaultView || window;
@@ -3844,6 +4563,10 @@ export async function collectDomTargets(page, options) {
 }
 export const __testDomTargetCollection = {
     collectDomTargetsFromDocument,
+    collectDomTargetsDebugFromDocument: (context, options) => collectDomTargetsFromDocumentRaw(context, {
+        ...options,
+        debugStructuralProfileStats: true,
+    }),
     inferStructuredCellVariantFromEvidence,
     inferDirectionalControlFallbackFromEvidence,
     locatorDomSignatureScript: LOCATOR_DOM_SIGNATURE_SCRIPT,