@nuanu-ai/agentbrowse 0.2.7 → 0.2.8

package/dist/commands/action-value-projection.js

@@ -0,0 +1,151 @@
+const PHONE_PROJECTION_CONTEXT_SCRIPT = String.raw `
+  if (!(element instanceof HTMLElement)) {
+    return null;
+  }
+
+  const autocomplete = (element.getAttribute('autocomplete') || '').trim().toLowerCase();
+  const inputName = (element.getAttribute('name') || '').trim().toLowerCase();
+  const inputType = (element.getAttribute('type') || '').trim().toLowerCase();
+  const phoneLike =
+    inputType === 'tel' ||
+    autocomplete.includes('tel') ||
+    inputName.includes('phone');
+  const isNationalPhoneInput =
+    autocomplete.includes('tel-national') ||
+    autocomplete === 'tel-local' ||
+    autocomplete === 'tel';
+  if (!phoneLike || !isNationalPhoneInput) {
+    return null;
+  }
+
+  const anchors = [];
+  let current = element.parentElement;
+  for (let depth = 0; current && depth < 8; depth += 1, current = current.parentElement) {
+    anchors.push(current);
+  }
+
+  const extractDialCode = (rawValue) => {
+    const normalized = String(rawValue ?? '').replace(/\s+/g, ' ').trim();
+    const matches = normalized.match(/\+\d{1,4}/g);
+    return matches && matches.length > 0 ? matches[matches.length - 1] : null;
+  };
+
+  for (const anchor of anchors) {
+    const companions = Array.from(
+      anchor.querySelectorAll('select, input, [role="combobox"]')
+    ).filter((candidate) => candidate instanceof HTMLElement && candidate !== element);
+
+    for (const companion of companions) {
+      const companionAutocomplete = (
+        companion.getAttribute('autocomplete') || ''
+      ).trim().toLowerCase();
+      const companionName = (companion.getAttribute('name') || '').trim().toLowerCase();
+      const companionTestId = (
+        companion.getAttribute('data-testid') || companion.getAttribute('data-test-id') || ''
+      )
+        .trim()
+        .toLowerCase();
+      const companionAriaLabel = (
+        companion.getAttribute('aria-label') || ''
+      ).trim().toLowerCase();
+      const isCountryCodeCompanion =
+        companionAutocomplete.includes('tel-country-code') ||
+        companionName.includes('countrycode') ||
+        companionTestId.includes('phone-country-code') ||
+        companionAriaLabel.includes('country or region');
+      if (!isCountryCodeCompanion) {
+        continue;
+      }
+
+      if (companion instanceof HTMLSelectElement) {
+        const selectedOption = companion.selectedOptions && companion.selectedOptions[0]
+          ? companion.selectedOptions[0]
+          : null;
+        const selectedText = (selectedOption && selectedOption.textContent
+          ? selectedOption.textContent
+          : ''
+        ).replace(/\s+/g, ' ').trim();
+        return {
+          selectedDialCode: extractDialCode(selectedText),
+          selectedOptionText: selectedText || undefined,
+        };
+      }
+
+      const currentValue =
+        companion instanceof HTMLInputElement
+          ? companion.value
+          : (companion.textContent || '').replace(/\s+/g, ' ').trim();
+      return {
+        selectedDialCode: extractDialCode(currentValue),
+        selectedOptionText: currentValue || undefined,
+      };
+    }
+  }
+
+  return null;
+`;
+function looksPhoneLike(target) {
+    const inputType = (target.inputType ?? '').trim().toLowerCase();
+    const autocomplete = (target.autocomplete ?? '').trim().toLowerCase();
+    const inputName = (target.inputName ?? '').trim().toLowerCase();
+    const label = (target.label ?? '').trim().toLowerCase();
+    return (inputType === 'tel' ||
+        autocomplete.includes('tel') ||
+        inputName.includes('phone') ||
+        /\bphone\b|\bтелефон\b|\bномер\b/.test(label));
+}
+function normalizePhoneComparable(value) {
+    const compact = value.replace(/[^\d+]/g, '');
+    if (!compact) {
+        return '';
+    }
+    if (!compact.startsWith('+')) {
+        return compact.replace(/\+/g, '');
+    }
+    return `+${compact.slice(1).replace(/\+/g, '')}`;
+}
+function readPhoneProjectionContextInBrowser(element) {
+    return Function('element', PHONE_PROJECTION_CONTEXT_SCRIPT)(element);
+}
+async function readPhoneProjectionContext(locator) {
+    return locator
+        .evaluate((element, source) => Function('element', source)(element), PHONE_PROJECTION_CONTEXT_SCRIPT)
+        .catch(() => null);
+}
+export async function projectActionValue(args) {
+    const { target, action, actionValue, locator, attempts } = args;
+    if (!actionValue || (action !== 'fill' && action !== 'type')) {
+        return null;
+    }
+    if (!looksPhoneLike(target)) {
+        return null;
+    }
+    const normalized = normalizePhoneComparable(actionValue);
+    if (!normalized.startsWith('+')) {
+        return null;
+    }
+    const context = await readPhoneProjectionContext(locator);
+    if (!context?.selectedDialCode) {
+        return null;
+    }
+    const selectedDialCode = normalizePhoneComparable(context.selectedDialCode);
+    if (!selectedDialCode.startsWith('+') || !normalized.startsWith(selectedDialCode)) {
+        return null;
+    }
+    const localPart = normalized.slice(selectedDialCode.length);
+    if (!/^\d{4,}$/.test(localPart)) {
+        return null;
+    }
+    attempts.push(`projection:phone.local-from-selected-code:${selectedDialCode}`);
+    return {
+        kind: 'phone-national',
+        executionValue: localPart,
+        acceptanceValue: localPart,
+        selectedDialCode,
+        selectedOptionText: context.selectedOptionText,
+    };
+}
+export const __testActionValueProjection = {
+    phoneProjectionContextScript: PHONE_PROJECTION_CONTEXT_SCRIPT,
+    readPhoneProjectionContextInBrowser,
+};

package/dist/commands/browse-actions.d.ts

@@ -0,0 +1,4 @@
+export declare const BROWSE_ACTIONS: readonly ["click", "fill", "type", "select", "press"];
+export type BrowseAction = (typeof BROWSE_ACTIONS)[number];
+export declare function isBrowseAction(value: string): value is BrowseAction;
+//# sourceMappingURL=browse-actions.d.ts.map

package/dist/commands/browse-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse-actions.d.ts","sourceRoot":"","sources":["../../src/commands/browse-actions.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,uDAAwD,CAAC;AAEpF,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAEnE"}

package/dist/commands/browse-actions.js

@@ -0,0 +1,4 @@
+export const BROWSE_ACTIONS = ['click', 'fill', 'type', 'select', 'press'];
+export function isBrowseAction(value) {
+    return BROWSE_ACTIONS.includes(value);
+}

package/dist/commands/captcha-solve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"captcha-solve.d.ts","sourceRoot":"","sources":["../../src/commands/captcha-solve.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAOnD,wBAAsB,YAAY,CAChC,OAAO,EAAE,aAAa,GAAG,IAAI,EAC7B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CA+Bf"}
+{"version":3,"file":"captcha-solve.d.ts","sourceRoot":"","sources":["../../src/commands/captcha-solve.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAOnD,wBAAsB,YAAY,CAChC,OAAO,EAAE,aAAa,GAAG,IAAI,EAC7B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAyCf"}

package/dist/commands/captcha-solve.js

@@ -3,15 +3,25 @@
  */
 import { solveCaptchasByCdp } from '../solver/captcha-runtime.js';
 import { supportsCaptchaSolve } from '../session.js';
-import { info, outputError, outputJSON } from '../output.js';
+import { info, outputContractFailure, outputJSON } from '../output.js';
 import { applyAgentpayGatewayEnv, resolveAgentpayGatewayConfig } from '../agentpay-gateway.js';
 const DEFAULT_TIMEOUT_SECONDS = 90;
 export async function captchaSolve(session, timeoutSeconds) {
     if (!session) {
-        outputError('Captcha solving requires an active browser session started with browse launch.');
+        outputContractFailure({
+            error: 'captcha_session_required',
+            outcomeType: 'blocked',
+            message: 'Captcha solving requires an active browser session.',
+            reason: 'Start a browser session with browse launch before running solve-captcha.',
+        });
     }
     if (!supportsCaptchaSolve(session)) {
-        outputError('Current browser session does not support captcha solving.');
+        outputContractFailure({
+            error: 'captcha_not_supported',
+            outcomeType: 'unsupported',
+            message: 'The current browser session does not support captcha solving.',
+            reason: 'This session was started without captcha-solving capability.',
+        });
     }
     const gateway = resolveAgentpayGatewayConfig();
     applyAgentpayGatewayEnv(gateway);

package/dist/commands/click-action-executor.d.ts

@@ -0,0 +1,10 @@
+import type { Locator, Page } from 'playwright-core';
+import { type ActionExecutionGuards } from './action-execution-guards.js';
+type ClickRetryOptions = {
+    beforeRetry?: () => Promise<void>;
+    guards?: ActionExecutionGuards;
+};
+export declare function applyEditableClickAction(page: Page, locator: Locator, attempts: string[], options?: ClickRetryOptions): Promise<boolean>;
+export declare function applyTriggerAction(page: Page, locator: Locator, attempts: string[], options?: ClickRetryOptions): Promise<boolean>;
+export {};
+//# sourceMappingURL=click-action-executor.d.ts.map

package/dist/commands/click-action-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"click-action-executor.d.ts","sourceRoot":"","sources":["../../src/commands/click-action-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAMrD,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,8BAA8B,CAAC;AAEtC,KAAK,iBAAiB,GAAG;IACvB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC,CAAC;AAwEF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAElB"}

package/dist/commands/click-action-executor.js

@@ -0,0 +1,68 @@
+import { LOCATOR_CLICK_TIMEOUT_MS, dismissBlockingOverlay, looksLikeOverlayInterference, } from './action-executor-helpers.js';
+import { runActionExecutionGuard, } from './action-execution-guards.js';
+async function ensureLocatorRetryReady(locator, error, options) {
+    await runActionExecutionGuard(options?.guards, 'click.before-retry');
+    await options?.beforeRetry?.();
+    const count = await locator.count().catch(() => 0);
+    if (count === 0) {
+        throw error;
+    }
+}
+async function applyClickSequence(page, locator, attempts, options) {
+    attempts.push('locator.click');
+    try {
+        await locator.click({ timeout: LOCATOR_CLICK_TIMEOUT_MS });
+        return false;
+    }
+    catch (error) {
+        let lastError = error instanceof Error ? error : new Error(String(error));
+        await runActionExecutionGuard(options?.guards, 'click.after-error');
+        if (looksLikeOverlayInterference(error)) {
+            await runActionExecutionGuard(options?.guards, 'click.overlay-dismiss');
+            const dismissed = await dismissBlockingOverlay(page, attempts);
+            if (dismissed) {
+                await ensureLocatorRetryReady(locator, lastError, options);
+                attempts.push('locator.click.retry.afterOverlay');
+                try {
+                    await runActionExecutionGuard(options?.guards, 'click.retry.after-overlay');
+                    await locator.click({ timeout: LOCATOR_CLICK_TIMEOUT_MS });
+                    return true;
+                }
+                catch (retryError) {
+                    lastError = retryError instanceof Error ? retryError : new Error(String(retryError));
+                    // Fall through to scroll / JS fallback.
+                }
+            }
+        }
+        await ensureLocatorRetryReady(locator, lastError, options);
+        await runActionExecutionGuard(options?.guards, 'click.scroll-into-view');
+        attempts.push('locator.scrollIntoViewIfNeeded');
+        await locator.scrollIntoViewIfNeeded();
+        await ensureLocatorRetryReady(locator, lastError, options);
+        attempts.push('locator.click.retry');
+        try {
+            await runActionExecutionGuard(options?.guards, 'click.retry');
+            await locator.click({ timeout: LOCATOR_CLICK_TIMEOUT_MS });
+            return true;
+        }
+        catch (retryError) {
+            lastError = retryError instanceof Error ? retryError : new Error(String(retryError));
+            await ensureLocatorRetryReady(locator, lastError, options);
+            await runActionExecutionGuard(options?.guards, 'click.evaluate');
+            attempts.push('locator.evaluate.click');
+            await locator.evaluate((element) => {
+                if (!(element instanceof HTMLElement)) {
+                    throw new Error('unsupported_js_click_fallback');
+                }
+                element.click();
+            });
+        }
+        return true;
+    }
+}
+export async function applyEditableClickAction(page, locator, attempts, options) {
+    return applyClickSequence(page, locator, attempts, options);
+}
+export async function applyTriggerAction(page, locator, attempts, options) {
+    return applyClickSequence(page, locator, attempts, options);
+}

package/dist/commands/create-intent.d.ts

@@ -0,0 +1,6 @@
+/**
+ * browse create-intent <fillRef> <storedSecretRef> — Create or reuse a stored-secret access intent.
+ */
+import type { BrowseSession } from '../session.js';
+export declare function createIntent(session: BrowseSession, fillRef: string, storedSecretRef: string): Promise<void>;
+//# sourceMappingURL=create-intent.d.ts.map

package/dist/commands/create-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-intent.d.ts","sourceRoot":"","sources":["../../src/commands/create-intent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAmBnD,wBAAsB,YAAY,CAChC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAqEf"}

package/dist/commands/create-intent.js

@@ -0,0 +1,75 @@
+/**
+ * browse create-intent <fillRef> <storedSecretRef> — Create or reuse a stored-secret access intent.
+ */
+import { outputFailure, outputJSON } from '../output.js';
+import { getFillableForm, saveSecretIntentSnapshot } from '../runtime-state.js';
+import { saveSession } from '../session.js';
+import { tryResolveCatalogHost } from '../secrets/catalog-sync.js';
+import { getSecretBackend } from '../secrets/backend.js';
+import { describeSecretIntentStatus, serializeSecretIntent } from '../secrets/intent-output.js';
+function deriveRequestedFieldKeys(fillableForm, storedSecret) {
+    if (storedSecret.fieldKeys && storedSecret.fieldKeys.length > 0) {
+        return [...storedSecret.fieldKeys];
+    }
+    return fillableForm.fields.map((field) => field.fieldKey);
+}
+export async function createIntent(session, fillRef, storedSecretRef) {
+    const fillableForm = getFillableForm(session, fillRef);
+    if (!fillableForm) {
+        return outputFailure({
+            error: 'unknown_fill_ref',
+            outcomeType: 'blocked',
+            message: 'Protected intent was not created because the requested fill reference is unknown.',
+            reason: 'The provided fillRef does not match any currently observed protected fill target.',
+            fillRef,
+        });
+    }
+    const storedSecret = fillableForm.storedSecretCandidates.find((candidate) => candidate.storedSecretRef === storedSecretRef);
+    if (!storedSecret) {
+        return outputFailure({
+            error: 'stored_secret_not_available_for_fill_ref',
+            outcomeType: 'blocked',
+            message: 'Protected intent was not created because this stored secret is not available for the requested fill target.',
+            reason: 'The provided storedSecretRef is not a candidate for the requested protected fill target.',
+            fillRef,
+            storedSecretRef,
+        });
+    }
+    const pageUrl = session.runtime?.pages?.[fillableForm.pageRef]?.url;
+    const host = tryResolveCatalogHost(pageUrl);
+    if (!host) {
+        return outputFailure({
+            error: 'secret_intent_host_resolution_failed',
+            outcomeType: 'blocked',
+            message: 'Protected intent was not created because AgentBrowse could not determine the current site host.',
+            reason: 'The current page URL did not resolve to a usable host for protected intent creation.',
+            fillRef,
+            storedSecretRef,
+        });
+    }
+    const result = await getSecretBackend().createOrReuseSecretIntent({
+        fillRef,
+        storedSecretRef,
+        host,
+        pageRef: fillableForm.pageRef,
+        scopeRef: fillableForm.scopeRef,
+        purpose: fillableForm.purpose,
+        secretKind: storedSecret.kind,
+        requestedFieldKeys: deriveRequestedFieldKeys(fillableForm, storedSecret),
+    });
+    const snapshot = saveSecretIntentSnapshot(session, result.intent);
+    saveSession(session);
+    const statusContract = describeSecretIntentStatus(snapshot.status);
+    const reasonPrefix = result.reused
+        ? 'AgentBrowse reused an existing intent for this fill target.'
+        : 'AgentBrowse created a new intent for this fill target.';
+    outputJSON({
+        success: true,
+        ...serializeSecretIntent(snapshot),
+        reused: result.reused,
+        ...(statusContract.outcomeType ? { outcomeType: statusContract.outcomeType } : {}),
+        message: statusContract.message,
+        reason: `${reasonPrefix} ${statusContract.reason}`,
+        ...(statusContract.nextAction ? { nextAction: statusContract.nextAction } : {}),
+    });
+}

package/dist/commands/datepicker-action-executor.d.ts

@@ -0,0 +1,12 @@
+import type { Locator, Page } from 'playwright-core';
+import { type ActionExecutionGuards } from './action-execution-guards.js';
+type DatepickerActionHelpers = {
+    normalizeFillValue: (locator: Locator, value: string, attempts: string[]) => Promise<string>;
+    focusLocator: (page: Page, locator: Locator, attempts: string[]) => Promise<void>;
+    clearLocatorForReplacement: (locator: Locator, attempts: string[]) => Promise<void>;
+    applyValueWithJsFallback: (locator: Locator, value: string, attempts: string[]) => Promise<void>;
+    blurLocator: (locator: Locator, attempts: string[]) => Promise<void>;
+};
+export declare function applyDatepickerAction(page: Page, locator: Locator, value: string, attempts: string[], helpers: DatepickerActionHelpers, guards?: ActionExecutionGuards): Promise<boolean>;
+export {};
+//# sourceMappingURL=datepicker-action-executor.d.ts.map

package/dist/commands/datepicker-action-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datepicker-action-executor.d.ts","sourceRoot":"","sources":["../../src/commands/datepicker-action-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,8BAA8B,CAAC;AAmBtC,KAAK,uBAAuB,GAAG;IAC7B,kBAAkB,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7F,YAAY,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,0BAA0B,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,wBAAwB,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjG,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE,CAAC;AAkKF,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE,uBAAuB,EAChC,MAAM,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,OAAO,CAAC,CAyElB"}

package/dist/commands/datepicker-action-executor.js

@@ -0,0 +1,218 @@
+import { runActionExecutionGuard, } from './action-execution-guards.js';
+const DATEPICKER_DAY_ROLES = [
+    'gridcell',
+    'button',
+    'option',
+];
+const DATEPICKER_CONTAINER_SELECTORS = [
+    '[role="dialog"]',
+    '[aria-modal="true"]',
+    '[data-testid*="calendar"]',
+    '[data-testid*="datepicker"]',
+    '[class*="calendar"]',
+    '[class*="datepicker"]',
+];
+const ISO_DATE_ENTRY_RE = /^\d{4}-\d{2}-\d{2}$/;
+function isLiteralDateEntry(value) {
+    return /\d{1,2}[./-]\d{1,2}[./-]\d{2,4}/.test(value);
+}
+async function isNativeDateInput(locator) {
+    const type = await locator.getAttribute('type').catch(() => null);
+    return (type ?? '').toLowerCase() === 'date';
+}
+function datepickerDayLabels(value) {
+    const labels = new Set([value]);
+    const triplet = value.match(/^(\d{1,4})[./-](\d{1,2})[./-](\d{1,4})$/);
+    const parts = value.match(/\d+/g);
+    if (!parts || parts.length < 3) {
+        return [...labels];
+    }
+    let day;
+    if (triplet) {
+        const firstPart = triplet[1];
+        const lastPart = triplet[3];
+        if (firstPart && firstPart.length === 4) {
+            day = lastPart;
+        }
+        else if (lastPart && lastPart.length === 4) {
+            day = firstPart;
+        }
+    }
+    if (!day) {
+        day = parts.at(-1);
+    }
+    if (!day) {
+        return [...labels];
+    }
+    const normalized = String(Number(day));
+    if (normalized) {
+        labels.add(normalized);
+    }
+    if (day.length === 2) {
+        labels.add(day);
+    }
+    return [...labels];
+}
+async function trySelectDateFromPicker(page, anchor, value, attempts, guards) {
+    const labels = datepickerDayLabels(value);
+    if (labels.length === 1 && labels[0] === value && !/\d/.test(value)) {
+        return false;
+    }
+    const scopedContainers = [];
+    for (const selector of DATEPICKER_CONTAINER_SELECTORS) {
+        const containers = page.locator(selector);
+        const count = await containers.count().catch(() => 0);
+        for (let index = 0; index < count; index += 1) {
+            const container = containers.nth(index);
+            const visible = await container.isVisible().catch(() => false);
+            if (!visible) {
+                continue;
+            }
+            scopedContainers.push({ selector, container });
+        }
+    }
+    const scopedRoots = scopedContainers.length > 0
+        ? scopedContainers
+        : [{ selector: 'page', container: page }];
+    const anchorBox = await anchor.boundingBox().catch(() => null);
+    async function clickBestMatch(root, descriptor, locatorFactory) {
+        const locator = locatorFactory();
+        const count = await locator.count().catch(() => 0);
+        let bestCandidate = null;
+        for (let index = 0; index < count; index += 1) {
+            const candidate = locator.nth(index);
+            const visible = await candidate.isVisible().catch(() => false);
+            if (!visible) {
+                continue;
+            }
+            const box = await candidate.boundingBox().catch(() => null);
+            const score = anchorBox && box
+                ? Math.abs(box.y - anchorBox.y) * 10 + Math.abs(box.x - anchorBox.x)
+                : index;
+            if (!bestCandidate || score < bestCandidate.score) {
+                bestCandidate = { locator: candidate, score };
+            }
+        }
+        if (!bestCandidate) {
+            return false;
+        }
+        await bestCandidate.locator.evaluate((element) => {
+            if (!(element instanceof HTMLElement)) {
+                throw new Error('unsupported_datepicker_dom_click');
+            }
+            element.click();
+        });
+        attempts.push(`datepicker.click.dom:${descriptor}`);
+        return true;
+    }
+    for (const { selector, container } of scopedRoots) {
+        await runActionExecutionGuard(guards, `datepicker.scope:${selector}`);
+        attempts.push(`datepicker.scope:${selector}`);
+        for (const role of DATEPICKER_DAY_ROLES) {
+            for (const label of labels) {
+                const descriptor = `${role}:${label}`;
+                attempts.push(`datepicker.resolve:${descriptor}`);
+                try {
+                    const clicked = await clickBestMatch(container, descriptor, () => container.getByRole(role, { name: label }));
+                    if (!clicked) {
+                        continue;
+                    }
+                    return true;
+                }
+                catch {
+                    // Try the next label/role combination.
+                }
+            }
+        }
+        for (const label of labels) {
+            const descriptor = `text:${label}`;
+            attempts.push(`datepicker.resolve:${descriptor}`);
+            try {
+                const clicked = await clickBestMatch(container, descriptor, () => container.getByText(label));
+                if (!clicked) {
+                    continue;
+                }
+                return true;
+            }
+            catch {
+                // Try next text label.
+            }
+        }
+    }
+    return false;
+}
+export async function applyDatepickerAction(page, locator, value, attempts, helpers, guards) {
+    const normalizedValue = await helpers.normalizeFillValue(locator, value, attempts);
+    const editable = await locator.isEditable().catch(() => false);
+    const nativeDateInput = await isNativeDateInput(locator);
+    if (nativeDateInput && editable && ISO_DATE_ENTRY_RE.test(normalizedValue)) {
+        attempts.push('datepicker.native:js-value');
+        await helpers.applyValueWithJsFallback(locator, normalizedValue, attempts);
+        await helpers.blurLocator(locator, attempts);
+        return true;
+    }
+    if (isLiteralDateEntry(normalizedValue)) {
+        await helpers.focusLocator(page, locator, attempts);
+        if (!editable) {
+            attempts.push('datepicker.readonly:picker-only');
+            return trySelectDateFromPicker(page, locator, normalizedValue, attempts, guards);
+        }
+        await helpers.clearLocatorForReplacement(locator, attempts);
+        if (typeof locator.pressSequentially === 'function') {
+            attempts.push('locator.pressSequentially.datepicker');
+            try {
+                await runActionExecutionGuard(guards, 'datepicker.press-sequentially');
+                await locator.pressSequentially(normalizedValue);
+                await helpers.blurLocator(locator, attempts);
+                return true;
+            }
+            catch {
+                // Fall through to fill/picker fallback.
+            }
+        }
+    }
+    attempts.push('locator.fill');
+    try {
+        await locator.fill(normalizedValue, { timeout: 1_500 });
+        if (isLiteralDateEntry(normalizedValue)) {
+            await helpers.blurLocator(locator, attempts);
+        }
+        return false;
+    }
+    catch {
+        await runActionExecutionGuard(guards, 'datepicker.after-error');
+        await helpers.focusLocator(page, locator, attempts);
+        if (await trySelectDateFromPicker(page, locator, normalizedValue, attempts, guards)) {
+            return true;
+        }
+        await helpers.clearLocatorForReplacement(locator, attempts);
+        if (typeof locator.pressSequentially === 'function') {
+            attempts.push('locator.pressSequentially');
+            try {
+                await runActionExecutionGuard(guards, 'datepicker.press-sequentially');
+                await locator.pressSequentially(normalizedValue);
+                if (isLiteralDateEntry(normalizedValue)) {
+                    await helpers.blurLocator(locator, attempts);
+                }
+                return true;
+            }
+            catch {
+                // Fall through to retry and DOM-event fallback.
+            }
+        }
+        attempts.push('locator.fill.retry');
+        try {
+            await runActionExecutionGuard(guards, 'datepicker.fill.retry');
+            await locator.fill(normalizedValue, { timeout: 1_500 });
+            if (isLiteralDateEntry(normalizedValue)) {
+                await helpers.blurLocator(locator, attempts);
+            }
+            return true;
+        }
+        catch {
+            await runActionExecutionGuard(guards, 'datepicker.js-fallback');
+            await helpers.applyValueWithJsFallback(locator, normalizedValue, attempts);
+        }
+        return true;
+    }
+}

package/dist/commands/descriptor-validation.d.ts

@@ -0,0 +1,27 @@
+import type { Locator } from 'playwright-core';
+import type { TargetDescriptor } from '../runtime-state.js';
+export declare function normalizePageSignature(url: string): string;
+export declare const LOCATOR_DOM_SIGNATURE_SCRIPT: string;
+declare function readLocatorDomSignatureInBrowser(element: Element): string | null;
+export type LocatorBindingSnapshot = {
+    domSignature: string | null;
+    kind?: string;
+    role?: string;
+    label?: string;
+    placeholder?: string;
+    inputName?: string;
+    inputType?: string;
+    autocomplete?: string;
+};
+export declare function readLocatorDomSignature(locator: Locator): Promise<string | null>;
+export declare function readLocatorBindingSnapshot(locator: Locator): Promise<LocatorBindingSnapshot | null>;
+export declare function isCompatibleMutableFieldBinding(target: TargetDescriptor, snapshot: LocatorBindingSnapshot | null): boolean;
+export declare const __testDescriptorValidation: {
+    readLocatorDomSignatureInBrowser: typeof readLocatorDomSignatureInBrowser;
+    locatorDomSignatureScript: string;
+    locatorBindingSnapshotScript: string;
+    isCompatibleMutableFieldBinding: typeof isCompatibleMutableFieldBinding;
+};
+export declare function readLocatorOuterHtml(locator: Locator): Promise<string | null>;
+export {};
+//# sourceMappingURL=descriptor-validation.d.ts.map

package/dist/commands/descriptor-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor-validation.d.ts","sourceRoot":"","sources":["../../src/commands/descriptor-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO1D;AAED,eAAO,MAAM,4BAA4B,QA+JxC,CAAC;AAEF,iBAAS,gCAAgC,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEzE;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAgCF,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWtF;AAED,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAWzG;AAOD,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,sBAAsB,GAAG,IAAI,GACtC,OAAO,CAoCT;AAED,eAAO,MAAM,0BAA0B;;;;;CAKtC,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmFnF"}