@nuanu-ai/agentbrowse 0.2.7 → 0.2.9

package/dist/secrets/protected-fill.js

@@ -0,0 +1,512 @@
+import { getSurface, getTarget } from '../runtime-state.js';
+import { createAcceptanceProbe, rankLocatorCandidates, waitForAcceptanceProbe, } from '../commands/action-acceptance.js';
+import { buildLocator, resolveLocatorRoot } from '../commands/action-fallbacks.js';
+import { applyActionWithFallbacks } from '../commands/action-executor.js';
+import { normalizePageSignature, readLocatorDomSignature } from '../commands/descriptor-validation.js';
+import { resolveSurfaceScopeRoot } from '../commands/target-resolution.js';
+import { resolveProtectedFieldPolicy } from './field-policy.js';
+import { protectedBindingKey } from './protected-bindings.js';
+import { resolveAssistedProtectedFieldValues } from './protected-field-values.js';
+import { sortProtectedBindingsForExecution } from './fill-ordering.js';
+function targetUsesSurfaceAsPrimaryLocator(target, surface) {
+    const surfaceCandidateKeys = new Set(surface.locatorCandidates.map((candidate) => [candidate.strategy, candidate.name ?? '', candidate.value, candidate.attribute ?? '', candidate.scope ?? ''].join(':')));
+    return target.locatorCandidates.some((candidate) => surfaceCandidateKeys.has([candidate.strategy, candidate.name ?? '', candidate.value, candidate.attribute ?? '', candidate.scope ?? ''].join(':')));
+}
+function resolveLocatorRootForCandidate(baseRoot, defaultRoot, surfaceRoot, scope) {
+    if (scope === 'root') {
+        return baseRoot;
+    }
+    if (scope === 'surface') {
+        return surfaceRoot;
+    }
+    return defaultRoot;
+}
+async function prepareLocator(locator, action, strategy, attempts, options) {
+    const count = await locator.count().catch(() => 0);
+    if (count === 0) {
+        attempts.push(`resolve.skip:${strategy}:empty`);
+        return { locator: null };
+    }
+    if (count > 1) {
+        attempts.push(`resolve.skip:${strategy}:ambiguous:${count}`);
+        return { locator: null };
+    }
+    const resolvedLocator = locator.first();
+    const visible = await resolvedLocator.isVisible().catch(() => false);
+    if (!visible) {
+        attempts.push(`resolve.skip:${strategy}:hidden`);
+        return { locator: null };
+    }
+    const disabled = await resolvedLocator.isDisabled?.().catch(() => false);
+    if (disabled) {
+        attempts.push(`resolve.skip:${strategy}:disabled`);
+        return { locator: null, blockedReason: 'disabled' };
+    }
+    if (action === 'fill' || action === 'type') {
+        const editable = await resolvedLocator.isEditable().catch(() => false);
+        if (!editable) {
+            const descendants = resolvedLocator.locator('input:not([type="hidden"]), textarea, select, [contenteditable="true"]');
+            const descendantCount = await descendants.count().catch(() => 0);
+            const visibleEditableDescendants = [];
+            for (let index = 0; index < descendantCount; index += 1) {
+                const descendant = descendants.nth(index);
+                const descendantVisible = await descendant.isVisible().catch(() => false);
+                if (!descendantVisible) {
+                    continue;
+                }
+                const descendantEditable = await descendant.isEditable().catch(() => false);
+                if (!descendantEditable) {
+                    continue;
+                }
+                visibleEditableDescendants.push(descendant);
+            }
+            if (visibleEditableDescendants.length === 1) {
+                attempts.push(`resolve.descendant-editable:${strategy}`);
+                return { locator: visibleEditableDescendants[0] ?? null };
+            }
+            if (visibleEditableDescendants.length > 1) {
+                attempts.push(`resolve.skip:${strategy}:descendant-ambiguous:${visibleEditableDescendants.length}`);
+                return { locator: null };
+            }
+            const readonly = await resolvedLocator
+                .getAttribute?.('readonly')
+                .then((value) => value !== null)
+                .catch(() => false);
+            if (readonly && !options?.allowReadonlyFallback) {
+                attempts.push(`resolve.skip:${strategy}:readonly`);
+                return { locator: null, blockedReason: 'readonly' };
+            }
+        }
+    }
+    return { locator: resolvedLocator };
+}
+function actionForTarget(target) {
+    if (target.controlFamily === 'select') {
+        return 'select';
+    }
+    if (target.allowedActions.includes('fill')) {
+        return 'fill';
+    }
+    if (target.allowedActions.includes('type')) {
+        return 'type';
+    }
+    if (target.allowedActions.includes('select')) {
+        return 'select';
+    }
+    return 'fill';
+}
+function formatCardExpiry(month, year) {
+    const normalizedMonth = month.trim().padStart(2, '0');
+    const normalizedYear = year.trim().length > 2 ? year.trim().slice(-2) : year.trim().padStart(2, '0');
+    return `${normalizedMonth}/${normalizedYear}`;
+}
+function resolveBindingValue(fields, protectedValues, fieldPolicies, assistedValues) {
+    if (fields.length === 1) {
+        const field = fields[0];
+        const policy = resolveProtectedFieldPolicy(fieldPolicies, field.fieldKey);
+        if (policy === 'llm_assisted') {
+            const assistedValue = assistedValues.get(protectedBindingKey(field));
+            if (typeof assistedValue === 'string' && assistedValue.length > 0) {
+                return assistedValue;
+            }
+            throw new Error('assisted_value_resolution_failed');
+        }
+        if ((field.valueHint ?? 'direct') !== 'direct') {
+            throw new Error('deterministic_only_resolution_failed');
+        }
+        const value = protectedValues[field.fieldKey];
+        if (typeof value === 'string' && value.length > 0) {
+            return value;
+        }
+        throw new Error('missing_protected_value');
+    }
+    const includesExpiry = fields.some((field) => field.fieldKey === 'exp_month') &&
+        fields.some((field) => field.fieldKey === 'exp_year') &&
+        fields.length === 2;
+    if (includesExpiry) {
+        const month = protectedValues.exp_month;
+        const year = protectedValues.exp_year;
+        if (typeof month === 'string' &&
+            month.length > 0 &&
+            typeof year === 'string' &&
+            year.length > 0) {
+            return formatCardExpiry(month, year);
+        }
+        throw new Error('missing_protected_value');
+    }
+    throw new Error('unsupported_protected_field_group');
+}
+function flattenFilledFields(fieldKeys, targetRef) {
+    return fieldKeys.map((fieldKey) => ({
+        fieldKey,
+        targetRef,
+    }));
+}
+function buildProtectedValidationDetails(validationText) {
+    return validationText ? { validationTextRedacted: true } : {};
+}
+function shouldIgnoreNativeInvalidForTarget(target) {
+    return Array.isArray(target.framePath) && target.framePath.length > 0;
+}
+async function readValidationState(locator) {
+    const payload = await locator
+        .evaluate((element) => {
+        if (!(element instanceof HTMLElement)) {
+            return null;
+        }
+        const maybeControl = element instanceof HTMLInputElement ||
+            element instanceof HTMLTextAreaElement ||
+            element instanceof HTMLSelectElement
+            ? element
+            : null;
+        const validationMessage = maybeControl?.validationMessage?.trim() ?? '';
+        const describedByIds = (element.getAttribute('aria-describedby') ?? '')
+            .split(/\s+/)
+            .map((value) => value.trim())
+            .filter(Boolean);
+        const describedByText = describedByIds
+            .map((id) => element.ownerDocument?.getElementById(id)?.textContent?.trim() ?? '')
+            .filter(Boolean)
+            .join(' ');
+        const ariaInvalid = element.getAttribute('aria-invalid') === 'true';
+        const candidate = validationMessage || describedByText || '';
+        return {
+            validationText: candidate || undefined,
+            ariaInvalid,
+            invalid: ariaInvalid ||
+                Boolean(maybeControl &&
+                    typeof maybeControl.checkValidity === 'function' &&
+                    maybeControl.checkValidity() === false),
+        };
+    })
+        .catch(() => null);
+    if (!payload) {
+        return {
+            invalid: false,
+        };
+    }
+    return {
+        invalid: payload.invalid,
+        validationText: payload.validationText ||
+            (payload.ariaInvalid ? 'Field rejected by client-side validation.' : undefined),
+    };
+}
+function groupBindingsByTarget(fillableForm, session) {
+    const grouped = new Map();
+    for (const field of fillableForm.fields) {
+        const target = getTarget(session, field.targetRef);
+        if (!target) {
+            return null;
+        }
+        const existing = grouped.get(field.targetRef);
+        if (existing) {
+            existing.fields.push(field);
+            existing.fieldKeys.push(field.fieldKey);
+            continue;
+        }
+        grouped.set(field.targetRef, {
+            targetRef: field.targetRef,
+            fields: [field],
+            fieldKeys: [field.fieldKey],
+            target,
+        });
+    }
+    return sortProtectedBindingsForExecution(fillableForm.purpose, [...grouped.values()]);
+}
+async function prepareBindings(session, page, fillableForm) {
+    const groupedBindings = groupBindingsByTarget(fillableForm, session);
+    if (!groupedBindings) {
+        const firstField = fillableForm.fields[0];
+        return {
+            kind: 'binding_stale',
+            targetRef: firstField?.targetRef ?? 'unknown',
+            fieldKeys: firstField ? [firstField.fieldKey] : [],
+            reason: 'target_missing',
+            attempts: [],
+        };
+    }
+    const preparedBindings = [];
+    for (const binding of groupedBindings) {
+        const attempts = [];
+        const { target } = binding;
+        if (target.lifecycle !== 'live') {
+            return {
+                kind: 'binding_stale',
+                targetRef: binding.targetRef,
+                fieldKeys: [...binding.fieldKeys],
+                reason: 'target_not_live',
+                attempts,
+            };
+        }
+        if (target.pageSignature && normalizePageSignature(page.url()) !== target.pageSignature) {
+            attempts.push('stale.page-signature:before-fill');
+            return {
+                kind: 'binding_stale',
+                targetRef: binding.targetRef,
+                fieldKeys: [...binding.fieldKeys],
+                reason: 'page_signature_mismatch',
+                attempts,
+            };
+        }
+        const surface = target.surfaceRef ? getSurface(session, target.surfaceRef) : null;
+        const baseRoot = resolveLocatorRoot(page, target.framePath ?? surface?.framePath);
+        let locatorRoot = baseRoot;
+        let surfaceRoot = null;
+        if (surface) {
+            surfaceRoot = await resolveSurfaceScopeRoot(page, surface, attempts).catch(() => null);
+            if (surfaceRoot && !targetUsesSurfaceAsPrimaryLocator(target, surface)) {
+                locatorRoot = surfaceRoot;
+            }
+            else if (!surfaceRoot) {
+                attempts.push('surface.resolve.fallback:page');
+            }
+        }
+        let resolvedLocator = null;
+        let sawDomSignatureMismatch = false;
+        let sawBlockedTarget = false;
+        const action = actionForTarget(target);
+        for (const candidate of rankLocatorCandidates(target.locatorCandidates, action)) {
+            const candidateRoot = resolveLocatorRootForCandidate(baseRoot, locatorRoot, surfaceRoot, candidate.scope);
+            if (!candidateRoot) {
+                attempts.push(`resolve.skip:${candidate.strategy}:surface-unavailable`);
+                continue;
+            }
+            const locator = buildLocator(candidateRoot, candidate);
+            if (!locator) {
+                continue;
+            }
+            const prepared = await prepareLocator(locator, action, candidate.strategy, attempts, {
+                allowReadonlyFallback: action === 'fill' && target.controlFamily === 'datepicker',
+            });
+            if (prepared.blockedReason === 'disabled' || prepared.blockedReason === 'readonly') {
+                sawBlockedTarget = true;
+            }
+            if (!prepared.locator) {
+                continue;
+            }
+            if (target.domSignature) {
+                const liveSignature = await readLocatorDomSignature(prepared.locator).catch(() => null);
+                if (liveSignature && liveSignature !== target.domSignature) {
+                    sawDomSignatureMismatch = true;
+                    attempts.push(`domSignature.mismatch:${candidate.strategy}`);
+                    continue;
+                }
+            }
+            resolvedLocator = prepared.locator;
+            attempts.push(`resolve:${candidate.strategy}`);
+            break;
+        }
+        if (!resolvedLocator) {
+            return {
+                kind: 'binding_stale',
+                targetRef: binding.targetRef,
+                fieldKeys: [...binding.fieldKeys],
+                reason: sawDomSignatureMismatch
+                    ? 'dom_signature_mismatch'
+                    : sawBlockedTarget
+                        ? 'target_blocked'
+                        : 'locator_resolution_failed',
+                attempts,
+            };
+        }
+        preparedBindings.push({
+            targetRef: binding.targetRef,
+            fields: [...binding.fields],
+            fieldKeys: [...binding.fieldKeys],
+            action,
+            target,
+            root: locatorRoot,
+            locator: resolvedLocator,
+            attempts,
+        });
+    }
+    return preparedBindings;
+}
+async function assertBindingStillValid(page, binding, stage) {
+    if (binding.target.pageSignature &&
+        normalizePageSignature(page.url()) !== binding.target.pageSignature) {
+        throw new Error(`binding_stale:page_signature_mismatch:${stage}`);
+    }
+    const liveCount = await binding.locator.count().catch(() => 0);
+    if (liveCount === 0) {
+        throw new Error(`binding_stale:locator_resolution_failed:${stage}`);
+    }
+    if (binding.target.domSignature) {
+        const liveSignature = await readLocatorDomSignature(binding.locator).catch(() => null);
+        if (liveSignature && liveSignature !== binding.target.domSignature) {
+            throw new Error(`binding_stale:dom_signature_mismatch:${stage}`);
+        }
+    }
+}
+function staleReasonFromError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('page_signature_mismatch')) {
+        return 'page_signature_mismatch';
+    }
+    if (message.includes('dom_signature_mismatch')) {
+        return 'dom_signature_mismatch';
+    }
+    if (message.includes('locator_resolution_failed')) {
+        return 'locator_resolution_failed';
+    }
+    return null;
+}
+export async function executeProtectedFill(params) {
+    const preparedBindings = await prepareBindings(params.session, params.page, params.fillableForm);
+    if (!Array.isArray(preparedBindings)) {
+        return preparedBindings;
+    }
+    let assistedValues;
+    try {
+        assistedValues = await resolveAssistedProtectedFieldValues({
+            page: params.page,
+            bindings: preparedBindings.map((binding) => ({
+                binding: binding.fields[0],
+                target: binding.target,
+            })),
+            protectedValues: params.protectedValues,
+            fieldPolicies: params.fieldPolicies,
+        });
+    }
+    catch {
+        return {
+            kind: 'unexpected_error',
+            reason: 'assisted_value_resolution_failed',
+        };
+    }
+    const filledFields = [];
+    for (const binding of preparedBindings) {
+        let actionValue;
+        let acceptanceProbe = null;
+        let acceptanceResult = null;
+        try {
+            actionValue = resolveBindingValue(binding.fields, params.protectedValues, params.fieldPolicies, assistedValues);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message === 'missing_protected_value') {
+                return {
+                    kind: 'unexpected_error',
+                    reason: 'missing_protected_value',
+                };
+            }
+            if (message === 'deterministic_only_resolution_failed') {
+                return {
+                    kind: 'unexpected_error',
+                    reason: 'deterministic_only_resolution_failed',
+                };
+            }
+            if (message === 'assisted_value_resolution_failed') {
+                return {
+                    kind: 'unexpected_error',
+                    reason: 'assisted_value_resolution_failed',
+                };
+            }
+            return {
+                kind: 'unexpected_error',
+                reason: 'unsupported_protected_field_group',
+            };
+        }
+        try {
+            acceptanceProbe = await createAcceptanceProbe({
+                session: params.session,
+                page: params.page,
+                target: binding.target,
+                action: binding.action,
+                actionValue,
+                locator: binding.locator,
+                beforePageObservation: null,
+            });
+            await applyActionWithFallbacks(params.page, binding.root, binding.locator, binding.action, actionValue, binding.attempts, binding.target.controlFamily, {
+                guards: {
+                    assertStillValid: async (stage) => {
+                        await assertBindingStillValid(params.page, binding, stage);
+                    },
+                },
+            });
+            if (acceptanceProbe) {
+                acceptanceResult = await waitForAcceptanceProbe(acceptanceProbe);
+                const acceptance = acceptanceResult;
+                if (!acceptance.accepted) {
+                    const validationState = await readValidationState(acceptanceProbe.readLocator);
+                    return {
+                        kind: 'validation_failed',
+                        filledFields,
+                        fieldErrors: binding.fieldKeys.map((fieldKey) => ({
+                            fieldKey,
+                            targetRef: binding.targetRef,
+                            reason: validationState.validationText
+                                ? 'client_validation_rejected'
+                                : 'value_not_applied',
+                            ...buildProtectedValidationDetails(validationState.validationText),
+                        })),
+                    };
+                }
+                const validationState = await readValidationState(acceptanceProbe.readLocator);
+                if (validationState.invalid && !shouldIgnoreNativeInvalidForTarget(binding.target)) {
+                    return {
+                        kind: 'validation_failed',
+                        filledFields,
+                        fieldErrors: binding.fieldKeys.map((fieldKey) => ({
+                            fieldKey,
+                            targetRef: binding.targetRef,
+                            reason: 'client_validation_rejected',
+                            ...buildProtectedValidationDetails(validationState.validationText),
+                        })),
+                    };
+                }
+            }
+            filledFields.push(...flattenFilledFields(binding.fieldKeys, binding.targetRef));
+        }
+        catch (error) {
+            if (acceptanceProbe) {
+                acceptanceResult =
+                    acceptanceResult ?? (await waitForAcceptanceProbe(acceptanceProbe).catch(() => null));
+                if (acceptanceResult?.accepted) {
+                    const validationState = await readValidationState(acceptanceProbe.readLocator);
+                    if (validationState.invalid && !shouldIgnoreNativeInvalidForTarget(binding.target)) {
+                        return {
+                            kind: 'validation_failed',
+                            filledFields,
+                            fieldErrors: binding.fieldKeys.map((fieldKey) => ({
+                                fieldKey,
+                                targetRef: binding.targetRef,
+                                reason: 'client_validation_rejected',
+                                ...buildProtectedValidationDetails(validationState.validationText),
+                            })),
+                        };
+                    }
+                    filledFields.push(...flattenFilledFields(binding.fieldKeys, binding.targetRef));
+                    continue;
+                }
+            }
+            const staleReason = staleReasonFromError(error);
+            if (staleReason) {
+                return {
+                    kind: 'binding_stale',
+                    targetRef: binding.targetRef,
+                    fieldKeys: [...binding.fieldKeys],
+                    reason: staleReason,
+                    attempts: [...binding.attempts],
+                };
+            }
+            return {
+                kind: 'unexpected_error',
+                reason: 'action_failed',
+            };
+        }
+    }
+    return {
+        kind: 'success',
+        filledFields,
+    };
+}
+export const __testProtectedFill = {
+    actionForTarget,
+    formatCardExpiry,
+    resolveBindingValue: (fieldKeys, protectedValues) => resolveBindingValue(fieldKeys.map((fieldKey) => ({
+        fieldKey,
+        targetRef: 't_test',
+        valueHint: 'direct',
+    })), protectedValues, undefined, new Map()),
+};

package/dist/secrets/request-guidance.d.ts

@@ -0,0 +1,24 @@
+import type { TargetDescriptor } from '../runtime-state.js';
+import type { FillableFormFieldBinding, FillableFormGuidanceHint, FillableFormRecommendedTiming, StoredSecretFieldKey } from './types.js';
+declare function collectVisibleFieldEvidence(fields: ReadonlyArray<FillableFormFieldBinding>, targetByRef: ReadonlyMap<string, TargetDescriptor>): string;
+declare function collectBlockingValidationEvidence(fields: ReadonlyArray<FillableFormFieldBinding>, targetByRef: ReadonlyMap<string, TargetDescriptor>): string[];
+declare function collectPassiveRequiredEvidence(fields: ReadonlyArray<FillableFormFieldBinding>, targetByRef: ReadonlyMap<string, TargetDescriptor>): string[];
+declare function hasCorePaymentCardFields(fieldKeys: ReadonlySet<StoredSecretFieldKey>): boolean;
+declare function looksLikePrimaryLoginForm(fieldKeys: ReadonlySet<StoredSecretFieldKey>): boolean;
+declare function looksLikeStrongIdentityForm(fieldKeys: ReadonlySet<StoredSecretFieldKey>): boolean;
+export declare function buildFillableFormGuidance(params: {
+    purpose: string;
+    recommendedTiming?: FillableFormRecommendedTiming;
+    fields: ReadonlyArray<FillableFormFieldBinding>;
+    targetByRef: ReadonlyMap<string, TargetDescriptor>;
+}): FillableFormGuidanceHint;
+export declare const __testRequestGuidance: {
+    collectVisibleFieldEvidence: typeof collectVisibleFieldEvidence;
+    collectBlockingValidationEvidence: typeof collectBlockingValidationEvidence;
+    collectPassiveRequiredEvidence: typeof collectPassiveRequiredEvidence;
+    hasCorePaymentCardFields: typeof hasCorePaymentCardFields;
+    looksLikePrimaryLoginForm: typeof looksLikePrimaryLoginForm;
+    looksLikeStrongIdentityForm: typeof looksLikeStrongIdentityForm;
+};
+export {};
+//# sourceMappingURL=request-guidance.d.ts.map

package/dist/secrets/request-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-guidance.d.ts","sourceRoot":"","sources":["../../src/secrets/request-guidance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACxB,6BAA6B,EAC7B,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAoCpB,iBAAS,2BAA2B,CAClC,MAAM,EAAE,aAAa,CAAC,wBAAwB,CAAC,EAC/C,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACjD,MAAM,CAYR;AAED,iBAAS,iCAAiC,CACxC,MAAM,EAAE,aAAa,CAAC,wBAAwB,CAAC,EAC/C,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACjD,MAAM,EAAE,CA+BV;AAED,iBAAS,8BAA8B,CACrC,MAAM,EAAE,aAAa,CAAC,wBAAwB,CAAC,EAC/C,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACjD,MAAM,EAAE,CAsBV;AAED,iBAAS,wBAAwB,CAAC,SAAS,EAAE,WAAW,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAEvF;AAED,iBAAS,yBAAyB,CAAC,SAAS,EAAE,WAAW,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAExF;AAED,iBAAS,2BAA2B,CAAC,SAAS,EAAE,WAAW,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAK1F;AAmBD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,6BAA6B,CAAC;IAClD,MAAM,EAAE,aAAa,CAAC,wBAAwB,CAAC,CAAC;IAChD,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACpD,GAAG,wBAAwB,CA4C3B;AAED,eAAO,MAAM,qBAAqB;;;;;;;CAOjC,CAAC"}

package/dist/secrets/request-guidance.js

@@ -0,0 +1,142 @@
+const PAYMENT_CARD_CORE_KEYS = new Set([
+    'pan',
+    'exp_month',
+    'exp_year',
+    'cvv',
+]);
+const HIGH_SIGNAL_IDENTITY_KEYS = new Set([
+    'document_number',
+    'date_of_birth',
+    'issue_date',
+    'expiry_date',
+    'issuing_country',
+]);
+const IMMEDIATE_HINT = 'This secret is likely needed now.';
+const DEFER_HINT = 'Hold off on requesting this secret for now.';
+const DEFER_RECHECK = 'Re-check only if submit or validation explicitly points back to this form.';
+function humanizeFieldKey(fieldKey) {
+    return fieldKey.replace(/_/g, ' ');
+}
+function labelForField(field, target) {
+    return target?.displayLabel ?? target?.label ?? field.label ?? humanizeFieldKey(field.fieldKey);
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function collectVisibleFieldEvidence(fields, targetByRef) {
+    const labels = unique(fields
+        .map((field) => labelForField(field, targetByRef.get(field.targetRef)))
+        .filter((value) => value.length > 0));
+    if (labels.length === 0) {
+        return 'Matched fields are visible on the page.';
+    }
+    return `Visible matched fields: ${labels.join(', ')}.`;
+}
+function collectBlockingValidationEvidence(fields, targetByRef) {
+    const evidence = [];
+    const seenTargets = new Set();
+    for (const field of fields) {
+        if (seenTargets.has(field.targetRef)) {
+            continue;
+        }
+        seenTargets.add(field.targetRef);
+        const target = targetByRef.get(field.targetRef);
+        const validation = target?.validation;
+        if (!validation) {
+            continue;
+        }
+        const label = labelForField(field, target);
+        if (validation.message) {
+            evidence.push(`"${label}" already shows validation: ${validation.message}`);
+            continue;
+        }
+        if (validation.invalid) {
+            evidence.push(`"${label}" is currently marked invalid.`);
+            continue;
+        }
+        if (validation.errorStyling) {
+            evidence.push(`"${label}" is already styled like an error.`);
+        }
+    }
+    return evidence;
+}
+function collectPassiveRequiredEvidence(fields, targetByRef) {
+    const evidence = [];
+    const seenTargets = new Set();
+    for (const field of fields) {
+        if (seenTargets.has(field.targetRef)) {
+            continue;
+        }
+        seenTargets.add(field.targetRef);
+        const target = targetByRef.get(field.targetRef);
+        if (!target?.validation?.required) {
+            continue;
+        }
+        if (target.validation.invalid || target.validation.message || target.validation.errorStyling) {
+            continue;
+        }
+        evidence.push(`"${labelForField(field, target)}" is marked required.`);
+    }
+    return evidence;
+}
+function hasCorePaymentCardFields(fieldKeys) {
+    return [...PAYMENT_CARD_CORE_KEYS].every((fieldKey) => fieldKeys.has(fieldKey));
+}
+function looksLikePrimaryLoginForm(fieldKeys) {
+    return fieldKeys.has('password');
+}
+function looksLikeStrongIdentityForm(fieldKeys) {
+    const strongFieldCount = [...HIGH_SIGNAL_IDENTITY_KEYS].filter((fieldKey) => fieldKeys.has(fieldKey)).length;
+    return strongFieldCount > 0 || fieldKeys.size >= 3;
+}
+function immediateGuidance(why, evidence) {
+    return {
+        hint: IMMEDIATE_HINT,
+        why,
+        evidence: evidence.filter((value) => value.length > 0),
+    };
+}
+function deferGuidance(why, evidence) {
+    return {
+        hint: DEFER_HINT,
+        why,
+        recheckWhen: DEFER_RECHECK,
+        evidence: evidence.filter((value) => value.length > 0),
+    };
+}
+export function buildFillableFormGuidance(params) {
+    const { purpose, recommendedTiming, fields, targetByRef } = params;
+    const visibleFieldEvidence = collectVisibleFieldEvidence(fields, targetByRef);
+    const blockingValidationEvidence = collectBlockingValidationEvidence(fields, targetByRef);
+    const passiveRequiredEvidence = collectPassiveRequiredEvidence(fields, targetByRef);
+    const fieldKeys = new Set(fields.map((field) => field.fieldKey));
+    if (blockingValidationEvidence.length > 0) {
+        return immediateGuidance('The page is already pointing at this form through active validation signals.', [visibleFieldEvidence, ...blockingValidationEvidence]);
+    }
+    if (purpose === 'payment_card' && hasCorePaymentCardFields(fieldKeys)) {
+        return immediateGuidance('This is the visible card form for the active checkout.', [
+            visibleFieldEvidence,
+            ...passiveRequiredEvidence,
+        ]);
+    }
+    if (purpose === 'login' && looksLikePrimaryLoginForm(fieldKeys)) {
+        return immediateGuidance('This looks like the main login form needed to continue.', [
+            visibleFieldEvidence,
+            ...passiveRequiredEvidence,
+        ]);
+    }
+    if (purpose === 'identity' && looksLikeStrongIdentityForm(fieldKeys)) {
+        return immediateGuidance('This looks like a full identity form rather than a one-off contact field.', [visibleFieldEvidence, ...passiveRequiredEvidence]);
+    }
+    const lateTimingEvidence = recommendedTiming === 'late' ? 'Matcher marked this form for late timing.' : '';
+    const noActiveBlockerEvidence = 'No matched field currently shows active validation that blocks progress.';
+    return deferGuidance('This form is visible, but there is not enough evidence yet that it is the blocker right now.', [visibleFieldEvidence, ...passiveRequiredEvidence, noActiveBlockerEvidence, lateTimingEvidence]);
+}
+export const __testRequestGuidance = {
+    collectVisibleFieldEvidence,
+    collectBlockingValidationEvidence,
+    collectPassiveRequiredEvidence,
+    hasCorePaymentCardFields,
+    looksLikePrimaryLoginForm,
+    looksLikeStrongIdentityForm,
+};