@nuanu-ai/agentbrowse 0.2.29 → 0.2.31

package/README.md

@@ -165,6 +165,9 @@ overrides.
 Human-readable progress is written to `stderr`. Command results are written to
 `stdout`.
 
+When `launch` detects a newer npm release, it prints the reminder to `stderr`
+without changing the JSON result written to `stdout`.
+
 `observe()` and `extract()` responses expose where runtime work came from:
 
 - top-level `source` shows the winning execution source, for example `dom` or `stagehand`

package/dist/commands/extract-snapshot-sanitizer.d.ts

@@ -1,2 +1,5 @@
 export declare function sanitizeExtractSnapshot(snapshot: string): string;
+export declare function budgetExtractSnapshot(snapshot: string, options?: {
+    scoped?: boolean;
+}): string;
 //# sourceMappingURL=extract-snapshot-sanitizer.d.ts.map

package/dist/commands/extract-snapshot-sanitizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-snapshot-sanitizer.d.ts","sourceRoot":"","sources":["../../src/commands/extract-snapshot-sanitizer.ts"],"names":[],"mappings":"AAuEA,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQhE"}
+{"version":3,"file":"extract-snapshot-sanitizer.d.ts","sourceRoot":"","sources":["../../src/commands/extract-snapshot-sanitizer.ts"],"names":[],"mappings":"AAyEA,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQhE;AA4BD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,MAAM,CAcR"}

package/dist/commands/extract-snapshot-sanitizer.js

@@ -1,6 +1,8 @@
 const SUSPICIOUS_LINE_LENGTH = 220;
 const SUSPICIOUS_TOKEN_LENGTH = 120;
 const MIN_MACHINE_PUNCTUATION_RATIO = 0.18;
+const MAX_SCOPED_EXTRACT_LINES = 160;
+const MAX_SCOPED_EXTRACT_CHARS = 12_000;
 const SCRIPT_MARKERS = [
     /\bwindow\./i,
     /\bdocument\./i,
@@ -63,3 +65,34 @@ export function sanitizeExtractSnapshot(snapshot) {
     });
     return sanitized.some((line) => line.trim()) ? sanitized.join('\n') : snapshot;
 }
+function trimSnapshotToBudget(snapshot, options) {
+    const lines = snapshot.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    const kept = [];
+    let totalChars = 0;
+    for (const line of lines) {
+        const nextChars = totalChars + line.length + (kept.length > 0 ? 1 : 0);
+        if (kept.length >= options.maxLines || nextChars > options.maxChars) {
+            break;
+        }
+        kept.push(line);
+        totalChars = nextChars;
+    }
+    if (kept.length === 0) {
+        return snapshot;
+    }
+    const trimmed = kept.join('\n');
+    return trimmed.length >= Math.floor(snapshot.length * 0.35) ? trimmed : snapshot;
+}
+export function budgetExtractSnapshot(snapshot, options = {}) {
+    if (!options.scoped) {
+        return snapshot;
+    }
+    const lines = snapshot.split(/\r?\n/);
+    if (lines.length <= MAX_SCOPED_EXTRACT_LINES && snapshot.length <= MAX_SCOPED_EXTRACT_CHARS) {
+        return snapshot;
+    }
+    return trimSnapshotToBudget(snapshot, {
+        maxLines: MAX_SCOPED_EXTRACT_LINES,
+        maxChars: MAX_SCOPED_EXTRACT_CHARS,
+    });
+}

package/dist/commands/extract-stagehand-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-stagehand-executor.d.ts","sourceRoot":"","sources":["../../src/commands/extract-stagehand-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAI5C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAA8B,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAI9F,MAAM,MAAM,yBAAyB,GAAG,iBAAiB,GAAG;IAC1D,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,mBAAmB,CAAC;CACjC,CAAC;AAiBF,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAsDrC"}
+{"version":3,"file":"extract-stagehand-executor.d.ts","sourceRoot":"","sources":["../../src/commands/extract-stagehand-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAI5C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAA8B,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAK9F,MAAM,MAAM,yBAAyB,GAAG,iBAAiB,GAAG;IAC1D,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,mBAAmB,CAAC;CACjC,CAAC;AAiEF,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAwFrC"}

package/dist/commands/extract-stagehand-executor.js

@@ -1,10 +1,41 @@
 import { extract as runExtract } from '@browserbasehq/stagehand/lib/inference.js';
 import { v3Logger } from '@browserbasehq/stagehand/lib/v3/logger.js';
 import { captureHybridSnapshot } from '@browserbasehq/stagehand/lib/v3/understudy/a11y/snapshot/index.js';
-import { incrementMetric } from '../runtime-state.js';
+import { incrementMetric, recordLlmUsage, recordPayloadBudget } from '../runtime-state.js';
 import { stagehandRuntimeResolution } from '../runtime-resolution.js';
 import { withStagehand } from '../stagehand-runtime.js';
-import { sanitizeExtractSnapshot } from './extract-snapshot-sanitizer.js';
+import { readLocatorOuterHtml } from './descriptor-validation.js';
+import { budgetExtractSnapshot, sanitizeExtractSnapshot } from './extract-snapshot-sanitizer.js';
+const SCOPED_EXTRACT_MIRROR_SELECTOR = '#agentbrowse-scope';
+async function mirrorScopedSnapshotPage(page, selector) {
+    if (!selector || selector === SCOPED_EXTRACT_MIRROR_SELECTOR) {
+        return null;
+    }
+    const locator = page.locator(selector);
+    const first = locator.first();
+    const count = typeof first.count === 'function' ? await first.count().catch(() => 0) : 1;
+    if (count === 0) {
+        return null;
+    }
+    let scopedHtml = await readLocatorOuterHtml(first).catch(() => null);
+    if (!scopedHtml) {
+        scopedHtml = await first
+            .evaluate((element) => (element instanceof Element ? element.outerHTML : null))
+            .catch(() => null);
+    }
+    if (!scopedHtml) {
+        return null;
+    }
+    const scratchPage = await page.context().newPage();
+    await scratchPage.setContent(`<!doctype html><html lang="en"><body><div id="agentbrowse-scope">${scopedHtml}</div></body></html>`);
+    return {
+        page: scratchPage,
+        focusSelector: SCOPED_EXTRACT_MIRROR_SELECTOR,
+        cleanup: async () => {
+            await scratchPage.close().catch(() => undefined);
+        },
+    };
+}
 export async function executeStagehandExtract(args) {
     const { session, instruction, schema, page, selector, degradationReason } = args;
     const data = await withStagehand(session, async (stagehand) => {
@@ -21,24 +52,57 @@ export async function executeStagehandExtract(args) {
             });
         }
         const extractPage = await resolvePage.call(internalStagehand, page);
-        const focusSelector = selector?.replace(/^xpath=/i, '') ?? '';
-        const snapshot = await captureHybridSnapshot(extractPage, {
-            experimental: internalStagehand.experimental ?? false,
-            focusSelector,
-        });
-        // Deferred decision: budget-aware narrowing stays separate from this change.
-        const sanitizedTree = sanitizeExtractSnapshot(snapshot.combinedTree);
-        const extractionResponse = await runExtract({
-            instruction,
-            domElements: sanitizedTree,
-            schema: schema,
-            llmClient: internalStagehand.llmClient,
-            userProvidedInstructions: internalStagehand.opts?.systemPrompt ?? '',
-            logger: v3Logger,
-            logInferenceToFile: internalStagehand.logInferenceToFile ?? false,
-        });
-        const { metadata: _metadata, prompt_tokens: _promptTokens, completion_tokens: _completionTokens, reasoning_tokens: _reasoningTokens, cached_input_tokens: _cachedInputTokens, inference_time_ms: _inferenceTimeMs, ...result } = extractionResponse;
-        return result;
+        let snapshotPage = extractPage;
+        let focusSelector = selector?.replace(/^xpath=/i, '') ?? '';
+        let cleanupMirroredSnapshot = null;
+        try {
+            if (selector) {
+                const mirroredSnapshot = await mirrorScopedSnapshotPage(page, selector);
+                if (mirroredSnapshot) {
+                    cleanupMirroredSnapshot = mirroredSnapshot.cleanup;
+                    snapshotPage = await resolvePage.call(internalStagehand, mirroredSnapshot.page);
+                    focusSelector = mirroredSnapshot.focusSelector;
+                }
+            }
+            const snapshot = await captureHybridSnapshot(snapshotPage, {
+                experimental: internalStagehand.experimental ?? false,
+                focusSelector,
+            });
+            recordPayloadBudget(session, {
+                extractSnapshotLinesSeen: snapshot.combinedTree.split(/\r?\n/).length,
+            });
+            const sanitizedTree = sanitizeExtractSnapshot(snapshot.combinedTree);
+            const budgetedTree = budgetExtractSnapshot(sanitizedTree, {
+                scoped: Boolean(selector),
+            });
+            recordPayloadBudget(session, {
+                extractSnapshotLinesSent: budgetedTree.split(/\r?\n/).length,
+            });
+            const extractionResponse = await runExtract({
+                instruction,
+                domElements: budgetedTree,
+                schema: schema,
+                llmClient: internalStagehand.llmClient,
+                userProvidedInstructions: internalStagehand.opts?.systemPrompt ?? '',
+                logger: v3Logger,
+                logInferenceToFile: internalStagehand.logInferenceToFile ?? false,
+            });
+            const { metadata: _metadata, prompt_tokens: promptTokens, completion_tokens: completionTokens, reasoning_tokens: reasoningTokens, cached_input_tokens: cachedInputTokens, inference_time_ms: _inferenceTimeMs, ...result } = extractionResponse;
+            recordLlmUsage(session, {
+                purpose: 'browse.extract',
+                inputChars: budgetedTree.length,
+                promptTokens: typeof promptTokens === 'number' ? promptTokens : undefined,
+                completionTokens: typeof completionTokens === 'number' ? completionTokens : undefined,
+                cachedInputTokens: typeof cachedInputTokens === 'number' ? cachedInputTokens : undefined,
+                reasoningTokens: typeof reasoningTokens === 'number' ? reasoningTokens : undefined,
+            });
+            return result;
+        }
+        finally {
+            if (cleanupMirroredSnapshot) {
+                await cleanupMirroredSnapshot().catch(() => undefined);
+            }
+        }
     });
     return {
         resolvedBy: 'stagehand-extract',

package/dist/commands/observe-inventory.d.ts

@@ -93,7 +93,16 @@ type StructuredCellVariantEvidence = {
     hasSeatColumnAttribute?: boolean;
     hasDateMetadata?: boolean;
 };
+export type DirectionalControlFallbackPosition = 'leading' | 'trailing' | 'upper' | 'lower';
+export type DirectionalControlFallbackEvidence = {
+    kind?: string;
+    role?: string;
+    groupLabel?: string;
+    anchorText?: string;
+    position?: DirectionalControlFallbackPosition;
+};
 export declare function inferStructuredCellVariantFromEvidence(evidence: StructuredCellVariantEvidence): 'date-cell' | 'seat-cell' | 'grid-cell' | undefined;
+export declare function inferDirectionalControlFallbackFromEvidence(evidence: DirectionalControlFallbackEvidence): string | undefined;
 export declare function readStagehandLocatorSnapshot(locator: Locator): Promise<StagehandLocatorSnapshot>;
 declare function readStagehandDomFactsInBrowser(element: Element): StagehandDomFacts | null;
 declare function readStagehandDomFacts(locator: Locator): Promise<StagehandDomFacts | null>;
@@ -114,6 +123,7 @@ export declare function collectDomTargets(page: {
 export declare const __testDomTargetCollection: {
     collectDomTargetsFromDocument: typeof collectDomTargetsFromDocument;
     inferStructuredCellVariantFromEvidence: typeof inferStructuredCellVariantFromEvidence;
+    inferDirectionalControlFallbackFromEvidence: typeof inferDirectionalControlFallbackFromEvidence;
     locatorDomSignatureScript: string;
 };
 export declare const __testStagehandDescriptor: {

package/dist/commands/observe-inventory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe-inventory.d.ts","sourceRoot":"","sources":["../../src/commands/observe-inventory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"observe-inventory.d.ts","sourceRoot":"","sources":["../../src/commands/observe-inventory.ts"],"names":[],"mappings":"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"}

package/dist/commands/observe-inventory.js

@@ -31,7 +31,78 @@ export function inferStructuredCellVariantFromEvidence(evidence) {
     }
     return undefined;
 }
+export function inferDirectionalControlFallbackFromEvidence(evidence) {
+    const normalize = (value) => {
+        const normalized = (value ?? '').replace(/\s+/g, ' ').trim();
+        return normalized || undefined;
+    };
+    const normalizedKind = normalize(evidence.kind)?.toLowerCase();
+    const normalizedRole = normalize(evidence.role)?.toLowerCase();
+    const buttonLike = normalizedKind === 'button' ||
+        normalizedRole === 'button' ||
+        (normalizedKind === 'input' && normalizedRole === 'button');
+    if (!buttonLike) {
+        return undefined;
+    }
+    const position = normalize(evidence.position)?.toLowerCase();
+    const anchorText = normalize(evidence.anchorText);
+    const groupLabel = normalize(evidence.groupLabel);
+    if (!position || !anchorText) {
+        return undefined;
+    }
+    const monthYearLike = /\b(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:t(?:ember)?)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?|январ|феврал|март|апрел|ма[йя]|июн|июл|август|сентябр|октябр|ноябр|декабр)\b/i.test(anchorText);
+    if (monthYearLike && (position === 'leading' || position === 'trailing')) {
+        return position === 'leading' ? 'Previous month' : 'Next month';
+    }
+    const counterLike = /^\d{1,3}$/.test(anchorText);
+    if (counterLike && groupLabel && (position === 'leading' || position === 'trailing')) {
+        const subject = groupLabel.toLowerCase();
+        return position === 'leading' ? `Decrease ${subject}` : `Increase ${subject}`;
+    }
+    return undefined;
+}
 const INFER_STRUCTURED_CELL_VARIANT_HELPER_SCRIPT = `const inferStructuredCellVariantFromEvidence = ${inferStructuredCellVariantFromEvidence.toString()};`;
+const INFER_DIRECTIONAL_CONTROL_FALLBACK_HELPER_SCRIPT = String.raw `
+    const inferDirectionalControlFallbackFromEvidence = (evidence) => {
+      const normalizeDirectionalControlFallbackValue = (value) => {
+        const normalized = (value || '').replace(/\s+/g, ' ').trim();
+        return normalized || undefined;
+      };
+
+      const normalizedKind = normalizeDirectionalControlFallbackValue(evidence?.kind)?.toLowerCase();
+      const normalizedRole = normalizeDirectionalControlFallbackValue(evidence?.role)?.toLowerCase();
+      const buttonLike =
+        normalizedKind === 'button' ||
+        normalizedRole === 'button' ||
+        (normalizedKind === 'input' && normalizedRole === 'button');
+      if (!buttonLike) {
+        return undefined;
+      }
+
+      const position = normalizeDirectionalControlFallbackValue(evidence?.position)?.toLowerCase();
+      const anchorText = normalizeDirectionalControlFallbackValue(evidence?.anchorText);
+      const groupLabel = normalizeDirectionalControlFallbackValue(evidence?.groupLabel);
+      if (!position || !anchorText) {
+        return undefined;
+      }
+
+      const monthYearLike =
+        /\b(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:t(?:ember)?)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?|январ|феврал|март|апрел|ма[йя]|июн|июл|август|сентябр|октябр|ноябр|декабр)\b/i.test(
+          anchorText
+        );
+      if (monthYearLike && (position === 'leading' || position === 'trailing')) {
+        return position === 'leading' ? 'Previous month' : 'Next month';
+      }
+
+      const counterLike = /^\d{1,3}$/.test(anchorText);
+      if (counterLike && groupLabel && (position === 'leading' || position === 'trailing')) {
+        const subject = groupLabel.toLowerCase();
+        return position === 'leading' ? 'Decrease ' + subject : 'Increase ' + subject;
+      }
+
+      return undefined;
+    };
+`;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -352,6 +423,7 @@ async function collectDomTargetsFromDocument(context, options) {
     ${TRANSPARENT_ACTIONABLE_CONTROL_HELPER_SCRIPT}
     ${OBSERVE_DOM_LABEL_CONTRACT_HELPER_SCRIPT}
     ${INFER_STRUCTURED_CELL_VARIANT_HELPER_SCRIPT}
+    ${INFER_DIRECTIONAL_CONTROL_FALLBACK_HELPER_SCRIPT}
 
     const normalizeDescriptorText = (value) => observedNormalizeDescriptorText(value);
 
@@ -1144,6 +1216,315 @@ async function collectDomTargetsFromDocument(context, options) {
       return composedClosest(element, itemSelector) || undefined;
     };
 
+    const directionalControlSelector =
+      'button, [role="button"], input[type="button"], input[type="submit"], input[type="reset"]';
+    const weakDirectionalTextRe = /^[+\-<>‹›«»←→↑↓]+$/;
+
+    const isButtonLikeDirectionalElement = (element) => {
+      if (!isHTMLElementNode(element)) {
+        return false;
+      }
+
+      const tag = element.tagName.toLowerCase();
+      const role = (element.getAttribute('role') || '').trim().toLowerCase();
+      if (tag === 'button') {
+        return true;
+      }
+      if (tag === 'input') {
+        return isButtonLikeInput(element);
+      }
+      return role === 'button';
+    };
+
+    const isWeakDirectionalText = (value) => {
+      const normalized = normalizeDescriptorText(value || '');
+      return Boolean(normalized) && weakDirectionalTextRe.test(normalized);
+    };
+
+    const directionalButtonsOf = (scope) => {
+      if (!isHTMLElementNode(scope)) {
+        return [];
+      }
+
+      return Array.from(scope.querySelectorAll(directionalControlSelector))
+        .filter((candidate) => isHTMLElementNode(candidate))
+        .filter((candidate) => isVisible(candidate))
+        .filter((candidate) => isButtonLikeDirectionalElement(candidate))
+        .slice(0, 6);
+    };
+
+    const directionalChildTextCandidatesOf = (scope, exclude = []) => {
+      if (!isHTMLElementNode(scope)) {
+        return [];
+      }
+
+      const excluded = exclude.filter((candidate) => isHTMLElementNode(candidate));
+      const candidates = [];
+      for (const child of Array.from(scope.children).slice(0, 12)) {
+        if (!isHTMLElementNode(child) || !isVisible(child)) {
+          continue;
+        }
+        if (
+          excluded.some(
+            (candidate) =>
+              child === candidate || child.contains(candidate) || candidate.contains(child)
+          )
+        ) {
+          continue;
+        }
+        if (isButtonLikeDirectionalElement(child)) {
+          continue;
+        }
+        if (directionalButtonsOf(child).length > 0) {
+          continue;
+        }
+
+        const text = normalizeDescriptorText(textOf(child, { container: true }) || '');
+        if (!text || text.length > 48) {
+          continue;
+        }
+
+        candidates.push({
+          element: child,
+          text,
+          rect: child.getBoundingClientRect(),
+        });
+      }
+
+      return candidates;
+    };
+
+    const directionalAxisOf = (buttons) => {
+      if (buttons.length !== 2) {
+        return undefined;
+      }
+
+      const firstRect = buttons[0].getBoundingClientRect();
+      const secondRect = buttons[1].getBoundingClientRect();
+      const deltaX = Math.abs(
+        firstRect.left + firstRect.width / 2 - (secondRect.left + secondRect.width / 2)
+      );
+      const deltaY = Math.abs(
+        firstRect.top + firstRect.height / 2 - (secondRect.top + secondRect.height / 2)
+      );
+      return deltaX >= deltaY ? 'horizontal' : 'vertical';
+    };
+
+    const orderedDirectionalButtonsOf = (buttons, axis) => {
+      return [...buttons].sort((left, right) => {
+        const leftRect = left.getBoundingClientRect();
+        const rightRect = right.getBoundingClientRect();
+        return axis === 'vertical'
+          ? leftRect.top - rightRect.top
+          : leftRect.left - rightRect.left;
+      });
+    };
+
+    const directionalPositionOf = (element, orderedButtons, axis) => {
+      if (orderedButtons.length !== 2) {
+        return undefined;
+      }
+
+      if (orderedButtons[0] === element) {
+        return axis === 'vertical' ? 'upper' : 'leading';
+      }
+      if (orderedButtons[1] === element) {
+        return axis === 'vertical' ? 'lower' : 'trailing';
+      }
+      return undefined;
+    };
+
+    const directionalAnchorCandidateOf = (cluster, orderedButtons, axis) => {
+      if (!isHTMLElementNode(cluster) || orderedButtons.length !== 2) {
+        return undefined;
+      }
+
+      const firstRect = orderedButtons[0].getBoundingClientRect();
+      const secondRect = orderedButtons[1].getBoundingClientRect();
+      const midpointX =
+        (firstRect.left + firstRect.width / 2 + (secondRect.left + secondRect.width / 2)) / 2;
+      const midpointY =
+        (firstRect.top + firstRect.height / 2 + (secondRect.top + secondRect.height / 2)) / 2;
+
+      const candidates = directionalChildTextCandidatesOf(cluster, orderedButtons)
+        .filter((candidate) => {
+          const centerX = candidate.rect.left + candidate.rect.width / 2;
+          const centerY = candidate.rect.top + candidate.rect.height / 2;
+          if (axis === 'vertical') {
+            return (
+              centerY >= Math.min(midpointY, secondRect.top + secondRect.height / 2) - 40 &&
+              centerY <= Math.max(midpointY, firstRect.top + firstRect.height / 2) + 40 &&
+              Math.abs(centerX - midpointX) <= Math.max(40, firstRect.width * 1.5)
+            );
+          }
+
+          return (
+            centerX >= Math.min(firstRect.left + firstRect.width / 2, midpointX) - 40 &&
+            centerX <= Math.max(secondRect.left + secondRect.width / 2, midpointX) + 40 &&
+            Math.abs(centerY - midpointY) <= Math.max(32, firstRect.height * 1.5)
+          );
+        })
+        .sort((left, right) => {
+          const leftCenterX = left.rect.left + left.rect.width / 2;
+          const leftCenterY = left.rect.top + left.rect.height / 2;
+          const rightCenterX = right.rect.left + right.rect.width / 2;
+          const rightCenterY = right.rect.top + right.rect.height / 2;
+          const leftDistance = Math.hypot(leftCenterX - midpointX, leftCenterY - midpointY);
+          const rightDistance = Math.hypot(rightCenterX - midpointX, rightCenterY - midpointY);
+          return leftDistance - rightDistance;
+        });
+
+      return candidates[0];
+    };
+
+    const stepperGroupLabelOf = (element, cluster, axis, anchorText) => {
+      const scopes = [];
+      const parent = composedParentElement(cluster);
+      const grandParent = composedParentElement(parent);
+      const item = itemOf(element);
+
+      for (const scope of [parent, item, grandParent]) {
+        if (
+          isHTMLElementNode(scope) &&
+          scope !== cluster &&
+          !scopes.includes(scope)
+        ) {
+          scopes.push(scope);
+        }
+      }
+
+      const anchorMonthLike = Boolean(
+        inferDirectionalControlFallbackFromEvidence({
+          kind: 'button',
+          anchorText,
+          position: 'leading',
+        })
+      );
+
+      for (const scope of scopes) {
+        const scopeRect = cluster.getBoundingClientRect();
+        const clusterCenterX = scopeRect.left + scopeRect.width / 2;
+        const clusterCenterY = scopeRect.top + scopeRect.height / 2;
+        const ranked = directionalChildTextCandidatesOf(scope, [cluster])
+          .filter((candidate) => candidate.text !== anchorText)
+          .filter((candidate) => !/^\d{1,3}$/.test(candidate.text))
+          .filter(
+            (candidate) =>
+              !Boolean(
+                inferDirectionalControlFallbackFromEvidence({
+                  kind: 'button',
+                  anchorText: candidate.text,
+                  position: 'leading',
+                })
+              ) || !anchorMonthLike
+          )
+          .sort((left, right) => {
+            const leftRect = left.rect;
+            const rightRect = right.rect;
+            const leftCenterX = leftRect.left + leftRect.width / 2;
+            const leftCenterY = leftRect.top + leftRect.height / 2;
+            const rightCenterX = rightRect.left + rightRect.width / 2;
+            const rightCenterY = rightRect.top + rightRect.height / 2;
+            const leftBias =
+              axis === 'vertical'
+                ? leftRect.bottom <= scopeRect.top + 16
+                  ? 0
+                  : leftRect.right <= scopeRect.left + 16
+                    ? 1
+                    : 2
+                : leftRect.right <= scopeRect.left + 16
+                  ? 0
+                  : leftRect.bottom <= scopeRect.top + 16
+                    ? 1
+                    : 2;
+            const rightBias =
+              axis === 'vertical'
+                ? rightRect.bottom <= scopeRect.top + 16
+                  ? 0
+                  : rightRect.right <= scopeRect.left + 16
+                    ? 1
+                    : 2
+                : rightRect.right <= scopeRect.left + 16
+                  ? 0
+                  : rightRect.bottom <= scopeRect.top + 16
+                    ? 1
+                    : 2;
+            if (leftBias !== rightBias) {
+              return leftBias - rightBias;
+            }
+            const leftDistance = Math.hypot(leftCenterX - clusterCenterX, leftCenterY - clusterCenterY);
+            const rightDistance = Math.hypot(rightCenterX - clusterCenterX, rightCenterY - clusterCenterY);
+            if (leftDistance !== rightDistance) {
+              return leftDistance - rightDistance;
+            }
+            return left.text.length - right.text.length;
+          });
+
+        const subject = ranked[0]?.text;
+        if (subject) {
+          return subject;
+        }
+      }
+
+      return undefined;
+    };
+
+    const directionalControlFallbackLabelOf = (element, directFallbackLabel) => {
+      if (!isButtonLikeDirectionalElement(element)) {
+        return undefined;
+      }
+      if (directFallbackLabel && !isWeakDirectionalText(directFallbackLabel)) {
+        return undefined;
+      }
+
+      let current = composedParentElement(element);
+      let depth = 0;
+      while (current && depth < 4) {
+        if (!isHTMLElementNode(current) || !isVisible(current)) {
+          current = composedParentElement(current);
+          depth += 1;
+          continue;
+        }
+
+        const buttons = directionalButtonsOf(current);
+        if (buttons.length !== 2 || !buttons.includes(element)) {
+          current = composedParentElement(current);
+          depth += 1;
+          continue;
+        }
+
+        const axis = directionalAxisOf(buttons);
+        if (!axis) {
+          return undefined;
+        }
+        const orderedButtons = orderedDirectionalButtonsOf(buttons, axis);
+        const position = directionalPositionOf(element, orderedButtons, axis);
+        const anchorCandidate = directionalAnchorCandidateOf(current, orderedButtons, axis);
+        const anchorText = anchorCandidate?.text;
+        if (!position || !anchorText) {
+          return undefined;
+        }
+
+        const groupLabel = /^\d{1,3}$/.test(anchorText)
+          ? stepperGroupLabelOf(element, current, axis, anchorText)
+          : undefined;
+        const fallbackLabel = inferDirectionalControlFallbackFromEvidence({
+          kind: element.tagName.toLowerCase(),
+          role: element.getAttribute('role')?.trim() || undefined,
+          groupLabel,
+          anchorText,
+          position,
+        });
+        if (fallbackLabel) {
+          return fallbackLabel;
+        }
+
+        return undefined;
+      }
+
+      return undefined;
+    };
+
     const normalizeText = (value) => (value || '').replace(/\s+/g, ' ').trim().toLowerCase();
 
     const VALIDATION_CLASS_RE = /\b(?:error|invalid|warning|danger|alert|failed)\b/i;
@@ -2192,7 +2573,12 @@ async function collectDomTargetsFromDocument(context, options) {
           (isHTMLElementNode(overlaySurface) ? overlaySurface : localSurface || selfSurface);
         const surfaceSelectors = surfaceSelectorsOf(element, localSurface || selfSurface);
         const structure = visualSeatGrid?.structure || inferStructuredCell(element, surface);
-        const fallbackLabel = explicitLabelOf(element) || looseFieldLabelOf(element);
+        const directFallbackLabel = explicitLabelOf(element) || looseFieldLabelOf(element);
+        const directionalFallbackLabel = directionalControlFallbackLabelOf(
+          element,
+          directFallbackLabel
+        );
+        const fallbackLabel = directionalFallbackLabel || directFallbackLabel;
         const currentValue = popupCurrentValueOf(element);
         const role = inferRole(element);
         const surfaceKind = visualSeatGrid?.surfaceKind || surfaceKindOf(surface);
@@ -2681,6 +3067,7 @@ export async function collectDomTargets(page, options) {
 export const __testDomTargetCollection = {
     collectDomTargetsFromDocument,
     inferStructuredCellVariantFromEvidence,
+    inferDirectionalControlFallbackFromEvidence,
     locatorDomSignatureScript: LOCATOR_DOM_SIGNATURE_SCRIPT,
 };
 export const __testStagehandDescriptor = {