@trusty-squire/mcp 1.1.8 → 1.1.9-rc.2

package/dist/bot/browser.js

@@ -269,6 +269,46 @@ function parseCheckoutAmountResult(texts, fallbackCurrency) {
 export function parseCheckoutAmount(texts, fallbackCurrency) {
     return parseCheckoutAmountResult(texts, fallbackCurrency).amount;
 }
+/**
+ * Like parseCheckoutAmount but returns every currency-guard-clean match
+ * instead of the first — checkout review pages can show a pre-shipping
+ * subtotal before the final labeled total, so the caller needs the full
+ * sequence to pick the settled one. Reuses the same regex and currency-guard
+ * helpers as parseCheckoutAmountResult (unresolved-currency and
+ * fallback-scale-mismatch matches are skipped identically), just without the
+ * single-result early return.
+ */
+export function parseCheckoutAmounts(texts, fallbackCurrency) {
+    const amounts = [];
+    for (const text of texts) {
+        checkoutTotalPattern.lastIndex = 0;
+        for (const match of text.matchAll(checkoutTotalPattern)) {
+            const prefix = classifyCheckoutCurrencyToken(match[1]);
+            const symbol = classifyCheckoutCurrencyToken(match[2]);
+            const suffix = classifyCheckoutCurrencyToken(match[4]);
+            if (prefix.unresolved || symbol.unresolved || suffix.unresolved)
+                continue;
+            const pageCurrency = prefix.currency ?? suffix.currency ?? symbol.currency;
+            const currency = (pageCurrency ?? fallbackCurrency)?.toUpperCase();
+            if (currency === undefined || !/^[A-Z]{3}$/.test(currency))
+                continue;
+            const minorDigits = currencyMinorDigits(currency);
+            if (pageCurrency === undefined &&
+                fallbackCurrencyScaleMismatches(match[3] ?? "", minorDigits)) {
+                continue;
+            }
+            const amount = parseDisplayedNumber(match[3] ?? "", minorDigits);
+            if (amount === null)
+                continue;
+            const scale = 10 ** minorDigits;
+            const minor = Math.round(amount * scale);
+            if (Math.abs(amount * scale - minor) > 1e-6)
+                continue;
+            amounts.push({ amount_cents: minor, currency });
+        }
+    }
+    return amounts;
+}
 function merchantFromPage(title, siteName, url) {
     if (siteName.trim().length > 0)
         return siteName.trim().slice(0, 256);
@@ -950,6 +990,9 @@ export class BrowserController {
     // different signal from the same failure on a raw datacenter IP.
     proxyServer = null;
     profileDir;
+    // The replay harness owns this context so it can route the storefront from a
+    // HAR, then remove that route before checkout becomes live.
+    harnessAttachedPage = false;
     // T6/T7 — OAuth handshake bookkeeping. When startOAuth() adopts a
     // popup window as the active page, the original product page is
     // parked here so settleAfterOAuth() can switch back to it once the
@@ -980,6 +1023,16 @@ export class BrowserController {
         this.proxyOverride =
             opts.proxyUrl !== undefined && opts.proxyUrl.trim().length > 0 ? opts.proxyUrl.trim() : null;
     }
+    /** Attach normal controller behavior to a harness-owned Playwright page. */
+    static fromHarnessPage(page) {
+        const controller = new BrowserController({ humanize: false });
+        controller.context = page.context();
+        controller.page = page;
+        controller.primaryPage = page;
+        controller.harnessAttachedPage = true;
+        controller.launchedMode = "headless";
+        return controller;
+    }
     // Per-launch egress override (verify-fleet identities each get their own IP).
     // null → use the env-global proxy. See resolveProxy().
     proxyOverride;
@@ -3931,6 +3984,167 @@ export class BrowserController {
         await this.humanClickLocator(target);
         await this.wait(0.5);
     }
+    // ───────────── type-triggered autocomplete (3.1) ─────────────
+    // A free-text `type` into a Google-Places-style address field or a
+    // react-select/cmdk/Radix combobox can open the same kind of suggestion
+    // popup `select`'s selectFromCombobox() already knows how to drive — the
+    // difference is the host issued `type`, not an explicit `select`, so
+    // nothing today detects or commits the popup. These three methods reuse
+    // the exact open-detect/click machinery selectFromCombobox() uses; the
+    // match-or-stop decision of WHICH option (if any) to click lives in
+    // provision-session.ts (matchAutocompleteSuggestions), kept a pure
+    // function there so it's unit-testable without a browser.
+    /**
+     * Snapshot popups that already exist BEFORE typing — the suggestion popup
+     * can open mid-keystroke, so this must run before type(), not after.
+     */
+    async markPreexistingTypeSuggestionPopups() {
+        await this.markComboboxPreexistingElements();
+    }
+    /**
+     * After typing into `selector`, detect whether a suggestion popup opened
+     * as a side effect and return its option texts in DOM order. Empty when
+     * no popup opened — `type` behaved as an ordinary text field and the
+     * caller should no-op. Google-Places-style pickers debounce (~200ms)
+     * plus a network round-trip before rendering suggestions, so a single
+     * synchronous check right after the last keystroke commonly sees
+     * nothing — poll on a bounded budget (mirroring settleAfterStateChange's
+     * shape), returning as soon as options appear so an already-open popup
+     * pays no extra latency.
+     */
+    async detectTypeSuggestionPopup(selector) {
+        if (!this.page)
+            throw new Error("Browser not started");
+        for (let attempt = 0; attempt < 6; attempt += 1) {
+            if (attempt > 0)
+                await this.sleep(300);
+            await this.refreshComboboxMarkers(selector);
+            const options = this.page.locator("[data-ts-select-option-tier]");
+            const count = await options.count();
+            if (count === 0)
+                continue;
+            const texts = [];
+            for (let i = 0; i < count; i += 1) {
+                texts.push((await options.nth(i).innerText()).replace(/\s+/g, " ").trim());
+            }
+            return texts;
+        }
+        return [];
+    }
+    /** Click the option at `index` (as indexed by detectTypeSuggestionPopup). */
+    async commitTypeSuggestion(index) {
+        if (!this.page)
+            throw new Error("Browser not started");
+        const options = this.page.locator("[data-ts-select-option-tier]");
+        await this.clickComboboxOption(options.nth(index));
+    }
+    /**
+     * Clean up after a type-triggered autocomplete interaction, regardless of
+     * outcome (committed, ambiguous/zero-match stop, or a failed commit).
+     * When `dismissWithEscape` is true — the caller determined a detected
+     * popup is plausibly still open (an ambiguous/zero-match stop where no
+     * option was ever clicked, or a commit whose confirmation failed) —
+     * presses Escape to dismiss it BEFORE clearing our own tracking markers:
+     * some widgets (Google Places classic's `.pac-container` in particular)
+     * never fully unmount, just toggle visibility, so a popup left open would
+     * otherwise be captured as "preexisting" the next time
+     * markPreexistingTypeSuggestionPopups snapshots the page (it snapshots by
+     * current visibility, not by who opened it), silently disabling detection
+     * on a host's very next retry. Escape must NOT fire when no popup was
+     * ever detected, nor after a confirmed successful commit (the widget
+     * already closed its popup on selection): it commonly bubbles to close an
+     * enclosing modal/dialog too, so firing it with nothing left to dismiss
+     * risks closing a dialog the typed-into field happens to live in (a
+     * cmdk-in-Radix-dialog combobox, a cart-drawer quantity field, a login
+     * modal's email field, an address-edit modal). Marker clearing stays
+     * unconditional — it only removes our own tracking attributes, never
+     * touches page behavior.
+     */
+    async discardTypeSuggestionPopup(dismissWithEscape) {
+        if (dismissWithEscape)
+            await this.pressKey("Escape");
+        await this.clearComboboxMarkers();
+    }
+    /**
+     * After commitTypeSuggestion, POSITIVELY confirm the picked option's value
+     * actually committed. A same-selector `.value` change is one signal, but
+     * react-select/cmdk-style widgets clear their search input on selection
+     * and render the committed choice in a separate nearby element instead —
+     * checking only the original selector's `.value` would false-fail on
+     * exactly the widgets this feature targets. Checks, in order: the field's
+     * own live value; a native `<select>`'s selected-option label; a nearby
+     * (within two DOM ancestor hops of the field, never page-wide) element
+     * whose own text or aria-label exactly equals the picked option's text.
+     * Returns false — never true — when nothing positively confirms it; the
+     * caller must treat false as a miss (stop), never as a silent success.
+     */
+    async confirmAutocompleteCommitted(fieldSelector, pickedOptionText) {
+        if (!this.page)
+            throw new Error("Browser not started");
+        try {
+            return await this.page
+                .locator(fieldSelector)
+                .first()
+                .evaluate((field, wantedRaw) => {
+                const normalize = (s) => (s ?? "").toLowerCase().replace(/\s+/g, " ").trim();
+                const wanted = normalize(wantedRaw);
+                if (wanted.length === 0)
+                    return false;
+                const ownValue = field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement
+                    ? field.value
+                    : "";
+                if (normalize(ownValue) === wanted)
+                    return true;
+                if (field instanceof HTMLSelectElement) {
+                    const opt = field.options[field.selectedIndex];
+                    if (opt !== undefined && normalize(opt.textContent) === wanted)
+                        return true;
+                }
+                // Bounded to the field's immediate wrapper (walk up at most two
+                // ancestors) so a coincidental text match elsewhere on the page —
+                // or elsewhere in a large `<form>` — can't produce a false
+                // positive. React-select/cmdk render the committed choice as a
+                // sibling of the (now-cleared) search input under a shared
+                // control wrapper, well within this range.
+                //
+                // This runs BEFORE discardTypeSuggestionPopup (Escape is in the
+                // caller's finally), so a suggestion menu that never really
+                // committed can still be open here — and menus commonly render
+                // within two ancestor hops of the input too. Without excluding
+                // it, the picked OPTION's own (still-visible, un-really-clicked)
+                // element trivially satisfies the text-equality check every
+                // time, defeating the "positively confirm or stop" guarantee for
+                // exactly the failure this exists to catch. Exclude anything
+                // that IS, is INSIDE, or CONTAINS our own tracked popup/option
+                // markers — the last case matters because `.textContent`
+                // aggregates every descendant's text, so a plain wrapper div that
+                // merely contains the still-open popup reads as if it displayed
+                // the picked text itself.
+                const TRACKED_POPUP_SELECTOR = "[data-ts-select-popup],[data-ts-select-option-tier]";
+                const inTrackedPopup = (el) => el.matches(TRACKED_POPUP_SELECTOR) ||
+                    el.closest("[data-ts-select-popup]") !== null ||
+                    el.querySelector(TRACKED_POPUP_SELECTOR) !== null;
+                let scope = field.parentElement;
+                for (let hop = 0; hop < 2 && scope !== null; hop += 1) {
+                    const found = Array.from(scope.querySelectorAll("*")).some((el) => {
+                        if (el === field || inTrackedPopup(el))
+                            return false;
+                        if (normalize(el.textContent) === wanted)
+                            return true;
+                        const ariaLabel = el.getAttribute("aria-label");
+                        return ariaLabel !== null && normalize(ariaLabel) === wanted;
+                    });
+                    if (found)
+                        return true;
+                    scope = scope.parentElement;
+                }
+                return false;
+            }, pickedOptionText);
+        }
+        catch {
+            return false;
+        }
+    }
     // ───────────── humanization internals ─────────────
     // Click that mimics a real user: locate element, bezier-path the
     // mouse to it, hover briefly, then click. The mouse position is
@@ -5258,7 +5472,55 @@ export class BrowserController {
     async extractVisibleText() {
         if (!this.page)
             throw new Error("Browser not started");
-        return await this.page.evaluate(() => document.body?.innerText ?? "");
+        return await this.page.evaluate(() => {
+            const body = document.body;
+            if (!body)
+                return "";
+            // innerText excludes display:none/visibility:hidden but NOT opacity:0 —
+            // an element with opacity:0 keeps its layout box, so innerText still
+            // walks it. Hidden-native-<select> country-code widgets (e.g.
+            // react-phone-number-input) commonly style the real <select>
+            // opacity:0 (rather than display:none) so a native mobile picker still
+            // opens on tap; with every <option> in the box, that dumps hundreds of
+            // country names into the page text, flooding/truncating what a sighted
+            // user never sees (and what really matters, like an error banner past
+            // the truncation cutoff). A detached clone won't do: innerText on an
+            // unrendered element degrades to textContent semantics, re-including
+            // the display:none/script text innerText exists to exclude. Instead,
+            // temporarily force display:none on opacity:0 elements in the LIVE
+            // body, read innerText, and restore each element's style attribute
+            // byte-identically (removing it when it was absent) — all inside
+            // this one synchronous evaluate, so the change is never painted.
+            const hidden = [];
+            let text = "";
+            try {
+                for (const el of Array.from(body.querySelectorAll("*"))) {
+                    if (!(el instanceof HTMLElement || el instanceof SVGElement))
+                        continue;
+                    if (window.getComputedStyle(el).opacity === "0") {
+                        hidden.push({ el, style: el.getAttribute("style") });
+                        el.style.setProperty("display", "none", "important");
+                    }
+                }
+                text = body.innerText ?? "";
+            }
+            finally {
+                for (const { el, style } of hidden) {
+                    if (style === null) {
+                        // Plain removeAttribute here leaves an empty style="" behind:
+                        // Blink lazily re-syncs the dirty CSSOM declaration back into the
+                        // attribute after the innerText read. Clear the declaration first.
+                        el.style.removeProperty("display");
+                        if (el.getAttribute("style") === "")
+                            el.removeAttribute("style");
+                    }
+                    else {
+                        el.setAttribute("style", style);
+                    }
+                }
+            }
+            return text;
+        });
     }
     async readCheckoutSummary(fallbackCurrency) {
         if (!this.page)
@@ -5289,6 +5551,127 @@ export class BrowserController {
             ...amount,
         };
     }
+    /**
+     * Read a settled checkout-review amount.  Checkout pages can retain an
+     * earlier subtotal while asynchronously replacing the final labeled total;
+     * the harness calls this only after it has proved a shipping method is
+     * present, then requires this value to remain stable across two reads.
+     * Payment continues to use readCheckoutSummary's original first-read
+     * contract; this is a review-only, pre-payment reader.
+     */
+    async readCheckoutReviewSummary(fallbackCurrency) {
+        if (!this.page)
+            throw new Error("Browser not started");
+        const page = this.page;
+        const identity = await page.evaluate(() => ({
+            title: document.title,
+            siteName: document.querySelector('meta[property="og:site_name"]')?.content ??
+                document.querySelector('[itemprop="merchant"]')?.textContent ??
+                "",
+        }));
+        const texts = await Promise.all(page
+            .frames()
+            .map(async (frame) => await frame.evaluate(() => document.body?.innerText ?? "").catch(() => "")));
+        const amount = parseCheckoutAmounts(texts, fallbackCurrency).at(-1);
+        if (amount === undefined)
+            throw new Error("payment_checkout_total_not_found");
+        return {
+            merchant: merchantFromPage(identity.title, identity.siteName, page.url()),
+            checkout_origin: new URL(page.url()).origin,
+            ...amount,
+        };
+    }
+    async readCheckoutReviewLineItems() {
+        if (!this.page)
+            throw new Error("Browser not started");
+        return await this.page.evaluate(() => {
+            const normalize = (value) => value.replace(/\s+/g, " ").trim();
+            const visible = (element) => {
+                if (!(element instanceof HTMLElement) || element.getClientRects().length === 0)
+                    return false;
+                const style = getComputedStyle(element);
+                return style.display !== "none" && style.visibility !== "hidden";
+            };
+            const quantityIn = (container) => {
+                const field = Array.from(container.querySelectorAll('input[name*="quantity" i], input[aria-label*="quantity" i], select[name*="quantity" i]')).find(visible);
+                const fieldValue = field?.value === undefined ? Number.NaN : Number(field.value);
+                if (Number.isInteger(fieldValue) && fieldValue > 0)
+                    return fieldValue;
+                const text = normalize(container.textContent ?? "");
+                const labeled = /\bquantity\s*:?[\s\n]*(\d+)\b/i.exec(text)?.[1];
+                const parsed = Number(labeled);
+                return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+            };
+            const titleFrom = (container) => {
+                const candidates = [
+                    ...Array.from(container.querySelectorAll('a[href*="/products/"], [data-testid*="title" i], [class*="title" i], h1, h2, h3, h4, td, [role="cell"]'), (element) => normalize(element.innerText)),
+                    ...Array.from(container.querySelectorAll("img[alt]"), (image) => normalize(image.alt)),
+                ];
+                return candidates.find((candidate) => candidate.length > 0 &&
+                    candidate.length <= 240 &&
+                    !/^product(?: image| information)?$/i.test(candidate) &&
+                    !/^quantity\b/i.test(candidate) &&
+                    !/^\$|\$\s*\d/.test(candidate));
+            };
+            const rows = Array.from(document.querySelectorAll('tr, [role="row"], [data-testid*="line-item" i], [data-testid*="product" i], [class*="line-item" i], [class*="product" i]')).filter(visible);
+            const observed = rows.flatMap((row) => {
+                const quantity = quantityIn(row);
+                const title = titleFrom(row);
+                return quantity === undefined || title === undefined
+                    ? []
+                    : [{ title, quantity, size: normalize(row.textContent ?? "").length }];
+            });
+            const byTitle = new Map();
+            for (const item of observed) {
+                const key = item.title.toLowerCase();
+                const previous = byTitle.get(key);
+                if (previous === undefined || item.size < previous.size)
+                    byTitle.set(key, item);
+            }
+            return [...byTitle.values()].map(({ title, quantity }) => ({ title, quantity }));
+        });
+    }
+    async readSettledCheckoutReviewSummary(fallbackCurrency, timeoutMs = 12_000) {
+        if (!this.page)
+            throw new Error("Browser not started");
+        const deadline = Date.now() + timeoutMs;
+        let previous;
+        while (Date.now() < deadline) {
+            const shippingReady = await this.page
+                .evaluate(() => {
+                const labels = Array.from(document.querySelectorAll('input[type="radio"]'))
+                    .flatMap((input) => [
+                    ...(input.labels === null
+                        ? []
+                        : Array.from(input.labels, (label) => label.innerText)),
+                    input.getAttribute("aria-label") ?? "",
+                    input.closest("label")?.textContent ?? "",
+                ])
+                    .map((label) => label.replace(/\s+/g, " ").trim())
+                    .filter((label) => label.length > 0 && !/loading/i.test(label));
+                return (/\bdelivery\b|\bshipping\b/i.test(document.body?.innerText ?? "") &&
+                    labels.some((label) => /\b(?:standard|express|shipping|delivery|pickup)\b/i.test(label)));
+            })
+                .catch(() => false);
+            if (shippingReady) {
+                const current = await Promise.all([
+                    this.readCheckoutReviewSummary(fallbackCurrency),
+                    this.readCheckoutReviewLineItems(),
+                ])
+                    .then(([summary, line_items]) => ({ ...summary, line_items }))
+                    .catch(() => undefined);
+                if (current !== undefined &&
+                    current.line_items.length > 0 &&
+                    previous !== undefined &&
+                    JSON.stringify(current) === JSON.stringify(previous)) {
+                    return current;
+                }
+                previous = current;
+            }
+            await this.page.waitForTimeout(250);
+        }
+        return undefined;
+    }
     async isPayPalHostedCheckout() {
         if (!this.page)
             throw new Error("Browser not started");
@@ -7557,6 +7940,11 @@ export class BrowserController {
                         const lm = el.closest("header,main,footer,nav,aside,article,section");
                         return lm !== null ? lm.tagName.toLowerCase() : null;
                     })(),
+                    // Locale-stable role signals for money-path fill guards. Prefer
+                    // autocomplete over visible labels (labels flip under i18n).
+                    autocomplete: (el.getAttribute("autocomplete") ?? "").trim() || null,
+                    dataRole: (el.getAttribute("data-field-role") ?? el.getAttribute("data-role") ?? "").trim() ||
+                        null,
                     value: el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement
                         ? el.value
                         : el instanceof HTMLSelectElement
@@ -7612,6 +8000,29 @@ export class BrowserController {
             cardRadioGroup: groups[i] ?? null,
         }));
     }
+    // replay-per-leg-signature — the checkout-leg shape signature (see
+    // checkoutFieldSetSignature in @trusty-squire/recipe-schema) is computed
+    // from a page's FULL field-name set, deliberately including `type=hidden`
+    // fields — unlike extractInteractiveElements above (which deliberately
+    // skips hidden/password inputs, since those aren't things a planner can
+    // act on), a checkout platform's own hidden session/GraphQL-serialized
+    // fields are exactly the stable, platform-authored signal the signature
+    // depends on. Reads every input/select/textarea's `name` (falling back to
+    // `id`) with a single flat query — no visibility/shadow-DOM handling,
+    // matching the method proven in the field-name-set discriminator report.
+    async extractCheckoutFieldNames() {
+        if (!this.page)
+            throw new Error("Browser not started");
+        return await this.page.evaluate(() => {
+            const names = [];
+            document.querySelectorAll("input,select,textarea").forEach((el) => {
+                const name = el.getAttribute("name") ?? el.getAttribute("id") ?? "";
+                if (name.length > 0)
+                    names.push(name);
+            });
+            return names;
+        });
+    }
     // Resolve a selector against the live page for the verify step
     // (F3 T5). Returns the match count plus the first match's
     // tag/id/name so the caller can confirm a still-resolving selector
@@ -8537,6 +8948,14 @@ export class BrowserController {
         });
     }
     async close() {
+        if (this.harnessAttachedPage) {
+            this.page = null;
+            this.primaryPage = null;
+            this.oauthProductPage = null;
+            this.oauthNetLog = [];
+            this.context = null;
+            return;
+        }
         // Each step is best-effort and independent: a throw closing the page
         // or context must NOT skip the Xvfb teardown below, or the virtual
         // display leaks (orphaned Xvfb procs pile up over a long-lived MCP